@descryy/core 0.3.0 → 0.5.0

package/dist/validation/route-drift.d.ts

@@ -1,43 +1,6 @@
 /**
- * Route drift — static extraction against framework introspection (DEC-115).
- *
- * The comparison logic only; identity from `@descryy/ir`, never re-implemented
- * here. The `bench/route-drift.mjs` instrument does the harder half of this
- * row — reading `php artisan route:list`, the `--introspection` file
- * fallback, and the refusal to run an installer on a cloned repository (§5
- * rule 10, DEC-115 clause 3). This module is the query it calls: given two
- * already-extracted route lists, decide what they say about each other.
- *
- * ## The rule this file is built around, before anything else
- *
- * **A diff is the one measurement where an empty input produces the most
- * reassuring possible output.** If introspection returns nothing —
- * `artisan` not runnable, the application not bootable, the command failing
- * quietly — the drift is zero, and zero drift is exactly what a healthy
- * repository looks like. So both population *sizes* are part of the result,
- * not scaffolding, and this module cannot report agreement it was not
- * actually given. An empty or implausible side is a **refusal** to report
- * drift, never a clean bill — the same shape this lane measured directly on
- * `env-precision-adapter.mjs`: two runs both printed `decision accuracy
- * 100.0%`, one on 5 decisions and one on 51, indistinguishable except for the
- * confidence interval underneath. A diff has no interval to fall back on, so
- * the refusal has to be explicit.
- *
- * ## The polarity is DEC-115's and is not re-opened here
- *
- * Static extraction is the **floor**; introspection is a **promotion** over
- * the same node ids. The two disagreement directions are two findings with
- * different audiences and different truth conditions, and collapsing them is
- * the error:
- *
- * | direction | what it is | what it is NOT |
- * | --- | --- | --- |
- * | static says yes, listing says no | "these two sources disagree" | **never** "dead route" — ambiguous between the customer's app and our own false positive, and nothing here separates them |
- * | listing says yes, static says no | a statement about **us**: the extractor missed one | not a finding about the customer at all |
- *
- * The second row is the more valuable one. Where a listing exists it is
- * **ground truth for recall** — a complete denominator this project has
- * never had without hand-building it.
+ * Route drift (DEC-115): compares two already-extracted route lists; identity via `@descryy/ir`, never re-implemented. An empty/implausible introspection side must be a *refusal*, never reported as zero drift — the emptiest input would otherwise be the most falsely reassuring output.
+ * Static extraction is the floor, introspection a promotion (DEC-115 polarity): static-yes/listing-no is an ambiguous disagreement, never "dead route"; listing-yes/static-no is a statement about our own extractor missing a route, and listing is ground truth for recall.
  */
 /** One route, from either side, before identity is applied. */
 export interface DriftRoute {
@@ -46,13 +9,8 @@ export interface DriftRoute {
     /** Repo-relative, when the side has one (the static extractor always does). */
     readonly file?: string;
 }
-/**
- * What the introspected side actually returned.
- *
- * Three refusal states plus `read`, mirroring `RollbackReport.ran` /
- * `blockers` one level down: a caller needs to know *why* nothing was
- * compared, not just that nothing was.
- */
+/** What the introspected side returned. Three refusal states plus `read` — a
+ *  caller needs to know *why* nothing was compared, not just that it wasn't. */
 export type Introspection = {
     readonly state: "read";
     readonly source: string;
@@ -86,23 +44,12 @@ export interface DriftReport {
     readonly recallAgainstListing?: number;
 }
 export interface DriftOptions {
-    /**
-     * Below this, a listing is not believed.
-     *
-     * A Laravel application with `artisan` and one route is far more likely to
-     * be a listing that failed than an application with one route. Crude on
-     * purpose — it exists to catch "the command produced almost nothing," not
-     * to model route counts.
-     */
+    /** Below this, a listing isn't believed — crude on purpose, catches "the
+     *  command produced almost nothing," not a route-count model. */
     readonly implausibleBelow?: number;
 }
-/**
- * The comparison, and the refusal that guards it.
- *
- * `staticOnly`/`listedOnly`/`agreed` are only ever populated when both sides
- * were actually read and the introspected side is not implausibly small.
- * Every other path returns `reported: false` carrying both counts, because
- * the counts are the evidence the refusal was necessary.
- */
+/** The comparison, and the refusal that guards it. `staticOnly`/`listedOnly`/
+ *  `agreed` populate only when both sides read and neither is implausibly
+ *  small; otherwise `reported: false` carries both counts as evidence. */
 export declare function checkRouteDrift(staticSide: readonly DriftRoute[], introspected: Introspection, options?: DriftOptions): DriftReport;
 //# sourceMappingURL=route-drift.d.ts.map

package/dist/validation/route-drift.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-drift.d.ts","sourceRoot":"","sources":["../../src/validation/route-drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC3F;IAAE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AASD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,YAAY,EAAE,aAAa,EAC3B,OAAO,GAAE,YAAiB,GACzB,WAAW,CAkDb"}
+{"version":3,"file":"route-drift.d.ts","sourceRoot":"","sources":["../../src/validation/route-drift.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;gFACgF;AAChF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC3F;IAAE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B;qEACiE;IACjE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AASD;;0EAE0E;AAC1E,wBAAgB,eAAe,CAC7B,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,YAAY,EAAE,aAAa,EAC3B,OAAO,GAAE,YAAiB,GACzB,WAAW,CA+Cb"}

package/dist/validation/route-drift.js

@@ -1,43 +1,6 @@
 /**
- * Route drift — static extraction against framework introspection (DEC-115).
- *
- * The comparison logic only; identity from `@descryy/ir`, never re-implemented
- * here. The `bench/route-drift.mjs` instrument does the harder half of this
- * row — reading `php artisan route:list`, the `--introspection` file
- * fallback, and the refusal to run an installer on a cloned repository (§5
- * rule 10, DEC-115 clause 3). This module is the query it calls: given two
- * already-extracted route lists, decide what they say about each other.
- *
- * ## The rule this file is built around, before anything else
- *
- * **A diff is the one measurement where an empty input produces the most
- * reassuring possible output.** If introspection returns nothing —
- * `artisan` not runnable, the application not bootable, the command failing
- * quietly — the drift is zero, and zero drift is exactly what a healthy
- * repository looks like. So both population *sizes* are part of the result,
- * not scaffolding, and this module cannot report agreement it was not
- * actually given. An empty or implausible side is a **refusal** to report
- * drift, never a clean bill — the same shape this lane measured directly on
- * `env-precision-adapter.mjs`: two runs both printed `decision accuracy
- * 100.0%`, one on 5 decisions and one on 51, indistinguishable except for the
- * confidence interval underneath. A diff has no interval to fall back on, so
- * the refusal has to be explicit.
- *
- * ## The polarity is DEC-115's and is not re-opened here
- *
- * Static extraction is the **floor**; introspection is a **promotion** over
- * the same node ids. The two disagreement directions are two findings with
- * different audiences and different truth conditions, and collapsing them is
- * the error:
- *
- * | direction | what it is | what it is NOT |
- * | --- | --- | --- |
- * | static says yes, listing says no | "these two sources disagree" | **never** "dead route" — ambiguous between the customer's app and our own false positive, and nothing here separates them |
- * | listing says yes, static says no | a statement about **us**: the extractor missed one | not a finding about the customer at all |
- *
- * The second row is the more valuable one. Where a listing exists it is
- * **ground truth for recall** — a complete denominator this project has
- * never had without hand-building it.
+ * Route drift (DEC-115): compares two already-extracted route lists; identity via `@descryy/ir`, never re-implemented. An empty/implausible introspection side must be a *refusal*, never reported as zero drift — the emptiest input would otherwise be the most falsely reassuring output.
+ * Static extraction is the floor, introspection a promotion (DEC-115 polarity): static-yes/listing-no is an ambiguous disagreement, never "dead route"; listing-yes/static-no is a statement about our own extractor missing a route, and listing is ground truth for recall.
  */
 import { endpointQsp, normaliseEndpointPath } from "@descryy/ir";
 const DEFAULT_IMPLAUSIBLE_BELOW = 3;
@@ -45,14 +8,9 @@ const DEFAULT_IMPLAUSIBLE_BELOW = 3;
 function key(method, path) {
     return endpointQsp(String(method || "").toUpperCase(), normaliseEndpointPath(String(path || "")));
 }
-/**
- * The comparison, and the refusal that guards it.
- *
- * `staticOnly`/`listedOnly`/`agreed` are only ever populated when both sides
- * were actually read and the introspected side is not implausibly small.
- * Every other path returns `reported: false` carrying both counts, because
- * the counts are the evidence the refusal was necessary.
- */
+/** The comparison, and the refusal that guards it. `staticOnly`/`listedOnly`/
+ *  `agreed` populate only when both sides read and neither is implausibly
+ *  small; otherwise `reported: false` carries both counts as evidence. */
 export function checkRouteDrift(staticSide, introspected, options = {}) {
     const implausibleBelow = options.implausibleBelow ?? DEFAULT_IMPLAUSIBLE_BELOW;
     if (introspected.state !== "read") {
@@ -92,11 +50,8 @@ export function checkRouteDrift(staticSide, introspected, options = {}) {
         staticOnly,
         listedOnly,
         agreed,
-        // `exactOptionalPropertyTypes` distinguishes an absent property from one
-        // present-and-undefined, so the spread includes the key only when there
-        // is a real ratio — `listedKeys.size` is never 0 on this path, since
-        // `implausibleBelow` already refused anything under it, but the type
-        // stays honest about the precondition rather than asserting past it.
+        // listedKeys.size is never 0 here (implausibleBelow refused that), but the
+        // type stays honest about the precondition rather than asserting past it.
         ...(listedKeys.size === 0 ? {} : { recallAgainstListing: agreed / listedKeys.size }),
     };
 }

package/dist/validation/route-drift.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-drift.js","sourceRoot":"","sources":["../../src/validation/route-drift.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"route-drift.js","sourceRoot":"","sources":["../../src/validation/route-drift.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAqCjE,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAEpC,sFAAsF;AACtF,SAAS,GAAG,CAAC,MAAc,EAAE,IAAY;IACvC,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,qBAAqB,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACpG,CAAC;AAED;;0EAE0E;AAC1E,MAAM,UAAU,eAAe,CAC7B,UAAiC,EACjC,YAA2B,EAC3B,UAAwB,EAAE;IAE1B,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,yBAAyB,CAAC;IAE/E,IAAI,YAAY,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAClC,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,UAAU,CAAC,MAAM;YAC9B,iBAAiB,EAAE,CAAC;YACpB,aAAa,EAAE,iBAAiB,YAAY,CAAC,KAAK,KAAK,YAAY,CAAC,GAAG,EAAE;SAC1E,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAClD,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,UAAU,CAAC,MAAM;YAC9B,iBAAiB,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM;YAC7C,aAAa,EACX,8BAA8B,gBAAgB,8CAA8C;gBAC5F,gCAAgC;SACnC,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IACjD,KAAK,MAAM,KAAK,IAAI,UAAU;QAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IACrF,MAAM,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IACjD,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,MAAM;QAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAE9F,MAAM,UAAU,GAAG,CAAC,GAAG,UAAU,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,CAAC,GAAG,UAAU,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEzE,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,UAAU,CAAC,MAAM;QAC9B,iBAAiB,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM;QAC7C,UAAU;QACV,UAAU;QACV,MAAM;QACN,2EAA2E;QAC3E,0EAA0E;QAC1E,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;KACrF,CAAC;AACJ,CAAC"}

package/dist/validation/sources.d.ts

@@ -1,47 +1,7 @@
-/**
- * The declaration side of §15's env/config check — read from the repository, not
- * from the graph.
- *
- * ## Why this is not an adapter, and why it is legal here
- *
- * §15.3's own wording is *"cross-check against declared variables **or the
- * deploy target's actual state**"*. The deploy target's state is not in the graph
- * and never will be. What holds it is `.env`, a container manifest, a CI
- * workflow, an image build file — **formats, not languages.** Reading
- * `KEY=value` and an indented `env:` block names no language, so it does not
- * cross the Canonical IR boundary; it is legal above it for the same reason
- * reading a commit log is (`sources/git`).
- *
- * That is what lets the check produce findings with no adapter change at all.
- * See DEC-120.
- *
- * ## Precision over recall, three times, because a misparse here is a wrong finding
- *
- * A name invented by a sloppy scan becomes a confident sentence about somebody's
- * configuration. So:
- *
- * 1. **Two different name rules, on purpose.** In a dotenv file `KEY=` is
- *    unambiguous, so any identifier shape is taken. Inside a structured document
- *    an `env:` block is indistinguishable from any other mapping once the scan
- *    loses its place, so only `UPPER_SNAKE` is accepted. The cost is a lowercase
- *    variable in a manifest, which is rare; the alternative is turning a stray
- *    key into a declaration.
- * 2. **A block ends at the first line indented no deeper than its header.** No
- *    document model, no continuation handling, no anchors. A construct this scan
- *    cannot follow ends the block early, which *loses* names — a disclosed gap
- *    rather than a wrong one.
- * 3. **A commented-out declaration counts, and is marked.** `# STRIPE_KEY=` in a
- *    sample file documents that the variable exists, which is exactly the
- *    question being asked. Treating it as absent would report every well
- *    documented optional setting as undeclared.
- *
- * ## The example/supply distinction
- *
- * `.env.example` **documents**; `.env.development` and a container manifest
- * **supply**. Both are declarations for the purpose of "does this repository know
- * this variable exists", and they are not interchangeable for anything else, so
- * the distinction is carried on the surface rather than flattened.
- */
+/** §15's env/config check reads `.env`/manifests/CI directly — formats, not
+ *  languages, so it never crosses the IR boundary (DEC-120). Precision over
+ *  recall: strict names, lossy block-end, commented lines count.
+ *  `.env.example` documents, others supply. */
 /** What a surface is evidence *of*. */
 export type SurfaceRole = 
 /** The repository's own statement that a variable exists. */
@@ -71,15 +31,8 @@ export interface SurfaceScan {
     readonly unreadable: readonly string[];
     /** True when the walk hit its file budget before finishing. */
     readonly truncated: boolean;
-    /**
-     * The noise directories this walk actually used, echoed back.
-     *
-     * Empty means no adapter declared any, and the walk therefore descended into
-     * whatever vendored trees the repository holds. Reporting it is what keeps an
-     * undeclared scan from reading like a complete one (rule 7) — the caller can
-     * see that the surface count is inflated rather than inferring it from a number
-     * that looks fine.
-     */
+    /** Noise dirs actually used. Empty means none declared (rule 7) — surface
+     *  count may be inflated by vendored trees. */
     readonly noiseDirectories: readonly string[];
 }
 export interface ScanOptions {
@@ -87,41 +40,21 @@ export interface ScanOptions {
     readonly maxDepth?: number;
     /** Total files a walk may consider. */
     readonly maxFiles?: number;
-    /**
-     * Directories this repository's ecosystems install dependencies or build output
-     * into — `node_modules`, `vendor`, `target`. **Supplied by the caller from the
-     * active adapters' `CapabilityMatrix.noiseDirectories`, never known here**
-     * (DEC-110). Undeclared, they are walked, and `SurfaceScan` says so.
-     */
+    /** Ecosystem install/build dirs, supplied by the caller's
+     *  `CapabilityMatrix.noiseDirectories` (DEC-110); undeclared, they get walked. */
     readonly noiseDirectories?: readonly string[];
 }
-/**
- * Shared with the migration scan, so the two walks cannot disagree about what
- * counts as vendored. A second copy of this rule is a second place to forget the
- * next ecosystem.
- */
+/** Shared with the migration scan — one rule, not two that can disagree. */
 export declare function skipDirectory(name: string, noiseDirectories?: readonly string[]): boolean;
-/**
- * Read every configuration surface a repository exposes.
- *
- * Structured documents are only opened when their path says they are a manifest
- * or a workflow. Opening every YAML file in a repository would pull in test
- * data, schema definitions and dependency lockfiles, and an `env:` key inside a
- * schema definition is a description of a variable rather than a declaration of
- * one.
- */
+/** Reads every config surface. Structured docs open only when their path
+ *  names a manifest/workflow, else a schema `env:` key would count as one. */
 export declare function scanConfigSurfaces(root: string, options?: ScanOptions): SurfaceScan;
 /** `KEY=value`, and `# KEY=value`, which documents the same variable. */
 export declare function readDotenv(text: string): readonly EnvDeclaration[];
 /** `ENV K=V`, the legacy `ENV K V`, and `ARG K`. */
 export declare function readImageBuild(text: string): readonly EnvDeclaration[];
-/**
- * `env:` / `environment:` blocks in an indented document, in both forms.
- *
- * Mapping — `KEY: value` — and sequence — `- KEY=value` or a bare `- KEY`. The
- * bare sequence form declares a pass-through from the host, which is still the
- * document stating that the variable exists.
- */
+/** `env:`/`environment:` blocks: mapping (`KEY: value`) or sequence
+ *  (`- KEY=value` / bare `- KEY`, a host pass-through — still a declaration). */
 export declare function readStructured(text: string): readonly EnvDeclaration[];
 /** One `KEY = "value"` line inside a `wrangler.toml` `[vars]` or `[env.<name>.vars]` table. */
 export interface WranglerVarsEntry {
@@ -133,20 +66,9 @@ export interface WranglerVarsEntry {
     readonly line: number;
     readonly commented: boolean;
 }
-/**
- * Walk a `wrangler.toml`'s `[vars]` and `[env.<name>.vars]` tables only.
- *
- * Every other table — `[[kv_namespaces]]`, `[assets]`, `[env.<name>]` itself
- * (the deploy target's own settings, not its vars) — is out of scope by
- * construction rather than by exclusion list: entering *any* table this
- * function does not recognise as a vars table resets tracking to "outside",
- * so a line that merely looks like `KEY = value` inside `[[kv_namespaces]]`
- * (e.g. `binding = "HOSTNAMES"`) is never mistaken for a declared variable.
- * `[[...]]` array-of-tables headers are matched and reset scope the same way,
- * rather than silently falling through as an unrecognised line — an
- * `[[env.staging.kv_namespaces]]` line right after `[env.staging.vars]` must
- * end that table, not extend it.
- */
+/** Only `[vars]`/`[env.<name>.vars]` tables are read; any other table (or
+ *  `[[...]]` header) resets scope to "outside", so `[[kv_namespaces]]` lines
+ *  are never mistaken for a var. */
 export declare function readWranglerVarsEntries(text: string): readonly WranglerVarsEntry[];
 /** The declaration-only projection `scanConfigSurfaces` uses. See `readWranglerVarsEntries` for the value-carrying form `resolve.ts` reads. */
 export declare function readWranglerVars(text: string): readonly EnvDeclaration[];

package/dist/validation/sources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/validation/sources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,uCAAuC;AACvC,MAAM,MAAM,WAAW;AACrB,6DAA6D;AAC3D,aAAa;AACf,oEAAoE;GAClE,cAAc,CAAC;AAEnB,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,CAAC;AAEpF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AA4DD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,gBAAgB,GAAE,SAAS,MAAM,EAAO,GACvC,OAAO,CAMT;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,WAAW,CAmDvF;AAqED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAgBlE;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAwBtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CA4BtE;AAED,+FAA+F;AAC/F,MAAM,WAAW,iBAAiB;IAChC,2HAA2H;IAC3H,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,CAoClF;AAED,+IAA+I;AAC/I,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAGxE"}
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/validation/sources.ts"],"names":[],"mappings":"AAAA;;;+CAG+C;AAK/C,uCAAuC;AACvC,MAAM,MAAM,WAAW;AACrB,6DAA6D;AAC3D,aAAa;AACf,oEAAoE;GAClE,cAAc,CAAC;AAEnB,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,CAAC;AAEpF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;mDAC+C;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;sFACkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAkBD,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,gBAAgB,GAAE,SAAS,MAAM,EAAO,GACvC,OAAO,CAKT;AAmCD;8EAC8E;AAC9E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,WAAW,CAsDvF;AA+DD,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAelE;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAwBtE;AAED;iFACiF;AACjF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CA4BtE;AAED,+FAA+F;AAC/F,MAAM,WAAW,iBAAiB;IAChC,2HAA2H;IAC3H,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAWD;;oCAEoC;AACpC,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,CAoClF;AAED,+IAA+I;AAC/I,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAGxE"}

package/dist/validation/sources.js

@@ -1,97 +1,15 @@
-/**
- * The declaration side of §15's env/config check — read from the repository, not
- * from the graph.
- *
- * ## Why this is not an adapter, and why it is legal here
- *
- * §15.3's own wording is *"cross-check against declared variables **or the
- * deploy target's actual state**"*. The deploy target's state is not in the graph
- * and never will be. What holds it is `.env`, a container manifest, a CI
- * workflow, an image build file — **formats, not languages.** Reading
- * `KEY=value` and an indented `env:` block names no language, so it does not
- * cross the Canonical IR boundary; it is legal above it for the same reason
- * reading a commit log is (`sources/git`).
- *
- * That is what lets the check produce findings with no adapter change at all.
- * See DEC-120.
- *
- * ## Precision over recall, three times, because a misparse here is a wrong finding
- *
- * A name invented by a sloppy scan becomes a confident sentence about somebody's
- * configuration. So:
- *
- * 1. **Two different name rules, on purpose.** In a dotenv file `KEY=` is
- *    unambiguous, so any identifier shape is taken. Inside a structured document
- *    an `env:` block is indistinguishable from any other mapping once the scan
- *    loses its place, so only `UPPER_SNAKE` is accepted. The cost is a lowercase
- *    variable in a manifest, which is rare; the alternative is turning a stray
- *    key into a declaration.
- * 2. **A block ends at the first line indented no deeper than its header.** No
- *    document model, no continuation handling, no anchors. A construct this scan
- *    cannot follow ends the block early, which *loses* names — a disclosed gap
- *    rather than a wrong one.
- * 3. **A commented-out declaration counts, and is marked.** `# STRIPE_KEY=` in a
- *    sample file documents that the variable exists, which is exactly the
- *    question being asked. Treating it as absent would report every well
- *    documented optional setting as undeclared.
- *
- * ## The example/supply distinction
- *
- * `.env.example` **documents**; `.env.development` and a container manifest
- * **supply**. Both are declarations for the purpose of "does this repository know
- * this variable exists", and they are not interchangeable for anything else, so
- * the distinction is carried on the surface rather than flattened.
- */
+/** §15's env/config check reads `.env`/manifests/CI directly — formats, not
+ *  languages, so it never crosses the IR boundary (DEC-120). Precision over
+ *  recall: strict names, lossy block-end, commented lines count.
+ *  `.env.example` documents, others supply. */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 const DEFAULT_MAX_DEPTH = 5;
 const DEFAULT_MAX_FILES = 20_000;
-/**
- * Directories a configuration scan must not descend into.
- *
- * Vendored code carries its own `.env.example` files, and a dependency's sample
- * configuration is not this repository's declaration of anything. Including one
- * would put another project's variable names into the denominator of the
- * coverage guard, which is the number that decides whether anything is reported
- * at all.
- *
- * **The rule is structural, not a list of ecosystems' cache directories.** The
- * first version of this was such a list and the boundary lint rejected it, which
- * was the correct call: engine code that knows one ecosystem's build cache by
- * name is engine code that will be missing the next one's. Every dotted directory
- * is skipped apart from the ones that hold pipeline definitions.
- *
- * **`node_modules`, `vendor`, `target`, `dist`, `build`, `out` and `coverage`
- * used to sit here too**, and DEC-110 recorded them as the unfinished half of its
- * own ruling — *"three ecosystems' names in the skip list"* — while naming the end
- * state: `noiseDirectories` on `CapabilityMatrix`, declared per adapter. They are
- * gone from the engine now and arrive through `ScanOptions.noiseDirectories`
- * instead. **The knowledge moved to the layer that has it; a second list was not
- * created** — DEC-110's *"what must not happen is a third list."*
- *
- * The cost is real and disclosed rather than hidden: with nothing declared, a
- * dependency tree in an undotted directory is walked and a sample inside it is
- * read. `SurfaceScan.noiseDirectories` reports the set actually used, so an empty
- * declaration cannot pass for a complete one (rule 7), and
- * `bench/env-precision.mjs` still reports the surface count per repository.
- */
-/**
- * Dotted directories that are walked anyway, because **configuration lives in
- * them**.
- *
- * The list started as pipelines only and that was too narrow — found by the
- * decisions denominator, not by reasoning. `dispatch` keeps a real
- * `.devcontainer/.env.example` documenting five variables; skipping it made the
- * declaration surface incomplete, which moved the coverage guard *and* made
- * three variables look undocumented when the repository documents all three. A
- * missing declaration source does not fail loudly here: it silently turns
- * correct suppressions into findings.
- *
- * These are directories a human authors configuration in, as opposed to ones a
- * tool writes state into — which is the distinction the dotted-skip rule is
- * reaching for and cannot express structurally. DEC-110 records the end state:
- * the adapter declares its own noise directories and this list goes away.
- */
+/** Skip vendored/build dirs structurally (dotted-dir rule, not an ecosystem
+ *  list) so another project's `.env.example` can't pollute the denominator. */
+/** Dotted dirs walked anyway — config lives here. Missing one silently turns
+ *  correct suppressions into findings. Adapter-declared list (DEC-110) replaces this. */
 const CONFIG_DIRECTORIES = new Set([
     ".github",
     ".circleci",
@@ -99,22 +17,36 @@ const CONFIG_DIRECTORIES = new Set([
     ".devcontainer",
     ".config",
 ]);
-/**
- * Shared with the migration scan, so the two walks cannot disagree about what
- * counts as vendored. A second copy of this rule is a second place to forget the
- * next ecosystem.
- */
+/** Shared with the migration scan — one rule, not two that can disagree. */
 export function skipDirectory(name, noiseDirectories = []) {
-    // The structural rule is checked first, and deliberately: a declaration cannot
-    // re-admit a dotted state directory, and cannot exclude `.github`. The adapter
-    // declares what its ecosystem installs, not what the engine's own rule means.
+    // Structural check first: a declaration can't re-admit a dotted dir or
+    // exclude `.github`; adapters declare installs, not the engine's own rule.
     if (name.startsWith("."))
         return !CONFIG_DIRECTORIES.has(name);
     return noiseDirectories.includes(name);
 }
-/** `.env`, `.env.local`, `.env.test` — but not `.env.d.ts` or `.envrc`. */
-const DOTENV = /^\.env(\.[A-Za-z0-9_.-]+)?$/;
-const EXAMPLE_SUFFIX = /\.(example|sample|template|dist|defaults?)$/i;
+/**
+ * `.env`, `.env.local`, `.env-production` — but not `.env.d.ts` or `.envrc`.
+ *
+ * **The separator is `[.-]`, not `.`, and the leading dot is optional on an
+ * example file.** Both were `.`-and-dot-only, and both spellings the pattern
+ * missed are in real repositories: `.env-example` and `env.example`. The cost
+ * was not a missing surface, it was a **one-sided comparison** — with no
+ * example file read, every variable a `.env` sets reads as documented nowhere,
+ * so the check either reports the whole file or, past the coverage floor,
+ * reports nothing and says the examples cover 0%.
+ *
+ * The dotless form is admitted **only when it carries an example suffix**. A
+ * bare `env` is as likely a shell script or a directory as a declaration, and
+ * `env.ts` is code; requiring the suffix keeps both out rather than relying on
+ * the reader finding no `KEY=` in them.
+ */
+const DOTENV = /^\.env([.-][A-Za-z0-9_.-]+)?$/;
+/** `env.example`, `env-sample` — the same file, without the leading dot. */
+const BARE_ENV_EXAMPLE = /^env[.-](example|sample|template|dist|defaults?)$/i;
+/** TypeScript that happens to be named for the environment. Never a declaration. */
+const DECLARATION_FILE = /\.d\.[cm]?ts$/i;
+const EXAMPLE_SUFFIX = /[.-](example|sample|template|dist|defaults?)$/i;
 const CONTAINER_MANIFEST = /^(docker-)?compose([.-][A-Za-z0-9_.-]+)?\.ya?ml$/i;
 const IMAGE_BUILD = /^(Containerfile|Dockerfile)([.-][A-Za-z0-9_.-]+)?$/i;
 const STRUCTURED = /\.ya?ml$/i;
@@ -124,15 +56,8 @@ const WRANGLER_TOML = /^wrangler\.toml$/;
 const UPPER_SNAKE = /^[A-Z][A-Z0-9_]*$/;
 /** Any identifier shape, for the unambiguous `KEY=` form. */
 const ANY_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/**
- * Read every configuration surface a repository exposes.
- *
- * Structured documents are only opened when their path says they are a manifest
- * or a workflow. Opening every YAML file in a repository would pull in test
- * data, schema definitions and dependency lockfiles, and an `env:` key inside a
- * schema definition is a description of a variable rather than a declaration of
- * one.
- */
+/** Reads every config surface. Structured docs open only when their path
+ *  names a manifest/workflow, else a schema `env:` key would count as one. */
 export function scanConfigSurfaces(root, options = {}) {
     const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
     const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
@@ -161,6 +86,9 @@ export function scanConfigSurfaces(root, options = {}) {
                 directory = statSync(full).isDirectory();
             }
             catch {
+                // Same as an unreadable dir, on one entry (broken symlink, perm error,
+                // race). Disclosed via `unreadable` (rule 7), not dropped silently.
+                unreadable.push(rel(root, full));
                 continue;
             }
             if (directory) {
@@ -188,17 +116,16 @@ export function scanConfigSurfaces(root, options = {}) {
     return { surfaces, unreadable, truncated, noiseDirectories };
 }
 function classify(root, dir, entry) {
-    if (DOTENV.test(entry)) {
-        const example = EXAMPLE_SUFFIX.test(entry) || entry === ".env.example";
+    if ((DOTENV.test(entry) || BARE_ENV_EXAMPLE.test(entry)) && !DECLARATION_FILE.test(entry)) {
+        const example = EXAMPLE_SUFFIX.test(entry);
         // An example file states what exists; a concrete one states what is set.
         // Neither is on a path to production by itself, so both are declarations —
         // the deploy target is the manifest that mounts them.
         return { format: "dotenv", role: "declaration", example };
     }
     if (WRANGLER_TOML.test(entry)) {
-        // Same status `.env.development` holds: the repository's own statement of
-        // what it runs with, not a deploy pipeline's manifest of it. `[vars]` and
-        // `.env.development` are read the same way for the same reason.
+        // Same status as `.env.development`: repo's own statement, not a deploy
+        // manifest — `[vars]` read the same way for the same reason.
         return { format: "wranglerVars", role: "declaration", example: false };
     }
     if (IMAGE_BUILD.test(entry)) {
@@ -212,13 +139,8 @@ function classify(root, dir, entry) {
     }
     return null;
 }
-/**
- * Only structured documents whose *path* declares them a pipeline are opened.
- *
- * Named rather than pattern-matched on content: a document that happens to
- * contain an `env:` key is not necessarily setting one, and guessing from
- * content is how a schema fragment becomes a declaration.
- */
+/** Only path-classified pipeline docs are opened — matching content (an
+ *  `env:` key) would turn a schema fragment into a false declaration. */
 function isPipelineDirectory(dir) {
     const parts = dir.split("/");
     return (parts.includes("workflows") ||
@@ -250,8 +172,7 @@ export function readDotenv(text) {
     for (let i = 0; i < lines.length; i += 1) {
         const raw = lines[i] ?? "";
         const commented = /^\s*#/.test(raw);
-        // `export KEY=value` is the shell-sourceable form of the same file and is
-        // common in deployment scripts.
+        // `export KEY=value` — shell-sourceable form, common in deploy scripts.
         const match = /^\s*(?:#\s*)?(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(raw);
         if (match === null)
             continue;
@@ -290,13 +211,8 @@ export function readImageBuild(text) {
     }
     return dedupe(out);
 }
-/**
- * `env:` / `environment:` blocks in an indented document, in both forms.
- *
- * Mapping — `KEY: value` — and sequence — `- KEY=value` or a bare `- KEY`. The
- * bare sequence form declares a pass-through from the host, which is still the
- * document stating that the variable exists.
- */
+/** `env:`/`environment:` blocks: mapping (`KEY: value`) or sequence
+ *  (`- KEY=value` / bare `- KEY`, a host pass-through — still a declaration). */
 export function readStructured(text) {
     const out = [];
     const lines = text.split(/\r?\n/);
@@ -334,20 +250,9 @@ function wranglerTableEnvironment(table) {
         return "default";
     return WRANGLER_ENV_VARS_TABLE.exec(trimmed)?.[1] ?? null;
 }
-/**
- * Walk a `wrangler.toml`'s `[vars]` and `[env.<name>.vars]` tables only.
- *
- * Every other table — `[[kv_namespaces]]`, `[assets]`, `[env.<name>]` itself
- * (the deploy target's own settings, not its vars) — is out of scope by
- * construction rather than by exclusion list: entering *any* table this
- * function does not recognise as a vars table resets tracking to "outside",
- * so a line that merely looks like `KEY = value` inside `[[kv_namespaces]]`
- * (e.g. `binding = "HOSTNAMES"`) is never mistaken for a declared variable.
- * `[[...]]` array-of-tables headers are matched and reset scope the same way,
- * rather than silently falling through as an unrecognised line — an
- * `[[env.staging.kv_namespaces]]` line right after `[env.staging.vars]` must
- * end that table, not extend it.
- */
+/** Only `[vars]`/`[env.<name>.vars]` tables are read; any other table (or
+ *  `[[...]]` header) resets scope to "outside", so `[[kv_namespaces]]` lines
+ *  are never mistaken for a var. */
 export function readWranglerVarsEntries(text) {
     const out = [];
     const lines = text.split(/\r?\n/);
@@ -394,8 +299,7 @@ function dedupe(declarations) {
     const seen = new Map();
     for (const declaration of declarations) {
         const existing = seen.get(declaration.name);
-        // An active assignment outranks a commented one even if it comes later:
-        // "set here" is a stronger fact than "documented here".
+        // Active assignment outranks a later commented one: "set" beats "documented".
         if (existing === undefined || (existing.commented && !declaration.commented)) {
             seen.set(declaration.name, declaration);
         }