@alexgorbatchev/typescript-ai-policy 1.0.3 → 1.0.5

package/README.md

@@ -10,6 +10,9 @@ as direct repair instructions so an agent can make the required change instead o
 
 The shared Oxlint policy is implemented in TypeScript-authored custom rule modules under `src/oxlint/`.
 
+File-level diagnostics are anchored to the first top-level syntax node when possible so editors highlight a concrete
+repair location instead of painting the entire file.
+
 Upstream rules stay enabled as baseline correctness guardrails around that stricter policy layer.
 
 These rules are designed to work as a **full policy set**, not as a grab bag of independent preferences. Disabling one
@@ -149,6 +152,15 @@ conflicting keys.
 For Oxlint specifically, consumer configs are extension-only: if the callback tries to redefine any shared rule name,
 the factory throws with guidance to change the shared package instead of overriding that rule downstream.
 
+When you run Oxlint manually, use Bun to launch the CLI:
+
+```bash
+bun --bun oxlint .
+```
+
+Treat `bun --bun oxlint ...` as the canonical invocation form for this package and for consumer repositories using
+these TypeScript config entrypoints.
+
 ## Local package setup
 
 This package also uses its own shared configs at the repository root:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexgorbatchev/typescript-ai-policy",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Shared TypeScript AI policy configs and Oxlint rules",
   "homepage": "https://github.com/alexgorbatchev/typescript-ai-policy#readme",
   "repository": {

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

@@ -1,5 +1,11 @@
 import type { RuleModule } from "./types.ts";
-import { getBaseName, getExtension, isExemptSupportBasename, readPathFromFirstMatchingDirectory } from "./helpers.ts";
+import {
+  getBaseName,
+  getExtension,
+  isExemptSupportBasename,
+  readPathFromFirstMatchingDirectory,
+  readProgramReportNode,
+} 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"]);
@@ -50,7 +56,7 @@ const componentDirectoryFileConventionRule: RuleModule = {
         }
 
         context.report({
-          node,
+          node: readProgramReportNode(node),
           messageId: "invalidComponentDirectoryFile",
           data: {
             directoryName: componentDirectoryMatch.directoryName,

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

@@ -15,6 +15,7 @@ import {
   isInTestsDirectory,
   isTypeDeclaration,
   readDeclarationIdentifierNames,
+  readProgramReportNode,
   readMultipartComponentRootName,
   readPatternIdentifierNames,
   unwrapExpression,
@@ -286,7 +287,7 @@ const componentFileContractRule: RuleModule = {
         const runtimeExportEntries = readRuntimeExportEntries(node);
         if (runtimeExportEntries.length === 0) {
           context.report({
-            node,
+            node: readProgramReportNode(node),
             messageId: "missingMainComponentExport",
           });
           return;

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

@@ -1,5 +1,5 @@
 import type { RuleModule } from "./types.ts";
-import { getExtension, hasPathSegment, isInTestsDirectory } from "./helpers.ts";
+import { getExtension, hasPathSegment, isInTestsDirectory, readProgramReportNode } from "./helpers.ts";
 
 const COMPONENT_DIRECTORY_NAMES = new Set(["components", "templates", "layouts"]);
 
@@ -32,7 +32,7 @@ const componentFileLocationConventionRule: RuleModule = {
         }
 
         context.report({
-          node,
+          node: readProgramReportNode(node),
           messageId: "unexpectedComponentFileLocation",
         });
       },

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

@@ -15,6 +15,7 @@ import {
   isPascalCase,
   readDeclarationIdentifierNames,
   readMultipartComponentRootName,
+  readProgramReportNode,
 } from "./helpers.ts";
 
 function isTypeOnlyExportSpecifier(
@@ -187,10 +188,6 @@ function readExpectedComponentNameFromFilename(filename: string): string | null
     .join("");
 }
 
-function readInvalidFilenameReportNode(program: AstProgram): TSESTree.Node {
-  return program.body[0] ?? program;
-}
-
 const componentFileNamingConventionRule: RuleModule = {
   meta: {
     type: "problem" as const,
@@ -228,7 +225,7 @@ const componentFileNamingConventionRule: RuleModule = {
         const expectedComponentName = readExpectedComponentNameFromFilename(context.filename);
         if (!expectedComponentName) {
           context.report({
-            node: readInvalidFilenameReportNode(node),
+            node: readProgramReportNode(node),
             messageId: "invalidComponentFileName",
           });
           return;

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

@@ -1,5 +1,4 @@
-import type { TSESTree } from "@typescript-eslint/types";
-import type { AstProgram, AstProgramStatement, RuleModule } from "./types.ts";
+import type { AstNode, AstProgram, RuleModule } from "./types.ts";
 import { dirname, join } from "node:path";
 import {
   findDescendantFilePath,
@@ -8,6 +7,7 @@ import {
   isInStoriesDirectory,
   isInTestsDirectory,
   readAbbreviatedSiblingDirectoryPath,
+  readProgramReportNode,
 } from "./helpers.ts";
 
 function readRequiredStoriesDirectoryPath(filename: string): string {
@@ -20,9 +20,7 @@ function readRequiredStoryFileName(filename: string): string {
   return `${sourceBaseName}.stories.tsx`;
 }
 
-type ReportNode = AstProgramStatement | TSESTree.Node;
-
-function readReportNode(program: AstProgram): ReportNode {
+function readReportNode(program: AstProgram): AstNode {
   for (const statement of program.body) {
     if (statement.type === "ExportNamedDeclaration") {
       if (statement.exportKind === "type") {
@@ -60,7 +58,7 @@ function readReportNode(program: AstProgram): ReportNode {
     }
   }
 
-  return program.body[0] ?? program;
+  return readProgramReportNode(program);
 }
 
 const componentStoryFileConventionRule: RuleModule = {

package/src/oxlint/rules/helpers.ts

@@ -7,6 +7,7 @@ import type {
   AstDestructuringPattern,
   AstFunctionLike,
   AstNode,
+  AstProgram,
   AstTypeDeclaration,
 } from "./types.ts";
 
@@ -84,6 +85,10 @@ export function readAbbreviatedSiblingDirectoryPath(filename: string, siblingDir
   return readAbbreviatedPath(`${dirname(filename)}/${siblingDirectoryName}`);
 }
 
+export function readProgramReportNode(program: AstProgram): AstNode {
+  return program.body[0] ?? program;
+}
+
 export function readPathFromFirstMatchingDirectory(
   filename: string,
   expectedDirectoryNames: DirectoryNames,

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

@@ -7,7 +7,14 @@ import type {
   AstProgramStatement,
   RuleModule,
 } from "./types.ts";
-import { isExemptSupportBasename, isTypeDeclaration, readPatternIdentifierNames } from "./helpers.ts";
+import {
+  isExemptSupportBasename,
+  isInStoriesDirectory,
+  isInTestsDirectory,
+  isTypeDeclaration,
+  readPatternIdentifierNames,
+  readProgramReportNode,
+} from "./helpers.ts";
 
 type HookRuntimeExportEntry = {
   kind:
@@ -138,7 +145,11 @@ const hookFileContractRule: RuleModule = {
     },
   },
   create(context) {
-    if (isExemptSupportBasename(context.filename)) {
+    if (
+      isExemptSupportBasename(context.filename) ||
+      isInStoriesDirectory(context.filename) ||
+      isInTestsDirectory(context.filename)
+    ) {
       return {};
     }
 
@@ -147,7 +158,7 @@ const hookFileContractRule: RuleModule = {
         const runtimeExportEntries = readRuntimeExportEntries(node);
         if (runtimeExportEntries.length === 0) {
           context.report({
-            node,
+            node: readProgramReportNode(node),
             messageId: "missingMainHookExport",
           });
           return;

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

@@ -1,11 +1,19 @@
 import type {
   AstExportNamedDeclaration,
   AstExportSpecifier,
+  AstNode,
   AstProgram,
   AstProgramStatement,
   RuleModule,
 } from "./types.ts";
-import { getFilenameWithoutExtension, isExemptSupportBasename, readDeclarationIdentifierNames } from "./helpers.ts";
+import {
+  getFilenameWithoutExtension,
+  isExemptSupportBasename,
+  isInStoriesDirectory,
+  isInTestsDirectory,
+  readDeclarationIdentifierNames,
+  readProgramReportNode,
+} from "./helpers.ts";
 
 function isTypeOnlyExportSpecifier(
   specifier: AstExportSpecifier,
@@ -22,18 +30,23 @@ function readExportedSpecifierName(specifier: AstExportSpecifier): string {
   return String(specifier.exported.value);
 }
 
-function readFirstRuntimeExportName(program: AstProgram): string | null {
+type HookRuntimeExportEntry = {
+  name: string;
+  reportNode: AstNode;
+};
+
+function readFirstRuntimeExportEntry(program: AstProgram): HookRuntimeExportEntry | null {
   for (const statement of program.body) {
-    const exportName = readStatementRuntimeExportName(statement);
-    if (exportName !== null) {
-      return exportName;
+    const exportEntry = readStatementRuntimeExportEntry(statement);
+    if (exportEntry !== null) {
+      return exportEntry;
     }
   }
 
   return null;
 }
 
-function readStatementRuntimeExportName(statement: AstProgramStatement): string | null {
+function readStatementRuntimeExportEntry(statement: AstProgramStatement): HookRuntimeExportEntry | null {
   if (statement.type !== "ExportNamedDeclaration") {
     return null;
   }
@@ -50,10 +63,28 @@ function readStatementRuntimeExportName(statement: AstProgramStatement): string
 
     if (statement.declaration.type === "VariableDeclaration") {
       const firstDeclarator = statement.declaration.declarations[0];
-      return firstDeclarator?.id.type === "Identifier" ? firstDeclarator.id.name : null;
+      if (!firstDeclarator || firstDeclarator.id.type !== "Identifier") {
+        return null;
+      }
+
+      return {
+        name: firstDeclarator.id.name,
+        reportNode: firstDeclarator.id,
+      };
+    }
+
+    const declarationName = readDeclarationIdentifierNames(statement.declaration)[0];
+    if (!declarationName) {
+      return null;
     }
 
-    return readDeclarationIdentifierNames(statement.declaration)[0] ?? null;
+    const reportNode =
+      "id" in statement.declaration && statement.declaration.id ? statement.declaration.id : statement.declaration;
+
+    return {
+      name: declarationName,
+      reportNode,
+    };
   }
 
   const runtimeSpecifier = statement.specifiers.find((specifier) => !isTypeOnlyExportSpecifier(specifier, statement));
@@ -61,7 +92,10 @@ function readStatementRuntimeExportName(statement: AstProgramStatement): string
     return null;
   }
 
-  return readExportedSpecifierName(runtimeSpecifier);
+  return {
+    name: readExportedSpecifierName(runtimeSpecifier),
+    reportNode: runtimeSpecifier.exported.type === "Identifier" ? runtimeSpecifier.exported : runtimeSpecifier,
+  };
 }
 
 function readExpectedHookNameFromFilename(filename: string): string | null {
@@ -101,21 +135,26 @@ const hookFileNamingConventionRule: RuleModule = {
     },
   },
   create(context) {
-    if (isExemptSupportBasename(context.filename)) {
+    if (
+      isExemptSupportBasename(context.filename) ||
+      isInStoriesDirectory(context.filename) ||
+      isInTestsDirectory(context.filename)
+    ) {
       return {};
     }
 
     return {
       Program(node) {
-        const exportedHookName = readFirstRuntimeExportName(node);
-        if (!exportedHookName) {
+        const exportedHookEntry = readFirstRuntimeExportEntry(node);
+        if (!exportedHookEntry) {
           return;
         }
 
+        const { name: exportedHookName, reportNode } = exportedHookEntry;
         const expectedHookName = readExpectedHookNameFromFilename(context.filename);
         if (!expectedHookName) {
           context.report({
-            node,
+            node: readProgramReportNode(node),
             messageId: "invalidHookFileName",
           });
           return;
@@ -123,7 +162,7 @@ const hookFileNamingConventionRule: RuleModule = {
 
         if (!/^use[A-Z][A-Za-z0-9]*$/u.test(exportedHookName)) {
           context.report({
-            node,
+            node: reportNode,
             messageId: "invalidHookExportName",
           });
         }
@@ -135,7 +174,7 @@ const hookFileNamingConventionRule: RuleModule = {
         const extension = context.filename.endsWith(".tsx") ? ".tsx" : ".ts";
 
         context.report({
-          node,
+          node: reportNode,
           messageId: "mismatchedHookFileName",
           data: {
             exportedName: exportedHookName,

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

@@ -1,12 +1,14 @@
 import type { AstProgram, RuleModule } from "./types.ts";
-import type { TSESTree } from "@typescript-eslint/types";
 import { dirname, join } from "node:path";
 import {
   findDescendantFilePath,
   getBaseName,
   getFilenameWithoutExtension,
   isExemptSupportBasename,
+  isInStoriesDirectory,
+  isInTestsDirectory,
   readAbbreviatedSiblingDirectoryPath,
+  readProgramReportNode,
 } from "./helpers.ts";
 
 function readRequiredTestsDirectoryPath(filename: string): string {
@@ -20,10 +22,6 @@ function readRequiredHookTestFileName(filename: string): string {
   return `${sourceBaseName}${testExtension}`;
 }
 
-function readReportNode(program: AstProgram): TSESTree.Node {
-  return program.body[0] ?? program;
-}
-
 const hookTestFileConventionRule: RuleModule = {
   meta: {
     type: "problem" as const,
@@ -38,7 +36,11 @@ const hookTestFileConventionRule: RuleModule = {
     },
   },
   create(context) {
-    if (isExemptSupportBasename(context.filename)) {
+    if (
+      isExemptSupportBasename(context.filename) ||
+      isInStoriesDirectory(context.filename) ||
+      isInTestsDirectory(context.filename)
+    ) {
       return {};
     }
 
@@ -52,7 +54,7 @@ const hookTestFileConventionRule: RuleModule = {
         }
 
         context.report({
-          node: readReportNode(node),
+          node: readProgramReportNode(node),
           messageId: "missingHookTestFile",
           data: {
             requiredTestFileName,

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

@@ -4,6 +4,7 @@ import {
   getFilenameWithoutExtension,
   isStrictAreaAllowedSupportFile,
   readPathFromDirectory,
+  readProgramReportNode,
 } from "./helpers.ts";
 
 function isAllowedHookOwnershipBasename(filename: string): boolean {
@@ -61,7 +62,7 @@ const hooksDirectoryFileConventionRule: RuleModule = {
         }
 
         context.report({
-          node,
+          node: readProgramReportNode(node),
           messageId: "invalidHooksDirectoryFile",
           data: {
             relativePath: relativePath || ".",

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

@@ -1,6 +1,6 @@
 import type { TSESTree } from "@typescript-eslint/types";
 import type { AstProgramStatement, RuleModule } from "./types.ts";
-import { getBaseName } from "./helpers.ts";
+import { getBaseName, readProgramReportNode } from "./helpers.ts";
 
 type IndexMessageId = "unexpectedIndexExport" | "unexpectedIndexStatement";
 
@@ -86,10 +86,6 @@ function readExportDefaultReportNode(node: TSESTree.ExportDefaultDeclaration): T
   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) {

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

@@ -1,7 +1,7 @@
 import type { RuleModule } from "./types.ts";
 import { existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { readPathFromStoriesDirectory, readPathFromTestsDirectory } from "./helpers.ts";
+import { readPathFromStoriesDirectory, readPathFromTestsDirectory, readProgramReportNode } from "./helpers.ts";
 
 const FIXTURE_ENTRYPOINT_CANDIDATE_KEYS = ["fixtures.ts", "fixtures.tsx", "fixtures/"];
 
@@ -127,7 +127,7 @@ const singleFixtureEntrypointRule: RuleModule = {
     return {
       Program(node) {
         context.report({
-          node,
+          node: readProgramReportNode(node),
           messageId: "conflictingFixtureEntrypoints",
           data: {
             directoryLabel,

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

@@ -1,5 +1,5 @@
 import type { RuleModule } from "./types.ts";
-import { isInStoriesDirectory, readPathFromStoriesDirectory } from "./helpers.ts";
+import { isInStoriesDirectory, readPathFromStoriesDirectory, readProgramReportNode } 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"]);
@@ -41,7 +41,7 @@ const storiesDirectoryFileConventionRule: RuleModule = {
         }
 
         context.report({
-          node,
+          node: readProgramReportNode(node),
           messageId: "invalidStoriesDirectoryFile",
           data: {
             relativePath,

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

@@ -1,6 +1,12 @@
 import type { TSESTree } from "@typescript-eslint/types";
 import type { AstProgram, RuleModule } from "./types.ts";
-import { getStorySourceBaseName, isPascalCase, unwrapExpression, unwrapTypeScriptExpression } from "./helpers.ts";
+import {
+  getStorySourceBaseName,
+  isPascalCase,
+  readProgramReportNode,
+  unwrapExpression,
+  unwrapTypeScriptExpression,
+} from "./helpers.ts";
 
 type StoryExportRecord = {
   exportedName: string;
@@ -245,7 +251,7 @@ const storyExportContractRule: RuleModule = {
 
         if (storyEntries.length === 0) {
           context.report({
-            node,
+            node: readProgramReportNode(node),
             messageId: "missingStoryExport",
           });
           return;
@@ -285,7 +291,7 @@ const storyExportContractRule: RuleModule = {
         const exportedStoryEntries = storyEntries.filter((storyEntry) => storyEntry.exports.length > 0);
         if (exportedStoryEntries.length === 0) {
           context.report({
-            node,
+            node: readProgramReportNode(node),
             messageId: "missingStoryExport",
           });
           return;

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

@@ -1,4 +1,3 @@
-import type { TSESTree } from "@typescript-eslint/types";
 import type { AstProgram, RuleModule } from "./types.ts";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -6,6 +5,7 @@ import {
   getStorySourceBaseName,
   readAbbreviatedPath,
   readPathFromStoriesDirectory,
+  readProgramReportNode,
   readRootPathBeforeDirectory,
 } from "./helpers.ts";
 
@@ -23,10 +23,6 @@ function readRequiredSiblingComponentFilePath(filename: string): string | null {
   return join(siblingDirectoryPath, `${storySourceBaseName}.tsx`);
 }
 
-function readReportNode(program: AstProgram): TSESTree.Node {
-  return program.body[0] ?? program;
-}
-
 const storyFileLocationConventionRule: RuleModule = {
   meta: {
     type: "problem" as const,
@@ -45,7 +41,7 @@ const storyFileLocationConventionRule: RuleModule = {
   create(context) {
     return {
       Program(node: AstProgram) {
-        const reportNode = readReportNode(node);
+        const reportNode = readProgramReportNode(node);
         const relativeStoryPath = readPathFromStoriesDirectory(context.filename);
         if (relativeStoryPath === null) {
           context.report({

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

@@ -1,6 +1,6 @@
 import type { TSESTree } from "@typescript-eslint/types";
 import type { AstProgram, RuleModule } from "./types.ts";
-import { unwrapExpression } from "./helpers.ts";
+import { readProgramReportNode, unwrapExpression } from "./helpers.ts";
 
 type MetaBinding = {
   declaration: TSESTree.VariableDeclaration;
@@ -79,7 +79,7 @@ const storyMetaTypeAnnotationRule: RuleModule = {
         const defaultExportDeclaration = readDefaultExportDeclaration(node);
         if (!defaultExportDeclaration || defaultExportDeclaration.declaration.type !== "Identifier") {
           context.report({
-            node: defaultExportDeclaration ?? node,
+            node: defaultExportDeclaration ?? readProgramReportNode(node),
             messageId: "invalidMetaBinding",
           });
           return;

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

@@ -1,13 +1,11 @@
-import type { AstExpression, AstProgram, AstProgramStatement, RuleModule } from "./types.ts";
-import { getBaseName, isInTestsDirectory } from "./helpers.ts";
+import type { AstExpression, RuleModule } from "./types.ts";
+import { getBaseName, isInTestsDirectory, readProgramReportNode } 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;
@@ -25,10 +23,6 @@ function readCallTargetName(node: AstExpression): string | null {
   return null;
 }
 
-function readProgramReportNode(node: AstProgram): ProgramReportNode {
-  return node.body[0] ?? node;
-}
-
 const testFileLocationConventionRule: RuleModule = {
   meta: {
     type: "problem" as const,

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

@@ -1,5 +1,5 @@
 import type { RuleModule } from "./types.ts";
-import { isInTestsDirectory, readPathFromTestsDirectory } from "./helpers.ts";
+import { isInTestsDirectory, readPathFromTestsDirectory, readProgramReportNode } 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"]);
@@ -41,7 +41,7 @@ const testsDirectoryFileConventionRule: RuleModule = {
         }
 
         context.report({
-          node,
+          node: readProgramReportNode(node),
           messageId: "invalidTestsDirectoryFile",
           data: {
             relativePath,