@geonosis/doctor 2.10.0 → 2.11.0

package/dist/doctor-cli.js

@@ -4,7 +4,7 @@ import {
   formatDoctor,
   formatJson,
   runDoctor
-} from "./chunk-2ZVCJG5R.js";
+} from "./chunk-2VHAFVWH.js";
 
 // src/doctor-cli.ts
 import { fstatSync, statSync } from "fs";
@@ -138,6 +138,10 @@ var ABOUT = {
   seams: `The seam globs adoption.seams declares each name a file. A glob whose file was deleted and
               never undeclared measures nothing \u2014 every bump reads 0 deleted, 0 added over it \u2014 and a
               floor's adoption is measured by exactly those files.`,
+  formatter: `Whether the repo's own oxfmt would rewrite the kit's rule files under
+              .claude/rules/geonosis \u2014 tiers.md among them is generated. \`oxfmt --migrate=prettier\`
+              writes ignorePatterns: [], and the first format of a migrated repo did exactly that.
+              oxfmt is asked, so its ignore rules are read by the tool that applies them.`,
   exercised: `Every rule a config enables, against the corpus the loaded plugin ships. A rule at
               "error" that can never fire is indistinguishable from a clean tree. The line says what
               its number is evidence ABOUT \u2014 the corpus and the probes, never this tree \u2014 and a rule
@@ -184,7 +188,7 @@ var USAGE = `geonosis-doctor [--root <dir>] [--only <check,\u2026>] [--json] [--
 
 ${CHECKS.length} questions a version bump is not finished until something has asked. Most are ways
 enforcement has reported green while measuring nothing; drift asks whether the gate is still there
-at all, and the last two ask whether what was reported is what happened.
+at all, and observability and deployed ask whether what was reported is what happened.
 
 With no arguments it runs every one of them over the working directory. A tree holding no
 package.json and no .oxlintrc.json is REFUSED with exit 2 \u2014 there is nothing there to examine, and a
@@ -193,13 +197,13 @@ page of SKIPs is not a pass.
 ${CHECKS.map((check) => `  ${check.padEnd(11)} ${ABOUT[check]}`).join("\n\n")}
 
 exercised reads the corpus the loaded plugin ships, and \u2014 when geonosis.json names one under
-doctor.corpus \u2014 the corpus THIS repo ships for its own options. Three rules cannot be answered any
-other way: layer-walls fires on a repo's own layer names, no-brand-names on its brand, and
-plugin-route-namespaced on its package root, while the shipped corpus says acme and layers/core.
+doctor.corpus \u2014 the corpus THIS repo ships for its own options. A rule whose reach is the repo's
+own vocabulary \u2014 its layer names, its brand, its plugin package root, the within its sagas live
+in \u2014 cannot be answered any other way, while the shipped corpus says acme and layers/core.
 
   --print-config-shape   every file this reads, and the keys it reads out of each
 
-Every run writes .geonosis/envelopes/doctor.json: the eleven checks CONSIDERED against the ones this
+Every run writes .geonosis/envelopes/doctor.json: the ${CHECKS.length} checks CONSIDERED against the ones this
 run read, with the rest excused by name, so a --only run can never read as a verdict about the whole
 tree. The envelope check SKIPs that one file \u2014 this run is the one writing it.
 
@@ -256,6 +260,9 @@ geonosis.json \u2192 "law"
   maxLines        number?    the ceiling. Undeclared means UNJUDGED, never a default it fires on
 geonosis.json \u2192 "doctor"
   corpus          string?    the reach corpus this repo ships for its own rule options
+  apparatus       string[]?  directories whose .oxlintrc.json exists to EXERCISE rules over planted
+                             files \u2014 the source of a corpus, say \u2014 and is not asked which engine its
+                             manifests presume. A config inside a corpus needs no declaring
   groups          object[]?  { name, packages } sets of this repo's OWN packages that must resolve
                              to one version; declared and empty is a refusal. The kit's own fixed
                              group is checked when this is absent
@@ -336,11 +343,11 @@ var main = async () => {
   return report.ok ? 0 : 1;
 };
 try {
-  process.exit(await main());
+  process.exitCode = await main();
 } catch (error) {
   process.stderr.write(`geonosis-doctor: ${error.message}
 `);
-  process.exit(2);
+  process.exitCode = 2;
 }
 export {
   parseDoctorArgs

package/dist/index.d.ts

@@ -6,12 +6,11 @@ type Overrides = {
 /**
  * The questions a bump is not finished until something has asked, in the order a run asks them.
  * The first five are ways enforcement has reported green while measuring nothing; `envelope` asks
- * the arithmetic underneath all of them — whether a gate read as many things as it was handed;
- * `drift` asks whether the gate is still there at all; `observability` and `deployed` ask the same
- * question one layer out — whether what was reported is what happened; `rails` asks it of the
- * settings an unattended run is bounded by, where a rendered file is not a loaded setting.
+ * whether a gate read as many things as it was handed; `drift` whether the gate is still there;
+ * `observability` and `deployed` whether what was reported is what happened; `rails` the same of
+ * the settings an unattended run loads; `exams` and `seams` whether an adoption sees its floors.
  */
-declare const CHECKS: readonly ["loaded", "group", "exercised", "baseline", "runner", "envelope", "drift", "observability", "deployed", "rails", "exams", "seams"];
+declare const CHECKS: readonly ["loaded", "group", "exercised", "baseline", "runner", "envelope", "drift", "observability", "deployed", "rails", "exams", "seams", "formatter"];
 type CheckName = (typeof CHECKS)[number];
 /**
  * `SKIP` is a first-class answer and is printed like any other: a check whose line is missing reads
@@ -66,7 +65,7 @@ type RatchetConfig = {
     counters: Record<string, unknown>[];
 };
 type DoctorOptions = {
-    /** Where `~/.claude` lives — the plugin registry and the user settings the doctor reads; the home directory unless a caller says otherwise. */
+    /** Where `~/.claude` is, for the plugin registry and user settings; the home dir by default. */
     home?: string;
     /**
      * Present only when a baseline comparison was asked for, because making one is the one part of
@@ -95,6 +94,30 @@ type DoctorReport = {
     root: string;
 };
 
+/**
+ * Row 585: an `.oxlintrc.json` that exists to EXERCISE rules — the plugin's shipped corpus, a
+ * repo's own reach corpus — deliberately holds odd, partial and contradictory configuration,
+ * because that is what a fixture tree is for. Judged as though it governed a product it produced
+ * twenty-two WARNs about a tree nobody ships, and a reader who learns to skim those is a reader
+ * who skims the three lines that mean something.
+ *
+ * Apparatus is known STRUCTURALLY, never by a path list this package keeps (LAW 6): a config is
+ * apparatus when its directory is inside one the doctor already reads as evidence — the corpus
+ * the plugin ships (`corpusOfPlugin`), the corpus the repo declares (`geonosis.json` →
+ * `doctor.corpus`) — or inside one the repo names as such in `doctor.apparatus`, for a fixture
+ * tree that is the SOURCE of a corpus rather than a corpus itself. The default is empty: a repo
+ * that declares nothing has every config it holds judged, which is the safe direction — judging
+ * apparatus is noise, and ignoring a product config is a hole.
+ *
+ * The limit, stated: a fixture directory a repo neither ships as a corpus nor declares is still
+ * judged, by design.
+ */
+declare const APPARATUS_KEY = "apparatus";
+/** The directories `geonosis.json` names as apparatus, absolute; none when it names none. */
+declare const declaredApparatusOf: (root: string) => string[];
+/** The evidence directory a config sits in, if it sits in one at all. */
+declare const evidenceHolding: (config: DiscoveredConfig, evidence: readonly string[]) => string | undefined;
+
 /**
  * `origin/main`, when the repo has one. Never invented: a comparison against a ref that is not
  * there would either crash or, worse, be reported as a comparison that found nothing.
@@ -157,8 +180,8 @@ declare const READERS: Record<string, string>;
  *
  * Every line here is something that reads as green from the outside: a job that cannot run, a suite
  * nothing runs, a directory nothing reaches, a law nobody finishes, a plugin nobody installed, a
- * block nothing reads. The other four checks ask whether a gate measures what it names; this one
- * asks whether it is still there at all.
+ * block nothing reads. Most checks ask whether a gate measures what it names; this one asks whether
+ * it is still there at all.
  */
 declare const checkDrift: ({ readers, root, userSettings, workspaces }: {
     /**
@@ -222,6 +245,27 @@ declare const checkExercised: ({ config, corpus, entry, oxlint, repoCorpus, root
     root: string;
 }) => Promise<Finding>;
 
+type Constructible = {
+    create: (context: unknown) => unknown;
+};
+/**
+ * The option a rule says it is missing when constructed with these options, or undefined.
+ *
+ * Two shapes, because the doctor reads whatever plugin a config's directory resolves: a rule that
+ * THROWS its refusal from `create()` (the plugin up to 2.10.0, and any third-party plugin written
+ * that way), and a rule that answers a visitor which REPORTS the refusal on `Program` (the plugin
+ * from 2.11.0 — one attributable finding a run, in place of a throw that erased its neighbours).
+ * No filename: this is a question about the config, not a pass over a file, and a rule that has
+ * already answered for one file answers a fileless probe every time (#202).
+ */
+declare const missingOptionOf: (rule: Constructible, options: unknown[]) => string | undefined;
+
+declare const checkRequiredOptions: ({ config, entry }: {
+    config: DiscoveredConfig;
+    /** The plugin module oxlint loads from this config's directory. */
+    entry: string;
+}) => Promise<Finding[]>;
+
 /**
  * The packages that version as ONE number — the kit's method floor, as data a consumer's tree can
  * read.
@@ -243,18 +287,19 @@ type HeldTogether = {
 };
 declare const KIT_GROUP: HeldTogether;
 /**
- * The groups a repo declares for its OWN packages, under `doctor.groups` in `geonosis.json`. Law 6:
- * the kit's group is the default and a repo that declares nothing gets it; a repo that declares the
- * key and puts nothing in it is REFUSED, because "two copies are a bug" is a claim someone made and
- * an empty list cannot hold it.
+ * Row 549: this used to read `geonosis.json` for itself, with its own `catch { return undefined
+ * }` — a parse error read as "this repo declares no groups", the KIT_GROUP default, rather than a
+ * question nobody could answer. Routed through the one reader, `unreadable` throws rather than
+ * answering `absent`; `checkGroup` reads the file itself and turns that into a FAIL line the same
+ * way `checkSeams` and `checkRails` do, so a run over this repo still finishes.
  */
 declare const declaredGroupsOf: (root: string) => HeldTogether[] | undefined;
 /**
  * #158 — the group question nothing asked.
  *
- * during.day carried `@geonosis/visual-diff` at 1.1.0 and 1.4.0 in one tree and every doctor line
- * was green: `loaded` is scoped to the plugin a config names, so a second kit package at a second
- * version is outside every question it asks. This is the consumer-side mirror of
+ * A Workers + D1 app carried `@geonosis/visual-diff` at 1.1.0 and 1.4.0 in one tree and every
+ * doctor line was green: `loaded` is scoped to the plugin a config names, so a second kit package
+ * at a second version is outside every question it asks. This is the consumer-side mirror of
  * `geonosis-release published --group`.
  *
  * Asked of the RESOLVER from each workspace directory, never of `find` over `node_modules` — on
@@ -273,27 +318,46 @@ declare const checkGroup: ({ groups, root, workspaces }: {
  * MEASURED 2026-09-02 (`~/.claude/plugins/installed_plugins.json`, `version: 2`): a map keyed
  * `<plugin>@<marketplace>`, each value a list of installations carrying `version`, `installPath`
  * and the commit it came from. This is the file `claude plugin list` answers from.
+ *
+ * MEASURED 2026-09-18: an installation also carries `scope` (`user` or `project`) and, at project
+ * scope, the `projectPath` it loads in. One machine held `2.10.0` at user scope and `2.6.1` at
+ * project scope for another repo, and a doctor that read only `version` reported the second as
+ * this repo's drift (a Medusa storefront #13).
  */
 declare const INSTALLED_PLUGINS = ".claude/plugins/installed_plugins.json";
 /** The plugin this kit publishes. Its own name, the way `FIXED_GROUP` is its own group. */
 declare const PLUGIN_NAME = "geonosis";
+type InstalledPlugin = {
+    projectPath?: string;
+    scope?: string;
+    version: string;
+};
 /**
- * Every version of one plugin this machine has installed, in the order the record lists them.
+ * Every installation of one plugin this machine has, in the order the record lists them, with
+ * the scope each loads at.
  *
  * A name can be installed from more than one marketplace and at more than one scope, so this
- * answers with a list rather than picking one: a session loads what it loads, and a doctor that
- * chose for the reader would be reporting about an installation nobody has.
+ * answers with a list rather than picking one: which of them a session loads is a question about
+ * a ROOT, and `loadedAt` answers it.
  */
+declare const installedPlugins: (home: string, name: string) => InstalledPlugin[];
+/** Every version of one plugin this machine has installed, at any scope. */
 declare const installedPluginVersions: (home: string, name: string) => string[];
+/**
+ * The installations that LOAD in a session opened at `root`: a project-scoped install whose
+ * `projectPath` is this root wins, and only where none is does the user-scoped install load.
+ * A project-scoped install for another path loads nowhere here, whatever its version.
+ */
+declare const loadedAt: (installs: InstalledPlugin[], root: string) => InstalledPlugin[];
 /**
  * #133: a consumer's npm bump does not move the CLAUDE PLUGIN.
  *
  * The hooks, the agents and the skills live in the plugin, and it updates on `claude plugin update`
  * and never on an install — so a repo can be on this release's packages while every session in it
- * runs the hooks of the one before, and a refusal added this release cannot fire. That is the
- * declared-versus-loaded question one surface out, and it is this check's to ask.
+ * runs the hooks of the one before. That is the declared-versus-loaded question one surface out,
+ * and it is this check's to ask.
  */
-declare const checkClaudePlugin: ({ candidate, home, name, train }: {
+declare const checkClaudePlugin: ({ candidate, home, name, root, train }: {
     /**
      * Whether the packages here are a RELEASE CANDIDATE the registry has never seen — installed from
      * tarballs or a `file:` override. `claude plugin update` reads the marketplace, so it cannot
@@ -303,6 +367,8 @@ declare const checkClaudePlugin: ({ candidate, home, name, train }: {
     candidate?: boolean;
     home?: string;
     name?: string;
+    /** The repo being doctored — the root a project-scoped install has to name to load here. */
+    root?: string;
     /** The version the package train is on here, or nothing when this tree declares none. */
     train: string | undefined;
 }) => Finding[];
@@ -335,6 +401,20 @@ declare const checkLoaded: ({ configs, home, root, workspaces }: {
     workspaces: Workspace[];
 }) => Promise<Finding[]>;
 
+/**
+ * The exporter, asked three things: is one configured, can anything reach it, and has anything
+ * actually arrived lately.
+ *
+ * Two of the four lying instruments of `docs/rules-backlog.md` #42 are in this shape — a deploy job
+ * that reported success having deployed nothing, and a `/health` that answered ok over an
+ * unreachable database. Both leave a green build and a silent project, and neither is visible from
+ * inside the process that is not reporting.
+ *
+ * This check reads a FILE the consumer's sink wrote, and imports nothing of
+ * `@geonosis/observability`: a check that needed the library it checks cannot run in the tree where
+ * the library is missing, which is the first case it exists to find. The wall is planted in the
+ * plugin's `dogfood.bin.test.ts`.
+ */
 /** The record a sink writes on every capture. `@geonosis/observability` exports the same shape. */
 type LastEventRecord = {
     at?: unknown;
@@ -360,18 +440,14 @@ declare const checkObservability: ({ now, root }: {
 }) => Promise<Finding[]>;
 
 declare const GEONOSIS_FILE = "geonosis.json";
+
 /**
- * The reach corpus a repo ships for ITS OWN options, if it declares one.
- *
- * `exercised` asks whether an enabled rule can fire at all, against the corpus the PLUGIN ships.
- * That answers for most rules and cannot answer for the ones whose reach is a repo's vocabulary:
- * `layer-walls` fires on this repo's layer names, `no-brand-names` on its brand,
- * `plugin-route-namespaced` on its package root. The plugin's corpus says `acme` and `layers/core`,
- * so it is no evidence either way — and those rules read as firing nowhere in a tree that enforces
- * them perfectly well.
- *
- * A repo answers for its own options by shipping fixtures in its own vocabulary and naming, in that
- * corpus's own manifest, exactly which rules it is evidence about.
+ * Row 549: this used to read `geonosis.json` for itself, with its own `catch { return undefined
+ * }` — a parse error read as "this repo declares no corpus", the exact collapse `geonosis-file.ts`
+ * exists to make unrepresentable (measured 2026-09-17 alongside `deployed`, `seams`, `rails`: a
+ * truncated file, a green line). Routed through the one reader, `unreadable` throws rather than
+ * answering `absent` — a config nobody can read has not been read, and every question this would
+ * answer is answered from a default nobody chose.
  */
 declare const repoCorpusOf: (root: string) => string | undefined;
 
@@ -379,6 +455,14 @@ declare const formatDoctor: ({ counts, findings, ok, root }: DoctorReport) => st
 declare const formatJson: (report: DoctorReport) => string;
 
 /**
+ * What oxlint would load, asked the only way that answers on every package manager.
+ *
+ * oxlint resolves a `jsPlugins` specifier from the CONFIG FILE's directory, not the working
+ * directory, so the question is asked from a directory and never from the process's cwd. And it is
+ * asked of the RESOLVER: counting copies with `find` is a bun/npm check only — on pnpm the entries
+ * under `node_modules/@scope/` are symlinks into `.pnpm/`, which keeps every version ever
+ * installed, so the same count answers 7 on a correct tree and 0 with the store excluded.
+ *
  * `root` is the directory the doctor was HANDED — the boundary a deployed tree actually has. A
  * package on the way up from `dir` but past `root` is not this tree's to see; #373/#386 measured
  * the kit's own workspace two directories above a consumer's checkout read exactly that way.
@@ -435,4 +519,4 @@ declare const checkRunner: ({ ratchet, root, workspaces }: {
     workspaces: Workspace[];
 }) => Finding[];
 
-export { CHECKS, COMPOSITION_ROOT, CONFIG_FILE, type CheckName, DEPLOYED_FILE, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, ENVELOPES_DIR, FIXED_GROUP, FLOOR_PACKAGES, type Finding, GEONOSIS_FILE, type HeldTogether, INSTALLED_PLUGINS, KIT_GROUP, type LastEventRecord, MANIFEST_FILE, type Manifest, NOT_WRITTEN, NO_ENVELOPES, type ObservabilityConfig, PLUGIN_NAME, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkClaudePlugin, checkDeployed, checkDrift, checkEnvelopes, checkExams, checkExercised, checkGroup, checkLoaded, checkObservability, checkRunner, corpusOfPlugin, declaredFor, declaredGroupsOf, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, formatDoctor, formatJson, installedPluginVersions, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };
+export { APPARATUS_KEY, CHECKS, COMPOSITION_ROOT, CONFIG_FILE, type CheckName, DEPLOYED_FILE, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, ENVELOPES_DIR, FIXED_GROUP, FLOOR_PACKAGES, type Finding, GEONOSIS_FILE, type HeldTogether, INSTALLED_PLUGINS, type InstalledPlugin, KIT_GROUP, type LastEventRecord, MANIFEST_FILE, type Manifest, NOT_WRITTEN, NO_ENVELOPES, type ObservabilityConfig, PLUGIN_NAME, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkClaudePlugin, checkDeployed, checkDrift, checkEnvelopes, checkExams, checkExercised, checkGroup, checkLoaded, checkObservability, checkRequiredOptions, checkRunner, corpusOfPlugin, declaredApparatusOf, declaredFor, declaredGroupsOf, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, evidenceHolding, formatDoctor, formatJson, installedPluginVersions, installedPlugins, loadedAt, missingOptionOf, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  APPARATUS_KEY,
   CHECKS,
   COMPOSITION_ROOT,
   CONFIG_FILE,
@@ -27,17 +28,23 @@ import {
   checkGroup,
   checkLoaded,
   checkObservability,
+  checkRequiredOptions,
   checkRunner,
   corpusOfPlugin,
+  declaredApparatusOf,
   declaredFor,
   declaredGroupsOf,
   defaultRef,
   discoverConfigs,
   discoverWorkspaces,
   enabledRulesOf,
+  evidenceHolding,
   formatDoctor,
   formatJson,
   installedPluginVersions,
+  installedPlugins,
+  loadedAt,
+  missingOptionOf,
   packageDirOf,
   pluginVersionOf,
   readConfig,
@@ -48,8 +55,9 @@ import {
   resolveFrom,
   runDoctor,
   satisfies
-} from "./chunk-2ZVCJG5R.js";
+} from "./chunk-2VHAFVWH.js";
 export {
+  APPARATUS_KEY,
   CHECKS,
   COMPOSITION_ROOT,
   CONFIG_FILE,
@@ -78,17 +86,23 @@ export {
   checkGroup,
   checkLoaded,
   checkObservability,
+  checkRequiredOptions,
   checkRunner,
   corpusOfPlugin,
+  declaredApparatusOf,
   declaredFor,
   declaredGroupsOf,
   defaultRef,
   discoverConfigs,
   discoverWorkspaces,
   enabledRulesOf,
+  evidenceHolding,
   formatDoctor,
   formatJson,
   installedPluginVersions,
+  installedPlugins,
+  loadedAt,
+  missingOptionOf,
   packageDirOf,
   pluginVersionOf,
   readConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/doctor",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "types": "./dist/index.d.ts",
   "description": "The adoption doctor — declared ≠ loaded, enabled ≠ exercised, a baseline that grew, a runner whose exit code is the only verdict.",
   "keywords": [
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@geonosis/lint-parity": "2.10.0"
+    "@geonosis/lint-parity": "2.11.0"
   },
   "devDependencies": {
-    "@geonosis/ratchet": "2.10.0"
+    "@geonosis/ratchet": "2.11.0"
   },
   "peerDependencies": {
     "oxlint": ">=1.77"
@@ -51,7 +51,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsx ../../tooling/build-step.ts tsup",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint --config ../../.oxlintrc.json .",
     "test:unit": "vitest run --project unit --root ../.. --passWithNoTests \"$PWD\"",