@starci/eslint-canon-fe 8.4.39 → 8.4.40

package/menu-entries.mjs

@@ -0,0 +1,133 @@
+/**
+ * The menu entries a product hands to Grammar's `DropdownMenu`.
+ *
+ * HeroUI colours a destructive menu item through its `danger` variant, which Grammar exposes as `tone: "danger"`. An entry the app
+ * forgets to tone reads like any other command: sign out and delete sit beside "Settings" in the same ink, and the one click that
+ * cannot be taken back gets no mark. The decision is the entry's meaning, so it is checked where the entry is written: an entry whose
+ * id or label says it signs out, deletes, removes, leaves or revokes carries `tone: "danger"`.
+ *
+ * The terms are this canon's own list, English and Vietnamese. They are compared as whole words after the text is lower-cased, split
+ * at `-`, `_` and camelCase, and stripped of diacritics (the Vietnamese for "sign out" with its tone marks is `dang xuat`), so `signOut`, `sign-out`,
+ * `Sign out` and the tone-marked Vietnamese spelling are one term.
+ *
+ * WHERE IT LOOKS. A menu entry is an object literal in the `entries` attribute of a `DropdownMenu`, or in a declaration typed as
+ * `DropdownMenuEntry`, `DropdownMenuItem` or `DropdownMenuSection` (an array of them too), including the `items` of a section and the
+ * `submenu` of an item. Anything it cannot see through (a spread, a call) it leaves alone: the rule refuses to guess.
+ */
+
+import { stringOf } from "./lib/ast.mjs"
+import { isProductSource } from "./lib/scope.mjs"
+
+/** The English terms of a destructive entry. */
+const DESTRUCTIVE_TERMS_EN = Object.freeze([
+  "sign out", "log out", "logout", "signout",
+  "delete", "remove", "erase", "destroy", "discard", "purge",
+  "leave workspace", "leave team", "leave group", "leave organization", "leave project", "leave channel", "leave course", "revoke", "deactivate", "disconnect", "unlink", "unsubscribe", "terminate",
+  "close account", "cancel subscription", "cancel plan",
+])
+
+/** The Vietnamese terms, written without diacritics (the text is compared after the diacritics are stripped). */
+const DESTRUCTIVE_TERMS_VI = Object.freeze([
+  "dang xuat", "xoa", "xoa bo", "go bo", "loai bo", "roi khoi", "roi nhom", "thu hoi",
+  "vo hieu hoa", "ngat ket noi", "huy dang ky", "huy goi", "cham dut", "dong tai khoan",
+])
+
+/** A destructive term as a whole word or phrase of the normalized text. */
+const DESTRUCTIVE_PATTERN = new RegExp(String.raw`(?:^|\s)(?:${[...DESTRUCTIVE_TERMS_EN, ...DESTRUCTIVE_TERMS_VI].map((term) => term.replaceAll(" ", String.raw`\s+`)).join("|")})(?=\s|$)`)
+
+/** The text lower-cased, split at separators and camelCase, with diacritics stripped. */
+export const normalizeText = (text) =>
+  text
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replaceAll(/[-_./:]+/g, " ")
+    .toLowerCase()
+    .replaceAll("\u0111", "d")
+    .normalize("NFD")
+    .replaceAll(/\p{M}+/gu, "")
+    .replaceAll(/\s+/g, " ")
+    .trim()
+
+/** True when the id or label text names a destructive command. */
+export const isDestructiveText = (text) => DESTRUCTIVE_PATTERN.test(normalizeText(text))
+
+const MENU_TYPES = new Set(["DropdownMenuEntry", "DropdownMenuItem", "DropdownMenuSection"])
+
+/** The value node of the property called `name` in an object literal, or null. */
+const propertyValue = (object, name) =>
+  object.properties.find((entry) => entry.type === "Property" && !entry.computed && (entry.key.name === name || entry.key.value === name))?.value ?? null
+
+/** The element type of an array type (`T[]`, `readonly T[]`, `ReadonlyArray<T>`), else the type itself. */
+const elementTypeOf = (type) => {
+  if (type.type === "TSTypeOperator") return elementTypeOf(type.typeAnnotation)
+  if (type.type === "TSArrayType") return type.elementType
+  const isArrayName = type.type === "TSTypeReference" && type.typeName.type === "Identifier" && (type.typeName.name === "ReadonlyArray" || type.typeName.name === "Array")
+  return isArrayName ? (type.typeArguments ?? type.typeParameters)?.params[0] ?? type : type
+}
+
+/** True when the type annotation names a menu entry type or an array of one. */
+const isMenuType = (annotation) => {
+  const type = annotation?.typeAnnotation
+  if (!type) return false
+  const element = elementTypeOf(type)
+  return element.type === "TSTypeReference" && element.typeName.type === "Identifier" && MENU_TYPES.has(element.typeName.name)
+}
+
+/** Report an entry (an object literal), then walk the `items` of a section and the `submenu` of an item. */
+function visitEntries(node, report) {
+  if (!node) return
+  if (node.type === "ArrayExpression") {
+    for (const element of node.elements) visitEntries(element, report)
+    return
+  }
+  if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") {
+    visitEntries(node.expression, report)
+    return
+  }
+  if (node.type !== "ObjectExpression") return
+  const kind = stringOf(propertyValue(node, "kind"))
+  if (kind === "section") {
+    visitEntries(propertyValue(node, "items"), report)
+    return
+  }
+  const text = [stringOf(propertyValue(node, "id")), stringOf(propertyValue(node, "label"))].filter((value) => value !== null)
+  const tone = propertyValue(node, "tone")
+  const toned = tone !== null && (stringOf(tone) === "danger" || stringOf(tone) === null)
+  if (!toned && text.some(isDestructiveText)) report(node, text.find(isDestructiveText))
+  visitEntries(propertyValue(node, "submenu"), report)
+}
+
+/** A destructive menu entry carries `tone: "danger"`. */
+export const destructiveMenuEntryNeedsDangerTone = {
+  meta: {
+    type: "problem",
+    docs: { description: "A menu entry whose id or label signs out, deletes, removes, leaves or revokes carries `tone: \"danger\"`." },
+    schema: [],
+    messages: {
+      tone:
+        "The menu entry `{{text}}` is destructive but has no `tone: \"danger\"`. HeroUI colours the label and glyph of a danger item so the one click that cannot be taken back is marked; without the tone it reads like \"Settings\". Add `tone: \"danger\"` to the entry.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const report = (node, text) => context.report({ node, messageId: "tone", data: { text } })
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || node.name.name !== "entries") return
+        const element = node.parent?.name
+        if (element?.type !== "JSXIdentifier" || element.name !== "DropdownMenu") return
+        visitEntries(node.value?.type === "JSXExpressionContainer" ? node.value.expression : null, report)
+      },
+      VariableDeclarator(node) {
+        if (isMenuType(node.id.typeAnnotation)) visitEntries(node.init, report)
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "destructive-menu-entry-needs-danger-tone": destructiveMenuEntryNeedsDangerTone,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "8.4.39",
+  "version": "8.4.40",
   "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": "MIT",

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

@@ -1,6 +1,6 @@
 schema: starci/canon-pins@1
 purpose: >-
-  The exact version of every dependency a StarCi product repository pins. One version per dependency for the whole
+  The exact version of every shared dependency in the StarCi family, including package-owned runtime dependencies. One version per dependency for the whole
   family. Raising a version is a change to this file first (with the package bump when it is a @starci package),
   then the repositories' own upgrade lane (each sets the exact version and reinstalls; nothing else installs a @starci package). Read on 2026-09-29 from the packages under
   .claude/packages and from the installed node_modules of the six product repositories; where they disagreed the
@@ -10,7 +10,8 @@ purpose: >-
   two, pinned here with a why (2026-10-01: every such conflict but graphql was already pinned). The runtime's example apps
   merged the same way on 2026-10-01: no dependency outside this file was declared at two versions across their sides, so
   every choice is a pin (each side's older @starci pins and graphql moved to the version here). `side` names the side whose code uses
-  the dependency; the app root package.json carries the pins of both.
+  the dependency; the app root package.json declares the direct dependencies and tools its sides need. Package-owned
+  runtime dependencies are declared by their package, not by the app.
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
@@ -22,28 +23,28 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.11.0
+    version: 0.12.0
     group: starci
     install: registry
     side: fe
     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.40
+    version: 3.4.41
     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.39
+    version: 8.4.40
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe 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; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/stylelint-canon':
-    version: 2.0.10
+    version: 2.0.11
     group: starci
     install: registry
     side: fe
@@ -62,7 +63,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.5
+    version: 2.3.6
     group: starci
     install: registry
     side: be
@@ -76,14 +77,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.32
+    version: 1.7.33
     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.32
+    version: 4.7.33
     group: starci
     install: registry
     side: both
@@ -238,6 +239,11 @@ pins:
     group: framework
     side: be
     why: 'the Postgres driver behind TypeORM; the reference app declares ^8.12.0 and resolves 8.23.1.'
+  bullmq:
+    version: 6.3.11
+    group: framework
+    side: be
+    why: 'the queue transport of both editions behind platform/queue (ruling:R212/case-10); starci app add queue|job declares it in a lite app together with its Redis, and both example apps resolve this version.'
   reflect-metadata:
     version: 0.2.2
     group: framework
@@ -305,6 +311,11 @@ pins:
     group: framework
     side: fe
     why: 'the GraphQL client of every front end (fe-stack graphql): auth and no-auth clients with the link chain in modules/api/graphql; version read from the starci-academy package-lock on 2026-10-13.'
+  graphql-ws:
+    version: 6.2.1
+    group: framework
+    side: both
+    why: 'the subscription transport: the front end opens it only in the Apollo clients folder (fe-stack graphql, GraphQLWsLink of @apollo/client/link/subscriptions) and the back end serves it only from platform/realtime; the version resolved by the full-app lockfile on 2026-10-24.'
   '@graphql-codegen/cli':
     version: 7.4.6
     group: tooling
@@ -370,6 +381,16 @@ pins:
     group: ui
     side: fe
     why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-canon-fe (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
+  '@dicebear/core':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar for its seeded circle avatars; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/styles.'
+  '@dicebear/styles':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar supplying its fixed avatar DNA style; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/core.'
   'next-themes':
     version: 0.4.6
     group: ui
@@ -481,6 +502,16 @@ pins:
     group: framework
     side: be
     why: 'the Apollo driver of @nestjs/graphql; the full-app resolution on 2026-10-13. Stays on 13.x with @nestjs/graphql (accepted advisory, major deferred to alpha.19).'
+  '@aws-sdk/client-s3':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces, Supabase Storage); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
+  '@aws-sdk/s3-request-presigner':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'signs the presigned PUT and GET of integrations/object-storage locally, the same release as client-s3.'
   '@apollo/server':
     version: 5.5.1
     group: framework
@@ -496,6 +527,31 @@ pins:
     group: framework
     side: be
     why: 'the socket.io platform of @nestjs/websockets; the @nestjs/core pin line.'
+  socket.io:
+    version: 4.8.3
+    group: framework
+    side: be
+    why: 'the socket.io server the IoAdapter of platform/realtime builds (types and the adapter contract); the exact version @nestjs/platform-socket.io 11.2.5 depends on, so the workspace keeps one copy (4.8.4 is the latest on 2026-10-24).'
+  '@socket.io/postgres-adapter':
+    version: 0.5.0
+    group: framework
+    side: be
+    why: 'the stateless socket.io adapter of a back end without Redis that runs several api replicas (LISTEN/NOTIFY, no sticky sessions, websocket only), imported only by platform/realtime (knowledge/patterns/be/realtime.yaml BE-REALTIME-7); the latest registry version on 2026-10-24.'
+  '@socket.io/redis-adapter':
+    version: 8.3.0
+    group: framework
+    side: be
+    why: 'the sharded Redis adapter (createShardedAdapter, Redis 7 or later) of a back end with Redis declared that runs several api replicas, imported only by platform/realtime; the latest registry version on 2026-10-24.'
+  ioredis:
+    version: 5.11.1
+    group: framework
+    side: be
+    why: 'the one Redis client of a back end: the cache, the optional peer bullmq loads for the queue of platform/queue, and the Redis hub and sharded socket.io adapter of platform/realtime (its docs recommend ioredis over redis); the latest 5.x on 2026-10-24, because typeorm 0.3.31 declares ioredis ^5.0.4 as a peer and ioredis 6.0.0 (the latest) does not satisfy it.'
+  '@types/pg':
+    version: 8.23.1
+    group: framework
+    side: be
+    why: 'the types of the pg driver the Postgres hub of platform/realtime opens a LISTEN connection with; the pg pin line, the latest registry version on 2026-10-24.'
   '@as-integrations/express5':
     version: 1.1.2
     group: framework

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -19,7 +19,14 @@ concerns:
     home: [fe.modules.api, fe.transport.client, fe.transport.outcome]
     pattern: FE-API-GRAPHQL
     forbids: [urql, graphql-request, '@urql/core', graphql-hooks, apollo-boost]
-    why: one file per operation under modules/api/graphql/{queries,mutations}, run by the auth or no-auth Apollo client with the link chain.
+    why: one file per operation under modules/api/graphql/{queries,mutations,subscriptions}, run by the auth or no-auth Apollo client with the link chain.
+  - id: graphql-subscriptions
+    tier: opt
+    packages: [graphql-ws]
+    home: [fe.transport.client, fe.package.api.client]
+    pattern: FE-REALTIME
+    forbids: []
+    why: the subscription transport of a GraphQL subscription door (be.feature.realtime.graphql); only the Apollo clients folder imports it (GraphQLWsLink of @apollo/client/link/subscriptions), a subscription operation runs on that client and a useSubscribe hook of hooks/swr reads it.
   - id: codegen
     tier: core
     packages: ['@graphql-codegen/cli', '@graphql-codegen/client-preset']
@@ -74,8 +81,8 @@ concerns:
     packages: [socket.io-client, eventemitter2]
     home: [fe.hooks.socketio]
     pattern: FE-REALTIME
-    forbids: [graphql-ws, subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
-    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; lite runs the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a fetch reader in modules/api/sse and a use<Channel>Stream hook (FE-REALTIME).
+    forbids: [subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
+    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; both editions run the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a stream reader in modules/api/sse/clients, a stream operation in modules/api/sse and a useSubscribe<Channel>Swr hook (FE-REALTIME).
   - id: auth
     tier: core
     packages: []
@@ -89,7 +96,7 @@ concerns:
     home: [fe.modules.i18n]
     pattern: FE-I18N
     forbids: [i18next, react-i18next, next-i18next, react-intl, '@lingui/react']
-    why: useTranslations for copy and the next-intl formatter for numbers, dates and currency.
+    why: useTranslations for copy and the next-intl formatter for numbers, fixed dates and currency; FE-DATE owns live time display.
   - id: ui
     tier: core
     packages: ['@heroui/react', '@heroui/styles', tailwindcss, '@starci/grammar']
@@ -107,6 +114,17 @@ concerns:
       one application icon set, the heroicons family (owner ruling 2026-10-13), on the 24/outline and 16/solid cuts. @heroicons/react
       is the base set and is used first; @starci/heroicons holds only the glyphs heroicons lacks (brand or domain glyphs drawn in
       heroicons style), never duplicates a heroicons glyph, and a missing glyph is added to it.
+  - id: avatar-illustration
+    tier: opt
+    packages: ['@starci/grammar']
+    home: [fe.components]
+    pattern: FE-UI
+    forbids: ['@dicebear/*', boring-avatars, 'react-nice-avatar', multiavatar]
+    why: >-
+      Grammar owns circle avatars: pass the uploaded avatar as src, otherwise pass the user or identity id as seed on
+      Avatar, AvatarButton or AvatarGroup members. Grammar renders deterministic DiceBear images with its fixed DNA style;
+      @dicebear/core and @dicebear/styles are Grammar runtime dependencies pinned in canon-pins.yaml. Apps declare and
+      import @starci/grammar, never @dicebear/*, and draw no avatar visuals. With neither src nor seed, initials remain.
   - id: theme
     tier: core
     packages: [next-themes]
@@ -127,7 +145,7 @@ concerns:
     home: [fe.modules]
     pattern: FE-DATE
     forbids: [moment, moment-timezone, date-fns, luxon]
-    why: dayjs (modules/dayjs) for date math and parsing; display through the next-intl formatter.
+    why: FE-DATE owns application date math, fixed date formatting and Grammar's live time display.
   - id: numbers
     tier: opt
     packages: [decimal.js]