feat(webapp): keep Storybook titles derived from the file tree

Author: FelixTJDietrich

.claude/skills/storybook-components/rules/story-titles.md

@@ -5,6 +5,8 @@ Two conventions live side by side, and which one applies is a property of the co
 - **Omit `title` by default.** `webapp/.storybook/main.ts` globs `../src/**` with no `titlePrefix`, so
   a story with no title is filed by its path under `src` — `components/admin/ai/ModelPicker`. Most
   stories belong here: the file tree *is* the grouping, and it cannot go stale.
+  `hephaestus/prefer-auto-story-title` rejects an explicit title that only repeats this derived path,
+  including copies that differ only in case or punctuation.
 
 - **Declare a `title` when the file layout cannot express where a reader looks for the thing.** A
   product surface assembled from several directories, or one an admin knows by the screen it is on,

webapp/.oxlintrc.json

@@ -660,6 +660,9 @@
 				// so anything counted there is counted here. A literal cannot be shared across JSON and
 				// TypeScript, so it is that relation `play-must-assert.test.ts` pins.
 				"hephaestus/play-must-assert": "error",
+				// The file path is the component tree's source of truth. An explicit title is only for a
+				// deliberate reader-facing relocation, never a differently-cased copy of that path.
+				"hephaestus/prefer-auto-story-title": "error",
 				// One story quietly exempting itself leaves the whole suite green.
 				"hephaestus/no-story-a11y-override": "error",
 				"hephaestus/no-within-canvas-element": "error",

webapp/tools/oxlint/index.ts

@@ -6,6 +6,7 @@ import { noRedundantInTheDocument } from "./rules/no-redundant-in-the-document.t
 import { noStoryA11yOverride } from "./rules/no-story-a11y-override.ts";
 import { noWithinCanvasElement } from "./rules/no-within-canvas-element.ts";
 import { playMustAssert } from "./rules/play-must-assert.ts";
+import { preferAutoStoryTitle } from "./rules/prefer-auto-story-title.ts";
 import { svgNeedsAccessibleName } from "./rules/svg-needs-accessible-name.ts";
 import { typedStoryMeta } from "./rules/typed-story-meta.ts";
 
@@ -19,6 +20,7 @@ export default definePlugin({
 		"no-story-a11y-override": noStoryA11yOverride,
 		"no-within-canvas-element": noWithinCanvasElement,
 		"play-must-assert": playMustAssert,
+		"prefer-auto-story-title": preferAutoStoryTitle,
 		"svg-needs-accessible-name": svgNeedsAccessibleName,
 		"typed-story-meta": typedStoryMeta,
 	},

webapp/tools/oxlint/rules/prefer-auto-story-title.test.ts

@@ -0,0 +1,42 @@
+import { ruleTester } from "../rule-tester.ts";
+import { preferAutoStoryTitle } from "./prefer-auto-story-title.ts";
+
+const component = "const Button = () => null;";
+
+ruleTester.run("prefer-auto-story-title", preferAutoStoryTitle, {
+	valid: [
+		{
+			code: `${component}\nconst meta = { component: Button } satisfies Meta<typeof Button>;`,
+			filename: "webapp/src/components/ui/Button.stories.tsx",
+		},
+		{
+			// Dropping the implementation-only `components` segment is a real sidebar relocation.
+			code: `${component}\nconst meta = { title: "UI primitives/Button", component: Button } satisfies Meta<typeof Button>;`,
+			filename: "webapp/src/components/ui/Button.stories.tsx",
+		},
+		{
+			// Product surfaces can cut across the source layout.
+			code: `${component}\nconst meta = { title: "Workspace admin/Practices/Review/Overview", component: Button } satisfies Meta<typeof Button>;`,
+			filename: "webapp/src/components/admin/practices/review/ReviewPage.stories.tsx",
+		},
+		{
+			// A computed title is owned by check:story-sort, which gives the more precise diagnostic.
+			code: `${component}\nconst meta = { title: prefix + "/Button", component: Button } satisfies Meta<typeof Button>;`,
+			filename: "webapp/src/components/ui/Button.stories.tsx",
+		},
+	],
+	invalid: [
+		{
+			code: `${component}\nconst meta = { title: "components/ui/Button", component: Button } satisfies Meta<typeof Button>;`,
+			filename: "webapp/src/components/ui/Button.stories.tsx",
+			errors: [{ messageId: "redundant", data: { automatic: "components/ui/Button" } }],
+		},
+		{
+			// Sentence case and punctuation do not make the same Storybook path meaningful metadata.
+			code: `${component}\nconst meta = { title: "components/UI/button", component: Button } satisfies Meta<typeof Button>;`,
+			filename: "/repo/webapp/src/components/ui/Button.stories.tsx",
+			cwd: "/repo",
+			errors: [{ messageId: "redundant" }],
+		},
+	],
+});

webapp/tools/oxlint/rules/prefer-auto-story-title.ts

@@ -0,0 +1,80 @@
+import { relative } from "node:path";
+import { defineRule, type ESTree } from "@oxlint/plugins";
+import { propertyName } from "../property.ts";
+
+const STORY_SUFFIX = /\.stories\.[cm]?[jt]sx?$/;
+const PATH_SEPARATOR = /[\\/]/;
+
+/** Storybook ignores case and punctuation when it turns a path or title into an id. */
+const normalizedSegments = (segments: string[]) =>
+	segments.map((segment) => segment.replaceAll(/[^a-zA-Z0-9]/g, "").toLowerCase());
+
+/** The title Storybook derives from this file when `meta.title` is absent. */
+function automaticTitle(filename: string, cwd: string): string[] | undefined {
+	const segments = relative(cwd, filename).split(PATH_SEPARATOR);
+	const src = segments.findIndex(
+		(segment, index) => segment === "src" && (index === 0 || segments[index - 1] === "webapp"),
+	);
+	if (src === -1) return undefined;
+	const owned = segments.slice(src + 1);
+	const file = owned.at(-1);
+	if (file === undefined || !STORY_SUFFIX.test(file)) return undefined;
+	owned[owned.length - 1] = file.replace(STORY_SUFFIX, "");
+	return owned;
+}
+
+function objectExpression(expression: ESTree.Expression | null | undefined) {
+	let current = expression;
+	while (
+		current?.type === "TSSatisfiesExpression" ||
+		current?.type === "TSAsExpression" ||
+		current?.type === "TSInstantiationExpression"
+	) {
+		current = current.expression;
+	}
+	return current?.type === "ObjectExpression" ? current : undefined;
+}
+
+export const preferAutoStoryTitle = defineRule({
+	meta: {
+		type: "suggestion",
+		docs: {
+			description:
+				"Omit a Storybook meta title when it only restates the title Storybook derives from the story file. Explicit titles are reserved for a reader-facing hierarchy the source path cannot express.",
+		},
+		messages: {
+			redundant:
+				"This title restates `{{automatic}}`, which Storybook already derives from the file path. Delete `title`; keep an explicit title only when it deliberately relocates the component in the reader-facing tree.",
+		},
+	},
+	create(context) {
+		const automatic = automaticTitle(context.filename, context.cwd);
+		if (automatic === undefined) return {};
+		return {
+			VariableDeclarator(node) {
+				if (node.id.type !== "Identifier" || node.id.name !== "meta") return;
+				const meta = objectExpression(node.init);
+				if (meta === undefined) return;
+				const title = meta.properties.find(
+					(property) => property.type === "Property" && propertyName(property) === "title",
+				);
+				if (
+					title?.type !== "Property" ||
+					title.value.type !== "Literal" ||
+					typeof title.value.value !== "string"
+				) {
+					return;
+				}
+				const declared = title.value.value.split("/");
+				if (normalizedSegments(declared).join("/") !== normalizedSegments(automatic).join("/")) {
+					return;
+				}
+				context.report({
+					node: title,
+					messageId: "redundant",
+					data: { automatic: automatic.join("/") },
+				});
+			},
+		};
+	},
+});