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

package/dist/extract/extract-tokens.js

@@ -0,0 +1,328 @@
+import { resolveExtractorAnchor, resolveExtractorKind, validateWiringSource, } from '@shrkcrft/core';
+import { safeCompile } from "../util/safe-regex.js";
+import { elementToken, elementValue, escapeRegex, lineOf, scanBalanced, } from "./scan-literals.js";
+/**
+ * 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 function extractTokens(source, files) {
+    const error = validateWiringSource(source);
+    if (error)
+        return { sites: [], error };
+    const kind = resolveExtractorKind(source);
+    const anchor = resolveExtractorAnchor(source);
+    let sites;
+    switch (kind) {
+        case 'regex-capture':
+            sites = byRegex(source, files);
+            break;
+        case 'array-members':
+            sites = byBracketLiteral(anchor, '[', files, (el) => elementToken(el));
+            break;
+        case 'object-keys':
+            sites = byBracketLiteral(anchor, '{', files, (el) => source.capture === 'value' ? elementValue(el) : elementToken(el));
+            break;
+        case 'enum-members':
+            sites = byEnumMembers(anchor, source.capture === 'value', files);
+            break;
+        case 'export-names':
+            sites = byExportNames(files);
+            break;
+        case 'call-args':
+            sites = byCallArgs(anchor, source.argIndex ?? 0, false, files);
+            break;
+        case 'decorator-args':
+            sites = byCallArgs(anchor, source.argIndex ?? 0, true, files);
+            break;
+        case 'string-union-members':
+            sites = byStringUnion(anchor, files);
+            break;
+        case 'json-path':
+            sites = byJsonPath(source.jsonPath, files);
+            break;
+        default:
+            return { sites: [], error: `unknown extract kind "${String(kind)}"` };
+    }
+    if (source.match !== undefined) {
+        const { re } = safeCompile(source.match, source.matchFlags);
+        if (re) {
+            sites = sites.filter((s) => {
+                re.lastIndex = 0;
+                return re.test(s.token);
+            });
+        }
+    }
+    if (source.exclude !== undefined) {
+        const { re } = safeCompile(source.exclude, source.excludeFlags);
+        if (re) {
+            sites = sites.filter((s) => {
+                re.lastIndex = 0;
+                return !re.test(s.token);
+            });
+        }
+    }
+    return { sites };
+}
+/** Capture-group-1 of a pattern, per file. */
+function byRegex(source, files) {
+    const { re } = safeCompile(source.pattern, source.flags);
+    if (!re)
+        return [];
+    const sites = [];
+    for (const f of files) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(f.content)) !== null) {
+            // Guard against a zero-width match looping forever.
+            if (m.index === re.lastIndex)
+                re.lastIndex += 1;
+            const token = m[1];
+            if (token === undefined || token === '')
+                continue;
+            sites.push({ token, file: f.path, line: lineOf(f.content, m.index) });
+        }
+    }
+    return sites;
+}
+/**
+ * Elements of every `<anchor> = <open> … ` / `<anchor>: <open> … ` literal.
+ *
+ * Covers `export const ARR = [ … ]`, an inline `arrayProperty: [ … ]`, a typed
+ * `const ARR: readonly T[] = [ … ]`, and the very common freeze/wrapper form
+ * `export const ARR = Object.freeze([ … ])` — a registry array is nearly always
+ * wrapped, and missing that would silently extract nothing.
+ */
+function byBracketLiteral(anchor, open, files, tokenOf) {
+    const sites = [];
+    const head = new RegExp(`(?<![\\w$])${escapeRegex(anchor)}\\s*(?::[^=\\n]*)?[:=]\\s*(?:[A-Za-z_$][\\w$.]*\\s*\\(\\s*)?\\${open}`, 'g');
+    for (const f of files) {
+        head.lastIndex = 0;
+        let m;
+        while ((m = head.exec(f.content)) !== null) {
+            if (m.index === head.lastIndex)
+                head.lastIndex += 1;
+            const openIndex = m.index + m[0].length - 1;
+            const { elements, end } = scanBalanced(f.content, openIndex);
+            for (const el of elements) {
+                const token = tokenOf(el.text);
+                if (token === undefined || token === '')
+                    continue;
+                sites.push({ token, file: f.path, line: lineOf(f.content, el.index) });
+            }
+            head.lastIndex = Math.max(end + 1, head.lastIndex);
+        }
+    }
+    return sites;
+}
+/** Members of `enum <anchor> { … }` — the member name, or its assigned value. */
+function byEnumMembers(anchor, wantValue, files) {
+    const sites = [];
+    const head = new RegExp(`\\benum\\s+${escapeRegex(anchor)}\\s*\\{`, 'g');
+    for (const f of files) {
+        head.lastIndex = 0;
+        let m;
+        while ((m = head.exec(f.content)) !== null) {
+            if (m.index === head.lastIndex)
+                head.lastIndex += 1;
+            const openIndex = m.index + m[0].length - 1;
+            const { elements, end } = scanBalanced(f.content, openIndex);
+            for (const el of elements) {
+                const token = wantValue ? elementValue(el.text) : elementToken(el.text);
+                if (token === undefined || token === '')
+                    continue;
+                sites.push({ token, file: f.path, line: lineOf(f.content, el.index) });
+            }
+            head.lastIndex = Math.max(end + 1, head.lastIndex);
+        }
+    }
+    return sites;
+}
+/** Every exported binding name, including re-export aliases (`export { A as B }` → `B`). */
+const EXPORT_DECL = /\bexport\s+(?:declare\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:const|let|var|function\*?|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/g;
+const EXPORT_CLAUSE = /\bexport\s*(?:type\s+)?\{([^}]*)\}/g;
+function byExportNames(files) {
+    const sites = [];
+    for (const f of files) {
+        EXPORT_DECL.lastIndex = 0;
+        let m;
+        while ((m = EXPORT_DECL.exec(f.content)) !== null) {
+            sites.push({ token: m[1], file: f.path, line: lineOf(f.content, m.index) });
+        }
+        EXPORT_CLAUSE.lastIndex = 0;
+        while ((m = EXPORT_CLAUSE.exec(f.content)) !== null) {
+            const line = lineOf(f.content, m.index);
+            for (const raw of m[1].split(',')) {
+                const spec = raw.trim().replace(/^type\s+/, '');
+                if (spec === '' || spec === 'default')
+                    continue;
+                // `A as B` exports B; a bare `A` exports A.
+                const parts = spec.split(/\s+as\s+/);
+                const name = (parts[parts.length - 1] ?? '').trim();
+                if (/^[A-Za-z_$][\w$]*$/.test(name))
+                    sites.push({ token: name, file: f.path, line });
+            }
+        }
+    }
+    return sites;
+}
+/** Argument `argIndex` of every `anchor(…)` call — or `@anchor(…)` decorator. */
+function byCallArgs(anchor, argIndex, decorator, files) {
+    const sites = [];
+    const head = decorator
+        ? new RegExp(`@${escapeRegex(anchor)}\\s*\\(`, 'g')
+        : new RegExp(`(?<![\\w$.@])${escapeRegex(anchor)}\\s*\\(`, 'g');
+    for (const f of files) {
+        head.lastIndex = 0;
+        let m;
+        while ((m = head.exec(f.content)) !== null) {
+            if (m.index === head.lastIndex)
+                head.lastIndex += 1;
+            const openIndex = m.index + m[0].length - 1;
+            const { elements, end } = scanBalanced(f.content, openIndex);
+            const el = elements[argIndex];
+            if (el) {
+                const token = elementToken(el.text);
+                if (token !== undefined && token !== '') {
+                    sites.push({ token, file: f.path, line: lineOf(f.content, el.index) });
+                }
+            }
+            head.lastIndex = Math.max(end + 1, head.lastIndex);
+        }
+    }
+    return sites;
+}
+/** The string literals of `type <anchor> = 'a' | 'b' | 'c'`. */
+function byStringUnion(anchor, files) {
+    const sites = [];
+    const head = new RegExp(`\\btype\\s+${escapeRegex(anchor)}\\s*(?:<[^>]*>)?\\s*=`, 'g');
+    const member = /['"`]([^'"`]+)['"`]/g;
+    for (const f of files) {
+        head.lastIndex = 0;
+        let m;
+        while ((m = head.exec(f.content)) !== null) {
+            if (m.index === head.lastIndex)
+                head.lastIndex += 1;
+            const start = m.index + m[0].length;
+            // The alias body runs to the first `;` or blank line at depth 0.
+            const semi = f.content.indexOf(';', start);
+            const blank = f.content.indexOf('\n\n', start);
+            const ends = [semi, blank].filter((i) => i >= 0);
+            const end = ends.length > 0 ? Math.min(...ends) : f.content.length;
+            const body = f.content.slice(start, end);
+            member.lastIndex = 0;
+            let mm;
+            while ((mm = member.exec(body)) !== null) {
+                sites.push({
+                    token: mm[1],
+                    file: f.path,
+                    line: lineOf(f.content, start + mm.index),
+                });
+            }
+            head.lastIndex = Math.max(end, head.lastIndex);
+        }
+    }
+    return sites;
+}
+/**
+ * Leaves selected by a JSON path. Supports `.key`, `[n]`, `[*]`; a leading `$.`
+ * is accepted and ignored. Scalars become ids; a selected object contributes
+ * its KEYS (so `compilerOptions.paths` yields the alias names). Line numbers are
+ * resolved by locating the token's first quoted occurrence in the raw text —
+ * exact when the id is unique, and honestly approximate when it is not.
+ */
+function byJsonPath(jsonPath, files) {
+    const segments = parseJsonPath(jsonPath);
+    const sites = [];
+    for (const f of files) {
+        let doc;
+        try {
+            doc = JSON.parse(f.content);
+        }
+        catch {
+            continue; // not JSON — a `json-path` source over mixed globs skips it
+        }
+        for (const leaf of selectJsonPath(doc, segments)) {
+            const token = String(leaf);
+            if (token === '')
+                continue;
+            const at = f.content.indexOf(`"${token}"`);
+            sites.push({
+                token,
+                file: f.path,
+                line: at >= 0 ? lineOf(f.content, at) : 1,
+            });
+        }
+    }
+    return sites;
+}
+function parseJsonPath(path) {
+    const out = [];
+    const cleaned = path.replace(/^\$\.?/, '');
+    for (const part of cleaned.split('.')) {
+        if (part === '')
+            continue;
+        const head = part.replace(/\[.*$/, '');
+        if (head !== '')
+            out.push({ key: head });
+        for (const b of part.matchAll(/\[([^\]]*)\]/g)) {
+            const inner = (b[1] ?? '').trim();
+            if (inner === '*')
+                out.push({ all: true });
+            else if (/^\d+$/.test(inner))
+                out.push({ index: Number(inner) });
+            else
+                out.push({ key: inner.replace(/^['"]|['"]$/g, '') });
+        }
+    }
+    return out;
+}
+function selectJsonPath(doc, segments) {
+    let current = [doc];
+    for (const seg of segments) {
+        const next = [];
+        for (const node of current) {
+            if (node === null || node === undefined)
+                continue;
+            if ('all' in seg) {
+                if (Array.isArray(node))
+                    next.push(...node);
+                else if (typeof node === 'object')
+                    next.push(...Object.values(node));
+            }
+            else if ('index' in seg) {
+                if (Array.isArray(node))
+                    next.push(node[seg.index]);
+            }
+            else if (typeof node === 'object' && !Array.isArray(node)) {
+                next.push(node[seg.key]);
+            }
+        }
+        current = next;
+    }
+    const out = [];
+    for (const leaf of current) {
+        if (leaf === null || leaf === undefined)
+            continue;
+        if (typeof leaf === 'object') {
+            // A selected object contributes its keys; an array, its scalar elements.
+            if (Array.isArray(leaf)) {
+                for (const el of leaf)
+                    if (typeof el === 'string' || typeof el === 'number')
+                        out.push(String(el));
+            }
+            else {
+                out.push(...Object.keys(leaf));
+            }
+            continue;
+        }
+        if (typeof leaf === 'boolean')
+            continue;
+        out.push(String(leaf));
+    }
+    return out;
+}

package/dist/extract/inspect-source.d.ts

@@ -0,0 +1,24 @@
+import type { IWiringSource } from '@shrkcrft/core';
+import { type IExtractedSite } from './extract-tokens.js';
+/** What one source actually resolved to against the live tree. */
+export interface ISourceInspection {
+    /** Files the globs matched (after the shared walk's skip rules). */
+    readonly filesScanned: number;
+    /** Distinct ids extracted, sorted. */
+    readonly ids: readonly string[];
+    /** Every capture site, in stable (file, line) order. */
+    readonly sites: readonly IExtractedSite[];
+    /** Set when the source is misconfigured. */
+    readonly error?: string;
+}
+/**
+ * Resolve ONE source against the tree and report what it matched.
+ *
+ * This is the primitive behind the rule-authoring trust layer: every plane
+ * (wiring, registry, registration idioms, extractor baselines) is ultimately a
+ * set of these, so "how many files did this rule see, and which ids did it
+ * extract?" has one answer computed one way. A rule that matched 0 is then a
+ * fact the tooling can report, not something an author has to notice.
+ */
+export declare function inspectSource(projectRoot: string, source: IWiringSource, excludeDirs?: readonly string[]): ISourceInspection;
+//# sourceMappingURL=inspect-source.d.ts.map

package/dist/extract/inspect-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-source.d.ts","sourceRoot":"","sources":["../../src/extract/inspect-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEzE,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAgBnB"}

package/dist/extract/inspect-source.js

@@ -0,0 +1,27 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { extractTokens } from "./extract-tokens.js";
+/**
+ * Resolve ONE source against the tree and report what it matched.
+ *
+ * This is the primitive behind the rule-authoring trust layer: every plane
+ * (wiring, registry, registration idioms, extractor baselines) is ultimately a
+ * set of these, so "how many files did this rule see, and which ids did it
+ * extract?" has one answer computed one way. A rule that matched 0 is then a
+ * fact the tooling can report, not something an author has to notice.
+ */
+export function inspectSource(projectRoot, source, excludeDirs = []) {
+    const globs = source.files ?? [];
+    const cache = readMatchingFiles(projectRoot, globs, new Set(excludeDirs));
+    const files = [...cache.entries()]
+        .filter(([path]) => matchesAny(path, globs))
+        .map(([path, content]) => ({ path, content }));
+    const res = extractTokens(source, files);
+    const sites = [...res.sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.token.localeCompare(b.token));
+    return {
+        filesScanned: files.length,
+        ids: [...new Set(sites.map((s) => s.token))].sort(),
+        sites,
+        ...(res.error ? { error: res.error } : {}),
+    };
+}

package/dist/extract/scan-literals.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lexical primitives shared by every extractor and by the policy zone
+ * classifier: skip a string literal, skip a comment, find the line of an
+ * offset, split a balanced bracket block into its top-level elements.
+ *
+ * These are deliberately a LEXER, not a parser. The engine must read `.ts`,
+ * `.kt`, `.swift`, `.scss`, `.json` and inline template strings with one code
+ * path and no per-language toolchain; a lexer is the largest thing that stays
+ * honest across all of them. The documented limits: a regex literal whose body
+ * contains `//` or `/*` is read as a comment, and a language whose string or
+ * comment syntax differs from the C/JS family (e.g. `#` comments) is scanned as
+ * plain code.
+ */
+/** Index of the closing quote of the string starting at `start` (handles escapes). */
+export declare function skipString(content: string, start: number): number;
+/**
+ * If a comment starts at `start`, the index of its LAST character; otherwise
+ * `-1`. Handles `// … \n` and `/* … *\/`.
+ */
+export declare function skipComment(content: string, start: number): number;
+/** 1-based line number of a character offset. */
+export declare function lineOf(content: string, index: number): number;
+/** Escape a literal string for embedding in a RegExp source. */
+export declare function escapeRegex(s: string): string;
+/** One top-level element of a balanced bracket block, with its source offset. */
+export interface IBracketElement {
+    readonly text: string;
+    readonly index: number;
+}
+/** Result of {@link scanBalanced}: the elements and the closing bracket's offset. */
+export interface IBracketScan {
+    readonly elements: readonly IBracketElement[];
+    readonly end: number;
+}
+/**
+ * Scan a `[ … ]` / `( … )` / `{ … }` block from its OPENING bracket, splitting
+ * the top-level (depth-1) comma-separated elements. String- and comment-aware,
+ * so commas and brackets inside nested literals, strings, or comments never
+ * mis-split. An unterminated block yields everything to end-of-content.
+ */
+export declare function scanBalanced(content: string, openIndex: number): IBracketScan;
+/**
+ * The id carried by one element: the contents of a leading quoted string, or
+ * the leading identifier. `undefined` when the element starts with neither
+ * (a spread, a number, a nested literal).
+ */
+export declare function elementToken(text: string): string | undefined;
+/**
+ * The VALUE side of a `key: value` / `member = value` element: the contents of
+ * a quoted string, or a bare numeric/identifier token. `undefined` when the
+ * element carries no assignment or the value is a nested construct.
+ */
+export declare function elementValue(text: string): string | undefined;
+//# sourceMappingURL=scan-literals.d.ts.map

package/dist/extract/scan-literals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-literals.d.ts","sourceRoot":"","sources":["../../src/extract/scan-literals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYlE;AAED,iDAAiD;AACjD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AA0CD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAgC7E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsB7D"}

package/dist/extract/scan-literals.js

@@ -0,0 +1,177 @@
+/**
+ * Lexical primitives shared by every extractor and by the policy zone
+ * classifier: skip a string literal, skip a comment, find the line of an
+ * offset, split a balanced bracket block into its top-level elements.
+ *
+ * These are deliberately a LEXER, not a parser. The engine must read `.ts`,
+ * `.kt`, `.swift`, `.scss`, `.json` and inline template strings with one code
+ * path and no per-language toolchain; a lexer is the largest thing that stays
+ * honest across all of them. The documented limits: a regex literal whose body
+ * contains `//` or `/*` is read as a comment, and a language whose string or
+ * comment syntax differs from the C/JS family (e.g. `#` comments) is scanned as
+ * plain code.
+ */
+/** Index of the closing quote of the string starting at `start` (handles escapes). */
+export function skipString(content, start) {
+    const quote = content[start];
+    for (let i = start + 1; i < content.length; i += 1) {
+        if (content[i] === '\\') {
+            i += 1;
+            continue;
+        }
+        if (content[i] === quote)
+            return i;
+    }
+    return content.length - 1;
+}
+/**
+ * If a comment starts at `start`, the index of its LAST character; otherwise
+ * `-1`. Handles `// … \n` and `/* … *\/`.
+ */
+export function skipComment(content, start) {
+    if (content[start] !== '/')
+        return -1;
+    const next = content[start + 1];
+    if (next === '/') {
+        const nl = content.indexOf('\n', start + 2);
+        return nl === -1 ? content.length - 1 : nl - 1;
+    }
+    if (next === '*') {
+        const end = content.indexOf('*/', start + 2);
+        return end === -1 ? content.length - 1 : end + 1;
+    }
+    return -1;
+}
+/** 1-based line number of a character offset. */
+export function lineOf(content, index) {
+    let line = 1;
+    const end = Math.min(index, content.length);
+    for (let i = 0; i < end; i += 1) {
+        if (content[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+/** Escape a literal string for embedding in a RegExp source. */
+export function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Advance past whitespace AND leading comments, returning the offset of the
+ * element's first real character.
+ *
+ * A registry array is exactly where authors leave section comments
+ * (`// spec read-only tools.`), and treating one as the element's text drops
+ * the entry that follows it — a false "not registered" that is worse than no
+ * rule at all. Skipping the trivia also puts the reported line on the token
+ * rather than on its comment.
+ */
+function skipLeadingTrivia(content, start, end) {
+    let i = start;
+    while (i < end) {
+        const c = content[i];
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+            i += 1;
+            continue;
+        }
+        const commentEnd = skipComment(content, i);
+        if (commentEnd >= 0) {
+            i = commentEnd + 1;
+            continue;
+        }
+        break;
+    }
+    return i;
+}
+function pushElement(elements, content, start, end) {
+    const from = skipLeadingTrivia(content, start, end);
+    const text = content.slice(from, end).trim();
+    if (text === '')
+        return;
+    elements.push({ text, index: from });
+}
+/**
+ * Scan a `[ … ]` / `( … )` / `{ … }` block from its OPENING bracket, splitting
+ * the top-level (depth-1) comma-separated elements. String- and comment-aware,
+ * so commas and brackets inside nested literals, strings, or comments never
+ * mis-split. An unterminated block yields everything to end-of-content.
+ */
+export function scanBalanced(content, openIndex) {
+    const elements = [];
+    let depth = 0;
+    let elemStart = openIndex + 1;
+    for (let i = openIndex; i < content.length; i += 1) {
+        const c = content[i];
+        if (c === '"' || c === "'" || c === '`') {
+            i = skipString(content, i);
+            continue;
+        }
+        if (c === '/') {
+            const commentEnd = skipComment(content, i);
+            if (commentEnd >= 0) {
+                i = commentEnd;
+                continue;
+            }
+        }
+        if (c === '[' || c === '(' || c === '{') {
+            depth += 1;
+        }
+        else if (c === ']' || c === ')' || c === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                pushElement(elements, content, elemStart, i);
+                return { elements, end: i };
+            }
+        }
+        else if (c === ',' && depth === 1) {
+            pushElement(elements, content, elemStart, i);
+            elemStart = i + 1;
+        }
+    }
+    pushElement(elements, content, elemStart, content.length);
+    return { elements, end: content.length - 1 };
+}
+/**
+ * The id carried by one element: the contents of a leading quoted string, or
+ * the leading identifier. `undefined` when the element starts with neither
+ * (a spread, a number, a nested literal).
+ */
+export function elementToken(text) {
+    const first = text[0];
+    if (first === '"' || first === "'" || first === '`') {
+        const close = text.indexOf(first, 1);
+        return close > 0 ? text.slice(1, close) : undefined;
+    }
+    const m = /^[A-Za-z_$][\w$]*/.exec(text);
+    return m ? m[0] : undefined;
+}
+/**
+ * The VALUE side of a `key: value` / `member = value` element: the contents of
+ * a quoted string, or a bare numeric/identifier token. `undefined` when the
+ * element carries no assignment or the value is a nested construct.
+ */
+export function elementValue(text) {
+    // Find the first top-level `:` or `=` (skipping strings and `=>`).
+    for (let i = 0; i < text.length; i += 1) {
+        const c = text[i];
+        if (c === '"' || c === "'" || c === '`') {
+            i = skipString(text, i);
+            continue;
+        }
+        if (c === '=' && text[i + 1] === '>')
+            return undefined;
+        if (c === ':' || c === '=') {
+            const rhs = text.slice(i + 1).trim();
+            if (rhs === '')
+                return undefined;
+            const q = rhs[0];
+            if (q === '"' || q === "'" || q === '`') {
+                const close = rhs.indexOf(q, 1);
+                return close > 0 ? rhs.slice(1, close) : undefined;
+            }
+            const m = /^[\w$.-]+/.exec(rhs);
+            return m ? m[0] : undefined;
+        }
+    }
+    return undefined;
+}

package/dist/generated/check-provenance.d.ts

@@ -0,0 +1,37 @@
+import type { IGeneratedArtifactRule } from '@shrkcrft/core';
+/** What a provenance finding is about. */
+export type ProvenanceFindingKind = 
+/** A file inside `generatedGlob` carries no "do not edit" header. */
+'missing-header'
+/** A file OUTSIDE the glob carries the header — a hand-written file mislabeled. */
+ | 'mislabeled'
+/** Advisory: the header does not name how to regenerate the file. */
+ | 'no-regen-pointer';
+export interface IProvenanceFinding {
+    readonly ruleId: string;
+    readonly file: string;
+    readonly kind: ProvenanceFindingKind;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+}
+/**
+ * Derive the globs to search for MISLABELED files when the rule doesn't name
+ * them: one `**\/*.<ext>` per distinct extension in `generatedGlob`. Bounded and
+ * deterministic — never a whole-tree read of every file type.
+ */
+export declare function deriveOutsideGlobs(generatedGlob: readonly string[]): string[];
+/**
+ * Check the "this file is generated" header contract.
+ *
+ * Pure: the caller supplies the file contents, so this runs with no regen
+ * command, no temp dir, and no spawn — a header-only rule is fully useful (and
+ * safe to ship from a pack) on its own.
+ *
+ * `outside` should contain candidate files NOT in `generatedGlob`; pass an empty
+ * map when `forbidOutside` is off.
+ */
+export declare function checkProvenanceHeaders(rule: IGeneratedArtifactRule, generated: ReadonlyMap<string, string>, outside: ReadonlyMap<string, string>): {
+    findings: readonly IProvenanceFinding[];
+    error?: string;
+};
+//# sourceMappingURL=check-provenance.d.ts.map

package/dist/generated/check-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-provenance.d.ts","sourceRoot":"","sources":["../../src/generated/check-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAG7D,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB;AAC/B,qEAAqE;AACnE,gBAAgB;AAClB,mFAAmF;GACjF,YAAY;AACd,qEAAqE;GACnE,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAO7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC;IAAE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2D7D"}