@shrkcrft/api-surface-diff 0.1.0-alpha.10

package/dist/cache/signature-cache.d.ts

@@ -0,0 +1,34 @@
+export declare const SIGNATURE_CACHE_SCHEMA: "sharkcraft.api-surface-cache/v1";
+/**
+ * Per-file entry. `sha1` is the SHA1 of the source file's contents at
+ * the time the cache was written. `signatures` maps `symbol-name +
+ * isDefault` (within that file) to its canonical signature string.
+ *
+ * We key signatures within a file by `${name}|${isDefault?1:0}` rather
+ * than by global symbol id so the cache survives file renames (a file
+ * rename invalidates the SHA1 anyway, so the cache misses on the old
+ * file but the new file builds fresh).
+ */
+export interface ISignatureCacheFileEntry {
+    /** SHA1 of file contents when the cache was written. */
+    sha1: string;
+    /** keyed by `${name}|${isDefault?1:0}`. */
+    signatures: Readonly<Record<string, string>>;
+}
+export interface ISignatureCache {
+    schema: typeof SIGNATURE_CACHE_SCHEMA;
+    generatedAt: string;
+    /** Workspace-relative POSIX paths → per-file cache entry. */
+    files: Readonly<Record<string, ISignatureCacheFileEntry>>;
+}
+export declare function emptyCache(): ISignatureCache;
+export declare function loadSignatureCache(projectRoot: string): ISignatureCache;
+export declare function saveSignatureCache(projectRoot: string, cache: ISignatureCache): void;
+export declare function symbolCacheKey(name: string, isDefault: boolean): string;
+/**
+ * Lightweight content fingerprint. Used to invalidate cached
+ * signatures when a source file changes. Mirrors `@shrkcrft/graph`'s
+ * fingerprint algorithm so the two stores agree on file identity.
+ */
+export declare function fingerprintContent(text: string): string;
+//# sourceMappingURL=signature-cache.d.ts.map

package/dist/cache/signature-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-cache.d.ts","sourceRoot":"","sources":["../../src/cache/signature-cache.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,sBAAsB,EAAG,iCAA0C,CAAC;AAGjF;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;CAC3D;AAED,wBAAgB,UAAU,IAAI,eAAe,CAM5C;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAWvE;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAQpF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/cache/signature-cache.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const SIGNATURE_CACHE_SCHEMA = 'sharkcraft.api-surface-cache/v1';
+const CACHE_REL = '.sharkcraft/api-surface/signatures.json';
+export function emptyCache() {
+    return {
+        schema: SIGNATURE_CACHE_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        files: {},
+    };
+}
+export function loadSignatureCache(projectRoot) {
+    const abs = nodePath.join(projectRoot, CACHE_REL);
+    if (!existsSync(abs))
+        return emptyCache();
+    try {
+        const raw = JSON.parse(readFileSync(abs, 'utf8'));
+        if (raw.schema !== SIGNATURE_CACHE_SCHEMA)
+            return emptyCache();
+        return raw;
+    }
+    catch {
+        // Corrupted cache — treat as cold start. The next write will overwrite.
+        return emptyCache();
+    }
+}
+export function saveSignatureCache(projectRoot, cache) {
+    const abs = nodePath.join(projectRoot, CACHE_REL);
+    mkdirSync(nodePath.dirname(abs), { recursive: true });
+    const stamped = {
+        ...cache,
+        generatedAt: new Date().toISOString(),
+    };
+    writeFileSync(abs, JSON.stringify(stamped, null, 2), 'utf8');
+}
+export function symbolCacheKey(name, isDefault) {
+    return `${name}|${isDefault ? 1 : 0}`;
+}
+/**
+ * Lightweight content fingerprint. Used to invalidate cached
+ * signatures when a source file changes. Mirrors `@shrkcrft/graph`'s
+ * fingerprint algorithm so the two stores agree on file identity.
+ */
+export function fingerprintContent(text) {
+    return createHash('sha1').update(text).digest('hex');
+}

package/dist/engine/diff-surfaces.d.ts

@@ -0,0 +1,18 @@
+import { type DiffChangeKind, type IApiSurface, type IApiSurfaceDiff } from '../schema/api-surface.js';
+/**
+ * Compare two API surface snapshots and return a structured diff.
+ *
+ * Matching strategy: symbols are paired by `(package, name, isDefault)`
+ * tuple. This means a symbol that moved files (within the same
+ * package) is reported as `moved-file` (additive); a symbol that moved
+ * packages is `moved-package` (breaking — consumers' imports must
+ * change). Pure rename or kind change with the same matching tuple is
+ * reported as `kind-changed`.
+ *
+ * `removed` entries are always **breaking**. `added` entries are
+ * **additive**. Returned `entries` are sorted breaking → additive →
+ * info, then alphabetically by symbol name.
+ */
+export declare function diffApiSurfaces(baseline: IApiSurface, current: IApiSurface): IApiSurfaceDiff;
+export type { DiffChangeKind };
+//# sourceMappingURL=diff-surfaces.d.ts.map

package/dist/engine/diff-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-surfaces.d.ts","sourceRoot":"","sources":["../../src/engine/diff-surfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,eAAe,EAGrB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,eAAe,CAuH5F;AAqBD,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/engine/diff-surfaces.js

@@ -0,0 +1,150 @@
+import { API_SURFACE_DIFF_SCHEMA, } from "../schema/api-surface.js";
+/**
+ * Compare two API surface snapshots and return a structured diff.
+ *
+ * Matching strategy: symbols are paired by `(package, name, isDefault)`
+ * tuple. This means a symbol that moved files (within the same
+ * package) is reported as `moved-file` (additive); a symbol that moved
+ * packages is `moved-package` (breaking — consumers' imports must
+ * change). Pure rename or kind change with the same matching tuple is
+ * reported as `kind-changed`.
+ *
+ * `removed` entries are always **breaking**. `added` entries are
+ * **additive**. Returned `entries` are sorted breaking → additive →
+ * info, then alphabetically by symbol name.
+ */
+export function diffApiSurfaces(baseline, current) {
+    const baselineByKey = new Map();
+    const currentByKey = new Map();
+    for (const s of baseline.symbols)
+        baselineByKey.set(keyOf(s), s);
+    for (const s of current.symbols)
+        currentByKey.set(keyOf(s), s);
+    const entries = [];
+    // Removed: present in baseline, absent in current.
+    for (const [key, b] of baselineByKey) {
+        if (currentByKey.has(key))
+            continue;
+        entries.push({
+            kind: 'removed',
+            severity: 'breaking',
+            message: `removed: ${describe(b)}`,
+            symbol: b,
+        });
+    }
+    // Added or modified.
+    for (const [key, c] of currentByKey) {
+        const b = baselineByKey.get(key);
+        if (!b) {
+            entries.push({
+                kind: 'added',
+                severity: 'additive',
+                message: `added: ${describe(c)}`,
+                symbol: c,
+            });
+            continue;
+        }
+        // Kind change.
+        if (b.kind !== c.kind) {
+            entries.push({
+                kind: 'kind-changed',
+                severity: kindChangeSeverity(b.kind, c.kind),
+                message: `kind change: ${describe(c)} was ${b.kind}, now ${c.kind}`,
+                symbol: c,
+                previous: b,
+            });
+        }
+        // Signature change (only when both surfaces carry signatures —
+        // typically when extracted via ts.Program with --with-signatures).
+        if (b.signature && c.signature && b.signature !== c.signature) {
+            entries.push({
+                kind: 'signature-changed',
+                severity: 'breaking',
+                message: `signature change: ${describe(c)}\n  was: ${b.signature}\n  now: ${c.signature}`,
+                symbol: c,
+                previous: b,
+            });
+        }
+        // File move within the same package (additive).
+        if (b.file !== c.file) {
+            entries.push({
+                kind: 'moved-file',
+                severity: 'additive',
+                message: `moved: ${describe(c)} from ${b.file} → ${c.file}`,
+                symbol: c,
+                previous: b,
+            });
+        }
+    }
+    // Cross-package moves (breaking): same name, different package.
+    // These appear as `removed` + `added` from the key-based match above.
+    // Reclassify them.
+    const byNameRemoved = new Map();
+    const byNameAdded = new Map();
+    for (const e of entries) {
+        if (e.kind === 'removed')
+            byNameRemoved.set(e.symbol.name, e.symbol);
+        if (e.kind === 'added')
+            byNameAdded.set(e.symbol.name, e.symbol);
+    }
+    const reclassified = [];
+    for (const e of entries) {
+        if (e.kind === 'removed') {
+            const counterpart = byNameAdded.get(e.symbol.name);
+            if (counterpart && counterpart.package !== e.symbol.package) {
+                reclassified.push({
+                    kind: 'moved-package',
+                    severity: 'breaking',
+                    message: `moved package: ${e.symbol.name} from ${e.symbol.package ?? '?'} → ${counterpart.package ?? '?'}`,
+                    symbol: counterpart,
+                    previous: e.symbol,
+                });
+                continue;
+            }
+        }
+        else if (e.kind === 'added') {
+            const counterpart = byNameRemoved.get(e.symbol.name);
+            if (counterpart && counterpart.package !== e.symbol.package) {
+                // Skip — already represented as moved-package via the removed side.
+                continue;
+            }
+        }
+        reclassified.push(e);
+    }
+    // Sort: breaking first, then additive, then info; tiebreak by name.
+    const severityRank = { breaking: 0, additive: 1, info: 2 };
+    reclassified.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] ||
+        a.symbol.name.localeCompare(b.symbol.name));
+    const added = reclassified.filter((e) => e.kind === 'added').length;
+    const removed = reclassified.filter((e) => e.kind === 'removed').length;
+    const changed = reclassified.length - added - removed;
+    const breakingCount = reclassified.filter((e) => e.severity === 'breaking').length;
+    return {
+        schema: API_SURFACE_DIFF_SCHEMA,
+        baselineTotal: baseline.total,
+        currentTotal: current.total,
+        added,
+        removed,
+        changed,
+        breakingCount,
+        entries: reclassified,
+    };
+}
+function keyOf(s) {
+    return `${s.package ?? ''}|${s.name}|${s.isDefault ? '1' : '0'}`;
+}
+function describe(s) {
+    return s.package ? `${s.package}#${s.name} (${s.kind})` : `${s.name} (${s.kind})`;
+}
+function kindChangeSeverity(from, to) {
+    // class ↔ function ↔ const are likely breaking; interface ↔ type-alias
+    // is usually additive (TS treats them interchangeably for most uses).
+    if (from === 'interface' && to === 'type-alias')
+        return 'additive';
+    if (from === 'type-alias' && to === 'interface')
+        return 'additive';
+    // Re-export wrappers can change kind details for cosmetic reasons.
+    if (from === 'unknown' || to === 'unknown')
+        return 'info';
+    return 'breaking';
+}

package/dist/engine/extract-surface-with-program.d.ts

@@ -0,0 +1,52 @@
+import { type IApiSurface } from '../schema/api-surface.js';
+export interface IExtractWithProgramOptions {
+    projectRoot: string;
+    /** Restrict to these workspace packages. */
+    packageFilter?: readonly string[];
+    /** Path to tsconfig (default: `tsconfig.base.json` then `tsconfig.json`). */
+    tsconfigPath?: string;
+    /**
+     * Cap on the wall-clock time the extractor will spend (ms). When
+     * exceeded, the extractor returns what it has so far + a diagnostic.
+     * Default 60 s.
+     */
+    timeBudgetMs?: number;
+    /**
+     * When true (default), reuse `.sharkcraft/api-surface/signatures.json`
+     * entries whose file SHA1 matches the current content. Saves a few
+     * hundred ms on incremental CI runs. Pass `false` to force a
+     * full rebuild (the cache is overwritten on the next save).
+     */
+    useCache?: boolean;
+}
+export interface IExtractWithProgramResult {
+    surface: IApiSurface;
+    diagnostics: readonly string[];
+    /** Number of source files visited by the type checker. */
+    filesVisited: number;
+    /** Wall-clock duration. */
+    durationMs: number;
+    /** Signature cache hit / miss / unchanged-file counts. */
+    cacheStats: {
+        enabled: boolean;
+        hits: number;
+        misses: number;
+        /** Files whose every exported symbol was a cache hit. */
+        filesReused: number;
+    };
+}
+/**
+ * Build a `ts.Program` for the project and harvest a public-API surface
+ * with **canonical signature strings** for each exported symbol. The
+ * signatures let the diff engine catch parameter-type / return-type /
+ * member-type changes that the AST-only extractor misses.
+ *
+ * Costs:
+ *   - ts.Program over a medium-sized repo: hundreds of ms to a few s.
+ *   - Memory: roughly proportional to total .ts size.
+ *
+ * Opt-in only — the AST-only `extractApiSurface(snap)` remains the
+ * default path. This extractor is what `--with-signatures` invokes.
+ */
+export declare function extractApiSurfaceWithProgram(options: IExtractWithProgramOptions): IExtractWithProgramResult;
+//# sourceMappingURL=extract-surface-with-program.d.ts.map

package/dist/engine/extract-surface-with-program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-surface-with-program.d.ts","sourceRoot":"","sources":["../../src/engine/extract-surface-with-program.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,EAAE;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,yDAAyD;QACzD,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CA8J3B"}

package/dist/engine/extract-surface-with-program.js

@@ -0,0 +1,456 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+import { emptyCache, fingerprintContent, loadSignatureCache, saveSignatureCache, symbolCacheKey, } from "../cache/signature-cache.js";
+import { API_SURFACE_SCHEMA, } from "../schema/api-surface.js";
+/**
+ * Build a `ts.Program` for the project and harvest a public-API surface
+ * with **canonical signature strings** for each exported symbol. The
+ * signatures let the diff engine catch parameter-type / return-type /
+ * member-type changes that the AST-only extractor misses.
+ *
+ * Costs:
+ *   - ts.Program over a medium-sized repo: hundreds of ms to a few s.
+ *   - Memory: roughly proportional to total .ts size.
+ *
+ * Opt-in only — the AST-only `extractApiSurface(snap)` remains the
+ * default path. This extractor is what `--with-signatures` invokes.
+ */
+export function extractApiSurfaceWithProgram(options) {
+    const start = Date.now();
+    const timeBudgetMs = options.timeBudgetMs ?? 60_000;
+    const diagnostics = [];
+    const tsconfigPath = resolveTsconfig(options.projectRoot, options.tsconfigPath);
+    if (!tsconfigPath) {
+        return emptyResult(start, options.projectRoot, diagnostics, 0, `no tsconfig found under ${options.projectRoot} (looked for tsconfig.base.json, tsconfig.json)`);
+    }
+    const program = buildProgram(tsconfigPath, options.projectRoot, diagnostics);
+    if (!program) {
+        return emptyResult(start, options.projectRoot, diagnostics, 0, `failed to build ts.Program from ${tsconfigPath}`);
+    }
+    const checker = program.getTypeChecker();
+    const fileToPackage = buildFileToPackageMap(options.projectRoot);
+    const filter = options.packageFilter && options.packageFilter.length > 0
+        ? new Set(options.packageFilter)
+        : undefined;
+    // Signature cache (file SHA1 → per-symbol signature) — load once,
+    // write back at the end. Cache disabled when `options.useCache === false`.
+    const cacheEnabled = options.useCache !== false;
+    const oldCache = cacheEnabled ? loadSignatureCache(options.projectRoot) : emptyCache();
+    const newCacheFiles = {};
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    let filesReused = 0;
+    const symbols = [];
+    let filesVisited = 0;
+    for (const sf of program.getSourceFiles()) {
+        if (sf.isDeclarationFile && !sf.fileName.includes(options.projectRoot))
+            continue;
+        if (sf.fileName.includes('/node_modules/'))
+            continue;
+        if (!sf.fileName.startsWith(options.projectRoot))
+            continue;
+        if (Date.now() - start > timeBudgetMs) {
+            diagnostics.push(`time budget exceeded after visiting ${filesVisited} files; surface is partial`);
+            break;
+        }
+        filesVisited += 1;
+        const relPath = nodePath
+            .relative(options.projectRoot, sf.fileName)
+            .split(nodePath.sep)
+            .join('/');
+        const pkg = lookupPackage(relPath, fileToPackage);
+        if (filter && (!pkg || !filter.has(pkg)))
+            continue;
+        // Compute the file SHA1 once and decide whether the cache is
+        // usable for this file. We still walk the module's exports below
+        // — the cache only short-circuits the per-symbol type checker
+        // call (the expensive part).
+        const fileSha = fingerprintContent(sf.getFullText());
+        const cachedEntry = cacheEnabled ? oldCache.files[relPath] : undefined;
+        const fileCacheUsable = !!cachedEntry && cachedEntry.sha1 === fileSha;
+        const fileNewSignatures = {};
+        let fileSymbolsCount = 0;
+        let fileHits = 0;
+        const moduleSymbol = checker.getSymbolAtLocation(sf);
+        if (!moduleSymbol)
+            continue;
+        const exported = checker.getExportsOfModule(moduleSymbol);
+        for (const sym of exported) {
+            // Skip module re-exports (we want declarations).
+            const decls = sym.getDeclarations() ?? [];
+            if (decls.length === 0)
+                continue;
+            const decl = decls[0];
+            const declSf = decl.getSourceFile();
+            if (declSf.fileName.includes('/node_modules/'))
+                continue;
+            const declRel = nodePath
+                .relative(options.projectRoot, declSf.fileName)
+                .split(nodePath.sep)
+                .join('/');
+            const declPkg = lookupPackage(declRel, fileToPackage);
+            if (filter && (!declPkg || !filter.has(declPkg)))
+                continue;
+            const name = sym.getName();
+            if (name === '__export')
+                continue; // synthetic, comes from `export * from`
+            const isDefault = name === 'default';
+            const kind = pickKind(decl);
+            const key = symbolCacheKey(name, isDefault);
+            let signature;
+            // Cache lookup is keyed by the file the symbol is *declared* in,
+            // not the file we're walking — they differ for re-exports.
+            const sameFile = declRel === relPath;
+            if (cacheEnabled && sameFile && fileCacheUsable && cachedEntry.signatures[key]) {
+                signature = cachedEntry.signatures[key];
+                cacheHits += 1;
+                fileHits += 1;
+            }
+            else {
+                signature = serializeSymbol(checker, sym, decl);
+                if (cacheEnabled)
+                    cacheMisses += 1;
+            }
+            if (signature && sameFile) {
+                fileNewSignatures[key] = signature;
+            }
+            fileSymbolsCount += 1;
+            symbols.push({
+                id: `symbol:${declRel}#${name}`,
+                name,
+                kind,
+                file: declRel,
+                ...(declPkg ? { package: declPkg } : {}),
+                isDefault,
+                ...(signature ? { signature } : {}),
+            });
+        }
+        if (cacheEnabled) {
+            newCacheFiles[relPath] = { sha1: fileSha, signatures: fileNewSignatures };
+            if (fileSymbolsCount > 0 && fileHits === fileSymbolsCount)
+                filesReused += 1;
+        }
+    }
+    // De-dupe by `id` — re-exports can surface the same declaration
+    // multiple times.
+    const seen = new Set();
+    const deduped = [];
+    for (const s of symbols) {
+        if (seen.has(s.id))
+            continue;
+        seen.add(s.id);
+        deduped.push(s);
+    }
+    deduped.sort((a, b) => a.id.localeCompare(b.id));
+    const counts = {};
+    for (const s of deduped) {
+        const key = s.package ?? '<no-package>';
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    const surface = {
+        schema: API_SURFACE_SCHEMA,
+        projectRoot: options.projectRoot,
+        ...(options.packageFilter && options.packageFilter.length > 0 ? { packageFilter: options.packageFilter } : {}),
+        symbols: deduped,
+        countsByPackage: counts,
+        total: deduped.length,
+    };
+    if (cacheEnabled) {
+        saveSignatureCache(options.projectRoot, {
+            schema: oldCache.schema,
+            generatedAt: oldCache.generatedAt, // overwritten by saveSignatureCache
+            files: newCacheFiles,
+        });
+    }
+    return {
+        surface,
+        diagnostics,
+        filesVisited,
+        durationMs: Date.now() - start,
+        cacheStats: {
+            enabled: cacheEnabled,
+            hits: cacheHits,
+            misses: cacheMisses,
+            filesReused,
+        },
+    };
+}
+function resolveTsconfig(projectRoot, explicit) {
+    if (explicit) {
+        const abs = nodePath.isAbsolute(explicit) ? explicit : nodePath.resolve(projectRoot, explicit);
+        return existsSync(abs) ? abs : undefined;
+    }
+    for (const name of ['tsconfig.base.json', 'tsconfig.json']) {
+        const cand = nodePath.join(projectRoot, name);
+        if (existsSync(cand))
+            return cand;
+    }
+    return undefined;
+}
+function buildProgram(tsconfigPath, projectRoot, diagnostics) {
+    const raw = ts.readConfigFile(tsconfigPath, (p) => readFileSync(p, 'utf8'));
+    if (raw.error) {
+        diagnostics.push(`tsconfig read error: ${ts.flattenDiagnosticMessageText(raw.error.messageText, '\n')}`);
+        return undefined;
+    }
+    const parsed = ts.parseJsonConfigFileContent(raw.config, ts.sys, nodePath.dirname(tsconfigPath));
+    for (const d of parsed.errors) {
+        diagnostics.push(`tsconfig parse: ${ts.flattenDiagnosticMessageText(d.messageText, '\n')}`);
+    }
+    // Add the workspace's own source roots in case tsconfig.base.json
+    // doesn't list them (the SharkCraft monorepo's tsconfig.base.json
+    // uses `include: ['packages/*/src/**/*.ts']` already).
+    return ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: {
+            ...parsed.options,
+            // Forcibly disable emit / type errors that don't matter for symbol
+            // discovery.
+            noEmit: true,
+            skipLibCheck: true,
+        },
+    });
+}
+function pickKind(decl) {
+    if (ts.isClassDeclaration(decl))
+        return 'class';
+    if (ts.isFunctionDeclaration(decl))
+        return 'function';
+    if (ts.isInterfaceDeclaration(decl))
+        return 'interface';
+    if (ts.isTypeAliasDeclaration(decl))
+        return 'type-alias';
+    if (ts.isEnumDeclaration(decl))
+        return 'enum';
+    if (ts.isVariableDeclaration(decl)) {
+        const list = decl.parent;
+        if (list && list.flags & ts.NodeFlags.Const)
+            return 'const';
+        if (list && list.flags & ts.NodeFlags.Let)
+            return 'let';
+        return 'var';
+    }
+    if (ts.isModuleDeclaration(decl)) {
+        if (decl.flags & ts.NodeFlags.Namespace)
+            return 'namespace';
+        return 'module';
+    }
+    return 'unknown';
+}
+const TYPE_FORMAT_FLAGS = ts.TypeFormatFlags.NoTruncation |
+    ts.TypeFormatFlags.WriteArrayAsGenericType |
+    ts.TypeFormatFlags.UseStructuralFallback |
+    ts.TypeFormatFlags.InTypeAlias;
+function serializeSymbol(checker, sym, decl) {
+    try {
+        const allDecls = sym.getDeclarations() ?? [decl];
+        const typeParamNames = extractTypeParameterNames(allDecls);
+        // Type-shape symbols (interface / type alias / class) need
+        // structural serialization — `typeToString` would just print the
+        // symbol's own name (`IUser`) and miss member changes. Walk the
+        // properties explicitly so two interfaces with different member
+        // lists serialize to different strings.
+        if (sym.flags & (ts.SymbolFlags.Interface | ts.SymbolFlags.Class)) {
+            return normalizeGenerics(serializeStructuralType(checker, sym, decl), typeParamNames);
+        }
+        if (sym.flags & ts.SymbolFlags.Enum) {
+            return serializeEnum(checker, sym);
+        }
+        if (sym.flags & ts.SymbolFlags.TypeAlias) {
+            const type = checker.getDeclaredTypeOfSymbol(sym);
+            // For type aliases, typeToString *does* expand most shapes — but
+            // when the alias resolves to another named type the result is
+            // just the name. Fall back to structural for object types.
+            if (type.flags & ts.TypeFlags.Object) {
+                return normalizeGenerics(canonicalizeSignature(formatObjectType(checker, type, decl)), typeParamNames);
+            }
+            return normalizeGenerics(canonicalizeSignature(checker.typeToString(type, decl, TYPE_FORMAT_FLAGS)), typeParamNames);
+        }
+        // Value symbols (function / const / let / var): serialize the
+        // expression / call-signature type.
+        const type = checker.getTypeOfSymbolAtLocation(sym, decl);
+        const text = checker.typeToString(type, decl, TYPE_FORMAT_FLAGS);
+        return normalizeGenerics(canonicalizeSignature(text), typeParamNames);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Collect type-parameter names from a symbol's declarations, in
+ * declaration order. Used to substitute `T`/`U`/etc. with positional
+ * placeholders so rename-only refactors don't read as breaking changes
+ * in the diff.
+ *
+ * Only top-level type parameters on the declaration itself are
+ * captured; nested generic closures keep their original names (we
+ * don't have a stable positional identity for them at the symbol
+ * level).
+ */
+function extractTypeParameterNames(decls) {
+    for (const decl of decls) {
+        const tp = decl.typeParameters;
+        if (tp && tp.length > 0) {
+            const names = [];
+            for (const t of tp) {
+                if (ts.isIdentifier(t.name))
+                    names.push(t.name.text);
+            }
+            if (names.length > 0)
+                return names;
+        }
+    }
+    return [];
+}
+function normalizeGenerics(serialized, paramNames) {
+    if (paramNames.length === 0)
+        return serialized;
+    // Substitute in two passes so a rename like `T → U` doesn't collide
+    // when an output placeholder happens to match another input name.
+    // First pass: rename each input to a unique placeholder using a
+    // marker prefix that can't appear in legitimate identifiers.
+    let out = serialized;
+    for (let i = 0; i < paramNames.length; i += 1) {
+        const re = new RegExp('\\b' + escapeRegExp(paramNames[i]) + '\\b', 'g');
+        out = out.replace(re, `
P${i}
`);
+    }
+    // Second pass: turn the markers into stable, human-readable
+    // placeholders.
+    out = out.replace(/
P(\d+)
/g, '__P$1');
+    return out;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function serializeStructuralType(checker, sym, decl) {
+    const type = checker.getDeclaredTypeOfSymbol(sym);
+    return canonicalizeSignature(formatObjectType(checker, type, decl));
+}
+function formatObjectType(checker, type, locus) {
+    const props = checker.getPropertiesOfType(type);
+    const memberStrs = [];
+    for (const prop of props) {
+        const propDecl = prop.getDeclarations()?.[0] ?? locus;
+        const propType = checker.getTypeOfSymbolAtLocation(prop, propDecl);
+        const optional = (prop.flags & ts.SymbolFlags.Optional) !== 0 ? '?' : '';
+        memberStrs.push(`${prop.getName()}${optional}: ${checker.typeToString(propType, propDecl, TYPE_FORMAT_FLAGS)}`);
+    }
+    // Call signatures (function-shaped object types).
+    for (const sig of checker.getSignaturesOfType(type, ts.SignatureKind.Call)) {
+        memberStrs.push(`(call): ${checker.signatureToString(sig, locus)}`);
+    }
+    // Construct signatures (classes / interfaces with new(...)).
+    for (const sig of checker.getSignaturesOfType(type, ts.SignatureKind.Construct)) {
+        memberStrs.push(`(new): ${checker.signatureToString(sig, locus)}`);
+    }
+    memberStrs.sort();
+    return `{ ${memberStrs.join('; ')} }`;
+}
+function serializeEnum(checker, sym) {
+    const decls = sym.getDeclarations() ?? [];
+    const members = [];
+    for (const decl of decls) {
+        if (!ts.isEnumDeclaration(decl))
+            continue;
+        for (const member of decl.members) {
+            if (ts.isIdentifier(member.name)) {
+                members.push(member.name.text);
+            }
+            else if (ts.isStringLiteral(member.name)) {
+                members.push(`'${member.name.text}'`);
+            }
+        }
+    }
+    members.sort();
+    return canonicalizeSignature(`enum { ${members.join(', ')} }`);
+    // (Silence unused-import warning if checker isn't referenced.)
+    void checker;
+}
+/**
+ * Normalize whitespace so two semantically-equivalent signatures
+ * compare equal across tsserver / compiler version drift.
+ */
+function canonicalizeSignature(s) {
+    return s.replace(/\s+/g, ' ').replace(/\s*([,;:<>(){}|&=])\s*/g, '$1').trim();
+}
+function buildFileToPackageMap(projectRoot) {
+    const out = new Map();
+    try {
+        const pkgJson = nodePath.join(projectRoot, 'package.json');
+        const root = existsSync(pkgJson) ? JSON.parse(readFileSync(pkgJson, 'utf8')) : {};
+        const patterns = normalizeWorkspaces(root.workspaces);
+        for (const pattern of patterns) {
+            const dir = pattern.replace(/\/\*?$/, '');
+            const full = nodePath.join(projectRoot, dir);
+            if (!existsSync(full))
+                continue;
+            let children;
+            try {
+                children = readdirSync(full);
+            }
+            catch {
+                continue;
+            }
+            for (const child of children) {
+                const inner = nodePath.join(full, child);
+                const childPkg = nodePath.join(inner, 'package.json');
+                if (!existsSync(childPkg))
+                    continue;
+                try {
+                    const pj = JSON.parse(readFileSync(childPkg, 'utf8'));
+                    if (pj.name) {
+                        const rel = nodePath.relative(projectRoot, inner).split(nodePath.sep).join('/');
+                        out.set(rel, pj.name);
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return out;
+}
+function lookupPackage(relPath, fileToPackage) {
+    // Walk path prefixes; pick the longest match.
+    const parts = relPath.split('/');
+    for (let i = parts.length - 1; i > 0; i -= 1) {
+        const prefix = parts.slice(0, i).join('/');
+        const hit = fileToPackage.get(prefix);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function normalizeWorkspaces(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (typeof value === 'object') {
+        const packages = value.packages;
+        if (Array.isArray(packages))
+            return packages.filter((v) => typeof v === 'string');
+    }
+    return [];
+}
+function emptyResult(start, projectRoot, diagnostics, filesVisited, message) {
+    diagnostics.push(message);
+    return {
+        surface: {
+            schema: API_SURFACE_SCHEMA,
+            projectRoot,
+            symbols: [],
+            countsByPackage: {},
+            total: 0,
+        },
+        diagnostics,
+        filesVisited,
+        durationMs: Date.now() - start,
+        cacheStats: { enabled: false, hits: 0, misses: 0, filesReused: 0 },
+    };
+}

package/dist/engine/extract-surface.d.ts

@@ -0,0 +1,18 @@
+import { type IGraphSnapshot } from '@shrkcrft/graph';
+import { type IApiSurface } from '../schema/api-surface.js';
+export interface IExtractSurfaceOptions {
+    /** Restrict surface to these package names. */
+    packageFilter?: readonly string[];
+    /** Include only declared symbols (excludes re-exports). Default true. */
+    includeDeclaredOnly?: boolean;
+}
+/**
+ * Walk a graph snapshot and produce a deterministic `IApiSurface`.
+ *
+ * A "public" symbol is any `symbol:` node whose `data.isExported`
+ * is true. The owning file (and its owning package) are resolved via
+ * the symbol node id (`symbol:<filePath>#<name>`) and the file's
+ * BelongsToPackage edge.
+ */
+export declare function extractApiSurface(snap: IGraphSnapshot, options?: IExtractSurfaceOptions): IApiSurface;
+//# sourceMappingURL=extract-surface.d.ts.map

package/dist/engine/extract-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-surface.d.ts","sourceRoot":"","sources":["../../src/engine/extract-surface.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,sBAA2B,GACnC,WAAW,CAkDb"}

package/dist/engine/extract-surface.js

@@ -0,0 +1,65 @@
+import { EdgeKind, NodeKind, } from '@shrkcrft/graph';
+import { API_SURFACE_SCHEMA, } from "../schema/api-surface.js";
+/**
+ * Walk a graph snapshot and produce a deterministic `IApiSurface`.
+ *
+ * A "public" symbol is any `symbol:` node whose `data.isExported`
+ * is true. The owning file (and its owning package) are resolved via
+ * the symbol node id (`symbol:<filePath>#<name>`) and the file's
+ * BelongsToPackage edge.
+ */
+export function extractApiSurface(snap, options = {}) {
+    const filter = options.packageFilter && options.packageFilter.length > 0
+        ? new Set(options.packageFilter)
+        : undefined;
+    // Build file → package map from BelongsToPackage edges.
+    const fileToPackage = new Map();
+    for (const e of snap.edges.values()) {
+        if (e.kind !== EdgeKind.BelongsToPackage)
+            continue;
+        const fileId = e.from;
+        const pkgId = e.to;
+        if (!fileId.startsWith('file:') || !pkgId.startsWith('package:'))
+            continue;
+        fileToPackage.set(fileId, pkgId.slice('package:'.length));
+    }
+    const symbols = [];
+    for (const node of snap.nodes.values()) {
+        if (node.kind !== NodeKind.Symbol)
+            continue;
+        const exported = (node.data?.['isExported'] ?? false) === true;
+        if (!exported)
+            continue;
+        const file = node.path;
+        if (!file)
+            continue;
+        const fileId = `file:${file}`;
+        const pkg = fileToPackage.get(fileId);
+        if (filter && (!pkg || !filter.has(pkg)))
+            continue;
+        const visibility = node.data?.['visibility'] ?? '';
+        const isDefault = visibility === 'default';
+        symbols.push({
+            id: node.id,
+            name: node.label,
+            kind: (node.data?.['declKind'] ?? 'unknown'),
+            file,
+            ...(pkg ? { package: pkg } : {}),
+            isDefault,
+        });
+    }
+    symbols.sort((a, b) => a.id.localeCompare(b.id));
+    const counts = {};
+    for (const s of symbols) {
+        const key = s.package ?? '<no-package>';
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return {
+        schema: API_SURFACE_SCHEMA,
+        projectRoot: snap.manifest.projectRoot,
+        ...(options.packageFilter && options.packageFilter.length > 0 ? { packageFilter: options.packageFilter } : {}),
+        symbols,
+        countsByPackage: counts,
+        total: symbols.length,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './schema/api-surface.js';
+export * from './engine/extract-surface.js';
+export * from './engine/extract-surface-with-program.js';
+export * from './engine/diff-surfaces.js';
+export * from './cache/signature-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0CAA0C,CAAC;AACzD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./schema/api-surface.js";
+export * from "./engine/extract-surface.js";
+export * from "./engine/extract-surface-with-program.js";
+export * from "./engine/diff-surfaces.js";
+export * from "./cache/signature-cache.js";

package/dist/schema/api-surface.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Public-API surface snapshot for a workspace package or the whole
+ * repo. Produced from a `@shrkcrft/graph` snapshot; consumed by the
+ * diff engine to detect breaking changes.
+ */
+export declare const API_SURFACE_SCHEMA: "sharkcraft.api-surface/v1";
+export declare const API_SURFACE_DIFF_SCHEMA: "sharkcraft.api-surface-diff/v1";
+export type ApiSymbolKind = 'class' | 'function' | 'interface' | 'type-alias' | 'enum' | 'const' | 'let' | 'var' | 'module' | 'namespace' | 'unknown';
+export interface IPublicSymbol {
+    /** Symbol node id (e.g. `symbol:packages/foo/src/index.ts#myFn`). */
+    id: string;
+    /** Symbol name as exposed by the file. */
+    name: string;
+    /** Declaration kind. */
+    kind: ApiSymbolKind;
+    /** File where the symbol is declared. */
+    file: string;
+    /** Workspace package name (if known). */
+    package?: string;
+    /** True for default exports. */
+    isDefault: boolean;
+    /**
+     * Canonical signature string from the TS type checker, when
+     * extracted via `extractApiSurfaceWithProgram`. Absent for surfaces
+     * captured from the AST-only graph snapshot.
+     */
+    signature?: string;
+}
+export interface IApiSurface {
+    schema: typeof API_SURFACE_SCHEMA;
+    /** Top-level project root (POSIX-normalised) when known. */
+    projectRoot?: string;
+    /** When set, only entries under one of these packages are included. */
+    packageFilter?: readonly string[];
+    /** Symbols sorted by id ascending. */
+    symbols: readonly IPublicSymbol[];
+    /** Per-package summary counts. */
+    countsByPackage: Readonly<Record<string, number>>;
+    /** Total symbol count. */
+    total: number;
+}
+/**
+ * Severity of a single diff entry.
+ *
+ *   - `breaking`: a public symbol was removed, OR its kind changed in a
+ *     way that breaks consumer code (e.g. class → function).
+ *   - `additive`: a new symbol was added, OR a non-breaking detail
+ *     changed (e.g. moved file within the same package).
+ *   - `info`: cosmetic / structural change only.
+ */
+export type DiffSeverity = 'breaking' | 'additive' | 'info';
+export type DiffChangeKind = 'added' | 'removed' | 'kind-changed' | 'moved-file' | 'moved-package' | 'signature-changed';
+export interface IApiSymbolDiff {
+    kind: DiffChangeKind;
+    severity: DiffSeverity;
+    /** Stable, human-readable summary. */
+    message: string;
+    symbol: IPublicSymbol;
+    /** Old version of the symbol for changed entries. */
+    previous?: IPublicSymbol;
+}
+export interface IApiSurfaceDiff {
+    schema: typeof API_SURFACE_DIFF_SCHEMA;
+    baselineTotal: number;
+    currentTotal: number;
+    added: number;
+    removed: number;
+    changed: number;
+    /** Total breaking-severity entries. */
+    breakingCount: number;
+    /** Diff entries, sorted: breaking → additive → info. */
+    entries: readonly IApiSymbolDiff[];
+}
+//# sourceMappingURL=api-surface.d.ts.map

package/dist/schema/api-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-surface.d.ts","sourceRoot":"","sources":["../../src/schema/api-surface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAG,2BAAoC,CAAC;AACvE,eAAO,MAAM,uBAAuB,EAAG,gCAAyC,CAAC;AAEjF,MAAM,MAAM,aAAa,GACrB,OAAO,GACP,UAAU,GACV,WAAW,GACX,YAAY,GACZ,MAAM,GACN,OAAO,GACP,KAAK,GACL,KAAK,GACL,QAAQ,GACR,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sCAAsC;IACtC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,kCAAkC;IAClC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5D,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,SAAS,GACT,cAAc,GACd,YAAY,GACZ,eAAe,GACf,mBAAmB,CAAC;AAExB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC;IACvB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC"}

package/dist/schema/api-surface.js

@@ -0,0 +1,7 @@
+/**
+ * Public-API surface snapshot for a workspace package or the whole
+ * repo. Produced from a `@shrkcrft/graph` snapshot; consumed by the
+ * diff engine to detect breaking changes.
+ */
+export const API_SURFACE_SCHEMA = 'sharkcraft.api-surface/v1';
+export const API_SURFACE_DIFF_SCHEMA = 'sharkcraft.api-surface-diff/v1';

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@shrkcrft/api-surface-diff",
+  "version": "0.1.0-alpha.10",
+  "description": "SharkCraft API surface diff: compare two code-graph snapshots and report added / removed / changed public symbols. Catches accidental API breaks before publish.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/api-surface-diff"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "api-surface",
+    "diff",
+    "code-intelligence",
+    "breaking-change"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.10",
+    "@shrkcrft/graph": "^0.1.0-alpha.10",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}