31 Commits

Author SHA1 Message Date
5822bfaa31 fix: flush a pending debounced diff before stopping watch mode
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).
2026-10-29 16:23:52 +03:00
003d9acfa1 fix: serialize CHANGELOG/RELEASE_NOTES read-merge-write behind a lock to prevent a concurrent-generate lost-update race
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.
2026-10-29 16:14:18 +03:00
144e7ed11f fix: add timeout and response-size cap to the AI narrative network call
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.
2026-10-29 16:02:53 +03:00
8a2903b049 fix: detect index signature removal and value-type changes
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>
2026-10-29 15:54:50 +03:00
420ed76788 fix: don't let a plain version match collide with its own prerelease/hotfix suffix in CHANGELOG merge
mergeChangelogFile's heading regex used a \b word-boundary after the
version string, but \b also fires between a digit and a following "-"
-- so version "1.7.2" matched the heading "## 1.7.2-hotfix.1 -- <date>"
too. Re-running generate for the plain version silently replaced (not
appended after) the unrelated, already-shipped prerelease/hotfix
section instead of leaving it alone, destroying real prior release
history -- the exact failure class this merge function exists to
prevent. Require the version to be followed by whitespace or
end-of-line instead of a bare \b boundary.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-29 15:35:51 +03:00
29a7587aeb fix: detect lost overload signatures on interface and type-literal methods
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>
2026-10-29 15:17:55 +03:00
f0ec8e358a fix: resolve export * as NS namespace re-exports in the structural differ
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).
2026-10-29 15:08:21 +03:00
5311c8005b docs: correct README claiming --ai pass isn't wired up (it shipped 2026-10-27)
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>
2026-10-29 14:59:38 +03:00
28ee0c642d docs: document CHANGELOG.md history-preserving merge behavior
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-29 14:47:20 +03:00
1c0350c6e7 fix: preserve prior release history in CHANGELOG.md/RELEASE_NOTES.md
generate previously overwrote both files on every run with writeFileSync,
silently destroying every previously-recorded release the moment the next
one was generated into the same --out-dir. Confirmed live: running
v1.6.0..v1.6.1 then v1.6.1..v1.6.2 into the same dir left CHANGELOG.md
containing only the v1.6.2 section, v1.6.1 gone without a trace -- a real
problem for a tool whose whole premise is a growing changelog across
releases, not a one-shot report.

New mergeChangelogFile() in changelog.ts prepends the freshly rendered
entry above whatever already exists, searching only by the "## <version>"
heading (not the full heading+date) so re-running generate for the same
version on a different day replaces that version's section in place
instead of duplicating it. Verified for real: three sequential runs
(v1.6.0->v1.6.1->v1.6.2->v1.6.3) against the real usesend SDK history
all three version headings end up present and in reverse-chronological
order; re-running the last one again leaves exactly one v1.6.3 heading
(no duplicate). Both standing 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).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-29 14:46:55 +03:00
340373e598 fix: detect removed method-shorthand members on object-shaped type aliases
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>
2026-10-29 14:35:12 +03:00
d38fbe506c fix: flag a property gaining the readonly modifier as breaking
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>
2026-10-29 14:21:36 +03:00
be96e2f9b5 fix: detect a class member flipping between static and instance
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>
2026-10-29 13:58:31 +03:00
c67b929a6d fix: detect a property/return type widening to include undefined/null
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.
2026-10-29 13:45:04 +03:00
8c52f7245c fix: resolve .js/.mjs/.cjs-extension relative imports to their real .ts source
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>
2026-10-29 13:35:27 +03:00
8a791795e6 fix: detect lost call signatures in overloaded functions/methods
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>
2026-10-29 13:22:38 +03:00
0b7597978e fix: catch a new/un-defaulted generic type parameter as breaking
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>
2026-10-29 12:25:33 +03:00
fdfcc9f634 fix: catch an existing parameter narrowed from optional to required
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>
2026-10-29 11:44:18 +03:00
c8bd37a826 fix: stop the word "default" from masking real breaks on default exports
verify()'s per-symbol declared-breaking check (1b21879) compares a
breaking change's root symbol name against each declared-breaking
commit's text via a plain substring match. For every other export this
is safe because the root symbol is a real identifier from the package's
own source. For `export default ...` (support added the same day in
5d2a88a) the root symbol is always the literal generic placeholder
"default" -- an ordinary English word that shows up constantly in
unrelated commit messages ("change default timeout", etc.) -- so any
unrelated declared-breaking commit in the same release that happens to
use the word "default" silently masked a real, separately-committed,
mislabeled break on the actual default-exported symbol.

Confirmed live with a synthetic repro: a default-exported class gaining
a new required parameter via a mislabeled `fix:` went from a correct
exit 2 to an incorrect exit 0/"no breaking changes" purely because an
unrelated `feat!: change default timeout from 30s to 10s` commit existed
in the same range. Fixed by requiring the more specific two-word phrase
"default export" when the root symbol is "default", instead of the bare
word. Verified: the masking repro now correctly exits 2; a positive
control ("fix!: default export now requires an apiKey") still correctly
suppresses the warning; both standing real-world regressions re-run
unchanged (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). `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>
2026-10-29 11:15:55 +03:00
5d2a88a3b3 fix: detect default exports, incl. anonymous export default class/function
`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>
2026-10-29 10:55:06 +03:00
60fca38091 fix: detect removed/changed class get/set accessors
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>
2026-10-29 10:22:22 +03:00
d61842760c fix: detect enum member value shifts, incl. auto-numbering renumber bug
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>
2026-10-29 08:51:52 +03:00
1b218791f1 fix: stop one declared-breaking commit from masking a different real break
verify() previously computed a single release-wide claimedSeverity ("did
any commit in this range declare breaking?") and suppressed the undeclared-
breaking-change warning for the whole release if so. That let an unrelated
commit with `!`/BREAKING CHANGE cover a completely different, mislabeled
`fix:` commit's real structural break in the same range -- the exact "quiet
lie" this tool exists to catch, reproduced live: a repo with one commit
declaring an unrelated CLI-flag breaking change and a second, separate
`fix:` commit that actually added a required field to an exported
interface generated a clean "API verified: no breaking changes" banner and
exit 0.

verify() now checks each breaking ApiChange individually against whether
any declared-breaking commit's own text actually names that change's root
exported symbol, instead of trusting a single boolean for the whole range.
Verified for real: the masking repro above now correctly fires the
VERIFIED BREAKING CHANGE banner naming the right symbol and exits 2; a
negative control where the declared-breaking commit does name the broken
symbol still exits 0; both documented real-world regressions re-run
unchanged (usesend SDK v1.6.0..v1.7.2: 73 commits, 5 structural changes,
exit 0; resend-node v4.6.0->v4.7.0 freshly re-cloned: 23 structural
changes, exit 2, byte-identical CHANGELOG.md).
2026-10-29 08:04:07 +03:00
a419dd5e1b feat: add surfacenotes watch local dev-loop mode
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>
2026-10-29 06:53:06 +03:00
466f99f66f fix: catch breaking changes from a shrinking parameter list
diffMembers/diffSurfaces only checked for newly *added* required
parameters, never for the parameter list getting shorter. TypeScript
enforces a hard max-argument-count for any non-rest signature
("Expected N arguments, but got M") -- confirmed directly against
tsc --strict with a synthetic before/after -- so dropping a trailing
parameter (even one that was previously optional) is a real breaking
change for existing call sites, and surfacenotes was reporting "no
breaking changes" for exactly that case.

New arityNarrowed() fires when the new param list is strictly shorter
than the old one, skipped entirely when either signature has a rest
parameter (which removes the fixed-arity ceiling this depends on).
Wired into both the method-member diff and the top-level function diff.

Verified for real: a synthetic repro shrinking sendEmail(to, subject,
body) to sendEmail(to, subject), committed as a mislabeled `fix:`,
went from exit 0 / "no breaking changes" to exit 2 with the correct
"now takes only 2 parameter(s), down from 3" detail. Negative control
with a rest parameter absorbing the removed arg still exits 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).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-29 05:08:28 +03:00
4fc316420b fix: stop miscounting function params whose type text contains a comma
paramsSignature() serialized each parameter into a joined "name:type, name:type"
string, and both diffMembers() and diffSurfaces() re-split that string on ", " to
detect newly-added required parameters. Any parameter whose own type text contains
a comma (a two-arg generic like Map<string, number>, an inline object-type literal
with multiple properties, a tuple, etc.) got re-split into fake extra "parameters",
corrupting the count.

Confirmed as a real false positive via a synthetic repro: adding a harmless optional
b?: Map<string, number> property to an existing object-typed function parameter was
misread as "gained a new required parameter" and fired the tool's own "VERIFIED
BREAKING CHANGE" banner (exit 2) for a change that was 100% additive -- exactly the
kind of lie this tool exists to catch, now coming from the tool itself.

Fix: track each parameter as structured data (new ParamSurface: name/optional/type)
throughout, never a flattened string. collectParams() replaces the string-returning
paramsSignature() as the source of truth for comparisons; paramsSignature()/
formatParams() now only produce the display string, never fed back into a diff.
newlyAddedRequiredParams() compares the real param lists directly.

Verified: synthetic repro goes from exit 2 (false positive) to exit 0 (correct);
negative control with a genuinely new required param after a comma-containing type
still correctly fires exit 2; both previously-documented real-world regression
checks 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,
identical before/after this change via git stash comparison). npm run build clean.
2026-10-29 02:38:19 +03:00
f25b336a55 fix: flag new required interface/type-alias members as breaking
diffMembers always marked a newly-added member as severity "safe",
even on an interface or object-shaped type alias. A brand new
non-optional field on those shapes breaks every caller that builds
the shape via an object literal (const x: Foo = {...}), since
TypeScript will now reject it for missing the new required key --
the exact same caller impact as the optional-to-required transition
already handled a few lines above. Classes are left alone (adding a
member to a class is genuinely additive for its callers).

Verified with a real before/after repro: v1.0.0 added SendOptions{to,
subject}, v1.1.0 added a new required idempotencyKey field, committed
as a (mislabeled) `fix:` with no `!`/BREAKING CHANGE footer -- exactly
the false-negative shape this tool exists to catch. Before this fix
the diff reported "member-added / safe" and exited 0; after the fix
it reports "required-field-added / breaking" with the correct detail
message and exits 2. Negative control (same repro but the new field is
optional) still exits 0. Class negative control (new class member)
still exits 0. Re-ran both previously-documented real-world regression
checks 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 (still fires, exit 2,
same 22-response-type interface->typeAlias catch). npm run build clean.
2026-10-28 02:51:42 +03:00
e798026216 fix: resolve re-exported types that are only import'd, never declared
collectExports previously only resolved a bare `export { X }`/`export
type { X }` (no "from" clause) by looking for a direct local
declaration of X in the same file. A common real barrel pattern —
`import type { Foo } from "./types"; export type { Foo };` — has no
local declaration at all, so X silently landed in unresolvedWarnings
and the structural differ never saw it: a false negative, the failure
mode worse than a false positive for a tool whose entire point is
catching undeclared breaking changes.

New findImportSource() scans the file's own import declarations (incl.
`import { Foo as Bar }` aliasing) to find where a bare re-export's
symbol actually came from, then recurses through collectExports on
that target file — same recursion already used for `export {X} from
"./y"` barrels, just triggered from the import side instead of the
export side.

Verified: a synthetic repo reproducing the exact pattern (interface
gains a new field via an import-then-bare-export barrel) went from "0
structural changes, 2 unresolved" to "1 structural change, 0
unresolved" after this fix. Re-ran both existing real-world regression
checks unchanged: the usesend SDK v1.6.0..v1.7.2 demo (73 commits, 5
structural changes, byte-identical to before) and the real resend-node
v4.6.0->v4.7.0 citable catch (still fires: CreateApiKeyResponse/
ListApiKeysResponse interface->typeAlias kind change, exit 2). npm run
build clean.

Separately noticed, not fixed (out of scope for this change, noting
honestly rather than silently expanding scope): diffMembers always
marks a newly-added non-optional interface/type member as severity
"safe" — a brand new required field is actually breaking for literal-
constructing callers, same category of bug as this one but a different
code path. Left for a future pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-27 23:59:22 +03:00
2ee89cc04c feat: optional --ai narrative pass, fed only deduplicated commit bullets
src/ai.ts: resolveAiConfig() reads SURFACENOTES_AI_BASE_URL/API_KEY (any
OpenAI-compatible endpoint), SURFACENOTES_AI_BASE_URL=ollama for local
models, or a plain OPENAI_API_KEY — returns null (not a throw) when
nothing is configured. generateNarrative() posts only the already-grouped,
already-deduplicated commit bullets this tool already extracted (never
raw commits/diffs, the exact anti-hallucination constraint the original
research behind this project flagged as mandatory) to /chat/completions,
and returns null on any network/API failure instead of crashing.

cli.ts: new --ai flag wires this in; changelog.ts renders the result as
a clearly-labeled "AI-generated summary... not used for the verified
check" section so it can never be mistaken for the structural-diff
verification that is this tool's actual differentiator.

Verified for real: baseline run (no --ai) byte-for-byte unaffected;
--ai with no env configured warns and degrades to structured-only output,
exit 0; --ai against a real local mock OpenAI-compatible HTTP server
correctly posted exactly the 22 deduplicated bullets (not the raw 73
commits or any diff) and the real response landed in CHANGELOG.md;
resolveAiConfig's 4 branches (unset/OpenAI-key-only/ollama-shortcut/
custom-endpoint) unit-checked directly. npm run build clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-27 23:42:02 +03:00
e83a2f2aea fix: directory-vs-blob crash and interface/typeAlias false positive in the structural differ
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>
2026-10-27 02:35:16 +03:00
507427c4ae feat: verified-breaking-change changelog generator for TypeScript SDKs
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>
2026-10-26 15:54:44 +03:00