@geonosis/doctor 2.0.0 → 2.1.0

package/dist/doctor-cli.js

@@ -1,12 +1,99 @@
 import {
   CHECKS,
+  ENVELOPES_DIR,
   formatDoctor,
   formatJson,
   runDoctor
-} from "./chunk-SMCRXSH5.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
@@ -94,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.`;
@@ -186,6 +277,15 @@ geonosis.json \u2192 "rails.egress"
 .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")) {
@@ -199,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

@@ -83,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.
@@ -189,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[];

package/dist/index.js

@@ -43,7 +43,7 @@ import {
   resolveFrom,
   runDoctor,
   satisfies
-} from "./chunk-SMCRXSH5.js";
+} from "./chunk-R2R2OYH3.js";
 export {
   CHECKS,
   COMPOSITION_ROOT,

package/package.json

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