Architecture

gitscribe is a pipeline: read commits, classify them, group them, then render — either deterministically or via a local LLM. Grouping happens before the LLM, so the model rewrites a clean list instead of raw commits.

flowchart LR
  G["git log"] --> PA["parseGitLog"]
  PA --> CL["parseConventional<br/>(type · scope · breaking)"]
  CL --> GR["groupCommits"]
  GR --> DEC{"--model?"}
  DEC -- no --> TPL["renderMarkdown<br/>(template)"]
  DEC -- yes --> LLM["Ollama<br/>(buildPrompt → generate)"]
  TPL --> OUT["release notes"]
  LLM --> OUT

Module map

Module	Responsibility
git.ts	Read commits via a delimited git log; parseGitLog (pure)
conventional.ts	Parse Conventional Commits and group by type
render.ts	Deterministic markdown changelog (offline)
llm.ts	buildPrompt (pure) + OllamaClient
generate.ts	Choose template vs LLM

Design principles

• Offline by default — template mode is deterministic and dependency-free (ideal for CI).
• LLM as polish, not source — the model sees categorized commits, so it can't invent features.
• Testable core — parsing, grouping and rendering are pure; git/Ollama are thin adapters.