@geonosis/doctor 1.0.0 → 1.2.0

package/README.md

@@ -1,22 +1,27 @@
 # @geonosis/doctor
 
-Five questions a version bump is not finished until something has asked. The first four are ways
+Seven questions a version bump is not finished until something has asked. The first four are ways
 enforcement has reported **green while measuring nothing** — in real repos, for weeks at a time.
-The fifth asks whether the gate is still there at all.
+`drift` asks whether the gate is still there at all. The last two ask the same question one layer
+out: whether what a pipeline reported is what actually happened.
 
 ```bash
 pnpm add -D @geonosis/doctor
 npx geonosis-doctor
 ```
 
-Run it **after every bump** and **in CI**. It exits 1 when any line is a FAIL, 2 when the run could
-not be made at all.
+Run it **after every bump** and **in CI**. It exits 1 when any line is a FAIL or an UNJUDGED — a
+question it could not ask is not a pass — and 2 when the run could not be made at all.
 
 ```
 geonosis-doctor [--root <dir>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
 ```
 
-## The five checks
+## One check, asked alone
+
+`geonosis-doctor --only loaded` runs that check and no other, in well under a second: a manifest read and a resolution per config. It exists because the doctor subsumed a consumer's own declared-vs-loaded script that lived in a 2.5 s local gate, and eleven seconds for seven checks cannot live there — so the question that catches a stale nested copy earliest had fallen out of the gate that runs most often (during.day, 2026-08-30: `bun add` across eleven workspaces left `packages/workflows` loading 1.0.0 against configs written for 1.1.0, and the script about to be deleted caught it). `--only loaded,runner` takes a list; a name the doctor does not have is refused with the seven it does. A `loaded` FAIL now says the remedy: remove the nested copies and reinstall.
+
+## The seven checks
 
 ### `loaded` — declared ≠ loaded
 
@@ -66,6 +71,51 @@ that ships no corpus is a SKIP: it never claimed to be evidence about anything.
 A rule enabled without the options it needs makes oxlint refuse. That refusal is reported as the
 finding — with the sentence naming the rule, which takes a second run to obtain (see below).
 
+#### The probe a rule declares for itself
+
+A rule whose REACH is an option can never fire on a fixed corpus. The fixtures say `acme` and
+`corpus/workflows/`; a repo says its own brand and `packages/workflows/src/`, and the rule reads as
+firing nowhere in a tree that enforces it on every file. Both source repos reported exactly that
+against themselves on 2026-08-30, and both were right about the fact.
+
+So an option-gated rule declares a `probe(options)` beside its `fixShape`, returning the smallest
+source that must fire it under the options it was handed, at a path that lands where it looks. When
+a rule fires nowhere, this writes that probe into a **copy of the corpus** — beside the fixtures,
+because a rule that reads a sibling off disk is answering about a tree — and runs it again:
+
+```
+OK       .oxlintrc.json: 17 enabled, 17 exercised — 1 through its declared probe under this repo's options
+FAIL     .oxlintrc.json: 1 enabled rule fires nowhere in the corpus and nothing through the probe it
+         declares either: bio/no-unregistered-plugin-dir under [{"roots":…,"registry":…}]
+UNJUDGED .oxlintrc.json: bio/atom-no-deps declares no probe, so its scope does not reach the corpus
+```
+
+**It does not soften the check.** A probe that was PLACED under this repo's options and still fired
+nothing is a FAIL naming the option VALUES — the question was asked and the answer was no, and the
+values are what a reader has to go and look at.
+
+A rule with no probe, or one whose options admit no constructible path, is **UNJUDGED**: the
+question could not be ASKED. That is not a pass — the run still exits non-zero — and it is not a
+failure either, because a FAIL over a rule a repo is enforcing on every file reads as an invitation
+to delete the rule, and one consumer names exactly such a rule as live enforcement in its own law.
+The sentence says why the corpus cannot answer instead.
+
+The probes are read off the plugin the config LOADS, the way `loaded` reads its version — this
+package still depends on no rule plugin. A plugin too old to declare any answers with none, and the
+check behaves exactly as it did before they existed.
+
+The probe's PATH is half of it. `step-opens-its-own-cell` records zero findings against the shipped
+corpus not because its source is wrong but because the fixture is at `corpus/workflows/` and the
+consumer's `within` says `packages/workflows/src/` — the same bytes at the second path fire. So a
+probe derives its path from the option, never from a fixed corpus location, and
+`lib/probe.ts`'s `pathMatching` builds one back out of the regex and then tests it against that
+regex, refusing with a sentence rather than placing a file the rule will never look at.
+
+One rule cannot be probed by a single file and says so: `no-unregistered-plugin-dir` reports a
+directory its registry does not name and reads that registry off disk, so the probe fires only when
+the configured registry is also in the tree. Widening it until it fired would be the rule claiming
+evidence it does not have, which is the defect the rule itself is about.
+
 #### The corpus a shipped one cannot be
 
 Three rules cannot be answered by the plugin's corpus at all, because their reach is a **repo's own
@@ -112,8 +162,20 @@ other people are working in.
 
 `@cloudflare/vitest-pool-workers` exited 0 over suites it had just reported as failing, for weeks,
 in a consumer, so every gate that trusted the status read green over red. A workspace whose `test`
-script runs vitest or `bun test` without asking for a JSON report, and which no `testFailures`
-counter in report mode covers, gets a WARN. `--strict` makes it a FAIL.
+script runs **vitest** without asking for a JSON report, and which no `testFailures` counter in
+report mode covers, gets a WARN. `--strict` makes it a FAIL.
+
+`bun test` is a different answer, because it is a different runner and it was measured: on bun 1.4.0
+a planted failing assertion exits 1, so does an awaited one, so does a throw in `afterAll`, and an
+all-passing run exits 0. Its exit code IS the verdict, so a bun workspace is OK and the line says so
+naming bun. It used to be warned with vitest's sentence — eight lines of it in one consumer's
+report, each blaming a runner the check had not read, which is how a reader learns to skim the
+section and miss the vitest lines beside them that are true.
+
+The message names the runner it read. What it does not do is see through a wrapper: a script that
+runs `bun ./scripts/vitest-strict.ts` reads as neither, and that consumer's wrapper is in fact the
+exemplary fix — it spawns vitest with `--reporter=json`, reads the report, and fails on a missing
+one. The verdict is right and the sentence understates it.
 
 ### `drift` — the gate that is no longer there
 
@@ -128,6 +190,35 @@ The other four ask whether a gate measures what it names. This one asks whether
 | `.claude/settings.json` | WARN | nothing installs the kit's plugin, so the gates run and the method does not (D-041) |
 | `geonosis.json` blocks | WARN | a block whose package is not installed — nothing reads it — or an installed package with no block, running on defaults nobody chose |
 
+### `observability` — a sink nobody can reach
+
+The exporter named by the `observability` block in `geonosis.json`: is a sink configured, is its
+endpoint reachable, and did an event arrive inside `maxAgeSeconds`. Read from the `lastEventFile`
+the sink writes — never by importing the library being checked, because a check that needs the
+library cannot run in the tree where the library is missing.
+
+### `deployed` — declared ≠ deployed
+
+`wrangler versions upload` applies no triggers. A cron or a route edited in the config is therefore
+silently ignored in production for ever, with a green pipeline; `wrangler secret put` creates AND
+deploys a version outside the gate entirely. Nothing in either source repo measured any of it.
+
+`.geonosis/deployed.json` is what the consumer's pipeline writes **after promote** — the versions,
+the crons and routes it applied, the secret names and the binding names. This line compares it
+against what the tree declares: the wrangler configs `geonosis.json` → `release.wrangler` names
+(JSON or JSONC, with `release.wranglerEnv` selecting an environment block, because named
+environments inherit nothing per binding) and `release.secrets`.
+
+| | |
+|---|---|
+| the file is absent | **SKIP**, with the sentence: it is written by the pipeline after promote, and its absence is not a pass |
+| `release.wrangler` and `release.secrets` are both empty | **SKIP** — this repo has declared nothing a deployment is supposed to carry |
+| a config it was told to read cannot be read | **FAIL** — a config nobody can parse is a finding, never a skip |
+| anything declared is not deployed, or anything deployed is not declared | **FAIL**, naming each |
+
+It reads the file, and imports nothing of `@geonosis/release` — the same wall `observability` keeps,
+held by the kit's own `layer-walls` config, so a repo can install either package alone.
+
 ## What `--format=unix` does not tell you
 
 Measured on oxlint 1.80: a JS plugin rule that throws from `create()` is reported **once per file**,
@@ -150,7 +241,7 @@ The whole report, for a CI step to read:
 
 ```json
 {
-  "counts": { "FAIL": 1, "OK": 12, "SKIP": 2, "WARN": 0 },
+  "counts": { "FAIL": 1, "OK": 12, "SKIP": 2, "UNJUDGED": 0, "WARN": 0 },
   "findings": [{ "check": "loaded", "message": "…", "subject": "apps/web/.oxlintrc.json", "verdict": "FAIL" }],
   "ok": false,
   "root": "/repo"
@@ -160,8 +251,9 @@ The whole report, for a CI step to read:
 ## What it does not depend on
 
 Not the rule plugin. This tool asks which plugin a config loads; a copy of that plugin in its own
-dependency tree would be one more copy for the question to be wrong about. It depends on
-`@geonosis/lint-parity` for the reach engine and on nothing else, and the kit's own `layer-walls`
-config holds that wall.
+dependency tree would be one more copy for the question to be wrong about. Not
+`@geonosis/observability` and not `@geonosis/release` either: both of those lines read a FILE the
+consumer wrote. It depends on `@geonosis/lint-parity` for the reach engine and on nothing else, and
+the kit's own `layer-walls` config holds every one of those walls.
 
 Apache-2.0.

package/bin/geonosis-doctor.mjs

@@ -1,4 +1,27 @@
 #!/usr/bin/env node
 // Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
 // produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
-import '../dist/doctor-cli.js'
+//
+// In the repo, `src/` sits beside `dist/`, and a dist older than src answered for a fix it did not
+// carry once (#62). The published package ships no src, so there the check is skipped.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const newest = (dir) =>
+  existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true }).reduce((most, entry) => {
+        const at = join(dir, entry.name)
+        return Math.max(most, entry.isDirectory() ? newest(at) : statSync(at).mtimeMs)
+      }, 0)
+    : 0
+const src = join(here, '..', 'src')
+if (existsSync(src) && newest(src) > newest(join(here, '..', 'dist'))) {
+  process.stderr.write(
+    'geonosis-doctor: dist is older than src — run pnpm build before trusting this bin.\n',
+  )
+  process.exit(2)
+}
+
+await import('../dist/doctor-cli.js')