@alexgorbatchev/typescript-ai-policy 0.1.0

package/src/oxlint/rules/story-meta-type-annotation.ts

@@ -0,0 +1,129 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type { AstProgram, RuleModule } from "./types.ts";
+import { unwrapExpression } from "./helpers.ts";
+
+type MetaBinding = {
+  declaration: TSESTree.VariableDeclaration;
+  declarator: TSESTree.VariableDeclarator;
+};
+
+function readDefaultExportDeclaration(program: AstProgram): TSESTree.ExportDefaultDeclaration | null {
+  return program.body.find((statement) => statement.type === "ExportDefaultDeclaration") ?? null;
+}
+
+function readTopLevelVariableDeclarator(program: AstProgram, name: string): MetaBinding | null {
+  for (const statement of program.body) {
+    if (statement.type !== "VariableDeclaration") {
+      continue;
+    }
+
+    for (const declarator of statement.declarations) {
+      if (declarator.id.type === "Identifier" && declarator.id.name === name) {
+        return {
+          declaration: statement,
+          declarator,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+function isMetaTypeReference(typeAnnotation: TSESTree.TypeNode | null | undefined): boolean {
+  if (typeAnnotation?.type !== "TSTypeReference") {
+    return false;
+  }
+
+  if (typeAnnotation.typeName.type !== "Identifier" || typeAnnotation.typeName.name !== "Meta") {
+    return false;
+  }
+
+  const metaTypeArguments = typeAnnotation.typeArguments?.params ?? [];
+  if (metaTypeArguments.length !== 1) {
+    return false;
+  }
+
+  return metaTypeArguments[0]?.type === "TSTypeQuery";
+}
+
+function readMetaAssertionTypeAnnotation(expression: TSESTree.Expression): TSESTree.TypeNode | null {
+  const unwrappedExpression = unwrapExpression(expression);
+  if (unwrappedExpression.type !== "TSAsExpression" && unwrappedExpression.type !== "TSSatisfiesExpression") {
+    return null;
+  }
+
+  return unwrappedExpression.typeAnnotation;
+}
+
+const storyMetaTypeAnnotationRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require Storybook files to default-export a top-level const meta binding typed as "Meta<typeof ComponentName>" and ban meta object assertions',
+    },
+    schema: [],
+    messages: {
+      invalidMetaBinding:
+        "Bind the default Storybook meta as a top-level const object and export that identifier: `const meta: Meta<typeof ComponentName> = { ... }; export default meta;`.",
+      missingMetaTypeAnnotation:
+        "Annotate the meta binding as `Meta<typeof ComponentName>`. Storybook meta objects must use a type annotation on the const binding instead of inference.",
+      unexpectedMetaTypeAssertion:
+        "Replace this meta object assertion with a const type annotation: `const meta: Meta<typeof ComponentName> = { ... };`.",
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const defaultExportDeclaration = readDefaultExportDeclaration(node);
+        if (!defaultExportDeclaration || defaultExportDeclaration.declaration.type !== "Identifier") {
+          context.report({
+            node: defaultExportDeclaration ?? node,
+            messageId: "invalidMetaBinding",
+          });
+          return;
+        }
+
+        const metaBinding = readTopLevelVariableDeclarator(node, defaultExportDeclaration.declaration.name);
+        if (!metaBinding || metaBinding.declaration.kind !== "const" || !metaBinding.declarator.init) {
+          context.report({
+            node: defaultExportDeclaration,
+            messageId: "invalidMetaBinding",
+          });
+          return;
+        }
+
+        const metaInitializer = unwrapExpression(metaBinding.declarator.init);
+        if (
+          metaInitializer.type !== "ObjectExpression" &&
+          metaInitializer.type !== "TSAsExpression" &&
+          metaInitializer.type !== "TSSatisfiesExpression"
+        ) {
+          context.report({
+            node: metaBinding.declarator,
+            messageId: "invalidMetaBinding",
+          });
+          return;
+        }
+
+        const metaAssertionTypeAnnotation = readMetaAssertionTypeAnnotation(metaBinding.declarator.init);
+        if (metaAssertionTypeAnnotation && isMetaTypeReference(metaAssertionTypeAnnotation)) {
+          context.report({
+            node: metaBinding.declarator.init,
+            messageId: "unexpectedMetaTypeAssertion",
+          });
+        }
+
+        if (!isMetaTypeReference(metaBinding.declarator.id.typeAnnotation?.typeAnnotation)) {
+          context.report({
+            node: metaBinding.declarator.id,
+            messageId: "missingMetaTypeAnnotation",
+          });
+        }
+      },
+    };
+  },
+};
+
+export default storyMetaTypeAnnotationRule;

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

@@ -0,0 +1,115 @@
+import type { AstExpression, AstProgram, AstProgramStatement, RuleModule } from "./types.ts";
+import { getBaseName, isInTestsDirectory } from "./helpers.ts";
+
+const TEST_FRAMEWORK_MODULES = new Set(["@jest/globals", "bun:test", "node:test", "vitest"]);
+const TEST_IMPORT_NAMES = new Set(["describe", "it", "test"]);
+const REQUIRED_TEST_FILE_NAME_PATTERN = /\.test\.tsx?$/u;
+const SPEC_TEST_FILE_NAME_PATTERN = /\.spec\.tsx?$/u;
+
+type ProgramReportNode = AstProgram | AstProgramStatement;
+
+function readCallTargetName(node: AstExpression): string | null {
+  if (node.type === "Identifier") {
+    return node.name;
+  }
+
+  if (
+    node.type === "MemberExpression" &&
+    !node.computed &&
+    node.object.type === "Identifier" &&
+    node.property.type === "Identifier"
+  ) {
+    return node.object.name;
+  }
+
+  return null;
+}
+
+function readProgramReportNode(node: AstProgram): ProgramReportNode {
+  return node.body[0] ?? node;
+}
+
+const testFileLocationConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require non-.spec test files to live under a sibling "__tests__/" directory and use the .test.ts/.test.tsx suffix',
+    },
+    schema: [],
+    messages: {
+      invalidTestFileName: 'Rename this file to match the "*.test.ts" or "*.test.tsx" pattern.',
+      missingTestsDirectory:
+        'Move this test file into a sibling "__tests__/" directory. Misplaced tests belong at "__tests__/basename.test.ts[x]" next to the source they cover.',
+    },
+  },
+  create(context) {
+    const testFunctionNames = new Set();
+    let hasTestDefinitionCall = false;
+
+    return {
+      ImportDeclaration(node) {
+        if (!TEST_FRAMEWORK_MODULES.has(String(node.source?.value ?? ""))) {
+          return;
+        }
+
+        node.specifiers.forEach((specifier) => {
+          if (specifier.type !== "ImportSpecifier") {
+            return;
+          }
+
+          if (specifier.imported.type !== "Identifier" || specifier.local.type !== "Identifier") {
+            return;
+          }
+
+          if (!TEST_IMPORT_NAMES.has(specifier.imported.name)) {
+            return;
+          }
+
+          testFunctionNames.add(specifier.local.name);
+        });
+      },
+      CallExpression(node) {
+        const callTargetName = readCallTargetName(node.callee);
+        if (!callTargetName) {
+          return;
+        }
+
+        if (!testFunctionNames.has(callTargetName)) {
+          return;
+        }
+
+        hasTestDefinitionCall = true;
+      },
+      "Program:exit"(node) {
+        const baseName = getBaseName(context.filename);
+        if (SPEC_TEST_FILE_NAME_PATTERN.test(baseName)) {
+          return;
+        }
+
+        const looksLikeTestFile = hasTestDefinitionCall || REQUIRED_TEST_FILE_NAME_PATTERN.test(baseName);
+        if (!looksLikeTestFile) {
+          return;
+        }
+
+        const reportNode = readProgramReportNode(node);
+
+        if (!isInTestsDirectory(context.filename)) {
+          context.report({
+            node: reportNode,
+            messageId: "missingTestsDirectory",
+          });
+        }
+
+        if (!REQUIRED_TEST_FILE_NAME_PATTERN.test(baseName)) {
+          context.report({
+            node: reportNode,
+            messageId: "invalidTestFileName",
+          });
+        }
+      },
+    };
+  },
+};
+
+export default testFileLocationConventionRule;

package/src/oxlint/rules/testid-naming-convention.ts

@@ -0,0 +1,63 @@
+import type { RuleModule } from "./types.ts";
+import { getComponentNameFromAncestors, getFilenameWithoutExtension, readJsxAttributeName } from "./helpers.ts";
+
+const testIdNamingConventionRule: RuleModule = {
+  meta: {
+    type: "suggestion" as const,
+    docs: {
+      description: "Enforce React test ids to use ComponentName for roots and ComponentName--thing for children",
+    },
+    messages: {
+      invalidTestId:
+        'Rename {{ attributeName }} to "{{ componentName }}" on the component root, or to "{{ componentName }}--thing" on child elements. Received "{{ candidate }}".',
+    },
+    schema: [],
+    fixable: "code" as const,
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        const attributeName = readJsxAttributeName(node.name);
+        if (attributeName !== "testId" && attributeName !== "data-testid") {
+          return;
+        }
+
+        if (node.value?.type !== "Literal" || typeof node.value.value !== "string") {
+          return;
+        }
+
+        const literalValue = node.value;
+        const attributeValue = literalValue.value;
+
+        const componentName = getComponentNameFromAncestors(node) || getFilenameWithoutExtension(context.filename);
+        const expectedFormat = `${componentName}--`;
+
+        if (attributeValue !== componentName && !attributeValue.startsWith(expectedFormat)) {
+          context.report({
+            node,
+            messageId: "invalidTestId",
+            data: {
+              attributeName,
+              candidate: attributeValue,
+              componentName,
+            },
+            fix(fixer) {
+              let newValue;
+              const parts = attributeValue.split("--");
+
+              if (parts.length > 1) {
+                newValue = `${expectedFormat}${parts.slice(1).join("--")}`;
+              } else {
+                newValue = `${expectedFormat}${attributeValue}`;
+              }
+
+              return fixer.replaceText(literalValue, `"${newValue}"`);
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default testIdNamingConventionRule;

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

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

package/src/oxlint/rules/types.ts

@@ -0,0 +1,45 @@
+import type { TSESLint, TSESTree } from "@typescript-eslint/utils";
+
+export type RuleModule = TSESLint.RuleModule<string, readonly unknown[]>;
+export type RuleContext = Readonly<TSESLint.RuleContext<string, readonly unknown[]>>;
+export type RuleFixer = TSESLint.RuleFixer;
+export type RuleListener = TSESLint.RuleListener;
+
+export type AstNode = TSESTree.Node;
+export type AstProgram = TSESTree.Program;
+export type AstProgramStatement = TSESTree.ProgramStatement;
+export type AstStatement = TSESTree.Statement;
+export type AstExpression = TSESTree.Expression;
+export type AstLiteral = TSESTree.Literal;
+export type AstTypeNode = TSESTree.TypeNode;
+export type AstTypeDeclaration = TSESTree.TSInterfaceDeclaration | TSESTree.TSTypeAliasDeclaration;
+export type AstDestructuringPattern = TSESTree.DestructuringPattern;
+export type AstDeclarationWithIdentifiers =
+  | TSESTree.ClassDeclaration
+  | TSESTree.FunctionDeclaration
+  | TSESTree.TSDeclareFunction
+  | TSESTree.TSEnumDeclaration
+  | TSESTree.TSImportEqualsDeclaration
+  | TSESTree.TSInterfaceDeclaration
+  | TSESTree.TSModuleDeclaration
+  | TSESTree.TSTypeAliasDeclaration
+  | TSESTree.VariableDeclaration;
+export type AstFunctionExpression = TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression;
+export type AstFunctionLike = TSESTree.FunctionDeclaration | AstFunctionExpression;
+export type AstClassLike = TSESTree.ClassDeclaration | TSESTree.ClassExpression;
+export type AstImportClause = TSESTree.ImportClause;
+export type AstImportSpecifier = TSESTree.ImportSpecifier;
+export type AstExportSpecifier = TSESTree.ExportSpecifier;
+export type AstImportDeclaration = TSESTree.ImportDeclaration;
+export type AstExportNamedDeclaration = TSESTree.ExportNamedDeclaration;
+export type AstVariableDeclaration = TSESTree.VariableDeclaration;
+export type AstVariableDeclarator = TSESTree.VariableDeclarator;
+export type AstCallExpression = TSESTree.CallExpression;
+export type AstMemberExpression = TSESTree.MemberExpression;
+export type AstIdentifier = TSESTree.Identifier;
+export type AstJsxAttribute = TSESTree.JSXAttribute;
+export type AstJsxAttributeName = TSESTree.JSXAttribute["name"];
+export type AstJsxAttributeValue = TSESTree.JSXAttribute["value"];
+export type AstJsxAttributeList = TSESTree.JSXOpeningElement["attributes"];
+export type AstProperty = TSESTree.Property;
+export type AstSourceLocationNode = TSESTree.Node | TSESTree.Token;

package/src/semantic-fixes/applyFileChanges.ts

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { applyTextEdits, readUpdatedContent } from "./applyTextEdits.ts";
+import type { IFileMove, ITextEdit } from "./types.ts";
+
+function readTextEditsByFilePath(textEdits: readonly ITextEdit[]): Map<string, readonly ITextEdit[]> {
+  const textEditsByFilePath = new Map<string, ITextEdit[]>();
+
+  for (const textEdit of textEdits) {
+    const existingTextEdits = textEditsByFilePath.get(textEdit.filePath);
+    if (existingTextEdits) {
+      existingTextEdits.push(textEdit);
+      continue;
+    }
+
+    textEditsByFilePath.set(textEdit.filePath, [textEdit]);
+  }
+
+  return new Map(textEditsByFilePath);
+}
+
+function assertMoveFileOperationsAreSafe(fileMoves: readonly IFileMove[]): void {
+  const sourceFilePathSet = new Set<string>();
+  const destinationFilePathSet = new Set<string>();
+
+  for (const fileMove of fileMoves) {
+    if (fileMove.sourceFilePath === fileMove.destinationFilePath) {
+      throw new Error(`Refusing to move a file onto itself: ${fileMove.sourceFilePath}`);
+    }
+
+    if (sourceFilePathSet.has(fileMove.sourceFilePath)) {
+      throw new Error(`Duplicate semantic fix move source detected: ${fileMove.sourceFilePath}`);
+    }
+
+    if (destinationFilePathSet.has(fileMove.destinationFilePath)) {
+      throw new Error(`Duplicate semantic fix move destination detected: ${fileMove.destinationFilePath}`);
+    }
+
+    sourceFilePathSet.add(fileMove.sourceFilePath);
+    destinationFilePathSet.add(fileMove.destinationFilePath);
+  }
+}
+
+function applyMovedFile(fileMove: IFileMove, textEdits: readonly ITextEdit[]): void {
+  if (!existsSync(fileMove.sourceFilePath)) {
+    throw new Error(`Cannot move a missing file: ${fileMove.sourceFilePath}`);
+  }
+
+  if (existsSync(fileMove.destinationFilePath)) {
+    throw new Error(`Refusing to overwrite an existing file: ${fileMove.destinationFilePath}`);
+  }
+
+  const content = readFileSync(fileMove.sourceFilePath, "utf8");
+  const updatedContent = readUpdatedContent(fileMove.sourceFilePath, content, textEdits);
+
+  mkdirSync(dirname(fileMove.destinationFilePath), { recursive: true });
+  writeFileSync(fileMove.destinationFilePath, updatedContent, "utf8");
+  rmSync(fileMove.sourceFilePath);
+}
+
+export function applyFileChanges(textEdits: readonly ITextEdit[], fileMoves: readonly IFileMove[]): readonly string[] {
+  assertMoveFileOperationsAreSafe(fileMoves);
+
+  const changedFilePathSet = new Set<string>();
+  const textEditsByFilePath = readTextEditsByFilePath(textEdits);
+
+  for (const fileMove of [...fileMoves].sort((left, right) =>
+    left.sourceFilePath.localeCompare(right.sourceFilePath),
+  )) {
+    applyMovedFile(fileMove, textEditsByFilePath.get(fileMove.sourceFilePath) ?? []);
+    textEditsByFilePath.delete(fileMove.sourceFilePath);
+    changedFilePathSet.add(fileMove.destinationFilePath);
+  }
+
+  const remainingTextEdits = [...textEditsByFilePath.values()].flat();
+  for (const changedFilePath of applyTextEdits(remainingTextEdits)) {
+    changedFilePathSet.add(changedFilePath);
+  }
+
+  return [...changedFilePathSet].sort((left, right) => left.localeCompare(right));
+}