Merge branch 'worktree-frontend-conformance': frontend conformance rules v1

docs/work/frontend-conformance-v1/01-frontend-rules/_story.md

@@ -0,0 +1,42 @@
+---
+id: 01-frontend-rules
+epic: frontend-conformance-v1
+title: Three structural frontend conformance ESLint rules
+type: technical-story
+status: done
+feature: core-eslint
+depends-on: []
+blocks: []
+---
+
+## Goal
+Three new rules under the `conformance/` plugin namespace:
+`component-must-have-story`, `component-must-have-test`,
+`atomic-tier-import-direction`. All ship as WARN initially because
+no components exist in the repo today.
+
+## Done when
+- Three rules registered in `@repo/core-eslint/plugin`
+- Each has RuleTester tests
+- `base.js` registers them at WARN severity
+- `pnpm lint` passes (zero firings expected today; rules activate when
+  first component lands)
+
+## In scope
+- Three new rule files in `packages/core-eslint/rules/`
+- Plugin + base.js wiring
+- Tests via RuleTester
+
+## Out of scope
+- Visual regression infrastructure (Playwright screenshots — separate plan)
+- `story-must-cover-all-prop-variants` advisory rule
+- Detection beyond filesystem siblings (no AST-level component-detection
+  heuristics)
+
+## Tasks
+- [x] Epic + story scaffold
+- [x] `component-must-have-story` rule + tests
+- [x] `component-must-have-test` rule + tests
+- [x] `atomic-tier-import-direction` rule + tests
+- [x] Plugin update + base.js wiring
+- [x] Final verification + closeout

docs/work/frontend-conformance-v1/_epic.md

@@ -0,0 +1,22 @@
+---
+id: frontend-conformance-v1
+prd: null
+title: Frontend conformance rules v1
+type: epic
+status: done
+features: [core-eslint]
+created: 2026-05-13
+---
+
+## Goal
+Three structural ESLint rules for frontend component files: every
+component has a sibling Storybook story, a sibling test, and respects
+atomic-design tier direction (atoms can't import from organisms, etc.).
+
+## Why
+The frontend-work-shape guide describes these conventions; without
+rules, they're advisory only. Ship them now so they activate the moment
+core-ui or feature UI components land — preventing drift from day one.
+
+## Stories
+- [x] [01 — Frontend ESLint rules](01-frontend-rules/_story.md)

packages/core-eslint/base.js

@@ -45,6 +45,9 @@ export default [
       ],
       "conformance/no-undeclared-event-publish": ["warn", { repoRoot }],
       "conformance/no-undeclared-audit": ["warn", { repoRoot }],
+      "conformance/component-must-have-story": "warn",
+      "conformance/component-must-have-test": "warn",
+      "conformance/atomic-tier-import-direction": "warn",
     },
   },
   {

packages/core-eslint/plugin.js

@@ -3,6 +3,9 @@ import usecaseMustHaveTestFile from "./rules/usecase-must-have-test-file.js";
 import requiredCoresInstalled from "./rules/required-cores-installed.js";
 import noUndeclaredEventPublish from "./rules/no-undeclared-event-publish.js";
 import noUndeclaredAudit from "./rules/no-undeclared-audit.js";
+import componentMustHaveStory from "./rules/component-must-have-story.js";
+import componentMustHaveTest from "./rules/component-must-have-test.js";
+import atomicTierImportDirection from "./rules/atomic-tier-import-direction.js";
 
 /**
  * The `@repo/core-eslint` conformance plugin. Aggregates custom rules that
@@ -18,13 +21,16 @@ import noUndeclaredAudit from "./rules/no-undeclared-audit.js";
  *   ];
  */
 const plugin = {
-  meta: { name: "conformance", version: "0.2.0" },
+  meta: { name: "conformance", version: "0.3.0" },
   rules: {
     "feature-must-have-manifest": featureMustHaveManifest,
     "usecase-must-have-test-file": usecaseMustHaveTestFile,
     "required-cores-installed": requiredCoresInstalled,
     "no-undeclared-event-publish": noUndeclaredEventPublish,
     "no-undeclared-audit": noUndeclaredAudit,
+    "component-must-have-story": componentMustHaveStory,
+    "component-must-have-test": componentMustHaveTest,
+    "atomic-tier-import-direction": atomicTierImportDirection,
   },
 };
 

packages/core-eslint/rules/atomic-tier-import-direction.js

@@ -0,0 +1,47 @@
+const TIERS = ["atoms", "molecules", "organisms", "templates", "pages"];
+
+function tierOf(filepath) {
+  for (let i = 0; i < TIERS.length; i++) {
+    const tier = TIERS[i];
+    if (filepath.includes(`/${tier}/`) || filepath.includes(`\\${tier}\\`)) {
+      return { name: tier, index: i };
+    }
+  }
+  return null;
+}
+
+/** @type {import("eslint").Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Atomic-design tier imports respect direction: atoms ← molecules ← organisms ← templates ← pages.",
+    },
+    schema: [],
+    messages: {
+      wrongDirection:
+        "{{fromTier}} cannot import from {{toTier}} ({{importPath}}). Tier direction: atoms ← molecules ← organisms ← templates ← pages.",
+    },
+  },
+  create(context) {
+    const filename = context.filename;
+    const from = tierOf(filename);
+    if (!from) return {};
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (typeof source !== "string") return;
+        const to = tierOf(source);
+        if (!to) return;
+        if (to.index > from.index) {
+          context.report({
+            node,
+            messageId: "wrongDirection",
+            data: { fromTier: from.name, toTier: to.name, importPath: source },
+          });
+        }
+      },
+    };
+  },
+};

packages/core-eslint/rules/atomic-tier-import-direction.test.js

@@ -0,0 +1,55 @@
+import { describe, it } from "vitest";
+import { RuleTester } from "eslint";
+import rule from "./atomic-tier-import-direction.js";
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser: await import("@typescript-eslint/parser"),
+    ecmaVersion: "latest",
+    sourceType: "module",
+    parserOptions: { ecmaFeatures: { jsx: true } },
+  },
+});
+
+describe("atomic-tier-import-direction", () => {
+  it("passes when an organism imports from atoms", () => {
+    tester.run("atomic-tier-import-direction", rule, {
+      valid: [{
+        filename: "/repo/packages/core-ui/src/organisms/Card/Card.tsx",
+        code: `import { Button } from "../../atoms/Button/Button";`,
+      }],
+      invalid: [],
+    });
+  });
+
+  it("fires when an atom imports from organisms", () => {
+    tester.run("atomic-tier-import-direction", rule, {
+      valid: [],
+      invalid: [{
+        filename: "/repo/packages/core-ui/src/atoms/Button/Button.tsx",
+        code: `import { Card } from "../../organisms/Card/Card";`,
+        errors: [{ messageId: "wrongDirection", data: { fromTier: "atoms", toTier: "organisms", importPath: "../../organisms/Card/Card" } }],
+      }],
+    });
+  });
+
+  it("is a no-op for files outside any tier folder", () => {
+    tester.run("atomic-tier-import-direction", rule, {
+      valid: [{
+        filename: "/repo/packages/auth/src/application/use-cases/sign-in.use-case.ts",
+        code: `export const x = 1;`,
+      }],
+      invalid: [],
+    });
+  });
+
+  it("passes for same-tier imports", () => {
+    tester.run("atomic-tier-import-direction", rule, {
+      valid: [{
+        filename: "/repo/packages/core-ui/src/molecules/SearchBar/SearchBar.tsx",
+        code: `import { FormField } from "../FormField/FormField";`,
+      }],
+      invalid: [],
+    });
+  });
+});

packages/core-eslint/rules/component-must-have-story.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Identifies "component files" by location + extension:
+ * - `.tsx` extension
+ * - Inside `packages/core-ui/src/` OR `packages/<feature>/src/ui/`
+ * - NOT a test, stories, spec, or barrel file
+ */
+function isComponentFile(filename) {
+  if (!filename.endsWith(".tsx")) return false;
+  const base = path.basename(filename);
+  if (
+    base === "index.tsx" ||
+    base.endsWith(".test.tsx") ||
+    base.endsWith(".stories.tsx") ||
+    base.endsWith(".spec.tsx")
+  ) {
+    return false;
+  }
+  return (
+    filename.includes("/packages/core-ui/src/") ||
+    /\/packages\/[^/]+\/src\/ui\//.test(filename)
+  );
+}
+
+/** @type {import("eslint").Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every component file must have a sibling *.stories.tsx for Storybook coverage.",
+    },
+    schema: [],
+    messages: {
+      missingStory:
+        "Component {{filename}} has no sibling Storybook story at {{expected}}. Stories are the spec for visual conformance.",
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const filename = context.filename;
+        if (!isComponentFile(filename)) return;
+        const expected = filename.replace(/\.tsx$/, ".stories.tsx");
+        if (fs.existsSync(expected)) return;
+        context.report({
+          node,
+          messageId: "missingStory",
+          data: {
+            filename: path.basename(filename),
+            expected: path.basename(expected),
+          },
+        });
+      },
+    };
+  },
+};

packages/core-eslint/rules/component-must-have-story.test.js

@@ -0,0 +1,84 @@
+import { describe, it } from "vitest";
+import { RuleTester } from "eslint";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import rule from "./component-must-have-story.js";
+
+function makeFixture({ withStory, location = "core-ui" }) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmhs-"));
+  const dir =
+    location === "core-ui"
+      ? path.join(root, "packages", "core-ui", "src", "atoms", "Button")
+      : path.join(root, "packages", "demo", "src", "ui", "atoms", "Button");
+  fs.mkdirSync(dir, { recursive: true });
+  const component = path.join(dir, "Button.tsx");
+  fs.writeFileSync(component, `export const Button = () => <button>x</button>;`);
+  if (withStory) {
+    fs.writeFileSync(path.join(dir, "Button.stories.tsx"), `export default { title: "Button" };`);
+  }
+  return { component };
+}
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser: await import("@typescript-eslint/parser"),
+    ecmaVersion: "latest",
+    sourceType: "module",
+    parserOptions: { ecmaFeatures: { jsx: true } },
+  },
+});
+
+describe("component-must-have-story", () => {
+  it("passes for a core-ui component with a sibling .stories.tsx", () => {
+    const { component } = makeFixture({ withStory: true });
+    tester.run("component-must-have-story", rule, {
+      valid: [{ filename: component, code: fs.readFileSync(component, "utf8") }],
+      invalid: [],
+    });
+  });
+
+  it("fires for a core-ui component without a sibling .stories.tsx", () => {
+    const { component } = makeFixture({ withStory: false });
+    tester.run("component-must-have-story", rule, {
+      valid: [],
+      invalid: [{
+        filename: component,
+        code: fs.readFileSync(component, "utf8"),
+        errors: [{ messageId: "missingStory" }],
+      }],
+    });
+  });
+
+  it("passes for a feature ui component with a sibling .stories.tsx", () => {
+    const { component } = makeFixture({ withStory: true, location: "feature" });
+    tester.run("component-must-have-story", rule, {
+      valid: [{ filename: component, code: fs.readFileSync(component, "utf8") }],
+      invalid: [],
+    });
+  });
+
+  it("is a no-op for index.tsx", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmhs-"));
+    const dir = path.join(root, "packages", "core-ui", "src", "atoms", "Button");
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, "index.tsx");
+    fs.writeFileSync(file, `export * from "./Button";`);
+    tester.run("component-must-have-story", rule, {
+      valid: [{ filename: file, code: fs.readFileSync(file, "utf8") }],
+      invalid: [],
+    });
+  });
+
+  it("is a no-op for files outside packages/core-ui/ and packages/*/src/ui/", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmhs-"));
+    const dir = path.join(root, "packages", "auth", "src", "application", "use-cases");
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, "sign-in.use-case.tsx");
+    fs.writeFileSync(file, `export const x = 1;`);
+    tester.run("component-must-have-story", rule, {
+      valid: [{ filename: file, code: fs.readFileSync(file, "utf8") }],
+      invalid: [],
+    });
+  });
+});

packages/core-eslint/rules/component-must-have-test.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function isComponentFile(filename) {
+  if (!filename.endsWith(".tsx")) return false;
+  const base = path.basename(filename);
+  if (
+    base === "index.tsx" ||
+    base.endsWith(".test.tsx") ||
+    base.endsWith(".stories.tsx") ||
+    base.endsWith(".spec.tsx")
+  ) {
+    return false;
+  }
+  return (
+    filename.includes("/packages/core-ui/src/") ||
+    /\/packages\/[^/]+\/src\/ui\//.test(filename)
+  );
+}
+
+/** @type {import("eslint").Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every component file must have a sibling *.test.tsx for behavioural coverage.",
+    },
+    schema: [],
+    messages: {
+      missingTest:
+        "Component {{filename}} has no sibling test at {{expected}}. Write the red test first.",
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const filename = context.filename;
+        if (!isComponentFile(filename)) return;
+        const expected = filename.replace(/\.tsx$/, ".test.tsx");
+        if (fs.existsSync(expected)) return;
+        context.report({
+          node,
+          messageId: "missingTest",
+          data: {
+            filename: path.basename(filename),
+            expected: path.basename(expected),
+          },
+        });
+      },
+    };
+  },
+};

packages/core-eslint/rules/component-must-have-test.test.js

@@ -0,0 +1,49 @@
+import { describe, it } from "vitest";
+import { RuleTester } from "eslint";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import rule from "./component-must-have-test.js";
+
+function makeFixture({ withTest }) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmht-"));
+  const dir = path.join(root, "packages", "core-ui", "src", "atoms", "Button");
+  fs.mkdirSync(dir, { recursive: true });
+  const component = path.join(dir, "Button.tsx");
+  fs.writeFileSync(component, `export const Button = () => <button>x</button>;`);
+  if (withTest) {
+    fs.writeFileSync(path.join(dir, "Button.test.tsx"), `import { it } from "vitest"; it("works", () => {});`);
+  }
+  return { component };
+}
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser: await import("@typescript-eslint/parser"),
+    ecmaVersion: "latest",
+    sourceType: "module",
+    parserOptions: { ecmaFeatures: { jsx: true } },
+  },
+});
+
+describe("component-must-have-test", () => {
+  it("passes when sibling .test.tsx exists", () => {
+    const { component } = makeFixture({ withTest: true });
+    tester.run("component-must-have-test", rule, {
+      valid: [{ filename: component, code: fs.readFileSync(component, "utf8") }],
+      invalid: [],
+    });
+  });
+
+  it("fires when no sibling .test.tsx exists", () => {
+    const { component } = makeFixture({ withTest: false });
+    tester.run("component-must-have-test", rule, {
+      valid: [],
+      invalid: [{
+        filename: component,
+        code: fs.readFileSync(component, "utf8"),
+        errors: [{ messageId: "missingTest" }],
+      }],
+    });
+  });
+});