@starci/eslint-canon-fe 8.0.8 → 8.0.9

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Changed: `one-outcome-union` reads the Outcome home from the slot manifest (`outcomeHome` on `fe.transport.outcome`, `fe.package.api.outcome` and the lite `fe.modules.db.outcome`, i.e. `modules/db/outcome.ts`) instead of two slot ids in code; a lite app's db owner is its transport, so its `modules/db/outcome.ts` is THE union and a second one anywhere else is still refused. Full is unchanged.
 - Changed: `public-component-signature` accepts a component with no parameter; `no-raw-structural-element` names `Region`, `NavLandmark`, `List` and `ListItem` as owners of section, nav, ul/ol and li; FE-I18N-1 and FE-TYPING-6 canon text (request locale through `next/root-params`, no `void props`); the FE_SWR_KEY_IDENTITY check reads `&&` and `||` gates in its bundled runtime.
 ## Unreleased (C0 batch)
 

package/README.md

@@ -8,7 +8,7 @@ and colocated class-name composition consistent without prescribing a custom ren
 npm i -D @starci/eslint-canon-fe eslint-plugin-react-hooks typescript
 ```
 
-A repository's `eslint.config.mjs` is the managed one-liner `hfs sync` renders (and `hfs check` compares, R05/R17):
+A repository's `eslint.config.mjs` is the managed one-liner `starci app sync` renders (and `starci app check` compares, R05/R17):
 
 ```js
 import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
@@ -42,12 +42,13 @@ naming, props, served locales, component splits, design tokens, type safety, typ
 class-name ownership. Reusable class names belong in a colocated `classNames.ts` module and should
 be composed with HeroUI `cn` using one utility token per argument.
 
-The `shape-slot` law holds the split surfaces (blocks, pages, layouts, overlays under `components/`
+The `drawing` law holds the split surfaces (blocks, pages, layouts, overlays under `components/`
 or `features/`): the pure `XBase` takes `{ state, props, on }` of atoms (`base-props-atom`), only its
 sibling `index.tsx` imports it and never re-exports it (`base-import-pair`), `XState` names drawn
 shapes and never a data status (`no-data-status-shape`), and a block renders each slot's
-loading/forbidden/error/empty through `SlotView` (`slot-status-through-slotview`). Reference tree:
-`.claude/examples/shape-slot`.
+loading/forbidden/error/empty through `SlotView` (`slot-status-through-slotview`). The law's name is
+the `drawing` slot role of `component.tsx`; a split-surface reference tree lives under
+`.claude/examples/`.
 
 The one locale pattern everywhere is `next-intl`, a `[locale]` segment, default `vi`,
 `localePrefix: "as-needed"`, and `proxy.ts` instead of `middleware.ts`.

package/client-boundary.mjs

@@ -139,7 +139,8 @@ const isMarkerStatement = (statement) =>
 
 /** True when a TypeScript source file opens with `import "server-only"`. */
 const tsFileIsMarked = (file) => {
-  const first = file.statements[0]
+  // a file-level directive ("use server") is the prologue: the marker is the first statement after it
+  const first = file.statements.find((statement) => !(ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)))
   return Boolean(first) && ts.isImportDeclaration(first) && !first.importClause && ts.isStringLiteral(first.moduleSpecifier) && first.moduleSpecifier.text === "server-only"
 }
 
@@ -183,7 +184,8 @@ export const serverModuleMarksServerOnly = {
     return {
       Program(program) {
         client = clientDirective(program) !== null
-        marked = isMarkerStatement(program.body[0])
+        // a file-level directive ("use server") is the prologue, not a statement: the marker is the first statement after it
+        marked = isMarkerStatement(program.body.find((statement) => !(statement.type === "ExpressionStatement" && typeof statement.directive === "string")))
       },
       "ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration"(node) {
         if (!node.source || node.importKind === "type" || node.exportKind === "type") return

package/comments.mjs

@@ -25,7 +25,7 @@ import { fileOf, inSlot } from "./lib/scope.mjs"
  * - a single class covering both trips the misleading-character-class rule, and a rule that has to
  * be silenced to exist is one nobody trusts.
  */
-export const hasEmoji = (text) =>
+const hasEmoji = (text) =>
   typeof text === "string" &&
   (/\p{Extended_Pictographic}/u.test(text) || /[\u{1F1E6}-\u{1F1FF}]{2}/u.test(text))
 

package/docs/next-conventions.md

@@ -221,7 +221,7 @@ export default getRequestConfig(async () => ({ locale: "vi", messages: {} }))
 **Valid** (`apps/web/src/modules/i18n/index.ts`)
 
 ```ts
-import { createAppI18n } from "@nivo/i18n"
+import { createAppI18n } from "@acme/i18n"
 export const i18n = createAppI18n({ locales: ["vi"] })
 ```
 

package/docs/translation.md

@@ -2,7 +2,7 @@
 
 Law module: `translation.mjs`. Catalogue: R58 FE_I18N_LITERAL.
 
-No text a reader can see or hear is written in source, at any tier and in any language: it is read from a `next-intl` catalogue through `t()`. There is no `vn-ok` pragma, no endonym exemption and no `resources/` copy folder; the catalogues (`messages/<locale>.json`), fixtures and specs are the only content paths. The notion of a literal is the same as nivo-fe's `scripts/check-i18n-catalog.mjs`: a word is two or more letters, and the copy attributes are `label`, `title`, `alt`, `placeholder` and the `aria-*` set.
+No text a reader can see or hear is written in source, at any tier and in any language: it is read from a `next-intl` catalogue through `t()`. There is no `vn-ok` pragma, no endonym exemption and no `resources/` copy folder; the catalogues (`messages/<locale>.json`), fixtures and specs are the only content paths. The notion of a literal is the same as the repository's i18n catalog check: a word is two or more letters, and the copy attributes are `label`, `title`, `alt`, `placeholder` and the `aria-*` set.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 

package/docs/transport.md

@@ -2,7 +2,7 @@
 
 Law module: `transport.mjs`. Catalogue: R50 FE_TRANSPORT_OWNER, R51 FE_HTTP_STATUS_COLLAPSE, R52 FE_WIRE_GENERATED.
 
-One repository, one client, one result vocabulary. The client is the file of HFS slot `fe.transport.client` (`apps/<app>/src/modules/api/client.ts`, a one-app repository) or `fe.package.api.client` (`packages/<family>-api/src/client.ts`, the shared client of a multi-app repository); the vocabulary is `Outcome<T>` (`ok`, `refused`, `invalid`, `not-found`, `unavailable`), declared in the `fe.transport.outcome` / `fe.package.api.outcome` file. The rules read the slot of the file being linted, never its path. 401 and 403 become `refused`; nothing collapses a status into `null`; wire types are generated from the contract copy in `modules/api/contract/`.
+One repository, one client, one result vocabulary. The client is the file of HFS slot `fe.transport.client` (`apps/<app>/src/modules/api/client.ts`, a one-app repository) or `fe.package.api.client` (`packages/<family>-api/src/client.ts`, the shared client of a multi-app repository); the vocabulary is `Outcome<T>` (`ok`, `refused`, `invalid`, `not-found`, `unavailable`), declared in the file of the slot the manifest marks `outcomeHome`: `fe.transport.outcome`, `fe.package.api.outcome`, or `fe.modules.db.outcome` (`modules/db/outcome.ts`) in a lite app, whose db owner is the transport. The rules read the slot of the file being linted, never its path. 401 and 403 become `refused`; nothing collapses a status into `null`; wire types are generated from the contract copy in `modules/api/contract/`.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
@@ -171,7 +171,7 @@ switch (outcome.kind) {
 
 ## `starci-fe/one-outcome-union`
 
-A result union (`ok` / `kind` discriminant) is declared only in the outcome slot; elsewhere the code composes `Outcome<T>`.
+A result union (`ok` / `kind` discriminant) is declared only in the outcome-home slot (`outcomeHome: true` in the slot manifest); elsewhere the code composes `Outcome<T>`.
 
 A union type alias is a result union when its resolved members are all object types that carry the same literal-typed discriminant in the result vocabulary: `ok` (each member pins it to one value, `true` and `false` both present) or `kind` (at least one literal of the Outcome vocabulary: `ok`, `refused`, `forbidden`, `invalid`, `not-found`, `unavailable`). The members are read through the type checker, so `Ok<T> | Failure` and intersections are seen as what they are; no name (`*Outcome`, `*Result`) decides anything. UI state unions (`status`, `state`, `type`, a `kind` of tree nodes or menu items) are not result vocabulary and pass; so does an alias that only composes the one union (`type Read = Outcome<Course>`, `Exclude<Outcome<T>, ...>`). `Outcome<T> | { ok: false; kind: "conflict" }` adds an arm to the one union and is refused.
 

package/{shape-slot.mjs → drawing.mjs}

@@ -1,5 +1,5 @@
 /**
- * The rules that hold the shape-slot law (example: examples/shape-slot).
+ * The rules that hold the drawing law (the `drawing` slot role: a surface's pure `component.tsx`).
  *
  * TWO AXES, AND ONLY ONE IS DRAWN. A surface's `state` is its SHAPE: a layout the owner approves as
  * one drawing. A slot's data status (loading, forbidden, error, empty) is not a shape; it is a
@@ -77,7 +77,7 @@ const membersOf = (node, types, seen = new Set()) => {
 /** The key a property signature declares. */
 const keyOf = (member) => (member.key?.type === "Identifier" ? member.key.name : member.key?.value)
 
-// -- SHAPE-SLOT-1 ----------------------------------------------------------------------------------
+// -- DRAWING-1 ----------------------------------------------------------------------------------
 
 /** The pure half takes `{ state, props, on }` of atoms; only a layout also takes `children`. */
 export const basePropsAtom = {
@@ -189,7 +189,7 @@ export const basePropsAtom = {
   },
 }
 
-// -- SHAPE-SLOT-2 ----------------------------------------------------------------------------------
+// -- DRAWING-2 ----------------------------------------------------------------------------------
 
 /** Only the sibling `index.tsx` (and its specs) may reach `component.tsx`; only `X` leaves the folder. */
 export const baseImportPair = {
@@ -241,7 +241,7 @@ export const baseImportPair = {
   },
 }
 
-// -- SHAPE-SLOT-3 ----------------------------------------------------------------------------------
+// -- DRAWING-3 ----------------------------------------------------------------------------------
 
 /** Words that name a data status or an open/closed lifecycle, never a drawn shape. */
 const DATA_STATUS = new Set([
@@ -279,7 +279,7 @@ export const noDataStatusShape = {
   },
 }
 
-// -- SHAPE-SLOT-4 ----------------------------------------------------------------------------------
+// -- DRAWING-4 ----------------------------------------------------------------------------------
 
 /** Flags that are a slot's data status. */
 const STATUS_FLAG = /^(?:isLoading|isError|isForbidden|isPending|isValidating|isEmpty)$/

package/file-layout.mjs

@@ -205,14 +205,15 @@ const featureTiers = (hfs) => {
 }
 
 /**
- * In a monorepo, the shared package stops below the block.
+ * In a front end with two or more apps, the shared package stops below the block.
  *
  * WHY THE SLOT IS ENOUGH HERE. The feature line is already drawn by the layer: a leaf knows
  * no domain and a block is a domain sentence, so which side of the workspace each belongs on
  * follows from the layer the slot reports. The layers a shared package may hold are the `kinds` of
- * `fe.package.ui`; an app holds the shared ones only when the repository declares that package.
+ * `fe.package.ui`; an app holds the shared ones only when the repository declares that package and another app can
+ * consume them. A one-app front end has nothing to share, so every tier may stay with that app.
  *
- * WHAT IT COST TO LEARN. A shared package carried one `blocks/FleetRow/` while its own header
+ * WHAT IT COST TO LEARN. A shared package carried one `blocks/WorkerRow/` while its own header
  * insisted that "a block carries feature meaning and therefore belongs to the app that owns the
  * feature". The document was right, the tree disagreed, and nothing turned red for either of them -
  * which is the whole argument for this rule rather than the paragraph.
@@ -222,18 +223,19 @@ export const monorepoTierBelongsToItsSide = {
     type: "problem",
     docs: {
       description:
-        "In a monorepo the shared package holds leaves, composites and branches; blocks, overlays, layouts and pages belong to the app that owns the feature.",
+        "With two or more apps, the shared package holds leaves, composites and branches; blocks, overlays, layouts and pages belong to the app that owns the feature.",
     },
     schema: [],
     messages: {
       featureInPackage:
         "`{{tier}}/` knows a feature, so it belongs to the app that owns that feature, not to the shared package - every app that never wanted this domain now ships it. Move it to `apps/<app>/src/components/{{tier}}/`.",
       vocabularyInApp:
-        "`{{tier}}/` knows no feature, so one copy belongs to every app - left here, the second app writes it again and the two drift with nothing to notice. Move it to `packages/ui/src/{{tier}}/`.",
+        "`{{tier}}/` knows no feature, and this repository has multiple apps, so one copy belongs to every app - left here, another app writes it again and the two drift with nothing to notice. Move it to `packages/ui/src/{{tier}}/`.",
     },
   },
   create(context) {
     const hfs = hfsOf(context)
+    if (hfs.apps.length < 2) return {}
     const folder = unknownLayerFolder(context)
     const inPackage = inSlot(context, "fe.package.ui") && folder !== null && featureTiers(hfs).has(folder) ? folder : null
     const tier = kindOfFile(context)
@@ -257,7 +259,7 @@ export const monorepoTierBelongsToItsSide = {
  *
  * WHY THIS RULE EXISTS RATHER THAN THE PARAGRAPH ALONE. The law said "the route file mounts and
  * nothing else" and had said so for as long as the tier list existed. Nothing checked it. A page
- * owner was written to `app/<segment>/fleet-page.tsx`, carried through a build, a lint run, a
+ * owner was written to `app/<segment>/workers-page.tsx`, carried through a build, a lint run, a
  * typecheck, four sealed screenshots and an approval, and arrived at the edge of a production write
  * with every gate green - because every gate was reading rules, and this one was only prose.
  *

package/icon.mjs

@@ -12,6 +12,7 @@
  * generalises on its own, and the gap between them is exactly where a third step gets invented.
  */
 
+import { isClassAttribute, staticText } from "./lib/ast.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { fileOf, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "./lib/scope.mjs"
 
@@ -51,14 +52,6 @@ const HEROICON_PACKAGES = new Set([
   "@starci/heroicons/16/solid",
 ])
 
-/**
- * Product reactions are attributed artwork rather than glyph-library imports.
- *
- * Their leaf owns this closed vocabulary and maps it to checked-in Fluent Emoji Flat SVGs under
- * `public/reactions/`; callers pass identities, never Unicode pictographs or asset paths.
- */
-export const REACTION_ASSET_NAMES = new Set(["like", "love", "haha", "wow", "sad", "angry"])
-
 /**
  * True when the file is the entry (slot role `entry`) of the component owner named `owner` in the layer `kind`.
  * The slot says which layer and which role; the owner's own folder name is the one fact it cannot say, so it is compared.
@@ -84,21 +77,6 @@ const isGlyphImport = (source) => {
 /** A glyph size written as a fraction of a step, or as an arbitrary value. */
 const OFF_SCALE_GLYPH = /\bsize-(?:\d+\.\d+|\[[^\]]+\])/
 
-/** True for a `className` / `class` JSX attribute. */
-const isClassAttribute = (node) =>
-  node.type === "JSXAttribute" && node.name && (node.name.name === "className" || node.name.name === "class")
-
-/** Static string carried by a JSX attribute, or by a module constant holding a class string. */
-const staticText = (value) => {
-  if (!value) return null
-  if (value.type === "Literal" && typeof value.value === "string") return value.value
-  if (value.type === "TemplateLiteral" && value.expressions.length === 0) {
-    return value.quasis.map((quasi) => quasi.value.cooked).join(" ")
-  }
-  if (value.type === "JSXExpressionContainer") return staticText(value.expression)
-  return null
-}
-
 // -- ICON-6 ----------------------------------------------------------------------------------------
 
 /** A glyph library is named in one file, and a caller asks for a MEANING instead. */

package/index.mjs

@@ -35,7 +35,7 @@ import { recommended as nativeControlsRecommended, rules as nativeControlsRules
 import { recommended as nextConventionsRecommended, rules as nextConventionsRules } from "./next-conventions.mjs"
 import { recommended as propsRecommended, rules as propsRules } from "./props-and-slots.mjs"
 import { recommended as servedLocaleRecommended, rules as servedLocaleRules } from "./served-locale.mjs"
-import { recommended as shapeSlotRecommended, rules as shapeSlotRules } from "./shape-slot.mjs"
+import { recommended as drawingRecommended, rules as drawingRules } from "./drawing.mjs"
 import { recommended as sizeBudgetRecommended, rules as sizeBudgetRules } from "./size-and-state-budget.mjs"
 import { recommended as sizeGrowthRecommended, rules as sizeGrowthRules } from "./size-growth.mjs"
 import { recommended as statusColorsRecommended, rules as statusColorsRules } from "./status-colors.mjs"
@@ -77,7 +77,7 @@ const CONTRIBUTIONS = [
   { law: "next-conventions", rules: nextConventionsRules, recommended: nextConventionsRecommended },
   { law: "props-and-slots", rules: propsRules, recommended: propsRecommended },
   { law: "served-locale", rules: servedLocaleRules, recommended: servedLocaleRecommended },
-  { law: "shape-slot", rules: shapeSlotRules, recommended: shapeSlotRecommended },
+  { law: "drawing", rules: drawingRules, recommended: drawingRecommended },
   { law: "size-and-state-budget", rules: sizeBudgetRules, recommended: sizeBudgetRecommended },
   { law: "size-growth", rules: sizeGrowthRules, recommended: sizeGrowthRecommended },
   { law: "status-colors", rules: statusColorsRules, recommended: statusColorsRecommended },

package/lib/ast.mjs

@@ -47,20 +47,23 @@ export const calleeName = (node) => {
 /** The name of a JSX element for a plain tag or a component; null for a member or namespaced name. */
 export const tagName = (opening) => (opening.name.type === "JSXIdentifier" ? opening.name.name : null)
 
-/** True for a function expression or an arrow function. */
-export const isFunction = (node) => node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression"
+/** True for a `className` / `class` JSX attribute. */
+export const isClassAttribute = (node) =>
+  node.type === "JSXAttribute" && node.name && (node.name.name === "className" || node.name.name === "class")
 
-/** True when the call is `useEffect(...)` or `useLayoutEffect(...)`, bare or through `React.`. */
-export const isEffectCall = (node) => {
-  const name = calleeName(node.callee)
-  return name === "useEffect" || name === "useLayoutEffect" || name === "React.useEffect" || name === "React.useLayoutEffect"
+/** Static string carried by a JSX attribute or by a module constant holding a class string. */
+export const staticText = (value) => {
+  if (!value) return null
+  if (value.type === "Literal" && typeof value.value === "string") return value.value
+  if (value.type === "TemplateLiteral" && value.expressions.length === 0) {
+    return value.quasis.map((quasi) => quasi.value.cooked).join(" ")
+  }
+  if (value.type === "JSXExpressionContainer") return staticText(value.expression)
+  return null
 }
 
-/** The callback of an effect call when it is written inline, else null. */
-export const effectCallback = (node) => {
-  const first = node.arguments[0]
-  return first && isFunction(first) ? first : null
-}
+/** True for a function expression or an arrow function. */
+export const isFunction = (node) => node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression"
 
 /**
  * Every node under `root`, depth first, through the visitor keys of the parser in use.

package/lib/config.mjs

@@ -1,7 +1,7 @@
 /**
  * The one flat config of a StarCi front end.
  *
- * A repository's `eslint.config.mjs` is a managed file (R05/R16/R17), rendered by `hfs sync` as exactly:
+ * A repository's `eslint.config.mjs` is a managed file (R05/R16/R17), rendered by `starci app sync` as exactly:
  *
  *     import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
  *     export default starciFeConfig({ hfs: loadHfs(import.meta.url) })

package/lib/scope.mjs

@@ -63,8 +63,12 @@ export const isConfigModule = (context) => inSlot(context, "fe.modules.config")
 /** The one place that may call `fetch`: slot `fe.transport.client` (one-app repository) or `fe.package.api.client` (shared package). */
 export const isApiClient = (context) => inSlot(context, "fe.transport.client", "fe.package.api.client")
 
-/** The file that may declare the one Outcome union: slot `fe.transport.outcome` or `fe.package.api.outcome`. */
-export const isOutcomeModule = (context) => inSlot(context, "fe.transport.outcome", "fe.package.api.outcome")
+/** The file that may declare the one Outcome union: the file of the slot the manifest marks `outcomeHome`. */
+export const isOutcomeModule = (context) => {
+  const hfs = hfsOf(context)
+  const slot = slotOfFile(context)
+  return slot !== null && hfs.slot(slot)?.outcomeHome === true
+}
 
 /** The basename of a path without directories. */
 export const baseName = (filename) => normalizePath(filename).split("/").pop() ?? ""