sigdiff 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# sigdiff
+
+Diffs the public API surface of a TypeScript project between two git refs and outputs a structured changelog.
+
+```bash
+npx sigdiff v1.0.0..v2.0.0
+```
+
+## Why
+
+Commit messages are a human interpretation of a change — imprecise, incomplete, or missing entirely. `sigdiff` adds a second perspective: what the code actually exported. It catches things commit messages miss, like a signature change buried in a large PR.
+
+## Usage
+
+```bash
+# Compare last tag to HEAD
+npx sigdiff
+
+# Compare two refs
+npx sigdiff v1.0.0..v2.0.0
+
+# Scope to a specific entrypoint
+npx sigdiff --entrypoint src/index.ts
+
+# JSON output
+npx sigdiff --json
+```
+
+## What it detects
+
+Functions, arrow functions, interfaces, type aliases, enums, classes, and constants — parameters, return types, property shapes, and member names.
+
+Changes are classified as `major`, `minor`, or `patch` per semver rules.
+
+## Example output
+
+```
+### Breaking Changes
+
+- Removed function `fetchLegacyData`
+- `createUser` signature changed: `(name: string, email: string)` → `(opts: CreateUserOpts)`
+
+### New
+
+- Added function `updateUser`
+- Added interface `CreateUserOpts`
+
+Suggested version bump: major
+```
+
+## Programmatic API
+
+```typescript
+import { extract, diff, classify, buildResult, format } from 'sigdiff';
+
+const before = extract(['src/v1/index.ts']);
+const after = extract(['src/v2/index.ts']);
+
+console.log(format(buildResult(classify(diff(before, after)))));
+```
+
+## Notes
+
+- TypeScript only — no JS support (no type info to diff)
+- Single-package projects only — no monorepo support yet
+- Read-only — never touches your working tree
+- 1 runtime dependency ([`cac`](https://github.com/cacjs/cac))
+
+## License
+
+MIT

package/dist/classify.d.ts

@@ -0,0 +1,2 @@
+import { Change, ClassifiedChange } from './types';
+export declare function classify(changes: Change[]): ClassifiedChange[];

package/dist/classify.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = classify;
+function classify(changes) {
+    return changes.map(classifyOne);
+}
+function classifyOne(change) {
+    switch (change.type) {
+        case 'removed':
+            return {
+                change,
+                level: 'major',
+                description: `Removed ${change.symbol.kind} \`${change.symbol.name}\``
+            };
+        case 'added':
+            return {
+                change,
+                level: 'minor',
+                description: `Added ${change.symbol.kind} \`${change.symbol.name}\``
+            };
+        case 'modified':
+            return {
+                change,
+                level: classifyModification(change),
+                description: buildModificationDescription(change)
+            };
+    }
+}
+function classifyModification(change) {
+    const { before, after } = change;
+    if (before.kind !== after.kind)
+        return 'major';
+    if (before.kind === 'function') {
+        return classifyFunctionChange(before.signature, after.signature);
+    }
+    if (before.kind === 'interface' || before.kind === 'type-alias' || before.kind === 'class') {
+        return classifyStructuralChange(before.signature, after.signature);
+    }
+    return 'major';
+}
+function classifyFunctionChange(beforeSig, afterSig) {
+    const beforeParams = extractParamsFromSignature(beforeSig);
+    const afterParams = extractParamsFromSignature(afterSig);
+    const beforeReturn = extractReturnFromSignature(beforeSig);
+    const afterReturn = extractReturnFromSignature(afterSig);
+    if (beforeReturn === afterReturn &&
+        afterParams.startsWith(beforeParams) &&
+        isOnlyOptionalParamsAdded(beforeParams, afterParams)) {
+        return 'minor';
+    }
+    return 'major';
+}
+function classifyStructuralChange(beforeSig, afterSig) {
+    const beforeProps = extractPropsFromSignature(beforeSig);
+    const afterProps = extractPropsFromSignature(afterSig);
+    const beforeSet = new Set(beforeProps);
+    const afterSet = new Set(afterProps);
+    for (const prop of beforeProps) {
+        if (!afterSet.has(prop))
+            return 'major';
+    }
+    let hasAdditions = false;
+    for (const prop of afterProps) {
+        if (!beforeSet.has(prop)) {
+            hasAdditions = true;
+            if (!prop.includes('?:'))
+                return 'major';
+        }
+    }
+    return hasAdditions ? 'minor' : 'patch';
+}
+function buildModificationDescription(change) {
+    const { before, after } = change;
+    if (before.kind !== after.kind) {
+        return `\`${before.name}\` changed from ${before.kind} to ${after.kind}`;
+    }
+    return `\`${before.name}\` signature changed: \`${before.signature}\` -> \`${after.signature}\``;
+}
+function extractParamsFromSignature(sig) {
+    const start = sig.indexOf('(');
+    if (start === -1)
+        return '';
+    const end = findMatchingParen(sig, start);
+    return sig.slice(start + 1, end);
+}
+function extractReturnFromSignature(sig) {
+    const start = sig.indexOf('(');
+    if (start === -1)
+        return '';
+    const end = findMatchingParen(sig, start);
+    const afterParen = sig.slice(end + 1);
+    const match = afterParen.match(/^:\s*(.+)$/);
+    return match ? match[1].trim() : '';
+}
+function findMatchingParen(str, openIndex) {
+    let depth = 0;
+    for (let i = openIndex; i < str.length; i++) {
+        if (str[i] === '(')
+            depth++;
+        else if (str[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return str.length;
+}
+function isOnlyOptionalParamsAdded(beforeParams, afterParams) {
+    const added = afterParams.slice(beforeParams.length).trim();
+    if (!added)
+        return true;
+    const parts = added
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return parts.every((p) => p.includes('?'));
+}
+function extractPropsFromSignature(sig) {
+    const match = sig.match(/\{([^}]*)\}/);
+    if (!match)
+        return [];
+    return match[1]
+        .split(/[;,]/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const cac_1 = __importDefault(require("cac"));
+const errors_1 = require("./errors");
+const git_1 = require("./git");
+const diff_1 = require("./diff");
+const classify_1 = require("./classify");
+const format_1 = require("./format");
+const cli = (0, cac_1.default)('sigdiff');
+cli
+    .command('[range]', 'Diff the public API surface between two git refs')
+    .option('--entrypoint <path>', 'Scope to a specific file')
+    .option('--json', 'Output as JSON instead of markdown')
+    .action((range, options) => {
+    try {
+        (0, git_1.assertGitRepo)();
+        const refs = (0, git_1.resolveRefs)(range);
+        const before = (0, git_1.extractAtRef)(refs.before, options.entrypoint);
+        const after = (0, git_1.extractAtRef)(refs.after, options.entrypoint);
+        const changes = (0, diff_1.diff)(before, after);
+        const classified = (0, classify_1.classify)(changes);
+        const result = (0, format_1.buildResult)(classified);
+        const output = (0, format_1.format)(result, { json: options.json });
+        process.stdout.write(output);
+    }
+    catch (err) {
+        if (err instanceof errors_1.AstlogException) {
+            process.stderr.write(`Error: ${err.error.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+});
+cli.help();
+cli.version('0.1.0');
+cli.parse();

package/dist/diff.d.ts

@@ -0,0 +1,2 @@
+import { ApiSurface, Change } from './types';
+export declare function diff(before: ApiSurface, after: ApiSurface): Change[];

package/dist/diff.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diff = diff;
+function diff(before, after) {
+    const changes = [];
+    for (const [key, symbol] of before.symbols) {
+        if (!after.symbols.has(key)) {
+            changes.push({ type: 'removed', symbol });
+        }
+    }
+    for (const [key, symbol] of after.symbols) {
+        if (!before.symbols.has(key)) {
+            changes.push({ type: 'added', symbol });
+        }
+    }
+    for (const [key, afterSymbol] of after.symbols) {
+        const beforeSymbol = before.symbols.get(key);
+        if (beforeSymbol && beforeSymbol.signature !== afterSymbol.signature) {
+            changes.push({ type: 'modified', before: beforeSymbol, after: afterSymbol });
+        }
+    }
+    return changes;
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+export type AstlogError = {
+    code: 'INVALID_REF';
+    message: string;
+} | {
+    code: 'NO_TAGS';
+    message: string;
+} | {
+    code: 'NO_TYPESCRIPT';
+    message: string;
+} | {
+    code: 'PARSE_ERROR';
+    message: string;
+} | {
+    code: 'NOT_GIT_REPO';
+    message: string;
+};
+export declare class AstlogException extends Error {
+    readonly error: AstlogError;
+    constructor(error: AstlogError);
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AstlogException = void 0;
+class AstlogException extends Error {
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+        this.name = 'AstlogException';
+    }
+}
+exports.AstlogException = AstlogException;

package/dist/extract.d.ts

@@ -0,0 +1,3 @@
+import * as ts from 'typescript';
+import { ApiSurface } from './types';
+export declare function extract(fileNames: string[], compilerOptions?: ts.CompilerOptions): ApiSurface;

package/dist/extract.js

@@ -0,0 +1,210 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extract = extract;
+const path = __importStar(require("path"));
+const ts = __importStar(require("typescript"));
+function extract(fileNames, compilerOptions) {
+    const options = compilerOptions ?? {
+        target: ts.ScriptTarget.ES2020,
+        module: ts.ModuleKind.CommonJS,
+        strict: true,
+        skipLibCheck: true
+    };
+    const program = ts.createProgram(fileNames, options);
+    const checker = program.getTypeChecker();
+    const symbols = new Map();
+    for (const fileName of fileNames) {
+        const sourceFile = program.getSourceFile(fileName);
+        if (!sourceFile)
+            continue;
+        const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+        if (!moduleSymbol)
+            continue;
+        const relativePath = path.relative(process.cwd(), fileName);
+        const exports = checker.getExportsOfModule(moduleSymbol);
+        for (const exp of exports) {
+            const extracted = extractSymbol(exp, relativePath, checker);
+            if (extracted) {
+                const key = `${extracted.filePath}:${extracted.name}`;
+                symbols.set(key, extracted);
+            }
+        }
+    }
+    return { symbols };
+}
+function extractSymbol(symbol, filePath, checker) {
+    const declarations = symbol.getDeclarations();
+    if (!declarations || declarations.length === 0)
+        return null;
+    const decl = declarations[0];
+    const name = symbol.getName();
+    const kind = getSymbolKind(decl, checker);
+    if (!kind)
+        return null;
+    const rawSignature = buildSignature(name, kind, decl, checker);
+    const signature = normalizeSignature(rawSignature);
+    return { name, kind, signature, filePath };
+}
+function getSymbolKind(decl, checker) {
+    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.isClassDeclaration(decl))
+        return 'class';
+    if (ts.isVariableDeclaration(decl)) {
+        const type = checker.getTypeAtLocation(decl);
+        if (type.getCallSignatures().length > 0)
+            return 'function';
+        return 'constant';
+    }
+    return null;
+}
+function buildSignature(name, kind, decl, checker) {
+    switch (kind) {
+        case 'function':
+            if (ts.isFunctionDeclaration(decl)) {
+                return buildFunctionSignature(name, decl, checker);
+            }
+            return buildArrowFunctionSignature(name, decl, checker);
+        case 'interface':
+            return buildInterfaceSignature(name, decl, checker);
+        case 'type-alias':
+            return buildTypeAliasSignature(name, decl, checker);
+        case 'enum':
+            return buildEnumSignature(name, decl);
+        case 'class':
+            return buildClassSignature(name, decl, checker);
+        case 'constant':
+            return buildConstantSignature(name, decl, checker);
+    }
+}
+function buildFunctionSignature(name, decl, checker) {
+    const params = formatParams(decl.parameters, checker);
+    const returnType = inferReturnType(decl, checker);
+    return `function ${name}(${params}): ${returnType}`;
+}
+function buildInterfaceSignature(name, decl, checker) {
+    const props = formatMembers(decl.members, checker);
+    return `interface ${name} { ${props} }`;
+}
+function buildTypeAliasSignature(name, decl, checker) {
+    const type = checker.getTypeAtLocation(decl);
+    const typeStr = checker.typeToString(type, decl, ts.TypeFormatFlags.NoTruncation);
+    return `type ${name} = ${typeStr}`;
+}
+function buildEnumSignature(name, decl) {
+    const members = decl.members.map((m) => ts.isIdentifier(m.name) ? m.name.text : m.name.getText());
+    return `enum ${name} { ${members.join(', ')} }`;
+}
+function buildClassSignature(name, decl, checker) {
+    const props = formatMembers(decl.members, checker);
+    return `class ${name} { ${props} }`;
+}
+function buildArrowFunctionSignature(name, decl, checker) {
+    const type = checker.getTypeAtLocation(decl);
+    const sig = type.getCallSignatures()[0];
+    if (!sig)
+        return `function ${name}(): void`;
+    const params = sig
+        .getParameters()
+        .map((p) => {
+        const paramType = checker.getTypeOfSymbolAtLocation(p, decl);
+        const optional = p.flags & ts.SymbolFlags.Optional ? '?' : '';
+        return `${p.getName()}${optional}: ${checker.typeToString(paramType)}`;
+    })
+        .join(', ');
+    const returnType = checker.typeToString(checker.getReturnTypeOfSignature(sig));
+    return `function ${name}(${params}): ${returnType}`;
+}
+function buildConstantSignature(name, decl, checker) {
+    const type = checker.getTypeAtLocation(decl);
+    return `const ${name}: ${checker.typeToString(type)}`;
+}
+function formatParams(parameters, checker) {
+    return parameters
+        .map((param) => {
+        const name = param.name.getText();
+        const type = checker.typeToString(checker.getTypeAtLocation(param));
+        const optional = param.questionToken || param.initializer ? '?' : '';
+        return `${name}${optional}: ${type}`;
+    })
+        .join(', ');
+}
+function formatMembers(members, checker) {
+    const parts = [];
+    for (const member of members) {
+        if (ts.isPropertySignature(member) || ts.isPropertyDeclaration(member)) {
+            const name = member.name?.getText() ?? '';
+            let type = checker.typeToString(checker.getTypeAtLocation(member));
+            const optional = member.questionToken ? '?' : '';
+            if (optional && type.endsWith(' | undefined')) {
+                type = type.slice(0, -' | undefined'.length);
+            }
+            parts.push(`${name}${optional}: ${type}`);
+        }
+        else if (ts.isMethodSignature(member) || ts.isMethodDeclaration(member)) {
+            const name = member.name?.getText() ?? '';
+            const sig = checker.getSignatureFromDeclaration(member);
+            const type = sig ? checker.signatureToString(sig) : '(...args: any[]) => any';
+            parts.push(`${name}: ${type}`);
+        }
+    }
+    return parts.join(', ');
+}
+function inferReturnType(decl, checker) {
+    const sig = checker.getSignatureFromDeclaration(decl);
+    if (!sig)
+        return 'void';
+    return checker.typeToString(checker.getReturnTypeOfSignature(sig));
+}
+/**
+ * Normalize signatures to prevent false positives from cosmetic differences
+ * between TS versions or source formatting (whitespace, semicolons, index signatures).
+ */
+function normalizeSignature(sig) {
+    let result = sig;
+    result = result.replace(/\s+/g, ' ');
+    result = result.replace(/;\s*}/g, ' }');
+    result = result.replace(/;\s+(?=\w)/g, ', ');
+    result = result.replace(/\{\s*\[\w+:\s*string\]:\s*([^}]+)\}/g, (_, valueType) => `Record<string, ${valueType.trim()}>`);
+    result = result.replace(/\s+/g, ' ').trim();
+    return result;
+}

package/dist/format.d.ts

@@ -0,0 +1,5 @@
+import { ChangelogResult, ClassifiedChange } from './types';
+export declare function buildResult(classified: ClassifiedChange[]): ChangelogResult;
+export declare function format(result: ChangelogResult, options?: {
+    json?: boolean;
+}): string;

package/dist/format.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildResult = buildResult;
+exports.format = format;
+function buildResult(classified) {
+    const breaking = [];
+    const features = [];
+    const fixes = [];
+    for (const c of classified) {
+        switch (c.level) {
+            case 'major':
+                breaking.push(c);
+                break;
+            case 'minor':
+                features.push(c);
+                break;
+            case 'patch':
+                fixes.push(c);
+                break;
+        }
+    }
+    let suggestedBump = 'patch';
+    if (breaking.length > 0)
+        suggestedBump = 'major';
+    else if (features.length > 0)
+        suggestedBump = 'minor';
+    return { breaking, features, fixes, suggestedBump };
+}
+function format(result, options) {
+    if (options?.json) {
+        return JSON.stringify(result, null, 2);
+    }
+    return formatMarkdown(result);
+}
+const MAX_SIGNATURE_LENGTH = 120;
+function truncateSignature(sig) {
+    if (sig.length <= MAX_SIGNATURE_LENGTH)
+        return sig;
+    return sig.slice(0, MAX_SIGNATURE_LENGTH) + '...';
+}
+function deduplicateDescriptions(changes) {
+    const seen = new Set();
+    const descriptions = [];
+    for (const c of changes) {
+        const name = getChangeName(c);
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        descriptions.push(truncateDescription(c));
+    }
+    return descriptions;
+}
+function getChangeName(c) {
+    switch (c.change.type) {
+        case 'added':
+            return c.change.symbol.name;
+        case 'removed':
+            return c.change.symbol.name;
+        case 'modified':
+            return c.change.before.name;
+    }
+}
+function truncateDescription(c) {
+    if (c.change.type !== 'modified')
+        return c.description;
+    const { before, after } = c.change;
+    if (before.kind !== after.kind) {
+        return c.description;
+    }
+    const beforeSig = truncateSignature(before.signature);
+    const afterSig = truncateSignature(after.signature);
+    return `\`${before.name}\` signature changed: \`${beforeSig}\` -> \`${afterSig}\``;
+}
+function formatMarkdown(result) {
+    const sections = [
+        formatSection('### Breaking Changes', result.breaking),
+        formatSection('### New', result.features),
+        formatSection('### Changed', result.fixes)
+    ]
+        .filter(Boolean)
+        .join('\n');
+    if (!sections)
+        return 'No API changes detected.\n';
+    return `${sections}\n**Suggested version bump:** ${result.suggestedBump}\n`;
+}
+function formatSection(heading, changes) {
+    if (changes.length === 0)
+        return '';
+    const items = deduplicateDescriptions(changes)
+        .map((d) => `- ${d}`)
+        .join('\n');
+    return `${heading}\n\n${items}\n`;
+}

package/dist/git.d.ts

@@ -0,0 +1,7 @@
+import { ApiSurface } from './types';
+export declare function assertGitRepo(): void;
+export declare function resolveRefs(rangeArg?: string): {
+    before: string;
+    after: string;
+};
+export declare function extractAtRef(ref: string, entrypoint?: string): ApiSurface;

package/dist/git.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertGitRepo = assertGitRepo;
+exports.resolveRefs = resolveRefs;
+exports.extractAtRef = extractAtRef;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const errors_1 = require("./errors");
+const extract_1 = require("./extract");
+function assertGitRepo() {
+    try {
+        (0, child_process_1.execSync)('git rev-parse --git-dir', { stdio: 'ignore' });
+    }
+    catch {
+        throw new errors_1.AstlogException({
+            code: 'NOT_GIT_REPO',
+            message: 'Not a git repository. Run sigdiff from inside a git repo.'
+        });
+    }
+}
+function resolveRefs(rangeArg) {
+    if (rangeArg) {
+        const parts = rangeArg.split('..');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new errors_1.AstlogException({
+                code: 'INVALID_REF',
+                message: `Invalid range format: "${rangeArg}". Expected format: <ref>..<ref>`
+            });
+        }
+        validateRef(parts[0]);
+        validateRef(parts[1]);
+        return { before: parts[0], after: parts[1] };
+    }
+    let lastTag;
+    try {
+        lastTag = (0, child_process_1.execSync)('git describe --tags --abbrev=0', {
+            encoding: 'utf-8'
+        }).trim();
+    }
+    catch {
+        throw new errors_1.AstlogException({
+            code: 'NO_TAGS',
+            message: 'No git tags found. Provide an explicit range: sigdiff <ref>..<ref>'
+        });
+    }
+    return { before: lastTag, after: 'HEAD' };
+}
+function extractAtRef(ref, entrypoint) {
+    const files = discoverFiles(ref, entrypoint);
+    if (files.length === 0) {
+        throw new errors_1.AstlogException({
+            code: 'NO_TYPESCRIPT',
+            message: `No TypeScript files found at ref "${ref}".`
+        });
+    }
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sigdiff-'));
+    try {
+        const pathMap = new Map();
+        for (const logicalPath of files) {
+            const content = (0, child_process_1.execSync)(`git show '${ref}:${logicalPath}'`, {
+                encoding: 'utf-8'
+            });
+            const tempAbsPath = path.join(tmpDir, logicalPath);
+            fs.mkdirSync(path.dirname(tempAbsPath), { recursive: true });
+            fs.writeFileSync(tempAbsPath, content);
+            const tempRelative = path.relative(process.cwd(), tempAbsPath);
+            pathMap.set(tempRelative, logicalPath);
+        }
+        const tempPaths = files.map((f) => path.join(tmpDir, f));
+        const rawSurface = (0, extract_1.extract)(tempPaths);
+        return normalizeSurface(rawSurface, pathMap);
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+function validateRef(ref) {
+    try {
+        (0, child_process_1.execSync)(`git rev-parse --verify ${ref}`, { stdio: 'ignore' });
+    }
+    catch {
+        throw new errors_1.AstlogException({
+            code: 'INVALID_REF',
+            message: `Git ref "${ref}" does not exist.`
+        });
+    }
+}
+function discoverFiles(ref, entrypoint) {
+    const output = (0, child_process_1.execSync)(`git ls-tree -r --name-only ${ref}`, {
+        encoding: 'utf-8'
+    });
+    const allFiles = output.trim().split('\n').filter(Boolean);
+    let tsFiles = allFiles.filter((f) => (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+        !f.endsWith('.d.ts') &&
+        !f.includes('node_modules/'));
+    if (entrypoint) {
+        tsFiles = tsFiles.filter((f) => f === entrypoint);
+    }
+    return tsFiles;
+}
+function normalizeSurface(surface, pathMap) {
+    const normalized = new Map();
+    for (const [, symbol] of surface.symbols) {
+        const logicalPath = pathMap.get(symbol.filePath);
+        if (!logicalPath)
+            continue;
+        const newSymbol = { ...symbol, filePath: logicalPath };
+        const key = `${logicalPath}:${newSymbol.name}`;
+        normalized.set(key, newSymbol);
+    }
+    return { symbols: normalized };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { extract } from './extract';
+export { diff } from './diff';
+export { classify } from './classify';
+export { buildResult, format } from './format';
+export { AstlogException } from './errors';
+export type { ApiSurface, ExportedSymbol, Change, ClassifiedChange, ChangelogResult, SemverLevel, SymbolKind } from './types';
+export type { AstlogError } from './errors';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AstlogException = exports.format = exports.buildResult = exports.classify = exports.diff = exports.extract = void 0;
+var extract_1 = require("./extract");
+Object.defineProperty(exports, "extract", { enumerable: true, get: function () { return extract_1.extract; } });
+var diff_1 = require("./diff");
+Object.defineProperty(exports, "diff", { enumerable: true, get: function () { return diff_1.diff; } });
+var classify_1 = require("./classify");
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return classify_1.classify; } });
+var format_1 = require("./format");
+Object.defineProperty(exports, "buildResult", { enumerable: true, get: function () { return format_1.buildResult; } });
+Object.defineProperty(exports, "format", { enumerable: true, get: function () { return format_1.format; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AstlogException", { enumerable: true, get: function () { return errors_1.AstlogException; } });

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export type SymbolKind = 'function' | 'interface' | 'type-alias' | 'class' | 'constant' | 'enum';
+export interface ExportedSymbol {
+    name: string;
+    kind: SymbolKind;
+    signature: string;
+    filePath: string;
+}
+export interface ApiSurface {
+    symbols: Map<string, ExportedSymbol>;
+}
+export type Change = {
+    type: 'added';
+    symbol: ExportedSymbol;
+} | {
+    type: 'removed';
+    symbol: ExportedSymbol;
+} | {
+    type: 'modified';
+    before: ExportedSymbol;
+    after: ExportedSymbol;
+};
+export type SemverLevel = 'major' | 'minor' | 'patch';
+export interface ClassifiedChange {
+    change: Change;
+    level: SemverLevel;
+    description: string;
+}
+export interface ChangelogResult {
+    breaking: ClassifiedChange[];
+    features: ClassifiedChange[];
+    fixes: ClassifiedChange[];
+    suggestedBump: SemverLevel;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "sigdiff",
+  "version": "0.1.0",
+  "description": "Changelog from code, not commits. AST-based API surface diffing for TypeScript.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "sigdiff": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix && prettier --write src/ tests/ fixtures/",
+    "format": "prettier --write src/ tests/ fixtures/",
+    "format:check": "prettier --check src/ tests/ fixtures/",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "changelog",
+    "ast",
+    "typescript",
+    "semver",
+    "diff",
+    "api-surface",
+    "breaking-changes"
+  ],
+  "author": "Andy Deng",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1dengaroo/sigdiff"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7.0"
+  },
+  "dependencies": {
+    "cac": "^6.7.14"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.2.0",
+    "prettier": "^3.8.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}