Glossary
Every term mendapi uses in its output, JSON schemas and documentation — defined once, with the exact literal values the shipped code emits.
Change intelligence
change
One recorded upstream API modification in the local SQLite database, sourced from SDK release feeds, changelogs, or OpenAPI spec diffs. Each change carries a provider, a title, a change type and evidence of where it was observed.
change type
The classification of a change. Literal values in the database: breaking (removes or reshapes something your code may rely on), deprecation (still works, scheduled to break), additive (new capability, no risk), fix (upstream bugfix), docs-only (documentation move, no API behaviour change), and unknown (could not be classified deterministically — never silently guessed into another bucket).
provider
An upstream API vendor being monitored (for example stripe, openai, aws, paypal). Findings are only raised for providers your repo demonstrably uses.
spec diff
A breaking-change detection made by comparing two versions of a provider's OpenAPI specification directly, rather than trusting the vendor's prose changelog. This is how changes get recorded even when the upstream changelog omits them.
Scanning
impact
One scan finding: a recorded change matched against evidence in your repo, with file-and-line usage sites. Impacts live in impact.json (the scan report).
confidence
How strong the evidence for an impact is. high: a changed API symbol was matched at an identifier boundary in your files. medium: the provider surface is present and source-valid, but no changed symbol matched directly. low: weak or indirect evidence; hidden from terminal output by default (full list in --json/--out). Prose or comment mentions never inflate confidence to high.
severity
Derived from the change type: breaking → high, deprecation → medium, unknown → low, additive and docs-only → info.
usage site
The file:line evidence behind an impact. Every finding is evidence-gated — if it cannot point at lines, it is not reported.
Fixing
migration pack
A named, deterministic fix rule set for one specific upstream change family (for example stripe-terminal-tipping-bgn-removal). Packs record which change IDs they cover and the upstream state they assume; mendapi fix --migration <name> applies one as a dry-run diff by default. The full catalogue is on Migration Packs.
covers
The explicit list of change IDs a pack fixes. Coverage accounting is mechanical: a change is pack-covered if and only if its ID appears in some pack's covers list.
staleness / needs-revalidation
A pack is stale when the database records upstream changes on the same API surface that are newer than the pack's baseline. mendapi revalidate reports each pack as fresh, needs-revalidation, no-covers, or covers-missing; fix refuses to apply a stale pack (exit 3) without an explicit --ack-stale. Rules are never allowed to rot silently.
pack surfaces (API-surface anchor set)
The surfaces list in a revalidate pack assessment and on the Migration Packs page: the upstream API surfaces a pack's fix targets, expressed as METHOD /path pairs. The set is derived mechanically from the pack's covered change records — never hand-written — so it always reflects recorded evidence. Packs whose covered changes carry no endpoint anchor (SDK release changes) get an honest empty list rather than a guess.
fixability
The honest-coverage verdict for a breaking change. Literal values: code-fixable (a code migration can mend it — counts in the coverage denominator), not-code-fixable (runtime upgrades, product retirements with no successor, platform policy — excluded from the denominator with a recorded reason), and unclear (cannot rule fixability out yet; never counted as covered).
dry run
The default mode of fix: emit a unified diff that git apply accepts cleanly, change nothing. Writing requires an explicit --apply.
draft (LLM fix)
A patch generated by llmfix with your own LLM key. Drafts are previews: syntax-checked, saved to a report, and never applied to your repo automatically. Unparseable or non-compiling drafts are dropped, not written.
syntax verification / verdict
The evidence attached to every rewritten file inside a fix report. Before the report is written, each rewritten file is run through node --check and the result ships as a syntax_check verdict. Literal values: pass (the rewritten file parses cleanly), fail (it does not — the first error line is recorded in reason and a warning is written to stderr, never silently swallowed), and skipped (a file node --check cannot parse, such as TypeScript or JSX — recorded with a reason, never counted as a pass). The report's verification.syntax_check block totals these as passed / failed / skipped counts so a reviewer or an automated gate can cite the numbers mechanically. See the evidence chain.
repo checks (second verification layer)
The optional second evidence layer in a fix report's verification.repo_checks block: after --apply, the repo's own package.json scripts are run — a conservative whitelist of test and typecheck only, never build or start. Opt-in via --run-checks, because running repo scripts executes third-party code. Literal status values: ran (carries passed / failed totals plus a per-script entry with the command, an exit_code and an output_tail) and skipped (the flag was not passed, --apply was missing, the repo has no readable package.json, or it defines none of the whitelisted scripts — always with a recorded reason, never silently counted as passed). Where the syntax verdict above proves the patch itself parses, repo checks prove the repo's own tests are still green after the patch is applied. Details and a CI gate example in the evidence chain.
Dependency awareness
surface
One concrete way your repo touches a provider, as inventoried by mendapi deps. Kinds: module (an import/require of the provider SDK), env (a provider credential environment variable), endpoint (a literal API URL your code calls), sdk-call (a resolved SDK client method chain such as client.kv.namespaces.values.get), and controller-call (a method call on a named-import controller instance). Every surface carries file:line evidence.
match (deps --match)
The join between your repo's surfaces and recorded breaking changes or migration packs. A match means the fix would really rewrite that line — it is looked up against the pack's declared anchors, never guessed heuristically. The report's pack_match section additionally joins your endpoint surfaces against each pack's API-surface anchor set (above), so a hit comes with a runnable mendapi fix --migration <pack> suggestion and file:line evidence.
Interfaces & contracts
schema_version
The integer version stamped on every JSON envelope mendapi emits (scan, deps, fix, llmfix, review). It bumps only on breaking shape changes — pin your parser to it instead of sniffing key names. Distinct from the tool string, which tracks implementation versions.
metadata-only payload
The only thing mendapi can ever transmit when hosted reporting is explicitly enabled: a whitelist-constructed summary (counts, change IDs, confidence tiers) with all strings passed through secrets redaction. Source code never leaves your machine. Full schema on the security model page.
MCP server
mendapi mcp: a zero-dependency stdio JSON-RPC 2.0 server exposing scan / fix / deps / revalidate / changes as tools for any Model Context Protocol client. See For AI Agents.
BYO LLM
Bring-your-own LLM: all model-assisted features run against a provider you configure (openai, anthropic, or any openai-compatible endpoint, including local ones) with your own key. mendapi ships no key, defaults to off, and fails loud when unconfigured. See BYO LLM.