@cosyte/script-utils 0.1.2 → 0.1.4

package/attw.js

@@ -160,9 +160,16 @@
  *      one, and `prepare` and `postpack` double the same way. `prepublishOnly` does
  *      not run under `npm pack` AT ALL (measured: 0 through either gate), which is
  *      why this cannot recurse into the gate that runs it. Of the three that do
- *      double, every repo here defines only `prepare`, and defines it as the same
- *      `command -v simple-git-hooks … || true` one-liner, so
- *      nothing reds today. IT IS NOT FIXED WITH `--ignore-scripts`, AND THAT IS
+ *      double, the repos here define only `prepare`. AN EARLIER VERSION OF THIS
+ *      PARAGRAPH SAID EVERY ONE DEFINES IT AS THE SAME ONE-LINER, SO NOTHING REDS,
+ *      AND THAT WAS FALSE. The `prepare` lines differ, and the one the parser
+ *      template shipped printed simple-git-hooks' `[INFO]` lines on STDOUT, inside
+ *      the JSON this net parses: every repo scaffolded from it was born with a gate
+ *      that refused ("did not print JSON"). The template now sends that output to
+ *      stderr (`simple-git-hooks 1>&2`, cosyte/config#131), and twelve sibling
+ *      repos still carry the older line, so a `prepare` that writes to stdout is
+ *      a refusal here rather than a pass, by design: what it printed is in the
+ *      message. IT IS NOT FIXED WITH `--ignore-scripts`, AND THAT IS
  *      DELIBERATE: a `prepack` may GENERATE files that belong in the tarball, so
  *      suppressing it would make this net read a listing the real publish would not
  *      produce, which is a correctness bug wearing a performance fix.
@@ -734,15 +741,17 @@ import { spawnSync } from "node:child_process";
 import {
   accessSync,
   constants,
+  existsSync,
   mkdtempSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   rmSync,
   statSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { basename, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { gunzipSync } from "node:zlib";
 
 /**
@@ -990,6 +999,27 @@ function summarizeProblems(out) {
   return [`attw reported ${lines.length} problem kind(s):`, ...lines].join("\n");
 }
 
+/**
+ * The entries of an `npm pack --json` report that describe the package `name`.
+ *
+ * npm 10 and 11 print an ARRAY of entries; npm 12 prints an OBJECT keyed by
+ * package name. An entry counts only when its own `name` is `name`, and in the
+ * object shape only under the key `name` as well, so a key and an entry that
+ * disagree count for nothing. Any other document (a string, a number, `null`)
+ * yields no entries, which the caller refuses rather than grades.
+ *
+ * @param {unknown} doc The parsed report.
+ * @param {string | undefined} name The package name from package.json.
+ * @returns {Array<{ name?: unknown, files?: unknown }>}
+ */
+function packReportEntries(doc, name) {
+  if (Array.isArray(doc)) return doc.filter((entry) => entry?.name === name);
+  if (doc === null || typeof doc !== "object") return [];
+  return Object.entries(doc)
+    .filter(([key, entry]) => key === name && entry?.name === name)
+    .map(([, entry]) => entry);
+}
+
 /**
  * The paths a published tarball of this directory would carry, read from npm
  * rather than recomputed from `files`/`.npmignore` here.
@@ -1006,6 +1036,15 @@ function summarizeProblems(out) {
  * file list, because a partial answer graded as a whole one is the false green
  * this whole file exists to refuse.
  *
+ * TWO SHAPES OF REPORT ARE READ, AND ONLY TWO. npm 10 and 11 print an ARRAY of
+ * tarball entries; npm 12 prints an OBJECT keyed by package name whose values
+ * are the same entries. Measured on npm 12.2.0: `npm pack --dry-run --json` on a
+ * package named `@scope/probe` printed `{"@scope/probe": {"name": "@scope/probe",
+ * "files": [...], ...}}`. Before this read both, the object fell through to an
+ * empty list and the net refused every package ("npm described 0 tarball(s)"),
+ * which is a red for the right reason (it read nothing) and the wrong outcome
+ * (CI moving to npm 12 would have refused every publish). See `packReportEntries`.
+ *
  * @param {{ name?: string }} pkg The parsed manifest.
  * @param {NodeJS.ProcessEnv} childEnv The environment to hand npm.
  * @returns {{ files: Set<string>, error?: undefined } | { error: string, files?: undefined }}
@@ -1032,11 +1071,12 @@ function packedFiles(pkg, childEnv) {
       error: `\`npm pack --dry-run --json\` did not print JSON. What it printed:\n\n${res.stdout ?? ""}`,
     };
   }
-  // npm reports an ARRAY of tarballs, because the same command run at a workspace
-  // root describes several. Only this package's own entry is gradeable here, and
+  // npm describes one entry per tarball, because the same command run at a
+  // workspace root describes several, in one of the two shapes read by
+  // `packReportEntries`. Only this package's own entry is gradeable here, and
   // anything other than exactly one of them means npm was asked a different
   // question than this net thinks it asked.
-  const mine = (Array.isArray(doc) ? doc : []).filter((entry) => entry?.name === pkg.name);
+  const mine = packReportEntries(doc, pkg.name);
   if (mine.length !== 1) {
     return {
       error:
@@ -1677,3 +1717,143 @@ function gate({ callerUrl, argv = process.argv.slice(2) }) {
   );
   return 0;
 }
+
+// ---- The command-line form (ST34) --------------------------------------------
+//
+// `node node_modules/@cosyte/script-utils/attw.js` runs this gate for the
+// package in the working directory with no caller file of its own: it is what
+// the one-line `scripts/attw.mjs` caller does, resolving the package's own
+// `node_modules/.bin/attw`. What the package leaves out of attw's analysis is
+// declared in `scripts/attw.exclude`, one resolution per line, `#` for comments:
+//
+//   node10       left out by attw's `node16` profile
+//   node16-cjs   left out, with node10, by its `esm-only` profile
+//
+// The file SELECTS A PROFILE and nothing else, so it reaches only what the
+// argument allow-list already forwards. A name it does not know, a repeat,
+// node16-cjs without node10 (no profile leaves out that one alone) and a
+// `--profile` on the command line beside the file are each refused: one source
+// for the profile, and nothing an exclusion could use to blind net 2.
+
+/** The resolutions an exclusions file may name. */
+const EXCLUDABLE_RESOLUTIONS = new Set(["node10", "node16-cjs"]);
+
+/** Where the command-line form reads what a package leaves out. */
+export const ATTW_EXCLUDE_PATH = "scripts/attw.exclude";
+
+/**
+ * Read an attw exclusions file into the one profile it selects.
+ *
+ * @param {string} text The file's contents.
+ * @returns {{ profile: "node16" | "esm-only" | null, problems: string[] }}
+ */
+export function readAttwExclusions(text) {
+  const problems = [];
+  const seen = new Set();
+  text.split("\n").forEach((raw, index) => {
+    const hash = raw.indexOf("#");
+    const entry = (hash < 0 ? raw : raw.slice(0, hash)).trim();
+    if (entry === "") return;
+    if (!EXCLUDABLE_RESOLUTIONS.has(entry)) {
+      problems.push(
+        `line ${index + 1}: ${JSON.stringify(entry)} is not a resolution this gate can ` +
+          `leave out (node10, node16-cjs).`,
+      );
+    } else if (seen.has(entry)) {
+      problems.push(`line ${index + 1}: ${entry} is listed twice.`);
+    } else {
+      seen.add(entry);
+    }
+  });
+  let profile = null;
+  if (seen.has("node16-cjs") && !seen.has("node10")) {
+    problems.push(
+      "node16-cjs can be left out only with node10: attw's esm-only profile leaves out both " +
+        "CommonJS resolutions, and no profile leaves out node16-cjs alone.",
+    );
+  } else if (seen.has("node16-cjs")) {
+    profile = "esm-only";
+  } else if (seen.has("node10")) {
+    profile = "node16";
+  }
+  return { profile, problems };
+}
+
+/**
+ * Run the gate from the command line for the package in the working directory.
+ *
+ * @param {string[]} argv The command-line arguments, graded by the same allow-list.
+ * @returns {number} The gate's exit code: 0 pass, attw's own status, or 1 for a refusal.
+ */
+export function runAttwCli(argv) {
+  const args = argv.filter((arg) => arg !== "--");
+  const file = join(process.cwd(), ...ATTW_EXCLUDE_PATH.split("/"));
+  const profile = [];
+  if (existsSync(file)) {
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch (err) {
+      process.stderr.write(`\n✗ attw gate: could not read ${ATTW_EXCLUDE_PATH}: ${err.message}\n`);
+      return 1;
+    }
+    const read = readAttwExclusions(text);
+    if (read.problems.length > 0) {
+      process.stderr.write(
+        `\n✗ attw gate: ${ATTW_EXCLUDE_PATH} is not usable, so nothing was checked:\n` +
+          read.problems.map((problem) => `  ${problem}\n`).join(""),
+      );
+      return 1;
+    }
+    if (read.profile !== null) {
+      if (args.some((arg) => arg.split("=")[0] === "--profile")) {
+        process.stderr.write(
+          `\n✗ attw gate: --profile was given and ${ATTW_EXCLUDE_PATH} selects a profile ` +
+            `too. Declare it in the file alone.\n`,
+        );
+        return 1;
+      }
+      profile.push("--profile", read.profile);
+    }
+  }
+  // The caller this form stands in for lives at `scripts/attw.mjs`, so the gate
+  // resolves `../node_modules/.bin/attw` from there: this package's own binary.
+  return runAttwGate({
+    callerUrl: pathToFileURL(join(process.cwd(), "scripts", "attw.mjs")).href,
+    argv: [...args, ...profile],
+  });
+}
+
+/**
+ * Whether node was pointed at this file, which is the command-line form.
+ *
+ * SELF-CONTAINED ON PURPOSE: this module is also vendored and copied as a single file, so it may not
+ * import a sibling at load. A file whose name differs from the one node was pointed at cannot be the
+ * entry point, and that is settled without loading anything; only a matching name asks `index.js`'s
+ * `isCliEntrypoint`, and a copy with no `index.js` beside it compares real paths instead. Unsure is
+ * yes, so a gate that cannot tell runs loudly rather than skipping.
+ *
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @returns {Promise<boolean>}
+ */
+async function invokedAsCommand(moduleUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== "string" || entry === "") return false;
+  const own = fileURLToPath(moduleUrl);
+  const stem = (path) => basename(path).replace(/\.[cm]?[jt]s$/, "");
+  if (stem(entry) !== stem(own)) return false;
+  try {
+    const { isCliEntrypoint } = await import("./index.js");
+    return isCliEntrypoint(moduleUrl);
+  } catch {
+    try {
+      return realpathSync(entry) === realpathSync(own);
+    } catch {
+      return true;
+    }
+  }
+}
+
+void invokedAsCommand(import.meta.url).then((command) => {
+  if (command) process.exitCode = runAttwCli(process.argv.slice(2));
+});

package/bin/cosyte-agent-notes.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// cosyte-agent-notes: the agent-notes checker for the repository in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-agent-notes`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runAgentNotesCheck } from "../agent-notes.js";
+
+const HELP = `cosyte-agent-notes: check a repository's agent notes and every pointer into them.
+
+  cosyte-agent-notes [--dir <repository root>]
+
+The notes are one file, documentation/agent-notes.md, and CLAUDE.md points into it as
+documentation/agent-notes.md#<anchor>. Every pointer in a tracked file must name a heading or an
+explicit anchor. Exit 0 clean, 1 a finding, 2 the check could not run.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runAgentNotesCheck({ argv: args });
+}

package/bin/cosyte-attw.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// cosyte-attw: the attw publish gate for the package in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-attw`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runAttwCli } from "../attw.js";
+
+const HELP = `cosyte-attw: run the attw publish gate for the package in the working directory.
+
+  cosyte-attw [--no-definitely-typed]
+
+It runs this package's own node_modules/.bin/attw over the tarball npm would publish, with four
+nets attw lacks. scripts/attw.exclude names the resolutions the package leaves out, one per line:
+node10 selects attw's node16 profile, node10 with node16-cjs selects esm-only. Exit 0 every net
+passed; attw's own status when attw judged the package; 1 a refusal.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runAttwCli(args);
+}

package/bin/cosyte-catalog.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// cosyte-catalog: the catalog check for the library in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-catalog`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runCatalogCheck } from "../catalog.js";
+
+const HELP = `cosyte-catalog: check that a library's package.json description is the catalog's.
+
+  cosyte-catalog [--dir <package directory>]
+
+The catalog is the one list of our libraries, generated in cosyte/config from each package.json.
+Exit 0 the description is the catalog's, 1 it is not (both values printed), 2 the package is not
+listed or package.json cannot be read.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runCatalogCheck({ argv: args });
+}

package/bin/cosyte-claude-card.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// cosyte-claude-card: the CLAUDE.md card checker for the repository in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-claude-card`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runClaudeCardGate } from "../claude-card.js";
+
+const HELP = `cosyte-claude-card: check a repository's CLAUDE.md against the card spec.
+
+  cosyte-claude-card [--dir <repository root>]
+
+Gate, Hazard and Rules in order, at most 60 lines of at most 100 characters and 5,120 bytes, and an
+@AGENTS.md import when an AGENTS.md sits beside it. Exit 0 the card follows the spec, 1 a finding,
+2 CLAUDE.md could not be read.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runClaudeCardGate({ argv: args });
+}

package/bin/cosyte-internal-refs.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// cosyte-internal-refs: the internal-reference gate over the repository in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-internal-refs`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runInternalRefsCli } from "../internal-refs.js";
+
+const HELP = `cosyte-internal-refs: run the internal-reference gate over the repository in the working directory.
+
+  cosyte-internal-refs [--config <path>]
+
+It refuses internal bookkeeping on a public surface: item identifiers, phase and wave language, ADR
+numbers, internal repo paths. The axes come from scripts/internal-refs.json (or --config). Exit 0
+clean, 1 hits, 2 the gate could not run.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runInternalRefsCli(args);
+}

package/bin/cosyte-no-emdash.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// cosyte-no-emdash: the em and en dash gate over the repository in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-no-emdash`. The gate is the shell script beside this
+// package's entry points; this runs it with bash, forwards every argument (`--help` included, which
+// the gate answers itself) and exits with its code.
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const gate = fileURLToPath(new URL("../check-no-emdash.sh", import.meta.url));
+const run = spawnSync("bash", [gate, ...process.argv.slice(2)], { stdio: "inherit" });
+if (run.error) {
+  process.stderr.write(`cosyte-no-emdash: could not run bash ${gate}: ${run.error.message}\n`);
+  process.exitCode = 1;
+} else {
+  process.exitCode = run.status ?? 1;
+}

package/bin/cosyte-phi-scan.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// cosyte-phi-scan: the PHI commit-gate over the repository in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-phi-scan`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runPhiScanCli } from "../phi-scan.js";
+
+const HELP = `cosyte-phi-scan: run the PHI commit-gate over the repository in the working directory.
+
+  cosyte-phi-scan                 scan the whole repository
+  cosyte-phi-scan --staged        scan what is staged, Markdown excepted (the pre-commit route)
+  cosyte-phi-scan <path>...       scan these paths
+
+It carries the cross-cutting floor (a dashed SSN shape, an email at an undeclared domain) and
+reports a place and a rule, never the matched value. scripts/phi-allow-list.txt declares synthetic
+values, and scripts/phi-scan.exclude names literal tracked paths to leave out. Exit 0 clean, 1 hits,
+2 the scan could not account for something.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runPhiScanCli(args);
+}

package/bin/cosyte-readme.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// cosyte-readme: the README gate for the library in the working directory.
+// A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-readme`. It forwards every argument to the gate and exits with
+// the gate's own code; `--help` prints what it does and exits 0.
+
+import { runReadmeGate } from "../readme.js";
+
+const HELP = `cosyte-readme: check a library README against the house skeleton and npm's size limit.
+
+  cosyte-readme [--dir <package directory>]
+
+It reads README.md and package.json. Exit 0 the README follows the skeleton, 1 a finding (each
+names its line and rule), 2 the package could not be read.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(HELP);
+} else {
+  process.exitCode = runReadmeGate({ argv: args });
+}

package/bin/script-utils.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// script-utils: one entry for every gate in @cosyte/script-utils (D56). npx runs the bin named
+// after the package, so `npx -y @cosyte/script-utils@<version> <command> [args]` reaches each gate
+// from a repository with no package.json. `<command> --help` is the gate's own help.
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const COMMANDS = {
+  "no-emdash": ["cosyte-no-emdash", "the em and en dash gate, over tracked files and their names"],
+  attw: ["cosyte-attw", "the attw publish gate, for the package here"],
+  "phi-scan": ["cosyte-phi-scan", "the PHI commit-gate, over the repository here"],
+  "internal-refs": [
+    "cosyte-internal-refs",
+    "the internal-reference gate, over the repository here",
+  ],
+  readme: ["cosyte-readme", "the README gate, for the library here"],
+  "claude-card": ["cosyte-claude-card", "the CLAUDE.md card checker"],
+  "agent-notes": ["cosyte-agent-notes", "the agent-notes checker"],
+  catalog: ["cosyte-catalog", "the catalog check, for the library here"],
+};
+
+const HELP = `script-utils: run one of the @cosyte/script-utils gates over the working directory.
+
+  script-utils <command> [arguments]
+  script-utils <command> --help
+
+${Object.entries(COMMANDS)
+  .map(([command, [bin, what]]) => `  ${command.padEnd(14)} ${what} (also the bin ${bin})`)
+  .join("\n")}
+`;
+
+const [command, ...rest] = process.argv.slice(2);
+if (command === undefined || command === "--help" || command === "-h") {
+  process.stdout.write(HELP);
+  process.exitCode = command === undefined ? 2 : 0;
+} else if (!(command in COMMANDS)) {
+  process.stderr.write(`script-utils: ${JSON.stringify(command)} is not a command.\n\n${HELP}`);
+  process.exitCode = 2;
+} else {
+  const bin = fileURLToPath(new URL(`./${COMMANDS[command][0]}.js`, import.meta.url));
+  const run = spawnSync(process.execPath, [bin, ...rest], { stdio: "inherit" });
+  process.exitCode = run.error ? 2 : (run.status ?? 2);
+}

package/catalog.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Types for `@cosyte/script-utils/catalog`: the catalog of Cosyte's libraries and Pathways
+ * (ST13, ST14), generated in cosyte/config from each package's package.json, and the check every
+ * library runs that its description is the catalog's.
+ */
+
+/** The three tiers, in the order ST13 names them. */
+export declare const TIERS: readonly ["standard", "built-on", "engine"];
+
+/** What every record carries, generated from the package's package.json. */
+export interface CatalogRecord {
+  /** The npm package name, for example `@cosyte/hl7`. */
+  readonly name: string;
+  /** The name without its scope, for example `hl7`. */
+  readonly slug: string;
+  /** The package.json description: the package's one canonical line. */
+  readonly description: string;
+  /** The release line, for example `0.1`. */
+  readonly line: string;
+  readonly engines: { readonly node: string };
+  /** `https://github.com/cosyte/<repo>`. */
+  readonly repository: string;
+  /** `https://docs.cosyte.com/<slug>`. */
+  readonly docs: string;
+}
+
+/** One of the 14 libraries. */
+export interface CatalogLibrary extends CatalogRecord {
+  /** `https://www.npmjs.com/package/<name>`. */
+  readonly npm: string;
+  readonly tier: "standard" | "built-on";
+  /** The standard, as readers see it (`HL7 v2`, `C-CDA`), for a library of the standard tier. */
+  readonly standard?: string;
+}
+
+/** Pathways, our integration engine. */
+export interface CatalogEngine extends CatalogRecord {
+  readonly tier: "engine";
+  /** The product name, `Pathways`. */
+  readonly displayName: string;
+  /** For example `in development`. */
+  readonly status: string;
+  /** Whether it is published to npm. */
+  readonly onNpm: boolean;
+}
+
+export interface Catalog {
+  /** The 8 standards' libraries, then the 6 built on them, in the order ST13 names them. */
+  readonly libraries: readonly CatalogLibrary[];
+  readonly engine: CatalogEngine;
+}
+
+/** The hand-kept tiers file, `catalog/tiers.json` in cosyte/config. */
+export interface CatalogTiers {
+  standards: { package: string; standard: string }[];
+  builtOn: string[];
+  engine: { package: string; name: string; status: string; onNpm: boolean };
+}
+
+/** The catalog, as the `catalog.json` beside this module carries it. Deeply frozen. */
+export declare const CATALOG: Catalog;
+
+/** The release line a version is on: `0.<minor>` below 1.0.0, the major from 1.0.0 on. */
+export declare function releaseLine(version: string): string;
+
+/**
+ * Build the catalog from the tiers file and each package's parsed package.json, keyed by name.
+ *
+ * @throws {TypeError} When a tier names a package with no usable manifest, or names one twice.
+ */
+export declare function buildCatalog(
+  tiers: CatalogTiers,
+  manifests: Map<string, Record<string, unknown>> | Record<string, Record<string, unknown>>,
+): Catalog;
+
+/** The record for a package name: a library, the engine, or `undefined`. */
+export declare function catalogEntry(
+  name: string,
+  catalog?: Catalog,
+): CatalogLibrary | CatalogEngine | undefined;
+
+/** A field where a package.json and its catalog record disagree. */
+export interface CatalogDifference {
+  field: "description";
+  catalog: string;
+  packageJson: string;
+}
+
+/**
+ * Compare a package.json with its catalog record. Only the description is compared.
+ *
+ * @throws {TypeError} When the catalog does not list the package.
+ */
+export declare function compareWithCatalog(
+  manifest: Record<string, unknown>,
+  catalog?: Catalog,
+): CatalogDifference[];
+
+export interface CatalogCheckOptions {
+  /** The package directory holding package.json. Default: the working directory. */
+  dir?: string;
+  /** CLI arguments; only `--dir <path>` is accepted. */
+  argv?: string[];
+}
+
+/**
+ * Run the check over one package directory and return the exit code: 0 the description is the
+ * catalog's, 1 it is not, 2 the check could not run. It never exits the process.
+ */
+export declare function runCatalogCheck(options?: CatalogCheckOptions): 0 | 1 | 2;