@cosyte/script-utils 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -12,6 +12,33 @@ pre-alpha rule. See
 
 ## [Unreleased]
 
+## [0.1.2] - Unreleased
+
+### Changed
+
+- **`check-no-emdash.sh` refuses the en dash (U+2013) as well as the em dash** (operator decision,
+  2026-11-07). It matches the en dash in the same six forms it already matched for the em dash: the
+  literal character, its URL encoding, its JS escape and three HTML entity spellings. Its self-test
+  now also proves it matches a known en dash and passes a clean line (hyphens, a range written with
+  "to", the minus sign U+2212). Exit codes, modes and the exclusion declaration are unchanged; the
+  messages name both dashes. **A tracked file or a PR text carrying an en dash in any of those forms
+  now refuses where 0.1.1 printed OK**: write a range with "to", and rewrite a pause with a period,
+  a colon, a comma or parentheses.
+
+## [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

@@ -20,7 +20,7 @@ Zero-dependency helpers for the repo-local gate scripts in @cosyte/\* repos.
 
 A gate script that exits 0 without having checked anything is worse than no gate, because the run
 conclusion is the only thing anyone reads. Two ways of producing one turned out to be universal
-across the cosyte repositories: an entrypoint guard written by hand that answers `false` for ordinary
+across the Cosyte repositories: an entrypoint guard written by hand that answers `false` for ordinary
 invocations, and thirteen byte-distinct copies of one PHI scanner, each of which had to be fixed
 separately when an escape was found.
 
@@ -30,7 +30,7 @@ request and a version bump.
 
 ## Status
 
-`@cosyte/script-utils` is on the cosyte 0.1.x line: the public API is settled and bump types follow ordinary semver.
+`@cosyte/script-utils` is on the Cosyte 0.1.x line: the public API is settled and bump types follow ordinary semver.
 
 Still moving: the `runPhiScan` option surface, which is where the per-repo axes below are still being
 argued about, and the cross-cutting detection floor, which gains patterns as escapes are found. A new
@@ -183,8 +183,9 @@ A repository narrows WHAT IS SCANNED, and only that, through a tracked file at i
 `scripts/check-no-emdash.exclude`: one entry per line, `#` comments and blank lines ignored, an entry
 ending in `/` covering every tracked path beneath it, and every entry anchored at the repository
 root. An entry that matches no tracked path is refused rather than ignored, because an exclusion that
-has outlived its subject is a hole nobody is looking at. Nothing narrows WHAT IS MATCHED: the six
-banned forms are fixed in the gate.
+has outlived its subject is a hole nobody is looking at. Nothing narrows WHAT IS MATCHED: the twelve
+banned forms are fixed in the gate. They are the em dash (U+2014) and the en dash (U+2013), each as
+the literal character, its URL encoding, its JS escape and three HTML entity spellings.
 
 ## Overrides
 
@@ -246,7 +247,7 @@ Is this module the file Node was pointed at, rather than one imported by somethi
 
 #### Why not compare the strings
 
-The obvious spelling is a one-liner, and several cosyte repos wrote it by hand:
+The obvious spelling is a one-liner, and several Cosyte repos wrote it by hand:
 
 ```js
 // Do not do this.
@@ -314,7 +315,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 +360,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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);