parseman 0.46.0 → 0.47.0

package/src/parse-context.ts

@@ -0,0 +1,91 @@
+import type { ParseContext } from './types.ts'
+
+/**
+ * THE canonical `ParseContext` literal — the only place in the runtime where one
+ * is constructed from scratch.
+ *
+ * `ctx` is threaded through every combinator call, so it is the single most
+ * megamorphism-sensitive object in the system: every `ctx.<field>` load in
+ * `choice`/`sequence`/`regex`/`node`/… is an inline cache keyed on its hidden
+ * class. Historically the entry points built `ctx` with CONDITIONAL SPREADS
+ * (`...(cond ? { x } : {})`), which is a shape hazard, not a cost-free idiom:
+ *
+ *   - `run()` had SIX of them (root trivia, grammar trivia, scan-skip, capture
+ *     mask, tolerant, instrumentation) — up to 2^6 distinct hidden classes for
+ *     `ctx` across configurations, all landing on the same ICs.
+ *   - Fields that appear only inside a spread are ABSENT from the map on the
+ *     paths that don't take the branch. That is why `ctx._triviaLog = undefined`
+ *     is not free there: it is a property ADD (a map transition), not a store.
+ *     And it is why `delete ctx._triviaLog` is expensive on the paths where the
+ *     field IS present: a transition to dictionary mode.
+ *
+ * Declaring every field unconditionally — `undefined` when unset — collapses
+ * that to ONE realised map. Clearing a field is then a plain in-object store to
+ * an existing slot on every path, so `delete` is never needed and neither
+ * operation can transition the map.
+ *
+ * This is safe because absence and `undefined` are already interchangeable
+ * throughout the runtime: every reader tests `!== undefined` or truthiness, and
+ * none uses `in`, `hasOwnProperty`, or `Object.keys` on a `ParseContext`.
+ * `recovery/scan.ts` already restores these exact fields by assigning the saved
+ * value, which is `undefined` when the field was absent.
+ *
+ * Callers assign what they need AFTER construction; because every slot already
+ * exists those are in-object stores, and the shape is preserved. Do NOT
+ * reintroduce a conditional spread, and do NOT add a field here without also
+ * declaring it on `ParseContext`.
+ *
+ * Key ORDER matters as much as the key set — two literals with the same keys in
+ * a different order are two different maps — which is why there is one literal
+ * and not one per call site. It follows the declaration order of `ParseContext`.
+ */
+export function createParseContext(): ParseContext {
+  return {
+    trivia: undefined,
+    scanSkip: undefined,
+    triviaKindLabels: undefined,
+    captureTrivia: undefined,
+    _triviaCaptureMask: undefined,
+    trackLines: false,
+    state: undefined,
+    build: undefined,
+    _errors: undefined,
+    _tolerant: undefined,
+    _sync: undefined,
+    _rec: undefined,
+    _fe: undefined,
+    _fx: undefined,
+    _fc: undefined,
+    _probe: undefined,
+    _cstChildren: undefined,
+    _cstLeaves: undefined,
+    _cstRawChildren: undefined,
+    _triviaLog: undefined,
+    _rootTriviaLog: undefined,
+    _rootTriviaKindIndex: undefined,
+    _rootTriviaStrictScopes: undefined,
+    _rootTriviaCapture: undefined,
+    _cstTriviaLog: undefined,
+    _fields: undefined,
+    _cstBuf: undefined,
+    _routed: undefined,
+    _lineStarts: undefined,
+    _lineIndex: undefined,
+    _lineScannedTo: undefined,
+    _grammarCoverage: undefined,
+    _grammarTrace: undefined,
+  }
+}
+
+/**
+ * A `ctx` for a THROWAWAY sub-parse that must not inherit or pollute any sink —
+ * the trailing-trivia probe in `run()`/`doc()`, the trivia-kind classifier, and
+ * the no-capture trivia parses in `trivia-skip`. Identical shape to
+ * `createParseContext()`; only `trackLines`/`state` are seeded.
+ */
+export function createDetachedParseContext(trackLines: boolean, state: unknown): ParseContext {
+  const ctx = createParseContext()
+  ctx.trackLines = trackLines
+  ctx.state = state
+  return ctx
+}

package/src/plugin/direct-builder-static.ts

@@ -0,0 +1,102 @@
+/**
+ * Build-time validation for a direct node builder that may cross a compiled
+ * artifact boundary. This module deliberately belongs to the macro plugin: the
+ * public parser/compiler runtime must not import Oxc or its platform bindings.
+ */
+import { parseSync } from 'oxc-parser'
+
+const STATIC_BUILDER_GLOBALS = new Set([
+  'Array', 'Boolean', 'Date', 'JSON', 'Math', 'NaN', 'Number', 'Object', 'String',
+  'Infinity', 'parseFloat', 'parseInt', 'undefined',
+])
+
+type Ast = { type: string; [key: string]: unknown }
+
+function astArray(value: unknown): Ast[] {
+  return Array.isArray(value) ? value as Ast[] : []
+}
+
+function astChild(value: unknown): Ast | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Ast
+    : null
+}
+
+function unwrapCallbackExpression(node: Ast | undefined): Ast | undefined {
+  let current = node
+  while (current?.type === 'ParenthesizedExpression') current = astChild(current.expression) ?? undefined
+  return current
+}
+
+/**
+ * Return lexical reads that cannot cross an artifact boundary. This is an Oxc
+ * AST binding check, never a source-text heuristic: property names and plain
+ * object keys are not lexical reads. The result becomes inert metadata on the
+ * macro-produced node and is enforced later by the runtime IR re-lowerer.
+ */
+export function directBuilderUnsupportedBindings(src: string): string[] {
+  let init: Ast | undefined
+  try {
+    const parsed = parseSync('parseman-direct-builder.ts', `const _direct = (${src})`)
+    if (parsed.errors.length > 0) return ['invalid callback source']
+    const program = parsed.program as unknown as Ast
+    const statement = (program.body as Ast[] | undefined)?.[0]
+    const declaration = (statement?.declarations as Ast[] | undefined)?.[0]
+    init = unwrapCallbackExpression(declaration?.init as Ast | undefined)
+  } catch {
+    return ['invalid callback source']
+  }
+  if (init?.type !== 'ArrowFunctionExpression' || !Array.isArray(init.params)) return ['unsupported callback shape']
+  const allowed = new Set(STATIC_BUILDER_GLOBALS)
+  for (const param of init.params as Ast[]) {
+    if (param.type !== 'Identifier' || typeof param.name !== 'string') return ['unsupported parameter pattern']
+    allowed.add(param.name)
+  }
+  const unsupported = new Set<string>()
+  const reportUnsupportedNode = (ast: Ast): void => { unsupported.add(`unsupported ${ast.type}`) }
+  const read = (ast: Ast, allowedNames: ReadonlySet<string>): void => {
+    if (typeof ast.name === 'string' && allowedNames.has(ast.name)) return
+    unsupported.add(typeof ast.name === 'string' ? ast.name : 'identifier')
+  }
+  const expression = (node: unknown, allowedNames: ReadonlySet<string>): void => {
+    const ast = astChild(node)
+    if (!ast) return
+    switch (ast.type) {
+      case 'Literal': return
+      case 'Identifier': read(ast, allowedNames); return
+      case 'ParenthesizedExpression': case 'ChainExpression': case 'TSAsExpression':
+      case 'TSTypeAssertion': case 'TSNonNullExpression': expression(ast.expression, allowedNames); return
+      case 'ArrayExpression': for (const element of astArray(ast.elements)) expression(element, allowedNames); return
+      case 'ObjectExpression':
+        for (const property of astArray(ast.properties)) {
+          if (property.type === 'SpreadElement') { expression(property.argument, allowedNames); continue }
+          if (property.type !== 'Property' || property.method === true || property.kind !== 'init') { reportUnsupportedNode(property); continue }
+          if (property.computed === true) expression(property.key, allowedNames)
+          expression(property.value, allowedNames)
+        }
+        return
+      case 'MemberExpression': expression(ast.object, allowedNames); if (ast.computed === true) expression(ast.property, allowedNames); return
+      case 'CallExpression': case 'NewExpression': expression(ast.callee, allowedNames); for (const argument of astArray(ast.arguments)) expression(argument, allowedNames); return
+      case 'UnaryExpression': case 'UpdateExpression': expression(ast.argument, allowedNames); return
+      case 'BinaryExpression': case 'LogicalExpression': case 'AssignmentExpression': expression(ast.left, allowedNames); expression(ast.right, allowedNames); return
+      case 'ConditionalExpression': expression(ast.test, allowedNames); expression(ast.consequent, allowedNames); expression(ast.alternate, allowedNames); return
+      case 'SequenceExpression': for (const value of astArray(ast.expressions)) expression(value, allowedNames); return
+      case 'TemplateLiteral': for (const value of astArray(ast.expressions)) expression(value, allowedNames); return
+      case 'SpreadElement': expression(ast.argument, allowedNames); return
+      case 'ArrowFunctionExpression': {
+        const nested = new Set(allowedNames)
+        for (const param of astArray(ast.params)) {
+          if (param.type !== 'Identifier' || typeof param.name !== 'string') { reportUnsupportedNode(param); continue }
+          nested.add(param.name)
+        }
+        if (astChild(ast.body)?.type === 'BlockStatement') { reportUnsupportedNode(astChild(ast.body)!); return }
+        expression(ast.body, nested)
+        return
+      }
+      default: reportUnsupportedNode(ast); return
+    }
+  }
+  if (astChild(init.body)?.type === 'BlockStatement') unsupported.add('unsupported BlockStatement')
+  else expression(init.body, allowed)
+  return [...unsupported]
+}