@alexgorbatchev/typescript-ai-policy 0.1.0

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

@@ -0,0 +1,65 @@
+import type { RuleModule } from "./types.ts";
+import { getBaseName, getExtension, isExemptSupportBasename, readPathFromFirstMatchingDirectory } from "./helpers.ts";
+
+const COMPONENT_DIRECTORY_NAMES = new Set(["components", "templates", "layouts"]);
+const COMPONENT_ALLOWED_SUPPORT_FILES = new Set(["constants.ts", "index.ts", "types.ts"]);
+
+function isAllowedComponentDirectoryRelativePath(relativePath: string, filename: string): boolean {
+  if (!relativePath) {
+    return false;
+  }
+
+  if (relativePath.startsWith("stories/")) {
+    return true;
+  }
+
+  if (relativePath.includes("/")) {
+    return false;
+  }
+
+  if (COMPONENT_ALLOWED_SUPPORT_FILES.has(getBaseName(filename))) {
+    return true;
+  }
+
+  return getExtension(filename) === ".tsx" && !isExemptSupportBasename(filename);
+}
+
+const componentDirectoryFileConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Restrict "components", "templates", and "layouts" directories to direct-child component files, direct-child support files (`constants.ts`, `index.ts`, `types.ts`), and sibling "stories/" trees',
+    },
+    schema: [],
+    messages: {
+      invalidComponentDirectoryFile:
+        'Move or rename "{{ relativePath }}". A "{{ directoryName }}/" directory may contain only direct-child component ".tsx" files, direct-child "constants.ts", "index.ts", or "types.ts" files, or a direct-child "stories/" tree.',
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const componentDirectoryMatch = readPathFromFirstMatchingDirectory(context.filename, COMPONENT_DIRECTORY_NAMES);
+        if (!componentDirectoryMatch) {
+          return;
+        }
+
+        if (isAllowedComponentDirectoryRelativePath(componentDirectoryMatch.relativePath, context.filename)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "invalidComponentDirectoryFile",
+          data: {
+            directoryName: componentDirectoryMatch.directoryName,
+            relativePath: componentDirectoryMatch.relativePath || ".",
+          },
+        });
+      },
+    };
+  },
+};
+
+export default componentDirectoryFileConventionRule;

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

@@ -0,0 +1,328 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type {
+  AstDeclarationWithIdentifiers,
+  AstExportNamedDeclaration,
+  AstExportSpecifier,
+  AstNode,
+  AstProgram,
+  AstProgramStatement,
+  AstVariableDeclarator,
+  RuleModule,
+} from "./types.ts";
+import {
+  isExemptSupportBasename,
+  isInStoriesDirectory,
+  isInTestsDirectory,
+  isTypeDeclaration,
+  readDeclarationIdentifierNames,
+  readMultipartComponentRootName,
+  readPatternIdentifierNames,
+  unwrapExpression,
+} from "./helpers.ts";
+
+type WrappedFunctionExpressionState = TSESTree.FunctionExpression | false | null;
+
+type ComponentRuntimeExportEntry = {
+  declarationKind?: TSESTree.VariableDeclaration["kind"];
+  declarator?: AstVariableDeclarator;
+  kind:
+    | "class-declaration"
+    | "const-variable"
+    | "default-export"
+    | "enum-declaration"
+    | "export-all"
+    | "function-declaration"
+    | "indirect-export"
+    | "variable-declaration";
+  name: string;
+  node: AstNode;
+  reportNode: 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 readWrappedNamedFunctionExpression(
+  initializer: TSESTree.Expression | null | undefined,
+): TSESTree.FunctionExpression | null {
+  if (!initializer) {
+    return null;
+  }
+
+  const currentInitializer = unwrapExpression(initializer);
+  if (currentInitializer.type === "FunctionExpression") {
+    return currentInitializer;
+  }
+
+  if (currentInitializer.type !== "CallExpression") {
+    return null;
+  }
+
+  let wrappedFunctionExpression: WrappedFunctionExpressionState = null;
+
+  currentInitializer.arguments.forEach((argument) => {
+    if (argument.type === "SpreadElement") {
+      return;
+    }
+
+    const candidate = readWrappedNamedFunctionExpression(argument);
+    if (!candidate) {
+      return;
+    }
+
+    if (wrappedFunctionExpression) {
+      wrappedFunctionExpression = false;
+      return;
+    }
+
+    wrappedFunctionExpression = candidate;
+  });
+
+  return wrappedFunctionExpression || null;
+}
+
+function readRuntimeExportEntries(program: AstProgram): ComponentRuntimeExportEntry[] {
+  return program.body.flatMap((statement) => readStatementRuntimeExportEntries(statement));
+}
+
+function readStatementRuntimeExportEntries(statement: AstProgramStatement): ComponentRuntimeExportEntry[] {
+  if (statement.type === "ExportDefaultDeclaration") {
+    return [
+      {
+        kind: "default-export",
+        name: readDefaultExportName(statement.declaration) ?? "default",
+        node: statement,
+        reportNode: statement,
+      },
+    ];
+  }
+
+  if (statement.type === "TSExportAssignment") {
+    return [{ kind: "default-export", name: "default", node: statement, reportNode: statement }];
+  }
+
+  if (statement.type === "ExportAllDeclaration") {
+    if (statement.exportKind === "type") {
+      return [];
+    }
+
+    return [{ kind: "export-all", name: "*", node: statement, reportNode: 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,
+        reportNode: specifier.exported.type === "Identifier" ? specifier.exported : specifier,
+      }));
+  }
+
+  return readDeclarationRuntimeExportEntries(statement.declaration);
+}
+
+function readDefaultExportName(declaration: TSESTree.ExportDefaultDeclaration["declaration"]): string | null {
+  if (declaration.type === "Identifier") {
+    return declaration.name;
+  }
+
+  if (declaration.type === "VariableDeclaration") {
+    const firstDeclarator = declaration.declarations[0];
+    return firstDeclarator?.id.type === "Identifier" ? firstDeclarator.id.name : null;
+  }
+
+  if (
+    declaration.type === "FunctionDeclaration" ||
+    declaration.type === "ClassDeclaration" ||
+    declaration.type === "TSEnumDeclaration" ||
+    declaration.type === "TSInterfaceDeclaration" ||
+    declaration.type === "TSTypeAliasDeclaration"
+  ) {
+    return readDeclarationIdentifierNames(declaration)[0] ?? null;
+  }
+
+  return null;
+}
+
+function readDeclarationRuntimeExportEntries(
+  declaration: AstDeclarationWithIdentifiers,
+): ComponentRuntimeExportEntry[] {
+  if (declaration.type === "FunctionDeclaration") {
+    return declaration.id
+      ? [{ kind: "function-declaration", name: declaration.id.name, node: declaration, reportNode: declaration.id }]
+      : [];
+  }
+
+  if (declaration.type === "ClassDeclaration") {
+    return declaration.id
+      ? [{ kind: "class-declaration", name: declaration.id.name, node: declaration, reportNode: declaration.id }]
+      : [];
+  }
+
+  if (declaration.type === "TSEnumDeclaration") {
+    return declaration.id
+      ? [{ kind: "enum-declaration", name: declaration.id.name, node: declaration, reportNode: declaration.id }]
+      : [];
+  }
+
+  if (declaration.type !== "VariableDeclaration") {
+    return [];
+  }
+
+  return declaration.declarations.flatMap((declarator) => {
+    const declarationNames = readPatternIdentifierNames(declarator.id);
+
+    return declarationNames.map((name) => ({
+      declarationKind: declaration.kind,
+      declarator,
+      kind: declaration.kind === "const" ? ("const-variable" as const) : ("variable-declaration" as const),
+      name,
+      node: declarator,
+      reportNode: declarator.id.type === "Identifier" ? declarator.id : declarator,
+    }));
+  });
+}
+
+function isValidWrappedComponentExport(entry: ComponentRuntimeExportEntry): boolean {
+  if (entry.kind !== "const-variable" || !entry.declarator) {
+    return false;
+  }
+
+  if (entry.declarator.id.type !== "Identifier") {
+    return false;
+  }
+
+  const wrappedFunctionExpression = readWrappedNamedFunctionExpression(entry.declarator.init);
+  if (!wrappedFunctionExpression || !wrappedFunctionExpression.id) {
+    return false;
+  }
+
+  return wrappedFunctionExpression.id.name === entry.name;
+}
+
+function isValidMainComponentRuntimeExport(entry: ComponentRuntimeExportEntry): boolean {
+  return entry.kind === "function-declaration" || isValidWrappedComponentExport(entry);
+}
+
+function isValidMultipartComponentRuntimeExportFamily(
+  runtimeExportEntries: readonly ComponentRuntimeExportEntry[],
+): boolean {
+  if (runtimeExportEntries.length < 2) {
+    return false;
+  }
+
+  const validComponentRuntimeExportEntries = runtimeExportEntries.filter(isValidMainComponentRuntimeExport);
+  if (validComponentRuntimeExportEntries.length !== runtimeExportEntries.length) {
+    return false;
+  }
+
+  const multipartComponentRootName = readMultipartComponentRootName(
+    validComponentRuntimeExportEntries.map((runtimeExportEntry) => runtimeExportEntry.name),
+  );
+
+  return multipartComponentRootName !== null;
+}
+
+const componentFileContractRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Require component ownership files to export exactly one named runtime component or one multipart component family and allow only type-only secondary exports",
+    },
+    schema: [],
+    messages: {
+      missingMainComponentExport:
+        "Export exactly one main runtime component from this file. Component ownership files must use one direct named export plus optional type-only exports.",
+      invalidMainComponentExport:
+        "Replace this export with a valid component ownership export. Use `export function ComponentName() {}` for plain components, or `export const ComponentName = wrapper(function ComponentName() {})` for wrapped components.",
+      invalidIndirectComponentExport:
+        "Export this component directly from its declaration. Component ownership files must use `export function ComponentName() {}` or a direct named wrapped `export const` binding, not an `export { ComponentName }` list.",
+      unexpectedAdditionalRuntimeExport:
+        "Extract this runtime export to its own ownership file. Component ownership files may export only one main runtime component, or one multipart component family whose members share the base component name, plus unrestricted type-only API.",
+    },
+  },
+  create(context) {
+    if (
+      isExemptSupportBasename(context.filename) ||
+      isInStoriesDirectory(context.filename) ||
+      isInTestsDirectory(context.filename)
+    ) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        const runtimeExportEntries = readRuntimeExportEntries(node);
+        if (runtimeExportEntries.length === 0) {
+          context.report({
+            node,
+            messageId: "missingMainComponentExport",
+          });
+          return;
+        }
+
+        if (isValidMultipartComponentRuntimeExportFamily(runtimeExportEntries)) {
+          return;
+        }
+
+        const [mainRuntimeExportEntry, ...additionalRuntimeExportEntries] = runtimeExportEntries;
+        if (!mainRuntimeExportEntry) {
+          return;
+        }
+
+        if (!isValidMainComponentRuntimeExport(mainRuntimeExportEntry)) {
+          context.report({
+            node: mainRuntimeExportEntry.reportNode,
+            messageId:
+              mainRuntimeExportEntry.kind === "indirect-export"
+                ? "invalidIndirectComponentExport"
+                : "invalidMainComponentExport",
+          });
+        }
+
+        additionalRuntimeExportEntries.forEach((runtimeExportEntry) => {
+          context.report({
+            node: runtimeExportEntry.reportNode,
+            messageId:
+              runtimeExportEntry.kind === "indirect-export"
+                ? "invalidIndirectComponentExport"
+                : "unexpectedAdditionalRuntimeExport",
+          });
+        });
+      },
+    };
+  },
+};
+
+export default componentFileContractRule;

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

@@ -0,0 +1,43 @@
+import type { RuleModule } from "./types.ts";
+import { getExtension, hasPathSegment, isInTestsDirectory } from "./helpers.ts";
+
+const COMPONENT_DIRECTORY_NAMES = new Set(["components", "templates", "layouts"]);
+
+const componentFileLocationConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        'Require non-hook, non-test ".tsx" files to live under a "components", "templates", or "layouts" directory',
+    },
+    schema: [],
+    messages: {
+      unexpectedComponentFileLocation:
+        'Move this ".tsx" file under a "components", "templates", or "layouts" directory. Files inside "hooks/" and "__tests__/" are exempt from this placement rule.',
+    },
+  },
+  create(context) {
+    if (getExtension(context.filename) !== ".tsx") {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        if (isInTestsDirectory(context.filename) || hasPathSegment(context.filename, "hooks")) {
+          return;
+        }
+
+        if ([...COMPONENT_DIRECTORY_NAMES].some((directoryName) => hasPathSegment(context.filename, directoryName))) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "unexpectedComponentFileLocation",
+        });
+      },
+    };
+  },
+};
+
+export default componentFileLocationConventionRule;

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

@@ -0,0 +1,260 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type {
+  AstDeclarationWithIdentifiers,
+  AstExportNamedDeclaration,
+  AstExportSpecifier,
+  AstProgram,
+  AstProgramStatement,
+  RuleModule,
+} from "./types.ts";
+import {
+  getFilenameWithoutExtension,
+  isExemptSupportBasename,
+  isInStoriesDirectory,
+  isInTestsDirectory,
+  isPascalCase,
+  readDeclarationIdentifierNames,
+  readMultipartComponentRootName,
+} 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);
+}
+
+type RuntimeExportNameEntry = {
+  name: string;
+  reportNode: TSESTree.Node;
+};
+
+function readRuntimeExportNameEntries(program: AstProgram): RuntimeExportNameEntry[] {
+  return program.body.flatMap((statement) => {
+    const exportEntry = readStatementRuntimeExportEntry(statement);
+    return exportEntry === null ? [] : [exportEntry];
+  });
+}
+
+function readCanonicalRuntimeExportEntry(program: AstProgram): RuntimeExportNameEntry | null {
+  const runtimeExportEntries = readRuntimeExportNameEntries(program);
+  if (runtimeExportEntries.length === 0) {
+    return null;
+  }
+
+  const multipartComponentRootName = readMultipartComponentRootName(
+    runtimeExportEntries.map((runtimeExportEntry) => runtimeExportEntry.name),
+  );
+
+  if (!multipartComponentRootName) {
+    return runtimeExportEntries[0] ?? null;
+  }
+
+  return (
+    runtimeExportEntries.find((runtimeExportEntry) => runtimeExportEntry.name === multipartComponentRootName) ??
+    runtimeExportEntries[0] ??
+    null
+  );
+}
+
+function readStatementRuntimeExportEntry(statement: AstProgramStatement): RuntimeExportNameEntry | null {
+  if (statement.type === "ExportDefaultDeclaration") {
+    return readDefaultExportEntry(statement.declaration);
+  }
+
+  if (statement.type !== "ExportNamedDeclaration") {
+    return null;
+  }
+
+  if (statement.declaration) {
+    if (statement.exportKind === "type") {
+      return null;
+    }
+
+    return readDeclarationRuntimeExportEntry(statement.declaration);
+  }
+
+  const runtimeSpecifier = statement.specifiers.find((specifier) => !isTypeOnlyExportSpecifier(specifier, statement));
+  if (!runtimeSpecifier) {
+    return null;
+  }
+
+  return {
+    name: readExportedSpecifierName(runtimeSpecifier),
+    reportNode: runtimeSpecifier.exported.type === "Identifier" ? runtimeSpecifier.exported : runtimeSpecifier,
+  };
+}
+
+function readDefaultExportEntry(
+  declaration: TSESTree.ExportDefaultDeclaration["declaration"],
+): RuntimeExportNameEntry | null {
+  if (declaration.type === "Identifier") {
+    return {
+      name: declaration.name,
+      reportNode: declaration,
+    };
+  }
+
+  if (
+    declaration.type === "FunctionDeclaration" ||
+    declaration.type === "ClassDeclaration" ||
+    declaration.type === "TSEnumDeclaration" ||
+    declaration.type === "TSInterfaceDeclaration" ||
+    declaration.type === "TSTypeAliasDeclaration"
+  ) {
+    return declaration.id
+      ? {
+          name: declaration.id.name,
+          reportNode: declaration.id,
+        }
+      : null;
+  }
+
+  if (declaration.type === "VariableDeclaration") {
+    return readVariableDeclarationExportEntry(declaration);
+  }
+
+  return null;
+}
+
+function readDeclarationRuntimeExportEntry(declaration: AstDeclarationWithIdentifiers): RuntimeExportNameEntry | null {
+  if (
+    declaration.type === "TSTypeAliasDeclaration" ||
+    declaration.type === "TSInterfaceDeclaration" ||
+    declaration.type === "TSModuleDeclaration"
+  ) {
+    return null;
+  }
+
+  if (declaration.type === "VariableDeclaration") {
+    return readVariableDeclarationExportEntry(declaration);
+  }
+
+  const declarationName = readDeclarationIdentifierNames(declaration)[0];
+  if (!declarationName) {
+    return null;
+  }
+
+  if (
+    declaration.type === "FunctionDeclaration" ||
+    declaration.type === "ClassDeclaration" ||
+    declaration.type === "TSEnumDeclaration"
+  ) {
+    return declaration.id
+      ? {
+          name: declaration.id.name,
+          reportNode: declaration.id,
+        }
+      : null;
+  }
+
+  return null;
+}
+
+function readVariableDeclarationExportEntry(declaration: TSESTree.VariableDeclaration): RuntimeExportNameEntry | null {
+  const firstDeclarator = declaration.declarations[0];
+  if (!firstDeclarator || firstDeclarator.id.type !== "Identifier") {
+    return null;
+  }
+
+  return {
+    name: firstDeclarator.id.name,
+    reportNode: firstDeclarator.id,
+  };
+}
+
+function readExpectedComponentNameFromFilename(filename: string): string | null {
+  const fileStem = getFilenameWithoutExtension(filename);
+  if (isPascalCase(fileStem)) {
+    return fileStem;
+  }
+
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(fileStem)) {
+    return null;
+  }
+
+  return fileStem
+    .split("-")
+    .map((segment) => `${segment[0]?.toUpperCase() ?? ""}${segment.slice(1)}`)
+    .join("");
+}
+
+const componentFileNamingConventionRule: RuleModule = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Require component ownership filenames to match their exported PascalCase component name, or multipart family root name, in either PascalCase or kebab-case form",
+    },
+    schema: [],
+    messages: {
+      invalidComponentFileName:
+        'Rename this file to either "ComponentName.tsx" or "component-name.tsx" so its basename can map deterministically to the exported component name.',
+      invalidComponentExportName:
+        "Rename the exported component to PascalCase. Component ownership files must export a PascalCase component name.",
+      mismatchedComponentFileName:
+        'Rename this file or the exported component so they match exactly. "{{ exportedName }}" must live in either "{{ pascalFilename }}" or "{{ kebabFilename }}".',
+    },
+  },
+  create(context) {
+    if (
+      isExemptSupportBasename(context.filename) ||
+      isInStoriesDirectory(context.filename) ||
+      isInTestsDirectory(context.filename)
+    ) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        const exportedComponentEntry = readCanonicalRuntimeExportEntry(node);
+        if (!exportedComponentEntry) {
+          return;
+        }
+
+        const { name: exportedComponentName, reportNode } = exportedComponentEntry;
+        const expectedComponentName = readExpectedComponentNameFromFilename(context.filename);
+        if (!expectedComponentName) {
+          context.report({
+            node,
+            messageId: "invalidComponentFileName",
+          });
+          return;
+        }
+
+        if (!isPascalCase(exportedComponentName)) {
+          context.report({
+            node: reportNode,
+            messageId: "invalidComponentExportName",
+          });
+        }
+
+        if (exportedComponentName === expectedComponentName) {
+          return;
+        }
+
+        const kebabFilename = `${exportedComponentName.replaceAll(/([a-z0-9])([A-Z])/gu, "$1-$2").toLowerCase()}.tsx`;
+
+        context.report({
+          node: reportNode,
+          messageId: "mismatchedComponentFileName",
+          data: {
+            exportedName: exportedComponentName,
+            pascalFilename: `${exportedComponentName}.tsx`,
+            kebabFilename,
+          },
+        });
+      },
+    };
+  },
+};
+
+export default componentFileNamingConventionRule;