@starci/hfs 2.0.1 → 3.0.0

package/runtime/modules/kernel/failure-codes.yaml

@@ -245,10 +245,9 @@ BE_APP_BUSINESS_ROLE:
 BE_APP_COMPOSITION_ONLY:
   title: "Composition root has stray source"
   title_vi: "Gốc ghép nối có tệp lạc chỗ"
-  meaning_vi: "Mã trong ứng dụng gốc không phải tệp mà slot ứng dụng cho phép (main.ts, app.module.ts, <app>.options.ts)."
+  meaning_vi: "Mã trong ứng dụng gốc không phải tệp mà slot ứng dụng cho phép (main.ts, app.module.ts, <app>.options.ts; operations.ts ở ứng dụng API)."
   causes_vi:
     - "Thêm tệp không đúng tên vào thư mục ứng dụng gốc"
-    - "Composition spec của app tự khai AppModule, import AppModule từ tệp khác app.module, hoặc không gọi AppModule.register( — module thật không bao giờ được khởi chạy"
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -516,6 +515,7 @@ BE_SPEC_QUALITY:
     - "Spec chỉ có toHaveBeenCalled*, không khẳng định kết quả hay trạng thái"
     - "`it.skip`, `describe.skip`, `xit`, `it.todo`, `.skipIf`/`.runIf` hoặc `(cond ? describe : describe.skip)` trong spec; hãy viết test thật hoặc xóa nó, còn việc bỏ qua khi thiếu sandbox nằm trong contract helper của world (`sandbox.describe(...)`)"
     - "e2e gọi CommandBus, QueryBus hay handler trực tiếp; dùng sleep thay cho waitFor; tự gọi Test.createTestingModule; import SDK của nhà cung cấp mô hình; không đọc lại dòng đã lưu qua EntityManager"
+    - "Spec đơn vị của service khẳng định `expect.any(String)`, `expect.any(Number)` hoặc `expect.any(Date)` cho giá trị service tự sinh; service nhận bộ sinh id và đồng hồ qua token, spec cấp `fakeIds()` và `new FakeClock(...)` từ @starci/jest-preset rồi khẳng định đúng giá trị"
     - "Spec đơn vị của service có providers khác với phụ thuộc constructor: thừa nhà cung cấp, thiếu nhà cung cấp, service không đứng đầu, token không suy ra được hoặc nhà cung cấp không phải lớp hay { provide, useValue }"
   nextStep_vi: "Chuyển luật kiến trúc sang lint hoặc bộ kiểm tra; khẳng định kết quả hoặc trạng thái; e2e vào bằng transport thật, chờ bằng waitFor và dựng thế giới ở src/tests/e2e/setup. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
   owner: op-retry
@@ -981,11 +981,11 @@ HFS_CANON_PIN_DRIFT:
   kind: check-finding
 
 HFS_CI_MISSING_CANON:
-  title: "CI runs the pinned `@starci/hfs check`; pre-push runs typecheck and lint"
+  title: "CI runs the pinned `hfs lint`; pre-push runs typecheck and lint"
   title_vi: "CI thiếu bước canon"
   meaning_vi: "Workflow/husky thiếu bước `<step>`. Cấu trúc chỉ được kiểm khi agent chạy — CI phải tự kiểm."
   causes_vi:
-    - "Vi phạm luật R13: CI phải chạy `npx @starci/hfs check` (bản pin); pre-push phải có `typecheck` + `lint:check`."
+    - "Vi phạm luật R13: CI phải chạy `hfs lint` (`npm run lint` hoặc `npx @starci/hfs lint`, bản pin); pre-push phải có `typecheck` + `lint`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -1283,7 +1283,7 @@ HFS_README_DESCRIPTION_INVALID:
 HFS_README_DEVELOPMENT_INCOMPLETE:
   title: "README Development section incomplete"
   title_vi: "Mục Development trong README chưa đủ lệnh"
-  meaning_vi: "Mục Development chưa nêu đủ các lệnh cài đặt, typecheck, lint:check, build và test (các script do hfs sync quản lý; test chạy bằng npm test)."
+  meaning_vi: "Mục Development chưa nêu đủ các lệnh cài đặt, typecheck, lint, build và test (các script do hfs sync quản lý; test chạy bằng npm test)."
   causes_vi:
     - "Quên một hoặc vài lệnh"
     - "Viết bằng lệnh của trình quản lý khác"
@@ -1433,18 +1433,6 @@ HFS_RULE_OFF_WITHOUT_REPLACEMENT:
   owner: op-retry
   kind: check-finding
 
-HFS_SIZE_GROWTH:
-  title: "Source file over the size budget grew"
-  title_vi: "Tệp mã nguồn vượt hạn mức dòng vẫn tiếp tục dài thêm"
-  meaning_vi: "Một tệp mã nguồn đã dài hơn hạn mức mềm của ruleParams.fileLines nhưng lại dài thêm so với phiên bản gốc của nhánh, hoặc một tệp mới tạo đã vượt hạn mức ngay từ đầu. Tệp quá dài khó đọc, khó sửa và là nơi lỗi dễ ẩn; quy tắc này cho phép tệp cũ đang quá dài được giữ nguyên hoặc thu nhỏ dần, nhưng không cho phép nó phình thêm."
-  causes_vi:
-    - "Op thêm mã mới vào một tệp vốn đã quá hạn mức thay vì tách phần mới sang tệp khác"
-    - "Một tệp đang dưới hạn mức được thêm mã cho đến khi vượt hạn mức"
-    - "Một tệp mới tạo dài hơn hạn mức, hoặc một tệp bị di chuyển sang đường dẫn mới nên bị coi là tệp mới"
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để tách phần mã mới (hoặc bớt phần cũ) sang tệp riêng đúng ô của nó, sao cho tệp không dài hơn phiên bản gốc và tệp mới nằm trong hạn mức."
-  owner: op-retry
-  kind: check-finding
-
 HFS_SIZE_SOFT_BACKLOG:
   title: "Source file above the soft size"
   title_vi: "Tệp mã vượt cỡ mềm (chỉ báo cáo)"
@@ -1478,12 +1466,12 @@ HFS_SLOT_NOT_ENABLED:
   kind: check-finding
 
 HFS_SLOT_REQUIRED_MISSING:
-  title: "A slot is missing a required file (feature `index.ts`, app composition spec, FE `global-error.tsx`)"
+  title: "A slot is missing a required file (feature `index.ts`, app `main.ts`, FE `global-error.tsx`)"
   title_vi: "Ô thiếu tệp bắt buộc"
   meaning_vi: "Một ô bắt buộc (hoặc một thực thể của ô, như một ứng dụng hay một tính năng) đòi có tệp hoặc thư mục này nhưng nó không nằm trong những gì Git theo dõi."
   causes_vi:
-    - "Vi phạm luật R02: slot bắt buộc thiếu tệp `requires` (vd feature thiếu `index.ts`, app thiếu composition spec, FE thiếu `global-error.tsx`)."
-    - "Ứng dụng thiếu main.ts, app.module.ts hoặc spec ghép ứng dụng"
+    - "Vi phạm luật R02: slot bắt buộc thiếu tệp `requires` (vd feature thiếu `index.ts`, app thiếu `main.ts`, FE thiếu `global-error.tsx`)."
+    - "Ứng dụng thiếu main.ts hoặc app.module.ts"
     - "Kho thiếu tệp gốc bắt buộc như README.md, hfs.json, .starciwork, .starcistacks"
   nextStep_vi: "Tạo tệp hoặc thư mục theo mẫu của ô rồi commit; tệp chưa git add vẫn tính là thiếu. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry

package/runtime/scripts/checks/architecture/hfs-graph.mjs

@@ -5,7 +5,7 @@ import { relativePath } from './typescript.mjs';
  * The file and owner graph the HFS architecture checks share. Every production source file the TypeScript context
  * loaded becomes a node classified by the slot manifest (config.hfs is the resolver of scripts/lib/hfs-slots.mjs);
  * every import, re-export and type-only import between two of them becomes an edge. Nothing here judges: the checks
- * in tiers.mjs, reachability.mjs, dead-exports.mjs, required-files.mjs, size-growth.mjs and clones.mjs read it.
+ * in tiers.mjs, reachability.mjs, dead-exports.mjs, required-files.mjs and clones.mjs read it.
  *
  *   graph.profile            'be' | 'fe'
  *   graph.resolver           the slot resolver (config.hfs)

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

@@ -189,7 +189,7 @@ function privateHost(hostname) {
 
 // The scripts the README Development section shows; each is required only when the managed package-scripts template of the
 // profile (packages/hfs/templates/<profile>/package-scripts/package.json, the one source of the managed script names) has it.
-const DEVELOPMENT_SCRIPTS = ['typecheck', 'lint:check', 'build', 'test'];
+const DEVELOPMENT_SCRIPTS = ['typecheck', 'lint', 'build', 'test'];
 // The templates sit beside the runtime in a checkout (packages/hfs/templates) and one level above the bundled runtime of @starci/hfs.
 const TEMPLATE_ROOTS = [path.resolve(import.meta.dirname, '..', '..', '..', 'packages', 'hfs', 'templates'), path.resolve(import.meta.dirname, '..', '..', '..', '..', 'templates')];
 const managedScriptCache = new Map();

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

@@ -15,7 +15,6 @@ import { checkTiers, TIER_RULE_IDS } from './tiers.mjs';
 import { checkReachability, REACHABILITY_RULE_IDS } from './reachability.mjs';
 import { checkDeadExports, DEAD_EXPORT_RULE_IDS } from './dead-exports.mjs';
 import { checkRequiredFiles, REQUIRED_FILE_RULE_IDS } from './required-files.mjs';
-import { checkSizeGrowth, SIZE_GROWTH_RULE_IDS } from './size-growth.mjs';
 import { checkClones, CLONE_RULE_IDS } from './clones.mjs';
 import { checkSymbols, SYMBOL_RULE_IDS } from './symbols.mjs';
 import { checkConnectionMap, CONNECTION_RULE_IDS } from './connection-map.mjs';
@@ -43,6 +42,7 @@ import { checkPackageShape, PACKAGE_SHAPE_RULE_IDS } from './package-shape.mjs';
 import { checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS } from './fe-slot-allows.mjs';
 import { checkI18nKeys, I18N_KEYS_RULE_IDS } from './i18n-keys.mjs';
 import { checkDocLanguage, DOC_LANGUAGE_RULE_IDS } from './doc-language.mjs';
+import { LINT_CODES, onLintSurface } from './surface.mjs';
 
 export { REGISTRATION_RULE_IDS, SWR_DATA_RULE_IDS };
 
@@ -138,13 +138,12 @@ export const ERROR_RULE_IDS = Object.freeze([
 ]);
 
 const machineIds = () => [
-  ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS, ...DEAD_EXPORT_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...SIZE_GROWTH_RULE_IDS, ...CLONE_RULE_IDS, ...SYMBOL_RULE_IDS,
+  ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS, ...DEAD_EXPORT_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...CLONE_RULE_IDS, ...SYMBOL_RULE_IDS,
   ...Object.values(BACKEND_MACHINE).flatMap(([, ids]) => ids), ...Object.values(FRONTEND_MACHINE).flatMap(([, ids]) => ids),
 ];
 /**
- * The rules only the HFS machine emits: the tier, reachability, dead-export, required-file, size, clone and symbol checks and the
- * backend composition and data machine and frontend repository machine. A rule id an ordinary check also emits (the composition
- * spec and the app-composition check both report BE_APP_COMPOSITION_ONLY) is not here. A spec about another rule judges its own
+ * The rules only the HFS machine emits: the tier, reachability, dead-export, required-file, clone and symbol checks and the
+ * backend composition and data machine and frontend repository machine. A spec about another rule judges its own
  * report without these (they have their own specs); every one of them is in ARCHITECTURE_RULE_IDS.
  */
 export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
@@ -156,7 +155,7 @@ export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
 /** Every code the machine can emit, derived from the rule id lists of its checks (`hfs check` ships exactly these why entries). */
 export const ARCHITECTURE_RULE_IDS = Object.freeze([...new Set([
   ...COMMON_RULE_IDS, ...BACKEND_RULE_IDS, ...FRONTEND_RULE_IDS, ...HFS_RULE_IDS, ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS,
-  ...DEAD_EXPORT_RULE_IDS, ...DOC_LANGUAGE_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...SIZE_GROWTH_RULE_IDS, ...CLONE_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS,
+  ...DEAD_EXPORT_RULE_IDS, ...DOC_LANGUAGE_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...CLONE_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS,
   ...REGISTRATION_RULE_IDS, ...SWR_DATA_RULE_IDS, ...SYMBOL_RULE_IDS, SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID, PUBLIC_CONTRACT_RULE_ID,
   READONLY_BOUNDARY_RULE_ID, ...ERROR_RULE_IDS, ...CONFIG_UNREAD_RULE_IDS, ...Object.values(BACKEND_MACHINE).flatMap(([, ids]) => ids), ...Object.values(FRONTEND_MACHINE).flatMap(([, ids]) => ids),
 ])].sort());
@@ -169,7 +168,8 @@ function stable(items) {
  * Check a target repository. injectedTypeScript exists only for hermetic rule fixtures. `fast` leaves out the checks
  * that read the whole repository to answer (clones, dead exports, repository-wide symbols); the pre-push check of the changed owners uses it.
  */
-export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths = [], base, fast = false, hfs: openedHfs } = {}) {
+export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths = [], base, fast = false, hfs: openedHfs, surface = 'all' } = {}) {
+  if (!['all', 'lint', 'check'].includes(surface)) throw new Error(`unknown surface ${surface}`);
   let config;
   try {
     config = loadArchitectureConfig(repositoryRoot, { hfs: openedHfs });
@@ -233,24 +233,30 @@ export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths =
   }
   // HFS machine: the slot-driven graph checks read the whole program, also when the caller asked for one path.
   const hfsContext = paths.length ? buildTypeScriptContext(config, injectedTypeScript) : context;
-  const hfsChecks = { tiers: null, reachability: null, deadExports: null, requiredFiles: null, sizeGrowth: null, clones: null, symbols: null, docLanguage: null };
+  const hfsChecks = { tiers: null, reachability: null, deadExports: null, requiredFiles: null, clones: null, symbols: null, docLanguage: null };
   if (hfsContext.program) {
     const graph = buildHfsGraph(config, hfsContext);
     const input = { config, context: hfsContext, graph, base };
     const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
-      requiredFiles: () => checkRequiredFiles(input), sizeGrowth: () => checkSizeGrowth(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
+      requiredFiles: () => checkRequiredFiles(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
     if (graph.profile === 'be') for (const [name, [check]] of Object.entries(BACKEND_MACHINE)) runs[name] = () => check(input);
     if (graph.profile === 'fe') for (const [name, [check]] of Object.entries(FRONTEND_MACHINE)) runs[name] = () => check(input);
     if (fast) { delete runs.deadExports; delete runs.clones; delete runs.symbols; }
     for (const [name, run] of Object.entries(runs)) {
       const result = run();
-      violations.push(...result.violations);
+      violations.push(...result.violations.map(violation => ({ ...violation, check: name })));
       hfsChecks[name] = result.coverage;
     }
   }
   const inScope = item => !paths.length || (item.path && paths.some(prefix => sameOrUnder(item.path, prefix.replace(/\/$/, ''))));
-  const errors = stable(context.errors.filter(item => item.ruleId.startsWith('ARCH_TSCONFIG_') || !item.path || inScope(item)));
-  const scopedViolations = stable(violations.filter(inScope));
+  // Two findings travel as context errors (package boundary edges); they are obligations of the lint surface like any other finding.
+  const asViolation = item => LINT_CODES.has(item.ruleId);
+  const allErrors = context.errors.filter(item => item.ruleId.startsWith('ARCH_TSCONFIG_') || !item.path || inScope(item));
+  const obligations = surface === 'all' ? violations : [...violations, ...context.errors.filter(asViolation).filter(inScope)];
+  // The lint surface is what an editor can show on a line of a TypeScript file; `hfs check` keeps every other finding of the machine.
+  const onSurface = item => surface === 'all' || onLintSurface(config.root, item) === (surface === 'lint');
+  const errors = stable(surface === 'all' ? allErrors : allErrors.filter(item => !asViolation(item)));
+  const scopedViolations = stable(obligations.filter(inScope).filter(onSurface));
   const sourceFiles = new Set(context.files.map(file => canonical(file.fileName)));
   const missingOwnerEntries = config.owners?.filter(owner => !sourceFiles.has(canonical(path.resolve(config.root, ...owner.entry.split('/'))))) ?? [];
   const coverage = {
@@ -282,7 +288,6 @@ export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths =
     ...(hfsChecks.reachability?.status === 'checked' ? REACHABILITY_RULE_IDS : []),
     ...(hfsChecks.deadExports?.status === 'checked' ? DEAD_EXPORT_RULE_IDS : []),
     ...(hfsChecks.requiredFiles?.status === 'checked' ? REQUIRED_FILE_RULE_IDS : []),
-    ...(hfsChecks.sizeGrowth?.status === 'checked' ? SIZE_GROWTH_RULE_IDS : []),
     ...(hfsChecks.clones?.status === 'checked' ? CLONE_RULE_IDS : []),
     ...(hfsChecks.symbols?.status === 'checked' ? SYMBOL_RULE_IDS : []),
     ...(hfsChecks.docLanguage?.status === 'checked' ? DOC_LANGUAGE_RULE_IDS : []),

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

@@ -1,14 +1,20 @@
 import path from 'node:path';
 import { canonical, isInside } from './config.mjs';
-import { relativePath, sourceLocation } from './typescript.mjs';
+import { relativePath, sourceLocation, workspaceExportSources } from './typescript.mjs';
 
 function absolute(root, relative) {
   return canonical(path.resolve(root, ...relative.split('/')));
 }
 
-function ownerDeclarations(config) {
-  return config.owners.map(owner => ({ ...owner, root: absolute(config.root, owner.root), entry: absolute(config.root, owner.entry) }))
-    .sort((a, b) => b.root.length - a.root.length);
+/** The owner's public entries: its declared entry, plus every source file its package.json `exports` maps when the owner is a workspace package. */
+function ownerDeclarations(config, context) {
+  return config.owners.map(owner => {
+    const root = absolute(config.root, owner.root);
+    const entry = absolute(config.root, owner.entry);
+    const workspace = context.workspaces?.find(item => item.root === root);
+    const entries = new Set([entry, ...(workspace ? workspaceExportSources(context.ts, workspace) : [])]);
+    return { ...owner, root, entry, entries };
+  }).sort((a, b) => b.root.length - a.root.length);
 }
 
 function ownerOf(owners, file) {
@@ -24,7 +30,7 @@ function privateOwnerChain(context, owners, edge) {
     if (visited.has(current.file)) continue;
     visited.add(current.file);
     const owner = ownerOf(owners, current.file);
-    if (owner && sourceOwner?.id !== owner.id) return current.file === owner.entry ? null : { owner, chain: current.chain };
+    if (owner && sourceOwner?.id !== owner.id) return owner.entries.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] });
     }
@@ -46,7 +52,7 @@ function arrangesSchema(config, from, to) {
 /** 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);
+  const owners = ownerDeclarations(config, context);
   const violations = [];
   const sourceFiles = new Map(context.files.map(file => [canonical(file.fileName), file]));
   for (const owner of owners) {

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

@@ -0,0 +1,91 @@
+/**
+ * The lint surface: which architecture-machine findings an ESLint rule judges instead of `hfs 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.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BE = ['be'];
+const FE = ['fe'];
+const BOTH = ['be', 'fe'];
+
+// `via` names the machine check (the key of its run in index.mjs) when two enforcers share a code; `origin: 'repo'` marks a finding of the
+// slot manifest's per-path judgement (hfs-path-findings.mjs) instead of the machine. A finding reaches exactly one rule.
+const enforcer = (id, plugins, codes, description, extra = {}) => Object.freeze({ id, plugins: Object.freeze(plugins), codes: Object.freeze(codes), description, ...extra });
+
+export const LINT_ENFORCERS = Object.freeze([
+  enforcer('duplicate-code', BOTH, ['HFS_DUPLICATE_CODE'], 'A block of production code never repeats elsewhere in the owner graph.'),
+  enforcer('duplicate-symbol', BOTH, ['HFS_DUPLICATE_SYMBOL'], 'A symbol name is declared once across the production source.'),
+  enforcer('alias-reexport', BOTH, ['HFS_ALIAS_REEXPORT'], 'An owner entry re-exports a symbol under its own name, never through a const alias.'),
+  // cross-app-duplicate emits only FE_CROSS_APP_DUPLICATE today; HFS_DUPLICATE_CODE is named in its comment only.
+  enforcer('cross-app-duplicate', FE, ['FE_CROSS_APP_DUPLICATE'], 'A file is never copied between apps; shared code lives in a package.'),
+  enforcer('dead-exports', BOTH, ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'], 'Every owner export and every production file is reached by a root.'),
+  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('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.'),
+  enforcer('owner-export-bypass', BOTH, ['ARCH_OWNER_EXPORT_BYPASS', 'ARCH_OWNER_EXPORT_STAR'], 'Another owner is imported only through its index entry, and an entry never uses export star.'),
+  enforcer('feature-not-composed', BE, ['BE_FEATURE_NOT_COMPOSED'], 'Every feature owner is composed into an app.'),
+  enforcer('owner-reachable', FE, ['FE_OWNER_REACHABLE', 'FE_HREF_RESOLVES'], 'Every owner is mounted by a route and every href resolves to a route.'),
+  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('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.'),
+  // BE_MODULE_SHAPE is emitted by both register-once and module-per-transport.
+  enforcer('register-once', BE, ['BE_MODULE_SHAPE'], 'A module is registered once and imported by one module.', { via: 'registerOnce' }),
+  enforcer('module-per-transport', BE, ['BE_MODULE_SHAPE'], 'An app imports transport modules only.', { via: 'modulePerTransport' }),
+  enforcer('module-registration', BE, ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'], 'Every handler is registered by a module and no provider is registered twice.'),
+  enforcer('background-unowned', BE, ['BE_BACKGROUND_UNOWNED'], 'Every background job is reachable from a worker app.'),
+  enforcer('test-world-files', BE, ['BE_TEST_TOPOLOGY'], 'The test world files match the stack declaration.'),
+  enforcer('unit-spec-providers', BE, ['BE_SPEC_QUALITY'], 'A unit spec provides exactly the dependencies its service constructor takes.'),
+  enforcer('transport-owner', FE, ['FE_TRANSPORT_OWNER'], 'One client and one outcome type own the transport of the repository.'),
+  enforcer('swr-data-lifecycle', FE, ['FE_SWR_KEY_IDENTITY', 'FE_SWR_MUTATION_RESOURCE_IDENTITY'], 'SWR keys and mutations share one resource identity.'),
+  enforcer('route-files-thin', FE, ['FE_ROUTE_FILES_THIN'], 'A route file only mounts one feature owner.'),
+  enforcer('route-adapter', FE, ['FE_ROUTE_ONE_PAGE', 'FE_ROUTE_DRAWING_DECISION', 'FE_ROUTE_CLIENT_BOUNDARY', 'FE_ROUTE_CLIENT_HOOK', 'FE_ROUTE_DEFAULT_EXPORT'], 'A page route is a server adapter that mounts one pages-tier component.'),
+  enforcer('client-reaches-server', FE, ['FE_CLIENT_REACHES_SERVER'], 'Client code never reaches server-only code through any import chain.'),
+  enforcer('hooks-are-hooks', FE, ['FE_HOOKS_ARE_HOOKS'], 'A hooks folder holds hooks only, one shared file per domain.'),
+  enforcer('hook-location', FE, ['FE_CUSTOM_HOOK_LOCATION', 'FE_BLOCK_PRODUCT_HOOK_DEFINITION', 'FE_COMPONENT_DEEP_HOOK_IMPORT'], 'A custom hook is defined in the hooks folder and imported through its entry.'),
+  enforcer('connection-map', BE, ['BE_CONNECTION_DUPLICATE'], 'Each database connection is declared once and matches the connection map.'),
+  enforcer('injection-token-exported', BE, ['BE_RAW_INJECT'], 'An injection token is exported by its owner and never injected raw.'),
+  enforcer('sql-owner', BE, ['BE_SQL_TABLE_OWNER'], 'A SQL table is touched only by the owner of its entity.'),
+  enforcer('readonly-boundary', BE, ['BE_READONLY_BOUNDARY'], 'Messages and injected classes crossing a boundary are readonly.'),
+  enforcer('source-names', BE, ['BE_SOURCE_FORM'], 'Names and forms inside a source file follow its role.'),
+  enforcer('public-contract-form', BE, ['BE_PUBLIC_CONTRACT_FORM'], 'A public signature is typed by a named contract, never inline or untyped.'),
+  enforcer('frontend-source-layout', FE, ['FE_SOURCE_LAYOUT_INVALID'], 'A front-end source file sits in a tier folder.'),
+  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.
+  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' }),
+  // The two below are emitted into context.errors today, not into violations.
+  enforcer('package-imports-app', BOTH, ['ARCH_PACKAGE_IMPORTS_APP'], 'A package never imports an app.'),
+  enforcer('package-export-bypass', BOTH, ['ARCH_PACKAGE_EXPORT_BYPASS'], 'A package is imported only through its declared exports.'),
+]);
+
+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) {
+  const file = violation?.path;
+  if (typeof file !== 'string' || !TS_SOURCE.test(file)) return false;
+  return fs.existsSync(path.join(repositoryRoot, ...file.split('/')));
+}
+
+/** The finding's code: a machine violation spells it `ruleId`, a repository finding `code`. */
+export const codeOf = (finding) => finding?.ruleId ?? finding?.code;
+
+/** Whether `finding` (with its origin and check tags) belongs to `enforcer`. */
+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. */
+export const onLintSurface = (repositoryRoot, finding) => LINT_ENFORCERS.some(enforcer => belongsTo(enforcer, finding)) && attachesToSource(repositoryRoot, finding);

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

@@ -184,7 +184,7 @@ function workspaceMetadata(config) {
     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,
+    return { root: canonical(root), relative, name: typeof pkg.name === 'string' ? pkg.name : null, exports: pkg.exports, manifest: pkg, workspace: true,
       app: routeRoots.some(route => isInside(root, route))
         || backendAppRoots.some(appRoot => isInside(appRoot, root) || isInside(root, appRoot)) };
   };
@@ -212,18 +212,19 @@ function exportTargetStrings(value) {
   return [];
 }
 
-function packageExported(workspace, specifier, actualTarget) {
-  if (!workspace.name || !sameOrUnder(specifier, workspace.name)) return false;
+/** The package-relative export targets a request (`.` or `./sub`) of a workspace package declares, from exports, else types/main. */
+function exportCandidates(workspace, specifier) {
+  if (!workspace.name || !sameOrUnder(specifier, workspace.name)) return [];
   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;
+    if (request !== '.') return [];
     candidates = exportTargetStrings(declaration);
   } else if (declaration && typeof declaration === 'object') {
     const keys = Object.keys(declaration);
     if (!keys.some(key => key.startsWith('.'))) {
-      if (request !== '.') return false;
+      if (request !== '.') return [];
       candidates = exportTargetStrings(declaration);
     } else {
       for (const key of keys) {
@@ -232,10 +233,80 @@ function packageExported(workspace, specifier, actualTarget) {
       }
     }
   }
-  return candidates.some(target => {
+  return candidates;
+}
+
+const SOURCE_EXTENSIONS = { '.d.ts': ['.ts', '.tsx'], '.d.mts': ['.mts'], '.d.cts': ['.cts'], '.js': ['.ts', '.tsx'], '.jsx': ['.tsx'], '.mjs': ['.mts'], '.cjs': ['.cts'] };
+
+/** rootDir and outDir of a workspace package's build tsconfig (tsconfig.build.json, else tsconfig.json), extends followed; null when it declares none. */
+function workspaceBuildLayout(ts, workspace) {
+  if (workspace.layout !== undefined) return workspace.layout;
+  workspace.layout = null;
+  for (const name of ['tsconfig.build.json', 'tsconfig.json']) {
+    const file = path.join(workspace.root, name);
+    if (!fs.existsSync(file)) continue;
+    const read = ts.readConfigFile(file, ts.sys.readFile);
+    if (read.error) continue;
+    const { options } = ts.parseJsonConfigFileContent(read.config, ts.sys, workspace.root, undefined, file);
+    if (options.outDir) { workspace.layout = { rootDir: options.rootDir ? path.resolve(options.rootDir) : path.join(workspace.root, 'src'), outDir: path.resolve(options.outDir) }; break; }
+  }
+  return workspace.layout;
+}
+
+/** The source file a built export target (`./dist/sub/index.js`, `.d.ts`) stands for: outDir back to rootDir, else the dist-to-src layout; null when none exists. */
+function sourceOfTarget(ts, workspace, target) {
+  const absolute = path.resolve(workspace.root, target);
+  const layout = workspaceBuildLayout(ts, workspace);
+  const extension = Object.keys(SOURCE_EXTENSIONS).filter(item => absolute.endsWith(item)).sort((a, b) => b.length - a.length)[0];
+  const sourceRoots = [];
+  if (layout && isInside(layout.outDir, absolute)) sourceRoots.push([layout.outDir, layout.rootDir]);
+  const first = slash(path.relative(workspace.root, absolute)).split('/')[0];
+  if (first) sourceRoots.push([path.join(workspace.root, first), path.join(workspace.root, 'src')]);
+  if (!extension) return null;
+  for (const [from, to] of sourceRoots) {
+    const stem = path.join(to, path.relative(from, absolute)).slice(0, -extension.length);
+    for (const candidate of SOURCE_EXTENSIONS[extension]) if (fs.existsSync(stem + candidate)) return canonical(stem + candidate);
+  }
+  return null;
+}
+
+/** The source entry a workspace import resolves to without a build: its export targets mapped back to source, `src/index.ts` for the package root. */
+function workspaceSourceEntry(ts, workspace, specifier) {
+  if (!workspace.workspace || !workspace.name || !sameOrUnder(specifier, workspace.name)) return null;
+  let candidates = exportCandidates(workspace, specifier);
+  if (specifier === workspace.name && !workspace.exports) candidates = [workspace.manifest?.types, workspace.manifest?.typings, workspace.manifest?.module, workspace.manifest?.main].filter(item => typeof item === 'string');
+  for (const target of candidates) {
+    if (!target.startsWith('./') || target.includes('..')) continue;
+    const source = sourceOfTarget(ts, workspace, target);
+    if (source) return source;
+  }
+  if (specifier === workspace.name) {
+    for (const name of ['index.ts', 'index.tsx']) if (fs.existsSync(path.join(workspace.root, 'src', name))) return canonical(path.join(workspace.root, 'src', name));
+  }
+  return null;
+}
+
+/** Every source file the package.json `exports` of a workspace package maps (each non-wildcard subpath, dist back to source): its public entries. */
+export function workspaceExportSources(ts, workspace) {
+  const declaration = workspace.exports;
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) return [];
+  const sources = new Set();
+  for (const [key, value] of Object.entries(declaration)) {
+    if (!key.startsWith('.') || key.includes('*')) continue;
+    for (const target of exportTargetStrings(value)) {
+      if (!target.startsWith('./') || target.includes('..')) continue;
+      const source = sourceOfTarget(ts, workspace, target);
+      if (source) sources.add(source);
+    }
+  }
+  return [...sources];
+}
+
+function packageExported(ts, workspace, specifier, actualTarget) {
+  return exportCandidates(workspace, specifier).some(target => {
     if (!target.startsWith('./') || target.includes('..')) return false;
     const expected = canonical(path.resolve(workspace.root, target));
-    return expected === canonical(actualTarget);
+    return expected === canonical(actualTarget) || sourceOfTarget(ts, workspace, target) === canonical(actualTarget);
   });
 }
 
@@ -385,7 +456,9 @@ function typeScriptContext(config, loaded, paths) {
       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);
+      // A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
+      const workspaceTarget = workspaces.filter(item => item.root !== canonical(config.root)).map(item => workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
+      const resolvedName = workspaceTarget ?? 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));
@@ -443,7 +516,7 @@ function typeScriptContext(config, loaded, paths) {
         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)) {
+        if (!packageExported(ts, 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.'));
         }
       }

package/runtime/scripts/checks/architecture.mjs

@@ -7,6 +7,7 @@
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {checkArchitecture} from './architecture/index.mjs';
+import { isMain } from './common.mjs';
 
 export {checkArchitecture};
 
@@ -38,4 +39,4 @@ export function architectureMain(argv, {check = checkArchitecture, write = (text
   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));
+if (isMain(import.meta.url)) process.exitCode = architectureMain(process.argv.slice(2));

package/runtime/scripts/checks/common.mjs

@@ -9,7 +9,14 @@ export function isInside(root, target) {
 }
 
 /** True when this module is the process entry point (`node file.mjs`, not an import). */
-export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && path.resolve(argv[1]) === fileURLToPath(metaUrl);
+/** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
+const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
+/**
+ * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
+ * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
+ * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
+ */
+export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));
 
 /**
  * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full