@geonosis/doctor 1.0.0

package/dist/doctor-cli.js

@@ -0,0 +1,109 @@
+import {
+  formatDoctor,
+  formatJson,
+  runDoctor
+} from "./chunk-R4AHDFE3.js";
+
+// src/doctor-cli.ts
+import { resolve } from "path";
+var USAGE = `geonosis-doctor [--root <dir>] [--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
+              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
+              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).
+
+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.
+
+Exits 1 when any line is a FAIL, 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.`;
+var VALUED = /* @__PURE__ */ new Set(["--oxlint", "--root"]);
+var parseDoctorArgs = (argv, cwd) => {
+  const read = {};
+  let baseline;
+  let json = false;
+  let strict = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index] ?? "";
+    const value = argv[index + 1];
+    if (flag === "--json") {
+      json = true;
+      continue;
+    }
+    if (flag === "--strict") {
+      strict = true;
+      continue;
+    }
+    if (flag === "--baseline-against") {
+      const named = value === void 0 || value.startsWith("--") ? void 0 : value;
+      baseline = { ref: named };
+      if (named !== void 0) index += 1;
+      continue;
+    }
+    if (!VALUED.has(flag)) throw new Error(`unknown argument "${flag}"`);
+    if (value === void 0 || value.startsWith("--")) throw new Error(`${flag} needs a value`);
+    read[flag] = value;
+    index += 1;
+  }
+  return {
+    ...baseline === void 0 ? {} : { baseline },
+    json,
+    ...read["--oxlint"] === void 0 ? {} : { oxlint: resolve(cwd, read["--oxlint"]) },
+    root: resolve(cwd, read["--root"] ?? cwd),
+    strict
+  };
+};
+var main = async () => {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
+  const { json, ...options } = parseDoctorArgs(argv, process.cwd());
+  const report = await runDoctor(options);
+  process.stdout.write(json ? formatJson(report) : formatDoctor(report));
+  return report.ok ? 0 : 1;
+};
+try {
+  process.exit(await main());
+} catch (error) {
+  process.stderr.write(`geonosis-doctor: ${error.message}
+`);
+  process.exit(2);
+}
+export {
+  parseDoctorArgs
+};

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+/**
+ * The five 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; the fifth
+ * asks whether the gate is still there at all.
+ */
+declare const CHECKS: readonly ["loaded", "exercised", "baseline", "runner", "drift", "observability"];
+type CheckName = (typeof CHECKS)[number];
+/**
+ * `SKIP` is a first-class answer and is printed like any other: a check whose line is missing reads
+ * as a check that passed, and that is the failure this whole package is about.
+ */
+type Verdict = 'FAIL' | 'OK' | 'SKIP' | 'WARN';
+type Finding = {
+    check: CheckName;
+    message: string;
+    /** The config, manifest, baseline or plugin this line is about, relative to the root. */
+    subject: string;
+    verdict: Verdict;
+};
+/** A question that could not be asked at all. Never a verdict — a refusal. */
+declare class DoctorError extends Error {
+    constructor(message: string);
+}
+type Manifest = {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    name?: string;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+};
+type Workspace = {
+    dir: string;
+    manifest: Manifest;
+    /** Relative to the root, `/`-separated; the root workspace is the empty string. */
+    relative: string;
+};
+type DiscoveredConfig = {
+    dir: string;
+    /** Why this config could not be read. A config nobody can parse is a finding, never a skip. */
+    error?: string;
+    jsPlugins: string[];
+    path: string;
+    relative: string;
+    rules: Record<string, unknown>;
+};
+type RatchetConfig = {
+    baseline: string;
+    counters: Record<string, unknown>[];
+};
+type DoctorOptions = {
+    /**
+     * Present only when a baseline comparison was asked for, because making one is the one part of
+     * this tool that runs git — and the release check runs the doctor inside repos other sessions
+     * are working in. `ref` absent means `origin/main` if the repo has one.
+     */
+    baseline?: {
+        ref?: string;
+    };
+    oxlint?: string;
+    root: string;
+    strict?: boolean;
+};
+type DoctorReport = {
+    counts: Record<Verdict, number>;
+    findings: Finding[];
+    /** False as soon as one line is a FAIL — after `--strict` has promoted the warnings. */
+    ok: boolean;
+    root: string;
+};
+
+/**
+ * `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.
+ */
+declare const defaultRef: (root: string) => string | undefined;
+/**
+ * The rail a PreToolUse guard never was.
+ *
+ * A ratchet lowers its OWN baseline whenever a number shrinks, which is what locks a win in — and
+ * it is also what lets a branch write any number it likes and stay green on every gate it runs.
+ * Nothing inside one checkout can tell the difference. Only the same file at another ref can.
+ */
+declare const checkBaseline: ({ ref, root }: {
+    ref: string;
+    root: string;
+}) => Finding[];
+
+declare const CONFIG_FILE = ".oxlintrc.json";
+declare const MANIFEST_FILE = "package.json";
+declare const RATCHET_FILE = "geonosis.ratchet.json";
+/** `/`-separated, so a subject reads the same on every platform and sorts the way a path should. */
+declare const relativePath: (root: string, path: string) => string;
+declare const readConfig: (path: string, root: string) => DiscoveredConfig;
+declare const discoverConfigs: (root: string) => DiscoveredConfig[];
+declare const discoverWorkspaces: (root: string) => Workspace[];
+declare const readRatchet: (root: string) => RatchetConfig | undefined;
+
+declare const runDoctor: ({ baseline, oxlint, root, strict, }: DoctorOptions) => Promise<DoctorReport>;
+
+/** Which kit package reads which block of `geonosis.json`. */
+declare const READERS: Record<string, string>;
+/**
+ * What has drifted since the gates were set up.
+ *
+ * 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.
+ */
+declare const checkDrift: ({ readers, root, 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
+     * it runs against goes green for a reason that is not the code, and red the day that package
+     * ships — which is exactly what this one did.
+     */
+    readers?: Record<string, string>;
+    root: string;
+    workspaces: Workspace[];
+}) => 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
+ * enabled would report every one of them as firing nowhere, which is exactly what they do.
+ */
+declare const enabledRulesOf: (rules: Record<string, unknown>, plugin: string) => string[];
+/**
+ * Enabled is not exercised. A rule at "error" over a tree with no violation of it, and a rule at
+ * "error" that can never fire at all, produce the identical green — one consumer ran
+ * `no-raw-html-atoms` that way for months with 136 raw elements in the tree. The corpus is the one
+ * place where the difference is visible, so the question is asked there, under THIS config's
+ * options, because the options are usually where the reach went.
+ */
+declare const checkExercised: ({ config, corpus, oxlint, repoCorpus, root, }: {
+    config: DiscoveredConfig;
+    corpus: string;
+    oxlint: string;
+    /** The corpus this repo ships for its OWN options, when `geonosis.json` declares one. */
+    repoCorpus?: string;
+    root: string;
+}) => Finding;
+
+/** The scope this tool asks about. A config's other plugins are somebody else's release to check. */
+declare const SCOPE = "@geonosis/";
+/**
+ * Whether the version that loaded is the version the manifest asked for — or `undefined` when the
+ * range is one this cannot read. A range it cannot judge is a REFUSAL, never a pass: "the check ran
+ * and said nothing" is the shape every gate in this kit exists to stop.
+ */
+declare const satisfies: (version: string, spec: string) => boolean | undefined;
+/**
+ * What the repo SAYS this config's plugin should be: the nearest manifest, walking up from the
+ * config, that names the package in any dependency block — ending at the root's. A workspace that
+ * declares nothing inherits the root's pin, which is what a hoisted install actually installed.
+ */
+declare const declaredFor: ({ dir, specifier, workspaces, }: {
+    dir: string;
+    specifier: string;
+    workspaces: Workspace[];
+}) => {
+    at: string;
+    spec: string;
+} | undefined;
+declare const checkLoaded: ({ configs, root, workspaces, }: {
+    configs: DiscoveredConfig[];
+    root: string;
+    workspaces: Workspace[];
+}) => Promise<Finding[]>;
+
+/** The record a sink writes on every capture. `@geonosis/observability` exports the same shape. */
+type LastEventRecord = {
+    at?: unknown;
+    id?: unknown;
+    release?: unknown;
+    sink?: unknown;
+};
+type ObservabilityConfig = {
+    /** Where reports go. `https://eu.i.posthog.com`, an OTLP collector, a self-hosted host. */
+    endpoint?: string;
+    /** Where the sink writes its `LastEventRecord`, relative to the root. */
+    lastEventFile?: string;
+    /** How old the last event may be before this is a finding. */
+    maxAgeSeconds?: number;
+    /** The command that plants an error and proves it arrived. Named here, never run from here. */
+    probe?: string;
+    /** What kind of sink this repo runs: `posthog`, `otlp`, `memory`, … */
+    sink?: string;
+};
+declare const checkObservability: ({ now, root, }: {
+    now: number;
+    root: string;
+}) => 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.
+ */
+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;
+/**
+ * The version the plugin itself declares — `meta.version`, the number a diagnostic would carry,
+ * read by importing the module exactly as oxlint does. The manifest beside it is a different
+ * claim, and when the two disagree the one that ran is the one that matters.
+ */
+declare const pluginVersionOf: (entry: string) => Promise<string>;
+/** Where a plugin keeps the corpus it is evidence by, if it ships one at all. */
+declare const corpusOfPlugin: (from: string, specifier: string) => string;
+/**
+ * A resolved path, said relative to the root. Both sides are realpath'd first: a resolver returns
+ * the real path, and on macOS a temp root under `/var/folders` is a symlink to `/private/var`, so
+ * the naive answer is a relative path that climbs out of the repo and back in.
+ */
+declare const relativeToRoot: (root: string, path: string) => string;
+
+/**
+ * A test runner's exit code is not a verdict; its summary is.
+ *
+ * `@cloudflare/vitest-pool-workers` exited 0 over suites it had just reported as failing, for
+ * weeks, in a consumer — so every gate that trusted the status read green over red. The fix is a
+ * runner that writes its own report and something that reads it; this says which workspaces have
+ * neither.
+ */
+declare const checkRunner: ({ ratchet, workspaces, }: {
+    ratchet?: RatchetConfig;
+    workspaces: Workspace[];
+}) => Finding[];
+
+export { CHECKS, CONFIG_FILE, type CheckName, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, type Finding, GEONOSIS_FILE, type LastEventRecord, MANIFEST_FILE, type Manifest, type ObservabilityConfig, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkDrift, 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

@@ -0,0 +1,68 @@
+import {
+  CHECKS,
+  CONFIG_FILE,
+  DoctorError,
+  GEONOSIS_FILE,
+  MANIFEST_FILE,
+  RATCHET_FILE,
+  READERS,
+  SCOPE,
+  checkBaseline,
+  checkDrift,
+  checkExercised,
+  checkLoaded,
+  checkObservability,
+  checkRunner,
+  corpusOfPlugin,
+  declaredFor,
+  defaultRef,
+  discoverConfigs,
+  discoverWorkspaces,
+  enabledRulesOf,
+  formatDoctor,
+  formatJson,
+  packageDirOf,
+  pluginVersionOf,
+  readConfig,
+  readRatchet,
+  relativePath,
+  relativeToRoot,
+  repoCorpusOf,
+  resolveFrom,
+  runDoctor,
+  satisfies
+} from "./chunk-R4AHDFE3.js";
+export {
+  CHECKS,
+  CONFIG_FILE,
+  DoctorError,
+  GEONOSIS_FILE,
+  MANIFEST_FILE,
+  RATCHET_FILE,
+  READERS,
+  SCOPE,
+  checkBaseline,
+  checkDrift,
+  checkExercised,
+  checkLoaded,
+  checkObservability,
+  checkRunner,
+  corpusOfPlugin,
+  declaredFor,
+  defaultRef,
+  discoverConfigs,
+  discoverWorkspaces,
+  enabledRulesOf,
+  formatDoctor,
+  formatJson,
+  packageDirOf,
+  pluginVersionOf,
+  readConfig,
+  readRatchet,
+  relativePath,
+  relativeToRoot,
+  repoCorpusOf,
+  resolveFrom,
+  runDoctor,
+  satisfies
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@geonosis/doctor",
+  "version": "1.0.0",
+  "description": "The adoption doctor — declared ≠ loaded, enabled ≠ exercised, a baseline that grew, a runner whose exit code is the only verdict.",
+  "keywords": [
+    "oxlint",
+    "lint",
+    "doctor",
+    "monorepo",
+    "adoption",
+    "ratchet",
+    "ci"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/doctor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/doctor"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "geonosis-doctor": "bin/geonosis-doctor.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "dependencies": {
+    "@geonosis/lint-parity": "1.0.0"
+  },
+  "peerDependencies": {
+    "oxlint": ">=1.77"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}