@starci/eslint-canon-fe 1.0.0

package/lint-adoption.mjs

@@ -0,0 +1,116 @@
+/**
+ * Repository-level audit for effective StarCi FE lint adoption.
+ *
+ * An ESLint config can import a plugin, copy a plugin, or call itself StarCi while still leaving
+ * canonical rules switched off. The only useful evidence is the effective config ESLint applies
+ * to a real production file. This audit compares that printed config with this canon.
+ */
+/**
+ * Where the component tree sits, per supported repository shape.
+ *
+ * ONE BRANCH, IN ONE PLACE. The difference between a monorepo and a single app is not a difference
+ * of law - the rules, their severities and the inline-config refusal are identical. It is only
+ * WHERE the law applies. Written out in each repository's config, that fact became two hand-kept
+ * lists, and the lists did what hand-kept lists do: one enabled 43 rules, the other 53, and canon
+ * had 49. Neither repository was wrong on purpose; nothing told either of them.
+ *
+ * The candidate path is included deliberately. A Preview candidate is the exact source Apply later
+ * ports into production, and leaving it ungoverned means the one file that becomes production was
+ * judged by nothing.
+ */
+const LAYOUT_GLOBS = {
+    monorepo: [
+        "packages/ui/src/**/*.{ts,tsx}",
+        "apps/*/src/**/*.{ts,tsx}",
+        "**/candidate/src/**/*.{ts,tsx}",
+    ],
+    "single-app": [
+        "src/**/*.{ts,tsx}",
+        "**/candidate/src/**/*.{ts,tsx}",
+    ],
+}
+
+/** The repository shapes this canon knows how to govern. */
+export const LAYOUTS = Object.keys(LAYOUT_GLOBS)
+
+/**
+ * The one flat-config block that attaches this canon to a repository.
+ *
+ * A consuming `eslint.config.mjs` spreads the result and owns nothing else about the rules: not
+ * which are on, not their severity, not whether an inline comment may switch one off. Its own
+ * plugins, its own ignores and its own 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.
+ * @param {object} input.plugin - The plugin object, imported from this canon.
+ * @param {object} input.recommended - The recommendation, imported from this canon.
+ * @param {object} input.linterOptions - The linter options, imported from this canon.
+ * @returns {object} One flat-config block.
+ */
+export const starciFeConfig = ({ layout, plugin, recommended, linterOptions }) => {
+    const files = LAYOUT_GLOBS[layout]
+    if (!files) {
+        throw new Error(`unknown layout "${layout}" - expected one of: ${LAYOUTS.join(", ")}`)
+    }
+    /*
+     * `recommended` is a FLAT rule map here, not a config object with a `rules` key - and reaching
+     * for `.rules` on it is the mistake this line exists to stop repeating. Spread that way it
+     * yields `undefined`, the block ends up with zero rules, and the repository lints clean while
+     * being governed by nothing. That is the worst possible failure for this file: green, silent,
+     * and indistinguishable from success. Both spellings are accepted so neither shape can produce
+     * an empty block.
+     */
+    const rules = recommended?.rules ?? recommended
+    if (!rules || Object.keys(rules).length === 0) {
+        throw new Error("starciFeConfig received an empty recommendation - a config with no rules is not adoption")
+    }
+    return {
+        files,
+        linterOptions,
+        plugins: { "starci-fe": plugin },
+        rules: { ...rules },
+    }
+}
+
+/** Convert every flat-config severity spelling to its numeric meaning. */
+const severityOf = (setting) => {
+  const severity = Array.isArray(setting) ? setting[0] : setting
+  if (severity === "error") return 2
+  if (severity === "warn") return 1
+  if (severity === "off") return 0
+  return severity
+}
+
+/**
+ * Compare an `eslint --print-config` result with the canonical recommendation.
+ *
+ * @param {object} printedConfig - Parsed effective ESLint config for one production probe file.
+ * @param {Record<string, string | number | unknown[]>} expectedRules - Canonical rule levels.
+ */
+export const auditLintAdoption = (printedConfig, expectedRules) => {
+  const actualRules = printedConfig?.rules ?? {}
+  const missing = []
+  const nonError = []
+
+  for (const name of Object.keys(expectedRules).sort()) {
+    if (actualRules[name] === undefined) {
+      missing.push(name)
+      continue
+    }
+    if (severityOf(actualRules[name]) !== 2) nonError.push(name)
+  }
+
+  const refusesInlineConfig = printedConfig?.linterOptions?.noInlineConfig === true
+  return {
+    ok: missing.length === 0 && nonError.length === 0 && refusesInlineConfig,
+    missing,
+    nonError,
+    refusesInlineConfig,
+  }
+}
+
+/** Repository audits are gathered beside rules, but are not ESLint AST rules themselves. */
+export const audits = { "effective-config": auditLintAdoption }
+export const rules = {}
+export const recommended = {}

package/lint-escape-hatch.mjs

@@ -0,0 +1,56 @@
+/** The rule and flat-config fence that hold `lint-escape-hatch.md`. */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** Product source is governed; canon tests deliberately construct forbidden directives. */
+const isProductSource = (filename) => normalizePath(filename).includes("/src/")
+
+/**
+ * Any directive that changes ESLint's active rule set inside a source file.
+ *
+ * ANCHORED AT THE START OF THE COMMENT, because that is the only place ESLint itself honours one:
+ * a directive is recognised from the first non-space character of the comment body and nowhere else.
+ * An unanchored pattern matched the WORD instead of the directive, so a comment explaining why a
+ * file carries no `eslint-disable` was reported as carrying one - and the only way to silence that
+ * was to stop writing the explanation, which is the opposite of what this law wants. Under-catching
+ * is not the trade: a directive ESLint would obey always sits at the start.
+ */
+const INLINE_DIRECTIVE = /^\s*eslint-(?:disable(?:-next-line|-line)?|enable)\b/
+
+/** Inline lint configuration is repository policy, never a file-local choice. */
+export const noInlineLintConfig = {
+  meta: {
+    type: "problem",
+    docs: { description: "Product source cannot change its own ESLint policy." },
+    schema: [],
+    messages: {
+      directive:
+        "Inline ESLint configuration makes this file the author of whether repository law applies. Remove the directive and fix the code or the shared rule; there is no local exception path.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    return {
+      Program() {
+        for (const comment of source.getAllComments()) {
+          if (INLINE_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "directive" })
+        }
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-inline-lint-config": noInlineLintConfig,
+}
+
+/** Every lint escape is a build error. */
+export const recommended = {
+  "starci-fe/no-inline-lint-config": "error",
+}
+
+/** Consuming flat configs apply this beside the recommended rules. */
+export const linterOptions = Object.freeze({ noInlineConfig: true })

package/loading.mjs

@@ -0,0 +1,164 @@
+/**
+ * The rules that hold `loading.md`.
+ *
+ * Three shapes of the same mistake: a second tree describing the first. A twin component, a
+ * ready-made placeholder handed in as a prop, and a ternary picking between two different
+ * components at a call site. Each is correct on the day it is written and wrong the first time the
+ * real shape changes.
+ *
+ * WHY THIS NEEDS RULES AT ALL, when so much of this canon is held by types. A resting shape has no
+ * assertion to fail: it is not wrong in a way a compiler or a test can see, it is wrong on screen,
+ * and only for the second somebody happens to be watching. That is exactly the class of defect a
+ * lint rule is for - the one nothing else will ever report.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The component tree; a placeholder in a test fixture is a fixture, not a second tree. */
+const isComponentFile = (filename) => normalizePath(filename).includes("/src/components/")
+
+/** A twin test may build a resting shape by hand to assert against it. */
+const isTestFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx)$/.test(normalizePath(filename))
+
+/** Product component source these rules govern. */
+const isGoverned = (filename) => isComponentFile(filename) && !isTestFile(filename)
+
+/** A flag that means "waiting", in the spellings this codebase uses. */
+const WAITING_FLAG = /\bis(?:Loading|Skeleton|Pending)\b/
+
+/** The name of a component whose whole job is to mirror another one's shape. */
+const TWIN_NAME = /^[A-Za-z0-9]*Skeleton$/
+
+/** JSX element name, including `Foo.Bar`. */
+const jsxElementName = (opening) => {
+  const name = opening && opening.name
+  if (!name) return null
+  if (name.type === "JSXIdentifier") return name.name
+  if (name.type === "JSXMemberExpression" && name.object && name.property) {
+    return `${name.object.name}.${name.property.name}`
+  }
+  return null
+}
+
+// -- LOADING-1 -------------------------------------------------------------------------------------
+
+/** No component exists whose job is to mirror another component's shape. */
+export const noRestingTwinComponent = {
+  meta: {
+    type: "problem",
+    docs: { description: "No component whose whole job is to mirror another one's shape." },
+    schema: [],
+    messages: {
+      twin:
+        "`{{name}}` is a hand-mirrored twin: a second description of a shape that already has one. It cannot be kept in step - it can only be noticed after it has already drifted, and a resting shape has no assertion to fail, so nothing will report the drift. Give the component it mirrors a resting state and let it rest as ITSELF.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isGoverned(file)) return {}
+    const hit = file.match(/\/([A-Za-z0-9]*Skeleton)\/index\.tsx?$/) || file.match(/\/([A-Za-z0-9]*Skeleton)\.tsx?$/)
+    if (!hit || !TWIN_NAME.test(hit[1])) return {}
+    return {
+      Program(node) {
+        context.report({ node, messageId: "twin", data: { name: hit[1] } })
+      },
+    }
+  },
+}
+
+// -- LOADING-1, handed in from outside --------------------------------------------------------------
+
+/** A ready-made placeholder is the same second tree, passed as a prop. */
+export const noPlaceholderProp = {
+  meta: {
+    type: "problem",
+    docs: { description: "No prop hands a component a ready-made resting shape to render." },
+    schema: [],
+    messages: {
+      prop:
+        "A resting shape handed in as markup is a second description of a tree that already has one, and it sits further from the shape it copies than a twin does - the component it describes cannot even see it. Pass the waiting flag down instead, and let each part rest as itself.",
+      import:
+        "`{{name}}` is a hand-kept resting tree imported from beside its subject. It drifts the first time the real shape changes, and nothing reports it. Thread the waiting flag down instead.",
+    },
+  },
+  create(context) {
+    if (!isGoverned(context.filename || context.getFilename())) return {}
+    return {
+      JSXAttribute(node) {
+        const name = node.name && node.name.type === "JSXIdentifier" ? node.name.name : null
+        if (name !== "skeleton" && name !== "placeholder" && name !== "fallback") return
+        const value = node.value
+        if (!value || value.type !== "JSXExpressionContainer") return
+        const expression = value.expression
+        if (expression.type === "JSXElement" || expression.type === "JSXFragment") {
+          context.report({ node, messageId: "prop" })
+        }
+      },
+      ImportDeclaration(node) {
+        const source = node.source && node.source.value
+        if (typeof source !== "string" || !/^\.\.?\//.test(source)) return
+        for (const specifier of node.specifiers || []) {
+          const local = specifier.local && specifier.local.name
+          // A bare `Skeleton` is the primitive a component rests WITH, not a twin of one.
+          if (!local || local === "Skeleton" || !TWIN_NAME.test(local)) continue
+          context.report({ node: specifier, messageId: "import", data: { name: local } })
+        }
+      },
+    }
+  },
+}
+
+// -- LOADING-2 -------------------------------------------------------------------------------------
+
+/** A caller never picks between a resting shape and a real one. */
+export const noRestingBranchAtCallSite = {
+  meta: {
+    type: "problem",
+    docs: { description: "A waiting flag must not choose between two different components." },
+    schema: [],
+    messages: {
+      branch:
+        "`{{flag}}` picks between two DIFFERENT elements, which is a resting shape written at the call site - and it drifts from the real one the first time the real one changes. Give the component below a waiting flag and pass it down; let it rest as ITSELF. The same component on both sides is the honest form: one description, two states.",
+    },
+  },
+  create(context) {
+    if (!isGoverned(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    /** Root element name of one arm, or null when the arm is not an element. */
+    const armName = (expression) => {
+      if (!expression) return null
+      if (expression.type === "JSXElement") return jsxElementName(expression.openingElement)
+      if (expression.type === "JSXFragment") return "<>"
+      return null
+    }
+    return {
+      ConditionalExpression(node) {
+        const test = source.getText(node.test)
+        if (!WAITING_FLAG.test(test)) return
+        const left = armName(node.consequent)
+        const right = armName(node.alternate)
+        // Both arms must be real elements AND differ. `null` on one side is LOADING-5 - a control
+        // that has nowhere to go yet - and that is correct rather than a second tree.
+        if (!left || !right || left === right) return
+        context.report({ node, messageId: "branch", data: { flag: test.trim().slice(0, 40) } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-resting-twin-component": noRestingTwinComponent,
+  "no-placeholder-prop": noPlaceholderProp,
+  "no-resting-branch-at-call-site": noRestingBranchAtCallSite,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * A repository adopting these with history should expect the twin rule to report a folder at a
+ * time: hand-kept placeholder trees arrive in families, one per screen, and each is a real shape
+ * that has to be folded back into the component it copies rather than deleted.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/naming.mjs

@@ -0,0 +1,150 @@
+/**
+ * The rules that hold `naming.md`.
+ *
+ * Two spellings, both of which work, which is exactly why they are rules: nothing corrects the
+ * second one, so a file written on a Tuesday reads differently from its neighbour and every diff
+ * afterwards carries noise that has nothing to do with the change.
+ *
+ * Neither rule can see intent, and both are deliberately narrow because of it. NAMING-1 fires on
+ * shape alone - a module-level `function` - which is exact. NAMING-2 fires on the `handle` prefix
+ * alone, which catches the rename-at-the-boundary case and nothing else; a name that merely
+ * describes an action is not its business.
+ */
+
+/** Parents that make a function declaration module-level rather than nested. */
+const MODULE_LEVEL_PARENTS = new Set(["Program", "ExportNamedDeclaration", "ExportDefaultDeclaration"])
+
+// -- NAMING-1 --------------------------------------------------------------------------------------
+
+/** A module-level function is an arrow const, so nothing exists before the line that declares it. */
+export const preferArrowExport = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Module-level functions use an arrow const, not a `function` declaration." },
+    schema: [],
+    messages: {
+      fn: "`function {{name}}` is hoisted, so it exists before the line that declares it and the order of this file stops promising anything about what is defined when. Write `const {{name}} = (...) => {...}` - a const cannot be used before it exists, so the file reads in the order it runs.",
+    },
+  },
+  create(context) {
+    return {
+      FunctionDeclaration(node) {
+        const parent = node.parent && node.parent.type
+        if (!MODULE_LEVEL_PARENTS.has(parent)) return
+        context.report({
+          node: node.id || node,
+          messageId: "fn",
+          data: { name: (node.id && node.id.name) || "default" },
+        })
+      },
+    }
+  },
+}
+
+// -- NAMING-2 --------------------------------------------------------------------------------------
+
+/** Something a reader triggers is named `onX`, so the name survives being passed. */
+export const handlerOnPrefix = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Handlers are named `onX`, not `handleX`." },
+    schema: [],
+    messages: {
+      handle: "`{{name}}` is renamed at every boundary it crosses - the slot is `on`, the DOM attribute is `onClick`, and the props type says `on{{rest}}`. Call it `on{{rest}}` at birth and the name is the same at the declaration, at the call site and in the type.",
+    },
+  },
+  create(context) {
+    const flag = (node, name) => {
+      if (!name || !/^handle[A-Z]/.test(name)) return
+      context.report({ node, messageId: "handle", data: { name, rest: name.slice("handle".length) } })
+    }
+    return {
+      VariableDeclarator(node) {
+        if (node.id && node.id.type === "Identifier") flag(node.id, node.id.name)
+      },
+      JSXAttribute(node) {
+        if (node.name) flag(node.name, node.name.name)
+      },
+      TSPropertySignature(node) {
+        if (node.key && node.key.type === "Identifier") flag(node.key, node.key.name)
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+// -- NAMING-3 --------------------------------------------------------------------------------------
+
+/** Letters that exist in Vietnamese and not in English, in the forms a path can carry. */
+const SECOND_LANGUAGE_PATH = /[àáâãèéêìíòóôõùúýăđĩũơưạảấầẩẫậắằẳẵặẹẻẽếềểễệỉịọỏốồổỗộớờởỡợụủứừửữựỳỵỷỹ]/i
+
+/**
+ * Second-language words spelled in ASCII, as a route or folder segment writes them.
+ *
+ * A path cannot carry diacritics, so `cấp phát` reaches the filesystem as `cap-phat` and every
+ * accent-based check passes it. The segments below are the ones this product actually produced.
+ * A list is the honest instrument here: guessing at Vietnamese-shaped ASCII would refuse `dang`
+ * in `dangerous` and `cap` in `capacity`, and a rule that fires on English words is one a
+ * repository turns off.
+ */
+const ROMANISED = [
+  "dang-nhap", "dang-ky", "dang-xuat", "cap-phat", "khoa-hoc", "hoc-vien", "gioi-thieu",
+  "lien-he", "tai-khoan", "thanh-toan", "gio-hang", "tin-tuc", "san-pham", "bang-gia",
+  "dieu-khoan", "chinh-sach", "trang-chu", "quan-ly", "cai-dat", "ho-so",
+]
+
+/** A route segment or folder name, lowercased, from a normalized path. */
+const segmentsOf = (filename) =>
+  String(filename || "").replace(/\\/g, "/").toLowerCase().split("/").filter(Boolean)
+
+/**
+ * A path names things in one language: the one every reader of this repository shares.
+ *
+ * WHY A PATH AND NOT ONLY THE SOURCE. `no-second-language-in-source` reads identifiers, comments
+ * and strings, and cannot see the file it is reading. So a route could be `app/cap-phat/page.tsx`
+ * with every identifier inside it in English, and nothing said a word - while the URL, the import
+ * specifier, the folder in every editor sidebar and the path in every stack trace stayed in a
+ * language half the readers do not have.
+ *
+ * A ROUTE SEGMENT IS ALSO A PUBLIC NAME. It is the address a customer sees and a support ticket
+ * quotes, so this is not only an authoring question: the product's own URLs stop being readable to
+ * anybody outside one language.
+ */
+export const noSecondLanguageInPath = {
+  meta: {
+    type: "problem",
+    docs: { description: "File and route names are written in the repository's one shared language." },
+    schema: [],
+    messages: {
+      path:
+        "`{{segment}}` names this file in a second language. A path is read by more people than the code inside it - it is the URL a customer quotes, the folder every editor shows, and the specifier every import repeats - and unlike a comment it cannot be skimmed past. Rename the segment; the words a person READS belong in the locale catalogue, never in the address.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const offending = segmentsOf(filename).find(
+      (segment) => SECOND_LANGUAGE_PATH.test(segment) || ROMANISED.includes(segment.replace(/[()[\]]/g, "")),
+    )
+    if (!offending) return {}
+    return {
+      Program(node) {
+        context.report({ node, messageId: "path", data: { segment: offending } })
+      },
+    }
+  },
+}
+
+export const rules = {
+  "prefer-arrow-export": preferArrowExport,
+  "handler-on-prefix": handlerOnPrefix,
+  "no-second-language-in-path": noSecondLanguageInPath,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * A consuming repository's `eslint.config.mjs` stays the authority on what is actually switched on.
+ * Both rules here are mechanical and auto-correctable by hand in seconds, so a repository adopting
+ * them with existing debt should burn the count down rather than live at `warn`.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@starci/eslint-canon-fe",
+  "version": "1.0.0",
+  "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "exports": {
+    ".": "./index.mjs",
+    "./contracts": "./contracts.ts",
+    "./props": "./props.ts"
+  },
+  "main": "./index.mjs",
+  "files": [
+    "*.mjs",
+    "*.ts",
+    "!*.test.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"*.test.mjs\""
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "starci",
+    "canon"
+  ]
+}