@4da/mcp-server 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -1,5 +1,173 @@
 # Changelog
 
+## 6.2.0 — 2026-10-11
+
+### `dependency_check`: the release-age hold no longer leaves only vulnerable choices
+
+The 3-day hold on new releases is waived for a clean version when every safe
+release on its line is inside the hold too and every older release on that line
+has a known advisory: holding back would leave only vulnerable releases to
+write. The `release_age` signal then says `proceed` with
+`hold_waived: "no_settled_safe_release"`, names the line and the count of
+vulnerable older releases, and asks the agent to tell the user the version's
+age. A package whose only releases are new keeps the hold (that is the
+supply-chain case it exists for). Found by G7 (golang.org/x/net on 2026-10-11:
+the only safe releases were 1.8 and 2.8 days old, 59 of 61 v0 releases were
+vulnerable, and every run left go.mod unchanged).
+
+### `dependency_check`: PyPI and Go, safe versions in a constraint, and instructions that make agents call it
+
+The G7 agent evaluation (49 dependency tasks x 3 trials, 2026-10-11) found that
+when an agent called a 4DA tool, 0 of 60 runs wrote a vulnerable version, and
+when it did not, 41 of 78 did. The misses were runs that never called one:
+PyPI and Go adds (`dependency_check` took npm and crates.io only), pin tasks
+("pin ws 7.x" wrote 7.5.10 from memory; body-parser 1.20.3), and agents told
+they could not browse concluding they could not check versions at all.
+
+- **PyPI.** Releases, upload times and yanks from the PyPI JSON API (a release
+  is yanked when every file is; one with no files is not installable), PEP 440
+  ordering, OSV.dev for the exact version.
+- **Go.** Versions from proxy.golang.org, each judged version's date from its
+  `.info` (the list has none), `retract` directives in the latest go.mod
+  reported like a yank, `+incompatible` releases matched (`v2.0.0` finds
+  `v2.0.0+incompatible`), pseudo-versions dated and judged, and a major 2+
+  without its `/vN` path named as the different module it is.
+- Signals the registry cannot supply (publisher trust, install scripts, new
+  transitive dependencies on PyPI and Go) say "not applicable" with the
+  reason, never a made-up value or an `unknown` that blocks the verdict.
+- **Constraints.** `to` may be the constraint the agent was given: `"7.x"`,
+  `"^1.20"`, `"=0.17"`, `"~=3.1"`, `"3.1.*"`, `">=2,<3"`, `"v1"`. The item then
+  returns `range_check` (`smallest_safe_in_range`, `newest_safe_in_range`,
+  `safe_versions`, `smallest_safe_upgrade` above `from`), from every advisory
+  OSV.dev lists for the package evaluated against each release the constraint
+  admits, and the verdict is given for the version it picks: the smallest safe
+  upgrade above `from`, else the newest safe release past the 3-day hold. An
+  exact `to` an advisory affects gets the same `range_check` over its own line,
+  so "is ws 7.5.10 safe?" answers avoid and names 7.5.11. Withdrawn and
+  deprecated releases are never picked; maintenance notices do not make a
+  release unsafe. When nothing in the constraint is safe, the advisories that
+  affect all of it and the newest safe release outside it are named. A test
+  holds the local range evaluation to OSV.dev's own per-version answers on
+  recorded data (ws, Jinja2, golang.org/x/net).
+- **Instructions and descriptions.** The server instructions now open with
+  the rule "before writing any dependency version into a manifest or
+  lockfile, call dependency_check on that exact version, or on the constraint
+  you were given", name add / pin / upgrade / bump / downgrade / choose a
+  version for all four ecosystems, and say the server reads the registries
+  for the agent (so "I cannot browse" is not a reason to skip it).
+  `vulnerability_scan` says it judges installed versions and points at
+  `dependency_check` for a version about to be written.
+- The manifest-edit hook names a `dependency_check` call for PyPI and Go edits
+  too, and passes a range edit (`^7.0.0`) as a constraint instead of dropping it.
+- `ecosystem` is matched case-insensitively (`pypi`, `go`).
+
+### `upgrade_impact` reads PyPI and Go
+
+Until 6.1 it answered for npm and crates.io only, and pointed Python and Go
+upgrades at the briefing.
+
+- **PyPI.** Versions, publish dates and yanks from the PyPI JSON API, ordered
+  by PEP 440 (`2.0`, `3.0.0rc1` and `1.0.post1` are releases, not unreadable
+  semver); a two-part version such as pydantic `2.0` is that release, not a
+  line. The changelog is read from the target release's sdist on
+  files.pythonhosted.org (`CHANGES.rst`, `HISTORY.md`, ...); a release with
+  wheels only says so. Import sites are matched on the MODULE the
+  distribution installs, established from the project's virtualenv metadata
+  (`.venv` / `venv` / `env`: `top_level.txt`, else `RECORD`), else a table of
+  well-known differences (`PyYAML` -> `yaml`, `beautifulsoup4` -> `bs4`,
+  `Pillow` -> `PIL`), else the distribution name, which the answer labels an
+  assumption (`your_code.import_name_source`, `import_name_note`) instead of
+  guessing silently.
+- **Go.** Versions from proxy.golang.org (`/@v/list`, dates from `.info`), the
+  changelog from the module zip. A major version 2+ is a different module
+  path: `github.com/jackc/pgx/v4` -> `v5.0.0` reads the `/v5` module, lists
+  the rest of the v4 line and the v5 releases crossed, and reports
+  `module_path_change` with the files that import the old path. An up-to-date
+  module whose next major exists says so (`newer_major_module`). Import sites
+  come from `import "module/..."` specs, never counting another major's path.
+- The parser reads reStructuredText changelogs: titles underlined (or over-
+  and underlined) with any RST adornment, their `Released <date>` lines, and
+  non-release setext/RST titles as sub-headings. `CHANGELOG_PARSER_VERSION` is
+  4 (with the classifier changes below), so changelogs cached by 6.1 are re-read.
+- A zip reader (central directory only, stored and deflate entries, every
+  inflate capped) for Go module zips and zip sdists.
+
+### GitHub release notes, opt-in (`FOURDA_GITHUB_CHANGELOG`)
+
+Off by default: the default contract is unchanged, and only the package's
+own registry and OSV.dev are contacted. With `FOURDA_GITHUB_CHANGELOG=true`,
+when the archive has no changelog for the range, `upgrade_impact` reads the
+repository's GitHub releases (for PyPI, first a changelog file the project
+links on GitHub in `project_urls`), with the same parser and classifier.
+
+- The repository comes from registry metadata; for Go from the proxy's
+  recorded VCS origin, so vanity paths (`google.golang.org/grpc`) and
+  multi-module repositories (`service/s3/v1.50.0` tags) resolve. Monorepo tags
+  for other packages are skipped.
+- Unauthenticated REST API, or `GITHUB_TOKEN` when set. A rate limit is
+  reported with its reset time and how to raise it, and is not cached.
+  Results are cached under a key that carries `CHANGELOG_PARSER_VERSION`.
+- With the fallback off and no usable changelog, the answer says the
+  changelog is unavailable and gives `github_fallback.how_to_enable` (or says
+  enabling it would not help: no GitHub repository). `_meta.sources` and
+  `_meta.privacy` name GitHub whenever it was contacted.
+
+### Breaking-entry precision gate (G3)
+
+A held-out panel, re-measured by the test suite on every run
+(`src/__tests__/g3-breaking-precision.test.ts`, fixtures in
+`src/__tests__/fixtures/g3/`): 40 real upgrade pairs, 10 each from npm,
+crates.io, PyPI and Go, none of them a package the 6.1 rules were built on.
+Each pair records the changelog source the tool read live (registry archive or
+GitHub releases), trimmed to the range and checked to parse identically. Gold
+for each of the 1,618 entries shown is the majority of three blind raters
+working to a written rubric (`rubric.txt`), each label backed by a verbatim
+quote from the entry (Fleiss kappa 0.984; the raters were model instances,
+so agreement may be higher than independent human raters would reach). The
+test fails below 90% precision, overall or on the held-out half, and on any
+entry without a label.
+
+| | flagged | precision | recall |
+|---|---|---|---|
+| 6.1 rules, all 40 pairs | 246 | 94.7% | 55.0% |
+| 6.1 rules, 20 held-out pairs | 108 | 95.4% | 67.8% |
+| 6.2 rules, all 40 pairs | 326 | 97.2% (95% CI 94.8-98.5) | 74.8% |
+| 6.2 rules, 20 held-out pairs | 115 | 94.8% (95% CI 89.1-97.6) | 71.7% |
+
+The 6.2 rule changes were made from the 20 dev pairs' errors only:
+
+- An API change is read under any heading but a fix one. Covered: a leading
+  removal or rename of something API-shaped ("remove UMD build"), a changed
+  default, a type made private, a move or replacement, keyword-only
+  arguments, "now ... instead of", and "no longer comparable / usable /
+  subclasses".
+- Dropped runtimes and raised minimums break whatever the reason given
+  ("drop node 10.x to upgrade dev dependencies", "Replace go 1.21 with go 1.22
+  in go mod").
+- "Other Changes" / "Misc" headings are neutral, not additive: pgx 5 filed its
+  type removals there.
+- Fix headings are their own context.
+- "Previously-deprecated APIs have been removed" is a removal list.
+- `*Backwards-incompatible*` is an explicit marker.
+- Link targets, bare URLs and GitHub's "by @user in <PR>" are dropped before
+  classifying (a `go.dev/doc/...` link read "Drop support for Go 1.21" as a
+  docs change); RST ``literals`` read as code.
+- No longer breaking: entries that say they still work or have no effect on
+  users, private modules and `_names`, removing a deprecation notice,
+  restoring an API, relaxing a bound, renaming the repository, swapping a
+  dependency crate, and changes scoped to an example, docs or CI.
+
+Per ecosystem over all 40 pairs: npm 99.0% / 84.2%, crates.io 99.0% /
+81.3%, PyPI 95.7% / 72.5%, Go 92.0% / 54.1% (Go's GitHub release notes are
+largely PR titles and prose). `CHANGELOG_PARSER_VERSION` is 4.
+
+### Hook and briefing
+
+- The manifest-edit hook names the exact `upgrade_impact` call for
+  `pyproject.toml`, `requirements.txt` and `go.mod` edits (`ecosystem: "PyPI"`
+  / `"Go"`); `what_should_i_know`'s next step for a PyPI or Go package is
+  `upgrade_impact`.
+
 ## 6.1.0 — 2026-10-10
 
 Fixes from an agent eval over stdio JSON-RPC against real projects (2026-10-07)

package/README.md

@@ -112,23 +112,25 @@ Measured against osv-scanner on 19 public repositories (npm, pnpm v5-v9, yarn v1
 
 - **OSV.dev** for known vulnerabilities, matched to exact installed versions
 - **npm registry, crates.io, PyPI, Go module proxy** for versions, deprecations and yanks
-- **The package's own registry archive** (registry.npmjs.org, static.crates.io) for the changelog `upgrade_impact` reads; never GitHub
-- **npm full packument** and the **crates.io versions API** for `dependency_check` (publish times, publishers, install scripts, per-version dependencies). These requests carry the package name only; the version you have installed is never sent to a registry. Packuments are cached on disk and revalidated with `If-None-Match`; crates.io API reads are spaced one per second.
+- **The package's own registry archive** (registry.npmjs.org, static.crates.io, files.pythonhosted.org, proxy.golang.org) for the changelog `upgrade_impact` reads; GitHub only if you opt in with `FOURDA_GITHUB_CHANGELOG=true` (below)
+- **npm full packument**, the **crates.io versions API**, the **PyPI JSON API** and the **Go proxy's version list** for `dependency_check` (publish times, yanks and retractions; on npm and crates.io also publishers, install scripts, per-version dependencies). These requests carry the package name only; the version you have installed is never sent to a registry, except that the Go proxy's list has no dates, so it is asked for the `.info` of the versions being judged (the same request `go get` makes). OSV.dev's advisory list for the package lets `dependency_check` name the safe releases in a constraint. Packuments are cached on disk and revalidated with `If-None-Match`; crates.io API reads are spaced one per second.
 - **Hacker News Algolia API**, only when you call `ecosystem_pulse`
 
 Results are cached (24h for registry data, 1h for vulnerabilities, 30min for news) and rate-limited per source.
 
 **What's sent over the network:** package names and versions (the same data visible in your lockfile), and, only for `ecosystem_pulse`, the names of a few of your dependencies as search terms. No source code, no file paths, no personal data. The call-site scan of `upgrade_impact` runs locally. Set `FOURDA_OFFLINE=true` to disable all network calls.
 
+**GitHub release notes (opt-in, off by default).** Many packages ship no changelog in their registry archive (vite, zod, cobra, most Go modules). With `FOURDA_GITHUB_CHANGELOG=true` in the server's environment, `upgrade_impact` reads the repository's GitHub releases when the archive has no changelog for the range (for PyPI, first a changelog file the project links on GitHub from its `project_urls`). GitHub then receives the repository name and the versions, nothing else. It uses the unauthenticated REST API (60 requests an hour) or `GITHUB_TOKEN` when set (5,000); a rate limit is reported with its reset time, never retried in a loop, and results are cached. With it off, an answer without a changelog says so and names the setting; nothing is guessed.
+
 **What's written to disk, and where:** only files the server owns, in its folder in your user data directory (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp` or `~/.local/share/4da-mcp`; `FOURDA_MCP_HOME` moves it): `cache.db` (registry, OSV and changelog responses; safe to delete) and `standalone.db` (without the desktop app: your project scan and the decisions, agent memory and feedback you record). Nothing is written inside your repository.
 
 When the 4DA desktop app is installed, the server reads the app's database (`4da.db`) through a **read-only** connection and never creates or alters anything in it: no tables, no columns, no cache. The only writes are rows in the four app-owned tables the tools exist to fill, so the app sees them: decisions (`decision_memory` -> `developer_decisions`), agent memory (`agent_memory`), and feedback (`record_feedback` -> `interactions` and `feedback`, which the app's calibration reads). Those go through a separate write connection that waits briefly for the app's lock. If your app version lacks the table or a column a record needs, the record goes to `standalone.db` instead and the response says so in `_meta`. (Before 6.1 the server also created a `live_cache` table inside the app's database; it now keeps that cache in `cache.db`.)
 
 > The one exception: if you *explicitly* configure an OpenAI embedding provider (`FOURDA_EMBED_PROVIDER=openai`) for semantic recall, the decision/memory text you store is sent to OpenAI to be embedded. The default — no embedding provider, or a local Ollama one — keeps everything on your machine, and `FOURDA_OFFLINE=true` overrides it regardless.
 
-**Ecosystems supported:** npm, crates.io (Rust), PyPI (Python), Go. `upgrade_impact`: npm and crates.io.
+**Ecosystems supported:** npm, crates.io (Rust), PyPI (Python), Go. `upgrade_impact` reads all four. PyPI: versions and dates from the PyPI JSON API, the changelog from the release's sdist, and import sites matched on the module the distribution installs: read from your virtualenv's metadata (`.venv`, `venv`, `env`: `top_level.txt` or `RECORD`), else a table of well-known differences (`PyYAML` -> `yaml`, `Pillow` -> `PIL`), else the distribution name, which the answer then labels an assumption. Go: versions and dates from proxy.golang.org, the changelog from the module zip, and a major version 2+ reported as the module path change it is (`github.com/jackc/pgx/v4` -> `/v5`), with the files that import the old path. `dependency_check` reads all four too; on PyPI and Go, where the registry exposes no publisher identity or install hooks, those signals say "not applicable".
 
-**Known limits, stated plainly:** a `requirements.txt` without a lockfile names only your direct pins, so their transitive dependencies are not scanned (use `uv lock`, `poetry lock` or `pip-compile`). Many packages ship no changelog in their registry archive (fastembed, vite, zod among them); `upgrade_impact` then says so and gives the release-notes URL instead of guessing. Breaking entries are flagged from the changelog's headings and wording, and every entry carries the heading it sits under (`under`). Measured on 47 upgrades never used to build the rules, against three blind raters who saw each entry's heading: 99% of entries flagged breaking were breaking (95% CI 95-100%) and about 65% of breaking entries were flagged. Earlier corpora, before the last parser fixes, measured 73-87%, so treat the flags as a pre-sort: read every entry of a major upgrade. Each answer says this in `_meta.classification`.
+**Known limits, stated plainly:** a `requirements.txt` without a lockfile names only your direct pins, so their transitive dependencies are not scanned (use `uv lock`, `poetry lock` or `pip-compile`). Many packages ship no changelog in their registry archive (fastembed, vite, zod among them); `upgrade_impact` then says so and gives the release-notes URL instead of guessing. Breaking entries are flagged from the changelog's headings and wording, and every entry carries the heading it sits under (`under`). Measured on a panel of 40 real upgrades across npm, crates.io, PyPI and Go (1,618 entries, gold from three blind raters with verbatim evidence; the panel and the measurement are in the test suite): on the 20 upgrades held out from rule-making, 95% of entries flagged breaking were breaking (95% CI 89-98%) and about 72% of breaking entries were flagged; Go release notes written as prose are the weakest (about 54% recall). Treat the flags as a pre-sort: read every entry of a major upgrade. Each answer says this in `_meta.classification`.
 
 ## What You Can Ask
 
@@ -138,6 +140,7 @@ When the 4DA desktop app is installed, the server reads the app's database (`4da
 "Scan for vulnerabilities"                    -> vulnerability_scan
 "Which deps should I upgrade first?"          -> upgrade_planner
 "Is it safe to bump axios to 1.14.1?"         -> dependency_check
+"Pin ws to a 7.x version"                     -> dependency_check (to: "7.x")
 "I'm about to bump fastembed 5 -> 7"          -> what_should_i_know
 "What's happening in the ecosystem?"          -> ecosystem_pulse
 "What's my tech stack?"                       -> get_context
@@ -152,11 +155,11 @@ When the 4DA desktop app is installed, the server reads the app's database (`4da
 
 | Tool | What it does |
 |------|-------------|
-| `upgrade_impact` | What changes between the installed and a target version of one dependency: releases in between, changelog entries classified breaking / deprecation / security, the breaking ones that touch your code (symbols you import, and route or pattern syntax in your string literals, e.g. axum 0.8's `/:id` -> `/{id}`), the files that import it, advisories fixed. |
+| `upgrade_impact` | What changes between the installed and a target version of one dependency (npm, crates.io, PyPI, Go): releases in between, changelog entries classified breaking / deprecation / security, the breaking ones that touch your code (symbols you import, and route or pattern syntax in your string literals, e.g. axum 0.8's `/:id` -> `/{id}`), the files that import it, advisories fixed. |
 | `vulnerability_scan` | Every installed copy in every lockfile matched against OSV.dev. Scope-adjusted severity, an upgrade target checked against every advisory of the package (the highest per-advisory fix can itself be affected by another), where each version is pinned, and a `coverage` block whenever the scan is partial. Concise by default (one row per vulnerable package version, the 40 most severe, about 4k tokens on a 290-advisory project); `package` for one dependency; `response_format: "detailed"` for every advisory. |
 | `dependency_health` | Version freshness, deprecation (of the version you run) and vulnerability counts per dependency. |
 | `upgrade_planner` | The smallest version no advisory affects for each vulnerable package, majors flagged (a 0.x minor counts as a major). Transitive fixes: `lockfile_refresh` with the exact command (`npm update`, `pnpm update`, `yarn up -R`, `cargo update -p ... --precise`) when every parent's declared requirement already admits a clean version, else `waiting_on_upstream` naming the requirement that blocks it. For one project: `project_path` (default: the project the server was started in; `"*"` for every project the desktop app tracks). `package` for a one-package plan. |
-| `dependency_check` | Call before adding a dependency or applying a bump. Verdict per item (`proceed` / `wait` / `review` / `avoid` / `unknown`) with evidence: advisories on the target, release age (holds releases under 3 days unless they fix an advisory you have), publish-trust drop, new install scripts, brand-new transitive dependencies, yanked or deprecated, and a breaking version range (a major, or a 0.x minor) is `review` with a pointer to `upgrade_impact`. npm and crates.io. |
+| `dependency_check` | Call before writing any dependency version into a manifest: adding, pinning, upgrading, bumping, downgrading. `to` is the exact version, or the constraint you were given (`"7.x"`, `"^1.20"`, `"~=3.1"`, `"v1"`): then `range_check` lists the smallest and newest release in it that no known advisory affects, and the verdict is for the one it picks. An exact version an advisory affects gets the safe releases on its line. Verdict per item (`proceed` / `wait` / `review` / `avoid` / `unknown`) with evidence: advisories on the target, release age (holds releases under 3 days unless they fix an advisory you have), publish-trust drop, new install scripts, brand-new transitive dependencies, yanked or deprecated, and a breaking version range (a major, or a 0.x minor) is `review` with a pointer to `upgrade_impact`. npm, crates.io, PyPI and Go (publisher trust, install scripts and new transitive dependencies are npm/crates.io signals and say "not applicable" elsewhere). |
 
 ### Intelligence
 
@@ -206,7 +209,7 @@ The MCP server works without the desktop app. It keeps a small local database in
 | Tech stack detection + resolved versions | Yes | Yes |
 | Decision memory + alignment checking | Yes | Yes |
 | Agent memory (cross-session) | Yes | Yes |
-| Scored content feed (20+ sources) | -- | Yes |
+| Developer news judged against your stack (the app's feed) | -- | Yes |
 | Actionable signals + knowledge gaps | -- | Yes |
 | The analysis layer (Signal Chains, Knowledge Gaps, temporal analysis) | -- | Yes |
 
@@ -255,6 +258,8 @@ npx @4da/mcp-server --version    # Print version
 |----------|-------------|---------|
 | `FOURDA_DB_PATH` | Path to 4DA's SQLite database | Auto-detected |
 | `FOURDA_OFFLINE` | Disable all network calls | `false` |
+| `FOURDA_GITHUB_CHANGELOG` | `upgrade_impact`: read GitHub release notes when the registry archive has no changelog for the range (`true` / `1` / `yes` / `on`) | Off |
+| `GITHUB_TOKEN` | Used only with `FOURDA_GITHUB_CHANGELOG`: raises GitHub's rate limit from 60 to 5,000 requests an hour | Unset |
 | `FOURDA_MCP_HOME` | Folder for the files the server writes (`cache.db`, `standalone.db`) | Your user data folder + `4da-mcp` |
 | `MCP_AUTH_SECRET` | Shared secret for verifying Bearer tokens on `--http` (HMAC-SHA256). Falls back to `JWT_SECRET`. Unset means no token is accepted. | Unset |
 | `MCP_AUTH_REQUIRED` | Require auth on a **loopback** `--http` bind. Always required on a non-loopback bind. | `false` |
@@ -263,10 +268,10 @@ npx @4da/mcp-server --version    # Print version
 ## FAQ
 
 **Does this send my code anywhere?**
-No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy), downloads the target version's archive from the package's own registry for `upgrade_impact`, and, only when you call `ecosystem_pulse`, sends a few dependency names as search terms to [HN Algolia](https://hn.algolia.com/api). No source code, no file paths, no personal data: the call-site scan runs locally. Set `FOURDA_OFFLINE=true` to disable all network calls. (The sole exception is opt-in OpenAI embeddings — see the network note above.)
+No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy), downloads the target version's archive from the package's own registry for `upgrade_impact` (and reads GitHub release notes only if you set `FOURDA_GITHUB_CHANGELOG=true`), and, only when you call `ecosystem_pulse`, sends a few dependency names as search terms to [HN Algolia](https://hn.algolia.com/api). No source code, no file paths, no personal data: the call-site scan runs locally. Set `FOURDA_OFFLINE=true` to disable all network calls. (The sole exception is opt-in OpenAI embeddings — see the network note above.)
 
 **Do I need the 4DA desktop app?**
-No. 11 tools work standalone: upgrade impact, pre-install dependency checks, vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app adds a scored content feed from 20+ sources, judged against your actual stack.
+No. 11 tools work standalone: upgrade impact, pre-install dependency checks, vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app is where the same engine runs day to day: one worklist across every project on the machine, a morning Brief of what changed in your stack, and an Upgrade Plan. With it installed, your agent also gets 5 more tools: signals, knowledge gaps, developer news judged against your stack, Developer DNA and feedback.
 
 **Which AI tools does this work with?**
 Any tool that supports [MCP](https://modelcontextprotocol.io): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), and any custom MCP client.

package/dist/live/changelog-classify.d.ts

@@ -20,8 +20,14 @@ export type EntryKind = "breaking" | "deprecation" | "security" | "change";
 export declare const MAX_ENTRY_CHARS = 400;
 /** Strip control and invisible/bidi characters, collapse whitespace, cap length. */
 export declare function sanitizeEntry(text: string, cap?: number): string;
+/**
+ * The text classified: RST ``literals`` read as `literals`, link targets and
+ * bare URLs dropped (a `go.dev/doc/go1.21` link made "Drop support for Go 1.21"
+ * read as a docs change), GitHub's "by @user in <PR url>" suffix dropped.
+ */
+export declare function classificationText(text: string): string;
 /** Kind of a single changelog line by its own wording. */
-export declare function classifyText(text: string): EntryKind;
+export declare function classifyText(raw: string): EntryKind;
 /**
  * What a sub-heading (or a label-only bullet such as express's "* remove:")
  * says about the entries under it:
@@ -34,8 +40,8 @@ export declare function classifyText(text: string): EntryKind;
  *   where only an explicit marker makes an entry breaking ("Added a clear()
  *   function ... removed from an axios instance" is not a removal).
  */
-export type EntryContext = EntryKind | "removal" | "additive";
+export type EntryContext = EntryKind | "removal" | "additive" | "fixes";
 /** Context implied by a heading or label, or null when it carries no signal ("### Changed"). */
 export declare function classifyHeading(heading: string): EntryContext | null;
 /** Final kind: an explicit heading or bullet parent wins; removal and additive contexts refine the line's wording. */
-export declare function classifyEntry(text: string, context: EntryContext | null): EntryKind;
+export declare function classifyEntry(raw: string, context: EntryContext | null): EntryKind;

package/dist/live/changelog-classify.js

@@ -35,7 +35,8 @@ export function sanitizeEntry(text, cap = MAX_ENTRY_CHARS) {
 // `BREAKING` but not the file name `BREAKING-CHANGES.md` (ratatui links it from routine entries);
 // a leading "Breaking -" / "[Breaking]" label too (webpack-merge 5, handlebars-rust).
 // Case-sensitive on purpose: lowercase "breaking" is prose, handled (with negation) below.
-const EXPLICIT_BREAKING_MARKER = /\bBREAKING\b(?![-_.]\w)|⚠|^\s*\*{0,2}\w+(?:\([^)]*\))?!:|^\s*\*{0,2}[Bb]reaking\*{0,2}\s*(?::|[-–—]\s)|^\s*\[(?:[Bb]reaking|[Rr]emoved)\]/;
+// "*Backwards-incompatible*:" (marshmallow 4) is the same call in other words.
+const EXPLICIT_BREAKING_MARKER = /\bBREAKING\b(?![-_.]\w)|⚠|^\s*\*{0,2}\w+(?:\([^)]*\))?!:|^\s*\*{0,2}[Bb]reaking\*{0,2}\s*(?::|[-–—]\s)|^\s*\[(?:[Bb]reaking|[Rr]emoved)\]|\b[Bb]ackwards?[- ][Ii]ncompatible\b/;
 /**
  * Text ABOUT breaking changes rather than one: a pointer to the list ("⚠️ List
  * of breaking changes can be found here"), a CI label check, a docs fix
@@ -126,7 +127,81 @@ const BREAKING_HEURISTIC = new RegExp([
     "\\bincompatib",
 ].join("|"), "i");
 /** Removals that change nothing a caller sees: "Removed unused imports", "Removed Webpack". */
-const INTERNAL_CHANGE = /\b(?:unused|unneeded|unnecessary|internal(?:ly)?|dead code|tests?|ci|lint(?:ing)?|typos?|comments?|docs?|documentation|readme|redundant|duplicated?|webpack|dev-?dependenc(?:y|ies)|dependency|warnings?|examples?|benchmarks?|release process|build process|tooling|usage|incorrect|wrong|erroneous|stray|spurious)\b/i;
+const INTERNAL_CHANGE = /\b(?:unused|unneeded|unnecessary|internal(?:ly)?|dead code|tests?|ci|lint(?:ing)?|typos?|comments?|docs?|documentation|readme|redundant|duplicated?|webpack|dev-?dependenc(?:y|ies)|dependency|warnings?|examples?|benchmarks?|release process|build process|tooling|usage|incorrect|wrong|erroneous|stray|spurious|private|maintainers?|contributors?|invalid|broken|bogus|[\w-]+\.(?:md|json|ya?ml|toml|lock|txt|cfg)(?![\w(]))\b/i;
+/**
+ * The removed thing is private by its name (`_prepare_conn`, a leading
+ * underscore): urllib3 2.0 lists such removals under "Removed".
+ */
+const PRIVATE_NAME = /^\W*(?:remove[sd]?|delete[sd]?|drop(?:s|ped)?)\b[^`]{0,40}`_[A-Za-z]/i;
+const isInternal = (t) => INTERNAL_CHANGE.test(t) || PRIVATE_NAME.test(t);
+/** Public API made private ("Assorted array helper methods and types made private"): a removal, though it says "private". */
+const MADE_PRIVATE = /\b(?:made|make|makes|is now|are now)\b[^.]{0,60}\bprivate\b/i;
+/**
+ * The entry says it changes nothing for users: "passing string or boolean still
+ * works as before", "This change should have no effect on users".
+ */
+const STATED_COMPATIBLE = /\b(?:still works?|still work as before|continues? to work|(?:is|are) still supported|remains? supported|(?:should|will|has|have) (?:have )?no (?:effect|impact) on (?:users|you|most users|existing code)|no user-facing)\b|(?<!\bnot |\bnon-?)\bbackwards?[- ]compatib(?:le|ility)\b/i;
+/**
+ * Not an API change although worded like one: undoing a removal or deprecation
+ * ("removes the deprecation notice from", "restore the `X()` function"), a
+ * relaxation ("remove Send bounds for request `Body`"), a repository rename, a
+ * swapped dependency ("Move from `winapi` to `windows` crate").
+ */
+const UNDO = /\bremov\w*\s+(?:the\s+)?(?:[\w`]+\s+)?(?:bounds?|restrictions?|limitations?|limits?|requirements?|constraints?|need for)\b|\brenam\w*\s+(?:the\s+)?(?:github\s+)?repo(?:sitory)?\b|\bmov(?:e|ed|es)\s+from\s+\x60[^\x60]+\x60\s+to\s+\x60[^\x60]+\x60\s+(?:crate|package|library)\b|\bremov\w*\s+(?:the\s+)?deprecation\s+(?:notices?|warnings?|messages?)\b|\bun-?deprecat|\b(?:restore[sd]?|restoring|re-?add(?:ed|s)?|reintroduc\w*)\b/i;
+/** A change confined to examples, docs, tests or CI: "Drop support for Go 1.21 in dice example". */
+const SCOPED_NON_API = /\bin (?:the )?(?:[\w-]+ )?(?:examples?|docs?|documentation|tests?|ci|workflows?|benchmarks?|readme)\b/i;
+const LEAD = String.raw `^\W*(?:\*\*[^*]{1,40}\*\*:?\s*)?`;
+/**
+ * Runtime and language support: dropped versions and raised minimums ("drop
+ * node 10.x", "Drop support for Go 1.21", "only support node 16-20", "Replace
+ * go 1.21 with go 1.22 in go mod", "increase MSRV to 1.63"). Breaking whatever
+ * the reason the entry gives ("drop node 10.x to upgrade dev dependencies").
+ */
+const RUNTIME_SUPPORT = new RegExp([
+    String.raw `\b(?:drop(?:s|ped|ping)?|remove[sd]?|removing|end(?:s|ed)?)\s+(?:official\s+)?(?:support\s+(?:for\s+)?)?(?:node(?:\.?js)?|python|py|go|golang|ruby|php|java|jdk|rust|rustc)\s*v?\d`,
+    String.raw `\b(?:only supports?|now requires?|requires? at least|minimum (?:supported )?(?:version of )?)\s*(?:node(?:\.?js)?|python|go|golang|rust|ruby|php|java)\s*v?\d`,
+    String.raw `\bonly supports? (?:node(?:\.?js)?|python|go|golang)\b`,
+    String.raw `\bgo\s*1\.\d+[^.]{0,30}\bgo\.?\s?mod\b`,
+    String.raw `\b(?:bump|bumped|raise|raised|increase|increased|update|updated|require|requires|now)\b.{0,60}\b(?:MSRV|minimum supported rust version|rust-version)\b.{0,30}\d+\.\d+`,
+].join("|"), "i");
+/**
+ * Wording that changes the API whatever heading it sits under (rule set added
+ * 2026-10-11 from the G3 panel's dev pairs): a leading removal or rename of
+ * something API-shaped, a changed default, a type made private, a move, a
+ * replacement, keyword-only arguments, "now ... instead of".
+ */
+const API_CHANGE = new RegExp([
+    // "remove UMD build", "remove `ReasonPhrase::from_bytes_unchecked()` method", "Remove previously deprecated code".
+    // The removed thing is named within the next few words, as in REMOVAL_HEURISTIC: "Remove a window when ...
+    // `cd`able by non-owners" (a security fix) has its backtick far later.
+    String.raw `${LEAD}(?:remove[sd]?|delete[sd]?|drop(?:s|ped)?)\b(?=(?:\s+[\w.:/-]+){0,4}\s*\(?\x60|(?:\s+[\w.:/-]+){0,5}?\s+(?:support|builds?|param(?:eter)?s?|options?|methods?|functions?|modules?|class(?:es)?|types?|exports?|features?|flags?|apis?|prefix(?:es)?|constructors?|requires|imports|entry ?points?|fields?|propert(?:y|ies)|arguments?|attributes?|traits?|structs?|enums?|macros?|commands?|settings?|config|keys?|aliases?|fallback|deprecated|code)\b)`,
+    String.raw `${LEAD}renamed?\b`,
+    String.raw `\x60[^\x60]+\x60\s+(?:is |was |has been )?renamed\b|\bchanged? (?:the )?name of\b`,
+    // Defaults: "Changed the default `blocksize` to 16KB", "now defaults `extended` to `false`", "default `header_read_timeout` to 30 seconds".
+    String.raw `${LEAD}(?:change[sd]?|set|make|made)\b[^.]{0,60}\bdefaults?\b[^.]{0,60}\bto\b`,
+    String.raw `${LEAD}default\s[^.]{0,60}\bto\b`,
+    String.raw `\bnow defaults?\b[^.]{0,40}\bto\b|\bdefaults? (?:value |values )?(?:is|are) now\b`,
+    String.raw `\b(?:keyword|positional)[- ]only\b`,
+    String.raw `\x60[^\x60]+\x60\s+(?:has been |have been |was |were |is |are )?moved (?:to|into|out of)\b`,
+    String.raw `${LEAD}moved?\b[^.]{0,80}\x60[^\x60]+\x60[^.]{0,60}\b(?:to|into|out of)\b`,
+    String.raw `\b(?:are|is|was|were|been)\s+(?:both\s+)?replaced\b|\x60[^\x60]+\x60\s+replaces\s+\x60`,
+    String.raw `\bnow\b[^.]{0,60}\binstead of\b`,
+    String.raw `\b(?:accepts?|takes?|returns?|receives?)\s+(?:a |an )?(?:pointer|reference|value|slice|copy)\b[^.]{0,30}\binstead of\b`,
+    String.raw `\bchang(?:e|ed|es)\b[^.]{0,80}\bfrom\s+\x60[^\x60]+\x60\s+to\s+\x60`,
+    String.raw `\bno longer (?:subclass(?:es)?|inherits?|comparable|usable|considers?|escapes?|initiali[sz]ed|quotes?|sets?|ha(?:s|ve) a default|safe|valid|recogni[sz]ed|parsed?|emitted|exposed|called)\b|\bis not set anymore\b|\bnot set anymore\b`,
+].join("|"), "i");
+/**
+ * The text classified: RST ``literals`` read as `literals`, link targets and
+ * bare URLs dropped (a `go.dev/doc/go1.21` link made "Drop support for Go 1.21"
+ * read as a docs change), GitHub's "by @user in <PR url>" suffix dropped.
+ */
+export function classificationText(text) {
+    return text
+        .replace(/``/g, "`")
+        .replace(/\]\([^)]*\)/g, "]")
+        .replace(/\bby @[\w-]+(?:\[bot\])? in\s+\S+/g, " ")
+        .replace(/https?:\/\/\S+/g, " ");
+}
 const DEPRECATION = /deprecat/i;
 /**
  * An entry whose main verb is "deprecate" is a deprecation even when it names
@@ -135,11 +210,14 @@ const DEPRECATION = /deprecat/i;
  */
 const LEADING_DEPRECATION = /^\W*(?:\*\*[^*]{1,40}\*\*:?\s*)?(?:deprecated?|deprecates|deprecating)\b/i;
 /** Kind of a single changelog line by its own wording. */
-export function classifyText(text) {
+export function classifyText(raw) {
+    const text = classificationText(raw);
     if (META_BREAKING.test(text))
         return SECURITY.test(text) ? "security" : "change";
     if (EXPLICIT_BREAKING_MARKER.test(text))
         return "breaking";
+    if (STATED_COMPATIBLE.test(text))
+        return DEPRECATION.test(text) ? "deprecation" : "change";
     if (NON_BREAKING_LABEL.test(text)) {
         if (SECURITY.test(text))
             return "security";
@@ -158,15 +236,26 @@ export function classifyText(text) {
         return "security";
     if (FUTURE_INTENT.test(text))
         return DEPRECATION.test(text) ? "deprecation" : "change";
-    if (BREAKING_HEURISTIC.test(text))
-        return "breaking";
-    if (REMOVAL_HEURISTIC.test(text) && !INTERNAL_CHANGE.test(text) && !LEADING_FIX.test(text))
+    if (UNDO.test(text))
+        return DEPRECATION.test(text) ? "deprecation" : "change";
+    if (!SCOPED_NON_API.test(text)) {
+        if (RUNTIME_SUPPORT.test(text) || BREAKING_HEURISTIC.test(text))
+            return "breaking";
+        if (MADE_PRIVATE.test(text) && !LEADING_FIX.test(text))
+            return "breaking";
+        if (API_CHANGE.test(text) && !isInternal(text) && !LEADING_FIX.test(text))
+            return "breaking";
+    }
+    if (REMOVAL_HEURISTIC.test(text) && !isInternal(text) && !LEADING_FIX.test(text))
         return "breaking";
     if (DEPRECATION.test(text))
         return "deprecation";
     return "change";
 }
-const ADDITIVE_HEADING = /^\W*(?:added|adds|new|new features?|features?|enhancements?|improvements?|fixed|fixes|bug ?fixes|performance(?: improvements)?|perf|optimi[sz]ations?|docs?|documentation|tests?|testing|internal|chores?|ci|build|refactor(?:ing)?|misc(?:ellaneous)?|other(?: changes)?)\W*$/i;
+const FIX_HEADING = /^\W*(?:fixed|fixes|bug ?fixes|bugfixes|fix)\W*$/i;
+// "Other changes" / "Misc" are not additive: pgx 5 files its type removals and renames
+// under "Other Changes", and marshmallow 4 a changed base class.
+const ADDITIVE_HEADING = /^\W*(?:added|adds|new|new features?|features?|enhancements?|improvements?|fixed|fixes|bug ?fixes|performance(?: improvements)?|perf|optimi[sz]ations?|docs?|documentation|tests?|testing|internal|chores?|ci|build|refactor(?:ing)?)\W*$/i;
 /** Context implied by a heading or label, or null when it carries no signal ("### Changed"). */
 export function classifyHeading(heading) {
     if (/(?<!-)\bbreaking\b|⚠|incompatib|migration|\bmajor changes?\b/i.test(heading))
@@ -174,34 +263,55 @@ export function classifyHeading(heading) {
     // "Removed", "Removals", "Deprecated and Removed", "API changes": a category.
     // "`Cargo.lock` Removed from Tracking" (sqlx 0.9.0) is a news item about the
     // repository, and its three paragraphs were flagged breaking.
-    if (/(?:^\W*|(?:\band|[&/,])\s*)remov(?:e|ed|als?)\b|\bapi changes?\b/i.test(heading))
+    // "Previously-deprecated APIs have been removed, including" (marshmallow 4) is a removal list, not a deprecation one.
+    if (/(?:^\W*|(?:\band|[&/,])\s*)remov(?:e|ed|als?)\b|\bapi changes?\b|\b(?:have|has) been removed\b|\b(?:were|are) removed\b/i.test(heading))
         return "removal";
     if (/security|vulnerab/i.test(heading))
         return "security";
     if (/deprecat/i.test(heading))
         return "deprecation";
+    // Fixes are additive, and stricter: the author filed the entry as a bug fix, so API-shaped
+    // wording in it ("change default export to named function") is not read as a break.
+    if (FIX_HEADING.test(heading))
+        return "fixes";
     if (ADDITIVE_HEADING.test(heading))
         return "additive";
     return null;
 }
 /** Final kind: an explicit heading or bullet parent wins; removal and additive contexts refine the line's wording. */
-export function classifyEntry(text, context) {
+export function classifyEntry(raw, context) {
     if (context === "breaking" || context === "security" || context === "deprecation") {
         // A security line under "Breaking" stays breaking: the heading is the author's own call.
         return context;
     }
+    const text = classificationText(raw);
     if (context === "removal") {
         if (META_BREAKING.test(text))
             return "change";
         if (EXPLICIT_BREAKING_MARKER.test(text))
             return "breaking";
-        if (DEPRECATION.test(text) && !/\bremov/i.test(text))
+        if (STATED_COMPATIBLE.test(text) || UNDO.test(text))
+            return DEPRECATION.test(text) ? "deprecation" : "change";
+        // A deprecation filed under Removed is one when it leads with it; "`x` (deprecated in 3.24.0)" was removed.
+        if (LEADING_DEPRECATION.test(text) || (DEPRECATION.test(text) && !/\bremov|\(deprecated (?:in|since)\b|\bno longer\b|\bwere replaced\b/i.test(text))) {
             return "deprecation";
-        return INTERNAL_CHANGE.test(text) ? "change" : "breaking";
+        }
+        return isInternal(text) ? "change" : "breaking";
     }
-    if (context === "additive") {
+    if (context === "additive" || context === "fixes") {
         if (!META_BREAKING.test(text) && EXPLICIT_BREAKING_MARKER.test(text))
             return "breaking";
+        // An API removal, rename or raised runtime minimum is breaking under "Features" too
+        // (uuid 11 lists "remove UMD build" there; hyper 1.0 "rename to `Http2ClientConnExec`").
+        const quiet = STATED_COMPATIBLE.test(text) || UNDO.test(text) || SCOPED_NON_API.test(text) || NON_BREAKING_LABEL.test(text);
+        if (!quiet && !META_BREAKING.test(text)) {
+            if (RUNTIME_SUPPORT.test(text))
+                return "breaking";
+            if (context === "additive" && MADE_PRIVATE.test(text) && !LEADING_FIX.test(text))
+                return "breaking";
+            if (context === "additive" && API_CHANGE.test(text) && !isInternal(text) && !LEADING_FIX.test(text))
+                return "breaking";
+        }
         if (SECURITY.test(text))
             return "security";
         return DEPRECATION.test(text) ? "deprecation" : "change";

package/dist/live/changelog.d.ts

@@ -7,6 +7,8 @@
  *   conventional          `## [7.0.0](https://…/compare/…) (2025-06-24)`
  *   plain / prefixed      `## 1.2.3`, `# v1.2.3 (2024-01-01)`, `### Version 1.2.3`, `## fastembed 5.0.0`
  *   setext                `1.2.3` underlined with `===` / `---`
+ *   reStructuredText      `Version 3.0.0` underlined (or over- and underlined)
+ *                         with any of `= - ~ ^ * + # " '`, then `Released 2023-09-30`
  *   History.md (express)  `1.2.3 / 2020-01-01`
  * A heading only opens a section when the rest of it looks like a trailer
  * (date, link, "yanked") — `## Upgrading from 1.x` or `#### Rust 1.70 support`
@@ -23,7 +25,7 @@ import { type EntryKind } from "./changelog-classify.js";
  * for a week unless this changes: bump it with every change to parseChangelog
  * or changelog-classify.ts that can alter a section or an entry's kind.
  */
-export declare const CHANGELOG_PARSER_VERSION = 2;
+export declare const CHANGELOG_PARSER_VERSION = 4;
 export interface ChangelogEntry {
     kind: EntryKind;
     text: string;
@@ -64,8 +66,10 @@ export declare function parseVersionHeading(raw: string): {
 } | null;
 /** Parse a changelog into version sections, in document order (usually newest first). */
 export declare function parseChangelog(text: string): ChangelogSection[];
-/** True when `version` lies in (from, to] by semver precedence; unreadable versions are out. */
-export declare function inRange(version: string, from: string, to: string): boolean;
+/** Version order: 1, -1, 0, or null when either side is unreadable. Semver precedence by default. */
+export type VersionOrder = (a: string, b: string) => number | null;
+/** True when `version` lies in (from, to] by `order`; unreadable versions are out. */
+export declare function inRange(version: string, from: string, to: string, order?: VersionOrder): boolean;
 /**
  * Sections in (from, to], plus whether the changelog reaches both ends of the
  * range: its newest section is at or past `to`, and its oldest at or before
@@ -73,7 +77,7 @@ export declare function inRange(version: string, from: string, to: string): bool
  * stopped being maintained two majors ago is reported as not covering the
  * range instead of silently presenting a partial history as the whole one.
  */
-export declare function selectRange(sections: ChangelogSection[], from: string, to: string, firstInRange: string): {
+export declare function selectRange(sections: ChangelogSection[], from: string, to: string, firstInRange: string, order?: VersionOrder): {
     sections: ChangelogSection[];
     coversRange: boolean;
 };