@starci/eslint-canon-be 3.4.24 → 3.4.25

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 3.4.25 - 2026-10-21
+- Added: Sonar way at lint time: every rule of the Sonar way TypeScript profile with an ESLint equivalent is on at error over the files the scan judges (a unit or end-to-end spec is outside), from the shared `scripts/lib/sonar-way.mjs`: eslint-plugin-sonarjs' Sonar way set (cognitive complexity 15, super-linear and slow regex, sort compare, nested template literals, ...) and the rules SonarSource builds on (`max-params` 7, `no-duplicate-imports`, `@typescript-eslint/prefer-optional-chain`, unicorn's `prefer-native-coercion-functions`, `prefer-includes`, `prefer-set-has` and the other S77xx rules). New exact dependencies eslint-plugin-sonarjs 4.2.1 and eslint-plugin-unicorn 65.0.0 (the last line for ESLint 9).
+- Changed: the bundled canon-pins copy follows the 1.7.17 cohort (cli 1.7.17, hfs 4.7.17).
+
 ## 3.4.24 - 2026-10-21
 - Changed: the bundled canon-pins copy follows the 1.7.16 cohort (cli 1.7.16, hfs 4.7.16); lint behavior is unchanged.
 

package/lib/config.mjs

@@ -9,13 +9,16 @@
  * The factory owns everything else: typed linting on every tracked TypeScript and JavaScript file
  * (`parserOptions.projectService`), the ignores (`dist/`, `coverage/`, `node_modules/` and nothing more), the
  * linter options that make a disable comment impossible, the borrowed typescript-eslint rules, every canon rule at
- * `error`, and `settings.starci.hfs` - the slot view each path-scoped rule asks instead of a path pattern.
+ * `error`, the Sonar way rules over the files the scan judges (scripts/lib/sonar-way.mjs: eslint-plugin-sonarjs and unicorn), and
+ * `settings.starci.hfs` - the slot view each path-scoped rule asks instead of a path pattern.
  *
  * NO RULE IS OFF OR WARN. The recommendation itself ships `error`; the factory refuses one that carries anything
  * else, so a rule cannot be published weakened and still look adopted. The factory takes no rule overrides, globs
  * or ignores: there is no parameter through which a repository could weaken the canon.
  */
 import tsParser from "@typescript-eslint/parser"
+import { OUTSIDE_THE_SCAN_FILES } from "../runtime/scripts/lib/sonar-syntax-rules.mjs"
+import { sonarWayRules } from "../runtime/scripts/lib/sonar-way.mjs"
 
 /** A disable directive is a weakening of lint, and one that suppresses nothing is dead weight. */
 export const linterOptions = Object.freeze({ noInlineConfig: true, reportUnusedDisableDirectives: "error" })
@@ -56,7 +59,7 @@ const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting)
  * @param {object} input.hfs - The HFS view of the repository (`loadHfs(import.meta.url)`).
  * @param {object} input.plugin - The canon plugin.
  * @param {Record<string, unknown>} input.recommended - The canon levels.
- * @returns {Promise<Array<object>>} The flat config (ESLint awaits an exported promise): one ignore block and one rule block.
+ * @returns {Promise<Array<object>>} The flat config (ESLint awaits an exported promise): one ignore block, one rule block and the Sonar way block.
  */
 export const buildBeConfig = async ({ hfs, plugin, recommended }) => {
     if (!hfs || typeof hfs.slotOf !== "function" || typeof hfs.repoRoot !== "string") {
@@ -70,6 +73,7 @@ export const buildBeConfig = async ({ hfs, plugin, recommended }) => {
     if (weak.length > 0) throw new Error(`starciBeConfig refuses a recommendation with rules not at error: ${weak.join(", ")}`)
     // Loaded here, not at import: the rule catalog check imports this package to list its rules and needs no linter plugin.
     const { default: tsPlugin } = await import("@typescript-eslint/eslint-plugin")
+    const [{ default: sonarjs }, { default: unicorn }] = await Promise.all([import("eslint-plugin-sonarjs"), import("eslint-plugin-unicorn")])
     return [
         { ignores: [...IGNORED] },
         {
@@ -85,5 +89,7 @@ export const buildBeConfig = async ({ hfs, plugin, recommended }) => {
             settings: { starci: { hfs } },
             rules: { ...rules, ...BORROWED },
         },
+        // Sonar way: what the scan raises is refused while the code is written; a spec is outside the scan, so outside this block.
+        { files: [...SOURCE_FILES], ignores: [...OUTSIDE_THE_SCAN_FILES], plugins: { sonarjs, unicorn }, rules: sonarWayRules(sonarjs).rules },
     ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "3.4.24",
+  "version": "3.4.25",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,8 @@
   ],
   "dependencies": {
     "@typescript-eslint/eslint-plugin": "^8.70.0",
-    "@typescript-eslint/parser": "^8.70.0"
+    "@typescript-eslint/parser": "^8.70.0",
+    "eslint-plugin-sonarjs": "4.2.1",
+    "eslint-plugin-unicorn": "65.0.0"
   }
 }

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.24
+    version: 3.4.25
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.23
+    version: 8.4.24
     group: starci
     install: registry
     side: fe
@@ -62,7 +62,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.2
+    version: 2.3.3
     group: starci
     install: registry
     side: be
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.16
+    version: 1.7.17
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.16
+    version: 4.7.17
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -3754,7 +3754,7 @@ rules:
       - {path: packages/eslint/be/sonar-parity-editions.spec.mjs, edition: full}
       - {path: packages/eslint/fe/sonar-parity-editions.spec.mjs, edition: lite}
       - {path: packages/eslint/fe/sonar-parity-editions.spec.mjs, edition: full}
-    law: "Code carries none of the smells SonarCloud measures that a lint rule can decide: no `await` inside a loop (S9382; an endless loop is spared), no `charCodeAt`/`fromCharCode` (S7758), no string that only escapes backslashes (S7780; a Next `matcher` is spared, it is read statically), no nested conditional expression (S3358), no `void` on anything but a call (S3735), no unused import (S1128), no import that is only handed on instead of `export ... from` (S7763), no prop of a component's props type the component never reads (S6767, front end), and, through typescript-eslint with type information, no deprecated API (S1874), no object turned into text (S6551) and no `async` function that never awaits and returns no promise (S7503). The files a unit or an end-to-end spec names are outside the scan, so outside these rules."
+    law: "Code carries none of the smells SonarCloud measures that a lint rule can decide: no `await` inside a loop (S9382; an endless loop is spared), no `charCodeAt`/`fromCharCode` (S7758), no string that only escapes backslashes (S7780; a Next `matcher` is spared, it is read statically), no nested conditional expression (S3358), no `void` on anything but a call (S3735), no unused import (S1128), no import that is only handed on instead of `export ... from` (S7763), no prop of a component's props type the component never reads (S6767, front end), no `<video>` or `<audio>` without a captions track unless muted (S4084, front end), and, through typescript-eslint with type information, no deprecated API (S1874), no object turned into text (S6551) and no `async` function that never awaits and returns no promise (S7503). Every other rule of the Sonar way TypeScript profile with an ESLint equivalent (scripts/lib/sonar-way.mjs: eslint-plugin-sonarjs' Sonar way set, the core, typescript-eslint and unicorn rules it builds on) is on at error in both canons. The files a unit or an end-to-end spec names are outside the scan, so outside these rules."
     kinds: [lint, codemod]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["SCAN_SMELL"]
@@ -3774,6 +3774,7 @@ rules:
       - {kind: eslint-fe, id: no-unused-import}
       - {kind: eslint-fe, id: prefer-export-from}
       - {kind: eslint-fe, id: no-unused-prop-types}
+      - {kind: eslint-fe, id: media-has-caption}
   - id: R236
     code: "RT_GATE_LOOSENING"
     editions: [lite, full]

package/runtime/knowledge/hfs/slots.yaml

@@ -38,7 +38,7 @@ versioning:
 # or environment reads (BE_APP_OPTIONS_COMPOSITION). Secrets use EnvSource.secret(): <NAME>_FILE first, plain <NAME> only
 # when the file key is absent; .starcistacks owns custody. Capability <capability>.config.ts roles stay unchanged.
 # 3.3.0 is a minor (alpha.16): it ADDS the optional app.ci-stack-deploy slot, the managed workflow of the starci app stack verbs.
-# 3.4.0 is a minor (alpha.24): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
+# 3.4.0 is a minor (alpha.25): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.

package/runtime/scripts/lib/sonar-syntax-rules.mjs

@@ -206,8 +206,28 @@ const noUnusedPropTypes = {
   },
 };
 
-/** The files the example scans leave out: a unit spec and an end-to-end spec. */
+/** S4084: a `<video>` or `<audio>` element plays captions: a `<track kind="captions">` child, or it is `muted`. */
+const MEDIA = new Set(['video', 'audio']);
+const jsxName = (node) => (node?.name?.type === 'JSXIdentifier' ? node.name.name : null);
+const attributeOf = (opening, name) => opening.attributes.find((attribute) => attribute.type === 'JSXAttribute' && attribute.name?.name === name);
+const isCaptionTrack = (child) => child.type === 'JSXElement' && jsxName(child.openingElement) === 'track'
+  && attributeOf(child.openingElement, 'kind')?.value?.value === 'captions';
+const mediaHasCaption = {
+  meta: { type: 'problem', schema: [], messages: { caption: 'S4084: give this <{{ name }}> a <track kind="captions"> child (or make it muted) so it can be followed without sound.' } },
+  create(context) {
+    return {
+      JSXElement(node) {
+        const name = jsxName(node.openingElement);
+        if (!MEDIA.has(name) || attributeOf(node.openingElement, 'muted') || node.children.some(isCaptionTrack)) return;
+        context.report({ node: node.openingElement, messageId: 'caption', data: { name } });
+      },
+    };
+  },
+};
+
+/** The files the example scans leave out: a unit spec and an end-to-end spec (the regex, and the flat-config globs of the same set). */
 const OUTSIDE_THE_SCAN = /\.(?:e2e-)?spec\.[cm]?[jt]sx?$/;
+export const OUTSIDE_THE_SCAN_FILES = Object.freeze(['**/*.spec.{js,mjs,cjs,ts,mts,cts,jsx,tsx}', '**/*.e2e-spec.{js,mjs,cjs,ts,mts,cts,jsx,tsx}']);
 
 /** The rule judging only the files the scan judges. */
 const scanned = (rule) => ({ ...rule, create: (context) => (OUTSIDE_THE_SCAN.test(context.filename) ? {} : rule.create(context)) });
@@ -222,4 +242,5 @@ export const SONAR_SYNTAX_RULES = Object.freeze({
   'no-unused-import': scanned(noUnusedImport),
   'prefer-export-from': scanned(preferExportFrom),
   'no-unused-prop-types': scanned(noUnusedPropTypes),
+  'media-has-caption': scanned(mediaHasCaption),
 });

package/runtime/scripts/lib/sonar-way.mjs

@@ -0,0 +1,68 @@
+// sonar-way.mjs - the Sonar way TypeScript profile (the default quality profile sonar.starci.org and SonarCloud apply) as ESLint rules:
+// the one mapping both lint canons (@starci/eslint-canon-be and -fe) publish, so `starci app lint` in the op loop refuses what the scan would
+// raise while the code is written. The base is eslint-plugin-sonarjs's recommended config, SonarSource's own port of Sonar way (each rule's
+// docs url names its S-id); its rules the canons already publish in another form stay with that owner (SONAR_WAY_OWNED), and the Sonar way
+// rules SonarSource builds on other ESLint rules are SONAR_WAY_EXTRA. Every rule is `error`. A unit or end-to-end spec is outside the scan,
+// so outside these rules: the canons give this block the ignores of sonar-syntax-rules.mjs OUTSIDE_THE_SCAN_FILES. The runtime's own
+// `sonar-rules` gate reads the two limits below.
+
+/** S3776 cognitive complexity and S107 parameters: the Sonar way thresholds. */
+export const COGNITIVE_COMPLEXITY_LIMIT = 15;
+export const MAX_PARAMETERS = 7;
+
+/** sonarjs rules of Sonar way another canon rule already reports: the owner that reports the same Sonar id. */
+const SONAR_WAY_OWNED = Object.freeze({
+  'sonarjs/no-nested-conditional': 'S3358, the canon syntax rule no-nested-conditional',
+  'sonarjs/unused-import': 'S1128, the canon syntax rule no-unused-import',
+  'sonarjs/void-use': 'S3735, the canon syntax rule no-void-operator',
+  'sonarjs/deprecation': 'S1874, the borrowed @typescript-eslint/no-deprecated',
+});
+
+/**
+ * The Sonar way rules SonarSource implements on an ESLint rule outside eslint-plugin-sonarjs: `{ sonar, rule, options? }`. S4084 (a
+ * `<video>`/`<audio>` without captions) is the front-end canon's syntax rule media-has-caption. S7785 (top-level await) is left out: an
+ * app's TypeScript compiles to CommonJS (`module: nodenext` without `type: module`), where top-level await does not exist.
+ */
+export const SONAR_WAY_EXTRA = Object.freeze([
+  { sonar: 'S107', rule: 'max-params', options: [{ max: MAX_PARAMETERS }] },
+  { sonar: 'S3863', rule: 'no-duplicate-imports', options: [{ allowSeparateTypeImports: true }] },
+  { sonar: 'S6582', rule: '@typescript-eslint/prefer-optional-chain' },
+  { sonar: 'S4138', rule: 'unicorn/no-for-loop' },
+  { sonar: 'S7721', rule: 'unicorn/consistent-function-scoping', options: [{ checkArrowFunctions: false }] },
+  { sonar: 'S7732', rule: 'unicorn/no-instanceof-builtins' },
+  { sonar: 'S7740', rule: 'unicorn/no-this-assignment' },
+  { sonar: 'S7744', rule: 'unicorn/no-useless-fallback-in-spread' },
+  { sonar: 'S7747', rule: 'unicorn/no-useless-spread' },
+  { sonar: 'S7750', rule: 'unicorn/prefer-array-find' },
+  { sonar: 'S7754', rule: 'unicorn/prefer-array-some' },
+  { sonar: 'S7765', rule: 'unicorn/prefer-includes' },
+  { sonar: 'S7767', rule: 'unicorn/prefer-math-trunc' },
+  { sonar: 'S7770', rule: 'unicorn/prefer-native-coercion-functions' },
+  { sonar: 'S7776', rule: 'unicorn/prefer-set-has' },
+  { sonar: 'S7778', rule: 'unicorn/prefer-single-call' },
+  { sonar: 'S7784', rule: 'unicorn/prefer-structured-clone' },
+]);
+
+/** The Sonar id a sonarjs rule documents (its docs url ends in `#/rspec/S<id>/javascript`), or null. */
+const sonarIdOf = (rule) => /\/rspec\/#\/rspec\/(S\d+)\//u.exec(rule?.meta?.docs?.url ?? '')?.[1] ?? null;
+
+/**
+ * The Sonar way rules, `{ rules, mapped }`: `rules` the flat-config rule levels (sonarjs' recommended rules at error minus the owned ones,
+ * with S3776's limit, then SONAR_WAY_EXTRA), `mapped` every `{ sonar, rule }` row.
+ */
+export function sonarWayRules(sonarjs) {
+  const mapped = [];
+  const rules = {};
+  for (const [name, setting] of Object.entries(sonarjs.configs.recommended.rules)) {
+    if ((Array.isArray(setting) ? setting[0] : setting) !== 'error' || SONAR_WAY_OWNED[name]) continue;
+    const declared = Array.isArray(setting) ? setting.slice(1) : [];
+    const options = name === 'sonarjs/cognitive-complexity' ? [COGNITIVE_COMPLEXITY_LIMIT] : declared;
+    rules[name] = ['error', ...options];
+    mapped.push({ sonar: sonarIdOf(sonarjs.rules[name.slice('sonarjs/'.length)]), rule: name });
+  }
+  for (const entry of SONAR_WAY_EXTRA) {
+    rules[entry.rule] = ['error', ...(entry.options ?? [])];
+    mapped.push({ sonar: entry.sonar, rule: entry.rule });
+  }
+  return { rules, mapped };
+}

package/sonar-parity.mjs

@@ -3,7 +3,8 @@
  *
  * Each rule is the syntax-tree form of one Sonar rule, shared with the front-end canon (scripts/lib/sonar-syntax-rules.mjs,
  * bundled under `runtime/`): `no-await-in-loop` (S9382), `prefer-code-point` (S7758), `prefer-string-raw` (S7780),
- * `no-nested-conditional` (S3358), `no-void-operator` (S3735), `no-unused-import` (S1128) and `prefer-export-from` (S7763).
+ * `no-nested-conditional` (S3358), `no-void-operator` (S3735), `no-unused-import` (S1128) and `prefer-export-from` (S7763); the rest of
+ * Sonar way is the factory's Sonar way block (scripts/lib/sonar-way.mjs).
  * The three Sonar rules that need the type checker, S1874 (a deprecated API), S6551 (an object turned into text) and S7503 (an `async`
  * function that never awaits and returns no promise), are the typescript-eslint rules `no-deprecated`, `no-base-to-string` and
  * `require-await` the factory turns on.