@maverickcer/env-cap 0.2.0

package/dist/.dts/build/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/build/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAyB,MAAM,qBAAqB,CAAA;AACvF,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAe5D,6YAA6Y;AAC7Y,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AACD,4JAA4J;AAC5J,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AACD,wGAAwG;AACxG,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,+FAA+F;IAC/F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,iNAAiN;IACjN,QAAQ,CAAC,qBAAqB,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAClE,sKAAsK;IACtK,QAAQ,CAAC,qBAAqB,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAClE,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAA;IAC1B,2GAA2G;IAC3G,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAG5D;AASD,sVAAsV;AACtV,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE,CAAA;CAChG;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,qBAAqB,EAAE,EAC3C,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,IAAI,GACR,aAAa,EAAE,CA2DjB;AAED;;;;;;;GAOG;AACH,UAAU,eAAgB,SAAQ,mBAAmB;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,2NAA2N;IAC3N,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,0JAA0J;IAC1J,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,CAAA;CAC1D;AAED,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C;iFAC6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;CAC9D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAAG,eAAe,EAAE,CAwC3F;AASD,uHAAuH;AACvH,wBAAgB,+BAA+B,CAAC,eAAe,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAapF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,eAAe,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAehF;AAidD,2GAA2G;AAC3G,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;IAC1C,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAA;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAA;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAA;IAC3C,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;IAC1C,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;CAC3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,qBAAqB,EAAE,EAC3C,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,IAAI,EACT,yBAAyB,EAAE,MAAM,EACjC,yBAAyB,EAAE,MAAM,GAChC,sBAAsB,CAoDxB;AAsCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,qBAAqB,EAAE,EAC3C,OAAO,EAAE,iBAAiB,GACzB,MAAM,CA2BR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOlE"}

package/dist/.dts/build/env-example.d.ts

@@ -0,0 +1,85 @@
+import type { DiscoveredContract } from "./link.js";
+import type { BuildFileSystem } from "./types.js";
+/**
+ * Controls what happens when a `.env.example` already exists at the target
+ * location. `"keep-sibling"` (default): never touch the existing file --
+ * write a timestamped sibling instead, for the developer to diff/merge
+ * manually. `"overwrite"`: replace the existing file with freshly rendered
+ * content directly. `"skip"`: write nothing at all.
+ */
+export type EnvExampleOnExisting = "keep-sibling" | "overwrite" | "skip";
+/** The result of a completed {@link writeEnvExample} call. */
+export interface EnvExampleResult {
+    /**
+     * Where the example file actually got written. `undefined` only when
+     * `onExisting: "skip"` left an existing file untouched and nothing was
+     * written.
+     */
+    readonly writtenPath: string | undefined;
+    /**
+     * Set when a file already existed at the requested location and was left
+     * untouched: with the default `"keep-sibling"`, `writtenPath` is a fresh
+     * timestamped sibling instead; with `"skip"`, this is the only outcome and
+     * `writtenPath` is `undefined`. Always `undefined` with `"overwrite"`.
+     */
+    readonly skippedExistingPath: string | undefined;
+    /** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
+    readonly staleVariables: readonly string[];
+    /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs -- safe to comment out. */
+    readonly variablesToComment: readonly string[];
+    /** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
+    readonly variablesToAdd: readonly string[];
+}
+/** The result of {@link computeReconciliation}: an existing `.env.example` diffed against the current configuration. */
+export interface Reconciliation {
+    /** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
+    readonly staleVariables: readonly string[];
+    /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs -- safe to comment out. */
+    readonly variablesToComment: readonly string[];
+    /** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
+    readonly variablesToAdd: readonly string[];
+}
+/**
+ * Renders a deterministic `.env.example`-style file scoped to the *current*
+ * configuration: every unique variable the active contracts require (one
+ * live entry per key, alphabetical; a key declared by more than one active
+ * contract renders once live and the rest commented-out with a pointer),
+ * followed by variables unique to disabled contracts (commented-out, for
+ * visibility -- a key already required by an active contract is not unique
+ * and never repeated here). `reconciliationHeader`, when non-empty, is
+ * spliced in right after the banner (see `computeReconciliation`).
+ */
+export declare function renderEnvExample(contracts: readonly DiscoveredContract[], reconciliationHeader?: readonly string[]): string;
+/** Parses `KEY=value` lines out of an existing `.env`-style file, ignoring comments and blank lines. */
+export declare function extractDeclaredVariables(source: string): string[];
+/** Parses `# KEY=value` lines out of an existing `.env`-style file -- variables it already knows about but has turned off. */
+export declare function extractCommentedVariables(source: string): string[];
+/**
+ * Diffs an existing `.env.example` against the current configuration into
+ * three actionable sets. Pure and filesystem-independent -- `writeEnvExample`
+ * is the only caller that reads the file itself.
+ */
+export declare function computeReconciliation(contracts: readonly DiscoveredContract[], existingContent: string): Reconciliation;
+/**
+ * Writes a rendered `.env.example` to `location`. Behavior when a file
+ * already exists there is governed by `options.onExisting` (default
+ * `"keep-sibling"`, see `EnvExampleOnExisting`):
+ *  - `"keep-sibling"`: the existing file is left alone; freshly generated
+ *    content is written to a timestamped sibling instead
+ *    (`<location>.<epoch-ms>`), prefixed with a reconciliation header
+ *    comparing it against the existing file (omitted when there's nothing
+ *    to report).
+ *  - `"overwrite"`: the existing file is replaced directly with freshly
+ *    rendered content -- no reconciliation header (the changes it would
+ *    describe are already applied).
+ *  - `"skip"`: nothing is written.
+ * When no file exists yet at `location`, all three modes behave the same:
+ * write fresh content, nothing to reconcile against. `staleVariables`/
+ * `variablesToComment`/`variablesToAdd` are always computed and returned
+ * when a prior file existed, even under `"overwrite"`/`"skip"`, as a
+ * diagnostic -- independent of whether anything was actually written.
+ */
+export declare function writeEnvExample(contracts: readonly DiscoveredContract[], location: string, fs: BuildFileSystem, options?: {
+    onExisting?: EnvExampleOnExisting;
+}): Promise<EnvExampleResult>;
+//# sourceMappingURL=env-example.d.ts.map

package/dist/.dts/build/env-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-example.d.ts","sourceRoot":"","sources":["../../../src/build/env-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,GAAG,MAAM,CAAA;AAExE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,yJAAyJ;IACzJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,yJAAyJ;IACzJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAqED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAwER;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBjE;AAED,8HAA8H;AAC9H,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,eAAe,EAAE,MAAM,GACtB,cAAc,CAkBhB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAClD,OAAO,CAAC,gBAAgB,CAAC,CA+D3B"}

package/dist/.dts/build/errors.d.ts

@@ -0,0 +1,78 @@
+import type { CompatibilityIssue } from "./compatibility.js";
+/**
+ * Thrown by {@link generateEnvManifest} on a blocking compatibility/exclusive-group
+ * finding, or an output path escaping `root`.
+ *
+ * @remarks
+ * Nothing is written when this throws -- generation fails atomically, same as
+ * {@link runtime.validateEnv} fails atomically at runtime.
+ *
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
+ */
+export declare class EnvManifestGenerationError extends Error {
+    /** Stable discriminant for programmatic handling; always `"ENV_MANIFEST_GENERATION_FAILED"`. */
+    readonly code = "ENV_MANIFEST_GENERATION_FAILED";
+    /** Every blocking finding, aggregated. */
+    readonly issues: readonly CompatibilityIssue[];
+    constructor(issues: readonly CompatibilityIssue[]);
+}
+/**
+ * Thrown by {@link generateDocumentation} on a blocking undocumented-contract/
+ * variable finding (when `onUndocumented: "throw"`), or an output path
+ * (`location`/`envExample.location`) escaping `root`. Nothing is written
+ * when this throws.
+ *
+ * @remarks
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
+ */
+export declare class EnvDocumentationGenerationError extends Error {
+    /** Stable discriminant for programmatic handling; always `"ENV_DOCUMENTATION_GENERATION_FAILED"`. */
+    readonly code = "ENV_DOCUMENTATION_GENERATION_FAILED";
+    /** Every blocking finding, aggregated. */
+    readonly issues: readonly CompatibilityIssue[];
+    constructor(issues: readonly CompatibilityIssue[]);
+}
+/**
+ * Thrown by {@link generateUsageReport} on a blocking abandoned-contract/
+ * unconsumed-owned-variable finding (when `onOwnershipIssue: "throw"`), or an
+ * output path (`report.location`) escaping `root`.
+ *
+ * @remarks
+ * Never thrown for `unresolvedConsumers` or `indeterminate` findings -- both are "we don't
+ * know" states, and uncertainty is never promoted to a failure.
+ *
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
+ */
+export declare class EnvUsageAnalysisError extends Error {
+    /** Stable discriminant for programmatic handling; always `"ENV_USAGE_ANALYSIS_FAILED"`. */
+    readonly code = "ENV_USAGE_ANALYSIS_FAILED";
+    /** Every blocking finding, aggregated. */
+    readonly issues: readonly CompatibilityIssue[];
+    constructor(issues: readonly CompatibilityIssue[]);
+}
+/**
+ * Thrown by {@link generateEnvArtifacts} when any requested pass (manifest/docs/usage)
+ * reports a blocking finding, aggregated across all requested passes into
+ * one error.
+ *
+ * @remarks
+ * Nothing from any pass is written when this throws -- see
+ * `generate-env-artifacts.ts`'s compute-atomic guarantee (ADR 0011). Write-phase failures
+ * (a real I/O error after all computes already passed) are NOT wrapped in
+ * this type -- they propagate as whatever `fs.writeFile` itself throws,
+ * since by that point some artifacts may already be on disk.
+ *
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
+ */
+export declare class EnvProjectGenerationError extends Error {
+    /** Stable discriminant for programmatic handling; always `"ENV_PROJECT_GENERATION_FAILED"`. */
+    readonly code = "ENV_PROJECT_GENERATION_FAILED";
+    /** Every blocking finding, aggregated across all requested passes. */
+    readonly issues: readonly CompatibilityIssue[];
+    constructor(issues: readonly CompatibilityIssue[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/.dts/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/build/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAmB5D;;;;;;;;;;GAUG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,gGAAgG;IAChG,QAAQ,CAAC,IAAI,oCAAmC;IAChD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAelD;AAED;;;;;;;;;GASG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,qGAAqG;IACrG,QAAQ,CAAC,IAAI,yCAAwC;IACrD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAelD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,+BAA8B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAWlD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,mCAAkC;IAC/C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAQlD"}

package/dist/.dts/build/evidence-cache.d.ts

@@ -0,0 +1,74 @@
+import type { EvidenceModel } from "./evidence-model.js";
+import type { GenerateEvidenceModelOptions } from "./generate-evidence.js";
+import type { BuildFileSystem } from "./types.js";
+/**
+ * A fast, honest read path for the persisted evidence artifact -- for a
+ * report/projection script, a CI step, or any consumer that just wants the
+ * current `EvidenceModel` without paying a full `generateEvidenceModel()`
+ * recompute (schema parsing, cross-file linking, the dependency-graph AST
+ * scan, all six model builds) on every single invocation, and without ever
+ * risking silently-stale data. The mechanism: a cheap content fingerprint,
+ * computed from raw file bytes with zero AST work, lets a caller cheaply
+ * prove "nothing relevant to evidence generation has changed since this file
+ * was last written" before trusting it.
+ */
+/** Options for {@link computeSourceFingerprint}. */
+export interface ComputeSourceFingerprintOptions {
+    /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
+    readonly fs: BuildFileSystem;
+    readonly root: string;
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+    readonly packages: readonly string[];
+}
+/**
+ * SHA-256 over the raw bytes of every schema file and every usage-scan-
+ * surface file (the same file sets `assembleProject()`/`computeScanSurface()`
+ * touch), plus env-cap's own installed version -- zero AST parsing or
+ * linking. Still requires the discovery/glob walk itself (fingerprinting has
+ * to know which files matter), but skips everything after it. Deterministic:
+ * file paths are deduplicated and sorted before hashing, so the result never
+ * depends on filesystem enumeration order.
+ *
+ * @remarks
+ * Not a timestamp, and never compared as one -- a fresh mtime doesn't prove
+ * content is unchanged (a checkout, a rebase, or a touch can all bump it
+ * with no real edit), and content is the only thing that actually
+ * invalidates a cached evidence artifact.
+ */
+export declare function computeSourceFingerprint(options: ComputeSourceFingerprintOptions): Promise<string>;
+/** Writes `fingerprint`'s paired sidecar for `evidencePath` -- call immediately after writing the evidence artifact itself, so the two files always describe the same moment in the source tree's history. */
+export declare function writeEvidenceFingerprint(evidencePath: string, fingerprint: string, fs: BuildFileSystem): Promise<void>;
+/** Options for {@link getEvidenceModel} -- every `generateEvidenceModel()` option, plus where the cached artifact lives. */
+export interface GetEvidenceModelOptions extends GenerateEvidenceModelOptions {
+    /** Where the cached evidence artifact (and its `.fingerprint` sidecar) live, e.g. `docs/env.evidence.json`, relative to `root`. Required -- there is no honest default env-cap could guess at for where a project keeps this. */
+    readonly location: string;
+}
+/** The result of {@link getEvidenceModel}. */
+export interface GetEvidenceModelResult {
+    readonly evidence: EvidenceModel;
+    /** `"hit"` -- the committed evidence artifact's fingerprint matched current source; read from disk, no recompute. `"miss"` -- a real `generateEvidenceModel()` call ran. */
+    readonly source: "hit" | "miss";
+    /** Set only when `source === "miss"` -- why the cache wasn't trusted, for a caller that wants to log it. */
+    readonly missReason: string | undefined;
+}
+/**
+ * Trusts the committed evidence artifact at `options.location` only when its
+ * paired `.fingerprint` sidecar matches a freshly (cheaply) computed
+ * {@link computeSourceFingerprint} -- never on file presence alone, never on
+ * a timestamp. On any mismatch (stale fingerprint, missing/corrupt evidence
+ * file, no fingerprint sidecar at all), falls back to a real
+ * `generateEvidenceModel()` call -- never hard-fails, never silently serves
+ * data that might be stale.
+ *
+ * @remarks
+ * Never writes anything. A cache miss here does not self-heal the cache --
+ * only an explicit write (`generateEnvArtifacts()`'s `evidence` option)
+ * refreshes the committed artifact and its fingerprint together, so "when
+ * was this last regenerated" stays under explicit control, never an
+ * implicit side effect of a read. Two independent callers hitting the same
+ * stale cache both recompute independently; neither one's recompute updates
+ * the file the other reads.
+ */
+export declare function getEvidenceModel(options: GetEvidenceModelOptions): Promise<GetEvidenceModelResult>;
+//# sourceMappingURL=evidence-cache.d.ts.map

package/dist/.dts/build/evidence-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAO1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,MAAM,CAAC,CA+CjB;AAMD,8MAA8M;AAC9M,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,4HAA4H;AAC5H,MAAM,WAAW,uBAAwB,SAAQ,4BAA4B;IAC3E,iOAAiO;IACjO,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,4KAA4K;IAC5K,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAgFjC"}

package/dist/.dts/build/evidence-model.d.ts

@@ -0,0 +1,50 @@
+import type { ChangeModel } from "./change-model.js";
+import type { ContractModel } from "./contract-model.js";
+import type { DependencyModel } from "./dependency-model.js";
+import type { FindingModel } from "./finding-model.js";
+import type { LifecycleModel } from "./lifecycle-model.js";
+import type { OwnershipModel } from "./ownership-model.js";
+/**
+ * Bump only when a reader could misinterpret the new shape of `EvidenceModel`
+ * itself (not any one sub-model's own `<MODEL>_SCHEMA_VERSION`, which is
+ * versioned independently) -- same rule every other canonical model follows.
+ */
+export declare const EVIDENCE_MODEL_SCHEMA_VERSION = 1;
+/**
+ * Who/when/what produced a given `EvidenceModel` instance. Caller-supplied,
+ * never ambient-detected -- `generateEvidenceModel()` never shells out to
+ * `git` itself, mirroring ADR 0012's live-expiration-callback precedent.
+ */
+export interface EvidenceProvenance {
+    readonly generatedAt: string;
+    readonly toolVersion: string;
+    readonly commit: string | undefined;
+}
+/**
+ * The seventh canonical fact model (ADR 0024): the assembled union of the
+ * other six, plus provenance, the immutable input every
+ * `defineEvidenceProjection()` projector runs over (`env-cap/evidence`,
+ * ADR 0031).
+ *
+ * @remarks
+ * This type is the one intentional exception to `src/build/`'s zero-
+ * cross-folder-import rule: `src/evidence/` imports it with `import type`
+ * only (fully erased at compile time under `verbatimModuleSyntax`), the same
+ * shape as `helpers`' single sanctioned edge onto `runtime` -- see
+ * `specs/architecture.md`. `src/evidence/` never imports a *value* from
+ * here, only this shape, so it stays isomorphic and Node-free. An actual
+ * `EvidenceModel` instance is produced by {@link generateEvidenceModel}
+ * (`env-cap/build`, Node-only), which runs discovery once,
+ * builds all six sub-models, and `deepFreeze()`s the result.
+ */
+export interface EvidenceModel {
+    readonly schemaVersion: typeof EVIDENCE_MODEL_SCHEMA_VERSION;
+    readonly provenance: EvidenceProvenance;
+    readonly contract: ContractModel;
+    readonly dependency: DependencyModel;
+    readonly ownership: OwnershipModel;
+    readonly lifecycle: LifecycleModel;
+    readonly finding: FindingModel;
+    readonly change: ChangeModel;
+}
+//# sourceMappingURL=evidence-model.d.ts.map

package/dist/.dts/build/evidence-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-model.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAA;IAC5D,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B"}

package/dist/.dts/build/evidence-reference.d.ts

@@ -0,0 +1,67 @@
+import type { SourcePosition } from "./source-position.js";
+/**
+ * A structured pointer back to where a `Finding` (or, later, any other
+ * model's derived fact) came from -- never a formatted string. See ADR 0024
+ * and ADR 0026.
+ *
+ * @remarks
+ * Deliberately only as many `model` variants as something in this codebase
+ * actually needs to reference today (`"contract"`, `"ownership"`,
+ * `"change"`). This is an additive, growable union, not a speculative
+ * six-model union built ahead of a real consumer -- a later phase (e.g. the
+ * Dependency or Lifecycle Model) adds its own variant only once a finding
+ * or projector genuinely needs to point at it.
+ */
+export type EvidenceReference = ContractEvidenceReference | OwnershipEvidenceReference | ChangeEvidenceReference;
+/**
+ * The one shape every model in this package uses to point at a declared
+ * contract: the file it's declared in, and the binding it's exported as.
+ * Nothing else -- see ADR 0039.
+ *
+ * @remarks
+ * Deliberately *not* carrying `contractName`. A display name is a rendering
+ * concern, resolved on demand from `ContractModel` (the one model that owns
+ * it) by whichever renderer actually needs prose; duplicating it onto every
+ * reference made it a second, independently-stale copy of a fact that can
+ * change under a `documentEnv()` edit. Deliberately not carrying a
+ * pre-formatted `identity` string either -- `${file}#${exportName}` is
+ * trivially derivable, and a stored copy is one more thing that can disagree
+ * with the two fields it was built from. Code that genuinely needs a map key
+ * builds that string locally, at the point of use.
+ */
+export interface ContractRef {
+    /** Root-relative, POSIX-separated path of the file declaring the contract -- see `displayPath()`. */
+    readonly file: string;
+    /** The binding name the `createEnv()` result is exported as. */
+    readonly exportName: string;
+}
+/** Points at a declared contract and, optionally, one of its variables -- the shape every `CompatibilityIssue`/documentation finding can be resolved to. Unlike {@link ContractRef}, both identity fields are optional here: a finding can legitimately know only the file (an unresolvable `documentEnv()` link) or neither. */
+export interface ContractEvidenceReference {
+    readonly model: "contract";
+    /** Root-relative, POSIX-separated path of the file declaring the contract, when known -- see `displayPath()`. */
+    readonly file: string | undefined;
+    /** The contract's exported binding name, when known. */
+    readonly exportName: string | undefined;
+    /** The environment variable name, when the finding is variable-level rather than contract-level. */
+    readonly variable: string | undefined;
+    /** Exact file:line:column this finding is about -- the contract's `createEnv()` declaration, its `documentEnv()` declaration, or the specific variable's own declaration, whichever is most relevant to the finding. `undefined` only when no single position is more relevant than another (e.g. an `indeterminate-ownership` finding, which can have multiple candidate sites -- see `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list instead). See ADR 0036. */
+    readonly position: SourcePosition | undefined;
+}
+/** Points at a contract by name for an ownership/usage finding -- `usage-report.ts`'s finding types don't consistently carry `file`/`exportName` together, only `contractName`. */
+export interface OwnershipEvidenceReference {
+    readonly model: "ownership";
+    readonly contractName: string;
+    /** Root-relative path of the file declaring the contract, when the source finding carries one. */
+    readonly file: string | undefined;
+    /** The environment variable name, when the finding is variable-level rather than contract-level. */
+    readonly variable: string | undefined;
+    /** See {@link ContractEvidenceReference.position}. */
+    readonly position: SourcePosition | undefined;
+}
+/** Points at a generated artifact's path -- what `checkEnvArtifacts()`'s drift findings are about, not a declared contract or variable at all. */
+export interface ChangeEvidenceReference {
+    readonly model: "change";
+    /** Absolute path of the generated artifact. */
+    readonly path: string;
+}
+//# sourceMappingURL=evidence-reference.d.ts.map

package/dist/.dts/build/evidence-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-reference.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC3B,yBAAyB,GAAG,0BAA0B,GAAG,uBAAuB,CAAA;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,iUAAiU;AACjU,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,iHAAiH;IACjH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,udAAud;IACvd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,mLAAmL;AACnL,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,kJAAkJ;AAClJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}

package/dist/.dts/build/evidence-snapshot.d.ts

@@ -0,0 +1,123 @@
+import type { DynamicAccessCitationProblem } from "./citation-verification.js";
+import type { ContractRef } from "./evidence-reference.js";
+import type { ContractModelContract } from "./contract-model.js";
+import type { EvidenceModel } from "./evidence-model.js";
+import type { DiscoveredContract } from "./link.js";
+import type { ParseWarning } from "./parse.js";
+import type { DynamicAccessAssertion } from "./source-position.js";
+import type { BuildFileSystem } from "./types.js";
+/**
+ * The persisted evidence artifact and everything that reads/diffs it.
+ *
+ * Not a sibling of `env.manifest.ts`. `env.manifest.ts` is a *runtime build
+ * artifact* -- real TypeScript, imported and executed by the running
+ * application. This module's own artifact is a *CI/reporting artifact*: the
+ * literal `EvidenceModel` a caller gets back from `generateEvidenceModel()`,
+ * serialized to disk, read only by `--check`, by CI tooling, and by whatever
+ * a project's own reporting/projection code chooses to do with it -- never
+ * imported by anything under `src/runtime/`, never a build input to the
+ * application itself. Its location is never derived from a manifest's own
+ * output path (there is no `<manifest>.snapshot.json` sidecar mechanism
+ * anymore); a caller supplies it directly, independent of whether a `.ts`
+ * manifest is even being generated at all.
+ *
+ * Two jobs, one file: this is both (a) the baseline `diffContracts()`
+ * compares the current run's `ContractModel` against to produce
+ * `ManifestChangeReport`, and (b) the committed-baseline content-hash source
+ * `buildCitationSnapshots()` (`citation-verification.ts`) uses to tell a
+ * "fresh" developer dynamic-access citation from a "stale" one (ADR 0037).
+ * Whether a project commits this file to git or regenerates it fresh every CI
+ * run is that project's call -- a missing file is always treated as the normal
+ * first-run state, never an error.
+ */
+/** One field's before/after value in a {@link ManifestContractUpdate} or {@link ManifestVariableUpdate}. */
+export interface ManifestFieldChange {
+    /** The changed field's name. */
+    readonly field: string;
+    /** The value from the previous snapshot, or `undefined` if the field was unset. */
+    readonly previous: string | undefined;
+    /** The value in the current run, or `undefined` if the field is now unset. */
+    readonly current: string | undefined;
+}
+/** Identifies one contract for {@link ManifestChangeReport} purposes -- see {@link ContractRef} for why neither a `contractName` nor a pre-formatted `identity` is carried here. */
+export type ManifestContractRef = ContractRef;
+/** Identifies one variable for {@link ManifestChangeReport} purposes -- its owning contract's identity plus its own key. See {@link ContractRef}. */
+export interface ManifestVariableRef extends ContractRef {
+    /** The environment variable name. */
+    readonly key: string;
+}
+/** A contract present in both snapshots, with at least one changed field. */
+export interface ManifestContractUpdate extends ManifestContractRef {
+    /** Every field that changed between the previous and current snapshot. */
+    readonly changes: readonly ManifestFieldChange[];
+}
+/** A variable present in both snapshots, with at least one changed field. */
+export interface ManifestVariableUpdate extends ManifestVariableRef {
+    /** Every field that changed between the previous and current snapshot. */
+    readonly changes: readonly ManifestFieldChange[];
+}
+/**
+ * The result of diffing two `ContractModel.contracts` arrays -- see
+ * `diffContracts()`. Comprehensive by construction: every own field of
+ * `ContractModelContract`/`ContractModelVariable` (schema facts --
+ * `hasDefault`/`processorSource`/`validatorSource`/... -- alongside
+ * documented metadata) participates, and every discovered contract is
+ * covered, not only active ones. A field-by-field, hand-maintained diff
+ * (this module's previous design) would need updating by hand every time
+ * Contract Model gains a field; the generic differ below can't drift out of
+ * sync with the model it diffs.
+ */
+export interface ManifestChangeReport {
+    /** Contracts present now but not in the previous snapshot. */
+    readonly addedContracts: readonly ManifestContractRef[];
+    /** Contracts present in the previous snapshot but not now. */
+    readonly removedContracts: readonly ManifestContractRef[];
+    /** Variables present now but not in the previous snapshot. */
+    readonly addedVariables: readonly ManifestVariableRef[];
+    /** Variables present in the previous snapshot but not now. */
+    readonly removedVariables: readonly ManifestVariableRef[];
+    /** Contracts present in both snapshots with at least one changed field. */
+    readonly updatedContracts: readonly ManifestContractUpdate[];
+    /** Variables present in both snapshots with at least one changed field. */
+    readonly updatedVariables: readonly ManifestVariableUpdate[];
+}
+/**
+ * Pure. `previous === undefined` (no snapshot last time, for any reason --
+ * see `EvidenceSnapshotReadResult`) reports everything in `current` as
+ * added, nothing as removed/updated.
+ */
+export declare function diffContracts(previous: readonly ContractModelContract[] | undefined, current: readonly ContractModelContract[]): ManifestChangeReport;
+/** Distinguishes *why* there's no usable previous snapshot, rather than collapsing every case into a bare `undefined`. A missing file is the normal, silent, expected first-run/never-configured case. An unparseable file or a `schemaVersion` this build doesn't recognize are both real, diagnosable problems. */
+export type EvidenceSnapshotReadResult = {
+    readonly status: "missing";
+} | {
+    readonly status: "invalid-json";
+    readonly detail: string;
+} | {
+    readonly status: "unsupported-version";
+    readonly foundVersion: unknown;
+} | {
+    readonly status: "ok";
+    readonly snapshot: EvidenceModel;
+};
+export declare function readEvidenceSnapshot(snapshotPath: string, fs: BuildFileSystem): Promise<EvidenceSnapshotReadResult>;
+export declare function writeEvidenceSnapshot(snapshotPath: string, snapshot: EvidenceModel, fs: BuildFileSystem): Promise<void>;
+export declare function normalizeEvidenceSnapshotForComparison(snapshot: EvidenceModel): EvidenceModel;
+/** Everything reading a previous evidence snapshot and diffing the current run against it produces, in one call. Never writes anything itself -- writing the fresh snapshot stays a separate, explicit step on the real write path. */
+export interface EvidenceChangesComputation {
+    readonly report: ManifestChangeReport;
+    /** Set only when the previous snapshot existed but was unusable (corrupt JSON or an unrecognized `schemaVersion`) -- never set for the ordinary "no snapshot yet" first-run case. */
+    readonly readWarning: ParseWarning | undefined;
+    readonly dynamicAccessAcknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>;
+    readonly dynamicAccessCitationProblems: readonly DynamicAccessCitationProblem[];
+}
+/**
+ * The one I/O-performing helper every caller wanting change/citation-freshness
+ * data shares: reads the previous evidence snapshot (if `snapshotPath` is
+ * given and a file exists there), diffs the current run's `ContractModel`
+ * against it, and re-checks every current `dynamicAccess` citation's
+ * freshness. `snapshotPath` is always caller-supplied, directly -- there is
+ * no derivation from a manifest's own output path.
+ */
+export declare function computeEvidenceChanges(root: string, snapshotPath: string, activeContracts: readonly DiscoveredContract[], currentContracts: readonly ContractModelContract[], readFile: (filePath: string) => Promise<string>, fs: BuildFileSystem): Promise<EvidenceChangesComputation>;
+//# sourceMappingURL=evidence-snapshot.d.ts.map

package/dist/.dts/build/evidence-snapshot.d.ts.map

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

package/dist/.dts/build/exclusive-group.d.ts

@@ -0,0 +1,19 @@
+import type { CompatibilityIssue } from "./compatibility.js";
+import type { DiscoveredContract } from "./link.js";
+/**
+ * Detects two *active* contracts declaring the same `exclusiveGroup` --
+ * e.g. two interchangeable database backends both left enabled at once.
+ *
+ * @remarks
+ * Unlike `detectCompatibilityIssues`, this is never a heuristic warning: an
+ * author explicitly declared these contracts mutually exclusive, so any
+ * violation is always a hard error, regardless of `onIncompatibility`. See
+ * ADR 0009 for why this doesn't follow 0005's warn-by-default policy.
+ *
+ * Inactive contracts are ignored entirely here (filtered internally, not by
+ * the caller) so this stays correct even when called directly via the
+ * `/build` export -- an inactive contract can share a group with an active
+ * one with no conflict, since it was never wired into anything.
+ */
+export declare function detectExclusiveGroupIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
+//# sourceMappingURL=exclusive-group.d.ts.map

package/dist/.dts/build/exclusive-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusive-group.d.ts","sourceRoot":"","sources":["../../../src/build/exclusive-group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAoCtB"}

package/dist/.dts/build/finding-model.d.ts

@@ -0,0 +1,79 @@
+import type { ArtifactCheckFinding } from "./check-artifacts.js";
+import type { CompatibilityIssue, CompatibilityIssueCode } from "./compatibility.js";
+import type { EvidenceReference } from "./evidence-reference.js";
+import type { DocumentationFindings } from "./generate-documentation.js";
+import type { DynamicAccessCitationProblem } from "./citation-verification.js";
+import type { AbandonedContractFinding, IndeterminateOwnershipFinding, UnconsumedOwnedVariableFinding, UnresolvedConsumerFinding } from "./usage-report.js";
+/**
+ * The fourth of env-cap's seven canonical fact models (ADR 0024) -- every
+ * rule violation and derived risk signal, unified behind one shape, with a
+ * stable `code` and a structured {@link EvidenceReference} instead of four
+ * independently-shaped finding families. See ADR 0026.
+ */
+/** Every stable `code` a {@link Finding} can carry. A superset of {@link CompatibilityIssueCode} plus one code per non-compatibility source family this model adapts. */
+export type FindingCode = CompatibilityIssueCode | "EXCLUSIVE_GROUP_VIOLATION" | "ARTIFACT_STALE" | "ARTIFACT_MISSING" | "UNDOCUMENTED_CONTRACT" | "UNDOCUMENTED_VARIABLE" | "STALE_DOC_ENTRY" | "EXPIRED" | "EXPIRING_SOON" | "UNRESOLVED_DOCUMENTENV_LINK" | "ABANDONED_CONTRACT" | "UNRESOLVED_CONSUMER" | "UNCONSUMED_OWNED_VARIABLE" | "INDETERMINATE_OWNERSHIP" | "MISSING_DYNAMIC_ACCESS_CITATION" | "STALE_DYNAMIC_ACCESS_CITATION" | "NONSTANDARD_SENSITIVITY_LEVEL";
+/** Which source check produced a {@link Finding} -- coarser than `code`, for a consumer that only wants to filter by kind (e.g. "show me every documentation gap") without enumerating every individual code. */
+export type FindingFamily = "compatibility" | "drift" | "documentation" | "ownership";
+/** One rule violation or derived signal, in the Finding Model's canonical shape. */
+export interface Finding {
+    /**
+     * `"error"` for a provable, always-blocking violation (e.g. an
+     * exclusive-group conflict); `"warning"` for everything gated by
+     * `onIncompatibility`/`onUndocumented`/`onOwnershipIssue`'s default "warn"
+     * behavior; `"info"` for an observation that is never actionable enough to
+     * block anything, even under `--strict` -- see `INFO_ONLY_CODES` in
+     * `generate-env-artifacts.ts`.
+     */
+    readonly severity: "error" | "warning" | "info";
+    /** Stable, machine-readable identifier -- always set, unlike {@link CompatibilityIssue.code} which stays optional on that narrower, pre-existing type. */
+    readonly code: FindingCode;
+    /** Which source check produced this finding. */
+    readonly family: FindingFamily;
+    /** Human-readable explanation, reusing the source finding's own prose where one exists. */
+    readonly message: string;
+    /** Structured pointer back to what this finding is about. */
+    readonly location: EvidenceReference;
+}
+/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
+export declare const FINDING_MODEL_SCHEMA_VERSION = 3;
+export interface FindingModel {
+    readonly schemaVersion: typeof FINDING_MODEL_SCHEMA_VERSION;
+    readonly findings: readonly Finding[];
+}
+/**
+ * Every source a {@link buildFindingModel} call can adapt, all optional --
+ * a caller passes whichever of `generateEnvArtifacts()`'s `manifest`/`docs`/
+ * `usage` results it actually requested, exactly like that result's own
+ * top-level fields are each independently optional.
+ */
+export interface BuildFindingModelInput {
+    /** Every `EvidenceReference.file` below is rendered relative to this, matching every other rendered path in this package's output -- see `displayPath()`. */
+    readonly root: string;
+    /** From `detectCompatibilityIssues()`. */
+    readonly compatibilityIssues?: readonly CompatibilityIssue[];
+    /** From `detectExclusiveGroupIssues()` -- kept separate from `compatibilityIssues` since it never sets its own `code` yet (ADR 0009), so this adapter synthesizes `"EXCLUSIVE_GROUP_VIOLATION"` for every entry. */
+    readonly exclusiveGroupIssues?: readonly CompatibilityIssue[];
+    /** From `checkEnvArtifacts()`'s result. Only `"stale"`/`"missing"` findings become a `Finding` -- `"ok"` means nothing to report. */
+    readonly artifactCheckFindings?: readonly ArtifactCheckFinding[];
+    /** From `generateDocumentation()`'s result. */
+    readonly documentation?: DocumentationFindings;
+    /** From `generateUsageReport()`'s result. */
+    readonly abandonedContracts?: readonly AbandonedContractFinding[];
+    /** From `generateUsageReport()`'s result. */
+    readonly unresolvedConsumers?: readonly UnresolvedConsumerFinding[];
+    /** From `generateUsageReport()`'s result. */
+    readonly unconsumedOwnedVariables?: readonly UnconsumedOwnedVariableFinding[];
+    /** From `generateUsageReport()`'s result. */
+    readonly indeterminateOwnership?: readonly IndeterminateOwnershipFinding[];
+    /** From `computeManifestChanges()`'s result -- every `dynamicAccess` citation that's gone `"stale"` or `"missing"` since it was last acknowledged. See ADR 0037. */
+    readonly dynamicAccessCitationProblems?: readonly DynamicAccessCitationProblem[];
+}
+/**
+ * Adapts every existing finding family into the Finding Model's unified
+ * shape -- an adapter over data that already exists, not a new source of
+ * truth. Order of the returned array mirrors the order sources are given
+ * above; a consumer wanting a specific order (by severity, by file, ...)
+ * sorts it themselves.
+ */
+export declare function buildFindingModel(input: BuildFindingModelInput): FindingModel;
+//# sourceMappingURL=finding-model.d.ts.map