sigdiff 0.1.0 → 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

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const cac_1 = __importDefault(require("cac"));
+const package_json_1 = require("../package.json");
 const errors_1 = require("./errors");
 const git_1 = require("./git");
 const diff_1 = require("./diff");
@@ -15,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)();
@@ -26,9 +28,12 @@ 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.AstlogException) {
+        if (err instanceof errors_1.SigdiffException) {
             process.stderr.write(`Error: ${err.error.message}\n`);
             process.exit(1);
         }
@@ -36,5 +41,5 @@ cli
     }
 });
 cli.help();
-cli.version('0.1.0');
+cli.version(package_json_1.version);
 cli.parse();

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type AstlogError = {
+export type SigdiffError = {
     code: 'INVALID_REF';
     message: string;
 } | {
@@ -14,7 +14,7 @@ export type AstlogError = {
     code: 'NOT_GIT_REPO';
     message: string;
 };
-export declare class AstlogException extends Error {
-    readonly error: AstlogError;
-    constructor(error: AstlogError);
+export declare class SigdiffException extends Error {
+    readonly error: SigdiffError;
+    constructor(error: SigdiffError);
 }

package/dist/errors.js

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

package/dist/git.js

@@ -47,7 +47,7 @@ function assertGitRepo() {
         (0, child_process_1.execSync)('git rev-parse --git-dir', { stdio: 'ignore' });
     }
     catch {
-        throw new errors_1.AstlogException({
+        throw new errors_1.SigdiffException({
             code: 'NOT_GIT_REPO',
             message: 'Not a git repository. Run sigdiff from inside a git repo.'
         });
@@ -57,7 +57,7 @@ function resolveRefs(rangeArg) {
     if (rangeArg) {
         const parts = rangeArg.split('..');
         if (parts.length !== 2 || !parts[0] || !parts[1]) {
-            throw new errors_1.AstlogException({
+            throw new errors_1.SigdiffException({
                 code: 'INVALID_REF',
                 message: `Invalid range format: "${rangeArg}". Expected format: <ref>..<ref>`
             });
@@ -73,7 +73,7 @@ function resolveRefs(rangeArg) {
         }).trim();
     }
     catch {
-        throw new errors_1.AstlogException({
+        throw new errors_1.SigdiffException({
             code: 'NO_TAGS',
             message: 'No git tags found. Provide an explicit range: sigdiff <ref>..<ref>'
         });
@@ -83,7 +83,7 @@ function resolveRefs(rangeArg) {
 function extractAtRef(ref, entrypoint) {
     const files = discoverFiles(ref, entrypoint);
     if (files.length === 0) {
-        throw new errors_1.AstlogException({
+        throw new errors_1.SigdiffException({
             code: 'NO_TYPESCRIPT',
             message: `No TypeScript files found at ref "${ref}".`
         });
@@ -114,7 +114,7 @@ function validateRef(ref) {
         (0, child_process_1.execSync)(`git rev-parse --verify ${ref}`, { stdio: 'ignore' });
     }
     catch {
-        throw new errors_1.AstlogException({
+        throw new errors_1.SigdiffException({
             code: 'INVALID_REF',
             message: `Git ref "${ref}" does not exist.`
         });

package/dist/index.d.ts

@@ -2,6 +2,6 @@ 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, ExportedSymbol, Change, ClassifiedChange, ChangelogResult, SemverLevel, SymbolKind } from './types';
-export type { AstlogError } from './errors';
+export type { SigdiffError } from './errors';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AstlogException = exports.format = exports.buildResult = exports.classify = exports.diff = exports.extract = void 0;
+exports.SigdiffException = 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");
@@ -11,4 +11,4 @@ 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; } });
+Object.defineProperty(exports, "SigdiffException", { enumerable: true, get: function () { return errors_1.SigdiffException; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigdiff",
-  "version": "0.1.0",
+  "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",