diff --git a/docs/work/frontend-conformance-v1/01-frontend-rules/_story.md b/docs/work/frontend-conformance-v1/01-frontend-rules/_story.md new file mode 100644 index 0000000..ab44733 --- /dev/null +++ b/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 diff --git a/docs/work/frontend-conformance-v1/_epic.md b/docs/work/frontend-conformance-v1/_epic.md new file mode 100644 index 0000000..c136427 --- /dev/null +++ b/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) diff --git a/packages/core-eslint/base.js b/packages/core-eslint/base.js index 02f839e..efa673b 100644 --- a/packages/core-eslint/base.js +++ b/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", }, }, { diff --git a/packages/core-eslint/plugin.js b/packages/core-eslint/plugin.js index 20ebd7a..b060410 100644 --- a/packages/core-eslint/plugin.js +++ b/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, }, }; diff --git a/packages/core-eslint/rules/atomic-tier-import-direction.js b/packages/core-eslint/rules/atomic-tier-import-direction.js new file mode 100644 index 0000000..7b8e032 --- /dev/null +++ b/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 }, + }); + } + }, + }; + }, +}; diff --git a/packages/core-eslint/rules/atomic-tier-import-direction.test.js b/packages/core-eslint/rules/atomic-tier-import-direction.test.js new file mode 100644 index 0000000..c2c67e6 --- /dev/null +++ b/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: [], + }); + }); +}); diff --git a/packages/core-eslint/rules/component-must-have-story.js b/packages/core-eslint/rules/component-must-have-story.js new file mode 100644 index 0000000..3338da4 --- /dev/null +++ b/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//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), + }, + }); + }, + }; + }, +}; diff --git a/packages/core-eslint/rules/component-must-have-story.test.js b/packages/core-eslint/rules/component-must-have-story.test.js new file mode 100644 index 0000000..00b1cb6 --- /dev/null +++ b/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 = () => ;`); + 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: [], + }); + }); +}); diff --git a/packages/core-eslint/rules/component-must-have-test.js b/packages/core-eslint/rules/component-must-have-test.js new file mode 100644 index 0000000..dd45df3 --- /dev/null +++ b/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), + }, + }); + }, + }; + }, +}; diff --git a/packages/core-eslint/rules/component-must-have-test.test.js b/packages/core-eslint/rules/component-must-have-test.test.js new file mode 100644 index 0000000..398826c --- /dev/null +++ b/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 = () => ;`); + 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" }], + }], + }); + }); +});