@shrkcrft/boundaries 0.1.0-alpha.26 → 0.1.0-alpha.28

package/dist/baseline/canonicalize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonicalization for baseline comparison.
+ *
+ * The point is NOT prettiness — it is that a reordering, a re-indent, or a
+ * key shuffle must not read as drift. A noisy diff trains reviewers to bless
+ * without reading, which is how a real deletion ships inside a "formatting"
+ * update.
+ */
+/** The canonical forms a baseline rule may request. */
+export type CanonicalForm = 'auto' | 'json-sorted-keys' | 'lines-sorted' | 'lines' | 'raw';
+/** The form actually applied, plus the canonical text. */
+export interface ICanonicalResult {
+    readonly text: string;
+    /** The concrete form used (`auto` is resolved to one of the others). */
+    readonly form: Exclude<CanonicalForm, 'auto'>;
+}
+/** Parse `text` as JSON, or `undefined` when it is not JSON. */
+export declare function tryParseJson(text: string): unknown | undefined;
+/** Recursively sort object keys so key ORDER is never mistaken for a change. */
+export declare function sortJsonKeys(value: unknown): unknown;
+/**
+ * Bring both sides of a comparison into the same form.
+ *
+ * `auto` resolves to `json-sorted-keys` only when BOTH sides parse as JSON —
+ * a pure function of the two inputs, so the same pair always canonicalizes the
+ * same way (a per-side sniff would make the result depend on which file was
+ * malformed).
+ */
+export declare function canonicalizePair(expected: string, actual: string, form?: CanonicalForm): {
+    expected: ICanonicalResult;
+    actual: ICanonicalResult;
+};
+/** Apply one concrete canonical form. Falls back to `lines` when JSON won't parse. */
+export declare function canonicalizeOne(text: string, form: Exclude<CanonicalForm, 'auto'>): string;
+//# sourceMappingURL=canonicalize.d.ts.map

package/dist/baseline/canonicalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.d.ts","sourceRoot":"","sources":["../../src/baseline/canonicalize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,kBAAkB,GAAG,cAAc,GAAG,OAAO,GAAG,KAAK,CAAC;AAE3F,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;CAC/C;AAED,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAU9D;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUpD;AAWD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,aAAsB,GAC3B;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAa1D;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,MAAM,CAgB1F"}

package/dist/baseline/canonicalize.js

@@ -0,0 +1,87 @@
+/**
+ * Canonicalization for baseline comparison.
+ *
+ * The point is NOT prettiness — it is that a reordering, a re-indent, or a
+ * key shuffle must not read as drift. A noisy diff trains reviewers to bless
+ * without reading, which is how a real deletion ships inside a "formatting"
+ * update.
+ */
+/** Parse `text` as JSON, or `undefined` when it is not JSON. */
+export function tryParseJson(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return undefined;
+    const first = trimmed[0];
+    if (first !== '{' && first !== '[' && first !== '"')
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Recursively sort object keys so key ORDER is never mistaken for a change. */
+export function sortJsonKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortJsonKeys);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortJsonKeys(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+function normalizeLines(text, sorted) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((l) => l.replace(/[ \t]+$/, ''))
+        .filter((l) => l.trim() !== '');
+    if (sorted)
+        lines.sort();
+    return lines.join('\n');
+}
+/**
+ * Bring both sides of a comparison into the same form.
+ *
+ * `auto` resolves to `json-sorted-keys` only when BOTH sides parse as JSON —
+ * a pure function of the two inputs, so the same pair always canonicalizes the
+ * same way (a per-side sniff would make the result depend on which file was
+ * malformed).
+ */
+export function canonicalizePair(expected, actual, form = 'auto') {
+    let resolved;
+    if (form === 'auto') {
+        const bothJson = tryParseJson(expected) !== undefined && tryParseJson(actual) !== undefined;
+        resolved = bothJson ? 'json-sorted-keys' : 'lines';
+    }
+    else {
+        resolved = form;
+    }
+    const one = (text) => ({
+        text: canonicalizeOne(text, resolved),
+        form: resolved,
+    });
+    return { expected: one(expected), actual: one(actual) };
+}
+/** Apply one concrete canonical form. Falls back to `lines` when JSON won't parse. */
+export function canonicalizeOne(text, form) {
+    switch (form) {
+        case 'json-sorted-keys': {
+            const parsed = tryParseJson(text);
+            if (parsed === undefined)
+                return normalizeLines(text, false);
+            return JSON.stringify(sortJsonKeys(parsed), null, 2);
+        }
+        case 'lines-sorted':
+            return normalizeLines(text, true);
+        case 'lines':
+            return normalizeLines(text, false);
+        case 'raw':
+            return text.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+        default:
+            return text;
+    }
+}

package/dist/baseline/compute-baseline.d.ts

@@ -0,0 +1,23 @@
+import type { IWiringSource } from '@shrkcrft/core';
+/** The value an extractor-backed baseline computes, ready to diff or commit. */
+export interface IExtractorCompute {
+    /** Canonical serialization: a pretty-printed JSON array of sorted, unique ids. */
+    readonly text: string;
+    readonly ids: readonly string[];
+    readonly filesScanned: number;
+    /** Set when the source is misconfigured (never throws). */
+    readonly error?: string;
+}
+/**
+ * Compute a baseline from the extraction DSL — the pure alternative to shelling
+ * out.
+ *
+ * Emitted as a pretty-printed JSON array so the committed artifact is valid
+ * JSON *and* diffs one id per line: a review can see exactly which entry was
+ * gained or lost without a tool.
+ *
+ * No spawn, no network, no model — so an extractor baseline is safe to ship
+ * from a pack, unlike a `command` one.
+ */
+export declare function computeBaselineFromExtractor(projectRoot: string, source: IWiringSource, excludeDirs?: readonly string[]): IExtractorCompute;
+//# sourceMappingURL=compute-baseline.d.ts.map

package/dist/baseline/compute-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/compute-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKpD,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAenB"}

package/dist/baseline/compute-baseline.js

@@ -0,0 +1,30 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { extractTokens } from "../extract/extract-tokens.js";
+/**
+ * Compute a baseline from the extraction DSL — the pure alternative to shelling
+ * out.
+ *
+ * Emitted as a pretty-printed JSON array so the committed artifact is valid
+ * JSON *and* diffs one id per line: a review can see exactly which entry was
+ * gained or lost without a tool.
+ *
+ * No spawn, no network, no model — so an extractor baseline is safe to ship
+ * from a pack, unlike a `command` one.
+ */
+export function computeBaselineFromExtractor(projectRoot, source, excludeDirs = []) {
+    const cache = readMatchingFiles(projectRoot, source.files ?? [], new Set(excludeDirs));
+    const files = [...cache.entries()]
+        .filter(([path]) => matchesAny(path, source.files ?? []))
+        .map(([path, content]) => ({ path, content }));
+    const res = extractTokens(source, files);
+    if (res.error) {
+        return { text: '[]', ids: [], filesScanned: files.length, error: res.error };
+    }
+    const ids = [...new Set(res.sites.map((s) => s.token))].sort();
+    return {
+        text: JSON.stringify(ids, null, 2) + '\n',
+        ids,
+        filesScanned: files.length,
+    };
+}

package/dist/baseline/diff-baseline.d.ts

@@ -0,0 +1,68 @@
+import type { IBaselineRule } from '@shrkcrft/core';
+export declare const BASELINE_SCHEMA: "sharkcraft.baseline/v1";
+/** How the two sides were compared. */
+export type BaselineCompareMode = 'keyed-set' | 'element-set' | 'canonical-text';
+/**
+ * Per-rule outcome. `skipped` is DISTINCT from `passed`: a recompute that
+ * produced nothing compared nothing, and a silently-empty compute would
+ * "match" an empty baseline forever.
+ */
+export type BaselineStatus = 'passed' | 'failed' | 'skipped' | 'error';
+export interface IBaselineDiff {
+    /** Entries present now but not in the committed baseline. */
+    readonly added: readonly string[];
+    /** Entries in the committed baseline but gone now. */
+    readonly removed: readonly string[];
+    /** How the comparison was performed. */
+    readonly mode: BaselineCompareMode;
+    /** The canonical form applied to both sides. */
+    readonly canonical: string;
+    /** True when the canonical texts are byte-identical. */
+    readonly identical: boolean;
+}
+export interface IBaselineResult {
+    readonly ruleId: string;
+    readonly description?: string;
+    readonly baselinePath: string;
+    readonly severity: 'error' | 'warning';
+    readonly status: BaselineStatus;
+    readonly direction: 'two-way' | 'additions-only' | 'no-shrink';
+    readonly diff?: IBaselineDiff;
+    /** Entry count on each side (keyed mode) or line count (text mode). */
+    readonly baselineCount: number;
+    readonly currentCount: number;
+    /** Set when the rule could not run (missing baseline file, failed compute, bad config). */
+    readonly error?: string;
+    /** Why the rule compared nothing. */
+    readonly skipReason?: string;
+    /** The remediation line for this rule. */
+    readonly hint: string;
+}
+export interface IBaselineReport {
+    readonly schema: typeof BASELINE_SCHEMA;
+    readonly results: readonly IBaselineResult[];
+    readonly evaluated: number;
+    readonly verdict: 'pass' | 'errors' | 'warnings';
+}
+/**
+ * Compare a committed baseline against a freshly computed value.
+ *
+ * With `keyBy` the two sides are compared as KEYED SETS (per-key added/removed);
+ * otherwise both are canonicalized and compared as text, with the line-level set
+ * difference reported so the human diff names what actually moved.
+ *
+ * Pure: the caller supplies both strings, so the same engine serves a
+ * shell-computed ledger, an extractor-computed inventory, and a unit test.
+ */
+export declare function diffBaseline(rule: IBaselineRule, committed: string, current: string): IBaselineDiff;
+/**
+ * Does this diff fail under the rule's direction?
+ *
+ * `two-way` (the default) is deliberate: the historical failure of hand-rolled
+ * ledgers is being one-directional, so a silent DELETION passes. Narrowing to
+ * one direction must be an explicit, visible choice.
+ */
+export declare function baselineFails(rule: IBaselineRule, diff: IBaselineDiff): boolean;
+/** Entry count for a side, matching the comparison mode. */
+export declare function baselineCount(rule: IBaselineRule, text: string): number;
+//# sourceMappingURL=diff-baseline.d.ts.map

package/dist/baseline/diff-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/diff-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,eAAO,MAAM,eAAe,EAAG,wBAAiC,CAAC;AAEjE,uCAAuC;AACvC,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEjF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GAAG,WAAW,CAAC;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,eAAe,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAwCD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,aAAa,CA4Bf;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAU/E;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvE"}

package/dist/baseline/diff-baseline.js

@@ -0,0 +1,110 @@
+import { extractJsonPath } from "./json-path-keys.js";
+import { canonicalizePair, tryParseJson } from "./canonicalize.js";
+export const BASELINE_SCHEMA = 'sharkcraft.baseline/v1';
+/** Split canonical text into comparable entries (a set of non-empty lines). */
+function textEntries(text) {
+    return text.split('\n').filter((l) => l.trim() !== '');
+}
+/**
+ * The scalar elements of a top-level JSON array, or `undefined` for any other
+ * shape.
+ *
+ * A committed inventory is most often exactly this — a JSON list of ids — and
+ * diffing it by LINE reports `  "beta"` with its quote and comma, plus the
+ * bracket lines, as changes. Naming the entry is the whole point of a ledger
+ * diff, so the array case is compared element-wise.
+ */
+function jsonArrayEntries(text) {
+    const parsed = tryParseJson(text);
+    if (!Array.isArray(parsed))
+        return undefined;
+    const out = [];
+    for (const el of parsed) {
+        if (el === null || typeof el === 'object')
+            return undefined;
+        out.push(String(el));
+    }
+    return out;
+}
+/** Set difference preserving the left side's order, de-duplicated. */
+function minus(left, right) {
+    const rightSet = new Set(right);
+    const seen = new Set();
+    const out = [];
+    for (const v of left) {
+        if (rightSet.has(v) || seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
+/**
+ * Compare a committed baseline against a freshly computed value.
+ *
+ * With `keyBy` the two sides are compared as KEYED SETS (per-key added/removed);
+ * otherwise both are canonicalized and compared as text, with the line-level set
+ * difference reported so the human diff names what actually moved.
+ *
+ * Pure: the caller supplies both strings, so the same engine serves a
+ * shell-computed ledger, an extractor-computed inventory, and a unit test.
+ */
+export function diffBaseline(rule, committed, current) {
+    const form = (rule.compute.canonical ?? 'auto');
+    const pair = canonicalizePair(committed, current, form);
+    if (rule.keyBy) {
+        const before = extractJsonPath(committed, rule.keyBy);
+        const after = extractJsonPath(current, rule.keyBy);
+        return {
+            added: minus(after, before),
+            removed: minus(before, after),
+            mode: 'keyed-set',
+            canonical: pair.expected.form,
+            identical: pair.expected.text === pair.actual.text,
+        };
+    }
+    const beforeArray = jsonArrayEntries(committed);
+    const afterArray = jsonArrayEntries(current);
+    const elementSet = beforeArray !== undefined && afterArray !== undefined;
+    const before = elementSet ? beforeArray : textEntries(pair.expected.text);
+    const after = elementSet ? afterArray : textEntries(pair.actual.text);
+    return {
+        added: minus(after, before),
+        removed: minus(before, after),
+        mode: elementSet ? 'element-set' : 'canonical-text',
+        canonical: pair.expected.form,
+        identical: pair.expected.text === pair.actual.text,
+    };
+}
+/**
+ * Does this diff fail under the rule's direction?
+ *
+ * `two-way` (the default) is deliberate: the historical failure of hand-rolled
+ * ledgers is being one-directional, so a silent DELETION passes. Narrowing to
+ * one direction must be an explicit, visible choice.
+ */
+export function baselineFails(rule, diff) {
+    const direction = rule.direction ?? 'two-way';
+    const gained = diff.added.length > 0;
+    const lost = diff.removed.length > 0;
+    // A pure-reordering change is not drift under keyed-set semantics, but under
+    // canonical-text semantics an identical canonical form means no change at all.
+    if (!gained && !lost && diff.identical)
+        return false;
+    if (direction === 'additions-only')
+        return gained;
+    if (direction === 'no-shrink')
+        return lost;
+    return gained || lost || !diff.identical;
+}
+/** Entry count for a side, matching the comparison mode. */
+export function baselineCount(rule, text) {
+    if (rule.keyBy)
+        return extractJsonPath(text, rule.keyBy).length;
+    const asArray = jsonArrayEntries(text);
+    if (asArray !== undefined)
+        return asArray.length;
+    const form = (rule.compute.canonical ?? 'auto');
+    const pair = canonicalizePair(text, text, form);
+    return textEntries(pair.expected.text).length;
+}

package/dist/baseline/json-path-keys.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract every id `jsonPath` selects from `text` (JSON only — a hand-rolled
+ * YAML reader would be a silent-wrong-answer risk). Non-JSON text yields no
+ * keys, which the caller reports as an empty side rather than a false match.
+ *
+ * Delegates to the shared extraction DSL so `keyBy` and a wiring rule's
+ * `json-path` source resolve paths identically.
+ */
+export declare function extractJsonPath(text: string, jsonPath: string): string[];
+//# sourceMappingURL=json-path-keys.d.ts.map

package/dist/baseline/json-path-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-path-keys.d.ts","sourceRoot":"","sources":["../../src/baseline/json-path-keys.ts"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAGxE"}

package/dist/baseline/json-path-keys.js

@@ -0,0 +1,13 @@
+import { extractTokens } from "../extract/extract-tokens.js";
+/**
+ * Extract every id `jsonPath` selects from `text` (JSON only — a hand-rolled
+ * YAML reader would be a silent-wrong-answer risk). Non-JSON text yields no
+ * keys, which the caller reports as an empty side rather than a false match.
+ *
+ * Delegates to the shared extraction DSL so `keyBy` and a wiring rule's
+ * `json-path` source resolve paths identically.
+ */
+export function extractJsonPath(text, jsonPath) {
+    const source = { files: ['<inline>'], extract: 'json-path', jsonPath };
+    return extractTokens(source, [{ path: '<inline>', content: text }]).sites.map((s) => s.token);
+}

package/dist/extract/code-zones.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which lexical zone of a file a character belongs to.
+ *
+ * The dominant false positive of a text-based policy rule is a hit inside a
+ * comment ("we used to call Date.now() here") or inside an unrelated string.
+ * The dominant false NEGATIVE of a language-scoped linter is the opposite: it
+ * cannot see inside an inline `template:` string at all. Classifying zones
+ * lexically lets one rule say which of the three it means — without a parser,
+ * and identically across `.ts`, `.kt`, `.scss` and friends.
+ */
+export type CodeZoneKind = 'code' | 'string' | 'comment';
+/** A half-open `[start, end)` span of one zone kind. */
+export interface ICodeZone {
+    readonly kind: CodeZoneKind;
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Split `content` into contiguous code / string / comment zones.
+ *
+ * A lexer, not a parser: it recognises the C/JS-family string quotes
+ * (`'`, `"`, `` ` ``) and comment forms (`//`, `/* … *\/`). Documented limits —
+ * a regex literal containing `//` reads as a comment, and `#`-comment languages
+ * are reported as code.
+ */
+export declare function lexCodeZones(content: string): readonly ICodeZone[];
+/**
+ * Zone kind at a character offset. `code` when the offset falls outside every
+ * recorded zone (e.g. past end-of-content).
+ */
+export declare function zoneAt(zones: readonly ICodeZone[], index: number): CodeZoneKind;
+//# sourceMappingURL=code-zones.d.ts.map

package/dist/extract/code-zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-zones.d.ts","sourceRoot":"","sources":["../../src/extract/code-zones.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CA4BlE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAY/E"}

package/dist/extract/code-zones.js

@@ -0,0 +1,59 @@
+import { skipComment, skipString } from "./scan-literals.js";
+/**
+ * Split `content` into contiguous code / string / comment zones.
+ *
+ * A lexer, not a parser: it recognises the C/JS-family string quotes
+ * (`'`, `"`, `` ` ``) and comment forms (`//`, `/* … *\/`). Documented limits —
+ * a regex literal containing `//` reads as a comment, and `#`-comment languages
+ * are reported as code.
+ */
+export function lexCodeZones(content) {
+    const zones = [];
+    let codeStart = 0;
+    const flushCode = (upTo) => {
+        if (upTo > codeStart)
+            zones.push({ kind: 'code', start: codeStart, end: upTo });
+    };
+    for (let i = 0; i < content.length; i += 1) {
+        const c = content[i];
+        if (c === '"' || c === "'" || c === '`') {
+            flushCode(i);
+            const end = skipString(content, i);
+            zones.push({ kind: 'string', start: i, end: end + 1 });
+            i = end;
+            codeStart = i + 1;
+            continue;
+        }
+        if (c === '/') {
+            const end = skipComment(content, i);
+            if (end >= 0) {
+                flushCode(i);
+                zones.push({ kind: 'comment', start: i, end: end + 1 });
+                i = end;
+                codeStart = i + 1;
+            }
+        }
+    }
+    flushCode(content.length);
+    return zones;
+}
+/**
+ * Zone kind at a character offset. `code` when the offset falls outside every
+ * recorded zone (e.g. past end-of-content).
+ */
+export function zoneAt(zones, index) {
+    // Zones are contiguous and ascending — binary search.
+    let lo = 0;
+    let hi = zones.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const z = zones[mid];
+        if (index < z.start)
+            hi = mid - 1;
+        else if (index >= z.end)
+            lo = mid + 1;
+        else
+            return z.kind;
+    }
+    return 'code';
+}

package/dist/extract/extract-tokens.d.ts

@@ -0,0 +1,30 @@
+import { type IWiringSource } from '@shrkcrft/core';
+/** A file made available to an extractor. */
+export interface IExtractFileEntry {
+    /** Project-relative POSIX path. */
+    readonly path: string;
+    readonly content: string;
+}
+/** A captured id + where it was captured. */
+export interface IExtractedSite {
+    readonly token: string;
+    readonly file: string;
+    readonly line: number;
+}
+/** Outcome of running one source: the sites, or a configuration error. */
+export interface IExtractResult {
+    readonly sites: readonly IExtractedSite[];
+    /** Set when the SOURCE is misconfigured (never thrown — rules degrade). */
+    readonly error?: string;
+}
+/**
+ * Run one source's extractor over the given files.
+ *
+ * This is the reusable core of the completeness plane: wiring rules, registry
+ * inventories, and extractor-backed baselines all harvest their ids through
+ * here, so every one of them honours the exact same semantics (and gains every
+ * new extractor kind for free). Never throws — a misconfigured source returns
+ * an `error` and no sites.
+ */
+export declare function extractTokens(source: IWiringSource, files: readonly IExtractFileEntry[]): IExtractResult;
+//# sourceMappingURL=extract-tokens.d.ts.map

package/dist/extract/extract-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-tokens.d.ts","sourceRoot":"","sources":["../../src/extract/extract-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAUxB,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAClC,cAAc,CA4DhB"}