@nt-ai-lab/opencode-skillz 0.3.14 → 0.4.1

package/dist/tools/infra/vitest-coverage/review.js

@@ -0,0 +1,298 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { childProcessCommandRunner, resolvePullRequestChangedFiles, } from "../source-control/changed-files.js";
+import { createVitestCoverageCommandSpec, } from "./command.js";
+export const VITEST_COVERAGE_TOOL_NAME = "nt_skillz_vitest_coverage";
+class CoverageUsageError extends Error {
+}
+class CoverageSummaryReadError extends Error {
+}
+function normalizeOptionalText(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmedValue = value.trim();
+    if (!trimmedValue) {
+        return undefined;
+    }
+    return trimmedValue;
+}
+function normalizeMode(value) {
+    const normalizedMode = normalizeOptionalText(value);
+    if (!normalizedMode) {
+        return "files";
+    }
+    if (normalizedMode === "pr-review") {
+        return "pr-review";
+    }
+    if (normalizedMode === "files") {
+        return "files";
+    }
+    throw new CoverageUsageError(`Expected coverage mode to be 'files' or 'pr-review'. Got ${normalizedMode}.`);
+}
+function isTypeScriptPath(filePath) {
+    return filePath.endsWith(".ts") || filePath.endsWith(".tsx");
+}
+function isExcludedTypeScriptPath(filePath) {
+    return (filePath.endsWith(".spec.ts")
+        || filePath.endsWith(".spec.tsx")
+        || filePath.endsWith(".test.ts")
+        || filePath.endsWith(".test.tsx")
+        || filePath.endsWith(".d.ts")
+        || filePath.endsWith(".config.ts")
+        || filePath.endsWith(".config.tsx")
+        || filePath.includes("/fixtures/")
+        || filePath.includes("/__fixtures__/"));
+}
+function isCoverableSourcePath(repositoryRoot, filePath) {
+    if (!isTypeScriptPath(filePath)) {
+        return false;
+    }
+    if (isExcludedTypeScriptPath(filePath)) {
+        return false;
+    }
+    const absoluteFilePath = path.resolve(repositoryRoot, filePath);
+    return fs.existsSync(absoluteFilePath) && fs.statSync(absoluteFilePath).isFile();
+}
+function normalizeFileList(filePaths) {
+    if (!filePaths) {
+        return [];
+    }
+    return [...new Set(filePaths.map((filePath) => filePath.trim()).filter(Boolean))];
+}
+function resolveCoverageTargets(request, repositoryRoot, commandRunner) {
+    const mode = normalizeMode(request.mode);
+    if (mode === "pr-review") {
+        return resolvePullRequestChangedFiles({
+            repositoryRoot,
+            pullRequest: request.pullRequest,
+            base: request.base,
+            head: request.head,
+        }, commandRunner).filter((filePath) => isCoverableSourcePath(repositoryRoot, filePath));
+    }
+    return normalizeFileList(request.files).filter((filePath) => isCoverableSourcePath(repositoryRoot, filePath));
+}
+function findPackageRootFromDirectory(repositoryRoot, directoryPath) {
+    if (fs.existsSync(path.join(directoryPath, "package.json"))) {
+        return directoryPath;
+    }
+    if (directoryPath === repositoryRoot) {
+        throw new CoverageUsageError(`Expected package.json ancestor for ${directoryPath}.`);
+    }
+    const parentDirectoryPath = path.dirname(directoryPath);
+    if (parentDirectoryPath === directoryPath) {
+        throw new CoverageUsageError(`Expected package.json ancestor for ${directoryPath}.`);
+    }
+    return findPackageRootFromDirectory(repositoryRoot, parentDirectoryPath);
+}
+function runCoverageCommand(commandSpec, environment) {
+    const commandResult = environment.commandRunner.run(commandSpec.executable, commandSpec.commandArguments, commandSpec.workingDirectory);
+    const output = [commandResult.stdout, commandResult.stderr].filter(Boolean).join("\n").trim();
+    return {
+        status: commandResult.status,
+        output,
+        errorMessage: commandResult.errorMessage,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readNumber(record, key) {
+    const value = record[key];
+    if (typeof value === "number") {
+        return value;
+    }
+    throw new CoverageSummaryReadError(`Expected numeric coverage field '${key}'.`);
+}
+function readMetric(record, key) {
+    const value = record[key];
+    if (!isRecord(value)) {
+        throw new CoverageSummaryReadError(`Expected coverage metric '${key}'.`);
+    }
+    return {
+        total: readNumber(value, "total"),
+        covered: readNumber(value, "covered"),
+        skipped: readNumber(value, "skipped"),
+        pct: readNumber(value, "pct"),
+    };
+}
+function readFileCoverageSummary(value) {
+    if (!isRecord(value)) {
+        throw new CoverageSummaryReadError("Expected file coverage summary object.");
+    }
+    return {
+        lines: readMetric(value, "lines"),
+        statements: readMetric(value, "statements"),
+        functions: readMetric(value, "functions"),
+        branches: readMetric(value, "branches"),
+    };
+}
+function normalizeCoverageKey(packageRoot, coverageKey) {
+    if (path.isAbsolute(coverageKey)) {
+        return path.resolve(coverageKey);
+    }
+    return path.resolve(packageRoot, coverageKey);
+}
+function readCoverageSummary(packageRoot, reportsDirectory, packageRelativeFilePath) {
+    const summaryPath = path.join(reportsDirectory, "coverage-summary.json");
+    if (!fs.existsSync(summaryPath)) {
+        throw new CoverageSummaryReadError(`Expected coverage summary at ${summaryPath}.`);
+    }
+    const parsedSummary = JSON.parse(fs.readFileSync(summaryPath, "utf8"));
+    if (!isRecord(parsedSummary)) {
+        throw new CoverageSummaryReadError("Expected coverage summary JSON object.");
+    }
+    const expectedFilePath = path.resolve(packageRoot, packageRelativeFilePath);
+    const matchingCoverageEntry = Object.entries(parsedSummary).find(([coverageKey]) => normalizeCoverageKey(packageRoot, coverageKey) === expectedFilePath);
+    if (!matchingCoverageEntry) {
+        throw new CoverageSummaryReadError(`Expected coverage summary row for ${packageRelativeFilePath}.`);
+    }
+    return readFileCoverageSummary(matchingCoverageEntry[1]);
+}
+function hasCompleteCoverage(summary) {
+    return summary.statements.pct === 100
+        && summary.branches.pct === 100
+        && summary.functions.pct === 100
+        && summary.lines.pct === 100;
+}
+function formatCoverageErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return `Expected coverage error message. Got ${String(error)}.`;
+}
+function executeCoverageWithReports(repositoryRoot, filePath, packageRoot, packageRelativeFilePath, environment) {
+    const reportsDirectory = environment.temporaryDirectoryCreator(path.join(os.tmpdir(), "nt-skillz-coverage-"));
+    try {
+        const commandSpec = createVitestCoverageCommandSpec({
+            repositoryRoot,
+            filePath,
+            packageRoot,
+            packageRelativeFilePath,
+            reportsDirectory,
+        });
+        const commandResult = runCoverageCommand(commandSpec, environment);
+        if (commandResult.errorMessage) {
+            return {
+                status: "errored",
+                filePath,
+                message: commandResult.errorMessage,
+                commandOutput: commandResult.output,
+            };
+        }
+        const summary = readCoverageSummary(commandSpec.coverageSummaryRoot, reportsDirectory, commandSpec.coverageSummaryFilePath);
+        if (commandResult.status === 0 && hasCompleteCoverage(summary)) {
+            return {
+                status: "passed",
+                filePath,
+                summary,
+            };
+        }
+        return {
+            status: "failed",
+            filePath,
+            summary,
+            commandOutput: commandResult.output,
+        };
+    }
+    catch (error) {
+        const message = formatCoverageErrorMessage(error);
+        return {
+            status: "errored",
+            filePath,
+            message,
+            commandOutput: "",
+        };
+    }
+    finally {
+        environment.temporaryDirectoryRemover(reportsDirectory);
+    }
+}
+function executeFileCoverage(repositoryRoot, filePath, environment) {
+    try {
+        const absoluteFilePath = path.resolve(repositoryRoot, filePath);
+        const packageRoot = findPackageRootFromDirectory(repositoryRoot, path.dirname(absoluteFilePath));
+        const packageRelativeFilePath = path.relative(packageRoot, absoluteFilePath);
+        return executeCoverageWithReports(repositoryRoot, filePath, packageRoot, packageRelativeFilePath, environment);
+    }
+    catch (error) {
+        const message = formatCoverageErrorMessage(error);
+        return {
+            status: "errored",
+            filePath,
+            message,
+            commandOutput: "",
+        };
+    }
+}
+function formatPercent(metric) {
+    return `${metric.pct}%`;
+}
+function formatCoverageRow(result) {
+    if (result.status === "errored") {
+        return `| \`${result.filePath}\` | error | error | error | error | ERROR |`;
+    }
+    const status = result.status === "passed" ? "PASS" : "FAIL";
+    return `| \`${result.filePath}\` | ${formatPercent(result.summary.statements)} | ${formatPercent(result.summary.branches)} | ${formatPercent(result.summary.functions)} | ${formatPercent(result.summary.lines)} | ${status} |`;
+}
+function formatCoverageDetails(result) {
+    if (result.status === "passed") {
+        return [];
+    }
+    const detailContent = result.status === "failed" ? result.commandOutput : [result.message, result.commandOutput].filter(Boolean).join("\n");
+    if (!detailContent) {
+        return [];
+    }
+    return [
+        `<details><summary>Coverage output for \`${result.filePath}\`</summary>`,
+        "",
+        "```text",
+        detailContent,
+        "```",
+        "",
+        "</details>",
+    ];
+}
+function formatCoverageMarkdown(results) {
+    if (results.length === 0) {
+        return [
+            "<!-- nt-skillz-coverage:start -->",
+            "## Coverage",
+            "",
+            "No changed TypeScript source files.",
+            "<!-- nt-skillz-coverage:end -->",
+        ].join("\n");
+    }
+    const tableRows = results.map(formatCoverageRow);
+    const detailRows = results.flatMap(formatCoverageDetails);
+    const lines = [
+        "<!-- nt-skillz-coverage:start -->",
+        "## Coverage",
+        "",
+        "| File | Statements | Branches | Functions | Lines | Status |",
+        "| --- | ---: | ---: | ---: | ---: | --- |",
+        ...tableRows,
+    ];
+    if (detailRows.length > 0) {
+        return [...lines, "", ...detailRows, "<!-- nt-skillz-coverage:end -->"].join("\n");
+    }
+    return [...lines, "<!-- nt-skillz-coverage:end -->"].join("\n");
+}
+export async function runVitestCoverageReview(request, environment = {
+    commandRunner: childProcessCommandRunner,
+    temporaryDirectoryCreator: fs.mkdtempSync,
+    temporaryDirectoryRemover: (directoryPath) => fs.rmSync(directoryPath, {
+        recursive: true,
+        force: true,
+    }),
+}) {
+    const repositoryRoot = path.resolve(request.repositoryRoot ?? process.cwd());
+    const coverageTargets = resolveCoverageTargets(request, repositoryRoot, environment.commandRunner);
+    const results = coverageTargets.map((filePath) => executeFileCoverage(repositoryRoot, filePath, environment));
+    return {
+        markdown: formatCoverageMarkdown(results),
+        results,
+    };
+}

package/dist/tools/infra/vitest-coverage/test-support.d.ts

@@ -0,0 +1,15 @@
+import type { CommandRunner } from "../source-control/changed-files.js";
+export interface CapturedCoverageRun {
+    executable: string;
+    commandArguments: string[];
+    workingDirectory: string;
+}
+export declare function createRepository(sourceFilePath: string): string;
+export declare function createRepositoryWithoutVitest(sourceFilePath: string): string;
+export declare function createRepositoryWithoutPackage(sourceFilePath: string): string;
+export declare function createCoverageCommandRunner(percent: number, capturedRuns: CapturedCoverageRun[], commandOutput?: string): CommandRunner;
+export declare function createPullRequestCoverageCommandRunner(changedFiles: string[], percent: number): CommandRunner;
+export declare function createCoverageSummaryCommandRunner(summaryJson: string): CommandRunner;
+export declare function createCoverageErrorCommandRunner(): CommandRunner;
+export declare function installFailingVitestBinary(repositoryRoot: string): void;
+export declare function removeDirectory(directoryPath: string): void;

package/dist/tools/infra/vitest-coverage/test-support.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function createRepository(sourceFilePath) {
+    const repositoryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nt-skillz-test-repo-"));
+    const sourceAbsolutePath = path.join(repositoryRoot, sourceFilePath);
+    const vitestBinaryPath = path.join(repositoryRoot, "node_modules", ".bin", "vitest");
+    fs.mkdirSync(path.dirname(sourceAbsolutePath), { recursive: true });
+    fs.mkdirSync(path.dirname(vitestBinaryPath), { recursive: true });
+    fs.writeFileSync(path.join(repositoryRoot, "package.json"), "{}");
+    fs.writeFileSync(sourceAbsolutePath, "export const answer = 42\n");
+    fs.writeFileSync(vitestBinaryPath, "");
+    return repositoryRoot;
+}
+export function createRepositoryWithoutVitest(sourceFilePath) {
+    const repositoryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nt-skillz-test-repo-"));
+    const sourceAbsolutePath = path.join(repositoryRoot, sourceFilePath);
+    fs.mkdirSync(path.dirname(sourceAbsolutePath), { recursive: true });
+    fs.writeFileSync(path.join(repositoryRoot, "package.json"), "{}");
+    fs.writeFileSync(sourceAbsolutePath, "export const answer = 42\n");
+    return repositoryRoot;
+}
+export function createRepositoryWithoutPackage(sourceFilePath) {
+    const repositoryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nt-skillz-test-repo-"));
+    const sourceAbsolutePath = path.join(repositoryRoot, sourceFilePath);
+    fs.mkdirSync(path.dirname(sourceAbsolutePath), { recursive: true });
+    fs.writeFileSync(sourceAbsolutePath, "export const answer = 42\n");
+    return repositoryRoot;
+}
+function createCoverageMetric(percent) {
+    return {
+        total: 1,
+        covered: percent === 100 ? 1 : 0,
+        skipped: 0,
+        pct: percent,
+    };
+}
+function writeCoverageSummary(reportsDirectory, filePath, percent) {
+    fs.mkdirSync(reportsDirectory, { recursive: true });
+    fs.writeFileSync(path.join(reportsDirectory, "coverage-summary.json"), JSON.stringify({
+        total: {
+            lines: createCoverageMetric(percent),
+            statements: createCoverageMetric(percent),
+            functions: createCoverageMetric(percent),
+            branches: createCoverageMetric(percent),
+        },
+        [filePath]: {
+            lines: createCoverageMetric(percent),
+            statements: createCoverageMetric(percent),
+            functions: createCoverageMetric(percent),
+            branches: createCoverageMetric(percent),
+        },
+    }));
+}
+export function createCoverageCommandRunner(percent, capturedRuns, commandOutput = "coverage output") {
+    return {
+        run(executable, commandArguments, workingDirectory) {
+            capturedRuns.push({
+                executable,
+                commandArguments,
+                workingDirectory,
+            });
+            const reportsDirectoryArgument = commandArguments.find((commandArgument) => commandArgument.startsWith("--coverage.reportsDirectory="));
+            if (reportsDirectoryArgument === undefined) {
+                return {
+                    status: 1,
+                    stdout: "",
+                    stderr: "missing reports directory",
+                };
+            }
+            const reportsDirectory = reportsDirectoryArgument.replace("--coverage.reportsDirectory=", "");
+            const coverageIncludeArgument = commandArguments.find((commandArgument) => commandArgument.startsWith("--coverage.include="));
+            if (coverageIncludeArgument === undefined) {
+                return {
+                    status: 1,
+                    stdout: "",
+                    stderr: "missing coverage include",
+                };
+            }
+            const coveredFilePath = coverageIncludeArgument.replace("--coverage.include=", "");
+            writeCoverageSummary(reportsDirectory, path.join(workingDirectory, coveredFilePath), percent);
+            return {
+                status: percent === 100 ? 0 : 1,
+                stdout: commandOutput,
+                stderr: "",
+            };
+        },
+    };
+}
+export function createPullRequestCoverageCommandRunner(changedFiles, percent) {
+    return {
+        run(executable, commandArguments, workingDirectory) {
+            if (executable === "gh") {
+                return {
+                    status: 0,
+                    stdout: changedFiles.join("\n"),
+                    stderr: "",
+                };
+            }
+            return createCoverageCommandRunner(percent, []).run(executable, commandArguments, workingDirectory);
+        },
+    };
+}
+export function createCoverageSummaryCommandRunner(summaryJson) {
+    return {
+        run(_executable, commandArguments) {
+            const reportsDirectoryArgument = commandArguments.find((commandArgument) => commandArgument.startsWith("--coverage.reportsDirectory="));
+            if (reportsDirectoryArgument !== undefined) {
+                const reportsDirectory = reportsDirectoryArgument.replace("--coverage.reportsDirectory=", "");
+                fs.mkdirSync(reportsDirectory, { recursive: true });
+                fs.writeFileSync(path.join(reportsDirectory, "coverage-summary.json"), summaryJson);
+            }
+            return {
+                status: 0,
+                stdout: "",
+                stderr: "",
+            };
+        },
+    };
+}
+export function createCoverageErrorCommandRunner() {
+    return {
+        run() {
+            return {
+                status: null,
+                stdout: "coverage stdout",
+                stderr: "coverage stderr",
+                errorMessage: "spawn failed",
+            };
+        },
+    };
+}
+export function installFailingVitestBinary(repositoryRoot) {
+    const vitestBinaryPath = path.join(repositoryRoot, "node_modules", ".bin", "vitest");
+    const scriptContent = [
+        "#!/usr/bin/env node",
+        "const fs = require('node:fs')",
+        "const path = require('node:path')",
+        "const filePath = path.join(process.cwd(), process.argv[3])",
+        "const reportsArgument = process.argv.find((argument) => argument.startsWith('--coverage.reportsDirectory='))",
+        "const reportsDirectory = reportsArgument.replace('--coverage.reportsDirectory=', '')",
+        "const metric = { total: 1, covered: 0, skipped: 0, pct: 50 }",
+        "fs.mkdirSync(reportsDirectory, { recursive: true })",
+        "fs.writeFileSync(path.join(reportsDirectory, 'coverage-summary.json'), JSON.stringify({ total: { lines: metric, statements: metric, functions: metric, branches: metric }, [filePath]: { lines: metric, statements: metric, functions: metric, branches: metric } }))",
+        "process.stdout.write('tool coverage output')",
+        "process.exit(1)",
+    ].join("\n");
+    fs.rmSync(vitestBinaryPath, { force: true });
+    fs.writeFileSync(vitestBinaryPath, scriptContent, { mode: 0o755 });
+}
+export function removeDirectory(directoryPath) {
+    fs.rmSync(directoryPath, {
+        recursive: true,
+        force: true,
+    });
+}

package/dist/tools/lint.d.ts

@@ -1,3 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
 interface PortableLintRequest {
     repositoryRoot?: string;
     files?: string[];
@@ -9,19 +10,8 @@ interface PortableLintOutcome {
     output: string;
 }
 export declare const LINT_TOOL_NAME = "nt_skillz_lint";
+export declare function prependLintFailureGuidance(formattedOutput: string, errorCount: number, lintFailureGuidance: string): string;
 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 declare const lintTool: ToolDefinition;
 export {};

package/dist/tools/lint.js

@@ -5,7 +5,10 @@ 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";
+import { tool, } from "@opencode-ai/plugin";
+import { createLintFailureGuidance } from "./infra/lint/guidance.js";
+import { childProcessCommandRunner } from "./infra/source-control/changed-files.js";
+import { runPrReviewLint } from "./infra/lint/review.js";
 class UsageError extends Error {
     constructor(message) {
         super(message);
@@ -31,6 +34,14 @@ const toolDirectory = path.dirname(fileURLToPath(import.meta.url));
 const toolRepositoryRoot = path.resolve(toolDirectory, "..", "..");
 const eslintConfigPath = path.join(toolRepositoryRoot, "scripts", "living-architecture-eslint.config.mjs");
 const gitBinaryPath = "/usr/bin/git";
+const helpText = [
+    "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");
 export const LINT_TOOL_NAME = "nt_skillz_lint";
 function normalizeOptionalText(value) {
     if (typeof value !== "string") {
@@ -42,6 +53,16 @@ function normalizeOptionalText(value) {
     }
     return trimmedValue;
 }
+function normalizeToolMode(value) {
+    const normalizedValue = normalizeOptionalText(value);
+    if (!normalizedValue) {
+        return "files";
+    }
+    if (normalizedValue === "files" || normalizedValue === "pr-review") {
+        return normalizedValue;
+    }
+    throw new UsageError(`Expected lint mode to be 'files' or 'pr-review'. Got ${normalizedValue}.`);
+}
 function resolveDirectory(directoryPath) {
     const absoluteDirectoryPath = path.resolve(directoryPath);
     if (!fs.existsSync(absoluteDirectoryPath)) {
@@ -77,8 +98,8 @@ function runGitCommand(repositoryRoot, gitArguments) {
     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}.`);
+    const failureOutput = gitResult.stderr.trim() || gitResult.stdout.trim() || `exit status ${gitResult.status}`;
+    throw new GitCommandError(`Expected git command to succeed. Got ${failureOutput}.`);
 }
 function readChangedTypeScriptFiles(repositoryRoot, baseReference, headReference) {
     const diffRange = `${baseReference}...${headReference}`;
@@ -134,6 +155,15 @@ function createLintTitle(filePaths, baseReference) {
 function removeAnsiEscapeSequences(value) {
     return value.replaceAll(ansiEscapeSequencePattern, "");
 }
+export function prependLintFailureGuidance(formattedOutput, errorCount, lintFailureGuidance) {
+    if (errorCount === 0) {
+        return formattedOutput;
+    }
+    if (!formattedOutput) {
+        return lintFailureGuidance;
+    }
+    return [lintFailureGuidance, "", formattedOutput].join("\n");
+}
 async function runEslint(repositoryRoot, lintTargets) {
     const previousLintRepositoryRoot = process.env.NT_SKILLZ_LINT_REPO_ROOT;
     process.env.NT_SKILLZ_LINT_REPO_ROOT = repositoryRoot;
@@ -150,7 +180,7 @@ async function runEslint(repositoryRoot, lintTargets) {
         const errorCount = lintResults.reduce((count, lintResult) => count + lintResult.errorCount + lintResult.fatalErrorCount, 0);
         return {
             exitCode: errorCount > 0 ? 1 : 0,
-            output: formattedOutput,
+            output: prependLintFailureGuidance(formattedOutput, errorCount, createLintFailureGuidance(lintResults)),
         };
     }
     finally {
@@ -176,17 +206,6 @@ function parsePortableLintCommandLine(commandLineArguments) {
         },
         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),
@@ -211,6 +230,10 @@ export async function runPortableLint(request) {
     return runEslint(repositoryRoot, lintTargets);
 }
 export async function runPortableLintFromCommandLine(commandLineArguments) {
+    if (commandLineArguments.includes("--help") || commandLineArguments.includes("-h")) {
+        process.stdout.write(`${helpText}\n`);
+        return 0;
+    }
     const request = parsePortableLintCommandLine(commandLineArguments);
     const outcome = await runPortableLint(request);
     if (outcome.output) {
@@ -221,11 +244,28 @@ export async function runPortableLintFromCommandLine(commandLineArguments) {
 export const lintTool = tool({
     description: "Run bundled TypeScript lint rules against current project files.",
     args: {
+        mode: tool.schema.string().optional().describe("Use 'pr-review' to lint changed pull request TypeScript files."),
+        pullRequest: tool.schema.string().optional().describe("Pull request number or URL for pr-review mode."),
         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 mode = normalizeToolMode(request.mode);
+        if (mode === "pr-review") {
+            context.metadata({ title: "Lint pull request TypeScript changes" });
+            return {
+                output: await runPrReviewLint({
+                    repositoryRoot: context.worktree,
+                    pullRequest: normalizeOptionalText(request.pullRequest),
+                    base: normalizeOptionalText(request.base),
+                    head: normalizeOptionalText(request.head),
+                }, {
+                    commandRunner: childProcessCommandRunner,
+                    lintRunner: runPortableLint,
+                }),
+            };
+        }
         const filePaths = normalizeFilePaths(request.files);
         const baseReference = normalizeOptionalText(request.base);
         const headReference = normalizeOptionalText(request.head);
@@ -238,7 +278,7 @@ export const lintTool = tool({
             head: headReference,
         });
         if (outcome.exitCode !== 0) {
-            throw new LintExecutionError(outcome.output || "Lint failed.");
+            throw new LintExecutionError(outcome.output);
         }
         return {
             output: outcome.output || "Lint passed.",

package/dist/tools/pull-request-feedback-tool.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import { PULL_REQUEST_FEEDBACK_TOOL_NAME, type PullRequestFeedbackDependencies } from "./infra/pull-request/feedback.js";
+export declare function createPullRequestFeedbackTool(dependencies?: PullRequestFeedbackDependencies): ToolDefinition;
+export declare const pullRequestFeedbackTool: ToolDefinition;
+export { PULL_REQUEST_FEEDBACK_TOOL_NAME };

package/dist/tools/pull-request-feedback-tool.js

@@ -0,0 +1,23 @@
+import { tool, } from "@opencode-ai/plugin";
+import { PULL_REQUEST_FEEDBACK_TOOL_NAME, readPullRequestFeedback, } from "./infra/pull-request/feedback.js";
+export function createPullRequestFeedbackTool(dependencies = {}) {
+    return tool({
+        description: "Fetch unresolved GitHub pull request review feedback with diff hunks and local code excerpts.",
+        args: {
+            pullRequestNumber: tool.schema.string().describe("Pull request number from GitHub."),
+            pullRequestUrl: tool.schema.string().describe("Full GitHub pull request URL."),
+        },
+        async execute(request, context) {
+            context.metadata({ title: "Fetch unresolved PR feedback" });
+            return {
+                output: readPullRequestFeedback({
+                    repositoryRoot: context.worktree,
+                    pullRequestNumber: request.pullRequestNumber,
+                    pullRequestUrl: request.pullRequestUrl,
+                }, dependencies),
+            };
+        },
+    });
+}
+export const pullRequestFeedbackTool = createPullRequestFeedbackTool();
+export { PULL_REQUEST_FEEDBACK_TOOL_NAME };

package/dist/tools/vitest-coverage-tool.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import { VITEST_COVERAGE_TOOL_NAME } from "./infra/vitest-coverage/review.js";
+export declare const vitestCoverageTool: ToolDefinition;
+export { VITEST_COVERAGE_TOOL_NAME };