@vantageos/mcp-doctor 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.3.2 — 2026-10-04
+
+### Changed — read this if your CI distinguishes exit codes
+- **Unreadable input is now `could-not-judge` (exit 2), no longer a crash (exit 1).**
+  A tree holding input a detector could not read — malformed JSON in an extension
+  manifest or `evals.json`, a computed or non-literal value where a literal is
+  required — used to abort the run with a stack trace and exit 1, the code this
+  tool uses for *a violation*. It now completes the run, names the unreadable
+  file in the row, and exits 2 (no violation, but part of the tree was not judged).
+  Pipelines that treat any non-zero exit as failure are unaffected. Pipelines that
+  distinguish 1 from 2 must read the new state: a run that used to exit 1 on
+  unreadable input now exits 2. (#46)
+
+### Fixed
+- **A manifest that parses but is wrong is `non-conforming`.** It is a finding
+  (exit 1) rather than an abstention or a crash. (#46)
+- **An unparseable `package.json` is `could-not-judge` for C17, D10 and D7** (and C14, D12), where each had judged an empty manifest and reported the emptiness as a finding (C17, D10 non-conforming) or an absence (D7), so the run exited 1 instead of 2. The parse failure is now recorded once at load time and every detector reading that file honours it.
+- **Tools declared as descriptor objects are now found.** Five detectors (D3, D4, D8, D11, DServer2) and C19 reported "no registered tools" on servers that declare their tools as descriptor objects (`{ name, inputSchema }`). They now find those tools. A tree that serves tools but where none can be located reads `could-not-judge`, not `absent`. On a real vCRM tree, the "no registered tools found" rows went from 1 to 0, and D11 is now a real finding. (#48)
+- **`package.json` is now what npm publishes.** `npm publish` of 0.3.1 printed
+  "npm auto-corrected some errors in your package.json": `bin` was `"./dist/doctor.js"`
+  and is now `"dist/doctor.js"`, and `files` is reformatted, both exactly as
+  `npm pkg fix` writes them. A new test, `tests/publish-manifest-clean.test.ts`,
+  runs `npm publish --dry-run` and fails if that warning returns, and asserts the
+  tarball lists `dist/doctor.js`, `README.md` and `LICENSE`.
+
+### Docs
+- README: the states table and the known limits no longer say unreadable input is
+  handled in band by D9 only.
+
+---
+
+## 0.3.1 — 2026-10-04
+
+### Fixed
+- **`npm test` on a clean clone failed 3 of 341.** `tests/bin-entrypoint.test.ts`
+  symlinks to `dist/doctor.js` and invokes it — deliberately, because the symlink is
+  the trigger for the defect those cases cover — but it never ensured the build
+  existed. A contributor cloning the repo and running the suite got
+  `Cannot find module .../dist/doctor.js` three times, on `main`, with nothing saying
+  a build was required first.
+  Fixed with `pretest: npm run build`, following the convention `prepack` and
+  `prepublishOnly` already use in this manifest rather than inventing a mechanism.
+- **D9 no longer throws when no `package.json` sits above the scanned root.** It
+  returns `could-not-judge` in band, the run completes the remaining detectors, and
+  the table prints. Previously the throw reached the consumer as exit 1 with a stack
+  trace — exit 1 being this tool's code for *a violation*, so a crash was
+  indistinguishable from a finding.
+
+### Note on why 0.3.0 shipped with the test defect
+Every environment where the work happens already has `dist/` — so the test passed for
+everyone who wrote it, and the one gated path (`prepublishOnly`, which runs
+`build && test`) was the one path that could not expose it. A test depending on an
+unstated prior step cannot fail for its author.
+
+---
+
 ## 0.3.0 — 2026-10-04
 
 The documented invocation never ran. Through `node_modules/.bin/mcp-doctor` this

package/README.md

@@ -1,13 +1,17 @@
 # @vantageos/mcp-doctor
 
-Static **MCP conformance checker**. Point it at an MCP server source tree and it emits a
-**conformance-diff table** against the MCP **2026-07-28** standard — one row per checked item:
+**MCP conformance checker**. Point it at an MCP server source tree and it emits a
+**conformance-diff table** against the MCP **2026-07-28** standard — one row per detector:
 
 ```
-item | file:line | present | absent | non-conforming | verdict
+item | file:line | state | verdict
 ```
 
-No narrative, no LLM, no network: a deterministic static scan you can wire into CI. It reproduces,
+where `state` is one of `present`, `absent`, `non-conforming` or `could-not-judge` (see
+[States and exit codes](#states-and-exit-codes)).
+
+No narrative, no LLM. By default it is a deterministic **static** scan you can wire into CI; with
+`--mode=dynamic` it also launches the server and judges what it actually serves. It reproduces,
 unaided, the manual conformance audits the fleet ran by hand on its own MCP servers.
 
 ## Usage
@@ -37,6 +41,52 @@ D7 protocol-kit          | package.json       | absent          | hand-rolled bu
 The path is the root of the MCP server sources (the folder holding `server.ts` / `transport/` /
 `package.json`). `node_modules`, `dist`, `build`, `.git` and test folders are skipped automatically.
 
+### Options
+
+The binary's own `--help` is the authority; this is what it prints:
+
+```
+usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
+
+  --mode=static   read the tree only (default)
+  --mode=dynamic  launch the server and judge what it serves
+  --mode=both     both, dynamic findings taking precedence
+  --version       print the version and exit
+  --help          print this and exit
+
+exit: 0 clean, 1 a violation, 2 an abstention with no violation
+```
+
+## States and exit codes
+
+| state | meaning | effect on exit |
+|---|---|---|
+| `present` | the standard item is satisfied | none |
+| `absent` | the detector found nothing to judge — see the caveat below | none |
+| `non-conforming` | the item is present and wrong (this includes a manifest that parses but holds a wrong value) | **exit 1** |
+| `could-not-judge` | the detector could not read its input and says so in the row — malformed JSON, a computed or non-literal value, no `package.json` above the root; the run completes and the row names the file | **exit 2**, unless something else is non-conforming |
+
+The exit code keeps three outcomes distinct, which is what makes the tool safe in CI:
+
+- **0** — clean.
+- **1** — at least one violation.
+- **2** — no violation, but at least one detector abstained. **An abstention is never a pass**: it
+  means part of the tree was not judged, and the row names which part and why.
+
+**One known limit in 0.3.2, stated rather than hidden:**
+
+- **`absent` currently means two things.** It is used both for "this rule does not apply here" and,
+  for some detectors, "this is required and missing". The second should move the exit code and
+  today does not. Until that is split, read an `absent` row against the rule it names rather than
+  treating it as harmless.
+
+By design, a detector whose own internal self-check fails stops the run — that is the instrument
+reporting that it is broken, and silencing it would hide the fault behind a normal-looking table.
+
+**Upgrading from 0.2.0:** through `npx` or `node_modules/.bin`, 0.2.0 printed nothing and exited 0
+for every target, because its entrypoint guard never fired under a symlink. A CI job that has been
+green on 0.2.0 was green because nothing ran. Expect findings on the first run of 0.3.x.
+
 ## Programmatic use
 
 ```ts
@@ -46,7 +96,7 @@ const results = runDoctor("./mcp-server");
 console.log(renderTable("./mcp-server", results));
 ```
 
-## What it checks — the 6 Tier-A detectors (MCP 2026-07-28)
+## What it checks (MCP 2026-07-28)
 
 Each detector maps one standard item and is proven **bipolar** on real material: a genuine defect
 (MUST_FLAG) and a genuine conformant site (MUST_PASS).
@@ -62,7 +112,11 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D15** cache-coherence | Server Rule 15 — every tool-set mutation (RegisteredTool `.enable/.disable/.update/.remove`, `unregisterTool`) is correlated with a `notifications/tools/list_changed` emission | present / absent / non-conforming / could-not-judge |
 | **D16** version-observable | Server Rule 16 — `server/discover` (or an HTTP `/health` route) exposes a `version` field sourced from `package.json`, reachable pre-auth | present / absent / non-conforming / could-not-judge |
 
-The registered detector set is the source of truth (`src/detectors/index.ts`); the table above is illustrative, not the count. **Adding a detector is how a friction becomes durable — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the loop.**
+**This table is a sample, not the inventory.** Every registered detector runs on every invocation,
+so the authoritative list is simply the output of a run — one row per detector. The registered set
+lives in `src/detectors/index.ts`. No count is written here on purpose: a number typed into a README
+is correct on the day it is written and wrong at the next detector, which is exactly how this
+heading came to claim 6 while the tool shipped dozens. **Adding a detector is how a friction becomes durable — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the loop.**
 
 ## Positioning
 
@@ -71,10 +125,17 @@ standard by naming the exact `file:line` to fix — and a **vendable product** f
 MCP servers who needs a reproducible conformance gate. It is deterministic: the same tree yields the
 same diff on any machine, so it belongs in CI, not in a review checklist.
 
+## Contributing
+
+`npm test` builds first (a `pretest` script runs `npm run build`), because several tests drive the
+real published entry point through a symlinked bin and need `dist/` to exist. Earlier versions
+assumed a prior build, which passed for anyone who had already built and failed for anyone who had
+just cloned.
+
 ## License
 
 FSL-1.1-Apache-2.0 (Functional Source License, Apache 2.0 future license). See [LICENSE](./LICENSE).
 
 ---
 
-Orchestrator: Gamma — VantageOS Team | 2026-08-03
+Orchestrator: Gamma — VantageOS Team | 2026-10-04

package/dist/doctor.d.ts

@@ -13,9 +13,15 @@ interface SourceFile {
 interface Tree {
     root: string;
     files: SourceFile[];
+    /**
+     * `unreadable` is set (with the parse error) when the file exists but is not a
+     * JSON object; `json` is then `{}` and MUST NOT be read as the file's content.
+     * Detectors that read this file go through `guardUnreadablePackageJson`.
+     */
     packageJson: {
         path: string;
         json: Record<string, unknown>;
+        unreadable?: string;
     } | null;
 }