@shrkcrft/inspector 0.1.0-alpha.2

package/dist/asset-provenance.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Asset provenance tracking.
+ *
+ * Append-only JSONL ledger that records every authoring action: who/what
+ * authored which knowledge entry / pack asset, when, why, and where the
+ * preview/patch lives. Pure local metadata — no telemetry, no network.
+ *
+ * File: <projectRoot>/.sharkcraft/asset-provenance.jsonl
+ *
+ * Each line: a single `IAssetProvenanceEntry` JSON object, schema
+ * `sharkcraft.asset-provenance/v1`.
+ */
+export declare const ASSET_PROVENANCE_SCHEMA = "sharkcraft.asset-provenance/v1";
+/**
+ * Schema marker emitted iff an entry carries `relatedSpec`. v1
+ * entries (no relatedSpec) remain readable forever; v2 entries add
+ * the spec back-pointer without breaking back-compat.
+ */
+export declare const ASSET_PROVENANCE_SCHEMA_V2 = "sharkcraft.asset-provenance/v2";
+export type AssetProvenanceSchema = typeof ASSET_PROVENANCE_SCHEMA | typeof ASSET_PROVENANCE_SCHEMA_V2;
+export declare enum AssetProvenanceSource {
+    Manual = "manual",
+    Agent = "agent",
+    Cli = "cli",
+    Session = "session",
+    Unknown = "unknown"
+}
+export declare enum AssetProvenanceOperation {
+    Add = "add",
+    Update = "update",
+    Remove = "remove",
+    Preview = "preview",
+    Apply = "apply",
+    Acknowledge = "acknowledge"
+}
+export declare enum AssetKind {
+    Knowledge = "knowledge",
+    SearchTuning = "search-tuning",
+    FeedbackRule = "feedback-rule",
+    AgentTest = "agent-test",
+    Convention = "convention",
+    TaskRoutingHint = "task-routing-hint",
+    RegistrationHint = "registration-hint",
+    ScaffoldPattern = "scaffold-pattern",
+    Template = "template",
+    Rule = "rule",
+    Path = "path",
+    Pipeline = "pipeline",
+    Preset = "preset",
+    Boundary = "boundary"
+}
+export interface IAssetProvenanceEntry {
+    schema: AssetProvenanceSchema;
+    generatedAt: string;
+    operation: AssetProvenanceOperation;
+    assetKind: AssetKind | string;
+    assetId: string;
+    targetFile?: string;
+    source: AssetProvenanceSource;
+    sessionId?: string;
+    bundleId?: string;
+    reason?: string;
+    relatedTask?: string;
+    /**
+     * Back-pointer to a `.sharkcraft/specs/<id>/` spec. Present iff
+     * the entry was recorded as part of a spec implement/apply. When
+     * present, the entry's schema is bumped to v2; absent entries stay v1.
+     */
+    relatedSpec?: string;
+    author?: string;
+    previewPath?: string;
+    patchPath?: string;
+    /** Free-form, structured payload — kept small. */
+    extra?: Record<string, unknown>;
+}
+export interface IRecordProvenanceInput {
+    /** Project root (where `.sharkcraft/` lives). */
+    projectRoot: string;
+    /** Entry fields — everything except schema + generatedAt (auto-filled). */
+    entry: Omit<IAssetProvenanceEntry, 'schema' | 'generatedAt'>;
+    /** Override the generatedAt — defaults to now. */
+    generatedAt?: string;
+}
+export interface IProvenanceListOptions {
+    /** Filter by asset kind. */
+    assetKind?: AssetKind | string;
+    /** Filter by asset id. */
+    assetId?: string;
+    /** Filter by operation. */
+    operation?: AssetProvenanceOperation;
+    /** Max entries to return (most recent first). */
+    limit?: number;
+}
+export declare function provenancePath(projectRoot: string): string;
+export declare function ensureProvenanceDir(projectRoot: string): void;
+export declare function provenanceExists(projectRoot: string): boolean;
+export declare function readProvenance(projectRoot: string): IAssetProvenanceEntry[];
+export declare function recordProvenance(input: IRecordProvenanceInput): IAssetProvenanceEntry;
+export declare function listProvenance(projectRoot: string, options?: IProvenanceListOptions): IAssetProvenanceEntry[];
+export interface IProvenanceShowResult {
+    assetKind: string;
+    assetId: string;
+    entries: ReadonlyArray<IAssetProvenanceEntry>;
+    /** Most recent entry, for quick access. */
+    latest?: IAssetProvenanceEntry;
+}
+export declare function showProvenance(projectRoot: string, assetId: string, assetKind?: AssetKind | string): IProvenanceShowResult;
+export interface IProvenanceReport {
+    schema: 'sharkcraft.asset-provenance-report/v1';
+    generatedAt: string;
+    total: number;
+    byKind: Readonly<Record<string, number>>;
+    byOperation: Readonly<Record<string, number>>;
+    bySource: Readonly<Record<string, number>>;
+    recent: ReadonlyArray<IAssetProvenanceEntry>;
+    /** Whether the ledger file exists at all. */
+    ledgerExists: boolean;
+    ledgerPath: string;
+    ledgerSizeBytes: number;
+}
+export declare function buildProvenanceReport(projectRoot: string, recentLimit?: number): IProvenanceReport;
+export declare function renderProvenanceMarkdown(report: IProvenanceReport): string;
+//# sourceMappingURL=asset-provenance.d.ts.map

package/dist/asset-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-provenance.d.ts","sourceRoot":"","sources":["../src/asset-provenance.ts"],"names":[],"mappings":"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"}

package/dist/asset-provenance.js

@@ -0,0 +1,209 @@
+/**
+ * Asset provenance tracking.
+ *
+ * Append-only JSONL ledger that records every authoring action: who/what
+ * authored which knowledge entry / pack asset, when, why, and where the
+ * preview/patch lives. Pure local metadata — no telemetry, no network.
+ *
+ * File: <projectRoot>/.sharkcraft/asset-provenance.jsonl
+ *
+ * Each line: a single `IAssetProvenanceEntry` JSON object, schema
+ * `sharkcraft.asset-provenance/v1`.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const ASSET_PROVENANCE_SCHEMA = 'sharkcraft.asset-provenance/v1';
+/**
+ * Schema marker emitted iff an entry carries `relatedSpec`. v1
+ * entries (no relatedSpec) remain readable forever; v2 entries add
+ * the spec back-pointer without breaking back-compat.
+ */
+export const ASSET_PROVENANCE_SCHEMA_V2 = 'sharkcraft.asset-provenance/v2';
+export var AssetProvenanceSource;
+(function (AssetProvenanceSource) {
+    AssetProvenanceSource["Manual"] = "manual";
+    AssetProvenanceSource["Agent"] = "agent";
+    AssetProvenanceSource["Cli"] = "cli";
+    AssetProvenanceSource["Session"] = "session";
+    AssetProvenanceSource["Unknown"] = "unknown";
+})(AssetProvenanceSource || (AssetProvenanceSource = {}));
+export var AssetProvenanceOperation;
+(function (AssetProvenanceOperation) {
+    AssetProvenanceOperation["Add"] = "add";
+    AssetProvenanceOperation["Update"] = "update";
+    AssetProvenanceOperation["Remove"] = "remove";
+    AssetProvenanceOperation["Preview"] = "preview";
+    AssetProvenanceOperation["Apply"] = "apply";
+    AssetProvenanceOperation["Acknowledge"] = "acknowledge";
+})(AssetProvenanceOperation || (AssetProvenanceOperation = {}));
+export var AssetKind;
+(function (AssetKind) {
+    AssetKind["Knowledge"] = "knowledge";
+    AssetKind["SearchTuning"] = "search-tuning";
+    AssetKind["FeedbackRule"] = "feedback-rule";
+    AssetKind["AgentTest"] = "agent-test";
+    AssetKind["Convention"] = "convention";
+    AssetKind["TaskRoutingHint"] = "task-routing-hint";
+    AssetKind["RegistrationHint"] = "registration-hint";
+    AssetKind["ScaffoldPattern"] = "scaffold-pattern";
+    AssetKind["Template"] = "template";
+    AssetKind["Rule"] = "rule";
+    AssetKind["Path"] = "path";
+    AssetKind["Pipeline"] = "pipeline";
+    AssetKind["Preset"] = "preset";
+    AssetKind["Boundary"] = "boundary";
+})(AssetKind || (AssetKind = {}));
+export function provenancePath(projectRoot) {
+    return nodePath.join(projectRoot, '.sharkcraft', 'asset-provenance.jsonl');
+}
+export function ensureProvenanceDir(projectRoot) {
+    const dir = nodePath.join(projectRoot, '.sharkcraft');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+export function provenanceExists(projectRoot) {
+    return existsSync(provenancePath(projectRoot));
+}
+export function readProvenance(projectRoot) {
+    const path = provenancePath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    const out = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed &&
+                typeof parsed === 'object' &&
+                (parsed.schema === ASSET_PROVENANCE_SCHEMA ||
+                    parsed.schema === ASSET_PROVENANCE_SCHEMA_V2)) {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Tolerate corrupt lines — the ledger is append-only and lossy
+            // entries should not poison the read.
+        }
+    }
+    return out;
+}
+export function recordProvenance(input) {
+    const root = input.projectRoot;
+    ensureProvenanceDir(root);
+    const path = provenancePath(root);
+    // Safety: refuse to write anywhere except inside the project root's
+    // `.sharkcraft/` directory.
+    const expected = nodePath.resolve(root, '.sharkcraft', 'asset-provenance.jsonl');
+    const actual = nodePath.resolve(path);
+    if (actual !== expected) {
+        throw new Error(`refusing to write provenance outside .sharkcraft/: ${actual}`);
+    }
+    // Bump schema iff the entry carries a relatedSpec back-pointer.
+    // Otherwise stay v1 for back-compat. The optional field is the ONLY
+    // axis that triggers the bump.
+    const usesV2 = input.entry.relatedSpec !== undefined;
+    const entry = {
+        schema: usesV2 ? ASSET_PROVENANCE_SCHEMA_V2 : ASSET_PROVENANCE_SCHEMA,
+        generatedAt: input.generatedAt ?? new Date().toISOString(),
+        ...input.entry,
+    };
+    if (existsSync(path)) {
+        appendFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+    }
+    else {
+        writeFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+    }
+    return entry;
+}
+export function listProvenance(projectRoot, options = {}) {
+    const all = readProvenance(projectRoot);
+    let filtered = all;
+    if (options.assetKind)
+        filtered = filtered.filter((e) => e.assetKind === options.assetKind);
+    if (options.assetId)
+        filtered = filtered.filter((e) => e.assetId === options.assetId);
+    if (options.operation)
+        filtered = filtered.filter((e) => e.operation === options.operation);
+    // Most-recent first.
+    filtered = filtered.slice().sort((a, b) => (a.generatedAt < b.generatedAt ? 1 : -1));
+    if (options.limit && options.limit > 0)
+        filtered = filtered.slice(0, options.limit);
+    return filtered;
+}
+export function showProvenance(projectRoot, assetId, assetKind) {
+    const entries = listProvenance(projectRoot, { assetId, assetKind });
+    return {
+        assetKind: assetKind ? String(assetKind) : entries[0]?.assetKind ?? 'unknown',
+        assetId,
+        entries,
+        ...(entries[0] ? { latest: entries[0] } : {}),
+    };
+}
+export function buildProvenanceReport(projectRoot, recentLimit = 10) {
+    const path = provenancePath(projectRoot);
+    const ledgerExists = existsSync(path);
+    const all = ledgerExists ? readProvenance(projectRoot) : [];
+    const byKind = {};
+    const byOperation = {};
+    const bySource = {};
+    for (const e of all) {
+        byKind[e.assetKind] = (byKind[e.assetKind] ?? 0) + 1;
+        byOperation[e.operation] = (byOperation[e.operation] ?? 0) + 1;
+        bySource[e.source] = (bySource[e.source] ?? 0) + 1;
+    }
+    const recent = all
+        .slice()
+        .sort((a, b) => (a.generatedAt < b.generatedAt ? 1 : -1))
+        .slice(0, recentLimit);
+    let size = 0;
+    if (ledgerExists) {
+        try {
+            size = statSync(path).size;
+        }
+        catch {
+            size = 0;
+        }
+    }
+    return {
+        schema: 'sharkcraft.asset-provenance-report/v1',
+        generatedAt: new Date().toISOString(),
+        total: all.length,
+        byKind,
+        byOperation,
+        bySource,
+        recent,
+        ledgerExists,
+        ledgerPath: path,
+        ledgerSizeBytes: size,
+    };
+}
+export function renderProvenanceMarkdown(report) {
+    const lines = [];
+    lines.push('# Asset provenance report');
+    lines.push('');
+    lines.push(`Generated: ${report.generatedAt}`);
+    lines.push(`Ledger: \`${report.ledgerPath}\` (${report.ledgerExists ? `${report.ledgerSizeBytes} bytes` : 'missing'})`);
+    lines.push(`Total entries: ${report.total}`);
+    lines.push('');
+    if (!report.ledgerExists) {
+        lines.push('> No provenance ledger yet. Run any `shrk knowledge author` / `shrk pack author` preview to start one.');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('## Counts');
+    lines.push('');
+    for (const [k, n] of Object.entries(report.byKind))
+        lines.push(`- kind \`${k}\`: ${n}`);
+    for (const [k, n] of Object.entries(report.byOperation))
+        lines.push(`- op \`${k}\`: ${n}`);
+    for (const [k, n] of Object.entries(report.bySource))
+        lines.push(`- source \`${k}\`: ${n}`);
+    lines.push('');
+    lines.push('## Recent');
+    lines.push('');
+    for (const e of report.recent) {
+        lines.push(`- ${e.generatedAt} \`${e.operation}\` \`${e.assetKind}:${e.assetId}\` ← ${e.source}${e.reason ? ` — ${e.reason}` : ''}`);
+    }
+    return lines.join('\n');
+}

package/dist/barrel-operations.d.ts

@@ -0,0 +1,45 @@
+export interface IBuildBarrelExportInput {
+    /** Project-relative barrel file path (e.g. `libs/x/src/index.ts`). */
+    targetPath: string;
+    /** Source path `from './lib/y'`. */
+    from: string;
+    /** Optional explicit symbol export (`export { Foo } from '...'`). */
+    symbol?: string;
+    /** Insert sorted by `from` (default 'append'). */
+    sort?: 'alphabetic' | 'append';
+    /** Optional group comment / marker (e.g. `// feature exports`). */
+    group?: string;
+    /** Idempotency marker substring — when present in the file, the op is a no-op. */
+    idempotencyMarker?: string;
+    /** Project root for filesystem inspection (default cwd). */
+    projectRoot?: string;
+}
+export type BarrelExportOutcome = 'inserted-alphabetic' | 'appended' | 'duplicate-skipped' | 'idempotent-marker-present' | 'conflict-ambiguous-style';
+export interface IBarrelExportOperation {
+    schema: 'sharkcraft.barrel-export/v1';
+    targetPath: string;
+    outcome: BarrelExportOutcome;
+    operationDetail: string;
+    operation: {
+        kind: 'export';
+        from: string;
+        symbols?: readonly string[];
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'insert-before';
+        anchor: string;
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'append';
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    };
+    /** When `conflict-ambiguous-style`, surfaces what was inconsistent. */
+    conflict?: string;
+}
+export declare function buildBarrelExportOperation(input: IBuildBarrelExportInput): IBarrelExportOperation;
+//# sourceMappingURL=barrel-operations.d.ts.map

package/dist/barrel-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barrel-operations.d.ts","sourceRoot":"","sources":["../src/barrel-operations.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,IAAI,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;IAC/B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,UAAU,GACV,mBAAmB,GACnB,2BAA2B,GAC3B,0BAA0B,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EACL;QACE,IAAI,EAAE,QAAQ,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GACD;QACE,IAAI,EAAE,eAAe,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GACD;QACE,IAAI,EAAE,QAAQ,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACN,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+CD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,uBAAuB,GAC7B,sBAAsB,CA0FxB"}

package/dist/barrel-operations.js

@@ -0,0 +1,159 @@
+/**
+ * Anchor-aware barrel insert polish.
+ *
+ * Pure helper that turns a desired barrel mutation into a plan v2 `export`
+ * (or `append`) operation with:
+ *   - de-duplication: existing exports for the same `from` clause win.
+ *   - alphabetic insertion: when requested, insert the new line in sorted
+ *     order rather than appending.
+ *   - explicit idempotency marker: opt-in marker text the caller can use
+ *     to gate later runs.
+ *   - ambiguity detection: if the barrel mixes `export *` and
+ *     `export { ... }` styles for the same `from`, surface a conflict
+ *     instead of guessing.
+ *
+ * The output shape is suitable for `ITemplateChange.operation`. Callers
+ * compose it into the bigger plan exactly like the existing
+ * `add-barrel-export` helper does.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const SCHEMA = 'sharkcraft.barrel-export/v1';
+function readBarrel(targetPath, projectRoot) {
+    const full = nodePath.isAbsolute(targetPath)
+        ? targetPath
+        : nodePath.join(projectRoot, targetPath);
+    if (!existsSync(full))
+        return null;
+    try {
+        return readFileSync(full, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function buildExportLine(from, symbol) {
+    if (symbol)
+        return `export { ${symbol} } from '${from}';`;
+    return `export * from '${from}';`;
+}
+function findFirstSortedAnchor(text, from) {
+    const lines = text.split('\n');
+    for (const line of lines) {
+        const m = /^export\s+\*?\s*(\{[^}]*\}\s*)?from\s+['"]([^'"]+)['"]/.exec(line.trim());
+        if (!m)
+            continue;
+        const existingFrom = m[2] ?? '';
+        if (existingFrom > from)
+            return line;
+    }
+    return null;
+}
+function detectAmbiguousStyle(text, from) {
+    let starCount = 0;
+    let namedCount = 0;
+    for (const line of text.split('\n')) {
+        const m = /^export\s+(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/.exec(line.trim());
+        if (!m || m[1] !== from)
+            continue;
+        if (line.includes('export *'))
+            starCount += 1;
+        else
+            namedCount += 1;
+    }
+    if (starCount > 0 && namedCount > 0) {
+        return `Barrel exports for "${from}" mix \`export *\` and \`export { ... }\` styles.`;
+    }
+    return null;
+}
+export function buildBarrelExportOperation(input) {
+    const projectRoot = input.projectRoot ?? process.cwd();
+    const text = readBarrel(input.targetPath, projectRoot);
+    const exportLine = buildExportLine(input.from, input.symbol);
+    const description = `Barrel export for ${input.from}${input.symbol ? ` (${input.symbol})` : ''}`;
+    // 1) Idempotency marker — short-circuit if the marker is present.
+    if (text && input.idempotencyMarker && text.includes(input.idempotencyMarker)) {
+        return {
+            schema: SCHEMA,
+            targetPath: input.targetPath,
+            outcome: 'idempotent-marker-present',
+            operationDetail: `Barrel already contains marker "${input.idempotencyMarker}"; no op.`,
+            operation: {
+                kind: 'append',
+                snippet: '',
+                ifMissing: input.idempotencyMarker,
+                description,
+            },
+        };
+    }
+    // 2) Ambiguous-style conflict — surface, do not auto-pick.
+    if (text) {
+        const conflict = detectAmbiguousStyle(text, input.from);
+        if (conflict) {
+            return {
+                schema: SCHEMA,
+                targetPath: input.targetPath,
+                outcome: 'conflict-ambiguous-style',
+                operationDetail: conflict,
+                operation: {
+                    kind: 'append',
+                    snippet: exportLine + '\n',
+                    description,
+                },
+                conflict,
+            };
+        }
+        // 3) Existing export → duplicate-skipped.
+        if (text.includes(exportLine)) {
+            return {
+                schema: SCHEMA,
+                targetPath: input.targetPath,
+                outcome: 'duplicate-skipped',
+                operationDetail: `Barrel already exports ${input.from}; skipping.`,
+                operation: {
+                    kind: 'export',
+                    from: input.from,
+                    ifMissing: exportLine,
+                    description,
+                    ...(input.symbol ? { symbols: [input.symbol] } : {}),
+                },
+            };
+        }
+    }
+    // 4) Alphabetic insert.
+    if (input.sort === 'alphabetic' && text) {
+        const anchor = findFirstSortedAnchor(text, input.from);
+        if (anchor) {
+            const snippet = (input.group ? `// ${input.group}\n` : '') + exportLine + '\n';
+            return {
+                schema: SCHEMA,
+                targetPath: input.targetPath,
+                outcome: 'inserted-alphabetic',
+                operationDetail: `Inserted before "${anchor}".`,
+                operation: {
+                    kind: 'insert-before',
+                    anchor,
+                    snippet,
+                    ifMissing: exportLine,
+                    description,
+                },
+            };
+        }
+    }
+    // 5) Append fallback (default).
+    const snippet = (input.group ? `// ${input.group}\n` : '') + exportLine + '\n';
+    return {
+        schema: SCHEMA,
+        targetPath: input.targetPath,
+        outcome: 'appended',
+        operationDetail: 'Appended to end of barrel.',
+        operation: {
+            kind: 'export',
+            from: input.from,
+            ifMissing: exportLine,
+            description,
+            ...(input.symbol ? { symbols: [input.symbol] } : {}),
+        },
+    };
+    void snippet;
+}

package/dist/boundaries-changed-only.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Changed-only boundary filter.
+ *
+ * The boundary engine itself is unchanged. This module takes the raw
+ * violations list from `evaluateBoundaries` (or the polyglot equivalent) +
+ * a set of changed files, and returns:
+ *   - includedViolations:   violations whose origin file *or* the file that
+ *                           introduces the import edge is in the changed set.
+ *   - ignoredLegacyCount:   violations filtered out because no changed file
+ *                           touches them.
+ *   - ignoredLegacyByRule:  ignored counts grouped by ruleId.
+ *   - changedFiles:         the resolved changed-file set (project-relative).
+ *
+ * The engine never changes the violation contents — only filters.
+ */
+export declare enum ChangedScopeMode {
+    ChangedOnly = "changed-only",
+    Since = "since",
+    Staged = "staged",
+    Files = "files"
+}
+export interface IChangedScopeOptions {
+    /** Project root used to anchor relative paths. */
+    projectRoot: string;
+    /** When provided, `git diff <ref>` selects the changed file set. */
+    since?: string;
+    /** When true, only staged (index) files. */
+    staged?: boolean;
+    /** Explicit file list (project-relative, '/'-normalised). */
+    files?: ReadonlyArray<string>;
+    /** When true, include the unstaged working tree changes too. */
+    includeWorktree?: boolean;
+}
+export interface IBoundaryLikeViolation {
+    ruleId: string;
+    /** Either `file` (TS engine) or `fromFile` (polyglot engine). */
+    file?: string;
+    fromFile?: string;
+}
+export interface IChangedScopeFilterResult<TViolation extends IBoundaryLikeViolation> {
+    mode: ChangedScopeMode;
+    changedFiles: ReadonlyArray<string>;
+    includedViolations: ReadonlyArray<TViolation>;
+    ignoredLegacyCount: number;
+    ignoredLegacyByRule: Readonly<Record<string, number>>;
+}
+export declare function resolveChangedFiles(opts: IChangedScopeOptions): {
+    mode: ChangedScopeMode;
+    files: string[];
+};
+export declare function filterViolationsToChangedScope<TViolation extends IBoundaryLikeViolation>(violations: ReadonlyArray<TViolation>, opts: IChangedScopeOptions): IChangedScopeFilterResult<TViolation>;
+export interface IChangedBoundaryReport {
+    schema: 'sharkcraft.changed-boundary-report/v1';
+    mode: ChangedScopeMode;
+    changedFiles: ReadonlyArray<string>;
+    totalViolations: number;
+    includedViolations: ReadonlyArray<IBoundaryLikeViolation>;
+    ignoredLegacyCount: number;
+    ignoredLegacyByRule: Readonly<Record<string, number>>;
+}
+export declare function buildChangedBoundaryReport<TViolation extends IBoundaryLikeViolation>(violations: ReadonlyArray<TViolation>, opts: IChangedScopeOptions): IChangedBoundaryReport;
+//# sourceMappingURL=boundaries-changed-only.d.ts.map

package/dist/boundaries-changed-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundaries-changed-only.d.ts","sourceRoot":"","sources":["../src/boundaries-changed-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,oBAAY,gBAAgB;IAC1B,WAAW,iBAAiB;IAC5B,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB,CAAC,UAAU,SAAS,sBAAsB;IAClF,IAAI,EAAE,gBAAgB,CAAC;IACvB,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,kBAAkB,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAWD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG;IAC/D,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAkBA;AAED,wBAAgB,8BAA8B,CAAC,UAAU,SAAS,sBAAsB,EACtF,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,EACrC,IAAI,EAAE,oBAAoB,GACzB,yBAAyB,CAAC,UAAU,CAAC,CAiCvC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,uCAAuC,CAAC;IAChD,IAAI,EAAE,gBAAgB,CAAC;IACvB,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAC1D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED,wBAAgB,0BAA0B,CAAC,UAAU,SAAS,sBAAsB,EAClF,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,EACrC,IAAI,EAAE,oBAAoB,GACzB,sBAAsB,CAWxB"}