diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 194f5d2..c6cb43f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: steps: - uses: actions/checkout@v4 with: - fetch-depth: 0 # full history for astlog git refs + fetch-depth: 0 # full history for sigdiff git refs - uses: actions/setup-node@v4 with: diff --git a/CLAUDE.md b/CLAUDE.md index 984bbe8..62c4ebc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# astlog +# sigdiff Zero-config CLI that diffs the public API surface of a TypeScript project between two git refs and outputs a structured changelog. @@ -20,7 +20,7 @@ src/ diff.ts — Two ApiSurfaces -> Change[] classify.ts — Change -> SemverLevel format.ts — ChangelogResult -> markdown or JSON - errors.ts — Typed error union (AstlogError) + errors.ts — Typed error union (SigdiffError) git.ts — Read files at git refs, temp file management cli.ts — Entry point, arg parsing, error boundary index.ts — Barrel export for programmatic API @@ -32,11 +32,11 @@ src/ - **Discriminated unions over optional fields.** Each `Change` variant carries exactly its data. - **Validate at boundaries only.** CLI validates args. Internal functions trust typed inputs. - **Each function is independently useful.** `extract`, `diff`, `classify`, `format` are composable. -- **Consistent error format.** Library code throws `AstlogException`, never calls `process.exit`. +- **Consistent error format.** Library code throws `SigdiffException`, never calls `process.exit`. ## Conventions -- Zero config — no `.astlogrc`, no config files +- Zero config — no config files - `typescript` is a peer dep, `cac` for CLI parsing — that's it - `ExportedSymbol.signature` is a normalized string — comparison happens on strings, not AST nodes - `ApiSurface.symbols` keyed by `filePath:name` for cross-file uniqueness diff --git a/README.md b/README.md index f559d04..b04f33b 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,29 @@ -# astlog +# sigdiff Diffs the public API surface of a TypeScript project between two git refs and outputs a structured changelog. ```bash -npx astlog v1.0.0..v2.0.0 +npx sigdiff v1.0.0..v2.0.0 ``` ## Why -Commit messages are a human interpretation of a change — imprecise, incomplete, or missing entirely. `astlog` adds a second perspective: what the code actually exported. It catches things commit messages miss, like a signature change buried in a large PR. +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 astlog +npx sigdiff # Compare two refs -npx astlog v1.0.0..v2.0.0 +npx sigdiff v1.0.0..v2.0.0 # Scope to a specific entrypoint -npx astlog --entrypoint src/index.ts +npx sigdiff --entrypoint src/index.ts # JSON output -npx astlog --json +npx sigdiff --json ``` ## What it detects @@ -51,7 +51,7 @@ Suggested version bump: major ## Programmatic API ```typescript -import { extract, diff, classify, buildResult, format } from 'astlog'; +import { extract, diff, classify, buildResult, format } from 'sigdiff'; const before = extract(['src/v1/index.ts']); const after = extract(['src/v2/index.ts']); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5c871a8..bd46ef3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -19,7 +19,7 @@ src/ classify.ts — Change[] -> ClassifiedChange[] (semver levels) format.ts — ChangelogResult -> markdown or JSON string types.ts — All shared contracts - errors.ts — Typed error union (AstlogError) + errors.ts — Typed error union (SigdiffError) index.ts — Barrel export for programmatic API ``` @@ -64,7 +64,7 @@ interface ChangelogResult { **Signature as string.** `ExportedSymbol.signature` is a canonical string, not raw AST nodes. Diff comparison is string equality. Signatures are normalized at extraction time (whitespace collapsed, semicolons standardized, index signatures canonicalized to `Record<>`). -**Validate at boundaries only.** `cli.ts` validates args and catches `AstlogException`. Internal functions (`diff`, `classify`, `format`) trust typed inputs — no defensive checks. +**Validate at boundaries only.** `cli.ts` validates args and catches `SigdiffException`. Internal functions (`diff`, `classify`, `format`) trust typed inputs — no defensive checks. **Arrow function detection.** `const fn = () => ...` is classified as `"function"` kind, not `"constant"`. The extractor checks if a variable declaration's type has call signatures. @@ -79,7 +79,7 @@ interface ChangelogResult { ## Error Handling ```typescript -type AstlogError = +type SigdiffError = | { code: 'INVALID_REF'; message: string } | { code: 'NO_TAGS'; message: string } | { code: 'NO_TYPESCRIPT'; message: string } @@ -87,7 +87,7 @@ type AstlogError = | { code: 'NOT_GIT_REPO'; message: string }; ``` -Library code throws `AstlogException`. Only `cli.ts` calls `process.exit`. +Library code throws `SigdiffException`. Only `cli.ts` calls `process.exit`. ## Semver Classification Rules diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 040ab02..9f11378 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -1,4 +1,4 @@ -# astlog — Changelog from code, not commits +# sigdiff — Changelog from code, not commits ## Problem @@ -10,7 +10,7 @@ Every existing changelog tool (conventional-changelog, changesets, release-it, a ## Solution -`astlog` reads what the code actually did. Your exported functions, types, and interfaces _are_ your API contract. If a function signature changed, that's a breaking change — regardless of what the commit message says. +`sigdiff` reads what the code actually did. Your exported functions, types, and interfaces _are_ your API contract. If a function signature changed, that's a breaking change — regardless of what the commit message says. ``` git ref A --> TS Compiler API --> API Surface A --\ @@ -22,16 +22,16 @@ git ref B --> TS Compiler API --> API Surface B --/ ```bash # Compare last tag to HEAD -npx astlog +npx sigdiff # Compare two specific refs -npx astlog v1.2.0..v1.3.0 +npx sigdiff v1.2.0..v1.3.0 # Scope to barrel export only -npx astlog --entrypoint src/index.ts +npx sigdiff --entrypoint src/index.ts # Machine-readable output -npx astlog --json +npx sigdiff --json ``` ## Example Output @@ -52,7 +52,7 @@ npx astlog --json ### In -- Single command: `astlog ..` (defaults to last tag..HEAD) +- Single command: `sigdiff ..` (defaults to last tag..HEAD) - TypeScript files only (`.ts`, `.tsx`) - Detect exports: functions, interfaces, type aliases, enums, classes, constants - Diff: added / removed / signature-changed @@ -60,7 +60,7 @@ npx astlog --json - Output: markdown (default) and `--json` - Zero config — works out of the box on any TS project - `--entrypoint` flag to scope to specific files -- Programmatic API: `import { extract, diff, classify, format } from 'astlog'` +- Programmatic API: `import { extract, diff, classify, format } from 'sigdiff'` ### Out of Scope @@ -74,8 +74,8 @@ npx astlog --json ## Design Philosophy -- Zero config. No `.astlogrc`, no `astlog.config.js`. +- Zero config. No `.sigdiffrc`, no `sigdiff.config.js`. - Tiny dependency footprint. `typescript` as a peer dep and `cac` for CLI parsing. - One command, one output. - Composable — generates a changelog, doesn't manage releases. Pipe its output wherever you want. -- Adopt in 30 seconds: `npx astlog` and you're done. +- Adopt in 30 seconds: `npx sigdiff` and you're done. diff --git a/docs/TODO.md b/docs/TODO.md index f6247b4..f4dbb4a 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -1,4 +1,4 @@ -# astlog — TODO +# sigdiff — TODO ## Next diff --git a/package.json b/package.json index 4c397e0..04b6418 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,11 @@ { - "name": "astlog", + "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": { - "astlog": "dist/cli.js" + "sigdiff": "dist/cli.js" }, "files": [ "dist" @@ -33,7 +33,7 @@ "license": "MIT", "repository": { "type": "git", - "url": "https://github.com/andydeng/astlog" + "url": "https://github.com/1dengaroo/sigdiff" }, "engines": { "node": ">=18" diff --git a/src/cli.ts b/src/cli.ts index dca1c32..8340d44 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1,13 +1,13 @@ #!/usr/bin/env node import cac from 'cac'; -import { AstlogException } from './errors'; +import { SigdiffException } from './errors'; import { assertGitRepo, extractAtRef, resolveRefs } from './git'; import { diff } from './diff'; import { classify } from './classify'; import { buildResult, format } from './format'; -const cli = cac('astlog'); +const cli = cac('sigdiff'); cli .command('[range]', 'Diff the public API surface between two git refs') @@ -28,7 +28,7 @@ cli process.stdout.write(output); } catch (err) { - if (err instanceof AstlogException) { + if (err instanceof SigdiffException) { process.stderr.write(`Error: ${err.error.message}\n`); process.exit(1); } diff --git a/src/errors.ts b/src/errors.ts index 4f10b40..a3ef2ce 100644 --- a/src/errors.ts +++ b/src/errors.ts @@ -1,13 +1,13 @@ -export type AstlogError = +export type SigdiffError = | { 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 class AstlogException extends Error { - constructor(public readonly error: AstlogError) { +export class SigdiffException extends Error { + constructor(public readonly error: SigdiffError) { super(error.message); - this.name = 'AstlogException'; + this.name = 'SigdiffException'; } } diff --git a/src/git.ts b/src/git.ts index 65182d1..c0d5084 100644 --- a/src/git.ts +++ b/src/git.ts @@ -2,7 +2,7 @@ import { execSync } from 'child_process'; import * as fs from 'fs'; import * as os from 'os'; import * as path from 'path'; -import { AstlogException } from './errors'; +import { SigdiffException } from './errors'; import { extract } from './extract'; import { ApiSurface, ExportedSymbol } from './types'; @@ -10,9 +10,9 @@ export function assertGitRepo(): void { try { execSync('git rev-parse --git-dir', { stdio: 'ignore' }); } catch { - throw new AstlogException({ + throw new SigdiffException({ code: 'NOT_GIT_REPO', - message: 'Not a git repository. Run astlog from inside a git repo.' + message: 'Not a git repository. Run sigdiff from inside a git repo.' }); } } @@ -24,7 +24,7 @@ export function resolveRefs(rangeArg?: string): { if (rangeArg) { const parts = rangeArg.split('..'); if (parts.length !== 2 || !parts[0] || !parts[1]) { - throw new AstlogException({ + throw new SigdiffException({ code: 'INVALID_REF', message: `Invalid range format: "${rangeArg}". Expected format: ..` }); @@ -40,9 +40,9 @@ export function resolveRefs(rangeArg?: string): { encoding: 'utf-8' }).trim(); } catch { - throw new AstlogException({ + throw new SigdiffException({ code: 'NO_TAGS', - message: 'No git tags found. Provide an explicit range: astlog ..' + message: 'No git tags found. Provide an explicit range: sigdiff ..' }); } @@ -53,13 +53,13 @@ export function extractAtRef(ref: string, entrypoint?: string): ApiSurface { const files = discoverFiles(ref, entrypoint); if (files.length === 0) { - throw new AstlogException({ + throw new SigdiffException({ code: 'NO_TYPESCRIPT', message: `No TypeScript files found at ref "${ref}".` }); } - const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astlog-')); + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sigdiff-')); try { const pathMap = new Map(); @@ -89,7 +89,7 @@ function validateRef(ref: string): void { try { execSync(`git rev-parse --verify ${ref}`, { stdio: 'ignore' }); } catch { - throw new AstlogException({ + throw new SigdiffException({ code: 'INVALID_REF', message: `Git ref "${ref}" does not exist.` }); diff --git a/src/index.ts b/src/index.ts index 947def3..68e9f6b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,7 +2,7 @@ export { extract } from './extract'; export { diff } from './diff'; export { classify } from './classify'; export { buildResult, format } from './format'; -export { AstlogException } from './errors'; +export { SigdiffException } from './errors'; export type { ApiSurface, @@ -14,4 +14,4 @@ export type { SymbolKind } from './types'; -export type { AstlogError } from './errors'; +export type { SigdiffError } from './errors';