@starci/eslint-grammar-offset-pop 0.12.13 → 0.13.0

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -0,0 +1,362 @@
+// rule-catalog.mjs - the parsed and validated HFS rule catalog.
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYamlCached } from '../lib/yaml-cached.mjs';
+import { jsonClone } from '../lib/json-clone.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { SEMVER } from './manifest-shape.mjs';
+import { enforcerJudgedInEdition, judgedInEdition, ruleEditionProblems } from './edition-slots.mjs';
+import { fail } from './slot-errors.mjs';
+
+const HFS_RULES_FILE = 'knowledge/hfs/rules.yaml';
+const RULE_GATES = Object.freeze(['pre-commit', 'pre-push', 'settle', 'land', 'ci', 'sonar', 'runtime']);
+const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'eslint-grammar-core', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
+const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
+const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
+const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const FILE_ENFORCERS = new Set(['machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
+/**
+ * The enforcer kinds that run only inside the StarCi runtime repository (`starci runtime check`, `starci work`): no published package carries
+ * them, so no package spec can hold them (owner ruling no-runtime-specs: the runtime has no specs of its own; the package clean-test and the
+ * scaffold e2e are its tests), and no example app is a product they judge. A rule is runtime-judged when every enforcer it has is of these kinds.
+ */
+export const RUNTIME_ONLY_ENFORCERS = Object.freeze(['work-validate', 'runtime']);
+const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'failureCodes', 'editions', 'codeEditions', 'enforcers', 'cases', 'docs', 'exemplifiedBy', 'proves', 'witness', 'editionWhy', 'amendedBy', 'templateNa']);
+const CASE_KEYS = new Set(['id', 'date', 'source', 'ruling', 'quote', 'supersedes', 'status', 'staleWhen', 'amendedBy']);
+const CASE_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const ENFORCER_KEYS = new Set(['kind', 'id', 'status', 'at', 'editions', 'editionWhy']);
+const CASE_ID = /case-[1-9]\d*/;
+const RULING_REFERENCE = new RegExp(String.raw`(?:ruling:)?R\d{2,3}(?:/${CASE_ID.source})?`);
+const OWNER_REFERENCE = /owner:[a-z][a-z0-9]*(?:-[a-z0-9]+)*/;
+const CASE_REFERENCE = new RegExp(`^(?:${CASE_ID.source}|${RULING_REFERENCE.source}|${OWNER_REFERENCE.source})$`);
+const EVIDENCE_KEYS = new Set(['path', 'edition', 'editions']);
+const PROOF_KEYS = new Set([...EVIDENCE_KEYS, 'codes', 'fixtures']);
+const WITNESS_KEYS = new Set(['edition', 'base', 'mutate', 'expect']);
+const MUTATION_KEYS = new Set(['op', 'path', 'content']);
+
+function textProblem(value, label, bad) {
+  if (typeof value !== 'string' || !value.trim()) bad.push(`${label} must be non-empty text`);
+}
+
+function dateProblem(value, label, bad) {
+  const date = typeof value === 'string' && CASE_DATE.test(value) ? new Date(`${value}T00:00:00Z`) : null;
+  if (!date || !Number.isFinite(date.getTime()) || date.toISOString() !== `${value}T00:00:00.000Z`) bad.push(`${label} must be a valid YYYY-MM-DD date`);
+}
+
+function relativePathProblem(value, label, bad, anchor = false) {
+  const parts = typeof value === 'string' ? value.split('#') : [];
+  const file = parts[0];
+  const valid = typeof value === 'string' && value.trim() === value && value.length > 0
+    && !value.includes('\0') && !/[\r\n\\]/.test(value) && !/^(?:\/|[a-z][a-z0-9+.-]*:)/i.test(value) && !file.includes(':')
+    && !file.split('/').some((part) => ['', '.', '..'].includes(part))
+    && (parts.length === 1 || (anchor && parts.length === 2 && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(parts[1])));
+  if (!valid) bad.push(`${label} must be a repository-relative path${anchor ? ' with an optional #anchor' : ''}`);
+}
+
+function unknownKeys(item, allowed, label, bad) {
+  for (const key of Object.keys(item)) if (!allowed.has(key)) bad.push(`${label} has unknown key ${key}`);
+}
+
+function nonEmptyList(value, label, bad) {
+  if (!Array.isArray(value) || !value.length) { bad.push(`${label} must be a non-empty list`); return false; }
+  const normalized = value.map((value) => JSON.stringify(value, (_key, item) => isPlainObject(item) ? Object.fromEntries(Object.keys(item).sort(byCodeUnit).map((key) => [key, item[key]])) : item));
+  if (new Set(normalized).size !== value.length) bad.push(`${label} repeats a value`);
+  return true;
+}
+
+function optionalText(item, key, label, bad) {
+  if (item[key] !== undefined) textProblem(item[key], `${label}.${key}`, bad);
+}
+
+function evidenceEditionProblems(item, label, bad) {
+  if (item.edition !== undefined && !['full', 'lite'].includes(item.edition)) bad.push(`${label}.edition must be full or lite`);
+  bad.push(...ruleEditionProblems(item, label));
+  if (item.edition !== undefined && item.editions !== undefined) bad.push(`${label} names edition or editions, not both`);
+}
+
+function codeListProblems(codes, label, bad) {
+  if (!nonEmptyList(codes, label, bad)) return;
+  for (const code of codes) if (typeof code !== 'string' || !FINDING_CODE.test(code)) bad.push(`${label} must contain UPPER_SNAKE finding codes`);
+}
+
+function evidenceMapProblems(item, key, label, bad) {
+  unknownKeys(item, key === 'docs' ? EVIDENCE_KEYS : PROOF_KEYS, label, bad);
+  relativePathProblem(item.path, `${label}.path`, bad, key === 'docs');
+  evidenceEditionProblems(item, label, bad);
+  if (item.codes !== undefined) codeListProblems(item.codes, `${label}.codes`, bad);
+  if (item.fixtures !== undefined && nonEmptyList(item.fixtures, `${label}.fixtures`, bad)) item.fixtures.forEach((value) => textProblem(value, `${label}.fixtures`, bad));
+}
+
+function evidenceProblems(rule, key, label, bad) {
+  if (rule[key] === undefined || !nonEmptyList(rule[key], `${label}.${key}`, bad)) return;
+  rule[key].forEach((item, index) => {
+    const at = `${label}.${key}[${index}]`;
+    if (typeof item === 'string') { relativePathProblem(item, at, bad, key === 'docs'); return; }
+    if (!isPlainObject(item)) { bad.push(`${at} must be a path or a map`); return; }
+    evidenceMapProblems(item, key, at, bad);
+  });
+}
+
+function mutationProblems(item, label, bad) {
+  if (!isPlainObject(item)) { bad.push(`${label} must be a map`); return; }
+  unknownKeys(item, MUTATION_KEYS, label, bad);
+  if (!['add', 'edit', 'delete'].includes(item.op)) bad.push(`${label}.op must be add, edit or delete`);
+  relativePathProblem(item.path, `${label}.path`, bad);
+  if (['add', 'edit'].includes(item.op) && typeof item.content !== 'string') bad.push(`${label}.content must be text for add or edit`);
+  if (item.op === 'delete' && item.content !== undefined) bad.push(`${label}.content is absent for delete`);
+}
+
+function witnessEntryProblems(item, label, bad) {
+  if (!isPlainObject(item)) { bad.push(`${label} must be a map`); return; }
+  if (Object.hasOwn(item, 'path')) { evidenceMapProblems(item, 'proves', label, bad); return; }
+  unknownKeys(item, WITNESS_KEYS, label, bad);
+  if (!['full', 'lite'].includes(item.edition)) bad.push(`${label}.edition must be full or lite`);
+  relativePathProblem(item.base, `${label}.base`, bad);
+  codeListProblems(item.expect, `${label}.expect`, bad);
+  if (nonEmptyList(item.mutate, `${label}.mutate`, bad)) item.mutate.forEach((mutation, index) => mutationProblems(mutation, `${label}.mutate[${index}]`, bad));
+}
+
+function witnessProblems(rule, label, bad) {
+  const value = rule.witness;
+  if (value === undefined) return;
+  const at = `${label}.witness`;
+  if (!nonEmptyList(value, at, bad)) return;
+  value.forEach((item, index) => witnessEntryProblems(item, `${at}[${index}]`, bad));
+}
+
+function caseReferenceProblems(value, label, bad) {
+  const values = Array.isArray(value) ? value : [value];
+  if (!nonEmptyList(values, label, bad)) return;
+  for (const ref of values) if (typeof ref !== 'string' || !CASE_REFERENCE.test(ref)) bad.push(`${label} must name case-N, R<id>[/case-N], ruling:R<id>[/case-N] or owner:<id>`);
+}
+
+function caseTransitionProblems(item, label, bad) {
+  if (item.status !== undefined && !['live', 'superseded', 'amended'].includes(item.status)) bad.push(`${label}.status must be live, superseded or amended`);
+  for (const key of ['supersedes', 'amendedBy']) if (item[key] !== undefined) caseReferenceProblems(item[key], `${label}.${key}`, bad);
+  if (item.staleWhen !== undefined && nonEmptyList(item.staleWhen, `${label}.staleWhen`, bad)) {
+    for (const pattern of item.staleWhen) {
+      if (typeof pattern !== 'string' || !pattern.trim()) { bad.push(`${label}.staleWhen must contain non-empty regex strings`); continue; }
+      try { new RegExp(pattern, 'i'); } catch { bad.push(`${label}.staleWhen has an invalid regex ${JSON.stringify(pattern)}`); }
+    }
+  }
+}
+
+function vocabularyProblems(catalog, key, names, bad) {
+  if (!isPlainObject(catalog[key])) { bad.push(`${key} must be a map`); return; }
+  if (JSON.stringify(Object.keys(catalog[key])) !== JSON.stringify(names)) bad.push(`${key} must list exactly ${names.join(', ')} in that order`);
+  for (const [name, text] of Object.entries(catalog[key])) {
+    if (typeof text !== 'string' || !text.trim()) bad.push(`${key}.${name} needs a description`);
+  }
+}
+
+function checkCatalogHeader(catalog, bad) {
+  for (const key of Object.keys(catalog)) {
+    if (!['schema', 'version', 'gates', 'enforcerKinds', 'rules'].includes(key)) bad.push(`unknown top-level key ${key}`);
+  }
+  const schemaOk = /^starci\/hfs-rules@\d+$/.test(String(catalog.schema));
+  if (!schemaOk) bad.push('schema must be starci/hfs-rules@<major>');
+  if (!SEMVER.test(String(catalog.version))) bad.push('version must be MAJOR.MINOR.PATCH');
+  else if (schemaOk && catalog.schema.split('@')[1] !== catalog.version.split('.')[0]) bad.push('the major of version must equal the number after @ in schema');
+  vocabularyProblems(catalog, 'gates', RULE_GATES, bad);
+  vocabularyProblems(catalog, 'enforcerKinds', ENFORCER_FAMILIES, bad);
+}
+
+function enumListProblems(rule, label, key, allowed, bad) {
+  if (!Array.isArray(rule[key]) || !rule[key].length) { bad.push(`${label}.${key} must be a non-empty list`); return []; }
+  for (const value of rule[key]) {
+    if (!allowed.includes(value)) bad.push(`${label}.${key} has ${JSON.stringify(value)}, not one of ${allowed.join(', ')}`);
+  }
+  if (new Set(rule[key]).size !== rule[key].length) bad.push(`${label}.${key} repeats a value`);
+  return rule[key];
+}
+
+function checkRuleIdentity(rule, index, catalog, at, label, bad) {
+  if (!/^R\d{2,3}$/.test(String(rule.id))) bad.push(`${at}.id must be R<two or three digits>`);
+  else if (index > 0 && typeof catalog.rules[index - 1]?.id === 'string' && Number(rule.id.slice(1)) <= Number(catalog.rules[index - 1].id.slice(1))) bad.push(`${label} is out of order: ids must increase, and ${catalog.rules[index - 1].id} comes before it`);
+  if (!FINDING_CODE.test(String(rule.code))) bad.push(`${label}.code must be an UPPER_SNAKE finding code`);
+}
+
+function checkRuleText(rule, label, bad) {
+  if (typeof rule.law !== 'string' || !rule.law.trim()) bad.push(`${label}.law is missing`);
+  if (typeof rule.law === 'string' && rule.law.includes('\n')) bad.push(`${label}.law must be one line`);
+  if (rule.scope !== undefined && rule.scope !== 'runtime') bad.push(`${label}.scope is absent or runtime`);
+}
+
+/** The dated owner cases of a rule: each {id case-N, date, source owner, ruling, quote?}, ids unique (an owner ruling recorded where the law lives). */
+function checkRuleCases(rule, label, bad) {
+  if (rule.cases === undefined) return;
+  if (!Array.isArray(rule.cases) || !rule.cases.length) { bad.push(`${label}.cases must be a non-empty list`); return; }
+  const ids = new Set();
+  rule.cases.forEach((item, index) => {
+    const at = `${label}.cases[${index}]`;
+    if (!isPlainObject(item)) { bad.push(`${at} is not a map`); return; }
+    for (const key of Object.keys(item)) if (!CASE_KEYS.has(key)) bad.push(`${at} has unknown key ${key}`);
+    if (typeof item.id !== 'string' || !/^case-[1-9]\d*$/.test(item.id) || ids.has(item.id)) bad.push(`${at}.id must be a unique case-N`);
+    ids.add(item.id);
+    if (typeof item.date !== 'string' || !CASE_DATE.test(item.date)) bad.push(`${at}.date must be YYYY-MM-DD`);
+    if (item.source !== 'owner') bad.push(`${at}.source must be owner`);
+    for (const key of ['ruling', ...(item.quote === undefined ? [] : ['quote'])]) if (typeof item[key] !== 'string' || !item[key].trim()) bad.push(`${at}.${key} must be text`);
+    caseTransitionProblems(item, at, bad);
+  });
+}
+
+function checkRuleGates(rule, label, gates, bad) {
+  if (!gates.length) return;
+  const releaseGate = gates.includes('land') || gates.includes('ci');
+  const runtimeGate = rule.scope === 'runtime' && gates.includes('runtime');
+  if (!releaseGate && !runtimeGate) bad.push(`${label} must run at land or ci or, for runtime scope, the runtime gate`);
+}
+
+function checkRuleFailureCodes(rule, label, codeOwner, bad) {
+  if (!Array.isArray(rule.failureCodes) || !rule.failureCodes.length || !rule.failureCodes.every((code) => FINDING_CODE.test(String(code)))) {
+    bad.push(`${label}.failureCodes must be a non-empty list of UPPER_SNAKE codes`);
+    return;
+  }
+  if (rule.failureCodes[0] !== rule.code) bad.push(`${label}.failureCodes must start with the rule's own code ${rule.code}`);
+  if (new Set(rule.failureCodes).size !== rule.failureCodes.length) bad.push(`${label}.failureCodes repeats a code`);
+  for (const code of rule.failureCodes) {
+    if (codeOwner.has(code) && codeOwner.get(code) !== label) bad.push(`${label} names ${code}, which ${codeOwner.get(code)} already owns`);
+    codeOwner.set(code, label);
+  }
+}
+
+function checkCodeEditions(rule, label, bad) {
+  const value = rule.codeEditions;
+  if (value === undefined) return;
+  if (!isPlainObject(value) || !Object.keys(value).length) { bad.push(`${label}.codeEditions must be a non-empty map`); return; }
+  const editions = Array.isArray(rule.editions) ? rule.editions : ['full', 'lite'];
+  for (const [code, selected] of Object.entries(value)) {
+    const at = `${label}.codeEditions.${code}`;
+    if (!Array.isArray(rule.failureCodes) || !rule.failureCodes.includes(code)) bad.push(`${at} must name a code owned by this rule`);
+    enumListProblems({ editions: selected }, at, 'editions', ['full', 'lite'], bad);
+    if (Array.isArray(selected) && selected.some((edition) => !editions.includes(edition))) bad.push(`${at} must be a subset of the rule's editions`);
+  }
+}
+
+function checkEnforcerIdentity(enforcer, label, seen, bad) {
+  if (!ENFORCER_FAMILIES.includes(enforcer.kind)) bad.push(`${label}.kind must be one of ${ENFORCER_FAMILIES.join(', ')}`);
+  if (!ENFORCER_ID.test(String(enforcer.id))) bad.push(`${label}.id must be kebab-case`);
+  if (seen.has(`${enforcer.kind}:${enforcer.id}`)) bad.push(`${label} repeats ${enforcer.kind}:${enforcer.id}`);
+  seen.add(`${enforcer.kind}:${enforcer.id}`);
+}
+
+function checkEnforcerLocation(enforcer, label, bad) {
+  if (enforcer.at !== undefined) {
+    if (typeof enforcer.at !== 'string' || !enforcer.at.trim() || enforcer.at.startsWith('/') || enforcer.at.includes('..')) bad.push(`${label}.at must be a repository-relative path`);
+    if (enforcer.status === 'planned') bad.push(`${label} is planned, so it has no file yet (at)`);
+    if (!FILE_ENFORCERS.has(enforcer.kind)) bad.push(`${label}.at belongs to a machine, hfs, work-validate, sonar or runtime enforcer only`);
+  } else if (FILE_ENFORCERS.has(enforcer.kind) && enforcer.status !== 'planned') bad.push(`${label} exists, so it names the file (at) that emits its code`);
+}
+
+function checkEnforcer(enforcer, index, ruleLabel, seen, bad) {
+  const label = `${ruleLabel}.enforcers[${index}]`;
+  if (!isPlainObject(enforcer)) { bad.push(`${label} is not a map`); return; }
+  for (const key of Object.keys(enforcer)) {
+    if (!ENFORCER_KEYS.has(key)) bad.push(`${label} has unknown key ${key}`);
+  }
+  bad.push(...ruleEditionProblems(enforcer, label));
+  optionalText(enforcer, 'editionWhy', label, bad);
+  checkEnforcerIdentity(enforcer, label, seen, bad);
+  if (enforcer.status !== undefined && enforcer.status !== 'planned') bad.push(`${label}.status is either absent or planned`);
+  checkEnforcerLocation(enforcer, label, bad);
+}
+
+function checkRuleEnforcers(rule, label, bad) {
+  if (!Array.isArray(rule.enforcers) || !rule.enforcers.length) { bad.push(`${label}.enforcers must name at least one enforcer`); return; }
+  const seen = new Set();
+  rule.enforcers.forEach((enforcer, index) => checkEnforcer(enforcer, index, label, seen, bad));
+}
+
+function checkRule(rule, index, catalog, codeOwner, bad) {
+  const at = `rules[${index}]`;
+  if (!isPlainObject(rule)) { bad.push(`${at} is not a map`); return; }
+  const label = typeof rule.id === 'string' ? rule.id : at;
+  for (const key of Object.keys(rule)) {
+    if (!RULE_KEYS.has(key)) bad.push(`${label} has unknown key ${key}`);
+  }
+  checkRuleIdentity(rule, index, catalog, at, label, bad);
+  checkRuleText(rule, label, bad);
+  checkRuleCases(rule, label, bad);
+  if (rule.amendedBy !== undefined) caseReferenceProblems(rule.amendedBy, `${label}.amendedBy`, bad);
+  optionalText(rule, 'editionWhy', label, bad);
+  optionalText(rule, 'templateNa', label, bad);
+  for (const key of ['docs', 'exemplifiedBy', 'proves']) evidenceProblems(rule, key, label, bad);
+  witnessProblems(rule, label, bad);
+  enumListProblems(rule, label, 'kinds', RULE_KINDS, bad);
+  bad.push(...ruleEditionProblems(rule, label));
+  const gates = enumListProblems(rule, label, 'gates', RULE_GATES, bad);
+  checkRuleGates(rule, label, gates, bad);
+  checkRuleFailureCodes(rule, label, codeOwner, bad);
+  checkCodeEditions(rule, label, bad);
+  checkRuleEnforcers(rule, label, bad);
+  if (Array.isArray(rule.gates)) {
+    const hasSonar = rule.enforcers.some((enforcer) => isPlainObject(enforcer) && enforcer.kind === 'sonar');
+    if (rule.gates.includes('sonar') !== hasSonar) bad.push(`${label}: the sonar gate and a sonar enforcer go together`);
+  }
+}
+
+/** Shape and semantic problems of a parsed knowledge/hfs/rules.yaml, in the words of modules/schemas/hfs-rules.schema.yaml. */
+function ruleCatalogProblems(catalog) {
+  const bad = [];
+  if (!isPlainObject(catalog)) return ['the rule catalog is not a map'];
+  checkCatalogHeader(catalog, bad);
+  if (!Array.isArray(catalog.rules) || !catalog.rules.length) { bad.push('rules must be a non-empty list'); return bad; }
+  const codeOwner = new Map();
+  catalog.rules.forEach((rule, index) => checkRule(rule, index, catalog, codeOwner, bad));
+  return bad;
+}
+
+const deepFreeze = (value) => { if (value && typeof value === 'object') { Object.values(value).forEach(deepFreeze); } return Object.freeze(value); };
+
+/**
+ * The parsed and validated HFS rule catalog. `text` (or `file`, or `root`) selects the source; the default is the runtime's
+ * own knowledge/hfs/rules.yaml. A catalog that breaks its shape or a semantic rule is refused whole (HFS_RULES_INVALID), and
+ * so is one whose major differs from the slot manifest passed as `manifest` (HFS_MANIFEST_MAJOR_MISMATCH).
+ * Answers: rule(id), byCode(code), forGate(gate), forEnforcer(kind, id), planned() and unbuilt().
+ */
+export function loadRuleCatalog({ root = skillRoot, file = path.join(root, HFS_RULES_FILE), text, manifest } = {}) {
+  let doc;
+  try { doc = parseYamlCached(text ?? fs.readFileSync(file, 'utf8')); } catch (error) { fail('HFS_RULES_INVALID', `the rule catalog cannot be read (${String(error?.message ?? error).split('\n')[0]})`, { file }); }
+  const problems = ruleCatalogProblems(doc);
+  if (problems.length) { fail('HFS_RULES_INVALID', `the rule catalog breaks its schema: ${problems.slice(0, 5).join('; ')}${problems.length > 5 ? '; and ' + (problems.length - 5) + ' more' : ''}`, { file, problems }); }
+  const [major, minor, patch] = doc.version.split('.').map(Number);
+  if (manifest && manifest.major !== major) fail('HFS_MANIFEST_MAJOR_MISMATCH', `the rule catalog is major ${major} but the slot manifest is major ${manifest.major}`, { catalog: major, manifest: manifest.major });
+  const list = deepFreeze(doc.rules.map((rule) => ({ ...rule, enforcers: rule.enforcers.map((enforcer) => ({ ...enforcer, planned: enforcer.status === 'planned' })) })));
+  const byId = new Map(list.map((rule) => [rule.id, rule]));
+  const byCode = new Map(list.flatMap((rule) => rule.failureCodes.map((code) => [code, rule])));
+  return Object.freeze({
+    version: doc.version, major, minor, patch,
+    gates: deepFreeze(jsonClone(doc.gates)),
+    enforcerKinds: deepFreeze(jsonClone(doc.enforcerKinds)),
+    rules: list,
+    /** The rule with this id (R01..), or null. */
+    rule: (id) => byId.get(id) ?? null,
+    /** The rule that owns this failure code (its own or a sub-check code), or null. */
+    byCode: (code) => byCode.get(code) ?? null,
+    /** Whether a finding code is judged under `edition`: codeEditions narrows its owner's editions; uncatalogued codes remain judged. */
+    judgedIn: (code, edition = 'full') => {
+      const owner = byCode.get(code);
+      return judgedInEdition(owner, edition) && (!owner?.codeEditions?.[code] || owner.codeEditions[code].includes(edition));
+    },
+    enforcerJudgedIn: (kind, id, edition = 'full') => enforcerJudgedInEdition(list, kind, id, edition),
+    /** The rules that run at a gate. */
+    forGate: (gate) => list.filter((rule) => rule.gates.includes(gate)),
+    /** The catalogued why code of a lint finding's rule id (`starci-be/<id>`, `starci-fe/<id>`), or undefined. */
+    lintCode: (ruleId) => {
+      const [plugin, id] = String(ruleId ?? '').split('/');
+      const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || (plugin === 'starci-grammar' && 'eslint-grammar-core') || null;
+      return kind ? list.find((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id))?.code : undefined;
+    },
+    /** The rules one enforcer judges, e.g. forEnforcer('eslint-be', 'error-home'). */
+    forEnforcer: (kind, id) => list.filter((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id)),
+    /** Every enforcer still owed, as {rule, kind, id}. */
+    planned: () => list.flatMap((rule) => rule.enforcers.filter((enforcer) => enforcer.planned).map((enforcer) => ({ rule: rule.id, kind: enforcer.kind, id: enforcer.id }))),
+    /** The rules with no existing enforcer at all. */
+    unbuilt: () => list.filter((rule) => rule.enforcers.every((enforcer) => enforcer.planned)),
+  });
+}
+
+/** The rules of this runtime's catalog, frozen, in id order. */
+export const rules = (options) => loadRuleCatalog(options).rules;

package/runtime/scripts/hfs/rule-params-shape.mjs

@@ -0,0 +1,80 @@
+// rule-params-shape.mjs - the shape of `ruleParams` of an app slot manifest (knowledge/hfs/slots.yaml): the parameters both sides
+// share (`common`), the back end's own (`be`) and the front end's overrides (`fe`). Pure: a parsed manifest in, a list of
+// problems out, in the words of modules/schemas/hfs-slots.schema.yaml. scripts/hfs/slots.mjs (loadSlotManifest) is the reader.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { paramNamesOk } from './param-names.mjs';
+import { kindParamProblems, scenarioProblem } from './declaration-slots.mjs';
+import { NAME, namedMapValid, PACKAGE_NAME, roleListProblems, SCHEMA_AUTHORITIES, unitRolesProblems } from './manifest-shape.mjs';
+import { byCodeUnit, nonemptyUniqueList } from '../lib/list.mjs';
+import { ruleEditionProblems } from './edition-slots.mjs';
+
+const PROFILES = ['be', 'fe'];
+const BE_OWN = ['infraOwners', 'eventBus', 'specDoubles', 'paramNames', 'suffixes', 'bannedSuffixes', 'contractShape', 'unitRoles', 'logicRoles', 'valueRoles', 'thinRoles', 'patternScenarios', 'kindPatterns', 'addKinds', 'backing'];
+const backingEntryOk = (entry) => isPlainObject(entry) && Object.keys(entry).every((key) => ['clients', 'images', 'patterns', 'editions'].includes(key))
+  && nonemptyUniqueList(entry.clients, (name) => PACKAGE_NAME.test(String(name)))
+  && Array.isArray(entry.patterns) && entry.patterns.every((name) => NAME.test(String(name))) && new Set(entry.patterns).size === entry.patterns.length
+  && nonemptyUniqueList(entry.images, (name) => PACKAGE_NAME.test(String(name)))
+  && ruleEditionProblems(entry, 'backing service').length === 0;
+const FORM_NAMES = new Set(['call', 'new', 'curried', 'object', 'primitive', 'array']);
+const blockOk = (v) => isPlainObject(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
+const fileLinesOk = (v) => isPlainObject(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
+const SHARED_PARAMS = {
+  fileLines: fileLinesOk,
+  duplicateBlock: blockOk,
+  functionLines: v => Number.isInteger(v) && v >= 1,
+  featureFiles: v => Number.isInteger(v) && v >= 1,
+};
+const SHARED_KEYS = Object.keys(SHARED_PARAMS);
+const sharedParam = (key, v) => Object.hasOwn(SHARED_PARAMS, key) && SHARED_PARAMS[key](v);
+const sideOk = (side, own, extra = []) => own.every((k) => side[k] !== undefined) && Object.entries(side).every(([k, v]) => own.includes(k) || extra.includes(k) || sharedParam(k, v));
+const liteKeyOk = (lite, key, keys) => key !== 'lite' && keys.includes(key)
+  && (!['functionLines', 'featureFiles'].includes(key) || sharedParam(key, lite[key]));
+const liteOk = (lite, keys) => lite === undefined || (isPlainObject(lite) && Object.keys(lite).length > 0 && Object.keys(lite).every((k) => liteKeyOk(lite, k, keys)));
+const memberMap = (v, allowEmpty) => isPlainObject(v) && Object.keys(v).length > 0 && Object.values(v).every((list) => Array.isArray(list) && (allowEmpty || list.length > 0) && list.every((x) => /^[A-Z][A-Za-z0-9]*$/.test(String(x))) && new Set(list).size === list.length);
+const roleList = (v) => nonemptyUniqueList(v, (role) => NAME.test(String(role)));
+const formsOk = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => FORM_NAMES.has(x)) && new Set(v).size === v.length;
+const doubleOk = (v) => isPlainObject(v) && /^[A-Za-z][A-Za-z0-9]*$/.test(String(v.double)) && formsOk(v.forms);
+const regexOk = (v) => { try { return typeof v === 'string' && v.length > 0 && Boolean(new RegExp(v)); } catch { return false; } };
+const dbExtensionsOk = (value) => Array.isArray(value) && value.every((name) => typeof name === 'string' && name.length > 0) && new Set(value).size === value.length;
+const SQL_NAME = /^[a-z_][a-z0-9_]*$/;
+const queueOutboxOk = (value) => isPlainObject(value) && Object.keys(value).sort(byCodeUnit).join() === 'columns,table'
+  && typeof value.table === 'string' && value.table.split('.').length === 2 && value.table.split('.').every((part) => SQL_NAME.test(part))
+  && nonemptyUniqueList(value.columns, (column) => SQL_NAME.test(String(column))) && value.columns.includes('queue');
+const DB_PARAMS = { extensions: dbExtensionsOk, queueOutbox: queueOutboxOk };
+const dbParamsOk = (db) => db === undefined || (isPlainObject(db) && Object.entries(db).every(([key, value]) => Object.hasOwn(DB_PARAMS, key) && DB_PARAMS[key](value)));
+
+function beSpecificProblems(be, manifest) {
+  const bad = [];
+  bad.push(...scenarioProblem(be.patternScenarios), ...kindParamProblems(be, manifest.triggerKinds));
+  if (!isPlainObject(be.contractShape) || Object.keys(be.contractShape).length !== 1 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(be.contractShape.helper))) bad.push('ruleParams.be.contractShape must be {helper: <identifier>}');
+  const owners = be.infraOwners;
+  const ownerId = /^(platform|integrations)\/[a-z][a-z0-9-]*$/;
+  if (!isPlainObject(owners) || !Object.keys(owners).length || !Object.entries(owners).every(([key, list]) => key && Array.isArray(list) && list.every((o) => ownerId.test(String(o))) && new Set(list).size === list.length)) bad.push('ruleParams.be.infraOwners must map a non-empty specifier to a list of unique platform/<capability> or integrations/<provider> owners ([] means nowhere)');
+  const eventBus = be.eventBus;
+  if (!isPlainObject(eventBus) || Object.keys(eventBus).sort(byCodeUnit).join() !== 'classes,imports' || !memberMap(eventBus.imports, true) || !memberMap(eventBus.classes, false)) bad.push('ruleParams.be.eventBus must be {imports: {<module>: [unique PascalCase members]}, classes: {<module>: [non-empty unique PascalCase classes]}}');
+  if (!paramNamesOk(be.paramNames)) bad.push('ruleParams.be.paramNames must be a non-empty list of unique {type | typeSuffix, names, nameSuffix?} entries');
+  if (!namedMapValid(be.backing, backingEntryOk)) bad.push('ruleParams.be.backing must map a backing service name to {clients: [unique package names], patterns: [unique pattern names], images: [unique image repositories], editions?: [unique known editions]}');
+  if (!roleList(be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
+  if (!roleList(be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
+  else if (roleList(be.suffixes) && be.suffixes.some((x) => be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
+  const sd = be.specDoubles;
+  if (!isPlainObject(sd) || Object.keys(sd).sort(byCodeUnit).join() !== 'doubles,fallback,kit' || typeof sd.kit !== 'string' || !sd.kit || !Array.isArray(sd.doubles) || !sd.doubles.length || !sd.doubles.every((e) => doubleOk(e) && regexOk(e.token) && (e.from === undefined || regexOk(e.from)) && Object.keys(e).length === (e.from === undefined ? 3 : 4)) || !doubleOk(sd.fallback) || Object.keys(sd.fallback).length !== 2) bad.push('ruleParams.be.specDoubles must be {kit, doubles: [{token: regex, double, forms}], fallback: {double, forms}} with forms drawn from call, new, curried, object, primitive, array');
+  return bad;
+}
+
+/** The shape problems of `m.ruleParams`. */
+export function ruleParamsProblems(m) {
+  const bad = [];
+  const rp = m.ruleParams;
+  if (!isPlainObject(rp) || Object.keys(rp).some((k) => ![...PROFILES, 'common', 'db'].includes(k)) || !isPlainObject(rp.common) || !isPlainObject(rp.be) || (rp.fe !== undefined && !isPlainObject(rp.fe))) return ['ruleParams must be a map with common, be and optionally fe and db'];
+  else {
+    // common holds the parameters both sides share; a side may restate one of them (a valid value) as an override, nothing else.
+    // Edition lite: a side's optional `lite` map overrides keys of the same side (never `lite` itself) when the app declares edition lite.
+    if (!sideOk(rp.common, []) || !fileLinesOk(rp.common.fileLines) || !blockOk(rp.common.duplicateBlock)) bad.push('ruleParams.common needs fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}; optional functionLines and featureFiles must be positive integers');
+    if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !liteOk(rp.be.lite, [...BE_OWN, ...SHARED_KEYS, 'schemaAuthority'])) bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns, addKinds and backing (shared parameters live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + ') and lite (overrides of the same keys)'); else bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
+    bad.push(...beSpecificProblems(rp.be, m));
+    if (rp.fe !== undefined && (!sideOk(rp.fe, [], ['lite']) || !liteOk(rp.fe.lite, SHARED_KEYS))) bad.push('ruleParams.fe may only restate the shared parameters of ruleParams.common, and carry a lite override of them');
+    if (!dbParamsOk(rp.db)) bad.push('ruleParams.db may contain only extensions (a list of unique non-empty extension names) and queueOutbox ({table: <schema>.<table>, columns: [unique column names including queue]})');
+  }
+  return bad;
+}

package/runtime/scripts/hfs/slot-app-view.mjs

@@ -0,0 +1,102 @@
+// slot-app-view.mjs - the resolver of a whole app: a root path is answered by the scope of the app root, a path below a side folder
+// (be/, fe/) by that side's scope with the side prefixed back onto every path and root it returns. Only the declared `reads` cross sides.
+// slots.mjs builds the scopes (`root` and `sides`, each a resolver of one scope) and hands them to appResolver.
+import { APP_SCOPE, PROFILES } from './slot-manifest-shape.mjs';
+import { cleanSlotPath } from './slot-path.mjs';
+
+/** { side, rest } when `p` lies below a side folder, else null. */
+function splitSide(input) {
+  const p = cleanSlotPath(input);
+  const slash = p.indexOf('/');
+  const head = slash < 0 ? p : p.slice(0, slash);
+  return PROFILES.includes(head) && slash > 0 ? { side: head, rest: p.slice(slash + 1) } : null;
+}
+
+const under = (side, rel) => (rel ? `${side}/${rel}` : side);
+
+function prefixed(side, c) {
+  return {
+    ...c,
+    path: under(side, c.path),
+    side,
+    ...(c.root !== undefined ? { root: under(side, c.root) } : {}),
+    ...(c.nearest ? { nearest: { ...c.nearest, matchedPrefix: under(side, c.nearest.matchedPrefix), matchedDepth: c.nearest.matchedDepth + 1 } } : {}),
+  };
+}
+
+function classifyApp({ root, sides }, input) {
+  const at = splitSide(input);
+  return at ? prefixed(at.side, sides[at.side].classifyPath(at.rest)) : root.classifyPath(input);
+}
+
+function ownerApp({ root, sides }, input) {
+  const at = splitSide(input);
+  if (!at) return root.ownerOf(input);
+  const owner = sides[at.side].ownerOf(at.rest);
+  return owner ? { ...owner, root: under(at.side, owner.root), side: at.side } : null;
+}
+
+/** Whether `toPath`, of the other side, lies below a path `fromSide` declares it reads. */
+const readsPath = (repo, fromSide, toPath) => repo.sides[fromSide].reads.some((read) => `${cleanSlotPath(toPath)}/`.startsWith(read));
+
+/** The verdict of an import from a side file to a path of the other side (or of the app root, `toSide` null): allowed only through a declared read. */
+function sideCrossing(repo, fromSide, toSide, toPath) {
+  return readsPath(repo, fromSide, toPath)
+    ? { allowed: true, reason: 'sideRead', fromSide, toSide }
+    : { allowed: false, reason: 'crossSide', fromSide, toSide, reads: repo.sides[fromSide].reads };
+}
+
+function importAllowedApp({ repo, root, sides }, fromPath, toPath) {
+  const from = splitSide(fromPath);
+  const to = splitSide(toPath);
+  // A side file may read an app-root path (supabase/types/) only through a declared read, exactly as it reads the other side.
+  if (from && from.side !== to?.side) return sideCrossing(repo, from.side, to?.side ?? null, toPath);
+  if (from && to) return sides[from.side].importAllowed(from.rest, to.rest);
+  return root.importAllowed(fromPath, toPath);
+}
+
+function requiredPathsApp({ root, sides }) {
+  const own = root.requiredPaths();
+  const paths = [...own.paths];
+  const minimums = [...own.minimums];
+  for (const side of PROFILES) {
+    const required = sides[side].requiredPaths();
+    paths.push(...required.paths.map((entry) => ({ ...entry, path: under(side, entry.path), side })));
+    minimums.push(...required.minimums.map((entry) => ({ ...entry, side })));
+  }
+  return { paths, minimums };
+}
+
+function slotEnabledApp({ root, sides }, slot) {
+  if (slot.profiles.includes(APP_SCOPE)) return root.slotEnabled(slot);
+  return PROFILES.some((side) => slot.profiles.includes(side) && sides[side].slotEnabled(slot));
+}
+
+/** The resolver of the app `repo`: `root` answers its root paths and `sides[side]` the paths below that side's folder. */
+export function appResolver(repo, root, sides) {
+  const view = { repo, root, sides };
+  const allSlots = [...new Map([...root.slots(), ...PROFILES.flatMap((side) => sides[side].slots())].map((s) => [s.id, s])).values()];
+  const byId = new Map(allSlots.map((s) => [s.id, s]));
+  const classifyPath = (input) => classifyApp(view, input);
+  return Object.freeze({
+    repo,
+    sides: Object.freeze(sides),
+    /** The side of a path (be, fe) or null for a root path. */
+    sideOf: (input) => splitSide(input)?.side ?? null,
+    slot: (id) => byId.get(id) ?? null,
+    slots: () => allSlots,
+    slotEnabled: (slot) => slotEnabledApp(view, slot),
+    classifyPath,
+    slotOf: (p) => { const c = classifyPath(p); return c.slot ? byId.get(c.slot) : null; },
+    ownerOf: (input) => ownerApp(view, input),
+    tierOf: (input) => { const at = splitSide(input); return at ? sides[at.side].tierOf(at.rest) : root.tierOf(input); },
+    importAllowed: (fromPath, toPath) => importAllowedApp(view, fromPath, toPath),
+    requiredFiles: (input) => { const at = splitSide(input); return at ? sides[at.side].requiredFiles(at.rest).map((p) => under(at.side, p)) : root.requiredFiles(input); },
+    requiredPaths: () => requiredPathsApp(view),
+    trackingOf: (p) => classifyPath(p).tracking ?? null,
+    isTracked: (p) => classifyPath(p).tracking === 'tracked',
+    // The root has no tier and no rule parameters of its own; each side has them (sides.<side>.ruleParams()).
+    ruleParams: () => null,
+    allowedImports: () => null,
+  });
+}

package/runtime/scripts/hfs/slot-classify.mjs

@@ -0,0 +1,65 @@
+// slot-classify.mjs - what slot of one scope (the app root or one side) owns a path: its status, owner unit, tier, folder kind and role.
+// A scope is {manifest, repo, profile, edition, slots, byId, variants, appKind} built once by slots.mjs; every function here reads it.
+import { globExpression } from '../lib/glob.mjs';
+import { declaredSlotEnabled } from './declaration-slots.mjs';
+import { bestMatch, fillVars, matchVariants, nearestSlot } from './slot-match.mjs';
+import { cleanSlotPath } from './slot-path.mjs';
+
+/** Whether the repository of the scope holds the slot. */
+export function slotEnabled(scope, slot) {
+  // A provider slot is gated by its provider in every edition: litePresence may lift it to required, but it still
+  // exists for this repository only while a connection declares the provider.
+  if (slot.provider !== undefined) return declaredSlotEnabled(slot, scope.repo);
+  if (slot.presence !== 'opt-in') return true;
+  return declaredSlotEnabled(slot, scope.repo);
+}
+
+/** The folder kind of a file in its slot, from a named layer or kind folder. */
+function kindOf({ variant, slot, root }, p) {
+  const names = [...(slot.layers ?? []), ...(slot.kinds ?? [])];
+  if (!names.length) return null;
+  const literal = variant.segments.find((segment) => names.includes(segment));
+  if (literal) return literal;
+  const below = root ? p.slice(root.length + 1) : p;
+  return below.split('/').slice(0, -1).find((segment) => names.includes(segment)) ?? null;
+}
+
+/** The role of a file in its slot: the entry of `roles` whose file name (variables filled from the path, `*` a wildcard inside the name) matches the file's name. */
+function roleOf(slot, bindings, p) {
+  const name = p.split('/').pop();
+  for (const [role, file] of Object.entries(slot.roles ?? {})) if (globExpression(fillVars(file, bindings)).test(name)) return role;
+  return null;
+}
+
+/**
+ * status: owned | forbidden (external slot) | not-enabled (opt-in slot the repository did not declare) | ambiguous
+ * (two slots of equal specificity; a manifest gap) | no-slot (code HFS_SLOT_UNDECLARED, with the nearest slot).
+ */
+export function classifyIn(scope, input) {
+  const p = cleanSlotPath(input);
+  const { hit, ambiguous } = bestMatch(matchVariants(scope, p));
+  if (ambiguous.length) return { path: p, status: 'ambiguous', candidates: ambiguous };
+  if (!hit) return { path: p, status: 'no-slot', code: 'HFS_SLOT_UNDECLARED', nearest: nearestSlot(scope.variants, p) };
+  const { slot, root, bindings } = hit;
+  const status = (slot.presence === 'forbidden' && 'forbidden') || (slotEnabled(scope, slot) ? 'owned' : 'not-enabled');
+  const kind = kindOf(hit, p);
+  const role = roleOf(slot, bindings, p);
+  return { path: p, status, slot: slot.id, root, bindings, ...(kind ? { kind } : {}), ...(role ? { role } : {}), presence: slot.presence, tracking: slot.tracked, ...(status === 'forbidden' ? { goesTo: slot.goesTo } : {}) };
+}
+
+/** The owner unit of `p`: the most specific owner slot instance containing it (a slot's own root when it owns nothing). */
+export function ownerIn(scope, input) {
+  const p = cleanSlotPath(input);
+  const { hit } = bestMatch(matchVariants(scope, p, (s) => s.owner === true));
+  return hit ? { slot: hit.slot.id, root: hit.root, bindings: hit.bindings } : null;
+}
+
+/** The tier of `p` in the direction matrix: its slot's tier, the owner's for an inheriting slot, none for an untiered one; null when no slot owns it. */
+export function tierIn(scope, input) {
+  const c = classifyIn(scope, input);
+  if (!c.slot) return null;
+  const tier = scope.byId.get(c.slot).tier;
+  if (tier !== 'inherit') return tier;
+  const owner = ownerIn(scope, input);
+  return owner ? scope.byId.get(owner.slot).tier : 'none';
+}

package/runtime/scripts/hfs/slot-errors.mjs

@@ -0,0 +1,11 @@
+// slot-errors.mjs - the shared refusal type for HFS manifest and declaration loaders.
+export class HfsSlotsError extends Error {
+  constructor(code, message, details = {}) {
+    super(`${code}: ${message}`);
+    this.name = 'HfsSlotsError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export const fail = (code, message, details) => { throw new HfsSlotsError(code, message, details); };