@trackunit/eslint-plugin-trackunit 0.6.49 → 0.6.50

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.6.50 (2026-06-30)
+
+### 🧱 Updated Dependencies
+
+- Updated shared-utils to 1.15.50
+
 ## 0.6.49 (2026-06-30)
 
 ### 🧱 Updated Dependencies

package/README.md

@@ -83,6 +83,12 @@ All custom rules are enabled automatically through the presets under the `@track
 | `@trackunit/no-internal-graphql-when-tagged-with-gql-public` | error    | —        | Prevents internal GraphQL usage in projects tagged with `gql-public`. Applied to `project.json` files. |
 
 
+### Storybook
+
+| Rule                                                  | Severity | Auto-fix | Description                                                                                                          |
+| ----------------------------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `@trackunit/require-storybook-folder-landing-page`    | —        | no       | Requires a `*.docs.mdx` landing page (`<Meta title>`) for every ancestor folder implied by a story's title. Report-only; not yet enabled in a preset. |
+
 ## Utilities
 
 ### `createSkipWhen`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/eslint-plugin-trackunit",
-  "version": "0.6.49",
+  "version": "0.6.50",
   "license": "SEE LICENSE IN LICENSE.txt",
   "repository": "https://github.com/Trackunit/manager",
   "engines": {

package/src/lib/config/index.d.ts

@@ -86,6 +86,9 @@ export declare const configs: {
                     }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                         name: string;
                     };
+                    "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                        name: string;
+                    };
                 };
             };
             "@typescript-eslint": {
@@ -272,6 +275,9 @@ export declare const configs: {
                     }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                         name: string;
                     };
+                    "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                        name: string;
+                    };
                 };
             };
             "@nx"?: undefined;
@@ -390,6 +396,9 @@ export declare const configs: {
                     }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                         name: string;
                     };
+                    "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                        name: string;
+                    };
                 };
             };
             "@typescript-eslint": {

package/src/lib/config/plugins.d.ts

@@ -104,6 +104,9 @@ export declare const localRulesPlugin: {
         }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
+        "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
     };
 };
 export { eslintConfigPrettier, globals, importPlugin, jest, jsdoc, jsoncParser, noNull, nx, react, reactHooks, testingLibrary, tsParser, typescriptEslint, };

package/src/lib/config/presets/base.d.ts

@@ -86,6 +86,9 @@ export declare const base: (import("eslint").Linter.FlatConfig<import("eslint").
                 }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                     name: string;
                 };
+                "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                    name: string;
+                };
             };
         };
         "@typescript-eslint": {
@@ -272,6 +275,9 @@ export declare const base: (import("eslint").Linter.FlatConfig<import("eslint").
                 }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                     name: string;
                 };
+                "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                    name: string;
+                };
             };
         };
         "@nx"?: undefined;

package/src/lib/config/presets/react.d.ts

@@ -85,6 +85,9 @@ export declare const reactPreset: (import("eslint").Linter.Config<import("eslint
                 }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                     name: string;
                 };
+                "require-storybook-folder-landing-page": import("@typescript-eslint/utils/ts-eslint").RuleModule<"missingLandingPage", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                    name: string;
+                };
             };
         };
         "@typescript-eslint": {

package/src/lib/rules/require-storybook-folder-landing-page/require-storybook-folder-landing-page.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Require a Storybook landing page (`*.docs.mdx` with `<Meta title="...">`) for every ancestor
+ * FOLDER implied by a story's title.
+ *
+ * Architecture: per-story-file rule. Each `*.stories.@(js|jsx|ts|tsx)` file declares a Storybook
+ * `title` (e.g. "Hooks/react-core-hooks/useDebounce"). The folders implied by that title are the
+ * accumulated path prefixes EXCLUDING the story leaf (here: "Hooks" and "Hooks/react-core-hooks").
+ * Every such folder must have a landing page: a `*.docs.mdx` somewhere in the workspace whose
+ * `<Meta title="FOLDER" />` EXACTLY equals the folder path, with non-empty body and no TODO marker.
+ *
+ * The rule is REPORT-ONLY: it does not scaffold files. Creating a separate `*.docs.mdx` cannot be
+ * expressed as a pure ESLint fix, and ESLint evaluates fix/suggestion callbacks on every lint pass
+ * (not only under `--fix`), so a file-writing fix would write stubs during ordinary editor/CI lint.
+ * Stub scaffolding is therefore delivered as a separate, explicit command (tracked as a follow-up).
+ *
+ * See README.md for incorrect/correct examples.
+ */
+import { ESLintUtils } from "@typescript-eslint/utils";
+/** Canonical TODO marker. A landing page still containing this marker does NOT satisfy the rule. */
+export declare const STORYBOOK_LANDING_PAGE_TODO_MARKER = "{/* TODO: storybook-folder-landing-page */}";
+/**
+ * Canonical permalink to the how-to-author doc. Single source of truth, embedded in the rule's
+ * error message so developers tripping the rule get a direct link. The `master` permalink stays
+ * stable across file moves within the (internal) repo.
+ */
+export declare const STORYBOOK_LANDING_PAGE_DOCS_URL = "https://github.com/Trackunit/manager/blob/master/docs/STORYBOOK-LANDING-PAGES.md";
+/** Clear the module-level scan cache (primarily for tests). */
+export declare const clearLandingPageCache: () => void;
+export declare const requireStorybookFolderLandingPage: ESLintUtils.RuleModule<"missingLandingPage", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/src/lib/rules/require-storybook-folder-landing-page/require-storybook-folder-landing-page.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Require a Storybook landing page (`*.docs.mdx` with `<Meta title="...">`) for every ancestor
+ * FOLDER implied by a story's title.
+ *
+ * Architecture: per-story-file rule. Each `*.stories.@(js|jsx|ts|tsx)` file declares a Storybook
+ * `title` (e.g. "Hooks/react-core-hooks/useDebounce"). The folders implied by that title are the
+ * accumulated path prefixes EXCLUDING the story leaf (here: "Hooks" and "Hooks/react-core-hooks").
+ * Every such folder must have a landing page: a `*.docs.mdx` somewhere in the workspace whose
+ * `<Meta title="FOLDER" />` EXACTLY equals the folder path, with non-empty body and no TODO marker.
+ *
+ * The rule is REPORT-ONLY: it does not scaffold files. Creating a separate `*.docs.mdx` cannot be
+ * expressed as a pure ESLint fix, and ESLint evaluates fix/suggestion callbacks on every lint pass
+ * (not only under `--fix`), so a file-writing fix would write stubs during ordinary editor/CI lint.
+ * Stub scaffolding is therefore delivered as a separate, explicit command (tracked as a follow-up).
+ *
+ * See README.md for incorrect/correct examples.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireStorybookFolderLandingPage = exports.clearLandingPageCache = exports.STORYBOOK_LANDING_PAGE_DOCS_URL = exports.STORYBOOK_LANDING_PAGE_TODO_MARKER = void 0;
+const tslib_1 = require("tslib");
+const utils_1 = require("@typescript-eslint/utils");
+const crypto = tslib_1.__importStar(require("crypto"));
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const file_utils_1 = require("../../utils/file-utils");
+const createRule = utils_1.ESLintUtils.RuleCreator(name => `https://github.com/trackunit/manager/blob/master/libs/eslint/plugin-trackunit/src/lib/rules/${name}/${name}.ts`);
+/** Canonical TODO marker. A landing page still containing this marker does NOT satisfy the rule. */
+exports.STORYBOOK_LANDING_PAGE_TODO_MARKER = "{/* TODO: storybook-folder-landing-page */}";
+/**
+ * Canonical permalink to the how-to-author doc. Single source of truth, embedded in the rule's
+ * error message so developers tripping the rule get a direct link. The `master` permalink stays
+ * stable across file moves within the (internal) repo.
+ */
+exports.STORYBOOK_LANDING_PAGE_DOCS_URL = "https://github.com/Trackunit/manager/blob/master/docs/STORYBOOK-LANDING-PAGES.md";
+/**
+ * Cache of landing-page scans, keyed by workspace root. The cached value is reused only while the
+ * current docs-file fingerprint matches, so long-lived ESLint processes pick up newly added or
+ * edited landing pages without requiring an ESLint server restart.
+ */
+const landingPageCache = new Map();
+/** Clear the module-level scan cache (primarily for tests). */
+const clearLandingPageCache = () => {
+    landingPageCache.clear();
+};
+exports.clearLandingPageCache = clearLandingPageCache;
+const SKIP_DIRECTORIES = new Set(["node_modules", "dist", ".git", ".nx"]);
+// Match `title="..."` anywhere within an opening `<Meta ...>` tag (attribute order independent).
+const META_TITLE_REGEX = /<Meta\b[^>]*?\btitle\s*=\s*("|')(.*?)\1/;
+const STORY_FILE_REGEX = /\.stories\.(js|jsx|ts|tsx)$/;
+const DOCS_MDX_REGEX = /\.docs\.mdx$/;
+/** Recursively collect absolute paths of every `*.docs.mdx` file under `dir`. */
+const collectDocsMdxFiles = (dir) => {
+    const result = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRECTORIES.has(entry.name)) {
+                result.push(...collectDocsMdxFiles(fullPath));
+            }
+        }
+        else if (DOCS_MDX_REGEX.test(entry.name)) {
+            result.push(fullPath);
+        }
+    }
+    return result;
+};
+/** Strip import lines and the `<Meta .../>` tag, leaving the documentation body. */
+const extractBody = (contents) => {
+    return contents
+        .split("\n")
+        .filter(line => !/^\s*import\s/.test(line))
+        .join("\n")
+        .replace(/<Meta\b[^>]*\/>/, "")
+        .trim();
+};
+/** Scan the workspace for `*.docs.mdx` landing pages, building a title -> entry map. */
+const scanLandingPages = (workspaceRoot) => {
+    const landingPages = new Map();
+    const hash = crypto.createHash("sha256");
+    for (const filePath of collectDocsMdxFiles(workspaceRoot).toSorted()) {
+        hash.update(filePath);
+        hash.update("\0");
+        let contents;
+        try {
+            contents = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            hash.update("unreadable");
+            hash.update("\0");
+            continue;
+        }
+        hash.update(contents);
+        hash.update("\0");
+        const match = META_TITLE_REGEX.exec(contents);
+        if (match && typeof match[2] === "string") {
+            landingPages.set(match[2], { filePath, body: extractBody(contents) });
+        }
+    }
+    return { fingerprint: hash.digest("hex"), landingPages };
+};
+/** Get landing pages from cache when the current docs-file fingerprint is unchanged. */
+const getLandingPages = (workspaceRoot) => {
+    const scan = scanLandingPages(workspaceRoot);
+    const cached = landingPageCache.get(workspaceRoot);
+    if (cached?.fingerprint === scan.fingerprint) {
+        return cached.landingPages;
+    }
+    landingPageCache.set(workspaceRoot, scan);
+    return scan.landingPages;
+};
+/** Derive ancestor folder paths from a title, dropping the story leaf. */
+const deriveFolders = (title) => {
+    const segments = title.split("/");
+    const folders = [];
+    // Drop the last segment (story leaf); accumulate prefixes for the rest.
+    for (let i = 1; i < segments.length; i++) {
+        folders.push(segments.slice(0, i).join("/"));
+    }
+    return folders;
+};
+/** A folder is satisfied by a landing page entry with non-empty body and no TODO marker. */
+const isSatisfied = (entry) => {
+    if (!entry) {
+        return false;
+    }
+    if (entry.body.length === 0) {
+        return false;
+    }
+    return !entry.body.includes(exports.STORYBOOK_LANDING_PAGE_TODO_MARKER);
+};
+/** Unwrap satisfies/as wrappers around an expression. */
+const unwrapExpression = (node) => {
+    let current = node;
+    while (current.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression || current.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
+        current = current.expression;
+    }
+    return current;
+};
+/** Extract a string-literal `title` property from an object expression, if present. */
+const getTitleFromObject = (object) => {
+    for (const property of object.properties) {
+        if (property.type === utils_1.AST_NODE_TYPES.Property &&
+            property.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+            property.key.name === "title" &&
+            property.value.type === utils_1.AST_NODE_TYPES.Literal &&
+            typeof property.value.value === "string") {
+            return property.value;
+        }
+    }
+    return null;
+};
+exports.requireStorybookFolderLandingPage = createRule({
+    name: "require-storybook-folder-landing-page",
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require a Storybook landing page (*.docs.mdx) for every ancestor folder implied by a story's title",
+        },
+        schema: [],
+        messages: {
+            // URL embedded from the single-source-of-truth const (see STORYBOOK_LANDING_PAGE_DOCS_URL).
+            missingLandingPage: `[require-storybook-folder-landing-page] Missing Storybook landing page for folder "{{folder}}". The <Meta title> must equal "{{folder}}" exactly (no extra leaf). Add a *.docs.mdx with <Meta title="{{folder}}" /> and real content. See ${exports.STORYBOOK_LANDING_PAGE_DOCS_URL} for how to author one.`,
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const currentFile = context.filename;
+        // Only analyze story files (never .docs.* or .mdx).
+        if (!STORY_FILE_REGEX.test(currentFile)) {
+            return {};
+        }
+        const nxJsonPath = (0, file_utils_1.findNearestFile)(currentFile, "nx.json");
+        if (nxJsonPath === null) {
+            return {};
+        }
+        const workspaceRoot = path.dirname(nxJsonPath);
+        const reportForObject = (titleNode, reportNode) => {
+            const title = titleNode.value;
+            if (typeof title !== "string") {
+                return;
+            }
+            const folders = deriveFolders(title);
+            if (folders.length === 0) {
+                return;
+            }
+            const landingPages = getLandingPages(workspaceRoot);
+            for (const folder of folders) {
+                const entry = landingPages.get(folder);
+                if (isSatisfied(entry)) {
+                    continue;
+                }
+                context.report({
+                    node: reportNode,
+                    messageId: "missingLandingPage",
+                    data: { folder },
+                });
+            }
+        };
+        return {
+            ExportDefaultDeclaration(node) {
+                const declaration = node.declaration;
+                // Shape 1: export default { title: "..." }
+                if (declaration.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    const titleNode = getTitleFromObject(declaration);
+                    if (titleNode) {
+                        reportForObject(titleNode, node);
+                    }
+                    return;
+                }
+                // Shape 2: const meta = { title: "..." } satisfies Meta; export default meta;
+                if (declaration.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    const variable = context.sourceCode
+                        .getScope(node)
+                        .references.find(ref => ref.identifier === declaration)?.resolved;
+                    const definition = variable?.defs[0];
+                    if (definition && definition.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator && definition.node.init) {
+                        const initializer = unwrapExpression(definition.node.init);
+                        if (initializer.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                            const titleNode = getTitleFromObject(initializer);
+                            if (titleNode) {
+                                reportForObject(titleNode, node);
+                            }
+                        }
+                    }
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=require-storybook-folder-landing-page.js.map

package/src/lib/rules-map.d.ts

@@ -82,4 +82,7 @@ export declare const rulesMap: {
     }], unknown, ESLintUtils.RuleListener> & {
         name: string;
     };
+    "require-storybook-folder-landing-page": ESLintUtils.RuleModule<"missingLandingPage", [], unknown, ESLintUtils.RuleListener> & {
+        name: string;
+    };
 };

package/src/lib/rules-map.js

@@ -18,6 +18,7 @@ const require_classname_alternatives_1 = require("./rules/require-classname-alte
 const require_component_prop_contracts_1 = require("./rules/require-component-prop-contracts/require-component-prop-contracts");
 const require_list_item_virtualization_props_1 = require("./rules/require-list-item-virtualization-props/require-list-item-virtualization-props");
 const require_optional_prop_initialization_1 = require("./rules/require-optional-prop-initialization/require-optional-prop-initialization");
+const require_storybook_folder_landing_page_1 = require("./rules/require-storybook-folder-landing-page/require-storybook-folder-landing-page");
 exports.rulesMap = {
     "component-name-matches-filename": component_name_matches_filename_1.componentNameMatchesFilename,
     "one-component-per-file": one_component_per_file_1.oneComponentPerFile,
@@ -36,5 +37,6 @@ exports.rulesMap = {
     "require-component-prop-contracts": require_component_prop_contracts_1.requireComponentPropContracts,
     "prefer-field-components": prefer_field_components_1.preferFieldComponents,
     "require-list-item-virtualization-props": require_list_item_virtualization_props_1.requireListItemVirtualizationProps,
+    "require-storybook-folder-landing-page": require_storybook_folder_landing_page_1.requireStorybookFolderLandingPage,
 };
 //# sourceMappingURL=rules-map.js.map