findLocalDeclaration (top-level functions) only ever returned the first
matching FunctionDeclaration node, and classMembers pushed one MemberSurface
per overload ClassElement, all keyed by the same name -- diffMembers' Map
construction then silently collapsed duplicates to whichever was pushed
last. Either way, a real TypeScript overload set (`send(a: string): void;
send(a: Opts): void; send(a) { ... }`) only ever had ONE of its declared
call shapes visible to the structural differ, on both snapshots, regardless
of which overload actually changed.
Confirmed as a real break directly against tsc --strict: a synthetic repro
narrowing createUser(email: string) | createUser(opts: Opts) down to just
the opts overload, committed as a mislabeled fix: with no breaking footer,
produced a real TS2345 for a caller using the removed string-argument shape
-- but surfacenotes printed "0 structural change(s)" and exited 0 before
this fix. Same bug, same fix, confirmed on a class method overload too.
New ExportSurface/MemberSurface.overloadParams carries every real call
signature (collected via sibling-declaration/ClassElement scanning, not the
single first/last match), and a new overloadRemoved() check flags any old
signature with no structurally-equal match anywhere in the new list as
breaking. Matching is by structural equality, not position, so reordering
or adding an overload stays safe (verified via two negative controls).
Never fires for ordinary non-overloaded functions/methods.
Verified live: both synthetic repros go from exit 0 to exit 2 with the
correct removed-shape detail; two negative controls (additive overload,
reordered-but-unchanged overloads) stay exit 0; both standing real-world
regressions re-run unchanged -- usesend SDK v1.6.0..v1.7.2 (5 structural
changes, exit 0) and a freshly re-cloned resend-node v4.6.0->v4.7.0 (23
structural changes, exit 2, no new overload findings). npm run build clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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) 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. - 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 or class method (send(a: string): void; send(a: Opts): void; send(a) { ... }) 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. - 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. 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.
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
- No AI narrative rewrite pass is wired up in this MVP. The structured,
already-deduplicated commit bullets are the right shape to safely feed
an AI rewrite later (constrained input avoids the "hallucination wearing
a changelog costume" failure mode found in research), but no hosted or
local model call ships in
v0.1.0— nothing here should send your commits to a third party. Hook it up insrc/changelog.tsbehind an explicit--aiflag that points at a local/your-own endpoint when ready. - 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>