@maverickcer/env-cap 0.2.0

package/dist/.dts/build/generate-usage.d.ts

@@ -0,0 +1,95 @@
+import type { BuildFileSystem } from "./types.js";
+import type { DependencyGraph, ScannedSurface } from "./dependency-graph.js";
+import type { DiscoveredContract } from "./link.js";
+import type { ParseWarning } from "./parse.js";
+import type { ImportResolutionContext } from "./resolution/resolve-import.js";
+import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
+import type { DynamicAccessAssertion } from "./source-position.js";
+import { type RenderUsageReportOptions } from "./usage-report.js";
+/**
+ * Computes the full usage-scan surface: the local project root, plus (ADR
+ * 0036) each allow-listed `packages` (ADR 0014) name whose schema was
+ * successfully resolved -- reusing `origins`' already-resolved
+ * `packageDir` (from `resolveAllowlistedPackages()`, already computed by
+ * the caller for contract discovery, not re-resolved here) as a bounded
+ * scan root, walked with the exact same `discoverSchemaFiles()` +
+ * `SCAN_INCLUDE`/`defaultExclude()` policy the local root already uses --
+ * never a naive, unbounded walk of the package's whole directory. Shared by
+ * `generateUsageReport()` and `generateEvidenceModel()` so both agree on
+ * exactly the same scanned surface.
+ */
+export declare function computeScanSurface(root: string, exclude: readonly string[], origins: ReadonlyMap<string, PackageOrigin>, fs: BuildFileSystem): Promise<{
+    scanFiles: string[];
+    scannedSurfaces: ScannedSurface[];
+}>;
+/** Options for {@link generateUsageReport}. */
+export interface GenerateUsageReportOptions {
+    /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
+    fs: BuildFileSystem;
+    /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
+    root?: string | undefined;
+    /** Schema-discovery glob, for the contract graph -- self-sufficient like the other two generator functions. */
+    include?: string[] | undefined;
+    /** Glob patterns to exclude, for both schema discovery and the usage scan. Defaults to node_modules/dist/.git. */
+    exclude?: string[] | undefined;
+    /** **Experimental** (see VERSIONING.md) -- see `GenerateEnvManifestOptions.packages`; see ADR 0014. */
+    packages?: readonly string[] | undefined;
+    /** **Experimental** (see VERSIONING.md) -- see `GenerateEnvManifestOptions.tsconfig`; see ADR 0023. */
+    tsconfig?: string | false | undefined;
+    /** Also write the rendered Markdown report to this path, relative to `root`. Omitted: the report is only returned, not written. */
+    report?: {
+        /** Output path for the report, relative to `root`. */
+        location: string;
+    } | undefined;
+}
+/**
+ * Public result of {@link generateUsageReport}.
+ *
+ * @remarks
+ * Composed from the building-block types `usage-report.ts` (the renderer) owns, the same way
+ * `GenerateDocumentationResult` composes from `docs.ts`'s `CatalogContract` --
+ * keeps the renderer importable without its orchestrator (see
+ * `RenderUsageReportOptions`'s own doc comment).
+ */
+export interface GenerateUsageReportResult extends RenderUsageReportOptions {
+    /** Absolute path the report was written to, or `undefined` if `options.report` wasn't passed. */
+    readonly reportPath: string | undefined;
+}
+export interface UsageComputation {
+    readonly graph: DependencyGraph;
+    readonly result: RenderUsageReportOptions;
+}
+/**
+ * Builds the dependency graph and maps it into the public, ownership-framed
+ * result. Never blocks -- see `RenderUsageReportOptions`'s finding fields'
+ * own doc comments; a team that wants to gate CI on an ownership issue reads
+ * `Finding[]` (the "ownership" family) from the persisted evidence artifact
+ * and decides for itself. See ADR 0038.
+ *
+ * @remarks
+ * This mapping is the actual API boundary: internal AST vocabulary
+ * ("member accessed", "dynamic") becomes ownership vocabulary ("who owns
+ * it", "who consumes it", "abandoned", "unresolved"). The result is a
+ * renderer-agnostic domain model -- the same computed data a future JSON or
+ * SARIF exporter would consume, not something coupled to the Markdown
+ * renderer.
+ */
+export declare function computeUsage(root: string, contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, parseWarnings: readonly ParseWarning[], scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<UsageComputation>;
+/** Writes the Dependency & Ownership Report. Callers must have already confirmed `reportPath` is safe and nothing is blocking. */
+export declare function writeUsageReport(reportPath: string, computed: Omit<GenerateUsageReportResult, "reportPath">, fs: BuildFileSystem): Promise<void>;
+/**
+ * Build-time only. Answers who owns each contract, which features depend on
+ * it, and what the blast radius is if it changes -- the mirror image of
+ * {@link generateEnvManifest}'s "safer migrations" story: a schema that was never
+ * wired up, or was abandoned mid-removal, shows up here instead of sitting
+ * unnoticed.
+ *
+ * @remarks
+ * This is an additional, separate artifact, not a replacement for
+ * {@link generateDocumentation}'s Catalog -- the two serve different audiences
+ * (see ADR 0010).
+ *
+ * @throws {EnvUsageAnalysisError} If `report.location` escapes `root`.
+ */
+export declare function generateUsageReport(options: GenerateUsageReportOptions): Promise<GenerateUsageReportResult>;
+//# sourceMappingURL=generate-usage.d.ts.map

package/dist/.dts/build/generate-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-usage.d.ts","sourceRoot":"","sources":["../../../src/build/generate-usage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAQ5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAML,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CA+BrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,uGAAuG;IACvG,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC,mIAAmI;IACnI,MAAM,CAAC,EACH;QACE,sDAAsD;QACtD,QAAQ,EAAE,MAAM,CAAA;KACjB,GACD,SAAS,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,aAAa,EAAE,SAAS,YAAY,EAAE,EACtC,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,gBAAgB,CAAC,CA8J3B;AAED,kIAAkI;AAClI,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC,EACvD,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAgDpC"}

package/dist/.dts/build/generated-banner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Single source of truth for the "this file is generated" marker text, so it
+ * can never drift out of sync between where it's written (`manifest.ts`,
+ * `docs.ts`, `usage-report.ts`) and where it's read (`scan-dependencies.ts`,
+ * closing the self-reference loop where a contract's own generated manifest
+ * would otherwise make it look permanently "used"). Not configurable, not
+ * public.
+ *
+ * Also home to the two standing notices every governance-adjacent artifact
+ * stamps near the top -- `evidenceDisclaimer()` and
+ * `evidenceProjectionNote()`. They live here, next to the banner, because
+ * they answer the same question the banner does ("what is this file, and how
+ * much should I trust it?") and because a renderer that emits one must never
+ * be able to emit the others from a stale, separately-maintained copy.
+ */
+/** Renders the "do not edit by hand" marker in the given comment syntax. */
+export declare function generatedBanner(format?: "ts" | "markdown"): string;
+/**
+ * Whether `content` carries a {@link generatedBanner}-produced marker, in
+ * either format.
+ *
+ * @remarks
+ * Deliberately not a bare `content.startsWith(generatedBanner(...))`: a
+ * shebang, a `"use strict"` pragma, or a license header pushes a real banner
+ * off line one, and a stricter check would then read a genuinely generated
+ * file as hand-written -- which `dependency-graph.ts` would take as "a real
+ * consumer imports this contract," permanently masking an abandoned one. The
+ * marker is looked for across the first 20 non-empty lines instead, which
+ * clears every realistic preamble without scanning a whole file.
+ */
+export declare function isGeneratedFile(content: string): boolean;
+/**
+ * Short disclaimer stamped into every artifact that renders sensitivity/
+ * ownership/expiry claims (the docs Catalog, the Dependency & Ownership
+ * Report). Never omit this from an artifact that renders `documentEnv()`
+ * metadata: it's what keeps "documented" from being misread as "verified" or
+ * "compliant." Every fact in those artifacts is either a statically-provable
+ * code fact or an author's own declaration -- env-cap never executes a schema
+ * file and never validates a declaration against reality.
+ */
+export declare function evidenceDisclaimer(): string;
+/**
+ * States, by concept, that this artifact is a projection of env-cap's
+ * Evidence Model (ADR 0031/0038) -- never a hardcoded path, since
+ * `docs/env.evidence.json` only exists on a run that actually passed
+ * `--evidence`; a project that never requests that flag would otherwise get
+ * a note pointing at a file that doesn't exist. `evidencePath`, when this
+ * same run's own options did include `--evidence <path>`, names that
+ * concrete path in addition to the concept.
+ */
+export declare function evidenceProjectionNote(evidencePath?: string): string;
+//# sourceMappingURL=generated-banner.d.ts.map

package/dist/.dts/build/generated-banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-banner.d.ts","sourceRoot":"","sources":["../../../src/build/generated-banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,GAAE,IAAI,GAAG,UAAiB,GAAG,MAAM,CAQxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAMpE"}

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

@@ -0,0 +1,18 @@
+/**
+ * Converts one glob pattern to a RegExp. Handles `**` as "any number of path
+ * segments, including zero" (so `**\/node_modules/**` matches a root-level
+ * `node_modules`, and `**\/env.schema.ts` matches a root-level file, not just
+ * nested ones) -- a plain `**` -> `.*` substitution gets both of those wrong.
+ *
+ * Used by discover.ts's `include`/`exclude` schema-discovery walk.
+ *
+ * Deliberately duplicated (not shared) with
+ * src/eslint-plugin/glob.ts, which needs the exact same matching behavior
+ * for its own `allow` option -- keeps this build-only module free of any
+ * import reaching outside src/build, so `src/build` stays independently
+ * splittable into its own package with zero source-level cross-folder
+ * dependency. Not re-exported from `./index.js` -- Private tier per
+ * VERSIONING.md.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+//# sourceMappingURL=glob.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../../src/build/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAyBpD"}

package/dist/.dts/build/governance-fields.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The declared governance-metadata field set every pipeline-stage contract and
+ * variable type carries -- `owner` through `metadata`. The field names and types
+ * are identical at every stage (parse -> link -> contract-model -> docs); only
+ * the surrounding context differs (a `parse`-stage value is "statically resolved
+ * from a string literal, or `undefined`"; a `link`/`contract-model`-stage value
+ * is "from the linked `documentEnv()` call, or `undefined`"). This is the single
+ * source of truth for the shape; each stage interface `extends` it.
+ *
+ * `metadata` is the open bag for keys `env-cap` has no named concept for (ADR
+ * 0037); `dataResidency`/`auditRequired`/`legalBasis`/`purpose`/`retention` are
+ * presence-only governance facts, never verified.
+ *
+ * Internal -- not re-exported from the public `.` barrel.
+ */
+export interface EnvGovernanceFields {
+    readonly owner: string | undefined;
+    readonly sensitivity: string | undefined;
+    readonly expiresAt: string | undefined;
+    readonly purpose: string | undefined;
+    readonly legalBasis: string | undefined;
+    readonly retention: string | undefined;
+    readonly dataResidency: string | readonly string[] | undefined;
+    readonly auditRequired: boolean | undefined;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * Copies exactly the {@link EnvGovernanceFields} out of a value that carries
+ * them -- for projecting one pipeline stage's contract/variable into the next
+ * (`link` -> `contract-model` -> `docs` catalog, ...) without re-listing all
+ * nine fields at every hop.
+ */
+export declare function governanceFieldsOf(source: EnvGovernanceFields): EnvGovernanceFields;
+//# sourceMappingURL=governance-fields.d.ts.map

package/dist/.dts/build/governance-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance-fields.d.ts","sourceRoot":"","sources":["../../../src/build/governance-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9D,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAYnF"}

package/dist/.dts/build/humanize-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats a metadata key for display in generated docs/examples:
+ * "lastRotation" -> "Last Rotation". Shared by `docs.ts` and `env-example.ts`
+ * so both generated artifacts label metadata the same way.
+ */
+export declare function humanizeKey(key: string): string;
+/**
+ * Formats a `metadata`/`dataResidency` value for display in generated docs/examples -- a string
+ * renders as-is; anything else (ADR 0035 widened `metadata` to any value) renders as its JSON
+ * text, so an object/array value never prints `[object Object]`. Shared by `docs.ts` and
+ * `env-example.ts`, same rationale as {@link humanizeKey}.
+ */
+export declare function renderMetadataValue(value: unknown): string;
+//# sourceMappingURL=humanize-key.d.ts.map

package/dist/.dts/build/humanize-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanize-key.d.ts","sourceRoot":"","sources":["../../../src/build/humanize-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D"}

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

@@ -0,0 +1,107 @@
+/**
+ * env-cap build-time entry point (`env-cap/build`).
+ *
+ * Discovery, static analysis, cross-file linking, and manifest/docs/
+ * ownership-report generation only -- this module imports `node:path` and
+ * (indirectly) `typescript`, and must never be imported from runtime/
+ * browser/edge code. It has no knowledge of `createEnv`/`documentEnv`/
+ * `validateEnv` and performs no environment validation, and never executes a
+ * discovered schema file.
+ *
+ * It never imports `node:fs` (ADR 0040): `./build` is a library surface, so
+ * the caller supplies the filesystem capability. Every public options object
+ * below carries a required `fs: BuildFileSystem` field; the `env-cap` CLI
+ * builds a concrete `node:fs/promises` adapter and hands it in. A consumer
+ * running these functions from their own Node build script imports the same
+ * adapter from `env-cap/node` (`{ nodeBuildFileSystem }`).
+ *
+ * The public API is deliberately curated: four generator functions
+ * (`generateEnvManifest`, `generateDocumentation`, `generateUsageReport`,
+ * `generateEnvArtifacts`) -- Stable, per VERSIONING.md -- plus the
+ * lower-level discovery/linking primitives already justified by real
+ * external use (custom CI scripts, bundler plugins). Those primitives are
+ * Experimental, not Stable, until each has been through a real feedback
+ * cycle on its own (see VERSIONING.md's Experimental tier). The
+ * dependency-ownership engine's internals (scanning, graph-building,
+ * derivation) are intentionally NOT exported here -- see ADR 0010 and ADR
+ * 0011. `env-cap` answers ownership/visibility questions; it doesn't ship a
+ * general-purpose static-analysis toolkit. The scanner follows
+ * object-destructuring and one level of file-unique `const` aliasing, and
+ * records every other shape as an explicit `escape` (ADR 0039); a variable
+ * on an escaped contract is `indeterminate`, never a false `unconsumed`, and
+ * the finding's `reason` cites every escape site.
+ *
+ * Each generator also accepts an Experimental `packages` option (an explicit
+ * allowlist of installed package names) for discovering a schema that ships
+ * inside a separately-published dependency rather than the project's own
+ * source tree -- see ADR 0014 and VERSIONING.md.
+ *
+ * Each generator also accepts an Experimental `tsconfig` option for resolving
+ * import specifiers written as TypeScript path aliases (e.g. `"@/lib/env"`)
+ * against a project's own `tsconfig.json` `paths`/`baseUrl` during static
+ * analysis. Unlike `packages`, this is on by default (auto-detecting
+ * `tsconfig.json` at `root`) since it never crosses a trust/versioning
+ * boundary -- see ADR 0023 and VERSIONING.md.
+ */
+export { checkEnvArtifacts } from "./check-artifacts.js";
+export type { ArtifactCheckFinding, CheckEnvArtifactsResult } from "./check-artifacts.js";
+export { generateDocumentation } from "./generate-documentation.js";
+export type { DocumentationFindings, GenerateDocumentationOptions, GenerateDocumentationResult, } from "./generate-documentation.js";
+export { generateEnvArtifacts } from "./generate-env-artifacts.js";
+export type { GenerateEnvArtifactsOptions, GenerateEnvArtifactsResult, } from "./generate-env-artifacts.js";
+export { generateEnvManifest } from "./generate-manifest.js";
+export type { GenerateEnvManifestOptions, GenerateEnvManifestResult } from "./generate-manifest.js";
+export type { ManifestChangeReport, ManifestContractRef, ManifestContractUpdate, ManifestFieldChange, ManifestVariableRef, ManifestVariableUpdate, } from "./evidence-snapshot.js";
+export { computeSourceFingerprint, getEvidenceModel } from "./evidence-cache.js";
+export type { ComputeSourceFingerprintOptions, GetEvidenceModelOptions, GetEvidenceModelResult, } from "./evidence-cache.js";
+export { generateUsageReport } from "./generate-usage.js";
+export type { GenerateUsageReportOptions, GenerateUsageReportResult } from "./generate-usage.js";
+export { renderUsageReport, type AbandonedContractFinding, type AssertedDynamicAccessFinding, type IndeterminateOwnershipFinding, type OwnershipDependencyEntry, type RenderUsageReportOptions, type UnconsumedOwnedVariableFinding, type UnresolvedConsumerFinding, } from "./usage-report.js";
+export type { DynamicAccessCitationProblem } from "./citation-verification.js";
+export type { CompatibilityIssue, CompatibilityIssueCode } from "./compatibility.js";
+export { EnvDocumentationGenerationError, EnvManifestGenerationError, EnvProjectGenerationError, EnvUsageAnalysisError, } from "./errors.js";
+export type { DiscoveredContractSummary } from "./link.js";
+export { buildChangeModel, CHANGE_MODEL_SCHEMA_VERSION } from "./change-model.js";
+export type { ChangeModel, RenamedVariable } from "./change-model.js";
+export { detectCompatibilityIssues, detectDuplicateVariableShapes } from "./compatibility.js";
+export { displayPath } from "./display-path.js";
+export { buildSarifLog } from "./sarif.js";
+export type { SarifLog } from "./sarif.js";
+export { configurationReference, expiringSoonReport, groupVariablesByOwner, ownershipSummary, } from "./reference-projections.js";
+export type { ConfigurationReference, ConfigurationReferenceEntry, ExpiringSoonEntry, ExpiringSoonReport, OwnerBearingContract, OwnershipSummary, OwnershipSummaryEntry, } from "./reference-projections.js";
+export { buildContractModel, CONTRACT_MODEL_SCHEMA_VERSION } from "./contract-model.js";
+export type { ContractModel, ContractModelContract, ContractModelVariable, } from "./contract-model.js";
+export { deepFreeze } from "./deep-freeze.js";
+export { buildDependencyModel, DEPENDENCY_MODEL_SCHEMA_VERSION } from "./dependency-model.js";
+export type { DependencyModel, DependencyModelConsumer, DependencyModelContract, DependencyModelContractRef, DependencyModelVariable, } from "./dependency-model.js";
+export type { ScannedSurface, VariableAccessStatus } from "./dependency-graph.js";
+export { discoverSchemaFiles } from "./discover.js";
+export { computeExpiringEntries, computeSecurityReviewCounters, extractPreviouslyDocumentedKeys, renderDocs, } from "./docs.js";
+export type { ExpiringEntry, RenderDocsOptions, SecurityReviewCounters, UndocumentedContractRef, UndocumentedVariableRef, } from "./docs.js";
+export { computeReconciliation, extractCommentedVariables, extractDeclaredVariables, renderEnvExample, writeEnvExample, } from "./env-example.js";
+export type { EnvExampleOnExisting, EnvExampleResult, Reconciliation } from "./env-example.js";
+export type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
+export { EVIDENCE_MODEL_SCHEMA_VERSION } from "./evidence-model.js";
+export type { EvidenceModel, EvidenceProvenance } from "./evidence-model.js";
+export { generateEvidenceModel } from "./generate-evidence.js";
+export type { GenerateEvidenceModelOptions } from "./generate-evidence.js";
+export type { ChangeEvidenceReference, ContractEvidenceReference, ContractRef, EvidenceReference, OwnershipEvidenceReference, } from "./evidence-reference.js";
+export { detectExclusiveGroupIssues } from "./exclusive-group.js";
+export { buildFindingModel, FINDING_MODEL_SCHEMA_VERSION } from "./finding-model.js";
+export type { BuildFindingModelInput, Finding, FindingCode, FindingFamily, FindingModel, } from "./finding-model.js";
+export { buildLifecycleModel, LIFECYCLE_MODEL_SCHEMA_VERSION } from "./lifecycle-model.js";
+export type { LifecycleModel, LifecycleModelContract, LifecycleModelVariable, } from "./lifecycle-model.js";
+export { effectiveOwner, linkFiles } from "./link.js";
+export type { DiscoveredContract, DiscoveredVariable, LinkResult, UnresolvedLink } from "./link.js";
+export { applyLiveExpirationOverrides, collectVariableNames, resolveLiveExpirationDates, } from "./live-expirations.js";
+export type { LiveExpirationDates } from "./live-expirations.js";
+export { renderManifest } from "./manifest.js";
+export { buildOwnershipModel, OWNERSHIP_MODEL_SCHEMA_VERSION } from "./ownership-model.js";
+export type { OwnershipModel, OwnershipModelContract, OwnershipModelContractRef, OwnershipModelVariable, OwnershipModelVariableRef, } from "./ownership-model.js";
+export { extractContractDocs, extractSchemaVariables, parseSchemaFile } from "./parse.js";
+export type { DiscoveredContractDocs, DiscoveredSchemaVariable, DiscoveredVariableDocs, FileParseResult, ImportBinding, ParseWarning, SchemaRef, } from "./parse.js";
+export { resolveRelativeImport } from "./resolution/resolve-import.js";
+export type { PackageOrigin } from "./resolution/resolve-package-schema.js";
+export type { BuildDirent, BuildFileSystem, BuildStats } from "./types.js";
+export { readToolVersion } from "./tool-version.js";
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,64 @@
+import type { ExpiringEntry } from "./docs.js";
+import type { DiscoveredContract } from "./link.js";
+/**
+ * The fifth of env-cap's seven canonical fact models (ADR 0024) -- every
+ * contract and variable's lifecycle data (expiry, deprecation, rename
+ * correlation), promoting `ExpiringEntry`/`computeExpiringEntries()`
+ * (already a good precedent -- real, exported, reused across `renderDocs()`
+ * and `generate-documentation.ts`) into a canonical, versioned shape
+ * alongside the new deprecation/rename fields. See ADR 0029.
+ */
+/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
+export declare const LIFECYCLE_MODEL_SCHEMA_VERSION = 2;
+/**
+ * One variable's lifecycle data (expiry, deprecation, rename correlation).
+ *
+ * @see {@link ContractModelVariable} -- this same declared variable's canonical starting point.
+ */
+export interface LifecycleModelVariable {
+    readonly key: string;
+    readonly expiresAt: string | undefined;
+    readonly refreshInstructions: string | undefined;
+    readonly deprecated: boolean | undefined;
+    readonly deprecatedReason: string | undefined;
+    readonly removeBy: string | undefined;
+    /** The previous variable name this one renames, if set -- see `ManifestChangeReport`'s rename correlation (ADR 0029/0030). */
+    readonly renamedFrom: string | undefined;
+    /** Descriptive retention policy (e.g. "delete after 90 days") -- a policy statement, never computed or parsed, deliberately independent of `expiresAt`'s actual temporal constraint. See ADR 0035. */
+    readonly retention: string | undefined;
+}
+export interface LifecycleModelContract {
+    /** Root-relative, POSIX-separated -- matches `ContractModelContract.file`. */
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    readonly expiresAt: string | undefined;
+    readonly deprecated: boolean | undefined;
+    readonly deprecatedReason: string | undefined;
+    /** See {@link LifecycleModelVariable.retention}. */
+    readonly retention: string | undefined;
+    /** Only variables with at least one lifecycle field set (`expiresAt`, `refreshInstructions`, `deprecated`, `removeBy`, `renamedFrom`, `retention`) -- same "only what's relevant" scope `renderLifecycleReport()` already uses for its rows. */
+    readonly variables: readonly LifecycleModelVariable[];
+}
+export interface LifecycleModel {
+    readonly schemaVersion: typeof LIFECYCLE_MODEL_SCHEMA_VERSION;
+    /** Only contracts with at least one lifecycle-relevant field set, at the contract level or on at least one variable. */
+    readonly contracts: readonly LifecycleModelContract[];
+    /**
+     * Every contract-/variable-level `expiresAt` within the configured window,
+     * soonest-first -- see `computeExpiringEntries()`. `file` is root-relative
+     * and POSIX-separated here, matching `LifecycleModelContract.file`/every
+     * other canonical model -- unlike `ExpiringEntry`'s own doc comment, which
+     * describes its shape in `computeExpiringEntries()`'s other direct
+     * consumers (e.g. `DocumentationFindings.expiringSoon`), where `file`
+     * stays the absolute path `renderDocs()` itself expects.
+     */
+    readonly expiring: readonly ExpiringEntry[];
+}
+/**
+ * Projects every discovered contract with at least one lifecycle-relevant
+ * field set into the Lifecycle Model's versioned, JSON-serializable shape,
+ * plus the already-established `expiring` view.
+ */
+export declare function buildLifecycleModel(contracts: readonly DiscoveredContract[], expiringWithinDays: number, now: Date, root: string): LifecycleModel;
+//# sourceMappingURL=lifecycle-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-model.d.ts","sourceRoot":"","sources":["../../../src/build/lifecycle-model.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAEvE;;;;;;;GAOG;AAEH,yIAAyI;AACzI,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,8HAA8H;IAC9H,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,sMAAsM;IACtM,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,gPAAgP;IAChP,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACtD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAA;IAC7D,wHAAwH;IACxH,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;CAC5C;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,MAAM,GACX,cAAc,CA+ChB"}