@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/hfs/architecture/owners.mjs

@@ -31,6 +31,10 @@ function ownerOf(owners, file) {
   return owners.find(owner => isInside(owner.root, file)) ?? null;
 }
 
+function reexportSteps(context, current) {
+  return (context.edges.get(current.file) ?? []).filter(candidate => candidate.reexport).map(candidate => ({ file: candidate.to, chain: [...current.chain, candidate.to] }));
+}
+
 function privateOwnerChain(context, owners, actionEntries, edge) {
   const sourceOwner = ownerOf(owners, edge.from);
   const queue = [{ file: edge.to, chain: [edge.from, edge.to] }];
@@ -41,9 +45,7 @@ function privateOwnerChain(context, owners, actionEntries, edge) {
     visited.add(current.file);
     const owner = ownerOf(owners, current.file);
     if (owner && sourceOwner?.id !== owner.id) return owner.entries.has(current.file) || actionEntries.has(current.file) ? null : { owner, chain: current.chain };
-    for (const candidate of context.edges.get(current.file) ?? []) if (candidate.reexport) {
-      queue.push({ file: candidate.to, chain: [...current.chain, candidate.to] });
-    }
+    queue.push(...reexportSteps(context, current));
   }
   return null;
 }
@@ -59,15 +61,8 @@ function arrangesSchema(config, from, to) {
     && resolver.classifyPath(relativePath(config.root, to)).slot === 'be.persistence';
 }
 
-/** Enforce explicit same-source owner entries without constraining imports inside one owner. */
-export function checkOwners(config, context) {
-  if (!config.owners?.length) return [];
-  const owners = ownerDeclarations(config, context);
+function publicEntryViolations(config, context, owners, sourceFiles, actionEntries) {
   const violations = [];
-  const sourceFiles = new Map(context.files.map(file => [canonical(file.fileName), file]));
-  const actionEntries = new Set(config.kinds.includes('frontend')
-    ? [...sourceFiles].filter(([, file]) => isServerActionModule(context.ts, file)).map(([name]) => name)
-    : []);
   for (const owner of owners) {
     const sourceFile = sourceFiles.get(owner.entry);
     if (!sourceFile) {
@@ -87,11 +82,16 @@ export function checkOwners(config, context) {
           path: relativePath(config.root, canonical(entryFile.fileName)),
           ...sourceLocation(entryFile, statement),
           owner: owner.id,
-          message: `Owner ${owner.id} public entry must use explicit named exports rather than export *.`
+          message: `Owner ${owner.id} public entry must use explicit named exports rather than export *.`,
         });
       }
     }
   }
+  return violations;
+}
+
+function ownerImportViolations(config, context, owners, actionEntries) {
+  const violations = [];
   for (const sourceFile of context.files) {
     const from = canonical(sourceFile.fileName);
     for (const edge of context.edges.get(from) ?? []) {
@@ -107,9 +107,23 @@ export function checkOwners(config, context) {
         specifier: edge.specifier,
         resolvedPath: relativePath(config.root, bypass.chain.at(-1)),
         dependencyChain: bypass.chain.map(file => relativePath(config.root, file)),
-        message: `Cross-owner dependency must enter ${bypass.owner.id} through ${relativePath(config.root, bypass.owner.entry)}.`
+        message: `Cross-owner dependency must enter ${bypass.owner.id} through ${relativePath(config.root, bypass.owner.entry)}.`,
       });
     }
   }
   return violations;
 }
+
+/** Enforce explicit same-source owner entries without constraining imports inside one owner. */
+export function checkOwners(config, context) {
+  if (!config.owners?.length) return [];
+  const owners = ownerDeclarations(config, context);
+  const sourceFiles = new Map(context.files.map(file => [canonical(file.fileName), file]));
+  const actionEntries = new Set(config.kinds.includes('frontend')
+    ? [...sourceFiles].filter(([, file]) => isServerActionModule(context.ts, file)).map(([name]) => name)
+    : []);
+  return [
+    ...publicEntryViolations(config, context, owners, sourceFiles, actionEntries),
+    ...ownerImportViolations(config, context, owners, actionEntries),
+  ];
+}

package/runtime/scripts/hfs/architecture/package-shape.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { treeOf } from './required-files.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R63 `package-shape` (FE_PACKAGE_SHAPE, knowledge/hfs/README.md 6.2). A shared package is built to `dist` and says what it
@@ -18,6 +19,7 @@ import { treeOf } from './required-files.mjs';
 export const PACKAGE_SHAPE_RULE_IDS = ['FE_PACKAGE_SHAPE'];
 
 const RULE = 'FE_PACKAGE_SHAPE';
+const UNREADABLE = Symbol('unreadable');
 
 /** Every string target of an exports value (a string, a condition map, an array of either), with the condition path. */
 function targetsOf(value, trail = []) {
@@ -29,35 +31,61 @@ function targetsOf(value, trail = []) {
 
 const insideDist = target => path.posix.normalize(target).replace(/^\.\//u, '').startsWith('dist/');
 
-export function checkPackageShape({ config, graph }) {
-  const resolver = graph.resolver;
-  const violations = [];
-  let packages = 0;
+function packageRoots(config, resolver) {
   const roots = new Set();
   for (const rel of treeOf(config.root).files) {
     const owner = resolver.ownerOf(rel);
     if (owner && resolver.slot(owner.slot)?.tier === 'package') roots.add(owner.root);
   }
-  for (const root of [...roots].sort()) {
-    const manifestRel = `${root}/package.json`;
-    const report = (message, extra = {}) => violations.push({ ruleId: RULE, path: manifestRel, line: 1, column: 1, package: root, message, ...extra });
-    let manifest;
-    try { manifest = JSON.parse(fs.readFileSync(path.join(config.root, ...manifestRel.split('/')), 'utf8')); } catch { continue; }
-    packages += 1;
-    if (typeof manifest.scripts?.build !== 'string' || !manifest.scripts.build.trim()) report(`${manifestRel} has no scripts.build; a shared package is built to dist before an app consumes it.`);
-    if (manifest.exports === undefined) {
-      report(`${manifestRel} declares no exports map; a package lists what it exports, subpath by subpath, each pointing into ./dist/.`);
-    } else {
-      if (typeof manifest.exports === 'object' && !Array.isArray(manifest.exports)) {
-        for (const key of Object.keys(manifest.exports)) if (key.includes('*') || key.endsWith('/')) report(`exports key "${key}" of ${manifestRel} is a pattern or folder mapping; list each exported subpath explicitly.`, { export: key });
-      }
-      for (const { target, trail } of targetsOf(manifest.exports)) {
-        if (!insideDist(target)) report(`exports target "${target}" (${trail.join(' > ') || '.'}) of ${manifestRel} is not inside ./dist/; a package exports what it built, never its source.`, { export: target });
-      }
-    }
-    for (const field of ['main', 'module', 'types', 'typings']) {
-      if (typeof manifest[field] === 'string' && !insideDist(manifest[field])) report(`${field} "${manifest[field]}" of ${manifestRel} is not inside ./dist/; a package points at what it built.`, { field });
+  return [...roots].sort(byCodeUnit);
+}
+
+function readManifest(config, manifestRel) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(config.root, ...manifestRel.split('/')), 'utf8'));
+  } catch {
+    return UNREADABLE;
+  }
+}
+
+function reportExportIssues(manifest, manifestRel, report) {
+  if (manifest.exports === undefined) {
+    report(`${manifestRel} declares no exports map; a package lists what it exports, subpath by subpath, each pointing into ./dist/.`);
+    return;
+  }
+  if (typeof manifest.exports === 'object' && !Array.isArray(manifest.exports)) {
+    for (const key of Object.keys(manifest.exports)) {
+      if (key.includes('*') || key.endsWith('/')) report(`exports key "${key}" of ${manifestRel} is a pattern or folder mapping; list each exported subpath explicitly.`, { export: key });
     }
   }
+  for (const { target, trail } of targetsOf(manifest.exports)) {
+    if (!insideDist(target)) report(`exports target "${target}" (${trail.join(' > ') || '.'}) of ${manifestRel} is not inside ./dist/; a package exports what it built, never its source.`, { export: target });
+  }
+}
+
+function reportManifestIssues(manifest, manifestRel, report) {
+  if (typeof manifest.scripts?.build !== 'string' || !manifest.scripts.build.trim()) report(`${manifestRel} has no scripts.build; a shared package is built to dist before an app consumes it.`);
+  reportExportIssues(manifest, manifestRel, report);
+  for (const field of ['main', 'module', 'types', 'typings']) {
+    if (typeof manifest[field] === 'string' && !insideDist(manifest[field])) report(`${field} "${manifest[field]}" of ${manifestRel} is not inside ./dist/; a package points at what it built.`, { field });
+  }
+}
+
+function inspectPackage(config, root, violations) {
+  const manifestRel = `${root}/package.json`;
+  const report = (message, extra = {}) => violations.push({ ruleId: RULE, path: manifestRel, line: 1, column: 1, package: root, message, ...extra });
+  const manifest = readManifest(config, manifestRel);
+  if (manifest === UNREADABLE) return false;
+  reportManifestIssues(manifest, manifestRel, report);
+  return true;
+}
+
+export function checkPackageShape({ config, graph }) {
+  const roots = packageRoots(config, graph.resolver);
+  const violations = [];
+  let packages = 0;
+  for (const root of roots) {
+    if (inspectPackage(config, root, violations)) packages += 1;
+  }
   return { violations, coverage: { status: 'checked', packages } };
 }

package/runtime/scripts/hfs/architecture/presentation.mjs

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { repositoryName } from '../repo-identity.mjs';
+import { managedScriptNames } from './managed-scripts.mjs';
+import { trimTrailingChars } from '../linear-text.mjs';
+
+const RUNTIME_ROOT_MARKDOWN = new Set(['README.md', 'CONTEXT.md', 'CONTRIBUTING.md', 'CHANGELOG.md', 'THIRD_PARTY_NOTICES.md']);
+const PRODUCT_ROOT_MARKDOWN = new Set(['README.md']);
+const README_SECTIONS = ['Overview', 'Stack', 'Repository layout', 'Development'];
+const DEVELOPMENT_SCRIPTS = ['typecheck', 'lint', 'build', 'test'];
+const README_HEADING = new RegExp(['^## ', '(.+?)', String.raw`\s*$`].join(''), 'u');
+const README_URL = new RegExp(['https?:', String.raw`\/\/`, String.raw`[^\s<>)"']+`].join(''), 'giu');
+
+function privateHost(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  if (host === 'localhost' || host === '::1' || host === '0.0.0.0' ||
+      /(?:\.localhost|\.local|\.internal|\.lan)$/u.test(host)) return true;
+  if (host.includes(':')) return /^(?:::|f[cd][0-9a-f]*:|fe[89ab][0-9a-f]*:)/iu.test(host);
+  if (!host.includes('.')) return true;
+  const octets = host.split('.');
+  if (octets.length !== 4 || !octets.every(part => /^\d{1,3}$/u.test(part) && Number(part) <= 255)) return false;
+  const [a, b] = octets.map(Number);
+  return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 ||
+    a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 100 && b >= 64 && b <= 127;
+}
+
+function scriptCommand(name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+  return new RegExp(name === 'test' ? String.raw`npm (?:run test|test)(?![\w:-])` : String.raw`npm run ${escaped}(?![\w:-])`, 'u');
+}
+
+function addFinding(state, ruleId, entry, message, line = 1) {
+  state.violations.push({ ruleId, path: entry, line, column: 1, message });
+}
+
+function checkRootPackageManager(state) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(state.root, 'package.json'), 'utf8'));
+    if (pkg.packageManager && !/^npm@\d/u.test(pkg.packageManager))
+      addFinding(state, 'HFS_PACKAGE_MANAGER_MIXED', 'package.json', `packageManager ${pkg.packageManager} contradicts the npm package-lock.json contract.`);
+  } catch { /* The repository's package/config checks own unreadable or invalid JSON. */ }
+}
+
+function checkRootPresentation(state) {
+  const { runtime, tree } = state;
+  for (const entry of tree.top) {
+    if (/\.md$/iu.test(entry) && !(runtime ? RUNTIME_ROOT_MARKDOWN : PRODUCT_ROOT_MARKDOWN).has(entry))
+      addFinding(state, 'HFS_ROOT_MARKDOWN_FORBIDDEN', entry, `Root Markdown ${entry} belongs under docs/ or the owning Work record.`);
+    if (state.nonNpmEntries.has(entry)) addFinding(state, 'HFS_PACKAGE_MANAGER_MIXED', entry, `${entry} contradicts the npm package manager contract.`);
+  }
+  for (const entry of ['.gitattributes', 'README.md']) {
+    if (!tree.hasFile(entry)) addFinding(state, 'HFS_ROOT_ENTRY_MISSING', entry, `Repository presentation requires root ${entry}.`);
+  }
+  if (tree.hasFile('package.json')) checkRootPackageManager(state);
+}
+
+function readmeSectionBody(lines, headings, section) {
+  const start = headings.find(item => item.name === section)?.index;
+  if (start === undefined) return '';
+  const end = headings.find(item => item.index > start)?.index ?? lines.length;
+  return lines.slice(start + 1, end).join('\n');
+}
+
+function checkReadmeHeadings(state, lines) {
+  const { root, runtime, tree } = state;
+  const name = runtime ? 'StarCi' : repositoryName(root);
+  if (lines[0].trim().toLowerCase() !== `# ${name}`.toLowerCase())
+    addFinding(state, 'HFS_README_TITLE_INVALID', 'README.md', `README.md must start with # ${name}.`);
+  const description = lines.slice(1).find(line => line.trim());
+  if (!description || /^\s*(?:#|!\[|\[!\[)/u.test(description) || description.trim().length > 240)
+    addFinding(state, 'HFS_README_DESCRIPTION_INVALID', 'README.md', 'Place one concise description line directly below the repository name.');
+  const headings = lines.map((line, index) => ({ name: README_HEADING.exec(line)?.[1], index })).filter(item => item.name);
+  const required = [...README_SECTIONS, ...(tree.hasDir('.starciwork') ? ['Work'] : [])];
+  let previous = -1;
+  for (const section of required) {
+    const found = headings.find(item => item.name === section);
+    if (!found) addFinding(state, 'HFS_README_SECTION_MISSING', 'README.md', `README.md requires a ## ${section} section.`);
+    else if (found.index <= previous) addFinding(state, 'HFS_README_SECTION_ORDER', 'README.md', `## ${section} must follow the preceding standard section.`, found.index + 1);
+    else previous = found.index;
+  }
+  return headings;
+}
+
+function checkReadmeDevelopment(state, lines, headings) {
+  if (state.runtime || !headings.some(item => item.name === 'Development')) return;
+  const development = readmeSectionBody(lines, headings, 'Development');
+  const scripts = DEVELOPMENT_SCRIPTS.filter(name => managedScriptNames(state.profile, state.edition).has(name));
+  const commands = [/npm (?:ci|install)/u, ...scripts.map(scriptCommand)];
+  if (commands.some(command => !command.test(development))) {
+    addFinding(state, 'HFS_README_DEVELOPMENT_INCOMPLETE', 'README.md', 'Development must show npm install and the managed script commands: '
+      + scripts.map(name => (name === 'test' ? 'npm test' : `npm run ${name}`)).join(', ') + '.');
+  }
+}
+
+function checkReadmeWorkPointer(state, lines, headings) {
+  if (state.tree.hasDir('.starciwork') && headings.some(item => item.name === 'Work') &&
+      !/\.starciwork\b/u.test(readmeSectionBody(lines, headings, 'Work')))
+    addFinding(state, 'HFS_README_WORK_POINTER_MISSING', 'README.md', 'Work must point at the backend .starciwork tree.');
+}
+
+function inspectReadmeUrl(state, value, line) {
+  try {
+    if (privateHost(new URL(value).hostname))
+      addFinding(state, 'HFS_README_PRIVATE_URL', 'README.md', `README URL ${value} points at a local or private host.`, line);
+  } catch { /* Malformed URLs are outside this presentation rule. */ }
+}
+
+function badgeTargets(prose) {
+  return [
+    ...[...prose.matchAll(/!\[([^\]]*)\]\(([^)]+)\)/gu)].map(match => ({ alt: match[1], target: match[2] })),
+    ...[...prose.matchAll(/<img\b[^>]*>/giu)].map(match => ({
+      alt: /\balt=["']([^"']*)["']/iu.exec(match[0])?.[1] ?? '',
+      target: /\bsrc=["']([^"']*)["']/iu.exec(match[0])?.[1] ?? '',
+    })),
+  ];
+}
+
+function inspectBadgeTarget(state, alt, rawTarget, line) {
+  const target = rawTarget.trim().replace(/^<|>$/gu, '');
+  if (!/badge/iu.test(alt) && !/badge|shields\.io|badgen\.net/iu.test(target)) return;
+  try {
+    const url = new URL(target);
+    if (url.protocol !== 'https:' || privateHost(url.hostname) ||
+        /^(?:img\.shields\.io|badgen\.net)$/iu.test(url.hostname) && url.pathname.startsWith('/badge/'))
+      addFinding(state, 'HFS_README_BADGE_NOT_LIVE', 'README.md', `Badge ${target} must represent a live external HTTPS service.`, line);
+  } catch { addFinding(state, 'HFS_README_BADGE_NOT_LIVE', 'README.md', `Badge ${target} must use a live external HTTPS service.`, line); }
+}
+
+function inspectReadmeLine(state, line, index, scan) {
+  if (/^\s*```/u.test(line)) {
+    scan.fenced = !scan.fenced;
+    return;
+  }
+  if (scan.fenced) return;
+  const prose = line.replace(/`[^`]*`/gu, '');
+  for (const match of prose.matchAll(README_URL)) inspectReadmeUrl(state, trimTrailingChars(match[0], '.,;!?'), index + 1);
+  for (const badge of badgeTargets(prose)) inspectBadgeTarget(state, badge.alt, badge.target, index + 1);
+}
+
+function checkReadmeLines(state, lines) {
+  const scan = { fenced: false };
+  for (let index = 0; index < lines.length; index += 1) inspectReadmeLine(state, lines[index], index, scan);
+}
+
+function presentationResult(state) {
+  return { violations: state.violations, coverage: { status: 'checked', source: state.tree.source } };
+}
+
+export function checkRepoPresentationImpl({ root, runtime, tree, profile, edition, nonNpmEntries }) {
+  const state = { root, runtime, tree, profile, edition, nonNpmEntries, violations: [] };
+  checkRootPresentation(state);
+  if (!tree.hasFile('README.md')) return presentationResult(state);
+  let readme;
+  try { readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8'); }
+  catch {
+    addFinding(state, 'HFS_ROOT_ENTRY_MISSING', 'README.md', 'Tracked README.md is not readable.');
+    return presentationResult(state);
+  }
+  const lines = readme.split(/\r?\n/u);
+  const headings = checkReadmeHeadings(state, lines);
+  checkReadmeDevelopment(state, lines, headings);
+  checkReadmeWorkPointer(state, lines, headings);
+  checkReadmeLines(state, lines);
+  return presentationResult(state);
+}

package/runtime/scripts/hfs/architecture/reachability.mjs

@@ -9,12 +9,16 @@
  *       must resolve to a route of that app (page.tsx / route.ts under src/app, route groups and [locale] transparent).
  * Only literals are judged: a computed href is counted as skipped, never guessed at.
  */
+import { byCodeUnit } from '../../lib/list.mjs';
+
 export const REACHABILITY_RULE_IDS = ['BE_FEATURE_NOT_COMPOSED', 'FE_OWNER_REACHABLE', 'FE_HREF_RESOLVES'];
 
 const BE_CAPABILITY_SLOTS = new Set(['be.domain', 'be.integrations', 'be.platform']);
 const TEST_FILE = /(?:\.(?:spec|test|stories|e2e-spec)\.[cm]?[jt]sx?$)|(?:(?:^|\/)__tests__\/)/;
 const ROUTE_FILE = /^(?:page|route)\.(?:tsx|ts|jsx|js)$/;
 const PLACEHOLDER = '\u0000';
+const REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+const ESCAPE_MATCH = String.raw`\$&`;
 
 /** Breadth-first reach over runtime, non-type-only edges (re-exports included) from `roots`. */
 function reachFrom(graph, roots) {
@@ -50,11 +54,11 @@ function ownerFiles(graph) {
 /** The file that stands for an owner in a finding: its public entry when the graph holds one, else its first file. */
 function entryOf(root, files) {
   const base = root.replace(/\/$/, '');
-  return files.find(rel => new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/index\\.[tj]sx?$`).test(rel)) ?? [...files].sort()[0];
+  const entry = new RegExp(String.raw`^${base.replace(REGEX_SPECIALS, ESCAPE_MATCH)}/index\.[tj]sx?$`);
+  return files.find(rel => entry.test(rel)) ?? [...files].sort(byCodeUnit)[0];
 }
 
-function checkBackend(graph) {
-  const byUnit = ownerFiles(graph);
+function backendAppRoots(byUnit) {
   const rootFiles = [];
   const appRoots = new Set();
   for (const [key, files] of byUnit) {
@@ -63,11 +67,10 @@ function checkBackend(graph) {
     appRoots.add(key.slice(key.indexOf(':') + 1));
     for (const rel of files) if (!TEST_FILE.test(rel)) rootFiles.push(rel);
   }
-  const roots = [...appRoots].sort();
-  const counts = { features: 0, modules: 0, appRoots: roots.length, notComposed: 0 };
-  if (!roots.length) return { violations: [], coverage: { status: 'unavailable', reason: 'no be.app.* owner instance holds a source file, so there is no app root to compose into', ...counts } };
-  const reached = reachFrom(graph, rootFiles);
-  const violations = [];
+  return { rootFiles, roots: [...appRoots].sort(byCodeUnit) };
+}
+
+function reportUncomposedBackendOwners(byUnit, reached, roots, counts, violations) {
   for (const [key, files] of [...byUnit].sort(([a], [b]) => a.localeCompare(b))) {
     const slot = key.slice(0, key.indexOf(':'));
     const root = key.slice(key.indexOf(':') + 1);
@@ -83,10 +86,41 @@ function checkBackend(graph) {
       message: `${feature ? 'Feature' : 'Module'} ${label} is not composed into any app: no runtime import path leads from ${roots.join(', ')} to it (a type-only import composes nothing), so it is dead code that no process serves.`,
     });
   }
+}
+
+function checkBackend(graph) {
+  const byUnit = ownerFiles(graph);
+  const { rootFiles, roots } = backendAppRoots(byUnit);
+  const counts = { features: 0, modules: 0, appRoots: roots.length, notComposed: 0 };
+  if (!roots.length) return { violations: [], coverage: { status: 'unavailable', reason: 'no be.app.* owner instance holds a source file, so there is no app root to compose into', ...counts } };
+  const reached = reachFrom(graph, rootFiles);
+  const violations = [];
+  reportUncomposedBackendOwners(byUnit, reached, roots, counts, violations);
   return { violations, coverage: { status: 'checked', ...counts } };
 }
 
 /** Route table of one app: arrays of segments, each {kind:'static'|'dyn'|'catch'|'optcatch', text}. */
+function routeSegmentsOf(parts) {
+  const segments = [];
+  let usable = true;
+  for (const part of parts) {
+    if (/^\([^.)][^)]*\)$/.test(part)) continue;            // route group
+    if (part.startsWith('@')) continue;                      // parallel slot: no URL segment
+    if (part.startsWith('_') || /^\(\.+\)/.test(part)) { usable = false; break; } // private folder, intercepting route
+    segments.push(part);
+  }
+  if (!usable) return null;
+  if (segments[0] === '[locale]') segments.shift();
+  return segments;
+}
+
+function routeSegmentOf(part) {
+  if (/^\[\[\.\.\..+\]\]$/.test(part)) return { kind: 'optcatch', text: part };
+  if (/^\[\.\.\..+\]$/.test(part)) return { kind: 'catch', text: part };
+  if (/^\[.+\]$/.test(part)) return { kind: 'dyn', text: part };
+  return { kind: 'static', text: part };
+}
+
 function routeTable(graph, app) {
   const prefix = `apps/${app}/src/app/`;
   const routes = [];
@@ -94,22 +128,9 @@ function routeTable(graph, app) {
     if (!rel.startsWith(prefix)) continue;
     const parts = rel.slice(prefix.length).split('/');
     if (!ROUTE_FILE.test(parts.at(-1))) continue;
-    const segments = [];
-    let usable = true;
-    for (const part of parts.slice(0, -1)) {
-      if (/^\([^.)][^)]*\)$/.test(part)) continue;            // route group
-      if (part.startsWith('@')) continue;                      // parallel slot: no URL segment
-      if (part.startsWith('_') || /^\(\.+\)/.test(part)) { usable = false; break; } // private folder, intercepting route
-      segments.push(part);
-    }
-    if (!usable) continue;
-    if (segments[0] === '[locale]') segments.shift();
-    routes.push(segments.map(part => {
-      if (/^\[\[\.\.\..+\]\]$/.test(part)) return { kind: 'optcatch', text: part };
-      if (/^\[\.\.\..+\]$/.test(part)) return { kind: 'catch', text: part };
-      if (/^\[.+\]$/.test(part)) return { kind: 'dyn', text: part };
-      return { kind: 'static', text: part };
-    }));
+    const segments = routeSegmentsOf(parts.slice(0, -1));
+    if (segments === null) continue;
+    routes.push(segments.map(routeSegmentOf));
   }
   return routes;
 }
@@ -118,7 +139,7 @@ function routeTable(graph, app) {
 function segmentMatches(hrefSegment, routeSegment) {
   if (!hrefSegment.includes(PLACEHOLDER)) return routeSegment.kind === 'dyn' || routeSegment.text === hrefSegment;
   if (routeSegment.kind === 'dyn' || routeSegment.kind === 'catch' || routeSegment.kind === 'optcatch') return true;
-  const parts = hrefSegment.split(PLACEHOLDER).map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const parts = hrefSegment.split(PLACEHOLDER).map(part => part.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`));
   return new RegExp(`^${parts.join('.*')}$`).test(routeSegment.text);
 }
 
@@ -147,7 +168,7 @@ function hrefResolves(href, routes) {
 /** The text of a string-ish expression with PLACEHOLDER for each ${...}; null when it is not a literal we can read. */
 function literalText(ts, node) {
   if (!node) return null;
-  while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || (ts.isNonNullExpression && ts.isNonNullExpression(node))) node = node.expression;
+  while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression?.(node)) node = node.expression;
   if (ts.isStringLiteralLike(node)) return node.text;                 // includes NoSubstitutionTemplateLiteral
   if (ts.isTemplateExpression(node)) return node.head.text + node.templateSpans.map(span => PLACEHOLDER + span.literal.text).join('');
   return null;
@@ -157,28 +178,47 @@ const NAVIGATION_CALLS = new Set(['redirect', 'permanentRedirect']);
 const ROUTER_METHODS = new Set(['push', 'replace', 'prefetch']);
 
 /** Every href-like target in a source file: {node, text|null (null = computed)}. */
+function jsxHrefTarget(ts, node) {
+  if (!ts.isJsxAttribute(node) || !ts.isIdentifier(node.name) || node.name.text !== 'href' || !node.initializer) return null;
+  const value = ts.isJsxExpression(node.initializer) ? node.initializer.expression : node.initializer;
+  return { node: value ?? node, text: value ? literalText(ts, value) : null };
+}
+
+function routerNameOf(ts, callee) {
+  if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)) return callee.expression.text;
+  if (ts.isPropertyAccessExpression(callee) && ts.isPropertyAccessExpression(callee.expression)) return callee.expression.name.text;
+  return '';
+}
+
+function isNavigationTarget(ts, callee) {
+  const routerName = routerNameOf(ts, callee);
+  return (ts.isIdentifier(callee) && NAVIGATION_CALLS.has(callee.text))
+    || (ts.isPropertyAccessExpression(callee) && ROUTER_METHODS.has(callee.name.text) && /router$/i.test(routerName));
+}
+
+function callHrefTarget(ts, node) {
+  if (!ts.isCallExpression(node) || !node.arguments.length) return null;
+  const callee = node.expression;
+  if (!isNavigationTarget(ts, callee)) return null;
+  return { node: node.arguments[0], text: literalText(ts, node.arguments[0]) };
+}
+
+function hrefTargetOf(ts, node) {
+  return jsxHrefTarget(ts, node) ?? callHrefTarget(ts, node);
+}
+
 function hrefTargets(ts, sourceFile) {
   const found = [];
   const visit = node => {
-    if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === 'href' && node.initializer) {
-      const value = ts.isJsxExpression(node.initializer) ? node.initializer.expression : node.initializer;
-      found.push({ node: value ?? node, text: value ? literalText(ts, value) : null });
-    } else if (ts.isCallExpression(node) && node.arguments.length) {
-      const callee = node.expression;
-      const navigates = (ts.isIdentifier(callee) && NAVIGATION_CALLS.has(callee.text))
-        || (ts.isPropertyAccessExpression(callee) && ROUTER_METHODS.has(callee.name.text)
-          && /router$/i.test(ts.isIdentifier(callee.expression) ? callee.expression.text : ts.isPropertyAccessExpression(callee.expression) ? callee.expression.name.text : ''));
-      if (navigates) found.push({ node: node.arguments[0], text: literalText(ts, node.arguments[0]) });
-    }
+    const target = hrefTargetOf(ts, node);
+    if (target) found.push(target);
     ts.forEachChild(node, visit);
   };
   visit(sourceFile);
   return found;
 }
 
-function checkFrontend(config, context, graph) {
-  const ts = context.ts ?? context.loaded.ts;
-  const byUnit = ownerFiles(graph);
+function appRouteRoots(graph) {
   const apps = new Map();
   for (const [rel, node] of graph.files) {
     if (node.slot !== 'fe.route') continue;
@@ -187,9 +227,10 @@ function checkFrontend(config, context, graph) {
     if (!apps.has(app)) apps.set(app, []);
     apps.get(app).push(rel);
   }
-  const counts = { pages: 0, mounted: 0, hrefs: 0, hrefsResolved: 0, hrefsSkipped: 0, routes: 0 };
-  const violations = [];
-  const reachedByApp = new Map([...apps].map(([app, roots]) => [app, reachFrom(graph, roots)]));
+  return apps;
+}
+
+function reportUnreachableFrontendFeatures(byUnit, reachedByApp, counts, violations) {
   for (const [key, files] of [...byUnit].sort(([a], [b]) => a.localeCompare(b))) {
     if (!key.startsWith('fe.feature:')) continue;
     const root = key.slice('fe.feature:'.length);
@@ -203,27 +244,52 @@ function checkFrontend(config, context, graph) {
       message: `${label} is not mounted: no runtime import path leads from a route file under apps/${app}/src/app to it (a type-only import mounts nothing), so the page is never shown.`,
     });
   }
-  for (const app of [...new Set([...apps.keys(), ...[...graph.files.keys()].map(rel => /^apps\/([^/]+)\/src\//.exec(rel)?.[1]).filter(Boolean)])].sort()) {
+}
+
+function routeApps(graph, apps) {
+  return [...new Set([...apps.keys(), ...[...graph.files.keys()].map(rel => /^apps\/([^/]+)\/src\//.exec(rel)?.[1]).filter(Boolean)])].sort(byCodeUnit);
+}
+
+function hrefNeedsSkipping(text, routes) {
+  if (text === null || !text.startsWith('/') || text.startsWith('//') || !routes.length) return true;
+  const hrefPath = text.split(/[?#]/)[0];
+  return /\.[A-Za-z0-9]{1,6}$/.test(hrefPath.split('/').at(-1)); // static asset
+}
+
+function reportUnresolvedHref(app, rel, node, target, prefix, violations) {
+  const point = node.sourceFile.getLineAndCharacterOfPosition(target.node.getStart(node.sourceFile));
+  const shown = target.text.split(PLACEHOLDER).join('${…}');
+  violations.push({
+    ruleId: 'FE_HREF_RESOLVES', path: rel, line: point.line + 1, column: point.character + 1, app, href: shown,
+    message: `href "${shown}" matches no route of app ${app}: no page.tsx or route.ts under ${prefix}app serves that path.`,
+  });
+}
+
+function inspectAppHrefTargets(app, graph, ts, routes, counts, violations) {
+  const prefix = `apps/${app}/src/`;
+  for (const [rel, node] of graph.files) {
+    if (!rel.startsWith(prefix) || TEST_FILE.test(rel)) continue;
+    for (const target of hrefTargets(ts, node.sourceFile)) {
+      counts.hrefs += 1;
+      if (hrefNeedsSkipping(target.text, routes)) { counts.hrefsSkipped += 1; continue; }
+      if (hrefResolves(target.text, routes)) { counts.hrefsResolved += 1; continue; }
+      reportUnresolvedHref(app, rel, node, target, prefix, violations);
+    }
+  }
+}
+
+function checkFrontend(config, context, graph) {
+  const ts = context.ts ?? context.loaded.ts;
+  const byUnit = ownerFiles(graph);
+  const apps = appRouteRoots(graph);
+  const counts = { pages: 0, mounted: 0, hrefs: 0, hrefsResolved: 0, hrefsSkipped: 0, routes: 0 };
+  const violations = [];
+  const reachedByApp = new Map([...apps].map(([app, roots]) => [app, reachFrom(graph, roots)]));
+  reportUnreachableFrontendFeatures(byUnit, reachedByApp, counts, violations);
+  for (const app of routeApps(graph, apps)) {
     const routes = routeTable(graph, app);
     counts.routes += routes.length;
-    const prefix = `apps/${app}/src/`;
-    for (const [rel, node] of graph.files) {
-      if (!rel.startsWith(prefix) || TEST_FILE.test(rel)) continue;
-      for (const target of hrefTargets(ts, node.sourceFile)) {
-        counts.hrefs += 1;
-        const text = target.text;
-        if (text === null || !text.startsWith('/') || text.startsWith('//') || !routes.length) { counts.hrefsSkipped += 1; continue; }
-        const hrefPath = text.split(/[?#]/)[0];
-        if (/\.[A-Za-z0-9]{1,6}$/.test(hrefPath.split('/').at(-1))) { counts.hrefsSkipped += 1; continue; } // static asset
-        if (hrefResolves(text, routes)) { counts.hrefsResolved += 1; continue; }
-        const point = node.sourceFile.getLineAndCharacterOfPosition(target.node.getStart(node.sourceFile));
-        const shown = text.split(PLACEHOLDER).join('${…}');
-        violations.push({
-          ruleId: 'FE_HREF_RESOLVES', path: rel, line: point.line + 1, column: point.character + 1, app, href: shown,
-          message: `href "${shown}" matches no route of app ${app}: no page.tsx or route.ts under ${prefix}app serves that path.`,
-        });
-      }
-    }
+    inspectAppHrefTargets(app, graph, ts, routes, counts, violations);
   }
   return { violations, coverage: { status: 'checked', ...counts } };
 }