ai-cmds 0.1.1 → 0.2.0

package/README.md

@@ -5,14 +5,16 @@ AI-powered CLI tool that uses OpenAI and Google Gemini models to review code cha
 ## Features
 
 - Multiple AI models: GPT-5, GPT-5-mini, GPT-4o-mini, Gemini 2.5 Pro, Gemini 2.0 Flash
-- Configurable review setups from very light to heavy
-- Custom setups with full control over reviewer, validator, and formatter models
-- Three commands: `review-code-changes` for local development, `review-pr` for CI, `create-pr` for PR creation
-- Parallel reviews with validation pass for higher accuracy
+- Configurable review setups from light to heavy
+- Custom setups with full control over reviewer and validator models
+- Four commands: `review-code-changes` for local development, `advanced-review-changes` for guided/customized local review focus, `review-pr` for CI, `create-pr` for PR creation
+- Parallel reviews with a single structured validation pass for higher accuracy
+- Optional provider-aware concurrency limits for reviewer fan-out
 - AI-generated PR titles and descriptions
 - Automatic filtering of import-only changes
 - Custom review instructions support
 - Token usage tracking and cost awareness
+- Improved review visualization with severity totals, issue IDs (`C1`, `P1`, `S1`), and impacted file counts
 
 ## Installation
 
@@ -47,12 +49,45 @@ ai-cmds review-code-changes --setup light
 
 # Specify base branch
 ai-cmds review-code-changes --scope all --base-branch develop
+
+# Save review to a custom file path
+ai-cmds review-code-changes --scope all --output reviews/local-review.md
 ```
 
 **Arguments:**
 - `--scope` - Review scope: `all`, `staged`, `globs`, `unViewed`, or custom scope id
 - `--setup` - Review setup: `light`, `medium`, `heavy`, or custom setup id
 - `--base-branch` - Base branch for diff comparison (if not specified, prompts for selection)
+- `--output` - Output file path for the generated review markdown (default: `pr-review.md`)
+
+### `advanced-review-changes` - Advanced Local Development
+
+Review local code changes with the same flow as `review-code-changes`, plus extra control over review guidance.
+
+```bash
+# Guided mode (prompts for custom instruction and instruction inclusion)
+ai-cmds advanced-review-changes
+
+# Pass a custom review focus instruction
+ai-cmds advanced-review-changes --custom-review-instruction "Focus on authentication and authorization issues"
+
+# Disable default/configured instructions and only use your custom instruction
+ai-cmds advanced-review-changes \
+  --custom-review-instruction "Focus on performance bottlenecks and N+1 queries" \
+  --include-default-review-instructions false
+```
+
+**Arguments:**
+- `--scope` - Review scope: `all`, `staged`, `globs`, `unViewed`, or custom scope id
+- `--setup` - Review setup: `light`, `medium`, `heavy`, or custom setup id
+- `--base-branch` - Base branch for diff comparison (if not specified, prompts for selection)
+- `--output` - Output file path for the generated review markdown (default: `pr-review.md`)
+- `--custom-review-instruction` - Extra custom instruction that tells reviewers what to focus on
+- `--include-default-review-instructions` - Whether to include configured/default instructions (`true` or `false`)
+
+**Interactive behavior:**
+- If `--include-default-review-instructions` is not provided, the CLI shows a confirm dialog.
+- If `--custom-review-instruction` is not provided, the CLI asks whether you want to add one and prompts for it if confirmed.
 
 ### `review-pr` - CI/PR Review
 
@@ -71,13 +106,15 @@ ai-cmds review-pr --pr 123 --setup heavy
 
 **Arguments:**
 - `--pr` - PR number to review (**required**)
-- `--setup` - Review setup: `light`, `medium`, `heavy`, or custom setup label
+- `--setup` - Review setup: `light`, `medium`, `heavy`, or custom setup id
 - `--test` - Test mode: skip posting review to PR, just save to file
 - `--skip-previous-check` - Skip checking if previous review issues are still present
 
 **Behavior:**
 - In GitHub Actions (`GITHUB_ACTIONS` env set): Posts review as PR comment
 - With `--test` flag or locally: Saves review to `pr-review-test.md`
+- If the filtered diff has no reviewable code (for example import/export-only changes), the command skips AI calls and emits a no-issues review
+- Reviewer fan-out respects `codeReview.concurrencyPerProvider` when configured
 
 **Previous Review Check:**
 
@@ -127,12 +164,9 @@ ai-cmds create-pr --title "Fix login validation"
 
 | Setup | Reviewers | Description |
 |-------|-----------|-------------|
-| `veryLight` | 1× GPT-5-mini | Fastest, lowest cost |
 | `light` | 1× GPT-5 | Balanced |
 | `medium` | 2× GPT-5 (high reasoning) | More thorough |
 | `heavy` | 4× GPT-5 (high reasoning) | Most comprehensive |
-| `lightGoogle` | 1× Gemini 2.5 Pro | Google alternative |
-| `mediumGoogle` | 2× Gemini 2.5 Pro | Google thorough |
 
 ## Review Scopes
 
@@ -169,7 +203,7 @@ This requires an open PR for the current branch. It uses the GitHub GraphQL API
 
 ## Configuration
 
-Create `ai-cli.config.ts` in your project root:
+Create `ai-cmds.config.ts` in your project root:
 
 ```typescript
 import { defineConfig } from 'ai-cmds';
@@ -179,6 +213,11 @@ export default defineConfig({
     baseBranch: 'main',
     codeReviewDiffExcludePatterns: ['pnpm-lock.yaml', '**/*.svg', '**/*.test.ts'],
     reviewInstructionsPath: '.github/PR_REVIEW_AGENT.md',
+    includeAgentsFileInReviewPrompt: true,
+    concurrencyPerProvider: {
+      'openai.responses': 2,
+      'google.generative-ai': 1,
+    },
   },
   createPR: {
     baseBranch: 'main',
@@ -224,11 +263,13 @@ By default, `.env` is loaded automatically before the config file is imported, a
 | `baseBranch` | Base branch for diff comparison. Can be a string or function `(currentBranch) => string`. If not set, prompts for selection |
 | `codeReviewDiffExcludePatterns` | Glob patterns for files to exclude from review |
 | `reviewInstructionsPath` | Path to custom review instructions markdown file |
+| `includeAgentsFileInReviewPrompt` | Include `<git-root>/AGENTS.md` content in reviewer prompts (default: `true`) |
+| `reviewOutputPath` | Default output file path for `review-code-changes` (can be overridden by `--output`) |
 | `setup` | Array of custom named setups (see below) |
 | `scope` | Array of custom named scopes (see below) |
 | `defaultValidator` | Default validator model for custom setups |
-| `defaultFormatter` | Default formatter model for custom setups |
-| `logsDir` | Directory for logs (can also use `AI_CLI_LOGS_DIR` env var) |
+| `concurrencyPerProvider` | Reviewer concurrency limit. Use a number for all providers or `{ [providerId]: number }` for per-provider limits (keys come from `model.provider`, e.g. `openai.responses`; unspecified providers default to unlimited) |
+| `logsDir` | Directory for review run artifacts (can also use `AI_CLI_LOGS_DIR` env var) |
 
 #### `createPR` Options
 
@@ -241,6 +282,14 @@ By default, `.env` is loaded automatically before the config file is imported, a
 | `diffExcludePatterns` | Glob patterns for files to exclude from diff |
 | `maxDiffTokens` | Maximum tokens from diff to include in AI prompt (default: 50000) |
 
+When `codeReview.logsDir` (or `AI_CLI_LOGS_DIR`) is set, each review run stores artifacts under:
+
+- `<logsDir>/advanced-review-changes/<run-id>/...` for advanced local reviews
+- `<logsDir>/review-code-changes/<run-id>/...` for local reviews
+- `<logsDir>/review-pr/<run-id>/...` for PR reviews
+
+Each run includes `context.yaml`, `changed-files.txt`, `diff.diff`, `reviewers/*.md`, `reviewers/*-debug.yaml`, `validator.yaml`, `final-review.md`, and `summary.yaml`.
+
 ### Dynamic Base Branch
 
 The `baseBranch` option can be a function that receives the current branch name:
@@ -256,7 +305,7 @@ export default defineConfig({
 
 ### Custom Setups
 
-Define custom named setups with full control over which models are used. **When custom setups are configured, they replace built-in options** (veryLight, light, medium, heavy).
+Define custom named setups with full control over which models are used. **When custom setups are configured, they replace built-in options** (light, medium, heavy).
 
 ```typescript
 import { defineConfig } from 'ai-cmds';
@@ -267,24 +316,24 @@ export default defineConfig({
   codeReview: {
     setup: [
       {
+        id: 'myCustomSetup',
         label: 'myCustomSetup',
         reviewers: [
           { label: 'GPT-5', model: openai('gpt-5.2'), providerOptions: { reasoningEffort: 'high' } },
           { model: google('gemini-2.5-pro') },
         ],
         validator: { model: openai('gpt-5.2') },
-        formatter: { model: openai('gpt-5-mini') },
       },
       {
+        id: 'fastReview',
         label: 'fastReview',
         reviewers: [{ model: openai('gpt-5-mini') }],
-        // validator and formatter use defaults
+        // validator uses defaultValidator
       },
     ],
 
-    // Defaults for custom setups that don't specify validator/formatter
+    // Default validator for custom setups that don't specify one
     defaultValidator: { model: openai('gpt-5.2'), providerOptions: { reasoningEffort: 'high' } },
-    defaultFormatter: { model: openai('gpt-5-mini') },
   },
 });
 ```
@@ -324,11 +373,13 @@ export default defineConfig({
       {
         id: 'src-only',
         label: 'Source files only',
+        diffSource: 'branch',
         getFiles: (ctx) => ctx.allFiles.filter((f) => f.startsWith('src/')),
       },
       {
         id: 'no-tests',
         label: 'Exclude tests',
+        diffSource: 'branch',
         getFiles: (ctx) => ctx.allFiles.filter((f) => !f.includes('.test.')),
       },
     ],
@@ -340,6 +391,10 @@ The `getFiles` function receives a context object with:
 - `stagedFiles`: Files currently staged for commit
 - `allFiles`: All files changed compared to base branch
 
+The optional `diffSource` field controls which git diff source the scope uses:
+- `'branch'` (default): compare against selected base branch
+- `'staged'`: use staged changes
+
 To include built-in options alongside your custom scopes, use `BUILT_IN_SCOPE_OPTIONS`:
 
 ```typescript

package/dist/{index-CuuBIk7l.d.ts → index-BN4ituqC.d.ts}

@@ -26,9 +26,13 @@ type SetupConfig = {
   reviewers: CustomModelConfig[];
   /** Model that validates and consolidates findings from all reviewers. Defaults to first reviewer if not specified. */
   validator?: CustomModelConfig;
-  /** Model that formats the final output to structured JSON. Defaults to gpt-5-mini if not specified. */
-  formatter?: CustomModelConfig;
 };
+/**
+ * Review concurrency settings.
+ * - number: applies the same concurrency limit to all providers
+ * - object: sets per-provider concurrency limits (fallback for unspecified providers is unlimited)
+ */
+type ReviewConcurrencyConfig = number | Record<string, number>;
 /**
  * Context provided to scope's getFiles function with all available file lists.
  */
@@ -47,6 +51,13 @@ type ScopeConfig = {
   id: string;
   /** Display label shown in UI */
   label: string;
+  /**
+   * Which git diff source this scope should use.
+   * - `branch` compares against the selected base branch
+   * - `staged` reviews staged changes
+   * @default 'branch'
+   */
+  diffSource?: 'branch' | 'staged';
   /** Function that receives available file lists and returns the files to review */
   getFiles: (ctx: ScopeContext) => string[] | Promise<string[]>;
   showFileCount?: boolean;
@@ -73,7 +84,21 @@ type ReviewCodeChangesConfig = {
    */
   reviewInstructionsPath?: string;
   /**
-   * Array of custom named setups with full control over reviewer, validator, and formatter models.
+   * Whether to include the repository AGENTS.md content in reviewer prompts.
+   * Uses `<git-root>/AGENTS.md` when available.
+   * @default true
+   */
+  includeAgentsFileInReviewPrompt?: boolean;
+  /**
+   * Output file path for local review markdown generated by
+   * `review-code-changes` or `advanced-review-changes`.
+   * Can be overridden via `--output`.
+   * @default 'pr-review.md'
+   * @example './reviews/local-review.md'
+   */
+  reviewOutputPath?: string;
+  /**
+   * Array of custom named setups with full control over reviewer and validator models.
    * Each setup has a label that can be selected via the CLI --setup flag.
    * Custom setups take precedence over built-in presets when labels match.
    */
@@ -89,17 +114,26 @@ type ReviewCodeChangesConfig = {
    * Falls back to first reviewer in the setup if not specified.
    */
   defaultValidator?: CustomModelConfig;
-  /**
-   * Default formatter model used when a setup doesn't specify one.
-   * Falls back to gpt-5-mini if not specified.
-   */
-  defaultFormatter?: CustomModelConfig;
   /**
    * Directory for storing review logs.
    * Can also be set via `AI_CLI_LOGS_DIR` environment variable.
    * Config value takes precedence over env var.
    */
   logsDir?: string;
+  /**
+   * Concurrency limit for running independent reviewer models.
+   *
+   * - `number`: same limit for all providers
+   * - `Record<string, number>`: per-provider limits keyed by provider id
+   *
+   * Provider ids come from `model.provider` (for example, `openai.responses` and `google.generative-ai`).
+   * Unspecified providers default to unlimited concurrency.
+   *
+   * @default Number.POSITIVE_INFINITY
+   * @example 2
+   * @example { 'openai.responses': 2, 'google.generative-ai': 1 }
+   */
+  concurrencyPerProvider?: ReviewConcurrencyConfig;
 };
 type CreatePRConfig = {
   /**
@@ -139,7 +173,8 @@ type CreatePRConfig = {
 };
 type Config = {
   /**
-   * Configuration for the review-code-changes and review-pr commands.
+   * Configuration for the review-code-changes, advanced-review-changes, and
+   * review-pr commands.
    */
   codeReview?: ReviewCodeChangesConfig;
   /**
@@ -178,24 +213,28 @@ declare const DEFAULT_SCOPES: {
   readonly all: {
     readonly id: "all";
     readonly label: "All changes";
+    readonly diffSource: "branch";
     readonly showFileCount: true;
     readonly getFiles: (ctx: ScopeContext) => string[];
   };
   readonly staged: {
     readonly id: "staged";
     readonly label: "Staged changes";
+    readonly diffSource: "staged";
     readonly showFileCount: true;
     readonly getFiles: (ctx: ScopeContext) => string[];
   };
   readonly globs: {
     readonly id: "globs";
     readonly label: "Select files using glob patterns (use !pattern to exclude)";
+    readonly diffSource: "branch";
     readonly showFileCount: false;
     readonly getFiles: (ctx: ScopeContext) => Promise<string[]>;
   };
   readonly unViewed: {
     readonly id: "unViewed";
     readonly label: "Unviewed files in PR";
+    readonly diffSource: "branch";
     readonly showFileCount: false;
     readonly getFiles: () => Promise<string[]>;
   };
@@ -233,7 +272,57 @@ declare const BUILT_IN_SETUP_OPTIONS: SetupConfig[];
  * Converts setup configs to CLI select options.
  */
 //#endregion
-//#region src/commands/create-pr/index.d.ts
+//#region src/commands/advanced-review-changes/advanced-review-changes.d.ts
+declare const advancedReviewChangesCommand: {
+  short: string | undefined;
+  description: string;
+  run: (cmdArgs: {
+    setup: string | undefined;
+    scope: string | undefined;
+    baseBranch: string | undefined;
+    output: string | undefined;
+    customReviewInstruction: string | undefined;
+    includeDefaultReviewInstructions: string | undefined;
+  }) => Promise<void> | void;
+  args: {
+    setup: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
+    scope: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
+    baseBranch: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
+    output: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
+    customReviewInstruction: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
+    includeDefaultReviewInstructions: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
+  } | undefined;
+  examples: {
+    args: string[];
+    description: string;
+  }[] | undefined;
+};
+//#endregion
+//#region src/commands/create-pr/create-pr.d.ts
 declare const createPRCommand: {
   short: string | undefined;
   description: string;
@@ -271,7 +360,7 @@ declare const createPRCommand: {
   }[] | undefined;
 };
 //#endregion
-//#region src/commands/review-code-changes/index.d.ts
+//#region src/commands/review-code-changes/review-code-changes.d.ts
 declare const reviewCodeChangesCommand: {
   short: string | undefined;
   description: string;
@@ -279,6 +368,7 @@ declare const reviewCodeChangesCommand: {
     setup: string | undefined;
     scope: string | undefined;
     baseBranch: string | undefined;
+    output: string | undefined;
   }) => Promise<void> | void;
   args: {
     setup: {
@@ -296,6 +386,11 @@ declare const reviewCodeChangesCommand: {
       name: string;
       description: string;
     };
+    output: {
+      type: "value-string-flag";
+      name: string;
+      description: string;
+    };
   } | undefined;
   examples: {
     args: string[];
@@ -303,7 +398,7 @@ declare const reviewCodeChangesCommand: {
   }[] | undefined;
 };
 //#endregion
-//#region src/commands/review-pr/index.d.ts
+//#region src/commands/review-pr/review-pr.d.ts
 declare const reviewPRCommand: {
   short: string | undefined;
   description: string;
@@ -341,4 +436,4 @@ declare const reviewPRCommand: {
   }[] | undefined;
 };
 //#endregion
-export { BUILT_IN_SCOPE_OPTIONS, BUILT_IN_SETUP_OPTIONS, type Config, type CreatePRConfig, type CustomModelConfig, DEFAULT_SCOPES, type ReviewCodeChangesConfig, type ScopeConfig, type ScopeContext, type SetupConfig, createPRCommand, defineConfig, reviewCodeChangesCommand, reviewPRCommand };
+export { BUILT_IN_SCOPE_OPTIONS, BUILT_IN_SETUP_OPTIONS, type Config, type CreatePRConfig, type CustomModelConfig, DEFAULT_SCOPES, type ReviewCodeChangesConfig, type ReviewConcurrencyConfig, type ScopeConfig, type ScopeContext, type SetupConfig, advancedReviewChangesCommand, createPRCommand, defineConfig, reviewCodeChangesCommand, reviewPRCommand };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as BUILT_IN_SCOPE_OPTIONS, i as BUILT_IN_SETUP_OPTIONS, n as reviewCodeChangesCommand, o as DEFAULT_SCOPES, r as createPRCommand, s as defineConfig, t as reviewPRCommand } from "./review-pr-Dh5esOtl.js";
+import { a as BUILT_IN_SETUP_OPTIONS, c as defineConfig, i as reviewCodeChangesCommand, n as createPRCommand, o as BUILT_IN_SCOPE_OPTIONS, r as advancedReviewChangesCommand, s as DEFAULT_SCOPES, t as reviewPRCommand } from "./review-pr-MkD-Pu9b.js";
 
-export { BUILT_IN_SCOPE_OPTIONS, BUILT_IN_SETUP_OPTIONS, DEFAULT_SCOPES, createPRCommand, defineConfig, reviewCodeChangesCommand, reviewPRCommand };
+export { BUILT_IN_SCOPE_OPTIONS, BUILT_IN_SETUP_OPTIONS, DEFAULT_SCOPES, advancedReviewChangesCommand, createPRCommand, defineConfig, reviewCodeChangesCommand, reviewPRCommand };

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as reviewCodeChangesCommand, r as createPRCommand, t as reviewPRCommand } from "./review-pr-Dh5esOtl.js";
+import { i as reviewCodeChangesCommand, n as createPRCommand, r as advancedReviewChangesCommand, t as reviewPRCommand } from "./review-pr-MkD-Pu9b.js";
 import { createCLI } from "@ls-stack/cli";
 
 //#region src/main.ts
@@ -9,7 +9,8 @@ await createCLI({
 }, {
 	"review-code-changes": reviewCodeChangesCommand,
 	"review-pr": reviewPRCommand,
-	"create-pr": createPRCommand
+	"create-pr": createPRCommand,
+	"advanced-review-changes": advancedReviewChangesCommand
 });
 
 //#endregion