@geonosis/doctor 1.1.0 → 1.3.0

package/README.md

@@ -13,10 +13,19 @@ npx geonosis-doctor
 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.
 
+**A directory that is not a project is a 2, not a pass.** With no `package.json` and no
+`.oxlintrc.json` anywhere under the root there is nothing here to examine, and every line it would
+print is about a gate that is not there. It used to answer `doctor PASS` at exit 0 off six SKIPs and
+three vacuous OKs — from the tool whose thesis is that a SKIP is not a pass.
+
 ```
 geonosis-doctor [--root <dir>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
 ```
 
+## 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
@@ -46,6 +55,26 @@ npm and pnpm alike.
 A declared range this check cannot read is a **FAIL**, not a pass. A version it cannot judge is a
 refusal.
 
+## The options a rule actually runs under
+
+Every reader here that consumes a rule's configuration reads `overrides[]` as well as `rules`, and
+resolves them the way oxlint does — **measured**, not assumed, against oxlint 1.80:
+
+- an override entry naming a rule again **replaces** its options for the files its `files` globs
+  claim; nothing is deep-merged into the base;
+- when several overrides claim one file, the **last** of them wins outright;
+- a rule an override names and the base block never mentions is **enabled**, on those files.
+
+Reading `rules` alone is one config with two answers. dielime registers its Medusa providers from
+three files — a base `medusa-config.ts` and two carrier registries — and declares that exactly
+where oxlint reads it, in overrides naming the carrier directories. The rule resolved it; `drift`
+read the base object and reported two working carriers as directories the registry "never names";
+`exercised` would have called a rule enabled only in an override "not enabled here" and skipped it.
+
+The glob subset understood is `**` across segments, `*` and `?` within one, and `{a,b}`; a pattern
+with no separator matches a basename anywhere. Like `pathMatching` in the rule plugin, it is a
+subset that says so rather than a dependency that would have to be right about everything.
+
 ### `exercised` — enabled ≠ exercised
 
 A rule at `"error"` over a tree with no violation of it, and a rule at `"error"` that can never
@@ -107,10 +136,14 @@ 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.
+A probe declares FILES, not a file. `no-unregistered-plugin-dir` reports a directory its registry
+does not name and reads that registry off disk, returning silently when it is not there — so one
+file could never exercise it, and dielime, enforcing it at error over four registries, read as a
+permanent FAIL for a gate that was working. Its probe now declares the directory AND the registry,
+and every file a probe declares is mounted into the copy. A probe declaring only `{ path, source }`
+is the one-file case of the same thing and is read unchanged, which matters: this reads probes off
+the plugin build the consumer has INSTALLED, and every build published before this shape existed
+answers in the bare form.
 
 #### The corpus a shipped one cannot be
 
@@ -168,6 +201,10 @@ naming bun. It used to be warned with vitest's sentence — eight lines of it in
 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.
 
+A workspace whose test script runs a runner over **zero test files** is a SKIP, not a warning:
+dielime's `packages/eslint-config` runs `vitest run` and has no test file under it, so there is no
+result for an exit code to be wrong about. The message says what was counted.
+
 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
@@ -181,10 +218,39 @@ The other four ask whether a gate measures what it names. This one asks whether
 |---|---|---|
 | `.github/workflows/*.yml` | FAIL | a job or step switched off by a condition that can never be true. One consumer carried 90 tests, a pgvector container and an E2E suite and ran none of it, the disablement documented as "TEMPORARY" in a comment. It is "never downgrade a rule", one level up |
 | test files | FAIL | a `*.test.*` file with no `test` script in any workspace from it up to the root. A monorepo that runs one vitest over the whole tree has no orphan in it, and this says so |
+| script paths | FAIL | a `scripts` entry that hands `bun`, `node` or `tsx` a file that is not on disk. during.day's `bun run fast` began `bun scripts/check-plugin-version.ts && …` and the script had been deleted: the 2.5 s gate had failed at its first command for as long as nobody looked. Only a word with a file extension is asked about, so `bun test`, `bun run lint` and `node --version` are not paths |
+| generated files | FAIL | a file carrying `geonosis:gated-by: <gate>` that nothing here runs the gate for — checked against every manifest script, every ratchet counter command and every workflow, because what matters is that SOMETHING runs it. A file that names its **writer** and no gate at all fails on that alone: during.day's AGENTS.md is a 1,117-line byte-copy of its own law, written by `geonosis sync`, and nothing ever ran `sync --check` — the doctor stood beside it warning about the shorter original |
+| `NODE_OPTIONS` | WARN | a manifest script preloading through `NODE_OPTIONS` beside a ratchet counter whose command shells to `pnpm`. The nested pnpm inherits the option: dielime's ts5 shim sent it looking for a `.pnpmfile.mjs` that is not there, the counter died, the ratchet refused correctly, and nothing in the message was near the cause. Both halves must be present, and the line names the script and the counter |
+| workspace bins | FAIL | a script calling a bin THIS repo's own workspaces declare, with no `node_modules/.bin/<name>` at the root. pnpm links a workspace bin only for the packages that depend on it: dielime's `@dielime/gate-tools` had to become an explicit root devDependency before the gate scripts could find it, and naming that took a debugging session. External commands are not judged — that would be a guess |
 | plugin directories | FAIL | a manifest directory under the roots `no-unregistered-plugin-dir` names that the registry never mentions. SKIP when the rule is not configured — the roots are the repo's, read from the rule it already wrote, never a list invented here |
-| the law | WARN | its measured length against `geonosis.json` → `law.maxLines` (200 by default). dielime is 382, during.day 1,104 |
-| `.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 |
+| `publicHoistPattern` | FAIL / SKIP | a pattern in `pnpm-workspace.yaml` with no root `node_modules` link for a workspace package it matches. pnpm dropped one during an **unrelated** `add`, then answered "Already up to date" to every install afterwards over a clean `git status` — the tree was fixed only by deleting `.modules.yaml` and `.pnpm-workspace-state-v1.json`, which the line carries verbatim. Only workspace packages are judged, because one exists on disk by construction and a missing link for it cannot be "the install never ran"; the root package is never asked about, since no package manager puts a repo's root inside its own `node_modules`. A pattern matching no workspace package is SKIP, never a pass |
+| the law | WARN / SKIP | its measured length against `geonosis.json` → `law.maxLines`. **SKIP when the repo declares no ceiling** — during.day read "1,104 lines against a ceiling of 200" for a number it never chose, which is unactionable in both directions. The length is still printed, because that is the number a repo declares against |
+| `.claude/settings.json` | WARN | nothing under `enabledPlugins` enables the kit's plugin, so the gates run and the method does not (D-041). The **user-scope** `~/.claude/settings.json` is read too and acknowledged as "installed elsewhere — not this repo's to declare": both source repos got this WARN while the plugin was installed machine-wide. The key is read, never the word `geonosis` appearing somewhere in the file |
+| `geonosis.json` blocks | WARN | a block whose package **no manifest declares** — nothing reads it, and a stale `node_modules` copy is named as what a previous install left behind; a block whose package is declared and does not resolve — run the install; or a **declared** package with no block, running on defaults nobody chose |
+
+The two directions do not read the same source. Whether a repo still *chose* a package is a question
+for the **manifests**: a `release` block whose package had been removed from every manifest, with a
+stale `node_modules` directory still present, resolved perfectly and the check said nothing (#78).
+Whether a tool will actually load is the forward question, and that one is resolution's.
+
+The "installed with no block" direction is scoped to **direct** dependencies. `@geonosis/review` and
+`@geonosis/testbed` arrive transitively through `@geonosis/cli`, and asking a consumer to configure
+a package they never installed is noise — which is how a reader learns to skip the section (#61). A
+transitive presence gets an OK line naming where it came from, and no demand.
+
+#### A geonosis bin a git hook cannot start
+
+Every committed hook — `lefthook.yml`, `.husky/*`, `.githooks/*` — is read, and a line running a
+geonosis bin through `pnpm`, `npx`, `bunx` or `yarn` is a **FAIL** naming the direct call that
+replaces it.
+
+A git hook's PATH is not the shell's: no nvm shim, no corepack shim, nothing a version manager put
+there. dielime's first hooked commit was "refused" on 2026-08-30 and the ledger never ran — `pnpm`
+was not found, and the sentence its author read was a version manager's failure wearing a gate's
+refusal costume. That is the worst shape a gate has, because it is indistinguishable from the gate
+working. `node_modules/.bin/<bin>` is linked by every package manager and needs nothing on PATH.
+
+A hook file naming no geonosis bin is a **SKIP** with the sentence, never a vacuous OK.
 
 ### `observability` — a sink nobody can reach