@alexgorbatchev/typescript-ai-policy 0.1.0

package/src/oxlint/rules/single-fixture-entrypoint.ts

@@ -0,0 +1,142 @@
+import type { RuleModule } from "./types.ts";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readPathFromStoriesDirectory, readPathFromTestsDirectory } from "./helpers.ts";
+
+const FIXTURE_ENTRYPOINT_CANDIDATE_KEYS = ["fixtures.ts", "fixtures.tsx", "fixtures/"];
+
+type FixtureDirectoryMatch = {
+  directoryLabel: string;
+  relativePath: string;
+};
+
+function readFixtureDirectoryMatch(filename: string): FixtureDirectoryMatch | null {
+  const testsRelativePath = readPathFromTestsDirectory(filename);
+  if (testsRelativePath !== null) {
+    return {
+      directoryLabel: "__tests__",
+      relativePath: testsRelativePath,
+    };
+  }
+
+  const storiesRelativePath = readPathFromStoriesDirectory(filename);
+  if (storiesRelativePath !== null) {
+    return {
+      directoryLabel: "stories",
+      relativePath: storiesRelativePath,
+    };
+  }
+
+  return null;
+}
+
+function readFixtureEntrypointCandidateKey(filename: string): string | null {
+  const fixtureDirectoryMatch = readFixtureDirectoryMatch(filename);
+  if (!fixtureDirectoryMatch) {
+    return null;
+  }
+
+  const relativePathSegments = fixtureDirectoryMatch.relativePath.split("/").filter(Boolean);
+  const lastPathSegment = relativePathSegments.at(-1);
+
+  if (lastPathSegment === "fixtures.ts" || lastPathSegment === "fixtures.tsx") {
+    return lastPathSegment;
+  }
+
+  if (relativePathSegments.includes("fixtures")) {
+    return "fixtures/";
+  }
+
+  return null;
+}
+
+function readFixtureSupportDirectoryPath(filename: string): string | null {
+  const fixtureDirectoryMatch = readFixtureDirectoryMatch(filename);
+  if (!fixtureDirectoryMatch) {
+    return null;
+  }
+
+  const relativePathSegments = fixtureDirectoryMatch.relativePath.split("/").filter(Boolean);
+  const fixtureFileIndex = relativePathSegments.findLastIndex(
+    (pathSegment) => pathSegment === "fixtures.ts" || pathSegment === "fixtures.tsx",
+  );
+  const fixtureDirectoryIndex = relativePathSegments.lastIndexOf("fixtures");
+  const fixtureSegmentIndex = fixtureFileIndex === -1 ? fixtureDirectoryIndex : fixtureFileIndex;
+  if (fixtureSegmentIndex === -1) {
+    return null;
+  }
+
+  const levelsToAscend = relativePathSegments.length - fixtureSegmentIndex;
+
+  let currentPath = filename;
+  for (let levelIndex = 0; levelIndex < levelsToAscend; levelIndex += 1) {
+    currentPath = dirname(currentPath);
+  }
+
+  return currentPath;
+}
+
+function readFixtureSupportDirectoryLabel(filename: string): string | null {
+  return readFixtureDirectoryMatch(filename)?.directoryLabel ?? null;
+}
+
+function isExistingDirectory(path: string): boolean {
+  return existsSync(path) && statSync(path).isDirectory();
+}
+
+function readExistingFixtureEntrypointCandidateKeys(fixtureSupportDirectoryPath: string): string[] {
+  return FIXTURE_ENTRYPOINT_CANDIDATE_KEYS.filter((candidateKey) => {
+    if (candidateKey === "fixtures/") {
+      return isExistingDirectory(join(fixtureSupportDirectoryPath, "fixtures"));
+    }
+
+    return existsSync(join(fixtureSupportDirectoryPath, candidateKey));
+  });
+}
+
+const singleFixtureEntrypointRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Allow only one fixture entrypoint shape per fixture-support directory under "__tests__" or "stories" so imports from "./fixtures" stay unambiguous',
+    },
+    schema: [],
+    messages: {
+      conflictingFixtureEntrypoints:
+        'Keep exactly one fixture entrypoint shape in this fixture-support directory under "{{ directoryLabel }}" so "./fixtures" resolves unambiguously. Remove all but one of: {{ entries }}.',
+    },
+  },
+  create(context) {
+    const currentCandidateKey = readFixtureEntrypointCandidateKey(context.filename);
+    if (!currentCandidateKey) {
+      return {};
+    }
+
+    const fixtureSupportDirectoryPath = readFixtureSupportDirectoryPath(context.filename);
+    const directoryLabel = readFixtureSupportDirectoryLabel(context.filename);
+    if (!fixtureSupportDirectoryPath || !directoryLabel) {
+      return {};
+    }
+
+    const existingCandidateKeys = readExistingFixtureEntrypointCandidateKeys(fixtureSupportDirectoryPath);
+    if (existingCandidateKeys.length <= 1 || currentCandidateKey !== existingCandidateKeys[0]) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        context.report({
+          node,
+          messageId: "conflictingFixtureEntrypoints",
+          data: {
+            directoryLabel,
+            entries: existingCandidateKeys.join(", "),
+          },
+        });
+      },
+    };
+  },
+};
+
+export default singleFixtureEntrypointRule;

package/src/oxlint/rules/stories-directory-file-convention.ts

@@ -0,0 +1,55 @@
+import type { RuleModule } from "./types.ts";
+import { isInStoriesDirectory, readPathFromStoriesDirectory } from "./helpers.ts";
+
+const ALLOWED_ROOT_STORY_FILES_PATTERN = /^[^/]+\.stories\.tsx$/u;
+const ALLOWED_SUPPORT_FILES = new Set(["fixtures.ts", "fixtures.tsx", "helpers.ts", "helpers.tsx"]);
+
+function isAllowedStoriesDirectoryPath(relativePath: string): boolean {
+  if (relativePath.startsWith("fixtures/")) {
+    return true;
+  }
+
+  if (ALLOWED_SUPPORT_FILES.has(relativePath)) {
+    return true;
+  }
+
+  return ALLOWED_ROOT_STORY_FILES_PATTERN.test(relativePath);
+}
+
+const storiesDirectoryFileConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description: "Restrict stories directory contents to story files, helpers, and fixtures",
+    },
+    schema: [],
+    messages: {
+      invalidStoriesDirectoryFile:
+        'Move or rename "{{ relativePath }}". A "stories" directory may contain only "*.stories.tsx", "helpers.ts", "helpers.tsx", "fixtures.ts", "fixtures.tsx", or files under "fixtures/".',
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        if (!isInStoriesDirectory(context.filename)) {
+          return;
+        }
+
+        const relativePath = readPathFromStoriesDirectory(context.filename);
+        if (!relativePath || isAllowedStoriesDirectoryPath(relativePath)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "invalidStoriesDirectoryFile",
+          data: {
+            relativePath,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default storiesDirectoryFileConventionRule;

package/src/oxlint/rules/story-export-contract.ts

@@ -0,0 +1,343 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type { AstProgram, RuleModule } from "./types.ts";
+import { getStorySourceBaseName, isPascalCase, unwrapExpression, unwrapTypeScriptExpression } from "./helpers.ts";
+
+type StoryExportRecord = {
+  exportedName: string;
+  kind: "declaration" | "specifier";
+  localName: string;
+  node: TSESTree.ExportSpecifier | TSESTree.VariableDeclarator;
+};
+
+type StoryCandidateEntry = {
+  declaration: TSESTree.VariableDeclaration;
+  declarator: TSESTree.VariableDeclarator & { id: TSESTree.Identifier; init: TSESTree.Expression };
+  exports: StoryExportRecord[];
+  name: string;
+};
+
+function readDefaultExportDeclaration(program: AstProgram): TSESTree.ExportDefaultDeclaration | null {
+  return program.body.find((statement) => statement.type === "ExportDefaultDeclaration") ?? null;
+}
+
+function readExpectedComponentNameFromStoryFilename(filename: string): string | null {
+  const storySourceBaseName = getStorySourceBaseName(filename);
+  if (!storySourceBaseName) {
+    return null;
+  }
+
+  if (isPascalCase(storySourceBaseName)) {
+    return storySourceBaseName;
+  }
+
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(storySourceBaseName)) {
+    return null;
+  }
+
+  return storySourceBaseName
+    .split("-")
+    .map((segment) => `${segment[0]?.toUpperCase() ?? ""}${segment.slice(1)}`)
+    .join("");
+}
+
+function isStoryTypeReference(typeAnnotation: TSESTree.TypeNode | null | undefined): boolean {
+  return (
+    typeAnnotation?.type === "TSTypeReference" &&
+    typeAnnotation.typeName.type === "Identifier" &&
+    typeAnnotation.typeName.name === "Story" &&
+    !typeAnnotation.typeArguments
+  );
+}
+
+function readStoryAssertionTypeAnnotation(expression: TSESTree.Expression): TSESTree.TypeNode | null {
+  const unwrappedExpression = unwrapExpression(expression);
+  if (unwrappedExpression.type !== "TSAsExpression" && unwrappedExpression.type !== "TSSatisfiesExpression") {
+    return null;
+  }
+
+  return unwrappedExpression.typeAnnotation;
+}
+
+function readStoryObjectExpression(expression: TSESTree.Expression): TSESTree.ObjectExpression | null {
+  const unwrappedExpression = unwrapTypeScriptExpression(expression);
+
+  return unwrappedExpression.type === "ObjectExpression" ? unwrappedExpression : null;
+}
+
+function readPropertyName(property: TSESTree.Property): string | null {
+  if (property.computed) {
+    return null;
+  }
+
+  if (property.key.type === "Identifier") {
+    return property.key.name;
+  }
+
+  if (property.key.type === "Literal" && typeof property.key.value === "string") {
+    return property.key.value;
+  }
+
+  return null;
+}
+
+function hasPlayProperty(expression: TSESTree.Expression): boolean {
+  const storyObjectExpression = readStoryObjectExpression(expression);
+  if (!storyObjectExpression) {
+    return false;
+  }
+
+  return storyObjectExpression.properties.some((property) => {
+    return property.type === "Property" && readPropertyName(property) === "play";
+  });
+}
+
+function isStoryDeclarator(declarator: TSESTree.VariableDeclarator): declarator is StoryCandidateEntry["declarator"] {
+  return declarator.id.type === "Identifier" && declarator.init !== null;
+}
+
+function readTopLevelStoryCandidateEntries(program: AstProgram): StoryCandidateEntry[] {
+  const entriesByName = new Map<string, StoryCandidateEntry>();
+
+  function upsertEntry(
+    variableDeclaration: TSESTree.VariableDeclaration,
+    declarator: TSESTree.VariableDeclarator,
+  ): StoryCandidateEntry | null {
+    if (!isStoryDeclarator(declarator)) {
+      return null;
+    }
+
+    const existingEntry = entriesByName.get(declarator.id.name);
+    if (existingEntry) {
+      return existingEntry;
+    }
+
+    const entry: StoryCandidateEntry = {
+      name: declarator.id.name,
+      declaration: variableDeclaration,
+      declarator,
+      exports: [],
+    };
+
+    entriesByName.set(entry.name, entry);
+    return entry;
+  }
+
+  function recordVariableDeclaration(variableDeclaration: TSESTree.VariableDeclaration, isDirectExport: boolean): void {
+    variableDeclaration.declarations.forEach((declarator) => {
+      const entry = upsertEntry(variableDeclaration, declarator);
+      if (!entry || !isDirectExport) {
+        return;
+      }
+
+      entry.exports.push({
+        kind: "declaration",
+        localName: entry.name,
+        exportedName: entry.name,
+        node: declarator,
+      });
+    });
+  }
+
+  program.body.forEach((statement) => {
+    if (statement.type === "VariableDeclaration") {
+      recordVariableDeclaration(statement, false);
+      return;
+    }
+
+    if (
+      statement.type === "ExportNamedDeclaration" &&
+      statement.exportKind !== "type" &&
+      statement.declaration?.type === "VariableDeclaration"
+    ) {
+      recordVariableDeclaration(statement.declaration, true);
+    }
+  });
+
+  program.body.forEach((statement) => {
+    if (
+      statement.type !== "ExportNamedDeclaration" ||
+      statement.declaration ||
+      statement.source ||
+      statement.exportKind === "type"
+    ) {
+      return;
+    }
+
+    statement.specifiers.forEach((specifier) => {
+      if (
+        specifier.type !== "ExportSpecifier" ||
+        specifier.exportKind === "type" ||
+        specifier.local.type !== "Identifier" ||
+        specifier.exported.type !== "Identifier"
+      ) {
+        return;
+      }
+
+      const entry = entriesByName.get(specifier.local.name);
+      if (!entry) {
+        return;
+      }
+
+      entry.exports.push({
+        kind: "specifier",
+        localName: specifier.local.name,
+        exportedName: specifier.exported.name,
+        node: specifier,
+      });
+    });
+  });
+
+  return [...entriesByName.values()];
+}
+
+function isStoryCandidateEntry(entry: StoryCandidateEntry, metaBindingName: string | null): boolean {
+  if (!entry.declarator.init || entry.name === metaBindingName) {
+    return false;
+  }
+
+  if (!readStoryObjectExpression(entry.declarator.init)) {
+    return false;
+  }
+
+  const hasStoryTypeContract =
+    isStoryTypeReference(entry.declarator.id.typeAnnotation?.typeAnnotation) ||
+    isStoryTypeReference(readStoryAssertionTypeAnnotation(entry.declarator.init));
+
+  return entry.exports.length > 0 || hasStoryTypeContract;
+}
+
+const storyExportContractRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Require Storybook story exports to use `const StoryName: Story = { ... }` bindings, enforce the single-vs-multiple export contract, and require a `play` property on every exported story",
+    },
+    schema: [],
+    messages: {
+      missingStoryExport:
+        "Add at least one exported story object after the default meta. Component story files must export Storybook stories for the sibling component.",
+      unexportedStoryBinding:
+        "Export this story binding. Story objects in `*.stories.tsx` files must be exported so Storybook can load them.",
+      missingStoryTypeAnnotation:
+        "Annotate this story binding as `: Story`. Story objects must use a type annotation instead of inference.",
+      unexpectedStoryTypeAssertion:
+        "Replace this story object assertion with a const type annotation: `const StoryName: Story = { ... };`.",
+      missingStoryPlay:
+        "Add a `play` property to this story object. Component stories are the required interaction-test surface for the sibling component.",
+      invalidSingleStoryExportShape:
+        "Use the single-story export shape exactly: `const Default: Story = { ... }; export { Default as {{ componentName }} };`.",
+      invalidMultiStoryExportShape:
+        "When a story file exports multiple stories, export each one directly as `export const StoryName: Story = { ... };`. Do not re-export local story bindings through an export list.",
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const defaultExportDeclaration = readDefaultExportDeclaration(node);
+        const metaBindingName =
+          defaultExportDeclaration?.declaration.type === "Identifier"
+            ? defaultExportDeclaration.declaration.name
+            : null;
+        const storyEntries = readTopLevelStoryCandidateEntries(node).filter((entry) => {
+          return isStoryCandidateEntry(entry, metaBindingName);
+        });
+
+        if (storyEntries.length === 0) {
+          context.report({
+            node,
+            messageId: "missingStoryExport",
+          });
+          return;
+        }
+
+        storyEntries.forEach((storyEntry) => {
+          if (storyEntry.exports.length === 0) {
+            context.report({
+              node: storyEntry.declarator.id,
+              messageId: "unexportedStoryBinding",
+            });
+          }
+
+          const storyAssertionTypeAnnotation = readStoryAssertionTypeAnnotation(storyEntry.declarator.init);
+          if (storyAssertionTypeAnnotation && isStoryTypeReference(storyAssertionTypeAnnotation)) {
+            context.report({
+              node: storyEntry.declarator.init,
+              messageId: "unexpectedStoryTypeAssertion",
+            });
+          }
+
+          if (!isStoryTypeReference(storyEntry.declarator.id.typeAnnotation?.typeAnnotation)) {
+            context.report({
+              node: storyEntry.declarator.id,
+              messageId: "missingStoryTypeAnnotation",
+            });
+          }
+
+          if (!hasPlayProperty(storyEntry.declarator.init)) {
+            context.report({
+              node: readStoryObjectExpression(storyEntry.declarator.init) ?? storyEntry.declarator,
+              messageId: "missingStoryPlay",
+            });
+          }
+        });
+
+        const exportedStoryEntries = storyEntries.filter((storyEntry) => storyEntry.exports.length > 0);
+        if (exportedStoryEntries.length === 0) {
+          context.report({
+            node,
+            messageId: "missingStoryExport",
+          });
+          return;
+        }
+
+        if (exportedStoryEntries.length === 1) {
+          const singleStoryEntry = exportedStoryEntries[0];
+          if (!singleStoryEntry) {
+            return;
+          }
+
+          const expectedComponentName = readExpectedComponentNameFromStoryFilename(context.filename) ?? "ComponentName";
+          const firstExport = singleStoryEntry.exports[0];
+          const hasValidSingleStoryExportShape =
+            singleStoryEntry.name === "Default" &&
+            singleStoryEntry.exports.length === 1 &&
+            firstExport?.kind === "specifier" &&
+            firstExport.localName === "Default" &&
+            firstExport.exportedName === expectedComponentName;
+
+          if (!hasValidSingleStoryExportShape) {
+            context.report({
+              node: firstExport?.node ?? singleStoryEntry.declarator,
+              messageId: "invalidSingleStoryExportShape",
+              data: {
+                componentName: expectedComponentName,
+              },
+            });
+          }
+
+          return;
+        }
+
+        exportedStoryEntries.forEach((storyEntry) => {
+          const firstExport = storyEntry.exports[0];
+          const hasValidMultiStoryExportShape =
+            storyEntry.exports.length === 1 &&
+            firstExport?.kind === "declaration" &&
+            firstExport.exportedName === storyEntry.name;
+
+          if (hasValidMultiStoryExportShape) {
+            return;
+          }
+
+          context.report({
+            node: firstExport?.node ?? storyEntry.declarator,
+            messageId: "invalidMultiStoryExportShape",
+          });
+        });
+      },
+    };
+  },
+};
+
+export default storyExportContractRule;

package/src/oxlint/rules/story-file-location-convention.ts

@@ -0,0 +1,64 @@
+import type { RuleModule } from "./types.ts";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getStorySourceBaseName, readPathFromStoriesDirectory, readRootPathBeforeDirectory } from "./helpers.ts";
+
+function readRequiredSiblingComponentFilePath(filename: string): string | null {
+  const storySourceBaseName = getStorySourceBaseName(filename);
+  if (!storySourceBaseName) {
+    return null;
+  }
+
+  const siblingDirectoryPath = readRootPathBeforeDirectory(filename, "stories");
+  if (siblingDirectoryPath === null) {
+    return null;
+  }
+
+  return join(siblingDirectoryPath, `${storySourceBaseName}.tsx`);
+}
+
+const storyFileLocationConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require Storybook files to live somewhere under a sibling "stories/" directory and match a sibling component ownership file basename',
+    },
+    schema: [],
+    messages: {
+      invalidStoryFileLocation:
+        'Move this story file under a "stories/" directory. Storybook files must not live outside a sibling "stories/" tree.',
+      missingSiblingComponent:
+        'Rename or move this story so it matches an existing sibling component ownership file. Expected "{{ requiredComponentFilePath }}" to exist for this story file.',
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const relativeStoryPath = readPathFromStoriesDirectory(context.filename);
+        if (relativeStoryPath === null) {
+          context.report({
+            node,
+            messageId: "invalidStoryFileLocation",
+          });
+          return;
+        }
+
+        const requiredComponentFilePath = readRequiredSiblingComponentFilePath(context.filename);
+        if (requiredComponentFilePath === null || existsSync(requiredComponentFilePath)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "missingSiblingComponent",
+          data: {
+            requiredComponentFilePath,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default storyFileLocationConventionRule;