@cosyte/script-utils 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.6
+
+### Patch Changes
+
+- 239ac9a: The catalog check a library runs is now advisory. `cosyte-catalog` (and `catalog.js`) still compares the package.json description with the catalog this release carries, but a disagreement, or a package the catalog does not list, prints both values as a note and exits 0: a library that changes its description is no longer held red until the next script-utils release. `--strict` (or `{ strict: true }`) restores the gate, 1 for a disagreement and 2 for an unlisted package; 2 still means the check could not run. Keeping the catalog fresh moves to cosyte/config, which compares it with every library's latest release on npm (its description, release line and engines range) nightly and before each config release, and regenerates it from there.
+- 4e30735: The dash gate reads a changelog's dated archive the way the repositories that keep one already do. A line in `scripts/check-no-emdash.exclude` of the form `CHANGELOG.md em-only below ## Released before this file was generated` reads the file from that exact line to its end for the em dash alone, in every form, so an en dash in an old range passes while an em dash still reds; `CHANGELOG.md unread below <line>` does not read the archive at all. Everything above the line is read for both dashes as before, the file's name is still scanned, and a boundary line the file no longer carries is refused rather than ignored. The test suite now spells out every encoded form terminology's own scanner carried (the braced escape, lower-case URL encoding, entities with no semicolon or with leading zeros, and the upper-case X), all of which 0.1.4 already refused. The internal-refs slice rule no longer counts `the` or `each` as a determiner: a fixed-width reader's field slice (`the field slices`, `the slice holding the concept code`) is the reader's vocabulary. `this`, `that`, `another`, `previous`, `next`, `final` and `current` still red, so `the final slice` and `the next slice` are still hits, but a bare `the slice` and `each slice` no longer are.
+- 409ef6c: Under CI, every gate's `--help` and `-h` now exit non-zero instead of 0: the bins exit 2 and the dash gate exits 1, after printing the help to stderr with a line saying why. Help checks nothing, so a package script such as `"attw": "cosyte-attw --help"` used to pass a required check having run no gate. CI is read the way the common runners set it: `CI` set to anything but an empty string, `false` or `0`. At a terminal `--help` prints to stdout and exits 0 as before.
+- 91f8d76: The internal-refs canonical rules take what generalizes from dicom's own gate. An umbrella spec id (`S0228-github-profile-ci-drift`, never a HCPCS code such as `S9083`) is an identifier. The phase rule also catches the adjective forms (`in subsequent phases`, `a later wave`, `waves 2 and 3`) while letting the clinical senses through (`a later phase of the disease`), and a citation of the roadmap (`tracked by the roadmap`). The ADR rule reads the plural, `#` and two-digit forms (`ADRs 0015`, `ADR #0018`, `ADR 23`). The jargon rule catches process commentary (`a later PR`, `this changeset`, `out of scope for this change`) but not `this spec`, `this session` or `this port`, which are reader words in a parser, and lets an image slice in its volume through. The repo-path rule catches the planning files a session writes (`CONTEXT.md`, `REQUIREMENTS.md`, `PITFALLS.md`), the meta-repo or umbrella repo named as a place, and its `work/` and `cards/` directories, and a `decisions/NNNN-` path wherever it sits. Measured on the pinned libraries, this adds 12 hits, all of them real (in hl7, x12 and ncpdp), and removes none. dicom's decision-number, issue-number, `WORD-N` and bare section rules stay dicom's: each collides with reference material another library publishes.
+- d75579c: The internal-refs gate gains a source string-literal pass, `sourceStringLiterals: { enabled, paths, extraRules }`, off by default like the doc-comment pass. It reads the double-quoted, single-quoted and template literals in the tracked source under `paths`, decoded, plus the literals on each line joined, because a string literal reaches a consumer as error and warning text. It never reads a comment, so an item identifier in a `//` note or a `/* */` block stays allowed, and it skips regular-expression literals. In both source passes a NUL byte now reads as a space instead of refusing the file: a raw separator inside a literal is legitimate source, and a space keeps the word boundary beside it. The public-surface pass still refuses a NUL-bearing target.
+- d30eca0: The PHI engine reads a JavaScript or TypeScript source as the document its string literals spell, as well as its bytes. A literal can spell a dashed identifier's separators as `-`, `\u{2D}` or `\x2D`, and the raw floor read straight past it. Each `.ts`, `.js`, `.mts`, `.cts`, `.mjs`, `.cjs`, `.tsx` and `.jsx` target is now also decoded (an escaped backslash first, so a doubled backslash stays text), and the floor and the caller's `detect` run over that view too, so a field-level detector can parse a record whose separators are escapes. The decoded view adds only what the raw view did not report, and says `escape-encoded in a source literal` on the hit. It is a view, not a parser, so it also decodes a `String.raw` template or a comment quoting an escape; an `ID <value>` declaration in the allow-list clears such a hit. `decodeSourceLiterals` and `isSourceLiteralContainer` are exported.
+
+## 0.1.5
+
+### Patch Changes
+
+- f5e1a1f: The internal-refs phase rule lets two kinds of ordinary prose through. `phase` as the second half of a compound word is no longer a hit (`connect-phase socket`, `two-phase state`, `read-phase timeout`), and neither is `phase` or `phases` followed by `where`, `are`, `was`, `were`, `during` or `at` (`All 5 phases are defined`, `Connection lifecycle phase where the error occurred`). A phase named beside those words is still a hit (`shipped in phase 2`, `Phase 3 was where it failed`, `Phase-L`), and both guards' passages are in the rule's self-test floor, so every run proves them. The catalog is regenerated from each library's current package.json: the terminology, deid and synth descriptions take the serial comma, the cli record carries cli's current description, and cli's engines are `>=22.0.0`.
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -271,6 +271,9 @@ npx -y -p @cosyte/script-utils@0.1 cosyte-readme   # or one gate's own bin
 
 Each runs over the working directory, takes the arguments its gate takes, exits with the gate's own
 code, and prints what it does with `--help`. `script-utils` with no command prints the list and exits 2.
+Under CI (`CI` set to anything but empty, `false` or `0`, as GitHub Actions sets it) `--help` and
+`-h` print to stderr and exit non-zero (2, or 1 for the dash gate, whose only codes are 0 and 1): help
+checks nothing, so a package script that ends in `--help` must not pass a required check.
 
 ### The em-dash gate, which is a file rather than a subpath
 
@@ -308,6 +311,16 @@ its backslash-u escape (plain, braced and eight-digit), its braced backslash-x e
 HTML entities, with or without the semicolon and with leading zeros. The default scan also reads
 every tracked file's NAME, because a name is copy too.
 
+A changelog whose dated archive predates the generated part names that archive with a boundary line
+in the same file, `CHANGELOG.md em-only below ## Released before this file was generated` or
+`CHANGELOG.md unread below ## Released before this file was generated`. The text after `below` is a
+whole line of that file, matched exactly; from it to the end of the file is the archive. `em-only`
+reads the archive for the em dash alone, in every form, so an en dash in an old range passes and an em
+dash still fails; `unread` does not read the archive. Above the line the file is read for both dashes
+like any other, and its name is scanned as always. A boundary line the file no longer carries is
+refused, so a lost heading fails closed, and a file cannot be both left out whole and given a
+boundary.
+
 ### The README gate
 
 `@cosyte/script-utils/readme` checks a library's README against the house skeleton, and against a
@@ -362,18 +375,28 @@ record is generated from the package's own `package.json` (name, description, re
 engines, repository, docs and npm URLs) and carries its tier; the data ships as `catalog.json`
 beside the module, and `CATALOG` is that file, frozen.
 
-Each package.json description is that library's one canonical line (ST14), so every library runs
-the check that its description is the catalog's, with no file of its own:
+Each package.json description is that library's one canonical line (ST14). Two sides check it, and
+each checks one thing:
+
+- **cosyte/config keeps the catalog fresh.** `node scripts/catalog.mjs check --npm` compares the
+  committed catalog with every library's latest release on npm. It runs nightly and before each
+  config release, and fails when a library has released a description, release line or engines
+  range the catalog does not carry; `write --npm` regenerates it. npm keeps 255 characters of a
+  description, so a longer one is fresh when npm holds its first 255, and the run notes it.
+- **A library can check its own line, advisory.** With no file of its own:
 
 ```sh
 node node_modules/@cosyte/script-utils/catalog.js              # the package in this directory
 node node_modules/@cosyte/script-utils/catalog.js --dir <path> # another package directory
+node node_modules/@cosyte/script-utils/catalog.js --strict     # a disagreement fails
 ```
 
-Exit 0 means the description is the catalog's, 1 that it is not (both values are printed), and 2
-that the check could not run (no package.json, or a package the catalog does not list). A changed
-description therefore goes through the catalog: regenerate it in cosyte/config
-(`node scripts/catalog.mjs write`), release this package, then move the library to that release.
+It compares the package.json description with the catalog this release of `@cosyte/script-utils`
+carries. A disagreement, or a package the catalog does not list, prints both values as a note and
+exits 0: a library that changes its description is not held red until the next script-utils
+release, because config's check against npm picks the change up once the library is released. Exit
+2 means the check could not run (no package.json, or an argument it does not accept). `--strict`
+restores the gate: 1 for a disagreement, 2 for an unlisted package.
 
 ### The agent-notes checker
 
@@ -528,6 +551,13 @@ every `scanRoots` entry yielded a file the WALK read, naming the starved roots);
 cross-cutting detection floor that finds a dashed SSN shape and an email at an undeclared domain over
 every file, always.
 
+**A JavaScript or TypeScript source is read twice**: as its bytes, and as the document its string
+literals spell, with `\uXXXX`, `\u{...}`, `\xHH` and the single-character escapes decoded (an
+escaped backslash first, so a doubled backslash before `u002D` stays text). The floor and your
+`detect` run over both views, and the decoded view adds only what the raw view did not report, with
+`, escape-encoded in a source literal` on its reason. It is a view, not a parser, so it also decodes a
+`String.raw` template or a comment quoting an escape; an `ID <value>` declaration clears such a hit.
+
 **The RULES, local to your repo, never moved and never shipped in this package.**
 `scripts/phi-allow-list.txt` (the positive declaration that a token is synthetic, tagged `NAME`,
 `DOB`, `ADDR`, `ID`, `EMAILDOMAIN`); `phi-scan-overrides.md` (the `--allow-fixture` audit log, and
@@ -593,7 +623,7 @@ still refuses such an entry on both of its routes.
 `@cosyte/script-utils/internal-refs` keeps our own bookkeeping off every surface a consumer reads:
 item identifiers, phase and wave language, ADR numbers, internal repository paths and traceability
 markers, on the pages, the npm metadata and, optionally, the doc comments that compile into shipped
-type declarations.
+type declarations and the string literals a consumer reads as error and warning text.
 
 ```ts
 import { runInternalRefsScan } from "@cosyte/script-utils/internal-refs";
@@ -605,6 +635,7 @@ process.exit(
     surfacePaths: ["README.md", "TRADEMARKS.md", "LICENSE", "docs-content"],
     accountedTarballFiles: ["CHANGELOG.md", "dist"],
     sourceDocComments: { enabled: true, paths: ["src/*.ts", "src/**/*.ts"] },
+    sourceStringLiterals: { enabled: true, paths: ["src/*.ts", "src/**/*.ts"] },
   }),
 );
 ```
@@ -632,14 +663,23 @@ gets wrong, and a default would be one repository's answer imposed on every othe
 | 3 Public surface           | `surfacePaths`          | **Required**, empty refused, every entry must be tracked.             |
 | 4 Tarball accounting       | `accountedTarballFiles` | **Required.** The `files` entries already accounted for.              |
 | 5 Source doc comments      | `sourceDocComments`     | Defaulted OFF. Enable where the build copies doc text verbatim.       |
-| 6 Exit codes               | `exitCodes`             | Defaulted `{ clean: 0, hits: 1, refuse: 1 }`. `clean` must stay 0.    |
-| 7 Added detection          | `extraRules`            | Defaulted `[]`. Each added rule brings its own samples.               |
-| 8 Added self-test material | `extraSamples`          | Defaulted `{}`. Additive only.                                        |
-| 9 Repository under test    | `repoRoot`              | Defaulted to the working directory, anchored at its git top level.    |
-| 10 Report destination      | `write`                 | Defaulted to the process streams.                                     |
+| 6 Source string literals   | `sourceStringLiterals`  | Defaulted OFF. Enable where messages reach a consumer. No comments.   |
+| 7 Exit codes               | `exitCodes`             | Defaulted `{ clean: 0, hits: 1, refuse: 1 }`. `clean` must stay 0.    |
+| 8 Added detection          | `extraRules`            | Defaulted `[]`. Each added rule brings its own samples.               |
+| 9 Added self-test material | `extraSamples`          | Defaulted `{}`. Additive only.                                        |
+| 10 Repository under test   | `repoRoot`              | Defaulted to the working directory, anchored at its git top level.    |
+| 11 Report destination      | `write`                 | Defaulted to the process streams.                                     |
 
 `CONFIG_AXES` is the same table as data, so a consumer can enumerate it rather than transcribe it.
 
+The string-literal pass reads double-quoted, single-quoted and template literals (a multi-line
+template whole, a `${...}` as a space), decodes their escapes, and also reads the literals on one
+source line joined, so a phrase split across `"a " + "b"` is seen. It never reads a comment: a `//`
+line, a trailing `//` and a `/* */` block are skipped, so an item identifier in a maintainer's note
+stays allowed. A regular-expression literal is skipped too. In both source passes a NUL byte reads as
+a space instead of refusing the file, since a raw separator inside a literal is legitimate source;
+the clean line counts them.
+
 #### Two things worth knowing before you adopt this one
 
 **The prefix set has to be extended by hand, and that is the cheaper mistake.** A new programme

package/bin/cosyte-agent-notes.js

@@ -2,9 +2,10 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runAgentNotesCheck } from "../agent-notes.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-agent-notes: check a repository's agent notes and every pointer into them.
 
@@ -17,7 +18,7 @@ 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);
+  process.exitCode = answerHelp("cosyte-agent-notes", HELP);
 } else {
   process.exitCode = runAgentNotesCheck({ argv: args });
 }

package/bin/cosyte-attw.js

@@ -2,9 +2,10 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runAttwCli } from "../attw.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-attw: run the attw publish gate for the package in the working directory.
 
@@ -18,7 +19,7 @@ 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);
+  process.exitCode = answerHelp("cosyte-attw", HELP);
 } else {
   process.exitCode = runAttwCli(args);
 }

package/bin/cosyte-catalog.js

@@ -2,22 +2,24 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runCatalogCheck } from "../catalog.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-catalog: check that a library's package.json description is the catalog's.
 
-  cosyte-catalog [--dir <package directory>]
+  cosyte-catalog [--dir <package directory>] [--strict]
 
-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.
+The catalog is the one list of our libraries, generated in cosyte/config, which keeps it fresh
+against npm. This check is advisory: exit 0 when the description is the catalog's, and 0 with both
+values printed when it is not or the package is unlisted; 2 when package.json cannot be read. With
+--strict a disagreement exits 1 and an unlisted package 2.
 `;
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-catalog", HELP);
 } else {
   process.exitCode = runCatalogCheck({ argv: args });
 }

package/bin/cosyte-claude-card.js

@@ -2,9 +2,10 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runClaudeCardGate } from "../claude-card.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-claude-card: check a repository's CLAUDE.md against the card spec.
 
@@ -17,7 +18,7 @@ Gate, Hazard and Rules in order, at most 60 lines of at most 100 characters and
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-claude-card", HELP);
 } else {
   process.exitCode = runClaudeCardGate({ argv: args });
 }

package/bin/cosyte-internal-refs.js

@@ -2,9 +2,10 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runInternalRefsCli } from "../internal-refs.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-internal-refs: run the internal-reference gate over the repository in the working directory.
 
@@ -17,7 +18,7 @@ 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);
+  process.exitCode = answerHelp("cosyte-internal-refs", HELP);
 } else {
   process.exitCode = runInternalRefsCli(args);
 }

package/bin/cosyte-phi-scan.js

@@ -2,9 +2,10 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runPhiScanCli } from "../phi-scan.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-phi-scan: run the PHI commit-gate over the repository in the working directory.
 
@@ -20,7 +21,7 @@ values, and scripts/phi-scan.exclude names literal tracked paths to leave out. E
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-phi-scan", HELP);
 } else {
   process.exitCode = runPhiScanCli(args);
 }

package/bin/cosyte-readme.js

@@ -2,9 +2,10 @@
 // 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.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runReadmeGate } from "../readme.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-readme: check a library README against the house skeleton and npm's size limit.
 
@@ -16,7 +17,7 @@ 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);
+  process.exitCode = answerHelp("cosyte-readme", HELP);
 } else {
   process.exitCode = runReadmeGate({ argv: args });
 }

package/bin/help.js

@@ -0,0 +1,41 @@
+// Not a bin: the one answer every gate bin gives to `--help` and `-h`, written once beside them.
+//
+// A gate asked for its help checks nothing. At a terminal that is what was asked for, so the help
+// goes to stdout and the exit is 0. Under CI it is a trap: a package script that ends in `--help`
+// passes a required check having checked nothing (`"attw": "cosyte-attw --help"` did exactly that).
+// So when `CI` is set to anything but an empty string, `false` or `0`, which is how GitHub Actions
+// and the other common runners announce themselves, the help goes to stderr, a refusal follows it,
+// and the bin exits 2, the code every gate here uses for "did not run".
+
+/**
+ * Whether this process runs under CI, read the way the common runners set it.
+ *
+ * @param {Record<string, string | undefined>} [env] The environment to read.
+ * @returns {boolean} True when `CI` is set to anything but an empty string, `false` or `0`.
+ */
+export function underCi(env = process.env) {
+  const value = env.CI;
+  return value !== undefined && value !== "" && value !== "false" && value !== "0";
+}
+
+/**
+ * Answer `--help`: print the help and return 0, or under CI print it to stderr with a refusal and
+ * return 2.
+ *
+ * @param {string} name The bin's name, for the refusal line.
+ * @param {string} help The help text.
+ * @param {Record<string, string | undefined>} [env] The environment to read.
+ * @returns {number} The exit code.
+ */
+export function answerHelp(name, help, env = process.env) {
+  if (!underCi(env)) {
+    process.stdout.write(help);
+    return 0;
+  }
+  process.stderr.write(help);
+  process.stderr.write(
+    `${name}: refusing --help under CI (CI=${env.CI}). It prints this text and checks nothing, ` +
+      "so a CI step that runs it must not pass. Run the gate without --help.\n",
+  );
+  return 2;
+}

package/bin/script-utils.js

@@ -1,11 +1,14 @@
 #!/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.
+// from a repository with no package.json. `<command> --help` is the gate's own help; under CI
+// every `--help` exits 2, because it checks nothing.
 
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { answerHelp } from "./help.js";
+
 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"],
@@ -31,9 +34,11 @@ ${Object.entries(COMMANDS)
 `;
 
 const [command, ...rest] = process.argv.slice(2);
-if (command === undefined || command === "--help" || command === "-h") {
+if (command === undefined) {
   process.stdout.write(HELP);
-  process.exitCode = command === undefined ? 2 : 0;
+  process.exitCode = 2;
+} else if (command === "--help" || command === "-h") {
+  process.exitCode = answerHelp("script-utils", HELP);
 } else if (!(command in COMMANDS)) {
   process.stderr.write(`script-utils: ${JSON.stringify(command)} is not a command.\n\n${HELP}`);
   process.exitCode = 2;

package/catalog.d.ts

@@ -99,12 +99,19 @@ export declare function compareWithCatalog(
 export interface CatalogCheckOptions {
   /** The package directory holding package.json. Default: the working directory. */
   dir?: string;
-  /** CLI arguments; only `--dir <path>` is accepted. */
+  /** CLI arguments; `--dir <path>` and `--strict` are accepted. */
   argv?: string[];
+  /**
+   * Fail on a disagreement (1) or an unlisted package (2) instead of printing a note and exiting
+   * 0. Default: false, because keeping the catalog fresh is cosyte/config's job.
+   */
+  strict?: boolean;
 }
 
 /**
- * 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.
+ * Run the check over one package directory and return the exit code. Advisory by default: 0 when
+ * the description is the catalog's, and 0 with a note when it is not or the package is unlisted.
+ * With `strict`, 1 for a disagreement and 2 for an unlisted package. 2 whenever the check could not
+ * run. It never exits the process.
  */
 export declare function runCatalogCheck(options?: CatalogCheckOptions): 0 | 1 | 2;

package/catalog.js

@@ -8,16 +8,20 @@
 // A site, the org profile, a deck or a knowledgebase page reads that one list instead of keeping
 // its own roster.
 //
-// IT ALSO CARRIES THE CHECK EVERY LIBRARY RUNS. Each package.json description is that library's one
-// canonical line (ST14), so the description in a library's package.json must be the catalog's.
-// When a library changes its description, its check fails until the catalog is regenerated and a
-// script-utils release carries it: the catalog and the package cannot quietly disagree.
+// IT ALSO CARRIES THE CHECK A LIBRARY CAN RUN, AND THAT CHECK IS ADVISORY. Each package.json
+// description is that library's one canonical line (ST14). Keeping the catalog fresh is cosyte/config's
+// job: `scripts/catalog.mjs check --npm` compares the catalog with every library's latest npm release,
+// nightly and before each config release. So a library that changes its description is not held red
+// until the next script-utils release: this check prints both values as a note and exits 0. `--strict`
+// makes a disagreement exit 1 and an unlisted package exit 2, for a caller that wants the old gate.
 //
 //   node node_modules/@cosyte/script-utils/catalog.js              # the package in this directory
 //   node node_modules/@cosyte/script-utils/catalog.js --dir <path> # another package directory
+//   node node_modules/@cosyte/script-utils/catalog.js --strict     # a disagreement fails
 //
-// EXIT CODES, the contract every gate here keeps: 0 the description agrees, 1 it does not, 2 the
-// check could not run (no package.json, or a package the catalog does not list).
+// EXIT CODES: 0 the description agrees, or (advisory) it does not and a note says so; 1 it does not,
+// with --strict; 2 the check could not run (no package.json, a bad argument, or, with --strict, a
+// package the catalog does not list).
 //
 // ZERO DEPENDENCIES AND NO BUILD STEP, like the rest of this package.
 
@@ -192,21 +196,29 @@ export function compareWithCatalog(manifest, catalog = CATALOG) {
 /**
  * Run the check over one package directory and return the exit code. It never exits the process.
  *
- * @param {{ dir?: string, argv?: string[] }} [options] `dir` is the package directory (default:
- *   the working directory). `argv` is the CLI arguments, read only for `--dir <path>`.
- * @returns {0 | 1 | 2} 0 agree, 1 disagree, 2 the check could not run.
+ * ADVISORY BY DEFAULT: a disagreement or an unlisted package is printed as a note and exits 0,
+ * because keeping the catalog fresh is cosyte/config's job (`scripts/catalog.mjs check --npm`).
+ * `strict` (or `--strict`) restores the gate: 1 for a disagreement, 2 for an unlisted package.
+ *
+ * @param {{ dir?: string, argv?: string[], strict?: boolean }} [options] `dir` is the package
+ *   directory (default: the working directory). `argv` is the CLI arguments, read for
+ *   `--dir <path>` and `--strict`.
+ * @returns {0 | 1 | 2} 0 agree (or advisory), 1 disagree under strict, 2 the check could not run.
  */
 export function runCatalogCheck(options = {}) {
   let dir = options.dir ?? process.cwd();
+  let strict = options.strict === true;
   const argv = options.argv ?? [];
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === "--dir" && typeof argv[i + 1] === "string") {
       dir = argv[i + 1];
       i += 1;
+    } else if (argv[i] === "--strict") {
+      strict = true;
     } else if (argv[i] !== "--") {
       process.stderr.write(
         `catalog check: ${JSON.stringify(argv[i])} is not an argument this check accepts (only ` +
-          `--dir <package directory>). Nothing was checked.\n`,
+          `--dir <package directory> and --strict). Nothing was checked.\n`,
       );
       return 2;
     }
@@ -223,8 +235,15 @@ export function runCatalogCheck(options = {}) {
   try {
     differences = compareWithCatalog(manifest);
   } catch (err) {
-    process.stderr.write(`catalog check: ${err.message} Nothing was checked.\n`);
-    return 2;
+    if (strict) {
+      process.stderr.write(`catalog check: ${err.message} Nothing was checked.\n`);
+      return 2;
+    }
+    process.stderr.write(
+      `catalog check: note: ${err.message} The catalog is cosyte/config's to keep fresh; this ` +
+        `check is advisory, so it exits 0.\n`,
+    );
+    return 0;
   }
   if (differences.length === 0) {
     process.stdout.write(`catalog check: ${manifest.name}'s description is the catalog's.\n`);
@@ -237,11 +256,21 @@ export function runCatalogCheck(options = {}) {
         `    catalog:      ${JSON.stringify(d.catalog)}`,
     )
     .join("\n");
+  if (!strict) {
+    process.stderr.write(
+      `catalog check: note: ${manifest.name}'s package.json and the catalog this release of ` +
+        `@cosyte/script-utils carries disagree.\n${report}\n` +
+        `This is advisory and exits 0. Once this package is released with the new description, ` +
+        `cosyte/config's nightly check against npm (scripts/catalog.mjs check --npm) flags the ` +
+        `catalog, and the next script-utils release carries it.\n`,
+    );
+    return 0;
+  }
   process.stderr.write(
     `catalog check: ${manifest.name}'s package.json and the catalog disagree.\n${report}\n` +
-      `The catalog is generated from package.json in cosyte/config (scripts/catalog.mjs) and ` +
-      `ships in @cosyte/script-utils. Change both together: regenerate the catalog, release ` +
-      `script-utils, then move this package to that release.\n`,
+      `The catalog is generated in cosyte/config (scripts/catalog.mjs) and ships in ` +
+      `@cosyte/script-utils. Regenerate it there, release script-utils, then move this package to ` +
+      `that release.\n`,
   );
   return 1;
 }

package/catalog.json

@@ -116,7 +116,7 @@
     {
       "name": "@cosyte/terminology",
       "slug": "terminology",
-      "description": "Terminology engine for US healthcare code systems in Node.js and TypeScript: FHIR $translate, $lookup, $validate-code and $expand over code systems, value sets and maps you supply.",
+      "description": "Terminology engine for US healthcare code systems in Node.js and TypeScript: FHIR $translate, $lookup, $validate-code, and $expand over code systems, value sets, and maps you supply.",
       "line": "0.1",
       "engines": {
         "node": ">=22.0.0"
@@ -142,7 +142,7 @@
     {
       "name": "@cosyte/deid",
       "slug": "deid",
-      "description": "Healthcare de-identification for Node.js and TypeScript: applies a HIPAA Safe Harbor policy to HL7 v2, C-CDA, FHIR R4, X12, NCPDP Telecom and DICOM, fails closed, and emits a value-free manifest.",
+      "description": "Healthcare de-identification for Node.js and TypeScript: applies a HIPAA Safe Harbor policy to HL7 v2, C-CDA, FHIR R4, X12, NCPDP Telecom, and DICOM, fails closed, and emits a value-free manifest.",
       "line": "0.1",
       "engines": {
         "node": ">=22.0.0"
@@ -155,7 +155,7 @@
     {
       "name": "@cosyte/synth",
       "slug": "synth",
-      "description": "Deterministic, seedable synthetic healthcare test fixtures for Node.js and TypeScript: HL7 v2, FHIR R4 and US Core, C-CDA, X12, NCPDP and ASTM, spec-clean by construction and never real PHI.",
+      "description": "Deterministic, seedable synthetic healthcare test fixtures for Node.js and TypeScript: HL7 v2, FHIR R4 and US Core, C-CDA, X12, NCPDP, and ASTM, spec-clean by construction and never real PHI.",
       "line": "0.1",
       "engines": {
         "node": ">=22.0.0"
@@ -181,10 +181,10 @@
     {
       "name": "@cosyte/cli",
       "slug": "cli",
-      "description": "The cosyte CLI: a PHI-safe developer front door over the @cosyte/* healthcare parsers. Parse HL7 v2 / FHIR from a file or stdin to typed JSON, with a documented exit-code contract.",
+      "description": "The Cosyte command line for Node.js and TypeScript: one command over HL7 v2, FHIR R4, X12, ASTM, NCPDP, C-CDA, DICOM, and MLLP, with HL7 v2 to FHIR conversion from transform, code mapping from terminology, and the cosyte-mcp MCP server for agents. Value-free diagnostics and a documented exit-code contract.",
       "line": "0.1",
       "engines": {
-        "node": ">=22.0.0 <26.0.0"
+        "node": ">=22.0.0"
       },
       "repository": "https://github.com/cosyte/cli",
       "docs": "https://docs.cosyte.com/cli",