@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/assets.mjs

@@ -5,7 +5,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { editionRuleParams } from '../edition-slots.mjs';
 import { found } from './read.mjs';
-
 export const HFS_ASSET_OVERSIZE = 'HFS_ASSET_OVERSIZE';
 export const HFS_ASSET_KIND = 'HFS_ASSET_KIND';
 export const DEFAULT_ASSET_BYTES = 512000;
@@ -21,59 +20,72 @@ const MODEL_DIRECTORY = /(?:^|\/)models?(?:\/|$)/i;
 const DOCS_MEDIA = /^docs\/.+\.(?:png|svg|webp)$/i;
 const USER_ASSET_DIRECTORY = /^src\/assets\/(?:media|uploads?|music|audio|videos?)(?:\/|$)/i;
 const MODEL_BINARY = /(?:^|\/)(?:[^/]*[-_.])?(?:model|weights|checkpoint)(?:[-_.][^/]*)?\.bin$/i;
-
 function assetPolicy(manifest, edition) {
-  const config = editionRuleParams(manifest?.ruleParams?.be ?? {}, edition).assets ?? {};
-  const cap = config.bytes ?? config.maxBytes;
-  const bytes = Number.isSafeInteger(cap) && cap > 0 ? cap : DEFAULT_ASSET_BYTES;
-  const extensions = Array.isArray(config.extensions) ? config.extensions : BUILD_EXTENSIONS;
-  return { bytes, extensions: new Set(extensions.filter((ext) => typeof ext === 'string').map((ext) => `.${ext.replace(/^\./, '').toLowerCase()}`)) };
+    const config = editionRuleParams(manifest?.ruleParams?.be ?? {}, edition).assets ?? {};
+    const cap = config.bytes ?? config.maxBytes;
+    const bytes = Number.isSafeInteger(cap) && cap > 0 ? cap : DEFAULT_ASSET_BYTES;
+    const extensions = Array.isArray(config.extensions) ? config.extensions : BUILD_EXTENSIONS;
+    return { bytes, extensions: new Set(extensions.filter((ext) => typeof ext === 'string').map((ext) => `.${ext.replace(/^\./, '').toLowerCase()}`)) };
 }
-
 function uncompressedName(file) {
-  let name = file;
-  while (COMPRESSED.test(name)) name = name.replace(COMPRESSED, '');
-  return name;
+    let name = file;
+    while (COMPRESSED.test(name))
+        name = name.replace(COMPRESSED, '');
+    return name;
 }
-
 function refusedKind(file, extensions) {
-  const name = uncompressedName(file);
-  const ext = path.posix.extname(name).toLowerCase();
-  const asset = file.startsWith('src/assets/');
-  if (MODEL_EXTENSIONS.has(ext) || MODEL_BINARY.test(name) || (ext === '.bin' && MODEL_DIRECTORY.test(file))) return 'model weights';
-  if (DATASET_EXTENSIONS.has(ext)) return 'a dataset or model artifact';
-  // repo.docs-media owns these images even when their subject is a dataset, weights or checkpoints.
-  if (DOCS_MEDIA.test(file)) return null;
-  if (DATA_DIRECTORY.test(file) && !SOURCE_OR_DOC.test(file)) return 'a dataset or model artifact';
-  if (MEDIA_EXTENSIONS.has(ext) || USER_ASSET_DIRECTORY.test(file)) return 'user media';
-  if (asset) {
-    if (!/^src\/assets\/[^/]+\/.+/.test(file)) return 'an asset outside a per-kind folder';
-    if (!extensions.has(path.posix.extname(file).toLowerCase())) return 'an asset extension outside ruleParams.be.assets.extensions';
-  } else if (IMAGE_EXTENSIONS.has(ext)) return 'media outside be.assets';
-  return null;
+    const name = uncompressedName(file);
+    const ext = path.posix.extname(name).toLowerCase();
+    const asset = file.startsWith('src/assets/');
+    if (MODEL_EXTENSIONS.has(ext) || MODEL_BINARY.test(name) || (ext === '.bin' && MODEL_DIRECTORY.test(file)))
+        return 'model weights';
+    if (DATASET_EXTENSIONS.has(ext))
+        return 'a dataset or model artifact';
+    // repo.docs-media owns these images even when their subject is a dataset, weights or checkpoints.
+    if (DOCS_MEDIA.test(file))
+        return null;
+    if (DATA_DIRECTORY.test(file) && !SOURCE_OR_DOC.test(file))
+        return 'a dataset or model artifact';
+    if (MEDIA_EXTENSIONS.has(ext) || USER_ASSET_DIRECTORY.test(file))
+        return 'user media';
+    if (asset) {
+        if (!/^src\/assets\/[^/]+\/.+/.test(file))
+            return 'an asset outside a per-kind folder';
+        if (!extensions.has(path.posix.extname(file).toLowerCase()))
+            return 'an asset extension outside ruleParams.be.assets.extensions';
+    }
+    else if (IMAGE_EXTENSIONS.has(ext))
+        return 'media outside be.assets';
+    return null;
 }
-
 function fileBytes(repoRoot, file) {
-  try {
-    const stat = fs.lstatSync(path.join(repoRoot, file));
-    return stat.isFile() ? stat.size : null;
-  } catch { return null; }
+    try {
+        const stat = fs.lstatSync(path.join(repoRoot, file));
+        return stat.isFile() ? stat.size : null;
+    }
+    catch {
+        return null;
+    }
 }
-
 /** Side-relative tracked paths only: the app root and FE are left to their own rules, avoiding duplicate root/side findings. */
 export function assetsFindings({ repoRoot, files = [], repo, manifest, isRoot = false, inScope = () => true }) {
-  const edition = repo?.edition ?? 'full';
-  if (isRoot || repo?.profile !== 'be' || !['lite', 'full'].includes(edition)) return [];
-  const policy = assetPolicy(manifest, edition);
-  const findings = [];
-  for (const raw of new Set(files)) {
-    if (!inScope(raw)) continue;
-    const file = raw.replaceAll('\\', '/');
-    const kind = refusedKind(file, policy.extensions);
-    if (kind) findings.push(found(HFS_ASSET_KIND, file, `${file} is ${kind}; keep only small build-time binaries in src/assets/<kind>/, put user media in object storage, and keep model weights and datasets outside git`));
-    if (!file.startsWith('src/assets/')) continue;
-    const bytes = fileBytes(repoRoot, file);
-    if (bytes !== null && bytes > policy.bytes) findings.push(found(HFS_ASSET_OVERSIZE, file, `${file} is ${bytes} bytes, above the ${policy.bytes}-byte per-file build-time asset budget; store it externally and fetch it at runtime`, { bytes, maxBytes: policy.bytes }));
-  }
-  return findings;
+    const edition = repo?.edition ?? 'full';
+    if (isRoot || repo?.profile !== 'be' || !['lite', 'full'].includes(edition))
+        return [];
+    const policy = assetPolicy(manifest, edition);
+    const findings = [];
+    for (const raw of new Set(files)) {
+        if (!inScope(raw))
+            continue;
+        const file = raw.replaceAll('\\', '/');
+        const kind = refusedKind(file, policy.extensions);
+        if (kind)
+            findings.push(found(HFS_ASSET_KIND, file, `${file} is ${kind}; keep only small build-time binaries in src/assets/<kind>/, put user media in object storage, and keep model weights and datasets outside git`));
+        if (!file.startsWith('src/assets/'))
+            continue;
+        const bytes = fileBytes(repoRoot, file);
+        if (bytes !== null && bytes > policy.bytes)
+            findings.push(found(HFS_ASSET_OVERSIZE, file, `${file} is ${bytes} bytes, above the ${policy.bytes}-byte per-file build-time asset budget; store it externally and fetch it at runtime`, { bytes, maxBytes: policy.bytes }));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/boot-proof.d.mts

@@ -0,0 +1,11 @@
+import type { Repo } from './rule-types.mjs';
+export declare const BE_APP_BOOT_PROOF_MISSING = "BE_APP_BOOT_PROOF_MISSING";
+/** Root scopes delegate to the be side, so each app is compiled once. */
+export declare function bootProofFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
+    repoRoot: string;
+    files: string[];
+    all?: string[];
+    repo: Repo;
+    isRoot?: boolean;
+    inScope?: (file: string) => boolean;
+}): import("../app-wiring.mjs").WiringFinding[];

package/runtime/scripts/hfs/rules/boot-proof.mjs

@@ -2,15 +2,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { appWiring } from '../app-wiring.mjs';
-
 export const BE_APP_BOOT_PROOF_MISSING = 'BE_APP_BOOT_PROOF_MISSING';
-
 /** Root scopes delegate to the be side, so each app is compiled once. */
 export function bootProofFindings({ repoRoot, files, all = files, repo, isRoot = Boolean(repo?.sides), inScope = () => true }) {
-  if (repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe') return [];
-  // Dependencies not installed (a fresh scaffold, a lint-only checkout): the Nest graph cannot be compiled, so the proof is unavailable here; CI and every installed app judge it.
-  const installed = [repoRoot, path.dirname(repoRoot ?? '.')].some((dir) => dir && fs.existsSync(path.join(dir, 'node_modules')));
-  return appWiring({ repoRoot, files: all, repo }).findings
-    .filter(finding => installed || finding.reason !== 'module or proof could not be compiled')
-    .filter(finding => inScope(finding.path));
+    if (repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe')
+        return [];
+    // Dependencies not installed (a fresh scaffold, a lint-only checkout): the Nest graph cannot be compiled, so the proof is unavailable here; CI and every installed app judge it.
+    const installed = [repoRoot, path.dirname(repoRoot ?? '.')].some((dir) => dir && fs.existsSync(path.join(dir, 'node_modules')));
+    return appWiring({ repoRoot, files: all, repo }).findings
+        .filter((finding) => installed || finding.reason !== 'module or proof could not be compiled')
+        .filter((finding) => inScope(finding.path));
 }

package/runtime/scripts/hfs/rules/bypass-markers.d.mts

@@ -0,0 +1,9 @@
+import type { Parsed } from './rule-types.mjs';
+export declare const HFS_BYPASS_MARKER = "HFS_BYPASS_MARKER";
+/** The finding message of one marker of `file`. */
+export declare const bypassMessage: (file: string, hit: Parsed) => string;
+/** The findings of R303 over the tracked paths `files` of the repository at `repoRoot`. */
+export declare function bypassMarkerFindings({ repoRoot, files }: {
+    repoRoot: string;
+    files: string[];
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/bypass-markers.mjs

@@ -8,32 +8,27 @@
 //   - a gate configuration relaxed: a coverage target or threshold below the canon, a relaxing switch, a disabled ESLint rule, a strictness option
 //     turned off, an exception file the design-truths manifest does not list.
 // The tree is read as it stands, by the library of the runtime's own loosening check (scripts/lib/loosening-state.mjs, knowledge/hfs/design-truths.yaml);
-// `starci app hygiene` (the pre-commit hook) reads the staged bypass markers with the same table (scripts/lib/bypass-markers.mjs). The ignore and
+// `starci app check --staged` (the pre-commit hook) reads the staged bypass markers with the same table (scripts/lib/bypass-markers.mjs). The ignore and
 // exclude lists of a managed config are the managed-file drift's (HFS_MANAGED_FILE_DRIFT).
 import fs from 'node:fs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readText } from './read.mjs';
 import { bypassesIn } from '../../lib/bypass-markers.mjs';
 import { findingLine, stateFindings } from '../../lib/loosening-state.mjs';
-
 export const HFS_BYPASS_MARKER = 'HFS_BYPASS_MARKER';
 const TRUTHS_FILE = new URL('../../../knowledge/hfs/design-truths.yaml', import.meta.url);
-
 /** The finding message of one marker of `file`. */
 export const bypassMessage = (file, hit) => `${file}:${hit.line} spells ${hit.label} (${hit.text.slice(0, 80)}); a check is satisfied, never bypassed: fix the cause and delete the marker`;
-
 const markerFindings = ({ repoRoot, files }) => files.flatMap((file) => {
-  const text = readText(repoRoot, file);
-  return text === null ? [] : bypassesIn(file, text).map((hit) => found(HFS_BYPASS_MARKER, file, bypassMessage(file, hit), { line: hit.line }));
+    const text = readText(repoRoot, file);
+    return text === null ? [] : bypassesIn(file, text).map((hit) => found(HFS_BYPASS_MARKER, file, bypassMessage(file, hit), { line: hit.line }));
 });
-
 /** The relaxed gate configuration of `files`: the library's findings other than the markers and the lists. */
 const configFindings = ({ repoRoot, files }) => stateFindings({ files, read: (file) => readText(repoRoot, file), truths: parseYaml(fs.readFileSync(TRUTHS_FILE, 'utf8')), lists: false })
-  .filter((entry) => entry.kind !== 'bypass' && entry.kind !== 'truths')
-  .map((entry) => found(HFS_BYPASS_MARKER, entry.file, `${entry.file}:${entry.line} relaxes a gate (${findingLine(entry)}); a check is satisfied, never relaxed: restore the canon value`, { line: entry.line }));
-
+    .filter((entry) => entry.kind !== 'bypass' && entry.kind !== 'truths')
+    .map((entry) => found(HFS_BYPASS_MARKER, entry.file, `${entry.file}:${entry.line} relaxes a gate (${findingLine(entry)}); a check is satisfied, never relaxed: restore the canon value`, { line: entry.line }));
 /** The findings of R303 over the tracked paths `files` of the repository at `repoRoot`. */
 export function bypassMarkerFindings({ repoRoot, files }) {
-  const markers = markerFindings({ repoRoot, files });
-  return markers.concat(configFindings({ repoRoot, files }));
+    const markers = markerFindings({ repoRoot, files });
+    return markers.concat(configFindings({ repoRoot, files }));
 }

package/runtime/scripts/hfs/rules/canon-copy-drift.d.mts

@@ -0,0 +1,10 @@
+import type { Finding } from './rule-types.mjs';
+/** The @starci/hfs version the app at `repoRoot` pins: its lockfile's resolution (hoisted first), else an exact package.json pin. */
+export declare function pinnedHfsVersion(repoRoot: string): string | undefined;
+/** The template roots of the app's pinned @starci/hfs, or null when no copy of that version is at hand. */
+export declare function pinnedTemplateRoots(repoRoot: string): string[] | null;
+export declare function canonCopyDriftFindings({ repoRoot, files, inScope }: {
+    repoRoot: string;
+    files: string[];
+    inScope: (file: string) => boolean;
+}): Finding[];

package/runtime/scripts/hfs/rules/canon-copy-drift.mjs

@@ -10,97 +10,99 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { found } from './read.mjs';
-
 const CANON_COPY = 'HFS_CANON_COPY_DRIFT';
 const OWN_ROOT = path.resolve(import.meta.dirname, '../../../..');
 const OWN_TEMPLATE_ROOTS = [
-  path.resolve(import.meta.dirname, '../../../packages/hfs/templates'),
-  path.join(OWN_ROOT, 'templates'),
+    path.resolve(import.meta.dirname, '../../../packages/hfs/templates'),
+    path.join(OWN_ROOT, 'templates'),
 ];
 const TEMPLATE_DIR = 'be/skeleton/';
 const HFS_LOCK_KEY = 'node_modules/@starci/hfs';
 const EXACT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
-
 // The three managed files the standard's secret-custody law pins byte-for-byte.
 const CANON_PATHS = [
-  'src/modules/platform/config/env-source.config.ts',
-  'src/modules/platform/http-security/origin.guard.ts',
-  'src/modules/platform/http-security/webhook-signature.service.ts',
+    'src/modules/platform/config/env-source.config.ts',
+    'src/modules/platform/http-security/origin.guard.ts',
+    'src/modules/platform/http-security/webhook-signature.service.ts',
 ];
-const REGEX_ESCAPE = String.raw`\$&`;
+const REGEX_ESCAPE = String.raw `\$&`;
 const CANON_SUFFIX = new RegExp(`(?:^|/)(${CANON_PATHS.map((rel) => rel.replace(/[.*+?^${}()|[\]\\]/g, REGEX_ESCAPE)).join('|')})$`);
-
 const readJson = (file) => {
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return undefined;
-  }
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
 };
 const versionAt = (folder) => readJson(path.join(folder, 'package.json'))?.version;
-
 /** The @starci/hfs version the app at `repoRoot` pins: its lockfile's resolution (hoisted first), else an exact package.json pin. */
 export function pinnedHfsVersion(repoRoot) {
-  const packages = readJson(path.join(repoRoot, 'package-lock.json'))?.packages ?? {};
-  const locked = Object.keys(packages)
-    .filter((key) => key === HFS_LOCK_KEY || key.endsWith(`/${HFS_LOCK_KEY}`))
-    .sort((left, right) => left.length - right.length)
-    .map((key) => packages[key]?.version)
-    .find((version) => typeof version === 'string');
-  if (locked) return locked;
-  const manifest = readJson(path.join(repoRoot, 'package.json')) ?? {};
-  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
-    const spec = manifest[field]?.['@starci/hfs'];
-    if (typeof spec === 'string' && EXACT.test(spec)) return spec;
-  }
-  return undefined;
+    const packages = readJson(path.join(repoRoot, 'package-lock.json'))?.packages ?? {};
+    const locked = Object.keys(packages)
+        .filter((key) => key === HFS_LOCK_KEY || key.endsWith(`/${HFS_LOCK_KEY}`))
+        .sort((left, right) => left.length - right.length)
+        .map((key) => packages[key]?.version)
+        .find((version) => typeof version === 'string');
+    if (locked)
+        return locked;
+    const manifest = readJson(path.join(repoRoot, 'package.json')) ?? {};
+    for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const spec = manifest[field]?.['@starci/hfs'];
+        if (typeof spec === 'string' && EXACT.test(spec))
+            return spec;
+    }
+    return undefined;
 }
-
 /** The template roots of the app's pinned @starci/hfs, or null when no copy of that version is at hand. */
 export function pinnedTemplateRoots(repoRoot) {
-  const pin = pinnedHfsVersion(repoRoot);
-  if (pin === undefined || versionAt(OWN_ROOT) === pin) return OWN_TEMPLATE_ROOTS;
-  const copies = [
-    path.join(repoRoot, 'node_modules', '@starci', 'hfs'),
-    path.join(repoRoot, 'node_modules', 'starci-harness', 'node_modules', '@starci', 'hfs'),
-  ];
-  const installed = copies.find((copy) => versionAt(copy) === pin);
-  return installed === undefined ? null : [path.join(installed, 'templates')];
+    const pin = pinnedHfsVersion(repoRoot);
+    if (pin === undefined || versionAt(OWN_ROOT) === pin)
+        return OWN_TEMPLATE_ROOTS;
+    const copies = [
+        path.join(repoRoot, 'node_modules', '@starci', 'hfs'),
+        path.join(repoRoot, 'node_modules', 'starci-harness', 'node_modules', '@starci', 'hfs'),
+    ];
+    const installed = copies.find((copy) => versionAt(copy) === pin);
+    return installed === undefined ? null : [path.join(installed, 'templates')];
 }
-
 const templateBytes = (roots, rel) => {
-  for (const root of roots) {
-    const file = path.join(root, TEMPLATE_DIR, rel);
-    try {
-      const bytes = fs.readFileSync(file);
-      if (bytes.length) return bytes;
-    } catch { /* next root */ }
-  }
-  return null;
+    for (const root of roots) {
+        const file = path.join(root, TEMPLATE_DIR, rel);
+        try {
+            const bytes = fs.readFileSync(file);
+            if (bytes.length)
+                return bytes;
+        }
+        catch { /* next root */ }
+    }
+    return null;
 };
 const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
-
 export function canonCopyDriftFindings({ repoRoot, files, inScope }) {
-  const findings = [];
-  const roots = pinnedTemplateRoots(repoRoot);
-  if (roots === null) return findings;
-  for (const file of files.filter((f) => !inScope || inScope(f))) {
-    const hit = CANON_SUFFIX.exec(file.replaceAll('\\', '/'));
-    if (!hit) continue;
-    const expected = templateBytes(roots, hit[1]);
-    if (!expected) continue;
-    let actual;
-    try {
-      actual = fs.readFileSync(path.join(repoRoot, file));
-    } catch {
-      continue;
+    const findings = [];
+    const roots = pinnedTemplateRoots(repoRoot);
+    if (roots === null)
+        return findings;
+    for (const file of files.filter((f) => !inScope || inScope(f))) {
+        const hit = CANON_SUFFIX.exec(file.replaceAll('\\', '/'));
+        if (!hit)
+            continue;
+        const expected = templateBytes(roots, hit[1]);
+        if (!expected)
+            continue;
+        let actual;
+        try {
+            actual = fs.readFileSync(path.join(repoRoot, file));
+        }
+        catch {
+            continue;
+        }
+        const expectedHash = sha256(expected);
+        const actualHash = sha256(actual);
+        if (actualHash === expectedHash)
+            continue;
+        findings.push(found(CANON_COPY, file, `${file} differs from the canon copy it was scaffolded from (sha256 ${actualHash.slice(0, 12)} vs ${expectedHash.slice(0, 12)}); restore the managed file's bytes - it is hash-sensitive canon, not a file to edit`, { expectedHash, actualHash }));
     }
-    const expectedHash = sha256(expected);
-    const actualHash = sha256(actual);
-    if (actualHash === expectedHash) continue;
-    findings.push(found(CANON_COPY, file,
-      `${file} differs from the canon copy it was scaffolded from (sha256 ${actualHash.slice(0, 12)} vs ${expectedHash.slice(0, 12)}); restore the managed file's bytes - it is hash-sensitive canon, not a file to edit`,
-      { expectedHash, actualHash }));
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/ci-custody.d.mts

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** Offline CI custody findings of an app root, in both lite and full editions. */
+export declare function ciCustodyFindings({ repoRoot, repo, isRoot }: {
+    repoRoot: string;
+    repo: Repo;
+    isRoot: boolean;
+}): any[];

package/runtime/scripts/hfs/rules/ci-custody.mjs

@@ -4,101 +4,100 @@ import { list } from '../../lib/list.mjs';
 import { findStackDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
 import { readCiDeclaration, sealedKeyNames, workflowReferences, ciNamesOfServices } from '../ci-declaration.mjs';
 import { found } from './read.mjs';
-
 const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
 const named = (entry) => typeof entry.name === 'string' && /^[A-Z][A-Z0-9_]*$/.test(entry.name);
 const identity = (kind, name) => `${kind}:${name}`;
 const atCi = (section) => `${DECLARATION}#ci.${section}`;
-
 /** A CI or Dependabot secret must never also live in a sealed app member. */
 function sealedFindings(ci, sealed) {
-  const names = new Set([...ci.secrets, ...ci.dependabotSecrets].filter(named).map((entry) => entry.name));
-  return sealed.filter(({ key }) => names.has(key)).map(({ key, file }) => found(
-    'CI_SECRET_SEALED', file,
-    `${key} is a CI secret (GitHub reads it) but it is sealed in ${file} for app containers; one key, one class: remove it from the member (starci app secret unset ...) and set it with starci app ci secret set ${key}`,
-  ));
+    const names = new Set([...ci.secrets, ...ci.dependabotSecrets].filter(named).map((entry) => entry.name));
+    return sealed.filter(({ key }) => names.has(key)).map(({ key, file }) => found('CI_SECRET_SEALED', file, `${key} is a CI secret (GitHub reads it) but it is sealed in ${file} for app containers; one key, one class: remove it from the member (starci app secret unset --env <env> ...) and set it with starci app ci secret set ${key} --execute`));
 }
-
 /** A source selects sealed keys only from its own member and environment. */
 function sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen }) {
-  for (const entry of sealed) {
-    if (entry.env !== environment || entry.member !== source?.member || !names.has(entry.key)) continue;
-    if (source.keys !== undefined && !list(source.keys).includes(entry.key)) continue;
-    const id = `${entry.file}:${grant.service}:${entry.key}`;
-    if (seen.has(id)) continue;
-    seen.add(id);
-    findings.push(found('APP_SECRET_IN_CI', entry.file,
-      `${entry.key} is read by the ${grant.service} container at runtime through the ${environment} deploy grant; keep it in the .enc and drop it from ci`));
-  }
+    for (const entry of sealed) {
+        if (entry.env !== environment || entry.member !== source?.member || !names.has(entry.key))
+            continue;
+        if (source.keys !== undefined && !list(source.keys).includes(entry.key))
+            continue;
+        const id = `${entry.file}:${grant.service}:${entry.key}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        findings.push(found('APP_SECRET_IN_CI', entry.file, `${entry.key} is read by the ${grant.service} container at runtime through the ${environment} deploy grant; keep it in the .enc and drop it from ci`));
+    }
 }
-
 /** Only keys actually selected by a grant, in that grant's environment and member, are runtime consumers. */
 function runtimeFindings(doc, ci, sealed) {
-  const names = new Set([...ci.secrets, ...ci.vars].filter(named).map((entry) => entry.name));
-  const findings = [], seen = new Set();
-  for (const [environment, spec] of Object.entries(doc.environments ?? {})) {
-    for (const grant of list(spec?.deploy?.secrets?.grants)) {
-      if (typeof grant?.service !== 'string') continue;
-      for (const source of list(grant.from)) sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen });
+    const names = new Set([...ci.secrets, ...ci.vars].filter(named).map((entry) => entry.name));
+    const findings = [], seen = new Set();
+    for (const [environment, spec] of Object.entries(doc.environments ?? {})) {
+        for (const grant of list(spec?.deploy?.secrets?.grants)) {
+            if (typeof grant?.service !== 'string')
+                continue;
+            for (const source of list(grant.from))
+                sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen });
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 /** Workflow reads are class-sensitive; legacy lists remain readable, but an absent ci block always signals migration once per name. */
 function workflowFindings(doc, declared, references) {
-  const hasCi = doc.ci !== undefined;
-  const allowed = new Set(declared.map(({ kind, name }) => identity(kind, name)));
-  if (hasCi) {
-    for (const entry of ciNamesOfServices(doc).filter(named)) {
-      const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);
-      if (legacy.some((item) => (typeof item === 'string' ? item : item?.name) === entry.name)) allowed.add(identity(`${entry.kind}s`, entry.name));
+    const hasCi = doc.ci !== undefined;
+    const allowed = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+    if (hasCi) {
+        for (const entry of ciNamesOfServices(doc).filter(named)) {
+            const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);
+            if (legacy.some((item) => (typeof item === 'string' ? item : item?.name) === entry.name))
+                allowed.add(identity(`${entry.kind}s`, entry.name));
+        }
+    }
+    const findings = [], seen = new Set();
+    for (const { file, kind, name } of references) {
+        if (allowed.has(identity(kind, name)))
+            continue;
+        const id = hasCi ? `${file}:${kind}:${name}` : name;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        findings.push(found('CI_DECLARATION_DRIFT', file, `${kind}.${name} is read by this workflow but is not declared in ci.${kind}; declare its name, scope and consumer in ${DECLARATION}`));
     }
-  }
-  const findings = [], seen = new Set();
-  for (const { file, kind, name } of references) {
-    if (allowed.has(identity(kind, name))) continue;
-    const id = hasCi ? `${file}:${kind}:${name}` : name;
-    if (seen.has(id)) continue;
-    seen.add(id);
-    findings.push(found('CI_DECLARATION_DRIFT', file,
-      `${kind}.${name} is read by this workflow but is not declared in ci.${kind}; declare its name, scope and consumer in ${DECLARATION}`));
-  }
-  return findings;
+    return findings;
 }
-
 /** Dependabot has its own store and consumer, so only Actions secrets and vars require a workflow read. */
 function driftFindings(doc, ci, references) {
-  const declared = [
-    ...ci.secrets.filter(named).map((entry) => ({ ...entry, kind: 'secrets' })),
-    ...ci.vars.filter(named).map((entry) => ({ ...entry, kind: 'vars' })),
-  ];
-  const findings = workflowFindings(doc, declared, references);
-  if (doc.ci === undefined) return findings;
-  const reads = new Set(references.map(({ kind, name }) => identity(kind, name)));
-  for (const { kind, name, optional } of declared) {
-    if (!optional && !reads.has(identity(kind, name))) findings.push(found('CI_DECLARATION_DRIFT', atCi(kind),
-      `${name} is declared in ci.${kind} as non-optional but no workflow reads it; remove the declaration, mark it optional or wire its workflow consumer`));
-  }
-  const names = new Set(declared.map(({ kind, name }) => identity(kind, name)));
-  for (const [service, entry] of Object.entries(doc.services ?? {})) {
-    for (const [field, kind] of [['token', 'secrets'], ['hostVar', 'vars']]) {
-      const name = entry?.ci?.[field];
-      if (typeof name !== 'string' || names.has(identity(kind, name))) continue;
-      findings.push(found('CI_DECLARATION_DRIFT', atCi(kind),
-        `services.${service}.ci.${field} names ${name}, which is not declared in ci.${kind}; declare the shared CI name`));
+    const declared = [
+        ...ci.secrets.filter(named).map((entry) => ({ ...entry, kind: 'secrets' })),
+        ...ci.vars.filter(named).map((entry) => ({ ...entry, kind: 'vars' })),
+    ];
+    const findings = workflowFindings(doc, declared, references);
+    if (doc.ci === undefined)
+        return findings;
+    const reads = new Set(references.map(({ kind, name }) => identity(kind, name)));
+    for (const { kind, name, optional } of declared) {
+        if (!optional && !reads.has(identity(kind, name)))
+            findings.push(found('CI_DECLARATION_DRIFT', atCi(kind), `${name} is declared in ci.${kind} as non-optional but no workflow reads it; remove the declaration, mark it optional or wire its workflow consumer`));
+    }
+    const names = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+    for (const [service, entry] of Object.entries(doc.services ?? {})) {
+        for (const [field, kind] of [['token', 'secrets'], ['hostVar', 'vars']]) {
+            const name = entry?.ci?.[field];
+            if (typeof name !== 'string' || names.has(identity(kind, name)))
+                continue;
+            findings.push(found('CI_DECLARATION_DRIFT', atCi(kind), `services.${service}.ci.${field} names ${name}, which is not declared in ci.${kind}; declare the shared CI name`));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 /** Offline CI custody findings of an app root, in both lite and full editions. */
 export function ciCustodyFindings({ repoRoot, repo, isRoot }) {
-  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
-  const { doc } = findStackDeclaration(repoRoot);
-  if (!doc) return [];
-  const ci = readCiDeclaration(doc);
-  const sealed = sealedKeyNames(repoRoot, { fs });
-  const references = workflowReferences(repoRoot, { fs });
-  return [...sealedFindings(ci, sealed), ...runtimeFindings(doc, ci, sealed), ...driftFindings(doc, ci, references)];
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((edition) => edition === repo.edition) || isRoot === false)
+        return [];
+    const { doc } = findStackDeclaration(repoRoot);
+    if (!doc)
+        return [];
+    const ci = readCiDeclaration(doc);
+    const sealed = sealedKeyNames(repoRoot, { fs });
+    const references = workflowReferences(repoRoot, { fs });
+    return [...sealedFindings(ci, sealed), ...runtimeFindings(doc, ci, sealed), ...driftFindings(doc, ci, references)];
 }

package/runtime/scripts/hfs/rules/ci-standard.d.mts

@@ -0,0 +1,12 @@
+import type { Parsed } from './rule-types.mjs';
+export declare const CI_STANDARD = "CI_STANDARD";
+/** The R301 findings of one workflow document: scope `app-ci` (with the app's edition) or `runtime`. Pure over the document and the standard. */
+export declare function ciStandardFindings({ doc, file, scope, edition, standard }: {
+    doc: Parsed;
+    file: string;
+    scope: Parsed;
+    edition?: string;
+    standard?: Parsed;
+}): any[];
+/** R301 over an app: its managed .github/workflows/ci.yml (the app check, and the runtime check over every example app). */
+export declare function ciStandardAppFindings(ctx: Parsed): any[];