@hublo/sentinel 1.6.0-alpha.0 → 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:
 

package/dist/bin/sentinel.js

@@ -12,7 +12,7 @@ import {
   presetNotInstalledYet,
   registerAdapters,
   resolve
-} from "../chunk-PC5R4DX5.js";
+} from "../chunk-5267A6X3.js";
 import {
   resolveContext
 } from "../chunk-P7NYSMLS.js";
@@ -34,7 +34,7 @@ import {
   TARGETS,
   VERBS
 } from "../chunk-7E6YTTAK.js";
-import "../chunk-NAFI7OLI.js";
+import "../chunk-4EIY7TTR.js";
 import "../chunk-O7REVMOC.js";
 import "../chunk-QXFCZON7.js";
 
@@ -183,6 +183,11 @@ 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;
@@ -209,8 +214,10 @@ async function analyseRepository(params) {
         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.
-        data: params.verb === "run" ? { level: metrics.level, blocking: metrics.blocking } : metrics
+        // 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) {

package/dist/{chunk-NAFI7OLI.js → chunk-4EIY7TTR.js}

@@ -22,10 +22,23 @@ var NESTED_KEYS = {
 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`];
-  return value.some((entry) => typeof entry !== "string" || entry === "") ? [`${path} must hold non-empty strings only`] : [];
+  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 = [];
@@ -37,10 +50,11 @@ function problemsOf(input) {
     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`);
-        } else if (Array.isArray(value) && value.some((entry) => !(entry instanceof RegExp) && typeof entry !== "string")) {
-          problems.push(`${key} must hold RegExp or strings only`);
+          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));
@@ -49,7 +63,7 @@ function problemsOf(input) {
     }
     if (value === void 0) continue;
     if (!isRecord(value)) {
-      problems.push(`${key} must be an object`);
+      problems.push(`${key} must be an object, got ${kindOf(value)}`);
       continue;
     }
     for (const [inner, innerValue] of Object.entries(value)) {
@@ -60,7 +74,7 @@ function problemsOf(input) {
   return problems;
 }
 function defineEnv(input = {}) {
-  if (!isRecord(input)) throw new Error("env config must export an object");
+  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:
@@ -72,4 +86,4 @@ function defineEnv(input = {}) {
 export {
   defineEnv
 };
-//# sourceMappingURL=chunk-NAFI7OLI.js.map
+//# 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":[]}

package/dist/{chunk-PC5R4DX5.js → chunk-5267A6X3.js}

@@ -84,7 +84,7 @@ import {
 } from "./chunk-7E6YTTAK.js";
 import {
   defineEnv
-} from "./chunk-NAFI7OLI.js";
+} from "./chunk-4EIY7TTR.js";
 import {
   globToRegExp
 } from "./chunk-O7REVMOC.js";
@@ -192,7 +192,15 @@ var shared_default = {
       ".spec.js",
       ".test.js",
       ".spec.jsx",
-      ".test.jsx"
+      ".test.jsx",
+      ".spec.mts",
+      ".test.mts",
+      ".spec.cts",
+      ".test.cts",
+      ".spec.mjs",
+      ".test.mjs",
+      ".spec.cjs",
+      ".test.cjs"
     ],
     excludeDirs: ["node_modules", "dist"]
   },
@@ -1400,16 +1408,25 @@ function deriveVars(files, readers) {
   return { required, optional };
 }
 var ENV_LINE = /^(?:export\s+)?([\w.-]+)\s*=(.*)$/;
-function isBlankValue(value) {
-  const trimmed = value.trim();
-  const quoted = /^(['"])(.*)\1$/.exec(trimmed);
-  return (quoted ? quoted[2] : trimmed) === "";
-}
-function openQuote(value) {
-  const trimmed = value.trim();
-  const quote = trimmed[0];
-  if (quote !== '"' && quote !== "'" && quote !== "`") return void 0;
-  return trimmed.length > 1 && trimmed.endsWith(quote) ? void 0 : quote;
+var QUOTES = /* @__PURE__ */ new Set(['"', "'", "`"]);
+function closingQuote(text, quote, from) {
+  for (let index = from; index < text.length; index += 1) {
+    if (text[index] === "\\" && text[index + 1] === quote) index += 1;
+    else if (text[index] === quote) return index;
+  }
+  return -1;
+}
+function readValue(raw) {
+  const value = raw.trimStart();
+  const quote = value[0];
+  if (quote !== void 0 && QUOTES.has(quote)) {
+    const end = closingQuote(value, quote, 1);
+    if (end === -1) return { blank: false, opens: quote };
+    const rest = value.slice(end + 1).trim();
+    return { blank: end === 1 && (rest === "" || rest.startsWith("#")) };
+  }
+  const comment = value.indexOf("#");
+  return { blank: (comment === -1 ? value : value.slice(0, comment)).trim() === "" };
 }
 function parseEnvFile(content) {
   const entries = [];
@@ -1418,15 +1435,15 @@ function parseEnvFile(content) {
   for (const [index, rawLine] of lines.entries()) {
     const line = rawLine.trim();
     if (closing !== void 0) {
-      if (line.endsWith(closing)) closing = void 0;
+      if (closingQuote(line, closing, 0) !== -1) closing = void 0;
       continue;
     }
     if (line === "" || line.startsWith("#")) continue;
     const match = ENV_LINE.exec(line);
     if (!match) continue;
-    const value = match[2] ?? "";
-    entries.push({ key: match[1] ?? "", line: index + 1, blank: isBlankValue(value) });
-    closing = openQuote(value);
+    const { blank, opens } = readValue(match[2] ?? "");
+    entries.push({ key: match[1] ?? "", line: index + 1, blank });
+    closing = opens;
   }
   return {
     entries,
@@ -2267,9 +2284,15 @@ function escapeData(text) {
 function escapeProperty(text) {
   return escapeData(text).replace(/:/g, "%3A").replace(/,/g, "%2C");
 }
+var GITHUB_ANNOTATION_CAP = 10;
+function summaryAnnotation(command, count, level) {
+  const what = command === "error" ? "blocking findings" : level === "error" ? "advisory findings" : "findings";
+  const message = `${count} ${what} (GitHub shows at most ${GITHUB_ANNOTATION_CAP} ${command} annotations per step): the full list is in the env report, in this step's log, and in env-report/env.md with --output markdown`;
+  return `::${command} title=${escapeProperty(`env: ${count} ${what}`)}::${escapeData(message)}`;
+}
 function renderAnnotations(report) {
   if (report.level === "info") return [];
-  return report.findings.filter((entry) => entry.severity !== "info").map((entry) => {
+  const annotations = report.findings.filter((entry) => entry.severity !== "info").map((entry) => {
     const command = report.level === "error" && entry.severity === "blocking" ? "error" : "warning";
     const properties = [
       entry.file === void 0 ? void 0 : `file=${escapeProperty(entry.file)}`,
@@ -2277,8 +2300,13 @@ function renderAnnotations(report) {
       `title=${escapeProperty(`env rule ${entry.number}: ${entry.rule}`)}`
     ].filter(Boolean);
     const message = `${entry.name}${entry.detail ? ` (${entry.detail})` : ""}: ${RULES[entry.rule].help}`;
-    return `::${command} ${properties.join(",")}::${escapeData(message)}`;
+    return { command, line: `::${command} ${properties.join(",")}::${escapeData(message)}` };
+  });
+  const summaries = ["error", "warning"].flatMap((command) => {
+    const count = annotations.filter((entry) => entry.command === command).length;
+    return count > GITHUB_ANNOTATION_CAP ? [summaryAnnotation(command, count, report.level)] : [];
   });
+  return [...summaries, ...annotations.map((entry) => entry.line)];
 }
 
 // src/roles/env/adapters/conformance/conformance.adapter.ts
@@ -2311,6 +2339,10 @@ function writeShapes(root, report, shapes) {
     return `${REPORT_DIR2}/${name}`;
   });
 }
+function oneLine(message) {
+  const [head = "", ...rest] = message.split("\n").map((line) => line.trim().replace(/^- /, "")).filter((line) => line !== "");
+  return rest.length === 0 ? head : `${head} ${rest.join("; ")}`;
+}
 var ConformanceAdapter = class extends BaseAdapter {
   target = TARGET2;
   runner = "conformance";
@@ -2345,17 +2377,17 @@ var ConformanceAdapter = class extends BaseAdapter {
         `writes ${ENV_SHAPES.join(", ")}; not ${unknown.join(", ")}, which another role may write.`
       );
     }
+    const refuse = (message) => {
+      this.say(message);
+      return { ok: false, code: 1, metrics: { level, error: oneLine(message) } };
+    };
     const { settings, from, unreadable } = await loadEnvConfig(ctx.cwd);
-    if (unreadable) {
-      this.say(unreadable);
-      return { ok: false, code: 1 };
-    }
+    if (unreadable) return refuse(unreadable);
     let report;
     try {
       report = collectEnvReport(openRepository(ctx.cwd), settings, level, from);
     } catch (error) {
-      this.say(error instanceof Error ? error.message : String(error));
-      return { ok: false, code: 1 };
+      return refuse(error instanceof Error ? error.message : String(error));
     }
     if (printing) {
       const written = writeShapes(ctx.cwd, report, known);

package/dist/index.js

@@ -6,13 +6,13 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-PC5R4DX5.js";
+} from "./chunk-5267A6X3.js";
 import {
   BaseAdapter
 } from "./chunk-P7NYSMLS.js";
 import "./chunk-JRZI5IIN.js";
 import "./chunk-7E6YTTAK.js";
-import "./chunk-NAFI7OLI.js";
+import "./chunk-4EIY7TTR.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";
 export {

package/dist/roles/env/config.js

@@ -1,6 +1,6 @@
 import {
   defineEnv
-} from "../../chunk-NAFI7OLI.js";
+} from "../../chunk-4EIY7TTR.js";
 export {
   defineEnv
 };

package/docs/env-adoption.md

@@ -127,12 +127,42 @@ A repository that runs sentinel with `npx` cannot import it, since its own `node
 tried. An unknown key is refused by name, in both spellings: the file is `.mjs`, and an ignored
 `allowNonBlankedSecret` would silently stop downgrading the finding it was written for.
 
+A refused config fails the run (exit 1, at every level) and says why twice: in full on stderr, one
+line per problem, and on the summary row, `level=warning error=env.config.mjs: invalid env config:
+unknown key "materialize"`, which is also the row's `error` in `--json`. A value of the wrong type is
+named with what was found, its kind and never its content: `scan.roots[1] is an empty string`.
+
+### Not the monorepo's `repo-env.config.mjs`
+
+`env.config.mjs` is sentinel's own schema, smaller than the monorepo's `tools/repo-env` config, and
+not a copy of it. Reusing the monorepo's file as-is in another repository is not correct either way:
+its allowlists, scan roots and readers describe the monorepo. A repository declares its own facts,
+with these keys and no others: `externallyProvided`, `knownExternalVars`, `knownExternalPatterns`,
+`allowNonBlankedSecrets`, `allowedCommittedEnvFiles`, `envFiles`, `contracts`, `scan` and
+`references` (each `roots`, `ext`, `excludeSuffixes`, `excludeDirs`), `readers` (`required`,
+`optional`) and `docker` (`allowRoot`, `excludePaths`).
+
+Four keys of `repo-env.config.mjs` are refused, on purpose:
+
+| `repo-env.config.mjs` key | in sentinel 1.6                                                                                                                                          |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `materialize`             | monorepo-only: it seeds that repository's test env files from its contracts, which is functional, not conformance. It stays in the monorepo              |
+| `references.patterns`     | fixed in V1, built in: `process.env.X`, `process.env['X']`, `import.meta.env.X`, `import.meta.env['X']`, `$env/static/*` imports, `env.X`, `{ X } = env` |
+| `secretNamePatterns`      | fixed in V1, built in: `SECRET`, `TOKEN`, `PASSWORD`, `PRIVATE_?KEY`, `ACCESS_?KEY`, `API_?KEY`, case-insensitive                                        |
+| `publicEnvPrefixes`       | fixed in V1, built in: `VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, `REACT_APP_`                                                                                  |
+
+The three fixed ones describe how code reads env and what a name means, which do not vary by
+repository. The migration of the monorepo onto the role is where they are revisited.
+
 ### Sentinel's defaults
 
 `presets/shared.json` in the role. Secret names match **case-insensitively** (`SECRET`, `TOKEN`,
 `PASSWORD`, `PRIVATE_?KEY`, `ACCESS_?KEY`, `API_?KEY`), so serviceapp's `facturationPassword` and a
 camel-case `apiKey` are seen. The scans read `.ts .tsx .mts .cts .js .jsx .mjs .cjs` (and `.svelte`,
-`.vue` for direct reads) across the whole repository, with test files left out of the reader scan.
+`.vue` for direct reads) across the whole repository, with test files left out of the reader scan:
+`.test.<ext>` and `.spec.<ext>` for each of those eight extensions. A value is read as dotenv reads
+it: an unquoted value ends at its first `#` (dotenv's README, "Comments begin where a `#` exists"),
+a quoted one at its closing quote, so `API_TOKEN= # filled by the vault` is blank.
 
 ## In CI
 
@@ -160,6 +190,10 @@ installs it for this step only.
 GitHub documents a cap of 10 warning and 10 error annotations per step
 (<https://docs.github.com/en/rest/checks/runs>): on a repository with more findings, the
 pull request shows only part of the annotations, and the markdown recap is the complete list.
+Past the cap, sentinel still emits one annotation per finding, and emits FIRST, so it is always
+shown, one summary annotation of the same type: at `error` on serviceapp, `55 blocking findings
+(GitHub shows at most 10 error annotations per step): the full list is in the env report, ...`.
+One per type at most, and none at or under 10.
 
 ## What changed from `tools/repo-env`
 
@@ -193,6 +227,11 @@ the same single difference.
 - Rule 6 reads every committed env file, not only contracts, and no contract at all is a note
   rather than a refusal to run.
 - Every finding has a line, so an annotation lands on it.
+- A comment after a value is a comment, as in dotenv: `KEY= # note` is blank, not a committed
+  secret. And a quoted value followed by one, `KEY="" # note`, no longer opens a multi-line value
+  that hid every key after it in the file. The original read `KEY= # note` as filled.
+- Test files are left out of the reader scan for every extension it reads; the original read
+  `.ts` and `.tsx` only, and left out `.spec.ts` and `.test.ts`.
 
 ## Outside the monorepo: what `tools/repo-env` assumed, and what the port does
 

package/docs/validating-a-change.md

@@ -141,8 +141,10 @@ Every cell is a test in `tests/e2e/env.e2e.test.ts`, against the built CLI, on g
 serviceapp-shaped repository (not nx, committed `variables/*.env`), the same with a package below
 its root, an nx workspace with a module, and a directory in no repository. `SENTINEL_ENV_LEVEL` and
 `GITHUB_ACTIONS` are pinned on every call, and "unset" removes the variable from the child's
-environment, which is a different input from the empty string. 52 cells: the 31 of the first draft,
-one more refused verb, 19 new ones, and the rule 1 note.
+environment, which is a different input from the empty string. 57 cells: the 31 of the first draft,
+one more refused verb, 19 new ones, the rule 1 note, and the 5 of the first adopter's feedback
+(a refused config's row, in console and `--json`; test files of every extension; a comment after a
+value; the summary annotation past GitHub's cap).
 
 ### verb, from the repository root
 
@@ -201,8 +203,17 @@ fails nothing would be decoration; none is, and every new cell fails under at le
 | `--json` annotations on stderr                        |             2 |
 | the rule 1 note, never emitted (unit + e2e)           |             3 |
 | the rule 1 note, always emitted (unit + e2e)          |             2 |
+| test files of every extension (suffixes reverted)     |             2 |
+| a comment after a value (parser reverted)             |             5 |
+| the refusal's `error` on the row (adapter reverted)   |             2 |
+| no `undefined` key on the row (orchestrate reverted)  |             1 |
+| a refusal names the kind found (define reverted)      |             4 |
+| the summary annotation past the cap (report reverted) |             4 |
 
 The `COPY` fix is unit (`env-checks-fixes`): reverted, its 3 tests fail and the 66 others pass.
+The six feedback controls ran unit and e2e together over the six env suites (187 tests, 193 for
+the last one, once the summary cells existed): each failed only its own new cells, and no cell that existed before. The two
+summary-annotation guards (nothing at exactly 10, nothing at `info`) pass reverted, as guards do.
 
 ### Against real repositories, from the packed tarball
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hublo/sentinel",
-  "version": "1.6.0-alpha.0",
+  "version": "1.6.0-alpha.1",
   "description": "One CLI that guards code health across Hublo repos: shared lint/typescript/build/test presets, static & dynamic analysis, and architecture checks.",
   "type": "module",
   "license": "MIT",

package/dist/chunk-NAFI7OLI.js.map

@@ -1 +0,0 @@
-{"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/** 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`]\n  return value.some((entry) => typeof entry !== 'string' || entry === '')\n    ? [`${path} must hold non-empty strings only`]\n    : []\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        if (value !== undefined && !Array.isArray(value)) {\n          problems.push(`${key} must be an array of RegExp or strings`)\n        } else if (\n          Array.isArray(value) &&\n          value.some((entry) => !(entry instanceof RegExp) && typeof entry !== 'string')\n        ) {\n          problems.push(`${key} must hold RegExp or strings only`)\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`)\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')\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":";AAwEA,IAAM,iBAAiB,oBAAI,IAAY;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AACD,IAAM,aAAa,oBAAI,IAAI,CAAC,SAAS,OAAO,mBAAmB,aAAa,CAAC;AAC7E,IAAM,cAA6D;AAAA,EACjE,MAAM;AAAA,EACN,YAAY;AAAA,EACZ,SAAS,oBAAI,IAAI,CAAC,YAAY,UAAU,CAAC;AAAA,EACzC,QAAQ,oBAAI,IAAI,CAAC,aAAa,cAAc,CAAC;AAC/C;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAGA,SAAS,mBAAmB,MAAc,OAA0B;AAClE,MAAI,UAAU,OAAW,QAAO,CAAC;AACjC,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC,GAAG,IAAI,8BAA8B;AACxE,SAAO,MAAM,KAAK,CAAC,UAAU,OAAO,UAAU,YAAY,UAAU,EAAE,IAClE,CAAC,GAAG,IAAI,mCAAmC,IAC3C,CAAC;AACP;AAGA,SAAS,WAAW,OAA0C;AAC5D,QAAM,WAAqB,CAAC;AAC5B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,CAAC,eAAe,IAAI,GAAG,GAAG;AAC5B,eAAS,KAAK,gBAAgB,GAAG,GAAG;AACpC;AAAA,IACF;AACA,UAAM,SAAS,YAAY,GAAG;AAC9B,QAAI,WAAW,QAAW;AACxB,UAAI,QAAQ,yBAAyB;AACnC,YAAI,UAAU,UAAa,CAAC,MAAM,QAAQ,KAAK,GAAG;AAChD,mBAAS,KAAK,GAAG,GAAG,wCAAwC;AAAA,QAC9D,WACE,MAAM,QAAQ,KAAK,KACnB,MAAM,KAAK,CAAC,UAAU,EAAE,iBAAiB,WAAW,OAAO,UAAU,QAAQ,GAC7E;AACA,mBAAS,KAAK,GAAG,GAAG,mCAAmC;AAAA,QACzD;AAAA,MACF,OAAO;AACL,iBAAS,KAAK,GAAG,mBAAmB,KAAK,KAAK,CAAC;AAAA,MACjD;AACA;AAAA,IACF;AACA,QAAI,UAAU,OAAW;AACzB,QAAI,CAAC,SAAS,KAAK,GAAG;AACpB,eAAS,KAAK,GAAG,GAAG,oBAAoB;AACxC;AAAA,IACF;AACA,eAAW,CAAC,OAAO,UAAU,KAAK,OAAO,QAAQ,KAAK,GAAG;AACvD,UAAI,CAAC,OAAO,IAAI,KAAK,EAAG,UAAS,KAAK,gBAAgB,GAAG,IAAI,KAAK,GAAG;AAAA,UAChE,UAAS,KAAK,GAAG,mBAAmB,GAAG,GAAG,IAAI,KAAK,IAAI,UAAU,CAAC;AAAA,IACzE;AAAA,EACF;AACA,SAAO;AACT;AAcO,SAAS,UAAU,QAAkB,CAAC,GAAa;AACxD,MAAI,CAAC,SAAS,KAAK,EAAG,OAAM,IAAI,MAAM,kCAAkC;AACxE,QAAM,WAAW,WAAW,KAAK;AACjC,MAAI,SAAS,SAAS,GAAG;AACvB,UAAM,IAAI,MAAM;AAAA,MAA4B,SAAS,KAAK,QAAQ,CAAC,EAAE;AAAA,EACvE;AACA,SAAO;AACT;","names":[]}