Reproduced live: saving a file schedules the debounced re-diff up to --debounce ms in the future; sending SIGINT (Ctrl+C) inside that window (realistic "save, then quit to go commit" sequence, well within the default 300ms) cleared the pending timer and exited without ever re-checking the final on-disk edit. The last printed report still showed the pre-edit verdict, so a breaking change made right before quitting watch mode was silently never checked. watchForChanges()'s returned stop() now flushes: if a change is pending when the watcher is torn down, it runs the diff once, synchronously, before closing. Verified the exact repro now prints the correct breaking-change banner before "stopped."; negative controls confirm no spurious extra diff when nothing is pending and no double-fire when the debounce had already settled naturally. Standing usesend-SDK regression re-run byte-identical (5 structural changes).
Surfacenotes
Changelog and release-notes generator for TypeScript library and SDK
maintainers. Surfacenotes writes the same CHANGELOG.md /
RELEASE_NOTES.md pair most changelog tools write — but it never trusts a
feat:/fix: commit label to tell you whether a release is actually
breaking. It parses the package's public entry file with the real
TypeScript compiler at both git refs, structurally diffs the exported
surface (removed exports, removed class members, new required parameters,
optional-to-required field changes), and cross-checks that against what the
commits in the same range declared. If the two disagree, the generated
changelog gets a loud warning banner instead of a confident lie.
Why this exists
Conventional-commit-based changelog tools (git-cliff, release-please,
conventional-changelog, and the newer AI wrappers like shipnote,
ChangelogAI, ShipTell, Engammo, ai-changelog-generator) all take the
author's feat:/fix:/BREAKING CHANGE: label on faith. That label is
written by a human in a hurry, and it is wrong more often than teams like to
admit — e.g. a "small refactor" that quietly drops a required export gets
tagged fix: and shipped as a patch. Separately, a handful of tools
(@clerk/break-check, semver-checks, semver-guard) already verify a
package's real TypeScript API surface for exactly this reason — but they
are CI gates that recommend a semver bump, not changelog generators, so
nobody sees a human-readable explanation of what broke.
Surfacenotes is the combination: a real changelog/release-notes generator
whose breaking-change section is backed by a real structural diff of your
code, not a trust exercise. Source research for this gap (AI "fluff" and
hallucination complaints on AI changelog tools, squash-merge handling
details, the p-limit 6.1.0 example of a breaking type change shipped as a
minor) is summarized in ~/products/plans/surfacenotes.md.
What it does today (MVP)
- Reads commits in a
from..togit range (works with squash-merged PRs:(#123)suffixes andgh-style merge subjects are recognized). - Groups them the conventional-commit way: Breaking / Added / Fixed /
Changed / Docs / Other. Commits without a recognizable
type:prefix still show up under "Other" instead of being silently dropped. - Pulls the package's public entry file (and everything it locally
re-exports, including
export default— bothexport default class Foo {...}/export default function foo() {...}declarations and the separateclass Foo {...}; export default Foo;assignment form, andexport * as Types from "./types"namespace re-exports, where every export reachable through the namespace is tracked individually under a qualifiedTypes.SendOptions-style name) at both refs straight out of git (git show/git cat-file, read-only, no checkout, no worktree) and parses both snapshots with the realtypescriptcompiler package. Relative imports/re-exports that name a compiled.js/.jsx/.mjs/.cjsextension (the real"moduleResolution": "nodenext"/"node16"ESM convention, e.g.export { X } from "./foo.js"resolving to a realfoo.ts— confirmed live against the real@octokit/coresource) resolve to their real TS source file instead of silently failing to resolve at all. - Structurally diffs the two snapshots: removed exports/members (including
get/setclass accessors, not just methods and plain properties) are breaking, new required parameters (or a shrinking parameter list) are breaking, an existing parameter tightened from optional to required in place (matched by position, e.g.send(to, subject?)->send(to, subject), no change in parameter count) is breaking, an optional-to-required or newly-added-required field on aninterface/typeis breaking, anenummember's real effective value changing — including the classic "inserted a member above an auto-numbered one and silently renumbered everything after it" footgun — is breaking, a generic type parameter added to an exportedinterface/type alias/class/functionwith no default (or an existing one losing a default it used to have) is breaking — even when the member-level diff sees nothing to flag, e.g. a new optional field riding along with the new type parameter — because it raises the number of explicit type arguments a usage likeResult<string>must supply, everything additive is safe. A real declared TypeScript overload set on an exported function, class method,interfacemethod, or object-shapedtypealias's method-shorthand member (send(a: string): void; send(a: Opts): void; send(a) { ... }, or the same shape declared on aninterface/type) is diffed as a full list of call signatures, not collapsed to just one of them — losing a previously declared call shape anywhere in that list (by structural match, not just position, so reordering or adding an overload is still safe) is breaking. A property's declared type, or a function/method's declared return type, widening to includeundefined/nullwhere it didn't before (e.g.name: string->name: string | undefined, orgetName(): string->getName(): string | undefined) is breaking — existing callers that use the value directly with no null/undefined check will fail to type-check under strict null checks. A class member flipping betweenstaticand instance (e.g.static send(a: string): void {}->send(a: string): void {}, same name, same params) is breaking in either direction — confirmed against the real compiler: existing callers written asClient.send(x)ornew Client().send(x)fail to type-check against the other shape, even though nothing else about the member changed. A property on aninterface/type/class gaining thereadonlymodifier (same name, same type, nothing else about it changed) is breaking — confirmed against the real compiler (TS2540: Cannot assign to '...' because it is a read-only property); droppingreadonlyonly loosens what callers may do and is never flagged. A method declared with TypeScript's shorthand method syntax inside an object-shapedtypealias (e.g.type Handlers = { onData(chunk: string): void }, as opposed to an arrow/function-typed property) is diffed the same way as aninterfacemethod — removing one is breaking. Aninterface/type/class's own index signature ([key: string]: T, e.g. a headers/options bag) is tracked too: removing it, or changing its value type in either direction (narrowing or widening, e.g.string | number->string), is breaking — confirmed against the real compiler both ways; adding one where there wasn't one before is purely additive and safe. - Writes
CHANGELOG.md(developer-facing, with commit/PR links) andRELEASE_NOTES.md(same data, plain language, no hashes) with a verification banner at the top of each release, prepending each new release's section above whatever releases are already recorded there instead of overwriting the file — runninggenerateagain for the same version (e.g. on a different day) replaces that version's section in place rather than duplicating it. That read-merge-write sequence is serialized behind a lock file scoped to--out-dir, so twogenerateinvocations targeting the same--out-dirat once (two CI jobs for two tags pushed close together, or a backfill script running several historical ranges in parallel) can't silently clobber each other's release section — confirmed live: without the lock, two concurrent runs reliably lost one release's entire section; with it, both always survive. Exits with status2when it finds an undeclared breaking change, so it can gate a CI release job. surfacenotes watch— a local dev-loop mode: diffs a baseline ref against your live working tree (uncommitted edits included) and re-checks every time a source file changes, so a breaking API edit is flagged the moment it's saved, not the next time someone remembers to rungenerateagainst a tag. See "Local dev loop" below.- Optional
--ainarrative pass: rewrites the already-grouped, already- deduplicated commit bullets into 2-4 plain sentences via any OpenAI- compatible endpoint (your own key, a local Ollama model viaSURFACENOTES_AI_BASE_URL=ollama, or plainOPENAI_API_KEY). It never sees a raw commit diff or source file, only the structured bullets this tool already extracted — the anti-hallucination constraint this project's own research flagged as mandatory. Off by default; a missing/misconfigured endpoint degrades silently to the structured-only output rather than erroring. See--aiinsurfacenotes generate --helpoutput above. The request itself has a 30s timeout and a 2MB response cap, so a hung or misbehaving endpoint (a local model still loading, a stalled proxy) can never wedgegenerateindefinitely or buffer an unbounded body into memory — it just degrades to the structured-only output, same as a missing config.
Local dev loop: surfacenotes watch
generate is after-the-fact — it diffs two refs that already exist. watch
is for while you're still writing the change:
surfacenotes watch \
--repo /path/to/your/repo \
--entry packages/sdk/index.ts \
--from v1.7.2
It diffs v1.7.2 against whatever is actually on disk right now (not a
commit, not a stash — the real files, saved or not), prints a report, then
keeps watching. Every time you save, it re-diffs and reprints:
[surfacenotes watch] 14:02:11 — v1.7.2 -> working tree (packages/sdk/index.ts)
⚠ 1 BREAKING change(s):
- [required-field-added] SendOptions.idempotencyKey: property "idempotencyKey" was
added to SendOptions as required (not optional) — existing object literals typed
as SendOptions that don't set it will now fail type-checking.
No files are written and no git state changes — it only reads (git show
for the baseline, the real filesystem for your edits). Stop with Ctrl+C.
Uses native recursive fs.watch where the platform supports it, and falls
back to lightweight polling (a directory signature of file paths + mtimes)
everywhere else, so it behaves the same on Linux as it does on macOS.
A real catch, not a canned demo
Ran Surfacenotes against every real patch and minor tag-to-tag range in
resend/resend-node's actual public
history (102 real version pairs, no cherry-picking) to find the exact kind of
case this tool exists for: a release that reads as safe from its version
number alone but genuinely changed the public type surface. 12 of 102 were
flagged; the clearest one:
v4.6.0 → v4.7.0 (a minor version bump) shipped
PR #535, "update types to
allow type narrowing" — and silently converted 22 response types
(CreateApiKeyResponse, GetContactResponse, CreateDomainResponse, and 19
more) from a loosely-typed interface where data/error were both
independently nullable:
export interface CreateApiKeyResponse {
data: CreateApiKeyResponseSuccess | null;
error: ErrorResponse | null;
}
into a real discriminated union:
export type CreateApiKeyResponse =
| { data: CreateApiKeyResponseSuccess; error: null }
| { data: null; error: ErrorResponse };
That's a genuinely better type — but it's also a real breaking change for
any caller whose code happened to rely on the old shape (e.g. constructing
{ data: null, error: null } directly, or widening the type before
narrowing it), and it shipped across the entire SDK's response surface with
no BREAKING CHANGE: footer and no major version bump. Surfacenotes caught
it because it diffs the actual exported type shape at both refs — not the
commit message.
Scanning also surfaced and fixed two real bugs in Surfacenotes itself along
the way: a crash when an import specifier resolved to a git directory
instead of a file (src/git.ts's existsAtRef wasn't checking the git
object was actually a blob), and a false positive where converting
interface X {...} to type X = {...} (or the much more common real-world
type X = {...} & OtherNamedType mixin pattern) was flagged as a breaking
"kind change" even when the actual member shape didn't change. Both fixed
and re-verified against the same real 102-pair scan before either number
above was written down.
What it intentionally does not do yet
- The
--ainarrative pass (see above) is opt-in only and never a silent default: with no--aiflag, and with no endpoint configured even when--aiis passed, nothing is ever sent anywhere — nothing here should send your commits to a third party without you explicitly asking it to. - The structural diff is a heuristic, not a full type-compatibility checker. It catches the common, high-value cases (removed exports, removed members, new required parameters, optional→required field flips, enum member value shifts) and intentionally reports ambiguous type-text changes as informational rather than guessing.
- Only local (relative-path) imports are followed. Changes inside a dependency you re-export are out of scope for v0.1.0.
Usage
npm install -g surfacenotes # or: npx surfacenotes ...
surfacenotes generate \
--repo /path/to/your/repo \
--entry packages/sdk/index.ts \
--from v1.6.0 --to v1.7.2 \
--repo-url https://github.com/you/your-repo \
--out-dir .
This writes CHANGELOG.md and RELEASE_NOTES.md into --out-dir. Run it
as a release-pipeline step right before npm publish; a non-zero exit
means an undeclared breaking change was found in the diff and the release
is worth a second look before it ships. (That's a feature to run inside
your CI — this repository itself has no CI/CD workflows by design.)
For local iteration before you ever get to a tag, run surfacenotes watch
instead — see "Local dev loop" above.
Using it programmatically
import { collectCommits, diffApiSurfaces, verify } from "surfacenotes";
See src/index.ts for the full list of exported building blocks.
License
MIT. See LICENSE. No code was forked from another project — this is a
fresh implementation written directly against the typescript compiler
package and Node's child_process/fs, after evaluating git-cliff,
conventional-changelog, release-please, mogesjohnson/release-notes,
shipnote, entro314-labs/ai-changelog-generator, @clerk/break-check,
and semver-checks as prior art (see the plan file for why none of them
cover this combination).
Verifying it yourself
npm install
npm run build
node dist/cli.js generate --repo <any git repo> --entry <path to its public entry file> --from <tag> --to <tag-or-HEAD>