@starci/eslint-canon-fe 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 7.1.0 - 2026-10-01
+
+- New: the `project-graph` law: the TS-attached front-end architecture checks (routes, owners, paths) as eslint rules at error, from one cached project graph per lint run.
+
+- Breaking (rule id): `no-http-status-collapse` is renamed `no-failure-collapse`. It fires on UI code that consumes an `Outcome` as well as on HTTP clients, so its name and messages now speak of a failure and its reason (branch on an `Outcome`'s reason code; map an HTTP status to an `Outcome` first). A branch that reads `reason` or `kind` counts as inspecting the failure. Update any `eslint-disable` naming the old id; there is no alias.
+
 ## 7.0.0 - 2026-09-30
 
 - **New: `no-vietnamese-in-source` (R91).** Identifiers, string literals, template text, JSX text, comments and test titles carry no Vietnamese letter, specs included. Detection is structural on characters (`scripts/lib/language.mjs` in `runtime/`, folded to NFC, so NFD is caught too). The only exemption is the i18n fixtures slot `fe.e2e-support.i18n` (`e2e/fixtures/i18n/`). Removed: the second-language branches of `no-hardcoded-copy` (its `second` and `comment` messages) and the `SECOND_LANGUAGE_LETTER` export; the one rule holds the law.

package/docs/transport.md

@@ -95,9 +95,9 @@ if (r.status === 401 || r.status === 403) return { ok: false, kind: "refused" }
 
 **Fix:** Add a branch `response.status === 401 || response.status === 403` returning `{ ok: false, kind: "refused" }` inside the client.
 
-## `starci-fe/no-http-status-collapse`
+## `starci-fe/no-failure-collapse`
 
-A non-ok response is not folded into one branch or into null; 401/403 become `refused`.
+A failure, a non-ok HTTP response or a failed `Outcome`, is not folded into one branch or into an empty value; its reason is read and kept (an HTTP status is mapped first: 401/403 `refused`, 404 `not-found`, 422 `invalid`, the rest `unavailable`).
 
 **Invalid** (`src/modules/api/client.ts`)
 
@@ -113,9 +113,9 @@ if (!res.ok) return toOutcome(res.status)
 
 **Finding code:** `FE_HTTP_STATUS_COLLAPSE`
 
-**Why:** `<file>` collapses every HTTP code into one branch (or returns null on an error response). 401/403 must become `refused`.
+**Why:** `<file>` collapses every failure (a failed HTTP response or a failed `Outcome`) into one branch or an empty value, so its reason is lost.
 
-**Fix:** Return an `Outcome` by code: `refused` (401/403), `not-found`, `invalid`, `unavailable`; do not return the server's raw error as the reason.
+**Fix:** Keep the reason: branch on an `Outcome`'s reason code; map an HTTP status to an `Outcome` first (`refused` for 401/403, `not-found`, `invalid`, `unavailable`). Never use the server's raw text as the reason.
 
 ## `starci-fe/no-hand-typed-wire`
 

package/index.mjs

@@ -46,11 +46,13 @@ import { recommended as translationRecommended, rules as translationRules } from
 import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
 import { recommended as typographyRecommended, rules as typographyRules } from "./typography.mjs"
 import { recommended as vendorRecommended, rules as vendorRules } from "./vendor-boundary.mjs"
+import { recommended as projectGraphRecommended, rules as projectGraphRules } from "./project-graph.mjs"
 import { buildFeConfig } from "./lib/config.mjs"
 import { why } from "./lib/why.mjs"
 
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
 const CONTRIBUTIONS = [
+    { law: "project-graph", rules: projectGraphRules, recommended: projectGraphRecommended },
   { law: "brand-values", rules: brandValuesRules, recommended: brandValuesRecommended },
   { law: "client-boundary", rules: clientBoundaryRules, recommended: clientBoundaryRecommended },
   { law: "comments", rules: commentsRules, recommended: commentsRecommended },

package/lib/why.mjs

@@ -46,10 +46,10 @@ export const why = {
     vi: "Client ở `<file>` không có nhánh so sánh `response.status` với 401 và 403 rồi trả `{ kind: \"refused\" }`, nên trạng thái \"cần đăng nhập\" không bao giờ đạt được.",
     fixVi: "Thêm nhánh `response.status === 401 || response.status === 403` trả `{ ok: false, kind: \"refused\" }` ngay trong client.",
   },
-  "no-http-status-collapse": {
+  "no-failure-collapse": {
     code: "FE_HTTP_STATUS_COLLAPSE",
-    vi: "`<file>` gộp mọi mã HTTP thành một nhánh (hoặc trả null khi phản hồi lỗi). 401/403 phải thành `refused`.",
-    fixVi: "Trả `Outcome` theo mã: `refused` (401/403), `not-found`, `invalid`, `unavailable`; không trả nguyên văn lỗi của server làm lý do.",
+    vi: "`<file>` gộp mọi thất bại (phản hồi HTTP lỗi hoặc `Outcome` thất bại) thành một nhánh hoặc một giá trị rỗng, nên lý do bị mất.",
+    fixVi: "Giữ lý do: với `Outcome` thì rẽ nhánh theo mã lý do; với phản hồi HTTP thì đổi mã trạng thái thành `Outcome` (`refused` cho 401/403, `not-found`, `invalid`, `unavailable`). Không dùng nguyên văn lỗi của server làm lý do.",
   },
   "no-hand-typed-wire": {
     code: "FE_WIRE_GENERATED",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin and attached by one factory.",
   "type": "module",
   "license": "UNLICENSED",

package/project-graph.mjs

@@ -0,0 +1,23 @@
+/**
+ * The rules that read the project graph: the findings of the architecture machine that sit on a TypeScript file.
+ *
+ * One graph per lint run: `scripts/lib/project-graph.mjs` (a byte copy in this package's runtime/) builds the machine's module
+ * graph and slot manifest once for the repository, caches it, and each rule below reports the findings of its own codes on
+ * the file ESLint is visiting, on the line the machine names. There is no second graph and no second judge: the list of
+ * rules and their codes is `LINT_ENFORCERS` of the machine (scripts/checks/architecture/surface.mjs); `hfs check` keeps the
+ * findings that have no TypeScript file to sit on. A graph that cannot be built stops the run with the machine's message.
+ */
+import { LINT_ENFORCERS } from "./runtime/scripts/checks/architecture/surface.mjs"
+import { projectRule } from "./runtime/scripts/lib/project-rule.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "runtime")
+const mine = LINT_ENFORCERS.filter((enforcer) => enforcer.plugins.includes("fe"))
+
+/** The rules this law contributes to the plugin: one per graph enforcer of this profile. */
+export const rules = Object.fromEntries(mine.map((e) => [e.id, projectRule({ enforcer: e, runtimeRoot: RUNTIME, hfsOf })]))
+
+/** Every one at error. */
+export const recommended = Object.fromEntries(mine.map((e) => [`starci-fe/${e.id}`, "error"]))

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -0,0 +1,309 @@
+schema: starci/knowledge-source@1
+id: fe.folder
+title: Folder
+purpose: |
+  Given a piece of frontend code, which directory and which file name does it get? Apply the HFS frontend tree
+  (knowledge/hfs/README.md section 6, slots fe.*).
+appliesTo:
+  - frontend
+family: fe
+provenance:
+  reviewedAt: 2026-09-29
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - https://nextjs.org/docs/app/getting-started/project-structure
+    - https://next-intl.dev/docs/routing
+    - packages/grammar/src/**
+  limitations: |
+    Folder rules place code by responsibility. They do not prove rendered behavior or accessibility. Inspect the
+    selected repository's actual source, manifests, aliases and lint and test configuration. Verify installed Grammar
+    exports at @starci/grammar/common.
+rules:
+  - id: FE-FOLDER-1
+    title: Responsibility directories
+    kind: mandatory
+    hfsRules: [R01, R02, R59, R64]
+    requirement: |
+      Every frontend repository is an apps/<app>/ monorepo even with one app, named by its role (for example web), and
+      all product source lives under apps/<app>/src. A repository-root src/ does not exist. Each Next source root
+      (apps/<app>/src) uses app/ for framework adapters; features/{pages,layouts,overlays} for route-facing product
+      composition; components/{blocks,composites,branches,leaves} for product visuals; hooks/<domain> for React hooks;
+      and modules/<capability> for cohesive reusable technical and domain capabilities. Every app has the modules api,
+      config, i18n and routes, and one brand.css under modules/brand when it sets brand tokens. No other empty role
+      folder is required. Grammar remains a separate product-agnostic package. The only files that may sit directly in the
+      source root (the directory holding app/) are the framework-pinned root files listed in frameworkPinnedRootFiles
+      below: Next.js loads them from that exact place. Each is a thin framework adapter whose internal imports enter
+      modules or a feature public entry only; every other rule still applies to it, except that the export names the
+      framework mandates there (frameworkPinnedRootExports) keep their framework spelling. HFS uses proxy.ts for locale
+      routing; a middleware.* file is refused on Next 16 and later by the Next conventions check and the slot
+      fe.source-root-pinned, even though the machine list names it as a file Next loads. Any other file at the source
+      root, including a helper folder beside a pinned file, has no owner and is refused.
+    frameworkPinnedRootFiles:
+      # Machine list read by scripts/checks/architecture/framework-pinned.mjs (FE_SOURCE_LAYOUT_INVALID accepts exactly
+      # these basenames directly in a Next source root; FE_TIER_DIRECTION keeps them thin). Exact names,
+      # case-sensitive, no globs. It lists what the framework loads from the source root. Which of them a repository may
+      # keep is decided by the slot fe.source-root-pinned and FE_NEXT_CONVENTIONS, not by this list.
+      # Machine list read by scripts/checks/architecture/framework-pinned.mjs (FE_SOURCE_LAYOUT_INVALID
+      # accepts exactly these basenames directly in a Next source root;
+      # their imports follow the FE_TIER_DIRECTION matrix). Exact names, case-sensitive, no globs. Supervisor rulings for nivo
+      # wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4 and inc-846867b9a34e (proxy is the Next 16 name of
+      # middleware, listed so the list survives the upgrade).
+      - middleware.ts
+      - middleware.js
+      - middleware.mjs
+      - proxy.ts
+      - proxy.js
+      - proxy.mjs
+      - instrumentation.ts
+      - instrumentation.js
+      - instrumentation.mjs
+      - instrumentation-client.ts
+      - instrumentation-client.js
+      - instrumentation-client.mjs
+      - next-env.d.ts
+    frameworkPinnedRootExports:
+      # Export names the framework mandates in a pinned root file, keyed by file stem (read by
+      # scripts/checks/architecture/framework-pinned.mjs). FE_SOURCE_NAME_SHAPE accepts exactly these names in exactly
+      # these files when they sit directly in a Next source root; everywhere else the name-shape rule is unchanged.
+      middleware: [config, middleware, default]
+      proxy: [config, proxy, default]
+      instrumentation: [register, onRequestError]
+      instrumentation-client: [onRouterTransitionStart]
+    rationale: |
+      One fixed source root per app keeps every repository the same shape while preventing app helpers, component-local
+      hooks and feature-local transport buckets from becoming undeclared owners.
+    cases:
+      - id: case-1
+        when: "A routed authentication scenario"
+        write: "apps/<app>/src/features/pages/AuthenticationPage/index.tsx"
+      - id: case-2
+        when: "A reusable API client, reader or session capability"
+        write: >
+          apps/<app>/src/modules/api/ or apps/<app>/src/modules/session/ with one explicit public index.ts entry
+      - id: case-3
+        when: "A reusable product visual without scenario ownership"
+        write: "apps/<app>/src/components/{blocks,composites,branches,leaves}/<Name>/index.tsx"
+      - id: case-4
+        when: "A React hook"
+        write: "apps/<app>/src/hooks/<domain>/useAutoScroll.ts; built-in React hook calls may remain in visuals"
+      - id: case-5
+        kind: exception
+        when: "Next.js only loads the file from the source root (proxy, instrumentation, instrumentation-client, next-env.d.ts)"
+        write: >
+          apps/<app>/src/proxy.ts beside apps/<app>/src/app/ as a thin adapter; locale routing logic lives in
+          apps/<app>/src/modules/i18n/ and the adapter imports it; the names the framework mandates there
+          (frameworkPinnedRootExports, for example export const config = { matcher }) keep their framework spelling
+      - id: case-6
+        when: "Any other file or folder directly under the source root (apps/<app>/src/i18n/request.ts, apps/<app>/src/config.ts), and a repository-root src/"
+        write: >
+          Move it to its owner, for example apps/<app>/src/modules/i18n/request.ts, and point framework configuration
+          (apps/<app>/next.config.ts) at the new path
+      - id: case-7
+        when: "The per-slot data-status recipe"
+        write: >
+          apps/<app>/src/components/composites/SlotView/index.tsx, apps/<app>/src/modules/slot/index.ts (Slot, toSlot,
+          SlotLabels) and apps/<app>/src/hooks/slot/useSlotLabels.ts, one copy each (examples/shape-slot)
+    verification:
+      automated:
+        - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_REQUIRED_MISSING
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_NEXT_CONVENTIONS
+        - FE_TIER_DIRECTION
+        - FE_CUSTOM_HOOK_LOCATION
+        - HFS_APPS_REQUIRED
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+      manual:
+        - Confirm the unit's responsibility and public entry, rather than assigning it by consumer count.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-2
+    title: Discoverable files for one unit
+    kind: mandatory
+    hfsRules: [R02, R55, R65]
+    requirement: |
+      A split unit (a connected block, and a feature page, layout or overlay) uses index.tsx for the connected X and
+      sibling component.tsx for the pure XBase, its XBaseProps and xDefaultState, plus XState when the shape is its own union
+      (a shape that is a domain status is typed with that status, never a second name for it). Only that index.tsx and the
+      unit's specs import component.tsx. Pure blocks, composites, branches and leaves use index.tsx only and never gain an
+      empty twin. classNames.ts is present only when the unit owns class strings. Budgets: component.tsx 300 lines,
+      connected index.tsx 200 lines, at most 6 data hooks and 6 useState per connected unit.
+    rationale: |
+      Stable basenames make class, tests and the connected and presentational split discoverable without forwarding
+      twins, and budgets keep a unit reviewable.
+    cases:
+      - id: case-1
+        when: "Connected block with product-world lifecycle"
+        write: "blocks/CatalogBlock/{index.tsx,component.tsx}; every nonempty index render reaches the sibling"
+      - id: case-2
+        when: "Feature page, layout or overlay"
+        write: >
+          features/pages/OperatePage/{index.tsx,component.tsx,classNames.ts}, features/layouts/WorkspaceLayout/…,
+          features/overlays/SendHandoffOverlay/… (examples/shape-slot)
+      - id: case-3
+        when: "Single visual unit"
+        write: "leaves/ButtonStateSample/{classNames.ts,index.tsx}; no component.tsx twin without a separate world owner"
+      - id: case-4
+        when: "Custom hook or reusable module"
+        write: "hooks/<domain>/useX.ts or modules/<capability>/...; do not create visual twins"
+    verification:
+      automated:
+        - class-names-in-colocated-file
+        - no-inline-class-name
+        - FE_CONNECTED_BLOCK_RENDER_PAIR
+        - FE_SIZE_AND_STATE_BUDGET
+        - HFS_SIZE_GROWTH
+        - starci-fe/base-import-pair
+      manual:
+        - Confirm each file owns a real responsibility; do not add a component.tsx twin by habit.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-3
+    title: Route files adapt to one visual owner and every app has its boundaries
+    kind: mandatory
+    hfsRules: [R53, R54, R55, R57]
+    requirement: |
+      Route files under app/[locale]/ (page, layout, template, loading, not-found) are server components. A route may
+      resolve framework server inputs (params, searchParams, headers, cookies), then mounts one page-level visual owner.
+      A route whose complete responsibility is redirect or notFound mounts none. A route file holds no inline component, no
+      drawing decision and no hook, and a redirect from an old URL lives in next.config redirects(), never in a page. Every app has
+      app/global-error.tsx, app/[locale]/layout.tsx, app/[locale]/error.tsx and app/[locale]/not-found.tsx, and a loading.tsx
+      for each route group that reads data. Each page exports generateMetadata. force-dynamic on a client page is forbidden.
+    rationale: |
+      Keeping default exports in the App Router layer prevents components from becoming route-coupled, and mandatory
+      boundaries turn a render failure into a recoverable screen instead of a blank page.
+    cases:
+      - id: case-1
+        when: "A route"
+        write: >
+          app/[locale]/authentication/page.tsx: const AuthenticationRoute = async () => <AuthenticationPage />, then export
+          default AuthenticationRoute
+      - id: case-2
+        kind: exception
+        when: "Redirect or notFound adapter"
+        write: "Resolve framework inputs and redirect or terminate without a visual owner."
+      - id: case-3
+        when: "Global app files"
+        write: >
+          app/globals.css, app/global-error.tsx, app/[locale]/error.tsx, app/[locale]/not-found.tsx, app/sitemap.ts,
+          app/robots.ts, app/health/{live,ready}/route.ts
+    verification:
+      automated:
+        - FE_ERROR_BOUNDARY_MISSING
+        - FE_ROUTE_FILES_THIN
+        - FE_CLIENT_BOUNDARY
+        - FE_OWNER_REACHABLE
+        - FE_TIER_DIRECTION
+      manual:
+        - Confirm visual routes have one page owner and redirect-only routes have no visual tree.
+    relatedExamples: []
+
+  - id: FE-FOLDER-4
+    title: Hooks are hooks; readers and transport live in modules
+    kind: mandatory
+    hfsRules: [R56, R50, R49]
+    requirement: |
+      hooks/<domain>/ holds React hooks (use*.ts, one hook per file) and exactly one <domain>.shared.ts for shared
+      non-hook helpers of that domain (key builders, token readers). A file in hooks/ that is not a hook and is not the shared
+      file is a finding. Server-side readers (fetch and map, no React) live in modules/api/<domain>/read-*.ts and are
+      wrapped in React cache() when several blocks call them in one request. Generic client plumbing, the Outcome type,
+      the contract copy and generated wire types live in modules/api; environment reading lives in modules/config; every
+      href builder lives in modules/routes; locale routing lives in modules/i18n; colour values live in modules/brand.
+      A helper name defined twice across hook files is a finding.
+    rationale: |
+      A rule that says what a hooks folder is also says where everything else goes, so nobody copies a helper sixteen
+      times or fills hooks/ with server fetch functions.
+    cases:
+      - id: case-1
+        when: "Authentication request lifecycle"
+        write: "apps/<app>/src/hooks/authentication/useAuthentication.ts"
+      - id: case-2
+        when: "A helper shared by the hooks of one domain"
+        write: "apps/<app>/src/hooks/sales/sales.shared.ts, for example useSalesAccessToken's token reader"
+      - id: case-3
+        when: "A server read used by several blocks"
+        write: "apps/<app>/src/modules/api/sales/read-sales-summary.ts, exported through modules/api/index.ts"
+      - id: case-4
+        when: "The API client"
+        write: "apps/<app>/src/modules/api/client.ts and apps/<app>/src/modules/api/outcome.ts"
+      - id: case-5
+        when: "Intrinsic custom helper"
+        write: "apps/<app>/src/hooks/ui/useAutoScroll.ts; direct useRef and useState calls may remain in their visual owner"
+    verification:
+      automated:
+        - FE_HOOKS_ARE_HOOKS
+        - FE_CUSTOM_HOOK_LOCATION
+        - HFS_DUPLICATE_CODE
+        - FE_TIER_DIRECTION
+      manual:
+        - Confirm each lifecycle has one feature owner and transport mechanics have one module owner.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-5
+    title: Package unit
+    kind: mandatory
+    hfsRules: [R63]
+    requirement: |
+      A shared package is packages/<pkg>/ with package.json (explicit exports), src/index.ts, tsconfig.json and colocated
+      specs, built to dist. Grammar components live under packages/grammar/src/core/<tier>/<Name>/ with collocated class
+      strings and specs; family entries and built-output proof stay at the package roots. See packages.yaml for the shared
+      UI package shape.
+    rationale: |
+      Package layout separates primitives from app composition and keeps public entry verification against dist.
+    cases:
+      - id: case-1
+        when: "A Grammar component"
+        write: "packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx"
+      - id: case-2
+        when: "A Grammar component's class strings and spec"
+        write: "sibling classNames.ts and index.spec.tsx"
+      - id: case-3
+        when: "Built-output proof"
+        write: "common/index.test.mjs, core/index.test.mjs, package-boundary.test.mjs (node:test against dist/)"
+    verification:
+      automated:
+        - FE_PACKAGE_SHAPE
+      manual:
+        - Verify public app imports use @starci/grammar/common and installed exports, never the package root.
+    relatedExamples: []
+
+  - id: FE-FOLDER-6
+    title: Keep units cohesive
+    kind: mandatory
+    hfsRules: [R49, R21]
+    requirement: |
+      A unit folder contains files that change for the same responsibility. Do not create generic helpers/ or utils/
+      buckets inside components, read deployment configuration in presentation, or split files solely to meet a count.
+      Collocated subordinate renders and pure helpers are valid when they remain private to the owner; a separately stable
+      responsibility receives its own named owner.
+    rationale: |
+      Cohesion prevents helper sprawl and duplicated configuration while avoiding one-component-per-folder ceremony that
+      has no dependency boundary.
+    cases:
+      - id: case-1
+        when: "A small subordinate render is private to one owner"
+        write: "Keep it local with an unexported contract; extract it when it gains a stable public responsibility."
+      - id: case-2
+        when: "Class strings in component.tsx"
+        write: "Never; they go to classNames.ts (lint class-names-in-colocated-file, no-inline-class-name)"
+      - id: case-3
+        when: "A helpers/ or utils/ folder"
+        write: "Do not use it to hide mixed feature, transport or visual responsibilities."
+      - id: case-4
+        when: "A deployment constant"
+        write: >
+          Never. process.env.NEXT_PUBLIC_* is read only in apps/<app>/src/modules/config and reached through that module,
+          with no localhost fallback; a missing value in production throws when the module loads.
+    verification:
+      automated:
+        - FE_ENV_OWNER
+        - class-names-in-colocated-file
+        - no-inline-class-name
+        - no-helper-folder-in-components
+      manual:
+        - Confirm extraction is justified by ownership or lifecycle rather than file length or count.
+    relatedExamples: []