@shrkcrft/inspector 0.1.0-alpha.1

package/dist/area-map.js

@@ -0,0 +1,214 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const AREA_MAP_SCHEMA = 'sharkcraft.area-map/v1';
+export var AreaKind;
+(function (AreaKind) {
+    AreaKind["Core"] = "core";
+    AreaKind["Common"] = "common";
+    AreaKind["Runtime"] = "runtime";
+    AreaKind["Kernel"] = "kernel";
+    AreaKind["Plugin"] = "plugin";
+    AreaKind["Adapter"] = "adapter";
+    AreaKind["Ui"] = "ui";
+    AreaKind["App"] = "app";
+    AreaKind["Api"] = "api";
+    AreaKind["Tests"] = "tests";
+    AreaKind["Docs"] = "docs";
+    AreaKind["Infra"] = "infra";
+    AreaKind["Generated"] = "generated";
+    AreaKind["Unknown"] = "unknown";
+})(AreaKind || (AreaKind = {}));
+/**
+ * Return a copy of `map` with `areas[]` filtered to only those whose `id`
+ * is in `keepIds`. Sets `filtered: true` and preserves `areasTotal` so
+ * consumers know the map was slimmed.
+ */
+export function filterAreaMap(map, keepIds) {
+    if (keepIds.length === 0)
+        return map;
+    const keep = new Set(keepIds);
+    const filtered = map.areas.filter((a) => keep.has(a.id));
+    return {
+        ...map,
+        areas: filtered,
+        areasTotal: map.areasTotal ?? map.areas.length,
+        filtered: true,
+    };
+}
+const AREA_PATTERNS = [
+    { kind: AreaKind.Core, match: [/^packages\/core(\/|$)/, /^src\/core(\/|$)/], idHint: 'core' },
+    { kind: AreaKind.Common, match: [/^packages\/(common|shared)(\/|$)/, /^src\/(common|shared)(\/|$)/], idHint: 'common' },
+    { kind: AreaKind.Runtime, match: [/^packages\/runtime(\/|$)/, /^src\/runtime(\/|$)/], idHint: 'runtime' },
+    { kind: AreaKind.Kernel, match: [/^packages\/kernel(\/|$)/, /^src\/kernel(\/|$)/], idHint: 'kernel' },
+    { kind: AreaKind.Plugin, match: [/plugins?(\/|$)/, /^packages\/plugin-/], idHint: 'plugin' },
+    { kind: AreaKind.Adapter, match: [/adapters?(\/|$)/, /^packages\/adapter-/], idHint: 'adapter' },
+    { kind: AreaKind.Ui, match: [/^packages\/(ui|dashboard|web)(\/|$)/, /^(src|app)\/(ui|components|pages|views)(\/|$)/], idHint: 'ui' },
+    { kind: AreaKind.App, match: [/^apps?\//, /^packages\/app(\/|$)/], idHint: 'app' },
+    { kind: AreaKind.Api, match: [/^packages\/api(\/|$)/, /\/api\//, /\/routes\//, /\/controllers\//], idHint: 'api' },
+    { kind: AreaKind.Tests, match: [/^tests?\//, /\.spec\.[tj]sx?$/, /\.test\.[tj]sx?$/, /\/__tests__\//], idHint: 'tests' },
+    { kind: AreaKind.Docs, match: [/^docs?\//, /\.md$/], idHint: 'docs' },
+    { kind: AreaKind.Infra, match: [/^(\.github|scripts|infra|docker|deploy)\//, /^Dockerfile/], idHint: 'infra' },
+    { kind: AreaKind.Generated, match: [/\/dist\//, /\/generated\//, /\/build\//, /\.d\.ts$/], idHint: 'generated' },
+];
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.sharkcraft',
+    'dist',
+    'build',
+    '.cache',
+    '.turbo',
+    '.nx',
+    'coverage',
+    '.next',
+]);
+function walk(root, base = '') {
+    const out = [];
+    const target = base ? nodePath.join(root, base) : root;
+    let entries;
+    try {
+        entries = readdirSync(target);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.') && !['.github', '.gitlab'].includes(name))
+            continue;
+        if (IGNORE_DIRS.has(name))
+            continue;
+        const rel = base ? `${base}/${name}` : name;
+        let stat;
+        try {
+            stat = statSync(nodePath.join(root, rel));
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            out.push(...walk(root, rel));
+        }
+        else if (stat.isFile()) {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+function classify(file) {
+    for (const p of AREA_PATTERNS) {
+        if (p.match.some((re) => re.test(file)))
+            return p.kind;
+    }
+    return AreaKind.Unknown;
+}
+function packageOrTopSegment(file) {
+    const segs = file.split('/');
+    if (segs[0] === 'packages' && segs[1])
+        return `packages/${segs[1]}`;
+    if (segs[0] === 'apps' && segs[1])
+        return `apps/${segs[1]}`;
+    return segs[0] ?? '';
+}
+export function buildAreaMap(inspection) {
+    const root = inspection.projectRoot;
+    const allFiles = existsSync(root) ? walk(root) : [];
+    const byKey = new Map();
+    let unclassified = 0;
+    for (const f of allFiles) {
+        const kind = classify(f);
+        if (kind === AreaKind.Unknown)
+            unclassified += 1;
+        const seg = packageOrTopSegment(f);
+        const key = `${kind}:${seg}`;
+        let entry = byKey.get(key);
+        if (!entry) {
+            entry = { kind, paths: new Set(), fileCount: 0 };
+            byKey.set(key, entry);
+        }
+        entry.paths.add(seg);
+        entry.fileCount += 1;
+    }
+    const boundaryRules = inspection.boundaryRegistry.list();
+    const templates = inspection.templateRegistry.list();
+    const pipelines = inspection.pipelineRegistry.list();
+    const areas = [];
+    for (const [key, info] of byKey) {
+        const paths = [...info.paths].sort();
+        const boundaryRuleIds = boundaryRules
+            .filter((r) => paths.some((p) => (r.from ?? []).some((g) => p.includes(stripGlob(g)))))
+            .map((r) => r.id);
+        const relatedTemplateIds = templates
+            .filter((t) => paths.some((p) => targetPathString(t).includes(p.split('/').pop() ?? '')))
+            .map((t) => t.id);
+        const relatedPipelineIds = pipelines
+            .filter((p) => paths.some((path) => (p.steps ?? []).some((s) => JSON.stringify(s).toLowerCase().includes(path.toLowerCase()))))
+            .map((p) => p.id);
+        areas.push({
+            id: key,
+            kind: info.kind,
+            paths,
+            fileCount: info.fileCount,
+            importsIn: 0,
+            importsOut: 0,
+            boundaryRuleIds,
+            relatedTemplateIds,
+            relatedPipelineIds,
+            riskScore: computeRiskScore({
+                kind: info.kind,
+                fileCount: info.fileCount,
+                boundaryRules: boundaryRuleIds.length,
+            }),
+        });
+    }
+    areas.sort((a, b) => b.fileCount - a.fileCount);
+    return {
+        schema: AREA_MAP_SCHEMA,
+        projectRoot: root,
+        areas,
+        unclassifiedFiles: unclassified,
+    };
+}
+function stripGlob(s) {
+    return s.replace(/[*?]/g, '');
+}
+function targetPathString(t) {
+    const tp = t.targetPath;
+    if (typeof tp === 'string')
+        return tp;
+    return '';
+}
+function computeRiskScore(input) {
+    let score = 0;
+    if (input.kind === AreaKind.Unknown)
+        score += 30;
+    if (input.kind === AreaKind.Generated)
+        score -= 10;
+    if (input.fileCount > 100)
+        score += 15;
+    if (input.fileCount > 25 && input.boundaryRules === 0)
+        score += 20;
+    if (input.boundaryRules > 3)
+        score -= 10;
+    return Math.max(0, Math.min(100, 30 + score));
+}
+export function renderAreaMapText(map) {
+    const lines = [];
+    lines.push(`Area map (${map.areas.length} areas, ${map.unclassifiedFiles} unclassified files)`);
+    for (const a of map.areas.slice(0, 50)) {
+        lines.push(`  ${a.kind.padEnd(10)} ${String(a.fileCount).padStart(5)} files  paths=${a.paths.join(', ')}  risk=${a.riskScore}`);
+    }
+    return lines.join('\n');
+}
+export function renderAreaMapMarkdown(map) {
+    const lines = [];
+    lines.push(`# Repository area map`);
+    lines.push('');
+    lines.push(`Total areas: **${map.areas.length}** — unclassified files: ${map.unclassifiedFiles}.`);
+    lines.push('');
+    lines.push('| Kind | Files | Paths | Boundary rules | Risk |');
+    lines.push('| --- | ---: | --- | ---: | ---: |');
+    for (const a of map.areas) {
+        lines.push(`| ${a.kind} | ${a.fileCount} | ${a.paths.join(', ')} | ${a.boundaryRuleIds.length} | ${a.riskScore} |`);
+    }
+    return lines.join('\n') + '\n';
+}

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"}