@starci/eslint-canon-fe 5.1.2 → 6.0.0

package/icon.mjs

@@ -12,13 +12,14 @@
  * generalises on its own, and the gap between them is exactly where a third step gets invented.
  */
 
-import { normalizePath } from "./lib/path.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { fileOf, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "./lib/scope.mjs"
 
-/** The one module allowed to name a glyph from a library. */
-const ICON_MODULE_RELATIVE = "leaves/Icon/index.tsx"
+/** The one module allowed to name a glyph from a library: the entry of the leaf owner named `Icon`. */
+const ICON_LEAF = { kind: "leaves", owner: "Icon" }
 
-/** Repeated goal / metric cells are text-led in the legacy reference. */
-const LABELLED_PROGRESS_ROW_RELATIVE = "composites/LabelledProgressRow/index.tsx"
+/** Repeated goal / metric cells are text-led in the legacy reference: the entry of the composite owner named `LabelledProgressRow`. */
+const LABELLED_PROGRESS_ROW = { kind: "composites", owner: "LabelledProgressRow" }
 
 /**
  * Package roots that ship glyphs.
@@ -58,15 +59,19 @@ const HEROICON_PACKAGES = new Set([
  */
 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.
+ */
+const isEntryOf = (context, { kind, owner }) =>
+  isComponentFile(context) && kindOfFile(context) === kind && roleOfFile(context) === "entry" &&
+  hfsOf(context).relative(fileOf(context)).split("/").slice(-2)[0] === owner
+
 /** True when this file is the icon leaf, which owns the meaning-to-glyph map. */
-const isIconLeafFile = (filename) => normalizePath(filename).endsWith(`/${ICON_MODULE_RELATIVE}`)
+const isIconLeafFile = (context) => isEntryOf(context, ICON_LEAF)
 
 /** True for the reusable repeated metric cell whose reference contains no decorative glyph. */
-const isLabelledProgressRowFile = (filename) =>
-  normalizePath(filename).endsWith(`/${LABELLED_PROGRESS_ROW_RELATIVE}`)
-
-/** Product source under `src/`; tooling and config are out of scope. */
-const isSourceFile = (filename) => normalizePath(filename).includes("/src/")
+const isLabelledProgressRowFile = (context) => isEntryOf(context, LABELLED_PROGRESS_ROW)
 
 /** True when an import source resolves into a glyph library, subpaths included. */
 const isGlyphImport = (source) => {
@@ -108,13 +113,12 @@ export const noVendorIconOutsideIconLeaf = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isSourceFile(file) || isIconLeafFile(file)) return {}
+    if (!isProductSource(context) || isIconLeafFile(context)) return {}
     return {
       ImportDeclaration(node) {
         const source = node.source && node.source.value
         if (!isGlyphImport(source)) return
-        context.report({ node, messageId: "vendor", data: { source, leaf: ICON_MODULE_RELATIVE } })
+        context.report({ node, messageId: "vendor", data: { source, leaf: `${ICON_LEAF.kind}/${ICON_LEAF.owner}/index.tsx` } })
       },
     }
   },
@@ -134,8 +138,7 @@ export const heroiconsIsTheGlyphVendor = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isSourceFile(file)) return {}
+    if (!isProductSource(context)) return {}
     return {
       ImportDeclaration(node) {
         const source = node.source && node.source.value
@@ -160,8 +163,7 @@ export const noOffScaleGlyphSize = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isSourceFile(file)) return {}
+    if (!isProductSource(context)) return {}
     const scan = (node, text) => {
       if (!text) return
       const hit = text.match(OFF_SCALE_GLYPH)
@@ -193,8 +195,7 @@ export const noDecorativeIconInMetricCell = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isLabelledProgressRowFile(file)) return {}
+    if (!isLabelledProgressRowFile(context)) return {}
     return {
       JSXOpeningElement(node) {
         if (node.name?.type === "JSXIdentifier" && node.name.name === "Icon") {

package/index.mjs

@@ -22,11 +22,7 @@ import { recommended as classNamesRecommended, rules as classNamesRules } from "
 import { recommended as e2eShapeRecommended, rules as e2eShapeRules, scope as e2eShapeScope } from "./e2e-shape.mjs"
 import { recommended as envOwnerRecommended, rules as envOwnerRules } from "./env-owner.mjs"
 import { recommended as fileLayoutRecommended, rules as fileLayoutRules } from "./file-layout.mjs"
-import {
-  audits as grammarBoundaryAudits,
-  recommended as grammarBoundaryRecommended,
-  rules as grammarBoundaryRules,
-} from "./grammar-boundary.mjs"
+import { recommended as grammarBoundaryRecommended, rules as grammarBoundaryRules } from "./grammar-boundary.mjs"
 import { recommended as formattingRecommended, rules as formattingRules } from "./formatting.mjs"
 import { recommended as hooksFolderRecommended, rules as hooksFolderRules } from "./hooks-folder.mjs"
 import { recommended as hygieneRecommended, rules as hygieneRules } from "./hygiene.mjs"
@@ -34,18 +30,7 @@ import { recommended as iconRecommended, rules as iconRules } from "./icon.mjs"
 import { recommended as landmarkRecommended, rules as landmarkRules } from "./landmark.mjs"
 import { recommended as listsRecommended, rules as listsRules } from "./lists.mjs"
 import { recommended as loadingRecommended, rules as loadingRules } from "./loading.mjs"
-import {
-  LAYOUT_GLOBS,
-  LAYOUTS,
-  audits as lintAdoptionAudits,
-  recommended as lintAdoptionRecommended,
-  rules as lintAdoptionRules,
-} from "./lint-adoption.mjs"
-import {
-  linterOptions as strictLinterOptions,
-  recommended as lintEscapeRecommended,
-  rules as lintEscapeRules,
-} from "./lint-escape-hatch.mjs"
+import { recommended as lintEscapeRecommended, rules as lintEscapeRules } from "./lint-escape-hatch.mjs"
 import { recommended as namingRecommended, rules as namingRules } from "./naming.mjs"
 import { recommended as nativeControlsRecommended, rules as nativeControlsRules } from "./native-controls.mjs"
 import { recommended as nextConventionsRecommended, rules as nextConventionsRules } from "./next-conventions.mjs"
@@ -53,7 +38,9 @@ import { recommended as propsRecommended, rules as propsRules } from "./props-an
 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 sizeBudgetRecommended, rules as sizeBudgetRules } from "./size-and-state-budget.mjs"
+import { recommended as sizeGrowthRecommended, rules as sizeGrowthRules } from "./size-growth.mjs"
 import { recommended as specQualityRecommended, rules as specQualityRules } from "./spec-quality.mjs"
+import { recommended as statusColorsRecommended, rules as statusColorsRules } from "./status-colors.mjs"
 import { recommended as splitRecommended, rules as splitRules } from "./the-split.mjs"
 import { recommended as tokensRecommended, rules as tokensRules } from "./tokens.mjs"
 import { recommended as transportRecommended, rules as transportRules } from "./transport.mjs"
@@ -61,6 +48,7 @@ import { recommended as translationRecommended, rules as translationRules } from
 import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
 import { recommended as typographyRecommended, rules as typographyRules } from "./typography.mjs"
 import { recommended as vendorRecommended, rules as vendorRules } from "./vendor-boundary.mjs"
+import { buildFeConfig } from "./lib/config.mjs"
 import { why } from "./lib/why.mjs"
 
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
@@ -76,12 +64,7 @@ const CONTRIBUTIONS = [
   { law: "e2e-shape", rules: e2eShapeRules, recommended: e2eShapeRecommended, scope: e2eShapeScope },
   { law: "env-owner", rules: envOwnerRules, recommended: envOwnerRecommended },
   { law: "file-layout", rules: fileLayoutRules, recommended: fileLayoutRecommended },
-  {
-    law: "grammar-boundary",
-    rules: grammarBoundaryRules,
-    recommended: grammarBoundaryRecommended,
-    audits: grammarBoundaryAudits,
-  },
+  { law: "grammar-boundary", rules: grammarBoundaryRules, recommended: grammarBoundaryRecommended },
   { law: "formatting", rules: formattingRules, recommended: formattingRecommended },
   { law: "hooks-folder", rules: hooksFolderRules, recommended: hooksFolderRecommended },
   { law: "hygiene", rules: hygieneRules, recommended: hygieneRecommended },
@@ -89,12 +72,6 @@ const CONTRIBUTIONS = [
   { law: "landmark", rules: landmarkRules, recommended: landmarkRecommended },
   { law: "lists", rules: listsRules, recommended: listsRecommended },
   { law: "loading", rules: loadingRules, recommended: loadingRecommended },
-  {
-    law: "lint-adoption",
-    rules: lintAdoptionRules,
-    recommended: lintAdoptionRecommended,
-    audits: lintAdoptionAudits,
-  },
   { law: "lint-escape-hatch", rules: lintEscapeRules, recommended: lintEscapeRecommended },
   { law: "naming", rules: namingRules, recommended: namingRecommended },
   { law: "native-controls", rules: nativeControlsRules, recommended: nativeControlsRecommended },
@@ -103,7 +80,9 @@ const CONTRIBUTIONS = [
   { law: "served-locale", rules: servedLocaleRules, recommended: servedLocaleRecommended },
   { law: "shape-slot", rules: shapeSlotRules, recommended: shapeSlotRecommended },
   { law: "size-and-state-budget", rules: sizeBudgetRules, recommended: sizeBudgetRecommended },
+  { law: "size-growth", rules: sizeGrowthRules, recommended: sizeGrowthRecommended },
   { law: "spec-quality", rules: specQualityRules, recommended: specQualityRecommended },
+  { law: "status-colors", rules: statusColorsRules, recommended: statusColorsRecommended },
   { law: "the-split", rules: splitRules, recommended: splitRecommended },
   { law: "tokens", rules: tokensRules, recommended: tokensRecommended },
   { law: "translation", rules: translationRules, recommended: translationRecommended },
@@ -113,21 +92,9 @@ const CONTRIBUTIONS = [
   { law: "vendor-boundary", rules: vendorRules, recommended: vendorRecommended },
 ]
 
-/** Every gathered law, including repository audits that publish no AST rule. */
+/** Every gathered law. */
 export const lawOwners = CONTRIBUTIONS.map((entry) => entry.law)
 
-/** Which law declares each repository-level audit. */
-export const auditOwners = Object.fromEntries(
-  CONTRIBUTIONS.flatMap((entry) =>
-    Object.keys(entry.audits ?? {}).map((name) => [name, entry.law]),
-  ),
-)
-
-/** Repository-level audits gathered beside the plugin. */
-export const audits = Object.fromEntries(
-  CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.audits ?? {})),
-)
-
 /**
  * Which law declares each rule.
  *
@@ -190,7 +157,8 @@ export const e2eRecommended = Object.fromEntries(
 )
 
 /** Flat-config options that make inline directives ineffective rather than merely forbidden. */
-export const linterOptions = strictLinterOptions
+export { linterOptions } from "./lib/config.mjs"
+export { loadHfs } from "./lib/hfs.mjs"
 
 /**
  * The Vietnamese why of each rule that carries a catalogue code: `{ code, vi, fixVi }`.
@@ -207,8 +175,6 @@ const plugin = {
 
 export default plugin
 
-export { LAYOUTS }
-
 /**
  * The React Hooks plugin, from wherever the consuming repository installed it.
  *
@@ -259,53 +225,29 @@ export const reactHooksRules = (reactHooks) => {
 }
 
 /**
- * Attach this canon to a repository: every rule, every level an error, both trees.
- *
- * A consuming `eslint.config.mjs` is three lines - it names its layout and spreads the result:
+ * The whole flat config of a front end: `export default starciFeConfig({ hfs: loadHfs(import.meta.url) })`.
  *
- *     import { starciFeConfig } from "@starci/eslint-canon-fe"
- *     export default [...starciFeConfig({ layout: "single-app" })]
+ * It owns nothing the repository could choose: which files are linted comes from the HFS profile (every app's and every
+ * workspace package's `src/`, and the e2e tree), not which rules are on, not their level, not whether an inline comment may
+ * switch one off. NO RULE IS OFF - the factory throws rather than emit a block in which a published rule is missing or
+ * below error, so a rule added to this package reaches every repository or the build of this package fails.
  *
- * It owns nothing about the law: not which rules are on, not their level, not whether an inline
- * comment may switch one off. NO RULE IS OFF - the factory throws rather than emit a block in which a
- * published rule is missing, so a rule added to this package reaches every repository or the build of
- * this package fails, and a repository cannot end up governed by a stale list.
- *
- * TWO BLOCKS. The first governs the product source (`src/**`, per layout) with every source rule and
- * the React Hooks rules; the second governs `e2e/**` and `playwright.config.*` with the e2e rules and
- * the escape-hatch fence. A repository's own plugins, ignores and language options stay its own
- * business; what it may not keep is a second opinion about the law.
- *
- * @param {object} input - Attachment options.
- * @param {"monorepo" | "single-app"} input.layout - Which shape this repository has.
- * @returns {object[]} Two flat-config blocks.
+ * @param {{ hfs: object }} input - The HFS view of the repository (`loadHfs(import.meta.url)`).
+ * @returns {object[]} The flat config: ignores, the typed source block, the e2e block.
  */
-export const starciFeConfig = ({ layout } = {}) => {
-  const globs = LAYOUT_GLOBS[layout]
-  if (!globs) {
-    throw new Error(`unknown layout "${layout}" - expected one of: ${LAYOUTS.join(", ")}`)
-  }
+export const starciFeConfig = ({ hfs } = {}) => {
   const published = Object.keys(rules).map((name) => `starci-fe/${name}`)
   const notRequested = published.filter((name) => recommended[name] !== "error")
   if (notRequested.length > 0) {
     throw new Error(`starciFeConfig: these published rules are not requested at error: ${notRequested.join(", ")}`)
   }
   const reactHooks = loadReactHooks()
-  const source = { ...sourceRecommended, ...reactHooksRules(reactHooks) }
-  // The escape-hatch fence is a source rule that must also cover the e2e tree.
-  const e2e = { ...e2eRecommended, "starci-fe/no-inline-lint-config": "error" }
-  return [
-    {
-      files: globs.src,
-      linterOptions: { ...linterOptions },
-      plugins: { "starci-fe": plugin, "react-hooks": reactHooks },
-      rules: source,
-    },
-    {
-      files: globs.e2e,
-      linterOptions: { ...linterOptions },
-      plugins: { "starci-fe": plugin },
-      rules: e2e,
-    },
-  ]
+  return buildFeConfig({
+    hfs,
+    plugin,
+    reactHooks,
+    source: { ...sourceRecommended, ...reactHooksRules(reactHooks) },
+    // The escape-hatch fence is a source rule that must also cover the e2e tree.
+    e2e: { ...e2eRecommended, "starci-fe/no-inline-lint-config": "error" },
+  })
 }

package/landmark.mjs

@@ -5,17 +5,6 @@
  * application may pass children through layouts and pages normally.
  */
 
-const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** Whether a file is a Next route layout. */
-export const isRouteLayoutFile = (filename) => /\/app\/(?:.*\/)?layout\.tsx$/.test(normalize(filename))
-
-/** Whether a file is a Next route entry. */
-export const isRouteFile = (filename) => /\/app\/(?:.*\/)?(?:layout|page)\.tsx$/.test(normalize(filename))
-
-/** Whether a file owns a page component. */
-export const isPageTierFile = (filename) => /\/src\/components\/pages\//.test(normalize(filename))
-
 /** Named branch owners that may provide landmark semantics. */
 export const LANDMARK_BRANCHES = new Set(["Main"])
 

package/lib/bindings.mjs

@@ -0,0 +1,144 @@
+/**
+ * Bindings of the front-end canon: what an identifier resolves to through the scope manager, which module an import
+ * comes from, which function a name stands for, and a stable KEY for an expression that names a place (a variable, a
+ * member path, `this.x`). A rule that must decide "is this the same handle / target / listener" compares keys, never
+ * spellings: two `id` variables in different scopes have different keys, `timerRef.current` has one key wherever it is
+ * written.
+ */
+
+/** The globals that all name the browser's global object. */
+const GLOBAL_OBJECT = new Set(["window", "globalThis", "self"])
+
+/** Wrappers that change a node's type, not its identity. */
+const TRANSPARENT = new Set(["TSAsExpression", "TSNonNullExpression", "TSSatisfiesExpression", "TSTypeAssertion", "ChainExpression", "ParenthesizedExpression"])
+
+/**
+ * The node without the wrappers that only change its type (`x as T`, `x!`, `x?.y`).
+ *
+ * @param {object} node - An ESTree node.
+ * @returns {object} The inner node.
+ */
+export const unwrap = (node) => {
+  let current = node
+  while (current && TRANSPARENT.has(current.type)) current = current.expression
+  return current
+}
+
+/**
+ * The node's parent with the type-only wrappers skipped upward.
+ *
+ * @param {object} node - An ESTree node.
+ * @returns {object|null} The first parent that is not a type-only wrapper.
+ */
+export const parentOf = (node) => {
+  let current = node.parent
+  while (current && TRANSPARENT.has(current.type)) current = current.parent
+  return current ?? null
+}
+
+/** True for a function expression, an arrow function or a function declaration. */
+export const isFn = (node) =>
+  Boolean(node) && (node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression" || node.type === "FunctionDeclaration")
+
+/**
+ * The scope-manager variable an identifier resolves to, or null for a global.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} identifier - An ESTree identifier.
+ * @returns {object|null} The variable.
+ */
+export const variableOf = (context, identifier) => {
+  for (let scope = context.sourceCode.getScope(identifier); scope; scope = scope.upper) {
+    const variable = scope.set.get(identifier.name)
+    if (variable) return variable
+  }
+  return null
+}
+
+/**
+ * Where an identifier was imported from.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} identifier - An ESTree identifier.
+ * @returns {{ source: string, imported: string|null }|null} The module specifier and the imported name (`null` for a default or namespace import), or null when the identifier is not an import.
+ */
+export const importOf = (context, identifier) => {
+  const variable = variableOf(context, identifier)
+  const definition = variable?.defs.find((entry) => entry.type === "ImportBinding")
+  if (!definition) return null
+  const specifier = definition.node
+  const source = String(definition.parent.source.value)
+  if (specifier.type === "ImportSpecifier") return { source, imported: specifier.imported.name ?? String(specifier.imported.value) }
+  return { source, imported: null }
+}
+
+/**
+ * The function an expression stands for: the function itself, or the function a same-file variable or declaration holds.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - An ESTree expression.
+ * @returns {object|null} The function node, or null when it cannot be resolved in this file.
+ */
+export const functionOf = (context, node) => {
+  const inner = unwrap(node)
+  if (!inner) return null
+  if (isFn(inner)) return inner
+  if (inner.type !== "Identifier") return null
+  const variable = variableOf(context, inner)
+  for (const definition of variable?.defs ?? []) {
+    if (definition.type === "FunctionName" && definition.node.type === "FunctionDeclaration") return definition.node
+    if (definition.type === "Variable" && definition.node.id.type === "Identifier") {
+      const init = unwrap(definition.node.init)
+      if (isFn(init)) return init
+    }
+  }
+  return null
+}
+
+/** A stable numeric id per scope-manager variable, so keys compare by binding and not by spelling. */
+const VARIABLE_IDS = new WeakMap()
+let nextVariableId = 1
+const idOf = (variable) => {
+  if (!VARIABLE_IDS.has(variable)) VARIABLE_IDS.set(variable, nextVariableId++)
+  return VARIABLE_IDS.get(variable)
+}
+
+/**
+ * The key of an expression that names a place: `v12` for a variable, `v12.current` for a member path, `this.timer` for
+ * a member of `this`, `g:window` for the browser's global object under any of its names. Anything else has no key.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - An ESTree expression.
+ * @returns {string|null} The key.
+ */
+export const keyOf = (context, node) => {
+  const inner = unwrap(node)
+  if (!inner) return null
+  if (inner.type === "Identifier") {
+    const variable = variableOf(context, inner)
+    if (variable && variable.defs.length > 0) return `v${idOf(variable)}`
+    return GLOBAL_OBJECT.has(inner.name) ? "g:window" : `g:${inner.name}`
+  }
+  if (inner.type === "ThisExpression") return "this"
+  if (inner.type === "MemberExpression") {
+    const head = keyOf(context, inner.object)
+    if (head === null) return null
+    if (!inner.computed && inner.property.type === "Identifier") return `${head}.${inner.property.name}`
+    if (inner.computed && inner.property.type === "Literal") return `${head}[${String(inner.property.value)}]`
+    return null
+  }
+  return null
+}
+
+/**
+ * The receiver and the member name of a call written as `receiver.name(...)`, or the bare name of `name(...)`.
+ *
+ * @param {object} call - An ESTree call expression.
+ * @returns {{ receiver: object|null, name: string }|null} The parts, or null for a computed or exotic callee.
+ */
+export const calleeParts = (call) => {
+  const callee = unwrap(call.callee)
+  if (callee.type === "Identifier") return { receiver: null, name: callee.name }
+  if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier") return { receiver: callee.object, name: callee.property.name }
+  return null
+}

package/lib/config.mjs

@@ -0,0 +1,79 @@
+/**
+ * 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:
+ *
+ *     import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+ *     export default starciFeConfig({ hfs: loadHfs(import.meta.url) })
+ *
+ * The factory owns everything else: which files are linted (the source of every app and every workspace package, and the
+ * e2e tree), typed linting on the source (`parserOptions.projectService`, so a rule asks what a node IS rather than what
+ * it is called), the ignores, the linter options that make a disable comment impossible, every canon rule at `error`,
+ * the React Hooks rules at `error`, and `settings.starci.hfs` - the slot view each path-scoped rule asks instead of a path
+ * pattern. It 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"
+
+/** 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" })
+
+/** The product source of a front end: every app's `src/` and every workspace package's `src/` (slots fe.* and repo.packages). */
+export const SOURCE_FILES = Object.freeze(["apps/*/src/**/*.{ts,tsx}", "packages/*/src/**/*.{ts,tsx}"])
+
+/** The e2e tree (slots fe.e2e, fe.e2e-support) and the Playwright config beside it. */
+export const E2E_FILES = Object.freeze(["e2e/**/*.{ts,tsx}", "playwright.config.ts"])
+
+/** Build output, installed packages, generated wire types and the harness's report directory are never linted. */
+export const IGNORED = Object.freeze(["**/node_modules/**", "**/.next/**", "**/dist/**", "**/coverage/**", "**/__generated__/**", ".starci/**"])
+
+const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting)
+
+/**
+ * The flat config of one front-end repository.
+ *
+ * @param {object} input - Attachment options.
+ * @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.source - The source-tree levels (canon rules plus the React Hooks rules).
+ * @param {Record<string, unknown>} input.e2e - The e2e-tree levels.
+ * @param {object} input.reactHooks - The React Hooks plugin.
+ * @returns {Array<object>} The flat config: one ignore block, one typed source block and one e2e block.
+ */
+export const buildFeConfig = ({ hfs, plugin, source, e2e, reactHooks }) => {
+  if (!hfs || typeof hfs.slotOf !== "function" || typeof hfs.repoRoot !== "string") {
+    throw new Error("starciFeConfig needs { hfs: loadHfs(import.meta.url) } - the rules read the repository's slots through it")
+  }
+  if (hfs.profile !== "fe") throw new Error(`starciFeConfig lints a front end; hfs.json declares profile ${hfs.profile}`)
+  for (const [tree, levels] of [["source", source], ["e2e", e2e]]) {
+    if (Object.keys(levels).length === 0) throw new Error(`starciFeConfig received an empty ${tree} recommendation - a config with no rules is not adoption`)
+    const weak = Object.entries(levels).filter(([, setting]) => levelOf(setting) !== "error").map(([name]) => name)
+    if (weak.length > 0) throw new Error(`starciFeConfig refuses ${tree} rules not at error: ${weak.join(", ")}`)
+  }
+  const settings = { starci: { hfs } }
+  return [
+    { ignores: [...IGNORED] },
+    {
+      files: [...SOURCE_FILES],
+      languageOptions: {
+        parser: tsParser,
+        ecmaVersion: "latest",
+        sourceType: "module",
+        parserOptions: { projectService: true, tsconfigRootDir: hfs.repoRoot, ecmaFeatures: { jsx: true } },
+      },
+      linterOptions: { ...linterOptions },
+      plugins: { "starci-fe": plugin, "react-hooks": reactHooks },
+      settings,
+      rules: { ...source },
+    },
+    {
+      // The e2e tree is typed by tsconfig.e2e.json, which the project service does not open; its rules read syntax only.
+      files: [...E2E_FILES],
+      languageOptions: { parser: tsParser, ecmaVersion: "latest", sourceType: "module" },
+      linterOptions: { ...linterOptions },
+      plugins: { "starci-fe": plugin },
+      settings,
+      rules: { ...e2e },
+    },
+  ]
+}

package/lib/hfs.mjs

@@ -0,0 +1,48 @@
+/**
+ * The one door between the front-end lint rules and the HFS slot manifest of the repository being linted.
+ *
+ * A consuming `eslint.config.mjs` is the managed one-liner `export default starciFeConfig({ hfs: loadHfs(import.meta.url) })`.
+ * `loadHfs` reads the repository's `hfs.json` beside that config file and the slot manifest this package ships in
+ * `runtime/` (a byte copy of the runtime's `knowledge/hfs/slots.yaml`, `scripts/lib/hfs-slots.mjs` and
+ * `scripts/lib/hfs-view.mjs`, refreshed by `packages/hfs/scripts/sync-runtime.mjs`), and returns the view the factory puts
+ * in `settings.starci.hfs`.
+ *
+ * Every path-scoped rule asks `slotOf` / `tierOf` here instead of testing a path with a regular expression. A rule that
+ * needs the view and finds none stops the lint run with an error naming the fix: a rule must not guess.
+ */
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { declaredHfsView, openHfsView } from "../runtime/scripts/lib/hfs-view.mjs"
+
+const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime")
+
+/**
+ * The HFS view of the repository whose `eslint.config.mjs` calls this.
+ *
+ * @param {string} configUrl - `import.meta.url` of the repository's `eslint.config.mjs`.
+ * @returns {object} The frozen HFS view.
+ */
+export const loadHfs = (configUrl) => openHfsView({ runtimeRoot: RUNTIME, repoRoot: dirname(fileURLToPath(configUrl)) })
+
+/**
+ * The HFS view of an in-memory declaration, for rule tests.
+ *
+ * @param {object} declaration - An `hfs.json` object.
+ * @param {string} repoRoot - The absolute root the linted filenames live under.
+ * @returns {object} The frozen HFS view.
+ */
+export const hfsFromDeclaration = (declaration, repoRoot) => declaredHfsView({ runtimeRoot: RUNTIME, declaration, repoRoot })
+
+/**
+ * The HFS view a rule runs under; a rule that needs it and gets none refuses to guess.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @returns {object} The HFS view from `settings.starci.hfs`.
+ */
+export const hfsOf = (context) => {
+  const hfs = context.settings?.starci?.hfs
+  if (!hfs || typeof hfs.slotOf !== "function") {
+    throw new Error(`${context.id ?? "a starci-fe rule"} needs settings.starci.hfs: lint through starciFeConfig({ hfs: loadHfs(import.meta.url) })`)
+  }
+  return hfs
+}

package/lib/next.mjs

@@ -0,0 +1,6 @@
+/**
+ * Next.js's own contract for route segment files, read from the runtime's one statement of it
+ * (`scripts/lib/next-contract.mjs`, shipped in `runtime/` by `packages/hfs/scripts/sync-runtime.mjs`): the architecture
+ * machine and these laws hold the same list by construction.
+ */
+export { NEXT_RESERVED_EXPORTS, NEXT_ROUTE_SEGMENT_STEMS } from "../runtime/scripts/lib/next-contract.mjs"

package/lib/platform.mjs

@@ -0,0 +1,66 @@
+/**
+ * Platform APIs of the front-end canon, decided by resolution: an identifier or member is "the platform's" when the
+ * TypeScript symbol it binds to is declared in a default library file or in an ambient global declaration, so a local
+ * function that happens to be called `setTimeout` or `fetch` is not mistaken for the browser's.
+ */
+import ts from "typescript"
+import { typed } from "./types.mjs"
+
+/** True when a declaration sits in the default lib, in a global script declaration file, or in a `declare global` block. */
+const isGlobalDeclaration = (program, declaration) => {
+  const file = declaration.getSourceFile()
+  if (program.isSourceFileDefaultLibrary(file)) return true
+  for (let current = declaration.parent; current; current = current.parent) {
+    if (ts.isModuleDeclaration(current) && current.flags & ts.NodeFlags.GlobalAugmentation) return true
+  }
+  return file.isDeclarationFile && !ts.isExternalModule(file)
+}
+
+/**
+ * True when the symbol at a node (an identifier, or the property of a member access) is declared by the platform.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - An ESTree identifier, or a member expression (its property is asked).
+ * @returns {boolean} Whether every declaration of the symbol is a platform (global, ambient) declaration.
+ */
+export const isPlatform = (context, node) => {
+  const { program, checker, toTs } = typed(context)
+  const target = node.type === "MemberExpression" ? node.property : node
+  const tsNode = toTs(target)
+  if (!tsNode) return false
+  const symbol = checker.getSymbolAtLocation(tsNode)
+  const declarations = symbol?.getDeclarations?.() ?? []
+  return declarations.length > 0 && declarations.every((declaration) => isGlobalDeclaration(program, declaration))
+}
+
+/**
+ * True when the type of an expression carries no information (`any`, `unknown` or an error type).
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - An ESTree expression.
+ * @returns {boolean} Whether the checker could not decide what the expression is.
+ */
+export const isUnresolvedType = (context, node) => {
+  const { checker, toTs } = typed(context)
+  const tsNode = toTs(node)
+  if (!tsNode) return true
+  const type = checker.getTypeAtLocation(tsNode)
+  return Boolean(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+}
+
+/**
+ * The property names of the type of an expression, after union members are read.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - An ESTree expression.
+ * @returns {Set<string>} The names of the properties every member of the type could carry.
+ */
+export const propertyNamesOf = (context, node) => {
+  const { checker, toTs } = typed(context)
+  const tsNode = toTs(node)
+  const names = new Set()
+  if (!tsNode) return names
+  const type = checker.getTypeAtLocation(tsNode)
+  for (const part of type.isUnion?.() ? type.types : [type]) for (const property of part.getProperties?.() ?? []) names.add(property.getName())
+  return names
+}