@alexgorbatchev/typescript-ai-policy 0.1.0

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

@@ -0,0 +1,108 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type { AstProgram, AstProgramStatement, RuleModule } from "./types.ts";
+import { dirname, join } from "node:path";
+import {
+  findDescendantFilePath,
+  getFilenameWithoutExtension,
+  isExemptSupportBasename,
+  isInStoriesDirectory,
+  isInTestsDirectory,
+} from "./helpers.ts";
+
+function readRequiredStoriesDirectoryPath(filename: string): string {
+  return join(dirname(filename), "stories");
+}
+
+function readRequiredStoryFileName(filename: string): string {
+  const sourceBaseName = getFilenameWithoutExtension(filename);
+
+  return `${sourceBaseName}.stories.tsx`;
+}
+
+type ReportNode = AstProgramStatement | TSESTree.Node;
+
+function readReportNode(program: AstProgram): ReportNode {
+  for (const statement of program.body) {
+    if (statement.type === "ExportNamedDeclaration") {
+      if (statement.exportKind === "type") {
+        continue;
+      }
+
+      if (!statement.declaration) {
+        return statement.specifiers[0] ?? statement;
+      }
+
+      if (
+        statement.declaration.type === "FunctionDeclaration" ||
+        statement.declaration.type === "ClassDeclaration" ||
+        statement.declaration.type === "TSEnumDeclaration"
+      ) {
+        return statement.declaration.id ?? statement.declaration;
+      }
+
+      if (statement.declaration.type === "VariableDeclaration") {
+        const firstDeclarator = statement.declaration.declarations[0];
+        return firstDeclarator?.id.type === "Identifier"
+          ? firstDeclarator.id
+          : (firstDeclarator ?? statement.declaration);
+      }
+
+      return statement.declaration;
+    }
+
+    if (statement.type === "ExportDefaultDeclaration" || statement.type === "TSExportAssignment") {
+      return statement;
+    }
+
+    if (statement.type === "ExportAllDeclaration" && statement.exportKind !== "type") {
+      return statement;
+    }
+  }
+
+  return program.body[0] ?? program;
+}
+
+const componentStoryFileConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require every component ownership file to have a matching "basename.stories.tsx" file somewhere under a sibling "stories/" directory',
+    },
+    schema: [],
+    messages: {
+      missingComponentStoryFile:
+        'Add a story file named "{{ requiredStoryFileName }}" somewhere under "{{ requiredStoriesDirectoryPath }}". Component ownership files must keep their Storybook coverage under a sibling "stories/" directory.',
+    },
+  },
+  create(context) {
+    if (
+      isExemptSupportBasename(context.filename) ||
+      isInStoriesDirectory(context.filename) ||
+      isInTestsDirectory(context.filename)
+    ) {
+      return {};
+    }
+
+    return {
+      Program(node: AstProgram) {
+        const requiredStoriesDirectoryPath = readRequiredStoriesDirectoryPath(context.filename);
+        const requiredStoryFileName = readRequiredStoryFileName(context.filename);
+        if (findDescendantFilePath(requiredStoriesDirectoryPath, requiredStoryFileName)) {
+          return;
+        }
+
+        context.report({
+          node: readReportNode(node),
+          messageId: "missingComponentStoryFile",
+          data: {
+            requiredStoriesDirectoryPath,
+            requiredStoryFileName,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default componentStoryFileConventionRule;

package/src/oxlint/rules/fixture-export-naming-convention.ts

@@ -0,0 +1,72 @@
+import type { RuleModule } from "./types.ts";
+import { isFactoryFunctionName, isFixtureConstName, isFixturesFile } from "./helpers.ts";
+
+const fixtureExportNamingConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Enforce fixture_ and factory_ lowerCamelCase export names in the __tests__/fixtures or stories/fixtures entrypoint",
+    },
+    schema: [],
+    messages: {
+      invalidFactoryExportName:
+        'Rename this factory export to the "factory_<lowerCamelCase>" form. Received "{{ name }}".',
+      invalidFixtureExportName:
+        'Rename this fixture export to the "fixture_<lowerCamelCase>" form. Received "{{ name }}".',
+    },
+  },
+  create(context) {
+    if (!isFixturesFile(context.filename)) {
+      return {};
+    }
+
+    return {
+      ExportNamedDeclaration(node) {
+        const declaration = node.declaration;
+        if (!declaration) {
+          return;
+        }
+
+        if (declaration.type === "VariableDeclaration" && declaration.kind === "const") {
+          declaration.declarations.forEach((declarator) => {
+            if (declarator.id.type !== "Identifier") {
+              return;
+            }
+
+            if (isFixtureConstName(declarator.id.name)) {
+              return;
+            }
+
+            context.report({
+              node: declarator.id,
+              messageId: "invalidFixtureExportName",
+              data: {
+                name: declarator.id.name,
+              },
+            });
+          });
+          return;
+        }
+
+        if (declaration.type !== "FunctionDeclaration" || !declaration.id) {
+          return;
+        }
+
+        if (isFactoryFunctionName(declaration.id.name)) {
+          return;
+        }
+
+        context.report({
+          node: declaration.id,
+          messageId: "invalidFactoryExportName",
+          data: {
+            name: declaration.id.name,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default fixtureExportNamingConventionRule;

package/src/oxlint/rules/fixture-export-type-contract.ts

@@ -0,0 +1,264 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type { AstProgram, AstVariableDeclarator, RuleModule } from "./types.ts";
+import { isFactoryFunctionName, isFixtureConstName, isFixturesFile, readChildNodes } from "./helpers.ts";
+
+type TypeContractAnalysis = {
+  hasAnyKeyword: boolean;
+  hasImportedTypeReference: boolean;
+  hasUnknownKeyword: boolean;
+};
+
+function readRootQualifiedIdentifierName(node: TSESTree.EntityName | null | undefined): string | null {
+  if (!node) {
+    return null;
+  }
+
+  if (node.type === "Identifier") {
+    return node.name;
+  }
+
+  if (node.type === "ThisExpression") {
+    return null;
+  }
+
+  return readRootQualifiedIdentifierName(node.left);
+}
+
+function readTypeContractNodesForFixtureDeclarator(declarator: AstVariableDeclarator): TSESTree.TypeNode[] {
+  const typeContractNodes: TSESTree.TypeNode[] = [];
+
+  if (declarator.id.type === "Identifier" && declarator.id.typeAnnotation) {
+    typeContractNodes.push(declarator.id.typeAnnotation.typeAnnotation);
+  }
+
+  if (declarator.init?.type === "TSSatisfiesExpression") {
+    typeContractNodes.push(declarator.init.typeAnnotation);
+  }
+
+  return typeContractNodes;
+}
+
+// Best-effort only: this rule is intentionally syntactic. It can require fixture
+// exports to reference imported type names and can reject explicit any/unknown in
+// the local type contract, but it does not resolve imported aliases transitively.
+// If an imported type eventually resolves to any/unknown elsewhere, this rule
+// will not detect that.
+function analyzeTypeContractNode(
+  typeNode: TSESTree.TypeNode,
+  importedTypeNames: ReadonlySet<string>,
+): TypeContractAnalysis {
+  const state: TypeContractAnalysis = {
+    hasImportedTypeReference: false,
+    hasAnyKeyword: false,
+    hasUnknownKeyword: false,
+  };
+
+  visitNode(typeNode);
+  return state;
+
+  function visitNode(node: TSESTree.Node | null | undefined): void {
+    if (!node) {
+      return;
+    }
+
+    if (node.type === "TSAnyKeyword") {
+      state.hasAnyKeyword = true;
+    }
+
+    if (node.type === "TSUnknownKeyword") {
+      state.hasUnknownKeyword = true;
+    }
+
+    if (node.type === "TSTypeReference") {
+      const rootQualifiedIdentifierName = readRootQualifiedIdentifierName(node.typeName);
+      if (rootQualifiedIdentifierName && importedTypeNames.has(rootQualifiedIdentifierName)) {
+        state.hasImportedTypeReference = true;
+      }
+    }
+
+    readChildNodes(node).forEach(visitNode);
+  }
+}
+
+function readImportedTypeNames(program: AstProgram): Set<string> {
+  const importedTypeNames = new Set<string>();
+
+  program.body.forEach((statement) => {
+    if (statement.type !== "ImportDeclaration") {
+      return;
+    }
+
+    statement.specifiers.forEach((specifier) => {
+      if (specifier.local.type !== "Identifier") {
+        return;
+      }
+
+      importedTypeNames.add(specifier.local.name);
+    });
+  });
+
+  return importedTypeNames;
+}
+
+const fixtureExportTypeContractRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Require __tests__/fixtures and stories/fixtures exports to use imported types and ban explicit any/unknown type contracts",
+    },
+    schema: [],
+    messages: {
+      forbiddenFactoryReturnTypeKeyword:
+        'Replace "{{ keyword }}" with an imported concrete return type for factory export "{{ name }}". Do not use "{{ keyword }}" in fixture entrypoints.',
+      forbiddenFixtureTypeKeyword:
+        'Replace "{{ keyword }}" with an imported concrete type for fixture export "{{ name }}". Do not use "{{ keyword }}" in fixture entrypoints.',
+      missingFactoryReturnTypeContract:
+        'Add an explicit return type to factory export "{{ name }}" and make that return type an imported concrete type.',
+      missingFixtureTypeContract:
+        'Add a type annotation or satisfies clause to fixture export "{{ name }}" and make it reference an imported concrete type.',
+      missingImportedFactoryReturnType:
+        'Change the return type of factory export "{{ name }}" so it references at least one imported concrete type.',
+      missingImportedFixtureType:
+        'Change the type annotation or satisfies clause of fixture export "{{ name }}" so it references at least one imported concrete type.',
+    },
+  },
+  create(context) {
+    if (!isFixturesFile(context.filename)) {
+      return {};
+    }
+
+    let importedTypeNames = new Set<string>();
+
+    return {
+      Program(program) {
+        importedTypeNames = readImportedTypeNames(program);
+      },
+      ExportNamedDeclaration(node) {
+        const declaration = node.declaration;
+        if (!declaration) {
+          return;
+        }
+
+        if (declaration.type === "VariableDeclaration") {
+          declaration.declarations.forEach((declarator) => {
+            if (declarator.id.type !== "Identifier" || !isFixtureConstName(declarator.id.name)) {
+              return;
+            }
+
+            const typeContractNodes = readTypeContractNodesForFixtureDeclarator(declarator);
+            if (typeContractNodes.length === 0) {
+              context.report({
+                node: declarator.id,
+                messageId: "missingFixtureTypeContract",
+                data: {
+                  name: declarator.id.name,
+                },
+              });
+              return;
+            }
+
+            const typeContractAnalyses = typeContractNodes.map((typeContractNode) => {
+              return analyzeTypeContractNode(typeContractNode, importedTypeNames);
+            });
+            if (typeContractAnalyses.some((typeContractAnalysis) => typeContractAnalysis.hasAnyKeyword)) {
+              context.report({
+                node: declarator.id,
+                messageId: "forbiddenFixtureTypeKeyword",
+                data: {
+                  name: declarator.id.name,
+                  keyword: "any",
+                },
+              });
+              return;
+            }
+
+            if (typeContractAnalyses.some((typeContractAnalysis) => typeContractAnalysis.hasUnknownKeyword)) {
+              context.report({
+                node: declarator.id,
+                messageId: "forbiddenFixtureTypeKeyword",
+                data: {
+                  name: declarator.id.name,
+                  keyword: "unknown",
+                },
+              });
+              return;
+            }
+
+            if (typeContractAnalyses.some((typeContractAnalysis) => typeContractAnalysis.hasImportedTypeReference)) {
+              return;
+            }
+
+            context.report({
+              node: declarator.id,
+              messageId: "missingImportedFixtureType",
+              data: {
+                name: declarator.id.name,
+              },
+            });
+          });
+          return;
+        }
+
+        if (
+          declaration.type !== "FunctionDeclaration" ||
+          !declaration.id ||
+          !isFactoryFunctionName(declaration.id.name)
+        ) {
+          return;
+        }
+
+        const returnTypeNode = declaration.returnType?.typeAnnotation;
+        if (!returnTypeNode) {
+          context.report({
+            node: declaration.id,
+            messageId: "missingFactoryReturnTypeContract",
+            data: {
+              name: declaration.id.name,
+            },
+          });
+          return;
+        }
+
+        const returnTypeAnalysis = analyzeTypeContractNode(returnTypeNode, importedTypeNames);
+        if (returnTypeAnalysis.hasAnyKeyword) {
+          context.report({
+            node: declaration.id,
+            messageId: "forbiddenFactoryReturnTypeKeyword",
+            data: {
+              name: declaration.id.name,
+              keyword: "any",
+            },
+          });
+          return;
+        }
+
+        if (returnTypeAnalysis.hasUnknownKeyword) {
+          context.report({
+            node: declaration.id,
+            messageId: "forbiddenFactoryReturnTypeKeyword",
+            data: {
+              name: declaration.id.name,
+              keyword: "unknown",
+            },
+          });
+          return;
+        }
+
+        if (returnTypeAnalysis.hasImportedTypeReference) {
+          return;
+        }
+
+        context.report({
+          node: declaration.id,
+          messageId: "missingImportedFactoryReturnType",
+          data: {
+            name: declaration.id.name,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default fixtureExportTypeContractRule;

package/src/oxlint/rules/fixture-file-contract.ts

@@ -0,0 +1,91 @@
+import type { RuleModule } from "./types.ts";
+import { isFixturesFile } from "./helpers.ts";
+
+const fixtureFileContractRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Only allow direct const fixture exports and function factory exports in nested "fixtures.ts" or "fixtures.tsx" entrypoints under "__tests__/" or "stories/"',
+    },
+    schema: [],
+    messages: {
+      unexpectedDefaultExport:
+        'Remove the default export. A nested "fixtures.ts" or "fixtures.tsx" entrypoint under "__tests__/" or "stories/" must use only named exports.',
+      unexpectedExportDeclaration:
+        'Replace this export with either "export const fixture_* = ..." or "export function factory_*() { ... }" in a nested "fixtures.ts" or "fixtures.tsx" entrypoint under "__tests__/" or "stories/".',
+      unexpectedExportList:
+        "Inline the exported declaration in this nested fixture entrypoint. Do not use export lists or re-exports here.",
+      unexpectedExportPattern:
+        'Bind the exported const to a direct identifier, for example "export const fixture_user = ...". Do not export destructuring patterns from a nested fixture entrypoint.',
+      unexpectedVariableKind:
+        'Change this exported "{{ kind }}" declaration to "const". Nested fixture entrypoints allow only exported const declarations.',
+    },
+  },
+  create(context) {
+    if (!isFixturesFile(context.filename)) {
+      return {};
+    }
+
+    return {
+      ExportAllDeclaration(node) {
+        context.report({
+          node,
+          messageId: "unexpectedExportList",
+        });
+      },
+      ExportDefaultDeclaration(node) {
+        context.report({
+          node,
+          messageId: "unexpectedDefaultExport",
+        });
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source || !node.declaration) {
+          context.report({
+            node,
+            messageId: "unexpectedExportList",
+          });
+          return;
+        }
+
+        const declaration = node.declaration;
+        if (declaration.type === "VariableDeclaration") {
+          if (declaration.kind !== "const") {
+            context.report({
+              node: declaration,
+              messageId: "unexpectedVariableKind",
+              data: {
+                kind: declaration.kind,
+              },
+            });
+            return;
+          }
+
+          declaration.declarations.forEach((declarator) => {
+            if (declarator.id.type === "Identifier") {
+              return;
+            }
+
+            context.report({
+              node: declarator.id,
+              messageId: "unexpectedExportPattern",
+            });
+          });
+          return;
+        }
+
+        if (declaration.type === "FunctionDeclaration" && declaration.id) {
+          return;
+        }
+
+        context.report({
+          node: declaration,
+          messageId: "unexpectedExportDeclaration",
+        });
+      },
+    };
+  },
+};
+
+export default fixtureFileContractRule;

package/src/oxlint/rules/fixture-import-path-convention.ts

@@ -0,0 +1,125 @@
+import type { AstImportClause, RuleModule } from "./types.ts";
+import { isAllowedFixturesImportPath, isFixtureConsumerFile, isFixtureLikeName } from "./helpers.ts";
+
+type ImportSpecifierNames = {
+  importedName: string | null;
+  isNamedImport: boolean;
+  localName: string;
+};
+
+function readImportSpecifierNames(specifier: AstImportClause): ImportSpecifierNames {
+  if (specifier.type === "ImportSpecifier") {
+    return {
+      importedName:
+        specifier.imported.type === "Identifier" ? specifier.imported.name : String(specifier.imported.value),
+      localName: specifier.local.type === "Identifier" ? specifier.local.name : "",
+      isNamedImport: true,
+    };
+  }
+
+  return {
+    importedName: null,
+    localName: specifier.local.type === "Identifier" ? specifier.local.name : "",
+    isNamedImport: false,
+  };
+}
+
+const fixtureImportPathConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require test and story files to import fixture_ and factory_ bindings only as named imports from a relative "fixtures" module inside the same "__tests__/" or "stories/" tree',
+    },
+    schema: [],
+    messages: {
+      invalidFixturesImportAlias:
+        'Import "{{ name }}" from a relative "fixtures" module without renaming it. The local binding must stay "{{ name }}".',
+      invalidFixturesImportName:
+        'Only named imports that start with "fixture_" or "factory_" are allowed from a relative "fixtures" module. Remove or rename "{{ name }}".',
+      invalidFixturesImportPath:
+        'Change this import so "{{ name }}" comes from a relative "fixtures" module inside the same "__tests__/" or "stories/" tree.',
+      invalidFixturesImportStyle:
+        'Rewrite this as a named import from a relative "fixtures" module, for example: import { fixture_name } from "./fixtures".',
+    },
+  },
+  create(context) {
+    if (!isFixtureConsumerFile(context.filename)) {
+      return {};
+    }
+
+    return {
+      ImportDeclaration(node) {
+        const importPath = typeof node.source.value === "string" ? node.source.value : "";
+
+        if (isAllowedFixturesImportPath(importPath, context.filename)) {
+          if (node.specifiers.length === 0) {
+            context.report({
+              node,
+              messageId: "invalidFixturesImportStyle",
+            });
+            return;
+          }
+
+          node.specifiers.forEach((specifier) => {
+            const { importedName, localName, isNamedImport } = readImportSpecifierNames(specifier);
+
+            if (!isNamedImport) {
+              context.report({
+                node: specifier,
+                messageId: "invalidFixturesImportStyle",
+              });
+              return;
+            }
+
+            if (!importedName || !isFixtureLikeName(importedName)) {
+              context.report({
+                node: specifier,
+                messageId: "invalidFixturesImportName",
+                data: {
+                  name: importedName ?? localName,
+                },
+              });
+              return;
+            }
+
+            if (localName !== importedName) {
+              context.report({
+                node: specifier,
+                messageId: "invalidFixturesImportAlias",
+                data: {
+                  name: importedName,
+                },
+              });
+            }
+          });
+
+          return;
+        }
+
+        node.specifiers.forEach((specifier) => {
+          const { importedName, localName, isNamedImport } = readImportSpecifierNames(specifier);
+          const fixtureLikeName = isNamedImport
+            ? [importedName, localName].find((name) => typeof name === "string" && isFixtureLikeName(name))
+            : isFixtureLikeName(localName)
+              ? localName
+              : null;
+
+          if (!fixtureLikeName) {
+            return;
+          }
+
+          context.report({
+            node: specifier,
+            messageId: "invalidFixturesImportPath",
+            data: {
+              name: fixtureLikeName,
+            },
+          });
+        });
+      },
+    };
+  },
+};
+
+export default fixtureImportPathConventionRule;