@cosyte/script-utils 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -8,6 +8,98 @@ the **`0.0.x`-until-first-alpha** ladder.
 > Because the generator is disabled, **`[Unreleased]` is promoted to a version heading BY HAND**, in
 > the pull request that adds the changeset. Nothing does it automatically.
 
+## [0.0.2] - 2026-08-11
+
+### Added
+
+- **`@cosyte/script-utils/phi-scan`: the shared machinery of the `@cosyte/*` PHI commit-gate, as a
+  parameterised engine.** `scripts/parser-template/` is a SCAFFOLD rather than a dependency, so
+  `scripts/phi-scan.ts` was COPIED into every parser repo. **Thirteen repos, thirteen byte-distinct
+  copies**, so a newly-found escape cost one pull request and one adversarial review PER REPO, and
+  three escape classes had already been paid for that way. `runPhiScan(config)` owns argument
+  parsing, the allow-list and override log, target enumeration on all three routes, the union of the
+  working-tree walk with the bytes git carries, content deduplication under git's own
+  `blob <len>\0` framing, the completeness rule, every refusal, and the cross-cutting SSN/email
+  floor.
+
+  **THE FIVE PER-REPO AXES ARE PARAMETERS, NOT FORKS**, and which ones are required is itself the
+  design. `exitCodes`, `scanRoots` and `isStagedReadable` are **REQUIRED**: the siblings genuinely
+  disagree on all three, and a default would be the porting mistake the gate exists to catch (at
+  least one sibling uses 2 where another uses 1). `excludedPaths`, `isWalkReadable` (the Markdown
+  read exemption) and `regularBlobModes` are **DEFAULTED**, so moving one of those boundaries is a
+  change to this package plus a version bump rather than an edit in thirteen repos. EOL
+  normalization has **no parameter at all** and stays machinery: the walk/index deduplication is by
+  CONTENT, so where a `text` attribute or `core.autocrlf` makes the index carry LF and the working
+  tree CRLF, BOTH forms are scanned.
+
+  **Per-standard field detection stays with the caller**, through `detect`. It is handed the
+  reported LOCUS rather than the target path, so a hit found in the bytes git carries cannot be
+  reported against a working-tree copy a developer would open and find clean. That used to be a
+  sentence in a comment; it is now the only path a caller can reach.
+
+- **A scan root may name a regular FILE, and the kind is DERIVED from the filesystem rather than
+  declared**, which is what keeps the parameter a plain `string[]`. Measured against the thirteen
+  live copies: they declare roots in at least six different shapes, and one declares
+  `{ rel, shape: "directory" | "file" }` with a single file among them. An earlier draft fed every
+  root to `readdirSync`, so such a root threw `ENOTDIR`, uncaught, and the run took node's exit 1,
+  the code this contract reserves for HITS FOUND. **What deriving gives up is stated rather than
+  left to be found**: a declaration can notice a root is not the KIND it was meant to be and
+  derivation cannot. A root that is neither a file nor a directory is still refused, a root naming a
+  symbolic link is refused rather than followed, and a MISSING root is skipped, which is unchanged
+  from the copied scanners and is named as the one remaining silently-empty root state.
+- **A scan root of `"."` means the whole repository**, with gitignored directories pruned during
+  descent and `.git` skipped by literal name, which is what makes a whole-repository root usable at
+  all rather than a walk through `node_modules`. Pruning is equivalent to filtering afterwards
+  because **`git check-ignore` is index-aware at directory granularity**, measured both ways on git
+  2.39.5: with nothing tracked underneath, a gitignored directory is reported ignored and pruned;
+  with one file force-added underneath it is reported NOT ignored, so the walk descends and still
+  reads it. An earlier draft justified this with the gitignore-pattern rule that a path under an
+  excluded directory cannot be re-included, which does not settle it, because the filter being
+  replaced asked `check-ignore` too.
+
+### Changed
+
+- **Two containments the first draft ASSERTED are now ENFORCED**, both falsified by this slice's
+  adversarial review and both reproduced against the pre-consolidation scanner too, so neither is a
+  regression this package introduced. What was introduced was the sentence claiming they held, on the
+  API contract thirteen migrations are about to be written against.
+  - **A staged path `isStagedReadable` admits that no scan root covers is REFUSED.** The type said
+    the `--staged` filter was "narrower than the root half by construction"; nothing constructed it,
+    because they are two independent keys. Measured with roots at `["src"]` and the filter at the
+    shared Markdown exemption: a STAGED mode-120000 entry under `test/fixtures/` was outside every
+    scan root, so the non-regular refusal never saw it, and the route enumerated it, READ it, handed
+    the link's TARGET PATH to the detector as if it were content, counted the scan complete and
+    printed `OK: no hits` at exit 0. Narrowing silently to the intersection would have been the wrong
+    repair: it hides a misconfiguration in the one place the gate blocks a commit.
+  - **A scan root is normalised the way every other path is, and one resolving outside the repository
+    is refused.** `"./src"` is a spelling the type documents as valid; it walked correctly while
+    `isUnderScanRoot` compared it against the normalized index path and never matched, emptying the
+    union, the index non-blob refusal and the unmerged refusal in silence. Measured: `["src"]`
+    refused a tracked mode-120000 entry at exit 2 while `["./src"]` reported clean at exit 0 over the
+    same repository.
+- **The optional axes are shape-checked.** `excludedPaths: ["a"]`, a plausible reading of
+  "repo-relative paths", used to survive normalization, reach `.has(...)` inside enumeration, and
+  take node's exit 1 from there, which the exit contract reserves for HITS FOUND.
+- **The floor's dashed-SSN branch now consults `allow.ids`, in either rendering.** This is a
+  correction rather than a port: with the whole-file `--allow-fixture` bypass closed, a detector
+  that consults nothing leaves a developer with a hit and **no remedy at all**, and a sibling
+  shipped a footer claiming the token allow-list was the only remedy that reaches a clean run while
+  that was false for exactly this branch. One `ID` entry now covers both the dashed and the undashed
+  rendering, so a repo does not have to guess which one a fixture uses.
+- **A fatal partway through the sweep prints the hits already found BEFORE the refusal**, instead of
+  discarding them. Measured on a mutant that throws after the reads: the old ordering produced a
+  refusal with **zero** `HIT:` lines over a corpus containing a real hit. The refusal still wins the
+  exit code and the clean line is still unreachable from there, so nothing is reported as accounted
+  for that is not.
+- **The hit footer is scoped to what the engine can know.** It says the cross-cutting floor consults
+  the allow-list and that a repo's own detectors are answerable that way **only if** they consult
+  it. The engine cannot see inside a caller's `detect`, so a wider claim would be one it has no
+  evidence for.
+- **A detector that throws REFUSES the scan** rather than escaping to node's own exit code, which
+  this contract reserves for HITS FOUND. A misconfigured scanner throws a `TypeError` rather than
+  returning a code: at the point a required axis is missing, `exitCodes` is itself the thing that
+  was not supplied, so there is no trustworthy code to return.
+
 ## [0.0.1] - 2026-08-05
 
 ### Added

package/README.md

@@ -81,6 +81,77 @@ exits 0, which is silent. Those are not symmetric, so the tie goes to running.
 It throws a `TypeError` rather than returning `false` when handed something that is not a non-empty
 string, for the same reason.
 
+## `runPhiScan(config)`
+
+`@cosyte/script-utils/phi-scan` is the shared machinery of the `@cosyte/*` PHI commit-gate.
+
+```ts
+import { exemptsMarkdown, runPhiScan } from "@cosyte/script-utils/phi-scan";
+
+process.exit(
+  runPhiScan({
+    exitCodes: { clean: 0, hits: 1, refuse: 2 },
+    scanRoots: ["."],
+    isStagedReadable: exemptsMarkdown,
+    detect: (ctx) => {
+      // Your standard's field-level detection. Check every PHI-bearing field
+      // against ctx.allow, and raise findings with ctx.hit(...).
+    },
+  }),
+);
+```
+
+It returns an exit code rather than calling `process.exit`, so a test can drive it in process.
+
+### Why it is a dependency and not a template file
+
+`scripts/parser-template/` is a **scaffold**, not a dependency: the scaffolder copies it, so fixing
+the template fixes no existing repo. That produced thirteen byte-distinct copies of one scanner, and
+a newly-found escape therefore cost one pull request and one adversarial review **per repo**. Three
+escape classes were paid for that way before this package existed. Here it is one pull request and a
+version bump.
+
+### What it owns
+
+Argument parsing and the three modes (`--staged`, explicit paths, and the `all`-mode sweep); the
+allow-list and the override log; target enumeration; the union of the working-tree walk with the
+bytes git carries, deduplicated **by content** under git's own `blob <len>\0` framing; the
+completeness rule (a target the run enumerated and never read refuses, naming the paths); every
+refusal; and a cross-cutting floor that detects a dashed SSN shape and an email at an undeclared
+domain.
+
+It does **not** own per-standard field detection: names, DOB, MRN / member id, address, phone.
+Those differ per healthcare standard and are supplied through `detect`.
+
+### The five per-repo axes
+
+Which ones are required is the design, not an oversight.
+
+| Axis                | Option                            | Required?                                                       |
+| ------------------- | --------------------------------- | --------------------------------------------------------------- |
+| 1 Exit codes        | `exitCodes`                       | **Required.** The siblings disagree; a default would be a port. |
+| 2 Roots             | `scanRoots`                       | **Required.** `["."]` is the whole repository.                  |
+| 2 Roots (subtract)  | `excludedPaths`, `isWalkReadable` | Defaulted. Moving the shared boundary is one change here.       |
+| 3 `--staged` scope  | `isStagedReadable`                | **Required.** It decides what a commit is blocked on.           |
+| 4 Gitlinks          | `regularBlobModes`                | Defaulted to git's two regular-blob modes.                      |
+| 5 EOL normalization | none                              | Machinery. A port must check it, not set it.                    |
+
+A required axis has no default **because** it is the thing a port gets wrong: carrying an exit code
+across a repo boundary is how a caller ends up branching on a meaning that repo never assigned.
+A defaulted axis is the opposite case: every repo wants the same answer, so the answer lives here
+and reaches all of them through a version bump.
+
+### Two things worth knowing before you adopt
+
+**A detector that consults nothing has no remedy.** The whole-file `--allow-fixture` bypass is
+recorded and then refused, so it cannot reach a clean run. Check every PHI-bearing field against
+`ctx.allow`, or a developer meeting your detector has nowhere to go. The engine's own floor does
+this on both branches.
+
+**`all` mode needs a git index.** It refuses when git cannot name the index or names it empty,
+because without it the sweep is the working-tree walk's word alone. A freshly scaffolded repo has to
+`git init` and commit before an `all`-mode run means anything.
+
 ## License
 
 MIT

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",
     "entrypoint",
     "import-meta",
+    "phi",
     "scripts",
     "cosyte"
   ],
@@ -24,11 +25,17 @@
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
+    },
+    "./phi-scan": {
+      "types": "./phi-scan.d.ts",
+      "default": "./phi-scan.js"
     }
   },
   "files": [
     "index.js",
     "index.d.ts",
+    "phi-scan.js",
+    "phi-scan.d.ts",
     "README.md",
     "CHANGELOG.md"
   ],

package/phi-scan.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Types for `@cosyte/script-utils/phi-scan`: the shared machinery of the `@cosyte/*` PHI
+ * commit-gate.
+ *
+ * The engine owns enumeration, the union of the working-tree walk with the bytes git carries,
+ * content deduplication, the completeness rule, the refusals and the cross-cutting SSN/email floor.
+ * The caller owns the five per-repo axes below and the per-standard field detectors.
+ */
+
+/** A reported PHI finding. `path` is the LOCUS the engine chose, never a path the caller invents. */
+export interface Hit {
+  /** The reported locus: the target's repo-relative path, plus an origin label when it has one. */
+  path: string;
+  /** A locator inside the target: `(ssn)`, `(email)`, or a field id from a per-standard detector. */
+  segment: string;
+  /** The offending value, as found. */
+  value: string;
+  /** Why it was raised, in a few words. */
+  reason: string;
+}
+
+/** The positive declaration that specific identifiers are synthetic. */
+export interface AllowList {
+  /** Uppercase synthetic person-name tokens. Consumed by a caller's structured name detector. */
+  names: Set<string>;
+  /** Synthetic dates of birth, in whatever form the caller's detector normalises to. */
+  dobs: Set<string>;
+  /** Synthetic id values (SSN / MRN / member-id shapes), uppercased. Also read by the SSN floor. */
+  ids: Set<string>;
+  /** Allowed email domains, lowercased. Anything else is a hit. Read by the email floor. */
+  emailDomains: Set<string>;
+}
+
+/** A stage-0 index entry: the mode git records, and the object it points at. */
+export interface IndexEntry {
+  mode: string;
+  oid: string;
+}
+
+/** One thing the scan will read, and where its bytes come from. */
+export interface Target {
+  /** Repo-relative, forward-slashed. Every filter, exclusion and completeness tier keys on this. */
+  path: string;
+  read: () => Buffer;
+  /**
+   * Where these bytes came from, when it is not simply the file at `path`. Set only by the index
+   * union, and it decorates the REPORTED LOCUS ONLY.
+   */
+  origin?: string;
+}
+
+/** An entry the enumeration reached and cannot scan. Both fields are safe to print. */
+export interface Unscannable {
+  path: string;
+  /** A token from the engine's own closed set. Never text off the other side of a link. */
+  kind: string;
+}
+
+/** What a per-standard field detector is handed for one target. */
+export interface DetectContext {
+  /**
+   * The reported LOCUS, already carrying any origin label. Raise hits against this and nothing else:
+   * a hit naming a bare path whose working-tree copy is clean sends a developer to the wrong file.
+   */
+  path: string;
+  /** The target's bytes decoded as UTF-8. */
+  text: string;
+  /** The target's bytes, for a byte-strict format. */
+  bytes: Buffer;
+  /** The parsed allow-list, so a detector can honour a positive synthetic declaration. */
+  allow: AllowList;
+  /** Raise a hit. The locus is filled in by the engine. */
+  hit: (h: Omit<Hit, "path">) => void;
+}
+
+/**
+ * A per-standard field detector. Throwing REFUSES the scan rather than taking node's exit code.
+ *
+ * 🛑 THE THROWN MESSAGE IS PRINTED VERBATIM, so it reaches CI logs. Name the position, never the
+ * content: a parser that interpolates the record it choked on turns a diagnostic into a PHI
+ * surface. This is the one place the engine prints text it cannot vouch for, and it is disclosed
+ * rather than suppressed, because a refusal nobody can diagnose is its own defect.
+ */
+export type DetectFn = (ctx: DetectContext) => void;
+
+/** The three codes this repo's own exit contract assigns. All three must differ. */
+export interface PhiScanExitCodes {
+  /** The scan ran, read every target it enumerated, and found nothing. */
+  clean: number;
+  /** This corpus contains something that looks like PHI. */
+  hits: number;
+  /** Every state the engine RAISES in which the scan cannot account for something. */
+  refuse: number;
+}
+
+export interface PhiScanConfig {
+  /**
+   * AXIS 1, REQUIRED. There is deliberately no default: the sibling `@cosyte/*` scanners do not
+   * agree on these numbers, and a caller that branches on the code (CI does) must read this repo's
+   * own contract rather than an inherited one.
+   */
+  exitCodes: PhiScanExitCodes;
+
+  /**
+   * AXIS 2, REQUIRED: the roots `all` mode walks. `["."]` means the whole repository, which is the
+   * only honest setting for a repo that has not yet decided what its corpus is. A ROOT IS A SCOPE
+   * DECISION AND IT IS THE AXIS MOST LIKELY TO BE WRONG IN A PORT: measure what a narrowing stops
+   * reading, rather than assuming it stops reading nothing.
+   *
+   * Each entry is normalised the way every other path is, so `src`, `./src`, `src/` and an absolute
+   * path to it are one root. That normalization is a fix rather than a convenience: `["./src"]`
+   * used to walk correctly while matching no index path, which emptied the union, the index
+   * non-blob refusal and the unmerged refusal in silence. A root resolving OUTSIDE the repository
+   * is refused for the same reason.
+   *
+   * A ROOT MAY NAME A REGULAR FILE, AND THE KIND IS DERIVED FROM THE FILESYSTEM RATHER THAN
+   * DECLARED. This parameter is a plain `string[]` on purpose. One sibling declares its roots as
+   * `{ rel, shape: "directory" | "file" }` and lists a single file among them, and that shape is
+   * expressible here without the richer type: such a root is scanned as one target. It is a
+   * measured decision rather than a preference, because an earlier draft fed every root to
+   * `readdirSync` and a file root threw `ENOTDIR`, uncaught, taking node's exit 1, the code this
+   * contract reserves for HITS FOUND.
+   *
+   * WHAT DERIVING GIVES UP: a declaration can notice that a root is not the KIND it was meant to be
+   * and derivation cannot, so a root that changes kind is silently treated as what it now is. A root
+   * that is NEITHER a file nor a directory is still refused, and a root naming a symbolic link is
+   * refused rather than followed. A MISSING root is skipped, which is unchanged from the copied
+   * scanners. It is not the last state in which a root contributes nothing without saying so, and
+   * two others are known: a file root the read filter drops (a `.md` file root reads nothing under
+   * the default `isWalkReadable`, so porting one means overriding that filter too), and an
+   * UNREADABLE root, which is reported the same way a missing one is.
+   */
+  scanRoots: readonly string[];
+
+  /**
+   * AXIS 3, REQUIRED: the READ half of scope for `--staged`. Widening it changes what a COMMIT is
+   * blocked on, which is a hook decision each repo takes for itself.
+   *
+   * IT MUST STAY INSIDE `scanRoots`, AND THE ENGINE ENFORCES THAT RATHER THAN ASSUMING IT. This
+   * doc used to say "narrower than the root half by construction", and nothing constructed it:
+   * these are two independent keys. A reviewer measured the gap with roots at `["src"]` and this
+   * filter at `exemptsMarkdown`: a STAGED symbolic link under `test/fixtures/` was outside every
+   * scan root, so the non-regular refusal never saw it, and the route read the link's TARGET PATH
+   * as if it were content and reported clean at exit 0. A staged path this admits and no scan root
+   * covers is now REFUSED, naming the path.
+   */
+  isStagedReadable: (relPath: string) => boolean;
+
+  /**
+   * AXIS 2, the subtractive half. Repo-relative paths NO route reads: not the walk, not the index
+   * union, not `--staged`.
+   *
+   * EXCLUDE A LITERAL PATH, NEVER A CLASS. A "skip binary blobs" predicate was measured to drop two
+   * of a sibling's hand-written sources, which embed NUL bytes as HMAC domain separators. A literal
+   * path is reviewable in a diff; a class quietly grows new members. Each entry is a file the scan
+   * has NO verdict about, so each one wants a comment saying why.
+   *
+   * @default new Set()
+   */
+  excludedPaths?: ReadonlySet<string>;
+
+  /**
+   * AXIS 2, the READ half of scope for the two SWEEPING routes. Defaults to the shared Markdown
+   * exemption, and the default is the point: moving that boundary is then one change here rather
+   * than one edit per repo.
+   *
+   * @default exemptsMarkdown
+   */
+  isWalkReadable?: (relPath: string) => boolean;
+
+  /**
+   * AXIS 4: git's modes for a regular blob. Every other mode names something with no bytes to read
+   * at that path, and is refused rather than skipped.
+   *
+   * @default new Set(["100644", "100755"])
+   */
+  regularBlobModes?: ReadonlySet<string>;
+
+  /** @default process.cwd() */
+  repoRoot?: string;
+
+  /** @default process.argv.slice(2) */
+  argv?: string[];
+
+  /** @default <repoRoot>/scripts/phi-allow-list.txt */
+  allowListPath?: string;
+
+  /** @default <repoRoot>/phi-scan-overrides.md */
+  overrideLogPath?: string;
+
+  /**
+   * The per-standard, field-level detection this engine deliberately does not own: names, DOB,
+   * MRN / member id, address, phone. Parse the wire format properly rather than bolting a blind text
+   * regex onto it; coded values produce false confidence.
+   */
+  detect?: DetectFn;
+}
+
+/**
+ * Run the PHI scan and return an exit code drawn from `config.exitCodes`. Nothing here calls
+ * `process.exit`, so a test can drive the engine in-process.
+ *
+ * @throws {TypeError} When a required axis is missing or malformed. That is a misconfigured scanner
+ *   rather than a scan result, it lands on the author's first run, and it must not be reportable as
+ *   a clean pass.
+ * @example
+ *   process.exit(
+ *     runPhiScan({
+ *       exitCodes: { clean: 0, hits: 1, refuse: 2 },
+ *       scanRoots: ["."],
+ *       isStagedReadable: (p) => p.startsWith("test/fixtures/"),
+ *     }),
+ *   );
+ */
+export declare function runPhiScan(config: PhiScanConfig): number;
+
+/**
+ * The shared Markdown read-exemption, and the default value of `isWalkReadable`.
+ *
+ * Markdown is documentation rather than fixture data and may legitimately describe a violator value.
+ * The consequence, stated because it is route-dependent rather than file-dependent: a tracked `.md`
+ * is read by NEITHER sweeping route, while a `.md` named explicitly on argv IS scanned.
+ */
+export declare function exemptsMarkdown(relPath: string): boolean;