@descryy/core 0.1.0

package/dist/validation/env.d.ts

@@ -0,0 +1,243 @@
+/**
+ * §15.3's environment/config check — *"cheapest and most reliable, ship first"*.
+ *
+ * The first thing in this repository that produces a statement about somebody's
+ * code rather than a measurement about the graph. Everything below is shaped by
+ * one fact, which was measured before any of it was written:
+ *
+ * > **A variable that is read and never declared is usually not a bug.**
+ *
+ * | repository | declared | read | read and never declared |
+ * | --- | --- | --- | --- |
+ * | `outline` | 91 | 23 | **18** |
+ * | `saleor` | 7 | 114 | **107** |
+ *
+ * The 107 are not defects; that repository's configuration lives in framework
+ * defaults and a deployment this run cannot see. The 18 are not defects either,
+ * and they are the more instructive set because they look plausible — container
+ * credentials, a platform's dyno id, a proxy setting, five alternates to a
+ * variable that *is* declared. A rule that reports them names a real variable at
+ * a real line and is wrong every time, which is how a tool gets uninstalled.
+ *
+ * This is the contract engine's problem in a second spelling — 117 callers, 24
+ * routes, and the 101 unmatched being a backend nobody analysed — so it takes the
+ * same two answers. **Report against evidence that exists; disclose the rest with
+ * a count.** See DEC-121.
+ *
+ * ## Three evidence sets, and the rule over them
+ *
+ * ```
+ *   reads (graph)        declarations (.env*)      deploy target (manifests, CI)
+ *        │                       │                          │
+ *        └───────── a finding needs two of these ────────────┘
+ *                    and, for a defect claim,
+ *              one of them must assert *requirement*
+ * ```
+ *
+ * Requirement is asserted by exactly one thing: **the read site fails when the
+ * variable is absent.** Not "has no fallback" — that was the first rule, it was
+ * measured, and it was wrong five times out of six.
+ *
+ * ## The rule that replaced it, and the six findings that killed the first one
+ *
+ * The first version asked whether the read supplied a fallback. On `dispatch` it
+ * emitted six findings and **five were false**:
+ *
+ * | finding | source | why it was wrong |
+ * | --- | --- | --- |
+ * | `FORMKIT_ENTERPRISE_TOKEN` | `if (env.X && env.X.startsWith(…))` | a feature gate |
+ * | `VITE_DISPATCH_SENTRY_ENABLED` | `let e = env.X; if (e) {…}` | a feature gate |
+ * | `VITE_DISPATCH_SENTRY_DSN` | used only inside that gate | never reached |
+ * | `VITE_DISPATCH_AVATAR_TEMPLATE` | `const t = env.X` | absent is a valid value |
+ * | `VITE_FORMKIT_PRO_PROJECT_KEY` | `const hasPro = env.X` | the name says it |
+ *
+ * Every one is *assigned without a fallback and then tested*. Deciding
+ * requirement from the assignment needs to know what happens to the value
+ * afterwards, which is dataflow — R1 work at least, and not available here.
+ *
+ * The sixth finding was true, and the difference is the whole rule: it read
+ * through an accessor that **raises** when the variable is unset. So:
+ *
+ * - an accessor that raises on absence — a subscript, a config lookup with no
+ *   declared default — **asserts requirement**;
+ * - an accessor that yields an absent value instead **asserts nothing at all**,
+ *   however the result is later used.
+ *
+ * The second case is not "optional". It is *unknown at this resolution*, and it
+ * is counted and disclosed rather than assumed either way. That is why a
+ * repository whose every read yields-on-absence produces no read-side finding at
+ * all and is told so in words.
+ *
+ * **A list of platform-supplied names was considered and rejected.** It decides a
+ * fact about a variable from its spelling, it cannot be maintained across
+ * clouds, and it is silently wrong on the repository that genuinely requires
+ * `PORT`. Rule 3's shape, one level up from node types.
+ *
+ * ## The coverage guard — `nearestMiss` in a second spelling
+ *
+ * `orphans.ts` refuses to report an unmatched caller when nothing on the provider
+ * side resembles it, because the honest description is *"the provider side was
+ * never read"*. Same refusal here: before any read-side finding is emitted, the
+ * check asks what fraction of the variables the code names the repository
+ * declares *at all*. Below the floor the declaration surface is decorative, the
+ * configuration lives somewhere this run cannot see, and **nothing is reported**
+ * — only a count and the reason. That is the rule that turns `saleor`'s 107 into
+ * one honest sentence.
+ *
+ * **The denominator is every named variable, not only the required ones**, and
+ * that is not a detail. Measured over required reads alone the denominator was
+ * four on a real repository, so deleting a single declaration moved coverage
+ * from 75% to 50% and flipped the guard from reporting six findings to
+ * reporting none. A guard that inverts on one line is not a guard. Asking "does
+ * this repository declare the variables its code names" over every read is the
+ * same question with a denominator large enough to answer it — and it is what
+ * the positive control found, which is precisely what a positive control is for.
+ *
+ * ## Deploy-target surfaces can only ever suppress a finding
+ *
+ * A container manifest's `environment:` block belongs to whichever image that
+ * service runs — a database's credentials are not this application's
+ * configuration. So manifests and pipelines count towards *declared*, and never
+ * towards *undocumented*: they can prevent a finding, never create one. Without
+ * this, `outline` reports three database credentials belonging to an image it
+ * merely depends on.
+ *
+ * ## Resolution, and why a config read is not R0
+ *
+ * A `.env` file is not code. *"This name is on line 12 of one file and in none of
+ * the others"* rests on a direct read of two declarative documents with no
+ * inference at any hop — strictly better evidence than an LSP-resolved name,
+ * because nothing needed resolving. It is treated as R3, on the same precedent
+ * that lets a contract format reach R3 with no language adapter at all.
+ *
+ * A claim about what the *code* requires is capped by the node the read came
+ * from, which is R0 for a syntax-only adapter. So a `REQUIRED_NOT_DECLARED`
+ * finding lands at class C and is labelled a prediction — principle 3 working,
+ * not a defect of the check. §15.3 calls this check Class A because the
+ * underlying fact is deterministic; the resolution cap is what reconciles the
+ * two, and the report says so rather than picking one.
+ */
+import type { ResolutionLevel } from "@descryy/ir";
+import type { AdjacencyProvider, QueryResult } from "../query/provider.ts";
+import type { ConfigSurface, SurfaceScan } from "./sources.ts";
+export type EnvFindingKind = "REQUIRED_NOT_DECLARED" | "SET_BUT_UNDOCUMENTED";
+/**
+ * How strongly the finding is stated.
+ *
+ * `lead` follows `ROUTE_NOT_CALLED`'s precedent: a fact worth a look whose usual
+ * explanation is benign, worded so that a reader is not told it is a defect.
+ */
+export type EnvClaim = "defect" | "lead";
+export interface EnvEvidence {
+    readonly file: string;
+    readonly line: number;
+    /** What this location proves, in plain words. */
+    readonly says: string;
+}
+export interface EnvFinding {
+    readonly kind: EnvFindingKind;
+    readonly name: string;
+    readonly claim: EnvClaim;
+    /** The sentence a developer reads. */
+    readonly detail: string;
+    /** Every location the finding rests on. Never empty. */
+    readonly evidence: readonly EnvEvidence[];
+    readonly resolution: ResolutionLevel;
+}
+/** One env read, normalised out of `attrs.envReads` — see DEC-120. */
+export interface EnvRead {
+    readonly name: string;
+    /**
+     * True when the read site **fails if the variable is absent** — a subscript, a
+     * config lookup with no declared default. False when the accessor yields an
+     * absent value instead, which asserts nothing about requirement either way.
+     */
+    readonly required: boolean;
+    readonly file: string;
+    readonly line: number;
+    readonly resolution: ResolutionLevel;
+}
+export interface CoverageGuard {
+    /** Distinct variables read through an accessor that fails when they are absent. */
+    readonly required: number;
+    /** Every variable the code names, however it reads them. Context, not the test. */
+    readonly named: number;
+    /** How many of those the repository declares anywhere. */
+    readonly declared: number;
+    readonly ratio: number;
+    readonly floor: number;
+    readonly passed: boolean;
+    /** Of the reads that assert requirement, how many are undeclared. */
+    readonly requiredUndeclared: number;
+    /** The absolute floor: how many declared peers the guard demands. */
+    readonly minDeclared: number;
+}
+export interface EnvReport {
+    readonly findings: readonly EnvFinding[];
+    /** The count before `maxFindings` capped it — P27's disclosed remainder: a structured field, not only a prose note. */
+    readonly findingsTotal: number;
+    readonly surfaces: readonly {
+        readonly file: string;
+        readonly role: ConfigSurface["role"];
+        readonly example: boolean;
+        readonly declared: number;
+    }[];
+    readonly reads: {
+        /** File nodes carrying `attrs.envReads`. */
+        readonly filesWithReads: number;
+        /** File nodes carrying none — the size of the region no adapter described. */
+        readonly filesWithoutReads: number;
+        /** Variables read through an accessor that fails when they are absent. */
+        readonly required: number;
+        /**
+         * Variables read through an accessor that yields absent instead.
+         *
+         * Not "optional" — *unknown at this resolution*. Whether the code copes
+         * depends on what happens to the value afterwards, which is dataflow.
+         */
+        readonly undetermined: number;
+        /** Reads through a computed name. A count, never a guessed name. */
+        readonly dynamic: number;
+    };
+    /** Null when no read existed at all, so the guard could not be evaluated. */
+    readonly coverage: CoverageGuard | null;
+    /** Declared and never read anywhere. A dead-configuration lead, not reported. */
+    readonly declaredNeverRead: number;
+    /** True when at least one adapter supplied env reads. */
+    readonly readsAvailable: boolean;
+}
+export interface EnvCheckOptions {
+    /**
+     * Minimum fraction of the variables the code names that the repository must
+     * declare before any read-side finding is emitted.
+     *
+     * **Picked before it was measured, per the gates rule.** A repository
+     * declaring fewer than this is telling you its configuration is elsewhere.
+     */
+    readonly coverageFloor?: number;
+    /** Rule 5's cap. Overflow is disclosed, never dropped quietly. */
+    readonly maxFindings?: number;
+    /**
+     * Restrict the read side to these repo-relative files — §15.1's *"against the
+     * scoped subgraph"*. Absent means the whole graph, and the report says which.
+     */
+    readonly files?: readonly string[];
+    /** Cap on file nodes enumerated. Truncation is reported. */
+    readonly limit?: number;
+}
+export declare const DEFAULT_COVERAGE_FLOOR = 0.6;
+/**
+ * Pull `attrs.envReads` off a file node, refusing anything malformed.
+ *
+ * `attrs` is opaque above the boundary and is written by code this engine does
+ * not own, so every field is checked. A row missing `required` is **dropped, not
+ * defaulted**: defaulting it to `true` would manufacture a requirement claim
+ * from an adapter that never made one, and that claim is the whole check.
+ */
+export declare function readEnvReads(attrs: Readonly<Record<string, unknown>>, file: string, resolution: ResolutionLevel): {
+    readonly reads: readonly EnvRead[];
+    readonly dynamic: number;
+    readonly malformed: number;
+};
+export declare function checkEnvironment(provider: AdjacencyProvider, scan: SurfaceScan, options?: EnvCheckOptions): QueryResult<EnvReport>;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/validation/env.ts"],"names":[],"mappings":"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"}