@starci/eslint-canon-fe 5.1.2 → 6.0.0

package/next-conventions.mjs

@@ -12,8 +12,8 @@
  */
 
 import { attribute, attributeValue, calleeName, leadingTextOf, stringOf } from "./lib/ast.mjs"
-import { baseName, isSpecFile, stem } from "./lib/scope.mjs"
-import { normalizePath } from "./lib/path.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { baseName, classOf, fileOf, inSlot, isSpecFile, roleOfFile, slotOfFile, stem } from "./lib/scope.mjs"
 
 /** Another i18n stack: a second place that decides which language a reader sees. */
 const OTHER_I18N = /^(?:react-i18next|i18next|next-i18next|react-intl|next-translate|@lingui\/.+|typesafe-i18n|rosetta)$/
@@ -34,13 +34,13 @@ export const noMiddlewareFile = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    const name = baseName(file)
+    const file = fileOf(context)
     if (isSpecFile(file)) return {}
-    if (stem(file) === "middleware" && /(?:^|\/)src\/middleware\.[cm]?[jt]sx?$/.test(file)) {
-      return { Program: (node) => context.report({ node, messageId: "file", data: { name } }) }
+    // The retired name has a slot of its own (`fe.source-root-retired`, forbidden); the interceptor is the `proxy` role of `fe.source-root-pinned`.
+    if (inSlot(context, "fe.source-root-retired")) {
+      return { Program: (node) => context.report({ node, messageId: "file", data: { name: baseName(file) } }) }
     }
-    if (stem(file) !== "proxy" || !/(?:^|\/)src\/proxy\.[cm]?[jt]s$/.test(file)) return {}
+    if (!inSlot(context, "fe.source-root-pinned") || roleOfFile(context) !== "proxy") return {}
     const check = (node) => {
       const names = []
       const declaration = node.declaration
@@ -69,10 +69,14 @@ export const localeSegmentIsLocale = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    const match = /\/app\/(?:.*\/)?\[(lang|lng|language|i18n)\]\//.exec(file)
-    if (!match) return {}
-    return { Program: (node) => context.report({ node, messageId: "segment", data: { name: match[1] } }) }
+    // A route folder is a segment of slot `fe.route`; the locale one is `[locale]`, never another spelling.
+    if (!inSlot(context, "fe.route")) return {}
+    const hfs = hfsOf(context)
+    const file = fileOf(context)
+    const below = hfs.relative(file).slice(classOf(context).root.length + 1).split("/")
+    const name = below.slice(0, -1).map((segment) => /^\[(lang|lng|language|i18n)\]$/.exec(segment)).find(Boolean)?.[1]
+    if (!name) return {}
+    return { Program: (node) => context.report({ node, messageId: "segment", data: { name } }) }
   },
 }
 
@@ -133,9 +137,6 @@ export const htmlLangFromLocale = {
 
 // -- FE-NEXT-5 -------------------------------------------------------------------------------------
 
-/** True for a route page: a `page.tsx` anywhere under `app`. */
-const isPageFile = (file) => /\/app\/(?:.*\/)?page\.[cm]?tsx?$/.test(file)
-
 /** The names a module exports, from declarations and specifiers. */
 const exportedNames = (program) => {
   const names = new Set()
@@ -163,8 +164,8 @@ export const pageExportsMetadata = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (isSpecFile(file) || !isPageFile(file)) return {}
+    // A page is the file the slot gives the role `page` (spec files carry no role).
+    if (!inSlot(context, "fe.route") || roleOfFile(context) !== "page") return {}
     return {
       "Program:exit"(program) {
         const names = exportedNames(program)
@@ -211,9 +212,11 @@ export const noNullSuspenseFallback = {
 
 // -- FE-NEXT-7 -------------------------------------------------------------------------------------
 
-/** Files that legitimately sit outside the locale provider or own the navigation module. */
-const isNavigationOwner = (file) =>
-  /\/modules\/i18n\//.test(file) || /\/app\/global-error\.[cm]?tsx?$/.test(file) || /\/src\/proxy\.[cm]?[jt]s$/.test(file)
+/** Files that legitimately sit outside the locale provider or own the navigation module: the i18n module, the root error boundary (role `global-error`), the proxy (role `proxy`; `instrumentation` files are not exempt). */
+const isNavigationOwner = (context) =>
+  inSlot(context, "fe.modules.i18n") ||
+  (inSlot(context, "fe.source-root-pinned") && roleOfFile(context) === "proxy") ||
+  (inSlot(context, "fe.route") && roleOfFile(context) === "global-error")
 
 /** The router helpers that are locale-blind in `next/navigation`. */
 const LOCALE_BLIND = new Set(["useRouter", "usePathname", "redirect", "permanentRedirect"])
@@ -232,8 +235,7 @@ export const navigationFromIntl = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (isSpecFile(file) || isNavigationOwner(file)) return {}
+    if (isSpecFile(fileOf(context)) || isNavigationOwner(context)) return {}
     return {
       ImportDeclaration(node) {
         if (node.importKind === "type") return
@@ -292,8 +294,8 @@ const isNavigation = (name) =>
 /** True for `/x`, `/x/y`; false for `//host` and for `/` alone, which every app owns. */
 const isInternalPath = (text) => text.startsWith("/") && !text.startsWith("//") && text.length > 1
 
-/** The one place that may write a route: `modules/routes`. */
-const isRoutesModule = (file) => /\/modules\/routes\//.test(file) || /\/modules\/i18n\//.test(file)
+/** The places that may write a route: the routes module (`fe.modules.routes`) and the i18n module (`fe.modules.i18n`). */
+const isRoutesModule = (context) => inSlot(context, "fe.modules.routes", "fe.modules.i18n")
 
 /** No route written by hand outside `modules/routes`. */
 export const noHardcodedRoute = {
@@ -307,8 +309,7 @@ export const noHardcodedRoute = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (isSpecFile(file) || isRoutesModule(file)) return {}
+    if (isSpecFile(fileOf(context)) || isRoutesModule(context)) return {}
     const source = context.sourceCode ?? context.getSourceCode()
     const report = (node, text) => context.report({ node, messageId: "route", data: { path: text } })
     return {
@@ -329,6 +330,88 @@ export const noHardcodedRoute = {
   },
 }
 
+// -- FE-NEXT-10 -----------------------------------------------------------------------------------
+
+/** The next-intl stack factories: module specifier -> the export that builds one layer of the stack (`default` for a default export). */
+const STACK_FACTORIES = new Map([
+  ["next-intl/routing", new Set(["defineRouting"])],
+  ["next-intl/navigation", new Set(["createNavigation"])],
+  ["next-intl/server", new Set(["getRequestConfig"])],
+  ["next-intl/middleware", new Set(["default"])],
+])
+
+/** The variable a name binds to, walking up from the scope of a node. */
+const bindingOf = (context, identifier) => {
+  let scope = (context.sourceCode ?? context.getSourceCode()).getScope(identifier)
+  while (scope) {
+    const variable = scope.set.get(identifier.name)
+    if (variable) return variable.defs[0] ?? null
+    scope = scope.upper
+  }
+  return null
+}
+
+/** The name a stack factory has where the call reads it: "defineRouting" (next-intl/routing), else null. */
+const stackFactoryOf = (context, callee) => {
+  if (callee.type === "Identifier") {
+    const definition = bindingOf(context, callee)
+    if (definition?.type !== "ImportBinding") return null
+    const source = String(definition.parent.source.value)
+    const specifier = definition.node
+    const exported = specifier.type === "ImportSpecifier" ? specifier.imported.name ?? specifier.imported.value : specifier.type === "ImportDefaultSpecifier" ? "default" : null
+    return exported !== null && STACK_FACTORIES.get(source)?.has(exported) ? { source, name: exported === "default" ? "createMiddleware" : exported } : null
+  }
+  if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier") {
+    const definition = bindingOf(context, callee.object)
+    if (definition?.type !== "ImportBinding" || definition.node.type !== "ImportNamespaceSpecifier") return null
+    const source = String(definition.parent.source.value)
+    return STACK_FACTORIES.get(source)?.has(callee.property.name) ? { source, name: callee.property.name } : null
+  }
+  return null
+}
+
+/**
+ * The next-intl stack is written once per repository.
+ *
+ * `defineRouting` (`next-intl/routing`), `createNavigation` (`next-intl/navigation`), `getRequestConfig` (`next-intl/server`) and
+ * `createMiddleware` (`next-intl/middleware`), resolved by the import that binds the called name (a renamed import or a namespace
+ * member counts), are called only in a file of the i18n package (slot `fe.package.i18n`, `createAppI18n`), or in the `fe.modules.i18n`
+ * slot of a repository that declares exactly one app. In a multi-app repository an app's `modules/i18n` imports the package
+ * factory; three byte-identical `request.ts` files, one per app, are three stacks that drift.
+ *
+ * It does not replace `no-second-i18n-stack`: that rule refuses another i18n LIBRARY at its import, this one refuses a second copy of
+ * next-intl's own stack. Different evidence, different remedy.
+ */
+export const i18nStackInOneModule = {
+  meta: {
+    type: "problem",
+    docs: { description: "next-intl's routing, navigation, request config and middleware factories are called only in the i18n package (or the only app's `modules/i18n`)." },
+    schema: [],
+    messages: {
+      stack:
+        "`{{name}}` builds a layer of the next-intl stack here. The stack is written once per repository, {{where}}; a copy in an app is a second stack that drifts from the first (three apps once carried byte-identical `request.ts` files). Import what the shared factory returns instead of calling `{{name}}`.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    const hfs = hfsOf(context)
+    const slot = slotOfFile(context)
+    const single = hfs.apps.length === 1
+    if (slot === "fe.package.i18n" || (slot === "fe.modules.i18n" && single)) return {}
+    const proxy = single && slot === "fe.source-root-pinned" && roleOfFile(context) === "proxy"
+    const where = single ? "in the app's `modules/i18n`" : "in the i18n package (`packages/<family>-i18n`, exported as `createAppI18n`) that every app's `modules/i18n` calls"
+    return {
+      CallExpression(node) {
+        const factory = stackFactoryOf(context, node.callee)
+        // In a one-app repository the proxy (role `proxy`) mounts the locale middleware built from the one routing; a shared repository
+        // builds it in the i18n package and the proxy re-exports it.
+        if (factory?.name === "createMiddleware" && proxy) return
+        if (factory) context.report({ node, messageId: "stack", data: { name: factory.name, where } })
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "no-middleware-file": noMiddlewareFile,
@@ -340,6 +423,7 @@ export const rules = {
   "navigation-from-intl": navigationFromIntl,
   "no-native-anchor": noNativeAnchor,
   "no-hardcoded-route": noHardcodedRoute,
+  "i18n-stack-in-one-module": i18nStackInOneModule,
 }
 
 /** Every rule is an error. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "5.1.2",
+  "version": "6.0.0",
   "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": "UNLICENSED",
@@ -12,6 +12,7 @@
   "files": [
     "*.mjs",
     "lib/*.mjs",
+    "runtime/**",
     "docs/*.md",
     "*.ts",
     "!*.test.mjs",
@@ -19,11 +20,12 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=22.13.0"
   },
   "peerDependencies": {
     "eslint": ">=9",
-    "eslint-plugin-react-hooks": ">=7"
+    "eslint-plugin-react-hooks": ">=7",
+    "typescript": ">=5.9"
   },
   "publishConfig": {
     "access": "public"
@@ -36,5 +38,8 @@
     "eslintplugin",
     "starci",
     "canon"
-  ]
+  ],
+  "dependencies": {
+    "@typescript-eslint/parser": "^8.70.0"
+  }
 }

package/props-and-slots.mjs

@@ -1,7 +1,8 @@
 /** Rules for named React props, ordinary children, and local visual ownership. */
 
-const isTestFile = (filename) => /(?:^|[\\/])(?:[^\\/]+\.)?(?:spec|test)\.[cm]?[jt]sx?$/.test(String(filename || ""))
-const isComponentSource = (filename) => /(?:^|[\\/])src[\\/]components[\\/]/.test(String(filename || "").replace(/\\/g, "/"))
+import { declarationsOf, fileOf as declarationFile } from "./lib/types.mjs"
+import { fileOf, isComponentFile, isComponentPath, isProductSource, isSpecFile, kindOfFile } from "./lib/scope.mjs"
+
 const propertyName = (node) => {
   const key = node?.key ?? node?.property
   if (!key) return null
@@ -69,7 +70,7 @@ export const publicComponentSignature = {
       const actual = type?.type === "TSTypeReference" && type.typeName?.type === "Identifier" ? type.typeName.name : null
       if (!actual || !expected.includes(actual)) context.report({ node: params[0], messageId: "type", data: { name, expected: expected.join(" or ") } })
     }
-    if (!isComponentSource(context.filename || context.getFilename()) || isTestFile(context.filename || context.getFilename())) return {}
+    if (!isComponentFile(context) || isSpecFile(fileOf(context))) return {}
     return {
       VariableDeclarator(node) {
         const name = componentNameOf(node)
@@ -92,7 +93,7 @@ export const noPerPartClassNameProp = {
     messages: { perPart: "Keep internal part styling owned by the component." },
   },
   create(context) {
-    if (!isComponentSource(context.filename || context.getFilename()) || isTestFile(context.filename || context.getFilename())) return {}
+    if (!isComponentFile(context) || isSpecFile(fileOf(context))) return {}
     return { TSPropertySignature(node) { const name = propertyName(node); if (name && name !== "className" && /^[a-z][A-Za-z0-9]*ClassName$/.test(name)) context.report({ node, messageId: "perPart" }) } }
   },
 }
@@ -106,13 +107,19 @@ export const noPublicClassNameProp = {
     messages: { declaration: "Component props must not expose {{prop}}.", usage: "Do not pass {{prop}} to house component {{component}}." },
   },
   create(context) {
-    const filename = context.filename || context.getFilename()
-    if (isTestFile(filename)) return {}
-    const bindings = new Set()
+    if (isSpecFile(fileOf(context))) return {}
+    const declared = isComponentFile(context)
+    /** A house component: the identifier resolves (through its import) to a file of a component layer. */
+    const isHouseComponent = (identifier) => declarationsOf(context, identifier).some((declaration) => isComponentPath(context, declarationFile(declaration)))
     return {
-      ImportDeclaration(node) { if (!/components\//.test(String(node.source?.value || ""))) return; for (const specifier of node.specifiers || []) if (specifier.local?.name) bindings.add(specifier.local.name) },
-      TSPropertySignature(node) { if (isComponentSource(filename) && ["className", "classNames"].includes(propertyName(node))) context.report({ node, messageId: "declaration", data: { prop: propertyName(node) } }) },
-      JSXOpeningElement(node) { const component = node.name?.type === "JSXIdentifier" ? node.name.name : null; if (!component || !bindings.has(component)) return; for (const attribute of node.attributes || []) { const prop = attribute.name?.type === "JSXIdentifier" ? attribute.name.name : null; if (["className", "classNames"].includes(prop)) context.report({ node: attribute, messageId: "usage", data: { prop, component } }) } },
+      TSPropertySignature(node) { if (declared && ["className", "classNames"].includes(propertyName(node))) context.report({ node, messageId: "declaration", data: { prop: propertyName(node) } }) },
+      JSXOpeningElement(node) {
+        const identifier = node.name?.type === "JSXIdentifier" ? node.name : null
+        if (!identifier) return
+        const styled = (node.attributes || []).filter((attribute) => ["className", "classNames"].includes(attribute.name?.type === "JSXIdentifier" ? attribute.name.name : null))
+        if (styled.length === 0 || !isHouseComponent(identifier)) return
+        for (const attribute of styled) context.report({ node: attribute, messageId: "usage", data: { prop: attribute.name.name, component: identifier.name } })
+      },
     }
   },
 }
@@ -121,8 +128,7 @@ export const noPublicClassNameProp = {
 export const noPublicFrameCssProps = {
   meta: { type: "problem", docs: { description: "Non-leaf component props do not expose CSS-shaped frame decisions." }, schema: [], messages: { css: "Move {{prop}} into component-owned layout behavior." } },
   create(context) {
-    const filename = context.filename || context.getFilename()
-    if (isTestFile(filename) || !isComponentSource(filename) || /[\\/]leaves[\\/]/.test(String(filename).replace(/\\/g, "/"))) return {}
+    if (isSpecFile(fileOf(context)) || !isComponentFile(context) || kindOfFile(context) === "leaves") return {}
     const cssProps = new Set(["gap", "padding", "align", "justify", "className", "classNames", "style", "inline", "nested"])
     return { TSPropertySignature(node) { const name = propertyName(node); if (cssProps.has(name)) context.report({ node, messageId: "css", data: { prop: name } }) } }
   },
@@ -132,7 +138,7 @@ export const noPublicFrameCssProps = {
 export const noCssDoorTypeLaundering = {
   meta: { type: "problem", docs: { description: "Omit, Pick, and Exclude cannot hide styling props." }, schema: [], messages: { utility: "Remove {{prop}} from the owning public type instead of hiding it with {{utility}}." } },
   create(context) {
-    if (!String(context.filename || context.getFilename()).replace(/\\/g, "/").includes("/src/")) return {}
+    if (!isProductSource(context)) return {}
     return { TSTypeReference(node) { const utility = node.typeName?.type === "Identifier" ? node.typeName.name : null; const params = node.typeArguments?.params || node.typeParameters?.params || []; if (!utility || !["Omit", "Pick", "Exclude"].includes(utility)) return; const keys = params[1]?.type === "TSLiteralType" ? [params[1].literal?.value] : params[1]?.types?.map((item) => item.literal?.value) || []; const prop = keys.find((key) => ["className", "classNames", "style"].includes(key)); if (prop) context.report({ node, messageId: "utility", data: { utility, prop } }) } }
   },
 }

package/runtime/engine/plain-object.mjs

@@ -0,0 +1,5 @@
+// plain-object.mjs — the one "is this a non-array object" predicate the runtime asks with.
+// A leaf beside digest.mjs: schema walkers, config readers and JSON consumers all mean the
+// same thing by "a mapping" - own object, never null, never an array - so they share it here.
+/** True for a non-null, non-array object. Does not check the prototype (a JSON.parse result). */
+export const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);

package/runtime/engine/runtime-root.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parseYaml} from './yaml.mjs';
+
+/**
+ * Runtime root helper. The runtime reads this source tree directly. `skillRoot` is the
+ * directory containing `package.json` (this module's parent) — the checkout, or the copy of it
+ * an install placed on the host.
+ *
+ * Every workflow, op, schema, knowledge and model contract read at runtime is an authored YAML
+ * file (or an authored JSON one where a document is stored that way). `readModuleJson` resolves a
+ * path under `skillRoot` and parses the file by its extension.
+ */
+const moduleRoot = path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+
+/** The runtime root: this source tree (or an immutable sealed payload of it). */
+export const skillRoot = moduleRoot;
+
+/**
+ * Read a runtime contract document. `parts` are path segments under `skillRoot`
+ * (e.g. readModuleJson('modules', 'models', 'kinds.yaml')).
+ */
+export function readModuleJson(...parts) {
+  const rel = parts.join('/');
+  const file = path.join(skillRoot, rel);
+  if (!(file.startsWith(skillRoot) && fs.existsSync(file) && fs.statSync(file).isFile()))
+    throw new Error(`Required contract not found for ${rel} under ${skillRoot}`);
+  const text = fs.readFileSync(file, 'utf8');
+  if (/\.ya?ml$/i.test(file)) return parseYaml(text);
+  return JSON.parse(text);
+}