env-cap build-time entry point (@maverickcer/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 @maverickcer/env-cap/node ({ nodeBuildFileSystem }).
The public API is deliberately curated: four generator functions
(generateEnvManifest, generateDocumentation, generateUsageReport,
generateEnvArtifacts) plus the lower-level discovery/linking primitives,
justified by real external use (custom CI scripts, bundler plugins) and
promoted to Stable alongside the orchestrators per ADR 0045 -- see
VERSIONING.md. 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 a 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 a tsconfig option for resolving
import specifiers written as TypeScript path aliases (e.g. "@/lib/env")
against a project's own tsconfig.jsonpaths/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.
Verifies every requested artifact (manifest/docs/envExample/usage)
matches what a real generateEnvArtifacts run would produce, without
writing anything.
env-cap build-time entry point (
@maverickcer/env-cap/build).Discovery, static analysis, cross-file linking, and manifest/docs/ ownership-report generation only -- this module imports
node:pathand (indirectly)typescript, and must never be imported from runtime/ browser/edge code. It has no knowledge ofcreateEnv/documentEnv/validateEnvand performs no environment validation, and never executes a discovered schema file.It never imports
node:fs(ADR 0040):./buildis a library surface, so the caller supplies the filesystem capability. Every public options object below carries a requiredfs: BuildFileSystemfield; theenv-capCLI builds a concretenode:fs/promisesadapter and hands it in. A consumer running these functions from their own Node build script imports the same adapter from@maverickcer/env-cap/node({ nodeBuildFileSystem }).The public API is deliberately curated: four generator functions (
generateEnvManifest,generateDocumentation,generateUsageReport,generateEnvArtifacts) plus the lower-level discovery/linking primitives, justified by real external use (custom CI scripts, bundler plugins) and promoted to Stable alongside the orchestrators per ADR 0045 -- seeVERSIONING.md. The dependency-ownership engine's internals (scanning, graph-building, derivation) are intentionally NOT exported here -- see ADR 0010 and ADR 0011.env-capanswers ownership/visibility questions; it doesn't ship a general-purpose static-analysis toolkit. The scanner follows object-destructuring and one level of file-uniqueconstaliasing, and records every other shape as an explicitescape(ADR 0039); a variable on an escaped contract isindeterminate, never a falseunconsumed, and the finding'sreasoncites every escape site.Each generator also accepts a
packagesoption (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 andVERSIONING.md.Each generator also accepts a
tsconfigoption for resolving import specifiers written as TypeScript path aliases (e.g."@/lib/env") against a project's owntsconfig.jsonpaths/baseUrlduring static analysis. Unlikepackages, this is on by default (auto-detectingtsconfig.jsonatroot) since it never crosses a trust/versioning boundary -- see ADR 0023 andVERSIONING.md.