docs(observability-map): split the README and cut its history

1stvamp · 1stvamp · commit be72dd5d9239 · 2026-08-03T15:22:46.000+01:00
The README carried four jobs at once after the inline commentary moved into
it: what the tool measures, how to read the report, how the scanner decides,
and a running account of what earlier rounds got wrong. Split it. README.md
keeps the reader-facing job (running it, CI, what the score means, the five
checks, headline figures, not-applicable, suppression, known limits, layout);
INTERNALS.md takes the scanner reasoning, the mutation harness, the reporting
arithmetic and the CI wiring, for someone changing the tool.

Cut the history throughout. What a fix changed and why the old shape was
broken is in the commits and the ledger; a rejected alternative is kept only
where someone would otherwise re-propose it, and then in one line. Every
inline 'README, &lt;section&gt;' pointer is repointed and every one resolves to a
heading that exists.

964 lines becomes 336 + 494. The real-tree report is byte-identical.
diff --git a/internal-packages/observability-map/INTERNALS.md b/internal-packages/observability-map/INTERNALS.md
diff --git a/internal-packages/observability-map/README.md b/internal-packages/observability-map/README.md
diff --git a/internal-packages/observability-map/src/checks/authBoundary.ts b/internal-packages/observability-map/src/checks/authBoundary.ts
@@ -11,8 +11,9 @@ const ID = "auth-boundary";
  * A guard the route only imports and never calls does not count, and neither does one the OTHER
  * export calls.
  *
- * Names rather than the three patterns it replaces, all of which over-matched: README, "Sensitivity,
- * and the names the tool matches on". `webappSymbols.test.ts` fails if a name stops resolving, but
+ * Names rather than the three patterns it replaces, all of which over-matched: INTERNALS.md,
+ * "Sensitivity, and the names the tool matches on". `webappSymbols.test.ts` fails if a name stops
+ * resolving, but
  * cannot check that a declaration with the right name is the guard we meant, which is the residual
  * the two local helpers below carry.
  */
diff --git a/internal-packages/observability-map/src/checks/authScope.ts b/internal-packages/observability-map/src/checks/authScope.ts
@@ -28,8 +28,8 @@ function builderExports(ep: EntryPoint): BuilderExport[] {
 
 /**
  * Whether a route the builder authenticated is also narrowed to the caller. The IDOR class it
- * measures, the two ways to be scoped, and why `ability.can(...)` is deliberately not a third:
- * README, "Authenticated is not the same as scoped".
+ * measures: README, "The five checks". The two ways to be scoped, and why `ability.can(...)` is
+ * deliberately not a third: INTERNALS.md, "What auth-scope reads as scoping".
  *
  * There is no triviality test here because `isTrivial` answers false for any route with an
  * initializer callee, and no delegating test because `scoreEntry` answers for every check before any
diff --git a/internal-packages/observability-map/src/checks/errorClassification.ts b/internal-packages/observability-map/src/checks/errorClassification.ts
@@ -31,7 +31,7 @@ export const BUILDERS = new Set([
  * An absolute count and not a ratio against the enclosing body, or padding the body relabels the
  * same broad swallow as a narrow guard (`inert-statements-after-try`). The count is NOT unpaddable,
  * which an earlier docstring claimed: it is one condition of three and no longer the load-bearing
- * one. See README, "Parse guards, and the narrow-try count".
+ * one. See INTERNALS.md, "Parse guards, and the narrow-try count".
  */
 const NARROW_TRY_STATEMENTS = 2;
 
@@ -88,7 +88,7 @@ function swallows(clause: CatchEvidence): boolean {
  * and is defeated by one inert call, so `try { String(0); }` reads as classification and takes the
  * tree from 19 to 44. `dead-classifying-try-with-call` in the mutation corpus is that shape,
  * running as an expected failure. Read the rule as "refuses `try { 0; }`", never as "an unreachable
- * catch cannot be credited". Everything else here: README, "The dead-code defence".
+ * catch cannot be credited". Everything else here: INTERNALS.md, "The dead-code defence".
  */
 export const errorClassification = {
   id: ID,
diff --git a/internal-packages/observability-map/src/checks/requestContext.ts b/internal-packages/observability-map/src/checks/requestContext.ts
@@ -32,7 +32,7 @@ function logLevel(callee: string): string {
  * is the whole point rather than an oversight: its failures go to the global handler, which names no
  * tenant. Passing those routes, as this check used to, meant deleting every catch clause in the tree
  * scored it 100, and excusing them as not-applicable is the same mistake in quieter clothes. What the
- * platform attaches centrally and why none of it is a tenant: README, "What 19 means".
+ * platform attaches centrally and why none of it is a tenant: README, "What the score means".
  */
 export const requestContext = {
   id: ID,
diff --git a/internal-packages/observability-map/src/docstringReferences.test.ts b/internal-packages/observability-map/src/docstringReferences.test.ts
@@ -7,7 +7,7 @@ import { MUTATIONS } from "./mutations.js";
 /**
  * Every test name a docstring in `src/` claims to be covered by must exist. The rule was asked for six
  * times in prose and broken six times, so prose does not enforce itself. Exactly what is and is not
- * checked, and the coverage holes that leaves: README, "Tests, timeouts and CI".
+ * checked, and the coverage holes that leaves: INTERNALS.md, "Tests, timeouts and CI".
  */
 
 const SRC = resolve(__dirname);
diff --git a/internal-packages/observability-map/src/integration.test.ts b/internal-packages/observability-map/src/integration.test.ts
@@ -21,7 +21,7 @@ import { SCORED_CHECK_IDS } from "./checks/index.js";
  * The coupling is acceptable because nothing here names a route or a count: the scan must not crash,
  * the entry point count must sit inside a wide band, and parse failures must be zero. Those are the
  * only things a fixture tree cannot tell us, since a fixture only contains shapes somebody thought to
- * write down. How the whole suite is gated in CI: README, "Tests, timeouts and CI".
+ * write down. How the whole suite is gated in CI: INTERNALS.md, "Tests, timeouts and CI".
  */
 const ROUTES = resolve(__dirname, "../../../apps/webapp/app/routes");
 
@@ -93,7 +93,8 @@ const steps = (block: string) => block.split(/^ {6}- name: /m).slice(1);
 
 /**
  * The one thing the docstring checker cannot reach, since it walks `src/` only. What the C1 defect was
- * and what replaced it: README, "Tests, timeouts and CI". These are text checks over the workflow
+ * and what replaced it: INTERNALS.md, "Tests, timeouts and CI". These are text checks over the
+ * workflow
  * rather than a parse of its semantics, so they catch the wiring coming apart and nothing about
  * whether GitHub agrees.
  */
@@ -176,7 +177,7 @@ describe("the report workflow reconciles a comment the paths no longer reach", (
 
 /**
  * Asserts the shape that cannot have the stdout-capture bug rather than the pnpm version that happens
- * not to. Why, and why the render step is left alone: README, "Tests, timeouts and CI".
+ * not to. Why, and why the render step is left alone: INTERNALS.md, "Tests, timeouts and CI".
  */
 describe("the report workflow's two scan steps", () => {
   it("let the scanner write its own report rather than capturing stdout", () => {
@@ -288,7 +289,7 @@ describe("the package's tests are wired into the gate", () => {
 /**
  * The third road into this suite, `turbo run test`. Asserts the task is uncacheable, because the
  * config is one line and reads like a performance oversight to anyone who does not know what the suite
- * reads. Measurement and the rejected `inputs` alternative: README, "Tests, timeouts and CI".
+ * reads. Measurement and the rejected `inputs` alternative: INTERNALS.md, "Tests, timeouts and CI".
  */
 describe("the third road in, turbo", () => {
   it("keeps its test task out of the turbo cache", () => {
@@ -322,7 +323,7 @@ describe("counting candidates independently of the scanner", () => {
  * Timeout for the two real-tree tests, which do not fit the suite's 10s default. A hang detector and
  * nothing else: neither test asserts anything about how long a scan takes, so a number tight enough to
  * be a performance budget would only be a way to fail on a busy runner. The contention measurements
- * behind 120s, and why 60s is not enough: README, "Tests, timeouts and CI".
+ * behind 120s, and why 60s is not enough: INTERNALS.md, "Tests, timeouts and CI".
  */
 const TREE_SCAN_TIMEOUT = 120_000;
 
diff --git a/internal-packages/observability-map/src/mutationCorpus.test.ts b/internal-packages/observability-map/src/mutationCorpus.test.ts
@@ -23,7 +23,7 @@ const ENABLED = process.env.OBS_MAP_MUTATION_CORPUS === "1";
 /**
  * Where a corpus entry goes when the tool does not defend it. `it.fails` keeps the entry running, so
  * closing the hole later turns this file red until the entry is moved back out deliberately. Both
- * gaps are described at length in README, "The mutation harness".
+ * gaps are described at length in INTERNALS.md, "The mutation harness".
  */
 const KNOWN_GAPS = new Set<string>([
   // `canRaise` accepts any call at all, so `try { String(0); }` reads as a clause guarding real work
@@ -201,7 +201,8 @@ function mutate(
  * Deliberately NOT gated behind `OBS_MAP_MUTATION_CORPUS`, unlike everything below it: the corpus
  * cannot catch its own omission by failing, since omitting a check from the sweep lowers the score
  * rather than raising it. Belongs in the default suite so adding a check without extending the corpus
- * turns `pnpm test` red rather than a job nobody runs locally. See README, "The mutation harness".
+ * turns `pnpm test` red rather than a job nobody runs locally. See INTERNALS.md, "The mutation
+ * harness".
  */
 describe("the corpus keeps up with the check registry", () => {
   it("suppresses every registered check in the exhaustive sweep", () => {
@@ -303,7 +304,7 @@ describeCorpus("mutation corpus over the real route tree", { timeout: ENTRY_TIME
   /**
    * How much a mutation must reach before its result means anything, since one that silently matched
    * nothing would otherwise pass by leaving the tree alone. On sites and not only files, and why
-   * verdict movement cannot be the guard instead: README, "The mutation harness".
+   * verdict movement cannot be the guard instead: INTERNALS.md, "The mutation harness".
    */
   const MINIMUM_FILES_TOUCHED = 20;
   const MINIMUM_SITES_TOUCHED = 40;
diff --git a/internal-packages/observability-map/src/mutations.ts b/internal-packages/observability-map/src/mutations.ts
@@ -3,7 +3,7 @@ import ts from "typescript";
 /**
  * Source-to-source mutations for the tree-scale corpus in `mutationCorpus.test.ts`. Why they are text
  * rewrites rather than reprints, what `preserving` and `deleting` mean, and why the additive direction
- * is tracked separately in `ADDITIVE_IDS`: README, "The mutation harness".
+ * is tracked separately in `ADDITIVE_IDS`: INTERNALS.md, "The mutation harness".
  */
 
 export type MutationKind = "preserving" | "deleting";
@@ -306,7 +306,7 @@ function bindingNameOf(clause: ts.CatchClause): string | null {
 /**
  * Splice a statement in at the HEAD of every catch clause that names its binding, which is the whole
  * point of the helper: 234 of the tree's 260 clauses end in a `return` or a `throw`, so an appended
- * shape was dead by ordering before the rule under test looked at it. See README, "The mutation
+ * shape was dead by ordering before the rule under test looked at it. See INTERNALS.md, "The mutation
  * harness".
  */
 function prependToEveryCatch(
diff --git a/internal-packages/observability-map/src/report/prComment.ts b/internal-packages/observability-map/src/report/prComment.ts
@@ -213,7 +213,7 @@ const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
  * misses is a change the pull request silently does not report. The terms overlap on purpose, and
  * what is defended is that their union is complete rather than that each one is load bearing.
  * `MapReport.suppressions` is the one term deliberately left out, because its totals are summed from
- * the very per-entry arrays the loop below compares. See README, "Reporting".
+ * the very per-entry arrays the loop below compares. See INTERNALS.md, "Reporting".
  */
 export function hasDelta(head: MapReport, base: MapReport | null): boolean {
   if (!base) return true;
diff --git a/internal-packages/observability-map/src/scan.ts b/internal-packages/observability-map/src/scan.ts
@@ -92,7 +92,7 @@ const CALLER_ID_FIELD =
 /**
  * Callees handed the caller's id that cannot narrow a read with it: the log line and the response
  * body. A denylist of sinks rather than an allowlist of query callees, which is a measurement and not
- * a preference. See README, "What auth-scope reads as scoping".
+ * a preference. See INTERNALS.md, "What auth-scope reads as scoping".
  */
 const NON_SCOPING_CALLEE = /(^|\.)console\.[A-Za-z_$][\w$]*$|^(json|typedjson|defer)$/;
 
@@ -135,7 +135,7 @@ function isHandedToAScopingCall(property: ts.PropertyAssignment): boolean {
 
 /**
  * Whether any handler in `fns` assigns the caller's own id to an object-literal property. Three
- * conditions, all load bearing: README, "What auth-scope reads as scoping".
+ * conditions, all load bearing: INTERNALS.md, "What auth-scope reads as scoping".
  *
  * Per export rather than per entry point, which is why it is computed here rather than in the main
  * body walk. Nested functions are walked, since a filter built inside a callback still filters.
@@ -272,7 +272,7 @@ function canRaise(node: ts.Node): boolean {
 
 /**
  * What the guarded region does, in the three terms `error-classification` needs. Each term's rule
- * and measurement: README, "Catch evidence, per clause".
+ * and measurement: INTERNALS.md, "Catch evidence, per clause".
  *
  * Two residuals in opposite directions, both live. `guardCanRaise` refuses `try { 0; }` and nothing
  * cleverer, because `canRaise` accepts any call at all, so `try { String(0); }` reads as
@@ -577,7 +577,7 @@ function tryBlockMayThrow(block: ts.Block): boolean {
 /**
  * Whether the tree rooted at `root` contains a node `hit` accepts that a provably-untaken branch does
  * not already rule out. Strictly subtractive against a plain containment read, which is what lets its
- * two callers read it for opposite purposes: see README, "Two folds, pointing opposite ways".
+ * two callers read it for opposite purposes: see INTERNALS.md, "Two folds, pointing opposite ways".
  *
  * The `exited` half is pinned by `dead and deferred code prepended to a deciding catch does not blind
  * it` and the `BRANCH_EXITED` family; the `selectsADistinctPath` half by `an arm whose only exit is
@@ -695,8 +695,9 @@ function selectsADistinctPath(statement: ts.IfStatement | ts.SwitchStatement): b
  * Both answers are read off the clause's own guaranteed path: the walk enters a construct exactly
  * where the entered statements are guaranteed to execute whenever the clause body runs, so no credit
  * can ever come from code a semantics-preserving edit could have added dead. Which constructs are
- * entered and which are refused, and the eleven dead spellings this replaced: README, "The dead-code
- * defence". `dead-*` in the mutation corpus is the tree-scale proof, one entry per shape.
+ * entered and which are refused, and the eleven dead spellings this replaced: INTERNALS.md,
+ * "The dead-code defence". `dead-*` in the mutation corpus is the tree-scale proof, one entry per
+ * shape.
  *
  * The cost is real, in both rules. `catch (e) { if (transient) throw e; return null; }` no longer
  * reads as a rethrow, so it fails rather than sitting out. That is the direction to be wrong in.
@@ -896,7 +897,8 @@ function isAtMostSingletonArray(expr: ts.Expression): boolean {
 
 /**
  * Whether the function-like `node` is the callback argument of a per-item iteration. Both directions
- * of being wrong, and what makes the name list survivable: README, "The iteration-callback boundary".
+ * of being wrong, and what makes the name list survivable: INTERNALS.md, "The iteration-callback
+ * boundary".
  *
  * The residual a reader here needs: a per-item callback under a callee this list does not know,
  * `pMap(items, cb)`, is attributed to the route, so a per-element catch that decides can carry it to
@@ -1266,7 +1268,7 @@ const SYNTAX_ONLY_OPTIONS: ts.CompilerOptions = { noLib: true, noResolve: true,
  * Syntactic diagnostics for an already-parsed source file, through `ts.Program` rather than off the
  * internal diagnostics array the parser hangs on the source file, which a compiler upgrade could
  * rename out from under us. The host hands the program the `sf` we already have, so nothing is parsed
- * twice. Costs and reasoning: README, "Tests, timeouts and CI".
+ * twice. Costs and reasoning: INTERNALS.md, "Tests, timeouts and CI".
  */
 function syntacticDiagnostics(sf: ts.SourceFile): readonly ts.Diagnostic[] {
   const host: ts.CompilerHost = {
@@ -1437,7 +1439,7 @@ export function scanFile(fileName: string, source: string): EntryPoint | null {
     // since nesting deeper inside one is still inside it. `calleeNames`, `logCalls` and the statement
     // count keep descending regardless; a catch does not, and is kept in `callbackCatches` with its
     // evidence rather than dropped. Only an iteration callback is a boundary, not every function-like
-    // node. See README, "The iteration-callback boundary".
+    // node. See INTERNALS.md, "The iteration-callback boundary".
     const visit = (node: ts.Node, inCatch: boolean, inCallback: boolean) => {
       if (ts.isFunctionLike(node)) {
         if (isEntryFunction(node)) addStatements(countFunctionStatements(node));
diff --git a/internal-packages/observability-map/src/sensitivity.ts b/internal-packages/observability-map/src/sensitivity.ts
@@ -5,7 +5,8 @@ import { routePathOf } from "./adapters/remix.js";
  * Symbols whose presence says the route does something risky: minting or revoking a credential,
  * escalating to another user, destroying a tenant. Calling a guard is never one of them, because a
  * mitigation cannot be the hazard, and `webappSymbols.test.ts` fails if a name stops resolving in the
- * webapp. Both rules and what they cost: README, "Sensitivity, and the names the tool matches on".
+ * webapp. Both rules and what they cost: INTERNALS.md, "Sensitivity, and the names the tool
+ * matches on".
  */
 export const SENSITIVE_SYMBOLS = [
   // Escalation: acting as another user.
diff --git a/internal-packages/observability-map/src/suppression.ts b/internal-packages/observability-map/src/suppression.ts
@@ -31,7 +31,7 @@ function leafTokens(node: ts.Node): ts.Node[] {
  * `ignores the directive inside a string literal`.
  *
  * The mutation corpus cannot cover any of this, because a suppression can only lower a score. See
- * README, "Reading the directive out of the source".
+ * INTERNALS.md, "Reading the directive out of the source".
  */
 function isClaimedContent(node: ts.Node): boolean {
   return (
@@ -49,7 +49,8 @@ function isClaimedContent(node: ts.Node): boolean {
  * Every comment range in the source, read off a real parsed `ts.SourceFile` rather than a standalone
  * `ts.createScanner`, and then filtered against the spans above. Both halves are needed, and the
  * filter is on the range's start offset rather than on the gap between a token's full start and its
- * start: README, "Reading the directive out of the source". Both lexers are called at every token
+ * start: INTERNALS.md, "Reading the directive out of the source". Both lexers are called at every
+ * token
  * boundary, because which one returns a given comment depends on whether it shares a line with the
  * token before it.
  */
diff --git a/internal-packages/observability-map/src/triviality.ts b/internal-packages/observability-map/src/triviality.ts
@@ -18,7 +18,7 @@ const MAX_STATEMENTS = 3;
 /**
  * What the rule reads, so the entry-point-wide answer and a single export's answer are the same rule
  * over different bodies rather than two rules that can drift. Both limits, the reluctance and the
- * measured `hintText` decision: README, "Triviality, in detail".
+ * measured `hintText` decision: INTERNALS.md, "Triviality, in detail".
  */
 type TrivialityView = {
   statementCount: number;
diff --git a/internal-packages/observability-map/src/types.ts b/internal-packages/observability-map/src/types.ts
@@ -9,7 +9,7 @@ export type CheckResult = {
 /**
  * One catch clause in a loader/action body, or in a same-file helper the body calls. Per clause
  * rather than per entry point, so a narrow parse guard sitting beside a broad handler catch stays
- * legible. Every field's exact rule and its measured reasoning: README, "Catch evidence, per
+ * legible. Every field's exact rule and its measured reasoning: INTERNALS.md, "Catch evidence, per
  * clause".
  */
 export type CatchEvidence = {
@@ -54,7 +54,7 @@ export type LogCall = {
 
 /**
  * Body-scoped evidence for one route module. Which fields are per export and why, and what "the
- * body" means: README, "How the scanner reads a route".
+ * body" means: INTERNALS.md, "How the scanner reads a route".
  */
 export type EntryPoint = {
   fileName: string;
