@maverickcer/env-cap 0.2.0 → 0.3.0

package/dist/.dts/build/resolve-import.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-import.d.ts","sourceRoot":"","sources":["../../../src/build/resolve-import.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAA;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B;AAWD,8GAA8G;AAC9G,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6HAA6H;IAC7H,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,8HAA8H;IAC9H,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACnE,0IAA0I;IAC1I,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAC3D,iMAAiM;IACjM,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}

package/dist/.dts/build/resolve-package-schema.d.ts

@@ -1,99 +0,0 @@
-import type { ParseWarning } from "./parse.js";
-/**
- * Cross-package schema discovery (ADR 0014, Experimental -- see VERSIONING.md).
- *
- * Resolves an explicitly allow-listed installed package name to the one
- * schema file it declares via its own `"envCap": { "schema": "<path>" }`
- * package.json field. Every step here is `createRequire(...).resolve(...)`,
- * `fs.stat`/`fs.realpath`/`fs.readFile` on a path already fully known --
- * never a `readdir` walk of any directory, named package or not. This is a
- * completely separate code path from `discover.ts`'s `discoverSchemaFiles()`,
- * which continues to unconditionally prune `node_modules` during its own
- * walk exactly as before; the two never overlap.
- *
- * This module only ever locates a file. It never imports, requires, or
- * executes it -- a package-resolved file is fed into the exact same
- * `parseSchemaFile()`/AST-only pipeline as a locally-discovered file,
- * indistinguishable from it after resolution. See ADR 0002 and ADR 0014.
- */
-export declare const SCHEMA_FILE_EXTENSIONS: readonly [".ts", ".tsx"];
-/** 1 MiB. New hardening specific to this trust tier -- a package crosses a
- *  real versioning/trust boundary that locally-discovered source doesn't,
- *  so this caps the cost of parsing an oversized or adversarial file before
- *  any of its content is even read into memory. See ADR 0014. */
-export declare const MAX_PACKAGE_SCHEMA_FILE_BYTES = 1048576;
-export type PackageResolutionFailureCode = "PACKAGE_NOT_FOUND" | "MALFORMED_PACKAGE_JSON" | "FIELD_MISSING" | "INVALID_EXTENSION" | "OUTSIDE_PACKAGE" | "FILE_TOO_LARGE";
-/** Both the authored and resolved forms are kept -- diagnostics benefit from
- *  showing exactly what a package author wrote versus what it resolved to. */
-export interface PackageOrigin {
-    /** The allow-listed package name that declared this schema. */
-    readonly packageName: string;
-    /** The `"envCap.schema"` value exactly as the package author wrote it. */
-    readonly declaredField: string;
-    /** Absolute, realpath-canonicalized path to the resolved schema file. */
-    readonly resolvedFile: string;
-    /** Absolute, realpath-canonicalized path to the package's own directory. */
-    readonly packageDir: string;
-}
-export type PackageSchemaResolutionResult = {
-    readonly ok: true;
-    readonly origin: PackageOrigin;
-} | {
-    readonly ok: false;
-    readonly code: PackageResolutionFailureCode;
-    readonly reason: string;
-};
-/**
- * Resolves one allow-listed package name. Memoized in a caller-owned
- * `cache` (one per `generate*()` invocation, shared with linking/dependency-
- * graph resolution) so a name referenced from multiple places -- multiple
- * scanned files bare-importing the same package, or a duplicate entry in
- * `packages` -- is only ever resolved once. The cache is populated with the
- * in-flight promise before it settles, so concurrent callers await the same
- * resolution rather than racing duplicate work.
- */
-export declare function resolvePackageSchemaFile(packageName: string, root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>): Promise<PackageSchemaResolutionResult>;
-export interface ResolvedPackageFile {
-    readonly packageName: string;
-    readonly file: string;
-}
-export interface ResolvePackagesResult {
-    readonly files: readonly ResolvedPackageFile[];
-    /** Keyed by resolved file path, for `DiscoveredContract.packageOrigin` lookups downstream. */
-    readonly origins: ReadonlyMap<string, PackageOrigin>;
-    readonly warnings: readonly ParseWarning[];
-}
-/**
- * Resolves every allow-listed package name. Input is deduplicated first, so
- * a duplicate entry in `packages` (accidental or defensive) produces exactly
- * one resolution attempt and, on failure, exactly one warning -- never two.
- * Never throws: every failure becomes one `ParseWarning`, consistent with
- * every other static-analysis boundary in this codebase.
- */
-export declare function resolveAllowlistedPackages(packages: readonly string[], root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>): Promise<ResolvePackagesResult>;
-/**
- * Combines local schema-discovery hits with package-resolved files into one
- * deduplicated list, keyed by realpath rather than lexical absolute path --
- * package-resolved files are already realpath-canonicalized (see
- * `resolveUncached` above), but local `discoverSchemaFiles()` hits are plain
- * `readdir`-derived absolute paths that may themselves traverse a symlink (a
- * symlinked `root`, or an included path reached through one). Deduplicating
- * on the lexical path alone would miss the case where the same physical file
- * is reached twice through two different symlinked routes -- one via local
- * glob discovery, one via package resolution -- and silently double-count it
- * into two identical contracts, including the more mundane case of a package
- * that's both locally glob-reachable (e.g. during a monorepo migration) and
- * explicitly allow-listed. On a collision, the local path string identity
- * wins (the package-resolved duplicate is dropped).
- */
-export declare function mergeLocalAndPackageFiles(localFiles: readonly string[], packageFiles: readonly string[]): Promise<string[]>;
-/**
- * Bare-specifier-to-allowlist matching, used by `resolve-import.ts`'s
- * `resolveImportSpecifier()` as its package-resolution fallback. Only ever
- * attempts resolution for a specifier that is (or is a subpath of) an
- * allow-listed package name -- any other bare specifier is not this
- * mechanism's concern and returns `undefined` immediately, identical to
- * `resolveRelativeImport()`'s existing bare-specifier no-op.
- */
-export declare function resolvePackageImport(specifier: string, allowedPackages: readonly string[], root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>): Promise<string | undefined>;
-//# sourceMappingURL=resolve-package-schema.d.ts.map

package/dist/.dts/build/resolve-package-schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-package-schema.d.ts","sourceRoot":"","sources":["../../../src/build/resolve-package-schema.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,sBAAsB,0BAA2B,CAAA;AAE9D;;;iEAGiE;AACjE,eAAO,MAAM,6BAA6B,UAAY,CAAA;AAItD,MAAM,MAAM,4BAA4B,GACpC,mBAAmB,GACnB,wBAAwB,GACxB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB;8EAC8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AA0LhG;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,GACzD,OAAO,CAAC,6BAA6B,CAAC,CAOxC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC9C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,GACzD,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,GACzD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B"}

package/dist/.dts/build/resolve-tsconfig-paths.d.ts

@@ -1,100 +0,0 @@
-import ts from "typescript";
-import type { ParseWarning } from "./parse.js";
-/**
- * TypeScript path-alias resolution (ADR 0023, Experimental -- see VERSIONING.md).
- *
- * Resolves a bare import specifier (`"@/lib/env.schema.js"`) against a project's own
- * `tsconfig.json` `compilerOptions.paths`/`baseUrl`, so a schema or consumer reached only
- * through an alias isn't misreported by `link.ts`/`dependency-graph.ts` as unresolved or
- * abandoned. Unlike `resolve-package-schema.ts` (ADR 0014), this never crosses a
- * trust/versioning boundary -- every resolved file is already local, already-trusted
- * project source -- so it is on by default (auto-detecting `root/tsconfig.json`) rather
- * than requiring an explicit allowlist.
- *
- * The actual `paths`/`baseUrl` matching algorithm (longest-prefix matching, `*` wildcard
- * substitution, multiple fallback targets, `extends`-chain merging, JSONC parsing) is
- * delegated entirely to the TypeScript compiler via `ts.resolveModuleName()` and
- * `ts.parseJsonConfigFileContent()` -- the same functions `tsc`/`tsserver` themselves use --
- * rather than reimplemented here. This module's own logic is limited to loading the config,
- * caching resolutions, and enforcing the `node_modules` safety boundary below.
- */
-/** Parsed `tsconfig.json` `paths`/`baseUrl` configuration, immutable for the life of one generate*() run. See {@link loadTsconfigPaths}. */
-export interface TsconfigPathsResolution {
-    /** The subset of `compilerOptions` `ts.resolveModuleName()` needs -- at minimum `paths` and/or `baseUrl`. */
-    readonly compilerOptions: ts.CompilerOptions;
-    /** Absolute path of the tsconfig.json this was loaded from, for diagnostics. */
-    readonly configFile: string;
-}
-/**
- * Opaque memoization for {@link resolveAliasImport}, created once per generate*() run via
- * {@link createAliasResolutionCache} and threaded through `ImportResolutionContext`. Kept
- * distinct from `TsconfigPathsResolution` (immutable config) so the cache's internal
- * representation stays free to change without touching that type's shape.
- */
-export interface AliasResolutionCache {
-    /**
-     * Keyed by `` `${importingFile}\0${specifier}` ``, not by `specifier` alone. With one
-     * fixed `compilerOptions` object and no project-reference support, `paths`-pattern
-     * substitution itself doesn't depend on the importing file -- but `ts.resolveModuleName()`'s
-     * fallback behavior when `paths` doesn't match a real file (classic-mode ancestor search,
-     * extension-preference edge cases) legitimately can. A `Map`, not a network call, so
-     * keying defensively by both costs nothing.
-     */
-    readonly resolutions: Map<string, string | undefined>;
-}
-/** Creates a fresh, empty {@link AliasResolutionCache} for one generate*()/computeArtifacts() run. */
-export declare function createAliasResolutionCache(): AliasResolutionCache;
-export interface LoadTsconfigPathsResult {
-    readonly resolution: TsconfigPathsResolution | undefined;
-    readonly warning: ParseWarning | undefined;
-}
-/**
- * Loads and parses a `tsconfig.json` for alias resolution. Called exactly once per
- * `generate*()`/`computeArtifacts()` invocation, at the same point
- * `resolveAllowlistedPackages()` is already called once -- so at most one tsconfig-related
- * warning is ever produced per run, never once per file scanned.
- *
- * @remarks
- * `tsconfigOption === false` disables alias resolution entirely.
- * `tsconfigOption === undefined` (the default) looks for `root/tsconfig.json` exactly --
- * deliberately not `ts.findConfigFile()`'s upward directory walk, since every other
- * root-relative mechanism in this codebase (schema discovery, `packages` resolution)
- * treats `root` as a hard boundary. A missing default tsconfig is silent (most projects
- * don't use aliases); a missing *explicit* `tsconfigOption` is a real misconfiguration and
- * warns. `jsconfig.json` is intentionally not auto-detected -- pass `tsconfig:
- * "jsconfig.json"` explicitly if needed; this loader only cares about the file's JSON
- * shape, not its name.
- *
- * The gate for building a resolution is "`paths` non-empty OR `baseUrl` set", not `paths`
- * alone -- a `baseUrl`-only tsconfig (no `paths` at all) still makes TypeScript resolve
- * bare specifiers relative to `baseUrl`, and `ts.resolveModuleName()` already handles that
- * once `compilerOptions.baseUrl` is passed through.
- */
-export declare function loadTsconfigPaths(root: string, tsconfigOption: string | false | undefined): Promise<LoadTsconfigPathsResult>;
-/**
- * Resolves one bare import specifier against a project's `tsconfig.json` `paths`/`baseUrl`,
- * or returns `undefined` if it doesn't resolve through this mechanism.
- *
- * @remarks
- * Necessarily synchronous -- `ts.resolveModuleName()` has no async form, matching how
- * `tsc`/`tsserver` themselves always call it. `ts.sys` is used directly as the resolution
- * host (an existing Node-backed singleton the `typescript` package exports; nothing to
- * construct).
- *
- * Two safety/scope filters apply to any candidate `ts.resolveModuleName()` returns,
- * independent of its own internal fallback behavior:
- *  - **Never resolves into `node_modules`.** `ts.resolveModuleName()` can, in principle,
- *    fall through to classic Node resolution and land inside `node_modules`; any resolved
- *    path containing a `node_modules` path segment (checked after `path.normalize()`, so
- *    mixed separators can't slip past it on Windows) is discarded here. Bare package
- *    specifiers continue to be handled exclusively by `resolvePackageImport()`
- *    (ADR 0014) -- this mechanism never overlaps with that trust boundary.
- *  - **`.ts`/`.tsx` only.** Matches `resolveRelativeImport()`'s own existing candidate set
- *    and `resolve-package-schema.ts`'s `SCHEMA_FILE_EXTENSIONS` -- this codebase's static-
- *    analysis pipeline is `.ts`/`.tsx` only today. A resolved non-`.ts`/`.tsx` file is a
- *    real risk, not just a gap: feeding it straight into `ts.createSourceFile()` wouldn't
- *    error, it would silently parse garbage -- exactly the "guess" this codebase's
- *    warn-don't-guess philosophy exists to avoid.
- */
-export declare function resolveAliasImport(specifier: string, importingFile: string, resolution: TsconfigPathsResolution, cache: AliasResolutionCache): string | undefined;
-//# sourceMappingURL=resolve-tsconfig-paths.d.ts.map

package/dist/.dts/build/resolve-tsconfig-paths.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-tsconfig-paths.d.ts","sourceRoot":"","sources":["../../../src/build/resolve-tsconfig-paths.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,YAAY,CAAA;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AAEH,4IAA4I;AAC5I,MAAM,WAAW,uBAAuB;IACtC,6GAA6G;IAC7G,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC,eAAe,CAAA;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACtD;AAED,sGAAsG;AACtG,wBAAgB,0BAA0B,IAAI,oBAAoB,CAEjE;AAWD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,GAAG,SAAS,CAAA;IACxD,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,GACzC,OAAO,CAAC,uBAAuB,CAAC,CAqClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,uBAAuB,EACnC,KAAK,EAAE,oBAAoB,GAC1B,MAAM,GAAG,SAAS,CAiBpB"}

package/dist/.dts/build/resolve-within-root.d.ts

@@ -1,35 +0,0 @@
-import type { CompatibilityIssue } from "./compatibility.js";
-export type ResolveWithinRootResult = {
-    readonly ok: true;
-    readonly resolved: string;
-} | {
-    readonly ok: false;
-    readonly issue: CompatibilityIssue;
-};
-/**
- * Plain lexical bounds-check: is `targetPath` inside `baseDir`? Shared by
- * `resolveWithinRoot()` below (output paths, checked lexically since they
- * usually don't exist on disk yet) and `resolve-package-schema.ts` (which
- * additionally re-checks this against `fs.realpath`-resolved paths, since a
- * package-declared schema path both exists on disk and crosses a real trust
- * boundary -- see ADR 0014). Boundary-agnostic on purpose: neither caller's
- * notion of "root" is baked in here.
- */
-export declare function isWithinDirectory(baseDir: string, targetPath: string): boolean;
-/**
- * Resolves `location` against `root` and checks the result doesn't escape it
- * (e.g. `location: "../../malicious.ts"`, or an absolute path on another
- * branch of the filesystem entirely). Discovery (`include`/`exclude`) is
- * already safe by construction -- it only ever walks *down* from `root` via
- * `readdir`, so a pattern can't make it read outside `root`. Output
- * locations have no such structural guarantee, since `path.resolve` happily
- * walks back out via `..` segments, so this is a plain lexical bounds-check
- * (not a symlink-aware `realpath` check -- these are *output* paths that
- * usually don't exist yet).
- *
- * Never throws itself -- returns a `CompatibilityIssue`-shaped finding on
- * escape so each generator function (`generateEnvManifest`, `generateDocumentation`,
- * `generateUsageReport`, `generateEnvArtifacts`) can wrap it in its own error type.
- */
-export declare function resolveWithinRoot(root: string, location: string, optionName: string, functionName: string): ResolveWithinRootResult;
-//# sourceMappingURL=resolve-within-root.d.ts.map

package/dist/.dts/build/resolve-within-root.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-within-root.d.ts","sourceRoot":"","sources":["../../../src/build/resolve-within-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,uBAAuB,CAgBzB"}