@descryy/core 0.1.0

package/dist/tiers/ladder.js

@@ -0,0 +1,197 @@
+/**
+ * The four capability tiers of §11A.11, expressed as requirements a machine can
+ * check — and the ones it cannot, named as such.
+ *
+ * ## Why this file exists at all
+ *
+ * Nine adapters state a tier in a doc comment. **DEC-075 §6 says a tier is
+ * generated from `capabilities()` and the gate results, never written in
+ * prose**, and until now nothing implemented that, so the only tier claims in
+ * the repository were the ones a human typed. That is the single piece of
+ * standing dishonesty in the codebase: a claim about what works for a language,
+ * made by the person who wanted it to be true, in a comment nothing checks.
+ *
+ * ## The ladder, from §11A.11
+ *
+ * | tier | what works | what it costs |
+ * | --- | --- | --- |
+ * | **S — Full** | contract *shape* matching, data propagation, oracle-derived tests | R3 + router extractor + ORM extractor |
+ * | **A — Contract** | endpoint matching, path-level orphans, migration DAG | R2/R3 + router extractor |
+ * | **B — Graph** | blast radius, impact scoring, test discovery, in-language root cause | R2 adapter |
+ * | **C — Signal** | env/config, rollback readiness, hidden dependency, file-level blast radius | R0, one grammar and one query set |
+ *
+ * A tier is **cumulative**: S implies A implies B implies C. So a language is
+ * awarded the highest tier whose requirements are *all* met, and the
+ * requirements of every tier below it are re-checked rather than assumed —
+ * because an adapter can reach R3 and still not emit a `FUNCTION`, and a ladder
+ * that assumed monotonicity would hand it an A on the strength of its routes.
+ *
+ * ## What a requirement may be
+ *
+ * Three kinds, and the split is the honest part:
+ *
+ * - **`capability`** — read straight off `capabilities()`. Machine-checked, no
+ *   judgement. `capabilities()` is itself machine-checked against what the
+ *   adapter actually emitted (DEC-070), so this is evidence, not a promise.
+ * - **`conformance`** — the corpus passes at the resolution the tier claims.
+ *   Machine-checked by running the harness.
+ * - **`attested`** — a fact no machine in this repository can establish, so it
+ *   is *declared* with its evidence and marked as declared. There is exactly
+ *   one, and it is DEC-075's second condition: a ≥200-edge precision draw on
+ *   two repositories **the adapter's author did not choose**. A machine can
+ *   check the 200 and the two; it cannot check "did not choose", which is a
+ *   fact about a person's intent. Recording it as attested is what stops the
+ *   generator laundering a human judgement into a computed result.
+ */
+/** Highest first. The order the generator walks, and the only place it lives. */
+export const TIERS = ["S", "A", "B", "C"];
+// ---------------------------------------------------------------------------
+// There is deliberately no list of framework names here.
+//
+// The first version of this file carried three: ROUTER_EXTRACTORS with
+// `express`, `fastapi`, `flask`, `django`; ORM_EXTRACTORS with `sqlalchemy`,
+// `prisma`, `gorm`; SCHEMA_EXTRACTORS with `pydantic`, `zod`. The boundary lint
+// rejected all twelve, and it was right on the merits rather than pedantic:
+// **that is engine code above the Canonical IR knowing what a Python web
+// framework is called**, which is rule 1, and a list that must grow every time
+// anyone writes an extractor is the shape rule 1 exists to prevent.
+//
+// The fix is not an allowlist entry. It is that the requirement was
+// **redundant**. "A router extractor is bound" was asking, indirectly, whether
+// the adapter can produce routes — and the requirement immediately above it
+// already asks that directly, in vocabulary terms: does it emit `API_ROUTE`,
+// `API_ENDPOINT` and `SERVES_API`. An adapter emitting those has a router
+// extractor by definition, whatever it is called, and one that does not cannot
+// be rescued by a name in `frameworkExtractors`. The same held for the ORM
+// requirement against `MODEL`/`READS`/`WRITES`, and for the schema requirement
+// against `DTO`/`USES_TYPE`.
+//
+// So the name check bought nothing and cost the boundary. Deleting it changed
+// no adapter's tier, which is the evidence that it was never load-bearing.
+//
+// The general form, worth keeping: **when engine code needs to know what a
+// framework is, ask what it produced.** The vocabulary is the shared language
+// precisely so the engine never has to learn a framework's name.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// The ladder itself.
+// ---------------------------------------------------------------------------
+const C_REQUIREMENTS = [
+    {
+        id: "C.parses",
+        kind: "capability",
+        statement: "the adapter produces a file-level graph",
+        // `MODULE`, not `FILE`. The vocabulary has both, and this requirement first
+        // asked for both — at which point every adapter in the repository failed
+        // Tier C. Checked against a real run rather than assumed: **no adapter
+        // emits or declares `FILE`**, and `MODULE` is what a file resolves to in
+        // all nine. A requirement no producer can satisfy does not make a generator
+        // strict, it makes it useless, and the ladder would have been "corrected"
+        // by whoever needed a tier first.
+        nodeTypes: ["MODULE"],
+    },
+    {
+        id: "C.corpus-r0",
+        kind: "conformance",
+        statement: "the conformance corpus passes at R0",
+        minResolution: 0,
+    },
+];
+const B_REQUIREMENTS = [
+    {
+        id: "B.declarations",
+        kind: "capability",
+        statement: "declarations and calls are resolved, so blast radius has edges to walk",
+        nodeTypes: ["FUNCTION", "CLASS"],
+        edgeTypes: ["CALLS", "IMPORTS"],
+    },
+    {
+        id: "B.tests",
+        kind: "capability",
+        statement: "tests are discoverable, which is what makes impact scoring actionable",
+        nodeTypes: ["TEST_CASE"],
+        edgeTypes: ["TESTS"],
+    },
+    {
+        id: "B.r2",
+        kind: "capability",
+        statement: "the adapter reaches R2 — references resolved, not only parsed",
+        minResolution: 2,
+    },
+    {
+        id: "B.corpus-r2",
+        kind: "conformance",
+        statement: "the conformance corpus passes at R2",
+        minResolution: 2,
+    },
+];
+const A_REQUIREMENTS = [
+    {
+        id: "A.routes",
+        kind: "capability",
+        statement: "routes are emitted from source and joined to the shared endpoint node",
+        nodeTypes: ["API_ROUTE", "API_ENDPOINT"],
+        edgeTypes: ["SERVES_API"],
+    },
+    {
+        id: "A.callers",
+        kind: "capability",
+        statement: "a caller reaches an endpoint through USES_API, which is the other half of the join",
+        edgeTypes: ["USES_API"],
+    },
+    {
+        id: "A.precision-draw",
+        kind: "attested",
+        statement: "a >=200-edge precision draw passes on two repositories the adapter's author did not choose (DEC-075 §6.2)",
+    },
+];
+const S_REQUIREMENTS = [
+    {
+        id: "S.r3",
+        kind: "capability",
+        statement: "the adapter reaches R3 — shapes, not only names, which is what shape matching compares",
+        minResolution: 3,
+    },
+    {
+        id: "S.shapes",
+        kind: "capability",
+        statement: "transport shapes are emitted, so a caller's body can be compared against a route's",
+        nodeTypes: ["DTO"],
+        edgeTypes: ["USES_TYPE"],
+    },
+    {
+        id: "S.persistence",
+        kind: "capability",
+        statement: "models and their storage are in the graph, so propagation reaches the database",
+        nodeTypes: ["MODEL"],
+        edgeTypes: ["READS", "WRITES"],
+    },
+    {
+        id: "S.corpus-r3",
+        kind: "conformance",
+        statement: "the conformance corpus passes at R3",
+        minResolution: 3,
+    },
+];
+export const LADDER = [
+    { tier: "C", name: "Signal", requires: C_REQUIREMENTS },
+    { tier: "B", name: "Graph", requires: B_REQUIREMENTS },
+    { tier: "A", name: "Contract", requires: A_REQUIREMENTS },
+    { tier: "S", name: "Full", requires: S_REQUIREMENTS },
+];
+/**
+ * Every requirement a tier needs, including the tiers beneath it.
+ *
+ * Cumulative and re-checked rather than assumed — see the header. `C` is the
+ * floor, so `requirementsFor("C")` is C's own list.
+ */
+export function requirementsFor(tier) {
+    const order = ["C", "B", "A", "S"];
+    const upTo = order.indexOf(tier);
+    if (upTo < 0)
+        throw new Error(`unknown tier ${tier}`);
+    return order
+        .slice(0, upTo + 1)
+        .flatMap((t) => LADDER.find((d) => d.tier === t)?.requires ?? []);
+}
+//# sourceMappingURL=ladder.js.map

package/dist/tiers/ladder.js.map

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

package/dist/validation/config-graph.d.ts

@@ -0,0 +1,104 @@
+/**
+ * §15.3's config dependency graph — *"track env vars, secrets, flags, config
+ * files and what uses them"*, and the row whose note reads *"feeds the
+ * deploy-target check"*.
+ *
+ * ## This is a query, not a check, and the distinction is the design
+ *
+ * Checks 1 and 2 emit findings. This one emits **structure**: for every variable
+ * the repository knows about, where it is declared, where it is read, and what
+ * transitively depends on the files that read it. §15.3 says it feeds check 1,
+ * and that is exactly what it is for — a missing variable read by a module forty
+ * others import is a different sentence from one read by a single script, and
+ * until now the check had no way to tell them apart.
+ *
+ * Because it produces no findings of its own, it has **no precision gate of its
+ * own**, and that is stated rather than quietly skipped. Its correctness rests
+ * entirely on the `IMPORTS` edges beneath it, whose precision is already gated
+ * elsewhere. What this module can get wrong on its own is the *join* — attaching
+ * the wrong file to a variable — and that is what its bench exercises.
+ *
+ * ## No new vocabulary, which is the whole reason it is shaped this way
+ *
+ * *"New capabilities are new queries over these edges, not new types."* A
+ * variable still has no node (DEC-120). The dependent set is `scopeChange`
+ * seeded with the **file that reads the variable** — impact flowing outward from
+ * a changed file is precisely the existing traversal, with its budgets, its decay
+ * scoring and its truncation disclosure already correct.
+ *
+ * Taking the scope rather than re-deriving it is deliberate: a second traversal
+ * with its own rules would drift from the one the rest of the engine uses, and
+ * the first symptom would be two different blast radiuses for the same file.
+ *
+ * ## Why R1, and what it degrades to
+ *
+ * Reaching *"what depends on this"* needs module resolution — `IMPORTS` edges
+ * that actually resolve. At R0 there are none, so the dependent set is empty and
+ * the report says the graph carried no import edges rather than reporting zero
+ * dependents as a fact. **An empty dependent set from a graph with no imports and
+ * an empty one from a genuinely unimported module are different statements**, and
+ * only the second is information.
+ *
+ * ## The completeness fence
+ *
+ * Every count here is *what this graph can see* and is worded that way. NFR-9's
+ * rule, and §15.3's own instruction for the neighbouring DB-impact check —
+ * *"output must state what the tool can see, never implying completeness"* —
+ * applies with equal force: a dependent set is a lower bound, always.
+ */
+import type { AdjacencyProvider, QueryResult } from "../query/provider.ts";
+import type { SurfaceScan } from "./sources.ts";
+export interface ConfigDeclaration {
+    readonly file: string;
+    readonly line: number;
+    readonly commented: boolean;
+    readonly role: "declaration" | "deployTarget";
+}
+export interface ConfigReadSite {
+    readonly file: string;
+    readonly line: number;
+    /** The read fails when the variable is unset — DEC-121's discriminator. */
+    readonly required: boolean;
+}
+export interface ConfigVariable {
+    readonly name: string;
+    readonly declaredAt: readonly ConfigDeclaration[];
+    readonly readAt: readonly ConfigReadSite[];
+    /**
+     * Files that transitively depend on a file reading this variable, as far as
+     * this graph can see.
+     *
+     * **A lower bound, never a total.** Null when the dependent set could not be
+     * computed at all — no reading file is in the graph, or the graph carries no
+     * import edges — which is not the same as zero.
+     */
+    readonly dependents: number | null;
+    /** A few dependent files, for a reader who wants to look. */
+    readonly dependentSample: readonly string[];
+    /** True when the traversal's budget stopped it short. */
+    readonly dependentsTruncated: boolean;
+}
+export interface ConfigGraph {
+    readonly variables: readonly ConfigVariable[];
+    /** Variables named by a declaration, a read, or both. */
+    readonly counts: {
+        readonly total: number;
+        readonly declaredOnly: number;
+        readonly readOnly: number;
+        readonly both: number;
+        /** Variables whose dependent set could be computed at all. */
+        readonly withDependents: number;
+    };
+    /** True when the graph carried at least one resolved import edge. */
+    readonly importsAvailable: boolean;
+}
+export interface ConfigGraphOptions {
+    /** Cap on variables whose dependent set is computed. Traversal is not free. */
+    readonly maxTraversals?: number;
+    /** Cap on file nodes enumerated. */
+    readonly limit?: number;
+    /** Budget handed to each dependent traversal. */
+    readonly budget?: number;
+}
+export declare function buildConfigGraph(provider: AdjacencyProvider, scan: SurfaceScan, options?: ConfigGraphOptions): QueryResult<ConfigGraph>;
+//# sourceMappingURL=config-graph.d.ts.map

package/dist/validation/config-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-graph.d.ts","sourceRoot":"","sources":["../../src/validation/config-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAc,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,8DAA8D;QAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAAC,WAAW,CAAC,CAgL1B"}

package/dist/validation/config-graph.js

@@ -0,0 +1,205 @@
+/**
+ * §15.3's config dependency graph — *"track env vars, secrets, flags, config
+ * files and what uses them"*, and the row whose note reads *"feeds the
+ * deploy-target check"*.
+ *
+ * ## This is a query, not a check, and the distinction is the design
+ *
+ * Checks 1 and 2 emit findings. This one emits **structure**: for every variable
+ * the repository knows about, where it is declared, where it is read, and what
+ * transitively depends on the files that read it. §15.3 says it feeds check 1,
+ * and that is exactly what it is for — a missing variable read by a module forty
+ * others import is a different sentence from one read by a single script, and
+ * until now the check had no way to tell them apart.
+ *
+ * Because it produces no findings of its own, it has **no precision gate of its
+ * own**, and that is stated rather than quietly skipped. Its correctness rests
+ * entirely on the `IMPORTS` edges beneath it, whose precision is already gated
+ * elsewhere. What this module can get wrong on its own is the *join* — attaching
+ * the wrong file to a variable — and that is what its bench exercises.
+ *
+ * ## No new vocabulary, which is the whole reason it is shaped this way
+ *
+ * *"New capabilities are new queries over these edges, not new types."* A
+ * variable still has no node (DEC-120). The dependent set is `scopeChange`
+ * seeded with the **file that reads the variable** — impact flowing outward from
+ * a changed file is precisely the existing traversal, with its budgets, its decay
+ * scoring and its truncation disclosure already correct.
+ *
+ * Taking the scope rather than re-deriving it is deliberate: a second traversal
+ * with its own rules would drift from the one the rest of the engine uses, and
+ * the first symptom would be two different blast radiuses for the same file.
+ *
+ * ## Why R1, and what it degrades to
+ *
+ * Reaching *"what depends on this"* needs module resolution — `IMPORTS` edges
+ * that actually resolve. At R0 there are none, so the dependent set is empty and
+ * the report says the graph carried no import edges rather than reporting zero
+ * dependents as a fact. **An empty dependent set from a graph with no imports and
+ * an empty one from a genuinely unimported module are different statements**, and
+ * only the second is information.
+ *
+ * ## The completeness fence
+ *
+ * Every count here is *what this graph can see* and is worded that way. NFR-9's
+ * rule, and §15.3's own instruction for the neighbouring DB-impact check —
+ * *"output must state what the tool can see, never implying completeness"* —
+ * applies with equal force: a dependent set is a lower bound, always.
+ */
+import { scopeChange } from "../scoping/traverse.js";
+import { readEnvReads } from "./env.js";
+import { fileScopedNodes } from "./nodes.js";
+const DEFAULT_MAX_TRAVERSALS = 50;
+const DEFAULT_BUDGET = 200;
+const SAMPLE = 5;
+export function buildConfigGraph(provider, scan, options = {}) {
+    const maxTraversals = options.maxTraversals ?? DEFAULT_MAX_TRAVERSALS;
+    const budget = options.budget ?? DEFAULT_BUDGET;
+    const notes = [];
+    // --- declarations, from the repository -----------------------------------
+    const declarations = new Map();
+    for (const surface of scan.surfaces) {
+        for (const declaration of surface.declarations) {
+            let bucket = declarations.get(declaration.name);
+            if (bucket === undefined)
+                declarations.set(declaration.name, (bucket = []));
+            bucket.push({
+                file: surface.file,
+                line: declaration.line,
+                commented: declaration.commented,
+                role: surface.role,
+            });
+        }
+    }
+    // --- reads, from the graph -----------------------------------------------
+    const files = fileScopedNodes(provider, options.limit);
+    const reads = new Map();
+    const readingFile = new Map();
+    let importEdges = 0;
+    for (const node of files.nodes) {
+        const path = node.file;
+        if (path === null)
+            continue;
+        // Counted across every file, not only the reading ones: "this graph has no
+        // import edges" is a property of the graph, and sampling it from the files
+        // that happen to read configuration would be a property of those files.
+        importEdges += provider.outgoing(node.id, { types: ["IMPORTS"], limit: 1 }).length;
+        const extracted = readEnvReads(node.attrs, path, node.resolution);
+        if (extracted.reads.length === 0)
+            continue;
+        readingFile.set(path, node);
+        for (const read of extracted.reads) {
+            let bucket = reads.get(read.name);
+            if (bucket === undefined)
+                reads.set(read.name, (bucket = []));
+            bucket.push({ file: read.file, line: read.line, required: read.required });
+        }
+    }
+    const importsAvailable = importEdges > 0;
+    // --- assemble, and traverse for the ones worth traversing ----------------
+    const names = [...new Set([...declarations.keys(), ...reads.keys()])].sort();
+    const variables = [];
+    let declaredOnly = 0;
+    let readOnly = 0;
+    let both = 0;
+    let withDependents = 0;
+    let traversals = 0;
+    let floor = 4;
+    let anyTruncated = false;
+    // Variables with a read site come first: a dependent set is only meaningful
+    // for one with a reading file, and the traversal budget should not be spent on
+    // declarations nothing reads.
+    const ordered = names.sort((a, b) => {
+        const ar = reads.has(a) ? 0 : 1;
+        const br = reads.has(b) ? 0 : 1;
+        return ar - br || a.localeCompare(b);
+    });
+    for (const name of ordered) {
+        const declaredAt = declarations.get(name) ?? [];
+        const readAt = reads.get(name) ?? [];
+        if (declaredAt.length > 0 && readAt.length > 0)
+            both += 1;
+        else if (declaredAt.length > 0)
+            declaredOnly += 1;
+        else
+            readOnly += 1;
+        let dependents = null;
+        let dependentSample = [];
+        let truncated = false;
+        const seeds = readAt
+            .map((site) => readingFile.get(site.file))
+            .filter((node) => node !== undefined)
+            .map((node) => node.id);
+        if (seeds.length > 0 && importsAvailable && traversals < maxTraversals) {
+            traversals += 1;
+            const scope = scopeChange(provider, [...new Set(seeds)], { budget });
+            // `changed` is the seed set itself — the files that read the variable —
+            // so the dependent count is `affected` alone. Including the seeds would
+            // report a variable read in one file as having one dependent.
+            const affected = scope.data.affected;
+            dependents = affected.length;
+            dependentSample = affected
+                .map((entry) => entry.node.file)
+                .filter((file) => file !== null)
+                .slice(0, SAMPLE);
+            truncated = scope.truncated || scope.data.dropped.length > 0;
+            if (truncated)
+                anyTruncated = true;
+            if (scope.stamp.resolutionFloor < floor)
+                floor = scope.stamp.resolutionFloor;
+            withDependents += 1;
+        }
+        variables.push({
+            name,
+            declaredAt,
+            readAt,
+            dependents,
+            dependentSample,
+            dependentsTruncated: truncated,
+        });
+    }
+    variables.sort((a, b) => (b.dependents ?? -1) - (a.dependents ?? -1) || a.name.localeCompare(b.name));
+    // --- disclosures ---------------------------------------------------------
+    if (!importsAvailable) {
+        notes.push("No resolved import edge is in this graph, so no dependent set could be computed for any " +
+            "variable. Every dependent count is reported as unknown rather than as zero: a module " +
+            "nothing imports and a graph that resolved no imports produce the same empty set, and " +
+            "only the first is information. This needs R1 — module resolution — which the producer " +
+            "did not reach.");
+    }
+    if (reads.size === 0) {
+        notes.push("No file in the graph carries environment reads, so this graph describes declarations only " +
+            "and nothing about what uses them. The engine reads attrs.envReads on a file-scoped node.");
+    }
+    if (traversals >= maxTraversals) {
+        notes.push(`Dependent sets were computed for the first ${maxTraversals} variable(s) with a read ` +
+            "site; the rest carry an unknown dependent count rather than zero. Raise " +
+            '"maxTraversals" to widen it.');
+    }
+    if (anyTruncated) {
+        notes.push("At least one dependent traversal hit its budget, so those counts are a floor rather than a " +
+            "total. The dropped nodes were the lowest-scoring ones reached.");
+    }
+    if (files.truncated) {
+        notes.push("More files exist in the graph than were enumerated, so this covers a prefix of the " +
+            "repository rather than all of it.");
+    }
+    notes.push("Every dependent count is what this graph can see, and is a lower bound. A consumer in a " +
+        "language with no adapter, in another repository, or reached through a call this analysis " +
+        "could not resolve does not appear here.");
+    const stamp = {
+        ...provider.baseStamp(),
+        resolutionFloor: withDependents === 0 ? 1 : floor,
+    };
+    return {
+        data: {
+            variables,
+            counts: { total: names.length, declaredOnly, readOnly, both, withDependents },
+            importsAvailable,
+        },
+        stamp,
+        truncated: files.truncated || anyTruncated,
+        notes,
+    };
+}
+//# sourceMappingURL=config-graph.js.map

package/dist/validation/config-graph.js.map

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