@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/{lib/hfs-rules/frontend.mjs → hfs/rules/frontend-tree.mjs}

@@ -1,4 +1,4 @@
-// frontend.mjs - the front-end tree checks of hfs check. Per app of the fe side (`apps/<app>`, kind next, side-relative paths):
+// frontend.mjs - the front-end tree checks of starci app check. Per app of the fe side (`apps/<app>`, kind next, side-relative paths):
 //   FE_I18N_PLACEMENT (R59)     next-intl with the `[locale]` segment: every route file sits under `src/app/[locale]/` (the root
 //                               redirect page, global-error and health probes excepted), locale routing is `src/proxy.ts` and never
 //                               `middleware.ts`, and the default locale's catalog `vi.json` exists
@@ -7,23 +7,23 @@
 //   FE_WIRE_GENERATED (R52)     wire types come from the be contract snapshots the fe side reads in place (its declared reads,
 //                               `be/contracts/`): the root package.json declares the `codegen` script, and each fe app's generated
 //                               types on disk (`modules/api/__generated__/`, never tracked) are not older than any snapshot
-//   FE_I18N_PLACEMENT (R59)     `next-intl` is a dependency of the root package.json or of a shared i18n package under fe/packages/
+//   FE_I18N_PLACEMENT (R59)     `next-intl` is a dependency of an fe workspace (an fe app manifest, or a shared i18n package under fe/packages/)
 // The files each app must hold (routing.ts, navigation.ts, request.ts, messages/, the [locale] layout) are the slot manifest's requires
 // (HFS_SLOT_REQUIRED_MISSING); which source may hold display text and how copy resolves is eslint-fe's.
 import fs from 'node:fs';
 import path from 'node:path';
 import { found, readJson } from './read.mjs';
 
-export const WIRE_GENERATED = 'FE_WIRE_GENERATED';
-export const I18N_PLACEMENT = 'FE_I18N_PLACEMENT';
-export const I18N_CATALOG = 'FE_I18N_CATALOG';
+const WIRE_GENERATED = 'FE_WIRE_GENERATED';
+const I18N_PLACEMENT = 'FE_I18N_PLACEMENT';
+const I18N_CATALOG = 'FE_I18N_CATALOG';
 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]+)*$/;
 const STALE_MS = 1000;
 
 /** Every leaf key of a parsed catalog as a dotted path. */
-export function catalogKeys(value, prefix = '') {
+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];
@@ -66,11 +66,11 @@ function wireFindings({ repoRoot, files, apps, reads }) {
   return findings;
 }
 
-/** R59 over the app: next-intl is a dependency of the one package.json or of a shared fe/packages/* manifest. */
+/** 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 shared = files.filter((file) => /^fe\/packages\/[^/]+\/package\.json$/.test(file));
-  return ['package.json', ...shared].some(declares) ? [] : [found(I18N_PLACEMENT, 'package.json', 'the app does not depend on next-intl (nor does a shared fe package); every fe app uses next-intl with the [locale] segment')];
+  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({ repoRoot, app, tracked }) {

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/integration-specs.mjs

@@ -14,10 +14,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { findPackage, requirePackage } from '../package-at.mjs';
+import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readText } from './read.mjs';
 
-export const INTEGRATION_SPEC_MISSING = 'BE_INTEGRATION_SPEC_MISSING';
+const INTEGRATION_SPEC_MISSING = 'BE_INTEGRATION_SPEC_MISSING';
 
 const CONFIG_FILE = /^((?:[^/]+\/)*?)src\/modules\/integrations\/([^/]+)\/\2\.config\.ts$/;
 const SPEC_SUFFIX = '.integration-spec.ts';
@@ -27,10 +27,7 @@ const INFRA_OUTAGES = new Set(['cut', 'latency', 'during', 'connection']);
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 /** The TypeScript compiler of the app (else of the runtime), or null. */
-function typescriptFor(repoRoot) {
-  const located = findPackage([repoRoot, HERE], ['typescript']);
-  return located ? requirePackage(located) : null;
-}
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
 
 /** The compiler options of the side (its tsconfig.json, `extends` and `paths` resolved by TypeScript itself). */
 function optionsOf(ts, sideRoot) {

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

@@ -0,0 +1,84 @@
+// kinds.mjs - the trigger kinds a back end uses are declared, whole and generated only when used (hfs.json sides.be.kinds).
+//   BE_KIND_DECLARATION   `sides.be.kinds` lists exactly the kinds the features hold: a kind in use that is not declared, a declared kind with no
+//                         feature, a declared kind whose patterns (ruleParams.be.kindPatterns) are not all in `sides.be.patterns`, and a declared
+//                         kind whose platform capabilities (the tier-platform slots that name those patterns) are not tracked are each a finding;
+//   BE_KIND_EMPTY         a kind folder `be/src/features/<kind>/` holds only instance folders `<kind>/<x>/`, and each instance holds source: a file
+//                         directly in the kind folder (a `.gitkeep`) or an instance with no TypeScript file is a finding.
+// A kind is a folder name of `be/src/features/` read from `triggerKinds` of the slot manifest (api features live in `features/api/<feature>/`);
+// `features/cli/` is the one cli feature root (its module and group folders), so it is in use as soon as it holds a file.
+import { loadSlotManifest, ruleParams } from '../slots.mjs';
+import { found } from './read.mjs';
+
+const KIND_DECLARATION = 'BE_KIND_DECLARATION';
+const KIND_EMPTY = 'BE_KIND_EMPTY';
+
+const FEATURES = 'be/src/features/';
+const CLI = 'cli';
+
+let memo;
+/** The manifest facts the rules read: the trigger kinds, the patterns each kind needs, and the platform capability folders of each pattern. */
+const facts = () => {
+  if (memo) return memo;
+  const manifest = loadSlotManifest();
+  const platform = new Map();
+  for (const slot of manifest.slots) {
+    if (slot.pattern === undefined || slot.tier !== 'platform' || !slot.profiles.includes('be')) continue;
+    const folder = /^src\/modules\/platform\/([a-z][a-z0-9-]*)\/$/.exec(slot.path);
+    if (!folder) continue;
+    if (!platform.has(slot.pattern)) platform.set(slot.pattern, []);
+    platform.get(slot.pattern).push(folder[1]);
+  }
+  memo = { triggerKinds: manifest.triggerKinds ?? [], kindPatterns: ruleParams(manifest, 'be').kindPatterns, platform };
+  return memo;
+};
+
+/** Findings of BE_KIND_DECLARATION and BE_KIND_EMPTY. */
+export function kindFindings({ files, repo }) {
+  const be = repo.sides?.be;
+  if (!be) return [];
+  const { triggerKinds, kindPatterns, platform } = facts();
+  const kindFolders = new Set(triggerKinds);
+  const findings = [];
+  const instances = new Map();
+  const sources = new Map();
+  const roots = new Set();
+  const tracked = new Set(files);
+  for (const file of files) {
+    if (!file.startsWith(FEATURES)) continue;
+    const rest = file.slice(FEATURES.length).split('/');
+    if (rest.length < 2) continue;
+    const [first, second] = rest;
+    if (!kindFolders.has(first)) continue;
+    if (first === CLI) { roots.add(CLI); continue; }
+    if (rest.length === 2) {
+      findings.push(found(KIND_EMPTY, file, `${file} sits directly in the kind folder ${FEATURES}${first}/, which holds only instance folders (${first}/<name>/); an empty kind folder is never kept: run \`starci app add\` to create the first member.`, { kind: first }));
+      continue;
+    }
+    if (!instances.has(first)) instances.set(first, new Set());
+    instances.get(first).add(second);
+    const key = `${first}/${second}`;
+    sources.set(key, (sources.get(key) ?? 0) + (/\.[cm]?tsx?$/.test(file) ? 1 : 0));
+  }
+  for (const [key, count] of sources) {
+    if (count === 0) findings.push(found(KIND_EMPTY, `${FEATURES}${key}/`, `${FEATURES}${key}/ holds no TypeScript source: a kind member without code is an empty folder; add its files with \`starci app add\` or remove the folder.`, { kind: key.split('/')[0] }));
+  }
+  const present = new Set([...instances.keys(), ...roots]);
+  const declared = new Set(be.kinds ?? []);
+  const patterns = new Set(be.patterns ?? []);
+  for (const kind of [...present].sort()) {
+    if (!declared.has(kind)) findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds does not declare the kind \`${kind}\`, which ${FEATURES}${kind}/ uses; declare every kind in use (\`starci app add\` registers it).`, { kind }));
+  }
+  for (const kind of [...declared].sort()) {
+    if (!present.has(kind)) {
+      findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds declares \`${kind}\` but no feature of that kind exists; a kind is declared only when it is used, so remove it or add its first member with \`starci app add\`.`, { kind }));
+      continue;
+    }
+    for (const pattern of kindPatterns[kind] ?? []) {
+      if (!patterns.has(pattern)) findings.push(found(KIND_DECLARATION, 'hfs.json', `the kind \`${kind}\` needs the pattern \`${pattern}\`, which hfs.json sides.be.patterns does not declare.`, { kind, pattern }));
+      for (const capability of platform.get(pattern) ?? []) {
+        if (!tracked.has(`be/src/modules/platform/${capability}/index.ts`)) findings.push(found(KIND_DECLARATION, `be/src/modules/platform/${capability}/`, `the kind \`${kind}\` needs the platform capability \`${capability}\` (pattern ${pattern}), which is not tracked at be/src/modules/platform/${capability}/; \`starci app add\` generates it with the first member of the kind.`, { kind, pattern, capability }));
+      }
+    }
+  }
+  return findings;
+}

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/lint-suppression.mjs

@@ -7,7 +7,7 @@
 // Comment-level suppression (`eslint-disable`) is the lint rule `no-inline-suppression`'s (R18).
 import { found, readJson, readText } from './read.mjs';
 
-export const LINT_SUPPRESSION_FILE = 'HFS_LINT_SUPPRESSION_FILE';
+const LINT_SUPPRESSION_FILE = 'HFS_LINT_SUPPRESSION_FILE';
 const SUPPRESSION_FILE = /(?:^|\/)eslint[.-]suppressions[^/]*$/;
 const SUPPRESSION_SCRIPT_NAME = /(?:^|:)suppressions$/;
 const SUPPRESSION_FLAG = /--(?:suppressions-location|suppress-all|suppress-rule|prune-suppressions)\b/;

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

@@ -0,0 +1,179 @@
+// monorepo.mjs - every product is a monorepo, even a single app: the app root holds one package.json and lockfile whose npm
+// workspaces are the fe apps and packages (turbo runs their tasks), and the back end is a Nest monorepo of be/apps/<app>.
+//   HFS_MONO_WORKSPACES          the root package.json: `workspaces` exactly fe/apps/* and fe/packages/*, `packageManager` npm at an
+//                                exact version, turbo a root devDependency (its version is the canon pin); turbo.json is app.task-graph
+//   HFS_MONO_FE_WORKSPACE        every fe app's package.json is @<project>/<app>, private, with exactly the workspace scripts; every
+//                                fe package's package.json is private with build and typecheck scripts and the workspace lint
+//   HFS_MONO_NEST_PROJECTS       be/nest-cli.json is `monorepo: true`, its root an api app, and one project per declared be app
+//   HFS_MONO_WORKSPACE_DEP       a package an fe workspace imports is declared in that workspace's package.json (a sibling workspace
+//                                package at "*"); the root package.json never declares a workspace package
+// The imports are read with TypeScript's own pre-processor (import, export-from, require and import() specifiers), and a
+// workspace's path aliases come from its tsconfig.json as TypeScript resolves it: no specifier is matched by a regular expression.
+import fs from 'node:fs';
+import { isBuiltin } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+const MONO_WORKSPACES = 'HFS_MONO_WORKSPACES';
+const MONO_FE_WORKSPACE = 'HFS_MONO_FE_WORKSPACE';
+const MONO_NEST_PROJECTS = 'HFS_MONO_NEST_PROJECTS';
+const MONO_WORKSPACE_DEP = 'HFS_MONO_WORKSPACE_DEP';
+
+/** The npm workspaces of every app, in this order. */
+export const WORKSPACES = Object.freeze(['fe/apps/*', 'fe/packages/*']);
+/** The lint script of every fe workspace: the one lint of the app, scoped to the workspace. */
+export const WORKSPACE_LINT = 'starci app lint --workspace .';
+/** The scripts of every fe app workspace, exactly: turbo runs build, dev, lint and typecheck; start serves a build. */
+export const FE_APP_SCRIPTS = Object.freeze({ build: 'next build', dev: 'next dev', lint: WORKSPACE_LINT, start: 'next start', typecheck: 'tsc --noEmit' });
+/** The scripts every fe package workspace has (its build and typecheck commands are its own; its lint is the workspace lint). */
+const FE_PACKAGE_SCRIPTS = Object.freeze(['build', 'typecheck', 'lint']);
+/** The package manager every app root declares (turbo reads it to parse the lockfile); the starci app scaffold writes it. */
+export const PACKAGE_MANAGER = 'npm@11.6.2';
+/** The npm name of an fe app workspace. */
+export const feAppPackageName = (project, app) => `@${project}/${app}`;
+
+const MANIFEST = 'package.json';
+const NEST_CLI = 'be/nest-cli.json';
+const PACKAGE_MANAGER_FORM = /^npm@\d+\.\d+\.\d+$/;
+const DEP_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const declaredIn = (pkg) => new Set(DEP_SECTIONS.flatMap((section) => Object.keys(pkg?.[section] ?? {})));
+const sameList = (a, b) => Array.isArray(a) && a.length === b.length && a.every((item, i) => item === b[i]);
+
+/** The workspace folders the tracked tree holds: fe/apps/<x> and fe/packages/<x> that track a package.json. */
+function workspacesOf(files) {
+  const folders = new Set();
+  for (const file of files) {
+    const parts = file.split('/');
+    if (parts.length === 4 && parts[0] === 'fe' && (parts[1] === 'apps' || parts[1] === 'packages') && parts[3] === MANIFEST) folders.add(parts.slice(0, 3).join('/'));
+  }
+  return [...folders].sort();
+}
+
+/** R143: the root package.json declares the workspaces, the package manager and turbo. */
+function rootFindings(repoRoot) {
+  const pkg = readJson(repoRoot, MANIFEST);
+  if (!pkg) return [];
+  const findings = [];
+  if (!sameList(pkg.workspaces, WORKSPACES)) findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares workspaces ${JSON.stringify(pkg.workspaces ?? null)}; every app is a monorepo whose npm workspaces are exactly ${JSON.stringify(WORKSPACES)} (each fe app and package has its own package.json; be has none).`, { workspaces: pkg.workspaces ?? null }));
+  if (!PACKAGE_MANAGER_FORM.test(String(pkg.packageManager ?? ''))) findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares packageManager ${JSON.stringify(pkg.packageManager ?? null)}; turbo needs \`npm@<exact version>\` there.`, { packageManager: pkg.packageManager ?? null }));
+  if (typeof pkg.devDependencies?.turbo !== 'string') findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} does not declare turbo in its devDependencies; the turbo task graph (turbo.json) runs build, dev, lint and typecheck over the fe workspaces.`, { missing: 'turbo' }));
+  return findings;
+}
+
+/** R144: the manifest of each fe workspace. */
+function workspaceManifestFindings(repoRoot, project, workspaces) {
+  const findings = [];
+  for (const folder of workspaces) {
+    const file = `${folder}/${MANIFEST}`;
+    const pkg = readJson(repoRoot, file);
+    if (!pkg) { findings.push(found(MONO_FE_WORKSPACE, file, `${file} is not readable JSON; an fe workspace has a package.json.`)); continue; }
+    const name = folder.split('/')[2];
+    if (pkg.private !== true) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is not \`"private": true\`; a workspace of the app is never published.`));
+    const scripts = pkg.scripts ?? {};
+    if (folder.startsWith('fe/apps/')) {
+      const expected = feAppPackageName(project, name);
+      if (pkg.name !== expected) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is named ${JSON.stringify(pkg.name ?? null)}; the fe app ${name} is the workspace ${expected}.`, { expected }));
+      const want = Object.keys(FE_APP_SCRIPTS).sort();
+      const off = [...new Set([...want, ...Object.keys(scripts)])].sort().filter((key) => scripts[key] !== FE_APP_SCRIPTS[key]);
+      if (off.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has scripts ${JSON.stringify(scripts)}; an fe app workspace has exactly ${JSON.stringify(FE_APP_SCRIPTS)} (turbo runs build, dev, lint and typecheck; differs at ${off.join(', ')}).`, { scripts: off }));
+    } else {
+      const missing = FE_PACKAGE_SCRIPTS.filter((key) => typeof scripts[key] !== 'string' || !scripts[key]);
+      if (missing.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has no ${missing.join(', ')} script; an fe package workspace builds, type-checks and lints (turbo builds it before the apps that import it).`, { scripts: missing }));
+      else if (scripts.lint !== WORKSPACE_LINT) findings.push(found(MONO_FE_WORKSPACE, file, `${file} lints with ${JSON.stringify(scripts.lint)}; a workspace lints with ${JSON.stringify(WORKSPACE_LINT)}, the one lint of the app scoped to it.`, { scripts: ['lint'] }));
+    }
+  }
+  return findings;
+}
+
+/** R145: be/nest-cli.json is the Nest monorepo of exactly the declared be apps. */
+function nestFindings(repoRoot, files, beApps) {
+  if (!files.includes(NEST_CLI)) return [];
+  const cli = readJson(repoRoot, NEST_CLI);
+  if (!cli) return [found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} is not readable JSON.`)];
+  const findings = [];
+  if (cli.monorepo !== true) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} is not \`"monorepo": true\`; the back end is a Nest monorepo of be/apps/<app>, even with one service.`));
+  const declared = beApps.map((app) => app.name).sort();
+  const projects = Object.keys(cli.projects ?? {}).sort();
+  if (!sameList(projects, declared)) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has projects ${JSON.stringify(projects)}, but hfs.json declares the be apps ${JSON.stringify(declared)}; one project per declared app, no other.`, { projects, declared }));
+  for (const name of projects.filter((project) => declared.includes(project))) {
+    const project = cli.projects[name] ?? {};
+    if (project.type !== 'application' || project.root !== `apps/${name}` || project.sourceRoot !== `apps/${name}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} project ${name} is ${JSON.stringify({ type: project.type, root: project.root, sourceRoot: project.sourceRoot })}; it is {"type":"application","root":"apps/${name}","sourceRoot":"apps/${name}/src"}.`, { project: name }));
+  }
+  const apis = beApps.filter((app) => app.kind === 'api').map((app) => app.name);
+  const rootApp = /^apps\/([^/]+)$/.exec(String(cli.root ?? ''))?.[1];
+  if (!apis.includes(rootApp) || cli.sourceRoot !== `apps/${rootApp}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has root ${JSON.stringify(cli.root ?? null)} and sourceRoot ${JSON.stringify(cli.sourceRoot ?? null)}; the default project is an api app (${apis.join(', ') || 'none declared'}): root apps/<api>, sourceRoot apps/<api>/src.`, { root: cli.root ?? null }));
+  return findings;
+}
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+/** The path-alias patterns of a workspace (its tsconfig.json as TypeScript resolves it, `extends` included): [{ prefix, exact }]. */
+function aliasesOf(ts, dir) {
+  const file = path.join(dir, 'tsconfig.json');
+  if (!fs.existsSync(file)) return [];
+  const read = ts.readConfigFile(file, ts.sys.readFile);
+  if (read.error) return [];
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dir);
+  return Object.keys(parsed.options.paths ?? {}).map((key) => (key.endsWith('*') ? { prefix: key.slice(0, -1), exact: false } : { prefix: key, exact: true }));
+}
+
+/** The npm package a bare module specifier names (`next/link` is next, `@scope/name/sub` is @scope/name). */
+const packageOf = (specifier) => {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+/** R146: what each fe workspace imports, it declares; the root declares no workspace package. */
+function workspaceDepFindings(repoRoot, files, workspaces) {
+  const findings = [];
+  const names = new Map(workspaces.map((folder) => [readJson(repoRoot, `${folder}/${MANIFEST}`)?.name, folder]).filter(([name]) => typeof name === 'string'));
+  const root = readJson(repoRoot, MANIFEST);
+  for (const name of declaredIn(root)) if (names.has(name)) findings.push(found(MONO_WORKSPACE_DEP, MANIFEST, `${MANIFEST} declares the workspace package ${name} (${names.get(name)}); the root never depends on a workspace: the fe workspace that imports it declares it.`, { dependency: name }));
+  if (!workspaces.length) return findings;
+  const ts = typescriptFor(repoRoot);
+  if (!ts) return [...findings, found(MONO_WORKSPACE_DEP, MANIFEST, 'the fe workspaces cannot be judged: no TypeScript resolves from the app; install the app\'s dependencies.', { missing: ['typescript'] })];
+  for (const folder of workspaces) {
+    const manifest = `${folder}/${MANIFEST}`;
+    const pkg = readJson(repoRoot, manifest);
+    if (!pkg) continue;
+    const declared = declaredIn(pkg);
+    const aliases = aliasesOf(ts, path.join(repoRoot, folder));
+    const isAlias = (specifier) => aliases.some((alias) => (alias.exact ? specifier === alias.prefix : specifier.startsWith(alias.prefix)));
+    const missing = new Map();
+    for (const file of files) {
+      if (!file.startsWith(`${folder}/`) || !SOURCE.test(file) || file.endsWith('.d.ts')) continue;
+      const text = readText(repoRoot, file);
+      if (text === null) continue;
+      for (const { fileName: specifier } of ts.preProcessFile(text, true, true).importedFiles) {
+        if (specifier.startsWith('.') || specifier.startsWith('/') || isBuiltin(specifier) || isAlias(specifier)) continue;
+        const name = packageOf(specifier);
+        if (declared.has(name) || name === pkg.name) continue;
+        if (!missing.has(name)) missing.set(name, file);
+      }
+    }
+    for (const [name, file] of [...missing].sort()) {
+      const sibling = names.get(name);
+      findings.push(found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${sibling ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`}.`, { dependency: name, importedBy: file }));
+    }
+  }
+  return findings;
+}
+
+/** The findings of the monorepo rules over the tracked paths `files` (app-relative) of the app at `repoRoot`. */
+export function monorepoFindings({ repoRoot, files, repo }) {
+  if (!repo?.sides) return [];
+  const workspaces = workspacesOf(files);
+  const beApps = repo.sides.be.apps;
+  return [
+    ...rootFindings(repoRoot),
+    ...workspaceManifestFindings(repoRoot, repo.project, workspaces),
+    ...nestFindings(repoRoot, files, beApps),
+    ...workspaceDepFindings(repoRoot, files, workspaces),
+  ];
+}

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/peer-integrations.mjs

@@ -8,19 +8,19 @@ import fs from 'node:fs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readJson } from './read.mjs';
 
-export const PEER_INTEGRATION_MISSING = 'HFS_PEER_INTEGRATION_MISSING';
+const PEER_INTEGRATION_MISSING = 'HFS_PEER_INTEGRATION_MISSING';
 const MANIFEST = 'package.json';
 const CATALOG_FILE = new URL('../../../knowledge/hfs/peer-integrations.yaml', import.meta.url);
 
 /** The pairs of the catalog: [{ id, when: [{ package, major? }], requires, why }]. */
-export function peerIntegrationPairs() {
+function peerIntegrationPairs() {
   const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
   if (catalog?.schema !== 'starci/hfs-peer-integrations@1' || !Array.isArray(catalog.pairs)) throw new Error('knowledge/hfs/peer-integrations.yaml is not a starci/hfs-peer-integrations@1 catalog');
   return catalog.pairs;
 }
 
 /** The major a dependency spec allows (`11.2.5`, `^11.0.0`, `~11.1`, `>=11 <12`), or null when the spec names none (a tag, a link, `*`). */
-export function majorOf(spec) {
+function majorOf(spec) {
   const match = /^\s*(?:[\^~]|>=?|=)?\s*v?(\d+)(?:\.|\s|$)/.exec(String(spec));
   return match ? Number(match[1]) : null;
 }

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/pipeline.mjs

@@ -1,19 +1,18 @@
-// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `hfs lint`; pre-push runs typecheck and lint.
-//   .github/workflows/ci.yml   a `run:` step that runs `hfs lint` (the one lint entry: eslint, the repository check, stylelint): `npx hfs lint`,
-//                              `npx @starci/hfs[@<version>] lint`, or `npm run <script>` of the root package.json whose command runs `hfs lint`
-//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the @starci/hfs pin of
+// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `starci app lint`.
+//   .github/workflows/ci.yml   a `run:` step that runs the one lint entry: `starci app lint`,
+//                              `npx @starci/cli[@<version>] app lint`, or `npm run <script>` whose command runs `starci app lint`
+//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the @starci/cli pin of
 //                              canon-pins.yaml (an installed one is pinned by the pin check, R15)
-//   .husky/pre-push            `npm run typecheck` and `npm run lint`, each on a line of its own
+//   (the push hook is no lint or typecheck step: it checks the release gate, scripts/hfs/runtime-rules/hook-shape.mjs keeps its shape)
 // A missing file is the slot manifest's finding (HFS_SLOT_REQUIRED_MISSING); a file that is present and lacks the step is this rule's.
 // The redirect of `core.hooksPath` away from husky is the architecture machine's (HFS_HOOKS_PATH_REDIRECTED).
 import { found, readJson, readText } from './read.mjs';
 
-export const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
-export const CI_FILE = '.github/workflows/ci.yml';
-export const PRE_PUSH_FILE = '.husky/pre-push';
-export const hfsPackage = '@starci/hfs';
+const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
+const CI_FILE = '.github/workflows/ci.yml';
+const hfsPackage = '@starci/cli';
 const RUN_LINE = /^\s*(?:-\s+)?run:\s*(.+?)\s*$/;
-const HFS_LINT = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/hfs|hfs)(?:@(\S+))?\s+lint(\s.*)?$/;
+const HFS_LINT = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/cli(?:@(\S+))?|starci)\s+app\s+lint(\s.*)?$/;
 const NPM_RUN = /^npm run ([\w:.-]+)(?:\s+--\s+(.*))?$/;
 
 const commandsOf = (text) => text.split(/\r?\n/).map((line) => RUN_LINE.exec(line)?.[1]).filter(Boolean).map((command) => command.replace(/^["']|["']$/g, ''));
@@ -24,8 +23,6 @@ function expanded(command, scripts) {
   return run && typeof scripts[run[1]] === 'string' ? `${scripts[run[1]]}${run[2] ? ` ${run[2]}` : ''}` : command;
 }
 
-const runsStep = (lines, step) => lines.some((line) => new RegExp(`^npm run ${step}(\\s|$)`).test(line));
-
 /** The findings of R13 over the repository at `repoRoot`; `pins` is the parsed canon-pins.yaml pin map. */
 export function pipelineFindings({ repoRoot, files, pins }) {
   const findings = [];
@@ -34,16 +31,9 @@ export function pipelineFindings({ repoRoot, files, pins }) {
   if (ci !== null) {
     const scripts = readJson(repoRoot, 'package.json')?.scripts ?? {};
     const lints = commandsOf(ci).flatMap((command) => expanded(command, scripts).split(/\s*&&\s*/)).map((command) => HFS_LINT.exec(command)).filter(Boolean);
-    if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`hfs lint\` (\`npm run lint\`, or \`npx hfs lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'hfs lint' }));
+    if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`starci app lint\` (directly or through \`npm run lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'starci app lint' }));
     else if (pinned && !lints.some((match) => match[1] === undefined || match[1] === pinned)) {
-      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs hfs lint at ${lints[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'hfs lint', pinned }));
-    }
-  }
-  const prePush = files.includes(PRE_PUSH_FILE) ? readText(repoRoot, PRE_PUSH_FILE) : null;
-  if (prePush !== null) {
-    const lines = prePush.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
-    for (const step of ['typecheck', 'lint']) {
-      if (!runsStep(lines, step)) findings.push(found(CI_MISSING_CANON, PRE_PUSH_FILE, `${PRE_PUSH_FILE} does not run \`npm run ${step}\`; pre-push runs typecheck and lint`, { step }));
+      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app lint at ${lints[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app lint', pinned }));
     }
   }
   return findings;

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/proof-commands.mjs

@@ -1,7 +1,7 @@
 // proof-commands.mjs - HFS_PROOF_COMMAND_FILE_MISSING (R105): a proof command a `.starciwork` record names runs files that exist.
 // A record's `requiresProof.<kind>.command` is "the exact command that satisfies this kind, runnable as written" (work-implementation
 // schema); a command that names a spec, a script or a config the repository does not hold cannot be run as written, and a record that
-// keeps one goes quietly false (nivo-backend, 2026-09-30: `node --test scripts/provision-keycloak.spec.mjs` after the script was deleted).
+// keeps one goes quietly false (a product repo once kept `node --test <repo>/scripts/provision-keycloak.spec.mjs` after the script was deleted).
 // Every argument of the command that is a repository-relative file path (an extension, no glob, no variable, not absolute, not a `..`
 // path into another repository) must be a tracked file or an existing one; a path an ignored slot owns (dist/, coverage/) is a build
 // product and is not judged. One finding per record, kind and missing path. The `.starciwork` of an app sits at the app root, and a
@@ -13,7 +13,7 @@ import path from 'node:path';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readText } from './read.mjs';
 
-export const PROOF_COMMAND_FILE_MISSING = 'HFS_PROOF_COMMAND_FILE_MISSING';
+const PROOF_COMMAND_FILE_MISSING = 'HFS_PROOF_COMMAND_FILE_MISSING';
 const RECORD = /^\.starciwork\/.+\.ya?ml$/;
 const FILE_ARGUMENT = /^(?:\.\/)?[\w@][\w@.\-[\]()]*(?:\/[\w@.\-[\]()]+)*\.[A-Za-z][A-Za-z0-9]{0,7}$/;
 const PATH_SEPARATOR = /\//;

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/read.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Files above this size are not read by a tree check (a tracked binary or a generated dump is no source of these laws). */
-export const MAX_READ_BYTES = 1024 * 1024;
+const MAX_READ_BYTES = 1024 * 1024;
 
 /** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
 export function readText(repoRoot, rel) {

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/repo-local-checks.mjs

@@ -9,7 +9,7 @@
 // included (HFS_RULE_OFF_WITHOUT_REPLACEMENT, R17). This rule adds the forbidden roles by name: what a check or a rule file is called.
 import { found, readJson } from './read.mjs';
 
-export const REPO_LOCAL_CHECK = 'HFS_REPO_LOCAL_CHECK';
+const REPO_LOCAL_CHECK = 'HFS_REPO_LOCAL_CHECK';
 const LOCAL_RULE_FILE = /(?:^|\/)(?:eslint-local-rules|eslint-plugin|eslint-local-plugin)[^/]*(?:\/|$)|(?:^|\/)(?:eslint-rules|lint-rules)\//;
 const CHECK_SCRIPT = /(?:^|\/)(?:scripts|tools)\/check-[^/]+$/;
 const RUNS_CHECK = /(?:^|[\s&|;(])(?:\.\/)?(?:scripts|tools)\/check-[^\s&|;)]+/;
@@ -20,7 +20,7 @@ export function repoLocalCheckFindings({ repoRoot, files }) {
   for (const file of files) {
     if (file.includes('node_modules/')) continue;
     if (LOCAL_RULE_FILE.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a local lint rule or plugin; a repository keeps no rule of its own: the rule is proposed to the canon (@starci/eslint-canon-*) in the .claude runtime`));
-    else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (hfs check, the canons), so a repository has none to keep`));
+    else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (starci app check, the canons), so a repository has none to keep`));
     else if (file === 'package.json' || file.endsWith('/package.json')) {
       const pkg = readJson(repoRoot, file);
       for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {