mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/escomplex-ast-compat.js

@@ -1,59 +1,10 @@
 /**
- * escomplex-ast-compat.js — reconcile the `typhonjs-escomplex` code generator
- * with the Babel AST that `typhonjs-escomplex`'s own default parser emits.
- *
- * ## The upstream defect
- *
- * The kernel parses with `@babel/parser`, so every AST it analyses is a
- * **Babel** AST. But `typhonjs-escomplex-commons`'
- * `utils/ast/astSyntax.js` — the code generator that `ASTGenerator` drives —
- * was written against **ESTree**. The two disagree on node names
- * (`OptionalMemberExpression` vs a `MemberExpression` with `optional: true`)
- * and on node shapes (Babel's `RegExpLiteral` carries `pattern`/`flags`
- * directly; ESTree wraps them in a `regex` object on a `Literal`).
- *
- * That mismatch is invisible for most code because the metric traversal runs
- * off the syntax plugin's trait tables, not off `astSyntax`. `astSyntax` is
- * only reached where a trait re-serialises a **sub-AST** to synthesise a
- * Halstead operand or a function signature — nine traits do this:
- * `For`/`ForIn`/`ForOf` heads, `Function`/`FunctionExpression`/
- * `ArrowFunctionExpression` parameter lists, `Class`/`ClassExpression`
- * bodies, and `YieldExpression` arguments.
- *
- * Reach one of those with a Babel-only node and `analyzeModule()` throws —
- * aborting the whole module, not just the sub-expression. The constructs that
- * trip it are ordinary modern JavaScript:
- *
- * ```js
- * for (const t of s.split(/[^a-z]+/)) {}   // TypeError: …reading 'pattern'
- * for (const t of await xs()) {}           // …generator[node.type] is not a function
- * for (const t of a?.b) {}                 // …generator[node.type] is not a function
- * function f(a = () => import('x')) {}     // …this[node.callee.type] is not a function
- * function f(a = { ...b }) {}              // TypeError: …reading 'type'
- * function f(a = { m() {} }) {}            // TypeError: …reading 'generator'
- * function f(a = class { m() {} }) {}      // …this[statement.type] is not a function
- * ```
- *
- * The `{ ...b }` case is upstream issue #24, open and untouched since
- * 2020-12-16 with a byte-identical stack trace. The package last published in
- * June 2022 and the repo that holds the defective file has issues *disabled*,
- * so waiting for an upstream release is not a plan. Consumers of this kernel
- * previously absorbed the breakage as an allowlist of "unscorable" files that
- * grew every time someone wrote a `?.` in a loop head.
- *
- * ## What this module does
- *
- * Installs the missing handlers and repairs the two shape assumptions, on the
- * shared `astSyntax` table, once per process. Every patch is **conditional**:
- * a handler is only installed where the table lacks one, and the two repairs
- * wrap the original rather than replacing its behaviour. If a future kernel
- * bump fixes any of this upstream, the corresponding patch silently stops
- * applying and `install()` reports a shorter list — which
- * `tests/lib/escomplex-ast-compat.test.js` asserts on, so the shrinkage is
- * visible rather than silent.
- *
- * Nothing here changes the score of a file that already parses: the patched
- * paths are exactly the paths that previously threw.
+ * escomplex-ast-compat.js — patch the ESTree-written `astSyntax` code
+ * generator for the Babel AST the kernel parses. A Babel-only node in a
+ * re-serialised sub-AST (loop head, parameter default) otherwise throws for
+ * the whole module; upstream is unmaintained. Patches are conditional, so an
+ * upstream fix shrinks `applied` (a test asserts it); parseable files score
+ * unchanged.
  *
  * @see https://github.com/typhonjs-node-escomplex/typhonjs-escomplex/issues/24
  */
@@ -62,54 +13,16 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 
-/**
- * The package whose resolution anchors every `typhonjs-escomplex-commons` deep
- * import in this module.
- *
- * `escomplex-plugin-syntax-babylon` is the package that actually reads the
- * `astSyntax` table during a metric traversal, so its copy of `commons` is the
- * only one worth patching.
- *
- * Module-local on purpose. A test proves the binding by resolving from this
- * package's own root itself — which is the assertion worth making, since our
- * copy and the plugin's coincide under a hoisting installer and an
- * "ours === theirs" check would pass vacuously.
- */
+/** Reads `astSyntax` during traversal, so its copy is the one to patch. */
 const ANCHOR_PACKAGE = 'escomplex-plugin-syntax-babylon';
 
-/** Marker set on every function this module installs, for idempotency. */
 const PATCH_MARKER = Symbol.for('mandrel.escomplexAstCompat');
 
-/** Memoised result of the one-time install. */
 let installResult = null;
 
 /**
- * Resolve the shared `astSyntax` generator table.
- *
- * This is a deep import into a transitive dependency's `dist/`, which is
- * exactly as fragile as it looks — hence the soft failure. If upstream ever
- * restructures, `install()` reports `available: false` and the engine falls
- * back to today's behaviour (unscorable files, now reported explicitly by
- * the engine rather than silently scored 0).
- *
- * The patch must land on the *same* `astSyntax` table the metric traversal
- * reads, and that table is resolved by **`escomplex-plugin-syntax-babylon`**,
- * from its own location — `PluginSyntaxBabylon` requires
- * `typhonjs-escomplex-commons/dist/utils/ast/ASTGenerator` and `ASTState` binds
- * the table it finds. So `commons` is anchored through the syntax plugin's
- * resolution, not through this module's and not through the kernel's.
- *
- * Resolving it from here, or from the kernel, would be a coin flip: under a
- * hoisting installer every copy usually coincides, but under pnpm's isolated
- * layout — or as soon as anything declares `commons` at a different version —
- * the plugin can read a *different* physical copy, and the patch then lands on
- * a table nobody reads while `install()` cheerfully reports success. Anchoring
- * on the reader makes that unreachable. Note this is why a test asserting
- * "our copy === the patched copy" proves nothing: under hoisting it passes
- * vacuously — a test must resolve from the plugin's own root instead.
- *
- * `requireFn` is the test seam: a cross-checkout verification harness passes
- * its own `createRequire` so the anchor starts from that checkout's plugin.
+ * Anchored through the reader plugin — under pnpm a copy resolved from here
+ * could be one nobody reads. A fragile deep import, so failure is soft.
  *
  * @param {NodeJS.Require} [requireFn]
  * @returns {Record<string, Function>|null}
@@ -132,8 +45,6 @@ function resolveSyntaxTable(requireFn = require) {
 }
 
 /**
- * Tag a handler as ours so a second `install()` is a no-op.
- *
  * @template {Function} F
  * @param {F} fn
  * @returns {F}
@@ -144,9 +55,6 @@ function mark(fn) {
 }
 
 /**
- * Install `name` only if the table has no handler for it. Returns whether the
- * install happened, so the caller can report the applied surface.
- *
  * @param {Record<string, Function>} table
  * @param {string} name
  * @param {Function} handler
@@ -159,10 +67,7 @@ function addMissing(table, name, handler) {
 }
 
 /**
- * Build an ESTree-shaped stand-in for a Babel `ObjectMethod` / `ClassMethod`,
- * whose function bits sit on the node itself rather than under `value`.
- * `MethodDefinition` reads `node.value.{generator,params,body}`, so handing it
- * a synthesized `value` lets the original handler do the work unchanged.
+ * Moves a Babel method's function bits under `value` for `MethodDefinition`.
  *
  * @param {object} node
  * @returns {object}
@@ -185,16 +90,10 @@ function asMethodDefinition(node) {
 }
 
 /**
- * Patch the shared `astSyntax` table. Idempotent; safe to call from every
- * entry point that is about to run `analyzeModule`.
+ * Idempotent via PATCH_MARKER.
  *
- * @param {{ requireFn?: NodeJS.Require, memoise?: boolean }} [options] Test
- *   seam only — see {@link resolveSyntaxTable}. Production callers pass
- *   nothing.
- * @returns {{ available: boolean, applied: string[] }} `available` is false
- *   when the upstream internals could not be resolved. `applied` names each
- *   patch that was actually needed, so an upstream fix shows up as a
- *   shorter list.
+ * @param {{ requireFn?: NodeJS.Require, memoise?: boolean }} [options]
+ * @returns {{ available: boolean, applied: string[] }}
  */
 export function install(options = {}) {
   const { requireFn, memoise = true } = options;
@@ -212,11 +111,8 @@ export function install(options = {}) {
     if (addMissing(table, name, handler)) applied.push(name);
   };
 
-  // ---- Repair 1: Babel's RegExpLiteral shape -------------------------------
-  // Upstream reads `node.regex.pattern`, which only exists on an ESTree
-  // `Literal`. Babel puts `pattern`/`flags` on the node. Wrapped rather than
-  // replaced so the ESTree delegate path (`Literal` → `RegExpLiteral`) keeps
-  // its exact original output.
+  // Babel puts `pattern`/`flags` on the node; upstream reads `node.regex`.
+  // Wrapped so the ESTree `Literal` delegate path keeps its exact output.
   if (
     typeof table.RegExpLiteral === 'function' &&
     !table.RegExpLiteral[PATCH_MARKER]
@@ -235,25 +131,10 @@ export function install(options = {}) {
     applied.push('RegExpLiteral');
   }
 
-  // ---- Repair 2: ObjectExpression's hard `this.Property()` dispatch --------
-  // `ObjectExpression` calls `this.Property(el)` on every element regardless
-  // of the element's actual type. Two Babel shapes get mis-routed by that:
-  //
-  //   `{ ...b }`    → a `SpreadElement` lands in `Property`, which reads
-  //                   `node.key.type` and throws. Upstream issue #24.
-  //   `{ m() {} }`  → an `ObjectMethod` has `kind: 'method'`, so `Property`'s
-  //                   `node.kind[0] !== 'i'` test sends the raw Babel node to
-  //                   `MethodDefinition`, which reads `node.value.generator`
-  //                   and throws.
-  //
-  // Patching `Property` rather than `ObjectExpression` keeps the patch small
-  // and leaves the indentation-sensitive object serialisation untouched:
-  // anything arriving here that is not actually a property node gets
-  // re-dispatched on its real type.
-  //
-  // `Property` and `ObjectProperty` are excluded from re-dispatch because the
-  // table aliases `ObjectProperty` to `Property` — re-dispatching either would
-  // recurse into this wrapper forever.
+  // `ObjectExpression` calls `this.Property(el)` for every element, so a
+  // `SpreadElement` or `ObjectMethod` is mis-routed and throws. Re-dispatch
+  // non-property nodes on their real type. `Property`/`ObjectProperty` are
+  // excluded: the table aliases them, so re-dispatch would recurse forever.
   if (typeof table.Property === 'function' && !table.Property[PATCH_MARKER]) {
     const original = table.Property;
     const PROPERTY_TYPES = new Set(['Property', 'ObjectProperty']);
@@ -271,9 +152,6 @@ export function install(options = {}) {
     applied.push('Property');
   }
 
-  // ---- Missing handlers: Babel-only node types ----------------------------
-
-  // `await x` — mirrors upstream's `YieldExpression`.
   add('AwaitExpression', function AwaitExpression(node, state) {
     const output = state.output;
     output.write('await ');
@@ -281,9 +159,7 @@ export function install(options = {}) {
     if (node.argument) this[node.argument.type](node.argument, state);
   });
 
-  // `a?.b` / `a?.[b]` — mirrors upstream's `MemberExpression`, with `?.`
-  // recorded as its own operator so optional access is not counted as plain
-  // member access.
+  // `?.` is its own operator, not counted as plain member access.
   add(
     'OptionalMemberExpression',
     function OptionalMemberExpression(node, state) {
@@ -302,7 +178,6 @@ export function install(options = {}) {
     },
   );
 
-  // `a?.()` — mirrors upstream's `CallExpression`.
   add('OptionalCallExpression', function OptionalCallExpression(node, state) {
     this[node.callee.type](node.callee, state);
     state.output.write('?.');
@@ -310,24 +185,20 @@ export function install(options = {}) {
     ASTUtil().formatSequence(node.arguments ?? [], state, this);
   });
 
-  // The callee node of a dynamic `import(...)`. Babel models the `import`
-  // keyword as its own node type; ESTree has no equivalent.
+  // Callee of a dynamic `import(...)`; ESTree has no equivalent node.
   add('Import', function Import(_node, state) {
     state.output.write('import');
     state.output.operators.push('import()');
   });
 
-  // `{ m() {} }` / `{ get m() {} }` — Babel's ObjectMethod.
   add('ObjectMethod', function ObjectMethod(node, state) {
     return this.MethodDefinition(asMethodDefinition(node), state);
   });
 
-  // `class { m() {} }` — Babel's ClassMethod (ESTree: MethodDefinition).
   add('ClassMethod', function ClassMethod(node, state) {
     return this.MethodDefinition(asMethodDefinition(node), state);
   });
 
-  // `class { p = 1 }` — Babel's ClassProperty (ESTree: PropertyDefinition).
   const classProperty = function ClassProperty(node, state) {
     const output = state.output;
     if (node.static) {
@@ -357,14 +228,7 @@ export function install(options = {}) {
 }
 
 /**
- * `ASTUtil` is only needed by the `OptionalCallExpression` handler, and only at
- * call time — resolving it lazily keeps `install()` free of a second deep
- * import that could fail at module load. Anchored through the syntax plugin
- * for the same reason as {@link resolveSyntaxTable}.
- *
- * `formatSequence` is a pure helper that takes the traveler and state as
- * arguments, so which copy answers is immaterial — but resolving it the same
- * way keeps one rule in this file rather than two.
+ * Lazy, so `install()` has no second deep import that could fail at load.
  *
  * @returns {{ formatSequence: Function }}
  */
@@ -375,8 +239,3 @@ function ASTUtil() {
   );
   return mod?.default ?? mod;
 }
-
-// A test that needs to re-run the install against the already-patched table
-// passes `{ memoise: false }` rather than resetting module state — the patches
-// are self-detecting via PATCH_MARKER, so a non-memoised re-run is exactly the
-// idempotency assertion worth making.

package/.agents/scripts/lib/escomplex-kernel.js

@@ -1,72 +1,13 @@
 /**
- * escomplex-kernel.js — the complexity kernel's parse and dispatch layers,
- * in-repo.
- *
- * ## Why this file exists
- *
- * `typhonjs-escomplex` was a thin shell around four packages that do all the
- * actual work. The shell contributed two things: a parser front-end
- * (`@typhonjs/babel-parser`, a ~100-LOC shim over `@babel/parser`) and a
- * generic plugin bus (`typhonjs-plugin-manager`, used as a hardcoded
- * two-plugin synchronous dispatcher). Nine packages of plumbing hang off
- * those two, and none of it computes anything.
- *
- * What this does **not** do is remove `core-js@2`. Four of the retained
- * metric-core packages `require('babel-runtime/core-js/*')` themselves, so it
- * is load-bearing for the code that stays; a change that claimed otherwise
- * would be unshippable. What it buys instead is an honest closure —
- * `babel-runtime` is required by those packages and declared by none of them,
- * so today it resolves only because the removed plumbing hoists it. Declaring
- * it turns an accident into a contract.
- *
- * This module reimplements exactly those two layers over the retained metric
- * core — `typhonjs-escomplex-commons`, `escomplex-plugin-metrics-module`,
- * `escomplex-plugin-syntax-babylon`, `typhonjs-ast-walker` — which compute
- * every score. Nothing here computes a metric; the scores come from the same
- * packages as before, which is why they do not move.
- *
- * ## The equivalence contract
- *
- * Reproducing the displaced shell's *behaviour* means reproducing three
- * details it never documented:
- *
- * 1. **The parser's fixed plugin list**, verbatim and in order, with
- *    `sourceType: 'unambiguous'` — see `PARSER_PLUGINS` below. The list is
- *    what makes a `.ts` file, a decorator or a pipeline operator parse at
- *    all, and `unambiguous` is what lets a CommonJS script and an ES module
- *    both score.
- * 2. **Both plugin instances, in registration order** — syntax first, then
- *    metrics. The metrics plugin reads trait tables the syntax plugin put on
- *    the event.
- * 3. **One mutable event object per dispatch**, threaded through every plugin
- *    in turn, with the caller reading the mutations back off it. The displaced
- *    bus also stamped `$$plugin_invoke_count` / `$$plugin_invoke_names` onto
- *    every event's data; no plugin and no report reads them, so they are not
- *    reproduced.
- *
- * Equivalence is not asserted by reasoning: `tests/lib/escomplex-kernel.test.js`
- * replays a corpus captured under the displaced kernel *before* it left the
- * tree (`tests/fixtures/escomplex-kernel-parity/`), because afterwards there is
- * nothing left to compare against.
- *
- * ## The one uncontrolled input
- *
- * `.agents/` materializes into a consumer's repository root, so `@babel/parser`
- * resolves from **their** `node_modules`. The preflight guard checks presence,
- * not range, and `@babel/parser@8` is GA and rejects several names in the
- * fixed plugin list. A manifest range documents the requirement; it does not
- * enforce it. So the resolved major is asserted here, at load, with an error
- * that names the problem — rather than surfacing as an opaque plugin-list
- * syntax error partway through a scan.
+ * escomplex-kernel.js — in-repo parse and plugin-dispatch layers over the
+ * retained metric core, which computes every score. A parity corpus pins
+ * equivalence with the displaced shell. `@babel/parser` resolves from the
+ * consumer's tree and v8 rejects the plugin list, so its major is asserted
+ * at load.
  */
 
-// Every metric-core package is reached by a STATIC import specifier with an
-// explicit `.js` extension. That is not style: `tests/scripts/
-// runtime-deps-drift.test.js` scans for literal `import`/`require` callees, so
-// a package reached through an aliased `createRequire` would be a runtime
-// dependency that is neither declared nor preflighted. The extensions are
-// mandatory because `typhonjs-escomplex-commons` ships an empty
-// `package.json` — no `main`, no `exports` — so a deep path is the only door.
+// Static `.js` specifiers: the drift test scans literal imports, and
+// `commons` has no `main`/`exports`.
 import { parse as babelParse } from '@babel/parser';
 import PluginMetricsModule from 'escomplex-plugin-metrics-module/dist/PluginMetricsModule.js';
 import PluginSyntaxBabylon from 'escomplex-plugin-syntax-babylon/dist/PluginSyntaxBabylon.js';
@@ -76,16 +17,7 @@ import ModuleReport from 'typhonjs-escomplex-commons/dist/module/report/ModuleRe
 import { install as installAstCompat } from './escomplex-ast-compat.js';
 import { describeParserMajorError } from './runtime-deps/parser-major.js';
 
-/**
- * The displaced parser shim's plugin list, verbatim and in order.
- *
- * Order is preserved because it is cheap to preserve, not because a
- * reordering is known to matter. The two entries with options
- * (`decorators`, `pipelineOperator`) carry the shim's exact settings —
- * `decoratorsBeforeExport: false` and the `minimal` pipeline proposal — which
- * decide whether decorated classes and `|>` parse. Re-cloned per parse so a
- * parser that mutated its options could not poison a later call.
- */
+/** The displaced shim's list, verbatim; cloned per parse. */
 const PARSER_PLUGINS = [
   'asyncGenerators',
   'bigInt',
@@ -112,21 +44,12 @@ const PARSER_PLUGINS = [
   'typescript',
 ];
 
-/**
- * The two plugins, in registration order: syntax populates the trait tables
- * the metrics plugin then reads. Neither defines `onPluginLoad`, and the
- * displaced bus was constructed without an eventbus, so there is no plugin
- * lifecycle or eventbus coupling to reproduce — only this list.
- */
+/** Registration order matters: syntax populates what metrics reads. */
 const PLUGINS = [
   ['escomplex-plugin-syntax-babylon', new PluginSyntaxBabylon()],
   ['escomplex-plugin-metrics-module', new PluginMetricsModule()],
 ];
 
-// The kernel's code generator predates the Babel AST its own parser emits, so
-// ordinary modern syntax aborts a WHOLE module — see `escomplex-ast-compat.js`
-// for the defect and the upstream status. Installing at the kernel rather than
-// at each caller makes the next scoring entrypoint correct by construction.
 installAstCompat();
 
 const parserProblem = describeParserMajorError();
@@ -135,17 +58,11 @@ if (parserProblem !== null) {
 }
 
 /**
- * Run one synchronous plugin dispatch.
- *
- * Reproduces the displaced bus's `invokeSyncEvents` for the degenerate shape
- * this kernel uses: no `copyProps` (the shell passed `void 0` at every call
- * site, so the merge base was always `{}`), no eventbus, and the caller
- * reading its results back off the same mutated `data` object every plugin
- * saw.
+ * Both plugins mutate the same `data`.
  *
- * @param {string} method Plugin method name, e.g. `onEnterNode`.
- * @param {object} passthru Properties placed on the event's `data`.
- * @returns {object} The event `data`, after every plugin has mutated it.
+ * @param {string} method
+ * @param {object} passthru
+ * @returns {object}
  */
 function dispatch(method, passthru) {
   const event = {
@@ -164,9 +81,7 @@ function dispatch(method, passthru) {
 }
 
 /**
- * The `ignoreKeys` a syntax trait wants withheld from the walker, if any.
- *
- * @param {object|undefined} syntax The trait entry for this node type.
+ * @param {object|undefined} syntax
  * @param {object} node
  * @param {object} parent
  * @returns {string[]}
@@ -178,9 +93,7 @@ function traitIgnoreKeys(syntax, node, parent) {
 }
 
 /**
- * The new scope a syntax trait opens at this node, if any.
- *
- * @param {object|undefined} syntax The trait entry for this node type.
+ * @param {object|undefined} syntax
  * @param {object} node
  * @param {object} parent
  * @returns {object|null}
@@ -191,17 +104,8 @@ function traitNewScope(syntax, node, parent) {
 }
 
 /**
- * Build the walker visitor for one module traversal.
- *
- * Split out of {@link analyzeModule} so the enter/exit symmetry is readable
- * side by side: each resolves the trait's scope, brackets the `scopeControl`
- * mutation with a pre/post dispatch, and straddles it with the node dispatch
- * in opposite order on the way in and out.
- *
- * The two event shapes are not interchangeable, and the difference is the
- * displaced shell's, not a simplification available here: node events carry
- * `syntaxes` and scope events do not, and a scope event names its scope
- * `newScope` on the way in but `scope` on the way out.
+ * Event shapes are the displaced shell's: scope events lack `syntaxes`, and
+ * name the scope `newScope` on entry but `scope` on exit.
  *
  * @param {{
  *   moduleReport: object,
@@ -248,16 +152,10 @@ function buildVisitor({ moduleReport, scopeControl, syntaxes, settings }) {
 }
 
 /**
- * Parse and score one module.
- *
- * Drop-in replacement for the displaced `escomplex.analyzeModule(source)`:
- * same report object, same `finalize()` shape, same thrown errors for source
- * the kernel cannot handle.
- *
- * @param {string} source JavaScript (or TypeScript) source text.
- * @param {object} [options] Passed to the plugins' `onConfigure`, as before.
- * @returns {object} The finalized module report.
- * @throws {SyntaxError} Propagated from the parser, as before.
+ * @param {string} source
+ * @param {object} [options]
+ * @returns {object}
+ * @throws {SyntaxError}
  */
 export function analyzeModule(source, options = {}) {
   const ast = babelParse(source, {