@vantageos/mcp-doctor 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 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,56 @@ 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 | **exit 1** |
+| `could-not-judge` | the detector could not read its input and says so in the row — in 0.3.1, only D9 does this (no `package.json` above the root); see the limits below | **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.
+
+**Two known limits in 0.3.1, 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.
+- **Unreadable input is handled in band by D9 only.** In 0.3.1, D9 reports `could-not-judge` when no
+  `package.json` sits above the scanned root, and the run completes. Several other detectors still
+  **throw** on unreadable input — a malformed manifest, a computed value — which aborts the run with
+  exit 1 and a stack trace, indistinguishable from a violation. Converting them is in progress.
+
+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 +100,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 +116,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 +129,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.js

@@ -3143,9 +3143,14 @@ var d9 = {
       );
     }
     if (!tree.packageJson) {
-      throw new Error(
-        "D9 could not locate package.json anywhere above the scanned root \u2014 cannot verify SemVer/CHANGELOG"
-      );
+      const reason = "no package.json found anywhere above the scanned root \u2014 cannot verify SemVer/CHANGELOG";
+      return {
+        id: this.id,
+        anchor: "package.json",
+        state: "could-not-judge",
+        reason,
+        verdict: `could not judge: ${reason}`
+      };
     }
     const { path: pkgPath, json: pkgJson } = tree.packageJson;
     if (!pkgJson || Object.keys(pkgJson).length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-doctor",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Static MCP conformance checker: audits an MCP server source tree against the MCP 2026-07-28 standard and emits a conformance-diff table (file:line | present | absent | non-conforming | verdict).",
   "type": "module",
   "main": "./dist/doctor.js",
@@ -39,6 +39,7 @@
   "scripts": {
     "build": "tsup",
     "doctor": "tsx src/doctor.ts",
+    "pretest": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:d10-foreign-bite": "bash scripts/d10-foreign-bite-probe.sh",