@geonosis/verify-arch 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * One finding. `scanner` is the check's id, which is what the human format prints in brackets and
+ * the ratchet format prints as the third field; `line` is absent when the fact is about the whole
+ * file, because a line number nobody can open is worse than none.
+ */
+type Violation = {
+    file: string;
+    line?: number;
+    message: string;
+    scanner: string;
+};
+/** A check a pack ran, named in the pass line so a reader can see what was and was not looked at. */
+type Check = {
+    id: string;
+    label: string;
+};
+type ScanContext = {
+    /** Every file under the root that survived the walk, absolute. One walk answers every pack. */
+    files: readonly string[];
+    /** Whatever this pack's entry in the config gave it. Each pack validates its own. */
+    options: Record<string, unknown>;
+    root: string;
+};
+/**
+ * A pack is the plugin unit: a set of whole-graph checks over one stack's conventions. It declares
+ * the checks it will run BEFORE it runs them, because the pass line has to name them and a line
+ * naming a check that did nothing is the failure this package exists to prevent.
+ */
+type Pack = {
+    checks: (options: Record<string, unknown>) => Check[];
+    id: string;
+    scan: (context: ScanContext) => Violation[];
+};
+type PackConfig = {
+    options?: Record<string, unknown>;
+    pack: string;
+};
+type Config = {
+    /** What the pass and fail lines call themselves. A repo's script name is the repo's to choose. */
+    label: string;
+    packs: PackConfig[];
+};
+/**
+ * A run that could not measure. Separate from a run that measured and found something, because the
+ * two are opposite verdicts and a gate that conflates them reports "clean" for "never looked".
+ */
+declare class VerifyArchError extends Error {
+    constructor(message: string);
+}
+
+declare const CONFIG_FILE = "geonosis.verify-arch.json";
+/**
+ * Every refusal here is one shape of the same failure: a run that scanned nothing and reported
+ * PASS. A missing config, an empty `packs`, a pack nobody ships — each would produce a clean exit
+ * over a tree nothing looked at, which is worse than a red, because nobody goes back to check it.
+ */
+declare const readConfig: (root: string) => Config;
+
+declare const compositionTree: Pack;
+
+declare const medusa: Pack;
+
+/** Every pack this build ships. A repo enables the ones its stack has, by name, in its config. */
+declare const PACKS: Record<string, Pack>;
+declare const PACK_NAMES: string[];
+
+/**
+ * The human format, byte-for-byte the one dielime's `verify:arch` prints today. That is the point:
+ * a scanner that found the same things and said them differently is a migration, not a drop-in, and
+ * a CI log, a runbook and a reviewer's habit all read these lines.
+ */
+declare const formatHuman: ({ checks, label, root, violations, }: {
+    checks: readonly Check[];
+    label: string;
+    root: string;
+    violations: readonly Violation[];
+}) => string;
+/**
+ * One finding, one line, so a counter can count them. The message is flattened because a finding
+ * spread over three lines would be counted as one and read as three — or the other way round,
+ * depending on the regex, which is the class of silent miscount a ratchet cannot survive.
+ */
+declare const formatRatchet: ({ root, violations, }: {
+    root: string;
+    violations: readonly Violation[];
+}) => string;
+
+type RunResult = {
+    /** Every check that RAN, in configured order. The pass line names these and nothing else. */
+    checks: Check[];
+    violations: Violation[];
+};
+/**
+ * One walk, every pack. The four Medusa collectors and the composition graph all want the same
+ * file list, and a monorepo walked once per check is four walks wearing one command's name.
+ */
+declare const runPacks: (root: string, packs: readonly PackConfig[]) => RunResult;
+
+/**
+ * The build output is the same artefact twice. A scan that read `.medusa/server/src` beside `src`
+ * reports every route as colliding with itself and every module name as duplicated — the gate
+ * failing loudest on the tree it is happiest with. So the walk excludes what a build writes, and
+ * the list is an argument because another stack builds somewhere else.
+ */
+declare const DEFAULT_IGNORED: string[];
+/** Every file under `root`, absolute, skipping the named directory names at any depth. */
+declare const walkFiles: (root: string, ignored?: readonly string[]) => string[];
+
+export { CONFIG_FILE, type Check, type Config, DEFAULT_IGNORED, PACKS, PACK_NAMES, type Pack, type PackConfig, type RunResult, type ScanContext, VerifyArchError, type Violation, compositionTree, formatHuman, formatRatchet, medusa, readConfig, runPacks, walkFiles };

package/dist/index.js

@@ -0,0 +1,28 @@
+import {
+  CONFIG_FILE,
+  DEFAULT_IGNORED,
+  PACKS,
+  PACK_NAMES,
+  VerifyArchError,
+  compositionTree,
+  formatHuman,
+  formatRatchet,
+  medusa,
+  readConfig,
+  runPacks,
+  walkFiles
+} from "./chunk-2N2AFWCY.js";
+export {
+  CONFIG_FILE,
+  DEFAULT_IGNORED,
+  PACKS,
+  PACK_NAMES,
+  VerifyArchError,
+  compositionTree,
+  formatHuman,
+  formatRatchet,
+  medusa,
+  readConfig,
+  runPacks,
+  walkFiles
+};

package/dist/verify-arch-cli.js

@@ -0,0 +1,89 @@
+import {
+  CONFIG_FILE,
+  VerifyArchError,
+  formatHuman,
+  formatRatchet,
+  readConfig,
+  runPacks
+} from "./chunk-2N2AFWCY.js";
+
+// src/verify-arch-cli.ts
+import { resolve } from "path";
+import process from "process";
+var USAGE = `geonosis-verify-arch [root] [--format human|ratchet]
+
+Runs the whole-graph architecture scans a per-file linter cannot: a name that must be unique across
+modules, two files registering one route, a tier composing something above it, a file nothing
+reaches. Which packs run \u2014 and with what \u2014 is ${CONFIG_FILE} at the root.
+
+  --format human    (default) the pass line naming every check that ran, or the findings on stderr
+  --format ratchet  one "\u2717 <file>[:<line>] <check> <message>" line per finding, for a counter
+
+Exit codes: 0 clean \xB7 1 violations \xB7 2 the run could not measure (no config, unknown pack, unknown
+format). A scan that never happened is not a clean scan, so it does not share an exit code with one.`;
+var FORMATS = /* @__PURE__ */ new Set(["human", "ratchet"]);
+var parse = (argv) => {
+  const args = { format: "human", root: process.cwd() };
+  let positional = false;
+  for (let at = 0; at < argv.length; at++) {
+    const arg = argv[at];
+    if (arg === "--format") {
+      const next = argv[at + 1];
+      if (next === void 0) throw new VerifyArchError("--format needs a value.");
+      args.format = next;
+      at++;
+      continue;
+    }
+    if (arg.startsWith("--")) throw new VerifyArchError(`Unknown option: ${arg}`);
+    if (positional) throw new VerifyArchError(`Unexpected second root: ${arg}`);
+    args.root = resolve(process.cwd(), arg);
+    positional = true;
+  }
+  if (!FORMATS.has(args.format)) {
+    throw new VerifyArchError(
+      `Unknown --format ${args.format}. It is one of ${[...FORMATS].join(", ")}.`
+    );
+  }
+  return args;
+};
+var main = (argv) => {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
+  let result;
+  let label;
+  let root;
+  let format;
+  try {
+    const args = parse(argv);
+    root = args.root;
+    format = args.format;
+    const config = readConfig(root);
+    label = config.label;
+    result = runPacks(root, config.packs);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+`);
+    return 2;
+  }
+  if (format === "ratchet") {
+    process.stdout.write(formatRatchet({ root, violations: result.violations }));
+    return result.violations.length === 0 ? 0 : 1;
+  }
+  const text = formatHuman({ checks: result.checks, label, root, violations: result.violations });
+  if (result.violations.length === 0) {
+    process.stdout.write(text);
+    return 0;
+  }
+  process.stderr.write(text);
+  return 1;
+};
+try {
+  process.exit(main(process.argv.slice(2)));
+} catch (error) {
+  process.stderr.write(`${error.message}
+`);
+  process.exit(2);
+}

package/examples/dielime.verify-arch.json

@@ -0,0 +1,27 @@
+{
+  "_comment": "dielime's ten checks, spelled as configuration. Copy to geonosis.verify-arch.json at the repo root. `label` reproduces the line its verify:arch script prints today; `kinds` keeps `workflow` because the repo is not yet pinned to Medusa >= 2.19, where workflow-loader.js passes allowIndex.",
+  "label": "verify:arch",
+  "packs": [
+    {
+      "pack": "medusa",
+      "options": {
+        "sourceRoots": ["packages", "apps"],
+        "moduleRoots": ["packages"],
+        "workflowRoots": ["packages"],
+        "packages": [
+          { "under": "packages/medusa-plugins", "name": "@dielime/{dir}", "namespaced": true },
+          { "under": "apps", "name": "app:{dir}" }
+        ],
+        "workflowFactories": [
+          "createWorkflow",
+          "createScheduledWorkflow",
+          "createCartMutatingWorkflow"
+        ],
+        "retrySpreads": ["RETRY_"],
+        "kinds": ["workflow", "subscriber", "job"],
+        "inlineMutationOk": "arch:inline-mutation-ok",
+        "routeOverrideOk": "arch:route-override-ok"
+      }
+    }
+  ]
+}

package/examples/during-day.verify-arch.json

@@ -0,0 +1,16 @@
+{
+  "_comment": "during.day's composition tree as a scanner pack. `roots` is the web app; `entryPoints` are the Next.js route-segment files that sit above biology, and naming them is what turns the orphan check on. Only the GATE is here — the mermaid/dot/json/html renderers of the original script are a viewer, not a check, and stay where they are.",
+  "label": "arch",
+  "packs": [
+    {
+      "pack": "composition-tree",
+      "options": {
+        "roots": ["apps/web/features", "apps/web/app"],
+        "aliases": [{ "prefix": "@/", "to": "apps/web/" }],
+        "entryPoints": [
+          "/app/(?:.*/)?(?:page|layout|template|default|error|not-found|loading|global-error)\\.tsx?$"
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@geonosis/verify-arch",
+  "version": "1.0.0",
+  "description": "Whole-graph architecture scans a per-file linter cannot do — unique module names, route collisions, tier direction, dead files — as configurable packs behind one exit code.",
+  "keywords": [
+    "architecture",
+    "medusa",
+    "monorepo",
+    "lint",
+    "scanner",
+    "ci",
+    "gate"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/verify-arch",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/verify-arch"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "geonosis-verify-arch": "bin/geonosis-verify-arch.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}