@geonosis/doctor 1.4.0 → 2.1.0

package/dist/doctor-cli.js

@@ -1,12 +1,99 @@
 import {
   CHECKS,
+  ENVELOPES_DIR,
   formatDoctor,
   formatJson,
   runDoctor
-} from "./chunk-R4OLFNI6.js";
+} from "./chunk-R2R2OYH3.js";
 
 // src/doctor-cli.ts
+import { fstatSync, statSync } from "fs";
 import { resolve } from "path";
+
+// src/envelope-write.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
+var UnbalancedEnvelope = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnbalancedEnvelope";
+  }
+};
+var isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+var unbalancedMessage = (envelope, next) => `${envelope.tool}: considered ${envelope.considered} but accounts for ${envelope.read + envelope.refused.length + envelope.excused.length} \u2014 ${envelope.read} read + ${envelope.refused.length} refused + ${envelope.excused.length} excused. A run that has lost count of its own inputs cannot say what it measured, so no verdict was rendered and no envelope was written. Next: ${next}`;
+var writeEnvelope = ({
+  envelope,
+  next,
+  root
+}) => {
+  if (envelope.tool.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `an envelope with no tool name cannot be filed or reported against. Next: ${next}`
+    );
+  }
+  if (envelope.version.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: an envelope that cannot name the build that wrote it dates nothing, and a stale one reads exactly like a fresh one. Next: ${next}`
+    );
+  }
+  if (!isCount(envelope.considered) || !isCount(envelope.read)) {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: considered ${envelope.considered} and read ${envelope.read} \u2014 a census is a whole number of things, and arithmetic over anything else balances by accident. Next: ${next}`
+    );
+  }
+  if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
+    throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
+  }
+  const at = envelopePath(root, envelope.tool);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
+`);
+  return at;
+};
+var UNKNOWN = "unknown";
+var versionIn = (dir) => {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var versionOf = (moduleUrl) => {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (; ; ) {
+    const found = versionIn(dir);
+    if (found !== void 0) return found;
+    const up = dirname(dir);
+    if (up === dir) return UNKNOWN;
+    dir = up;
+  }
+};
+var DOCTOR_TOOL = "doctor";
+var DOCTOR_NEXT = "geonosis-doctor --json and count the checks it printed \u2014 this run considered every question the tool has, and a check nobody asked for is excused by name rather than left out of the denominator";
+var doctorEnvelope = ({
+  durationMs,
+  report
+}) => {
+  const ran = new Set(report.ran);
+  return {
+    considered: CHECKS.length,
+    durationMs,
+    excused: CHECKS.filter((check) => !ran.has(check)).map((check) => ({
+      path: check,
+      reason: "not asked for by --only, so this run says nothing about it"
+    })),
+    findings: report.findings,
+    read: report.ran.length,
+    refused: [],
+    tool: DOCTOR_TOOL,
+    version: versionOf(import.meta.url)
+  };
+};
+
+// src/doctor-cli.ts
 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
@@ -21,8 +108,9 @@ var ABOUT = {
   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
+              an integration directory the registry never names, a package lint script narrower
+              than the hook beside it, an allowBuilds entry naming one platform of a split package,
+              an observability package nothing composes, 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
@@ -33,22 +121,46 @@ var ABOUT = {
               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.`,
+              "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
+              that PRESUMES an engine no manifest here declares is a WARN of its own: enabled where
+              the engine is absent it has no possible finding, which is the same green.`,
+  group: `The packages that are published on ONE version, asked of every workspace: one copy
+              repo-wide, and one number per workspace. A consumer carried @geonosis/visual-diff at
+              1.1.0 and 1.4.0 in one tree while every other line read green, because they are all
+              scoped to the plugin a config names. Membership ships with the kit; a repo declares
+              its OWN held-together sets under doctor.groups in geonosis.json. Asked of the
+              resolver, never of find, and UNJUDGED when the tree installs none of the group.
+              It also reads what the ROOT declares: the door (@geonosis/cli, or the geonosis
+              metapackage) plus the bins the root's own scripts call by name, and nothing the door
+              already owns.`,
   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.`,
+              never by find: on pnpm the store keeps every version ever installed. It also reads
+              every committed git hook: a geonosis bin called through pnpm/npx/bunx cannot START,
+              because a hook's PATH carries no version-manager shim.`,
   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.`,
+  rails: `The egress an unattended run is bounded by, read back out of the settings that
+              actually LOAD rather than out of the file this repo rendered \u2014 D-038 one file over.
+              Claude Code merges sandbox.network.allowedDomains across the managed, user, project
+              and local scopes, and two measured things make a perfect render load as nothing: a
+              settings file that fails validation is SILENTLY ignored under -p, and a managed
+              allowManagedDomainsOnly makes every other scope's allow list ignored. deniedEgress in
+              .geonosis/rails-run.json is a GATE AT ZERO (D-025): one denied attempt fails, and it
+              is never a counter to hold flat.`,
   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.`
+              test file under it is a SKIP \u2014 there is no result for an exit code to be wrong about.
+              And whether anything here ever runs geonosis-ratchet --prove: a counter that has
+              never been seen reading its own planted finding reads exactly like a clean tree.`
 };
 var USAGE = `geonosis-doctor [--root <dir>] [--only <check,\u2026>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
 
@@ -69,6 +181,10 @@ plugin-route-namespaced on its package root, while the shipped corpus says acme
 
   --print-config-shape   every file this reads, and the keys it reads out of each
 
+Every run writes .geonosis/envelopes/doctor.json: the ten 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.
+
 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.`;
@@ -115,11 +231,16 @@ var parseDoctorArgs = (argv, cwd) => {
   };
 };
 var CONFIG_SHAPE = `geonosis-doctor reads geonosis.json, geonosis.ratchet.json, .oxlintrc.json,
-pnpm-workspace.yaml and .claude/settings.json
+pnpm-workspace.yaml, .claude/settings.json and this repo's committed git hooks
 
 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 "doctor"
+  corpus          string?    the reach corpus this repo ships for its own rule options
+  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
 geonosis.json \u2192 "observability"
   sink            string     where this repo sends its errors
   endpoint        string     the URL that must be reachable
@@ -140,8 +261,31 @@ geonosis.ratchet.json
 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`;
+lefthook.yml, .lefthook.yml, .husky/*, .githooks/*
+  every line, as text        a geonosis bin run through pnpm/npx/bunx cannot START from a hook
+geonosis.json \u2192 "rails.egress"
+  allow           string[]   the hosts an unattended run may reach. The rails line reads each one
+                             back out of the settings that actually LOAD, never out of the file
+                             this repo rendered
+  deny            string[]   the hosts it may never reach
+.claude/settings.json, .claude/settings.local.json, ~/.claude/settings.json,
+/Library/Application Support/ClaudeCode/managed-settings.json (/etc/claude-code on Linux)
+  enabledPlugins  object     what installs the kit's plugin in THIS repo
+  sandbox.network.allowedDomains  string[]  merged across every scope above; a managed
+                             allowManagedDomainsOnly makes every other scope's list ignored
+  sandbox.network.deniedDomains   string[]  what this repo renders its deny list into
+.geonosis/rails-run.json
+  deniedEgress    object[]   what a run reached for and was refused. A GATE AT ZERO (D-025): one
+                             entry fails, and it is never a counter to hold flat`;
+var sameFile = (fd, path) => {
+  try {
+    const open = fstatSync(fd);
+    const there = statSync(path);
+    return open.dev === there.dev && open.ino === there.ino;
+  } catch {
+    return false;
+  }
+};
 var main = async () => {
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -155,7 +299,21 @@ var main = async () => {
     return 0;
   }
   const { json, ...options } = parseDoctorArgs(argv, process.cwd());
+  const started = Date.now();
   const report = await runDoctor(options);
+  const at = envelopePath(options.root, "doctor");
+  if (sameFile(process.stdout.fd, at)) {
+    process.stderr.write(
+      `geonosis-doctor: stdout is ${ENVELOPES_DIR}/doctor.json, so no envelope was written \u2014 it would have overwritten the report redirected there. Send --json somewhere else and the envelope is written after every run.
+`
+    );
+  } else {
+    writeEnvelope({
+      envelope: doctorEnvelope({ durationMs: Date.now() - started, report }),
+      next: DOCTOR_NEXT,
+      root: options.root
+    });
+  }
   process.stdout.write(json ? formatJson(report) : formatDoctor(report));
   return report.ok ? 0 : 1;
 };

package/dist/index.d.ts

@@ -5,12 +5,13 @@ type Overrides = {
 
 /**
  * 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; `envelope` asks
+ * 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.
+ * 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.
  */
-declare const CHECKS: readonly ["loaded", "exercised", "baseline", "runner", "envelope", "drift", "observability", "deployed"];
+declare const CHECKS: readonly ["loaded", "group", "exercised", "baseline", "runner", "envelope", "drift", "observability", "deployed", "rails"];
 type CheckName = (typeof CHECKS)[number];
 /**
  * `SKIP` is a first-class answer and is printed like any other: a check whose line is missing reads
@@ -82,6 +83,8 @@ type DoctorOptions = {
 type DoctorReport = {
     counts: Record<Verdict, number>;
     findings: Finding[];
+    /** The checks this run asked. `--only` makes it a subset, and the envelope's denominator needs it. */
+    ran: CheckName[];
     /**
      * False as soon as one line is a FAIL or an UNJUDGED — after `--strict` has promoted the
      * warnings. "We could not tell" is not a pass; it is the quietest way there is of reading green.
@@ -137,6 +140,14 @@ declare const readRatchet: (root: string) => RatchetConfig | undefined;
 
 declare const runDoctor: ({ baseline, only, oxlint, root, strict, }: DoctorOptions) => Promise<DoctorReport>;
 
+/** The file `create-geonosis --domains` writes, held against the scaffold's own name by a test. */
+declare const COMPOSITION_ROOT = "src/platform.ts";
+/**
+ * The floors, as data a consumer's tree can read — the same reason `FIXED_GROUP` ships as a list: a
+ * consumer has none of the kit's workspace globs to glob. `tooling/group-membership.test.ts` holds
+ * it against the workspace, so a foundation or a domain added tomorrow cannot arrive unasked.
+ */
+declare const FLOOR_PACKAGES: readonly string[];
 /** Which kit package reads which block of `geonosis.json`. */
 declare const READERS: Record<string, string>;
 /**
@@ -180,7 +191,7 @@ declare const checkDrift: ({ readers, root, userSettings, workspaces, }: {
  * 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 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 (this run\u2019s own doctor.json is not one of them: it is written after these checks, and balanced at write time)";
 declare const checkEnvelopes: ({ root }: {
     root: string;
 }) => Finding[];
@@ -209,6 +220,51 @@ declare const checkExercised: ({ config, corpus, entry, oxlint, repoCorpus, root
     root: string;
 }) => Promise<Finding>;
 
+/**
+ * The packages that version as ONE number — the kit's method floor, as data a consumer's tree can
+ * read.
+ *
+ * It ships here rather than being derived where it is decided: a consumer has no
+ * `.changeset/config.json` and no workspace globs of the kit to glob, so the only form of this fact
+ * that survives an install is a list inside a published package. `tooling/group-membership.test.ts`
+ * holds it against the workspace and against every other door that names the group, so the list
+ * cannot drift from the floors it describes.
+ *
+ * Foundations and domains are absent on purpose (D-053): a floor package moves on a line of its
+ * own, and asking it to match this number would be the cadence coupling the floors exist to end.
+ */
+declare const FIXED_GROUP: readonly string[];
+/** A set of packages a repo declares must move together. The kit's own is the default. */
+type HeldTogether = {
+    name: string;
+    packages: readonly string[];
+};
+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.
+ */
+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
+ * `geonosis-release published --group`.
+ *
+ * Asked of the RESOLVER from each workspace directory, never of `find` over `node_modules` — on
+ * pnpm the store keeps every version ever installed, so a count of directories answers nonsense on
+ * a correct tree.
+ */
+declare const checkGroup: ({ groups, root, workspaces, }: {
+    groups?: readonly HeldTogether[];
+    root: string;
+    workspaces: Workspace[];
+}) => Finding[];
+
 /** The scope this tool asks about. A config's other plugins are somebody else's release to check. */
 declare const SCOPE = "@geonosis/";
 /**
@@ -308,9 +364,10 @@ declare const relativeToRoot: (root: string, path: string) => string;
  * a WARN that names the wrong runner's sin is a line a reader learns to skip, and the lines it
  * teaches them to skip are the true ones next to it.
  */
-declare const checkRunner: ({ ratchet, workspaces, }: {
+declare const checkRunner: ({ ratchet, root, workspaces, }: {
     ratchet?: RatchetConfig;
+    root: string;
     workspaces: Workspace[];
 }) => Finding[];
 
-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 };
+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, KIT_GROUP, 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, checkGroup, checkLoaded, checkObservability, checkRunner, corpusOfPlugin, declaredFor, declaredGroupsOf, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, formatDoctor, formatJson, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };

package/dist/index.js

@@ -1,10 +1,14 @@
 import {
   CHECKS,
+  COMPOSITION_ROOT,
   CONFIG_FILE,
   DEPLOYED_FILE,
   DoctorError,
   ENVELOPES_DIR,
+  FIXED_GROUP,
+  FLOOR_PACKAGES,
   GEONOSIS_FILE,
+  KIT_GROUP,
   MANIFEST_FILE,
   NOT_WRITTEN,
   NO_ENVELOPES,
@@ -16,11 +20,13 @@ import {
   checkDrift,
   checkEnvelopes,
   checkExercised,
+  checkGroup,
   checkLoaded,
   checkObservability,
   checkRunner,
   corpusOfPlugin,
   declaredFor,
+  declaredGroupsOf,
   defaultRef,
   discoverConfigs,
   discoverWorkspaces,
@@ -37,14 +43,18 @@ import {
   resolveFrom,
   runDoctor,
   satisfies
-} from "./chunk-R4OLFNI6.js";
+} from "./chunk-R2R2OYH3.js";
 export {
   CHECKS,
+  COMPOSITION_ROOT,
   CONFIG_FILE,
   DEPLOYED_FILE,
   DoctorError,
   ENVELOPES_DIR,
+  FIXED_GROUP,
+  FLOOR_PACKAGES,
   GEONOSIS_FILE,
+  KIT_GROUP,
   MANIFEST_FILE,
   NOT_WRITTEN,
   NO_ENVELOPES,
@@ -56,11 +66,13 @@ export {
   checkDrift,
   checkEnvelopes,
   checkExercised,
+  checkGroup,
   checkLoaded,
   checkObservability,
   checkRunner,
   corpusOfPlugin,
   declaredFor,
+  declaredGroupsOf,
   defaultRef,
   discoverConfigs,
   discoverWorkspaces,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/doctor",
-  "version": "1.4.0",
+  "version": "2.1.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,10 @@
     "dist"
   ],
   "dependencies": {
-    "@geonosis/lint-parity": "1.4.0"
+    "@geonosis/lint-parity": "2.1.0"
+  },
+  "devDependencies": {
+    "@geonosis/ratchet": "2.1.0"
   },
   "peerDependencies": {
     "oxlint": ">=1.77"