@synmux/claude-commit 1.0.1 → 1.0.3

package/src/prompts.ts

@@ -5,7 +5,7 @@
  * Stage 2 (final model): turn the summaries into a commit message that obeys the
  * configured formatting rules (conventional commits, gitmoji, template, body).
  */
-import type { Config } from "./types";
+import type { ChangePriority, Config, DiffSummary } from "./types";
 
 /** Sentinel separating candidate messages in interactive mode. */
 export const OPTION_DELIMITER = "===OPTION===";
@@ -31,12 +31,39 @@ const GITMOJI_GUIDE = [
 const CONVENTIONAL_TYPES =
   "feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert";
 
-/** System prompt for the diff-summarization stage. */
-export function buildSummarySystem(): string {
+/**
+ * What "low priority" means, phrased once for both stages so the summary
+ * model and the final model share the same picture of the content.
+ */
+const LOW_PRIORITY_DESCRIPTION =
+  "paths the user has marked as low priority - typically generated or vendored content such as " +
+  "tool-generated documentation, lockfiles, snapshots or build output - whose changes matter less " +
+  "than the rest of the commit";
+
+/**
+ * System prompt for the diff-summarization stage. The low-priority variant
+ * asks for a deliberately short summary: the final model only needs to know
+ * which areas changed and how, so the churn cannot crowd out the primary
+ * changes when the summaries are combined.
+ */
+export function buildSummarySystem(
+  priority: ChangePriority = "primary",
+): string {
+  const role =
+    "You are an expert software engineer analyzing a git diff in preparation for writing a commit message.";
+  const guidance =
+    priority === "low"
+      ? [
+          `The diff you are given comes from ${LOW_PRIORITY_DESCRIPTION}.`,
+          "Summarize it briefly: a few sentences at most, naming which files or areas changed and the nature of the change (regenerated, bumped, added, removed), without describing individual edits.",
+        ]
+      : [
+          "Summarize the change factually and concisely: which files changed, what was added, removed or modified, and the apparent intent and impact of the change.",
+          "Focus on the substance of the change, not a line-by-line readout.",
+        ];
   return [
-    "You are an expert software engineer analyzing a git diff in preparation for writing a commit message.",
-    "Summarize the change factually and concisely: which files changed, what was added, removed or modified, and the apparent intent and impact of the change.",
-    "Focus on the substance of the change, not a line-by-line readout.",
+    role,
+    ...guidance,
     "Do not write a commit message. Do not include code fences or the raw diff.",
     "If you are told this is one part of a larger change, summarize only the part you are given.",
   ].join(" ");
@@ -47,11 +74,13 @@ export function buildSummaryUser(
   chunk: string,
   index: number,
   total: number,
+  priority: ChangePriority = "primary",
 ): string {
+  const subject = priority === "low" ? "low-priority diff" : "diff";
   const preamble =
     total > 1
-      ? `This is part ${index + 1} of ${total} of a larger diff. Summarize only this part:`
-      : "Summarize the following diff:";
+      ? `This is part ${index + 1} of ${total} of a larger ${subject}. Summarize only this part:`
+      : `Summarize the following ${subject}:`;
   return `${preamble}\n\n${chunk}`;
 }
 
@@ -89,12 +118,49 @@ export function extractMessages(structured: unknown): string[] | null {
   return null;
 }
 
+/**
+ * The weighting rules for a change with both primary and low-priority parts.
+ * They live in the system prompt next to the other subject-line rules so
+ * they carry the same authority, and every clause is branched on the config
+ * exactly as those rules are: a plain single-line setup is never told about
+ * a type, a gitmoji or a body it was not asked for. The wording is absolute
+ * and size-independent on purpose - a twenty-line fix next to thousands of
+ * regenerated lines must still read as a fix, however dull the fix is.
+ */
+function lowPriorityWeightingRules(config: Config): string[] {
+  const rules = [
+    `The summary is split into primary changes and low-priority changes (${LOW_PRIORITY_DESCRIPTION}). ` +
+      "The primary changes are what this commit is about.",
+    "The subject line describes the primary changes. This holds however small or routine the primary changes are " +
+      "and however many files or lines the low-priority changes touch: a one-line primary change still owns the subject. " +
+      "If the primary changes seem too small to fill a subject line, write a short subject about them anyway rather than " +
+      "reaching for the low-priority changes to pad it. " +
+      "Mention the low-priority changes in the subject only if they fit naturally without displacing anything about the primary changes.",
+  ];
+  if (config.conventionalCommits) {
+    rules.push(
+      "Choose the commit type and scope from the primary changes alone.",
+    );
+  }
+  if (config.gitmoji) {
+    rules.push("Choose the gitmoji from the primary changes alone.");
+  }
+  return rules;
+}
+
 /**
  * System prompt for the final commit-message stage, encoding all formatting
  * rules. When `structured` is true, the model returns its messages as JSON, so
- * the "no markdown" guidance is scoped to each message's own text.
+ * the "no markdown" guidance is scoped to each message's own text. When
+ * `hasLowPriority` is true the summaries come in two priority groups and the
+ * weighting rules ({@link lowPriorityWeightingRules}) are added between the
+ * subject-line rules and the body rule, in the order the constraints apply.
  */
-export function buildFinalSystem(config: Config, structured = false): string {
+export function buildFinalSystem(
+  config: Config,
+  structured = false,
+  hasLowPriority = false,
+): string {
   const rules: string[] = [
     "You are an expert at writing clear, high-quality git commit messages.",
     "You are given a summary of staged changes and must produce a commit message for them.",
@@ -132,10 +198,15 @@ export function buildFinalSystem(config: Config, structured = false): string {
     );
   }
 
+  if (hasLowPriority) rules.push(...lowPriorityWeightingRules(config));
+
   if (config.multiline) {
     rules.push(
       "After the subject line, add one blank line and then a body that explains what changed and why. " +
-        'Use concise bullet points ("- ...") when there are several distinct changes. Wrap body lines at about 72 characters.',
+        'Use concise bullet points ("- ...") when there are several distinct changes. Wrap body lines at about 72 characters.' +
+        (hasLowPriority
+          ? " Cover the primary changes first and in full, then reference the low-priority changes briefly after them."
+          : ""),
     );
   } else {
     rules.push("Output only the single subject line. Do not include a body.");
@@ -163,51 +234,101 @@ export function buildFinalSystem(config: Config, structured = false): string {
  * manufacture variety, so `multiline` appeared to be ignored in interactive
  * mode even though the system prompt still required a body.
  */
-function multiOptionInstruction(count: number): string {
+function multiOptionInstruction(count: number, hasLowPriority = false): string {
+  // With two priority groups, "different in emphasis" would license one
+  // option to lead with the churn - and this is the last instruction the
+  // model reads - so the variety axis is scoped to the primary changes and
+  // the subject rule is re-anchored. With one group the wording is untouched.
+  const variety = hasLowPriority
+    ? "Make the options genuinely different in wording and in which aspect of the primary changes they emphasise, " +
+      "but never drop the subject or a required body just to create variety. " +
+      "Each option's subject line describes the primary changes."
+    : "Make the options genuinely different in wording and emphasis, but never drop the subject or a required body just to create variety.";
   return (
     `Produce exactly ${count} distinct commit-message options for this change. ` +
     `Each option must be a complete commit message that independently obeys all the formatting rules above - ` +
     `including the blank line and body when those rules ask for one. ` +
-    `Make the options genuinely different in wording and emphasis, but never drop the subject or a required body just to create variety.`
+    variety
+  );
+}
+
+/** Join a group of summaries, numbering them as parts when there are several. */
+function joinSummaryTexts(texts: string[]): string {
+  return texts.length === 1
+    ? texts[0]!
+    : texts.map((text, index) => `Part ${index + 1}:\n${text}`).join("\n\n");
+}
+
+/** Whether the summaries span both priority groups (the only case that needs the weighting rules). */
+export function hasLowPrioritySummaries(summaries: DiffSummary[]): boolean {
+  return (
+    summaries.some((summary) => summary.priority === "low") &&
+    summaries.some((summary) => summary.priority === "primary")
   );
 }
 
+/**
+ * Present the summaries to the final model. With a single priority group the
+ * layout is the plain one; with both groups present they are labelled,
+ * primary first, and closed with a one-line anchor back to the primary
+ * changes. The weighting rules themselves live in the system prompt
+ * ({@link buildFinalSystem}); the user turn only carries the data.
+ */
+function describeSummaries(summaries: DiffSummary[]): string {
+  const primaryTexts = summaries
+    .filter((summary) => summary.priority === "primary")
+    .map((summary) => summary.text);
+  const lowTexts = summaries
+    .filter((summary) => summary.priority === "low")
+    .map((summary) => summary.text);
+
+  if (!hasLowPrioritySummaries(summaries)) {
+    const texts = primaryTexts.length > 0 ? primaryTexts : lowTexts;
+    const header =
+      texts.length === 1
+        ? "Here is the summary of the staged changes:"
+        : "Here are summaries of the parts of the staged changes:";
+    return `${header}\n\n${joinSummaryTexts(texts)}`;
+  }
+
+  return [
+    "Here are summaries of the staged changes, in two groups.",
+    `Primary changes (what this commit is about):\n\n${joinSummaryTexts(primaryTexts)}`,
+    `Low-priority changes (${LOW_PRIORITY_DESCRIPTION}):\n\n${joinSummaryTexts(lowTexts)}`,
+    "The subject line is about the primary changes above.",
+  ].join("\n\n");
+}
+
 /**
  * User prompt for the final stage.
  *
+ * Summaries are presented by priority group (see {@link describeSummaries}).
  * In `structured` mode the candidates are returned via {@link MESSAGES_SCHEMA}'s
  * `messages` array. Otherwise, when `count` > 1, they are separated by
  * {@link OPTION_DELIMITER} for text parsing.
  */
 export function buildFinalUser(
-  summaries: string[],
+  summaries: DiffSummary[],
   count = 1,
   structured = false,
 ): string {
-  const joined =
-    summaries.length === 1
-      ? summaries[0]!
-      : summaries.map((s, i) => `Part ${i + 1}:\n${s}`).join("\n\n");
-
-  const header =
-    summaries.length === 1
-      ? "Here is the summary of the staged changes:"
-      : "Here are summaries of the parts of the staged changes:";
+  const described = describeSummaries(summaries);
+  const hasLowPriority = hasLowPrioritySummaries(summaries);
 
   if (structured) {
     const ask =
       count <= 1
         ? `Produce a single commit message for this change and return it as the only element of the "messages" array.`
-        : `${multiOptionInstruction(count)} Return them in the "messages" array.`;
-    return `${header}\n\n${joined}\n\n${ask}`;
+        : `${multiOptionInstruction(count, hasLowPriority)} Return them in the "messages" array.`;
+    return `${described}\n\n${ask}`;
   }
 
   if (count <= 1) {
-    return `${header}\n\n${joined}`;
+    return described;
   }
 
   return (
-    `${header}\n\n${joined}\n\n${multiOptionInstruction(count)} ` +
+    `${described}\n\n${multiOptionInstruction(count, hasLowPriority)} ` +
     `Output each option on its own, preceded by a line containing exactly "${OPTION_DELIMITER}" and nothing else. ` +
     `Do not number the options or add any other text.`
   );

package/src/tokens.ts

@@ -7,6 +7,7 @@
  * latency for no real benefit. We slightly over-estimate tokens so that chunks
  * stay safely under the model's context window.
  */
+import { DEFAULT_OLLAMA_CONTEXT_TOKENS, isOllamaModel } from "./models";
 
 /** Estimate the number of tokens in `text` given a chars-per-token ratio. */
 export function estimateTokens(text: string, charsPerToken: number): number {
@@ -33,31 +34,68 @@ export function tokensToChars(tokens: number, charsPerToken: number): number {
 const MILLION_TOKEN_CONTEXT_MODELS =
   /\[1m\]|^(claude-)?(sonnet|opus)$|sonnet-5|sonnet-4-6|opus-4-[678]|fable|mythos/i;
 
-/** The context window (input token capacity) for a model name or alias. */
-export function contextWindowTokens(model: string): number {
+/**
+ * The context window (input token capacity) for a model name or alias.
+ *
+ * For an `ollama:` model the window is not a property of the name at all -
+ * it is whatever `options.num_ctx` the request asks for, which cco pins to
+ * `ollama.contextTokens` so that chunk sizing and the request agree. Pass
+ * that value as `ollamaContextTokens`; the default matches
+ * {@link DEFAULT_OLLAMA_CONTEXT_TOKENS}.
+ */
+export function contextWindowTokens(
+  model: string,
+  ollamaContextTokens: number = DEFAULT_OLLAMA_CONTEXT_TOKENS,
+): number {
+  if (isOllamaModel(model)) return Math.max(1, Math.floor(ollamaContextTokens));
   return MILLION_TOKEN_CONTEXT_MODELS.test(model) ? 1_000_000 : 200_000;
 }
 
 /**
- * Tokens reserved out of the context window before sizing diff chunks: the
- * system prompt, the Agent SDK's scaffolding, and room for the response.
- * Generous on purpose - `charsPerToken` is an estimate, and a chunk that
- * overflows the window fails the whole run.
+ * Ceiling on the tokens reserved out of the context window before sizing
+ * diff chunks: the system prompt, the backend's scaffolding, and room for
+ * the response. Generous on purpose - `charsPerToken` is an estimate, and a
+ * chunk that overflows the window fails the whole run.
  */
 export const CONTEXT_RESERVE_TOKENS = 32_000;
 
+/**
+ * The fraction of a context window the reserve may take when the flat
+ * {@link CONTEXT_RESERVE_TOKENS} would swallow it. A local model running at
+ * 32k has a window smaller than the flat reserve, which would leave a
+ * budget of zero and shatter the diff into one chunk per line.
+ */
+const MAX_RESERVE_FRACTION = 4;
+
+/**
+ * Tokens to hold back from `contextWindow` when sizing chunks: the flat
+ * reserve, or a quarter of the window when that is smaller. Both Claude
+ * tiers (200k and 1M) are far above the crossover, so they reserve the full
+ * 32k exactly as before; only windows under 128k - which in practice means
+ * Ollama - scale down.
+ */
+export function contextReserveTokens(contextWindow: number): number {
+  return Math.min(
+    CONTEXT_RESERVE_TOKENS,
+    Math.floor(contextWindow / MAX_RESERVE_FRACTION),
+  );
+}
+
 /**
  * Clamp a configured per-chunk token budget so that one chunk plus overhead
  * always fits the given model's context window. The configured
  * `maxChunkTokens` remains the user-facing cap; this only ever lowers it.
+ * `ollamaContextTokens` supplies the window for an `ollama:` model.
  */
 export function clampChunkTokens(
   model: string,
   maxChunkTokens: number,
+  ollamaContextTokens?: number,
 ): number {
-  return Math.min(
-    maxChunkTokens,
-    contextWindowTokens(model) - CONTEXT_RESERVE_TOKENS,
+  const window = contextWindowTokens(model, ollamaContextTokens);
+  return Math.max(
+    1,
+    Math.min(maxChunkTokens, window - contextReserveTokens(window)),
   );
 }
 

package/src/types.ts

@@ -2,7 +2,16 @@
  * Shared types for claude-commit.
  */
 
-/** Which models to use for each stage of the pipeline. */
+/**
+ * Which models to use for each stage of the pipeline.
+ *
+ * A bare name (`sonnet`, `haiku`, a full `claude-*` id) runs through the
+ * Claude Agent SDK. An `ollama:`-prefixed name runs against a local or
+ * self-hosted Ollama server instead, with everything after the prefix taken
+ * as the Ollama model name verbatim - tag included, so
+ * `ollama:ornith-1.5:35b` means the model `ornith-1.5:35b`. The two stages
+ * are resolved independently, so mixing providers is normal.
+ */
 export interface ModelConfig {
   /** Model used to read diffs and write summaries. Defaults to `sonnet`. */
   summary: string;
@@ -10,6 +19,44 @@ export interface ModelConfig {
   final: string;
 }
 
+/** Settings for the Ollama backend, used only by `ollama:`-prefixed models. */
+export interface OllamaConfig {
+  /**
+   * Base URL of the Ollama server. Defaults to `$OLLAMA_HOST`, falling back
+   * to `http://localhost:11434`. A bare `host:port` (Ollama's own
+   * convention for that variable) is given an `http://` scheme.
+   */
+  host: string;
+  /**
+   * Context window requested for every Ollama call (`options.num_ctx`) and
+   * used to size diff chunks: a token count, or `"auto"` (the default) to
+   * take the window Ollama itself chooses for the model on this machine.
+   *
+   * The window is always sent explicitly, never left to the server: a
+   * prompt over it is truncated *silently* - HTTP 200, oldest content
+   * dropped, no flag on the response - and a summary written from half a
+   * diff is worse than an error, so cco pins the number it sized its chunks
+   * against and cross-checks the response's token counts.
+   *
+   * `"auto"` asks Ollama rather than guessing: the model is preloaded with
+   * no `num_ctx`, which makes the server pick from its VRAM tiers (4k / 32k
+   * / 256k, capped at the model's trained maximum), and the choice is read
+   * back from `/api/ps`. That is the largest window the server believes
+   * this machine can run, resolved once per model per run. A number pins
+   * the window instead - lower it when memory is tight (memory scales with
+   * it, multiplied by `OLLAMA_NUM_PARALLEL`), or raise it past the tier if
+   * you know better than the server does.
+   */
+  context: number | "auto";
+  /**
+   * How long the server keeps the model loaded after a request: a duration
+   * string (`"10m"`), seconds as a number, `0` to unload immediately, or a
+   * negative value to pin it. `null` leaves the server's own default (which
+   * is itself 5 minutes unless `OLLAMA_KEEP_ALIVE` says otherwise).
+   */
+  keepAlive: string | number | null;
+}
+
 /** Fully-resolved configuration after merging defaults, file config and CLI flags. */
 export interface Config {
   /** Format the subject line as a Conventional Commit (`type(scope): description`). */
@@ -42,7 +89,7 @@ export interface Config {
   interactiveTemperature: number | null;
   /**
    * Name of the progress spinner animation: any spinner from the cli-spinners
-   * set bundled with ora (e.g. `"dots"`, `"moon"`, `"bouncingBall"`). Unknown
+   * set bundled with ora (e.g. `"dots"`, `"moon"`, `"material"`). Unknown
    * names are ignored and the default is used instead.
    */
   spinner: string;
@@ -64,6 +111,35 @@ export interface Config {
    * losing anything a summary could actually use.
    */
   skipArmored: boolean;
+  /**
+   * Gitignore-style patterns for paths whose changes matter less than the
+   * rest of the commit: generated docs, lockfiles, vendored snapshots, build
+   * output. Diff sections under these paths are summarised separately and
+   * briefly, and the final model is told to describe the other changes in
+   * the subject line and to mention these only after them. When every
+   * changed file matches, the changes are described normally - there is
+   * nothing else for them to yield to. A pattern containing `/` matches a
+   * path or any ancestor directory; a bare pattern matches any path segment
+   * (see `src/paths.ts`).
+   */
+  lowPriorityPaths: string[];
+  /**
+   * Gitignore-style patterns - the same language as `lowPriorityPaths` - for
+   * paths whose changes should not be read at all: vendored dependency
+   * trees, generated clients, bulk data fixtures. Matching diff sections are
+   * dropped before anything else looks at the diff, so they cost no tokens
+   * and cannot influence the message.
+   *
+   * The files are still committed; this governs only what the model reads.
+   * When every changed file matches, there is nothing left to describe and
+   * the run stops with an error naming the directive - unlike
+   * `lowPriorityPaths`, which promotes its partition in that case, because
+   * "this matters less" can degrade gracefully and "do not look at this"
+   * cannot.
+   */
+  ignore: string[];
+  /** Settings for the Ollama backend (`ollama:`-prefixed models). */
+  ollama: OllamaConfig;
   /**
    * Allow API credentials from the environment (`ANTHROPIC_API_KEY` /
    * `ANTHROPIC_AUTH_TOKEN`) to be used, billing pay-as-you-go instead of the
@@ -76,9 +152,27 @@ export interface Config {
 
 /** Partial config as it may appear in a config file or be produced by flags. */
 export type PartialConfig = {
-  [K in keyof Config]?: K extends "models" ? Partial<ModelConfig> : Config[K];
+  [K in keyof Config]?: K extends "models"
+    ? Partial<ModelConfig>
+    : K extends "ollama"
+      ? Partial<OllamaConfig>
+      : Config[K];
 };
 
+/**
+ * How much weight a slice of the diff carries in the commit message.
+ * `primary` changes define the commit; `low` changes - those under the
+ * configured `lowPriorityPaths` - are summarised briefly and mentioned only
+ * after the primary ones.
+ */
+export type ChangePriority = "primary" | "low";
+
+/** The summary of one diff chunk, tagged with the priority of the partition it came from. */
+export interface DiffSummary {
+  priority: ChangePriority;
+  text: string;
+}
+
 /** Result of a single model invocation. */
 export interface ModelResult {
   /** The text the model produced. */
@@ -98,3 +192,47 @@ export interface FileChange {
   /** Path of the file (the destination path for renames). */
   path: string;
 }
+
+/**
+ * One prompt to one model, whichever provider serves it.
+ *
+ * `model` carries the provider: bare names go to Claude, `ollama:`-prefixed
+ * ones to Ollama (see {@link ModelConfig}). Some options only apply to one
+ * provider - `allowApiKey` gates Claude credentials, `ollama` supplies the
+ * host and context window - and each is simply ignored by the other.
+ */
+export interface RunPromptOptions {
+  /** Model string: an alias (`sonnet`), a full id, or `ollama:<name>[:<tag>]`. */
+  model: string;
+  /** Full custom system prompt. */
+  system: string;
+  /** Receives assistant text as it streams in (enables partial messages). */
+  onText?: (delta: string) => void;
+  /** Abort the in-flight request. */
+  abortController?: AbortController;
+  /** Receives the underlying CLI's stderr (for `--verbose`). Claude only. */
+  onStderr?: (data: string) => void;
+  /**
+   * Sampling temperature. Used to add variety when generating several
+   * interactive options. Models that don't accept a temperature override
+   * will reject the request, so the caller should be prepared to retry
+   * without it.
+   */
+  temperature?: number;
+  /**
+   * Request a structured JSON response matching this schema. The parsed object
+   * is returned on {@link ModelResult.structured}. Models that don't support
+   * structured outputs will reject the request or return unparseable content,
+   * so the caller should be prepared to retry without it.
+   */
+  outputFormat?: { type: "json_schema"; schema: Record<string, unknown> };
+  /**
+   * Allow API credentials from the environment to reach the Claude Agent SDK
+   * subprocess. Defaults to false: `ANTHROPIC_API_KEY` /
+   * `ANTHROPIC_AUTH_TOKEN` are stripped so the run is billed to the Claude
+   * subscription. Has no meaning for Ollama, which takes no credential.
+   */
+  allowApiKey?: boolean;
+  /** Ollama host and context settings; required for an `ollama:` model. */
+  ollama?: OllamaConfig;
+}

package/src/ui/spinner.ts

@@ -16,7 +16,7 @@ import spinners, { type Spinner as SpinnerAnimation } from "cli-spinners";
 import { color } from "./colors";
 
 /** The spinner used when none (or an unknown one) is configured. */
-export const DEFAULT_SPINNER = "bouncingBall";
+export const DEFAULT_SPINNER = "material";
 
 /** Whether `name` is one of the cli-spinners animations bundled with ora. */
 export function isSpinnerName(name: string): boolean {