grammatik 0.1.0

package/src/lexer.js

@@ -0,0 +1,358 @@
+// @ts-check
+'use strict'
+
+import { firstCharSet } from './firstchars.js'
+
+/**
+ * A Chevrotain-style lexer. Token definitions are plain JSON, so a whole
+ * grammar (tokens + rules) stays serializable.
+ *
+ * @typedef {object} TokenDef
+ * @property {string} name       The token type produced.
+ * @property {string} [pattern]  A regex source string, matched sticky at the current offset.
+ * @property {string} [literal]  A literal string to match. Cheaper than a pattern; prefer it.
+ * @property {boolean} [skip]    When true the match is consumed but produces no token (whitespace, comments).
+ * @property {string} [longerAlt] Name of another token to prefer when it matches a longer string
+ *                                at the same offset (the classic `if` / `identifier` problem).
+ * @property {boolean} [ignoreCase] Case-insensitive matching.
+ * @property {string} [mode]     The lexer mode this token belongs to. Default `'default'`.
+ * @property {string[]} [modes]  Several modes, when one token serves more than one.
+ * @property {string} [pushMode] Enter this mode after the token matches.
+ * @property {boolean} [popMode] Leave the current mode after the token matches.
+ */
+
+/**
+ * @typedef {object} Token
+ * @property {string} type
+ * @property {string} image
+ * @property {number} start
+ * @property {number} end
+ * @property {number} line
+ * @property {number} col
+ */
+
+export class LexError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ offset: number, line: number, col: number }} position
+   */
+  constructor (message, position) {
+    super(message)
+    this.name = 'LexError'
+    this.offset = position.offset
+    this.line = position.line
+    this.col = position.col
+  }
+}
+
+const DEFAULT_MODE = 'default'
+
+/** The modes one definition belongs to, however it spelled them. */
+function modesOf (def) {
+  if (Array.isArray(def.modes) && def.modes.length > 0) return def.modes
+  if (def.mode) return [def.mode]
+  return [DEFAULT_MODE]
+}
+
+/**
+ * Compiles token definitions into a fast sticky-regex lexer.
+ *
+ * Literal tokens are matched with `startsWith` rather than a regex, which is a
+ * large win for punctuation-heavy grammars (JSON is ~60% punctuation by token count).
+ *
+ * ## Modes
+ *
+ * A token belongs to one or more modes and only competes while one of them is
+ * current. `pushMode` enters a mode after the token matches, `popMode` leaves
+ * one, and the stack starts fresh at `'default'` on every `tokenize` call. This
+ * is how context-sensitive vocabularies are expressed as data: in Handlebars,
+ * whitespace is literal text outside `{{ }}` and skipped inside it, which is one
+ * token definition per mode rather than a hand-written scanner.
+ *
+ * Everything a mode needs — its candidate list and its first-character dispatch
+ * table — is compiled here, so the hot path only indexes by mode id. A grammar
+ * with a single mode never touches a mode stack at all.
+ *
+ * @param {TokenDef[]} defs
+ * @param {{ positions?: 'full' | 'offset' }} [options]
+ *   `full` (default) records line and column on every token. `offset` records
+ *   only `start`/`end`, which skips a scan of the entire input for newlines —
+ *   worth taking when errors do not need to name a line, or when positions are
+ *   resolved lazily from the offset afterwards.
+ * @returns {{ tokenize: (text: string) => Token[], tokenNames: string[], positions: string, modeNames: string[] }}
+ */
+export function createLexer (defs, options = {}) {
+  const positions = options.positions === 'offset' ? 'offset' : 'full'
+  const trackLines = positions === 'full'
+  if (!Array.isArray(defs) || defs.length === 0) throw new Error('createLexer: expected a non-empty array of token definitions')
+
+  const tokenNames = defs.map((d) => d.name)
+  const seen = new Set()
+  for (const name of tokenNames) {
+    if (seen.has(name)) throw new Error(`createLexer: duplicate token name '${name}'`)
+    seen.add(name)
+  }
+
+  // ---- modes ----
+  // Mode ids are assigned before anything else so a definition can carry the
+  // numbers rather than the names, and the hot path never touches a string.
+  const modeIds = new Map([[DEFAULT_MODE, 0]])
+  const modeNames = [DEFAULT_MODE]
+  const idOf = (name) => {
+    let id = modeIds.get(name)
+    if (id === undefined) {
+      id = modeNames.length
+      modeIds.set(name, id)
+      modeNames.push(name)
+    }
+    return id
+  }
+  for (const def of defs) for (const mode of modesOf(def)) idOf(mode)
+
+  const compiled = defs.map((def) => {
+    if (!def.name) throw new Error('createLexer: every token definition needs a name')
+    if (!def.pattern && !def.literal) throw new Error(`createLexer: token '${def.name}' needs a pattern or a literal`)
+    if (def.pattern && def.literal) throw new Error(`createLexer: token '${def.name}' has both a pattern and a literal; pick one`)
+    if (def.longerAlt && !seen.has(def.longerAlt)) throw new Error(`createLexer: token '${def.name}' has longerAlt '${def.longerAlt}', which is not a defined token`)
+    if (def.pushMode && def.popMode) {
+      throw new Error(
+        `createLexer: token '${def.name}' both pushes '${def.pushMode}' and pops. ` +
+        'One token cannot do both — split it into two tokens, one per mode.'
+      )
+    }
+    // A mode nothing declares is a typo, and would otherwise strand the lexer in
+    // a mode where no token can ever match.
+    if (def.pushMode && !modeIds.has(def.pushMode)) {
+      throw new Error(`createLexer: token '${def.name}' pushes mode '${def.pushMode}', which no token belongs to`)
+    }
+
+    return {
+      name: def.name,
+      skip: !!def.skip,
+      literal: def.literal,
+      longerAlt: def.longerAlt || null,
+      regex: def.pattern ? new RegExp(def.pattern, def.ignoreCase ? 'iy' : 'y') : null,
+      modes: modesOf(def),
+      pushMode: def.pushMode ? idOf(def.pushMode) : -1,
+      popMode: !!def.popMode
+    }
+  })
+
+  const byName = new Map(compiled.map((c) => [c.name, c]))
+  // Resolve longerAlt names to the compiled definitions once, up front.
+  for (const c of compiled) if (c.longerAlt) c.longerAltDef = byName.get(c.longerAlt)
+
+  // A longerAlt can only win where it is itself active; otherwise a token would
+  // silently lose its alternative in one mode and keep it in another.
+  for (const c of compiled) {
+    if (!c.longerAltDef) continue
+    for (const mode of c.modes) {
+      if (c.longerAltDef.modes.includes(mode)) continue
+      throw new Error(
+        `createLexer: token '${c.name}' is active in mode '${mode}' with longerAlt '${c.longerAlt}', ` +
+        `which is not active there. Add '${mode}' to '${c.longerAlt}'.`
+      )
+    }
+  }
+
+  // ---- per-mode dispatch tables ----
+  // For each definition, work out which characters it can start with, so that a
+  // given offset only tries the handful of patterns that could match there
+  // rather than all of them in declaration order. Built once per mode, since a
+  // mode's candidate set never changes after the lexer is created.
+  for (const c of compiled) {
+    c.firstChars = c.literal !== undefined
+      ? (c.literal.length > 0 ? new Set([c.literal.charCodeAt(0)]) : null)
+      : firstCharSet(c.regex.source, !!c.regex.ignoreCase)
+  }
+
+  const modes = modeNames.map((name) => {
+    const members = compiled.filter((c) => c.modes.includes(name))
+    // Definitions whose first characters could not be determined must be tried
+    // at every offset, so they belong in every bucket.
+    const alwaysTry = members.filter((c) => c.firstChars === null)
+    const candidatesFor = (code) => members.filter((c) => c.firstChars === null || c.firstChars.has(code))
+
+    const ascii = new Array(128)
+    for (let code = 0; code < 128; code++) ascii[code] = candidatesFor(code)
+
+    return {
+      name,
+      members,
+      ascii,
+      wide: new Map(),
+      candidatesFor,
+      // If nothing could be analyzed, dispatch is pure overhead; skip it.
+      dispatch: alwaysTry.length < members.length
+    }
+  })
+
+  for (const mode of modes) {
+    if (mode.members.length === 0) throw new Error(`createLexer: mode '${mode.name}' has no tokens`)
+  }
+
+  function candidates (mode, code) {
+    if (code < 128) return mode.ascii[code]
+    let list = mode.wide.get(code)
+    if (list === undefined) {
+      list = mode.candidatesFor(code)
+      mode.wide.set(code, list)
+    }
+    return list
+  }
+
+  // No transitions anywhere means no stack and no per-token mode checks — the
+  // loop this had before modes existed. A grammar can declare one mode and still
+  // pop out of it, which is always an underflow; that has to be reported, not
+  // skipped along with the rest of the machinery.
+  const multiMode = modes.length > 1 || compiled.some((c) => c.popMode || c.pushMode !== -1)
+  // Naming the mode in an error only helps when there is more than one.
+  const namesModes = modes.length > 1
+  const initial = modes[0]
+
+  /** The `longerAlt` match end, or -1. Only reached when a `longerAlt` is set. */
+  function longerAltEnd (def, text, offset) {
+    const alt = def.longerAltDef
+    if (alt.literal !== undefined) return text.startsWith(alt.literal, offset) ? offset + alt.literal.length : -1
+    alt.regex.lastIndex = offset
+    return alt.regex.test(text) ? alt.regex.lastIndex : -1
+  }
+
+  /**
+   * @param {string} text
+   * @returns {Token[]}
+   */
+  function tokenize (text) {
+    if (typeof text !== 'string') throw new TypeError('tokenize: expected a string')
+
+    /** @type {Token[]} */
+    const tokens = []
+    let offset = 0
+    let line = 1
+    let lineStart = 0
+    const length = text.length
+
+    // The stack is local to this call, so a lexer is reusable and a failure
+    // partway through leaves nothing behind for the next one.
+    let mode = initial
+    const stack = multiMode ? [] : null
+    let depth = 0
+
+    outer: while (offset < length) {
+      // Inlining the ASCII table lookup here instead of calling `candidates` was
+      // measured and made no difference; the cost is in the patterns, not the
+      // dispatch.
+      const applicable = mode.dispatch ? candidates(mode, text.charCodeAt(offset)) : mode.members
+
+      for (let i = 0; i < applicable.length; i++) {
+        const def = applicable[i]
+
+        // Find where the match ends without necessarily building it. `test` on a
+        // sticky regex advances `lastIndex` just like `exec` but skips
+        // materializing the match array, and a skipped token's text is never
+        // read at all, so nothing is allocated for it.
+        let end = -1
+        let matched = null
+        if (def.literal !== undefined) {
+          if (text.startsWith(def.literal, offset)) end = offset + def.literal.length
+        } else if (def.skip) {
+          def.regex.lastIndex = offset
+          // A zero-length match would spin forever; treat it as no match.
+          if (def.regex.test(text) && def.regex.lastIndex > offset) end = def.regex.lastIndex
+        } else {
+          def.regex.lastIndex = offset
+          const match = def.regex.exec(text)
+          if (match !== null && match[0].length > 0) matched = match[0]
+          if (matched !== null) end = offset + matched.length
+        }
+
+        if (end === -1) continue
+
+        // `longerAlt` lets a keyword defer to an identifier that matches more
+        // text: `iffy` is an identifier, not `if` followed by `fy`.
+        let winner = def
+        if (def.longerAltDef) {
+          const altEnd = longerAltEnd(def, text, offset)
+          if (altEnd > end) {
+            end = altEnd
+            winner = def.longerAltDef
+          }
+        }
+
+        if (!winner.skip) {
+          const image = winner.literal !== undefined
+            ? winner.literal
+            : (winner === def && matched !== null ? matched : text.slice(offset, end))
+          // One object shape either way, so the parser's property loads stay
+          // monomorphic regardless of the position mode.
+          tokens.push({
+            type: winner.name,
+            image,
+            start: offset,
+            end,
+            line: trackLines ? line : 0,
+            col: trackLines ? offset - lineStart + 1 : 0
+          })
+        }
+
+        // A bounded scan over this token's own span, so the whole tokenize costs
+        // one pass over the input — and nothing at all in `offset` mode.
+        //
+        // An `indexOf('\n')` cursor was tried instead and looks strictly better:
+        // native scanning, and no work when the input has no newlines. It made
+        // `tokenize` slightly faster in isolation and then made parsing
+        // freshly-lexed tokens *sixty times slower* (6.8 ms -> 361 ms),
+        // reproducibly, for reasons that did not survive investigation. Do not
+        // "optimize" this without measuring the full pipeline.
+        if (trackLines) {
+          for (let j = offset; j < end; j++) {
+            if (text.charCodeAt(j) !== 10) continue
+            line++
+            lineStart = j + 1
+          }
+        }
+
+        // The transition belongs to whichever token was actually produced, so a
+        // `longerAlt` that wins brings its own mode change with it. Skipped
+        // tokens transition too: a comment can open a mode without being one.
+        if (multiMode) {
+          if (winner.popMode) {
+            if (depth === 0) {
+              throw new LexError(
+                `Token '${winner.name}' popped the initial lexer mode at ${describe(offset, line, lineStart)}`,
+                { offset, line: trackLines ? line : 0, col: trackLines ? offset - lineStart + 1 : 0 }
+              )
+            }
+            mode = stack[--depth]
+          } else if (winner.pushMode !== -1) {
+            stack[depth++] = mode
+            mode = modes[winner.pushMode]
+          }
+        }
+
+        offset = end
+        continue outer
+      }
+
+      const column = offset - lineStart + 1
+      throw new LexError(
+        trackLines
+          ? `Unexpected character '${text[offset]}' at line ${line} column ${column}${inMode(mode)}`
+          : `Unexpected character '${text[offset]}' at offset ${offset}${inMode(mode)}`,
+        { offset, line: trackLines ? line : 0, col: trackLines ? column : 0 }
+      )
+    }
+
+    // Reaching the end inside a pushed mode is not a lexer error: the tokens are
+    // all valid, and the parser gives a better message for the missing closer
+    // than "unexpected end of input" ever could.
+    return tokens
+  }
+
+  /** Names the mode in an error, but only when there is more than one to confuse. */
+  const inMode = (mode) => namesModes ? ` (in lexer mode '${mode.name}')` : ''
+  const describe = (offset, line, lineStart) =>
+    trackLines ? `line ${line} column ${offset - lineStart + 1}` : `offset ${offset}`
+
+  return { tokenize, tokenNames, positions, modeNames }
+}

package/src/methods.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The grammar combinators, as json-logic-engine methods.
+ *
+ * Every one is the same shape, because every one does the same thing: hand the
+ * node to the planner and run the closure it gives back. The per-operator
+ * behaviour lives in `plan.js` (interpreted) and `codegen.js` (compiled) —
+ * nothing here needs to know what `alt` or `manySep` mean.
+ *
+ * Two flags matter, and both are load-bearing:
+ *
+ * `lazy: true` — a combinator's arguments are alternatives and repetitions. The
+ * engine must not evaluate them before the combinator has decided whether, and
+ * how many times, each should run, so the method takes raw logic.
+ *
+ * `deterministic: false` — the optimizer inlines deterministic calls *at
+ * optimize time* (`optimizer.js`: `if (deterministic) return result()`), which
+ * for a parser would mean running it against no input before the parse begins.
+ */
+export const OPERATORS: string[];
+export function createMethods(): Record<string, any>;

package/src/methods.js

@@ -0,0 +1,61 @@
+// @ts-check
+'use strict'
+
+import { declareSync } from './plan.js'
+
+/**
+ * The grammar combinators, as json-logic-engine methods.
+ *
+ * Every one is the same shape, because every one does the same thing: hand the
+ * node to the planner and run the closure it gives back. The per-operator
+ * behaviour lives in `plan.js` (interpreted) and `codegen.js` (compiled) —
+ * nothing here needs to know what `alt` or `manySep` mean.
+ *
+ * Two flags matter, and both are load-bearing:
+ *
+ * `lazy: true` — a combinator's arguments are alternatives and repetitions. The
+ * engine must not evaluate them before the combinator has decided whether, and
+ * how many times, each should run, so the method takes raw logic.
+ *
+ * `deterministic: false` — the optimizer inlines deterministic calls *at
+ * optimize time* (`optimizer.js`: `if (deterministic) return result()`), which
+ * for a parser would mean running it against no input before the parse begins.
+ */
+
+export const OPERATORS = [
+  'consume', 'epsilon', 'seq', 'alt', 'oneOf', 'eof',
+  'many', 'many1', 'option', 'manySep', 'many1Sep',
+  'infixLeft', 'infixRight', 'prefix', 'postfix', 'between', 'as',
+  'subrule', 'label', 'action', 'lookahead', 'negLookahead', 'text'
+]
+
+const plannerOf = (engine) => {
+  const context = engine.__jlGrammar
+  if (!context) throw new Error('grammar combinators require a parser built by createParser')
+  return context.planner
+}
+
+/**
+ * The compiler calls this while generating source. Interpolating a *function*
+ * into `buildState.compile` puts it in the generated code's scope and emits a
+ * reference to it, so what comes back is a direct call into the planner's
+ * closure — no engine dispatch, no operator lookup, no per-node lookup at parse
+ * time. Returning `false` falls back to calling the method, which is what
+ * happens on an engine `createParser` never set up.
+ */
+const compileVia = (op) => (logic, buildState) => {
+  const context = buildState.engine.__jlGrammar
+  if (!context) return false
+  return buildState.compile`${declareSync(context.planner.planOp(op, logic))}(context)`
+}
+
+const combinator = (op) => ({
+  lazy: true,
+  deterministic: false,
+  compile: compileVia(op),
+  method: (logic, state, above, engine) => plannerOf(engine).planOp(op, logic)(state)
+})
+
+/** @returns {Record<string, any>} */
+export const createMethods = () =>
+  Object.fromEntries(OPERATORS.map((op) => [op, combinator(op)]))

package/src/methodsblock.js

@@ -0,0 +1,197 @@
+// @ts-check
+'use strict'
+
+/**
+ * The `methods { ... }` block: a terminal section of a `.gram` file holding the
+ * JavaScript its semantic actions call.
+ *
+ * A grammar's actions name methods — `{"formula.number": {"val": "image"}}` —
+ * and those methods have to be real functions somewhere. Without this, "somewhere"
+ * is a second file the caller has to wire up by hand.
+ *
+ * The block does not compromise the grammar's data property. It is separated
+ * textually *before* the definition language sees the source, so what
+ * `parseDefinition` returns is the same JSON-serializable object it always was,
+ * with the block carried alongside as an opaque string. A `.gram` with no block
+ * parses exactly as it did.
+ *
+ * The block is a module body: its default export is the methods table, or, with
+ * no default export, its named exports become the table. Named exports are also
+ * re-exported by a generated parser, which is how a grammar can ship helpers
+ * that its host needs — see `useFunctionSet` in sheetlang.
+ */
+
+/** Matches the block header. Anchored to a line so a stray identifier cannot start one. */
+const HEADER = /^[ \t]*methods[ \t]*\{/gm
+
+/** `import` as a single statement, which is all the CommonJS transform handles. */
+const IMPORT = /^[ \t]*import\b[^\n]*?['"][^'"]+['"][ \t]*;?[ \t]*$/gm
+
+/** `export const x`, `export function x`, `export class x`. */
+const DECLARED_EXPORT = /^[ \t]*export[ \t]+(?:const|let|var|function|class|async[ \t]+function)[ \t]+([A-Za-z_$][\w$]*)/gm
+
+/** `export { a, b as c }` — a standalone list, not a re-export from a module. */
+const EXPORT_LIST = /^[ \t]*export[ \t]*\{([^}]*)\}[ \t]*;?[ \t]*$/gm
+
+/**
+ * Splits definition source into the grammar text and the block body.
+ *
+ * The block is terminal by construction: it runs from its `{` to the last `}` in
+ * the file. That makes finding its end a search rather than a parse — no
+ * counting braces through string literals, comments and regex literals, which is
+ * where this kind of thing usually goes wrong.
+ *
+ * @param {string} source
+ * @returns {{ grammar: string, block: string | null }}
+ */
+export function splitMethodsBlock (source) {
+  HEADER.lastIndex = 0
+  let header = null
+  for (let match = HEADER.exec(source); match; match = HEADER.exec(source)) header = match
+
+  if (!header) return { grammar: source, block: null }
+
+  const open = header.index + header[0].length
+  const close = source.lastIndexOf('}')
+  if (close < open) throw new Error('methods block is not closed: no `}` after it')
+
+  const trailing = source.slice(close + 1).trim()
+  if (trailing) throw new Error(`the methods block must be the last thing in the file; found ${JSON.stringify(trailing.slice(0, 40))} after it`)
+
+  // Keep the grammar text the same length so parse errors still report true
+  // offsets; the block becomes whitespace rather than disappearing.
+  const blanked = source.slice(header.index, source.length).replace(/[^\n]/g, ' ')
+  return { grammar: source.slice(0, header.index) + blanked, block: source.slice(open, close) }
+}
+
+/**
+ * Reads a block body without executing it: which names it exports, whether it has
+ * a default export, and whether it imports anything.
+ *
+ * @param {string} body
+ */
+export function analyzeMethodsBlock (body) {
+  const names = []
+  for (const match of body.matchAll(DECLARED_EXPORT)) names.push(match[1])
+
+  // `export { a, b as c }`, including re-exports of things the block imported.
+  for (const match of body.matchAll(EXPORT_LIST)) {
+    for (const entry of match[1].split(',')) {
+      const name = entry.trim().split(/\s+as\s+/).pop()
+      if (name) names.push(name)
+    }
+  }
+
+  return {
+    names,
+    hasDefault: /^[ \t]*export[ \t]+default\b/m.test(body),
+    imports: (body.match(IMPORT) || []).map((line) => line.trim())
+  }
+}
+
+/**
+ * The block body as a plain function body: `export` stripped, and a `return`
+ * yielding the methods table.
+ *
+ * @param {string} body
+ * @param {{ names: string[], hasDefault: boolean }} info
+ */
+function asFunctionBody (body, info) {
+  const stripped = body
+    .replace(/^([ \t]*)export[ \t]+default[ \t]+/m, '$1const __default = ')
+    // `export { a, b }` names things already bound above it; the list itself goes.
+    .replace(EXPORT_LIST, '')
+    .replace(/^([ \t]*)export[ \t]+/gm, '$1')
+  const table = info.hasDefault ? '__default' : `{ ${info.names.join(', ')} }`
+  return `${stripped}\nreturn { methods: ${table}, exports: { ${info.names.join(', ')} } }`
+}
+
+/**
+ * Evaluates a block to its methods table.
+ *
+ * Needs `new Function`, so it is unavailable under a Content-Security-Policy
+ * without `unsafe-eval` — and unavailable to a block that imports anything,
+ * since a function body cannot. Both are build-time concerns: `emitModule`
+ * writes the block out as source and never runs it, and the CLI resolves an
+ * importing block through a real module.
+ *
+ * @param {string} body
+ * @returns {{ methods: Record<string, any>, exports: Record<string, any> }}
+ */
+export function evaluateMethodsBlock (body) {
+  const info = analyzeMethodsBlock(body)
+  if (info.imports.length > 0) {
+    throw new Error(
+      'this methods block imports, so it cannot be evaluated in place: ' +
+      `${JSON.stringify(info.imports[0])}. Generate a parser file from it instead ` +
+      '(`grammatik generate`), or pass `methods` explicitly.'
+    )
+  }
+  if (!info.hasDefault && info.names.length === 0) {
+    throw new Error('methods block exports nothing; it needs `export default <table>` or named exports')
+  }
+  // eslint-disable-next-line no-new-func
+  return new Function(asFunctionBody(body, info))()
+}
+
+/**
+ * Removes the indentation the block carried inside its braces, so it lands at
+ * the left margin of the generated module instead of two spaces in.
+ */
+function dedent (body) {
+  const lines = body.replace(/^\n+|\s+$/g, '').split('\n')
+  let common = Infinity
+  for (const line of lines) {
+    if (!line.trim()) continue
+    common = Math.min(common, line.length - line.trimStart().length)
+  }
+  if (!Number.isFinite(common) || common === 0) return lines.join('\n')
+  return lines.map((line) => line.slice(common)).join('\n')
+}
+
+/** Rewrites the `import` forms a CommonJS file can express as `require`. */
+function toRequire (line) {
+  const namespace = line.match(/^import[ \t]*\*[ \t]*as[ \t]+([\w$]+)[ \t]+from[ \t]*(['"][^'"]+['"])/)
+  if (namespace) return `const ${namespace[1]} = require(${namespace[2]})`
+
+  const named = line.match(/^import[ \t]*(\{[^}]*\})[ \t]*from[ \t]*(['"][^'"]+['"])/)
+  if (named) return `const ${named[1].replace(/\bas\b/g, ':')} = require(${named[2]})`
+
+  const fallback = line.match(/^import[ \t]+([\w$]+)[ \t]+from[ \t]*(['"][^'"]+['"])/)
+  if (fallback) return `const ${fallback[1]} = require(${fallback[2]}).default ?? require(${fallback[2]})`
+
+  const bare = line.match(/^import[ \t]*(['"][^'"]+['"])/)
+  if (bare) return `require(${bare[1]})`
+
+  throw new Error(`cannot express this import in CommonJS, move it or emit ES modules: ${JSON.stringify(line)}`)
+}
+
+/**
+ * The block as source for a generated module: `export` stripped so nothing
+ * escapes by accident, and the table bound to a name the file can register.
+ *
+ * @param {string} body
+ * @param {'esm'|'cjs'} format
+ * @returns {{ source: string, table: string, names: string[] }}
+ */
+export function emitMethodsBlock (body, format) {
+  const info = analyzeMethodsBlock(body)
+  if (!info.hasDefault && info.names.length === 0) {
+    throw new Error('methods block exports nothing; it needs `export default <table>` or named exports')
+  }
+
+  let source = dedent(body)
+    .replace(/^export[ \t]+default[ \t]+/m, 'const __methods = ')
+    .replace(EXPORT_LIST, '')
+    .replace(/^export[ \t]+/gm, '')
+
+  // ES modules take the imports as they are — an import declaration is legal
+  // anywhere at the top level of a module, so the block needs no hoisting.
+  if (format === 'cjs') source = source.replace(IMPORT, (line) => toRequire(line.trim()))
+
+  return {
+    source,
+    table: info.hasDefault ? '__methods' : `{ ${info.names.join(', ')} }`,
+    names: info.names
+  }
+}