@starci/hfs 4.7.32 → 4.7.33

package/runtime/scripts/hfs/stack-deploy-config.mjs

@@ -19,7 +19,7 @@ const ARGUMENT = /^[A-Za-z0-9_@%+=:,./-]+$/u;
 const UPPER_ENV = KEY;
 
 const FIELDS = {
-  deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
+  deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'postDeploy', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
   remote: ['host', 'releasesBase', 'sealed'],
   sealed: ['ops', 'sshKey', 'knownHosts'],
   image: ['app', 'buildArgs'],
@@ -35,7 +35,7 @@ const FIELDS = {
   http: ['name', 'url', 'method', 'body', 'status', 'json', 'contains', 'retry'],
   exec: ['name', 'service', 'command', 'stdout'],
   jobs: ['service', 'command'],
-  task: ['service', 'command'],
+  task: ['service', 'command', 'timeoutSeconds'],
   backup: ['image', 'keepDays', 'dir', 'volumes'],
   backupVolume: ['name', 'volume'],
   registry: ['host', 'visibility'],
@@ -228,9 +228,11 @@ function jobs(c, block, services) {
 }
 
 const TASK_NAME = /^[a-z][a-z0-9-]{0,40}$/u;
+/** The seconds a post-deploy task may run before the deploy counts it failed and rolls back. */
+const DEFAULT_TASK_TIMEOUT_SECONDS = 600;
 
 /** The one-off commands (`starci app stack task <name>`): name -> { service, command }, each run inside a running task of the service. */
-function tasks(c, block, services) {
+function tasksOf(c, block, services) {
   if (block === undefined) return {};
   if (!plain(block)) { c.problem('deploy.tasks', 'must be a mapping'); return {}; }
   const out = {};
@@ -240,11 +242,24 @@ function tasks(c, block, services) {
     if (!closedFields(c, at, entry, FIELDS.task)) continue;
     nameField(c, `${at}.service`, entry.service);
     if (services.size > 0 && !services.has(entry.service)) c.problem(`${at}.service`, `${entry.service} is not a service of the stack source`);
-    out[name] = { service: entry.service, command: command(c, `${at}.command`, entry.command) };
+    if (entry.timeoutSeconds !== undefined && !(Number.isInteger(entry.timeoutSeconds) && entry.timeoutSeconds >= 1 && entry.timeoutSeconds <= 3600)) c.problem(`${at}.timeoutSeconds`, 'must be a whole number of seconds from 1 to 3600');
+    out[name] = { service: entry.service, command: command(c, `${at}.command`, entry.command), timeoutSeconds: entry.timeoutSeconds ?? DEFAULT_TASK_TIMEOUT_SECONDS };
   }
   return out;
 }
 
+/** The release tasks that run after convergence and before verification: a unique list of declared task names, in run order. */
+function postDeploy(c, block, declared) {
+  if (block === undefined) return [];
+  if (!Array.isArray(block)) { c.problem('deploy.postDeploy', 'must be a list of declared task names'); return []; }
+  block.forEach((name, index) => {
+    const at = `deploy.postDeploy[${index}]`;
+    if (typeof name !== 'string' || !Object.hasOwn(declared, name)) c.problem(at, 'must name a task declared under deploy.tasks');
+    else if (block.indexOf(name) !== index) c.problem(at, `${name} is listed twice`);
+  });
+  return block;
+}
+
 const REGISTRY_HOST = /^[a-z0-9][a-z0-9.-]*(?::\d{1,5})?$/u;
 const VISIBILITY = ['public', 'private'];
 
@@ -295,6 +310,7 @@ export function normalizeDeploy(block, { project, probe }) {
   const services = probe.services ?? new Set();
   const members = probe.members ?? new Set();
   if (block.stack !== undefined) nameField(c, 'deploy.stack', block.stack);
+  const tasks = tasksOf(c, block.tasks, services);
   const config = {
     stack: block.stack ?? project,
     remote: remote(c, block.remote),
@@ -306,7 +322,8 @@ export function normalizeDeploy(block, { project, probe }) {
     passEnv: block.passEnv === undefined ? [] : stringList(c, 'deploy.passEnv', block.passEnv, KEY),
     verify: verify(c, block.verify, services),
     jobs: jobs(c, block.jobs, services),
-    tasks: tasks(c, block.tasks, services),
+    tasks,
+    postDeploy: postDeploy(c, block.postDeploy, tasks),
     backup: backup(c, block.backup),
     ingress: ingress(c, block.ingress, probe),
     registry: registry(c, block.registry),

package/runtime/scripts/hfs/stacks-gate.mjs

@@ -13,7 +13,8 @@ import { ingressIssues } from './rules/stacks-ingress.mjs';
 import { liteBackingIssues } from './rules/stacks-lite-backing.mjs';
 import { releaseBackupIssues, scheduleIssues } from './rules/stacks-release.mjs';
 import { stacksDeploymentContexts } from './rules/stacks-runtime.mjs';
-import { appEdition, applicationStackFindings, liteCustodyDirectory } from './starcistacks-runtime.mjs';
+import { readJson } from './rules/read.mjs';
+import { applicationStackFindings, liteCustodyDirectory } from './starcistacks-runtime.mjs';
 
 const RESULT='starci/application-stacks-check@1';
 const STACKS_DIR='.starcistacks';
@@ -32,7 +33,7 @@ const HARDENING_CODES=new Set([
   'STACKS_PLACEMENT_MISSING','STACKS_HEALTHCHECK_MISSING','STACKS_UPDATE_POLICY_MISSING','STACKS_REALTIME_SCALED',
   'STACKS_RELEASE_UNDECLARED','BACKUP_UNDECLARED','BACKUP_PROOF_MISSING','STACKS_MODEL_UNAVAILABLE',
   'HFS_SCHEDULE_UNDECLARED','STACKS_INGRESS_UNDECLARED','STACKS_INGRESS_UNKNOWN',
-  'STACKS_LITE_SELFHOSTED_DB','STACKS_SIDECAR_VOLUME_UNDECLARED','STACKS_SIDECAR_DB_UNSUPPORTED',
+  'STACKS_LITE_SELFHOSTED_DB','STACKS_SIDECAR_VOLUME_UNDECLARED','STACKS_SIDECAR_DB_UNSUPPORTED','STACKS_LITE_REDIS_PERSISTENCE',
 ]);
 
 function regular(file,{root=null}={}){
@@ -296,11 +297,29 @@ const checkServiceEnvironment=(services,add)=>{
   for(const [service,definition] of Object.entries(services))for(const [key] of composeEntries(definition?.environment, { isMapping: object }))
     if(sensitive.test(key)&&!/_FILE$/i.test(key))add('plaintext-sensitive-environment',`services.${service}.environment.${key}`,'sensitive configuration is present as a direct environment value; value redacted');
 };
-const checkModel=({model,ids,spec,manifest,lite,add})=>{
+const dependencyComponent=(id,component,apps)=>component?.stateful===true||component?.database!==undefined
+  ||!apps.has(component?.app)&&!apps.has(id)&&!['service','job'].includes(component?.role);
+const checkDependencyContainers=({services,spec,manifest,repo,add})=>{
+  const apps=new Set([...(Array.isArray(repo?.apps)?repo.apps:[]),
+    ...Object.values(object(repo?.sides)?repo.sides:{}).flatMap(side=>Array.isArray(side?.apps)?side.apps:[])].map(app=>app.name));
+  for(const id of Object.keys(object(spec?.components)?spec.components:{})){
+    const component=manifest.components?.[id];
+    if(nonempty(component?.app)&&!apps.has(component.app))
+      add('HFS_STACKS_SHAPE',`components.${id}.app`,'an application component must name an app in the HFS declaration');
+    if(!dependencyComponent(id,component,apps))continue;
+    const service=services[id];
+    if(!object(service)||!nonempty(service.image)&&!nonempty(service.build)&&!nonempty(service.build?.context))
+      add('HFS_STACKS_SHAPE',`services.${id}`,'a selected dependency must run in a Docker Linux container with a rendered image or build context');
+    else if(service.platform!==undefined&&(typeof service.platform!=='string'||!/^linux(?:\/[^/]+){0,2}$/.test(service.platform)))
+      add('HFS_STACKS_SHAPE',`services.${id}.platform`,'a selected dependency must use a Docker Linux container platform');
+  }
+};
+const checkModel=({model,ids,spec,manifest,lite,repo,add})=>{
   const services=object(model.services)?model.services:{};
   checkServiceIds(services,ids,add);
   if(unresolvedCompose(model))add('compose-placeholder-unresolved','composeModel','rendered Compose still contains an unresolved interpolation placeholder in a host-resolved field');
   checkServiceEnvironment(services,add);
+  checkDependencyContainers({services,spec,manifest,repo,add});
   if(object(spec)&&spec.runtime==='docker-swarm')for(const issue of swarmModelIssues({model,components:manifest.components,bindings:spec.components,lite}))
     add('HFS_STACKS_SHAPE',issue.at,issue.message);
 };
@@ -327,12 +346,12 @@ const checkKubernetesDeclaration=(manifest,add)=>{
   if(!['deferred','supported'].includes(manifest.k8s?.status)||!String(manifest.k8s?.reason??'').trim())
     add('k8s-status-invalid','k8s','Kubernetes must be explicitly deferred or supported with a reason');
 };
-const checkSelectedEnvironment=({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,add})=>{
+const checkSelectedEnvironment=({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,repo,add})=>{
   if(nonempty(environment)&&!environmentNames.has(String(environment)))
     add('environment-unknown','environment',`environment must be one the declaration admits: ${[...environmentNames].join(', ')}`);
   const spec=environments[String(environment)],envDir=path.join(stacksRoot,String(environment??''));
   if(object(spec))checkEnvironmentSpec({spec,environment,envDir,ids,root,add});
-  checkModel({model,ids,spec,manifest,lite,add});
+  checkModel({model,ids,spec,manifest,lite,repo,add});
 };
 const checkStacksManifest=(manifest,model,{stacksRoot,environment,root,repo,add})=>{
   for(const issue of validateSchema(manifest))add('schema-shape-invalid',issue.path,issue.message);
@@ -342,7 +361,7 @@ const checkStacksManifest=(manifest,model,{stacksRoot,environment,root,repo,add}
   checkStacksTree({stacksRoot,manifest,environmentNames,add,lite});
   checkKubernetesDeclaration(manifest,add);
   for(const issue of swarmInventoryIssues({components:manifest.components,lite}))add('HFS_STACKS_SHAPE',issue.at,issue.message);
-  checkSelectedEnvironment({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,add});
+  checkSelectedEnvironment({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,repo,add});
 };
 
 function deploymentAvailable(model,errors){
@@ -370,8 +389,10 @@ function checkSwarmHardening({manifest,model,environment,root,files,repo,errors,
 
 export function checkApplicationStacks({repoRoot,environment,deploymentModelFile,files,repo}={}){
   const root=path.resolve(String(repoRoot??'')),stacksRoot=path.join(root,STACKS_DIR),manifestFile=path.join(stacksRoot,'application-stacks.yaml'),errors=[];
-  const declaration=repo??{edition:appEdition(root)};
+  const diskDeclaration=readJson(root,'hfs.json'),declaration={edition:'full',...(object(diskDeclaration)?diskDeclaration:{}),...(object(repo)?repo:{})};
   const add=(code,at,message)=>errors.push({code,path:at,message});
+  if(fs.existsSync(path.join(root,'hfs.json'))&&!object(diskDeclaration))
+    add('HFS_STACKS_SHAPE','hfs.json','the HFS declaration must be a readable JSON object before application identities can be checked');
   checkInputPaths({environment,stacksRoot,manifestFile,deploymentModelFile,add});
   const {manifest,model}=loadInputs({manifestFile,deploymentModelFile,errors,add});
   checkStacksManifest(manifest,model,{stacksRoot,environment,root,repo:declaration,add});

package/runtime/scripts/hfs/view.mjs

@@ -14,7 +14,7 @@ const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(tex
  *
  * @param {object} opened - The result of `openHfs` (manifest, repo and resolver methods).
  * @param {string} repoRoot - The absolute repository root.
- * @returns {object} The frozen view: profile, apps, connections, ruleParams, relative, classify, slotOf, tierOf, ownerOf, slot.
+ * @returns {object} The frozen view: profile, apps, connections, patterns, ruleParams, relative, classify, slotOf, tierOf, ownerOf, slot.
  */
 function hfsView(opened, repoRoot) {
   const rel = (file) => {
@@ -35,6 +35,7 @@ function hfsView(opened, repoRoot) {
     edition: opened.repo.edition ?? 'full',
     apps: opened.repo.apps,
     connections: opened.repo.connections,
+    patterns: Object.freeze([...(opened.repo.patterns ?? [])]),
     ruleParams: opened.ruleParams(),
     /** The repository-relative, forward-slash form of a linted filename. */
     relative: rel,

package/runtime/scripts/lib/app-data.mjs

@@ -0,0 +1,11 @@
+// app-data.mjs — the per-OS application-data base directory (the parent of 'orca', 'codex-runtime-home'
+// and friends): %APPDATA% on Windows, ~/Library/Application Support on macOS, $XDG_CONFIG_HOME|~/.config elsewhere.
+import os from 'node:os';
+import path from 'node:path';
+
+/** The application-data base directory of this platform: {env, platform, home}: the caller passes the environment. */
+export const appDataBase = ({ env, platform = process.platform, home = os.homedir() } = {}) => {
+  if (platform === 'win32') return env.APPDATA || path.join(home, 'AppData', 'Roaming');
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support');
+  return env.XDG_CONFIG_HOME || path.join(home, '.config');
+};

package/runtime/scripts/lib/bypass-markers.mjs

@@ -1,116 +1,313 @@
 // bypass-markers.mjs - what a BYPASS of a check looks like in text (owner ruling loosening-always-red: any bypass is red, always).
-// One table serves both sides of the no-bypass law:
-//   product   scripts/hfs/rules/bypass-markers.mjs (HFS_BYPASS_MARKER, `starci app check`) and `starci app hygiene` (the pre-commit
-//             hook) read a whole file and refuse every marker in it;
-//   runtime   scripts/lib/gate-loosening.mjs reads the ADDED lines of a diff of a watched check, canon template or workflow.
-// A marker is a way to make a check pass without satisfying it: an inline disable of any tool, a type-check escape, a Sonar or
-// coverage exclusion comment, a skipped or focused test, a failure swallowed in a hook or a workflow step.
-// The patterns are assembled from fragments (joined) so that this file never spells a marker itself: the runtime detector watches
-// its own library like every other check script.
+// One table serves both sides of the no-bypass law, and both read a whole file as it stands (no history):
+//   product   scripts/hfs/rules/bypass-markers.mjs (HFS_BYPASS_MARKER, `starci app check`) and `starci app hygiene` (the pre-commit hook);
+//   runtime   scripts/lib/loosening-state.mjs (RT_LOOSENING_STATE, `starci runtime check`).
+// A marker is a way to make a check pass without satisfying it: an inline disable of any tool, a type-check escape, a Sonar or coverage
+// exclusion comment, a skipped or focused test, a failure swallowed in a hook, a script or a workflow step, a hook skipped.
+// A directive is read where it acts: a suppression word at the start of a comment, a test marker in code, a swallowed failure in a shell line or
+// in the string a script hands a shell. The same words quoted as data (a message, a ban list, a fixture) are no directive.
+// No file is skipped for its place or its name: a generated file or a folder named build is read like any other (a generator that emits a marker
+// is a loosening too); build output is untracked and never reaches a tree check.
+// The patterns are assembled from fragments (joined) so that this file never spells a marker itself.
+import { langOf, lexSource, splitLines } from './js-lex.mjs';
+
 const join = (...parts) => parts.join('');
-const COMMENT_OPEN = /\/\/|\/\*/g;
 
 const SUPPRESSION_WORDS = [
   join('eslint', '-disable'), join('stylelint', '-disable'), join('tslint', ':disable'), join('prettier', '-ignore'), join('biome', '-ignore'),
-  join('@ts', '-ignore'), join('@ts', '-expect-error'), join('@ts', '-nocheck'), join('NO', 'SONAR'),
-  join('istanbul', ' ignore'), join('c8', ' ignore'), join('v8', ' ignore'), join('jscpd', ':ignore'),
+  join('@ts', '-ignore'), join('@ts', '-expect-error'), join('@ts', '-nocheck'),
+  join('istanbul', ' ignore'), join('c8', ' ignore'), join('v8', ' ignore'), join('jscpd', ':ignore'), join('eslint', '-env'),
 ];
 const escaped = (word) => word.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
-const COMMENT_MARKER = new RegExp(`(${SUPPRESSION_WORDS.map(escaped).join('|')})`);
+/** A suppression directive opens its comment: after the opener only blanks and asterisks may precede it. */
+const DIRECTIVE = new RegExp(String.raw`^[\s*/]*(${SUPPRESSION_WORDS.map(escaped).join('|')})`);
+/** Inline configuration ESLint honours at the start of a comment: a rule level, declared globals or exports. */
+const INLINE_CONFIG = new RegExp(String.raw`^[\s*/]*(${join('eslint')}\s+[@\w/.-]+\s*:|globals?\s|exported\b)`);
+/** The type-check escapes: TypeScript reads them on the last line of a block comment too. */
+const TYPE_ESCAPES = SUPPRESSION_WORDS.filter((word) => word.startsWith('@ts'));
+/** Sonar reads its exclusion word anywhere in a comment. */
+const SONAR_WORD = join('NO', 'SONAR');
 
-const TEST_MARKERS = [
-  [new RegExp(String.raw`\b(?:it|test|describe|suite|context)\.(?:skip|only|todo|failing)\b`), 'a skipped or focused test'],
+const RUNNER = '(?:it|test|describe|suite)';
+const ANYWHERE_TESTS = [
+  [new RegExp(String.raw`\b${RUNNER}(?:\.\w+)*\.(?:skip|only|todo|failing)\b`), 'a skipped or focused test'],
+  [new RegExp(String.raw`\b${RUNNER}(?:\.\w+)*\.(?:skipIf|runIf)\(`), 'a conditionally skipped test'],
+  [new RegExp(String.raw`\{[^}]*\b(?:skip|only|todo)\b[^}]*\}\s*=\s*${RUNNER}\b`), 'a skip taken from the test runner'],
+];
+/** Names that are ordinary identifiers outside a test file: read only in a spec or test file. */
+const SPEC_TESTS = [
   [new RegExp(String.raw`\b(?:xit|xtest|xdescribe|fit|fdescribe)\(`), 'a skipped or focused test'],
-  [new RegExp(String.raw`\.skipIf\(|\.runIf\(`), 'a conditionally skipped test'],
-  [new RegExp(String.raw`\bskip\s*:\s*(?!false\b)\S`), 'a skip option'],
+  [new RegExp(String.raw`\b(?:skip|todo)\s*:\s*(?!false\b|\d|\[)\S|\bonly\s*:\s*true\b`), 'a skip option'],
+  [new RegExp(String.raw`\.\s*(?:skip|todo)\s*\(`), 'a skipped test through its context'],
   [new RegExp(String.raw`\bpending\(\)`), 'a pending test'],
 ];
+const TEST_KEYS = new Set(['skip', 'only', 'todo', 'failing']);
+
+const CHILD = '(?:execSync|spawnSync|execFileSync)';
+/** Exit codes that a script resets or a helper swallows (scripts, hooks and tools; never specs). */
+const EXIT_PATTERNS = [
+  [new RegExp(String.raw`\btry\s*\{[^{}]*\b${CHILD}\b[^{}]*\}\s*catch\s*(?:\(\s*\w*\s*\))?\s*\{\s*\}`), 'a child failure swallowed by an empty catch'],
+  [new RegExp(String.raw`\b${CHILD}\([^;]*\);\s*process\.exit\(\s*0\s*\)`), 'an exit 0 right after a child whose status is never read'],
+];
+const EXIT_EVENTS = new Set(['exit', 'uncaughtException', 'unhandledRejection']);
+const EXIT_ZERO = /exitCode\s*=\s*0|exit\(\s*0\s*\)/;
+
+/** The text after the `=>` of a handler argument that follows the event name (`, () => ...`), or null when it is not one. */
+function arrowBody(after) {
+  const text = after.trimStart();
+  const arrow = text.indexOf('=>');
+  return text.startsWith(',') && arrow > 0 && arrow < 60 ? text.slice(arrow + 2).trimStart() : null;
+}
+
+/** Whether the handler that starts at `after` (what follows the event name) is empty, resets the exit code or exits 0. */
+function resetsExit(after) {
+  const body = arrowBody(after);
+  if (body === null) return false;
+  if (!body.startsWith('{')) return EXIT_ZERO.test(body.slice(0, 40));
+  const inner = body.slice(1, Math.max(1, body.indexOf('}')));
+  return inner.trim() === '' || EXIT_ZERO.test(inner);
+}
+
+/** Whether a line commits with a short flag group that holds n, which skips the hooks (`-n`, `-nm`, `-an`). */
+function commitsWithShortSkip(line) {
+  const words = line.split(/\s+/);
+  const at = words.indexOf('commit');
+  return words.includes('git') && at >= 0 && words.slice(at + 1).some((word) => /^-[a-zA-Z]+$/.test(word) && word.includes('n'));
+}
 
 const SWALLOW = [
-  [/\|\|\s*(?:true|:)(?![\w-])/, 'a failure swallowed with `|| true`'],
+  [/\|\|\s*(?:true\b|:|"true"|'true'|\/(?:usr\/)?bin\/true|exit\s+0\b|return\s+0\b|echo\b|printf\b)/, 'a failure swallowed with or-true'],
+  [/;\s*(?:true\b(?!\s*[,:(.=])|:\s*$)/, 'a failure swallowed with semicolon-true'],
   [/\bcontinue-on-error\s*:\s*(?!false\b)\S/, join('continue', '-on-error')],
-  [/\bset\s+\+e\b/, 'set +e'],
-  [/\bHUSKY\s*=\s*0\b/, 'HUSKY=0'],
+  [/\bset\s+\+[a-z]*e/, join('set ', '+e')],
+  [/\bset\s+\+o\s+errexit\b/, join('set ', '+o errexit')],
+  [/\btrap\s+['"]?exit\s+0/, join('trap ', 'exit 0')],
+  [/\bHUSKY\s*=\s*0\b/, join('HUSKY', '=0')],
   [/--no-verify\b/, '--no-verify'],
+  [{ test: commitsWithShortSkip }, join('git commit ', '-n')],
+  [/-c\s+core\.hooksPath=[/\w]/, join('core.hooks', 'Path redirected')],
   [/\bfail_ci_if_error\s*:\s*false\b/, 'fail_ci_if_error: false'],
-];
-
-// A weakening of the run itself that today's rendered canon still spells in places (the CI template runs jest with it); the runtime
-// detector refuses it as an ADDED line, the product rule waits until the canon is rid of it.
-const PENDING = [
-  [/--passWithNoTests\b/, '--passWithNoTests'],
+  [/--(?:passWithNoTests|pass-with-no-tests)\b/, '--passWithNoTests'],
   [/--coverageThreshold\b/, '--coverageThreshold'],
+  [/--no-error-on-unmatched-pattern\b/, '--no-error-on-unmatched-pattern'],
+  [/--max-warnings(?:\s+|=)(?!0\b)\S/, 'a warning budget'],
+  [/--continue-on-error\b|--keep-going\b/, join('--continue', '-on-error')],
+  [/\beslint\b[^\n|;&]*--quiet\b/, 'eslint --quiet'],
+  [/--(?:rule\s+['"]?[@\w/-]+:\s*(?:off|0)|ignore-pattern|testPathIgnorePatterns)\b/, 'a check narrowed on the command line'],
+  [/-Dsonar\.(?:[\w.]*(?:exclusions|inclusions|sources)\b|qualitygate\.wait=(?!true\b))/, 'a Sonar scope set on the command line'],
+  [/sonar\.qualitygate\.wait\s*=\s*false/, 'a Sonar gate not waited for'],
 ];
+/** The failures a script hands a shell in a string: the commands only, never a flag a message names. */
+const COMMAND_SWALLOW = SWALLOW.filter(([, label]) => /or-true|semicolon-true|set \+|trap exit|HUSKY|git commit -n|Path redirected/.test(label));
+const GIT_VERBS = new Set(['commit', 'push', 'merge', 'rebase', 'cherry-pick', 'am', 'revert']);
+/** A git command line carrying the flag: after the flag only more flags, operators or quoted and variable words follow, never prose. */
+const GIT_COMMAND = /^\s*git\s(?:\S+\s)*?--no-verify(?:\s+(?:-\S*|[&|;>"'$]\S*))*\s*$/;
+const GIT_LINE_WITH_MESSAGE = /^\s*git\s.*--no-verify\b.*\s-m\s/;
 
+/** Workflow lines that make a job or a step not run, or a shell not stop on a failure. */
+const WORKFLOW_PATTERNS = [
+  [/^\s*shell:\s*bash\s*\{0\}/, 'a shell that does not stop on a failure'],
+];
 const CODE_FILE = /\.(?:[cm]?[jt]sx?|vue|svelte|css|scss|less)$/;
-const SHELL_FILE = /(?:^|\/)(?:\.husky\/(?!_\/)[^/]+|[^/]+\.sh|hooks\/husky\/[^/]+)$/;
-const WORKFLOW_FILE = /(?:^|\/)(?:\.github|github)\/(?:workflows|actions)\/.+\.ya?ml$/;
+const SHELL_FILE = /(?:^|\/)(?:\.(?:husky|githooks)\/(?!_\/)[^/]+|[^/]+\.sh|hooks\/husky\/[^/]+)$/;
+const WORKFLOW_FILE = /(?:^|\/)(?:(?:\.github|github)\/(?:workflows|actions)\/.+|ci-workflows(?:-lite)?\/[^/]+|lefthook)\.ya?ml$/;
+const DOCKERFILE = /(?:^|\/)Dockerfile(?:\.[\w-]+)?$/;
 const MANIFEST_FILE = /(?:^|\/)package\.json$/;
-const SKIPPED_TREE = /(?:^|\/)(?:node_modules|dist|coverage|\.next|build)\//;
-const GENERATED_NAME = /(?:^|\/)(?:package-lock\.json|[^/]+\.generated\.[^/]+|[^/]+\.min\.[^/]+)$/;
+const TEST_FILE = /(?:\.(?:spec|test|e2e-spec|integration-spec|contract-spec)\.[cm]?[jt]sx?$|(?:^|\/)(?:__tests__|tests?|e2e)\/)/;
+const SHEBANG = /^#!\s*(?:\/usr\/bin\/env\s+)?\S*(?:sh|bash|zsh|dash)\b/;
+const NAMED_SCRIPT = /\.\w+$/;
 
-/** The kind of text `file` holds for the markers: 'code', 'shell' (hooks, scripts), 'workflow', 'manifest', or null for a file no marker is read in. */
-export function bypassFileKind(file) {
-  if (SKIPPED_TREE.test(file) || GENERATED_NAME.test(file)) return null;
+/** The kind of text `file` holds for the markers: 'code', 'shell' (hooks, scripts), 'workflow', 'dockerfile', 'manifest', or null. `text` lets an extensionless file with a shell shebang count as a script. */
+export function bypassFileKind(file, text = '') {
   if (SHELL_FILE.test(file)) return 'shell';
   if (WORKFLOW_FILE.test(file)) return 'workflow';
+  if (DOCKERFILE.test(file)) return 'dockerfile';
   if (MANIFEST_FILE.test(file)) return 'manifest';
   if (CODE_FILE.test(file)) return 'code';
-  return null;
-}
-
-/** Whether `index` of `line` is outside every quoted string (a marker spelled inside a string is data, not a directive). */
-function outsideQuotes(line, index) {
-  let quote = null;
-  for (let at = 0; at < index; at += 1) {
-    const char = line[at];
-    if (quote) {
-      if (char === '\\') at += 1;
-      else if (char === quote) quote = null;
-    } else if (char === '"' || char === "'" || char === '`') quote = char;
-  }
-  return quote === null;
+  return !NAMED_SCRIPT.test(file.slice(file.lastIndexOf('/') + 1)) && SHEBANG.test(text) ? 'shell' : null;
+}
+
+/** The text of a shell line without the read-only git queries in its `$(...)` and backticks: `|| true` inside one is a query, not a bypass. */
+const QUERY = String.raw`git\s+(?:tag|rev-parse|config|ls-files|describe|log|show|status|branch|remote|diff|symbolic-ref|rev-list)\b[^()\`]*`;
+const withoutSubstitutions = (line) => line.replace(new RegExp(String.raw`\$\(\s*${QUERY}\)`, 'g'), '').replace(new RegExp(String.raw`\`\s*${QUERY}\``, 'g'), '');
+
+const labelsOf = (pairs, text) => pairs.filter(([pattern]) => pattern.test(text)).map(([, label]) => label);
+
+/** The labels of the bypass markers on one `line` of a shell, Dockerfile or workflow file ([] when none). */
+function textLabelsOf(kind, line) {
+  const text = withoutSubstitutions(line);
+  if (/^\s*#/.test(text)) return [];
+  const own = kind === 'workflow' ? WORKFLOW_PATTERNS : [];
+  return [...labelsOf(SWALLOW, text), ...labelsOf(own, text)];
 }
 
-/** The text of a shell line without its `$(...)` and backtick substitutions: `|| true` inside one is a query, not a bypass. */
-const withoutSubstitutions = (line) => line.replace(/\$\([^()]*\)/g, '').replace(/`[^`]*`/g, '');
+const CONSTANT_FALSE = /^\s*(?:-\s+)?if:\s*(?:\$\{\{\s*)?false\b/;
+const CHECK_STEP = /(?:run|uses|name):[^\n]*(?:test|lint|check|audit|tsc|coverage|sonar|codecov|jest|eslint|stylelint|prettier|verify|scan)/i;
 
-const hitsOf = (pairs, line) => pairs.filter(([pattern]) => pattern.test(line)).map(([, label]) => label);
+/** A job or a check step of a workflow that a constant false condition keeps from running (a setup step disabled for an app without build values is none). */
+function disabledHits(text) {
+  const lines = text.split('\n');
+  const hits = [];
+  lines.forEach((content, index) => {
+    if (!CONSTANT_FALSE.test(content)) return;
+    const indent = content.search(/\S/);
+    const label = 'a constant false condition';
+    if (indent === 4) { hits.push({ line: index + 1, label, text: content.trim() }); return; }
+    let start = index;
+    while (start > 0 && !/^\s*-\s/.test(lines[start]) && lines[start].search(/\S/) >= indent) start -= 1;
+    let end = index + 1;
+    while (end < lines.length && (lines[end].trim() === '' || lines[end].search(/\S/) >= indent) && !/^\s*-\s/.test(lines[end])) end += 1;
+    if (CHECK_STEP.test(lines.slice(start, end).join('\n'))) hits.push({ line: index + 1, label, text: content.trim() });
+  });
+  return hits;
+}
+
+/** A job-level `if: always()` of a workflow that never reads a result of the jobs it needs. */
+function alwaysHits(text) {
+  const reads = /needs\.[\w-]+\.result|needs\.\*|toJSON\(needs\)/.test(text);
+  return text.split('\n').flatMap((content, index) => (/^ {4}if:\s*(?:\$\{\{\s*)?always\(\)/.test(content) && !reads
+    ? [{ line: index + 1, label: 'always() without reading the results of the needed jobs', text: content.trim() }] : []));
+}
 
-function commentHit(line) {
-  for (const open of line.matchAll(COMMENT_OPEN)) {
-    if (!outsideQuotes(line, open.index)) continue;
-    const marker = COMMENT_MARKER.exec(line.slice(open.index));
-    if (marker) return marker[1];
+/** The directive a comment line is, or null: a suppression word opens its comment; the Sonar word may stand anywhere in one. */
+function commentDirective(comment, opening) {
+  const inline = comment.block ? INLINE_CONFIG.exec(comment.text)?.[1]?.trim() : undefined;
+  const open = opening ? (DIRECTIVE.exec(comment.text)?.[1] ?? inline) : null;
+  const closing = comment.last ? TYPE_ESCAPES.find((word) => comment.text.replace(/^[\s*]+/, '').startsWith(word)) : null;
+  return open ?? closing ?? (comment.text.includes(SONAR_WORD) ? SONAR_WORD : null);
+}
+
+/** The comments with the line a directive may open: the first non-blank line of each comment. */
+function commentHits(comments) {
+  let waiting = false;
+  return comments.flatMap((comment) => {
+    if (comment.first) waiting = true;
+    const opening = waiting && comment.text.trim() !== '';
+    if (opening) waiting = false;
+    const directive = commentDirective(comment, opening);
+    return directive ? [{ line: comment.line, label: directive, text: comment.text.trim() }] : [];
+  });
+}
+
+const OPENERS = '([{';
+const CLOSERS = ')]}';
+
+/** The index of the bracket that encloses `at` in the blanked `code` (walking back, skipping balanced pairs), or -1. */
+function enclosingOpen(code, at) {
+  let depth = 0;
+  for (let index = at; index >= 0; index -= 1) {
+    if (CLOSERS.includes(code[index])) depth += 1;
+    else if (OPENERS.includes(code[index]) && depth === 0) return index;
+    else if (OPENERS.includes(code[index])) depth -= 1;
   }
-  return null;
-}
-
-/** The labels of the bypass markers on one `line` of a file of `kind` ([] when none). `pending` also reads the markers the canon still spells. */
-export function bypassLabelsOf(kind, line, { pending = false } = {}) {
-  if (kind === 'code') {
-    const comment = commentHit(line);
-    const tests = TEST_MARKERS.filter(([pattern]) => {
-      const hit = pattern.exec(line);
-      return hit && outsideQuotes(line, hit.index);
-    }).map(([, label]) => label);
-    return [...(comment ? [comment] : []), ...tests];
+  return -1;
+}
+
+/** The index of the `]` that closes the `[` at `open`, or -1. */
+function closingBracket(code, open) {
+  let depth = 0;
+  for (let index = open + 1; index < code.length; index += 1) {
+    if (code[index] === '[') depth += 1;
+    else if (code[index] === ']' && depth === 0) return index;
+    else if (code[index] === ']') depth -= 1;
   }
-  if (kind === 'shell' || kind === 'workflow' || kind === 'manifest') {
-    const text = withoutSubstitutions(line);
-    if (kind === 'manifest' && !/"[^"]+"\s*:\s*"/.test(line)) return [];
-    if (/^\s*#/.test(text)) return [];
-    return [...hitsOf(SWALLOW, text), ...(pending ? hitsOf(PENDING, text) : [])];
+  return -1;
+}
+
+/** The offsets of the brackets of the array that holds `at` in the blanked `code`, or null when no array does. */
+function arrayAround(code, at) {
+  const open = enclosingOpen(code, at);
+  if (open < 0 || code[open] !== '[') return null;
+  const close = closingBracket(code, open);
+  return close < 0 ? null : [open, close];
+}
+
+/** Whether the string `piece` hands git the hook-skipping flag: a git command line, or an element of an array that also names a git verb. */
+function skipsHooks(piece, code, strings) {
+  if (GIT_COMMAND.test(piece.text) || GIT_LINE_WITH_MESSAGE.test(piece.text)) return true;
+  if (piece.text.trim() !== '--no-verify') return false;
+  const around = arrayAround(code, piece.at);
+  return around !== null && strings.some((other) => other.at > around[0] && other.at < around[1] && GIT_VERBS.has(other.text));
+}
+
+/** A test marker spelled as an index (`describe['skip']`): a string equal to a marker right after a `[`. */
+const indexedMarker = (piece, code) => TEST_KEYS.has(piece.text) && code.slice(0, piece.at).trimEnd().endsWith('[');
+
+/** An `exit` handler of the process that resets the exit code or swallows the failure. */
+function exitHandler(piece, code) {
+  if (!EXIT_EVENTS.has(piece.text)) return false;
+  const before = code.slice(Math.max(0, piece.at - 24), piece.at);
+  return /process\s*\.\s*(?:on|once)\(\s*['"]?$/.test(before) && resetsExit(code.slice(piece.at + piece.text.length + 1, piece.at + piece.text.length + 200));
+}
+
+function stringHits(strings, code) {
+  const hits = [];
+  for (const piece of strings) {
+    piece.text.split('\n').forEach((content, offset) => {
+      for (const label of labelsOf(COMMAND_SWALLOW, withoutSubstitutions(content))) hits.push({ line: piece.line + offset, label, text: content.trim() });
+    });
+    if (skipsHooks(piece, code, strings)) hits.push({ line: piece.line, label: '--no-verify', text: piece.text.trim() });
+    if (/\bHUSKY\b/.test(code.slice(Math.max(0, piece.at - 12), piece.at)) && /^["']?0$/.test(piece.text.trim())) hits.push({ line: piece.line, label: join('HUSKY', '=0'), text: piece.text });
+  }
+  return hits;
+}
+
+/** The exit patterns of a script, matched over the whole code (a try block and the call that follows it span lines). */
+function exitHits(code, sourceLines) {
+  return EXIT_PATTERNS.flatMap(([pattern, label]) => [...code.matchAll(new RegExp(pattern.source, 'g'))].map((match) => {
+    const line = splitLines(code.slice(0, match.index)).length;
+    return { line, label, text: (sourceLines[line - 1] ?? '').trim() };
+  }));
+}
+
+function codeHits(file, text) {
+  const { code, comments, strings } = lexSource(text, langOf(file));
+  const sourceLines = splitLines(text);
+  const spec = TEST_FILE.test(file);
+  const hits = commentHits(comments);
+  const tests = spec ? [...ANYWHERE_TESTS, ...SPEC_TESTS] : ANYWHERE_TESTS.slice(0, 2);
+  splitLines(code).forEach((content, index) => {
+    for (const label of labelsOf(tests, content)) hits.push({ line: index + 1, label, text: (sourceLines[index] ?? '').trim() });
+  });
+  if (!spec) hits.push(...exitHits(code, sourceLines));
+  for (const piece of strings) {
+    if (spec && indexedMarker(piece, code)) hits.push({ line: piece.line, label: 'a skipped or focused test', text: piece.text });
+    if (!spec && exitHandler(piece, code)) hits.push({ line: piece.line, label: 'a process exit handler that resets the exit code', text: piece.text });
   }
-  return [];
+  const seen = new Set();
+  return [...hits, ...stringHits(strings, code)].sort((x, y) => x.line - y.line).filter((hit) => !seen.has(hit.line) && seen.add(hit.line));
+}
+
+/** package.json: every command a shell runs (scripts, lint-staged, husky, simple-git-hooks) and a tool config kept outside its own file. */
+const COMMAND_KEYS = ['scripts', 'lint-staged', 'husky', 'simple-git-hooks'];
+const TOOL_BLOCKS = ['jest', 'eslintConfig', 'stylelint'];
+
+function commandStrings(value, name) {
+  if (typeof value === 'string') return [[name, value]];
+  if (value === null || typeof value !== 'object') return [];
+  return Object.entries(value).flatMap(([key, inner]) => commandStrings(inner, Array.isArray(value) ? name : key));
+}
+
+function manifestHits(text) {
+  let doc;
+  try { doc = JSON.parse(text); } catch { return []; }
+  const lines = text.split('\n');
+  const lineOf = (name) => lines.findIndex((line) => line.includes(JSON.stringify(name))) + 1;
+  const commands = COMMAND_KEYS.flatMap((key) => commandStrings(doc?.[key], key));
+  const hits = commands.flatMap(([name, command]) => labelsOf(SWALLOW, withoutSubstitutions(command)).map((label) => ({ line: lineOf(name), label, text: command.trim() })));
+  const blocks = TOOL_BLOCKS.filter((key) => doc?.[key] !== undefined).map((key) => ({ line: lineOf(key), label: `a ${key} config kept in package.json`, text: key }));
+  return [...hits, ...blocks];
 }
 
 /**
  * Every bypass marker of the text of one file: [{line, label, text}] (line numbers from 1). The file's kind decides the patterns;
  * a file of no kind has none.
  */
-export function bypassesIn(file, text, options = {}) {
-  const kind = bypassFileKind(file);
+export function bypassesIn(file, text) {
+  const kind = bypassFileKind(file, text);
   if (!kind || typeof text !== 'string') return [];
-  return text.split(/\r?\n/).flatMap((content, index) => bypassLabelsOf(kind, content, options).map((label) => ({ line: index + 1, label, text: content.trim() })));
+  if (kind === 'code') return codeHits(file, text);
+  if (kind === 'manifest') return manifestHits(text);
+  const hits = text.split(/\r?\n/).flatMap((content, index) => textLabelsOf(kind, content).map((label) => ({ line: index + 1, label, text: content.trim() })));
+  return kind === 'workflow' ? [...hits, ...alwaysHits(text), ...disabledHits(text)] : hits;
 }

package/runtime/scripts/lib/check-format.mjs

@@ -0,0 +1,7 @@
+// check-format.mjs — the one-line-per-check report every canon check CLI shares.
+
+const MARK = { pass: 'pass', fail: 'FAIL', skip: 'skip' };
+
+/** `header` plus one '  [outcome] id: detail' line per check of `checks`, joined with '\n'. */
+export const formatCheckLines = (header, checks) =>
+  [header, ...(checks ?? []).map((entry) => `  [${MARK[entry.outcome]}] ${entry.id}: ${entry.detail}`)].join('\n');