@brainervirus/workit-core 0.11.0 → 1.0.0

package/src/core/boundary.ts

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import type { JsonValue } from "./logger";
 
 // Named diagnostic boundary events (DG-04) shared by all adapters so event
@@ -25,3 +26,31 @@ export const errorDetail = (err: unknown): Record<string, JsonValue> => {
   }
   return { error_name: "unknown", error: String(err) };
 };
+
+export type SourceMarker = { loadedAt: number; files: string[] };
+
+/**
+ * Long-lived adapters (OpenCode plugin, MCP servers) load core once per
+ * process. A marker plus changedSourcesSinceLoad lets them warn once when the
+ * checkout sources move underneath the live process, instead of running stale
+ * behavior silently. Warning-only: it never blocks a call.
+ */
+export const markSourcesLoaded = (
+  files: string[],
+  loadedAt: number = Date.now(),
+): SourceMarker => ({
+  loadedAt,
+  files: [...files],
+});
+
+export const changedSourcesSinceLoad = (marker: SourceMarker): string[] => {
+  const changed: string[] = [];
+  for (const file of marker.files) {
+    try {
+      if (statSync(file).mtimeMs > marker.loadedAt) changed.push(file);
+    } catch {
+      // A missing source tells nothing; ignore it.
+    }
+  }
+  return changed;
+};

package/src/core/branch.ts

@@ -1,21 +1,8 @@
-import {
-  copyFileSync,
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { tmpdir } from "node:os";
 import path from "node:path";
 import { gitContext } from "./git";
-import { readConfig, resolveBranchPolicy } from "./config";
+import { readConfig, resolveBranchPolicy, resolveCommitPolicy } from "./config";
 import { resolveWorkspace } from "./workspaces";
 import { vcsConfig } from "./vcs-config";
 
@@ -23,6 +10,10 @@ import { vcsConfig } from "./vcs-config";
 export const resolveBranchPolicyFor = (workspaceRoot: string) =>
   resolveBranchPolicy(readConfig(), resolveWorkspace(workspaceRoot));
 
+/** Commit-flavor equivalent: workspace commitPolicy override, else global. */
+export const resolveCommitPolicyFor = (workspaceRoot: string) =>
+  resolveCommitPolicy(readConfig(), resolveWorkspace(workspaceRoot));
+
 const policy = (root: string) => resolveBranchPolicyFor(root);
 const allowedBranch = (root: string, name: string) =>
   policy(root).allowed.some((r) => r.test(name));
@@ -38,7 +29,6 @@ const USE_CURRENT_RE = /^\s*\*+Branch:\*+\s*use-current\s*$/im;
 // Windows portability: journal lines and stash-coverage sets carry
 // repo-relative paths, which must match git's POSIX separator output even
 // though path.join emits platform separators.
-const toPosix = (p: string) => p.split(path.sep).join("/");
 const readSafe = (p: string): string | null => {
   try {
     return readFileSync(p, "utf8");
@@ -278,114 +268,6 @@ export const ensureBaseBranch = (cwd: string, base: string): { ok: boolean; erro
   return fastForwardBase(cwd, base);
 };
 
-// CA-05: crash-orphaned guard roots are garbage-collected at snapshot time.
-// Fresh roots (any live invocation) and non-workit entries are never touched.
-export const purgeStaleFlowGuardRoots = (now: number): void => {
-  const cutoff = now - 24 * 3600_000;
-  let entries: string[];
-  try {
-    entries = readdirSync(tmpdir());
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (!entry.startsWith("workit-flow-guard-")) continue;
-    try {
-      if (statSync(path.join(tmpdir(), entry)).mtimeMs < cutoff)
-        rmSync(path.join(tmpdir(), entry), { recursive: true, force: true });
-    } catch {
-      /* raced removal or unreadable entry: skip */
-    }
-  }
-};
-
-// CA-04: flow-state snapshots live under the OS tempdir scoped by a hash of
-// the workspace path — never inside the repository or docs/. The pid+hrtime
-// suffix makes every invocation unique, so two concurrent setups never share
-// (and never clobber) a root; CA-05 GC reclaims anything a crash orphaned.
-export const snapshotFlowState = (cwd: string): string => {
-  purgeStaleFlowGuardRoots(Date.now());
-  const root = path.join(
-    tmpdir(),
-    `workit-flow-guard-${createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 16)}.${
-      process.pid
-    }.${process.hrtime.bigint()}`,
-  );
-  mkdirSync(root, { recursive: true });
-  const docsDir = path.join(path.resolve(cwd), "docs");
-  let slugs: string[] = [];
-  try {
-    slugs = readdirSync(docsDir);
-  } catch {
-    return root; // no docs/ yet — zero-file snapshot
-  }
-  for (const slug of slugs) {
-    // The approval gate digests docs/<slug>/spec.md and docs/<slug>/plan.md,
-    // so those bytes must survive the stash window too: a stash push -u takes
-    // untracked spec/plan away and any concurrent effective flow read would
-    // classify document_missing drift and persist an approval-chain wipe.
-    for (const rel of [["sdd", "flow.json"], ["spec.md"], ["plan.md"]]) {
-      const src = path.join(docsDir, slug, ...rel);
-      try {
-        if (!statSync(src).isFile()) continue;
-      } catch {
-        continue;
-      }
-      const dest = path.join(root, "docs", slug, ...rel);
-      mkdirSync(path.dirname(dest), { recursive: true });
-      cpSync(src, dest);
-    }
-  }
-  return root;
-};
-
-// CA-04: restore-if-missing keeps the newest working-tree bytes; the snapshot
-// root is removed only after every file is handled and retained on failure.
-// A caught failure must not vanish: the message is returned so callers can
-// surface it to operators as a warning. `restored` lists ONLY the files this
-// call actually wrote — present-at-restore files are skipped and excluded,
-// which is what makes the redundant-stash coverage check honest.
-export const restoreFlowSnapshot = (
-  snapDir: string,
-  cwd: string,
-): { restored: string[]; warning?: string } => {
-  const walk = (dir: string, rel: string): string[] =>
-    readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
-      entry.isDirectory()
-        ? walk(path.join(dir, entry.name), path.join(rel, entry.name))
-        : [path.join(rel, entry.name)],
-    );
-  const restored: string[] = [];
-  try {
-    const workspace = path.resolve(cwd);
-    for (const rel of walk(snapDir, "")) {
-      const dest = path.join(workspace, rel);
-      if (existsSync(dest)) continue;
-      mkdirSync(path.dirname(dest), { recursive: true });
-      // Atomic publish: a crash mid-copy must never leave a truncated flow.json
-      // at the destination.
-      const tmpDest = `${dest}.tmp-${process.pid}`;
-      try {
-        copyFileSync(path.join(snapDir, rel), tmpDest);
-        renameSync(tmpDest, dest);
-      } catch (error) {
-        rmSync(tmpDest, { force: true });
-        throw error;
-      }
-      restored.push(toPosix(rel));
-    }
-    rmSync(snapDir, { recursive: true, force: true });
-    return { restored };
-  } catch (error) {
-    return {
-      restored,
-      warning: `flow state snapshot restore failed: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    };
-  }
-};
-
 // Port of scripts/branch/setup-branch.sh
 export const branchSetup = ({
   action,
@@ -411,7 +293,11 @@ export const branchSetup = ({
   const manifestPath = path.isAbsolute(sdd)
     ? path.join(sdd, "manifest.json")
     : path.join(cwd, sdd, "manifest.json");
-  mkdirSync(path.dirname(manifestPath), { recursive: true, mode: 0o755 });
+  const ensureManifestDir = () => {
+    const dir = path.dirname(manifestPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o755 });
+  };
+  ensureManifestDir();
   const readManifest = (): Record<string, unknown> => {
     try {
       return JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -419,95 +305,29 @@ export const branchSetup = ({
       return {};
     }
   };
-  const writeManifest = (data: Record<string, unknown>) =>
+  const writeManifest = (data: Record<string, unknown>) => {
+    ensureManifestDir();
     writeFileSync(manifestPath, JSON.stringify(data, null, 2) + "\n", "utf8");
-
-  let snapDir: string | null = null;
-  // CA-01: flow-guard journal brackets the stash/checkout mutation window so a
-  // mid-window wipe is pinpointable between adjacent checkpoint lines. With no
-  // logger injected every call below is a no-op and nothing extra runs —
-  // behaviorally identical to the pre-journal code.
-  const journal = (message: string) => log?.(`flow-guard: ${message}`);
-  const snapshotRelPaths = (): string[] => {
-    const dir = snapDir;
-    // Not gated on log: the redundant-stash coverage check below needs this
-    // walk even without a logger (the walk is read-only over the tmpdir
-    // snapshot).
-    if (!dir) return [];
-    try {
-      const walk = (from: string, rel: string): string[] =>
-        readdirSync(from, { withFileTypes: true }).flatMap((entry) =>
-          entry.isDirectory()
-            ? walk(path.join(from, entry.name), path.join(rel, entry.name))
-            : [path.join(rel, entry.name)],
-        );
-      return walk(dir, "").map(toPosix);
-    } catch {
-      return [];
-    }
-  };
-  const journalSnapshot = () => {
-    const dir = snapDir;
-    if (!dir || !log) return;
-    const rels = snapshotRelPaths();
-    journal(`snapshot: ${rels.length} file(s)`);
-    for (const rel of rels) {
-      let shortHash = "";
-      try {
-        shortHash = createHash("sha256")
-          .update(readFileSync(path.join(dir, rel)))
-          .digest("hex")
-          .slice(0, 8);
-      } catch {}
-      journal(`snapshot: ${rel} sha=${shortHash}`);
-    }
-  };
-  const journalPresence = (phase: string) => {
-    for (const rel of snapshotRelPaths()) {
-      journal(`${phase}: ${rel} ${existsSync(path.join(cwd, rel)) ? "present" : "MISSING"}`);
-    }
-  };
-  const restoreWithWarning = (dir: string | null): { restored: string[]; warnings: string[] } => {
-    if (!dir) return { restored: [], warnings: [] };
-    const total = log ? snapshotRelPaths().length : 0;
-    const { restored, warning } = restoreFlowSnapshot(dir, cwd);
-    if (log)
-      journal(
-        `restore: restored=${restored.length} skipped=${total - restored.length}${warning ? ` warning: ${warning}` : ""}`,
-      );
-    else if (warning) journal(`restore warning: ${warning}`);
-    return { restored, warnings: warning ? [warning] : [] };
   };
 
+  const journal = (message: string) => log?.(`branch-setup: ${message}`);
+
   if (action === "reapply_stash") {
     const manifest = readManifest();
     const ref = manifest.stash_ref;
     if (!ref) return { error: "no stash_ref in manifest" };
-    // D-03: guard flow.json across the stash pop window.
-    snapDir = snapshotFlowState(cwd);
-    journalSnapshot();
     journal(`pre-pop: ${String(ref)}`);
     try {
       exec(["stash", "pop", String(ref)]);
     } catch (error) {
-      // CA-03: the snapshot ran before the pop — a failing pop must still
-      // restore a mid-window-wiped flow.json before returning.
       journal("pop: failed");
-      const {
-        warnings: [warning],
-      } = restoreWithWarning(snapDir);
-      return {
-        error: `${error instanceof Error ? error.message : "stash pop failed"}${
-          warning ? `; ${warning}` : ""
-        }`,
-      };
+      return { error: error instanceof Error ? error.message : "stash pop failed" };
     }
     journal("pop: ok");
     delete manifest.stash_ref;
     delete manifest.stash_created_at;
     writeManifest(manifest);
-    const { warnings } = restoreWithWarning(snapDir);
-    return { action: "reapply_stash", ok: true, ...(warnings.length > 0 ? { warnings } : {}) };
+    return { action: "reapply_stash", ok: true };
   }
 
   const target = target_branch ?? "";
@@ -549,14 +369,7 @@ export const branchSetup = ({
         suffix = " (changes preserved in stash)";
       }
     }
-    // CA-03: the snapshot ran before the stash push, so every error return
-    // here must still restore a mid-window-wiped flow.json and drop the
-    // guard root (a retained root is purged by the next run's 24h GC).
-    // Never masks the original error.
-    const {
-      warnings: [warning],
-    } = restoreWithWarning(snapDir);
-    return { error: `${message}${suffix}${warning ? `; ${warning}` : ""}` };
+    return { error: `${message}${suffix}` };
   };
   if (current !== target) {
     const dirty = Boolean(gitContext(cwd).status_short.trim());
@@ -578,11 +391,7 @@ export const branchSetup = ({
     }
     if (dirty) {
       try {
-        // CA-03: snapshot before the stash push so flow.json survives the
-        // stash/checkout window even if the pathspec exclusion misses.
-        snapDir = snapshotFlowState(cwd);
-        journalSnapshot();
-        exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`, "--", ":!docs/*/sdd"]);
+        exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`]);
       } catch (error) {
         return { error: error instanceof Error ? error.message : "stash push failed" };
       }
@@ -591,7 +400,7 @@ export const branchSetup = ({
     }
     try {
       exec(["checkout", target]);
-      journalPresence("post-checkout");
+      journal("post-checkout");
     } catch (error) {
       const message = error instanceof Error ? error.message : "checkout failed";
       if (/worktree/i.test(message)) {
@@ -614,7 +423,7 @@ export const branchSetup = ({
             : ensureBaseBranch(cwd, effectiveBase);
         if (!baseResult.ok) return failAfterStash(baseResult.error ?? "ensure-base-branch failed");
         exec(["checkout", "-b", target]);
-        journalPresence("post-create");
+        journal("post-create");
       } catch (createError) {
         return failAfterStash(
           createError instanceof Error ? createError.message : "branch create failed",
@@ -644,50 +453,13 @@ export const branchSetup = ({
     if (stash_ref === undefined && gitContext(cwd).branch !== current) {
       try {
         exec(["checkout", current]);
-      } catch {}
-    }
-    return result;
-  }
-  // Files the guard actually wrote back, straight from the restore itself.
-  const { restored: restoredRels, warnings } = restoreWithWarning(snapDir);
-  // Round-1 fallout: the guard restores untracked spec/plan right after
-  // checkout, but the stash pushed the same files — a later reapply_stash pop
-  // refuses ("untracked working tree files would be overwritten"), stranding
-  // a stash_ref on every successful setup. When every stashed path was just
-  // restored byte-identical from the pre-stash snapshot, the stash is
-  // redundant: drop it and clear the manifest ref. Coverage counts ONLY
-  // actually-restored paths: a tracked-and-modified file survives its stash
-  // (reverted to HEAD bytes, still present), so restore skips it — counting
-  // it as covered would drop the only copy of the user's edit. Any stashed
-  // path not restored keeps the ref so reapply_stash stays available.
-  // Best-effort: any failure keeps today's keep-the-ref behavior.
-  if (stash_ref && snapDir && warnings.length === 0) {
-    const covered = new Set(restoredRels.map(toPosix));
-    try {
-      const stashed = exec([
-        "stash",
-        "show",
-        "--include-untracked",
-        "--name-only",
-        String(stash_ref),
-      ])
-        .split("\n")
-        .map((line) => toPosix(line.trim()))
-        .filter(Boolean);
-      if (stashed.length > 0 && stashed.every((p) => covered.has(p))) {
-        exec(["stash", "drop", String(stash_ref)]);
-        stash_ref = undefined;
-        journal("dropped redundant stash (fully covered by snapshot restore)");
-        const manifest = readManifest();
-        delete manifest.stash_ref;
-        delete manifest.stash_created_at;
-        writeManifest(manifest);
-      } else {
-        journal(`kept stash ref ${stash_ref} (not fully covered by actual restores)`);
+      } catch {
+        try {
+          exec(["checkout", "-m", current]);
+        } catch {}
       }
-    } catch {
-      /* keep the stash ref — reapply_stash stays available */
     }
+    return result;
   }
   return {
     action: "setup",
@@ -696,6 +468,5 @@ export const branchSetup = ({
     previous_branch: current,
     stash_ref: stash_ref ?? null,
     manifest: manifestPath,
-    ...(warnings.length > 0 ? { warnings } : {}),
   };
 };

package/src/core/changelog.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { resolveWorkspaceRoot } from "./scripts";
 
 const CATEGORIES = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"];
@@ -23,6 +24,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 `;
 
+const digestBytes = (value: Buffer | string): string =>
+  createHash("sha256").update(value).digest("hex");
+
+type ChangelogSource = { exists: boolean; bytes: Buffer; text: string } | { error: string };
+
+const readChangelogSource = (target: string): ChangelogSource => {
+  if (!fs.existsSync(target)) {
+    const bytes = Buffer.from(SKELETON, "utf8");
+    return { exists: false, bytes, text: SKELETON };
+  }
+  try {
+    const bytes = fs.readFileSync(target);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return { exists: true, bytes, text };
+  } catch {
+    return { error: "changelog file must contain valid UTF-8" };
+  }
+};
+
 function normalizeBullet(text: string): string {
   text = text.trim();
   const m = BULLET_RE.exec(text);
@@ -184,13 +204,6 @@ function mergeSections(
   return [output, counts, added, null];
 }
 
-function ensureFile(target: string): string {
-  if (fs.existsSync(target)) return fs.readFileSync(target, "utf8");
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, SKELETON, "utf8");
-  return SKELETON;
-}
-
 function hasUnreleasedHeading(text: string): boolean {
   return text.split("\n").some((line) => UNRELEASED_RE.test(line.replace(/\n$/, "")));
 }
@@ -200,7 +213,21 @@ function applyChangelog(
   entries: Record<string, string[]>,
   normalizeOnly: boolean,
 ): Record<string, any> {
-  let text = ensureFile(target);
+  const source = readChangelogSource(target);
+  if ("error" in source) return { error: source.error };
+  const rendered = renderChangelog(source.text, entries, normalizeOnly);
+  if ("error" in rendered) return { error: rendered.error };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, rendered.text, "utf8");
+  return { ...rendered.result, path: target };
+}
+
+function renderChangelog(
+  source: string,
+  entries: Record<string, string[]>,
+  normalizeOnly: boolean,
+): { text: string; result: Record<string, any> } | { error: string } {
+  let text = source;
   if (!hasUnreleasedHeading(text)) {
     const lines = text.split(/(?<=\n)/);
     let insertAt = lines.length;
@@ -220,13 +247,65 @@ function applyChangelog(
   if (error) return { error };
   // before already includes "## [Unreleased]\n"
   const out = (before.endsWith("\n") ? before : before + "\n") + newBody + after;
-  fs.writeFileSync(target, out, "utf8");
+  return {
+    text: out,
+    result: { ok: true, normalize_only: normalizeOnly, added: addedCounts, categories: counts },
+  };
+}
+
+const changelogTarget = (
+  workspaceRoot: string,
+  changelogPath: string,
+): { cwd: string; target: string } | { error: string } => {
+  try {
+    const cwd = fs.realpathSync(resolveWorkspaceRoot(workspaceRoot));
+    const target = path.resolve(cwd, changelogPath || "CHANGELOG.md");
+    if (target !== cwd && !target.startsWith(cwd + path.sep))
+      return { error: "changelog path must be inside workspace_root" };
+    let ancestor = target;
+    while (!fs.existsSync(ancestor)) ancestor = path.dirname(ancestor);
+    const canonicalAncestor = fs.realpathSync(ancestor);
+    if (canonicalAncestor !== cwd && !canonicalAncestor.startsWith(cwd + path.sep))
+      return { error: "changelog path must be inside workspace_root" };
+    return { cwd, target: fs.existsSync(target) ? fs.realpathSync(target) : target };
+  } catch {
+    return { error: "changelog path must be inside workspace_root" };
+  }
+};
+
+export function changelogApplyPreview({
+  entries,
+  path: changelogPath,
+  normalize_only,
+  workspace_root,
+}: {
+  entries?: unknown;
+  path?: string;
+  normalize_only?: boolean;
+  workspace_root: string;
+}): Record<string, any> {
+  const normalized = normalize_only
+    ? { data: {} as Record<string, string[]> }
+    : normalizeEntries(entries);
+  if ("error" in normalized) return { error: normalized.error };
+  if (!normalize_only && Object.keys(normalized.data).length === 0)
+    return { error: "entries required unless normalize_only" };
+  const location = changelogTarget(workspace_root, changelogPath || "CHANGELOG.md");
+  if ("error" in location) return location;
+  const source = readChangelogSource(location.target);
+  if ("error" in source) return source;
+  const rendered = renderChangelog(source.text, normalized.data, Boolean(normalize_only));
+  if ("error" in rendered) return rendered;
   return {
     ok: true,
-    path: target,
-    normalize_only: normalizeOnly,
-    added: addedCounts,
-    categories: counts,
+    path: location.target,
+    entries: normalized.data,
+    normalize_only: Boolean(normalize_only),
+    beforeDigest: digestBytes(source.bytes),
+    beforeExists: source.exists,
+    afterDigest: digestBytes(Buffer.from(rendered.text, "utf8")),
+    after: rendered.text,
+    ...rendered.result,
   };
 }
 
@@ -280,11 +359,9 @@ export function changelogApply({
   }
 
   const rel = changelogPath || "CHANGELOG.md";
-  const target = path.resolve(cwd, rel);
-  const root = path.resolve(cwd);
-  if (target !== root && !target.startsWith(root + path.sep)) {
-    return { error: "changelog path must be inside workspace_root" };
-  }
+  const location = changelogTarget(cwd, rel);
+  if ("error" in location) return location;
+  const target = location.target;
 
   try {
     return applyChangelog(target, normalized.data, Boolean(normalize_only));

package/src/core/commit-flavors.ts

@@ -0,0 +1,65 @@
+// Commit message flavors: matchers plus history detection for the git.commit
+// gate. Detection is deterministic (majority vote, no LLM): sample recent
+// subjects, classify each, take the majority above threshold, else null so the
+// caller falls back to the configured preset.
+
+export type CommitFlavor = "conventional" | "gitmoji" | "ticket-prefix" | "freeform";
+export type CommitFlavorPreset = CommitFlavor | "custom" | "auto";
+
+const CONVENTIONAL_RE =
+  /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?(!)?: .+/;
+const TICKET_RE = /^[A-Z]{2,}-\d+\b/;
+const GITMOJI_RE = /^\p{Extended_Pictographic}/u;
+
+export const matchCommitFlavor = (
+  message: string,
+  flavor: CommitFlavorPreset,
+  pattern?: string,
+): boolean => {
+  const subject = message.split("\n", 1)[0] ?? "";
+  switch (flavor) {
+    case "conventional":
+      return CONVENTIONAL_RE.test(subject);
+    case "gitmoji":
+      return GITMOJI_RE.test(subject);
+    case "ticket-prefix":
+      return TICKET_RE.test(subject);
+    case "freeform":
+      return subject.trim().length > 0;
+    case "custom":
+      if (!pattern) return false;
+      try {
+        return new RegExp(pattern).test(subject);
+      } catch {
+        return false;
+      }
+    case "auto":
+      return subject.trim().length > 0;
+  }
+};
+
+const DETECTABLE: CommitFlavor[] = ["conventional", "gitmoji", "ticket-prefix"];
+
+export const detectCommitFlavor = (
+  subjects: string[],
+  threshold = 0.7,
+): { flavor: CommitFlavor | null; confidence: number } => {
+  if (subjects.length === 0) return { flavor: null, confidence: 0 };
+  const votes = new Map<CommitFlavor, number>();
+  for (const subject of subjects) {
+    const hit = DETECTABLE.find((flavor) => matchCommitFlavor(subject, flavor));
+    if (hit) votes.set(hit, (votes.get(hit) ?? 0) + 1);
+  }
+  let best: CommitFlavor | null = null;
+  let count = 0;
+  for (const [flavor, votesFor] of votes) {
+    if (votesFor > count) {
+      best = flavor;
+      count = votesFor;
+    }
+  }
+  const confidence = count / subjects.length;
+  return best !== null && confidence >= threshold
+    ? { flavor: best, confidence }
+    : { flavor: null, confidence };
+};