@maverickcer/env-cap 0.4.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -12
- package/dist/.dts/build/index.d.ts +2 -2
- package/dist/.dts/build/index.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +110 -2
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts +8 -0
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/parse.d.ts +8 -0
- package/dist/.dts/build/parse.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +40 -0
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/build-BBD3FEXB.js +5148 -0
- package/dist/build-BBD3FEXB.js.map +1 -0
- package/dist/build.cjs +5021 -6
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +5020 -7
- package/dist/build.js.map +1 -1
- package/dist/chunk-4GUTPGR6.js +11 -0
- package/dist/{chunk-QUSAQJ52.js.map → chunk-4GUTPGR6.js.map} +1 -1
- package/dist/cli/index.js +580 -38
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +701 -1
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +701 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/evidence.cjs +59 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js +59 -1
- package/dist/evidence.js.map +1 -1
- package/dist/helpers.cjs +379 -1
- package/dist/helpers.cjs.map +1 -1
- package/dist/helpers.js +379 -1
- package/dist/helpers.js.map +1 -1
- package/dist/index.cjs +249 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +249 -2
- package/dist/index.js.map +1 -1
- package/dist/node.cjs +27 -1
- package/dist/node.cjs.map +1 -1
- package/dist/node.js +27 -1
- package/dist/node.js.map +1 -1
- package/package.json +5 -3
- package/schemas/env-cap-report.schema.json +37 -3
- package/dist/build-ICYKXFRE.js +0 -12
- package/dist/build-ICYKXFRE.js.map +0 -1
- package/dist/chunk-QUSAQJ52.js +0 -3
package/dist/cli/index.js
CHANGED
|
@@ -1,5 +1,46 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import
|
|
2
|
+
import {
|
|
3
|
+
readToolVersion
|
|
4
|
+
} from "../chunk-4GUTPGR6.js";
|
|
5
|
+
|
|
6
|
+
// src/cli/index.ts
|
|
7
|
+
import { realpathSync } from "fs";
|
|
8
|
+
import { pathToFileURL } from "url";
|
|
9
|
+
|
|
10
|
+
// src/cli/filesystem.ts
|
|
11
|
+
import fs from "fs/promises";
|
|
12
|
+
function readFile(path2, encoding) {
|
|
13
|
+
return fs.readFile(path2, encoding);
|
|
14
|
+
}
|
|
15
|
+
function writeFile(path2, data, encoding) {
|
|
16
|
+
return fs.writeFile(path2, data, encoding);
|
|
17
|
+
}
|
|
18
|
+
async function mkdir(path2, options) {
|
|
19
|
+
await fs.mkdir(path2, options);
|
|
20
|
+
}
|
|
21
|
+
function readdir(path2, options) {
|
|
22
|
+
return fs.readdir(path2, options);
|
|
23
|
+
}
|
|
24
|
+
function stat(path2) {
|
|
25
|
+
return fs.stat(path2);
|
|
26
|
+
}
|
|
27
|
+
function realpath(path2) {
|
|
28
|
+
return fs.realpath(path2);
|
|
29
|
+
}
|
|
30
|
+
var nodeBuildFileSystem = {
|
|
31
|
+
readFile,
|
|
32
|
+
writeFile,
|
|
33
|
+
mkdir,
|
|
34
|
+
readdir,
|
|
35
|
+
stat,
|
|
36
|
+
realpath
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
// src/cli/init.ts
|
|
40
|
+
import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
|
|
41
|
+
import path from "path";
|
|
42
|
+
function usage() {
|
|
43
|
+
return `Usage: env-cap init
|
|
3
44
|
|
|
4
45
|
Scaffolds a minimal env-cap starting point into the current directory:
|
|
5
46
|
|
|
@@ -9,7 +50,10 @@ Scaffolds a minimal env-cap starting point into the current directory:
|
|
|
9
50
|
Never overwrites an existing file, never runs anything, never edits
|
|
10
51
|
package.json. Everything else -- generating artifacts, wiring validateEnv()
|
|
11
52
|
into startup -- is printed as a next step. Run generation afterwards with
|
|
12
|
-
\`node scripts/generate-env.mjs\` or \`npx env-cap --location <path
|
|
53
|
+
\`node scripts/generate-env.mjs\` or \`npx env-cap --location <path>\`.`;
|
|
54
|
+
}
|
|
55
|
+
function schemaTemplate() {
|
|
56
|
+
return `// Starter env-cap capability contract -- expand it: add your real variables,
|
|
13
57
|
// split into per-capability files (e.g. features/<name>/env.schema.ts), or
|
|
14
58
|
// keep everything here. env-cap discovers every **/env.schema.ts by default.
|
|
15
59
|
//
|
|
@@ -38,7 +82,10 @@ documentEnv(schema, {
|
|
|
38
82
|
},
|
|
39
83
|
},
|
|
40
84
|
})
|
|
41
|
-
|
|
85
|
+
`;
|
|
86
|
+
}
|
|
87
|
+
function generatorTemplate() {
|
|
88
|
+
return `// Build-time only. Run with \`node scripts/generate-env.mjs\`, or wire it into
|
|
42
89
|
// a package.json script (e.g. "generate:env"). Never imported by app code.
|
|
43
90
|
import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
|
|
44
91
|
import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
|
|
@@ -61,22 +108,290 @@ const result = await generateEnvArtifacts({
|
|
|
61
108
|
console.log(\`Discovered \${result.manifest?.contracts.length ?? 0} contract(s).\`)
|
|
62
109
|
if (result.manifest?.outputPath) console.log(\`Wrote manifest: \${result.manifest.outputPath}\`)
|
|
63
110
|
if (result.docs?.docsPath) console.log(\`Wrote docs: \${result.docs.docsPath}\`)
|
|
64
|
-
|
|
65
|
-
|
|
111
|
+
`;
|
|
112
|
+
}
|
|
113
|
+
function assertIsProject(cwd) {
|
|
114
|
+
const packageJsonPath = path.join(cwd, "package.json");
|
|
115
|
+
if (!existsSync(packageJsonPath)) {
|
|
116
|
+
throw new Error(`no package.json found at ${packageJsonPath} -- run \`npm init\` first.`);
|
|
117
|
+
}
|
|
118
|
+
let parsed;
|
|
119
|
+
try {
|
|
120
|
+
parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
|
|
121
|
+
} catch {
|
|
122
|
+
throw new Error(`package.json at ${packageJsonPath} is not valid JSON.`);
|
|
123
|
+
}
|
|
124
|
+
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
|
|
125
|
+
throw new Error(`package.json at ${packageJsonPath} must contain a top-level object.`);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
function schemaDirectory(cwd) {
|
|
129
|
+
const srcDir = path.join(cwd, "src");
|
|
130
|
+
return existsSync(srcDir) && statSync(srcDir).isDirectory() ? srcDir : cwd;
|
|
131
|
+
}
|
|
132
|
+
function planTargets(cwd) {
|
|
133
|
+
const schemaPath = path.join(schemaDirectory(cwd), "env.schema.ts");
|
|
134
|
+
const scriptsDir = path.join(cwd, "scripts");
|
|
135
|
+
const generatorPath = path.join(scriptsDir, "generate-env.mjs");
|
|
136
|
+
for (const filePath of [schemaPath, generatorPath]) {
|
|
137
|
+
if (existsSync(filePath) && statSync(filePath).isDirectory()) {
|
|
138
|
+
throw new Error(`${filePath} already exists and is a directory.`);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
if (existsSync(scriptsDir) && !statSync(scriptsDir).isDirectory()) {
|
|
142
|
+
throw new Error(`${scriptsDir} already exists and is not a directory.`);
|
|
143
|
+
}
|
|
144
|
+
return [
|
|
145
|
+
{
|
|
146
|
+
label: path.relative(cwd, schemaPath),
|
|
147
|
+
absolutePath: schemaPath,
|
|
148
|
+
content: schemaTemplate()
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
label: path.relative(cwd, generatorPath),
|
|
152
|
+
absolutePath: generatorPath,
|
|
153
|
+
content: generatorTemplate()
|
|
154
|
+
}
|
|
155
|
+
];
|
|
156
|
+
}
|
|
157
|
+
function writeIfAbsent(filePath, content) {
|
|
158
|
+
mkdirSync(path.dirname(filePath), { recursive: true });
|
|
159
|
+
try {
|
|
160
|
+
writeFileSync(filePath, content, { flag: "wx" });
|
|
161
|
+
return "created";
|
|
162
|
+
} catch (error) {
|
|
163
|
+
if (isFileExistsError(error)) return "skipped";
|
|
164
|
+
throw error;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
function isFileExistsError(error) {
|
|
168
|
+
return typeof error === "object" && error !== null && error.code === "EEXIST";
|
|
169
|
+
}
|
|
170
|
+
function runInit(cwd) {
|
|
171
|
+
assertIsProject(cwd);
|
|
172
|
+
const targets = planTargets(cwd);
|
|
173
|
+
const results = targets.map((target) => ({
|
|
174
|
+
target,
|
|
175
|
+
outcome: writeIfAbsent(target.absolutePath, target.content)
|
|
176
|
+
}));
|
|
177
|
+
return { results, schemaRelPath: targets[0].label };
|
|
178
|
+
}
|
|
179
|
+
function renderReport(report) {
|
|
180
|
+
const lines = ["env-cap initialized", ""];
|
|
181
|
+
const created = report.results.filter((r) => r.outcome === "created");
|
|
182
|
+
const skipped = report.results.filter((r) => r.outcome === "skipped");
|
|
183
|
+
if (created.length > 0) {
|
|
184
|
+
lines.push("Created:");
|
|
185
|
+
for (const r of created) lines.push(` + ${r.target.label}`);
|
|
186
|
+
lines.push("");
|
|
187
|
+
}
|
|
188
|
+
if (skipped.length > 0) {
|
|
189
|
+
lines.push("Skipped (already exists):");
|
|
190
|
+
for (const r of skipped) lines.push(` - ${r.target.label}`);
|
|
191
|
+
lines.push("");
|
|
192
|
+
}
|
|
193
|
+
const manifestImport = report.schemaRelPath.startsWith("src" + path.sep) ? "./generated/env.manifest.js" : "./src/generated/env.manifest.js";
|
|
194
|
+
lines.push(
|
|
195
|
+
"Next:",
|
|
196
|
+
" 1. Generate the manifest + docs: node scripts/generate-env.mjs",
|
|
197
|
+
` Requires "typescript" (>=5) in your project -- it's how env-cap parses`,
|
|
198
|
+
" env.schema.ts by static analysis. Add it if you don't already have it:",
|
|
199
|
+
" npm install --save-dev typescript",
|
|
200
|
+
" 2. Validate once at app startup:",
|
|
201
|
+
"",
|
|
202
|
+
' import { validateEnv } from "@maverickcer/env-cap"',
|
|
203
|
+
` import { manifest } from "${manifestImport}"`,
|
|
204
|
+
" await validateEnv({ manifest, values: process.env })",
|
|
205
|
+
"",
|
|
206
|
+
" 3. Read validated values through the contract: exampleEnv.EXAMPLE_API_URL",
|
|
207
|
+
"",
|
|
208
|
+
"env-cap init edited no package.json script -- add one if you want, e.g.",
|
|
209
|
+
' "generate:env": "node scripts/generate-env.mjs"'
|
|
210
|
+
);
|
|
211
|
+
return lines.join("\n");
|
|
212
|
+
}
|
|
213
|
+
function runInitCommand(rest) {
|
|
214
|
+
if (rest.includes("--help") || rest.includes("-h")) {
|
|
215
|
+
process.stdout.write(`${usage()}
|
|
216
|
+
`);
|
|
217
|
+
return 0;
|
|
218
|
+
}
|
|
219
|
+
if (rest.length > 0) {
|
|
220
|
+
process.stderr.write(`env-cap init takes no arguments (got: ${rest.join(" ")})
|
|
66
221
|
|
|
67
222
|
${usage()}
|
|
68
|
-
`);
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
223
|
+
`);
|
|
224
|
+
return 1;
|
|
225
|
+
}
|
|
226
|
+
try {
|
|
227
|
+
process.stdout.write(`${renderReport(runInit(process.cwd()))}
|
|
228
|
+
`);
|
|
229
|
+
return 0;
|
|
230
|
+
} catch (error) {
|
|
231
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
232
|
+
process.stderr.write(`env-cap init failed: ${message}
|
|
233
|
+
`);
|
|
234
|
+
return 1;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
// src/cli/json.ts
|
|
239
|
+
var JSON_SCHEMA_VERSION = 1;
|
|
240
|
+
var TOOL_VERSION = readToolVersion();
|
|
241
|
+
function hasIssues(error) {
|
|
242
|
+
return typeof error === "object" && error !== null && Array.isArray(error.issues);
|
|
243
|
+
}
|
|
244
|
+
function serializeSuccess(result, checkResult, includeEvidence = false, requested) {
|
|
245
|
+
const { evidence, ...rest } = result;
|
|
246
|
+
return {
|
|
247
|
+
schemaVersion: JSON_SCHEMA_VERSION,
|
|
248
|
+
kind: "env-cap-report",
|
|
249
|
+
toolVersion: TOOL_VERSION,
|
|
250
|
+
ok: true,
|
|
251
|
+
requested: requested ?? {
|
|
252
|
+
manifest: rest.manifest !== void 0,
|
|
253
|
+
docs: rest.docs !== void 0,
|
|
254
|
+
usage: rest.usage !== void 0,
|
|
255
|
+
evidence: includeEvidence
|
|
256
|
+
},
|
|
257
|
+
...rest,
|
|
258
|
+
...includeEvidence ? { evidence } : {},
|
|
259
|
+
...checkResult ? { checkResult } : {}
|
|
260
|
+
};
|
|
261
|
+
}
|
|
262
|
+
function serializeFailure(error) {
|
|
263
|
+
return {
|
|
264
|
+
schemaVersion: JSON_SCHEMA_VERSION,
|
|
265
|
+
kind: "env-cap-report",
|
|
266
|
+
toolVersion: TOOL_VERSION,
|
|
267
|
+
ok: false,
|
|
268
|
+
error: {
|
|
269
|
+
name: error instanceof Error ? error.name : "Error",
|
|
270
|
+
message: error instanceof Error ? error.message : String(error),
|
|
271
|
+
// exactOptionalPropertyTypes: omit the key rather than set it to
|
|
272
|
+
// `undefined` when the thrown error carries no issues of its own.
|
|
273
|
+
...hasIssues(error) ? { issues: error.issues } : {}
|
|
274
|
+
}
|
|
275
|
+
};
|
|
276
|
+
}
|
|
277
|
+
function writeJson(payload) {
|
|
278
|
+
process.stdout.write(`${JSON.stringify(payload, null, 2)}
|
|
279
|
+
`);
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// src/cli/index.ts
|
|
283
|
+
function setRoot(a, v) {
|
|
284
|
+
a.root = v;
|
|
285
|
+
}
|
|
286
|
+
function setLocation(a, v) {
|
|
287
|
+
a.location = v;
|
|
288
|
+
}
|
|
289
|
+
function pushInclude(a, v) {
|
|
290
|
+
a.include.push(v);
|
|
291
|
+
}
|
|
292
|
+
function pushExclude(a, v) {
|
|
293
|
+
a.exclude.push(v);
|
|
294
|
+
}
|
|
295
|
+
function pushPackage(a, v) {
|
|
296
|
+
a.packages.push(v);
|
|
297
|
+
}
|
|
298
|
+
function setTsconfig(a, v) {
|
|
299
|
+
a.tsconfig = v;
|
|
300
|
+
}
|
|
301
|
+
function setEvidence(a, v) {
|
|
302
|
+
a.evidence = v;
|
|
303
|
+
}
|
|
304
|
+
var VALUE_FLAGS = {
|
|
305
|
+
"--root": setRoot,
|
|
306
|
+
"--location": setLocation,
|
|
307
|
+
"--include": pushInclude,
|
|
308
|
+
"--exclude": pushExclude,
|
|
309
|
+
"--package": pushPackage,
|
|
310
|
+
"--tsconfig": setTsconfig,
|
|
311
|
+
"--evidence": setEvidence
|
|
312
|
+
};
|
|
313
|
+
function setNoTsconfig(a) {
|
|
314
|
+
a.tsconfig = false;
|
|
315
|
+
}
|
|
316
|
+
function setStrict(a) {
|
|
317
|
+
a.strict = true;
|
|
318
|
+
}
|
|
319
|
+
function setStrictDocs(a) {
|
|
320
|
+
a.strictDocs = true;
|
|
321
|
+
}
|
|
322
|
+
function setStrictOwnership(a) {
|
|
323
|
+
a.strictOwnership = true;
|
|
324
|
+
}
|
|
325
|
+
function setJson(a) {
|
|
326
|
+
a.json = true;
|
|
327
|
+
}
|
|
328
|
+
function setCheck(a) {
|
|
329
|
+
a.check = true;
|
|
330
|
+
}
|
|
331
|
+
function setHelp(a) {
|
|
332
|
+
a.help = true;
|
|
333
|
+
}
|
|
334
|
+
var BOOL_FLAGS = {
|
|
335
|
+
"--no-tsconfig": setNoTsconfig,
|
|
336
|
+
"--strict": setStrict,
|
|
337
|
+
"--strict-docs": setStrictDocs,
|
|
338
|
+
"--strict-ownership": setStrictOwnership,
|
|
339
|
+
"--json": setJson,
|
|
340
|
+
"--check": setCheck,
|
|
341
|
+
"--help": setHelp,
|
|
342
|
+
"-h": setHelp
|
|
343
|
+
};
|
|
344
|
+
function parseArgs(argv) {
|
|
345
|
+
const args = {
|
|
346
|
+
include: [],
|
|
347
|
+
exclude: [],
|
|
348
|
+
packages: [],
|
|
349
|
+
strict: false,
|
|
350
|
+
strictDocs: false,
|
|
351
|
+
strictOwnership: false,
|
|
352
|
+
json: false,
|
|
353
|
+
check: false,
|
|
354
|
+
help: false
|
|
355
|
+
};
|
|
356
|
+
let passes = 0;
|
|
357
|
+
const maxPasses = argv.length * 2 + 4;
|
|
358
|
+
for (let i = 0; i < argv.length; i++) {
|
|
359
|
+
passes++;
|
|
360
|
+
if (passes > maxPasses) {
|
|
361
|
+
throw new Error(
|
|
362
|
+
// Stryker disable next-line StringLiteral
|
|
363
|
+
`parseArgs: exceeded ${String(maxPasses)} iterations parsing ${String(argv.length)} argument(s) -- this should never happen for any real argv and indicates an internal parsing bug.`
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
const arg = argv[i] ?? "";
|
|
367
|
+
const valueFlag = VALUE_FLAGS[arg];
|
|
368
|
+
if (valueFlag) {
|
|
369
|
+
valueFlag(args, nonEmpty(argv[++i], arg));
|
|
370
|
+
continue;
|
|
371
|
+
}
|
|
372
|
+
const boolFlag = BOOL_FLAGS[arg];
|
|
373
|
+
if (boolFlag) {
|
|
374
|
+
boolFlag(args);
|
|
375
|
+
continue;
|
|
376
|
+
}
|
|
377
|
+
throw new Error(`Unknown argument: ${arg}`);
|
|
378
|
+
}
|
|
379
|
+
return args;
|
|
380
|
+
}
|
|
381
|
+
function nonEmpty(value, flag) {
|
|
382
|
+
if (!value) throw new Error(`${flag} requires a value.`);
|
|
383
|
+
return value;
|
|
384
|
+
}
|
|
385
|
+
function helpText() {
|
|
386
|
+
return `env-cap - generate a manifest and/or a persisted evidence artifact from discovered env.schema.ts contracts
|
|
72
387
|
|
|
73
388
|
Usage:
|
|
74
389
|
env-cap init
|
|
75
|
-
env-cap [--location <path>] [--
|
|
390
|
+
env-cap [--location <path>] [--evidence <path>] [options]
|
|
76
391
|
|
|
77
392
|
init Scaffold a minimal starting point (one env.schema.ts + a generate script); run \`env-cap init --help\` for details
|
|
78
393
|
|
|
79
|
-
At least one of --location
|
|
394
|
+
At least one of --location or --evidence is required (for a non-init invocation).
|
|
80
395
|
|
|
81
396
|
Options:
|
|
82
397
|
--root <path> Directory to resolve globs from (default: cwd)
|
|
@@ -86,40 +401,267 @@ Options:
|
|
|
86
401
|
--package <name> Installed package name to also discover a schema from, via its "envCap.schema" package.json field (repeatable)
|
|
87
402
|
--tsconfig <path> Path to a tsconfig.json (relative to root) whose "paths"/"baseUrl" resolve aliased imports encountered during static analysis (default: auto-detected "tsconfig.json" at root)
|
|
88
403
|
--no-tsconfig Disable tsconfig path-alias resolution entirely
|
|
89
|
-
--docs <path> Also emit the rich Markdown docs artifact at this path
|
|
90
|
-
--env-example <path> Also emit a .env.example file at this path (only meaningful alongside --docs)
|
|
91
|
-
--env-example-on-existing <mode> What to do when --env-example's target already exists: keep-sibling (default, never overwrites -- writes a timestamped sibling instead), overwrite, or skip (write nothing). No effect with --check, which never writes anything regardless.
|
|
92
|
-
--ownership <path> Also emit the Dependency & Ownership Report at this path
|
|
93
404
|
--evidence <path> Also emit the persisted evidence artifact (the full EvidenceModel, plus a paired .fingerprint sidecar) at this path, e.g. docs/env.evidence.json (see ADR 0038). Independent of --location -- needs no other pass.
|
|
94
405
|
--strict Escalate every pass's warning findings to hard errors -- compatibility (manifest pass -- ADR 0009's provable exclusive-group/compatibility errors), documentation, and ownership alike (ADR 0044). Nothing is written when it fires. Info-severity findings are never escalated. Equivalent to passing all three scoped flags below at once.
|
|
95
406
|
--strict-docs Escalate every documentation-family warning (undocumented contract/variable, stale doc entry, expiring/expired entry, unresolvable documentEnv() link) to a hard error, independent of --strict. Nothing is written when it fires. Info-severity findings are never escalated.
|
|
96
407
|
--strict-ownership Escalate every ownership-family warning (abandoned contract, unresolved consumer, unconsumed owned variable, indeterminate ownership, stale/missing dynamicAccess citation) to a hard error, independent of --strict. Nothing is written when it fires. Info-severity findings are never escalated.
|
|
97
|
-
--expiring-within-days <n> Window (in days) for the "expiring soon" report (default: 30)
|
|
98
408
|
--json Emit a machine-readable JSON report instead of formatted text (see ADR 0013)
|
|
99
409
|
--check Verify generated artifacts are up to date without writing anything; exits 1 if any is stale or missing (see ADR 0016)
|
|
100
410
|
--help Show this message
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
411
|
+
|
|
412
|
+
Documentation (a rich Markdown catalog), a dependency & ownership report, and
|
|
413
|
+
a reconciled .env.example are no longer generated by this CLI -- they have no
|
|
414
|
+
runtime consumer, so generating them is application-level code now, not a CLI
|
|
415
|
+
concern. Call \`computeDocumentation\`/\`writeDocumentation\`/\`computeUsage\`/
|
|
416
|
+
\`writeUsageReport\` (or the higher-level \`generateDocumentation\`/
|
|
417
|
+
\`generateUsageReport\` orchestrators) directly from \`env-cap/build\` in your
|
|
418
|
+
own build script -- see \`examples/nextjs-app/scripts/generate-docs\` for a
|
|
419
|
+
worked example, and specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md
|
|
420
|
+
for why.
|
|
421
|
+
`;
|
|
422
|
+
}
|
|
423
|
+
function formatFieldChanges(changes) {
|
|
424
|
+
return changes.map((c) => `${c.field} (${c.previous ?? "unset"} -> ${c.current ?? "unset"})`).join(", ");
|
|
425
|
+
}
|
|
426
|
+
function contractNameResolver(contracts) {
|
|
427
|
+
const byIdentity = new Map(contracts.map((c) => [`${c.file}#${c.exportName}`, c.contractName]));
|
|
428
|
+
return (ref) => byIdentity.get(`${ref.file}#${ref.exportName}`) ?? ref.exportName;
|
|
429
|
+
}
|
|
430
|
+
function writeEvidenceChanges(changes, contracts) {
|
|
431
|
+
const nameOf = contractNameResolver(contracts);
|
|
432
|
+
const hasAdded = changes.addedContracts.length > 0 || changes.addedVariables.length > 0;
|
|
433
|
+
const hasUpdated = changes.updatedContracts.length > 0 || changes.updatedVariables.length > 0;
|
|
434
|
+
const hasRemoved = changes.removedContracts.length > 0 || changes.removedVariables.length > 0;
|
|
435
|
+
process.stdout.write("\nEvidence changes since the last persisted snapshot:\n");
|
|
436
|
+
if (!hasAdded && !hasUpdated && !hasRemoved) {
|
|
437
|
+
process.stdout.write(" No changes.\n");
|
|
438
|
+
return;
|
|
439
|
+
}
|
|
440
|
+
if (hasAdded) {
|
|
441
|
+
process.stdout.write(" Added:\n");
|
|
442
|
+
for (const c of changes.addedContracts)
|
|
443
|
+
process.stdout.write(` - contract "${nameOf(c)}" (${c.file})
|
|
444
|
+
`);
|
|
445
|
+
for (const v of changes.addedVariables)
|
|
446
|
+
process.stdout.write(` - ${v.key} in "${nameOf(v)}"
|
|
447
|
+
`);
|
|
448
|
+
}
|
|
449
|
+
if (hasUpdated) {
|
|
450
|
+
process.stdout.write(" Updated:\n");
|
|
451
|
+
for (const c of changes.updatedContracts)
|
|
452
|
+
process.stdout.write(` - contract "${nameOf(c)}": ${formatFieldChanges(c.changes)}
|
|
453
|
+
`);
|
|
454
|
+
for (const v of changes.updatedVariables)
|
|
455
|
+
process.stdout.write(` - ${v.key} in "${nameOf(v)}": ${formatFieldChanges(v.changes)}
|
|
456
|
+
`);
|
|
457
|
+
}
|
|
458
|
+
if (hasRemoved) {
|
|
459
|
+
process.stdout.write(" Removed:\n");
|
|
460
|
+
for (const c of changes.removedContracts)
|
|
461
|
+
process.stdout.write(` - contract "${nameOf(c)}" (${c.file})
|
|
462
|
+
`);
|
|
463
|
+
for (const v of changes.removedVariables)
|
|
464
|
+
process.stdout.write(` - ${v.key} in "${nameOf(v)}"
|
|
465
|
+
`);
|
|
466
|
+
}
|
|
467
|
+
}
|
|
468
|
+
function requestedPasses(args) {
|
|
469
|
+
return {
|
|
470
|
+
manifest: args.location !== void 0,
|
|
471
|
+
// The CLI can no longer request either pass -- `--docs`/`--ownership`
|
|
472
|
+
// were removed (see specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md);
|
|
473
|
+
// `JsonRequestedPasses` keeps both fields, unchanged in shape, for
|
|
474
|
+
// `--json` schema compatibility (see JSON_SCHEMA_VERSION's own doc
|
|
475
|
+
// comment -- an unused-but-still-`false` field is additive, not a
|
|
476
|
+
// meaning change), always reporting them as not requested.
|
|
477
|
+
docs: false,
|
|
478
|
+
usage: false,
|
|
479
|
+
evidence: args.evidence !== void 0
|
|
480
|
+
};
|
|
481
|
+
}
|
|
482
|
+
function groupEscalates(strict, specificFlag) {
|
|
483
|
+
return strict || specificFlag;
|
|
484
|
+
}
|
|
485
|
+
function artifactOptions(args) {
|
|
486
|
+
const listOrUndefined = (list) => list.length > 0 ? list : void 0;
|
|
487
|
+
return {
|
|
488
|
+
// The deliberate injection boundary: the CLI (an executable consumer)
|
|
489
|
+
// hands `env-cap/build` (a library surface) its filesystem capability.
|
|
490
|
+
// See src/cli/filesystem.ts and ADR 0040.
|
|
491
|
+
fs: nodeBuildFileSystem,
|
|
492
|
+
root: args.root,
|
|
493
|
+
include: listOrUndefined(args.include),
|
|
494
|
+
exclude: listOrUndefined(args.exclude),
|
|
495
|
+
packages: listOrUndefined(args.packages),
|
|
496
|
+
tsconfig: args.tsconfig,
|
|
497
|
+
manifest: args.location ? {
|
|
498
|
+
location: args.location,
|
|
499
|
+
onIncompatibility: args.strict ? "throw" : "warn"
|
|
500
|
+
} : false,
|
|
501
|
+
// `docs`/`usage` are deliberately omitted (not set to `false`): the CLI
|
|
502
|
+
// no longer has `--docs`/`--ownership` flags to derive them from, and
|
|
503
|
+
// omitting an optional `GenerateEnvArtifactsOptions` field is already
|
|
504
|
+
// equivalent to passing `false` (`computeArtifacts()`'s `options.docs
|
|
505
|
+
// === false ? undefined : options.docs` treats a missing key and an
|
|
506
|
+
// explicit `false` identically). `computeDocumentation`/`computeUsage`
|
|
507
|
+
// themselves still run unconditionally inside `generateEnvArtifacts()`
|
|
508
|
+
// -- Finding Model needs both regardless (ADR 0038) -- only the CLI's
|
|
509
|
+
// ability to ALSO write a docs/ownership artifact is gone. See
|
|
510
|
+
// specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md.
|
|
511
|
+
evidence: args.evidence ? { location: args.evidence } : false,
|
|
512
|
+
onUndocumented: groupEscalates(args.strict, args.strictDocs) ? "throw" : "warn",
|
|
513
|
+
onOwnershipIssue: groupEscalates(args.strict, args.strictOwnership) ? "throw" : "warn"
|
|
514
|
+
};
|
|
515
|
+
}
|
|
516
|
+
function printList(items, header, render) {
|
|
517
|
+
if (items.length === 0) return;
|
|
518
|
+
process.stdout.write(`
|
|
108
519
|
${header}
|
|
109
|
-
`);
|
|
110
|
-
|
|
111
|
-
`)
|
|
520
|
+
`);
|
|
521
|
+
for (const item of items) process.stdout.write(` - ${render(item)}
|
|
522
|
+
`);
|
|
523
|
+
}
|
|
524
|
+
async function runCheckMode(args) {
|
|
525
|
+
let checkResult;
|
|
526
|
+
try {
|
|
527
|
+
const { checkEnvArtifacts } = await import("../build-BBD3FEXB.js");
|
|
528
|
+
checkResult = await checkEnvArtifacts(artifactOptions(args));
|
|
529
|
+
} catch (error) {
|
|
530
|
+
if (!args.json) throw error;
|
|
531
|
+
writeJson(serializeFailure(error));
|
|
532
|
+
process.exitCode = 1;
|
|
533
|
+
return;
|
|
534
|
+
}
|
|
535
|
+
const stale = checkResult.findings.filter((f) => f.status !== "ok").map((f) => f.artifact);
|
|
536
|
+
if (args.json) {
|
|
537
|
+
writeJson(
|
|
538
|
+
serializeSuccess(
|
|
539
|
+
{ manifest: void 0, docs: void 0, usage: void 0 },
|
|
540
|
+
{ ok: checkResult.ok, stale },
|
|
541
|
+
false,
|
|
542
|
+
// `--check` writes nothing, so every result above is undefined by
|
|
543
|
+
// construction -- `requested` is the only thing distinguishing "this run
|
|
544
|
+
// checked the docs artifact" from "it didn't."
|
|
545
|
+
requestedPasses(args)
|
|
546
|
+
)
|
|
547
|
+
);
|
|
548
|
+
} else {
|
|
549
|
+
process.stdout.write("Checking for drift (--check: nothing will be written)...\n\n");
|
|
550
|
+
for (const f of checkResult.findings) {
|
|
551
|
+
process.stdout.write(
|
|
552
|
+
` ${f.artifact.padEnd(10)} ${f.path.padEnd(50)} ${f.status.toUpperCase()}${f.detail ? ` (${f.detail})` : ""}
|
|
553
|
+
`
|
|
554
|
+
);
|
|
555
|
+
}
|
|
556
|
+
process.stdout.write(
|
|
557
|
+
checkResult.ok ? "\nAll generated artifacts are up to date.\n" : `
|
|
112
558
|
${stale.length} artifact(s) are stale or missing. Run without --check to regenerate.
|
|
113
|
-
`
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
`)
|
|
121
|
-
|
|
122
|
-
`)
|
|
123
|
-
|
|
124
|
-
|
|
559
|
+
`
|
|
560
|
+
);
|
|
561
|
+
}
|
|
562
|
+
process.exitCode = checkResult.ok ? 0 : 1;
|
|
563
|
+
}
|
|
564
|
+
function printManifestSummary(manifest) {
|
|
565
|
+
process.stdout.write(`Wrote manifest: ${manifest.outputPath}
|
|
566
|
+
`);
|
|
567
|
+
process.stdout.write(`Discovered ${String(manifest.contracts.length)} contract(s).
|
|
568
|
+
`);
|
|
569
|
+
printList(
|
|
570
|
+
manifest.warnings,
|
|
571
|
+
`${String(manifest.warnings.length)} compatibility warning(s):`,
|
|
572
|
+
(w) => `${w.code ? `[${w.code}] ` : ""}${w.variable}: ${w.reason}`
|
|
573
|
+
);
|
|
574
|
+
printList(
|
|
575
|
+
manifest.parseWarnings,
|
|
576
|
+
`${String(manifest.parseWarnings.length)} parse warning(s):`,
|
|
577
|
+
(w) => `${w.file}: ${w.message}`
|
|
578
|
+
);
|
|
579
|
+
}
|
|
580
|
+
async function runGenerateMode(args) {
|
|
581
|
+
let result;
|
|
582
|
+
try {
|
|
583
|
+
const { generateEnvArtifacts } = await import("../build-BBD3FEXB.js");
|
|
584
|
+
result = await generateEnvArtifacts(artifactOptions(args));
|
|
585
|
+
} catch (error) {
|
|
586
|
+
if (!args.json) throw error;
|
|
587
|
+
writeJson(serializeFailure(error));
|
|
588
|
+
process.exitCode = 1;
|
|
589
|
+
return;
|
|
590
|
+
}
|
|
591
|
+
if (args.json) {
|
|
592
|
+
writeJson(
|
|
593
|
+
serializeSuccess(result, void 0, args.evidence !== void 0, requestedPasses(args))
|
|
594
|
+
);
|
|
595
|
+
return;
|
|
596
|
+
}
|
|
597
|
+
const totalWarnings = result.manifest?.parseWarnings.length ?? 0;
|
|
598
|
+
if (totalWarnings > 0) {
|
|
599
|
+
process.stdout.write(
|
|
600
|
+
`\u26A0 ${totalWarnings} unresolved/dropped-schema warning(s) found -- details below. Re-run with --json for a machine-readable report.
|
|
601
|
+
|
|
602
|
+
`
|
|
603
|
+
);
|
|
604
|
+
}
|
|
605
|
+
if (result.manifest) printManifestSummary(result.manifest);
|
|
606
|
+
if (args.evidence) {
|
|
607
|
+
process.stdout.write(`Wrote evidence: ${args.evidence}
|
|
608
|
+
`);
|
|
609
|
+
writeEvidenceChanges(result.evidence.change.manifest, result.evidence.contract.contracts);
|
|
610
|
+
}
|
|
611
|
+
}
|
|
612
|
+
async function main() {
|
|
613
|
+
const argv = process.argv.slice(2);
|
|
614
|
+
if (argv[0] === "init") {
|
|
615
|
+
process.exitCode = runInitCommand(argv.slice(1));
|
|
616
|
+
return;
|
|
617
|
+
}
|
|
618
|
+
const args = parseArgs(argv);
|
|
619
|
+
if (args.help) {
|
|
620
|
+
process.stdout.write(helpText());
|
|
621
|
+
process.exitCode = 0;
|
|
622
|
+
return;
|
|
623
|
+
}
|
|
624
|
+
if (!args.location && !args.evidence) {
|
|
625
|
+
if (args.json) {
|
|
626
|
+
writeJson(
|
|
627
|
+
serializeFailure(new Error("At least one of --location or --evidence is required."))
|
|
628
|
+
);
|
|
629
|
+
} else {
|
|
630
|
+
process.stdout.write(helpText());
|
|
631
|
+
}
|
|
632
|
+
process.exitCode = 1;
|
|
633
|
+
return;
|
|
634
|
+
}
|
|
635
|
+
await (args.check ? runCheckMode(args) : runGenerateMode(args));
|
|
636
|
+
}
|
|
637
|
+
function directRunUrl() {
|
|
638
|
+
const entry = process.argv[1];
|
|
639
|
+
if (!entry) return void 0;
|
|
640
|
+
try {
|
|
641
|
+
return pathToFileURL(realpathSync(entry)).href;
|
|
642
|
+
} catch {
|
|
643
|
+
return pathToFileURL(entry).href;
|
|
644
|
+
}
|
|
645
|
+
}
|
|
646
|
+
var isDirectRun = import.meta.url === directRunUrl();
|
|
647
|
+
if (isDirectRun) {
|
|
648
|
+
main().catch((error) => {
|
|
649
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
650
|
+
process.stderr.write(`${message}
|
|
651
|
+
`);
|
|
652
|
+
process.exitCode = 1;
|
|
653
|
+
});
|
|
654
|
+
}
|
|
655
|
+
export {
|
|
656
|
+
artifactOptions,
|
|
657
|
+
contractNameResolver,
|
|
658
|
+
directRunUrl,
|
|
659
|
+
formatFieldChanges,
|
|
660
|
+
main,
|
|
661
|
+
parseArgs,
|
|
662
|
+
printList,
|
|
663
|
+
printManifestSummary,
|
|
664
|
+
requestedPasses,
|
|
665
|
+
writeEvidenceChanges
|
|
666
|
+
};
|
|
125
667
|
//# sourceMappingURL=index.js.map
|