@starci/eslint-canon-be 3.0.7 → 3.0.9

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

@@ -23,14 +23,16 @@ rules:
   - id: FE-FOLDER-1
     title: Responsibility directories
     kind: mandatory
-    hfsRules: [R01, R02, R59, R64]
+    hfsRules: [R01, R02, R59, R64, R26, R54, R56, R91, R94]
     requirement: |
-      The front end of every app (`fe/`) is an fe/apps/<app>/ monorepo even with one app, named by its role (for example
-      web), and all product source lives under fe/apps/<app>/src. An fe/src/ does not exist. Each Next source root
+      The front end of every app (`fe/`) is an fe/apps/<app>/ monorepo even with one app — each app declared in
+      `hfs.json` `sides.fe.apps` with kind `next` (slot `fe.app.next`; the scaffold writes `landing` and `app`) — and all
+      product source lives under fe/apps/<app>/src. An fe/src/ does not exist. Each Next source root
       (fe/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
+      and modules/<capability> for cohesive reusable technical and domain capabilities. Every app carries the required
+      module instances of slot `fe.modules` and one brand.css under modules/brand when it sets brand tokens
+      (`fe.modules.brand`). 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
@@ -40,15 +42,14 @@ rules:
       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
+      # Machine list read by scripts/hfs/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
+      # Machine list read by scripts/hfs/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).
+      # their imports follow the FE_TIER_DIRECTION matrix). Exact names, case-sensitive, no globs. Supervisor rulings
+      # (proxy is the Next 16 name of middleware, listed so the list survives the upgrade).
       - middleware.ts
       - middleware.js
       - middleware.mjs
@@ -82,7 +83,7 @@ rules:
           fe/apps/<app>/src/modules/api/ or fe/apps/<app>/src/modules/session/ with one explicit public index.ts entry
       - id: case-3
         when: "A reusable product visual without scenario ownership"
-        write: "fe/apps/<app>/src/components/{blocks,composites,branches,leaves}/<Name>/index.tsx"
+        write: "an owner folder of slot `fe.components` under the layer it belongs to — for example fe/apps/<app>/src/components/leaves/<Name>/index.tsx"
       - id: case-4
         when: "A React hook"
         write: "fe/apps/<app>/src/hooks/<domain>/useAutoScroll.ts; built-in React hook calls may remain in visuals"
@@ -94,7 +95,7 @@ rules:
           fe/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 (fe/apps/<app>/src/i18n/request.ts, fe/apps/<app>/src/config.ts), and an fe/src/"
+        when: "Any other file or folder directly under the source root (an `i18n/request.ts` or a `config.ts` there), and an fe/src/"
         write: >
           Move it to its owner, for example fe/apps/<app>/src/modules/i18n/request.ts, and point framework configuration
           (fe/apps/<app>/next.config.ts) at the new path
@@ -106,13 +107,53 @@ rules:
     verification:
       automated:
         - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_AMBIGUOUS
+        - HFS_SLOT_NOT_ENABLED
+        - HFS_FORBIDDEN_PRESENT
+        - HFS_TRACKED_MUST_BE_IGNORED
+        - HFS_ROOT_ENTRY_FORBIDDEN
+        - HFS_ROOT_MARKDOWN_FORBIDDEN
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - HFS_SRC_LAYOUT_INVALID
+        - HFS_MODULE_TIER_INVALID
+        - HFS_WORK_IN_FE
+        - HFS_STACKS_IN_SIDE
         - HFS_SLOT_REQUIRED_MISSING
-        - FE_SOURCE_LAYOUT_INVALID
-        - FE_NEXT_CONVENTIONS
+        - HFS_MIN_INSTANCES
+        - HFS_REQUIRED_FILE_MISSING
+        - HFS_ROOT_ENTRY_MISSING
+        - HFS_APPS_REQUIRED
+        - HFS_APP_LAYOUT_INVALID
+        - HFS_README_TITLE_INVALID
+        - HFS_README_DESCRIPTION_INVALID
+        - HFS_README_SECTION_MISSING
+        - HFS_README_SECTION_ORDER
+        - HFS_README_DEVELOPMENT_INCOMPLETE
+        - HFS_README_WORK_POINTER_MISSING
+        - HFS_README_PRIVATE_URL
+        - HFS_README_BADGE_NOT_LIVE
+        - FE_I18N_PLACEMENT
+        - FE_I18N_NAVIGATION
+        - FE_I18N_FORMATTER
+        - FE_APP_ISOLATION
+        - BE_TIER_DIRECTION
         - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
+        - FE_ROUTE_FILES_THIN
+        - FE_NEXT_CONVENTIONS
+        - FE_PAGE_METADATA_MISSING
+        - FE_ROUTE_ONE_PAGE
+        - FE_ROUTE_DRAWING_DECISION
+        - FE_ROUTE_CLIENT_BOUNDARY
+        - FE_ROUTE_CLIENT_HOOK
+        - FE_ROUTE_DEFAULT_EXPORT
+        - FE_HOOKS_ARE_HOOKS
         - FE_CUSTOM_HOOK_LOCATION
-        - HFS_APPS_REQUIRED
-        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - FE_BLOCK_PRODUCT_HOOK_DEFINITION
+        - FE_COMPONENT_DEEP_HOOK_IMPORT
+        - FE_SOURCE_FORM
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_SLOT_FILE_ROLE
       manual:
         - Confirm the unit's responsibility and public entry, rather than assigning it by consumer count.
     relatedExamples:
@@ -121,7 +162,7 @@ rules:
   - id: FE-FOLDER-2
     title: Discoverable files for one unit
     kind: mandatory
-    hfsRules: [R02, R55, R65]
+    hfsRules: [R02, R55, R65, R20, R92]
     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
@@ -149,12 +190,40 @@ rules:
         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
+        - HFS_SLOT_REQUIRED_MISSING
+        - HFS_MIN_INSTANCES
+        - HFS_REQUIRED_FILE_MISSING
+        - HFS_ROOT_ENTRY_MISSING
+        - HFS_APPS_REQUIRED
+        - HFS_APP_LAYOUT_INVALID
+        - HFS_README_TITLE_INVALID
+        - HFS_README_DESCRIPTION_INVALID
+        - HFS_README_SECTION_MISSING
+        - HFS_README_SECTION_ORDER
+        - HFS_README_DEVELOPMENT_INCOMPLETE
+        - HFS_README_WORK_POINTER_MISSING
+        - HFS_README_PRIVATE_URL
+        - HFS_README_BADGE_NOT_LIVE
+        - FE_CLIENT_BOUNDARY
+        - FE_CLIENT_SERVER_IMPORT
+        - FE_CLIENT_REACHES_SERVER
+        - FE_SERVER_ONLY_MARK
+        - FE_STORAGE_OUTSIDE_MODULES
+        - FE_DANGEROUS_HTML
         - FE_SIZE_AND_STATE_BUDGET
+        - FE_LIST_KEY
+        - FE_EFFECT_CLEANUP
+        - FE_SWALLOWED_ERROR
+        - FE_CONSOLE_CALL
         - HFS_SIZE_GROWTH
-        - starci-fe/base-import-pair
+        - HFS_SIZE_SOFT_BACKLOG
+        - FE_COMPONENT_API
+        - 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
       manual:
         - Confirm each file owns a real responsibility; do not add a component.tsx twin by habit.
     relatedExamples:
@@ -163,7 +232,7 @@ rules:
   - 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]
+    hfsRules: [R53, R54, R55, R57, R26]
     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.
@@ -192,10 +261,27 @@ rules:
     verification:
       automated:
         - FE_ERROR_BOUNDARY_MISSING
+        - FE_SUSPENSE_NULL_FALLBACK
         - FE_ROUTE_FILES_THIN
+        - FE_NEXT_CONVENTIONS
+        - FE_PAGE_METADATA_MISSING
+        - FE_ROUTE_ONE_PAGE
+        - FE_ROUTE_DRAWING_DECISION
+        - FE_ROUTE_CLIENT_BOUNDARY
+        - FE_ROUTE_CLIENT_HOOK
+        - FE_ROUTE_DEFAULT_EXPORT
         - FE_CLIENT_BOUNDARY
+        - FE_CLIENT_SERVER_IMPORT
+        - FE_CLIENT_REACHES_SERVER
+        - FE_SERVER_ONLY_MARK
+        - FE_STORAGE_OUTSIDE_MODULES
+        - FE_DANGEROUS_HTML
         - FE_OWNER_REACHABLE
+        - FE_ROUTE_HARDCODED
+        - FE_HREF_RESOLVES
+        - BE_TIER_DIRECTION
         - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
       manual:
         - Confirm visual routes have one page owner and redirect-only routes have no visual tree.
     relatedExamples: []
@@ -203,7 +289,7 @@ rules:
   - id: FE-FOLDER-4
     title: Hooks are hooks; readers and transport live in modules
     kind: mandatory
-    hfsRules: [R56, R50, R49]
+    hfsRules: [R56, R50, R49, R21, R26]
     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
@@ -235,8 +321,19 @@ rules:
       automated:
         - FE_HOOKS_ARE_HOOKS
         - FE_CUSTOM_HOOK_LOCATION
+        - FE_BLOCK_PRODUCT_HOOK_DEFINITION
+        - FE_COMPONENT_DEEP_HOOK_IMPORT
+        - FE_TRANSPORT_OWNER
+        - FE_EFFECT_FETCH
+        - FE_SWR_KEY_IDENTITY
+        - FE_SWR_MUTATION_RESOURCE_IDENTITY
+        - FE_ENV_OWNER
         - HFS_DUPLICATE_CODE
+        - HFS_DUPLICATE_SYMBOL
+        - FE_CROSS_APP_DUPLICATE
+        - BE_TIER_DIRECTION
         - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
       manual:
         - Confirm each lifecycle has one feature owner and transport mechanics have one module owner.
     relatedExamples:
@@ -274,7 +371,7 @@ rules:
   - id: FE-FOLDER-6
     title: Keep units cohesive
     kind: mandatory
-    hfsRules: [R49, R21]
+    hfsRules: [R49, R21, R91, R92]
     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.
@@ -301,9 +398,18 @@ rules:
     verification:
       automated:
         - FE_ENV_OWNER
-        - class-names-in-colocated-file
-        - no-inline-class-name
-        - no-helper-folder-in-components
+        - HFS_DUPLICATE_CODE
+        - HFS_DUPLICATE_SYMBOL
+        - FE_CROSS_APP_DUPLICATE
+        - FE_SOURCE_FORM
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_COMPONENT_API
+        - 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
       manual:
         - Confirm extraction is justified by ownership or lifecycle rather than file length or count.
     relatedExamples: []

package/runtime/knowledge/sonar-gate.yaml

@@ -4,7 +4,7 @@ title: The Sonar quality gate every product is held to
 purpose: |
   The one place the Sonar thresholds live. A product repository never restates them: its
   .starcistacks/application-stacks.yaml `services.sonar.qualityGate` names the gate below, and
-  scripts/checks/sonar-local.mjs (1) makes the local SonarQube's gate of that name carry exactly these
+  scripts/gates/sonar-local.mjs (1) makes the local SonarQube's gate of that name carry exactly these
   conditions and selects it for the project, and (2) judges an op's slice - the lines it changed - against
   the same numbers. Code-writing ops cannot settle done while the slice is red
   (scripts/kernel/sonar-settle.mjs). Changing a number here changes every repository on the next scan.
@@ -13,16 +13,16 @@ purpose: |
   vulnerability, every hotspot reviewed, no duplicated-lines excess, no cognitive-complexity issue). The one Sonar
   mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
 gate:
-  name: starci-new-code
-  # A project with no new-code baseline judges the whole project as new code (nivo inc-f92febebbb64); a fixed
+  name: starci-quality
+  # A project with no new-code baseline judges the whole project as new code; a fixed
   # window keeps "new code" the recent work on main, so the server gate is passable on a healthy main.
   newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
 newCode:
-  # Coverage of the services only. The be unit run writes coverage/lcov.info (@starci/jest-preset coverageReporters lcov) and the
+  # Coverage of the measured logic files only (the `ruleParams.be.logicRoles` roles of the `coverage: required` slots). The be unit run writes coverage/lcov.info (@starci/jest-preset coverageReporters lcov) and the
   # managed sonar-project.properties imports it (sonar.javascript.lcov.reportPaths=be/coverage/lcov.info) with
-  # sonar.coverage.inclusions=be/src/**/*.service.ts, the one scope rendered by hfs sync from the preset's COVERAGE_SOURCES (codecov.yml
-  # is rendered from the same constant). A handler, resolver, controller, module, config file or test is not a coverage target and
-  # fe/ is outside coverage entirely, so coverage on these conditions is the services' coverage alone.
+  # sonar.coverage.exclusions = the complement of the measured files (SonarQube has no coverage inclusions), rendered by starci app sync from the one derivation scripts/hfs/coverage-scope.mjs (be/jest.config.js and codecov.yml
+  # are rendered from it too; a hand edit of any of them is R204 HFS_COVERAGE_SCOPE_DRIFT). The feature tier, declaration files, tests and
+  # fe/ are never coverage targets, so coverage on these conditions is the coverage of the modules' logic alone.
   coverage:
     metric: new_coverage
     minPercent: 100
@@ -40,11 +40,11 @@ newCode:
     metric: new_security_hotspots_reviewed
     minReviewedPercent: 100
     unreviewedMax: 0
-# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `hfs lint`
+# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `starci app lint`
 # (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry), which writes ONE file, reports/lint.sonar.json
-# (`npm run lint -- --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
+# (`starci app lint --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
 # the whole project at zero. The file carries three engines:
-#   starci-hfs   the repository findings of `hfs check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
+#   starci-hfs   the repository findings of `starci app check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
 #   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)
 #   stylelint    stylelint's json over the style glob (front ends)
 # The engines share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own
@@ -63,9 +63,9 @@ overall:
   hotspots:
     metric: security_hotspots_reviewed
     minReviewedPercent: 100
-  # The services' coverage (see newCode.coverage), overall and per file: with the inclusions in place each `*.service.ts` is its
-  # own measure, so one service below 100 fails the slice verdict (sonar-local evaluateSlice) and the dashboard verdict
-  # (sonar-local dashboard) although the project average may round to 100. A file outside the inclusions is never read.
+  # The measured files' coverage (see newCode.coverage), overall and per file: with the exclusions in place each measured file is its
+  # own measure, so one measured file below 100 fails the slice verdict (sonar-local evaluateSlice) and the dashboard verdict
+  # (sonar-local dashboard) although the project average may round to 100. A file outside the scope is never read.
   coverage:
     metric: coverage
     minPercent: 100
@@ -81,6 +81,40 @@ overall:
   cognitiveComplexity:
     rule: typescript:S3776
     via: overall.issues
+# Lite is the same quality policy without a test or coverage world. Readers select this block from hfs.json edition;
+# keeping both gates in this document makes every threshold data, never a branch-local restatement.
+lite:
+  gate:
+    name: starci-quality-lite
+    newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
+  newCode:
+    ignoreBelowChangedLines: 20
+    duplication:
+      metric: new_duplicated_lines_density
+      maxPercent: 3
+    issues:
+      blockingSeverities: [BLOCKER, CRITICAL]
+      metrics: {BLOCKER: new_blocker_violations, CRITICAL: new_critical_violations}
+      max: 0
+    hotspots:
+      metric: new_security_hotspots_reviewed
+      minReviewedPercent: 100
+      unreviewedMax: 0
+  overall:
+    issues:
+      metric: violations
+      max: 0
+      engines: [starci-hfs, eslint, stylelint]
+      types: {bugs: BUG, code_smells: CODE_SMELL, vulnerabilities: VULNERABILITY}
+    hotspots:
+      metric: security_hotspots_reviewed
+      minReviewedPercent: 100
+    duplication:
+      metric: duplicated_lines_density
+      maxPercent: 3
+    cognitiveComplexity:
+      rule: typescript:S3776
+      via: overall.issues
 # The Sonar enforcers of the rule catalog (knowledge/hfs/rules.yaml): the failure code each condition above is the gate of.
 enforces:
   - {rule: R20, code: HFS_SIZE_GROWTH, enforcer: cognitive-complexity, condition: cognitiveComplexity}
@@ -91,19 +125,19 @@ enforcedOps: [backend.implement, interface.implement, code.refactor]
 reasoning: |
   Chosen against the four projects the local server holds on 2026-09-29 (whole-project duplicated lines
   1.6 / 2.1 / 1.7 / 0.0 percent), so new code that meets them is at or below what main already carries.
-  coverage 100 on services, overall and new code (owner 2026-10-01): the unit project already fails below its per-file
-  100 threshold on `*.service.ts`; Sonar imports the same run's lcov with the same scope, so the dashboard, the slice
-  verdict and the server gate show the number the runner enforces, file by file. Only services count: business logic
-  lives there, the thin layers are covered through them, and the front end has no unit tests.
+  coverage 100 on the measured logic files, overall and new code (owner 2026-10-01): the unit project already fails below its per-file
+  100 threshold on the `ruleParams.be.logicRoles` files of the `coverage: required` slots; Sonar imports the same run's lcov with the same scope, so the dashboard, the slice
+  verdict and the server gate show the number the runner enforces, file by file. Only the modules' logic counts: business logic
+  lives there, the feature tier is thin (R203) and proven by integration and e2e, and the front end has no unit tests.
   duplication 3: the Sonar way value; the worst project today is 2.1, so 3 rejects a real copy-paste block and
   passes ordinary work.
   blocker/critical 0: the two severities that are defects, not style. main carries old debt of both kinds
-  (nivo-backend 3 blocker, 137 critical), so the SLICE verdict reads only changed lines and never main's backlog;
+  (one product repository carries 3 blocker and 137 critical), so the SLICE verdict reads only changed lines and never main's backlog;
   major and lower are reported on the summary and never fail a slice.
   overall issues 0 and overall duplication 3: the server gate is also the owner's definition of done for the HFS canon:
   a repository that carries any open ESLint, stylelint or HFS finding is not green, whatever the age of the line. The
   op slice keeps judging changed lines (an op cannot fix a repository's whole backlog); the dashboard and CI show the
-  whole-project condition. Adopting a repository therefore means clearing its imported findings, which `hfs check`,
+  whole-project condition. Adopting a repository therefore means clearing its imported findings, which `starci app check`,
   eslint and stylelint already demand at land.
   hotspots 0 unreviewed: a hotspot is a question the author must answer; on changed lines it is answered in the
   same slice.