@cosyte/script-utils 0.0.2 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",
@@ -29,6 +29,14 @@
     "./phi-scan": {
       "types": "./phi-scan.d.ts",
       "default": "./phi-scan.js"
+    },
+    "./internal-refs": {
+      "types": "./internal-refs.d.ts",
+      "default": "./internal-refs.js"
+    },
+    "./attw": {
+      "types": "./attw.d.ts",
+      "default": "./attw.js"
     }
   },
   "files": [
@@ -36,6 +44,11 @@
     "index.d.ts",
     "phi-scan.js",
     "phi-scan.d.ts",
+    "internal-refs.js",
+    "internal-refs.d.ts",
+    "attw.js",
+    "attw.d.ts",
+    "check-no-emdash.sh",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -44,5 +57,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "4.1.4"
+  },
+  "scripts": {
+    "build": "node ../../scripts/pack-emdash-gate.mjs",
+    "test": "vitest run"
   }
 }

package/phi-scan.d.ts

@@ -7,15 +7,28 @@
  * 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. */
+/**
+ * A reported PHI finding: a POSITION and a RULE, never the token that matched. `path` is the LOCUS
+ * the engine chose, never a path the caller invents.
+ *
+ * 🛑 THE MATCHED VALUE IS NOT PART OF A FINDING. The report goes to stderr, stderr is a CI log, and
+ * a diagnostic about a PHI leak that quotes the leak is a second copy of it somewhere worse
+ * (`phi-safety` P4). A detector may pass `value`; the engine drops it at the boundary rather than
+ * storing it, so no reporting path downstream can print what no record carries.
+ */
 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. */
+  /**
+   * The offending value, as a detector found it. ACCEPTED AND DISCARDED: the engine neither stores
+   * nor prints it, and a hit the engine reports never carries one. It stays in the surface so a
+   * detector that has the token in hand can keep saying so at its own call site without the engine
+   * becoming the place that publishes it.
+   */
+  value?: string;
+  /** Why it was raised, in a few words. This is what the report prints beside the locator. */
   reason: string;
 }
 
@@ -45,6 +58,10 @@ export interface Target {
   /**
    * 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.
+   *
+   * TWO VALUES, BECAUSE THE REMEDY DIFFERS. `git index` is a path whose working-tree copy this run
+   * did not read at all; `git index; the working tree differs` is one whose disk copy WAS read and
+   * carries other bytes, so the file a developer opens is clean and re-staging is part of the fix.
    */
   origin?: string;
 }
@@ -85,7 +102,14 @@ 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. */
+  /**
+   * The scan ran, read every target it enumerated, and found nothing. The ONE subtraction is the
+   * enumeration TOCTOU window: an UNTRACKED file the walk listed, in `all` mode, that was gone by
+   * read time and is still gone at the end of the run, is reported SKIPPED. Git carries no bytes
+   * at such a path, so nothing this repository holds went unread. WHEN THAT HAPPENS THE CLEAN LINE
+   * ITSELF SAYS SO on stdout, counting the skipped files, so the subtraction is visible to a reader
+   * who never sees stderr; with nothing skipped the line is byte-identical to what it always was.
+   */
   clean: number;
   /** This corpus contains something that looks like PHI. */
   hits: number;
@@ -122,13 +146,31 @@ export interface PhiScanConfig {
    * 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.
+   * and derivation cannot, so a root that changes kind is silently treated as what it now is. That
+   * is a recorded narrowing rather than an oversight, with its compensating control named:
+   * `documentation/decisions/0003-the-phi-scan-engine-gap-settlements.md`, N2. Every TRACKED file
+   * that lived under such a root is still read, because the index half of `all` mode is not narrowed
+   * by this parameter at all.
+   *
+   * ALL THREE KINDS HAVE ONE SETTLED OUTCOME. A REGULAR FILE is scanned as one target. A SYMBOLIC
+   * LINK is refused rather than followed, and so is anything that is neither a file nor a directory.
+   * A DIRECTORY THAT CANNOT BE ENUMERATED is refused at the caller's `refuse` code, naming the path
+   * and the errno; it used to escape `readdirSync` uncaught and take node's own exit 1, the code
+   * this contract reserves for HITS FOUND. A MISSING root is skipped by the WALK, which is unchanged
+   * from the copied scanners, and is then caught by the rule below.
+   *
+   * 🛑 EVERY ROOT MUST YIELD AT LEAST ONE FILE THE WALK READ, OR `all` MODE REFUSES AND NAMES THE
+   * STARVED ROOTS. That is what closes the class the paragraph above used to end with: a root that
+   * contributes nothing WITHOUT SAYING SO. All three of the known members are in it - a missing
+   * root, an UNREADABLE root (reported the same way a missing one is), and a root whose every file
+   * the read filter drops, which is what a `.md` file root does under the default
+   * `isWalkReadable`. A root is a scope decision, and a scope decision that silently selected
+   * nothing is the sweep reporting on a corpus it never had.
+   *
+   * THE INDEX HALF NEVER CREDITS A ROOT. A root that is missing or empty on disk is starved even
+   * when git tracks files under it: those files are still read from the bytes git carries, and any
+   * hit in them is reported before the refusal, but what git carries cannot vouch for a directory
+   * on disk.
    */
   scanRoots: readonly string[];
 
@@ -143,6 +185,16 @@ export interface PhiScanConfig {
    * 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.
+   *
+   * 🛑 THIS PREDICATE ALSO DECIDES WHAT THE `--staged` ROUTE REFUSES, which is a change. Its
+   * non-regular and unmerged refusals used to key on the ROOT half of scope, so a caller whose
+   * staged scope is narrower than its roots had commits blocked that its own gate had always let
+   * through. What a commit is blocked on is this key's job. THE COST: a staged non-regular entry
+   * this predicate declines is no longer refused HERE. `all` mode still refuses it twice over (the
+   * walk classifies it under a scan root, and the index route refuses the tracked record wherever it
+   * sits), so a repository's own sweep still does. Recorded as N1 in
+   * `documentation/decisions/0003-the-phi-scan-engine-gap-settlements.md`; widen this predicate if
+   * you want the wider refusal.
    */
   isStagedReadable: (relPath: string) => boolean;