@skmtc/core 0.0.984 → 0.16.2

package/script/anchors/CaptureSink.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * @fileoverview Render-phase attribution capture.
+ *
+ * The capture mechanism for gen-maps. A {@link CaptureSink} is owned by
+ * {@link import('@/context/RenderContext.ts').RenderContext} for the
+ * duration of the single render pass and published to snippets through the
+ * shared {@link CaptureChannel}: every `SnippetBase` instance self-wraps
+ * its `toString` at construction (own-property wrapper), and the wrapper
+ * observes into the channel's sink while the **capture interval** is open
+ * — the span while `channel.sink` is set. Each `toString` invocation is
+ * observed into an **occurrence tree** — one node per call, keyed by
+ * invocation, not by instance. The wrapper is a pure pass-through: it
+ * returns the subclass `toString`'s output verbatim and only *observes*
+ * it.
+ *
+ * This replaces the old module-global constructor registry +
+ * render-time prototype wrapping: discovery is per-instance (self-wrap at
+ * birth — snippets constructed mid-render are captured too), the sink
+ * travels by object reference through `this.context` (no duplicate-module
+ * silent-failure hazard), and opening/closing the interval is a flag flip
+ * (no install/restore pass). Outside the interval there is no state, so a
+ * stray `toString()` during the generate phase captures nothing.
+ *
+ * Offset capture (this is the "store output, locate via `indexOf`" cut —
+ * RESUME §3.3 option (a)): each node stores its rendered output; after a
+ * file renders, {@link CaptureSink.spansForFile} locates each node's output
+ * inside its parent's output (moving cursor) to recover byte ranges. A
+ * later memory-efficient cut computes offsets inline as the stack unwinds
+ * and frees the strings; the resolver interface ({offset,length,children})
+ * is unchanged by that switch.
+ *
+ * Offsets are UTF-16 code-unit indices (`indexOf` / `String.length`),
+ * consistent with the rest of the attribution layer.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _CaptureSink_stack, _CaptureSink_fileRoots, _CaptureSink_active;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureSink = void 0;
+const Definition_js_1 = require("../dsl/Definition.js");
+/**
+ * Transient capture state for one render pass. Owned by `RenderContext`.
+ *
+ * `active` gates {@link observe}: only while a file is rendering (inside
+ * {@link captureFile}) does an observation record; otherwise `observe` is
+ * an inert pass-through. This keeps a stray `toString()` between files
+ * from polluting the tree even while the capture interval is open.
+ */
+class CaptureSink {
+    constructor() {
+        /** Live stack of occurrences currently rendering (innermost last). */
+        _CaptureSink_stack.set(this, []
+        /** Roots for the file currently rendering; `null` when no file is active. */
+        );
+        /** Roots for the file currently rendering; `null` when no file is active. */
+        _CaptureSink_fileRoots.set(this, null
+        /** Whether a file render is in progress (wrapper observes only then). */
+        );
+        /** Whether a file render is in progress (wrapper observes only then). */
+        _CaptureSink_active.set(this, false
+        /** True while a file is rendering — {@link observe} checks this. */
+        );
+    }
+    /** True while a file is rendering — {@link observe} checks this. */
+    get active() {
+        return __classPrivateFieldGet(this, _CaptureSink_active, "f");
+    }
+    /**
+     * Render one file with capture active and return its text plus the byte
+     * spans for every contributing Definition / Snippet. The wrapper builds
+     * the occurrence tree as `render()` runs; spans are resolved from that
+     * tree against the returned file text.
+     */
+    captureFile(render) {
+        const roots = [];
+        const previousRoots = __classPrivateFieldGet(this, _CaptureSink_fileRoots, "f");
+        const previousActive = __classPrivateFieldGet(this, _CaptureSink_active, "f");
+        const baseDepth = __classPrivateFieldGet(this, _CaptureSink_stack, "f").length;
+        __classPrivateFieldSet(this, _CaptureSink_fileRoots, roots, "f");
+        __classPrivateFieldSet(this, _CaptureSink_active, true, "f");
+        try {
+            const text = render();
+            return { text, spans: spansFromRoots(text, roots) };
+        }
+        finally {
+            __classPrivateFieldSet(this, _CaptureSink_fileRoots, previousRoots, "f");
+            __classPrivateFieldSet(this, _CaptureSink_active, previousActive, "f");
+            // Defensive rebalance: a thrown subclass `toString` unwinds via the
+            // per-call `finally` below, but guard against any leak.
+            __classPrivateFieldGet(this, _CaptureSink_stack, "f").length = baseDepth;
+        }
+    }
+    /**
+     * Observe one `toString` invocation. The per-instance wrapper installed
+     * by the `SnippetBase` constructor calls this whenever the capture
+     * interval is open. Outside a file render (`active` false) it is a pure
+     * pass-through; inside one it pushes an occurrence node, links it to its
+     * parent (or the file roots), runs the real `toString`, records the
+     * output, and returns it verbatim.
+     *
+     * @throws when `producer` is already live on the stack — a snippet that
+     *   composes itself, which would otherwise infinitely recurse.
+     */
+    observe(producer, impl) {
+        if (!__classPrivateFieldGet(this, _CaptureSink_active, "f")) {
+            return impl.call(producer);
+        }
+        for (const node of __classPrivateFieldGet(this, _CaptureSink_stack, "f")) {
+            if (node.producer === producer) {
+                throw new Error('CaptureSink: render cycle detected — a Snippet recursively ' +
+                    'includes itself via composition. Break the cycle in your ' +
+                    'generator (e.g. cache an Identifier and embed it instead).');
+            }
+        }
+        const node = { producer, output: '', children: [] };
+        const parent = __classPrivateFieldGet(this, _CaptureSink_stack, "f")[__classPrivateFieldGet(this, _CaptureSink_stack, "f").length - 1];
+        (parent ? parent.children : (__classPrivateFieldGet(this, _CaptureSink_fileRoots, "f") ?? [])).push(node);
+        __classPrivateFieldGet(this, _CaptureSink_stack, "f").push(node);
+        try {
+            node.output = impl.call(producer);
+            return node.output;
+        }
+        finally {
+            __classPrivateFieldGet(this, _CaptureSink_stack, "f").pop();
+        }
+    }
+}
+exports.CaptureSink = CaptureSink;
+_CaptureSink_stack = new WeakMap(), _CaptureSink_fileRoots = new WeakMap(), _CaptureSink_active = new WeakMap();
+/**
+ * Resolve byte spans for one file from its captured occurrence roots.
+ *
+ * Only Definition occurrences are file-level roots (matching the previous
+ * resolver, which iterated `file.definitions`); each is located inside the
+ * file text via `indexOf` from a moving cursor, then its descendants are
+ * located within it. Returns spans in document order (Definitions first,
+ * then their inner Snippets depth-first). Children that can't be found
+ * (parent reshaped the text) and zero-length nodes are dropped rather than
+ * mis-attributed.
+ */
+const spansFromRoots = (fileText, roots) => {
+    const spans = [];
+    let cursor = 0;
+    for (const root of roots) {
+        // File-level roots are Definitions; non-Definition file-scope renders
+        // (none today) carry no addressable region in the resolver's model.
+        // Any language's Definition is a `DefinitionBase` — the engine is
+        // language-blind, so this must not name a concrete (`Definition`) class.
+        if (!(root.producer instanceof Definition_js_1.DefinitionBase))
+            continue;
+        const defText = root.output;
+        if (defText.length === 0)
+            continue;
+        const index = fileText.indexOf(defText, cursor);
+        if (index < 0)
+            continue;
+        spans.push({ from: index, to: index + defText.length, producer: root.producer });
+        walkChildren(root, index, spans);
+        cursor = index + defText.length;
+    }
+    return spans;
+};
+/**
+ * Recurse a node's children, locating each child's output inside the
+ * parent's output (moving cursor so identical sibling text — two
+ * `z.string()` calls — attributes to its own position) and emitting a span.
+ */
+const walkChildren = (parent, parentStart, out) => {
+    let cursor = 0;
+    for (const child of parent.children) {
+        const childText = child.output;
+        if (childText.length === 0)
+            continue;
+        const index = parent.output.indexOf(childText, cursor);
+        if (index < 0)
+            continue;
+        const from = parentStart + index;
+        out.push({ from, to: from + childText.length, producer: child.producer });
+        walkChildren(child, from, out);
+        cursor = index + childText.length;
+    }
+};

package/script/anchors/ParserAdapter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Parser-agnostic interface for AST descend + landmark
+ * resolution. Per plan §8.3.
+ *
+ * One implementation today (`oxcAdapter`, backed by the Rust
+ * oxc-parser via napi). v1 originally landed `tscAdapter` but tsc's
+ * npm package can't bundle into a Worker (pulls in
+ * `source-map-support`), so we swapped to oxc — Spike 1b had already
+ * validated it works in Deno and is ~3.2× faster on raw parse.
+ * Consumers (`postPass`, the viewer's re-anchor path, the VSCode
+ * extension) import only through this interface so swapping parsers
+ * is a one-line change at the wire-up site.
+ *
+ * The interface is intentionally narrow — just what the post-pass
+ * and re-anchor flows need. Each adapter keeps its own node
+ * representation (`NodeHandle` is opaque to consumers) and exposes
+ * the operations below.
+ */
+/**
+ * Opaque per-adapter node reference. Consumers never inspect the
+ * inside; they pass handles through {@link ParserAdapter} operations
+ * that take care of the adapter-specific shape.
+ */
+export type NodeHandle = unknown;
+/**
+ * Parsed file handle. Same opacity story as {@link NodeHandle}.
+ */
+export type ParsedFile = unknown;
+/**
+ * Landmark name + AST path tuple. `landmark` is the top-level export
+ * name (`'User'`, `'createUser'`) the span lives under; `path` is a
+ * `forEachChild`-indexed descent from the landmark to the span's
+ * narrowest enclosing node. Empty `landmark` means "outside any
+ * landmark"; the consumer of {@link buildSidecar} treats that as a
+ * skip.
+ */
+export type LandmarkLocation = {
+    landmark: string;
+    path: number[];
+};
+/**
+ * Adapter contract. Implementations stay pure — no I/O, no global
+ * state. The conformance suite in plan §8.4 runs against each.
+ */
+export interface ParserAdapter {
+    /**
+     * Display id for the adapter — `"tsc@5.6.3"`, `"oxc@0.x.y"`. Lands
+     * on the sidecar's `parser` field so re-anchor consumers can warn
+     * on mismatch.
+     */
+    readonly id: string;
+    /** Parse a source string. Throws on syntax errors. */
+    parse(filePath: string, source: string): ParsedFile;
+    /**
+     * Index every top-level export (`export const X`, `export function
+     * f`, `export type T`, default export, etc.) so subsequent
+     * `landmarkFor` calls run in constant time per span.
+     */
+    collectLandmarks(file: ParsedFile): Map<string, NodeHandle>;
+    /**
+     * Descend through children to the smallest AST node whose byte
+     * range fully encloses `[from, to)`. Returns the file's root if
+     * nothing more specific contains the range.
+     */
+    smallestEnclosing(file: ParsedFile, from: number, to: number): NodeHandle;
+    /**
+     * Walk up from `node` to the nearest landmark (by entry in the
+     * `landmarks` map). Returns the landmark's export name plus the
+     * forEachChild-indexed path from the landmark down to `node`.
+     *
+     * If no landmark is found in the ancestor chain, returns
+     * `{ landmark: '', path: [] }` — sentinel "outside any landmark".
+     */
+    ascendToLandmark(node: NodeHandle, landmarks: Map<string, NodeHandle>): LandmarkLocation;
+}
+//# sourceMappingURL=ParserAdapter.d.ts.map

package/script/anchors/ParserAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParserAdapter.d.ts","sourceRoot":"","sources":["../../src/anchors/ParserAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAA;AAEhC;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAA;AAEhC;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,sDAAsD;IACtD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAEnD;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAE3D;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAA;IAEzE;;;;;;;OAOG;IACH,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,gBAAgB,CAAA;CACzF"}

package/script/anchors/ParserAdapter.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @fileoverview Parser-agnostic interface for AST descend + landmark
+ * resolution. Per plan §8.3.
+ *
+ * One implementation today (`oxcAdapter`, backed by the Rust
+ * oxc-parser via napi). v1 originally landed `tscAdapter` but tsc's
+ * npm package can't bundle into a Worker (pulls in
+ * `source-map-support`), so we swapped to oxc — Spike 1b had already
+ * validated it works in Deno and is ~3.2× faster on raw parse.
+ * Consumers (`postPass`, the viewer's re-anchor path, the VSCode
+ * extension) import only through this interface so swapping parsers
+ * is a one-line change at the wire-up site.
+ *
+ * The interface is intentionally narrow — just what the post-pass
+ * and re-anchor flows need. Each adapter keeps its own node
+ * representation (`NodeHandle` is opaque to consumers) and exposes
+ * the operations below.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/anchors/attribute.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Derive an Attribution tuple from a producer.
+ *
+ * `attribute()` is a pure function over a `SnippetBase` — it reads
+ * the producer's `generatorKey`, the producer's own `stackTrail` (if
+ * any), and the producer's `Definition`-shaped identifier (if applicable),
+ * and returns the canonical
+ * `{ generatorId, schemaPointer, variant, definitionName, producerName }`
+ * tuple. Used by sidecar emission (Phase C) and the viewer (Phase E).
+ *
+ * `genVersion` is intentionally not populated here. The version → id
+ * map is plumbed through Phase D when the CLI reads each entry's
+ * `denoJson.version`; this layer stays pure.
+ */
+import type { SnippetBase } from '../dsl/SnippetBase.js';
+import type { Attribution } from './types.js';
+/**
+ * Derive the attribution tuple for a producer.
+ *
+ * Producers without a `generatorKey` (rare — only test doubles or
+ * runtime-orphaned Snippets) get `generatorId: '<unknown>'` and a
+ * key-derived fallback pointer.
+ */
+export declare const attribute: (producer: SnippetBase) => Attribution;
+//# sourceMappingURL=attribute.d.ts.map

package/script/anchors/attribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute.d.ts","sourceRoot":"","sources":["../../src/anchors/attribute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,WAAW,KAAG,WAuBjD,CAAA"}

package/script/anchors/attribute.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * @fileoverview Derive an Attribution tuple from a producer.
+ *
+ * `attribute()` is a pure function over a `SnippetBase` — it reads
+ * the producer's `generatorKey`, the producer's own `stackTrail` (if
+ * any), and the producer's `Definition`-shaped identifier (if applicable),
+ * and returns the canonical
+ * `{ generatorId, schemaPointer, variant, definitionName, producerName }`
+ * tuple. Used by sidecar emission (Phase C) and the viewer (Phase E).
+ *
+ * `genVersion` is intentionally not populated here. The version → id
+ * map is plumbed through Phase D when the CLI reads each entry's
+ * `denoJson.version`; this layer stays pure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attribute = void 0;
+const GeneratorKeys_js_1 = require("../dsl/GeneratorKeys.js");
+const Definition_js_1 = require("../dsl/Definition.js");
+/**
+ * Derive the attribution tuple for a producer.
+ *
+ * Producers without a `generatorKey` (rare — only test doubles or
+ * runtime-orphaned Snippets) get `generatorId: '<unknown>'` and a
+ * key-derived fallback pointer.
+ */
+const attribute = (producer) => {
+    const key = producer.generatorKey;
+    const parsed = key ? (0, GeneratorKeys_js_1.fromGeneratorKey)(key) : undefined;
+    return {
+        generatorId: key && parsed ? (0, GeneratorKeys_js_1.toGeneratorId)(key) : '<unknown>',
+        // The producer's own position wins when it has one; otherwise fall
+        // back to the key-derived pointer. The string conversion happens
+        // here, once — `StackTrail` is carried everywhere upstream.
+        // `toSchemaPointer()` (not `toJsonPointer()`) strips the run's
+        // operational prefix so the pointer is document-relative and
+        // resolvable against the input schema — matching the key-derived
+        // fallback's form.
+        schemaPointer: producer.stackTrail.isEmpty()
+            ? schemaPointerFromKey(parsed)
+            : producer.stackTrail.toSchemaPointer(),
+        variant: parsed && 'variant' in parsed ? parsed.variant : 'main',
+        definitionName: producer instanceof Definition_js_1.DefinitionBase ? producer.identifier.name : undefined,
+        // The producer's class name — `var X = class extends …` still yields
+        // `X.name === 'X'` via named evaluation, so this survives `deno bundle`
+        // (as long as the bundle isn't minified / collision-renamed).
+        producerName: producer.constructor.name
+    };
+};
+exports.attribute = attribute;
+/**
+ * Compute a fallback schema pointer from the parsed generator key when
+ * the producer has no position of its own (empty trail).
+ *
+ * Pointers are **protocol-agnostic** — no `oas:` / `gql:` prefix; the
+ * protocol is a property of the run's input schema, not of each pointer.
+ *
+ * - OAS operation → `#/paths/<escaped-path>/<method>`
+ * - GQL operation → `<rootKind>.<fieldName>`
+ * - Model → `#/components/schemas/<refName>`
+ * - Generator-only / no key → `''` (no schema location to point at)
+ */
+const schemaPointerFromKey = (parsed) => {
+    if (!parsed)
+        return '';
+    switch (parsed.type) {
+        case 'oasOperation':
+            return `#/paths/${escapeJsonPointer(parsed.path)}/${parsed.method}`;
+        case 'webhook':
+            return `#/webhooks/${escapeJsonPointer(parsed.name)}/${parsed.method}`;
+        case 'gqlOperation':
+            return `${parsed.rootKind}.${parsed.fieldName}`;
+        case 'model':
+            return `#/components/schemas/${parsed.refName}`;
+        case 'generator-only':
+            return '';
+        default: {
+            const _exhaustive = parsed;
+            throw new Error(`Unhandled generator key type: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+};
+/**
+ * RFC 6901 JSON Pointer segment escaping. `~` → `~0`, `/` → `~1`.
+ * Order matters: escape `~` first so the `/` replacement doesn't
+ * later mangle the `~1` produced by the `~` step.
+ */
+const escapeJsonPointer = (segment) => segment.replace(/~/g, '~0').replace(/\//g, '~1');

package/script/anchors/buildSidecar.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Assemble a {@link Sidecar} from resolved spans +
+ * attributions + landmark/path pairs.
+ *
+ * Pure function: no I/O, no parser, no global state. The AST landmark
+ * resolution step (plan §4.2) is *not* done here — the caller passes
+ * pre-resolved `(landmark, path)` pairs alongside each span. This
+ * separation is deliberate:
+ *
+ * - The sidecar shape + interning logic can be tested without a
+ *   parser (`FakeParser` is enough).
+ * - When tsc / oxc adapters land (plan §8), they're swap-ins behind
+ *   the `ParserAdapter` interface — no churn here.
+ *
+ * `writeSidecar` (Phase D) is the thin I/O wrapper. It stays separate
+ * so the pure builder can be exercised independently with a temp dir.
+ */
+import type { Span, Attribution } from './types.js';
+import { type Sidecar, type RegistryEntry } from './sidecar.js';
+/**
+ * One (span, attribution, landmark) triple — the input unit for
+ * `buildSidecar`. `landmark` is the top-level export name the span
+ * lives under (empty string when the span sits outside any landmark,
+ * which the builder treats as a skip). `path` is the AST child-index
+ * trail inside the landmark; empty path means "the landmark itself".
+ */
+export type ResolvedAnchor = {
+    span: Span;
+    attribution: Attribution;
+    landmark: string;
+    path: number[];
+    /**
+     * Generator metadata for the producer that owns this span. The
+     * `attribute()` step gives us only the generator id; the version +
+     * registry come from the CLI's view of `deno.json`/lockfile (Phase
+     * D plumbs this). For now callers pass it in; the builder takes
+     * whatever they hand over and pools it.
+     */
+    generatorVersion: string;
+    registry: RegistryEntry;
+};
+export type BuildSidecarArgs = {
+    filePath: string;
+    schemaSrc: string;
+    parser: string;
+    anchors: ResolvedAnchor[];
+};
+/**
+ * Assemble a Sidecar v2 from resolved anchors. Anchors with an empty
+ * `landmark` string are skipped — they sit outside any top-level
+ * export and have no useful re-resolution path (plan #25).
+ */
+export declare const buildSidecar: ({ filePath, schemaSrc, parser, anchors }: BuildSidecarArgs) => Sidecar;
+//# sourceMappingURL=buildSidecar.d.ts.map

package/script/anchors/buildSidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSidecar.d.ts","sourceRoot":"","sources":["../../src/anchors/buildSidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAA;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,IAAI,CAAA;IACV,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,aAAa,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,cAAc,EAAE,CAAA;CAC1B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,0CAK1B,gBAAgB,KAAG,OAgFrB,CAAA"}

package/script/anchors/buildSidecar.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * @fileoverview Assemble a {@link Sidecar} from resolved spans +
+ * attributions + landmark/path pairs.
+ *
+ * Pure function: no I/O, no parser, no global state. The AST landmark
+ * resolution step (plan §4.2) is *not* done here — the caller passes
+ * pre-resolved `(landmark, path)` pairs alongside each span. This
+ * separation is deliberate:
+ *
+ * - The sidecar shape + interning logic can be tested without a
+ *   parser (`FakeParser` is enough).
+ * - When tsc / oxc adapters land (plan §8), they're swap-ins behind
+ *   the `ParserAdapter` interface — no churn here.
+ *
+ * `writeSidecar` (Phase D) is the thin I/O wrapper. It stays separate
+ * so the pure builder can be exercised independently with a temp dir.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSidecar = void 0;
+const sidecar_js_1 = require("./sidecar.js");
+/**
+ * Assemble a Sidecar v2 from resolved anchors. Anchors with an empty
+ * `landmark` string are skipped — they sit outside any top-level
+ * export and have no useful re-resolution path (plan #25).
+ */
+const buildSidecar = ({ filePath, schemaSrc, parser, anchors }) => {
+    const sidecar = (0, sidecar_js_1.emptySidecar)(filePath, schemaSrc, parser);
+    // String-pool interning. Repeated values get the same index.
+    const stringPool = (pool) => {
+        const cache = new Map();
+        return (value) => {
+            const hit = cache.get(value);
+            if (hit !== undefined)
+                return hit;
+            const idx = pool.length;
+            pool.push(value);
+            cache.set(value, idx);
+            return idx;
+        };
+    };
+    // Object pools key on a canonical string form so we don't double-
+    // intern entries that happen to be structurally equal but
+    // referentially distinct.
+    const internRegistry = (() => {
+        const cache = new Map();
+        return (entry) => {
+            const key = `${entry.kind}|${entry.host}`;
+            const hit = cache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const idx = sidecar.R.length;
+            sidecar.R.push(entry);
+            cache.set(key, idx);
+            return idx;
+        };
+    })();
+    const internGenerator = (() => {
+        const cache = new Map();
+        return (entry) => {
+            const key = `${entry.name}|${entry.version}|${entry.r}`;
+            const hit = cache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const idx = sidecar.G.length;
+            sidecar.G.push(entry);
+            cache.set(key, idx);
+            return idx;
+        };
+    })();
+    const internS = stringPool(sidecar.S);
+    const internV = stringPool(sidecar.V);
+    const internL = stringPool(sidecar.L);
+    const internP = stringPool(sidecar.P);
+    // Producer-name pool (`N`) + a parallel `An` array (one entry per
+    // emitted `A` row). Kept local then assigned, so the additive fields
+    // don't need non-null coercion on the optional sidecar shape.
+    const N = [];
+    const An = [];
+    const internN = stringPool(N);
+    for (const anchor of anchors) {
+        if (anchor.landmark === '') {
+            // Span outside any landmark. Skip — re-anchoring after
+            // reformatting wouldn't have anything stable to descend from.
+            continue;
+        }
+        const ri = internRegistry(anchor.registry);
+        const gi = internGenerator({
+            name: anchor.attribution.generatorId,
+            version: anchor.generatorVersion,
+            r: ri
+        });
+        // `schemaPointer` is `''` for spans with no schema location
+        // (generator-only producers); consumers treat the empty pool entry
+        // as "no schema pointer".
+        const si = internS(anchor.attribution.schemaPointer);
+        const vi = internV(anchor.attribution.variant);
+        const Li = internL(anchor.landmark);
+        const Pi = internP(anchor.path.join('.'));
+        sidecar.A.push([Li, Pi, gi, si, vi, anchor.span.from, anchor.span.to]);
+        // Parallel to the A row just pushed.
+        An.push(internN(anchor.attribution.producerName));
+    }
+    sidecar.N = N;
+    sidecar.An = An;
+    return sidecar;
+};
+exports.buildSidecar = buildSidecar;

package/script/anchors/generationMap.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Generation map — per-Definition summary used for
+ * reverse queries: "which files came from refName User?", "which
+ * files did gen-zod produce?". Per plan §4.3.
+ *
+ * Lives at `.skmtc/<project>/.maps/_map.ndjson`, **wholly rewritten**
+ * per generation (no accumulation across runs; stale entries would
+ * mislead the viewer). The CLI handles disk I/O — this module emits
+ * the entries + an NDJSON helper.
+ *
+ * One entry per Definition (landmark), not per anchor. The landmark
+ * appears in the generation map; the per-Snippet anchors stay inside
+ * the sidecar itself.
+ *
+ * "Generation map" by analogy with source maps: each row pairs a
+ * generated artifact with the schema location + generator + variant
+ * it came from. Same pattern as a sourcemap, at Definition rather
+ * than byte granularity.
+ */
+import * as v from 'valibot';
+import type { Sidecar } from './sidecar.js';
+/**
+ * Single row in the generation map. Mirrors the documented shape in
+ * `plan.md` §4.3:
+ *
+ *  - `f` — file path (relative to basePath)
+ *  - `name` — Definition / landmark name
+ *  - `g` — generator id (e.g. `@skmtc/gen-typescript`)
+ *  - `s` — schema pointer or empty string
+ *  - `v` — variant name (default `'main'`)
+ */
+export declare const generationMapEntry: v.ObjectSchema<{
+    readonly f: v.StringSchema<undefined>;
+    readonly name: v.StringSchema<undefined>;
+    readonly g: v.StringSchema<undefined>;
+    readonly s: v.StringSchema<undefined>;
+    readonly v: v.StringSchema<undefined>;
+}, undefined>;
+export type GenerationMapEntry = v.InferOutput<typeof generationMapEntry>;
+/**
+ * Extract one generation-map entry per unique landmark in `sidecar`.
+ *
+ * For each landmark, picks the **outermost** anchor — the one whose
+ * AST path is empty (meaning the span is the landmark node itself).
+ * If no path-empty anchor exists for a landmark (rare; happens when
+ * the Definition's full text was reshaped between render and
+ * post-pass), falls back to the first anchor for that landmark in
+ * document order. This keeps the map populated rather than silently
+ * dropping a Definition that the user can see in the file.
+ */
+export declare const entriesForSidecar: (sidecar: Sidecar) => GenerationMapEntry[];
+/**
+ * Convert generation-map entries to NDJSON (newline-delimited JSON).
+ * One row per line; trailing newline so concatenation between
+ * generations is boundary-safe.
+ *
+ * Pure: takes entries, returns a string. No I/O.
+ */
+export declare const toNdjson: (entries: readonly GenerationMapEntry[]) => string;
+/**
+ * Parse a generation-map NDJSON file (typically read off disk by the
+ * viewer or by a `doctor` check). Invalid rows fail the valibot parse
+ * — the map is wholly rewritten per generation so a row being
+ * unparseable means the file is corrupt, not just stale.
+ */
+export declare const parseNdjson: (text: string) => GenerationMapEntry[];
+//# sourceMappingURL=generationMap.d.ts.map

package/script/anchors/generationMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generationMap.d.ts","sourceRoot":"","sources":["../../src/anchors/generationMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;;;;aAM7B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,KAAG,kBAAkB,EAgCtE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,SAAS,kBAAkB,EAAE,KAAG,MACiB,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,kBAAkB,EAI5D,CAAA"}