@alexgorbatchev/typescript-ai-policy 0.1.0

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

@@ -0,0 +1,179 @@
+import type {
+  AstDeclarationWithIdentifiers,
+  AstExportNamedDeclaration,
+  AstExportSpecifier,
+  AstNode,
+  AstProgram,
+  AstProgramStatement,
+  RuleModule,
+} from "./types.ts";
+import { isExemptSupportBasename, isTypeDeclaration, readPatternIdentifierNames } from "./helpers.ts";
+
+type HookRuntimeExportEntry = {
+  kind:
+    | "class-declaration"
+    | "const-variable"
+    | "default-export"
+    | "enum-declaration"
+    | "export-all"
+    | "function-declaration"
+    | "indirect-export"
+    | "variable-declaration";
+  name?: string;
+  node: AstNode;
+};
+
+function readExportedSpecifierName(specifier: AstExportSpecifier): string {
+  if (specifier.exported.type === "Identifier") {
+    return specifier.exported.name;
+  }
+
+  return String(specifier.exported.value);
+}
+
+function isTypeOnlyExportSpecifier(
+  specifier: AstExportSpecifier,
+  exportDeclaration: AstExportNamedDeclaration,
+): boolean {
+  return exportDeclaration.exportKind === "type" || specifier.exportKind === "type";
+}
+
+function isTypeOnlyExportNamedDeclaration(node: AstExportNamedDeclaration): boolean {
+  if (node.declaration) {
+    return node.exportKind === "type" || isTypeDeclaration(node.declaration);
+  }
+
+  return node.exportKind === "type" || node.specifiers.every((specifier) => isTypeOnlyExportSpecifier(specifier, node));
+}
+
+function readRuntimeExportEntries(program: AstProgram): HookRuntimeExportEntry[] {
+  return program.body.flatMap((statement) => readStatementRuntimeExportEntries(statement));
+}
+
+function readStatementRuntimeExportEntries(statement: AstProgramStatement): HookRuntimeExportEntry[] {
+  if (statement.type === "ExportDefaultDeclaration") {
+    return [{ kind: "default-export", node: statement }];
+  }
+
+  if (statement.type === "TSExportAssignment") {
+    return [{ kind: "default-export", node: statement }];
+  }
+
+  if (statement.type === "ExportAllDeclaration") {
+    if (statement.exportKind === "type") {
+      return [];
+    }
+
+    return [{ kind: "export-all", node: statement }];
+  }
+
+  if (statement.type !== "ExportNamedDeclaration") {
+    return [];
+  }
+
+  if (isTypeOnlyExportNamedDeclaration(statement)) {
+    return [];
+  }
+
+  if (!statement.declaration) {
+    return statement.specifiers
+      .filter((specifier) => !isTypeOnlyExportSpecifier(specifier, statement))
+      .map((specifier) => ({
+        kind: "indirect-export" as const,
+        name: readExportedSpecifierName(specifier),
+        node: specifier,
+      }));
+  }
+
+  return readDeclarationRuntimeExportEntries(statement.declaration);
+}
+
+function readDeclarationRuntimeExportEntries(declaration: AstDeclarationWithIdentifiers): HookRuntimeExportEntry[] {
+  if (declaration.type === "FunctionDeclaration") {
+    return declaration.id ? [{ kind: "function-declaration", name: declaration.id.name, node: declaration }] : [];
+  }
+
+  if (declaration.type === "VariableDeclaration") {
+    return declaration.declarations.flatMap((declarator) => {
+      const declarationNames = readPatternIdentifierNames(declarator.id);
+
+      return declarationNames.map((name) => ({
+        kind: declaration.kind === "const" ? ("const-variable" as const) : ("variable-declaration" as const),
+        name,
+        node: declarator,
+      }));
+    });
+  }
+
+  if (declaration.type === "TSEnumDeclaration") {
+    return declaration.id ? [{ kind: "enum-declaration", name: declaration.id.name, node: declaration }] : [];
+  }
+
+  if (declaration.type === "ClassDeclaration") {
+    return declaration.id ? [{ kind: "class-declaration", name: declaration.id.name, node: declaration }] : [];
+  }
+
+  return [];
+}
+
+function isValidMainHookRuntimeExport(entry: HookRuntimeExportEntry): boolean {
+  return entry.kind === "function-declaration" && entry.name?.startsWith("use") === true;
+}
+
+const hookFileContractRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Require hook ownership files to export exactly one direct named hook function and allow only type-only secondary exports",
+    },
+    schema: [],
+    messages: {
+      missingMainHookExport:
+        "Export exactly one main runtime hook from this file. Hook ownership files must use one direct named `export function useThing()` export plus optional type-only exports.",
+      invalidMainHookExport:
+        "Replace this export with a plain named hook function declaration. Hook ownership files must use `export function useThing() {}` and must not wrap or const-bind the main hook export.",
+      unexpectedAdditionalRuntimeExport:
+        "Remove this additional runtime export. Hook ownership files may export only one main runtime hook plus unrestricted type-only API.",
+    },
+  },
+  create(context) {
+    if (isExemptSupportBasename(context.filename)) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        const runtimeExportEntries = readRuntimeExportEntries(node);
+        if (runtimeExportEntries.length === 0) {
+          context.report({
+            node,
+            messageId: "missingMainHookExport",
+          });
+          return;
+        }
+
+        const [mainRuntimeExportEntry, ...additionalRuntimeExportEntries] = runtimeExportEntries;
+        if (!mainRuntimeExportEntry) {
+          return;
+        }
+
+        if (!isValidMainHookRuntimeExport(mainRuntimeExportEntry)) {
+          context.report({
+            node: mainRuntimeExportEntry.node,
+            messageId: "invalidMainHookExport",
+          });
+        }
+
+        additionalRuntimeExportEntries.forEach((runtimeExportEntry) => {
+          context.report({
+            node: runtimeExportEntry.node,
+            messageId: "unexpectedAdditionalRuntimeExport",
+          });
+        });
+      },
+    };
+  },
+};
+
+export default hookFileContractRule;

package/src/oxlint/rules/hook-file-naming-convention.ts

@@ -0,0 +1,151 @@
+import type {
+  AstExportNamedDeclaration,
+  AstExportSpecifier,
+  AstProgram,
+  AstProgramStatement,
+  RuleModule,
+} from "./types.ts";
+import { getFilenameWithoutExtension, isExemptSupportBasename, readDeclarationIdentifierNames } from "./helpers.ts";
+
+function isTypeOnlyExportSpecifier(
+  specifier: AstExportSpecifier,
+  exportDeclaration: AstExportNamedDeclaration,
+): boolean {
+  return exportDeclaration.exportKind === "type" || specifier.exportKind === "type";
+}
+
+function readExportedSpecifierName(specifier: AstExportSpecifier): string {
+  if (specifier.exported.type === "Identifier") {
+    return specifier.exported.name;
+  }
+
+  return String(specifier.exported.value);
+}
+
+function readFirstRuntimeExportName(program: AstProgram): string | null {
+  for (const statement of program.body) {
+    const exportName = readStatementRuntimeExportName(statement);
+    if (exportName !== null) {
+      return exportName;
+    }
+  }
+
+  return null;
+}
+
+function readStatementRuntimeExportName(statement: AstProgramStatement): string | null {
+  if (statement.type !== "ExportNamedDeclaration") {
+    return null;
+  }
+
+  if (statement.declaration) {
+    if (
+      statement.exportKind === "type" ||
+      statement.declaration.type === "TSTypeAliasDeclaration" ||
+      statement.declaration.type === "TSInterfaceDeclaration" ||
+      statement.declaration.type === "TSModuleDeclaration"
+    ) {
+      return null;
+    }
+
+    if (statement.declaration.type === "VariableDeclaration") {
+      const firstDeclarator = statement.declaration.declarations[0];
+      return firstDeclarator?.id.type === "Identifier" ? firstDeclarator.id.name : null;
+    }
+
+    return readDeclarationIdentifierNames(statement.declaration)[0] ?? null;
+  }
+
+  const runtimeSpecifier = statement.specifiers.find((specifier) => !isTypeOnlyExportSpecifier(specifier, statement));
+  if (!runtimeSpecifier) {
+    return null;
+  }
+
+  return readExportedSpecifierName(runtimeSpecifier);
+}
+
+function readExpectedHookNameFromFilename(filename: string): string | null {
+  const fileStem = getFilenameWithoutExtension(filename);
+  if (/^use[A-Z][A-Za-z0-9]*$/u.test(fileStem)) {
+    return fileStem;
+  }
+
+  if (!/^use(?:-[a-z0-9]+)+$/u.test(fileStem)) {
+    return null;
+  }
+
+  const [, ...segments] = fileStem.split("-");
+
+  return `use${segments.map((segment) => `${segment[0]?.toUpperCase() ?? ""}${segment.slice(1)}`).join("")}`;
+}
+
+function readKebabCaseHookFilename(hookName: string): string {
+  return `${hookName.replaceAll(/([a-z0-9])([A-Z])/gu, "$1-$2").toLowerCase()}.ts`;
+}
+
+const hookFileNamingConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Require hook ownership filenames to match their exported hook name in either camelCase or kebab-case `use*` form",
+    },
+    schema: [],
+    messages: {
+      invalidHookFileName:
+        'Rename this hook file to either "useFoo.ts[x]" or "use-foo.ts[x]" so its basename maps deterministically to the exported hook name.',
+      invalidHookExportName:
+        'Rename the exported hook to lower camelCase starting with "use". Hook ownership files must export names like "useFoo".',
+      mismatchedHookFileName:
+        'Rename this file or the exported hook so they match exactly. "{{ exportedName }}" must live in either "{{ camelFilename }}" or "{{ kebabFilename }}".',
+    },
+  },
+  create(context) {
+    if (isExemptSupportBasename(context.filename)) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        const exportedHookName = readFirstRuntimeExportName(node);
+        if (!exportedHookName) {
+          return;
+        }
+
+        const expectedHookName = readExpectedHookNameFromFilename(context.filename);
+        if (!expectedHookName) {
+          context.report({
+            node,
+            messageId: "invalidHookFileName",
+          });
+          return;
+        }
+
+        if (!/^use[A-Z][A-Za-z0-9]*$/u.test(exportedHookName)) {
+          context.report({
+            node,
+            messageId: "invalidHookExportName",
+          });
+        }
+
+        if (exportedHookName === expectedHookName) {
+          return;
+        }
+
+        const extension = context.filename.endsWith(".tsx") ? ".tsx" : ".ts";
+
+        context.report({
+          node,
+          messageId: "mismatchedHookFileName",
+          data: {
+            exportedName: exportedHookName,
+            camelFilename: `${exportedHookName}${extension}`,
+            kebabFilename: readKebabCaseHookFilename(exportedHookName).replace(/\.ts$/u, extension),
+          },
+        });
+      },
+    };
+  },
+};
+
+export default hookFileNamingConventionRule;

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

@@ -0,0 +1,60 @@
+import type { AstProgram, RuleModule } from "./types.ts";
+import { dirname, join } from "node:path";
+import {
+  findDescendantFilePath,
+  getBaseName,
+  getFilenameWithoutExtension,
+  isExemptSupportBasename,
+} from "./helpers.ts";
+
+function readRequiredTestsDirectoryPath(filename: string): string {
+  return join(dirname(filename), "__tests__");
+}
+
+function readRequiredHookTestFileName(filename: string): string {
+  const sourceBaseName = getFilenameWithoutExtension(filename);
+  const testExtension = getBaseName(filename).endsWith(".tsx") ? ".test.tsx" : ".test.ts";
+
+  return `${sourceBaseName}${testExtension}`;
+}
+
+const hookTestFileConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require every hook ownership file to have a matching "basename.test.ts" or ".test.tsx" file somewhere under a sibling "__tests__/" directory',
+    },
+    schema: [],
+    messages: {
+      missingHookTestFile:
+        'Add a test file named "{{ requiredTestFileName }}" somewhere under "{{ requiredTestsDirectoryPath }}". Hook ownership files must keep their tests under a sibling "__tests__/" directory.',
+    },
+  },
+  create(context) {
+    if (isExemptSupportBasename(context.filename)) {
+      return {};
+    }
+
+    return {
+      Program(node: AstProgram) {
+        const requiredTestsDirectoryPath = readRequiredTestsDirectoryPath(context.filename);
+        const requiredTestFileName = readRequiredHookTestFileName(context.filename);
+        if (findDescendantFilePath(requiredTestsDirectoryPath, requiredTestFileName)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "missingHookTestFile",
+          data: {
+            requiredTestFileName,
+            requiredTestsDirectoryPath,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default hookTestFileConventionRule;

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

@@ -0,0 +1,75 @@
+import type { RuleModule } from "./types.ts";
+import {
+  getExtension,
+  getFilenameWithoutExtension,
+  isStrictAreaAllowedSupportFile,
+  readPathFromDirectory,
+} from "./helpers.ts";
+
+function isAllowedHookOwnershipBasename(filename: string): boolean {
+  const extension = getExtension(filename);
+  if (extension !== ".ts" && extension !== ".tsx") {
+    return false;
+  }
+
+  return getFilenameWithoutExtension(filename).startsWith("use");
+}
+
+function isAllowedHooksDirectoryRelativePath(relativePath: string, filename: string): boolean {
+  if (!relativePath) {
+    return false;
+  }
+
+  if (relativePath.startsWith("__tests__/")) {
+    return true;
+  }
+
+  if (relativePath.includes("/")) {
+    return false;
+  }
+
+  if (isStrictAreaAllowedSupportFile(filename)) {
+    return true;
+  }
+
+  return isAllowedHookOwnershipBasename(filename);
+}
+
+const hooksDirectoryFileConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Restrict "hooks" directories to direct-child hook ownership files, exempt support basenames, and sibling "__tests__" trees',
+    },
+    schema: [],
+    messages: {
+      invalidHooksDirectoryFile:
+        'Move or rename "{{ relativePath }}". A "hooks/" directory may contain only direct-child "use*.ts" or "use*.tsx" ownership files, direct-child "index.ts" or "types.ts" files, or a direct-child "__tests__/" tree.',
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const relativePath = readPathFromDirectory(context.filename, "hooks");
+        if (relativePath === null) {
+          return;
+        }
+
+        if (isAllowedHooksDirectoryRelativePath(relativePath, context.filename)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "invalidHooksDirectoryFile",
+          data: {
+            relativePath: relativePath || ".",
+          },
+        });
+      },
+    };
+  },
+};
+
+export default hooksDirectoryFileConventionRule;

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

@@ -0,0 +1,177 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type { AstProgramStatement, RuleModule } from "./types.ts";
+import { getBaseName } from "./helpers.ts";
+
+type IndexMessageId = "unexpectedIndexExport" | "unexpectedIndexStatement";
+
+function isIndexModuleFile(filename: string): boolean {
+  const baseName = getBaseName(filename);
+
+  return baseName === "index.ts" || baseName === "index.tsx";
+}
+
+function isIndexTsxFile(filename: string): boolean {
+  return getBaseName(filename) === "index.tsx";
+}
+
+function isAllowedIndexReExport(node: AstProgramStatement): boolean {
+  return (
+    node.type === "ExportAllDeclaration" ||
+    (node.type === "ExportNamedDeclaration" && node.source !== null && node.declaration === null)
+  );
+}
+
+function readIndexBarrelBaseName(filename: string): string {
+  return getBaseName(filename);
+}
+
+function readIndexRenameSuffix(filename: string): string {
+  return isIndexTsxFile(filename) ? ' Then rename this file to "index.ts".' : "";
+}
+
+function readUnexpectedMessageId(node: AstProgramStatement): IndexMessageId {
+  if (
+    node.type === "ExportNamedDeclaration" ||
+    node.type === "ExportDefaultDeclaration" ||
+    node.type === "TSExportAssignment"
+  ) {
+    return "unexpectedIndexExport";
+  }
+
+  return "unexpectedIndexStatement";
+}
+
+function readVariableDeclarationReportNode(node: TSESTree.VariableDeclaration): TSESTree.Node {
+  const firstDeclarator = node.declarations[0];
+  return firstDeclarator?.id.type === "Identifier" ? firstDeclarator.id : node;
+}
+
+function readDeclarationStatementReportNode(statement: AstProgramStatement): TSESTree.Node | null {
+  if (
+    statement.type === "FunctionDeclaration" ||
+    statement.type === "ClassDeclaration" ||
+    statement.type === "TSEnumDeclaration" ||
+    statement.type === "TSInterfaceDeclaration" ||
+    statement.type === "TSTypeAliasDeclaration"
+  ) {
+    return statement.id ?? statement;
+  }
+
+  if (statement.type === "VariableDeclaration") {
+    return readVariableDeclarationReportNode(statement);
+  }
+
+  return null;
+}
+
+function readExportDefaultReportNode(node: TSESTree.ExportDefaultDeclaration): TSESTree.Node {
+  if (node.declaration.type === "Identifier") {
+    return node.declaration;
+  }
+
+  if (
+    node.declaration.type === "FunctionDeclaration" ||
+    node.declaration.type === "ClassDeclaration" ||
+    node.declaration.type === "TSEnumDeclaration" ||
+    node.declaration.type === "TSInterfaceDeclaration" ||
+    node.declaration.type === "TSTypeAliasDeclaration"
+  ) {
+    return node.declaration.id ?? node.declaration;
+  }
+
+  if (node.declaration.type === "VariableDeclaration") {
+    return readVariableDeclarationReportNode(node.declaration);
+  }
+
+  return node;
+}
+
+function readProgramReportNode(node: TSESTree.Program): TSESTree.Node {
+  return node.body[0] ?? node;
+}
+
+function readIndexViolationReportNode(statement: AstProgramStatement): TSESTree.Node {
+  if (statement.type === "ExportNamedDeclaration") {
+    if (statement.declaration) {
+      if (
+        statement.declaration.type === "FunctionDeclaration" ||
+        statement.declaration.type === "ClassDeclaration" ||
+        statement.declaration.type === "TSEnumDeclaration" ||
+        statement.declaration.type === "TSInterfaceDeclaration" ||
+        statement.declaration.type === "TSTypeAliasDeclaration"
+      ) {
+        return statement.declaration.id ?? statement.declaration;
+      }
+
+      if (statement.declaration.type === "VariableDeclaration") {
+        return readVariableDeclarationReportNode(statement.declaration);
+      }
+    }
+
+    const firstSpecifier = statement.specifiers[0];
+    if (!firstSpecifier) {
+      return statement;
+    }
+
+    return firstSpecifier.exported.type === "Identifier" ? firstSpecifier.exported : firstSpecifier;
+  }
+
+  if (statement.type === "ExportDefaultDeclaration") {
+    return readExportDefaultReportNode(statement);
+  }
+
+  return readDeclarationStatementReportNode(statement) ?? statement;
+}
+
+const indexFileContractRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description: 'Require "index.ts" files to contain re-exports only and forbid "index.tsx" barrels',
+    },
+    schema: [],
+    messages: {
+      unexpectedIndexTsxFilename:
+        'Rename this file to "index.ts". Index barrel files must not use the ".tsx" extension.',
+      unexpectedIndexExport:
+        'Remove this local export from the index barrel. "{{ barrelBaseName }}" must not define symbols; move the definition into another module and re-export it from here instead{{ renameSuffix }}',
+      unexpectedIndexStatement:
+        'Remove this statement from the index barrel. "{{ barrelBaseName }}" may contain re-export statements only{{ renameSuffix }}',
+    },
+  },
+  create(context) {
+    if (!isIndexModuleFile(context.filename)) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        if (isIndexTsxFile(context.filename)) {
+          context.report({
+            node: readProgramReportNode(node),
+            messageId: "unexpectedIndexTsxFilename",
+          });
+        }
+
+        const reportData = {
+          barrelBaseName: readIndexBarrelBaseName(context.filename),
+          renameSuffix: readIndexRenameSuffix(context.filename),
+        };
+
+        node.body.forEach((statement) => {
+          if (isAllowedIndexReExport(statement)) {
+            return;
+          }
+
+          context.report({
+            node: readIndexViolationReportNode(statement),
+            messageId: readUnexpectedMessageId(statement),
+            data: reportData,
+          });
+        });
+      },
+    };
+  },
+};
+
+export default indexFileContractRule;