@nt-ai-lab/opencode-skillz 0.3.4 → 0.3.6

package/commands/implement.md

@@ -0,0 +1,18 @@
+---
+description: Implement the requested changes or specified document with small-step lint verification
+---
+
+Implement:
+$ARGUMENTS
+
+
+Implement the required task to the highest standards possible. Do not take shortcuts, do not rush, do not jump to the easiest solution to make the code pass. Think carefully, explore options and write the code that is easiest to read, easiest change, and will not break in production.
+
+## Linting
+
+After each small TypeScript code change, call `nt_skillz_lint` with only the `files` argument for the changed `.ts` or `.tsx` file or files from that step.
+
+- do not pass `base` or `head` during normal implementation work
+- all lint errors on new code must be addressed before continuing
+- if the lint fails on existing code, ignore the error unless it is very close to the new code
+- line-length limits do not count as existing code; if new code causes a file-length lint error, it must be fixed

package/dist/plugin-registry/index.js

@@ -1,10 +1,12 @@
 import { createDontStopHooks } from "../commands/dont-stop/index.js";
+import { LINT_TOOL_NAME, lintTool, } from "../tools/lint.js";
 import { registerAgents } from "./agents.js";
 import { registerCommands } from "./commands.js";
 export function createPluginRegistry(input, pluginRoot) {
     const dontStopHooks = createDontStopHooks(input.client);
     return {
         ...dontStopHooks,
+        tool: { [LINT_TOOL_NAME]: lintTool },
         config: async (config) => {
             config.command ??= {};
             config.agent ??= {};

package/dist/tools/lint.d.ts

@@ -0,0 +1,27 @@
+interface PortableLintRequest {
+    repositoryRoot?: string;
+    files?: string[];
+    base?: string;
+    head?: string;
+}
+interface PortableLintOutcome {
+    exitCode: number;
+    output: string;
+}
+export declare const LINT_TOOL_NAME = "nt_skillz_lint";
+export declare function runPortableLint(request: PortableLintRequest): Promise<PortableLintOutcome>;
+export declare function runPortableLintFromCommandLine(commandLineArguments: string[]): Promise<number>;
+export declare const lintTool: {
+    description: string;
+    args: {
+        files: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        base: import("zod").ZodOptional<import("zod").ZodString>;
+        head: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        files?: string[] | undefined;
+        base?: string | undefined;
+        head?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
+export {};

package/dist/tools/lint.js

@@ -0,0 +1,249 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { ESLint } from "eslint";
+import { tool } from "@opencode-ai/plugin";
+class UsageError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+class GitCommandError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+class MissingLocalDependencyError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+class LintExecutionError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+const toolDirectory = path.dirname(fileURLToPath(import.meta.url));
+const toolRepositoryRoot = path.resolve(toolDirectory, "..", "..");
+const eslintCliPath = path.join(toolRepositoryRoot, "node_modules", "eslint", "bin", "eslint.js");
+const eslintConfigPath = path.join(toolRepositoryRoot, "scripts", "living-architecture-eslint.config.mjs");
+const gitBinaryPath = "/usr/bin/git";
+export const LINT_TOOL_NAME = "nt_skillz_lint";
+function normalizeOptionalText(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmedValue = value.trim();
+    if (!trimmedValue) {
+        return undefined;
+    }
+    return trimmedValue;
+}
+function resolveDirectory(directoryPath) {
+    const absoluteDirectoryPath = path.resolve(directoryPath);
+    if (!fs.existsSync(absoluteDirectoryPath)) {
+        throw new UsageError(`Expected repository path to exist. Got ${absoluteDirectoryPath}.`);
+    }
+    if (!fs.statSync(absoluteDirectoryPath).isDirectory()) {
+        throw new UsageError(`Expected repository path to be a directory. Got ${absoluteDirectoryPath}.`);
+    }
+    return absoluteDirectoryPath;
+}
+function ensureSupportedFilePath(filePath) {
+    if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
+        return;
+    }
+    throw new UsageError(`Expected a TypeScript file path ending in .ts or .tsx. Got ${filePath}.`);
+}
+function normalizeFilePaths(filePaths) {
+    const normalizedFilePaths = (filePaths ?? []).map((filePath) => filePath.trim()).filter(Boolean);
+    normalizedFilePaths.forEach(ensureSupportedFilePath);
+    return normalizedFilePaths;
+}
+function ensureLocalDependencies() {
+    if (fs.existsSync(eslintCliPath)) {
+        return;
+    }
+    throw new MissingLocalDependencyError(`Expected ESLint dependencies to be installed in ${toolRepositoryRoot}.`);
+}
+function runGitCommand(repositoryRoot, gitArguments) {
+    const gitResult = spawnSync(gitBinaryPath, ["-C", repositoryRoot, ...gitArguments], { encoding: "utf8" });
+    if (gitResult.error) {
+        throw new GitCommandError(`Expected git command to run. Got ${gitResult.error.message}.`);
+    }
+    if (gitResult.status === 0) {
+        return gitResult.stdout;
+    }
+    const errorOutput = gitResult.stderr.trim() || gitResult.stdout.trim() || "git command failed";
+    throw new GitCommandError(`Expected git command to succeed. Got ${errorOutput}.`);
+}
+function readChangedTypeScriptFiles(repositoryRoot, baseReference, headReference) {
+    const diffRange = `${baseReference}...${headReference}`;
+    const output = runGitCommand(repositoryRoot, [
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMR",
+        diffRange,
+        "--",
+        "*.ts",
+        "*.tsx",
+    ]);
+    return output.split("\n").filter(Boolean);
+}
+function readTrackedAndUntrackedTypeScriptFiles(repositoryRoot) {
+    const output = runGitCommand(repositoryRoot, [
+        "ls-files",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--",
+        "*.ts",
+        "*.tsx",
+    ]);
+    return output.split("\n").filter(Boolean);
+}
+function ensureValidLintRequest(baseReference, headReference, filePaths) {
+    if (baseReference && filePaths.length > 0) {
+        throw new UsageError("Expected either file paths or base reference. Got both.");
+    }
+    if (!baseReference && headReference) {
+        throw new UsageError("Expected head reference to be used together with base reference.");
+    }
+}
+function resolveLintTargets(repositoryRoot, baseReference, headReference, filePaths) {
+    if (filePaths.length > 0) {
+        return filePaths;
+    }
+    if (baseReference) {
+        return readChangedTypeScriptFiles(repositoryRoot, baseReference, headReference ?? "HEAD");
+    }
+    return readTrackedAndUntrackedTypeScriptFiles(repositoryRoot);
+}
+function createLintTitle(filePaths, baseReference) {
+    if (filePaths.length > 0) {
+        return `Lint ${filePaths.length} TypeScript file(s)`;
+    }
+    if (baseReference) {
+        return `Lint TypeScript changes from ${baseReference}`;
+    }
+    return "Lint current TypeScript files";
+}
+async function runEslint(repositoryRoot, lintTargets) {
+    const previousLintRepositoryRoot = process.env.NT_SKILLZ_LINT_REPO_ROOT;
+    process.env.NT_SKILLZ_LINT_REPO_ROOT = repositoryRoot;
+    const eslint = new ESLint({
+        cwd: repositoryRoot,
+        errorOnUnmatchedPattern: false,
+        overrideConfigFile: eslintConfigPath,
+        warnIgnored: false,
+    });
+    try {
+        const lintResults = await eslint.lintFiles(lintTargets);
+        const formatter = await eslint.loadFormatter("stylish");
+        const formattedOutput = (await formatter.format(lintResults)).trim();
+        const errorCount = lintResults.reduce((count, lintResult) => count + lintResult.errorCount + lintResult.fatalErrorCount, 0);
+        return {
+            exitCode: errorCount > 0 ? 1 : 0,
+            output: formattedOutput,
+        };
+    }
+    finally {
+        if (previousLintRepositoryRoot) {
+            process.env.NT_SKILLZ_LINT_REPO_ROOT = previousLintRepositoryRoot;
+        }
+        else {
+            delete process.env.NT_SKILLZ_LINT_REPO_ROOT;
+        }
+    }
+}
+function parsePortableLintCommandLine(commandLineArguments) {
+    const parsedArguments = parseArgs({
+        args: commandLineArguments,
+        options: {
+            repo: { type: "string" },
+            base: { type: "string" },
+            head: { type: "string" },
+            help: {
+                type: "boolean",
+                short: "h",
+            },
+        },
+        allowPositionals: true,
+    });
+    if (parsedArguments.values.help) {
+        process.stdout.write([
+            "Usage: ./scripts/lint-ts.sh [--repo PATH] [--base REF] [--head REF] [file ...]",
+            "",
+            "Examples:",
+            "  ./scripts/lint-ts.sh --repo ../living-architecture --base origin/main",
+            "  ./scripts/lint-ts.sh --repo ../living-architecture packages/example/src/example.ts",
+            "  ./scripts/lint-ts.sh src/example.ts",
+        ].join("\n") + "\n");
+        process.exit(0);
+    }
+    return {
+        repositoryRoot: resolveDirectory(parsedArguments.values.repo ?? process.cwd()),
+        files: normalizeFilePaths(parsedArguments.positionals),
+        base: normalizeOptionalText(parsedArguments.values.base),
+        head: normalizeOptionalText(parsedArguments.values.head),
+    };
+}
+export async function runPortableLint(request) {
+    ensureLocalDependencies();
+    const repositoryRoot = resolveDirectory(request.repositoryRoot ?? process.cwd());
+    const baseReference = normalizeOptionalText(request.base);
+    const headReference = normalizeOptionalText(request.head);
+    const filePaths = normalizeFilePaths(request.files);
+    ensureValidLintRequest(baseReference, headReference, filePaths);
+    const lintTargets = resolveLintTargets(repositoryRoot, baseReference, headReference, filePaths);
+    if (lintTargets.length === 0) {
+        return {
+            exitCode: 0,
+            output: "No TypeScript files matched.",
+        };
+    }
+    return runEslint(repositoryRoot, lintTargets);
+}
+export async function runPortableLintFromCommandLine(commandLineArguments) {
+    const request = parsePortableLintCommandLine(commandLineArguments);
+    const outcome = await runPortableLint(request);
+    if (outcome.output) {
+        process.stdout.write(`${outcome.output}\n`);
+    }
+    return outcome.exitCode;
+}
+export const lintTool = tool({
+    description: "Run bundled TypeScript lint rules against current project files.",
+    args: {
+        files: tool.schema.array(tool.schema.string()).optional().describe("Relative .ts or .tsx file paths to lint."),
+        base: tool.schema.string().optional().describe("Base git reference for PR-style changed-file linting."),
+        head: tool.schema.string().optional().describe("Optional head git reference used with base."),
+    },
+    async execute(request, context) {
+        const filePaths = normalizeFilePaths(request.files);
+        const baseReference = normalizeOptionalText(request.base);
+        const headReference = normalizeOptionalText(request.head);
+        ensureValidLintRequest(baseReference, headReference, filePaths);
+        context.metadata({ title: createLintTitle(filePaths, baseReference) });
+        const outcome = await runPortableLint({
+            repositoryRoot: context.worktree,
+            files: filePaths,
+            base: baseReference,
+            head: headReference,
+        });
+        if (outcome.exitCode !== 0) {
+            throw new LintExecutionError(outcome.output || "Lint failed.");
+        }
+        return {
+            output: outcome.output || "Lint passed.",
+            metadata: {
+                base: baseReference ?? null,
+                fileCount: filePaths.length,
+                head: headReference ?? null,
+            },
+        };
+    },
+});

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
 export interface CommandDefinition {
     description?: string;
     template: string;
@@ -69,6 +70,7 @@ export interface OpencodeClient {
 }
 export interface PluginHooks {
     config?: (config: PluginConfig) => Promise<void>;
+    tool?: Record<string, ToolDefinition>;
     "command.execute.before"?: (input: CommandExecuteBeforeInput, output: CommandExecuteBeforeOutput) => Promise<void>;
     "experimental.chat.system.transform"?: (input: ChatSystemTransformInput, output: ChatSystemTransformOutput) => Promise<void>;
     event?: (input: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/opencode-skillz",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Bundled OpenCode commands and agents",
   "type": "module",
   "main": "dist/index.js",
@@ -19,12 +19,25 @@
     "dist",
     "commands",
     "agents",
+    "scripts",
     "AGENTS.md",
     "README.md"
   ],
+  "dependencies": {
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.5.0",
+    "@eslint/js": "^9.39.0",
+    "@opencode-ai/plugin": "^1.14.28",
+    "@stylistic/eslint-plugin": "^5.6.1",
+    "@vitest/eslint-plugin": "^1.0.1",
+    "eslint": "^9.39.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-sonarjs": "^3.0.5",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1"
+  },
   "devDependencies": {
-    "@types/node": "^24.7.2",
-    "typescript": "^5.9.3"
+    "@types/node": "^24.7.2"
   },
   "publishConfig": {
     "access": "public"

package/scripts/lint-ts.mjs

@@ -0,0 +1,10 @@
+import process from 'node:process'
+import { runPortableLintFromCommandLine } from '../dist/tools/lint.js'
+
+try {
+  process.exitCode = await runPortableLintFromCommandLine(process.argv.slice(2))
+} catch (error) {
+  const message = error instanceof Error ? error.message : `Expected an error message. Got ${String(error)}.`
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}

package/scripts/lint-ts.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+exec node "$script_dir/lint-ts.mjs" "$@"

package/scripts/living-architecture-eslint.config.mjs

@@ -0,0 +1,275 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import eslintComments from '@eslint-community/eslint-plugin-eslint-comments/configs'
+import importPlugin from 'eslint-plugin-import'
+import sonarjs from 'eslint-plugin-sonarjs'
+import stylistic from '@stylistic/eslint-plugin'
+import unicorn from 'eslint-plugin-unicorn'
+import vitest from '@vitest/eslint-plugin'
+import noGenericNames from './no-generic-names-eslint-rule.mjs'
+
+class MissingLintRepositoryRootError extends Error {
+  constructor() {
+    super('Expected NT_SKILLZ_LINT_REPO_ROOT environment variable.')
+  }
+}
+
+const lintRepositoryRoot = process.env.NT_SKILLZ_LINT_REPO_ROOT
+
+if (!lintRepositoryRoot) {
+  throw new MissingLintRepositoryRootError()
+}
+
+const typescriptFiles = ['**/*.ts', '**/*.tsx']
+const testFiles = ['**/*.spec.ts', '**/*.spec.tsx', '**/*.test.ts', '**/*.test.tsx']
+const thinLayerFiles = ['**/entrypoint/**/*.ts', '**/commands/**/*.ts', '**/queries/**/*.ts']
+const thinLayerIgnoredFiles = ['**/*.spec.ts', '**/*.test.ts']
+const ignoredPaths = [
+  '**/dist',
+  '**/out-tsc',
+  '**/node_modules',
+  '**/.nx',
+  '*.config.ts',
+  '*.config.mjs',
+  '*.config.js',
+  'vitest.workspace.ts',
+  '**/*.d.ts',
+  '**/test-output',
+  '**/api/generated/**',
+  '**/.vitepress/cache/**',
+  '.riviere/**',
+]
+
+const noLetRule = {
+  selector: 'VariableDeclaration[kind="let"]',
+  message: 'Use const. Avoid mutation.',
+}
+
+const noGenericErrorRule = {
+  selector: 'NewExpression[callee.name="Error"]',
+  message: 'Use custom precise error classes instead of generic Error or fail assertions in tests.',
+}
+
+const noEmptyStringFallbackRule = {
+  selector: 'LogicalExpression[operator="??"][right.type="Literal"][right.value=""]',
+  message:
+    'Banned: `?? \'\'` violates fail-fast principle. Never use empty string fallback. Options: (1) Fail fast if value should exist, (2) Handle undefined explicitly without empty string, (3) Create a type that represents emptiness.',
+}
+
+const restrictedSyntaxRules = ['error', noLetRule, noGenericErrorRule, noEmptyStringFallbackRule]
+
+const entrypointRestrictedSyntaxRules = [
+  'error',
+  noLetRule,
+  noGenericErrorRule,
+  {
+    selector: 'FunctionDeclaration:not([parent.type="ExportNamedDeclaration"])',
+    message: 'Entrypoints must not define private functions. Move logic to commands/, queries/, or infra/.',
+  },
+  {
+    selector: 'VariableDeclarator > ArrowFunctionExpression',
+    message: 'Entrypoints must not define private arrow functions. Move logic to commands/, queries/, or infra/.',
+  },
+  noEmptyStringFallbackRule,
+]
+
+const restrictedImportPatterns = [
+  {
+    group: ['*/utils/*', '*/utils', '*/utilities'],
+    message: 'No utils folders. Use domain-specific names.',
+  },
+  {
+    group: ['*/helpers/*', '*/helpers'],
+    message: 'No helpers folders. Use domain-specific names.',
+  },
+  {
+    group: ['*/common/*', '*/common'],
+    message: 'No common folders. Use domain-specific names.',
+  },
+  {
+    group: ['*/shared/*', '*/shared'],
+    message: 'No shared folders. Use domain-specific names.',
+  },
+  {
+    group: ['*/core/*', '*/core'],
+    message: 'No core folders. Use domain-specific names.',
+  },
+  {
+    group: ['*/src/lib/*', '*/src/lib', './lib/*', './lib', '../lib/*', '../lib'],
+    message: 'No lib folders in projects. Use domain-specific names.',
+  },
+]
+
+const namingConventionRules = [
+  'error',
+  {
+    selector: 'variable',
+    format: ['camelCase'],
+  },
+  {
+    selector: 'variable',
+    modifiers: ['const'],
+    format: ['camelCase', 'UPPER_CASE'],
+  },
+  {
+    selector: 'function',
+    format: ['camelCase', 'PascalCase'],
+  },
+  {
+    selector: 'parameter',
+    format: ['camelCase'],
+    leadingUnderscore: 'allow',
+  },
+  {
+    selector: 'typeLike',
+    format: ['PascalCase'],
+  },
+  {
+    selector: 'enumMember',
+    format: ['PascalCase'],
+  },
+  {
+    selector: 'objectLiteralProperty',
+    format: null,
+  },
+]
+
+export default tseslint.config(
+  {
+    files: typescriptFiles,
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+  },
+  {
+    ignores: ignoredPaths,
+  },
+  eslintComments.recommended,
+  {
+    rules: {
+      '@eslint-community/eslint-comments/no-use': ['error', { allow: [] }],
+    },
+  },
+  sonarjs.configs.recommended,
+  {
+    rules: {
+      'sonarjs/void-use': 'off',
+    },
+  },
+  {
+    files: typescriptFiles,
+    plugins: {
+      '@typescript-eslint': tseslint.plugin,
+      custom: {
+        rules: {
+          'no-generic-names': noGenericNames,
+        },
+      },
+      import: importPlugin,
+    },
+    languageOptions: {
+      parser: tseslint.parser,
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: lintRepositoryRoot,
+      },
+    },
+    rules: {
+      'import/extensions': ['error', 'never', { ts: 'never', tsx: 'never', js: 'never', json: 'always' }],
+      'custom/no-generic-names': 'error',
+      'no-warning-comments': 'off',
+      'multiline-comment-style': 'off',
+      'capitalized-comments': 'off',
+      'no-inline-comments': 'error',
+      'spaced-comment': 'off',
+      'no-negated-condition': 'error',
+      'no-restricted-syntax': restrictedSyntaxRules,
+      'prefer-const': 'error',
+      'no-var': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unsafe-assignment': 'error',
+      '@typescript-eslint/no-unsafe-member-access': 'error',
+      '@typescript-eslint/no-unsafe-call': 'error',
+      '@typescript-eslint/no-unsafe-return': 'error',
+      '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'never' }],
+      '@typescript-eslint/no-non-null-assertion': 'error',
+      '@typescript-eslint/prefer-includes': 'error',
+      '@typescript-eslint/prefer-nullish-coalescing': 'error',
+      '@typescript-eslint/prefer-optional-chain': 'error',
+      '@typescript-eslint/await-thenable': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': 'error',
+      'import/no-duplicates': 'error',
+      'no-restricted-imports': ['error', { patterns: restrictedImportPatterns }],
+      'max-lines': ['error', { max: 400, skipBlankLines: true, skipComments: true }],
+      'max-depth': ['error', 3],
+      complexity: ['error', 12],
+      'no-restricted-globals': [
+        'error',
+        {
+          name: '__dirname',
+          message: 'Use dirname(fileURLToPath(import.meta.url)) in ESM.',
+        },
+        {
+          name: '__filename',
+          message: 'Use fileURLToPath(import.meta.url) in ESM.',
+        },
+      ],
+      '@typescript-eslint/naming-convention': namingConventionRules,
+    },
+  },
+  {
+    files: typescriptFiles,
+    plugins: {
+      '@stylistic': stylistic,
+    },
+    rules: {
+      '@stylistic/indent': ['error', 2],
+      '@stylistic/object-curly-newline': ['error', { multiline: true, minProperties: 2 }],
+      '@stylistic/object-property-newline': ['error', { allowAllPropertiesOnSameLine: false }],
+    },
+  },
+  {
+    files: thinLayerFiles,
+    ignores: thinLayerIgnoredFiles,
+    rules: {
+      'max-lines': ['error', { max: 150, skipBlankLines: true, skipComments: true }],
+    },
+  },
+  {
+    files: ['**/entrypoint/**/*.ts'],
+    ignores: thinLayerIgnoredFiles,
+    rules: {
+      'no-restricted-syntax': entrypointRestrictedSyntaxRules,
+    },
+  },
+  {
+    files: typescriptFiles,
+    plugins: {
+      unicorn,
+    },
+    rules: {
+      'unicorn/prefer-string-replace-all': 'error',
+      'unicorn/prefer-type-error': 'error',
+    },
+  },
+  {
+    files: testFiles,
+    plugins: {
+      vitest,
+    },
+    rules: {
+      'vitest/no-conditional-expect': 'error',
+      'vitest/no-conditional-in-test': 'error',
+      'vitest/prefer-strict-equal': 'error',
+      'vitest/consistent-test-it': ['error', { fn: 'it' }],
+      'vitest/consistent-test-filename': ['error', { pattern: '.*\\.spec\\.[tj]sx?$' }],
+      'vitest/max-expects': ['error', { max: 4 }],
+      'vitest/prefer-called-with': 'error',
+      'vitest/prefer-to-have-length': 'error',
+      'vitest/require-to-throw-message': 'error',
+      'vitest/prefer-spy-on': 'error',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+    },
+  },
+)

package/scripts/no-generic-names-eslint-rule.mjs

@@ -0,0 +1,100 @@
+import path from 'node:path'
+
+const forbiddenWordSuggestions = {
+  utils: 'Use a domain-specific name that describes what it does.',
+  helpers: 'Use a purpose-specific name or fixtures for test data.',
+  helper: 'Use a purpose-specific name or fixtures for test data.',
+  service: 'Name it for the domain action it performs.',
+  services: 'Name it for the domain action it performs.',
+  manager: 'Name it for the responsibility it owns.',
+  managers: 'Name it for the responsibility it owns.',
+  processor: 'Name it for the domain work it performs.',
+  processors: 'Name it for the domain work it performs.',
+  data: 'Name it for the domain concept it represents.',
+}
+
+const forbiddenWords = Object.keys(forbiddenWordSuggestions)
+const forbiddenFilenamePattern = new RegExp(
+  `(^|/|-|[a-z])(${forbiddenWords.join('|')})(-|[.]ts$|[.]tsx$|/|$)`,
+  'i',
+)
+
+const findForbiddenWord = (text) => {
+  const lowercaseText = text.toLowerCase()
+  return forbiddenWords.find((forbiddenWord) => lowercaseText.includes(forbiddenWord))
+}
+
+const isForbiddenName = (name) => {
+  if (!name) {
+    return false
+  }
+
+  const lowercaseName = name.toLowerCase()
+  return forbiddenWords.some((forbiddenWord) => {
+    return lowercaseName === forbiddenWord || lowercaseName.startsWith(forbiddenWord) || lowercaseName.endsWith(forbiddenWord)
+  })
+}
+
+const createFilenameMessage = (filename) => {
+  const forbiddenWord = findForbiddenWord(filename)
+
+  if (!forbiddenWord) {
+    return 'Generic filename. Use domain-specific naming.'
+  }
+
+  const guidance = forbiddenWordSuggestions[forbiddenWord]
+  return `Generic word "${forbiddenWord}" in filename. ${guidance}`
+}
+
+const createClassMessage = (className) => {
+  const forbiddenWord = findForbiddenWord(className)
+
+  if (!forbiddenWord) {
+    return `Generic class name "${className}". Use domain-specific naming.`
+  }
+
+  const guidance = forbiddenWordSuggestions[forbiddenWord]
+  return `Generic word "${forbiddenWord}" in class "${className}". ${guidance}`
+}
+
+const noGenericNames = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Forbid generic names in filenames and class names.',
+      recommended: true,
+    },
+  },
+  create(context) {
+    const filename = path.basename(context.getFilename() || '')
+
+    return {
+      ClassDeclaration(node) {
+        if (!node.id) {
+          return
+        }
+
+        if (!isForbiddenName(node.id.name)) {
+          return
+        }
+
+        context.report({
+          node: node.id,
+          message: createClassMessage(node.id.name),
+        })
+      },
+      Program(node) {
+        if (!forbiddenFilenamePattern.test(filename)) {
+          return
+        }
+
+        context.report({
+          node,
+          message: createFilenameMessage(filename),
+        })
+      },
+    }
+  },
+}
+
+export default noGenericNames