@starci/eslint-canon-fe 6.0.2 → 7.0.0

package/docs/spec-quality.md

@@ -1,147 +0,0 @@
-# Spec quality
-
-Law module: `spec-quality.mjs`. Catalogue: R67 FE_SPEC_QUALITY, R60 (real catalogue in specs).
-
-A spec is a claim about one unit's behaviour: no class-string pinning, it imports the unit beside it, no spec for a barrel, no `as unknown as`, an axe assertion for every connected screen, and a real `next-intl` catalogue instead of a mock.
-
-Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
-
-## `starci-fe/no-class-string-in-spec`
-
-A component spec asserts behaviour, never a class string.
-
-**Invalid** (`src/components/leaves/Chip/Chip.test.tsx`)
-
-```ts
-expect(el).toHaveClass("bg-primary")
-```
-
-**Valid** (`src/components/leaves/Chip/Chip.test.tsx`)
-
-```ts
-expect(screen.getByRole("button", { name: "Save" })).toBeEnabled()
-```
-
-**Finding code:** `FE_SPEC_QUALITY`
-
-**Vì sao (why):** Spec `<file>` ghim chuỗi class. Spec kiểm hành vi, không kiểm stylesheet.
-
-**Cách sửa:** Assert theo role, tên, trạng thái hoặc chữ hiển thị.
-
-## `starci-fe/spec-tests-its-neighbour`
-
-A spec imports its sibling subject: `X.test.tsx` imports `./X`.
-
-**Invalid** (`src/components/leaves/Chip/Chip.test.tsx`)
-
-```ts
-import { Row } from "../Row"
-```
-
-**Valid** (`src/components/leaves/Chip/Chip.test.tsx`)
-
-```ts
-import { Chip } from "./Chip"
-```
-
-**Finding code:** `FE_SPEC_QUALITY`
-
-**Vì sao (why):** Spec `<file>` không import chủ thể nằm cạnh nó.
-
-**Cách sửa:** Đưa spec về cạnh chủ thể, hoặc test đúng đơn vị nằm cạnh.
-
-## `starci-fe/no-barrel-spec`
-
-No `index.spec.ts(x)` beside an `index.ts(x)` that holds only imports and re-exports. The sibling is read and parsed: an `index.ts` that declares a function, class or value (implementation) may have its spec; a missing sibling is no finding.
-
-**Invalid** (`src/hooks/index.spec.ts`, beside `src/hooks/index.ts` = `export * from "./useFeed"`)
-
-```ts
-// file: src/hooks/index.spec.ts
-```
-
-**Valid** (`src/modules/browser-storage/index.spec.ts`, beside an `index.ts` that declares `createStore` and exports two stores)
-
-```ts
-// file: src/modules/browser-storage/index.spec.ts
-```
-
-**Finding code:** `FE_SPEC_QUALITY`
-
-**Vì sao (why):** Spec `<file>` đặt cạnh một barrel. Barrel không có hành vi để test.
-
-**Cách sửa:** Xóa spec; test từng đơn vị mà barrel xuất lại, cạnh chính đơn vị đó.
-
-## `starci-fe/no-double-cast-in-spec`
-
-A spec builds its values with the type's own shape, not `as unknown as`.
-
-**Invalid** (`any spec`)
-
-```ts
-const x = { id: 1 } as unknown as Course
-```
-
-**Valid** (`any spec`)
-
-```ts
-const x = mock<Course>()
-```
-
-**Finding code:** `FE_SPEC_QUALITY`
-
-**Vì sao (why):** Spec `<file>` ép kiểu hai lần (`as unknown as`).
-
-**Cách sửa:** Dựng giá trị bằng factory có kiểu (`mock<T>()` hoặc fixture builder).
-
-## `starci-fe/connected-spec-has-axe`
-
-The spec of a connected block or feature runs an axe assertion.
-
-**Invalid** (`src/components/blocks/Feed/index.test.tsx`)
-
-```ts
-it("renders", () => {})
-```
-
-**Valid** (`src/components/blocks/Feed/index.test.tsx`)
-
-```ts
-it("a11y", async () => { expect(await axe(container)).toHaveNoViolations() })
-```
-
-**Finding code:** `FE_SPEC_QUALITY`
-
-**Vì sao (why):** Spec `<file>` của màn hình kết nối không có assert axe.
-
-**Cách sửa:** Thêm `expect(await axe(container)).toHaveNoViolations()`.
-
-## `starci-fe/no-mocked-translations`
-
-A spec renders with the real catalogue; it never mocks `next-intl`. A `vi.mock("next-intl/server", factory)` in the spec of a server helper (no provider exists for it) is allowed when the factory - or a `vi.hoisted` block it reads - uses the app's real catalogue (an import that resolves into `modules/i18n/messages/`); a literal or key-echoing server mock, an automock, and any mock of the client `next-intl` stay findings.
-
-**Invalid** (`any spec`)
-
-```ts
-vi.mock("next-intl", () => ({}))
-```
-
-**Valid** (`any spec`)
-
-```ts
-render(<NextIntlClientProvider messages={messages} locale="vi" />)
-```
-
-```ts
-import messages from "@/modules/i18n/messages/vi.json"
-vi.mock("next-intl/server", async () => {
-  const { createTranslator } = await import("next-intl")
-  return { getTranslations: async () => createTranslator({ locale: "vi", messages }) }
-})
-```
-
-**Finding code:** `FE_I18N_CATALOG`
-
-**Vì sao (why):** Spec `<file>` giả lập `next-intl`, nên chỉ kiểm khóa chứ không kiểm catalog thật.
-
-**Cách sửa:** Component client: render trong `NextIntlClientProvider` với `messages/<locale>.json` thật. Helper server (`next-intl/server`): factory của mock dựng translator từ catalog thật (`createTranslator` với `modules/i18n/messages/<locale>.json`).

package/e2e-shape.mjs

@@ -1,345 +0,0 @@
-/**
- * The rules that hold `e2e-shape.md` (HFS R66, `FE_E2E_SHAPE`).
- *
- * THESE RULES GOVERN THE E2E TREE, NOT `src/`. `starciFeConfig` attaches them to `e2e/**` and
- * `playwright.config.*`; every rule here also scopes itself by HFS slot (tier e2e, the Playwright config role), so a config that reaches it by
- * mistake governs nothing it should not.
- *
- * WHY THE SHAPE IS FIXED. An e2e suite is the only proof that the whole app works, and it is run by
- * hand, so it rots quietly: absolute paths that exist on one machine, a Docker dependency that makes
- * it unrunnable in CI, a helper that writes into the OTHER repository's tree, a `test.skip` that
- * turns a missing environment into a green run, and helpers whose untyped parameters hide the fields
- * a test depends on. One layout - `e2e/<area>/<name>.e2e-spec.ts`, three viewports, typed helpers -
- * is what lets the land gate check it statically even though it cannot run it.
- *
- * WHAT IS NOT HERE. That `typecheck:e2e` runs before `test:e2e` is a `package.json` fact (the
- * architecture machine reads it); that the specs pass is the run itself.
- */
-
-import { baseName, classOf, fileOf, inSlot, isE2eSource, roleOfFile } from "./lib/scope.mjs"
-
-/** The three viewports every e2e project set covers, as `width x height`. */
-export const VIEWPORTS = Object.freeze(["1440x900", "768x1024", "390x844"])
-
-/** A file that reads like a spec, by any of the common spellings. */
-const SPEC_LIKE = /(?:\.|-)(?:e2e-)?(?:spec|test)\.[cm]?tsx?$/
-
-/** A helper file that is named as a spec. */
-const E2E_SPEC_NAME = /\.e2e-spec\./
-
-/** The slots of the e2e tree: the specs (`fe.e2e`) and their helpers (`fe.e2e-support`). */
-const E2E_SLOTS = ["fe.e2e", "fe.e2e-support"]
-
-/** An absolute filesystem path: a drive, a UNC share, or a well-known root. */
-const ABSOLUTE_PATH = /^(?:[A-Za-z]:[\\/]|\\\\|\/(?:Users|home|tmp|mnt|var|opt|etc|root|d|c)\/)/
-
-/** A `..` segment in a path string. */
-const PARENT_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/
-
-/** Static string of a literal or an expression-free template, else null. */
-const staticString = (node) => {
-  if (!node) return null
-  if (node.type === "Literal" && typeof node.value === "string") return node.value
-  if (node.type === "TemplateLiteral") return node.quasis.map((quasi) => quasi.value.cooked ?? "").join("")
-  return null
-}
-
-/** Every string in a subtree, so `path.join(__dirname, "..", "..")` is read as its parts. */
-const stringsIn = (node, source) => {
-  const found = []
-  const walk = (current) => {
-    if (!current || typeof current.type !== "string") return
-    const text = staticString(current)
-    if (text !== null) found.push(text)
-    for (const key of source.visitorKeys[current.type] ?? []) {
-      const child = current[key]
-      if (Array.isArray(child)) child.forEach(walk)
-      else walk(child)
-    }
-  }
-  walk(node)
-  return found
-}
-
-// -- E2E-1 -----------------------------------------------------------------------------------------
-
-/** Specs live at `e2e/<area>/<name>.e2e-spec.ts`. */
-export const e2eSpecLocation = {
-  meta: {
-    type: "problem",
-    docs: { description: "An e2e spec is `e2e/<area>/<name>.e2e-spec.ts`; helpers live under `support/` or `fixtures/`." },
-    schema: [],
-    messages: {
-      location:
-        "`{{name}}` is not at `e2e/<area>/<name>.e2e-spec.ts`. One shape - an area folder, the `.e2e-spec.ts` suffix - is what lets the gate find every spec without running them; helpers go in `e2e/support/` or `e2e/fixtures/` and are never named like a spec.",
-    },
-  },
-  create(context) {
-    const name = baseName(fileOf(context))
-    const found = classOf(context)
-    // A helper slot (`fe.e2e-support`) owns no spec: a helper named like one is a spec in the wrong place.
-    const helperNamedSpec = inSlot(context, "fe.e2e-support") && E2E_SPEC_NAME.test(name)
-    // A spec-looking file no slot owns but that sits inside the e2e tree (the nearest slot is an e2e slot, matched past the repository root)
-    // is a spec off the one place `fe.e2e` gives it. A file outside the e2e tree is not this rule's business.
-    const misplacedSpec = found.status === "no-slot" && E2E_SLOTS.includes(found.nearest?.slot) && found.nearest.matchedDepth >= 1 && SPEC_LIKE.test(name)
-    if (helperNamedSpec || misplacedSpec) return { Program: (node) => context.report({ node, messageId: "location", data: { name } }) }
-    return {}
-  },
-}
-
-// -- E2E-2 -----------------------------------------------------------------------------------------
-
-/** No absolute path in e2e source. */
-export const e2eNoAbsolutePath = {
-  meta: {
-    type: "problem",
-    docs: { description: "No absolute filesystem path in e2e source." },
-    schema: [],
-    messages: {
-      absolute:
-        "An absolute path (`{{path}}`). It exists on one machine and nowhere else, so the suite passes locally and cannot run in CI or on another machine. Build the path from the config or the test's own directory.",
-    },
-  },
-  create(context) {
-    if (!isE2eSource(context)) return {}
-    const check = (node, text) => {
-      if (typeof text === "string" && ABSOLUTE_PATH.test(text)) context.report({ node, messageId: "absolute", data: { path: text } })
-    }
-    return {
-      Literal: (node) => check(node, node.value),
-      TemplateElement: (node) => check(node, node.value && node.value.cooked),
-    }
-  },
-}
-
-// -- E2E-3 -----------------------------------------------------------------------------------------
-
-/** Container tooling that an e2e suite must not depend on. */
-const DOCKER_MODULE = /^(?:dockerode|testcontainers|@testcontainers\/.+|docker-compose)$/
-
-/** A command or string that starts Docker. */
-const DOCKER_TEXT = /\bdocker(?:-compose)?\b|\bdocker\s+compose\b/i
-
-/** No Docker in e2e. */
-export const e2eNoDocker = {
-  meta: {
-    type: "problem",
-    docs: { description: "An e2e suite does not start or require Docker." },
-    schema: [],
-    messages: {
-      docker:
-        "Docker in an e2e suite. A suite that needs a container runtime cannot run where the app can, and it hides the real prerequisite (a running app and backend) behind a tool. Point the suite at a URL from the config and let the environment provide the stack.",
-    },
-  },
-  create(context) {
-    if (!isE2eSource(context)) return {}
-    return {
-      ImportDeclaration(node) {
-        if (DOCKER_MODULE.test(String(node.source.value))) context.report({ node, messageId: "docker" })
-      },
-      Literal(node) {
-        if (typeof node.value === "string" && DOCKER_TEXT.test(node.value)) context.report({ node, messageId: "docker" })
-      },
-      TemplateElement(node) {
-        if (DOCKER_TEXT.test((node.value && node.value.cooked) || "")) context.report({ node, messageId: "docker" })
-      },
-    }
-  },
-}
-
-// -- E2E-4 -----------------------------------------------------------------------------------------
-
-/** Filesystem calls that write, move or remove. */
-const FS_WRITE = new Set([
-  "writeFile",
-  "writeFileSync",
-  "appendFile",
-  "appendFileSync",
-  "mkdir",
-  "mkdirSync",
-  "rm",
-  "rmSync",
-  "rmdir",
-  "rmdirSync",
-  "copyFile",
-  "copyFileSync",
-  "cp",
-  "cpSync",
-  "rename",
-  "renameSync",
-  "unlink",
-  "unlinkSync",
-  "createWriteStream",
-])
-
-/** The name a call is made through: `writeFile` or `fs.writeFile` or `fs.promises.writeFile`. */
-const calleeName = (callee) => {
-  if (callee.type === "Identifier") return callee.name
-  if (callee.type === "MemberExpression" && !callee.computed) return callee.property.name
-  return null
-}
-
-/** No e2e write outside the repository's own tree. */
-export const e2eNoCrossRepoWrite = {
-  meta: {
-    type: "problem",
-    docs: { description: "An e2e file write never targets an absolute path or climbs out of the repository." },
-    schema: [],
-    messages: {
-      write:
-        "This file operation writes to a path that is absolute or climbs out with `..`. An e2e run that writes into another repository (the backend's tree, a shared folder) changes state it does not own, and its result depends on a checkout layout. Write under this repository's own output folder.",
-    },
-  },
-  create(context) {
-    if (!isE2eSource(context)) return {}
-    const source = context.sourceCode || context.getSourceCode()
-    return {
-      CallExpression(node) {
-        const name = calleeName(node.callee)
-        if (!name || !FS_WRITE.has(name)) return
-        const strings = node.arguments.flatMap((argument) => stringsIn(argument, source))
-        if (strings.some((text) => ABSOLUTE_PATH.test(text) || PARENT_SEGMENT.test(text) || text === "..")) {
-          context.report({ node, messageId: "write" })
-        }
-      },
-    }
-  },
-}
-
-// -- E2E-5 -----------------------------------------------------------------------------------------
-
-/** The root identifier of a member chain: `test` in `test.describe.skip`. */
-const chainRoot = (node) => {
-  let current = node
-  while (current && current.type === "MemberExpression") current = current.object
-  return current && current.type === "Identifier" ? current.name : null
-}
-
-/** No skipped test: a missing environment is a failure. */
-export const e2eNoSkip = {
-  meta: {
-    type: "problem",
-    docs: { description: "No `test.skip`, `test.fixme` or `describe.skip`: a missing environment fails the run." },
-    schema: [],
-    messages: {
-      skip:
-        "A skipped test. Skipping because the environment is missing turns \"the suite cannot run\" into a green run, which is the one result an e2e suite must never give. Fix the environment, or delete the test.",
-    },
-  },
-  create(context) {
-    if (!isE2eSource(context)) return {}
-    return {
-      CallExpression(node) {
-        const callee = node.callee
-        if (callee.type !== "MemberExpression" || callee.computed) return
-        if (!["skip", "fixme"].includes(callee.property.name)) return
-        if (["test", "it", "describe"].includes(chainRoot(callee.object))) context.report({ node, messageId: "skip" })
-      },
-    }
-  },
-}
-
-// -- E2E-6 -----------------------------------------------------------------------------------------
-
-/** True when a function is a module-level helper: declared, or bound to a top-level `const`. */
-const isModuleLevel = (node) => {
-  let current = node.parent
-  if (node.type !== "FunctionDeclaration") {
-    if (!current || current.type !== "VariableDeclarator") return false
-    current = current.parent && current.parent.parent
-  }
-  return Boolean(current) && ["Program", "ExportNamedDeclaration", "ExportDefaultDeclaration"].includes(current.type)
-}
-
-/** Helpers carry types; nothing is `any`. */
-export const e2eTypedHelpers = {
-  meta: {
-    type: "problem",
-    docs: { description: "e2e helper parameters are typed and nothing is `any`." },
-    schema: [],
-    messages: {
-      untyped:
-        "A helper parameter with no type. A test depends on the fields a helper takes and returns; untyped, a renamed field fails at run time in a test nobody touched. Annotate the parameter.",
-      any: "`any` in e2e source. It turns the compiler off for the value a test asserts on. Type it, or narrow from `unknown`.",
-    },
-  },
-  create(context) {
-    if (!isE2eSource(context)) return {}
-    const checkParams = (node) => {
-      if (!isModuleLevel(node)) return
-      for (const parameter of node.params) {
-        const target = parameter.type === "AssignmentPattern" ? parameter.left : parameter
-        // A default value gives the parameter a type the compiler infers.
-        if (parameter.type === "AssignmentPattern" && parameter.right.type === "Literal") continue
-        if (target.type === "RestElement") {
-          if (!target.typeAnnotation) context.report({ node: target, messageId: "untyped" })
-          continue
-        }
-        if (!target.typeAnnotation) context.report({ node: target, messageId: "untyped" })
-      }
-    }
-    return {
-      FunctionDeclaration: checkParams,
-      ArrowFunctionExpression: checkParams,
-      FunctionExpression: checkParams,
-      TSAnyKeyword(node) {
-        context.report({ node, messageId: "any" })
-      },
-    }
-  },
-}
-
-// -- E2E-7 -----------------------------------------------------------------------------------------
-
-/** Every Playwright config declares exactly the three viewports. */
-export const playwrightViewports = {
-  meta: {
-    type: "problem",
-    docs: { description: `playwright.config declares the viewports ${VIEWPORTS.join(", ")} and no others.` },
-    schema: [],
-    messages: {
-      missing:
-        "The Playwright config does not declare the viewport {{size}}. Every app is proved at 1440x900, 768x1024 and 390x844 so a layout that only works on a desktop screen fails here.",
-      extra:
-        "The Playwright config declares the viewport {{size}}, which is not one of 1440x900, 768x1024, 390x844. A fourth size is a fourth thing to keep passing that no design covers.",
-    },
-  },
-  create(context) {
-    if (roleOfFile(context) !== "playwright") return {}
-    const seen = new Map()
-    return {
-      Property(node) {
-        if (node.computed || node.key.type !== "Identifier" || node.key.name !== "viewport") return
-        if (node.value.type !== "ObjectExpression") return
-        const field = (name) => {
-          const property = node.value.properties.find((p) => p.type === "Property" && p.key.type === "Identifier" && p.key.name === name)
-          return property && property.value.type === "Literal" ? property.value.value : null
-        }
-        const width = field("width")
-        const height = field("height")
-        if (typeof width === "number" && typeof height === "number") seen.set(`${width}x${height}`, node)
-      },
-      "Program:exit"(program) {
-        for (const size of VIEWPORTS) if (!seen.has(size)) context.report({ node: program, messageId: "missing", data: { size } })
-        for (const [size, node] of seen) if (!VIEWPORTS.includes(size)) context.report({ node, messageId: "extra", data: { size } })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "e2e-spec-location": e2eSpecLocation,
-  "e2e-no-absolute-path": e2eNoAbsolutePath,
-  "e2e-no-docker": e2eNoDocker,
-  "e2e-no-cross-repo-write": e2eNoCrossRepoWrite,
-  "e2e-no-skip": e2eNoSkip,
-  "e2e-typed-helpers": e2eTypedHelpers,
-  "playwright-viewports": playwrightViewports,
-}
-
-/** Which tree these rules govern: the factory attaches them to `e2e/**`, not to `src/**`. */
-export const scope = "e2e"
-
-/** Every rule is an error. */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))