@synmux/claude-commit 1.0.1 → 1.0.3

package/src/generate.ts

@@ -1,9 +1,24 @@
 /**
  * The commit-message pipeline:
  *
- *   diff ──split──▶ [chunk, chunk, ...] ──summary model──▶ [summary, ...]
+ *   diff ──ignore──▶ ──partition──▶ primary diff, low-priority diff
+ *        ──split──▶ [chunk, chunk, ...] ──summary model──▶ [summary, ...]
  *        ──final model──▶ commit message(s)
  *
+ * The `ignore` patterns run first and remove file sections outright, so
+ * ignored content is never chunked, never sent and never paid for. Those
+ * files are still committed - `ignore` governs what the model reads, not
+ * what git stages - but when it matches *everything* there is nothing left
+ * to describe and the run stops rather than inventing a message.
+ *
+ * The remaining diff is partitioned by the configured `lowPriorityPaths`: file
+ * sections under those paths (generated docs, lockfiles, ...) form a
+ * low-priority partition that is summarised after, and more briefly than,
+ * the primary one, and the final model is told which is which so the
+ * subject line describes the primary changes. When every file is low
+ * priority the partition is promoted and the run is identical to one with
+ * no patterns configured.
+ *
  * The summary model (default `sonnet`) reads each diff chunk and writes a
  * factual summary; chunks are sized by a content-classified token estimate
  * (`splitDiffToFit`) so each request fits the model's context window, and a
@@ -14,7 +29,15 @@
  * message(s), applying the configured formatting rules.
  */
 import { runPrompt } from "./agent";
-import { redactOpaqueRuns, splitDiffToFit } from "./diff";
+import { isOllamaModel } from "./models";
+import { resolveOllamaContext } from "./ollama";
+import {
+  applyIgnorePatterns,
+  partitionDiff,
+  redactOpaqueRuns,
+  splitDiffToFit,
+} from "./diff";
+import { createPathMatcher } from "./paths";
 import { clampChunkTokens } from "./tokens";
 import { ClaudeCommitError, isPromptTooLongError } from "./errors";
 import {
@@ -24,10 +47,16 @@ import {
   buildSummaryUser,
   cleanMessage,
   extractMessages,
+  hasLowPrioritySummaries,
   MESSAGES_SCHEMA,
   parseOptions,
 } from "./prompts";
-import type { Config } from "./types";
+import type {
+  ChangePriority,
+  Config,
+  DiffSummary,
+  OllamaConfig,
+} from "./types";
 
 export interface GenerateProgress {
   /** Called when a new phase of work begins (for spinner labels). */
@@ -47,17 +76,97 @@ export interface GenerateOptions {
    * Defaults to {@link runPrompt}.
    */
   runner?: typeof runPrompt;
+  /**
+   * Resolves an `ollama:` model's context window, called once per model
+   * per run before any chunk is sized; injectable so tests can exercise an
+   * `"auto"` configuration without a server. Defaults to
+   * {@link resolveOllamaContext}.
+   */
+  resolveOllamaContext?: typeof resolveOllamaContext;
+}
+
+/** The context window one Ollama model ran with during this run. */
+export interface OllamaContextWindow {
+  /** The model string as configured, prefix included. */
+  model: string;
+  tokens: number;
+  /** Whether the number was configured or chosen by the server (`"auto"`). */
+  source: "config" | "auto";
+}
+
+/** How the `ignore` patterns applied to this diff (for `--verbose`). */
+export interface IgnoreStats {
+  /** File sections dropped before any model saw them. */
+  ignoredFiles: number;
+  /** File sections in the staged diff with a recognisable path. */
+  totalFiles: number;
+}
+
+/** How the `lowPriorityPaths` patterns applied to this diff (for `--verbose`). */
+export interface LowPriorityStats {
+  /** File sections whose paths all matched a pattern. */
+  matchedFiles: number;
+  /** File sections in the diff with a recognisable path. */
+  totalFiles: number;
+  /** Every file matched, so the changes were treated as primary after all. */
+  promoted: boolean;
 }
 
 export interface GenerateResult {
   /** Candidate commit messages (length 1 in non-interactive mode). */
   messages: string[];
-  /** The intermediate summaries (useful for `--verbose`). */
-  summaries: string[];
-  /** Number of diff chunks the summary stage processed. */
+  /** The intermediate summaries, primary first, each tagged with its priority. */
+  summaries: DiffSummary[];
+  /** Number of diff chunks the summary stage processed, across both partitions. */
   chunkCount: number;
   /** Total cost across all model calls, in USD. */
   costUsd: number;
+  /** How the low-priority patterns applied to this diff. */
+  lowPriority: LowPriorityStats;
+  /** How the ignore patterns applied to this diff. */
+  ignored: IgnoreStats;
+  /** The context window each Ollama model ran with, in order of first use. */
+  ollamaContexts: OllamaContextWindow[];
+}
+
+/**
+ * Resolves each `ollama:` model's context window once and hands back an
+ * {@link OllamaConfig} with the number pinned in place of `"auto"`, so the
+ * runner never repeats the probe. Claude models get `undefined`: they
+ * neither need nor understand the block.
+ */
+class OllamaContextResolver {
+  private readonly windows = new Map<string, Promise<number>>();
+  readonly resolved: OllamaContextWindow[] = [];
+
+  constructor(
+    private readonly config: OllamaConfig,
+    private readonly resolve: typeof resolveOllamaContext,
+    private readonly signal?: AbortSignal,
+  ) {}
+
+  /** The Ollama settings to run `model` with, or `undefined` for a Claude model. */
+  async settingsFor(model: string): Promise<OllamaConfig | undefined> {
+    if (!isOllamaModel(model)) return undefined;
+    const tokens = await this.windowFor(model);
+    return { ...this.config, context: tokens };
+  }
+
+  private windowFor(model: string): Promise<number> {
+    let pending = this.windows.get(model);
+    if (!pending) {
+      pending = this.resolve(model, this.config, this.signal).then((tokens) => {
+        this.resolved.push({
+          model,
+          tokens,
+          source: this.config.context === "auto" ? "auto" : "config",
+        });
+        return tokens;
+      });
+      this.windows.set(model, pending);
+    }
+    return pending;
+  }
 }
 
 /**
@@ -67,47 +176,59 @@ export interface GenerateResult {
  */
 const MIN_RETRY_CHUNK_TOKENS = 8_000;
 
-/** Run the full pipeline over a staged diff. */
-export async function generateCommit(
-  diff: string,
-  config: Config,
-  options: GenerateOptions = {},
-): Promise<GenerateResult> {
-  const {
-    count = 1,
-    progress = {},
-    abortController,
-    runner = runPrompt,
-  } = options;
+interface PartitionSummaryOptions {
+  config: Config;
+  runner: typeof runPrompt;
+  progress: GenerateProgress;
+  contexts: OllamaContextResolver;
+  abortController?: AbortController;
+}
+
+/** Spinner label for one chunk of a partition. */
+function readingLabel(
+  priority: ChangePriority,
+  position: number,
+  total: number,
+): string {
+  const subject = priority === "low" ? "low-priority diff" : "diff";
+  return total > 1
+    ? `Reading ${subject} (part ${position + 1}/${total})`
+    : `Reading ${subject}`;
+}
 
-  const effectiveDiff = config.skipArmored ? redactOpaqueRuns(diff) : diff;
+/**
+ * Stage 1 for one partition: split it into chunks and summarise each, via a
+ * work queue so an oversized chunk can be re-split and retried in place.
+ * The estimate is calibrated, but only the backend knows the true token
+ * count; its "prompt is too long" rejection is free, so treat it as the
+ * final arbiter: halve the budget, re-split just that chunk, and continue
+ * where we left off. Returns no summaries for an empty partition.
+ */
+async function summarizePartition(
+  diff: string,
+  priority: ChangePriority,
+  options: PartitionSummaryOptions,
+): Promise<{ summaries: DiffSummary[]; costUsd: number }> {
+  const { config, runner, progress, contexts, abortController } = options;
 
   // The configured chunk budget is clamped to the summary model's context
   // window so a single chunk (plus prompt scaffolding and response headroom)
-  // can never overflow it, whatever `maxChunkTokens` says. Chunks are sized
-  // by a content-classified token estimate: opaque content (age/gpg armor,
-  // binary patches) measures near 1 char/token, so a plain chars-based
-  // budget underestimates armor-heavy diffs more than threefold.
+  // can never overflow it, whatever `maxChunkTokens` says. For an Ollama
+  // model that window is resolved here first - possibly by asking the
+  // server - so the chunks and the request agree on the same number.
+  // Chunks are sized by a content-classified token estimate: opaque content
+  // (age/gpg armor, binary patches) measures near 1 char/token, so a plain
+  // chars-based budget underestimates armor-heavy diffs more than threefold.
+  const ollama = await contexts.settingsFor(config.models.summary);
   const chunkTokens = clampChunkTokens(
     config.models.summary,
     config.maxChunkTokens,
+    typeof ollama?.context === "number" ? ollama.context : undefined,
   );
-  const chunks = splitDiffToFit(
-    effectiveDiff,
-    chunkTokens,
-    config.charsPerToken,
-  );
-  if (chunks.length === 0) {
-    throw new ClaudeCommitError("There are no staged changes to summarize.");
-  }
+  const chunks = splitDiffToFit(diff, chunkTokens, config.charsPerToken);
 
-  // Stage 1: summarize each chunk, via a work queue so an oversized chunk
-  // can be re-split and retried in place. The estimate is calibrated, but
-  // only the backend knows the true token count; its "prompt is too long"
-  // rejection is free, so treat it as the final arbiter: halve the budget,
-  // re-split just that chunk, and continue where we left off.
-  const summarySystem = buildSummarySystem();
-  const summaries: string[] = [];
+  const summarySystem = buildSummarySystem(priority);
+  const summaries: DiffSummary[] = [];
   let costUsd = 0;
 
   const queue = chunks.map((chunk) => ({ chunk, tokenBudget: chunkTokens }));
@@ -115,22 +236,19 @@ export async function generateCommit(
     const task = queue.shift()!;
     const position = summaries.length;
     const total = summaries.length + queue.length + 1;
-    progress.onPhase?.(
-      total > 1
-        ? `Reading diff (part ${position + 1}/${total})`
-        : "Reading diff",
-    );
+    progress.onPhase?.(readingLabel(priority, position, total));
     try {
       const result = await runner(
-        buildSummaryUser(task.chunk, position, total),
+        buildSummaryUser(task.chunk, position, total, priority),
         {
           model: config.models.summary,
           system: summarySystem,
           allowApiKey: config.allowApiKey,
+          ...(ollama ? { ollama } : {}),
           ...(abortController ? { abortController } : {}),
         },
       );
-      summaries.push(result.text);
+      summaries.push({ priority, text: result.text });
       costUsd += result.costUsd;
     } catch (error) {
       const halvedBudget = Math.floor(task.tokenBudget / 2);
@@ -156,6 +274,83 @@ export async function generateCommit(
     }
   }
 
+  return { summaries, costUsd };
+}
+
+/** Run the full pipeline over a staged diff. */
+export async function generateCommit(
+  diff: string,
+  config: Config,
+  options: GenerateOptions = {},
+): Promise<GenerateResult> {
+  const {
+    count = 1,
+    progress = {},
+    abortController,
+    runner = runPrompt,
+    resolveOllamaContext: resolveContext = resolveOllamaContext,
+  } = options;
+  const contexts = new OllamaContextResolver(
+    config.ollama,
+    resolveContext,
+    abortController?.signal,
+  );
+
+  // Ignore first: dropped sections cost nothing downstream. Unlike a
+  // low-priority partition, an ignored one has nowhere to be promoted to,
+  // so matching every file is a dead end rather than a special case.
+  const ignoreResult = applyIgnorePatterns(
+    diff,
+    createPathMatcher(config.ignore),
+  );
+  const ignored: IgnoreStats = {
+    ignoredFiles: ignoreResult.ignoredFiles,
+    totalFiles: ignoreResult.totalFiles,
+  };
+  if (ignoreResult.diff.trim() === "" && ignoreResult.ignoredFiles > 0) {
+    throw new ClaudeCommitError(describeFullyIgnored(ignored));
+  }
+
+  const effectiveDiff = config.skipArmored
+    ? redactOpaqueRuns(ignoreResult.diff)
+    : ignoreResult.diff;
+  const partition = partitionDiff(
+    effectiveDiff,
+    createPathMatcher(config.lowPriorityPaths),
+  );
+  if (partition.primary.trim() === "") {
+    throw new ClaudeCommitError("There are no staged changes to summarize.");
+  }
+
+  // Stage 1: summarise the primary partition first - fail fast on the part
+  // that matters - then the low-priority one (skipped when empty).
+  const partitionOptions: PartitionSummaryOptions = {
+    config,
+    runner,
+    progress,
+    contexts,
+    ...(abortController ? { abortController } : {}),
+  };
+  const primaryStage = await summarizePartition(
+    partition.primary,
+    "primary",
+    partitionOptions,
+  );
+  const lowPriorityStage =
+    partition.lowPriority.trim() === ""
+      ? { summaries: [], costUsd: 0 }
+      : await summarizePartition(
+          partition.lowPriority,
+          "low",
+          partitionOptions,
+        );
+  const summaries = [...primaryStage.summaries, ...lowPriorityStage.summaries];
+  if (summaries.length === 0) {
+    throw new ClaudeCommitError("There are no staged changes to summarize.");
+  }
+  let costUsd = primaryStage.costUsd + lowPriorityStage.costUsd;
+  const hasLowPriority = hasLowPrioritySummaries(summaries);
+
   // Stage 2: write the commit message(s) from the summaries.
   //
   // Prefer a structured (JSON-schema) response so parsing is robust regardless
@@ -168,9 +363,11 @@ export async function generateCommit(
     count > 1 ? "Writing commit options" : "Writing commit message",
   );
 
+  const finalOllama = await contexts.settingsFor(config.models.final);
   const baseOpts = {
     model: config.models.final,
     allowApiKey: config.allowApiKey,
+    ...(finalOllama ? { ollama: finalOllama } : {}),
     ...(abortController ? { abortController } : {}),
   };
   const temperature =
@@ -191,7 +388,7 @@ export async function generateCommit(
         buildFinalUser(summaries, count, attempt.structured),
         {
           ...baseOpts,
-          system: buildFinalSystem(config, attempt.structured),
+          system: buildFinalSystem(config, attempt.structured, hasLowPriority),
           ...(attempt.structured
             ? {
                 outputFormat: {
@@ -225,7 +422,7 @@ export async function generateCommit(
 
   const cleaned = (messages ?? [])
     .map(cleanMessage)
-    .filter((m) => m.length > 0);
+    .filter((message) => message.length > 0);
   const deduped = dedupe(cleaned);
   if (deduped.length === 0) {
     if (lastError instanceof ClaudeCommitError) throw lastError;
@@ -239,9 +436,35 @@ export async function generateCommit(
     summaries,
     chunkCount: summaries.length,
     costUsd,
+    lowPriority: {
+      matchedFiles: partition.matchedFiles,
+      totalFiles: partition.totalFiles,
+      promoted: partition.promoted,
+    },
+    ignored,
+    ollamaContexts: contexts.resolved,
   };
 }
 
+/**
+ * The error for a commit whose every changed file matched `ignore`.
+ *
+ * There is no sensible fallback here. Describing the ignored files anyway
+ * would contradict the directive the user wrote; committing an empty or
+ * invented message would be worse. Naming the directive and the count makes
+ * the cause obvious, because the alternative - a run that mysteriously
+ * reports no staged changes when `git status` plainly disagrees - is the
+ * kind of bug people spend an afternoon on.
+ */
+export function describeFullyIgnored(stats: IgnoreStats): string {
+  const files = `${stats.ignoredFiles} staged file${stats.ignoredFiles === 1 ? "" : "s"}`;
+  return (
+    `Every one of the ${files} matches an "ignore" pattern, so there is ` +
+    `nothing left to describe. Narrow the patterns, or pass --no-ignore to ` +
+    `write a message about these changes for this commit.`
+  );
+}
+
 function dedupe(items: string[]): string[] {
   const seen = new Set<string>();
   const out: string[] = [];

package/src/git.ts

@@ -47,14 +47,48 @@ export async function getRepoRoot(): Promise<string> {
   return (await git(["rev-parse", "--show-toplevel"])).trim();
 }
 
-/** The unified diff of staged changes (`git diff --cached`). */
+/**
+ * Flags that pin the shape and membership of every staged-change reader
+ * against user diff settings. The list is exhaustive, not illustrative:
+ *
+ * - `--no-relative`: with `diff.relative=true`, running from a subdirectory
+ *   would both strip leading path segments (breaking `lowPriorityPaths`
+ *   matching, which is always repository-root-relative) and omit staged
+ *   files outside that directory entirely, so the message would describe a
+ *   subset of what gets committed.
+ * - `--no-ext-diff`: `diff.external` / `GIT_EXTERNAL_DIFF` / a gitattributes
+ *   `diff=<driver>` replace the diff body wholesale - a difftastic-style
+ *   driver emits no `diff --git` headers at all, and a driver can even forge
+ *   headers that attach one file's changes to another path.
+ * - `--ignore-submodules=none`: `diff.ignoreSubmodules=all` erases a staged
+ *   submodule bump from all three readers.
+ * - `--submodule=short`: `diff.submodule=log|diff` replace a submodule's
+ *   `diff --git` section with a header-less `Submodule <path> <a>..<b>:`
+ *   block, which the section splitter would glue onto the preceding file's
+ *   section (and priority).
+ * - The `a/`/`b/` prefixes are forced so `diff.noprefix` /
+ *   `diff.mnemonicPrefix` cannot change the header format the diff parser
+ *   (`sectionPaths` in `src/diff.ts`) expects.
+ */
+const STAGED_DIFF_FLAGS = [
+  "--cached",
+  "--no-color",
+  "--no-relative",
+  "--no-ext-diff",
+  "--ignore-submodules=none",
+  "--submodule=short",
+  "--src-prefix=a/",
+  "--dst-prefix=b/",
+];
+
+/** The unified diff of staged changes (`git diff --cached`), repository-root-relative. */
 export async function getStagedDiff(): Promise<string> {
-  return git(["diff", "--cached", "--no-color"]);
+  return git(["diff", ...STAGED_DIFF_FLAGS]);
 }
 
 /** Parsed list of staged files with their status codes. */
 export async function getStagedFiles(): Promise<FileChange[]> {
-  const out = await git(["diff", "--cached", "--name-status"]);
+  const out = await git(["diff", ...STAGED_DIFF_FLAGS, "--name-status"]);
   return out
     .split("\n")
     .map((line) => line.trim())
@@ -75,7 +109,7 @@ export async function stageAll(): Promise<void> {
 
 /** A short one-line stat summary of staged changes (for display). */
 export async function getStagedStat(): Promise<string> {
-  return (await git(["diff", "--cached", "--stat", "--no-color"])).trimEnd();
+  return (await git(["diff", ...STAGED_DIFF_FLAGS, "--stat"])).trimEnd();
 }
 
 /**

package/src/models.ts

@@ -0,0 +1,95 @@
+/**
+ * Model-string parsing: which provider serves a configured model name.
+ *
+ * A model string is either a Claude model (an alias like `sonnet`, or a full
+ * `claude-*` id) or, with an `ollama:` prefix, a model on a local or
+ * self-hosted Ollama server. Everything after the prefix is the Ollama model
+ * name **verbatim**, which matters because Ollama names carry their own
+ * colon: `ollama:ornith-1.5:35b` is the model `ornith-1.5:35b`, not
+ * `ornith-1.5` with some tag `35b` cco is expected to reassemble. Only the
+ * first `ollama:` is consumed.
+ *
+ * The prefix is matched case-insensitively - it is cco's own syntax, and
+ * `Ollama:` is an easy thing to type - while the model name is passed
+ * through with its case intact, because Ollama's registry is case-sensitive.
+ *
+ * This module is deliberately free of transport and SDK imports so that
+ * anything needing to know *which* provider a name refers to (chunk sizing
+ * in `src/tokens.ts`, for one) can ask without pulling in a backend.
+ */
+import { ClaudeCommitError } from "./errors";
+
+/** Marks a model name as belonging to an Ollama server. Case-insensitive. */
+export const OLLAMA_PREFIX = "ollama:";
+
+/** Which backend serves a model. */
+export type ModelProvider = "claude" | "ollama";
+
+/** A model string resolved into a provider and the name that provider expects. */
+export interface ModelRef {
+  provider: ModelProvider;
+  /** The model name to send to the provider, with any cco prefix removed. */
+  name: string;
+}
+
+/**
+ * Default Ollama base URL, used when neither the config nor `$OLLAMA_HOST`
+ * names one. This is Ollama's own default listen address.
+ */
+export const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+
+/**
+ * Default `ollama.context`: ask the server what window it would run the
+ * model with on this machine, rather than guess (see `probeOllamaContext`
+ * in `src/ollama.ts`). Ollama's choice is made from available VRAM and
+ * capped at the model's trained maximum, so it is the largest window the
+ * server believes it can actually load.
+ */
+export const DEFAULT_OLLAMA_CONTEXT = "auto" as const;
+
+/**
+ * The window assumed for an `ollama:` model when nothing better is known:
+ * the synchronous fallback in `contextWindowTokens` for callers that size
+ * chunks without first resolving the context. The pipeline never relies on
+ * it - it resolves `"auto"` to a real number before sizing - so this only
+ * matters to direct library use. 32768 is Ollama's middle VRAM tier.
+ */
+export const DEFAULT_OLLAMA_CONTEXT_TOKENS = 32_768;
+
+/** Whether `model` names an Ollama model (i.e. carries the `ollama:` prefix). */
+export function isOllamaModel(model: string): boolean {
+  return model.trim().toLowerCase().startsWith(OLLAMA_PREFIX);
+}
+
+/**
+ * Resolve a configured model string into its provider and provider-side name.
+ *
+ * Throws {@link ClaudeCommitError} for a name that no provider could serve:
+ * an empty string, or an `ollama:` prefix with nothing after it.
+ */
+export function parseModelRef(model: string): ModelRef {
+  const trimmed = model.trim();
+  if (trimmed === "") {
+    throw new ClaudeCommitError(
+      "No model configured. Set a model name, or an Ollama model as " +
+        `"${OLLAMA_PREFIX}<name>:<tag>".`,
+    );
+  }
+  if (!isOllamaModel(trimmed)) {
+    return { provider: "claude", name: trimmed };
+  }
+  const name = trimmed.slice(OLLAMA_PREFIX.length).trim();
+  if (name === "") {
+    throw new ClaudeCommitError(
+      `"${model}" names no Ollama model. Write the model after the prefix, ` +
+        `e.g. "${OLLAMA_PREFIX}ornith-1.5:35b".`,
+    );
+  }
+  return { provider: "ollama", name };
+}
+
+/** A model string as it should appear in an error or a `--verbose` line. */
+export function describeModel(model: string): string {
+  const trimmed = model.trim();
+  return isOllamaModel(trimmed) ? `${trimmed} (Ollama)` : `${trimmed} (Claude)`;
+}