@cosyte/terminology 0.0.9 → 0.0.10

package/CHANGELOG.md

@@ -9,6 +9,266 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [Unreleased]
 
+### Fixed
+
+- **The PHI scan had NO observation rule at all, so the all-mode sweep reported clean over a scan
+  root it never opened (`PHI-SCAN-OBSERVED-NOTHING-IS-GLOBAL`).** Development tooling only:
+  `scripts/phi-scan.ts` ships in no tarball, and the public surface, build output and runtime
+  behaviour are unchanged. `pnpm phi-scan` with no arguments is what CI runs. It walked two roots,
+  `test/fixtures` and `src`, and refused nothing on the strength of what it had read — not the
+  global "observed zero files in total" rule the siblings carried, but no rule of any kind.
+
+  **The starved state was LIVE here, not hypothetical.** `test/fixtures` has never existed in this
+  repository (`git log -- test/fixtures` is empty; every test is inline TypeScript and
+  `find test -type f -not -name '*.ts'` returns nothing; the throwaway-repo helper in
+  `test/scripts/phi-scan.test.ts` has only ever created `scripts/` and `src/`), so one of the two
+  declared roots was unopened on every run this gate has ever made. **Reproduced on `0fe4b84` on a
+  clone, three ways**, each printing `[phi-scan] OK — no hits` and exiting **0**: `src` moved aside,
+  `src` replaced by a **dangling symlink** — each leaving all 39 source files unread — and the
+  fixture root, which needed no manipulation at all.
+
+  **The dangling case is the sharpest, and nothing else in the scanner can see it.** `existsSync`
+  **follows** the link and answers false, so `walk()` returns before `readdirSync` and the
+  not-a-regular-file refusal never fires: that rule only classifies entries found **inside** a root,
+  and this is the root itself. Absent, dangling and empty are one state to the walk. **This reporter
+  prints no denominator either** — `report` writes `OK — no hits` and no file count — so nothing on
+  stdout looked wrong. Adding a count would be a real improvement and is **not** part of this
+  change.
+
+  **The rule is now per-root.** All-mode refuses (exit **2**) unless **every** declared root yielded
+  at least one file that was actually read, and the refusal names the starved roots. It is written
+  per-root rather than in the global form the siblings started from, so that shape — one surviving
+  file vouching for every other root — cannot arrive along with the second root.
+
+  **`test/fixtures` is no longer declared as a walk root, and its removal is not a narrowing.** If
+  readable, non-ignored content arrives there, all-mode **refuses** (exit 2) and names the
+  declaration rather than reporting clean over content nothing walks. **That refusal fires only
+  where the remedy it prints would help.** It uses the two predicates the walk already has:
+  `rootOf`, so declaring the path silences it by construction, and a content test mirroring the
+  walk's own rules, so an **empty** `test/fixtures`, a **markdown-only** one (the walk skips
+  markdown) and a **gitignored** one are all left alone at exit 0, exactly as before this change. An
+  `existsSync`-only guard refused over all three and kept refusing after the printed remedy was
+  followed — a gate that cannot be satisfied — and it invented a second, stricter gitignore boundary
+  beside the single one this file keeps. **Two exceptions are recorded rather than papered over**,
+  both counting as content because a scan that cannot account for something must not report clean: a
+  path the walk cannot list, where declaring it exits 1; and a path holding only a non-regular
+  entry, where declaring it lands on the not-a-regular-entry refusal at exit 2. Both behave the same
+  before this change, so neither is a regression. The `--staged` predicate is deliberately
+  untouched and still enumerates `test/fixtures/**` and that path's own name, so the pre-commit
+  route is unchanged in both directions.
+
+  **The STARVATION refusal never swallows a finding.** Hits from the roots that DID yield are
+  printed before it, and the exit code is still 2. That is scoped to the starvation branch and no
+  wider: the reappearing-corpus refusal, like the not-a-regular-entry and unmerged refusals beside
+  it, throws out of `buildTargetsForAll` before anything is scanned and so reports nothing found on
+  the way — fail-closed, and unchanged in that respect. With one root declared, starved means an empty target list, so that
+  line is unreachable from this repository's own configuration — it is therefore exercised against a
+  copy of the scanner with a second root declared, rather than shipped as an untested promise, which
+  is exactly how the defect being fixed here survived.
+
+  **Deliberately unchanged:** `--staged` and named-path mode make no per-root promise, because
+  neither enumerates a root. Both boundaries are pinned, and widening the rule to them was run as a
+  mutation rather than argued — dropping the mode guard reds 10 cases; removing the per-root rule
+  reds 4; removing the reappearing-corpus refusal reds 3; removing the print-hits-first line reds 1;
+  emptying `SCAN_ROOTS` reds 14.
+
+  **The granularity is the declared root and nothing finer, which is a real bound, not a slogan.**
+  Four states are still not refused, each measured **with** the rule in place, each now in the
+  scanner's own limits list with the command that produced it and each pinned by a characterization
+  test: a directory missing from **inside** a root (`mv src/ucum ..` still prints `OK — no hits`
+  with 6 sources unread, while a planted violator in it exits 1 with it present); a root that is
+  **itself a symlink** to a directory, which is followed, so the rule is satisfied by whatever is on
+  the other side; the floor is **one** file, whatever the root used to hold; and **any directory the
+  walk cannot list** exits **1** — the code this gate reserves for hits — because `walk()` does not
+  wrap `readdirSync` and the error reaches node's default handler with a v8 stack trace in place of
+  the scanner's own diagnostic. That last one is **not only about roots**: measured as `ENOTDIR` on
+  a root that is a regular file and on a root linking to one, and as `EACCES` on a `chmod 000`
+  directory at depth with the per-root rule otherwise satisfied. **It is CLOSED in the sibling this
+  rule was ported from and OPEN here**, and it is recorded so it is not ported back out as though it
+  were fixed; it belongs to the separate exit-code work.
+
+  **Two more bounds are recorded so none of the above reads as completeness, and both are
+  `PRE-EXISTING`.** The reappearing-corpus refusal sees only what `existsSync` can resolve: silent
+  on a dangling link, which is deliberate because a dangling link holds no corpus, but also silent
+  when a real corpus sits behind a directory that cannot be traversed (`chmod 000 test` with
+  `test/fixtures/leak.txt` present — measured, and identical before this change). And **all-mode
+  walks `src` and nothing else**, so the observation rule can be fully satisfied while every tracked
+  file under `test/` goes unread: measured back to back, `pnpm phi-scan` clean at exit 0 while
+  naming a file under `test/` directly returns hits at exit 1 over the same bytes
+  (`PHI-SCAN-WALK-ROOT-SCOPE`). Widening the walk is separate work with its own two-sided trap,
+  because this floor is SSN/email only.
+
+  Tests were added on throwaway repositories only, so no starved root, no dangling link and no
+  violator is ever written into the committed corpus. **No count of them is recorded here**: one
+  was, it was correct when written, two more cases were added in the same slice, and it was then
+  wrong. Several are red against the superseded scanner — every case asserting one of the new
+  refusals — and one is an explicit **anti-vacuity** control asserting the starved corpus really did
+  hold a detectable hit, because a starvation test over an empty corpus proves exactly nothing,
+  which is the defect itself.
+
+- **The PHI commit-gate's `--staged` route was blind to a staged RENAME or COPY, so an ordinary
+  `git mv` into a scan root printed its clean line and exited 0 at pre-commit**
+  (`PHI-SCAN-RENAME-BLIND-AT-PRECOMMIT`). Development tooling only: `scripts/phi-scan.ts` ships in
+  no tarball, and the public surface, build output and runtime behaviour are unchanged.
+
+  **The hole.** Rename detection is on by git's default, and `git diff --cached --raw
+--diff-filter=AMT` returns neither `R` (rename) nor `C` (copy). So `git mv <tracked link>
+test/fixtures/<name>` staged as `:120000 120000 <sha> <sha> R100` with **two** paths and the
+  status filter deleted the record outright: measured on git 2.39.5 in a throwaway repository, the
+  index held a mode-120000 entry under a scan root and `pnpm phi-scan --staged` reported clean. It
+  was never only a **mode** gap. A rename that also SUBSTITUTES a real-looking value into the moved
+  file passed identically, measured at mode 100644, while naming the same destination
+  directly returned a hit. The gap was at **pre-commit**, where `simple-git-hooks` runs
+  `pnpm phi-scan --staged`; the all-mode sweep is the backstop and saw both.
+
+  **The remedy is `--no-renames`, with no record-stride work.** With detection off git emits no `R`
+  and no `C` at all: the destination arrives as an ordinary single-path `A` and the source as a `D`
+  the filter already drops. **This route's own previous disclosure — that admitting `R`/`C` needed
+  the two-path record shape handled, "which is a scope decision" — was measured FALSE and is
+  withdrawn in place rather than deleted, because it shipped.** Verified under
+  `diff.renames=true|copies|false|1` with `diff.renameLimit=1`: every one yields the same
+  single-path records, so the two-field stride is STRUCTURAL rather than conditional on the caller's
+  configuration. **State the relation exactly, and SCOPE it. Of `--no-renames` alone, holding the
+  rest of the argv fixed: the new enumeration CONTAINS the old one — EQUAL whenever git emitted no
+  `R` and no `C`, larger only when it did.** It is a superset, not a strictly larger set. **That
+  equality is NOT a claim about the route as a whole** — the whole-argv change also adds the
+  unmerged and gitlink records below, so on an index holding an unmerged path the two enumerations
+  differ while git emitted no `R` and no `C` at all. The corollary, because it is easy to misread as "nobody was affected": a
+  caller who had already set `diff.renames=false` was covered before this, and everybody on git's
+  default was not.
+
+  **The `C` half is real and no rename fixture reaches it.** Under `diff.renames=copies`, copying an
+  out-of-scope file carrying the same payload INTO a scan root stages as a genuine `C100` two-path
+  record and was dropped identically: exit 0 before, exit 1 after. One precondition, recorded because
+  it is easy to state too broadly: configuration-only copy detection also needs the copy SOURCE
+  modified in the same staged diff, or git finds no copy source, the record arrives as an ordinary
+  `A` that even the previous argv enumerated, and the fixture proves nothing.
+
+  **Three further enumeration holes in the same route, each measured open here rather than assumed.**
+  An index entry at exactly `test/fixtures` or exactly `src` escaped a prefix test that required the
+  trailing slash (exit 0 over a staged mode-120000 entry at each), so a whole scan root replaced by a
+  link went unjudged — **the one ADDITION to this route's path scope in this change, named as an
+  addition rather than filed under narrowing.** `diff.ignoreSubmodules=all` ERASED a staged gitlink
+  from the enumeration entirely, so a refusal the route already had never fired (exit 2 on the
+  default, exit 0 with that config, same index); closed by `--ignore-submodules=none`, the same
+  remedy family. And an UNMERGED path was returned by neither `AM` nor `AMT`, so a conflicted
+  in-scope path made the route report clean over an index it structurally cannot read; it is now
+  enumerated so it can be REFUSED. **`U` is closed by a DIFFERENT mechanism and the two must not be
+  conflated: by being in `--diff-filter=AMTU`, not by `--no-renames`.** Git itself refuses to commit
+  while a path is unmerged, so that one was never a route to a committed leak; what it was is the
+  gate attesting clean over a state it never observed.
+
+  **One refusal message was false and is corrected, not softened.** It asserted that `git show
+:<path>` "hands back its target path rather than any content", which holds only for mode 120000;
+  on a staged gitlink it fails outright, and the same sentence was emitted for gitlinks and for the
+  mode fallback. It now says what the INDEX holds instead of what `git show` would answer.
+
+  **Twelve cases added**, most of them asserting git's own premise before the scanner's behaviour,
+  because the remedy rests on what git emits. Eight run red against the previous scanner; the other four
+  are the configuration sweep, two flag-coupling premises and an out-of-scope control, green on both
+  by design. **The argv coupling is pinned, and a first draft of this entry had half of it BACKWARDS.**
+  `-M`, `-C` and `--find-copies-harder` each turn detection back on over the top of `--no-renames`
+  and empty the route again; `--find-copies-harder` does so in EITHER order, so nothing here says a
+  later `--no-renames` undoes them. **`-B` IS NOT INERT, AND CALLING IT SO WAS THE PERMISSIVE HALF OF
+  A STANDING DIRECTIVE.** That reading came from a rename stage, the one stage where `-B` does
+  nothing. On a COMPLETE REWRITE `-B` breaks the pairing, the `--diff-filter` letter is `B` and not
+  `M`, `AMTU` drops the record outright, and the gate reports clean over a staged dashed SSN
+  (measured, same index: exit 1 without the flag, exit 0 with it). It empties this route through the
+  status FILTER rather than by re-enabling detection — a different mechanism, the same answer: do not
+  add it. Corrected in place rather than deleted, because an "inert" reading is exactly what gets
+  ported onward, and a case now pins it. That case guards GIT's premise rather than the scanner's argv, so it does not by
+  itself fail if someone adds `-M` to the scanner; the suite as a whole does. **Every flag is
+  counterfactually measured against the final suite of 34:** injecting `-M` reds 2 cases, `-C` reds
+  3, `--find-copies-harder` reds 3 and `-B` reds 1; removing `--ignore-submodules=none` reds 1, and
+  dropping `U` from the filter reds 1. Before the `-B` case was added, injecting `-B` red nothing,
+  which is how the false "inert" claim survived a first pass. Every case builds a
+  throwaway git repository, so no rename, copy, conflict or violator enters the committed corpus.
+  **No case runs `git merge`:** it resolves the COMMITTER IDENTITY up front and exits 128 before
+  merging anything when it cannot find one, which passes on a developer's box and fails on a runner,
+  so the unmerged fixtures are built with `git update-index --index-info` against an index state —
+  what this route actually reads, and `git status` still reports `UU`. The suite was re-run under
+  `env -i` with no discoverable git identity: 34 pass.
+
+  **Measured and deliberately NOT closed here, both PRE-EXISTING and identical before this change.**
+  With a scan root replaced by a link to a regular file the all-mode walk raises an uncaught
+  `ENOTDIR` and exits **1**, a code this contract reserves for HITS, with a stack trace in place of
+  the scanner's own diagnostic; a missing allow-list throws out of the same route the same way. Both
+  are fail-closed rather than silent, and belong to the separate exit-code work. And one property
+  that is newly true rather than unchanged, because such a blob was previously out of scope
+  entirely: a
+  regular blob staged at exactly a scan root is scanned at the SAME tier as one under it, which is
+  true **here** only because `scanTarget` has one tier — the SSN/email floor — and keys on nothing
+  about the path. Implementing the fenced TODO section with a path-keyed dispatch would break that,
+  and a case now says so.
+
+- **Nothing pinned that the publish gate FORWARDS `--no-definitely-typed`, so a gate that accepted
+  the flag and then dropped it would have looked exactly like one that forwards it**
+  (`TERMINOLOGY-ATTW-FORWARDING-UNPINNED`). Development tooling only: `scripts/attw.mjs` ships in no
+  tarball, and the public surface, build output and runtime behaviour are unchanged. No executable
+  line of the gate moved; the only edit to that file is one docblock paragraph.
+
+  **The gap was structural, not one forgotten assertion.** Every case in
+  `test/scripts/attw-gate.test.ts` passes `--no-definitely-typed`, to keep the gate off the network,
+  so the flag rode along on every run and no assertion ever depended on it arriving. The allow-list
+  covered the acceptance half incidentally, since removing the flag from it kills every other case at
+  the argument guard; the forwarding half was covered by nothing at all. The one test whose name said
+  otherwise, `"forwards the two arguments it does accept"`, measured `--profile` alone, and its name
+  is corrected here rather than left overclaiming.
+
+  **`attw` itself cannot settle it, which is why the answer is a shim.** The CLI reports on a packed
+  tarball, never on its own arguments, and on the `--pack` path this gate always takes the flag
+  suppresses a DefinitelyTyped lookup that is never made. Inert means unobservable: accepting the
+  flag and dropping it produces byte-identical output to forwarding it. The pin therefore runs this
+  repo's own `scripts/attw.mjs` against a fixture package whose `node_modules/.bin/attw` prints the
+  argv it was handed. The wrapper resolves its binary beside its own file rather than from the
+  working directory, so the probe needs its own copy of the script, and the suite asserts that copy
+  is byte-identical to the real one instead of trusting it.
+
+  **The negative controls are the load-bearing half, and they are committed rather than merely run.**
+  A test that would pass whether or not the flag is forwarded proves nothing. Given no arguments the
+  shim must see `--pack .` and nothing else, which reds a gate that hard-codes the flag into its own
+  spawn, which a positive assertion alone cannot tell apart. A second control
+  asserts that a refused argument never reaches the shim at all; that one sharpens the existing
+  refusal cases rather than catching anything they miss.
+
+  **Three counterfactuals were run against the real script, over the whole of
+  `test/scripts/attw-gate.test.ts` rather than the new block alone.** Dropping the forwarding reds
+  three cases, the new positive pin among them, and leaves both new controls green. Hard-coding the
+  flag into the spawn and discarding the argv also reds three, but the pairing is what matters: the
+  positive pin stays GREEN while the bare-`--pack .` control reds. That is the precise failure this
+  change exists to make visible.
+  Bypassing the allow-list so the whole argv is forwarded reds eighteen, of which seventeen are
+  refusal cases that were here already; the new refusal control is the eighteenth and adds only "and
+  `attw` never saw it". **So that control sharpens an existing guard rather than being what stops a
+  forward-everything gate from passing**, and it is recorded that way instead of being credited with
+  the catch.
+
+  **Unchanged, and not claimed to be closed: the `.attw.json` route.** `readConfig()` applies a
+  committed config file after argv and sets an option value for every key it carries, so a config
+  file wins regardless of the argument allow-list and no argv-level pin can reach it. This change
+  narrows nothing there, and the gate's docblock keeps stating it as the known limit it is.
+
+## Released, pending a per-version split
+
+> **Everything between this heading and `[0.0.1]` has already SHIPPED.** It accumulated under
+> `[Unreleased]` across the releases from `0.0.2` through `0.0.9`, because this file is maintained by
+> hand and the Changesets changelog generator is off (`"changelog": false` in
+> `.changeset/config.json`), so no release run ever moved an entry out of that section. Reading any
+> of it as work still awaiting a release was wrong, which is why the heading changed and the entries
+> did not.
+>
+> **What is deliberately NOT done here, and is tracked as `TERMINOLOGY-CHANGELOG-GAP`:** splitting
+> this into one `## [x.y.z]` section per published version, and the founder-owned question of whether
+> to turn the generator on across the repos that share this layout. No version from `0.0.2` to
+> `0.0.9` has a section of its own below, and none has a compare link. The `[Unreleased]` link at the
+> foot of this file now spans `v0.0.9...HEAD`, which is what that section actually holds; it spanned
+> `v0.0.1...HEAD` while this block was mislabelled.
+>
+> **`0.0.3` never reached npm, and LEAVING it that way is the deliberate part.** The gap itself was
+> a consequence, not a choice: a leftover changeset meant that release run only opened the next
+> version PR, and the content shipped in `0.0.4`. It is not a hole to be filled, because publishing a
+> `0.0.3` now would place it after `0.0.4` in registry order.
+
 ### Changed
 
 - **Breaking: `ExpansionDiagnostic.system` is replaced by `ExpansionDiagnostic.path`.** The field
@@ -177,7 +437,11 @@ this file is maintained by hand (Changesets handles the version bump and publish
   still **not** enumerated by `--staged` at all, so a staged rename that also appends PHI passes that
   route — pre-existing, unchanged here, and admitting it needs the two-path record shape handled,
   which is a scope decision rather than this one; CI's all-mode sweep does read the resulting
-  worktree file. A tracked file **absent from the worktree** is still caught at `git add` time only.
+  worktree file. **[Superseded — see the `[Unreleased]` entry above. `R`/`C` ARE now enumerated, and
+  the reason given here for deferring them — that it needs the two-path record shape handled, "which
+  is a scope decision" — was MEASURED FALSE: `--no-renames` closes it with no stride work. This
+  sentence is left standing rather than rewritten because it shipped, and because it is the sentence
+  this repo exported to the ecosystem backlog and to sibling repos.]** A tracked file **absent from the worktree** is still caught at `git add` time only.
   And the scanner still has no tolerance for a file that vanishes between enumeration and read, so an
   untracked transient appearing under a walk root can still refuse a whole sweep; that is a different
   defect, it fails closed, and it is not addressed here.
@@ -1058,5 +1322,5 @@ ladder (`0.0.x` until first alpha).
   `WARNING_CODES` entry, and the parse-oriented option/warning types). This package is an engine, not
   a parser; that placeholder surface never shipped.
 
-[Unreleased]: https://github.com/cosyte/terminology/compare/v0.0.1...HEAD
+[Unreleased]: https://github.com/cosyte/terminology/compare/v0.0.9...HEAD
 [0.0.1]: https://github.com/cosyte/terminology/releases/tag/v0.0.1

package/dist/index.cjs

@@ -4776,7 +4776,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.9";
+var VERSION = "0.0.10";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;