@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/fe-stack.mjs

@@ -14,7 +14,6 @@ import { editionRuleParams } from '../edition-slots.mjs';
 import { globExpression } from '../../lib/glob.mjs';
 import { grammarLintFor } from '../../lib/grammar-lint.mjs';
 import { numericMatch } from '../../lib/numeric-match.mjs';
-
 export const FE_STACK_FORBIDDEN = 'FE_STACK_FORBIDDEN';
 export const FE_STACK_UNLISTED = 'FE_STACK_UNLISTED';
 export const FE_STACK_CORE_MISSING = 'FE_STACK_CORE_MISSING';
@@ -24,153 +23,157 @@ const FAMILY_SPLIT_MAJOR = 9;
 const CATALOG_FILE = new URL('../../../knowledge/hfs/fe-stack.yaml', import.meta.url);
 const PACKAGE_JSON = /(?:^|\/)package\.json$/;
 const APP_ROOT_MANIFEST = 'package.json';
-
 let forbidden = null;
-
 /** Package-name patterns and their concern, canonical packages and guidance, read once. */
 function forbiddenPackages() {
-  if (forbidden) return forbidden;
-  const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
-  if (catalog?.schema !== 'starci/fe-stack@1' || !Array.isArray(catalog.concerns)) throw new Error('knowledge/hfs/fe-stack.yaml is not a starci/fe-stack@1 catalog');
-  forbidden = [];
-  for (const concern of catalog.concerns) {
-    for (const name of concern.forbids ?? []) forbidden.push({ matches: globExpression(name), concern: concern.id, canonical: concern.packages ?? [], why: concern.why });
-  }
-  return forbidden;
+    if (forbidden)
+        return forbidden;
+    const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
+    if (catalog?.schema !== 'starci/fe-stack@1' || !Array.isArray(catalog.concerns))
+        throw new Error('knowledge/hfs/fe-stack.yaml is not a starci/fe-stack@1 catalog');
+    forbidden = [];
+    for (const concern of catalog.concerns) {
+        for (const name of concern.forbids ?? [])
+            forbidden.push({ matches: globExpression(name), concern: concern.id, canonical: concern.packages ?? [], why: concern.why });
+    }
+    return forbidden;
 }
-
 /** A forbidden package or npm scope is judged before the closed dependency catalog. */
 function forbiddingPackage(name) {
-  return forbiddenPackages().find(entry => entry.matches.test(name));
+    return forbiddenPackages().find((entry) => entry.matches.test(name));
 }
-
 /**
  * The packages the back end owns (be infraOwners with at least one owner, full's view: a library lite removes is the edition rule's
  * finding, not a front-end one): a root dependency of the back end.
  */
 function backendOwned(manifest) {
-  const be = manifest?.ruleParams?.be;
-  if (!be) return new Set();
-  const owners = editionRuleParams(be, 'full').infraOwners ?? {};
-  return new Set(Object.keys(owners).filter((name) => Array.isArray(owners[name]) && owners[name].length > 0));
+    const be = manifest?.ruleParams?.be;
+    if (!be)
+        return new Set();
+    const owners = editionRuleParams(be, 'full').infraOwners ?? {};
+    return new Set(Object.keys(owners).filter((name) => Array.isArray(owners[name]) && owners[name].length > 0));
 }
-
 function manifestFindings(repoRoot, rel, skip) {
-  const pkg = readJson(repoRoot, rel);
-  if (!pkg || typeof pkg !== 'object') return [];
-  const findings = [];
-  for (const section of DEPENDENCY_SECTIONS) {
-    for (const name of Object.keys(pkg[section] ?? {})) {
-      const entry = forbiddingPackage(name);
-      if (!entry || skip.has(name)) continue;
-      const canonical = entry.canonical.length ? entry.canonical.join(', ') : 'the canonical library of the concern';
-      findings.push(found(FE_STACK_FORBIDDEN, rel, `${rel} ${section} declares ${name}, which the front-end stack forbids for the ${entry.concern} concern (knowledge/hfs/fe-stack.yaml); use ${canonical} and delete ${name}. ${entry.why}`, { section, dependency: name, concern: entry.concern }));
+    const pkg = readJson(repoRoot, rel);
+    if (!pkg || typeof pkg !== 'object')
+        return [];
+    const findings = [];
+    for (const section of DEPENDENCY_SECTIONS) {
+        for (const name of Object.keys(pkg[section] ?? {})) {
+            const entry = forbiddingPackage(name);
+            if (!entry || skip.has(name))
+                continue;
+            const canonical = entry.canonical.length ? entry.canonical.join(', ') : 'the canonical library of the concern';
+            findings.push(found(FE_STACK_FORBIDDEN, rel, `${rel} ${section} declares ${name}, which the front-end stack forbids for the ${entry.concern} concern (knowledge/hfs/fe-stack.yaml); use ${canonical} and delete ${name}. ${entry.why}`, { section, dependency: name, concern: entry.concern }));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 /**
  * FE_STACK_FORBIDDEN over the tracked paths `files` of one scope: every package.json of the fe side, or the app root's one
  * package.json minus what the back end owns. A be side has no front-end manifest and answers [].
  */
 export function feStackFindings({ repoRoot, files, repo, manifest }) {
-  if (repo.profile === 'be') return [];
-  const atRoot = repo.profile !== 'fe';
-  const skip = atRoot ? backendOwned(manifest) : new Set();
-  const manifests = files.filter((file) => !file.includes('node_modules/') && (atRoot ? file === APP_ROOT_MANIFEST : PACKAGE_JSON.test(file)));
-  return manifests.flatMap((rel) => manifestFindings(repoRoot, rel, skip));
+    if (repo.profile === 'be')
+        return [];
+    const atRoot = repo.profile !== 'fe';
+    const skip = atRoot ? backendOwned(manifest) : new Set();
+    const manifests = files.filter((file) => !file.includes('node_modules/') && (atRoot ? file === APP_ROOT_MANIFEST : PACKAGE_JSON.test(file)));
+    return manifests.flatMap((rel) => manifestFindings(repoRoot, rel, skip));
 }
-
 /** R288 uses the same catalog as the scaffold, including tools installed once at the app root. */
 function stackCatalog() {
-  const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
-  const allowed = new Set();
-  const core = new Map();
-  for (const concern of catalog.concerns) {
-    const rootTool = ['codegen', 'lint'].includes(concern.id);
-    for (const name of concern.packages ?? []) {
-      allowed.add(name);
-      if (concern.tier === 'core') core.set(name, { concern: concern.id, rootTool: rootTool || ['typescript', 'tailwindcss'].includes(name) });
+    const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
+    const allowed = new Set();
+    const core = new Map();
+    for (const concern of catalog.concerns) {
+        const rootTool = ['codegen', 'lint'].includes(concern.id);
+        for (const name of concern.packages ?? []) {
+            allowed.add(name);
+            if (concern.tier === 'core')
+                core.set(name, { concern: concern.id, rootTool: rootTool || ['typescript', 'tailwindcss'].includes(name) });
+        }
     }
-  }
-  return { allowed, core };
+    return { allowed, core };
 }
-
-const dependenciesOf = pkg => new Set(DEPENDENCY_SECTIONS.flatMap(section => Object.keys(pkg?.[section] ?? {})));
-
+const dependenciesOf = (pkg) => new Set(DEPENDENCY_SECTIONS.flatMap(section => Object.keys(pkg?.[section] ?? {})));
 function extraPackages(declaration) {
-  const entries = declaration?.sides?.fe?.extraPackages ?? declaration?.extraPackages ?? declaration?.fe?.extraPackages ?? [];
-  return new Set((Array.isArray(entries) ? entries : []).filter(entry => typeof entry?.name === 'string'
-    && typeof entry.reason === 'string' && entry.reason.trim()).map(entry => entry.name));
+    const entries = declaration?.sides?.fe?.extraPackages ?? declaration?.extraPackages ?? declaration?.fe?.extraPackages ?? [];
+    return new Set((Array.isArray(entries) ? entries : []).filter(entry => typeof entry?.name === 'string'
+        && typeof entry.reason === 'string' && entry.reason.trim()).map(entry => entry.name));
 }
-
 function unlistedFindings(rel, pkg, allowed, extras, workspaces) {
-  const findings = [];
-  for (const section of DEPENDENCY_SECTIONS) for (const name of Object.keys(pkg?.[section] ?? {})) {
-    if (allowed.has(name) || extras.has(name) || workspaces.has(name) || forbiddingPackage(name)) continue;
-    findings.push(found(FE_STACK_UNLISTED, rel, `${rel} ${section} declares ${name}, absent from knowledge/hfs/fe-stack.yaml; add a canonical concern or declare sides.fe.extraPackages with its name and a nonempty reason in hfs.json`, { section, dependency: name }));
-  }
-  return findings;
+    const findings = [];
+    for (const section of DEPENDENCY_SECTIONS)
+        for (const name of Object.keys(pkg?.[section] ?? {})) {
+            if (allowed.has(name) || extras.has(name) || workspaces.has(name) || forbiddingPackage(name))
+                continue;
+            findings.push(found(FE_STACK_UNLISTED, rel, `${rel} ${section} declares ${name}, absent from knowledge/hfs/fe-stack.yaml; add a canonical concern or declare sides.fe.extraPackages with its name and a nonempty reason in hfs.json`, { section, dependency: name }));
+        }
+    return findings;
 }
-
 /** The major version a dependency spec admits, or null when the spec names no plain semver (a tag, a path or a protocol). */
 const declaredMajor = (spec) => numericMatch(spec, /^[\^~>=v\s]*(\d+)(?:\.|$)/);
-
 /** The universal canon's declared spec in any front-end or app-root manifest, or null when none declares it. */
 function universalCanonSpec(manifests) {
-  for (const [, pkg] of manifests) for (const section of DEPENDENCY_SECTIONS) {
-    const spec = pkg?.[section]?.[UNIVERSAL_CANON];
-    if (spec !== undefined) return spec;
-  }
-  return null;
+    for (const [, pkg] of manifests)
+        for (const section of DEPENDENCY_SECTIONS) {
+            const spec = pkg?.[section]?.[UNIVERSAL_CANON];
+            if (spec !== undefined)
+                return spec;
+        }
+    return null;
 }
-
 /**
  * From canon-fe 9 the Grammar component rules ship in the selected family's lint package; an app that installs the
  * universal canon without that package would silently lose them, so the stack refuses it. An unparseable spec is judged
  * like 9 rather than waved through.
  */
 function familyLintFindings(declaration, repo, packages, rootManifest) {
-  const family = declaration?.sides?.fe?.grammar ?? repo.grammar;
-  if (typeof family !== 'string' || !family) return [];
-  const manifests = [...packages, ['../package.json', rootManifest]];
-  const product = (repo.apps ?? []).find(app => app.kind === 'next' && app.name !== 'landing');
-  const anchor = product ? `apps/${product.name}/package.json` : 'package.json';
-  const spec = universalCanonSpec(manifests);
-  if (spec === null) return [];
-  const major = declaredMajor(spec);
-  if (major !== null && major < FAMILY_SPLIT_MAJOR) return [];
-  const lint = grammarLintFor(family);
-  if (lint.package === null) return [];
-  if (manifests.some(([, pkg]) => dependenciesOf(pkg).has(lint.package))) return [];
-  const nextStep = `Add ${lint.package} beside ${UNIVERSAL_CANON} (the app root devDependencies or the fe workspace), compose ${lint.factory}({ hfs }) after starciFeConfig({ hfs }) in fe/eslint.config.mjs, or run starci app sync.`;
-  return [found(FE_STACK_FAMILY_LINT_MISSING, anchor,
-    `hfs.json selects sides.fe.grammar ${family} and the front end declares ${UNIVERSAL_CANON} ${spec}, but no manifest declares ${lint.package}: from ${UNIVERSAL_CANON} ${FAMILY_SPLIT_MAJOR} that package carries the ${family} Grammar component rules, so without it they are not enforced. ${nextStep}`,
-    { dependency: lint.package, family, nextStep })];
+    const family = declaration?.sides?.fe?.grammar ?? repo.grammar;
+    if (typeof family !== 'string' || !family)
+        return [];
+    const manifests = [...packages, ['../package.json', rootManifest]];
+    const product = (repo.apps ?? []).find((app) => app.kind === 'next' && app.name !== 'landing');
+    const anchor = product ? `apps/${product.name}/package.json` : 'package.json';
+    const spec = universalCanonSpec(manifests);
+    if (spec === null)
+        return [];
+    const major = declaredMajor(spec);
+    if (major !== null && major < FAMILY_SPLIT_MAJOR)
+        return [];
+    const lint = grammarLintFor(family);
+    if (lint.package === null)
+        return [];
+    if (manifests.some(([, pkg]) => dependenciesOf(pkg).has(lint.package)))
+        return [];
+    const nextStep = `Add ${lint.package} beside ${UNIVERSAL_CANON} (the app root devDependencies or the fe workspace), compose ${lint.factory}({ hfs }) after starciFeConfig({ hfs }) in fe/eslint.config.mjs, or run starci app sync.`;
+    return [found(FE_STACK_FAMILY_LINT_MISSING, anchor, `hfs.json selects sides.fe.grammar ${family} and the front end declares ${UNIVERSAL_CANON} ${spec}, but no manifest declares ${lint.package}: from ${UNIVERSAL_CANON} ${FAMILY_SPLIT_MAJOR} that package carries the ${family} Grammar component rules, so without it they are not enforced. ${nextStep}`, { dependency: lint.package, family, nextStep })];
 }
-
 /** Closed FE catalog and core presence over the front-end side (the mixed root also holds BE tools). */
 export function feStackAllowlistFindings({ repoRoot, files, all = files, repo, inScope = () => true }) {
-  if (repo.profile !== 'fe' || repo.kind === 'runtime') return [];
-  const declaration = readJson(repoRoot, '../hfs.json') ?? repo;
-  const manifests = all.filter(file => PACKAGE_JSON.test(file) && !file.includes('node_modules/'));
-  const packages = new Map(manifests.map(file => [file, readJson(repoRoot, file)]));
-  const workspaces = new Set([...packages].filter(([file]) => file.startsWith('packages/')).map(([, pkg]) => pkg?.name).filter(Boolean));
-  const { allowed, core } = stackCatalog();
-  const extras = extraPackages(declaration);
-  const findings = [...packages].filter(([file]) => inScope(file)).flatMap(([file, pkg]) => unlistedFindings(file, pkg, allowed, extras, workspaces));
-  const rootManifest = readJson(repoRoot, '../package.json');
-  const rootTools = dependenciesOf(rootManifest);
-  findings.push(...familyLintFindings(declaration, repo, packages, rootManifest));
-  for (const app of repo.apps ?? []) {
-    if (app.kind !== 'next' || app.name === 'landing') continue;
-    const rel = `apps/${app.name}/package.json`;
-    const installed = dependenciesOf(packages.get(rel));
-    for (const [name, entry] of core) {
-      if (installed.has(name) || (entry.rootTool && rootTools.has(name))) continue;
-      findings.push(found(FE_STACK_CORE_MISSING, rel, `${rel} lacks core package ${name} for ${entry.concern} in knowledge/hfs/fe-stack.yaml; declare it ${entry.rootTool ? 'in the app root devDependencies or this workspace' : 'in this product workspace'}`, { dependency: name, concern: entry.concern }));
+    if (repo.profile !== 'fe' || repo.kind === 'runtime')
+        return [];
+    const declaration = readJson(repoRoot, '../hfs.json') ?? repo;
+    const manifests = all.filter((file) => PACKAGE_JSON.test(file) && !file.includes('node_modules/'));
+    const packages = new Map(manifests.map((file) => [file, readJson(repoRoot, file)]));
+    const workspaces = new Set([...packages].filter(([file]) => file.startsWith('packages/')).map(([, pkg]) => pkg?.name).filter(Boolean));
+    const { allowed, core } = stackCatalog();
+    const extras = extraPackages(declaration);
+    const findings = [...packages].filter(([file]) => inScope(file)).flatMap(([file, pkg]) => unlistedFindings(file, pkg, allowed, extras, workspaces));
+    const rootManifest = readJson(repoRoot, '../package.json');
+    const rootTools = dependenciesOf(rootManifest);
+    findings.push(...familyLintFindings(declaration, repo, packages, rootManifest));
+    for (const app of repo.apps ?? []) {
+        if (app.kind !== 'next' || app.name === 'landing')
+            continue;
+        const rel = `apps/${app.name}/package.json`;
+        const installed = dependenciesOf(packages.get(rel));
+        for (const [name, entry] of core) {
+            if (installed.has(name) || (entry.rootTool && rootTools.has(name)))
+                continue;
+            findings.push(found(FE_STACK_CORE_MISSING, rel, `${rel} lacks core package ${name} for ${entry.concern} in knowledge/hfs/fe-stack.yaml; declare it ${entry.rootTool ? 'in the app root devDependencies or this workspace' : 'in this product workspace'}`, { dependency: name, concern: entry.concern }));
+        }
     }
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/feature-files.d.mts

@@ -0,0 +1,10 @@
+import type { Repo, Resolver } from './rule-types.mjs';
+export declare const HFS_FEATURE_FILE_BUDGET = "HFS_FEATURE_FILE_BUDGET";
+/** Count the complete tracked tree, even when a per-file check is scoped to only part of a feature. */
+export declare function featureFileFindings({ files, all, repo, resolver, isRoot }: {
+    files: string[];
+    all?: string[];
+    repo: Repo;
+    resolver: Resolver;
+    isRoot?: boolean;
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/feature-files.mjs

@@ -1,28 +1,23 @@
 // feature-files.mjs - R292: a feature stays within ruleParams.featureFiles tracked files, in lite and full.
 import { posixPath } from '../../lib/path-key.mjs';
 import { found } from './read.mjs';
-
 export const HFS_FEATURE_FILE_BUDGET = 'HFS_FEATURE_FILE_BUDGET';
-
 /** Feature owners come from the slot manifest: BE trigger roots (including cli) and FE feature owners. */
 const isFeature = (slot) => slot?.owner === true && slot.tier === 'feature' && (slot.trigger !== undefined || slot.id === 'fe.feature');
-
 /** Count the complete tracked tree, even when a per-file check is scoped to only part of a feature. */
 export function featureFileFindings({ files, all = files, repo, resolver, isRoot = repo.profile === 'app' }) {
-  // The app check invokes this again for each side, with that side's paths and edition-aware parameters.
-  if (isRoot || !['be', 'fe'].includes(repo.profile)) return [];
-  const max = resolver.ruleParams().featureFiles ?? 250;
-  const counts = new Map();
-  for (const file of new Set(all.map(posixPath))) {
-    if (!file || file.endsWith('/')) continue;
-    const owner = resolver.ownerOf(file);
-    if (!owner || !isFeature(resolver.slot(owner.slot))) continue;
-    counts.set(owner.root, (counts.get(owner.root) ?? 0) + 1);
-  }
-  return [...counts].filter(([, count]) => count > max).map(([root, count]) => found(
-    HFS_FEATURE_FILE_BUDGET,
-    root,
-    `${root} has ${count} tracked files, over the feature budget of ${max}; split it by product capability`,
-    { files: count, max },
-  ));
+    // The app check invokes this again for each side, with that side's paths and edition-aware parameters.
+    if (isRoot || !['be', 'fe'].some((value) => value === repo.profile))
+        return [];
+    const max = resolver.ruleParams().featureFiles ?? 250;
+    const counts = new Map();
+    for (const file of new Set(all.map(posixPath))) {
+        if (!file || file.endsWith('/'))
+            continue;
+        const owner = resolver.ownerOf(file);
+        if (!owner || !isFeature(resolver.slot(owner.slot)))
+            continue;
+        counts.set(owner.root, (counts.get(owner.root) ?? 0) + 1);
+    }
+    return [...counts].filter(([, count]) => count > max).map(([root, count]) => found(HFS_FEATURE_FILE_BUDGET, root, `${root} has ${count} tracked files, over the feature budget of ${max}; split it by product capability`, { files: count, max }));
 }

package/runtime/scripts/hfs/rules/frontend-tree.d.mts

@@ -0,0 +1,18 @@
+import type { Parsed, Repo } from './rule-types.mjs';
+export declare const DEFAULT_LOCALE = "vi";
+export declare const WIRE_SCHEMA_STAMP = ".schema-sha256";
+/** Digest protocol for codegen: sorted app-relative schema path, NUL, LF-normalized source, NUL. */
+export declare function wireSchemaDigest(repoRoot: string, snapshots: Parsed): string | null;
+/** The fe side's tree findings of R59 and R60 for every `next` app; `repoRoot` is the fe side folder, `files` side-relative. */
+export declare function frontendFindings({ repoRoot, files, repo }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+}): import("./rule-types.mjs").Finding[];
+/** The app's front-end findings that read the root; workspace checks include R52's ignored local artifacts. */
+export declare function appFrontendFindings({ repoRoot, files, repo, phase }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+    phase?: Parsed;
+}): any[];

package/runtime/scripts/hfs/rules/frontend-tree.mjs

@@ -15,7 +15,6 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { found, readJson, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
-
 const WIRE_GENERATED = 'FE_WIRE_GENERATED';
 const I18N_PLACEMENT = 'FE_I18N_PLACEMENT';
 const I18N_CATALOG = 'FE_I18N_CATALOG';
@@ -23,123 +22,138 @@ export const DEFAULT_LOCALE = 'vi';
 const ROUTE_FILE = /\/(?:page|layout|template|loading|error|not-found)\.[jt]sx?$/;
 const LOCALE = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
 export const WIRE_SCHEMA_STAMP = '.schema-sha256';
-
 /** Every leaf key of a parsed catalog as a dotted path. */
 function catalogKeys(value, prefix = '') {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return [prefix];
-  const entries = Object.entries(value);
-  return entries.length ? entries.flatMap(([key, child]) => catalogKeys(child, prefix ? `${prefix}.${key}` : key)) : [prefix];
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return [prefix];
+    const entries = Object.entries(value);
+    return entries.length ? entries.flatMap(([key, child]) => catalogKeys(child, prefix ? `${prefix}.${key}` : key)) : [prefix];
 }
-
 /** Digest protocol for codegen: sorted app-relative schema path, NUL, LF-normalized source, NUL. */
 export function wireSchemaDigest(repoRoot, snapshots) {
-  const hash = createHash('sha256');
-  for (const snapshot of [...snapshots].sort(byCodeUnit)) {
-    let source;
-    try { source = fs.readFileSync(path.join(repoRoot, snapshot), 'utf8'); } catch { return null; }
-    hash.update(`${snapshot}\0${source.replaceAll('\r\n', '\n')}\0`);
-  }
-  return hash.digest('hex');
+    const hash = createHash('sha256');
+    for (const snapshot of [...snapshots].sort(byCodeUnit)) {
+        let source;
+        try {
+            source = fs.readFileSync(path.join(repoRoot, snapshot), 'utf8');
+        }
+        catch {
+            return null;
+        }
+        hash.update(`${snapshot}\0${source.replaceAll('\r\n', '\n')}\0`);
+    }
+    return hash.digest('hex');
 }
-
 /** Generated output is untracked, so inspect disk; the digest sidecar alone is not generated wire types. */
 function hasGeneratedTypes(directory) {
-  let entries;
-  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
-  return entries.some((entry) => entry.isDirectory() ? hasGeneratedTypes(path.join(directory, entry.name)) : entry.isFile() && entry.name.endsWith('.ts'));
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    return entries.some((entry) => entry.isDirectory() ? hasGeneratedTypes(path.join(directory, entry.name)) : entry.isFile() && entry.name.endsWith('.ts'));
 }
-
 const scriptsOf = (repoRoot, file) => readJson(repoRoot, file)?.scripts ?? {};
-
 function wireDigestProblem(digest, stamped) {
-  if (digest === null) return 'cannot be verified against unreadable contract snapshots';
-  if (!/^[0-9a-f]{64}$/.test(stamped ?? '')) return 'has no valid schema digest recorded by codegen';
-  if (stamped !== digest) return 'records a different schema digest from the contract snapshots';
-  return null;
+    if (digest === null)
+        return 'cannot be verified against unreadable contract snapshots';
+    if (!/^[0-9a-f]{64}$/.test(stamped ?? ''))
+        return 'has no valid schema digest recorded by codegen';
+    if (stamped !== digest)
+        return 'records a different schema digest from the contract snapshots';
+    return null;
 }
-
 function appWireFindings({ repoRoot, files, app, snapshots, digest }) {
-  const graphql = `fe/apps/${app}/src/modules/api/graphql/`;
-  const generated = `${graphql}__generated__`;
-  if (!hasGeneratedTypes(path.join(repoRoot, generated))) {
-    const operations = files.some((file) => file.startsWith(graphql) && /^(?:(?:queries|mutations)\/[^/]+\.ts|(?!(?:__generated__|node_modules)\/).*\.graphql)$/.test(file.slice(graphql.length)));
-    if (operations) return [found(WIRE_GENERATED, generated, `${app} keeps GraphQL operations but ${generated} has no generated wire types; run \`npm run codegen\``, { app })];
-    return [];
-  }
-  if (!snapshots.length) return [];
-  const stamped = readText(repoRoot, `${generated}/${WIRE_SCHEMA_STAMP}`)?.trim();
-  const problem = wireDigestProblem(digest, stamped);
-  if (problem === null) return [];
-  return [found(WIRE_GENERATED, generated, `${generated} ${problem}; run \`npm run codegen\` so its wire types and ${WIRE_SCHEMA_STAMP} match the schema`, { app, snapshots })];
+    const graphql = `fe/apps/${app}/src/modules/api/graphql/`;
+    const generated = `${graphql}__generated__`;
+    if (!hasGeneratedTypes(path.join(repoRoot, generated))) {
+        const operations = files.some((file) => file.startsWith(graphql) && /^(?:(?:queries|mutations)\/[^/]+\.ts|(?!(?:__generated__|node_modules)\/).*\.graphql)$/.test(file.slice(graphql.length)));
+        if (operations)
+            return [found(WIRE_GENERATED, generated, `${app} keeps GraphQL operations but ${generated} has no generated wire types; run \`npm run codegen\``, { app })];
+        return [];
+    }
+    if (!snapshots.length)
+        return [];
+    const stamped = readText(repoRoot, `${generated}/${WIRE_SCHEMA_STAMP}`)?.trim();
+    const problem = wireDigestProblem(digest, stamped);
+    if (problem === null)
+        return [];
+    return [found(WIRE_GENERATED, generated, `${generated} ${problem}; run \`npm run codegen\` so its wire types and ${WIRE_SCHEMA_STAMP} match the schema`, { app, snapshots })];
 }
-
 /** R52's tracked-source obligations, plus generated local artifacts in the workspace phase. */
 function wireFindings({ repoRoot, files, apps, reads, phase }) {
-  const snapshots = files.filter((file) => file.endsWith('/schema.graphql') && reads.some((read) => file.startsWith(read)));
-  const findings = [];
-  if (snapshots.length && typeof scriptsOf(repoRoot, 'package.json').codegen !== 'string') findings.push(found(WIRE_GENERATED, 'package.json', `the app keeps contract snapshots (${reads.join(', ')}) but its package.json declares no \`codegen\` script; wire types are generated from the snapshots, never typed by hand`));
-  // A clean checkout has no ignored build artifacts. The runtime's source-render check judges their tracked inputs;
-  // the ordinary app check/lint judges the generated output after the app's codegen step (also required by L4).
-  if (phase === 'source') return findings;
-  const digest = snapshots.length ? wireSchemaDigest(repoRoot, snapshots) : null;
-  findings.push(...apps.flatMap((app) => appWireFindings({ repoRoot, files, app, snapshots, digest })));
-  return findings;
+    const snapshots = files.filter((file) => file.endsWith('/schema.graphql') && reads.some((read) => file.startsWith(read)));
+    const findings = [];
+    if (snapshots.length && typeof scriptsOf(repoRoot, 'package.json').codegen !== 'string')
+        findings.push(found(WIRE_GENERATED, 'package.json', `the app keeps contract snapshots (${reads.join(', ')}) but its package.json declares no \`codegen\` script; wire types are generated from the snapshots, never typed by hand`));
+    // A clean checkout has no ignored build artifacts. The runtime's source-render check judges their tracked inputs;
+    // the ordinary app check/lint judges the generated output after the app's codegen step (also required by L4).
+    if (phase === 'source')
+        return findings;
+    const digest = snapshots.length ? wireSchemaDigest(repoRoot, snapshots) : null;
+    findings.push(...apps.flatMap((app) => appWireFindings({ repoRoot, files, app, snapshots, digest })));
+    return findings;
 }
-
 /** R59 over the app: next-intl is a dependency of an fe workspace manifest (fe/apps/<app> or fe/packages/<pkg>; the workspace that imports it declares it, R146). */
 function intlDependencyFindings({ repoRoot, files }) {
-  const declares = (file) => { const pkg = readJson(repoRoot, file); return pkg ? ['dependencies', 'devDependencies'].some((section) => pkg[section]?.['next-intl'] !== undefined) : false; };
-  const workspaces = files.filter((file) => /^fe\/(?:apps|packages)\/[^/]+\/package\.json$/.test(file));
-  return workspaces.some(declares) ? [] : [found(I18N_PLACEMENT, 'package.json', 'no fe workspace depends on next-intl (an fe app or a shared fe package declares it); every fe app uses next-intl with the [locale] segment')];
+    const declares = (file) => { const pkg = readJson(repoRoot, file); return pkg ? ['dependencies', 'devDependencies'].some((section) => pkg[section]?.['next-intl'] !== undefined) : false; };
+    const workspaces = files.filter((file) => /^fe\/(?:apps|packages)\/[^/]+\/package\.json$/.test(file));
+    return workspaces.some(declares) ? [] : [found(I18N_PLACEMENT, 'package.json', 'no fe workspace depends on next-intl (an fe app or a shared fe package declares it); every fe app uses next-intl with the [locale] segment')];
 }
-
 function placementFindings({ app, tracked }) {
-  const base = `apps/${app}`;
-  const findings = [];
-  if (!tracked.includes(`${base}/src/proxy.ts`)) findings.push(found(I18N_PLACEMENT, `${base}/src/proxy.ts`, `${app} has no src/proxy.ts; locale routing lives in proxy.ts`, { app }));
-  for (const file of tracked.filter((f) => new RegExp(`^${base}/src/middleware.[cm]?[jt]s$`).test(f))) findings.push(found(I18N_PLACEMENT, file, `${file} is a middleware file; Next 16 routes through src/proxy.ts`, { app }));
-  const appDir = `${base}/src/app/`;
-  for (const file of tracked.filter((f) => f.startsWith(appDir) && ROUTE_FILE.test(f))) {
-    const rel = file.slice(appDir.length);
-    if (rel.startsWith('[locale]/') || rel.startsWith('health/') || ['page.tsx', 'not-found.tsx', 'layout.tsx'].includes(rel)) continue;  // next-intl's root not-found and its layout
-    findings.push(found(I18N_PLACEMENT, file, `${file} is a route file outside the [locale] segment; every page, layout and boundary sits under src/app/[locale]/`, { app }));
-  }
-  const messages = `${base}/src/modules/i18n/messages/`;
-  const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json'));
-  if (!catalogs.includes(`${messages}${DEFAULT_LOCALE}.json`)) findings.push(found(I18N_PLACEMENT, `${messages}${DEFAULT_LOCALE}.json`, `${app} has no ${DEFAULT_LOCALE}.json catalog; the default locale is ${DEFAULT_LOCALE}`, { app }));
-  for (const file of catalogs) {
-    const name = path.posix.basename(file, '.json');
-    if (path.posix.dirname(file) + '/' !== messages || !LOCALE.test(name)) findings.push(found(I18N_PLACEMENT, file, `${file} is not a <locale>.json catalog directly under modules/i18n/messages/`, { app }));
-  }
-  return findings;
+    const base = `apps/${app}`;
+    const findings = [];
+    if (!tracked.includes(`${base}/src/proxy.ts`))
+        findings.push(found(I18N_PLACEMENT, `${base}/src/proxy.ts`, `${app} has no src/proxy.ts; locale routing lives in proxy.ts`, { app }));
+    for (const file of tracked.filter((f) => new RegExp(`^${base}/src/middleware.[cm]?[jt]s$`).test(f)))
+        findings.push(found(I18N_PLACEMENT, file, `${file} is a middleware file; Next 16 routes through src/proxy.ts`, { app }));
+    const appDir = `${base}/src/app/`;
+    for (const file of tracked.filter((f) => f.startsWith(appDir) && ROUTE_FILE.test(f))) {
+        const rel = file.slice(appDir.length);
+        if (rel.startsWith('[locale]/') || rel.startsWith('health/') || ['page.tsx', 'not-found.tsx', 'layout.tsx'].includes(rel))
+            continue; // next-intl's root not-found and its layout
+        findings.push(found(I18N_PLACEMENT, file, `${file} is a route file outside the [locale] segment; every page, layout and boundary sits under src/app/[locale]/`, { app }));
+    }
+    const messages = `${base}/src/modules/i18n/messages/`;
+    const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json'));
+    if (!catalogs.includes(`${messages}${DEFAULT_LOCALE}.json`))
+        findings.push(found(I18N_PLACEMENT, `${messages}${DEFAULT_LOCALE}.json`, `${app} has no ${DEFAULT_LOCALE}.json catalog; the default locale is ${DEFAULT_LOCALE}`, { app }));
+    for (const file of catalogs) {
+        const name = path.posix.basename(file, '.json');
+        if (path.posix.dirname(file) + '/' !== messages || !LOCALE.test(name))
+            findings.push(found(I18N_PLACEMENT, file, `${file} is not a <locale>.json catalog directly under modules/i18n/messages/`, { app }));
+    }
+    return findings;
 }
-
 function catalogFindings({ repoRoot, app, tracked }) {
-  const messages = `apps/${app}/src/modules/i18n/messages/`;
-  const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json') && !f.slice(messages.length).includes('/'));
-  const keys = new Map();
-  for (const file of catalogs) {
-    const parsed = readJson(repoRoot, file);
-    if (parsed !== null) keys.set(file, new Set(catalogKeys(parsed)));
-  }
-  if (keys.size < 2) return [];
-  const all = new Set([...keys.values()].flatMap((set) => [...set]));
-  const findings = [];
-  for (const [file, set] of keys) {
-    const missing = [...all].filter((key) => !set.has(key)).sort(byCodeUnit);
-    if (missing.length) findings.push(found(I18N_CATALOG, file, `${file} lacks ${missing.length} key${missing.length === 1 ? '' : 's'} another locale has (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', ...' : ''}); every catalog holds the same keys`, { app, missing }));
-  }
-  return findings;
+    const messages = `apps/${app}/src/modules/i18n/messages/`;
+    const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json') && !f.slice(messages.length).includes('/'));
+    const keys = new Map();
+    for (const file of catalogs) {
+        const parsed = readJson(repoRoot, file);
+        if (parsed !== null)
+            keys.set(file, new Set(catalogKeys(parsed)));
+    }
+    if (keys.size < 2)
+        return [];
+    const all = new Set([...keys.values()].flatMap((set) => [...set]));
+    const findings = [];
+    for (const [file, set] of keys) {
+        const missing = [...all].filter((key) => !set.has(key)).sort(byCodeUnit);
+        if (missing.length)
+            findings.push(found(I18N_CATALOG, file, `${file} lacks ${missing.length} key${missing.length === 1 ? '' : 's'} another locale has (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', ...' : ''}); every catalog holds the same keys`, { app, missing }));
+    }
+    return findings;
 }
-
 /** The fe side's tree findings of R59 and R60 for every `next` app; `repoRoot` is the fe side folder, `files` side-relative. */
 export function frontendFindings({ repoRoot, files, repo }) {
-  return repo.apps.filter((a) => a.kind === 'next').flatMap((a) => [placementFindings, catalogFindings].flatMap((check) => check({ repoRoot, app: a.name, tracked: files })));
+    return repo.apps.filter((a) => a.kind === 'next').flatMap((a) => [placementFindings, catalogFindings].flatMap((check) => check({ repoRoot, app: a.name, tracked: files })));
 }
-
 /** The app's front-end findings that read the root; workspace checks include R52's ignored local artifacts. */
 export function appFrontendFindings({ repoRoot, files, repo, phase = 'workspace' }) {
-  const apps = repo.sides.fe.apps.filter((a) => a.kind === 'next').map((a) => a.name);
-  // The snapshots are the paths the fe side declares it reads of the be side (hfs.json sides.fe.reads: be/contracts/).
-  return [...wireFindings({ repoRoot, files, apps, reads: repo.sides.fe.reads, phase }), ...intlDependencyFindings({ repoRoot, files })];
+    const apps = repo.sides.fe.apps.filter((a) => a.kind === 'next').map((a) => a.name);
+    // The snapshots are the paths the fe side declares it reads of the be side (hfs.json sides.fe.reads: be/contracts/).
+    return [...wireFindings({ repoRoot, files, apps, reads: repo.sides.fe.reads, phase }), ...intlDependencyFindings({ repoRoot, files })];
 }

package/runtime/scripts/hfs/rules/integration-specs.d.mts

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** The full-edition test-world proofs of R112; lite owns its integration lane through R284. */
+export declare function integrationSpecFindings({ repoRoot, files, repo }: {
+    repoRoot: string;
+    files: string[];
+    repo?: Repo;
+}): import("./rule-types.mjs").Finding[];