@vantageos/mcp-doctor 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,87 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## Unreleased
+
+### Changed
+- **DLocalIdentity exemption marker renamed** `local-identity-exempt:` -> `allow-local-identity:`
+  (standard R-57), reason of 8 characters or more (was 10). The old spelling no longer exempts.
+
+### Added
+- **DLocalIdentity, third REVISE (PR #52):** reported now are `claimedName` (and any
+  `caller*`/`actor*`/`acting*`/`claimed*` property) compared to an agent's `.name`;
+  `switch (row.createdBy) { case caller: }`; `[caller].includes(row.createdBy)` and
+  `new Set([caller]).has(...)`; `a.localeCompare(b) === 0` on names or tenants; a primitive
+  imported or destructured under an alias (`import { createHash as h }`). Implemented as regex
+  matchers, not an AST: `typescript` is a devDependency only and the report contract is line-based.
+
+## 0.4.0 — 2026-10-09
+
+### Added
+- **`DLocalIdentity no-local-identity` — a local identity primitive in an MCP server is a violation.**
+  Operator order 2026-10-09: no application, MCP server or starter defines its own primitive for
+  resolving a caller to a tenant, asserting membership of an organisation, filtering rows by a
+  caller's scope, or validating a master credential; identity lives only in
+  `@vantageos/cloud-identity`. The detector reports every site as `file:line` with its category and
+  enclosing declaration: local JWT verification (`jwtVerify`, `createRemoteJWKSet`, `jwt.verify`),
+  raw claim reads (`payload.org_id`), a populated `fromAllowList` attached locally, role comparisons,
+  name allow-lists (`fromAllowList.includes`, `roster.includes`, `isInAllowList`, iteration over a
+  roster), tenant row filters (`row.orgId === caller.orgSlug`), and local credential checks
+  (`timingSafeEqual`, `createHash("sha256")`, `createHmac`, `subtle.digest("SHA-256")`). A call
+  whose callee is bound from `@vantageos/cloud-identity` is not a site.
+- **EXEMPT, reported:** the `@vantageos/cloud-identity` package itself, and a site justified by
+  `// allow-local-identity: <reason ≥ 8 chars>`. **COULD-NOT-JUDGE:** a file that is not UTF-8
+  text or whose brackets never balance.
+- **`--local-identity-ceiling=N`** (default 0). One site over the ceiling is `non-conforming`
+  (exit 1); at or under it the row reads `present` and still lists every site.
+- Name and tenant compares are caught in every spelling: `===`, `!==`, `==`, `!=`, `Object.is`,
+  bracket reads, and case-folded or normalised operands (`toLowerCase()`, `normalize()`). Acting-name
+  fields (`createdBy`, `assignedTo`, `from`, `recipient`, `callerOrchestrator`, `orchestrator`, ...) are
+  compared to each other or to a caller name; an operand that is `undefined`, `null`, a boolean or a
+  number is a presence test and is not a site.
+- A digest over static content is not a credential digest: `subtle.digest` / `createHash().update`
+  over a string literal or a module-level constant made of literals (the CSP hash of a static
+  stylesheet, `authorize.ts:373`) is not reported. A keyed `createHmac`, and any digest of a value the
+  caller supplied, stay sites.
+- Measured on vantage-peers `mcp-server/src` at `8fb7c12`: 33 sites, exit 1.
+
+### Changed
+- The registry has one more detector (46). `tests/__oracle__/oracle-complete-server.static.json`
+  gains one `present` row; no existing row changed.
+
+---
+
+## 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

package/README.md

@@ -51,6 +51,9 @@ 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
+  --local-identity-ceiling=N
+                  local identity primitives tolerated before DLocalIdentity
+                  fails (default 0)
   --version       print the version and exit
   --help          print this and exit
 
@@ -63,8 +66,8 @@ exit: 0 clean, 1 a violation, 2 an abstention with no violation
 |---|---|---|
 | `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 |
+| `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:
 
@@ -73,16 +76,12 @@ The exit code keeps three outcomes distinct, which is what makes the tool safe i
 - **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:**
+**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.
-- **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.
@@ -94,12 +93,18 @@ green on 0.2.0 was green because nothing ran. Expect findings on the first run o
 ## Programmatic use
 
 ```ts
-import { runDoctor, renderTable } from "@vantageos/mcp-doctor";
+import { runDoctorReport, renderTable } from "@vantageos/mcp-doctor";
 
-const results = runDoctor("./mcp-server");
-console.log(renderTable("./mcp-server", results));
+const { results, skipped } = runDoctorReport("./mcp-server");
+console.log(renderTable("./mcp-server", results, skipped));
 ```
 
+`skipped` is the list of directories the run actually walked past (`node_modules`, `dist`, test
+material...), recorded by the walks as they skip them. `renderTable` prints it as the
+"skipped directories" section, so a report never reads as full coverage of a narrowed scope. Pass it
+through; called with two arguments, `renderTable` prints a "NOT REPORTED" line in its place.
+`runDoctor(target)` still returns the results alone.
+
 ## What it checks (MCP 2026-07-28)
 
 Each detector maps one standard item and is proven **bipolar** on real material: a genuine defect
@@ -115,6 +120,16 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D7** protocol-kit | `@vantageos/mcp-protocol-kit` listed in `package.json` **and actually called** (builder invoked, not merely declared) | listed+called / listed-not-called / hand-rolled |
 | **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 |
+| **DLocalIdentity** no-local-identity | No MCP server defines its own identity primitive: resolving a caller to a tenant or agent (local JWT verify, a populated allow-list attached to a bearer), asserting org membership or role, filtering rows by caller scope (`fromAllowList`, a name allow-list, a row's `orgId` or acting-name field such as `createdBy` / `assignedTo` compared to the caller's, by `===`, `==`, `Object.is` or after `toLowerCase()`), or validating a credential (local `timingSafeEqual`, a digest of a presented value, HMAC; a hash over a static literal is not a site). A call to a binding imported from `@vantageos/cloud-identity` is not a site. | present (0, or EXEMPT) / non-conforming (count > ceiling, default 0) / could-not-judge |
+
+**DLocalIdentity exemptions.** Two, both reported as `EXEMPT` rather than hidden: the
+`@vantageos/cloud-identity` package itself (read from the target's `package.json` name), and a site
+carrying `// allow-local-identity: <reason of 8 characters or more>` on the line, in the comment
+block directly above it, or above its enclosing top-level declaration. A marker with a shorter reason,
+or the retired `local-identity-exempt:` spelling, is not a justification and the site stays a violation. A file whose brackets never balance, or that is
+not UTF-8 text, is `could-not-judge`. To adopt the rule on a tree that still holds sites, pass
+`--local-identity-ceiling=<current count>` as a ratchet; the row then reads `present` and still lists
+every site.
 
 **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

package/dist/doctor.d.ts

@@ -10,13 +10,39 @@ interface SourceFile {
     rel: string;
     lines: SourceLine[];
 }
+/** A directory a walk declined to descend into, recorded AS the walk skipped it. */
+interface SkippedDir {
+    /** Path relative to the walk root, `/`-separated. */
+    path: string;
+    /** Why the canonical list excludes this directory name. */
+    reason: string;
+    /**
+     * Set only by a walk that probed the skipped directory for its own candidate
+     * inputs (C-26: a deploy-config file). Names the first candidate found there,
+     * relative to the walk root. Unset means "not probed", never "nothing there".
+     */
+    candidate?: string;
+}
 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;
+    /**
+     * Directories skipped on THIS run, recorded by the walks as they skip them
+     * (deduplicated by path). Mutable on purpose: a detector that walks the tree
+     * itself records into it through `recordSkip`. Never derived from the
+     * configured list: the report states what was walked past, not what could be.
+     */
+    skippedDirs: SkippedDir[];
 }
 
 type State = "present" | "absent" | "non-conforming" | "could-not-judge";
@@ -212,6 +238,15 @@ interface RunDoctorOptions {
  * `detectorList` is injectable for tests; production uses the full registry.
  */
 declare function runDoctor(target: string, detectorList?: Detector[], opts?: RunDoctorOptions): DetectorResult[];
+/**
+ * `runDoctor` plus the directories the run ACTUALLY skipped, read from the tree
+ * AFTER the detectors ran (a detector that walks the tree records its own skips
+ * into it). This is what the report's skipped-directories section prints.
+ */
+declare function runDoctorReport(target: string, detectorList?: Detector[], opts?: RunDoctorOptions): {
+    results: DetectorResult[];
+    skipped: SkippedDir[];
+};
 /**
  * Async runner — the ADDITIVE extension for *dynamique* rules that must CALL a
  * running server. It is a superset of the sync `runDoctor` static path, never a
@@ -234,7 +269,13 @@ declare function runDoctorAsync(target: string, opts?: {
     session?: Session;
     detectorList?: (Detector | LiveDetector)[];
 }): Promise<DetectorResult[]>;
-declare function renderTable(surface: string, results: DetectorResult[]): string;
+/**
+ * The skipped-directories section. A skipped directory narrows the scope of the
+ * run, and a report that does not say so reads as full coverage. Always
+ * rendered: an empty list says "none", it is never omitted.
+ */
+declare function renderSkipped(skipped: SkippedDir[]): string;
+declare function renderTable(surface: string, results: DetectorResult[], skipped?: SkippedDir[]): string;
 /**
  * The process exit code a run's results carry, three-way with precedence:
  *   1 — a VIOLATION: at least one detector is `non-conforming` (something IS
@@ -247,4 +288,4 @@ declare function renderTable(surface: string, results: DetectorResult[]): string
  */
 declare function computeExitCode(results: DetectorResult[]): number;
 
-export { type LiveDetector, type RunDoctorOptions, type RunMode, type Session, computeExitCode, isLiveDetector, renderTable, runDoctor, runDoctorAsync };
+export { type LiveDetector, type RunDoctorOptions, type RunMode, type Session, computeExitCode, isLiveDetector, renderSkipped, renderTable, runDoctor, runDoctorAsync, runDoctorReport };