@starci/hfs 1.0.1 → 2.0.1

package/runtime/scripts/checks/architecture/typescript.mjs

@@ -0,0 +1,500 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { canonical, isInside, slash } from './config.mjs';
+import { sameOrUnder } from '../../lib/path-key.mjs';
+import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
+import { readJsonFile } from '../../lib/json.mjs';
+
+const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
+const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;
+const ASSET_EXTENSION = /\.(?:css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|ya?ml|json)$/i;
+// Framework build output a tsconfig may include (Next writes `.next/types/**/*.ts` back into tsconfig.json on
+// every build) is compiled for type resolution but is never source: it is gitignored, regenerated, and no
+// canon or architecture rule applies to it (starci-next inc-2260b3754afa, nivo inc-ffe60c49f502).
+export const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.output', '.nuxt', '.svelte-kit', '.expo', '.docusaurus', '.swc', '.cache']);
+export function isGeneratedPath(root, fileName) {
+  return slash(path.relative(root, fileName)).split('/').slice(0, -1).some(segment => GENERATED_SEGMENTS.has(segment));
+}
+// A `<tool>.config.*` or `<tool>.setup.*` module beside a package manifest (next.config.ts,
+// postcss.config.mjs) is build tooling a broad `**/*.ts` include pulls in; a `*.config.ts` inside a source tree
+// (src/config/database.config.ts) has no manifest beside it and stays source. The architecture program still
+// reads tooling modules (a profile may declare one as source); check-scoped-lint does not make one a canon
+// lint subject unless the profile's sourceGlobs name it.
+const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
+export function isToolingModule(fileName) {
+  return TOOLING_MODULE.test(path.basename(fileName)) && fs.existsSync(path.join(path.dirname(fileName), 'package.json'));
+}
+
+function diagnosticMessage(ts, diagnostic) {
+  return ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+}
+
+function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_INVALID') {
+  const fileName = diagnostic.file?.fileName;
+  let line;
+  let column;
+  if (diagnostic.file && Number.isInteger(diagnostic.start)) {
+    const point = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+    line = point.line + 1;
+    column = point.character + 1;
+  }
+  return {
+    ruleId,
+    project,
+    ...(fileName && isInside(root, fileName) ? { path: slash(path.relative(root, fileName)) } : {}),
+    ...(line ? { line, column } : {}),
+    message: diagnosticMessage(ts, diagnostic),
+  };
+}
+
+/** Load TypeScript through the target package boundary, never through StarCi's own dependency graph. */
+export function loadTargetTypeScript(repositoryRoot) {
+  const packageFile = path.join(repositoryRoot, 'package.json');
+  if (!fs.existsSync(packageFile)) throw Error('ARCH_TYPESCRIPT_MISSING: target package.json is required to resolve target-installed TypeScript.');
+  const targetRequire = createRequire(packageFile);
+  let resolved;
+  let ts;
+  try {
+    resolved = targetRequire.resolve('typescript');
+    ts = targetRequire('typescript');
+  } catch {
+    throw Error('ARCH_TYPESCRIPT_MISSING: install TypeScript in the checked repository; StarCi does not substitute its own parser.');
+  }
+  if (!ts?.createProgram || !ts?.resolveModuleName || !ts?.readConfigFile) {
+    throw Error('ARCH_TYPESCRIPT_INVALID: the target TypeScript package does not expose the compiler API.');
+  }
+  return { ts, resolved, version: String(ts.version ?? 'unknown') };
+}
+
+const readJson = (file) => readJsonFile(file, {});
+
+function pathAliasMatches(specifier, paths = {}) {
+  return Object.keys(paths).some(pattern => {
+    if (!pattern.includes('*')) return pattern === specifier;
+    const [before, after] = pattern.split('*');
+    return specifier.startsWith(before) && specifier.endsWith(after ?? '');
+  });
+}
+
+function runtimeImport(ts, node) {
+  if (ts.isImportDeclaration(node)) {
+    const clause = node.importClause;
+    if (!clause) return true;
+    if (clause.isTypeOnly) return false;
+    if (clause.name) return true;
+    const named = clause.namedBindings;
+    if (named && ts.isNamedImports(named)) return named.elements.some(element => !element.isTypeOnly);
+    return Boolean(named);
+  }
+  if (ts.isExportDeclaration(node)) {
+    if (node.isTypeOnly) return false;
+    if (node.exportClause && ts.isNamedExports(node.exportClause)) return node.exportClause.elements.some(element => !element.isTypeOnly);
+  }
+  return true;
+}
+
+function isUnshadowedCommonJsRequire(ts, checker, expression) {
+  if (!ts.isIdentifier(expression) || expression.text !== 'require') return false;
+  const symbol = checker?.getSymbolAtLocation(expression);
+  if (!symbol) return true;
+  const declarations = symbol.getDeclarations?.() ?? [];
+  return declarations.length > 0 && declarations.every(declaration => declaration.getSourceFile().isDeclarationFile);
+}
+
+/**
+ * The files a template-literal import of data can load. import(`../messages/${locale}.json`) - the
+ * next-intl request config - is bundled as a context of every file under ../messages whose name ends in
+ * .json, so that set is the dependency, exactly and statically. Only a relative static head naming an
+ * existing directory and a data-asset extension tail qualify; code never does, since a context of code would
+ * be an import graph nobody wrote down. Returns the specifiers, or null when the import stays unproven.
+ */
+export function assetContextSpecifiers(ts, sourceFile, argument) {
+  if (!argument || !ts.isTemplateExpression(argument)) return null;
+  const head = argument.head.text;
+  const spans = argument.templateSpans;
+  const tail = spans[spans.length - 1].literal.text;
+  if (!/^\.\.?\//.test(head) || !head.endsWith('/') || !/^\.[a-z0-9]+$/i.test(tail) || !ASSET_EXTENSION.test(tail)) return null;
+  if (spans.slice(0, -1).some(span => span.literal.text.split('/').includes('..'))) return null;
+  const directory = path.resolve(path.dirname(sourceFile.fileName), head);
+  let stat;
+  try { stat = fs.statSync(directory); } catch { return null; }
+  if (!stat.isDirectory()) return null;
+  const specifiers = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name === 'node_modules') continue;
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith(tail.toLowerCase())) specifiers.push(`${head}${slash(path.relative(directory, absolute))}`);
+    }
+  };
+  visit(directory);
+  return specifiers.length ? specifiers : null;
+}
+
+function moduleReferences(ts, sourceFile, checker) {
+  const found = [];
+  const unproven = [];
+  const visit = node => {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      found.push({ node: node.moduleSpecifier, specifier: node.moduleSpecifier.text, runtime: runtimeImport(ts, node), declaration: node });
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)
+      && node.moduleReference.expression && ts.isStringLiteralLike(node.moduleReference.expression)) {
+      found.push({ node: node.moduleReference.expression, specifier: node.moduleReference.expression.text, runtime: !node.isTypeOnly, declaration: node });
+    } else if (ts.isImportTypeNode(node)) {
+      const literal = ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal) ? node.argument.literal : null;
+      if (literal) found.push({ node: literal, specifier: literal.text, runtime: false, declaration: node });
+      else unproven.push({ node, kind: 'TypeScript import type' });
+    } else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const context = [1, 2].includes(node.arguments.length) ? assetContextSpecifiers(ts, sourceFile, node.arguments[0]) : null;
+      if ([1, 2].includes(node.arguments.length) && ts.isStringLiteralLike(node.arguments[0])) {
+        found.push({ node: node.arguments[0], specifier: node.arguments[0].text, runtime: true, declaration: node });
+      } else if (context) {
+        for (const specifier of context) found.push({ node: node.arguments[0], specifier, runtime: true, declaration: node });
+      } else unproven.push({ node, kind: 'dynamic import()' });
+    } else if (ts.isCallExpression(node) && isUnshadowedCommonJsRequire(ts, checker, node.expression)) {
+      if (node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])) {
+        found.push({ node: node.arguments[0], specifier: node.arguments[0].text, runtime: true, declaration: node });
+      } else unproven.push({ node, kind: 'dynamic require()' });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return { found, unproven };
+}
+
+function sourceLocation(sourceFile, node) {
+  const point = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { line: point.line + 1, column: point.character + 1 };
+}
+
+function isProductionSource(root, sourceFile) {
+  return isInside(root, sourceFile.fileName)
+    && CODE_EXTENSIONS.test(sourceFile.fileName)
+    && !sourceFile.isDeclarationFile
+    && !TEST_FILE.test(sourceFile.fileName)
+    && !slash(sourceFile.fileName).includes('/node_modules/')
+    && !isGeneratedPath(root, sourceFile.fileName);
+}
+
+function workspaceMetadata(config) {
+  const backendAppRoots = config.backend.apps.map(item => path.join(config.root, ...item.split('/')));
+  const create = relative => {
+    const root = path.join(config.root, ...relative.split('/'));
+    const pkg = readJson(path.join(root, 'package.json'));
+    const routeRoots = config.frontend.routes.map(item => path.join(config.root, ...item.split('/')));
+    return { root: canonical(root), relative, name: typeof pkg.name === 'string' ? pkg.name : null, exports: pkg.exports,
+      app: routeRoots.some(route => isInside(root, route))
+        || backendAppRoots.some(appRoot => isInside(appRoot, root) || isInside(root, appRoot)) };
+  };
+  const roots = config.workspaces.map(create);
+  const rootPackage = readJson(path.join(config.root, 'package.json'));
+  roots.push({ root: canonical(config.root), relative: '.', name: typeof rootPackage.name === 'string' ? rootPackage.name : null, exports: rootPackage.exports,
+    app: config.frontend.routes.some(item => isInside(config.root, path.join(config.root, ...item.split('/')))) || config.kinds.includes('backend') });
+  return roots.sort((a, b) => b.root.length - a.root.length);
+}
+
+function workspaceOf(workspaces, file) {
+  return workspaces.find(workspace => isInside(workspace.root, file)) ?? null;
+}
+
+function exportPatternCapture(pattern, request) {
+  if (!pattern.includes('*')) return pattern === request ? '' : null;
+  const [before, after = ''] = pattern.split('*');
+  return request.startsWith(before) && request.endsWith(after) ? request.slice(before.length, request.length - after.length) : null;
+}
+
+function exportTargetStrings(value) {
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value)) return value.flatMap(exportTargetStrings);
+  if (value && typeof value === 'object' && !Object.keys(value).some(key => key.startsWith('.'))) return Object.values(value).flatMap(exportTargetStrings);
+  return [];
+}
+
+function packageExported(workspace, specifier, actualTarget) {
+  if (!workspace.name || !sameOrUnder(specifier, workspace.name)) return false;
+  const request = specifier === workspace.name ? '.' : `.${specifier.slice(workspace.name.length)}`;
+  const declaration = workspace.exports;
+  let candidates = [];
+  if (typeof declaration === 'string' || Array.isArray(declaration)) {
+    if (request !== '.') return false;
+    candidates = exportTargetStrings(declaration);
+  } else if (declaration && typeof declaration === 'object') {
+    const keys = Object.keys(declaration);
+    if (!keys.some(key => key.startsWith('.'))) {
+      if (request !== '.') return false;
+      candidates = exportTargetStrings(declaration);
+    } else {
+      for (const key of keys) {
+        const capture = exportPatternCapture(key, request);
+        if (capture !== null) candidates.push(...exportTargetStrings(declaration[key]).map(target => target.replaceAll('*', capture)));
+      }
+    }
+  }
+  return candidates.some(target => {
+    if (!target.startsWith('./') || target.includes('..')) return false;
+    const expected = canonical(path.resolve(workspace.root, target));
+    return expected === canonical(actualTarget);
+  });
+}
+
+function boundaryViolation(root, edge, fromWorkspace, toWorkspace, ruleId, message) {
+  return {
+    ruleId,
+    path: relativePath(root, edge.from),
+    line: edge.line,
+    column: edge.column,
+    specifier: edge.specifier,
+    resolvedPath: relativePath(root, edge.to),
+    message,
+    fromPackage: fromWorkspace?.name ?? fromWorkspace?.relative,
+    toPackage: toWorkspace?.name ?? toWorkspace?.relative,
+  };
+}
+
+/** Parse configured tsconfigs, then build only selected programs and their project-reference closure. */
+export function buildTypeScriptContext(config, injectedTypeScript, paths = []) {
+  const loaded = injectedTypeScript ? { ts: injectedTypeScript, resolved: '(injected test compiler)', version: String(injectedTypeScript.version) }
+    : loadTargetTypeScript(config.root);
+  // config.hfs is the opened slot resolver (functions), so it never keys a shared value: the repository declaration it was opened
+  // from (plain data) identifies it, the manifest being the runtime's one.
+  const context = sharedInProgramRun('architecture-context', loaded.ts, { config: { ...config, hfs: config.hfs?.repo ?? null }, paths }, () => typeScriptContext(config, loaded, paths));
+  // Callers add to and sort the errors: each gets its own list.
+  return { ...context, errors: [...context.errors] };
+}
+
+function typeScriptContext(config, loaded, paths) {
+  const { ts } = loaded;
+  const errors = [];
+  const projects = [];
+  const parsedProjects = new Map();
+  const invalidProjects = new Set();
+  const queue = [...config.projects];
+  const seenProjects = new Set();
+  while (queue.length) {
+    const relative = queue.shift();
+    if (seenProjects.has(relative)) continue;
+    seenProjects.add(relative);
+    const configFile = path.join(config.root, ...relative.split('/'));
+    if (!fs.existsSync(configFile)) {
+      errors.push({ ruleId: 'ARCH_TSCONFIG_MISSING', project: relative, message: `${relative} does not exist.` });
+      invalidProjects.add(relative);
+      continue;
+    }
+    const { read, parsed } = readTypeScriptProject(ts, configFile);
+    if (read.error) {
+      errors.push(compilerError(ts, config.root, read.error, relative));
+      invalidProjects.add(relative);
+      continue;
+    }
+    if (parsed.errors.length) {
+      errors.push(...parsed.errors.map(item => compilerError(ts, config.root, item, relative)));
+      invalidProjects.add(relative);
+      continue;
+    }
+    for (const reference of parsed.projectReferences ?? []) {
+      const referencedFile = typeScriptProjectReferencePath(ts, reference);
+      const absoluteReference = path.resolve(referencedFile);
+      if (!isInside(config.root, absoluteReference)) {
+        errors.push({ ruleId: 'ARCH_TSCONFIG_REFERENCE_OUTSIDE', project: relative, message: `Project reference leaves the repository: ${slash(path.relative(config.root, absoluteReference))}.` });
+      } else {
+        queue.push(slash(path.relative(config.root, absoluteReference)));
+      }
+    }
+    parsedProjects.set(relative, parsed);
+  }
+  const matches = file => paths.some(prefix => {
+    const relative = slash(path.relative(config.root, file));
+    const normalized = slash(prefix).replace(/\/$/, '');
+    return sameOrUnder(relative, normalized);
+  });
+  const selected = new Set();
+  const direct = new Set();
+  if (paths.length) {
+    // TypeScript follows imports from these root files. Referenced projects need their declared
+    // roots as well, since a project reference need not be an import in the selected source.
+    const visit = relative => {
+      if (selected.has(relative)) return;
+      selected.add(relative);
+      for (const reference of parsedProjects.get(relative)?.projectReferences ?? []) {
+        const referencedFile = typeScriptProjectReferencePath(ts, reference);
+        const referenced = slash(path.relative(config.root, path.resolve(referencedFile)));
+        if (parsedProjects.has(referenced)) visit(referenced);
+      }
+    };
+    for (const [relative, parsed] of parsedProjects) if (parsed.fileNames.some(matches)) {
+      direct.add(relative);
+      visit(relative);
+    }
+    for (const relative of invalidProjects) {
+      const directory = path.dirname(path.join(config.root, ...relative.split('/')));
+      if (paths.some(prefix => {
+        const absolute = path.join(config.root, ...slash(prefix).split('/'));
+        return isInside(directory, absolute);
+      })) selected.add(relative);
+    }
+    errors.splice(0, errors.length, ...errors.filter(error => !error.project || selected.has(error.project)));
+  }
+  for (const [relative, parsed] of parsedProjects) {
+    if (paths.length && !selected.has(relative)) continue;
+    const rootNames = paths.length && direct.has(relative) ? parsed.fileNames.filter(matches) : parsed.fileNames;
+    const program = createTypeScriptProgram(ts, { rootNames, options: parsed.options, projectReferences: parsed.projectReferences });
+    errors.push(...program.getSyntacticDiagnostics().filter(item => !item.file || isInside(config.root, item.file.fileName))
+      .map(item => compilerError(ts, config.root, item, relative, 'ARCH_SYNTAX_INVALID')));
+    projects.push({ relative, program, options: parsed.options });
+  }
+  const fileMap = new Map();
+  const checkerByFile = new Map();
+  const occurrences = new Map();
+  for (const project of projects) {
+    for (const sourceFile of project.program.getSourceFiles().filter(file => isProductionSource(config.root, file))) {
+      const name = canonical(sourceFile.fileName);
+      if (!fileMap.has(name)) {
+        fileMap.set(name, sourceFile);
+        checkerByFile.set(name, project.program.getTypeChecker());
+      }
+      if (!occurrences.has(name)) occurrences.set(name, []);
+      occurrences.get(name).push(project);
+    }
+  }
+  const files = [...fileMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, file]) => file);
+  const edges = new Map([...fileMap.keys()].map(file => [file, []]));
+  for (const [file, sourceFile] of fileMap) {
+    const sourceName = path.resolve(sourceFile.fileName);
+    if (sourceName !== file) edges.set(sourceName, edges.get(file));
+  }
+  const edgeKeys = new Set();
+  const host = { ...ts.sys, fileExists: ts.sys.fileExists, readFile: ts.sys.readFile, realpath: ts.sys.realpath };
+  const workspaces = workspaceMetadata(config);
+  const workspaceNames = new Set(workspaces.map(item => item.name).filter(Boolean));
+  for (const [from, sourceFile] of fileMap) {
+    const owningWorkspace = workspaceOf(workspaces, from);
+    const candidates = occurrences.get(from) ?? [];
+    // The deepest project directory holding the file owns its resolution: a root tsconfig without paths must not
+    // shadow the app project whose aliases the file actually uses.
+    const project = candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), from))
+      .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+    if (!project) continue;
+    const references = moduleReferences(ts, sourceFile, project.program.getTypeChecker());
+    for (const item of references.unproven) errors.push({
+      ruleId: 'ARCH_DYNAMIC_DEPENDENCY_UNPROVEN',
+      project: project.relative,
+      path: relativePath(config.root, sourceFile.fileName),
+      ...sourceLocation(sourceFile, item.node),
+      message: `${item.kind} must use a string-literal module name so architecture coverage can resolve its dependency.`,
+    });
+    for (const reference of references.found) {
+      const resolvedName = resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host);
+      if (!resolvedName) {
+        const codeLike = !ASSET_EXTENSION.test(reference.specifier);
+        const workspaceImport = [...workspaceNames].some(name => sameOrUnder(reference.specifier, name));
+        const internal = reference.specifier.startsWith('.') || pathAliasMatches(reference.specifier, project.options.paths) || workspaceImport;
+        if (codeLike && internal) {
+          errors.push({
+            ruleId: 'ARCH_INTERNAL_IMPORT_UNRESOLVED',
+            project: project.relative,
+            path: relativePath(config.root, sourceFile.fileName),
+            ...sourceLocation(sourceFile, reference.node),
+            specifier: reference.specifier,
+            message: `Internal import ${reference.specifier} is not resolvable with ${project.relative}.`,
+          });
+        }
+        continue;
+      }
+      const actualTarget = canonical(resolvedName);
+      const workspaceImport = [...workspaceNames].some(name => reference.specifier === name || reference.specifier.startsWith(`${name}/`));
+      const internal = reference.specifier.startsWith('.') || pathAliasMatches(reference.specifier, project.options.paths) || workspaceImport;
+      // The boundary is the checkout, not the checked project: a path alias that lands in a sibling
+      // package of the same repository (`@fe-kit/*` -> packages/fe-kit) is still source a reviewer can
+      // open, while anything past the repository, or anything inside an installed dependency tree, is
+      // not. `config.repository` is null when there is no git checkout around the project, and the
+      // project is then the boundary it always was.
+      const reviewable = isInside(config.root, actualTarget)
+        || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
+      if (internal && !reviewable) {
+        errors.push({
+          ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
+          project: project.relative,
+          path: relativePath(config.root, sourceFile.fileName),
+          ...sourceLocation(sourceFile, reference.node),
+          specifier: reference.specifier,
+          message: `Internal import ${reference.specifier} resolves outside the checked repository.`,
+        });
+        continue;
+      }
+      if (!fileMap.has(actualTarget)) continue;
+      const edge = {
+        from,
+        to: actualTarget,
+        runtime: reference.runtime,
+        specifier: reference.specifier,
+        node: reference.node,
+        declaration: reference.declaration,
+        reexport: ts.isExportDeclaration(reference.declaration),
+        sourceFile,
+        project: project.relative,
+        ...sourceLocation(sourceFile, reference.node),
+      };
+      const key = `${from}\0${actualTarget}\0${reference.node.getStart(sourceFile)}\0${reference.specifier}`;
+      if (!edgeKeys.has(key)) { edges.get(from).push(edge); edgeKeys.add(key); }
+      const targetWorkspace = workspaceOf(workspaces, actualTarget);
+      if (owningWorkspace && targetWorkspace && owningWorkspace !== targetWorkspace) {
+        if (!owningWorkspace.app && targetWorkspace.app) {
+          errors.push(boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_IMPORTS_APP', 'A reusable workspace package cannot depend on an application workspace.'));
+        }
+        if (!packageExported(targetWorkspace, reference.specifier, actualTarget)) {
+          errors.push(boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_EXPORT_BYPASS', 'Cross-package imports must use the target package name and a declared package export.'));
+        }
+      }
+    }
+  }
+  if (projects.length && files.length === 0) errors.push({ ruleId: 'ARCH_NO_SOURCE', message: 'The configured TypeScript projects contain no production TypeScript or JavaScript source.' });
+  return { loaded, errors, files, edges, programs: projects.map(item => item.program), program: projects[0]?.program ?? null, projects, ts, workspaces,
+    checkerFor: file => checkerByFile.get(canonical(file)) ?? null,
+    workspaceOf: file => workspaceOf(workspaces, canonical(file)) };
+}
+
+export function relativePath(root, fileName) {
+  return slash(path.relative(root, fileName));
+}
+
+export function reachableViolation(edges, firstEdge, forbidden, { follow = () => true } = {}) {
+  const queue = [{ file: firstEdge.to, chain: [firstEdge.from, firstEdge.to] }];
+  const visited = new Set();
+  while (queue.length) {
+    const current = queue.shift();
+    if (visited.has(current.file)) continue;
+    visited.add(current.file);
+    if (forbidden(current.file)) return current.chain;
+    for (const edge of edges.get(current.file) ?? []) if (follow(edge)) queue.push({ file: edge.to, chain: [...current.chain, edge.to] });
+  }
+  return null;
+}
+
+/** A framework identity the checkers cannot prove statically. */
+export const UNPROVEN_FRAMEWORK = '(unproven framework identity)';
+
+/** The expression under parentheses, type assertions, non-null and satisfies wrappers. */
+export function unwrapExpression(ts, expression) {
+  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || ts.isTypeAssertionExpression(expression) || ts.isNonNullExpression(expression)
+    || (ts.isSatisfiesExpression?.(expression) ?? false))) expression = expression.expression;
+  return expression;
+}
+
+/** The names of `expected` an import or re-export statement binds (all of them for a namespace or star form). */
+export function referencedExports(ts, statement, expected) {
+  if (ts.isImportDeclaration(statement)) {
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || ts.isNamespaceImport(bindings)) return bindings ? [...expected] : [];
+    return bindings.elements.map(element => element.propertyName?.text ?? element.name.text).filter(name => expected.has(name));
+  }
+  if (ts.isExportDeclaration(statement)) {
+    if (!statement.exportClause || ts.isNamespaceExport(statement.exportClause)) return [...expected];
+    return statement.exportClause.elements.map(element => element.propertyName?.text ?? element.name.text).filter(name => expected.has(name));
+  }
+  return [...expected];
+}
+
+export { isUnshadowedCommonJsRequire, sourceLocation };

package/runtime/scripts/checks/architecture/unit-spec-providers.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+import { constructorDependencies } from './constructor-deps.mjs';
+import { treeOf } from './required-files.mjs';
+
+/**
+ * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
+ * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
+ * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ *
+ * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
+ * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides
+ * the token that decorator's `injector<T>(TOKEN)` names; an undecorated parameter of a class type provides that class (see
+ * constructor-deps.mjs). Providers are matched by the exported name of the imported binding (`import { CACHE as C }` is
+ * CACHE), never by text. A provider is a class, or `{ provide: TOKEN, useValue: double }` and nothing else.
+ *
+ * Findings: an extra provider, a missing provider, a service that is not the first provider, a dependency whose token cannot
+ * be resolved, a spec with no createTestingModule providers array, and a provider that is neither a class nor
+ * `{ provide, useValue }`. Which double a `useValue` is, and whether other specs exist at all, are other rules' business.
+ */
+export const UNIT_SPEC_PROVIDERS_RULE_IDS = ['BE_SPEC_QUALITY'];
+
+const RULE = 'BE_SPEC_QUALITY';
+const SERVICE_SPEC = /\.service\.spec\.ts$/u;
+const SPEC_ROOT = /^(?:src|apps)\//u;
+
+/** local name -> {name, module} for every named import of a source file. */
+function importsOf(ts, sourceFile) {
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    const bindings = ts.isImportDeclaration(statement) ? statement.importClause?.namedBindings : null;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) imports.set(element.name.text, { name: (element.propertyName ?? element.name).text, module: statement.moduleSpecifier.text });
+  }
+  return imports;
+}
+
+/** The `Test.createTestingModule(...)` calls of a spec. */
+function testingModules(ts, sourceFile) {
+  const calls = [];
+  const visit = node => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createTestingModule') calls.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return calls;
+}
+
+const literalKey = (ts, property) => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
+
+export function checkUnitSpecProviders(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let specs = 0;
+  const tree = treeOf(config.root);
+  for (const rel of [...tree.files].filter(file => SPEC_ROOT.test(file) && SERVICE_SPEC.test(file)).sort()) {
+    const abs = path.join(config.root, ...rel.split('/'));
+    if (!fs.existsSync(abs)) continue;
+    specs += 1;
+    const sourceFile = ts.createSourceFile(abs, fs.readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true);
+    const report = (node, message) => violations.push({ ruleId: RULE, path: rel, ...kit.at(rel, sourceFile, node), message });
+    const imports = importsOf(ts, sourceFile);
+    const nameOf = identifier => imports.get(identifier.text)?.name ?? identifier.text;
+
+    const serviceRel = rel.replace(/\.spec\.ts$/u, '.ts');
+    const serviceFile = graph.files.get(serviceRel);
+    if (!serviceFile) { report(sourceFile, `${rel} has no ${path.posix.basename(serviceRel)} beside it; a service spec sits next to the service it tests.`); continue; }
+
+    const modules = testingModules(ts, sourceFile);
+    if (!modules.length) { report(sourceFile, `${rel} never calls Test.createTestingModule({ providers: [...] }); build the service from a testing module holding exactly its constructor dependencies.`); continue; }
+
+    for (const call of modules) {
+      const options = call.arguments[0];
+      const property = options && ts.isObjectLiteralExpression(options) ? options.properties.find(item => literalKey(ts, item) === 'providers') : null;
+      const list = property && ts.isPropertyAssignment(property) && ts.isArrayLiteralExpression(property.initializer) ? property.initializer : null;
+      if (!list) { report(call, `${rel}: Test.createTestingModule has no literal \`providers\` array; list the service and each constructor dependency there.`); continue; }
+
+      const provided = []; // [{name, node}]
+      let readable = true;
+      for (const element of list.elements) {
+        if (ts.isIdentifier(element)) { provided.push({ name: nameOf(element), node: element, isClass: true }); continue; }
+        if (ts.isObjectLiteralExpression(element)) {
+          const keys = element.properties.map(item => literalKey(ts, item));
+          const provide = element.properties.find(item => literalKey(ts, item) === 'provide');
+          const value = provide && ts.isPropertyAssignment(provide) ? provide.initializer : null;
+          if (keys.length === 2 && keys.includes('useValue') && value && ts.isIdentifier(value)) { provided.push({ name: nameOf(value), node: element, isClass: false }); continue; }
+        }
+        readable = false;
+        report(element, `${rel}: a provider is a class or \`{ provide: TOKEN, useValue: double }\` and nothing else (no useClass, useFactory, useExisting, spread or computed token).`);
+      }
+      if (!readable) continue;
+
+      const first = list.elements[0];
+      const serviceName = first && ts.isIdentifier(first) ? imports.get(first.text) : null;
+      const target = serviceName ? path.posix.normalize(path.posix.join(path.posix.dirname(rel), serviceName.module)).replace(/\.[cm]?[jt]s$/u, '') : null;
+      const serviceClass = serviceName && target === serviceRel.replace(/\.ts$/u, '')
+        ? serviceFile.sourceFile.statements.find(statement => ts.isClassDeclaration(statement) && statement.name?.text === serviceName.name) : null;
+      if (!serviceClass) { report(first ?? list, `${rel}: the first provider is the service under test, imported from ./${path.posix.basename(serviceRel, '.ts')}.`); continue; }
+
+      const dependencies = constructorDependencies(kit, serviceFile, serviceClass);
+      const expected = [];
+      for (const dependency of dependencies) {
+        if (dependency.kind === 'unresolved') {
+          report(list, `${rel}: a constructor dependency of ${serviceName.name} cannot be resolved to a token (${dependency.reason}), so its provider cannot be checked; inject it through an exported Inject<Thing>() decorator or a class type.`);
+          continue;
+        }
+        expected.push(dependency.name);
+      }
+      const remaining = [...expected];
+      for (const item of provided.slice(1)) {
+        const index = remaining.indexOf(item.name);
+        if (index === -1) report(item.node, `${rel}: ${item.name} is provided but is not a constructor dependency of ${serviceName.name}; a unit spec provides exactly what the constructor needs.`);
+        else remaining.splice(index, 1);
+      }
+      for (const name of remaining) report(list, `${rel}: ${name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${name}, useValue: double }\` (or the class itself) to the providers.`);
+    }
+  }
+  return { violations, coverage: { status: 'checked', specs, files: graph.files.size } };
+}

package/runtime/scripts/checks/architecture.mjs

@@ -0,0 +1,41 @@
+// architecture.mjs — the architecture check (docs/architecture-check.md).
+//
+//   node scripts/checks/architecture.mjs <repo-root> [--base <commit>]
+//
+// Prints one starci/architecture-check@1 record. Exit 0: ok. Exit 1: violations or errors (a check that
+// cannot run is an error, never a pass). Exit 2: bad arguments.
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {checkArchitecture} from './architecture/index.mjs';
+
+export {checkArchitecture};
+
+const USAGE = 'usage: architecture.mjs <repo-root> [--base <commit>]';
+
+export function parseArchitectureArgs(argv) {
+  let root = null, base;
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--base') {
+      base = argv[++index];
+      if (!base) throw Error(`--base needs a commit; ${USAGE}`);
+    } else if (value.startsWith('-') || root !== null) throw Error(`unexpected argument ${value}; ${USAGE}`);
+    else root = value;
+  }
+  if (root === null) throw Error(USAGE);
+  return {root, base};
+}
+
+export function architectureMain(argv, {check = checkArchitecture, write = (text) => process.stdout.write(text), fail = (text) => process.stderr.write(text)} = {}) {
+  let parsed;
+  try { parsed = parseArchitectureArgs(argv); } catch (error) { fail(`${error.message}\n`); return 2; }
+  let report;
+  try { report = check({repositoryRoot: path.resolve(parsed.root), base: parsed.base}); } catch (error) {
+    report = {schema: 'starci/architecture-check@1', ok: false, repository: parsed.root, kinds: [], files: 0, violations: [],
+      errors: [{ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error)}]};
+  }
+  write(`${JSON.stringify(report, null, 2)}\n`);
+  return report?.ok === true ? 0 : 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = architectureMain(process.argv.slice(2));