@alexgorbatchev/typescript-ai-policy 1.0.0 → 1.0.2

package/README.md

@@ -114,6 +114,9 @@ If you want the semantic-fix CLI, install its tsgo backend too:
 bun add -d @typescript/native-preview
 ```
 
+The semantic-fix CLI requires Bun at runtime because the installed bin uses a Bun shebang. That means Bun must be
+installed and available on `PATH` when you run the command.
+
 ## Use
 
 `oxfmt.config.ts`
@@ -153,15 +156,18 @@ This package also uses its own shared configs at the repository root:
 - `oxfmt.config.ts`
 - `oxlint.config.ts`
 
-## Local semantic-fix tooling
+## Semantic-fix tooling
+
+The package includes a semantic-fix CLI backed by `tsgo --lsp --stdio`.
+
+Package-installed usage:
 
-The repository now includes a local semantic-fix command under `src/semantic-fixes/` that uses `tsgo --lsp --stdio` as its first real backend.
+- `bun run typescript-ai-policy-fix-semantic -- <target-directory>` — run Oxlint with this package's policy config, collect supported diagnostics, and apply semantic fixes to the target directory.
+- `bun run typescript-ai-policy-fix-semantic -- <target-directory> --dry-run` — print the planned semantic-fix scope without mutating files.
 
-Useful commands:
+Repository-local development usage:
 
-- `bun run fix:semantic -- <target-directory>` — run Oxlint with this repository's policy config, collect supported diagnostics, and apply semantic fixes to the target directory.
-- `bun run fix:semantic -- <target-directory> --dry-run` — print the planned semantic-fix scope without mutating files.
-- `typescript-ai-policy-fix-semantic <target-directory>` — run the same semantic fixer through the package-installed bin after installing this package and `@typescript/native-preview`.
+- `bun run fix:semantic -- <target-directory>` — run the same semantic fixer from this repository checkout while developing the package itself.
 
 Today the framework applies two conservative semantic fixes:
 
@@ -191,7 +197,7 @@ For rule-by-rule rationale plus good/bad examples, see [`src/oxlint/README.md`](
 | `@alexgorbatchev/no-react-create-element`                       | Regular application code must use JSX instead of `createElement`.                                                                                                                                                                                                         |
 | `@alexgorbatchev/require-component-root-testid`                 | Non-story exported React components must render a DOM root with `data-testid`/`testId` exactly equal to the component name, and child ids must use `ComponentName--thing`.                                                                                                |
 | `@alexgorbatchev/component-file-contract`                       | Component ownership files may export exactly one main runtime component plus unrestricted type-only API.                                                                                                                                                                  |
-| `@alexgorbatchev/component-file-naming-convention`              | Component filenames must match their exported PascalCase component name in either PascalCase or kebab-case form.                                                                                                                                                          |
+| `@alexgorbatchev/component-file-naming-convention`              | Component filenames must match their exported PascalCase component name in either PascalCase or kebab-case form; non-component `.tsx` modules should be renamed to `.ts`.                                                                                                 |
 | `@alexgorbatchev/component-story-file-convention`               | Every component ownership file must have a matching `basename.stories.tsx` file somewhere under a sibling `stories/` directory.                                                                                                                                           |
 | `@alexgorbatchev/story-file-location-convention`                | Storybook files must live under sibling `stories/` directories and must still match a sibling component basename.                                                                                                                                                         |
 | `@alexgorbatchev/story-meta-type-annotation`                    | The default Storybook meta must use a typed `const meta: Meta<typeof ComponentName>` binding instead of object assertions.                                                                                                                                                |

package/package.json

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

package/src/oxlint/createOxlintConfig.ts

@@ -26,7 +26,7 @@ const DEFAULT_OXLINT_CONFIG = defineConfig({
     "**/.vitepress/cache",
     "**/.vitepress/dist",
   ],
-  plugins: ["unicorn", "typescript", "oxc", "react", "jsx-a11y", "jest"],
+  plugins: ["unicorn", "typescript", "oxc", "react", "jest"],
   jsPlugins: [
     {
       name: "@alexgorbatchev",

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

@@ -187,6 +187,10 @@ 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,
@@ -197,7 +201,7 @@ const componentFileNamingConventionRule: RuleModule = {
     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.',
+        'Rename this file so its basename can map deterministically to the exported component name. Use "ComponentName.tsx" or "component-name.tsx"; if this is not a component ownership file and does not need JSX syntax, rename it to a ".ts" file instead.',
       invalidComponentExportName:
         "Rename the exported component to PascalCase. Component ownership files must export a PascalCase component name.",
       mismatchedComponentFileName:
@@ -224,7 +228,7 @@ const componentFileNamingConventionRule: RuleModule = {
         const expectedComponentName = readExpectedComponentNameFromFilename(context.filename);
         if (!expectedComponentName) {
           context.report({
-            node,
+            node: readInvalidFilenameReportNode(node),
             messageId: "invalidComponentFileName",
           });
           return;

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

@@ -7,6 +7,7 @@ import {
   isExemptSupportBasename,
   isInStoriesDirectory,
   isInTestsDirectory,
+  readAbbreviatedSiblingDirectoryPath,
 } from "./helpers.ts";
 
 function readRequiredStoriesDirectoryPath(filename: string): string {
@@ -67,12 +68,12 @@ const componentStoryFileConventionRule: RuleModule = {
     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',
+        'Require every component ownership file to have a matching "basename.stories.tsx" file 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 "{{ requiredStoryFileName }}" under "{{ requiredStoriesDirectoryPath }}". Component ownership files must keep their Storybook coverage under a sibling "stories/" directory.',
     },
   },
   create(context) {
@@ -87,6 +88,7 @@ const componentStoryFileConventionRule: RuleModule = {
     return {
       Program(node: AstProgram) {
         const requiredStoriesDirectoryPath = readRequiredStoriesDirectoryPath(context.filename);
+        const displayedStoriesDirectoryPath = readAbbreviatedSiblingDirectoryPath(context.filename, "stories");
         const requiredStoryFileName = readRequiredStoryFileName(context.filename);
         if (findDescendantFilePath(requiredStoriesDirectoryPath, requiredStoryFileName)) {
           return;
@@ -96,7 +98,7 @@ const componentStoryFileConventionRule: RuleModule = {
           node: readReportNode(node),
           messageId: "missingComponentStoryFile",
           data: {
-            requiredStoriesDirectoryPath,
+            requiredStoriesDirectoryPath: displayedStoriesDirectoryPath,
             requiredStoryFileName,
           },
         });

package/src/oxlint/rules/helpers.ts

@@ -74,6 +74,16 @@ export function readPathFromDirectory(filename: string, expectedDirectoryName: s
   return pathSegments.slice(directoryIndex + 1).join("/");
 }
 
+export function readAbbreviatedPath(path: string, segmentCount = 3): string {
+  const displayedPathSegments = getPathSegments(path).slice(-segmentCount);
+
+  return `.../${displayedPathSegments.join("/")}`;
+}
+
+export function readAbbreviatedSiblingDirectoryPath(filename: string, siblingDirectoryName: string): string {
+  return readAbbreviatedPath(`${dirname(filename)}/${siblingDirectoryName}`);
+}
+
 export function readPathFromFirstMatchingDirectory(
   filename: string,
   expectedDirectoryNames: DirectoryNames,

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

@@ -1,10 +1,12 @@
 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,
+  readAbbreviatedSiblingDirectoryPath,
 } from "./helpers.ts";
 
 function readRequiredTestsDirectoryPath(filename: string): string {
@@ -18,17 +20,21 @@ 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,
     docs: {
       description:
-        'Require every hook ownership file to have a matching "basename.test.ts" or ".test.tsx" file somewhere under a sibling "__tests__/" directory',
+        'Require every hook ownership file to have a matching "basename.test.ts" or ".test.tsx" file 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 "{{ requiredTestFileName }}" under "{{ requiredTestsDirectoryPath }}". Hook ownership files must keep their tests under a sibling "__tests__/" directory.',
     },
   },
   create(context) {
@@ -39,17 +45,18 @@ const hookTestFileConventionRule: RuleModule = {
     return {
       Program(node: AstProgram) {
         const requiredTestsDirectoryPath = readRequiredTestsDirectoryPath(context.filename);
+        const displayedTestsDirectoryPath = readAbbreviatedSiblingDirectoryPath(context.filename, "__tests__");
         const requiredTestFileName = readRequiredHookTestFileName(context.filename);
         if (findDescendantFilePath(requiredTestsDirectoryPath, requiredTestFileName)) {
           return;
         }
 
         context.report({
-          node,
+          node: readReportNode(node),
           messageId: "missingHookTestFile",
           data: {
             requiredTestFileName,
-            requiredTestsDirectoryPath,
+            requiredTestsDirectoryPath: displayedTestsDirectoryPath,
           },
         });
       },

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

@@ -1,7 +1,13 @@
-import type { RuleModule } from "./types.ts";
+import type { TSESTree } from "@typescript-eslint/types";
+import type { AstProgram, RuleModule } from "./types.ts";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { getStorySourceBaseName, readPathFromStoriesDirectory, readRootPathBeforeDirectory } from "./helpers.ts";
+import {
+  getStorySourceBaseName,
+  readAbbreviatedPath,
+  readPathFromStoriesDirectory,
+  readRootPathBeforeDirectory,
+} from "./helpers.ts";
 
 function readRequiredSiblingComponentFilePath(filename: string): string | null {
   const storySourceBaseName = getStorySourceBaseName(filename);
@@ -17,28 +23,33 @@ 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,
     docs: {
       description:
-        'Require Storybook files to live somewhere under a sibling "stories/" directory and match a sibling component ownership file basename',
+        'Require Storybook files to live under a sibling "stories/" directory and match a sibling component ownership file basename',
     },
     schema: [],
     messages: {
       invalidStoryFileLocation:
         'Move this story file under a "stories/" directory. Storybook files must not live outside a sibling "stories/" tree.',
       missingSiblingComponent:
-        'Rename or move this story so it matches an existing sibling component ownership file. Expected "{{ requiredComponentFilePath }}" to exist for this story file.',
+        'Rename or move this story so it matches an existing sibling component ownership file. "{{ requiredComponentFilePath }}" must exist for this story file.',
     },
   },
   create(context) {
     return {
-      Program(node) {
+      Program(node: AstProgram) {
+        const reportNode = readReportNode(node);
         const relativeStoryPath = readPathFromStoriesDirectory(context.filename);
         if (relativeStoryPath === null) {
           context.report({
-            node,
+            node: reportNode,
             messageId: "invalidStoryFileLocation",
           });
           return;
@@ -50,10 +61,10 @@ const storyFileLocationConventionRule: RuleModule = {
         }
 
         context.report({
-          node,
+          node: reportNode,
           messageId: "missingSiblingComponent",
           data: {
-            requiredComponentFilePath,
+            requiredComponentFilePath: readAbbreviatedPath(requiredComponentFilePath),
           },
         });
       },