@cosyte/script-utils 0.1.1 → 0.1.3

package/catalog.json

@@ -0,0 +1,210 @@
+{
+  "$comment": "GENERATED by cosyte/config scripts/catalog.mjs from each package's package.json and catalog/tiers.json. Do not edit by hand: change the package.json or the tiers file, then run `node scripts/catalog.mjs write` from the umbrella.",
+  "libraries": [
+    {
+      "name": "@cosyte/hl7",
+      "slug": "hl7",
+      "description": "Developer-focused HL7 v2 toolkit for Node.js and TypeScript, message parsing and building, mutation and serialization, and one-line helpers.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/hl7",
+      "docs": "https://docs.cosyte.com/hl7",
+      "npm": "https://www.npmjs.com/package/@cosyte/hl7",
+      "tier": "standard",
+      "standard": "HL7 v2"
+    },
+    {
+      "name": "@cosyte/mllp",
+      "slug": "mllp",
+      "description": "MLLP transport for HL7 v2 in Node.js and TypeScript: client and server, framing, ACK correlation, auto-reconnect, TLS, and an in-memory transport for tests.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/mllp",
+      "docs": "https://docs.cosyte.com/mllp",
+      "npm": "https://www.npmjs.com/package/@cosyte/mllp",
+      "tier": "standard",
+      "standard": "MLLP"
+    },
+    {
+      "name": "@cosyte/fhir",
+      "slug": "fhir",
+      "description": "FHIR R4 for Node.js and TypeScript: a resource model that keeps every value exactly as written, JSON and XML codecs, layered validation, and a safety readout for status and negation.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/fhir",
+      "docs": "https://docs.cosyte.com/fhir",
+      "npm": "https://www.npmjs.com/package/@cosyte/fhir",
+      "tier": "standard",
+      "standard": "FHIR"
+    },
+    {
+      "name": "@cosyte/ccda",
+      "slug": "ccda",
+      "description": "C-CDA parser, serializer, and builder for Node.js and TypeScript: lenient on parse, spec-clean on emit.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/ccda",
+      "docs": "https://docs.cosyte.com/ccda",
+      "npm": "https://www.npmjs.com/package/@cosyte/ccda",
+      "tier": "standard",
+      "standard": "C-CDA"
+    },
+    {
+      "name": "@cosyte/x12",
+      "slug": "x12",
+      "description": "Developer-focused ASC X12 healthcare EDI parser, serializer, and builder for Node.js and TypeScript: lenient on parse, spec-clean on emit.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/x12",
+      "docs": "https://docs.cosyte.com/x12",
+      "npm": "https://www.npmjs.com/package/@cosyte/x12",
+      "tier": "standard",
+      "standard": "X12"
+    },
+    {
+      "name": "@cosyte/ncpdp",
+      "slug": "ncpdp",
+      "description": "NCPDP parser, serializer, and builder for Node.js and TypeScript: SCRIPT ePrescribing and Telecom pharmacy claims, lenient on parse, spec-clean on emit.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/ncpdp",
+      "docs": "https://docs.cosyte.com/ncpdp",
+      "npm": "https://www.npmjs.com/package/@cosyte/ncpdp",
+      "tier": "standard",
+      "standard": "NCPDP"
+    },
+    {
+      "name": "@cosyte/astm",
+      "slug": "astm",
+      "description": "ASTM parser, serializer, and builder for Node.js and TypeScript: lenient on parse, spec-clean on emit.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/astm",
+      "docs": "https://docs.cosyte.com/astm",
+      "npm": "https://www.npmjs.com/package/@cosyte/astm",
+      "tier": "standard",
+      "standard": "ASTM"
+    },
+    {
+      "name": "@cosyte/dicom",
+      "slug": "dicom",
+      "description": "DICOM Part 10 parser + utility library for Node.js and TypeScript: metadata-first, vendor-quirky-tolerant, dual ESM/CJS.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/dicom",
+      "docs": "https://docs.cosyte.com/dicom",
+      "npm": "https://www.npmjs.com/package/@cosyte/dicom",
+      "tier": "standard",
+      "standard": "DICOM"
+    },
+    {
+      "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.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/terminology",
+      "docs": "https://docs.cosyte.com/terminology",
+      "npm": "https://www.npmjs.com/package/@cosyte/terminology",
+      "tier": "built-on"
+    },
+    {
+      "name": "@cosyte/transform",
+      "slug": "transform",
+      "description": "HL7 v2 → FHIR R4 transformation library for Node.js and TypeScript: IG-grounded, fail-safe, value-free diagnostics; never a confident wrong FHIR value.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/transform",
+      "docs": "https://docs.cosyte.com/transform",
+      "npm": "https://www.npmjs.com/package/@cosyte/transform",
+      "tier": "built-on"
+    },
+    {
+      "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.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/deid",
+      "docs": "https://docs.cosyte.com/deid",
+      "npm": "https://www.npmjs.com/package/@cosyte/deid",
+      "tier": "built-on"
+    },
+    {
+      "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.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/synth",
+      "docs": "https://docs.cosyte.com/synth",
+      "npm": "https://www.npmjs.com/package/@cosyte/synth",
+      "tier": "built-on"
+    },
+    {
+      "name": "@cosyte/dates",
+      "slug": "dates",
+      "description": "Date and time utilities for the @cosyte/* healthcare parsers: precision-preserving conversion and validation that never guesses a timezone.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "repository": "https://github.com/cosyte/dates",
+      "docs": "https://docs.cosyte.com/dates",
+      "npm": "https://www.npmjs.com/package/@cosyte/dates",
+      "tier": "built-on"
+    },
+    {
+      "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.",
+      "line": "0.1",
+      "engines": {
+        "node": ">=22.0.0 <26.0.0"
+      },
+      "repository": "https://github.com/cosyte/cli",
+      "docs": "https://docs.cosyte.com/cli",
+      "npm": "https://www.npmjs.com/package/@cosyte/cli",
+      "tier": "built-on"
+    }
+  ],
+  "engine": {
+    "name": "@cosyte/pathways",
+    "slug": "pathways",
+    "description": "A code-first healthcare integration engine for Node.js: channels in YAML, transforms in TypeScript. Early and not yet released.",
+    "line": "0.0",
+    "engines": {
+      "node": ">=24.0.0"
+    },
+    "repository": "https://github.com/cosyte/pathways",
+    "docs": "https://docs.cosyte.com/pathways",
+    "tier": "engine",
+    "displayName": "Pathways",
+    "status": "in development",
+    "onNpm": false
+  }
+}

package/check-no-emdash.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 # scripts/check-no-emdash.sh
-# Brand rule (founder directive, 2026-07-24): cosyte never uses the em dash.
+# Brand rule (founder directive, 2026-07-24): we never use the em dash.
 # The em dash (U+2014) reads as an AI tell, so it is banned outright across every
-# cosyte surface. Source of truth: `knowledgebase/06-brand/voice-and-tone.md`
-# ("No em dashes. Ever."), which names COMMIT MESSAGES explicitly.
+# Cosyte surface. The en dash (U+2013) is banned with it (operator decision,
+# 2026-11-07), and this gate refuses both. Source of truth:
+# `knowledgebase/06-brand/voice-and-tone.md`, which names COMMIT MESSAGES explicitly.
 #
 # THIS FILE IS THE ONE IMPLEMENTATION OF THE EM-DASH GATE FOR THIS ESTATE, and config
 # owns it. Every other repo EXECUTES THESE EXACT BYTES and tracks no implementation of
@@ -57,8 +58,8 @@
 # over a tree that was cleared rather than green over a tree nobody looked at. A gate
 # without the sweep reds CI on arrival; a sweep without the gate lets it grow back.
 #
-# The fix is never to re-encode the character: rewrite the sentence with a period, a
-# colon, a comma, or parentheses.
+# The fix is never to re-encode the character: write a range with "to", and rewrite a
+# pause with a period, a colon, a comma, or parentheses.
 #
 # ---------------------------------------------------------------------------
 # THE SURFACE. Four modes, and the exit vocabulary is CLOSED AT TWO CODES.
@@ -146,7 +147,7 @@
 # hardcoded name would have excluded a consuming repo's `scripts/check-no-emdash.sh`
 # whether or not one existed, which is an exclusion granted to a file nobody reviewed.
 #
-# Nothing checks the checker, so keep this file free of the literal character: it
+# Nothing checks the checker, so keep this file free of either literal character: it
 # matches by codepoint and by encoding and never spells one out.
 # ---------------------------------------------------------------------------
 # BINARY POSTURE. This repo scans EVERY tracked file with NO binary partition and
@@ -230,12 +231,16 @@ export LC_ALL=C.UTF-8
 # Matches U+2014 as the literal character and as its encodings: %E2%80%94 (URL), the
 # JS backslash-u escape, and the — / — / — HTML entities. The
 # escape is not theoretical in this repo: it is what the parser-template manifest
-# carried, and a literal-only sweep passed straight over it.
-#
-# THE MATCH VOCABULARY IS FROZEN at these six forms. A consumer may narrow WHAT IS
-# SCANNED through the declaration above; nothing may narrow WHAT IS MATCHED, and
-# widening it is a change every consuming repo inherits at once and is specced as one.
+# carried, and a literal-only sweep passed straight over it. Matches U+2013 the same
+# way: %E2%80%93, the backslash-u escape, and the – / – / – HTML
+# entities.
+#
+# THE MATCH VOCABULARY IS FROZEN at these twelve forms, six for each dash. A consumer
+# may narrow WHAT IS SCANNED through the declaration above; nothing may narrow WHAT IS
+# MATCHED, and widening it is a change every consuming repo inherits at once and is
+# specced as one. The en dash's six were that change (operator decision, 2026-11-07).
 PATTERN='\x{2014}|%E2%80%94|\\u2014|—|—|—'
+PATTERN+='|\x{2013}|%E2%80%93|\\u2013|–|–|–'
 
 # The declaration's path, relative to the top level of the repo under scan. Deliberately
 # NOT relative to this file: in a consuming repo this file lives under `node_modules/`
@@ -671,10 +676,11 @@ fi
 
 if [ "$MODE" = files ] || [ "$MODE" = stdin ]; then
   # SELF-TEST: prove the scanner can still MATCH what it is meant to catch before any
-  # clean result is believed. `printf` emits U+2014 as its UTF-8 bytes, so this file
-  # still never contains the literal character. Scope the claim honestly: this proves
-  # the PATTERN compiles and matches, not that the scan reached every tracked file. The
-  # probe below and the refusals further down cover the second half.
+  # clean result is believed, and that it leaves alone what the rule allows. `printf`
+  # emits U+2014, U+2013 and U+2212 as their UTF-8 bytes, so this file still never
+  # contains any of those characters. Scope the claim honestly: this proves the PATTERN
+  # compiles and matches, not that the scan reached every tracked file. The probe below
+  # and the refusals further down cover the second half.
   if ! printf 'a\xe2\x80\x94b\n' | grep -qP "$PATTERN"; then
     echo "ERROR: check-no-emdash - the scanner cannot match a known em dash." >&2
     echo "       grep -P is unavailable, not in UTF-8 mode (LC_ALL=${LC_ALL}), or has" >&2
@@ -683,6 +689,22 @@ if [ "$MODE" = files ] || [ "$MODE" = stdin ]; then
     echo "       Refusing to report a clean tree on a scanner that cannot see." >&2
     exit 1
   fi
+  if ! printf 'a\xe2\x80\x93b\n' | grep -qP "$PATTERN"; then
+    echo "ERROR: check-no-emdash - the scanner cannot match a known en dash." >&2
+    echo "       grep -P is unavailable, not in UTF-8 mode (LC_ALL=${LC_ALL}), or has" >&2
+    echo "       been forced to basic regular expressions, under which the alternations" >&2
+    echo "       in PATTERN are literals and match nothing." >&2
+    echo "       Refusing to report a clean tree on a scanner that cannot see." >&2
+    exit 1
+  fi
+  # The clean fixture: hyphens, a range written with "to", and the minus sign (U+2212),
+  # none of which the rule bans. A scanner that matched it would fail every tree, so its
+  # findings could not be told from noise.
+  if printf 'a-b, 2 to 3 tiers, \xe2\x88\x921\n' | grep -qP "$PATTERN"; then
+    echo "ERROR: check-no-emdash - the scanner matched clean text (hyphens and a minus sign)." >&2
+    echo "       Refusing to report findings from a scanner that flags what the rule allows." >&2
+    exit 1
+  fi
 
   # SCANNER VISIBILITY PROBE: prove the scanner can still READ a file before believing a
   # word it says about one. The self-test above asserts what the tool MATCHES; this
@@ -708,7 +730,7 @@ if [ "$MODE" = files ] || [ "$MODE" = stdin ]; then
     echo "       NUL byte and a seeded em dash: no hit on stdout, no diagnostic on stderr," >&2
     echo "       exit 0. That is a scanner that cannot see its subject, and it is" >&2
     echo "       indistinguishable from a clean tree." >&2
-    echo "       The known cause is a \`grep\` interposed with -I forced (the cosyte dev" >&2
+    echo "       The known cause is a \`grep\` interposed with -I forced (the Cosyte dev" >&2
     echo "       container ships one as a shell function; \`export -f grep\` reaches a child" >&2
     echo "       script). Run this gate with a real GNU grep." >&2
     exit 1
@@ -719,9 +741,10 @@ fail_with_hits() {
   local what="$1" hits="$2"
   echo "$hits" >&2
   echo "" >&2
-  echo "ERROR: check-no-emdash - em dash (U+2014, or an encoded form) found in ${what}." >&2
-  echo "       cosyte never uses em dashes (founder directive; 06-brand/voice-and-tone.md)." >&2
-  echo "       Rewrite with a period, colon, comma, or parentheses. Never re-encode it." >&2
+  echo "ERROR: check-no-emdash - em or en dash (U+2014 or U+2013, or an encoded form) found in ${what}." >&2
+  echo "       We never use em or en dashes (founder directive; 06-brand/voice-and-tone.md)." >&2
+  echo "       Write a range with \"to\"; rewrite a pause with a period, colon, comma, or" >&2
+  echo "       parentheses. Never re-encode it." >&2
   exit 1
 }
 
@@ -738,7 +761,7 @@ refuse_if_incomplete() {
   if grep -qi 'binary file' "$ERRLOG"; then
     echo "ERROR: check-no-emdash - the input named above MATCHED the banned pattern, but" >&2
     echo "       grep classifies it as binary, so the hit is reported without a line" >&2
-    echo "       number. Treat it as a real em dash." >&2
+    echo "       number. Treat it as a real em or en dash." >&2
     if [ "$SCAN_MODE" = stdin ]; then
       echo "       The text piped in is not valid UTF-8. Fix the encoding of whatever" >&2
       echo "       produced it, then rewrite the sentence." >&2
@@ -749,7 +772,7 @@ refuse_if_incomplete() {
       echo "       has ever tracked. If it is the latter, read the BINARY POSTURE note in" >&2
       echo "       this script's header before changing anything." >&2
     fi
-    echo "       cosyte never uses em dashes (founder directive; 06-brand/voice-and-tone.md)." >&2
+    echo "       We never use em or en dashes (founder directive; 06-brand/voice-and-tone.md)." >&2
   fi
   if grep -qiv 'binary file' "$ERRLOG"; then
     echo "ERROR: check-no-emdash - the scan reported errors, so it did not read all of" >&2
@@ -776,7 +799,7 @@ if [ "$MODE" = stdin ]; then
   HITS=$(grep -nP -e "$PATTERN" -- "$STDINBUF" 2>> "$ERRLOG" || true)
   refuse_if_incomplete
   [ -n "$HITS" ] && fail_with_hits "$LABEL" "$HITS"
-  echo "check-no-emdash: OK (no em dashes in ${LABEL})"
+  echo "check-no-emdash: OK (no em or en dashes in ${LABEL})"
   exit 0
 fi
 
@@ -869,6 +892,6 @@ refuse_if_incomplete
 
 [ -n "$HITS" ] && fail_with_hits "the tracked files listed above" "$HITS"
 
-echo "check-no-emdash: OK (no em dashes in ${scanned} of ${#TRACKED[@]} tracked file(s);" \
+echo "check-no-emdash: OK (no em or en dashes in ${scanned} of ${#TRACKED[@]} tracked file(s);" \
   "${gitlinks} gitlink(s) skipped, ${self_excluded} excluded as the implementation under" \
   "scan, ${declared_excluded} excluded by ${DECLARATION})"

package/claude-card.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Types for `@cosyte/script-utils/claude-card`: the checker for the CLAUDE.md card every Cosyte
+ * repository keeps. The spec is `documentation/claude-card.md` in cosyte/config.
+ */
+
+/** The most lines a card may have, counted as `wc -l` counts them. */
+export declare const CARD_MAX_LINES: 60;
+
+/** The most characters (code points) a line may have, code blocks included. */
+export declare const CARD_MAX_LINE_LENGTH: 100;
+
+/** The most bytes of UTF-8 a card may have. */
+export declare const CARD_MAX_BYTES: 5120;
+
+/** The three sections, in order. */
+export declare const CARD_SECTIONS: readonly ["Gate", "Hazard", "Rules"];
+
+/** The line that imports AGENTS.md into the card. */
+export declare const AGENTS_IMPORT: "@AGENTS.md";
+
+/** A rule id a finding can carry. */
+export type CardRule =
+  | "title"
+  | "intro"
+  | "section-missing"
+  | "section-order"
+  | "section-extra"
+  | "section-empty"
+  | "lines"
+  | "width"
+  | "bytes"
+  | "agents-import";
+
+/** Every rule id, with what it requires. */
+export declare const CARD_RULES: Readonly<Record<CardRule, string>>;
+
+/** One place a card departs from the spec. */
+export interface CardFinding {
+  rule: CardRule;
+  /** 1-based line, or 0 when the finding is about the whole file. */
+  line: number;
+  message: string;
+}
+
+export interface CardContext {
+  /** Whether an AGENTS.md sits beside the card. Left out, the import rule is not checked. */
+  agentsMd?: boolean;
+}
+
+/** Check a CLAUDE.md card against the spec. Returns no findings when it follows it. */
+export declare function checkClaudeCard(text: string, context?: CardContext): CardFinding[];
+
+export interface ClaudeCardGateOptions {
+  /** The repository root holding CLAUDE.md. Default: the working directory. */
+  dir?: string;
+  /** CLI arguments; only `--dir <path>` is accepted. */
+  argv?: string[];
+}
+
+/**
+ * Run the checker over one repository and return the exit code: 0 the card follows the spec, 1 at
+ * least one finding, 2 CLAUDE.md could not be read. It never exits the process.
+ */
+export declare function runClaudeCardGate(options?: ClaudeCardGateOptions): 0 | 1 | 2;