@cosyte/script-utils 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -12,6 +12,20 @@ pre-alpha rule. See
 
 ## [Unreleased]
 
+## [0.1.1] - Unreleased
+
+### Fixed
+
+- **`phi-scan`: the per-root observation rule is answered from the WALK's reads only.** It was
+  answered from every read the run took, including the index-union reads of the bytes git carries,
+  so a scan root that was missing or empty on disk was credited whenever git tracked a file under
+  it. In a real repository every root holds tracked files, so the rule never fired for the state it
+  exists to catch. Measured before the change: two repositories with `src` emptied on disk, differing
+  only in whether `src/index.ts` was tracked, exited at the refuse code and at the clean code with
+  `OK: no hits`. **Such a root now refuses at the `refuse` code, naming it.** Those tracked files are
+  still read from the bytes git carries and a hit in them is printed before the refusal; the
+  completeness rule still counts every read, and a root the walk reads is not refused.
+
 ## [0.1.0] - Unreleased
 
 ### Changed

package/README.md

@@ -314,7 +314,7 @@ paths, and the `all`-mode sweep); reading the allow-list and the override log; t
 the union of the working-tree walk with the bytes git carries at every index path, 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); the per-root observation rule (`all` mode refuses unless
-every `scanRoots` entry yielded a file that was read, naming the starved roots); every refusal; and a
+every `scanRoots` entry yielded a file the WALK read, naming the starved roots); every refusal; and a
 cross-cutting detection floor that finds a dashed SSN shape and an email at an undeclared domain over
 every file, always.
 
@@ -359,12 +359,13 @@ because without it the sweep is the working-tree walk's word alone. A freshly sc
 `git init` and commit before an `all`-mode run means anything.
 
 **Every scan root has to produce something.** `all` mode refuses when a `scanRoots` entry yielded no
-file that was read, and names it. A root that is missing, unreadable, or whose every file your read
-filter drops used to leave the sweep quietly narrower than its own configuration said, and one
-productive root made the whole run look productive. If you narrow `scanRoots`, this is the tier that
-tells you what the narrowing stopped reading. A root naming a regular file is scanned as one target;
-one naming a symbolic link is refused rather than followed; one naming a directory that cannot be
-listed is refused, naming the path.
+file the walk read, and names it, even when git tracks files under it: those are still read from the
+index, but what git carries cannot vouch for a directory on disk. A root that is missing, unreadable,
+or whose every file your read filter drops used to leave the sweep quietly narrower than its own
+configuration said, and one productive root made the whole run look productive. If you narrow
+`scanRoots`, this is the tier that tells you what the narrowing stopped reading. A root naming a
+regular file is scanned as one target; one naming a symbolic link is refused rather than followed;
+one naming a directory that cannot be listed is refused, naming the path.
 
 **`scanRoots` bounds the WALK, not the index.** `all` mode reads the bytes git carries at every
 tracked path, whatever your roots say, because a root list answers what is on disk under it and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",

package/phi-scan.d.ts

@@ -159,13 +159,18 @@ export interface PhiScanConfig {
    * 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 THAT WAS ACTUALLY 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
+   * 🛑 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[];
 

package/phi-scan.js

@@ -1287,14 +1287,16 @@ class PhiScan {
   }
 
   /**
-   * Did this root yield at least one file whose bytes were ACTUALLY READ?
+   * Did this root yield at least one file the WALK actually read?
    *
-   * IT IS ASKED OF `read`, WHICH IS EVIDENCE OF OBSERVATION RATHER THAN A PLAN TO OBSERVE, and it
-   * is asked per root rather than of the union, because the union is exactly what hides a starved
-   * root: one productive root makes the whole sweep look productive.
+   * IT IS ASKED OF THE WALK'S READS, WHICH ARE EVIDENCE OF OBSERVATION RATHER THAN A PLAN TO
+   * OBSERVE, and never of the index union's: the union reads the bytes git carries at a tracked
+   * path, and that cannot vouch for a directory on disk. It is asked per root rather than of the
+   * whole sweep, because the whole sweep is exactly what hides a starved root: one productive root
+   * makes the whole sweep look productive.
    *
    * @param {string} root A normalised scan root.
-   * @param {Set<string>} read The repo-relative paths this run opened.
+   * @param {Set<string>} read The repo-relative paths the walk opened.
    * @returns {boolean}
    */
   anyReadUnder(root, read) {
@@ -1751,6 +1753,11 @@ class PhiScan {
 
     const walkFailure = sweep(targets);
     if (walkFailure !== null) return walkFailure;
+    // WHAT THE WALK READ, FROZEN BEFORE THE UNION ADDS TO `read`. The per-root observation rule is
+    // answered from this and nothing else: the union reads what git carries at a tracked path, which
+    // is not evidence that anything under a root exists on disk. `read` itself keeps both halves,
+    // because the completeness rule needs every read the run took.
+    const walkRead = new Set(read);
 
     // THE INDEX ROUTE'S OWN REFUSALS, RAISED HERE RATHER THAN WHERE THEY ARE COMPUTED (AC-15). An
     // unmerged entry or a tracked link anywhere in the index refuses the whole sweep, and the walk
@@ -1799,9 +1806,10 @@ class PhiScan {
     // target was read; it cannot ask whether a root produced a target in the first place, and a
     // root that produces none is the silently-narrowed sweep: a typo, a directory that moved, a
     // root whose every file the read filter drops. One productive root makes the whole run look
-    // productive, so the question is asked per root and answered from `read`.
+    // productive, so the question is asked per root and answered from `walkRead`: a root git
+    // tracks files under and that holds nothing on disk is starved, whatever the union read there.
     const starved =
-      index === null ? [] : this.cfg.scanRoots.filter((root) => !this.anyReadUnder(root, read));
+      index === null ? [] : this.cfg.scanRoots.filter((root) => !this.anyReadUnder(root, walkRead));
 
     // Hits FIRST, so nothing below can swallow one.
     this.reportHits(hits);