@starci/hfs 4.11.21 → 4.12.0

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

@@ -16,12 +16,10 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readJson, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.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. */
@@ -34,196 +32,213 @@ const FE_PACKAGE_SCRIPTS = Object.freeze(['build', 'typecheck', 'lint']);
 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(byCodeUnit);
+    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(byCodeUnit);
 }
-
 /** 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;
+    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 appWorkspaceScriptFindings(file, project, name, pkg, scripts) {
-  const findings = [];
-  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(byCodeUnit);
-  const off = [...new Set([...want, ...Object.keys(scripts)])].sort(byCodeUnit).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 }));
-  return findings;
+    const findings = [];
+    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(byCodeUnit);
+    const off = [...new Set([...want, ...Object.keys(scripts)])].sort(byCodeUnit).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 }));
+    return findings;
 }
-
 function packageWorkspaceScriptFindings(file, scripts) {
-  const findings = [];
-  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;
+    const findings = [];
+    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;
 }
-
 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/')) findings.push(...appWorkspaceScriptFindings(file, project, name, pkg, scripts));
-    else findings.push(...packageWorkspaceScriptFindings(file, scripts));
-  }
-  return findings;
+    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/'))
+            findings.push(...appWorkspaceScriptFindings(file, project, name, pkg, scripts));
+        else
+            findings.push(...packageWorkspaceScriptFindings(file, scripts));
+    }
+    return findings;
 }
-
 const nestProjectShape = (project) => JSON.stringify({ type: project.type, root: project.root, sourceRoot: project.sourceRoot });
-
 /** One finding per declared project whose type, root or sourceRoot departs from the application layout. */
 function nestProjectFindings(cli, projects, declared) {
-  const findings = [];
-  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 ${nestProjectShape(project)}; it is {"type":"application","root":"apps/${name}","sourceRoot":"apps/${name}/src"}.`, { project: name }));
-  }
-  return findings;
+    const findings = [];
+    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 ${nestProjectShape(project)}; it is {"type":"application","root":"apps/${name}","sourceRoot":"apps/${name}/src"}.`, { project: name }));
+    }
+    return findings;
 }
-
 /** The finding when the default project of nest-cli.json is no declared api app, or null. */
 function nestRootFinding(cli, beApps) {
-  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`) return null;
-  return 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 });
+    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`)
+        return null;
+    return 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 });
 }
-
 /** 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(byCodeUnit);
-  const projects = Object.keys(cli.projects ?? {}).sort(byCodeUnit);
-  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 }));
-  findings.push(...nestProjectFindings(cli, projects, declared));
-  const rootFinding = nestRootFinding(cli, beApps);
-  if (rootFinding) findings.push(rootFinding);
-  return findings;
+    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(byCodeUnit);
+    const projects = Object.keys(cli.projects ?? {}).sort(byCodeUnit);
+    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 }));
+    findings.push(...nestProjectFindings(cli, projects, declared));
+    const rootFinding = nestRootFinding(cli, beApps);
+    if (rootFinding)
+        findings.push(rootFinding);
+    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 }));
+    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];
+    const parts = specifier.split('/');
+    return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
 };
-
 /** Records the first importing file of every package `file` imports without the workspace declaring it. */
 function collectUndeclaredImports(ts, file, text, isAlias, pkg, declared, missing) {
-  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 { 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);
+    }
 }
-
 /** The first importing file of every undeclared package a workspace's sources import, by package name. */
 function undeclaredImports(repoRoot, files, folder, pkg, declared, ts) {
-  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) collectUndeclaredImports(ts, file, text, isAlias, pkg, declared, missing);
-  }
-  return missing;
+    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)
+            collectUndeclaredImports(ts, file, text, isAlias, pkg, declared, missing);
+    }
+    return missing;
 }
-
 function workspaceMissingDependencies(repoRoot, files, folder, names, ts) {
-  const manifest = `${folder}/${MANIFEST}`;
-  const pkg = readJson(repoRoot, manifest);
-  if (!pkg) return [];
-  const missing = undeclaredImports(repoRoot, files, folder, pkg, declaredIn(pkg), ts);
-  const findings = [...missing].sort(byCodeUnit).map(([name, file]) => {
-    const declaration = names.get(name) ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`;
-    return found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${declaration}.`, { dependency: name, importedBy: file });
-  });
-  return [...findings, ...workspaceVersionFindings(manifest, pkg, names)];
+    const manifest = `${folder}/${MANIFEST}`;
+    const pkg = readJson(repoRoot, manifest);
+    if (!pkg)
+        return [];
+    const missing = undeclaredImports(repoRoot, files, folder, pkg, declaredIn(pkg), ts);
+    const findings = [...missing].sort(byCodeUnit).map(([name, file]) => {
+        const declaration = names.get(name) ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`;
+        return found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${declaration}.`, { dependency: name, importedBy: file });
+    });
+    return [...findings, ...workspaceVersionFindings(manifest, pkg, names)];
 }
-
 /** Every declaration of a sibling workspace uses npm's local workspace version, in every dependency section. */
 function workspaceVersionFindings(manifest, pkg, names) {
-  const findings = [];
-  for (const section of DEP_SECTIONS) {
-    for (const [name, version] of Object.entries(pkg[section] ?? {})) {
-      if (!names.has(name) || name === pkg.name || version === '*') continue;
-      findings.push(found(MONO_WORKSPACE_DEP, manifest, `${manifest} declares sibling workspace ${name} as ${JSON.stringify(version)} in ${section}; declare the workspace package as "*".`, { dependency: name, section, version }));
+    const findings = [];
+    for (const section of DEP_SECTIONS) {
+        for (const [name, version] of Object.entries(pkg[section] ?? {})) {
+            if (!names.has(name) || name === pkg.name || version === '*')
+                continue;
+            findings.push(found(MONO_WORKSPACE_DEP, manifest, `${manifest} declares sibling workspace ${name} as ${JSON.stringify(version)} in ${section}; declare the workspace package as "*".`, { dependency: name, section, version }));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 /** 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) findings.push(...workspaceMissingDependencies(repoRoot, files, folder, names, ts));
-  return findings;
+    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)
+        findings.push(...workspaceMissingDependencies(repoRoot, files, folder, names, ts));
+    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),
-  ];
+    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/hfs/rules/peer-integrations.d.mts

@@ -0,0 +1,7 @@
+import type { Parsed } from './rule-types.mjs';
+/** The findings of R111 over the app root package.json of `repoRoot`; `pairs` defaults to the catalog. */
+export declare function peerIntegrationFindings({ repoRoot, files, pairs }: {
+    repoRoot: string;
+    files: string[];
+    pairs?: Parsed;
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/peer-integrations.mjs

@@ -7,59 +7,62 @@
 import fs from 'node:fs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readJson } from './read.mjs';
-
 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);
 const WHITESPACE = /\s/;
 const isDigit = (char) => char >= '0' && char <= '9';
-
 /** The index of the first non-whitespace character of `text` at or after `from`. */
 function skipWhitespace(text, from) {
-  let index = from;
-  while (index < text.length && WHITESPACE.test(text[index])) index += 1;
-  return index;
+    let index = from;
+    while (index < text.length && WHITESPACE.test(text[index]))
+        index += 1;
+    return index;
 }
-
 /** The index after an optional range operator (`^`, `~`, `>`, `>=`, `=`) at `from`. */
 function skipOperator(text, from) {
-  if (text[from] === '>') return text[from + 1] === '=' ? from + 2 : from + 1;
-  return text[from] === '^' || text[from] === '~' || text[from] === '=' ? from + 1 : from;
+    if (text[from] === '>')
+        return text[from + 1] === '=' ? from + 2 : from + 1;
+    return text[from] === '^' || text[from] === '~' || text[from] === '=' ? from + 1 : from;
 }
-
 /** The pairs of the catalog: [{ id, when: [{ package, major? }], requires, why }]. */
 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;
+    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, `*`). */
 function majorOf(spec) {
-  const text = String(spec);
-  let index = skipWhitespace(text, skipOperator(text, skipWhitespace(text, 0)));
-  if (text[index] === 'v') index += 1;
-  const digits = index;
-  while (isDigit(text[index] ?? '')) index += 1;
-  if (index === digits) return null;
-  const next = text[index];
-  return next === undefined || next === '.' || WHITESPACE.test(next) ? Number(text.slice(digits, index)) : null;
+    const text = String(spec);
+    let index = skipWhitespace(text, skipOperator(text, skipWhitespace(text, 0)));
+    if (text[index] === 'v')
+        index += 1;
+    const digits = index;
+    while (isDigit(text[index] ?? ''))
+        index += 1;
+    if (index === digits)
+        return null;
+    const next = text[index];
+    return next === undefined || next === '.' || WHITESPACE.test(next) ? Number(text.slice(digits, index)) : null;
 }
-
 /** The findings of R111 over the app root package.json of `repoRoot`; `pairs` defaults to the catalog. */
 export function peerIntegrationFindings({ repoRoot, files, pairs = peerIntegrationPairs() }) {
-  if (!files.includes(MANIFEST)) return [];
-  const pkg = readJson(repoRoot, MANIFEST);
-  if (!pkg) return [];
-  const runtime = pkg.dependencies ?? {};
-  const declared = { ...pkg.devDependencies, ...runtime };
-  const findings = [];
-  for (const pair of pairs) {
-    const applies = pair.when.every((entry) => typeof declared[entry.package] === 'string' && (entry.major === undefined || majorOf(declared[entry.package]) === entry.major));
-    if (!applies || typeof runtime[pair.requires] === 'string') continue;
-    const because = pair.when.map((entry) => `${entry.package} ${declared[entry.package]}`).join(' with ');
-    const where = typeof declared[pair.requires] === 'string' ? ` (it is only a devDependency, which a production install omits)` : '';
-    findings.push(found(PEER_INTEGRATION_MISSING, MANIFEST, `${MANIFEST} depends on ${because} but does not declare ${pair.requires} in its dependencies${where}: ${pair.why.trim()} Add ${pair.requires} to the dependencies.`, { pair: pair.id, requires: pair.requires }));
-  }
-  return findings;
+    if (!files.includes(MANIFEST))
+        return [];
+    const pkg = readJson(repoRoot, MANIFEST);
+    if (!pkg)
+        return [];
+    const runtime = pkg.dependencies ?? {};
+    const declared = { ...pkg.devDependencies, ...runtime };
+    const findings = [];
+    for (const pair of pairs) {
+        const applies = pair.when.every((entry) => typeof declared[entry.package] === 'string' && (entry.major === undefined || majorOf(declared[entry.package]) === entry.major));
+        if (!applies || typeof runtime[pair.requires] === 'string')
+            continue;
+        const because = pair.when.map((entry) => `${entry.package} ${declared[entry.package]}`).join(' with ');
+        const where = typeof declared[pair.requires] === 'string' ? ` (it is only a devDependency, which a production install omits)` : '';
+        findings.push(found(PEER_INTEGRATION_MISSING, MANIFEST, `${MANIFEST} depends on ${because} but does not declare ${pair.requires} in its dependencies${where}: ${pair.why.trim()} Add ${pair.requires} to the dependencies.`, { pair: pair.id, requires: pair.requires }));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/pipeline.d.mts

@@ -0,0 +1,7 @@
+import type { Parsed } from './rule-types.mjs';
+/** The findings of R13 over the repository at `repoRoot`; `pins` is the canon pin map (canon-pins.mjs). */
+export declare function pipelineFindings({ repoRoot, files, pins }: {
+    repoRoot: string;
+    files: string[];
+    pins: Parsed;
+}): import("./rule-types.mjs").Finding[];