@mslmio/eslint-config 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mslm Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @mslmio/eslint-config
+
+Shareable ESLint **flat config** plus a small plugin of house rules — the kind of convention
+teams write down and then enforce with nothing.
+
+```sh
+pnpm add -D @mslmio/eslint-config eslint
+```
+
+## Use it
+
+```js
+// A backend service or a non-UI library - installs no Tailwind/React tooling.
+import { lib, typeChecked } from "@mslmio/eslint-config";
+export default [...lib, typeChecked(import.meta.dirname)];
+
+// Anything rendering Tailwind. Needs @shadcn/lint (and eslint-plugin-react-hooks
+// for uiLib) installed alongside - both are OPTIONAL peers.
+import { uiLib } from "@mslmio/eslint-config/ui";
+export default [...uiLib];
+```
+
+**Two entry points on purpose.** A backend service has no Tailwind and no React, so keeping the
+UI half behind `/ui` means the root entry resolves neither `@shadcn/lint` nor
+`eslint-plugin-react-hooks`, nor `oxc-parser`'s native binaries.
+
+| Preset | For | Adds |
+|---|---|---|
+| `house` | anything TS/JS | `no-property-shorthand`, `curly: all`, `us-spelling`, `no-express-json-spaces` |
+| `lib` | a published library | house + `no-lib-process-env`, `no-module-scope-init` |
+| `ui` | anything rendering Tailwind | house + `require-leading-with-text-size`, `prefer-copy-icon` |
+| `uiLib` | a published UI library | `lib` + `ui` |
+
+## Rules
+
+| Rule | What it says |
+|---|---|
+| `no-upward-import` | A package may not import a tier above it, or a sibling leaf. Off until configured — see below |
+| `no-property-shorthand` | Always `{ key: key }`; exempts destructuring and imports |
+| `no-lib-process-env` | A library never reads `process.env` — configuration is passed in |
+| `no-module-scope-init` | No client/config built at module scope; build lazily and memoise |
+| `no-express-json-spaces` | Express's `json spaces` indents but drops the trailing newline |
+| `prefer-copy-icon` | lucide `Copy`, not `Clipboard` |
+| `us-spelling` | US spelling in prose and identifiers |
+| `require-leading-with-text-size` | An arbitrary Tailwind text size must state its own line height |
+
+`us-spelling` skips regex literals — a pattern matching scraped text has to accept both
+spellings — and takes `allow` for proper names that keep their own:
+`["mslmio/us-spelling", "error", { allow: ["Macquarie Data Centres"] }]`.
+
+`no-lib-process-env` exempts `main.*` by default: a runnable entry point living in a library
+directory IS the service. Override with `{ entryPoints: [...] }`.
+
+Every rule that explains itself takes an optional `docsUrl`, appended to the message so you can
+point at your own write-up: `["mslmio/no-lib-process-env", "error", { docsUrl: "https://..." }]`.
+
+## `no-upward-import`
+
+A workspace layered into **ordered tiers** plus any number of **leaves**. A tier may import the
+tiers below it; a leaf may import every tier but no other leaf. Nothing reaches up.
+
+```js
+["mslmio/no-upward-import", "error", {
+    tiers: ["base", "platform"],   // ordered, lowest first
+    exempt: ["tools"],             // outside the layering entirely
+    typeDirs: ["svc", "lib", "web"],
+    docsUrl: "https://example.com/layering",
+}]
+```
+
+**It is a no-op until `tiers` is set**, which is the default. The leaves are *discovered* from the
+workspace root — the directory holding every tier as a child — rather than listed: any other child
+containing one of `typeDirs` is a leaf. So adding a leaf needs no config change, and no package has
+to hold a list of its siblings.
+
+## Ignores
+
+`house`, and so every preset, globally ignores `.design-sync/**`, `.ds-sync/**` and
+`ds-bundle/**`. Flat config does not read `.gitignore`, and these hold symlinks into app
+components — one moved component leaves a dangling link and `eslint .` exits `ENOENT` instead of
+reporting anything.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,135 @@
+import plugin from "./plugin.js";
+import tsParser from "@typescript-eslint/parser";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+
+const TS_GLOBS = ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.js", "**/*.mjs"];
+
+// design-sync scratch and its generated bundle. All three are gitignored, and `ds-src` holds
+// symlinks that dangle the moment a component moves - which makes `eslint .` exit on ENOENT
+// rather than report. Flat config does not read .gitignore, so every consumer needs this.
+export const designSyncIgnores = {
+    ignores: [".design-sync/**", ".ds-sync/**", "ds-bundle/**"],
+};
+
+// The @typescript-eslint rule set. Without this the parser parses TypeScript and
+// NOTHING lints it - no unused vars, no floating promises, no unsafe any. The rules
+// go in `house` (so every consumer gets them) while the PARSER stays out of it, since
+// a Next app already has one and flat config is last-wins.
+// The `plugins` key is stripped on purpose. A flat-config plugin namespace may be
+// declared only ONCE across the whole array, and eslint-config-next already declares
+// `@typescript-eslint`; redeclaring it fails the whole run with "Cannot redefine
+// plugin". Rules resolve against whichever config declared the namespace - next's in
+// an app, the `typescript` config below in a standalone package.
+export const typescriptRules = (tsPlugin.configs["flat/recommended"] ?? []).map((c) => {
+    const { plugins: _plugins, ...rest } = c;
+    return { ...rest, files: ["**/*.ts", "**/*.tsx", "**/*.mts"] };
+});
+
+// Scoped to TS files, not folded into `house`: `house` also matches .js/.mjs, where
+// the @typescript-eslint namespace is not declared and naming one of its rules fails
+// the whole run. A leading underscore is how you say "deliberately discarded".
+typescriptRules.push({
+    files: ["**/*.ts", "**/*.tsx", "**/*.mts"],
+    rules: {
+        "@typescript-eslint/no-unused-vars": ["error", {
+            argsIgnorePattern: "^_",
+            varsIgnorePattern: "^_",
+            caughtErrorsIgnorePattern: "^_",
+            destructuredArrayIgnorePattern: "^_",
+        }],
+    },
+});
+
+// Every rule here encodes a documented house rule. Adding one means editing
+export const house = [
+    designSyncIgnores,
+    ...typescriptRules,
+    {
+        files: TS_GLOBS,
+        plugins: { mslmio: plugin },
+        rules: {
+            "mslmio/no-property-shorthand": "error",
+            curly: ["error", "all"],
+            "mslmio/us-spelling": "error",
+            "mslmio/no-express-json-spaces": "error",
+            "mslmio/no-upward-import": "error",
+        },
+    },
+];
+
+// A parser for `.ts`/`.tsx`, for a package that has no framework config supplying one.
+// Deliberately NOT in `house`/`ui`: a Next app gets its parser from eslint-config-next,
+// and flat config is last-wins, so adding one here would silently replace theirs.
+export const typescript = {
+    files: ["**/*.ts", "**/*.tsx", "**/*.mts"],
+    plugins: { "@typescript-eslint": tsPlugin },
+    languageOptions: {
+        parser: tsParser,
+        parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+};
+
+// Type-aware rules, opt-in per package because they need that package's tsconfig.
+//
+//   import { uiLib, typeChecked } from "@mslmio/eslint-config";
+//   export default [...uiLib, typeChecked(import.meta.dirname)];
+//
+// Deliberately NOT the full `recommended-type-checked`: the no-unsafe-* family reports
+// every read off an `any`, which on a codebase with untyped edges is thousands of hits
+// that bury these four. These catch real bugs - an un-awaited promise silently does
+// nothing, and a promise in a boolean position is always truthy.
+export function typeChecked(tsconfigRootDir, extraProjectOptions = {}) {
+    return {
+        files: ["**/*.ts", "**/*.tsx", "**/*.mts"],
+        // Type-aware rules need the file to be in a tsconfig project. Tests and tool
+        // configs are routinely NOT - a separate tsconfig.test.json, or nothing at all -
+        // and the parser then fails the file outright rather than skipping it.
+        // `allowDefaultProject` is not the answer: it errors the other way round for a
+        // package whose tests ARE in the project, so it cannot be a shared default.
+        // They still get every non-type-aware rule from `typescript`.
+        ignores: ["**/*.test.ts", "**/*.test.tsx", "**/*.config.ts", "**/*.config.mts", "**/*.config.js"],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                projectService: true,
+                tsconfigRootDir: tsconfigRootDir,
+                ...extraProjectOptions,
+            },
+        },
+        rules: {
+            "@typescript-eslint/no-floating-promises": "error",
+            "@typescript-eslint/no-misused-promises": "error",
+            "@typescript-eslint/await-thenable": "error",
+            "@typescript-eslint/require-await": "warn",
+        },
+    };
+}
+
+// A runnable service. Reads process.env and builds clients at startup by design, so
+// it gets the house rules and a parser but NOT the library-only bans.
+export const svc = [
+    typescript,
+    ...house,
+];
+
+export const lib = [
+    typescript,
+    ...house,
+    {
+        files: TS_GLOBS,
+        rules: {
+            "mslmio/no-lib-process-env": "error",
+            "mslmio/no-module-scope-init": "error",
+        },
+    },
+];
+
+export default {
+    house: house,
+    svc: svc,
+    lib: lib,
+    typescript: typescript,
+    typescriptRules: typescriptRules,
+    typeChecked: typeChecked,
+    plugin: plugin,
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+    "name": "@mslmio/eslint-config",
+    "version": "1.0.0",
+    "description": "Shareable ESLint flat config and house rules: US spelling, library hygiene, workspace layering, and Tailwind/React conventions.",
+    "keywords": [
+        "eslint",
+        "eslintconfig",
+        "eslint-config",
+        "eslint-plugin",
+        "flat-config",
+        "typescript",
+        "monorepo",
+        "layering",
+        "tailwind",
+        "react"
+    ],
+    "license": "MIT",
+    "homepage": "https://github.com/mslmio/eslint-config",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mslmio/eslint-config.git"
+    },
+    "bugs": {
+        "url": "https://github.com/mslmio/eslint-config/issues"
+    },
+    "type": "module",
+    "packageManager": "pnpm@11.1.0",
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "exports": {
+        ".": "./index.js",
+        "./ui": "./ui.js",
+        "./plugin": "./plugin.js"
+    },
+    "files": [
+        "index.js",
+        "ui.js",
+        "plugin.js",
+        "rules/*.js",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "test": "node --test test/*.test.js",
+        "pub-dryrun": "pnpm run lint && pnpm publish --no-git-checks --dry-run",
+        "pub": "pnpm run lint && pnpm publish --no-git-checks",
+        "lint": "eslint"
+    },
+    "peerDependencies": {
+        "eslint": ">=9.30.0",
+        "@shadcn/lint": "^0.1.0",
+        "eslint-plugin-react-hooks": "^5.2.0"
+    },
+    "peerDependenciesMeta": {
+        "@shadcn/lint": {
+            "optional": true
+        },
+        "eslint-plugin-react-hooks": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "@typescript-eslint/eslint-plugin": "8.70.0",
+        "@typescript-eslint/parser": "8.70.0"
+    },
+    "devDependencies": {
+        "eslint": "^9.39.4",
+        "@shadcn/lint": "0.1.0",
+        "eslint-plugin-react-hooks": "^5.2.0"
+    }
+}

package/plugin.js

@@ -0,0 +1,22 @@
+import noLibProcessEnv from "./rules/no-lib-process-env.js";
+import noModuleScopeInit from "./rules/no-module-scope-init.js";
+import noExpressJsonSpaces from "./rules/no-express-json-spaces.js";
+import preferCopyIcon from "./rules/prefer-copy-icon.js";
+import usSpelling from "./rules/us-spelling.js";
+import requireLeadingWithTextSize from "./rules/require-leading-with-text-size.js";
+import noPropertyShorthand from "./rules/no-property-shorthand.js";
+import noUpwardImport from "./rules/no-upward-import.js";
+
+export default {
+    meta: { name: "@mslmio/eslint-plugin", version: "2.4.0" },
+    rules: {
+        "no-lib-process-env": noLibProcessEnv,
+        "no-module-scope-init": noModuleScopeInit,
+        "no-express-json-spaces": noExpressJsonSpaces,
+        "prefer-copy-icon": preferCopyIcon,
+        "us-spelling": usSpelling,
+        "require-leading-with-text-size": requireLeadingWithTextSize,
+        "no-property-shorthand": noPropertyShorthand,
+        "no-upward-import": noUpwardImport,
+    },
+};

package/rules/no-express-json-spaces.js

@@ -0,0 +1,32 @@
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description:
+                "Use the prettyJson middleware, not express's `json spaces`, which omits the trailing newline",
+        },
+        schema: [],
+        messages: {
+            jsonSpaces:
+                "`app.set('json spaces', ...)` indents but omits the trailing newline that keeps a shell " +
+                "prompt off the closing brace. Use a pretty-print middleware that emits one.",
+        },
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (node.callee?.type !== "MemberExpression") {
+                    return;
+                }
+                if (node.callee.property?.name !== "set" || node.arguments.length !== 2) {
+                    return;
+                }
+                const [key] = node.arguments;
+                if (key?.type !== "Literal" || key.value !== "json spaces") {
+                    return;
+                }
+                context.report({ node: node, messageId: "jsonSpaces" });
+            },
+        };
+    },
+};

package/rules/no-lib-process-env.js

@@ -0,0 +1,59 @@
+const DEFAULT_ENTRY_POINTS = ["main.ts", "main.js", "main.mts", "main.mjs"];
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description:
+                "A published library never reads process.env; configuration is passed in as a typed argument",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    entryPoints: { type: "array", items: { type: "string" } },
+                    docsUrl: { type: "string" },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            libReadsEnv:
+                "A library must not read process.env - take this as a typed argument instead. " +
+                "An env-reading library cannot be configured twice in one process or differently in a " +
+                "test, and a missing value fails at request time under a name the service author never " +
+                "saw.{{docs}}",
+        },
+    },
+    create(context) {
+        const docs = docsSuffix(context);
+        const entryPoints = context.options[0]?.entryPoints ?? DEFAULT_ENTRY_POINTS;
+        const filename = context.filename ?? context.getFilename();
+        if (entryPoints.some((e) => filename.endsWith(e))) {
+            return {};
+        }
+        return {
+            MemberExpression(node) {
+                if (!isProcessEnv(node)) {
+                    return;
+                }
+                context.report({ node: node, messageId: "libReadsEnv", data: { docs: docs } });
+            },
+        };
+    },
+};
+
+function isProcessEnv(node) {
+    return (
+        node.object?.type === "Identifier" &&
+        node.object.name === "process" &&
+        node.property?.type === "Identifier" &&
+        node.property.name === "env"
+    );
+}
+
+// A link only an internal caller can resolve, so the public default is none.
+function docsSuffix(context) {
+    const url = context.options[0]?.docsUrl;
+    return url ? ` See ${url}.` : "";
+}

package/rules/no-module-scope-init.js

@@ -0,0 +1,140 @@
+const FACTORY_RE = /^(create|connect|init|make|load|open|build)[A-Z]/;
+const CONFIG_CALLEES = new Set(["cfg", "config", "env", "getConfig", "getEnv"]);
+// Factories that MUST run at module scope. A React context is a shared token, not a
+// client: building it lazily would hand each caller a different context object, so the
+// provider would set one instance and the consumer read another.
+const SAFE_CALLEES = new Set([
+    "createContext",
+    "createServerContext",
+    "createElement",
+    "createRef",
+    "createPortal",
+    "createToastManager",
+    "createRoot",
+    "createSelector",
+    "createGlobalStyle",
+]);
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description:
+                "No client or config construction at module scope - it runs at import, before any caller can configure it",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    extraCallees: { type: "array", items: { type: "string" } },
+                    docsUrl: { type: "string" },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            moduleScopeInit:
+                "`{{name}}` is constructed at module scope, so it runs on import - before any caller " +
+                "can configure it, and in every process that merely imports this file. Build it lazily " +
+                "inside a function and memoise.{{docs}}",
+        },
+    },
+    create(context) {
+        const extra = new Set(context.options[0]?.extraCallees ?? []);
+        const docs = docsSuffix(context);
+        return {
+            "Program > VariableDeclaration > VariableDeclarator": (node) => check(context, extra, node, docs),
+            "Program > ExportNamedDeclaration > VariableDeclaration > VariableDeclarator": (node) =>
+                check(context, extra, node, docs),
+        };
+    },
+};
+
+function check(context, extra, node, docs) {
+    if (!node.init || node.id?.type !== "Identifier") {
+        return;
+    }
+    // A factory with STATIC arguments is a shared singleton, not config: `createRouteMemory("/",
+    // isOverlayHref)` computes nothing at import. What this rule is for is the config being READ
+    // at import - `createClient(cfg().url)` - so require an argument that computes, or an env read.
+    if (!readsEnv(node.init) && !(callsFactory(node.init, extra) && hasComputedArg(node.init))) {
+        return;
+    }
+    context.report({ node: node, messageId: "moduleScopeInit", data: { name: node.id.name, docs: docs } });
+}
+
+function callsFactory(node, extra) {
+    if (node.type !== "CallExpression") {
+        return false;
+    }
+    const name = calleeName(node.callee);
+    if (!name || SAFE_CALLEES.has(name)) {
+        return false;
+    }
+    return FACTORY_RE.test(name) || CONFIG_CALLEES.has(name) || extra.has(name);
+}
+
+function hasComputedArg(node) {
+    return (node.arguments ?? []).some((arg) => {
+        let found = false;
+        walk(arg, (n) => {
+            if (n.type === "CallExpression" || n.type === "NewExpression") {
+                found = true;
+            }
+        });
+        return found;
+    });
+}
+
+function calleeName(callee) {
+    if (callee?.type === "Identifier") {
+        return callee.name;
+    }
+    if (callee?.type === "MemberExpression" && callee.property?.type === "Identifier") {
+        return callee.property.name;
+    }
+    if (callee?.type === "NewExpression") {
+        return calleeName(callee.callee);
+    }
+    return null;
+}
+
+function readsEnv(node) {
+    let found = false;
+    walk(node, (n) => {
+        if (
+            n.type === "MemberExpression" &&
+            n.object?.type === "Identifier" &&
+            n.object.name === "process" &&
+            n.property?.type === "Identifier" &&
+            n.property.name === "env"
+        ) {
+            found = true;
+        }
+    });
+    return found;
+}
+
+function walk(node, visit) {
+    if (!node || typeof node.type !== "string") {
+        return;
+    }
+    visit(node);
+    for (const key of Object.keys(node)) {
+        if (key === "parent") {
+            continue;
+        }
+        const child = node[key];
+        if (Array.isArray(child)) {
+            child.forEach((c) => walk(c, visit));
+        } else if (child && typeof child.type === "string") {
+            walk(child, visit);
+        }
+    }
+}
+
+// A link only an internal caller can resolve, so the public default is none.
+function docsSuffix(context) {
+    const url = context.options[0]?.docsUrl;
+    return url ? ` See ${url}.` : "";
+}

package/rules/no-property-shorthand.js

@@ -0,0 +1,31 @@
+export default {
+    meta: {
+        type: "suggestion",
+        docs: { description: "Object literals spell out the value: `{ key: key }`, never `{ key }`" },
+        schema: [],
+        fixable: "code",
+        messages: { shorthand: "Write `{{name}}: {{name}}` rather than the shorthand `{{name}}`." },
+    },
+    create(context) {
+        return {
+            // Only object literal CREATION: code-ts.md exempts destructuring and imports, which
+            // also parse as shorthand Property nodes but under an ObjectPattern. `method` is
+            // excluded because the doc bans shorthand PROPERTIES, not `f() {}`.
+            Property(node) {
+                if (!node.shorthand || node.method || node.parent?.type !== "ObjectExpression") {
+                    return;
+                }
+                const name = node.key?.name;
+                if (!name) {
+                    return;
+                }
+                context.report({
+                    node: node,
+                    messageId: "shorthand",
+                    data: { name: name },
+                    fix: (fixer) => fixer.replaceText(node, `${name}: ${name}`),
+                });
+            },
+        };
+    },
+};

package/rules/prefer-copy-icon.js

@@ -0,0 +1,42 @@
+const BANNED = new Map([["Clipboard", "Copy"], ["ClipboardCopy", "Copy"]]);
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: { description: "Copy buttons use lucide's Copy icon, not Clipboard" },
+        schema: [],
+        fixable: "code",
+        messages: {
+            useCopy: "Use lucide's `{{good}}` icon rather than `{{bad}}` for copy affordances.",
+        },
+    },
+    create(context) {
+        return {
+            ImportDeclaration(node) {
+                if (node.source.value !== "lucide-react") {
+                    return;
+                }
+                for (const spec of node.specifiers) {
+                    if (spec.type !== "ImportSpecifier") {
+                        continue;
+                    }
+                    const good = BANNED.get(spec.imported.name);
+                    if (!good) {
+                        continue;
+                    }
+                    context.report({
+                        node: spec,
+                        messageId: "useCopy",
+                        data: { bad: spec.imported.name, good: good },
+                        fix: (fixer) => {
+                            if (spec.local.name !== spec.imported.name) {
+                                return null;
+                            }
+                            return fixer.replaceText(spec, good);
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/rules/require-leading-with-text-size.js

@@ -0,0 +1,115 @@
+const CLASS_FNS = new Set(["cn", "clsx", "cva", "classNames", "twMerge", "twJoin"]);
+const COLOR_RE = /^(#|rgba?\(|hsla?\(|oklch\(|oklab\(|lab\(|lch\(|color-mix\(|currentColor|transparent)/i;
+const LENGTH_RE = /(^|[\d.])(rem|px|em|ex|ch|vw|vh|vmin|vmax|pt|pc|%)\b|^(calc|clamp|min|max|var)\(|^[\d.]+$/;
+const TEXT_ARB_RE = /\btext-\[([^\]]+)\](\/\S+)?/g;
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description:
+                "An arbitrary text size must state its own line height - it inherits one otherwise, and the ancestor differs per host",
+        },
+        schema: [{ type: "object", properties: { docsUrl: { type: "string" } }, additionalProperties: false }],
+        messages: {
+            needsLeading:
+                "`text-[{{value}}]` sets a font SIZE only, so line height comes from whatever ancestor " +
+                "set one - which differs between hosts and renders the same row at two heights. State it: " +
+                "`text-[{{value}}]/[<leading>]` or an explicit `leading-*`.{{docs}}",
+        },
+    },
+    create(context) {
+        const docs = docsSuffix(context);
+        const seen = new WeakSet();
+
+        const checkContainer = (node, parts) => {
+            const combined = parts.join(" ");
+            if (/\bleading-/.test(combined)) {
+                return;
+            }
+            for (const part of parts) {
+                for (const m of part.matchAll(TEXT_ARB_RE)) {
+                    if (m[2] || !isLength(m[1])) {
+                        continue;
+                    }
+                    context.report({ node: node, messageId: "needsLeading", data: { value: m[1], docs: docs } });
+                }
+            }
+        };
+
+        return {
+            JSXAttribute(node) {
+                if (node.name?.name !== "className" && node.name?.name !== "class") {
+                    return;
+                }
+                seen.add(node);
+                checkContainer(node, collectStrings(node.value, seen));
+            },
+            CallExpression(node) {
+                if (!CLASS_FNS.has(calleeName(node.callee)) || seen.has(node)) {
+                    return;
+                }
+                seen.add(node);
+                checkContainer(node, node.arguments.flatMap((a) => collectStrings(a, seen)));
+            },
+        };
+    },
+};
+
+function collectStrings(node, seen) {
+    const out = [];
+    walk(node, (n) => {
+        if (n !== node && (n.type === "CallExpression" || n.type === "JSXAttribute")) {
+            seen.add(n);
+        }
+        if (n.type === "Literal" && typeof n.value === "string") {
+            out.push(n.value);
+        }
+        if (n.type === "TemplateElement") {
+            out.push(n.value?.raw ?? "");
+        }
+    });
+    return out;
+}
+
+function isLength(value) {
+    const v = value.trim();
+    if (COLOR_RE.test(v)) {
+        return false;
+    }
+    return LENGTH_RE.test(v);
+}
+
+function calleeName(callee) {
+    if (callee?.type === "Identifier") {
+        return callee.name;
+    }
+    if (callee?.type === "MemberExpression" && callee.property?.type === "Identifier") {
+        return callee.property.name;
+    }
+    return null;
+}
+
+function walk(node, visit) {
+    if (!node || typeof node.type !== "string") {
+        return;
+    }
+    visit(node);
+    for (const key of Object.keys(node)) {
+        if (key === "parent") {
+            continue;
+        }
+        const child = node[key];
+        if (Array.isArray(child)) {
+            child.forEach((c) => walk(c, visit));
+        } else if (child && typeof child.type === "string") {
+            walk(child, visit);
+        }
+    }
+}
+
+// A link only an internal caller can resolve, so the public default is none.
+function docsSuffix(context) {
+    const url = context.options[0]?.docsUrl;
+    return url ? ` See ${url}.` : "";
+}

package/rules/us-spelling.js

@@ -0,0 +1,134 @@
+const COMPOUND_STEMS = { centre: "center", centres: "centers", centred: "centered" };
+
+const WORDS = {
+    metre: "meter", metres: "meters", litre: "liter", litres: "liters",
+    fibre: "fiber", fibres: "fibers", theatre: "theater", calibre: "caliber",
+    sombre: "somber", spectre: "specter", lustre: "luster", manoeuvre: "maneuver",
+    colour: "color", colours: "colors", coloured: "colored", colourful: "colorful",
+    behaviour: "behavior", behaviours: "behaviors", favourite: "favorite",
+    favourites: "favorites", honour: "honor", neighbour: "neighbor",
+    neighbours: "neighbors", labour: "labor", flavour: "flavor", flavours: "flavors",
+    harbour: "harbor", rumour: "rumor", humour: "humor", odour: "odor",
+    vapour: "vapor", armour: "armor", endeavour: "endeavor", parlour: "parlor",
+    savour: "savor", valour: "valor",
+    grey: "gray", greyed: "grayed", licence: "license", licences: "licenses",
+    defence: "defense", offence: "offense", pretence: "pretense", practise: "practice",
+    analyse: "analyze", analysed: "analyzed", analysing: "analyzing",
+    paralyse: "paralyze", catalogue: "catalog", catalogues: "catalogs",
+    programme: "program", programmes: "programs", aluminium: "aluminum",
+    storey: "story", tyre: "tire", sulphur: "sulfur", plough: "plow",
+    mould: "mold", draught: "draft", enquire: "inquire", enquiry: "inquiry",
+    cancelled: "canceled", cancelling: "canceling", travelled: "traveled",
+    modelling: "modeling", labelled: "labeled", labelling: "labeling",
+    fuelled: "fueled", signalling: "signaling", marvellous: "marvelous",
+    skilful: "skillful", enrol: "enroll", fulfil: "fulfill", instalment: "installment",
+    organise: "organize", organised: "organized", organisation: "organization",
+    organisations: "organizations", recognise: "recognize", recognised: "recognized",
+    realise: "realize", realised: "realized", apologise: "apologize",
+    prioritise: "prioritize", prioritised: "prioritized", customise: "customize",
+    customised: "customized", normalise: "normalize", normalised: "normalized",
+    serialise: "serialize", serialised: "serialized", initialise: "initialize",
+    initialised: "initialized", optimise: "optimize", optimised: "optimized",
+    summarise: "summarize", categorise: "categorize", categorised: "categorized",
+    standardise: "standardize", specialise: "specialize", emphasise: "emphasize",
+    criticise: "criticize", authorise: "authorize", authorised: "authorized",
+    minimise: "minimize", maximise: "maximize", visualise: "visualize",
+    utilise: "utilize", memorise: "memorize", synchronise: "synchronize",
+    synchronised: "synchronized",
+};
+
+const WORD_RE = new RegExp(`\\b(${Object.keys(WORDS).join("|")})\\b`, "gi");
+const COMPOUND_RE = new RegExp(`\\b(\\w*?)(${Object.keys(COMPOUND_STEMS).join("|")})\\b`, "gi");
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: { description: "US spelling everywhere we write" },
+        // Fixable in COMMENTS and JSX TEXT only. A string literal can be a wire value -
+        // an upstream status, a served route, a search synonym - and rewriting one is how
+        // a filter silently stops matching. Those are reported for a human to judge.
+        fixable: "code",
+        schema: [
+            {
+                type: "object",
+                properties: { allow: { type: "array", items: { type: "string" } } },
+                additionalProperties: false,
+            },
+        ],
+        messages: { british: "Use US spelling: `{{bad}}` -> `{{good}}`." },
+    },
+    create(context) {
+        const allow = context.options[0]?.allow ?? [];
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+        const check = (node, text, fixable) => {
+            if (typeof text !== "string" || !text) {
+                return;
+            }
+            if (allow.some((phrase) => text.includes(phrase))) {
+                return;
+            }
+            for (const [bad, good] of findAll(text)) {
+                context.report({
+                    node: node,
+                    messageId: "british",
+                    data: { bad: bad, good: good },
+                    fix: fixable
+                        ? (fixer) => {
+                              const range = node.range ?? [node.start, node.end];
+                              const src = sourceCode.getText().slice(range[0], range[1]);
+                              return fixer.replaceTextRange(range, replaceWord(src, bad, good));
+                          }
+                        : null,
+                });
+            }
+        };
+
+        return {
+            // A regex matching scraped text must accept BOTH spellings, so literals carrying one are exempt.
+            Literal(node) {
+                if (node.regex) {
+                    return;
+                }
+                check(node, node.value, false);
+            },
+            TemplateElement(node) {
+                check(node, node.value?.raw, false);
+            },
+            JSXText(node) {
+                check(node, node.value, true);
+            },
+            "Program:exit": () => {
+                for (const comment of sourceCode.getAllComments()) {
+                    check(comment, comment.value, true);
+                }
+            },
+        };
+    },
+};
+
+function replaceWord(src, bad, good) {
+    return src.replace(new RegExp(`\\b${bad}\\b`, "g"), good);
+}
+
+function findAll(text) {
+    const hits = [];
+    for (const m of text.matchAll(WORD_RE)) {
+        hits.push([m[1], matchCase(m[1], WORDS[m[1].toLowerCase()])]);
+    }
+    for (const m of text.matchAll(COMPOUND_RE)) {
+        const stem = COMPOUND_STEMS[m[2].toLowerCase()];
+        hits.push([m[0], m[1] + matchCase(m[2], stem)]);
+    }
+    return hits;
+}
+
+function matchCase(sample, replacement) {
+    if (sample === sample.toUpperCase()) {
+        return replacement.toUpperCase();
+    }
+    if (sample[0] === sample[0].toUpperCase()) {
+        return replacement[0].toUpperCase() + replacement.slice(1);
+    }
+    return replacement;
+}

package/ui.js

@@ -0,0 +1,75 @@
+// The Tailwind + React half, behind its own entry point.
+//
+// A backend service has no Tailwind and no React. Keeping these behind their own
+// entry point means the root entry installs neither @shadcn/lint nor
+// eslint-plugin-react-hooks (nor oxc-parser's native binaries), and a service that
+// imports only the root never resolves them.
+//
+//   import { ui } from "@mslmio/eslint-config/ui";
+import shadcn from "@shadcn/lint";
+import reactHooks from "eslint-plugin-react-hooks";
+
+import { house, lib } from "./index.js";
+
+// Tailwind class hygiene. `cn`, `clsx`, `cva`, `twMerge` and `twJoin` are already
+// built-in merge functions, so only the component packages need naming.
+export const shadcnUi = [
+    {
+        files: ["**/*.tsx", "**/*.ts"],
+        plugins: { shadcn: shadcn },
+        settings: {
+            // EMPTY by default: which packages are the component library is the
+            // consumer's fact, not this config's. Append a later flat-config entry
+            // setting `settings.shadcn.componentImports` to declare them.
+            shadcn: { componentImports: [] },
+        },
+        rules: {
+            // `allow: ["layout"]` is the plugin's own documented adoption setting, and it
+            // matches how our library is actually built: Panel, PanelBody and friends take
+            // `className` and merge it with `cn()`, so external composition is their API.
+            // Typography, color and internal spacing stay errors - that is the drift
+            // this rule set exists to stop.
+            // WARN, not error, and deliberately so: these landed on a codebase with a
+            // real backlog (~1,340 at adoption), and clearing it needs design decisions
+            // rather than effort - component variants in the library, and a named
+            // typographic scale where clamp()/ch have no Tailwind equivalent. A red
+            // `pnpm lint` nobody can fix is a lint nobody reads. Ratchet per app to
+            // "error" as each backlog clears.
+            "shadcn/no-restyle": ["warn", { allow: ["layout"] }],
+            "shadcn/no-raw-colors": "warn",
+            "shadcn/no-arbitrary-values": "warn",
+            "shadcn/no-inline-styles": "warn",
+            "shadcn/require-static-classes": "warn",
+            "shadcn/no-unknown-classes": "warn",
+        },
+    },
+];
+
+export const ui = [
+    ...house,
+    ...shadcnUi,
+    {
+        files: ["**/*.tsx", "**/*.ts"],
+        rules: {
+            "mslmio/require-leading-with-text-size": "error",
+            "mslmio/prefer-copy-icon": "error",
+        },
+    },
+];
+
+// A published React component library. The hook rules are not decoration: a
+// rebuilt dependency can silently disable a memo other code relied on.
+export const uiLib = [
+    ...lib,
+    ...ui,
+    {
+        files: ["**/*.tsx", "**/*.ts"],
+        plugins: { "react-hooks": reactHooks },
+        rules: {
+            "react-hooks/rules-of-hooks": "error",
+            "react-hooks/exhaustive-deps": "warn",
+        },
+    },
+];
+
+export default { shadcnUi: shadcnUi, ui: ui, uiLib: uiLib };