@maverickcer/env-cap 0.2.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"finding-model.d.ts","sourceRoot":"","sources":["../../../src/build/finding-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAEpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,KAAK,EACV,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,mBAAmB,CAAA;AAE1B;;;;;GAKG;AAEH,yKAAyK;AACzK,MAAM,MAAM,WAAW,GACnB,sBAAsB,GACtB,2BAA2B,GAC3B,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,iBAAiB,GACjB,SAAS,GACT,eAAe,GACf,6BAA6B,GAC7B,oBAAoB,GACpB,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,iCAAiC,GACjC,+BAA+B,GAC/B,+BAA+B,CAAA;AAEnC,iNAAiN;AACjN,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,OAAO,GAAG,eAAe,GAAG,WAAW,CAAA;AAErF,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/C,0JAA0J;IAC1J,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;CACrC;AAED,yIAAyI;AACzI,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,4BAA4B,CAAA;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,6JAA6J;IAC7J,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC5D,oNAAoN;IACpN,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7D,qIAAqI;IACrI,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAChE,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAA;IAC9C,6CAA6C;IAC7C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAA;IACjE,6CAA6C;IAC7C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACnE,6CAA6C;IAC7C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,8BAA8B,EAAE,CAAA;IAC7E,6CAA6C;IAC7C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAA;IAC1E,oKAAoK;IACpK,QAAQ,CAAC,6BAA6B,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAA;CACjF;AAmCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAwN7E"}

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

@@ -0,0 +1,176 @@
+import type { ContractModelContract } from "./contract-model.js";
+import type { CatalogContract, ExpiringEntry } from "./docs.js";
+import type { EnvExampleOnExisting, EnvExampleResult } from "./env-example.js";
+import type { DiscoveredContract, DiscoveredContractSummary, LinkResult } from "./link.js";
+import type { LiveExpirationDates } from "./live-expirations.js";
+import type { ParseWarning } from "./parse.js";
+import type { BuildFileSystem } from "./types.js";
+/** Options for {@link generateDocumentation}. */
+export interface GenerateDocumentationOptions {
+    /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
+    fs: BuildFileSystem;
+    /** Project root schema discovery is relative to. Defaults to `process.cwd()`. */
+    root?: string | undefined;
+    /** Output path for the Markdown docs artifact, relative to `root`. */
+    location: string;
+    /** Glob patterns for files to scan. Defaults to `defaultInclude()`. */
+    include?: string[] | undefined;
+    /** Glob patterns for files/directories to prune. Defaults to `defaultExclude()`. */
+    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;
+    /** How many days out counts as "expiring soon". Defaults to 30. */
+    expiringWithinDays?: number | undefined;
+    /**
+     * Also emit a `.env.example`-style file, relative to `root`. `onExisting`
+     * controls what happens when a file already exists there -- defaults to
+     * `"keep-sibling"` (never overwrites; see `EnvExampleOnExisting` and
+     * `EnvExampleResult`).
+     */
+    envExample?: {
+        /** Output path for the `.env.example`-style file, relative to `root`. */
+        location: string;
+        /** What to do when a file already exists at `location`. Defaults to `"keep-sibling"`. */
+        onExisting?: EnvExampleOnExisting | undefined;
+    } | undefined;
+    /**
+     * Supplies expiration metadata from a live source as a post-discovery
+     * override, invoked exactly once with every discovered variable name after
+     * linking completes and before rendering. See `live-expirations.ts` and
+     * ADR 0012. Omitted: behavior is unchanged from a purely static `expiresAt`.
+     */
+    liveExpirationDates?: LiveExpirationDates | undefined;
+}
+/** Everything {@link generateDocumentation} found that isn't fully documented or up to date -- never blocks generation; a team that wants to gate CI on this reads `Finding[]` (the "documentation" family) from the persisted evidence artifact and decides for itself. See ADR 0038. */
+export interface DocumentationFindings {
+    /** Contracts with no linked `documentEnv()` call at all. */
+    readonly undocumentedContracts: readonly {
+        /** Absolute path of the file declaring the contract. */
+        readonly file: string;
+        /** The contract's exported binding name. */
+        readonly exportName: string;
+    }[];
+    /** Schema variables with no matching entry in their contract's linked documentation. */
+    readonly undocumentedVariables: readonly {
+        /** Absolute path of the file declaring the contract. */
+        readonly file: string;
+        /** The contract's exported binding name. */
+        readonly exportName: string;
+        /** The undocumented environment variable name. */
+        readonly key: string;
+    }[];
+    /** Documented variable entries with no matching schema variable (the schema key was removed or renamed). */
+    readonly staleDocEntries: readonly {
+        /** Absolute path of the file declaring the contract. */
+        readonly file: string;
+        /** The contract's exported binding name. */
+        readonly exportName: string;
+        /** The stale documented variable name. */
+        readonly key: string;
+    }[];
+    /** Variables whose `expiresAt` falls within the configured window. */
+    readonly expiringSoon: readonly ExpiringEntry[];
+    /** Contract- or variable-level `sensitivity` values outside {@link STANDARD_SENSITIVITY_LEVELS}. Advisory only -- the declared level is always honored verbatim; this exists purely so vocabulary drift across a repo stays visible. */
+    readonly nonstandardSensitivityLevels: readonly NonstandardSensitivityEntry[];
+    /** `documentEnv()` calls that couldn't be statically linked to a schema. */
+    readonly unresolvedLinks: readonly {
+        /** Absolute path of the file containing the unlinkable call. */
+        readonly file: string;
+        /** Human-readable explanation of why the link couldn't be resolved. */
+        readonly reason: string;
+    }[];
+}
+/** The result of a completed {@link generateDocumentation} run. */
+export interface GenerateDocumentationResult {
+    /** Absolute path the Markdown docs artifact was written to. */
+    readonly docsPath: string;
+    /** Set only when `options.envExample` was passed. */
+    readonly envExample: EnvExampleResult | undefined;
+    /** Root-relative summary of every discovered contract, active or not. */
+    readonly contracts: readonly DiscoveredContractSummary[];
+    /** Same descriptive content as the generated Markdown Catalog, reshaped for
+     *  programmatic consumers -- see `buildCatalog()` in `docs.ts`. */
+    readonly catalog: readonly CatalogContract[];
+    /** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
+    readonly parseWarnings: readonly ParseWarning[];
+    /** Everything found that isn't fully documented or up to date. */
+    readonly documentation: DocumentationFindings;
+}
+/** Default value for {@link GenerateDocumentationOptions.expiringWithinDays}. */
+export declare const DEFAULT_EXPIRING_WITHIN_DAYS = 30;
+/**
+ * The sensitivity vocabulary env-cap's own docs, examples, and `.env.example`
+ * comments are written around. Purely advisory: `sensitivity` is an open
+ * `string` (see {@link runtime.VariableDocs.sensitivity}), any value is
+ * honored verbatim, and nothing here ever drops or rewrites a declared level.
+ * A level outside this set only produces a non-blocking
+ * `NONSTANDARD_SENSITIVITY_LEVEL` finding, so a team that deliberately runs
+ * its own vocabulary sees one advisory line rather than silent data loss --
+ * and a team that meant to write `"secret"` and typo'd `"secrets"` finds out.
+ */
+export declare const STANDARD_SENSITIVITY_LEVELS: ReadonlySet<string>;
+/** One contract- or variable-level `sensitivity` declaring a level outside {@link STANDARD_SENSITIVITY_LEVELS}. */
+export interface NonstandardSensitivityEntry {
+    /** Absolute path of the file declaring the contract. */
+    readonly file: string;
+    /** The contract's exported binding name. */
+    readonly exportName: string;
+    /** `undefined` for a contract-level `sensitivity`, set for a per-variable one. */
+    readonly key: string | undefined;
+    /** The declared level, exactly as written. */
+    readonly sensitivity: string;
+}
+/**
+ * Every contract- or variable-level `sensitivity` outside the standard set,
+ * in declaration order (contract first, then its own variables by key).
+ *
+ * @remarks
+ * A variable's *own* declared level only -- never the contract-inherited one
+ * `effectiveSensitivity()` would resolve to. Reporting the inherited value
+ * would fire this same finding once per variable on a contract that already
+ * produced its own contract-level entry, turning one real vocabulary
+ * question into N duplicates of it.
+ */
+export declare function findNonstandardSensitivityLevels(contracts: readonly DiscoveredContract[]): NonstandardSensitivityEntry[];
+export interface DocumentationComputation {
+    readonly contractSummaries: readonly DiscoveredContractSummary[];
+    readonly catalog: readonly CatalogContract[];
+    readonly documentation: DocumentationFindings;
+    /** `ContractModel`'s own projection of the same contracts, built once here and reused by `writeDocumentation()` -- the shape `renderDocs()` itself takes (ADR 0038). */
+    readonly contractModelContracts: readonly ContractModelContract[];
+}
+/** Root-relative, POSIX-separated -- `RenderDocsOptions`'s own convention, matching `ContractModel`'s `file`. Exported so `check-artifacts.ts`'s drift check can convert the same `documentation.undocumentedContracts`/`undocumentedVariables` fields for its own `renderDocs()` call, identically. Delegates to `displayPath()` so this can never disagree with the `ContractModel` `file` values it's matched against by identity. */
+export declare function relativizeRef<T extends {
+    file: string;
+}>(root: string, ref: T): T;
+/**
+ * Pure -- no I/O. Computes undocumented/stale/expiring findings against an
+ * already-discovered contract graph (active and inactive alike -- docs
+ * document everything, unlike the manifest). Never blocks -- see
+ * `DocumentationFindings`'s own doc comment. Shared by the standalone
+ * `generateDocumentation()` and `generate-env-artifacts.ts` (which also
+ * reuses this same call for Finding Model's documentation-family findings,
+ * ADR 0038 -- one computation, not two).
+ */
+export declare function computeDocumentation(root: string, linkResult: LinkResult, expiringWithinDays: number, generatedAt: Date): DocumentationComputation;
+/** Writes the docs artifact and, if requested, the `.env.example` file. Callers must have already confirmed both output paths are safe and nothing is blocking. */
+export declare function writeDocumentation(docsPath: string, envExamplePath: string | undefined, root: string, contracts: readonly DiscoveredContract[], contractModelContracts: readonly ContractModelContract[], documentation: DocumentationFindings, expiringWithinDays: number, generatedAt: Date, fs: BuildFileSystem, envExampleOnExisting?: EnvExampleOnExisting): Promise<{
+    envExample: EnvExampleResult | undefined;
+}>;
+/**
+ * Build-time only. Discovers and links `env.schema.ts` files (same static
+ * analysis as {@link generateEnvManifest}) and writes the rich Markdown "Catalog" --
+ * every variable, its description, default, processor/validator flags,
+ * owner, and expiry -- the single onboarding reference application
+ * developers use to see what configuration a feature needs and how to set
+ * it up. Optionally also writes a reconciling `.env.example`.
+ *
+ * @remarks
+ * Documents every discovered contract, active or not, unlike {@link generateEnvManifest}.
+ *
+ * @throws {EnvDocumentationGenerationError} If `location`/`envExample.location` escape `root`.
+ */
+export declare function generateDocumentation(options: GenerateDocumentationOptions): Promise<GenerateDocumentationResult>;
+//# sourceMappingURL=generate-documentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate-documentation.d.ts","sourceRoot":"","sources":["../../../src/build/generate-documentation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAEhE,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAGd,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAI9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE1F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oFAAoF;IACpF,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,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,UAAU,CAAC,EACP;QACE,yEAAyE;QACzE,QAAQ,EAAE,MAAM,CAAA;QAChB,yFAAyF;QACzF,UAAU,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAA;KAC9C,GACD,SAAS,CAAA;IACb;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;CACtD;AAED,0RAA0R;AAC1R,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,qBAAqB,EAAE,SAAS;QACvC,wDAAwD;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,4CAA4C;QAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAC5B,EAAE,CAAA;IACH,wFAAwF;IACxF,QAAQ,CAAC,qBAAqB,EAAE,SAAS;QACvC,wDAAwD;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,4CAA4C;QAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,kDAAkD;QAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KACrB,EAAE,CAAA;IACH,4GAA4G;IAC5G,QAAQ,CAAC,eAAe,EAAE,SAAS;QACjC,wDAAwD;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,4CAA4C;QAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,0CAA0C;QAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KACrB,EAAE,CAAA;IACH,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/C,wOAAwO;IACxO,QAAQ,CAAC,4BAA4B,EAAE,SAAS,2BAA2B,EAAE,CAAA;IAC7E,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,SAAS;QACjC,gEAAgE;QAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,uEAAuE;QACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACxB,EAAE,CAAA;CACJ;AAED,mEAAmE;AACnE,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;IACjD,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD;uEACmE;IACnE,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IAC5C,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/C,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAA;CAC9C;AAED,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,KAAK,CAAA;AAE9C;;;;;;;;;GASG;AAeH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAK1D,CAAA;AAGF,mHAAmH;AACnH,MAAM,WAAW,2BAA2B;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,2BAA2B,EAAE,CAyB/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IAC5C,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAA;IAC7C,wKAAwK;IACxK,QAAQ,CAAC,sBAAsB,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAClE;AAED,yaAAya;AACza,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAEjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,IAAI,GAChB,wBAAwB,CAe1B;AAED,mKAAmK;AACnK,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,sBAAsB,EAAE,SAAS,qBAAqB,EAAE,EACxD,aAAa,EAAE,qBAAqB,EACpC,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,IAAI,EACjB,EAAE,EAAE,eAAe,EACnB,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC;IAAE,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;CAAE,CAAC,CA0CvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAsEtC"}

package/dist/.dts/build/generate-env-artifacts.d.ts

@@ -0,0 +1,176 @@
+import type { CompatibilityIssue } from "./compatibility.js";
+import type { EvidenceModel } from "./evidence-model.js";
+import type { Finding, FindingFamily } from "./finding-model.js";
+import type { DocumentationComputation, GenerateDocumentationOptions, GenerateDocumentationResult } from "./generate-documentation.js";
+import type { GenerateEnvManifestOptions, GenerateEnvManifestResult, ManifestComputation } from "./generate-manifest.js";
+import type { GenerateUsageReportOptions, GenerateUsageReportResult, UsageComputation } from "./generate-usage.js";
+import type { DiscoveredContract } from "./link.js";
+import type { LiveExpirationDates } from "./live-expirations.js";
+import type { ParseWarning } from "./parse.js";
+import type { BuildFileSystem } from "./types.js";
+/** Options for {@link generateEnvArtifacts}. */
+export interface GenerateEnvArtifactsOptions {
+    /** The filesystem capability, shared across every requested pass -- `./build` never imports `node:fs` (ADR 0040). */
+    fs: BuildFileSystem;
+    /** Directory glob patterns are resolved against, shared across every requested pass. Defaults to `process.cwd()`. */
+    root?: string | undefined;
+    /** Shared schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
+    include?: string[] | undefined;
+    /** Glob patterns to exclude, shared across every requested pass. Defaults to node_modules/dist/.git. */
+    exclude?: string[] | undefined;
+    /** **Experimental** (see VERSIONING.md) -- see `GenerateEnvManifestOptions.packages`; shared across every requested pass. See ADR 0014. */
+    packages?: readonly string[] | undefined;
+    /** **Experimental** (see VERSIONING.md) -- see `GenerateEnvManifestOptions.tsconfig`; shared across every requested pass. See ADR 0023. */
+    tsconfig?: string | false | undefined;
+    /** Manifest pass options, or `false` to skip it entirely. */
+    manifest?: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
+    /** Docs pass options, or `false` to skip it entirely. */
+    docs?: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates"> | false | undefined;
+    /** Usage-report pass options, or `false` to skip it entirely. */
+    usage?: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
+    /**
+     * Where to write the persisted evidence artifact (the full, literal
+     * `EvidenceModel`, plus a paired `.fingerprint` sidecar -- see
+     * `evidence-cache.ts`), e.g. `docs/env.evidence.json`, relative to `root`.
+     * Independent of `manifest.location` -- requesting this needs no other
+     * pass, and generating a manifest never requires it. `EvidenceModel`
+     * itself is always computed regardless of this option (ADR 0038, "free to
+     * compute, always real") and always returned as `result.evidence`; this
+     * option controls only whether it's also written to disk. Omitted:
+     * nothing is written, `result.evidence` is still populated.
+     */
+    evidence?: {
+        location: string;
+    } | false | undefined;
+    /**
+     * Escalates every warning-severity `"documentation"`-family finding
+     * (undocumented contracts/variables, stale doc entries, expiring/expired
+     * entries, unresolvable `documentEnv()` links) into a blocking error, so a
+     * run with any of them writes nothing and throws. Defaults to `"warn"` --
+     * ADR 0038's stance, unchanged: documentation gaps never block by default.
+     *
+     * @remarks
+     * Scoped deliberately narrowly, unlike `manifest.onIncompatibility`, which
+     * gates only the compatibility family. `"info"`-severity findings are never
+     * escalated by either -- see `Finding.severity`.
+     */
+    onUndocumented?: "warn" | "throw" | undefined;
+    /**
+     * Escalates every warning-severity `"ownership"`-family finding (abandoned
+     * contracts, unresolved consumers, unconsumed owned variables,
+     * indeterminate ownership, stale/missing `dynamicAccess` citations) into a
+     * blocking error. Defaults to `"warn"` -- see {@link onUndocumented}.
+     */
+    onOwnershipIssue?: "warn" | "throw" | undefined;
+    /**
+     * Supplies expiration metadata from a live source (a secrets manager, an
+     * internal inventory API, ...) as a post-discovery override applied only to
+     * the docs pass. Invoked at most once, only when a `docs` pass is actually
+     * requested, with every discovered variable name across all passes' shared
+     * contract graph. See `live-expirations.ts` and ADR 0012. Omitted: behavior
+     * is unchanged from a purely static `expiresAt`.
+     */
+    liveExpirationDates?: LiveExpirationDates | undefined;
+}
+/** The result of a completed {@link generateEnvArtifacts} run. */
+export interface GenerateEnvArtifactsResult {
+    /** Set only when `options.manifest` wasn't `false`. */
+    readonly manifest: GenerateEnvManifestResult | undefined;
+    /** Set only when `options.docs` wasn't `false`. */
+    readonly docs: GenerateDocumentationResult | undefined;
+    /** Set only when `options.usage` wasn't `false`. */
+    readonly usage: GenerateUsageReportResult | undefined;
+    /** Always populated, regardless of `options.evidence` -- see that option's own doc comment. */
+    readonly evidence: EvidenceModel;
+}
+/**
+ * Every intermediate value both the write path (`generateEnvArtifacts()`
+ * below) and the drift-check path (`checkEnvArtifacts()` in
+ * `check-artifacts.ts`) need, computed exactly once. Internal/Private tier
+ * per `VERSIONING.md` -- not re-exported from `./index.ts`.
+ */
+export interface ComputeArtifactsResult {
+    readonly root: string;
+    readonly manifestOptions: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | undefined;
+    readonly manifestOutputPath: string | undefined;
+    readonly manifestComputed: ManifestComputation | undefined;
+    readonly docsOptions: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates"> | undefined;
+    readonly docsPath: string | undefined;
+    readonly envExamplePath: string | undefined;
+    /** Always computed -- Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
+    readonly docsComputed: DocumentationComputation;
+    readonly docsContracts: readonly DiscoveredContract[];
+    readonly usageOptions: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | undefined;
+    readonly usageReportPath: string | undefined;
+    /** Always computed -- Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
+    readonly usageComputed: UsageComputation;
+    readonly evidencePath: string | undefined;
+    readonly evidence: EvidenceModel;
+    readonly blocking: readonly CompatibilityIssue[];
+    readonly packageWarnings: readonly ParseWarning[];
+    readonly linkWarnings: readonly ParseWarning[];
+    /** Single timestamp shared by every pass' own time-sensitive computation (`expiringSoon`, `EvidenceModel.provenance.generatedAt`), so all of them agree on exactly the same instant. */
+    readonly generatedAt: Date;
+}
+/**
+ * Adapts every warning-severity finding of one family into the
+ * `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak, so
+ * `--strict-docs`/`--strict-ownership` fail through exactly the same path
+ * `--strict` already does rather than inventing a second failure mode.
+ *
+ * @remarks
+ * `"info"` findings are filtered out unconditionally and can never be
+ * escalated by any flag -- they're observations, not gaps (see
+ * `Finding.severity`). `"error"` findings are excluded too: those already
+ * block on their own, via the manifest pass, and re-adding them here would
+ * report the same violation twice in one error message. `code` is left unset
+ * -- `CompatibilityIssueCode` is that check family's own closed vocabulary,
+ * and a `FindingCode` from another family is not a member of it.
+ */
+/** @internal Exported for direct unit coverage -- reached through `generateEnvArtifacts()`'s `--strict-docs`/`--strict-ownership` flags in production, but its filter/mapping logic isn't independently observable through that path alone (every mutant on it still needs a real `computeArtifacts()` call, discovery included, to reach it). */
+export declare function escalatedFindings(findings: readonly Finding[], family: FindingFamily): CompatibilityIssue[];
+/** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level -- matching `CompatibilityIssue.variable`'s own documented convention.
+ * @internal Exported for direct unit coverage -- see {@link escalatedFindings}'s own doc comment for why. */
+export declare function findingSubject(finding: Finding): string;
+/** Every file a finding names, as `CompatibilityIssue.files` -- empty when its location carries none (an ownership finding about a variable, which names no single file).
+ * @internal Exported for direct unit coverage -- see {@link escalatedFindings}'s own doc comment for why. */
+export declare function findingFiles(finding: Finding): string[];
+/**
+ * Runs schema discovery, linking, and every requested pass's pure `compute*()`
+ * step -- but never writes anything to disk. Throws `EnvProjectGenerationError`
+ * immediately if any requested output location escapes `root` (same
+ * fail-fast-before-any-work guarantee `generateEnvArtifacts()` has always
+ * given); otherwise returns every intermediate value without itself checking
+ * `blocking` findings, so callers (the write path below, and `--check`'s
+ * `checkEnvArtifacts()`) each decide when to throw on those.
+ *
+ * @remarks
+ * The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/
+ * Finding/Change -> `EvidenceModel`) are composed on every call,
+ * unconditionally, reusing the exact same builders `generateEvidenceModel()`
+ * calls -- not a second implementation of the same assembly. See ADR 0038.
+ */
+export declare function computeArtifacts(options: GenerateEnvArtifactsOptions): Promise<ComputeArtifactsResult>;
+/**
+ * Orchestrates {@link generateEnvManifest}/{@link generateDocumentation}/
+ * {@link generateUsageReport}, plus the persisted evidence artifact, by
+ * composing their shared private compute/write pipeline directly, running
+ * schema discovery+linking exactly once regardless of how many outputs are
+ * requested -- an orchestrator, not a new analysis engine (see ADR 0011).
+ *
+ * @remarks
+ * Two distinct atomicity guarantees, not one:
+ *  - **Compute atomicity (guaranteed)**: every requested pass's blocking
+ *    findings are checked, across all passes, before any pass writes
+ *    anything.
+ *  - **Write atomicity (NOT guaranteed, and not attempted)**: once writes
+ *    begin, each `fs.writeFile` is independent. A real I/O failure partway
+ *    through (disk full, permissions changed mid-run) can leave some
+ *    artifacts on disk and not others. Transactional (temp-file + rename)
+ *    writes across all three artifacts were considered and rejected as
+ *    disproportionate machinery for a rare failure mode -- see ADR 0011.
+ *
+ * @throws {EnvProjectGenerationError} If any requested output location escapes `root`, or if any requested pass reports a blocking finding.
+ */
+export declare function generateEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<GenerateEnvArtifactsResult>;
+//# sourceMappingURL=generate-env-artifacts.d.ts.map

package/dist/.dts/build/generate-env-artifacts.d.ts.map

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

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

@@ -0,0 +1,77 @@
+import type { EvidenceModel } from "./evidence-model.js";
+import type { LiveExpirationDates } from "./live-expirations.js";
+import type { BuildFileSystem } from "./types.js";
+/** Options for {@link generateEvidenceModel}. */
+export interface GenerateEvidenceModelOptions {
+    /** 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. Defaults to `["**\/env.schema.ts"]`. */
+    include?: string[] | undefined;
+    /** Glob patterns to exclude, shared across every pass. 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;
+    /**
+     * Where a previously-persisted evidence artifact lives, relative to
+     * `root` -- read (never written) as the baseline Change Model diffs
+     * against and dynamic-access citation freshness (ADR 0037) compares
+     * content hashes to. Independent of any `.ts` manifest a project may or
+     * may not also generate -- there is no derivation from a manifest's own
+     * location. Omitted: treated as the normal first-run state (everything
+     * reads as added, no citation-freshness baseline to compare against),
+     * never an error.
+     */
+    previousSnapshotLocation?: string | undefined;
+    /** Feeds Lifecycle Model's `expiring` list. Defaults to 30. */
+    expiringWithinDays?: number | undefined;
+    /**
+     * Supplies expiration metadata from a live source as a post-discovery
+     * override, applied to Lifecycle Model's (and Finding Model's
+     * `expiring-soon` findings') data only -- Contract Model still reflects the
+     * schema's own static `expiresAt`. See `live-expirations.ts` and ADR 0012.
+     */
+    liveExpirationDates?: LiveExpirationDates | undefined;
+    /**
+     * Resolves the commit SHA to stamp onto `EvidenceModel.provenance.commit`.
+     * Invoked at most once, after discovery/linking completes. env-cap never
+     * shells out to `git` itself -- see ADR 0012's callback precedent. Omitted:
+     * `commit` is `undefined`.
+     */
+    commit?: (() => Promise<string | undefined>) | undefined;
+}
+/**
+ * Node-only assembly orchestrator (ADR 0024, ADR 0031): runs schema
+ * discovery and linking once (via `assembleProject()`, shared with
+ * `computeArtifacts()`), then builds all seven canonical fact models by
+ * calling each model's own public builder directly -- this function
+ * introduces no derivation logic of its own, only sequencing and the shared
+ * discovery/linking every builder needs. The result is `deepFreeze()`-d
+ * before being returned.
+ *
+ * @remarks
+ * Deliberately never throws on a data-quality finding (a compatibility
+ * issue, an undocumented variable, an abandoned contract, ...) -- every one
+ * of those becomes a `Finding` in the returned model's `finding` field
+ * instead. This is a real difference from `generateEnvManifest()`, which
+ * throws by default: that's a "should I write this artifact" gate, while
+ * Evidence Model assembly is a read-only snapshot whose entire purpose is
+ * representing such issues as data for a consumer's own projection to act
+ * on (see ADR 0024's mission statement). It still throws
+ * `EnvProjectGenerationError` for a genuine configuration error --
+ * `previousSnapshotLocation` escaping `root`.
+ *
+ * The dependency-graph scan underlying Dependency Model (via
+ * `buildDependencyModel()`) and the one underlying Finding Model's
+ * ownership-related findings (via `computeUsage()`) each run their own,
+ * independent pass over the repository -- a real, accepted cost of calling
+ * each half's already-tested public building block directly rather than
+ * hand-deriving a second copy of either's logic here. Both are Node-only,
+ * dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
+ * an honest tradeoff, not an oversight.
+ */
+export declare function generateEvidenceModel(options: GenerateEvidenceModelOptions): Promise<EvidenceModel>;
+//# sourceMappingURL=generate-evidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,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;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAqJxB"}

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

@@ -0,0 +1,101 @@
+import type { BuildFileSystem } from "./types.js";
+import type { CompatibilityIssue } from "./compatibility.js";
+import { type DiscoveredContract, type DiscoveredContractSummary, type LinkResult } from "./link.js";
+import type { ParseWarning } from "./parse.js";
+/** Options for {@link generateEnvManifest}. */
+export interface GenerateEnvManifestOptions {
+    /** 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;
+    /** Output path for the generated manifest, relative to `root` (e.g. "src/generated/env.manifest.ts"). */
+    location: string;
+    /** Glob patterns for schema files. Defaults to `["**\/env.schema.ts"]`. */
+    include?: string[] | undefined;
+    /** Glob patterns to exclude. Defaults to node_modules/dist/.git. */
+    exclude?: string[] | undefined;
+    /**
+     * **Experimental** (see VERSIONING.md) -- explicit allowlist of installed
+     * package names whose declared `"envCap": { "schema": "<path>" }` entry
+     * point should also be discovered, so a contract that ships as its own
+     * separately-published package (no monorepo required) can be included in
+     * the manifest. Opt-in only: a package is never considered unless its
+     * exact name appears here. See ADR 0014.
+     */
+    packages?: readonly string[] | undefined;
+    /**
+     * **Experimental** (see VERSIONING.md) -- path to a tsconfig.json (relative to `root`)
+     * whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
+     * `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
+     * reached only through an alias isn't misreported as abandoned/unresolved. Defaults to
+     * `"tsconfig.json"` at `root` -- on automatically, no opt-in required, since (unlike
+     * `packages`) this never crosses a trust/versioning boundary: every resolved file is
+     * already local, already-trusted project source. Pass `false` to disable entirely. See
+     * ADR 0023.
+     */
+    tsconfig?: string | false | undefined;
+    /**
+     * "warn" (default): only provable incompatibilities (conflicting explicit processor
+     * return type annotations) block generation; everything else is reported as a warning.
+     * "throw": warnings are escalated to hard errors too, for stricter CI gates.
+     */
+    onIncompatibility?: "warn" | "throw" | undefined;
+}
+/** The result of a completed {@link generateEnvManifest} run. */
+export interface GenerateEnvManifestResult {
+    /** Absolute path the manifest file was written to. */
+    readonly outputPath: string;
+    /** Root-relative summary of every discovered contract, active or not. */
+    readonly contracts: readonly DiscoveredContractSummary[];
+    /** Non-blocking compatibility/exclusive-group issues (severity `"warning"`). */
+    readonly warnings: readonly CompatibilityIssue[];
+    /** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
+    readonly parseWarnings: readonly ParseWarning[];
+}
+/**
+ * Default value for {@link GenerateEnvManifestOptions.include}. A function
+ * (not a bare module-level `const`) so every call gets its own fresh array
+ * -- a shared literal used from many files (`evidence-cache.ts`,
+ * `generate-documentation.ts`, `generate-evidence.ts`,
+ * `generate-env-artifacts.ts`, `generate-usage.ts`) is a covered-static
+ * mutant magnet under Stryker's `coverageAnalysis: perTest` +
+ * `ignoreStatic: true` (a mutant on module-load code that's still referenced
+ * by a test is run anyway and falsely reported "Survived") -- see this
+ * drive's memory for the fully-documented limitation.
+ */
+export declare function defaultInclude(): string[];
+/** Default value for {@link GenerateEnvManifestOptions.exclude}. Same reasoning as {@link defaultInclude}. */
+export declare function defaultExclude(): string[];
+export interface ManifestComputation {
+    readonly activeContracts: readonly DiscoveredContract[];
+    readonly contractSummaries: readonly DiscoveredContractSummary[];
+    readonly warnings: readonly CompatibilityIssue[];
+    readonly blocking: readonly CompatibilityIssue[];
+}
+/**
+ * Pure -- no I/O. Runs compatibility (0005) and exclusive-group (0009,
+ * always-error, never gated by `onIncompatibility`) checks against an
+ * already-discovered contract graph and applies the `onIncompatibility` gate.
+ * Shared by the standalone `generateEnvManifest()` (which discovers its own
+ * graph) and `generate-env-artifacts.ts` (which discovers once and reuses it across
+ * manifest/docs/usage) -- see ADR 0011.
+ */
+export declare function computeManifest(root: string, linkResult: LinkResult, onIncompatibility: "warn" | "throw"): ManifestComputation;
+/** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
+export declare function writeManifest(outputPath: string, activeContracts: readonly DiscoveredContract[], fs: BuildFileSystem): Promise<void>;
+/**
+ * Build-time only. Discovers `env.schema.ts` files, statically analyzes them
+ * (never executes them) to link `createEnv()`/`documentEnv()` calls, checks
+ * for provable incompatibilities between duplicate variable declarations,
+ * and writes a deterministic manifest file that re-exports every discovered
+ * active contract.
+ *
+ * @remarks
+ * Never call this at application startup or import it from
+ * runtime code -- wire it into an npm script, a bundler plugin, or a CI
+ * step instead.
+ *
+ * @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
+ */
+export declare function generateEnvManifest(options: GenerateEnvManifestOptions): Promise<GenerateEnvManifestResult>;
+//# sourceMappingURL=generate-manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+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,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAgBzC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAClC,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAyDpC"}