@hublo/sentinel 1.5.1-alpha.2 → 1.6.0-alpha.1

package/README.md

@@ -141,7 +141,7 @@ The per-tool knowledge (eslint → `eslint.config.js`, tsc → `tsconfig`, …)
 
 **Registry: public npm**, under `@hublo`. We started on **GitHub Packages (private)** and moved off it: it authenticates every consumer, including a one-off run, which is incompatible with the zero-setup adoption above. Public npm needs no consumer auth, so a module adopts sentinel without any `.npmrc` or token. Releases go out through the repo's `publish` workflow, never from a laptop; a prerelease is published under its prerelease dist-tag (`alpha`) and a stable one under `latest`.
 
-**Node.** sentinel needs **Node >= 24.15**, which is the version the monorepo it serves pins in its own `.node-version`. The floor follows the consumer deliberately: a lower one means testing a runtime nobody runs, and it twice let an API through that the types allowed and the runtime did not. It fails fast with a clear message on an older runtime rather than crashing. If a project runs on an older Node (e.g. a legacy app on Node 10), run sentinel with a modern Node via `fnm`/`nvm`; you do not need to change the project's own Node.
+**Node.** sentinel needs **Node >= 24.15**, which is the version the monorepo it serves pins in its own `.node-version`. The floor follows the consumer deliberately: a lower one means testing a runtime nobody runs, and it twice let an API through that the types allowed and the runtime did not. It fails fast with a clear message on an older runtime rather than crashing. That message comes from sentinel itself, so `npx` must run on Node >= 24.15 too: the npm 10 that Node 20 and 22 bundle fails while installing sentinel (`Cannot read properties of null (reading 'edgesOut')`), before sentinel's own check can run. If a project runs on an older Node (e.g. a legacy app on Node 10), run sentinel with a modern Node via `fnm`/`nvm`; you do not need to change the project's own Node.
 
 **Try it without installing.** A one-off run needs no auth and touches nothing:
 
@@ -176,6 +176,7 @@ throwaway run wants. Once a module has adopted, nothing is fetched any more: the
 - [`docs/typescript-adoption.md`](docs/typescript-adoption.md) — the adoption cheat sheet: the two adoption steps, the command model (verb x type x location), options, reading a report, and troubleshooting.
 - [`docs/test-adoption.md`](docs/test-adoption.md) — migrating a module from jest to Vitest: the two steps, what the migration rewrites and what it refuses BY NAME, how the baseline gate proves nothing was lost, and the failures worth recognising.
 - [`docs/static-analysis-adoption.md`](docs/static-analysis-adoption.md) — running the static analysis role on a module: the two steps, the four output shapes, how to read each row and where its threshold comes from, declaring an entry point, and the two limits worth knowing before trusting a number.
+- [`docs/env-adoption.md`](docs/env-adoption.md) — checking a whole repository's env files, contracts and Dockerfiles from its root: the ten rules and which block, the three levels of `SENTINEL_ENV_LEVEL`, the optional `env.config.mjs`, and what changed from the monorepo's `tools/repo-env`.
 - [`docs/typescript-traces.md`](docs/typescript-traces.md) — a **generated, versioned** reference of live command + output traces (every verb, option, config result and edge case) against the mock monorepo. Regenerate after CLI changes with `pnpm docs:traces`.
 
 ## Architecture: `target → runner → preset`
@@ -184,7 +185,7 @@ Every check is described by three layers:
 
 | Layer                | Flag                        | What it is                                         | Examples                                                                                                                                                     |
 | -------------------- | --------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                        | `lint` `format` `typescript` `build` `dev` `test` `static-analysis` `runtime-analysis`                                                                       |
+| **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                        | `lint` `format` `typescript` `build` `dev` `test` `static-analysis` `env` `runtime-analysis`                                                                 |
 | **runner** (adapter) | `--runner=<tool>`           | the _tool_ behind the target, swappable            | lint: `eslint`/`biome`/`oxlint` · types: `tsc`/`tsgo` · build: `vite` · test: `vitest`                                                                       |
 | **shape** (output)   | `--output=<shape>`          | what a reporting role WRITES, not what it measures | `console` (default, writes nothing) `html` `json` `markdown`; roles that do not report ignore it                                                             |
 | **preset** (preset)  | detected / `--preset`       | the _variant_ per stack (strict by default)        | `react` `nest` `node` `svelte` (svelte: lint + format; no tsconfig preset yet, so the TypeScript role stands aside on those modules and the other two adopt) |
@@ -402,8 +403,10 @@ VERBS      --run       execute the target's tool (--json for metrics + diagnosti
            --status    deprecated → --inspect
 
 TYPES      --lint  --format  --typescript  --build  --dev  --test
-           --static-analysis  --runtime-analysis  --arch
+           --static-analysis  --env  --runtime-analysis  --arch
            (omit a type → every type that TERMINATES; --dev never sweeps)
+           --env checks the whole REPOSITORY from its git root, --run only;
+           a sweep includes it once, and only from that root
            --dev answers --run and --init only: a server is started, not read,
            so --inspect/--report/--status refuse it and point at --build
 
@@ -541,8 +544,9 @@ This scaffold is the foundation; each tool is added one at a time on top of it:
 4. **Build** (`--build`) — `vite`.
 5. **Test** (`--test`) — `vitest`, migration from jest proven module by module against a name-level baseline. **✅ shipped in `1.4.0-alpha.x`**; a11y / w3c setups still to come.
 6. **Static analysis** (`--static-analysis`) — cycles, complexity, duplication, centrality.
-7. **Runtime analysis** (`--runtime-analysis`) — bundle, Lighthouse, web vitals.
-8. **Unified CI workflow + `--report --all` dashboard.**
+7. **Env conformance** (`--env`) — the monorepo's `tools/repo-env`, ported to run on any repository from its root.
+8. **Runtime analysis** (`--runtime-analysis`) — bundle, Lighthouse, web vitals.
+9. **Unified CI workflow + `--report --all` dashboard.**
 
 ## Open decisions & risks being validated
 

package/dist/bin/sentinel.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  ENV_SHAPES,
   PresetUnsupportedError,
   availableTargets,
   buildConfigFile,
@@ -11,7 +12,7 @@ import {
   presetNotInstalledYet,
   registerAdapters,
   resolve
-} from "../chunk-JHLNNIZC.js";
+} from "../chunk-5267A6X3.js";
 import {
   resolveContext
 } from "../chunk-P7NYSMLS.js";
@@ -23,13 +24,17 @@ import {
   readProjectPackageJson
 } from "../chunk-JRZI5IIN.js";
 import {
+  DEFAULT_ENV_LEVEL,
+  ENV_LEVELS,
   LONG_RUNNING_TARGETS,
   OUTPUT_SHAPES,
   PRESET_NAMES,
+  REPOSITORY_TARGETS,
   SWEEPABLE_TARGETS,
   TARGETS,
   VERBS
-} from "../chunk-WBDBRGLV.js";
+} from "../chunk-7E6YTTAK.js";
+import "../chunk-4EIY7TTR.js";
 import "../chunk-O7REVMOC.js";
 import "../chunk-QXFCZON7.js";
 
@@ -37,6 +42,7 @@ import "../chunk-QXFCZON7.js";
 import { program } from "commander";
 
 // src/core/orchestrate.ts
+import { basename } from "node:path";
 async function analyse(params) {
   const results = [];
   let worstCode = 0;
@@ -177,6 +183,57 @@ async function analyse(params) {
   }
   return { results, worstCode };
 }
+function definedOnly(source, keys) {
+  return Object.fromEntries(
+    keys.flatMap((key) => source[key] === void 0 ? [] : [[key, source[key]]])
+  );
+}
+async function analyseRepository(params) {
+  const results = [];
+  let worstCode = 0;
+  const project = basename(params.root);
+  for (const target of params.targets) {
+    const ctx = {
+      module: project,
+      cwd: params.root,
+      preset: "node",
+      ci: params.ci,
+      fix: false,
+      output: params.output,
+      envLevel: params.envLevel,
+      githubActions: params.githubActions
+    };
+    try {
+      const adapter = resolve(target, void 0, params.runner);
+      const result = params.verb === "run" ? await adapter.run(ctx) : await adapter.report(ctx);
+      const metrics = result.metrics ?? {};
+      results.push({
+        project,
+        target,
+        flavour: "repository",
+        ok: result.ok,
+        status: result.ok ? "ok" : "failed",
+        // A run row carries the verdict's two inputs and nothing more: the report itself was just
+        // printed above it, and repeating it inline would print it twice. A run that could not
+        // start has no blocking count, and carries its `error` instead: a key is left out when it
+        // has no value, never printed as `undefined`.
+        data: params.verb === "run" ? definedOnly(metrics, ["level", "blocking", "error"]) : metrics
+      });
+      worstCode = Math.max(worstCode, result.code);
+    } catch (error) {
+      results.push({
+        project,
+        target,
+        flavour: "repository",
+        ok: false,
+        status: "failed",
+        data: { error: error instanceof Error ? error.message : String(error) }
+      });
+      worstCode = Math.max(worstCode, 1);
+    }
+  }
+  return { results, worstCode };
+}
 function generateSummary(result) {
   const { project, target, flavour, ok, status, data } = result;
   const details = data && typeof data === "object" ? data : { value: data };
@@ -221,7 +278,7 @@ import {
   writeFileSync
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, relative, sep } from "node:path";
+import { basename as basename2, dirname, join, relative, sep } from "node:path";
 var NOT_COPIED = /* @__PURE__ */ new Set(["node_modules", ".git"]);
 function contents(root) {
   const found = /* @__PURE__ */ new Map();
@@ -242,7 +299,7 @@ function contents(root) {
 }
 function stage(moduleDir, scratch) {
   const root = findWorkspaceRoot(moduleDir);
-  const segments = root === void 0 ? [basename(moduleDir)] : relative(root, moduleDir).split(sep).filter((segment) => segment !== "");
+  const segments = root === void 0 ? [basename2(moduleDir)] : relative(root, moduleDir).split(sep).filter((segment) => segment !== "");
   let real = root ?? dirname(moduleDir);
   let shadow = scratch;
   for (const segment of segments) {
@@ -257,7 +314,7 @@ function stage(moduleDir, scratch) {
   rmSync(shadow, { recursive: true, force: true });
   cpSync(moduleDir, shadow, {
     recursive: true,
-    filter: (source) => source === moduleDir || !NOT_COPIED.has(basename(source)) && !lstatSync(source).isSymbolicLink()
+    filter: (source) => source === moduleDir || !NOT_COPIED.has(basename2(source)) && !lstatSync(source).isSymbolicLink()
   });
   if (existsSync(join(moduleDir, "node_modules"))) {
     symlinkSync(join(moduleDir, "node_modules"), join(shadow, "node_modules"), "dir");
@@ -294,7 +351,7 @@ async function rehearseAfterInit(moduleDir, roles) {
       const before = contents(copy);
       const failure = await role.adapter.rehearseAfterInit?.(
         {
-          module: basename(moduleDir),
+          module: basename2(moduleDir),
           cwd: copy,
           preset: role.preset,
           ci: false,
@@ -541,6 +598,9 @@ async function runValidate(ctx) {
   return outcomes.every((outcome) => outcome.ok) ? 0 : 1;
 }
 
+// src/cli/run-verb.ts
+import { basename as basename3 } from "node:path";
+
 // src/core/render.ts
 var HEAD_KEYS = /* @__PURE__ */ new Set([
   "project",
@@ -660,7 +720,9 @@ function workspacePrep(cwd2) {
   return root ? inspectWorkspacePrep(root) : [];
 }
 async function runVerb(ctx) {
-  const { modules, scope } = resolveContext(ctx.cwd, { module: ctx.module, ci: ctx.ci });
+  const repositoryTargets = ctx.targets.filter((target) => REPOSITORY_TARGETS.includes(target));
+  const moduleTargets = ctx.targets.filter((target) => !REPOSITORY_TARGETS.includes(target));
+  const { modules, scope } = moduleTargets.length > 0 ? resolveContext(ctx.cwd, { module: ctx.module, ci: ctx.ci }) : { modules: [] };
   const out = palette(process.stdout);
   const err = palette(process.stderr);
   const longRunning = ctx.targets.filter((target) => LONG_RUNNING_TARGETS.includes(target));
@@ -701,9 +763,9 @@ async function runVerb(ctx) {
     );
   }
   const started = Date.now();
-  const { results, worstCode } = await analyse({
+  const moduleRun = await analyse({
     verb: shaped,
-    targets: ctx.targets,
+    targets: moduleTargets,
     modules,
     runner: ctx.runner,
     preset: ctx.preset,
@@ -721,6 +783,18 @@ async function runVerb(ctx) {
     onProgress: process.stderr.isTTY ? (done, total, name) => process.stderr.write(err.dim(`  [${done}/${total}] ${name}
 `)) : void 0
   });
+  const repositoryRun = repositoryTargets.length > 0 && ctx.repositoryRoot !== void 0 ? await analyseRepository({
+    verb: shaped === "report" ? "report" : "run",
+    targets: repositoryTargets,
+    root: ctx.repositoryRoot,
+    runner: ctx.runner,
+    ci: ctx.ci,
+    output: ctx.output,
+    envLevel: ctx.envLevel,
+    githubActions: ctx.githubActions
+  }) : { results: [], worstCode: 0 };
+  const results = [...moduleRun.results, ...repositoryRun.results];
+  const worstCode = Math.max(moduleRun.worstCode, repositoryRun.worstCode);
   const summary = generateSummaries(results, ctx.targets);
   if (ctx.json) {
     const base = ctx.verb === "status" || ctx.verb === "inspect" ? {
@@ -756,8 +830,11 @@ async function runVerb(ctx) {
     }
   }
   process.stderr.write(
-    err.dim(`  ${modules.length} module(s) [${scope}] in ${Date.now() - started}ms
-`)
+    err.dim(
+      moduleTargets.length > 0 ? `  ${modules.length} module(s) [${scope}] in ${Date.now() - started}ms
+` : `  1 repository [${basename3(ctx.repositoryRoot ?? ctx.cwd)}] in ${Date.now() - started}ms
+`
+    )
   );
   if (ctx.targetsExplicit && summary.skipped.length > 0) {
     const avail = availableTargets();
@@ -771,6 +848,35 @@ async function runVerb(ctx) {
   return ctx.verb === "run" || ctx.ci ? worstCode : 0;
 }
 
+// src/core/repository-root.ts
+import { execFileSync } from "node:child_process";
+import { realpathSync as realpathSync2 } from "node:fs";
+function findRepositoryRoot(cwd2) {
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: cwd2,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return root === "" ? void 0 : realpathSync2(root);
+  } catch {
+    return void 0;
+  }
+}
+function isRepositoryRoot(cwd2, root) {
+  try {
+    return realpathSync2(cwd2) === root;
+  } catch {
+    return false;
+  }
+}
+function locateRepository(cwd2) {
+  const root = findRepositoryRoot(cwd2);
+  if (root === void 0) return { ok: false, reason: "not-a-repository" };
+  if (!isRepositoryRoot(cwd2, root)) return { ok: false, reason: "not-the-root", root };
+  return { ok: true, root };
+}
+
 // src/shared/node-version.ts
 var MIN_NODE = "24.15.0";
 function parts(version) {
@@ -807,6 +913,7 @@ var TARGET_HELP = {
   dev: "dev server (long-running: never swept by an unqualified --run)",
   test: "tests",
   "static-analysis": "duplication, dead code, complexity, import graph, file size, bundle weight",
+  env: "env files, contracts and Dockerfiles, for the whole repository (run from its root)",
   "runtime-analysis": "Lighthouse, web vitals",
   arch: "architecture boundaries"
 };
@@ -929,7 +1036,64 @@ if (opts.all && namedTargets.length > 0) {
     `--all runs every target; drop the specific one(s): ${namedTargets.map((t) => `--${t}`).join(", ")}.`
   );
 }
-var targets = opts.all || namedTargets.length === 0 ? [...SWEEPABLE_TARGETS] : namedTargets;
+var RUNNING_VERBS = ["run", "report"];
+var runsRepository = RUNNING_VERBS.includes(verb);
+var sweeping = Boolean(opts.all) || namedTargets.length === 0;
+var sweptRoot = sweeping && runsRepository ? locateRepository(cwd) : void 0;
+var repositoryRoot = sweptRoot?.ok ? sweptRoot.root : void 0;
+var targets = sweeping ? SWEEPABLE_TARGETS.filter(
+  (target) => !REPOSITORY_TARGETS.includes(target) || repositoryRoot !== void 0
+) : namedTargets;
+var namedRepository = namedTargets.filter((target) => REPOSITORY_TARGETS.includes(target));
+if (namedRepository.length > 0) {
+  const flags = namedRepository.map((target) => `--${target}`).join(", ");
+  if (!runsRepository) {
+    program.error(
+      `sentinel: ${flags} reads the repository and writes no config, so it only runs: \`sentinel --run ${flags}\`. It has no --${verb}.`
+    );
+  }
+  if (opts.module !== void 0) {
+    program.error(
+      `sentinel: ${flags} checks the whole repository, so --module does not apply to it. Drop --module, or run ${flags} on its own.`
+    );
+  }
+  if (opts.fix) {
+    program.error(`sentinel: ${flags} reports and fixes nothing; drop --fix.`);
+  }
+  if (toolArgs.length > 0) {
+    program.error(
+      `sentinel: ${flags} runs no external tool, so options after \`--\` have nowhere to go.`
+    );
+  }
+  const location = locateRepository(cwd);
+  if (!location.ok) {
+    program.error(
+      location.reason === "not-a-repository" ? `sentinel: ${flags} reads the repository through git, and ${cwd} is not inside a git repository (or git cannot run here).` : `sentinel: ${flags} checks the whole repository, so it runs from its root rather than from a directory inside it. Run it from ${location.root ?? "the git top-level"}.`
+    );
+  }
+  repositoryRoot = location.root;
+  const asked = typeof opts.output === "string" ? opts.output.split(",").map((one) => one.trim()) : [];
+  const unwritten = asked.filter(
+    (one) => one !== "" && !ENV_SHAPES.includes(one)
+  );
+  if (targets.every((target) => REPOSITORY_TARGETS.includes(target)) && unwritten.length > 0) {
+    program.error(
+      `sentinel: ${flags} writes ${ENV_SHAPES.join(", ")}; not ${unwritten.join(", ")}.`
+    );
+  }
+}
+function parseEnvLevel(value) {
+  const asked = (value ?? "").trim().toLowerCase();
+  if (asked === "") return DEFAULT_ENV_LEVEL;
+  if (!ENV_LEVELS.includes(asked)) {
+    return program.error(
+      `sentinel: unknown SENTINEL_ENV_LEVEL ${JSON.stringify(value)}. Supported: ${ENV_LEVELS.join(", ")} (${DEFAULT_ENV_LEVEL} when unset).`
+    );
+  }
+  return asked;
+}
+var envLevel = targets.some((target) => REPOSITORY_TARGETS.includes(target)) ? parseEnvLevel(process.env.SENTINEL_ENV_LEVEL) : DEFAULT_ENV_LEVEL;
+var githubActions = process.env.GITHUB_ACTIONS === "true";
 var targetsExplicit = !(opts.all || namedTargets.length === 0);
 if (namedTargets.includes("static-analysis") && (verb === "report" || verb === "run" && opts.json)) {
   program.error(
@@ -991,6 +1155,9 @@ async function main() {
     output: parseOutput(opts.output, Boolean(opts.json)) ?? (opts.json ? "json" : void 0),
     dryRun: Boolean(opts.dryRun),
     rehearse: Boolean(opts.rehearse),
+    repositoryRoot,
+    envLevel,
+    githubActions,
     fail: (message) => program.error(message)
   };
   const exitCode = verb === "init" ? await runInit(context) : verb === "validate" ? await runValidate(context) : await runVerb(context);

package/dist/chunk-4EIY7TTR.js

@@ -0,0 +1,89 @@
+// src/roles/env/configs/define.ts
+var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "externallyProvided",
+  "knownExternalVars",
+  "knownExternalPatterns",
+  "allowNonBlankedSecrets",
+  "allowedCommittedEnvFiles",
+  "envFiles",
+  "contracts",
+  "scan",
+  "references",
+  "readers",
+  "docker"
+]);
+var SCOPE_KEYS = /* @__PURE__ */ new Set(["roots", "ext", "excludeSuffixes", "excludeDirs"]);
+var NESTED_KEYS = {
+  scan: SCOPE_KEYS,
+  references: SCOPE_KEYS,
+  readers: /* @__PURE__ */ new Set(["required", "optional"]),
+  docker: /* @__PURE__ */ new Set(["allowRoot", "excludePaths"])
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function kindOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (value instanceof RegExp) return "a RegExp";
+  if (value === "") return "an empty string";
+  const type = typeof value;
+  return type === "object" ? "an object" : `a ${type}`;
+}
+function badEntry(path, list, valid) {
+  const index = list.findIndex((entry) => !valid(entry));
+  return index === -1 ? void 0 : `${path}[${index}] is ${kindOf(list[index])}`;
+}
+function stringListProblems(path, value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) return [`${path} must be an array of strings, got ${kindOf(value)}`];
+  const bad = badEntry(path, value, (entry) => typeof entry === "string" && entry !== "");
+  return bad ? [`${path} must hold non-empty strings only: ${bad}`] : [];
+}
+function problemsOf(input) {
+  const problems = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (!TOP_LEVEL_KEYS.has(key)) {
+      problems.push(`unknown key "${key}"`);
+      continue;
+    }
+    const nested = NESTED_KEYS[key];
+    if (nested === void 0) {
+      if (key === "knownExternalPatterns") {
+        const bad = Array.isArray(value) ? badEntry(key, value, (entry) => entry instanceof RegExp || typeof entry === "string") : void 0;
+        if (value !== void 0 && !Array.isArray(value)) {
+          problems.push(`${key} must be an array of RegExp or strings, got ${kindOf(value)}`);
+        } else if (bad) {
+          problems.push(`${key} must hold RegExp or strings only: ${bad}`);
+        }
+      } else {
+        problems.push(...stringListProblems(key, value));
+      }
+      continue;
+    }
+    if (value === void 0) continue;
+    if (!isRecord(value)) {
+      problems.push(`${key} must be an object, got ${kindOf(value)}`);
+      continue;
+    }
+    for (const [inner, innerValue] of Object.entries(value)) {
+      if (!nested.has(inner)) problems.push(`unknown key "${key}.${inner}"`);
+      else problems.push(...stringListProblems(`${key}.${inner}`, innerValue));
+    }
+  }
+  return problems;
+}
+function defineEnv(input = {}) {
+  if (!isRecord(input)) throw new Error(`env config must export an object, got ${kindOf(input)}`);
+  const problems = problemsOf(input);
+  if (problems.length > 0) {
+    throw new Error(`invalid env config:
+  - ${problems.join("\n  - ")}`);
+  }
+  return input;
+}
+
+export {
+  defineEnv
+};
+//# sourceMappingURL=chunk-4EIY7TTR.js.map

package/dist/chunk-4EIY7TTR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/roles/env/configs/define.ts"],"sourcesContent":["/**\n * `defineEnv`: what a repository writes to declare its own env facts, all of them optional.\n *\n * ```js\n * // env.config.mjs, at the repository root\n * import { defineEnv } from '@hublo/sentinel/env'\n *\n * export default defineEnv({\n *   externallyProvided: ['NODE_ENV'],\n *   allowNonBlankedSecrets: ['apps/front/x/.env.example:LEGACY_API_KEY'],\n * })\n * ```\n *\n * A repository that does not install sentinel, and runs it with `npx`, cannot import this module:\n * its own `node_modules` has no `@hublo/sentinel`. So the file may export the same object PLAIN,\n * and the role passes it through this function itself. Both spellings mean the same thing, and the\n * function exists for the one that can import it: it validates at the moment the file is written,\n * in an editor that knows the types.\n *\n * ## What a repository declares, and what stays sentinel's\n *\n * A repository declares FACTS about itself: which variables its CI injects, which committed value\n * was reviewed and is not a secret, which Dockerfile must run as root, where its code lives. It\n * does not redefine what a secret NAME looks like or how code reads env, which are the same in\n * every repository and ship in `presets/shared.json`.\n *\n * Two semantics, stated once:\n *\n *  - `readers`, `envFiles` and `contracts` ADD to what sentinel ships, so no repository loses\n *    `getOrFail` or `**\\/.env` by declaring a reader or a glob of its own;\n *  - `scan` and `references` REPLACE, key by key: a repository naming its `roots` says where its\n *    code is, and keeping `.` beside them would scan everything anyway.\n *\n * ⛔ An unknown key is refused, by name. The file is `.mjs`, so nothing type-checks it, and a key\n * spelled `allowNonBlankedSecret` would otherwise be ignored in silence while the finding it was\n * meant to downgrade kept failing the build.\n */\n\n/** A source scope a repository may narrow, every key optional. */\nexport interface EnvScopeInput {\n  roots?: string[]\n  ext?: string[]\n  excludeSuffixes?: string[]\n  excludeDirs?: string[]\n}\n\n/** What `env.config.mjs` exports. */\nexport interface EnvInput {\n  /** Required variables in no contract because CI injects them or a secret store provides them. */\n  externallyProvided?: string[]\n  /** Declared variables consumed outside scannable source, so never reported dead (rule 4). */\n  knownExternalVars?: string[]\n  /** The same, by pattern, for a whole category such as `/_DATABASE_URL$/`. */\n  knownExternalPatterns?: (RegExp | string)[]\n  /** `<file>:<VAR>` locations whose committed value was reviewed and is not a secret (rule 6). */\n  allowNonBlankedSecrets?: string[]\n  /** Committed real env files permitted anyway, such as a test fixture (rule 2). */\n  allowedCommittedEnvFiles?: string[]\n  /** Globs of env files to read, ADDED to `**\\/.env`, `**\\/.env.*` and `**\\/*.env`. */\n  envFiles?: string[]\n  /** Globs of contracts, ADDED to `**\\/*.env*.example`. */\n  contracts?: string[]\n  /** Where the named readers are looked for (rules 1 and 3). Replaces, key by key. */\n  scan?: EnvScopeInput\n  /** Where direct `process.env` reads are looked for (rules 3 and 4). Replaces, key by key. */\n  references?: EnvScopeInput\n  /** Reader names ADDED to sentinel's: `required` throw when absent, `optional` default. */\n  readers?: { required?: string[]; optional?: string[] }\n  /** Docker rules: Dockerfiles allowed to run as root, and path prefixes not checked at all. */\n  docker?: { allowRoot?: string[]; excludePaths?: string[] }\n}\n\nconst TOP_LEVEL_KEYS = new Set<string>([\n  'externallyProvided',\n  'knownExternalVars',\n  'knownExternalPatterns',\n  'allowNonBlankedSecrets',\n  'allowedCommittedEnvFiles',\n  'envFiles',\n  'contracts',\n  'scan',\n  'references',\n  'readers',\n  'docker',\n])\nconst SCOPE_KEYS = new Set(['roots', 'ext', 'excludeSuffixes', 'excludeDirs'])\nconst NESTED_KEYS: Readonly<Record<string, ReadonlySet<string>>> = {\n  scan: SCOPE_KEYS,\n  references: SCOPE_KEYS,\n  readers: new Set(['required', 'optional']),\n  docker: new Set(['allowRoot', 'excludePaths']),\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * What a value IS, in a word, for a message that says what was found instead of what was wanted.\n * Its kind, never its content: a config line can hold a secret's location, and a refusal has no\n * reason to repeat it.\n */\nfunction kindOf(value: unknown): string {\n  if (value === null) return 'null'\n  if (Array.isArray(value)) return 'an array'\n  if (value instanceof RegExp) return 'a RegExp'\n  if (value === '') return 'an empty string'\n  const type = typeof value\n  return type === 'object' ? 'an object' : `a ${type}`\n}\n\n/** The first entry of a list that fails `valid`, named by its index and its kind. */\nfunction badEntry(path: string, list: readonly unknown[], valid: (entry: unknown) => boolean) {\n  const index = list.findIndex((entry) => !valid(entry))\n  return index === -1 ? undefined : `${path}[${index}] is ${kindOf(list[index])}`\n}\n\n/** Every problem with one list: it must be an array of non-empty strings. */\nfunction stringListProblems(path: string, value: unknown): string[] {\n  if (value === undefined) return []\n  if (!Array.isArray(value)) return [`${path} must be an array of strings, got ${kindOf(value)}`]\n  const bad = badEntry(path, value, (entry) => typeof entry === 'string' && entry !== '')\n  return bad ? [`${path} must hold non-empty strings only: ${bad}`] : []\n}\n\n/** Every problem with the input, each naming the key, so one run lists them all. */\nfunction problemsOf(input: Record<string, unknown>): string[] {\n  const problems: string[] = []\n  for (const [key, value] of Object.entries(input)) {\n    if (!TOP_LEVEL_KEYS.has(key)) {\n      problems.push(`unknown key \"${key}\"`)\n      continue\n    }\n    const nested = NESTED_KEYS[key]\n    if (nested === undefined) {\n      if (key === 'knownExternalPatterns') {\n        const bad = Array.isArray(value)\n          ? badEntry(key, value, (entry) => entry instanceof RegExp || typeof entry === 'string')\n          : undefined\n        if (value !== undefined && !Array.isArray(value)) {\n          problems.push(`${key} must be an array of RegExp or strings, got ${kindOf(value)}`)\n        } else if (bad) {\n          problems.push(`${key} must hold RegExp or strings only: ${bad}`)\n        }\n      } else {\n        problems.push(...stringListProblems(key, value))\n      }\n      continue\n    }\n    if (value === undefined) continue\n    if (!isRecord(value)) {\n      problems.push(`${key} must be an object, got ${kindOf(value)}`)\n      continue\n    }\n    for (const [inner, innerValue] of Object.entries(value)) {\n      if (!nested.has(inner)) problems.push(`unknown key \"${key}.${inner}\"`)\n      else problems.push(...stringListProblems(`${key}.${inner}`, innerValue))\n    }\n  }\n  return problems\n}\n\n/**\n * Validate a repository's env declaration and return it unchanged.\n *\n * The defaults are NOT merged in here. They ship with sentinel and are applied when the role runs,\n * so changing one reaches every repository at its next sentinel version instead of leaving a copy\n * frozen in each config. That also makes this function idempotent, which is what lets the role\n * pass a plain exported object through it a second time.\n *\n * @param input the declaration; omitted, the repository declares nothing\n * @returns the same declaration\n * @throws naming every unknown key and every malformed value at once\n */\nexport function defineEnv(input: EnvInput = {}): EnvInput {\n  if (!isRecord(input)) throw new Error(`env config must export an object, got ${kindOf(input)}`)\n  const problems = problemsOf(input)\n  if (problems.length > 0) {\n    throw new Error(`invalid env config:\\n  - ${problems.join('\\n  - ')}`)\n  }\n  return input\n}\n"],"mappings":"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","names":[]}