jti-ai-review 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andriy Zahura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# jti-ai-review
+
+npm package — local AI pre-commit review for **consumer repos**.
+
+This repository is the **CLI source**. It does not run the review pipeline on its own commits.
+
+Consumers install the package and run `npx ai-review init` to scaffold hooks, docs, and skills in their project.
+
+---
+
+## Package development
+
+```bash
+npm install
+npm run build:cli
+npm run pack:local          # test tarball without publishing
+```
+
+Pre-commit hook here only runs `build:cli` (compile check).
+
+To dogfood the full review flow locally:
+
+```bash
+node dist-cli/cli.js init --skip-prompt
+node dist-cli/cli.js run    # after git add
+```
+
+---
+
+## Consumer install (npm)
+
+```bash
+npm install -D jti-ai-review
+npx ai-review init
+npm install
+```
+
+Init scaffolds in the **consumer project**:
+
+- `.husky/pre-commit` → runs `ai-review` on commit
+- `.env` / `.env.example`
+- `review-mapping.json`, `docs/project-rules/`, `docs/ai-review/`
+- `.cursor/skills/jti-review/`
+
+### Workflow (consumer repo)
+
+```text
+1. /jti-review     → sync mapping + feature docs
+2. git add .
+3. git commit      → review → [P] commit / [R] report / [C] cancel
+```
+
+---
+
+## Providers
+
+| Provider | Env key |
+|----------|---------|
+| cursor | `CURSOR_API_KEY` |
+| openai | `OPENAI_API_KEY` |
+| codex | `OPENAI_API_KEY` |
+| claude | `ANTHROPIC_API_KEY` |
+| gemini | `GOOGLE_API_KEY` |
+
+Set `AI_REVIEW_PROVIDER` in `.env`. Falls back to `mock` without a key.
+
+For reliable reviews, prefer **anthropic** or **openai** direct API keys over cursor Cloud Agents.
+
+---
+
+## What ships on npm
+
+Only `dist-cli/`, `README.md`, and `LICENSE` — no consumer scaffold, no review reports.
+
+---
+
+## Commands
+
+```bash
+npm run build:cli
+npm run pack:local
+npm publish
+```
+
+CLI:
+
+```bash
+ai-review init [--force] [--skip-prompt]
+ai-review run [--provider <name>]
+```
+
+---
+
+## Design
+
+See [spec.md](spec.md) for full pipeline design.

package/dist-cli/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { ReadStream } from "node:tty";
+import { Command } from "commander";
+import { buildContext } from "./context/buildContext.js";
+import { checkDocCoverage, formatDocCoverageAlerts, } from "./context/docCoverage.js";
+import { loadMapping } from "./context/docMapper.js";
+import { loadEnv, resolveDefaultProvider } from "./config/loadEnv.js";
+import { normalizeProviderName } from "./config/providerConfig.js";
+import { runInit, printInitResult } from "./init/scaffold.js";
+import { runIsolatedReview } from "./review/spawnReview.js";
+import { saveReport } from "./report/saveReport.js";
+import { listProviders } from "./review/reviewer.js";
+function getRootDir() {
+    return process.cwd();
+}
+function printSummary(result, reportPath) {
+    console.log("\n--- AI Pre-Commit Review ---\n");
+    console.log(`Overall score: ${result.overallScore}/10`);
+    console.log(`Issues: ${result.issues.length}`);
+    console.log(`Report: ${reportPath}\n`);
+    for (const issue of result.issues) {
+        const location = issue.file ? ` (${issue.file})` : "";
+        console.log(`  [${issue.severity}]${location} ${issue.message}`);
+    }
+    console.log("");
+}
+function openFile(filePath) {
+    const platform = process.platform;
+    const command = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+    const args = platform === "win32" ? ["", filePath] : [filePath];
+    spawn(command, args, { detached: true, stdio: "ignore" }).unref();
+}
+function createPromptInterface() {
+    if (input.isTTY) {
+        return createInterface({ input, output, terminal: true });
+    }
+    if (process.platform === "win32") {
+        throw new Error("Interactive prompt requires a TTY. Run: npm run ai-review");
+    }
+    const ttyFd = openSync("/dev/tty", "r");
+    const ttyInput = new ReadStream(ttyFd);
+    return createInterface({
+        input: ttyInput,
+        output,
+        terminal: true,
+    });
+}
+async function promptAction(reportPath) {
+    const rl = createPromptInterface();
+    try {
+        while (true) {
+            const answer = (await rl.question("[P] Commit anyway  [R] Open review  [C] Cancel commit\n> "))
+                .trim()
+                .toLowerCase();
+            if (!answer) {
+                console.log("Choose P, R, or C.");
+                continue;
+            }
+            if (answer === "p" || answer === "commit") {
+                return "commit";
+            }
+            if (answer === "c" || answer === "cancel") {
+                return "cancel";
+            }
+            if (answer === "r" || answer === "open") {
+                openFile(reportPath);
+                console.log(`Opened ${reportPath}`);
+                continue;
+            }
+            console.log("Choose P, R, or C.");
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runReview(provider) {
+    const rootDir = getRootDir();
+    console.log("Building review context (staged changes)...");
+    const context = await buildContext(rootDir);
+    if (context.changedFiles.length === 0) {
+        console.log("No staged changes to review.");
+        process.exit(0);
+    }
+    const mapping = await loadMapping(rootDir);
+    const docIssues = await checkDocCoverage(rootDir, context.changedFiles, mapping);
+    const docAlerts = formatDocCoverageAlerts(docIssues);
+    if (docAlerts) {
+        console.log(docAlerts);
+    }
+    console.log(`Staged: ${context.changedFiles.length} file(s). Starting isolated ${provider} review...`);
+    const result = await runIsolatedReview(provider, context);
+    const reportPath = await saveReport(rootDir, result, context);
+    printSummary(result, reportPath);
+    const action = await promptAction(reportPath);
+    process.exit(action === "commit" ? 0 : 1);
+}
+const program = new Command();
+program
+    .name("ai-review")
+    .description("Local AI pre-commit review pipeline")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Scaffold review config, agent docs, and pre-commit hook")
+    .option("--force", "overwrite existing scaffold files")
+    .option("--skip-prompt", "skip interactive API key prompt")
+    .action(async (options) => {
+    try {
+        await loadEnv(getRootDir());
+        const result = await runInit(getRootDir(), Boolean(options.force), {
+            skipPrompt: Boolean(options.skipPrompt),
+        });
+        printInitResult(result);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program
+    .command("run")
+    .description("Review staged changes before commit")
+    .option("--provider <name>", "review provider (default: .env or mock)")
+    .action(async (options) => {
+    try {
+        await loadEnv(getRootDir());
+        const provider = normalizeProviderName(options.provider ?? resolveDefaultProvider());
+        if (!listProviders().includes(provider)) {
+            throw new Error(`Unknown provider "${provider}". Available: ${listProviders().join(", ")}`);
+        }
+        await runReview(provider);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist-cli/config/loadEnv.js

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectConfiguredProvider, getProviderDefinition, normalizeProviderName, providerHasCredentials, } from "./providerConfig.js";
+const ENV_FILES = [".env", ".env.local"];
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+        return null;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+        return null;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return { key, value };
+}
+export async function loadEnv(rootDir) {
+    for (const file of ENV_FILES) {
+        const path = join(rootDir, file);
+        try {
+            const raw = await readFile(path, "utf8");
+            for (const line of raw.split("\n")) {
+                const parsed = parseEnvLine(line);
+                if (parsed && process.env[parsed.key] === undefined) {
+                    process.env[parsed.key] = parsed.value;
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+}
+export function resolveDefaultProvider() {
+    const configured = process.env.AI_REVIEW_PROVIDER?.trim();
+    if (configured) {
+        const normalized = normalizeProviderName(configured);
+        if (normalized === "mock") {
+            return "mock";
+        }
+        if (providerHasCredentials(normalized)) {
+            return normalized;
+        }
+        return "mock";
+    }
+    return detectConfiguredProvider() ?? "mock";
+}
+export function missingKeyMessage(provider) {
+    const def = getProviderDefinition(provider);
+    if (!def) {
+        return `Provider "${provider}" is not configured.`;
+    }
+    return `${def.keyPrompt} is missing for provider "${provider}". Add it to .env or run: npm run ai-review:init`;
+}

package/dist-cli/config/providerConfig.js

@@ -0,0 +1,171 @@
+export const MODEL_ID_RULE = `Use the API model ID (lowercase, hyphens — not the UI display name).
+Examples: claude-fable-5, composer-2.5, gpt-4o-mini`;
+export const PROVIDER_DEFINITIONS = [
+    {
+        name: "cursor",
+        aliases: [],
+        label: "Cursor",
+        envKeys: ["CURSOR_API_KEY"],
+        modelEnvVars: ["CURSOR_MODEL", "AI_REVIEW_MODEL"],
+        defaultModel: "auto",
+        models: [
+            { id: "auto", label: "Auto (account default)" },
+            { id: "composer-2.5", label: "Composer 2.5" },
+            { id: "claude-fable-5", label: "Claude Fable 5" },
+            { id: "claude-opus-4-8", label: "Claude Opus 4.8" },
+            { id: "claude-sonnet-5", label: "Claude Sonnet 5" },
+        ],
+        keyPrompt: "CURSOR_API_KEY",
+        modelIdHint: "Copy from Cursor Settings → Models, or run: curl -u $CURSOR_API_KEY: https://api.cursor.com/v1/models",
+    },
+    {
+        name: "openai",
+        aliases: [],
+        label: "OpenAI",
+        envKeys: ["OPENAI_API_KEY"],
+        modelEnvVars: ["OPENAI_MODEL", "AI_REVIEW_MODEL"],
+        defaultModel: "gpt-4o-mini",
+        models: [
+            { id: "gpt-4o-mini", label: "GPT-4o mini" },
+            { id: "gpt-4o", label: "GPT-4o" },
+            { id: "gpt-4.1", label: "GPT-4.1" },
+            { id: "o4-mini", label: "o4-mini" },
+        ],
+        keyPrompt: "OPENAI_API_KEY",
+        modelIdHint: "See platform.openai.com/docs/models",
+    },
+    {
+        name: "codex",
+        aliases: [],
+        label: "OpenAI Codex",
+        envKeys: ["OPENAI_API_KEY", "CODEX_API_KEY"],
+        modelEnvVars: ["CODEX_MODEL", "OPENAI_MODEL", "AI_REVIEW_MODEL"],
+        defaultModel: "gpt-4.1",
+        models: [
+            { id: "gpt-4.1", label: "GPT-4.1 (Codex)" },
+            { id: "o4-mini", label: "o4-mini" },
+            { id: "gpt-4o", label: "GPT-4o" },
+        ],
+        keyPrompt: "OPENAI_API_KEY",
+        modelIdHint: "Same IDs as OpenAI API",
+    },
+    {
+        name: "anthropic",
+        aliases: ["claude"],
+        label: "Anthropic Claude",
+        envKeys: ["ANTHROPIC_API_KEY"],
+        modelEnvVars: ["ANTHROPIC_MODEL", "AI_REVIEW_MODEL"],
+        defaultModel: "claude-sonnet-4-20250514",
+        models: [
+            { id: "claude-fable-5", label: "Claude Fable 5" },
+            { id: "claude-opus-4-8", label: "Claude Opus 4.8" },
+            { id: "claude-sonnet-4-20250514", label: "Claude Sonnet 4" },
+            { id: "claude-3-5-haiku-20241022", label: "Claude 3.5 Haiku" },
+        ],
+        keyPrompt: "ANTHROPIC_API_KEY",
+        modelIdHint: "See docs.anthropic.com — e.g. claude-fable-5 (not 'Fable 5')",
+    },
+    {
+        name: "gemini",
+        aliases: ["google"],
+        label: "Google Gemini",
+        envKeys: ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+        modelEnvVars: ["GEMINI_MODEL", "GOOGLE_MODEL", "AI_REVIEW_MODEL"],
+        defaultModel: "gemini-2.0-flash",
+        models: [
+            { id: "gemini-2.0-flash", label: "Gemini 2.0 Flash" },
+            { id: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
+            { id: "gemini-1.5-pro", label: "Gemini 1.5 Pro" },
+        ],
+        keyPrompt: "GOOGLE_API_KEY",
+        modelIdHint: "See ai.google.dev/gemini-api/docs/models",
+    },
+];
+const ALIAS_MAP = new Map();
+for (const def of PROVIDER_DEFINITIONS) {
+    ALIAS_MAP.set(def.name, def.name);
+    for (const alias of def.aliases) {
+        ALIAS_MAP.set(alias, def.name);
+    }
+}
+export function normalizeProviderName(name) {
+    return ALIAS_MAP.get(name.trim().toLowerCase()) ?? name.trim().toLowerCase();
+}
+export function getProviderDefinition(name) {
+    const normalized = normalizeProviderName(name);
+    return PROVIDER_DEFINITIONS.find((def) => def.name === normalized);
+}
+export function isKnownProvider(name) {
+    return getProviderDefinition(name) !== undefined;
+}
+export function normalizeModelId(input, provider) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return getProviderDefinition(provider)?.defaultModel ?? trimmed;
+    }
+    const lower = trimmed.toLowerCase();
+    const displayNameAliases = {
+        "fable 5": "claude-fable-5",
+        "claude fable 5": "claude-fable-5",
+        fable5: "claude-fable-5",
+        "fable-5": "claude-fable-5",
+        "composer 2.5": "composer-2.5",
+        "composer2.5": "composer-2.5",
+    };
+    if (displayNameAliases[lower]) {
+        return displayNameAliases[lower];
+    }
+    if (/\s/.test(trimmed)) {
+        return lower.replace(/\s+/g, "-");
+    }
+    return lower;
+}
+export function providerHasCredentials(name) {
+    const def = getProviderDefinition(name);
+    if (!def) {
+        return false;
+    }
+    return def.envKeys.some((key) => Boolean(process.env[key]?.trim()));
+}
+export function resolveModel(name) {
+    const def = getProviderDefinition(name);
+    if (!def) {
+        return process.env.AI_REVIEW_MODEL?.trim() || "gpt-4o-mini";
+    }
+    for (const envVar of def.modelEnvVars) {
+        const value = process.env[envVar]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return def.defaultModel;
+}
+export function resolveApiKey(name) {
+    const def = getProviderDefinition(name);
+    if (!def) {
+        return undefined;
+    }
+    for (const key of def.envKeys) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function detectConfiguredProvider() {
+    const priority = ["cursor", "openai", "codex", "anthropic", "gemini"];
+    for (const name of priority) {
+        if (providerHasCredentials(name)) {
+            return name;
+        }
+    }
+    return null;
+}
+export function listConfiguredProviders() {
+    return PROVIDER_DEFINITIONS.filter((def) => providerHasCredentials(def.name)).map((def) => def.name);
+}
+export function primaryModelEnvVar(name) {
+    const def = getProviderDefinition(name);
+    return def?.modelEnvVars[0] ?? "AI_REVIEW_MODEL";
+}

package/dist-cli/context/buildContext.js

@@ -0,0 +1,70 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { simpleGit } from "simple-git";
+import { loadMapping, resolveDocDirs } from "./docMapper.js";
+import { findLatestReview } from "../report/findLatestReview.js";
+async function readDirMarkdown(dirPath) {
+    const result = {};
+    let entries;
+    try {
+        entries = await readdir(dirPath);
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry);
+        const info = await stat(fullPath);
+        if (info.isDirectory()) {
+            const nested = await readDirMarkdown(fullPath);
+            for (const [nestedPath, content] of Object.entries(nested)) {
+                result[nestedPath] = content;
+            }
+            continue;
+        }
+        if (info.isFile() && (entry.endsWith(".md") || entry.endsWith(".json"))) {
+            result[fullPath] = await readFile(fullPath, "utf8");
+        }
+    }
+    return result;
+}
+async function getStagedChanges(rootDir) {
+    const git = simpleGit(rootDir);
+    const diff = await git.diff(["--cached"]);
+    const summary = await git.diffSummary(["--cached"]);
+    const changedFiles = summary.files.map((file) => file.file);
+    return { changedFiles, diff };
+}
+export async function buildContext(rootDir) {
+    const mapping = await loadMapping(rootDir);
+    const { changedFiles, diff } = await getStagedChanges(rootDir);
+    const docDirs = resolveDocDirs(changedFiles, mapping);
+    const projectRules = {};
+    const featureDocs = {};
+    for (const dir of docDirs) {
+        const absDir = join(rootDir, dir);
+        const files = await readDirMarkdown(absDir);
+        const bucket = dir.includes("project-rules") ? projectRules : featureDocs;
+        for (const [filePath, content] of Object.entries(files)) {
+            bucket[filePath] = content;
+        }
+    }
+    let metadata = {};
+    try {
+        const pkgRaw = await readFile(join(rootDir, "package.json"), "utf8");
+        metadata = JSON.parse(pkgRaw);
+    }
+    catch {
+        metadata = {};
+    }
+    const previousReview = await findLatestReview(join(rootDir, "docs/reviews"));
+    return {
+        generatedAt: new Date().toISOString(),
+        changedFiles,
+        diff: diff || "(no staged diff)",
+        projectRules,
+        featureDocs,
+        metadata,
+        previousReview,
+    };
+}

package/dist-cli/context/docCoverage.js

@@ -0,0 +1,93 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { constants } from "node:fs";
+import { globMatch } from "../utils/glob.js";
+const SKIP_UNMAPPED_CHECK = [
+    /^docs\/reviews\//,
+    /^docs\/ai-review\//,
+    /^docs\/project-rules\//,
+    /^\.husky\//,
+    /^cli\//,
+    /^dist-cli\//,
+    /^node_modules\//,
+    /^dist\//,
+    /^package-lock\.json$/,
+    /^review-mapping\.json$/,
+];
+function isInfrastructurePath(file) {
+    return SKIP_UNMAPPED_CHECK.some((pattern) => pattern.test(file));
+}
+function findDocsDir(file, mapping) {
+    for (const entry of mapping.mappings) {
+        if (globMatch(file, entry.pattern)) {
+            return entry.docs;
+        }
+    }
+    return null;
+}
+async function fileExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isUnderDocs(dir, stagedFile) {
+    const prefix = dir.endsWith("/") ? dir : `${dir}/`;
+    return stagedFile === dir || stagedFile.startsWith(prefix);
+}
+export async function checkDocCoverage(rootDir, stagedFiles, mapping) {
+    const issues = [];
+    const stagedSet = new Set(stagedFiles);
+    for (const file of stagedFiles) {
+        if (isInfrastructurePath(file)) {
+            continue;
+        }
+        const docsDir = findDocsDir(file, mapping);
+        if (!docsDir) {
+            if (!file.startsWith("docs/")) {
+                issues.push({
+                    type: "unmapped",
+                    file,
+                    message: `No mapping in review-mapping.json for ${file}`,
+                });
+            }
+            continue;
+        }
+        const readmePath = join(rootDir, docsDir, "README.md");
+        const hasReadme = await fileExists(readmePath);
+        if (!hasReadme) {
+            issues.push({
+                type: "missing_readme",
+                file,
+                docsDir,
+                message: `${docsDir}/README.md missing — create feature doc`,
+            });
+            continue;
+        }
+        const readmeStaged = [...stagedSet].some((staged) => isUnderDocs(docsDir, staged));
+        const isCodeFile = !file.startsWith("docs/");
+        if (isCodeFile && !readmeStaged) {
+            issues.push({
+                type: "docs_not_staged",
+                file,
+                docsDir,
+                message: `${file} staged but ${docsDir}/ not updated in this commit`,
+            });
+        }
+    }
+    return issues;
+}
+export function formatDocCoverageAlerts(issues) {
+    if (issues.length === 0) {
+        return "";
+    }
+    const lines = ["--- Doc coverage alerts ---\n"];
+    for (const issue of issues) {
+        lines.push(`  [${issue.type}] ${issue.message}`);
+    }
+    lines.push("\nFix docs/mapping or run /jti-review before committing.\n");
+    return lines.join("\n");
+}

package/dist-cli/context/docMapper.js

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { globMatch } from "../utils/glob.js";
+export async function loadMapping(rootDir) {
+    const raw = await readFile(join(rootDir, "review-mapping.json"), "utf8");
+    return JSON.parse(raw);
+}
+export function resolveDocDirs(changedFiles, mapping) {
+    const dirs = new Set(mapping.alwaysInclude);
+    for (const file of changedFiles) {
+        for (const entry of mapping.mappings) {
+            if (globMatch(file, entry.pattern)) {
+                dirs.add(entry.docs);
+            }
+        }
+    }
+    return [...dirs];
+}