orca/mobile/scripts/build-terminal-document-script.mjs

import { readFile, writeFile } from 'node:fs/promises'
import path from 'node:path'
import * as esbuild from 'esbuild'
import { importTypeScriptModule } from './import-typescript-module.mjs'
import {
  TERMINAL_DOCUMENT_HOST_SEAMS_MODULE,
  TERMINAL_DOCUMENT_MODULE_ORDER,
  TERMINAL_DOCUMENT_RESET_CALL,
  TERMINAL_DOCUMENT_SCOPE_MODULE,
  terminalDocumentStartFunctionName,
  terminalDocumentStopFunctionName
} from './terminal-document-module-order.mjs'

/**
 * Turns one module of the in-WebView terminal document back into the script text the document
 * carries.
 *
 * The document is a string the native WebView loads, so its parts cannot be imported by anything;
 * the web page needs exactly those parts and must not re-implement them. So the parts are modules,
 * and this is the other direction: the modules' declarations, with their imports removed and their
 * exports unmarked, spliced into the one function scope the document has always been.
 *
 * Imports are dropped rather than resolved because inside the document every name is already in
 * scope — that is what the single IIFE means. `document-externals.ts` declares the names that have
 * not moved into modules yet, and it emits nothing at all.
 *
 * `esbuild` does the TypeScript, as it already does for the xterm engine beside this file. It is a
 * transform and not a bundle: a bundler would order the output by its dependency graph, and the
 * document's order is part of what the equivalence test holds fixed.
 */
const INDENT = '  '

const constantsPath = path.join(
  import.meta.dirname,
  '..',
  'src',
  'terminal',
  'document',
  'document-constants.ts'
)

let substitutions = null

/**
 * `document-constants.ts` as the literal text each name stands for.
 *
 * Substitution happens after the import lines are dropped, when the names are free again, and it is
 * textual rather than an esbuild `define` because a `define` whose value is an object or an array
 * is injected as a helper binding instead of being inlined, which is not what the document carries.
 * The names are exported for this purpose only and none of them appears inside a string.
 */
async function documentConstantSubstitutions() {
  if (substitutions === null) {
    const module = await importTypeScriptModule(constantsPath)
    substitutions = Object.fromEntries(
      Object.entries(module).map(([name, value]) => [name, JSON.stringify(value)])
    )
  }
  return substitutions
}

/**
 * Replaces each constant's name with its literal.
 *
 * The replacement is a function, not the literal itself: as a string, `$&`, `` $` ``, `$'` and
 * `$n` are replacement patterns, so a constant whose value contains one would be spliced with the
 * match rather than written out. A function replacer has no such reading.
 */
export function substituteDocumentConstants(text, substitutions) {
  let substituted = text
  for (const [name, literal] of Object.entries(substitutions)) {
    substituted = substituted.replaceAll(new RegExp(`\\b${name}\\b`, 'g'), () => literal)
  }
  return substituted
}

/**
 * Whether a line is a lint directive.
 *
 * These are removed before the transform, not after it: a directive inside an expression makes
 * esbuild wrap that expression in parentheses to keep the comment where it was, and those
 * parentheses are tokens the document does not have. They are tooling metadata about the source,
 * not part of the program the WebView runs.
 */
function isLintDirectiveLine(line) {
  return /^\s*\/\/\s*oxlint-disable/.test(line)
}

/** Whether a line opens an import the document does not need. */
function isImportLine(line) {
  return /^import[\s{'"]/.test(line)
}

/** Whether a statement that started on this line also ended on it. */
function closesOnSameLine(line, closer) {
  return line.includes(closer)
}

/**
 * The emitted text of one module: transpiled, unexported, un-imported and indented into the IIFE.
 *
 * Multi-line imports are handled by dropping through to the line that closes them, which esbuild's
 * output makes safe: it prints one import per line.
 */
export async function emitTerminalDocumentModule(modulePath) {
  const source = await readFile(modulePath, 'utf8')
  const program = source
    .split('\n')
    .filter((line) => !isLintDirectiveLine(line))
    .join('\n')
  const { code } = await esbuild.transform(program, {
    loader: 'ts',
    format: 'esm',
    target: 'chrome74',
    // The document is read by people as well as by a WebView, and the equivalence test compares
    // tokens, so keeping the printer's own layout costs nothing and keeps the diff legible.
    minify: false
  })
  const kept = []
  // esbuild wraps a long import or export list across lines, so both are skipped to their closer
  // rather than by their first line. An export list dropped by its keyword alone would leave a
  // bare block statement in the document, and an import list would leave its names loose.
  let skipUntil = null
  for (const line of code.split('\n')) {
    if (skipUntil !== null) {
      if (closesOnSameLine(line, skipUntil)) {
        skipUntil = null
      }
      continue
    }
    if (isImportLine(line)) {
      skipUntil = closesOnSameLine(line, ' from ') || closesOnSameLine(line, ';') ? null : ' from '
      continue
    }
    if (line.startsWith('export {')) {
      skipUntil = closesOnSameLine(line, '}') ? null : '}'
      continue
    }
    kept.push(line.startsWith('export ') ? line.slice('export '.length) : line)
  }
  const text = substituteDocumentConstants(kept.join('\n'), await documentConstantSubstitutions())
  const substituted = await esbuild.transform(text, {
    loader: 'js',
    format: 'esm',
    target: 'chrome74',
    minify: false
  })
  const body = substituted.code.trim()
  return body
    .split('\n')
    .map((line) => (line.length === 0 ? line : `${INDENT}${line}`))
    .join('\n')
}

const documentDirectory = path.join(import.meta.dirname, '..', 'src', 'terminal', 'document')

export const TERMINAL_DOCUMENT_SCRIPT_PATH = path.join(
  import.meta.dirname,
  '..',
  'src',
  'terminal',
  'terminal-webview-document-script.generated.ts'
)

/**
 * The start functions the emitted document calls, in module order (ruling 20).
 *
 * Presence is read from the source rather than listed here: a module that has no top-level effect
 * exports no start function, and one that grows an effect is reached the moment it does. The
 * declaration is matched on its own line because that is how esbuild's TypeScript prints it and
 * how every module in this directory writes it.
 */
export async function terminalDocumentStartCalls(moduleNames) {
  return await declaredFunctions(moduleNames, terminalDocumentStartFunctionName)
}

/** The stop functions, in module order. The page runs them in reverse; the WebView never stops. */
export async function terminalDocumentStopCalls(moduleNames) {
  return await declaredFunctions(moduleNames, terminalDocumentStopFunctionName)
}

async function declaredFunctions(moduleNames, nameFor) {
  const found = []
  for (const name of moduleNames) {
    const source = await readFile(path.join(documentDirectory, `${name}.ts`), 'utf8')
    const declared = nameFor(name)
    if (new RegExp(`^export function ${declared}\\(\\) \\{$`, 'm').test(source)) {
      found.push(declared)
    }
  }
  return found
}

/**
 * The document's whole script: every module in the order the document had, inside the one function
 * scope it has always been, and then the one call sequence that starts them.
 */
export async function buildTerminalDocumentScript() {
  const emitted = []
  // The scope object goes first: every module below reads it, and the document is one function
  // scope, so it has to exist before any of them run. It is the only part of the emitted script
  // the hand-written document did not have, and the host seams come ahead of it because its
  // defaults are those six functions.
  const order = [
    TERMINAL_DOCUMENT_HOST_SEAMS_MODULE,
    TERMINAL_DOCUMENT_SCOPE_MODULE,
    ...TERMINAL_DOCUMENT_MODULE_ORDER
  ]
  for (const name of order) {
    emitted.push(await emitTerminalDocumentModule(path.join(documentDirectory, `${name}.ts`)))
  }
  // Rulings 20 and 21: the modules above only declare. The scope's reset comes first, so the
  // state every module reads is the state a fresh parse has; then every element read, listener
  // and reporter install runs, once here and per mount on the page, in the order both hosts share.
  const calls = [TERMINAL_DOCUMENT_RESET_CALL, ...(await terminalDocumentStartCalls(order))].map(
    (name) => `${INDENT}${name}();`
  )
  return `(function() {\n${emitted.join('\n')}\n${calls.join('\n')}\n})();`
}

async function main() {
  const script = await buildTerminalDocumentScript()
  await writeFile(
    TERMINAL_DOCUMENT_SCRIPT_PATH,
    `// Generated by scripts/build-terminal-document-script.mjs. Do not edit.\n` +
      `// The source is mobile/src/terminal/document/, in the order\n` +
      `// scripts/terminal-document-module-order.mjs pins.\n` +
      `export const TERMINAL_DOCUMENT_SCRIPT = ${JSON.stringify(script)}\n`
  )
}

if (process.argv[1] === import.meta.filename) {
  await main()
}