@geonosis/doctor 1.2.0 → 1.4.0

package/dist/doctor-cli.js

@@ -3,58 +3,72 @@ import {
   formatDoctor,
   formatJson,
   runDoctor
-} from "./chunk-ZJCUTDQW.js";
+} from "./chunk-R4OLFNI6.js";
 
 // src/doctor-cli.ts
 import { resolve } from "path";
-var USAGE = `geonosis-doctor [--root <dir>] [--only <check,\u2026>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
-
-Five questions a version bump is not finished until something has asked. The first four are ways
-enforcement has reported green while measuring nothing; the fifth asks whether it is still there.
-
-  loaded      The plugin oxlint would LOAD from each config's directory, against the version that
+var ABOUT = {
+  baseline: `The ratchet's numbers at HEAD against another ref. A ratchet lowers its own baseline
+              when a number shrinks, so nothing inside one checkout can see a branch raise one back
+              up. OFF unless asked for: it is the only check that runs git, and this tool is run
+              over repos other people are working in.`,
+  deployed: `What the pipeline REPORTED deploying, in .geonosis/deployed.json, against what the
+              tree declares in the wrangler configs geonosis.json names and release.secrets.
+              "versions upload" applies no triggers, so a cron edited in a config is silently
+              ignored in production for ever with a green pipeline; a secret can be put outside the
+              gate entirely. SKIPs with the sentence when the file is absent \u2014 its absence is not a
+              pass \u2014 and reads the file rather than importing @geonosis/release.`,
+  drift: `The gates that were set up and are no longer running: a CI job switched off by a
+              condition that can never be true, a test file under a workspace with no test script, a
+              script handing bun/node/tsx a file that is not on disk, a workspace bin nothing links,
+              an integration directory the registry never names, a geonosis bin a git hook calls
+              through pnpm/npx/bunx and therefore cannot start, a law over the ceiling its own
+              geonosis.json declared, nothing enabling the plugin in either scope, and a
+              geonosis.json block no manifest declares a package for (or the reverse).`,
+  envelope: `The arithmetic under every other line: for each .geonosis/envelopes/<tool>.json a gate
+              wrote, considered === read + refused + excused. Four denominator bugs landed in one
+              day and every one of them was GREEN \u2014 a migrations run that reported on three of four
+              files, a plan check that printed "PASS \u2014 0 plan(s)" over a directory of twenty-one, a
+              parity run over a tree the second config ignored. Each published a numerator and no
+              denominator. Reads the files and imports nothing of the tools that wrote them; no
+              envelopes at all is a SKIP with the sentence.`,
+  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.`,
+  loaded: `The plugin oxlint would LOAD from each config's directory, against the version that
               config's workspace DECLARES. oxlint resolves a jsPlugins specifier from the CONFIG
               FILE's directory, so a nested copy left behind by a per-workspace install runs while
               every manifest and the lockfile say otherwise \u2014 one consumer measured a whole bug
               report against 0.3.0 on a repo pinned to 0.4.0. Every copy is found by RESOLUTION,
-              never by find: on pnpm the store keeps every version ever installed.
-
-  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.
-
-  baseline    The ratchet's numbers at HEAD against another ref. A ratchet lowers its own baseline
-              when a number shrinks, so nothing inside one checkout can see a branch raise one back
-              up. OFF unless asked for: it is the only check that runs git, and this tool is run
-              over repos other people are working in.
-
-  runner      Workspaces whose test script's exit code is the only verdict. A pool exited 0 over
-              suites it had just reported as failing, for weeks, in a consumer.
-
-  observability
-              The exporter named by the "observability" block in geonosis.json: is a sink
+              never by find: on pnpm the store keeps every version ever installed.`,
+  observability: `The exporter named by the "observability" block in geonosis.json: is a sink
               configured, is its endpoint reachable (a HEAD with a short timeout), and did an event
               arrive inside maxAgeSeconds \u2014 read from the lastEventFile the sink writes, never from
               this tool importing the library it is checking. A deploy job reported success having
               deployed nothing and a /health answered ok over a dead database on the same
-              afternoon; both left a green build and a silent project.
-  drift       The gates that were set up and are no longer running: a CI job switched off by a
-              condition that can never be true, a test file under a workspace with no test script,
-              an integration directory the registry never names, a law over the ceiling its own
-              geonosis.json set, no .claude/settings.json installing the plugin, and a
-              geonosis.json block whose package is not installed (or the reverse).
+              afternoon; both left a green build and a silent project.`,
+  runner: `Workspaces whose test script's exit code is the only verdict. A pool exited 0 over
+              suites it had just reported as failing, for weeks, in a consumer. A script with no
+              test file under it is a SKIP \u2014 there is no result for an exit code to be wrong about.`
+};
+var USAGE = `geonosis-doctor [--root <dir>] [--only <check,\u2026>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
 
-  deployed    What the pipeline REPORTED deploying, in .geonosis/deployed.json, against what the
-              tree declares in the wrangler configs geonosis.json names and release.secrets.
-              "versions upload" applies no triggers, so a cron edited in a config is silently
-              ignored in production for ever with a green pipeline; a secret can be put outside the
-              gate entirely. SKIPs with the sentence when the file is absent \u2014 its absence is not a
-              pass \u2014 and reads the file rather than importing @geonosis/release.
+${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.
+
+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
+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.
 
+  --print-config-shape   every file this reads, and the keys it reads out of each
+
 Exits 1 when any line is a FAIL or an UNJUDGED \u2014 a question this could not ask is not a pass \u2014 and
 2 when the run could not be made at all. --strict promotes every WARN to a FAIL. --json prints the
 whole report for a CI step to read.`;
@@ -100,10 +114,43 @@ var parseDoctorArgs = (argv, cwd) => {
     strict
   };
 };
+var CONFIG_SHAPE = `geonosis-doctor reads geonosis.json, geonosis.ratchet.json, .oxlintrc.json,
+pnpm-workspace.yaml and .claude/settings.json
+
+geonosis.json \u2192 "law"
+  file            string?    the law file to measure (default "CLAUDE.md")
+  maxLines        number?    the ceiling. Undeclared means UNJUDGED, never a default it fires on
+geonosis.json \u2192 "observability"
+  sink            string     where this repo sends its errors
+  endpoint        string     the URL that must be reachable
+  lastEventFile   string     the file the sink writes on arrival
+  probe           string?    a command that answers instead of lastEventFile
+  maxAgeSeconds   number     how old the last event may be
+geonosis.json \u2192 "release"
+  wrangler        string[]   the wrangler configs a deployment carries
+  wranglerEnv     string?    the named environment block to read
+  secrets         string[]   the secret names it carries
+.oxlintrc.json
+  jsPlugins       string[]   the plugin specifiers oxlint would load
+  rules           object     the base rules, and the options each was given
+  overrides       object[]   files + rules; an entry REPLACES a rule's options for the files it
+                             claims, last match winning \u2014 the same resolution oxlint does
+geonosis.ratchet.json
+  the ratchet's own \u2014 run \`geonosis-ratchet --print-config-shape\`
+pnpm-workspace.yaml
+  publicHoistPattern  string[]   the packages this repo claims are linked at the root, read as
+                                 text; a "*" is the only wildcard and it spans "/"
+.claude/settings.json
+  enabledPlugins  object     what installs the kit's plugin in THIS repo`;
 var main = async () => {
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h")) {
     process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
+  if (argv.includes("--print-config-shape")) {
+    process.stdout.write(`${CONFIG_SHAPE}
 `);
     return 0;
   }

package/dist/index.d.ts

@@ -1,10 +1,16 @@
+type Overrides = {
+    files: readonly string[];
+    rules: Record<string, unknown>;
+}[];
+
 /**
  * The questions a bump is not finished until something has asked, in the order a run asks them.
- * The first four are ways enforcement has reported green while measuring nothing; `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.
+ * The first four 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.
  */
-declare const CHECKS: readonly ["loaded", "exercised", "baseline", "runner", "drift", "observability", "deployed"];
+declare const CHECKS: readonly ["loaded", "exercised", "baseline", "runner", "envelope", "drift", "observability", "deployed"];
 type CheckName = (typeof CHECKS)[number];
 /**
  * `SKIP` is a first-class answer and is printed like any other: a check whose line is missing reads
@@ -29,6 +35,7 @@ declare class DoctorError extends Error {
     constructor(message: string);
 }
 type Manifest = {
+    bin?: Record<string, string> | string;
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
     name?: string;
@@ -47,6 +54,8 @@ type DiscoveredConfig = {
     /** Why this config could not be read. A config nobody can parse is a finding, never a skip. */
     error?: string;
     jsPlugins: string[];
+    /** Layers that REPLACE a rule's options for the files they claim — never merged into the base. */
+    overrides: Overrides;
     path: string;
     relative: string;
     rules: Record<string, unknown>;
@@ -138,7 +147,7 @@ declare const READERS: Record<string, string>;
  * 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.
  */
-declare const checkDrift: ({ readers, root, workspaces, }: {
+declare const checkDrift: ({ readers, root, userSettings, workspaces, }: {
     /**
      * Which package reads which block. It is a parameter so a test can name one that can NEVER be
      * installed: a fixture that turns on whether some real package happens to be present on the base
@@ -147,9 +156,35 @@ declare const checkDrift: ({ readers, root, workspaces, }: {
      */
     readers?: Record<string, string>;
     root: string;
+    /**
+     * The machine-wide settings, a parameter so a test never asks about the home directory it happens
+     * to run in — the same reason `readers` is one.
+     */
+    userSettings?: string;
     workspaces: Workspace[];
 }) => Finding[];
 
+/**
+ * The one line that catches a denominator bug: for every envelope a tool wrote,
+ * `considered === read + refused + excused`.
+ *
+ * Four of them landed in one day, all green — a migrations run that reported on three of four
+ * files, a plan check that printed `PASS — 0 plan(s)` over a directory of twenty-one, a parity run
+ * over a tree the second config had ignored, a validator that walked a list it had already
+ * filtered. Every one published a numerator and no denominator, so nothing could be wrong.
+ *
+ * This READS the files and imports nothing of the tools that wrote them — the same discipline
+ * `deployed` and `observability` follow. A check that needed the package it checks cannot run in
+ * the tree where that package is missing, which is the first case it exists to find; and this one
+ * has to work over a consumer's `.geonosis/` with no kit installed at all. The arithmetic is
+ * duplicated here on purpose: it is one comparison over three numbers, and it is the check.
+ */
+declare const ENVELOPES_DIR = ".geonosis/envelopes";
+declare const NO_ENVELOPES = "no .geonosis/envelopes/*.json \u2014 the tools write one per run, so an absent envelope is a run nobody has made here yet, and it is not a balanced one";
+declare const checkEnvelopes: ({ root }: {
+    root: string;
+}) => Finding[];
+
 /**
  * The rules of one plugin a config actually turns on. A rule NAMED in a config is not a rule
  * enabled by it — `"off"` is how a config records a rule it decided against, and counting those as
@@ -244,15 +279,6 @@ declare const repoCorpusOf: (root: string) => string | undefined;
 declare const formatDoctor: ({ counts, findings, ok, root }: DoctorReport) => string;
 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.
- */
 declare const resolveFrom: (dir: string, specifier: string) => string;
 /** The package a resolved entry point belongs to: up until a manifest claims the name. */
 declare const packageDirOf: (entry: string, name: string) => string;
@@ -287,4 +313,4 @@ declare const checkRunner: ({ ratchet, workspaces, }: {
     workspaces: Workspace[];
 }) => Finding[];
 
-export { CHECKS, CONFIG_FILE, type CheckName, DEPLOYED_FILE, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, type Finding, GEONOSIS_FILE, type LastEventRecord, MANIFEST_FILE, type Manifest, NOT_WRITTEN, type ObservabilityConfig, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkDeployed, checkDrift, checkExercised, checkLoaded, checkObservability, checkRunner, corpusOfPlugin, declaredFor, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, formatDoctor, formatJson, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };
+export { CHECKS, CONFIG_FILE, type CheckName, DEPLOYED_FILE, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, ENVELOPES_DIR, type Finding, GEONOSIS_FILE, type LastEventRecord, MANIFEST_FILE, type Manifest, NOT_WRITTEN, NO_ENVELOPES, type ObservabilityConfig, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkDeployed, checkDrift, checkEnvelopes, checkExercised, checkLoaded, checkObservability, checkRunner, corpusOfPlugin, declaredFor, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, formatDoctor, formatJson, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };

package/dist/index.js

@@ -3,15 +3,18 @@ import {
   CONFIG_FILE,
   DEPLOYED_FILE,
   DoctorError,
+  ENVELOPES_DIR,
   GEONOSIS_FILE,
   MANIFEST_FILE,
   NOT_WRITTEN,
+  NO_ENVELOPES,
   RATCHET_FILE,
   READERS,
   SCOPE,
   checkBaseline,
   checkDeployed,
   checkDrift,
+  checkEnvelopes,
   checkExercised,
   checkLoaded,
   checkObservability,
@@ -34,21 +37,24 @@ import {
   resolveFrom,
   runDoctor,
   satisfies
-} from "./chunk-ZJCUTDQW.js";
+} from "./chunk-R4OLFNI6.js";
 export {
   CHECKS,
   CONFIG_FILE,
   DEPLOYED_FILE,
   DoctorError,
+  ENVELOPES_DIR,
   GEONOSIS_FILE,
   MANIFEST_FILE,
   NOT_WRITTEN,
+  NO_ENVELOPES,
   RATCHET_FILE,
   READERS,
   SCOPE,
   checkBaseline,
   checkDeployed,
   checkDrift,
+  checkEnvelopes,
   checkExercised,
   checkLoaded,
   checkObservability,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/doctor",
-  "version": "1.2.0",
+  "version": "1.4.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": [
@@ -35,7 +35,7 @@
     "dist"
   ],
   "dependencies": {
-    "@geonosis/lint-parity": "1.2.0"
+    "@geonosis/lint-parity": "1.4.0"
   },
   "peerDependencies": {
     "oxlint": ">=1.77"