sigdiff 0.1.1 → 0.1.2

package/README.md

@@ -1,14 +1,18 @@
 # sigdiff
 
-Diffs the public API surface of a TypeScript project between two git refs and outputs a structured changelog.
+Detects breaking changes in TypeScript projects by diffing the actual API surface between git refs. No config, no setup, no commit conventions.
 
 ```bash
 npx sigdiff v1.0.0..v2.0.0
 ```
 
-## Why
+## Why this exists
 
-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.
+Tools like `changesets` require developers to manually describe what changed. `semantic-release` relies on commit message conventions. `api-extractor` extracts the API surface but leaves semver classification to humans.
+
+`sigdiff` skips all of that. Point it at two git refs and it tells you what changed in your exports, classified by semver level. Think [`cargo-semver-checks`](https://github.com/obi1kenobi/cargo-semver-checks) for TypeScript.
+
+The goal here is to keep it simple and minimize overhead. No config files. No plugins. No workflow changes.
 
 ## Usage
 
@@ -16,21 +20,23 @@ Commit messages are a human interpretation of a change — imprecise, incomplete
 # Compare last tag to HEAD
 npx sigdiff
 
-# Compare two refs
+# Compare two tags
 npx sigdiff v1.0.0..v2.0.0
 
+# Any git ref works: branches, commits, relative refs
+npx sigdiff main..feature-branch
+npx sigdiff abc1234..def5678
+npx sigdiff HEAD~5..HEAD
+
 # 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.
+# Exit with code 1 if breaking changes are detected (useful for CI)
+npx sigdiff --check
+```
 
 ## Example output
 
@@ -38,7 +44,7 @@ Changes are classified as `major`, `minor`, or `patch` per semver rules.
 ### Breaking Changes
 
 - Removed function `fetchLegacyData`
-- `createUser` signature changed: `(name: string, email: string)` → `(opts: CreateUserOpts)`
+- `createUser` signature changed: `(name: string, email: string)` -> `(opts: CreateUserOpts)`
 
 ### New
 
@@ -48,6 +54,34 @@ Changes are classified as `major`, `minor`, or `patch` per semver rules.
 Suggested version bump: major
 ```
 
+## 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.
+
+## How it compares
+
+|                       | sigdiff         | changesets              | semantic-release     | api-extractor   |
+| --------------------- | --------------- | ----------------------- | -------------------- | --------------- |
+| Detects API changes   | Automatic (AST) | Manual (you write them) | No (commit messages) | Automatic (AST) |
+| Semver classification | Automatic       | Manual                  | Commit-based         | Manual          |
+| Changelog output      | Yes             | Yes                     | Yes                  | No              |
+| Config required       | None            | Yes                     | Yes                  | Yes             |
+| Git ref comparison    | Any ref         | N/A                     | N/A                  | Baseline file   |
+
+## CI integration
+
+Use `--check` to fail your pipeline when breaking changes are introduced:
+
+```yaml
+# .github/workflows/ci.yml
+- name: API surface check
+  run: npx sigdiff origin/main..HEAD --entrypoint src/index.ts --check
+```
+
+Without `--check`, sigdiff always exits 0 and just prints the diff. With `--check`, it exits 1 if any breaking changes are detected, making it easy to gate PRs.
+
 ## Programmatic API
 
 ```typescript
@@ -61,10 +95,10 @@ 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))
+- TypeScript only. No JS support (no type info to diff).
+- Single-package projects. No monorepo support yet.
+- Read-only. Never touches your working tree.
+- 1 runtime dependency ([`cac`](https://github.com/cacjs/cac)). ~8 KB published.
 
 ## License
 

package/dist/cli.js

@@ -16,6 +16,7 @@ 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')
+    .option('--check', 'Exit with code 1 if breaking changes are detected')
     .action((range, options) => {
     try {
         (0, git_1.assertGitRepo)();
@@ -27,6 +28,9 @@ cli
         const result = (0, format_1.buildResult)(classified);
         const output = (0, format_1.format)(result, { json: options.json });
         process.stdout.write(output);
+        if (options.check && result.breaking.length > 0) {
+            process.exit(1);
+        }
     }
     catch (err) {
         if (err instanceof errors_1.SigdiffException) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigdiff",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Changelog from code, not commits. AST-based API surface diffing for TypeScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",