Confirmed live: two `generate` invocations targeting the same --out-dir at once
(e.g. two CI jobs for tags pushed close together, or a parallel backfill) could
both read the existing CHANGELOG.md before either wrote, so whichever wrote last
silently destroyed the other's freshly-merged release section entirely -- the
same failure class commit 1c0350c fixed for the single-process overwrite case,
reopened by concurrency. Reproduced deterministically with a barrier-forced
worst-case interleaving (reliable data loss pre-fix, 0 losses across repeated
real-process and deterministic trials post-fix) and fixed with a cross-process
advisory lock file (changelogLock.ts) scoped to --out-dir, with stale-lock
recovery so a crashed process can't deadlock future runs. Standing regressions
re-run byte-identical: usesend SDK v1.6.0..v1.7.2 (73 commits, 5 structural
changes, exit 0) and resend-node v4.6.0->v4.7.0 (23 structural changes, exit 2).
`watch` mode untouched -- it never writes CHANGELOG.md.
The one real network call in this codebase (the optional `--ai` chat
completions request in src/ai.ts) had no timeout and no cap on how much
of the response it would buffer before res.json() ran. A hung/slow
OpenAI-compatible endpoint (a local Ollama model still loading, a
stalled corporate proxy) wedged `generate --ai` forever with no
feedback and no way out but Ctrl+C; a misbehaving endpoint streaming an
unbounded body would be buffered fully into memory before any check.
Fixed with an AbortController-driven 30s timeout and a streamed,
2MB-capped body read (readBodyCapped) that aborts the reader as soon as
the running total crosses the cap instead of letting res.json()/res.text()
buffer it all first. Both failure modes degrade to the same null return
every other AI failure path already uses, so generate always still
finishes with the complete structured output.
Verified live: a hanging mock server reproduces an unkillable-without-
Ctrl+C hang pre-fix (confirmed via git stash, force-killed after 8s with
no output written) and a clean 30s-timeout degrade post-fix; an
oversized-response mock server aborts within ~1s instead of streaming
to its full 4MB; a normal mock server round-trip is unaffected. Both
standing real-world regressions (usesend SDK v1.6.0..v1.7.2, resend-node
v4.6.0->v4.7.0) re-run byte-identical.
interfaceMembers()/typeLiteralMembers()/classMembers() skipped index
signatures (`[key: string]: T`) entirely -- they have no `.name` node, so
`if (!m.name) continue` dropped them from the surface on both snapshots.
Removing an index signature, or changing its value type in either
direction (narrowing or widening), is a real breaking change confirmed
against the real compiler (TS2322/TS2353 on real callers in both
directions); before this fix surfacenotes printed "0 structural changes"
and exited 0 for exactly that edit. Adding a new index signature is
correctly classified as safe/additive (optional: true keeps it out of the
required-field-added path). Verified live: synthetic narrowing/widening and
removal repros go from exit 0 to exit 2 with the correct detail; negative
controls (unchanged index signature + unrelated safe add, and a newly
added index signature) stay exit 0. Both standing real-world regressions
re-run byte-identical: usesend SDK v1.6.0..v1.7.2 (73 commits, 5 structural
changes, exit 0) and resend-node v4.6.0->v4.7.0 (23 structural changes,
exit 2, same citable catch). npm run build clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
interfaceMembers() and typeLiteralMembers() pushed one MemberSurface per
ts.MethodSignature, all keyed by the same method name, which diffMembers'
Map collapse then silently kept only the last-pushed signature -- the same
overload-collapse bug already fixed for class methods and top-level
functions (8a79179), never ported to interface/type-literal method
signatures. A real overload set declared on an interface or an
object-shaped type alias (e.g. `on(event: "data", cb: ...): void; on(event:
"end", cb: () => void): void;`) had every signature but one invisible to
the structural diff on both snapshots.
Both functions now group MethodSignature nodes by name and carry every
signature via overloadParams, the same way classMembers already does, so
the existing overloadRemoved() check (no parentKind restriction) now fires
for these two cases too.
Verified live: synthetic repro removing one of two interface method
overloads went from exit 0 ("API diff found 0 structural change(s)") to
exit 2 with the correct overload-removed detail; same result for the
type-literal (object-shaped `type` alias) variant. Negative controls (an
additive third overload, and the same two overloads reordered) stayed
exit 0 -- no over-flagging. Both standing real-world regressions re-run
byte-identical: usesend SDK v1.6.0..v1.7.2 (73 commits, 5 structural
changes, exit 0) and resend-node v4.6.0->v4.7.0 (23 structural changes,
exit 2, same citable catch, zero new overload findings in that range).
npm run build clean. No test files added, per standing instruction.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
export * as Types from "./types" uses a distinct NamespaceExport
exportClause kind that matched neither the NamedExports branch nor the
bare "export * from" branch in collectExports(), so every export reachable
only through a namespace re-export was completely invisible to the
structural diff on both snapshots. Common SDK pattern (grouping
request/response types under a namespace). Now tracked under a qualified
"NS.subName" key through the same diffSurfaces()/diffMembers() path as
every other export.
Verified live: synthetic repro (new required field added to an interface
reachable only via `export * as Types`) went from exit 0/"0 structural
changes" to exit 2 with the correct Types.SendOptions finding; negative
control (safe additive optional field + new export under the namespace)
stayed exit 0. Both standing real-world regressions re-run byte-identical:
usesend SDK v1.6.0..v1.7.2 (73 commits, 5 structural changes, exit 0) and
resend-node v4.6.0->v4.7.0 (23 structural changes, exit 2).
The "What it intentionally does not do yet" section still told every
npm/GitHub visitor the --ai narrative pass was unbuilt future work and
pointed them to wire it up themselves, even though it has been fully
implemented and shipped since commit 2ee89cc (2026-10-27). Moved an
accurate description into "What it does today" and fixed the
"does not do yet" bullet to describe the real opt-in/no-silent-call
guarantee instead of a nonexistent gap. Verified live: built, then ran
`generate --ai` against a real local mock OpenAI-compatible server —
confirmed server-side it received exactly the deduplicated bullet text
(never a raw diff) and the real response landed in CHANGELOG.md exactly
as the corrected README now describes. Re-ran the standing real-world
regression (usesend SDK v1.6.0..v1.7.2) byte-identical after the change.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
typeLiteralMembers() only ever matched PropertySignature nodes inside a
TypeLiteral, so a member declared with TypeScript's method-shorthand
syntax (`type Handlers = { onData(chunk: string): void }`) parsed as a
distinct MethodSignature node and was silently dropped from the surface
on both snapshots. Confirmed as a real false negative via synthetic
repro: removing onEnd() from such a type, committed as a mislabeled
fix:, printed "0 structural change(s)" and exited 0 before this fix.
Mirrors interfaceMembers()'s existing MethodSignature handling. Verified:
repro now exits 2 with the correct member-removed finding; negative
control (adding a new optional method) stays exit 0; both standing
real-world regressions re-run byte-identical (usesend SDK 73 commits/5
changes/exit 0, resend-node v4.6.0->v4.7.0 23 changes/exit 2).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
interface/type-literal property signatures and class property declarations
never had their `readonly` modifier captured or compared anywhere in the
structural differ, so a property gaining `readonly` between two snapshots
(same name, same type, same optionality) produced zero structural change --
invisible to every existing check. Confirmed as a real break against the
compiler: an existing write (`instance.prop = x`) that type-checked under
the old shape produces a real TS2540 under the new one.
New `readonly` field on MemberSurface (computed via a generic
hasReadonlyModifier() that works across class/interface/type-literal
property nodes), new `readonly-added` ApiChangeKind, wired into diffMembers
as a one-directional check -- only readonly-added fires as breaking;
dropping readonly only loosens caller obligations and is never flagged
(verified via a negative control).
Verified live: synthetic repro goes from "0 structural change(s)"/exit 0
(confirmed via git stash before the fix) to the correct readonly-added
finding/exit 2 after it; negative control (readonly removed) stays exit 0.
Both standing real-world regressions re-run unchanged -- usesend SDK
v1.6.0..v1.7.2 (73 commits, 5 structural changes, exit 0) and a freshly
re-cloned resend-node v4.6.0->v4.7.0 (23 structural changes, exit 2, same
citable catch, 0 new readonly findings in that range).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
MemberSurface never tracked a member's static-ness at all, so
`static send(a: string): void {}` -> `send(a: string): void {}` (same
name, same kind, same params, either direction) compared as zero
structural changes -- confirmed as a real break against tsc --strict
(`Property 'send' does not exist on type 'typeof Client'` /
`'Client'`) that the tool's own purpose is to catch, missed because
no field anywhere carried static/instance information.
Adds isStatic to MemberSurface (real value from classMembers, false
everywhere else since interfaces/type-literals/enums have no such
concept) and a new static-modifier-changed breaking ApiChangeKind in
diffMembers, scoped to parentKind === "class".
Verified live: a synthetic before/after git repo goes from exit 0 to
exit 2 in both directions (static->instance and instance->static),
each cross-checked against a real tsc --strict error; a negative
control (adding a second static method) stays exit 0. Both standing
real-world regressions re-run byte-identical: usesend SDK
v1.6.0..v1.7.2 (73 commits, 5 structural changes, exit 0) and
resend-node v4.6.0->v4.7.0 (23 structural changes, exit 2, same
citable catch, no new findings).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
typeText was captured for every property and function/method return type
but never once compared across snapshots (the one exception, enum member
values, compares a different field) -- so `name: string` -> `name: string |
undefined`, or `getName(): string` -> `getName(): string | undefined`,
printed "no structural change(s)" even though a real caller using the value
directly (`getName().toUpperCase()`) compiles under the old signature and
fails with a real TS2532/TS18048 under the new one.
New isNullableTypeNode() checks the real AST (not typeText string matching,
which would false-positive on e.g. Record<string, string | undefined>) for
a top-level union including undefined/null; wired into both diffMembers
(properties, methods) and diffSurfaces (top-level functions, consts,
non-object-shaped type aliases) via a new type-widened-nullable/breaking
ApiChangeKind.
Verified for real: synthetic repro (interface property + function return
type both widened to nullable) goes from exit 0 to exit 2 with correct
detail text; tsc --strict confirms the real break (TS2532) on a caller that
was valid before. Negative control (already-nullable export unchanged, plus
a brand-new nullable export) stays exit 0. Both standing real-world
regressions re-run byte-identical: usesend SDK v1.6.0..v1.7.2 (73 commits, 5
structural changes, exit 0) and resend-node v4.6.0->v4.7.0 (23 structural
changes, exit 2, same citable catch, 0 new nullable findings in that range).
npm run build clean.
TypeScript's standards-documented "nodenext"/"node16" module resolution
convention writes a relative import/re-export specifier with the compiled
output extension (e.g. `export { X } from "./foo.js"`) even though the real
source file on disk is `foo.ts`. Neither of this tool's two import-resolution
candidate lists (git.ts's resolveImport, used to decide which files get
pulled from git into a snapshot at all; apidiff.ts's resolveLocalImport, used
to resolve re-export/import chains within an already-materialized snapshot)
handled this, so any file reachable only through a `.js`-suffixed relative
import was silently never pulled into either snapshot — its whole exported
surface invisible to the structural diff on both sides, not just masked on
one.
Confirmed as a real, live gap against the real @octokit/core source (part of
this tool's own TypeScript-SDK-maintainer target audience), whose src/index.ts
has `import { VERSION } from "./version.js"` and `export type { OctokitOptions }
from "./types.js"`: before this fix, only 1 of 3 real files got pulled into
each snapshot (2 exported symbols reported unresolved); after, all 3. A
synthetic repro proved the actual missed break: a new required field added to
an interface re-exported only via a `.js`-suffixed specifier went from exit 0
("0 structural changes") to the correct exit 2 VERIFIED BREAKING CHANGE. A
negative control (same `.js`-specifier shape, safe additive field) stayed exit
0. Both standing real-world regressions re-verified byte-identical: usesend
SDK v1.6.0..v1.7.2 (73 commits, 5 structural changes, exit 0) and resend-node
v4.6.0->v4.7.0 (23 structural changes, exit 2, same citable catch).
npm run build clean. No test files added, per standing instruction — verified
by running the real CLI against real (@octokit/core) and synthetic git
history.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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>
A generic type parameter added to an exported interface/type-alias/
class/function with no default (or an existing one losing a default
it used to have) was invisible to the structural differ entirely --
confirmed as a real break directly against the compiler: adding a
second, no-default type parameter to `type Result<T>` turns
`const r: Result<string> = {...}` into a real
`error TS2314: Generic type 'Result' requires 2 type argument(s).`
even when the only new member it carries is optional, so the
existing field-level checks saw nothing to flag and the tool printed
"no breaking changes" for a genuinely breaking range.
New TypeParamSurface tracking + typeParamsNarrowed() in apidiff.ts,
wired into diffSurfaces() as a new type-param-narrowed ApiChangeKind.
Verified live: synthetic repro goes from exit 0 to exit 2 with the
right detail; negative control (new type param given a default)
stays exit 0; both standing real-world regressions re-run byte-
identical (usesend SDK v1.6.0..v1.7.2: 73 commits, 5 structural
changes, exit 0; resend-node v4.6.0->v4.7.0: 23 structural changes,
exit 2).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
diffMembers/diffSurfaces only checked for required parameters appended
past the old list's length (newlyAddedRequiredParams) or for the list
getting strictly shorter (arityNarrowed) -- neither catches the common
real-world edit of tightening an *existing* parameter in place, e.g.
sendEmail(to, subject?) -> sendEmail(to, subject), where the parameter
count is unchanged on both sides.
Confirmed as a real break directly against the compiler: a synthetic
repro (sendEmail(to, subject?) -> sendEmail(to, subject), committed as
a mislabeled "fix:") produced a real `tsc --strict` error
(TS2554: Expected 2 arguments, but got 1) against a call site that was
valid under the old signature; before this fix surfacenotes printed
"API diff found 0 structural change(s)" and exited 0 for that exact
range.
New paramNarrowedToRequired() in src/apidiff.ts matches old/new
parameters by position (not name) and flags any overlapping index
where optional flips to required, wired into both the method-member
diff and the top-level function diff via a new
"param-became-required"/breaking ApiChangeKind.
Verified live: the repro now exits 2 with the correct detail; same
check verified on a class-method signature too. Negative control
(adding a new optional parameter) still exits 0. Both standing
real-world regressions re-run unchanged: usesend SDK v1.6.0..v1.7.2
(73 commits, 5 structural changes, exit 0) and a freshly re-cloned
resend-node v4.6.0->v4.7.0 (23 structural changes, exit 2, same
citable catch). npm run build clean. No test files added, per
standing instruction -- verified by running the real CLI against
real and synthetic git history.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
`export default X` was completely invisible to the structural differ in
two distinct ways: the separate `class Foo {}; export default Foo;`
assignment form (an ExportAssignment node, never matched by any branch of
collectExports) was dropped entirely, and the inline `export default class
{...}` / `export default function () {}` anonymous-declaration form was
also dropped since the code keyed exports by `stmt.name.text` and an
anonymous default declaration has no name. Both are real, common shapes for
exactly the SDK client-class pattern this tool targets (e.g. stripe-node's
historical `export default Stripe;`).
Both forms are now resolved into a "default" entry and run through the
same diffMembers/diffSurfaces machinery as every other export, so removed
members, new required params, etc. on a default export are caught instead
of silently passing as "no breaking changes."
Verified live: synthetic repro (class only reachable via `export default`,
not also named-exported) went from exit 0 / "0 structural change(s)" before
this fix to exit 2 with the correct new-required-param detail after it;
confirmed on git stash before/after. Anonymous `export default class {}`
form verified the same way. Negative control (safe additive member added
to a default-exported class) stays exit 0. Both documented real-world
regressions re-run unchanged: usesend SDK v1.6.0..v1.7.2 (73 commits, 5
structural changes, exit 0) and resend-node v4.6.0->v4.7.0 (23 structural
changes, exit 2). npm run build clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
classMembers() only matched MethodDeclaration, PropertyDeclaration, and
ConstructorDeclaration -- get/set accessors fell through every branch and
were silently dropped from the structural surface on both sides of a diff.
Confirmed as a real false negative via a synthetic repro: removing an
exported class's only public member, `get apiVersion(): string`, printed
"0 structural change(s)" and a clean "API verified: no breaking changes"
banner, exit 0 -- a genuine breaking removal (every external
`instance.apiVersion` read now fails to type-check) invisible to the one
tool whose job is to catch exactly that.
classMembers() now merges get/set accessors sharing a name into a single
MemberSurface (preferring the getter's return type, matching how
TypeScript itself presents them to a reader), so removal, addition, and
type changes all flow through the existing diffMembers() machinery
unchanged.
Verified for real: the removal repro now correctly fires
member-removed/breaking and exits 2; a negative control adding a second,
unrelated getter still exits 0 with a safe member-added change (no
over-flagging). Both documented real-world regressions re-run
byte-identical: usesend SDK v1.6.0..v1.7.2 (73 commits, 5 structural
changes, exit 0) and a freshly re-cloned resend-node v4.6.0->v4.7.0 (23
structural changes, exit 2). `npm run build` clean. No test files added,
per standing instruction -- verified by running the real CLI against real
and synthetic git history.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
diffMembers never compared an enum member's underlying value between two
snapshots, only its name -- so inserting a member above an auto-numbered
one (the classic `enum Direction { Up, Down, Left, Right }` -> inserting
`New` above `Down` silently renumbers Down/Left/Right) printed "no
structural API changes" even though every stored/compared value downstream
shifted. Confirmed via a synthetic repro: before this fix, the insertion
case exited 0 with zero findings; after, it correctly fires 3
`enum-value-changed`/breaking findings naming the exact old->new value for
each shifted member and exits 2. An append-only addition (no renumbering)
correctly stays exit 0 as a negative control.
New `enumMembers()` in src/apidiff.ts computes each member's real effective
value (explicit literal, or `previousNumeric + 1` for TS's actual
auto-numbering rule) instead of the literal initializer text, so two
enums that are both "auto" on paper but differently numbered at runtime no
longer compare as identical. Falls back to `"auto (unresolvable)"` and
skips the comparison when TS's own auto-numbering rules don't resolve
cleanly (e.g. no initializer directly after a string-valued member),
consistent with this differ's documented heuristic scope.
Re-ran both documented real-world regressions unchanged: usesend SDK
v1.6.0..v1.7.2 (73 commits, 5 structural changes, exit 0) and a freshly
re-cloned resend-node v4.6.0->v4.7.0 (23 structural changes, exit 2, same
citable catch). npm run build clean. No test files added, per standing
instruction -- verified by running the real CLI against real and synthetic
git history.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
generate only diffs refs that already exist, so a breaking edit isn't
caught until someone remembers to run it against a tag. watch diffs a
baseline ref against the live working tree (uncommitted edits included)
and re-checks on every source-file save, printing a report straight to
the terminal -- no files written, no git state touched.
Reuses the existing diffApiSurfaces/materializeSnapshot machinery
unchanged; only the "to" side now points at the real files on disk
instead of a second git ref. Change detection prefers native recursive
fs.watch and falls back to directory-signature polling on platforms
that don't support it (e.g. Linux inotify), so the feature behaves the
same everywhere the CLI installs.
Verified live against a real synthetic repo while the watch process was
running (not mocked): a saved edit adding a new required interface
field was caught mid-run and printed the correct breaking-change
banner; a follow-up additive edit on the same running process correctly
downgraded to "safe"; Ctrl+C (SIGINT) stopped it cleanly. Re-ran the
existing `generate` regression (usesend SDK v1.6.0..v1.7.2, 73 commits,
5 structural changes, exit 0) unchanged. `npm run build` clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
git.ts: existsAtRef used `git cat-file -e`, which succeeds for tree
(directory) objects too, not just blobs. When a relative import resolved to
a real directory before falling through to its `.ts`/`index.ts` candidates,
the directory's `git show` listing got written to disk as a fake file at
the exact path the real files inside it needed, crashing materializeSnapshot
with EEXIST. Fixed by checking `git cat-file -t` returns `blob`.
apidiff.ts: converting `interface X {...}` to `type X = {...}` (or the far
more common `type X = {...} & OtherNamedType` mixin pattern) was flagged as
a breaking "kind change" even when the member shape was identical. Added
objectShaped tracking (isObjectShapedTypeNode/objectShapedMembers, handles
plain type literals and intersections, excludes unions/function/mapped
types) so a pure syntax conversion falls through to the real member diff
instead of being misreported — which is what correctly surfaces a real
field-removal finding instead of masking it behind a vague message.
Found both bugs, and the real citable catch now in the README, by scanning
every real patch/minor tag pair in resend-node's actual history (102 pairs,
no cherry-picking): v4.6.0->v4.7.0 (PR #535, shipped as a minor) silently
converted 22 response types from independently-nullable data/error fields
into a real discriminated union -- a genuine breaking type change with no
BREAKING CHANGE footer. Re-ran the full 102-pair scan after both fixes:
zero crashes, zero remaining kind-change false positives.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Surfacenotes generates CHANGELOG.md/RELEASE_NOTES.md from a git commit
range like other changelog tools, but it also parses the package's
public entry file with the real TypeScript compiler at both refs,
structurally diffs the exported API surface, and cross-checks that
against the conventional-commit labels in the same range. A mislabeled
"fix:" that actually removes an export or adds a required parameter
gets a loud warning banner instead of a quiet lie.
Verified against the real git history of the usesend-js SDK
(v1.6.0..v1.7.2, 73 real commits) and against a small synthetic repo
built to prove the breaking-change detector fires correctly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>