@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/{checks → hfs}/architecture/surface.mjs

@@ -1,5 +1,5 @@
 /**
- * The lint surface: which architecture-machine findings an ESLint rule judges instead of `hfs check`.
+ * The lint surface: which architecture-machine findings an ESLint rule judges instead of `starci app check`.
  * Single source of truth. Each enforcer id is the rules.yaml enforcer; `codes` are the exact violation.ruleId strings its
  * check file emits on source files. plugins: 'be' = back-end profile repos, 'fe' = front-end profile, graph checks run for both.
  */
@@ -24,6 +24,7 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('tier-direction', BOTH, ['BE_TIER_DIRECTION', 'FE_TIER_DIRECTION'], 'An import goes only to a tier the slot matrix allows.'),
   enforcer('owner-cycle', BOTH, ['ARCH_OWNER_CYCLE'], 'Owners never import each other in a cycle.'),
   enforcer('feature-imports-feature', BE, ['BE_FEATURE_IMPORTS_FEATURE'], 'A feature never imports another feature.'),
+  enforcer('kind-isolation', BE, ['BE_KIND_ISOLATION'], 'A feature of one trigger kind never imports a feature of another kind; the kinds meet through the event bus.'),
   enforcer('app-isolation', FE, ['FE_APP_ISOLATION'], 'An app never imports another app.'),
   enforcer('feature-layout', BE, ['BE_FEATURE_LAYOUT_INVALID'], 'A feature file sits in the folder its role names.'),
   enforcer('application-never-imports-transport', BE, ['BE_APPLICATION_IMPORTS_TRANSPORT', 'BE_APPLICATION_TRANSPORT_FRAMEWORK'], 'Application code never imports transport code, directly or through a chain.'),
@@ -33,6 +34,11 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('app-composition-only', BE, ['BE_APP_COMPOSITION_ONLY', 'BE_APP_BUSINESS_ROLE'], 'An app only composes modules and holds no business role.'),
   enforcer('entrypoint-only-in-apps', BE, ['BE_ENTRYPOINT_ONLY_IN_APPS'], 'NestFactory and bootstrap live only in an app main file.'),
   enforcer('schema-owner', BE, ['BE_SCHEMA_OWNER'], 'Each entity array is registered by one owner across all apps.'),
+  enforcer('sql-returning', BE, ['BE_SQL_RETURNING_SHAPE'], 'An UPDATE or DELETE with RETURNING is wrapped in a CTE SELECT, because EntityManager.query returns it as [rows, count].'),
+  enforcer('context-owner', BE, ['BE_CONTEXT_OWNER'], 'An app composes only the contexts (connections) it owns; the migration apps compose all of them.'),
+  enforcer('context-coupling', BE, ['BE_CONTEXT_COUPLING'], 'Contexts are never coupled by a relation, a foreign key or an import; only by events.'),
+  enforcer('context-transaction', BE, ['BE_CONTEXT_TRANSACTION'], 'One transaction touches one context connection.'),
+  enforcer('context-platform-tables', BE, ['BE_CONTEXT_PLATFORM_TABLES'], 'A per-connection platform capability registers its tables on every connection that uses it.'),
   enforcer('error-code-unique', BE, ['BE_ERROR_HOME'], 'An error code is declared once in the repository.'),
   enforcer('error-masked', BE, ['BE_ERROR_MASKED'], 'Every app wires the error filter that masks internal errors.'),
   enforcer('default-deny-app-guard', BE, ['BE_DEFAULT_DENY'], 'Every app registers the default-deny guard before any other guard.'),
@@ -60,7 +66,7 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('component-purity', FE, ['FE_COMPONENT_WORLD_OWNERSHIP', 'FE_WORLD_OWNER_RENDER_BOUNDARY', 'FE_CONNECTED_BLOCK_RENDER_PAIR', 'FE_PURE_REACHES_DATA', 'FE_PURE_WORLD_HOOK', 'FE_PURE_WORLD_IMPORT'], 'A pure component reaches no data or world state; its connected entry owns them.'),
   enforcer('grammar-entry', FE, ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'], 'Vendor grammar is reached only through its owner entry.'),
   enforcer('i18n-keys', FE, ['FE_I18N_KEYS'], 'Translation keys read by source and keys held by catalogs agree both ways.'),
-  // The per-path judgements of the slot manifest (scripts/lib/hfs-path-findings.mjs), on a tracked TypeScript file.
+  // The per-path judgements of the slot manifest (scripts/hfs/path-findings.mjs), on a tracked TypeScript file.
   enforcer('slot-undeclared', BOTH, ['HFS_SLOT_UNDECLARED', 'HFS_SLOT_AMBIGUOUS', 'HFS_SLOT_NOT_ENABLED'], 'A TypeScript file is owned by exactly one slot of the repository.', { origin: 'repo' }),
   enforcer('source-suffix', BE, ['BE_SOURCE_FORM'], 'A source file name is index.ts, main.ts, a migration or <kebab-name>.<suffix>.ts with a suffix of the closed list.', { origin: 'repo' }),
   enforcer('spec-placement', BE, ['BE_SPEC_PLACEMENT'], 'A spec file lives in one of the four test layers and nowhere else.', { origin: 'repo' }),
@@ -74,7 +80,7 @@ export const LINT_CODES = new Set(LINT_ENFORCERS.flatMap(e => e.codes));
 export const TS_SOURCE = /\.(?:[cm]?tsx?)$/;
 
 /** True when a finding sits on an existing TypeScript file of the repository: the only findings an editor can show on a line. */
-export function attachesToSource(repositoryRoot, violation) {
+function attachesToSource(repositoryRoot, violation) {
   const file = violation?.path;
   if (typeof file !== 'string' || !TS_SOURCE.test(file)) return false;
   return fs.existsSync(path.join(repositoryRoot, ...file.split('/')));
@@ -87,5 +93,5 @@ export const codeOf = (finding) => finding?.ruleId ?? finding?.code;
 export const belongsTo = (enforcer, finding) => enforcer.codes.includes(codeOf(finding))
   && (finding.origin ?? 'machine') === (enforcer.origin ?? 'machine') && (enforcer.via === undefined || finding.check === enforcer.via);
 
-/** True when some lint rule owns the finding and it sits on an existing TypeScript file: it is an ESLint report, not a `hfs check` finding. */
+/** True when some lint rule owns the finding and it sits on an existing TypeScript file: it is an ESLint report, not a `starci app check` finding. */
 export const onLintSurface = (repositoryRoot, finding) => LINT_ENFORCERS.some(enforcer => belongsTo(enforcer, finding)) && attachesToSource(repositoryRoot, finding);

package/runtime/scripts/{checks → hfs}/architecture/test-world-files.mjs

@@ -1,7 +1,9 @@
-import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { checkerScope } from './required-files.mjs';
+import { allowsFile } from '../allows.mjs';
+import { locateDeclaration } from '../slots.mjs';
 import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
+import { unwrapEach } from './ast-walks.mjs';
+import { nameText, sourceLocation } from '../../lib/ts-ast.mjs';
 
 /**
  * R47 `test-world-files` (BE_TEST_TOPOLOGY). Judgements over the test world, read through slots, the repository's own
@@ -40,18 +42,9 @@ const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ...
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
-const nameOf = (ts, name) => (name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) ? name.text : null);
-const unwrap = (ts, node) => {
-  let current = node;
-  while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression?.(current))) current = current.expression;
-  return current;
-};
-const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameOf(ts, property.name) === key)?.initializer ?? null;
+const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
+const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameText(ts, property.name) === key)?.initializer ?? null;
 const isExported = (ts, statement) => (statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
-const positionOf = (sourceFile, node) => {
-  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-  return { line: position.line + 1, column: position.character + 1 };
-};
 
 /** The object literal of `defineTestWorld(<object literal>)`, or null. */
 function defineLiteral(ts, expression) {
@@ -89,7 +82,7 @@ function fakeEntriesOf(ts, sourceFile, literal) {
   const value = node ? unwrap(ts, node) : null;
   if (!value || !ts.isObjectLiteralExpression(value)) return [];
   return value.properties
-    .map(property => ({ name: nameOf(ts, property.name), ...positionOf(sourceFile, property) }))
+    .map(property => ({ name: nameText(ts, property.name), ...sourceLocation(sourceFile, property) }))
     .filter(entry => entry.name);
 }
 
@@ -107,21 +100,18 @@ function fakedByOf(ts, sourceFile, literal) {
     if (!fake) continue;
     const reason = propertyOf(ts, body, 'reason');
     entries.push({
-      service: nameOf(ts, property.name),
+      service: nameText(ts, property.name),
       fake: ts.isStringLiteralLike(fake) ? fake.text : '',
       reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
-      ...positionOf(sourceFile, property),
+      ...sourceLocation(sourceFile, property),
     });
   }
   return entries;
 }
 
 export function checkTestWorldFiles(input) {
-  const { config, graph, context } = input;
-  const ts = context.ts;
-  const resolver = graph.resolver;
+  const { config, graph, ts, resolver, tree } = checkerScope(input);
   const { suffixes } = resolver.ruleParams();
-  const tree = treeOf(config.root);
   const violations = [];
   const fakeProviders = new Map();
   let worldRoot = null;

package/runtime/scripts/{checks → hfs}/architecture/tiers.mjs

@@ -1,14 +1,18 @@
+import { isServerActionModule } from './server-action.mjs';
+
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
  *   1. the tier direction matrix: every import, re-export and type-only import between two owners must go from a tier to
  *      a tier its `mayImport` lists (BE_TIER_DIRECTION / FE_TIER_DIRECTION); a backend feature importing another feature
- *      is the one direction with its own code (BE_FEATURE_IMPORTS_FEATURE, R28), never BE_TIER_DIRECTION,
+ *      is the one direction with its own code (BE_FEATURE_IMPORTS_FEATURE, R28), never BE_TIER_DIRECTION, and a feature of one trigger
+ *      kind (slot field `trigger`: api, webhooks, realtime, saga, reactors, jobs, cli) importing a feature of another is
+ *      BE_KIND_ISOLATION, whose fix is the event bus,
  *      an app never imports another app (FE_APP_ISOLATION), and a component layer imports only the layers after it;
  *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE),
  *      reported with the cycle path and the import that closes each hop.
  * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
  */
-export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
+export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'BE_KIND_ISOLATION', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
 
 const REASON_TEXT = {
   tierDirection: ({ fromTier, toTier, mayImport }) => `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`,
@@ -70,6 +74,27 @@ function cycleThrough(adjacency, members, origin) {
   return [origin, origin];
 }
 
+/** The trigger kind (slot field `trigger`) of the owner that holds `file`, or null when its owner's slot names none. */
+const triggerOf = (resolver, file) => {
+  const owner = resolver.ownerOf(file);
+  return owner ? (resolver.slot(owner.slot)?.trigger ?? null) : null;
+};
+
+/** The db Server Action an edge targets, or null. */
+const serverActionTarget = (graph, edge) => {
+  if (graph.profile !== 'fe') return null;
+  const to = graph.resolver.classifyPath(edge.to);
+  return to.slot === 'fe.modules.db' && /^write-[^/]+\.ts$/u.test(edge.to.split('/').at(-1))
+    && isServerActionModule(null, graph.files.get(edge.to).sourceFile) ? to : null;
+};
+
+/** A connected block may call a db writer directly when that writer is a file-level Next Server Action. */
+const blockCallsServerAction = (graph, edge) => {
+  if (!serverActionTarget(graph, edge)) return false;
+  const from = graph.resolver.classifyPath(edge.from);
+  return from.slot === 'fe.components' && from.kind === 'blocks' && from.role === 'entry';
+};
+
 export function checkTiers(graph) {
   const { resolver, profile } = graph;
   const violations = [];
@@ -81,15 +106,32 @@ export function checkTiers(graph) {
     const verdict = resolver.importAllowed(edge.from, edge.to);
     if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) { unclassified += 1; continue; }
     edgesChecked += 1;
-    if (verdict.allowed || !REASON_TEXT[verdict.reason]) continue;
+    const actionTarget = serverActionTarget(graph, edge);
+    if ((verdict.allowed || verdict.reason === 'notPublicEntry') && actionTarget && graph.unit(edge.from) !== graph.unit(edge.to) && !blockCallsServerAction(graph, edge)) {
+      counts.tierDirection += 1;
+      violations.push({
+        ruleId: tierRule,
+        path: edge.from, line: edge.line, column: edge.column,
+        specifier: edge.specifier, resolvedPath: edge.to, typeOnly: !edge.runtime,
+        fromTier: resolver.tierOf(edge.from), toTier: resolver.tierOf(edge.to),
+        message: `${edge.from} -> ${edge.to}: a db Server Action is called directly only by a connected block entry; hooks and other tiers use their declared data path${edge.runtime ? '' : ' (type-only imports count)'}.`,
+      });
+      continue;
+    }
+    if (verdict.allowed || (verdict.reason === 'tierDirection' && blockCallsServerAction(graph, edge)) || !REASON_TEXT[verdict.reason]) continue;
     counts[verdict.reason] += 1;
     const featureToFeature = profile === 'be' && verdict.reason === 'tierDirection' && verdict.fromTier === 'feature' && verdict.toTier === 'feature';
+    const fromKind = featureToFeature ? triggerOf(resolver, edge.from) : null;
+    const toKind = featureToFeature ? triggerOf(resolver, edge.to) : null;
+    const crossKind = fromKind !== null && toKind !== null && fromKind !== toKind;
     violations.push({
-      ruleId: verdict.reason === 'crossApp' ? 'FE_APP_ISOLATION' : featureToFeature ? 'BE_FEATURE_IMPORTS_FEATURE' : tierRule,
+      ruleId: verdict.reason === 'crossApp' ? 'FE_APP_ISOLATION' : crossKind ? 'BE_KIND_ISOLATION' : featureToFeature ? 'BE_FEATURE_IMPORTS_FEATURE' : tierRule,
       path: edge.from, line: edge.line, column: edge.column,
       specifier: edge.specifier, resolvedPath: edge.to, typeOnly: !edge.runtime,
       fromTier: verdict.fromTier ?? null, toTier: verdict.toTier ?? null,
-      message: `${edge.from} -> ${edge.to}: ${REASON_TEXT[verdict.reason](verdict)}${edge.runtime ? '' : ' (type-only imports count)'}.`,
+      message: crossKind
+        ? `${edge.from} -> ${edge.to}: a ${fromKind} feature imports a ${toKind} feature; no kind imports another, every cross-kind call is an event published with eventBus.publish(event, tx) from a domain service${edge.runtime ? '' : ' (type-only imports count)'}.`
+        : `${edge.from} -> ${edge.to}: ${REASON_TEXT[verdict.reason](verdict)}${edge.runtime ? '' : ' (type-only imports count)'}.`,
     });
   }
 

package/runtime/scripts/{checks → hfs}/architecture/transport-owner.mjs

@@ -6,7 +6,8 @@ import { machineKit } from './machine-ast.mjs';
  * `client-fetch-has-signal`. ESLint judges one file at a time by the spelling of a call; the machine judges the repository by
  * what the checker resolves. A repository has exactly ONE transport client and ONE Outcome union, both named by slot (never
  * by a path spelled here): the api package's (`fe.package.api.client`, `fe.package.api.outcome`) when the repository shares
- * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app.
+ * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app. The
+ * Outcome homes are the slots the manifest marks `outcomeHome` (the lite edition adds `fe.modules.db.outcome`), not a list kept here.
  *
  *   - two or more clients, or two or more Outcome unions, in the repository (two apps each keeping one, or a package one plus
  *     an app one) are findings on every copy;
@@ -30,7 +31,6 @@ const APP_CLIENT_SLOT = 'fe.transport.client';
 const APP_OUTCOME_SLOT = 'fe.transport.outcome';
 const PACKAGE_API_SLOT = 'fe.package.api';
 const CLIENT_SLOTS = new Set([APP_CLIENT_SLOT, 'fe.package.api.client']);
-const OUTCOME_SLOTS = new Set([APP_OUTCOME_SLOT, 'fe.package.api.outcome']);
 const NO_CLIENT = "the repository has no transport client. Create the one client (packages/<family>-api/src/client.ts, or the only app's modules/api/client.ts) and call it.";
 
 export function checkTransportOwner(input) {
@@ -60,7 +60,7 @@ export function checkTransportOwner(input) {
 
   const files = [...graph.files.values()].filter(file => file.slot && file.tier !== 'e2e');
   const clients = files.filter(file => CLIENT_SLOTS.has(file.slot));
-  const outcomes = files.filter(file => OUTCOME_SLOTS.has(file.slot));
+  const outcomes = files.filter(file => resolver.slot(file.slot)?.outcomeHome === true);
   const clientRels = new Set(clients.map(file => file.rel));
   const list = items => items.map(item => item.rel).join(', ');
   const owned = clients.length ? `the repository has one transport (${list(clients)}). Call the client and take its Outcome.` : NO_CLIENT;

package/runtime/scripts/{checks → hfs}/architecture/typescript.mjs

@@ -2,31 +2,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { canonical, isInside, slash } from './config.mjs';
+import { crossesSide } from './side-boundary.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { locateDeclaration } from '../slots.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) {
+// canon or architecture rule applies to it (inc-ffe60c49f502).
+const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.output', '.nuxt', '.svelte-kit', '.expo', '.docusaurus', '.swc', '.cache']);
+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 at the root of a project (beside a package manifest or a tsconfig.json:
-// next.config.ts and postcss.config.mjs of an app, which has no package.json of its own) is build tooling a broad `**/*.ts`
-// include pulls in; a `*.config.ts` inside a source tree (src/config/database.config.ts) has neither beside it and stays source.
-// The architecture program still reads tooling modules (a profile may declare one as source); the lint (hfs lint) judges one only
-// through the repository's own eslint.config.
-const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
-export function isToolingModule(fileName) {
-  return TOOLING_MODULE.test(path.basename(fileName)) && ['package.json', 'tsconfig.json'].some((manifest) => fs.existsSync(path.join(path.dirname(fileName), manifest)));
-}
-
 function diagnosticMessage(ts, diagnostic) {
   return ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
 }
@@ -53,7 +45,7 @@ function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_IN
  * Load TypeScript through the target package boundary, never through StarCi's own dependency graph. A side folder of an app has no
  * package.json of its own: the app root's one manifest is the boundary its TypeScript is installed under.
  */
-export function loadTargetTypeScript(repositoryRoot) {
+function loadTargetTypeScript(repositoryRoot) {
   const packageFile = path.join(locateDeclaration(repositoryRoot).appRoot, '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);
@@ -98,7 +90,7 @@ function runtimeImport(ts, node) {
   return true;
 }
 
-function isUnshadowedCommonJsRequire(ts, checker, expression) {
+export function isUnshadowedCommonJsRequire(ts, checker, expression) {
   if (!ts.isIdentifier(expression) || expression.text !== 'require') return false;
   const symbol = checker?.getSymbolAtLocation(expression);
   if (!symbol) return true;
@@ -113,7 +105,7 @@ function isUnshadowedCommonJsRequire(ts, checker, expression) {
  * 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) {
+function assetContextSpecifiers(ts, sourceFile, argument) {
   if (!argument || !ts.isTemplateExpression(argument)) return null;
   const head = argument.head.text;
   const spans = argument.templateSpans;
@@ -168,11 +160,6 @@ function moduleReferences(ts, sourceFile, checker) {
   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)
@@ -210,7 +197,7 @@ function exportPatternCapture(pattern, request) {
   return request.startsWith(before) && request.endsWith(after) ? request.slice(before.length, request.length - after.length) : null;
 }
 
-function exportTargetStrings(value) {
+export 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);
@@ -497,9 +484,7 @@ function typeScriptContext(config, loaded, paths) {
         || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
       // A side of an app (config.root is be/ or fe/) imports nothing of the app outside itself: the root holds no source, the other
       // side is another program, and a declared read (sides.fe.reads, be/contracts/) is codegen input, never an import.
-      const crossesSide = config.packageRoot !== undefined && config.packageRoot !== config.root
-        && isInside(config.packageRoot, actualTarget) && !isInside(config.root, actualTarget) && !slash(actualTarget).includes('/node_modules/');
-      if (internal && crossesSide) {
+      if (internal && crossesSide(config, actualTarget)) {
         errors.push({
           ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
           project: project.relative,
@@ -581,6 +566,8 @@ export function unwrapExpression(ts, expression) {
   return expression;
 }
 
+/* ---- the AST walks every architecture checker shares ---- */
+
 /** 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)) {
@@ -595,4 +582,3 @@ export function referencedExports(ts, statement, expected) {
   return [...expected];
 }
 
-export { isUnshadowedCommonJsRequire, sourceLocation };

package/runtime/scripts/{checks → hfs}/architecture.mjs

@@ -1,19 +1,19 @@
-// architecture.mjs — the architecture check (docs/architecture-check.md).
+// architecture.mjs — the architecture check (docs/architecture.md).
 //
-//   node scripts/checks/architecture.mjs <repo-root> [--base <commit>]
+//   starci runtime architecture <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';
-import { isMain } from './common.mjs';
+import { isMain } from '../lib/is-main.mjs';
 
 export {checkArchitecture};
 
-const USAGE = 'usage: architecture.mjs <repo-root> [--base <commit>]';
+const USAGE = 'usage: starci runtime architecture <repo-root> [--base <commit>]';
 
-export function parseArchitectureArgs(argv) {
+function parseArchitectureArgs(argv) {
   let root = null, base;
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];