@hraness/kb 0.17.1

package/dist/index-1gwbassd.js

@@ -0,0 +1,743 @@
+// @bun
+// src/git.ts
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import { realpath, stat } from "fs/promises";
+import { isAbsolute, relative, resolve, sep } from "path";
+var MAX_GIT_HISTORY_COMMITS = 1000;
+var MAX_GIT_HISTORY_NOTES = 1e4;
+var MAX_GIT_HISTORY_OUTPUT_BYTES = 32 * 1024 * 1024;
+var MAX_GIT_HISTORY_TIMEOUT_MS = 30000;
+var MAX_GIT_PATHS_PER_COMMIT = 2000;
+var MAX_GIT_PATH_OBSERVATIONS = 1e5;
+var MAX_GIT_NOTE_ID_UTF8_BYTES = 16 * 1024;
+var MAX_GIT_NOTE_IDS_UTF8_BYTES = 16 * 1024 * 1024;
+var DEFAULT_COMMITS = 200;
+var DEFAULT_OUTPUT_BYTES = 8 * 1024 * 1024;
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_COMMITS_PER_NOTE = 5;
+var DEFAULT_COCHANGED_PATHS = 20;
+var DEFAULT_SEARCH_LIMIT = 20;
+var MAX_COMMITS_PER_NOTE = 50;
+var MAX_COCHANGED_PATHS = 100;
+var MAX_SEARCH_LIMIT = 100;
+var MAX_QUERY_LENGTH = 500;
+var commitMarker = "KB-GIT-HISTORY-V1";
+var objectIdPattern = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u;
+
+class GitHistoryError extends Error {
+  kind;
+  constructor(kind, message, options) {
+    super(message, options);
+    this.name = "GitHistoryError";
+    this.kind = kind;
+  }
+}
+var runGitCommand = (request) => new Promise((resolveResult) => {
+  let settled = false;
+  const bytes = { stdout: [], stderr: [], total: 0, exceeded: false };
+  let child;
+  try {
+    child = spawn("git", [...request.arguments], {
+      cwd: request.cwd,
+      env: {
+        ...process.env,
+        GIT_OPTIONAL_LOCKS: "0",
+        GIT_PAGER: "cat",
+        GIT_TERMINAL_PROMPT: "0",
+        LC_ALL: "C"
+      },
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    const code = errorCode(error);
+    resolveResult(code === "ENOENT" ? { status: "unavailable", message: "Git is not installed or is not on PATH." } : { status: "failed", message: errorMessage(error), reason: "exit" });
+    return;
+  }
+  const finish = (result) => {
+    if (settled)
+      return;
+    settled = true;
+    clearTimeout(timer);
+    resolveResult(result);
+  };
+  const append = (target, chunk) => {
+    if (settled || bytes.exceeded)
+      return;
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes.total += buffer.byteLength;
+    if (bytes.total > request.maxOutputBytes) {
+      bytes.exceeded = true;
+      child.kill("SIGKILL");
+      return;
+    }
+    bytes[target].push(buffer);
+  };
+  child.stdout.on("data", (chunk) => append("stdout", chunk));
+  child.stderr.on("data", (chunk) => append("stderr", chunk));
+  child.once("error", (error) => {
+    finish(error.code === "ENOENT" ? { status: "unavailable", message: "Git is not installed or is not on PATH." } : { status: "failed", message: error.message, reason: "exit" });
+  });
+  child.once("close", (exitCode) => {
+    const stdout = Buffer.concat(bytes.stdout);
+    const stderr = Buffer.concat(bytes.stderr);
+    if (bytes.exceeded) {
+      finish({
+        status: "failed",
+        message: `Git output exceeded ${request.maxOutputBytes} bytes.`,
+        reason: "output-limit",
+        stderr
+      });
+    } else if (exitCode === 0) {
+      finish({ status: "ok", stdout, stderr });
+    } else {
+      const failed = {
+        status: "failed",
+        message: `Git exited with code ${exitCode ?? "unknown"}.`,
+        reason: "exit",
+        stderr,
+        ...exitCode === null ? {} : { exitCode }
+      };
+      finish(failed);
+    }
+  });
+  const timer = setTimeout(() => {
+    child.kill("SIGKILL");
+    finish({
+      status: "failed",
+      message: `Git exceeded the ${request.timeoutMs}ms timeout.`,
+      reason: "timeout"
+    });
+  }, request.timeoutMs);
+});
+function errorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function checkedInteger(value, fallback, minimum, maximum, label) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < minimum || selected > maximum) {
+    throw new GitHistoryError("budget", `${label} must be an integer from ${minimum} through ${maximum}.`);
+  }
+  return selected;
+}
+function inside(parent, candidate) {
+  const path = relative(parent, candidate);
+  return path === "" || !path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path);
+}
+function posixRelative(parent, candidate) {
+  return relative(parent, candidate).split(sep).join("/");
+}
+function hasControlCharacter(value, allowTab) {
+  return [...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code < 32 && !(allowTab && code === 9) || code === 127;
+  });
+}
+function checkedRepositoryPath(value, label) {
+  if (value === "" || hasControlCharacter(value, false) || value.includes("\\")) {
+    throw new GitHistoryError("malformed", `${label} is not a safe repository-relative path.`);
+  }
+  if (value.startsWith("/") || value.endsWith("/") || value.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new GitHistoryError("malformed", `${label} is not a normalized repository-relative path.`);
+  }
+  return value;
+}
+function checkedNoteIdentity(note) {
+  const path = checkedRepositoryPath(note.path, `Note path ${JSON.stringify(note.path)}`);
+  const id = checkedRepositoryPath(note.id, `Note ID ${JSON.stringify(note.id)}`);
+  if (!path.endsWith(".md") || path.slice(0, -3) !== id) {
+    throw new GitHistoryError("malformed", `Note ${JSON.stringify(note.id)} must use its extensionless Markdown path as its ID.`);
+  }
+}
+function decodeOutput(value, label) {
+  if (value === undefined)
+    return "";
+  try {
+    return typeof value === "string" ? value : new TextDecoder("utf-8", { fatal: true }).decode(value);
+  } catch (error) {
+    throw new GitHistoryError("malformed", `${label} was not valid UTF-8.`, { cause: error });
+  }
+}
+async function checkedCommand(provider, cwd, arguments_, budget, required, label) {
+  const timeoutMs = budget.timeoutMs - (Date.now() - budget.startedAt);
+  const maxOutputBytes = budget.outputLimit - budget.outputBytes;
+  if (timeoutMs <= 0)
+    throw new GitHistoryError("budget", "Git history indexing exceeded its timeout.");
+  if (maxOutputBytes <= 0) {
+    throw new GitHistoryError("budget", "Git history indexing exceeded its output budget.");
+  }
+  let result;
+  try {
+    result = await provider({ cwd, arguments: arguments_, timeoutMs, maxOutputBytes });
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      result = { status: "unavailable", message: "Git is not installed or is not on PATH." };
+    } else {
+      throw new GitHistoryError("failed", `${label} failed: ${errorMessage(error)}`, { cause: error });
+    }
+  }
+  if (result.status === "unavailable") {
+    if (required)
+      throw new GitHistoryError("unavailable", result.message);
+    return {
+      status: "unavailable",
+      repository: cwd,
+      root: cwd,
+      vaultPrefix: "",
+      reason: result.message
+    };
+  }
+  if (result.status === "failed") {
+    const stderr = decodeOutput(result.stderr, "Git stderr").trim();
+    const detail = stderr === "" ? result.message : `${result.message} ${stderr}`;
+    throw new GitHistoryError(result.reason === "timeout" || result.reason === "output-limit" ? "budget" : "failed", `${label} failed: ${detail}`);
+  }
+  const stdoutBytes = typeof result.stdout === "string" ? Buffer.byteLength(result.stdout) : result.stdout.byteLength;
+  const stderrBytes = typeof result.stderr === "string" ? Buffer.byteLength(result.stderr) : result.stderr?.byteLength ?? 0;
+  budget.outputBytes += stdoutBytes + stderrBytes;
+  if (budget.outputBytes > budget.outputLimit) {
+    throw new GitHistoryError("budget", "Git history indexing exceeded its output budget.");
+  }
+  return { status: "ok", stdout: decodeOutput(result.stdout, label) };
+}
+function singleLine(value, label) {
+  const normalized = value.replace(/\r?\n$/u, "");
+  if (normalized === "" || /[\r\n\0]/u.test(normalized)) {
+    throw new GitHistoryError("malformed", `${label} was not one non-empty line.`);
+  }
+  return normalized;
+}
+function commitTime(timestamp) {
+  if (!/^(?:0|[1-9]\d*)$/u.test(timestamp)) {
+    throw new GitHistoryError("malformed", "Git returned a malformed commit timestamp.");
+  }
+  const value = Number(timestamp);
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new GitHistoryError("malformed", "Git returned an out-of-range commit timestamp.");
+  }
+  return value;
+}
+function normalizedSubject(value) {
+  if (value.includes("\uFFFD") || hasControlCharacter(value, true)) {
+    throw new GitHistoryError("malformed", "Git returned a malformed commit subject.");
+  }
+  return [...value.normalize("NFC").trim()].slice(0, 1000).join("");
+}
+function parseGitHistoryRecords(output, expectedMarker, changedPathPolicy, pathBudget) {
+  if (output === "")
+    return Object.freeze([]);
+  if (expectedMarker === "" || expectedMarker.includes("\x00")) {
+    throw new GitHistoryError("malformed", "Git history record marker is invalid.");
+  }
+  if (output.includes("\uFFFD")) {
+    throw new GitHistoryError("malformed", "Git history output was not valid UTF-8.");
+  }
+  const tokens = output.split("\x00");
+  const records = [];
+  let index = 0;
+  while (index < tokens.length) {
+    let marker = tokens[index] ?? "";
+    marker = marker.replace(/^\r?\n/u, "");
+    if (marker === "") {
+      index += 1;
+      continue;
+    }
+    if (marker !== expectedMarker) {
+      throw new GitHistoryError("malformed", "Git history output contained an unexpected record marker.");
+    }
+    const hash = tokens[index + 1];
+    const timestamp = tokens[index + 2];
+    const subject = tokens[index + 3];
+    if (hash === undefined || timestamp === undefined || subject === undefined || !objectIdPattern.test(hash)) {
+      throw new GitHistoryError("malformed", "Git history output contained an incomplete commit record.");
+    }
+    index += 4;
+    const parsedTimestamp = commitTime(timestamp);
+    const parsedSubject = normalizedSubject(subject);
+    const changedPaths = [];
+    const seenPaths = new Set;
+    let firstPath = true;
+    let limited = false;
+    let observedPathRecords = 0;
+    while (index < tokens.length) {
+      const token = tokens[index] ?? "";
+      const possibleMarker = token.replace(/^\r?\n/u, "");
+      if (possibleMarker === expectedMarker)
+        break;
+      index += 1;
+      if (token === "" || token === `
+` || token === `\r
+`)
+        continue;
+      const rawPath = firstPath ? token.replace(/^\r?\n/u, "") : token;
+      if (rawPath === "")
+        continue;
+      firstPath = false;
+      const path = checkedRepositoryPath(rawPath, "Git changed path");
+      observedPathRecords += 1;
+      pathBudget.observed += 1;
+      if (pathBudget.observed > MAX_GIT_PATH_OBSERVATIONS) {
+        throw new GitHistoryError("budget", `Git history exceeded the ${MAX_GIT_PATH_OBSERVATIONS} changed-path observation limit.`);
+      }
+      if (changedPathPolicy.kind === "select") {
+        if (!changedPathPolicy.paths.has(path) || seenPaths.has(path))
+          continue;
+        seenPaths.add(path);
+        changedPaths.push(path);
+        if (changedPaths.length > MAX_GIT_HISTORY_NOTES) {
+          throw new GitHistoryError("budget", `Git history selected more than ${MAX_GIT_HISTORY_NOTES} live-note paths in one commit.`);
+        }
+        continue;
+      }
+      if (!limited && seenPaths.has(path))
+        continue;
+      if (limited)
+        continue;
+      seenPaths.add(path);
+      changedPaths.push(path);
+      if (changedPaths.length > MAX_GIT_PATHS_PER_COMMIT) {
+        if (changedPathPolicy.kind === "reject") {
+          throw new GitHistoryError("budget", `A Git commit exceeded the ${MAX_GIT_PATHS_PER_COMMIT} changed-path limit.`);
+        }
+        limited = true;
+        changedPaths.length = 0;
+        seenPaths.clear();
+      }
+    }
+    records.push(limited ? {
+      status: "limited",
+      limit: Object.freeze({
+        hash,
+        timestamp: parsedTimestamp,
+        subject: parsedSubject,
+        reason: "changed-path-limit",
+        pathLimit: MAX_GIT_PATHS_PER_COMMIT,
+        observedPathRecords
+      })
+    } : {
+      status: "complete",
+      commit: Object.freeze({
+        hash,
+        timestamp: parsedTimestamp,
+        subject: parsedSubject,
+        changedPaths: Object.freeze(changedPaths)
+      })
+    });
+    if (records.length > MAX_GIT_HISTORY_COMMITS) {
+      throw new GitHistoryError("budget", `Git history exceeded the ${MAX_GIT_HISTORY_COMMITS} commit limit.`);
+    }
+  }
+  return Object.freeze(records);
+}
+function parseGitHistoryOutput(output, expectedMarker = commitMarker) {
+  return Object.freeze(parseGitHistoryRecords(output, expectedMarker, { kind: "reject" }, { observed: 0 }).map((record) => {
+    if (record.status === "limited") {
+      throw new GitHistoryError("budget", `A Git commit exceeded the ${MAX_GIT_PATHS_PER_COMMIT} changed-path limit.`);
+    }
+    return record.commit;
+  }));
+}
+function parseSelectedGitHistoryOutput(output, expectedMarker, paths, pathBudget) {
+  return Object.freeze(parseGitHistoryRecords(output, expectedMarker, { kind: "select", paths }, pathBudget).map((record) => {
+    if (record.status === "limited") {
+      throw new GitHistoryError("malformed", "Git live-note history was unexpectedly limited.");
+    }
+    return record.commit;
+  }));
+}
+function historyArguments(hashes, marker) {
+  return [
+    "show",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-renames",
+    "--diff-merges=first-parent",
+    `--format=${marker}%x00%H%x00%ct%x00%s%x00`,
+    "--name-only",
+    "-z",
+    ...hashes,
+    "--"
+  ];
+}
+function logArguments(maxCommits, vaultPrefix, marker, revision) {
+  return [
+    "--literal-pathspecs",
+    "log",
+    "--no-color",
+    "--no-decorate",
+    "--no-renames",
+    "--diff-merges=first-parent",
+    "--first-parent",
+    `--max-count=${maxCommits}`,
+    `--format=${marker}%x00%H%x00%ct%x00%s%x00`,
+    "--name-only",
+    "-z",
+    revision,
+    "--",
+    vaultPrefix === "" ? "." : vaultPrefix
+  ];
+}
+function freezeCommit(commit, changedPathDetailsLimited) {
+  return Object.freeze({
+    hash: commit.hash,
+    committedAt: new Date(commit.timestamp * 1000).toISOString(),
+    subject: commit.subject,
+    changedPaths: commit.changedPaths,
+    ...changedPathDetailsLimited ? { changedPathDetailsLimited: true } : {}
+  });
+}
+function recordHash(record) {
+  return record.status === "complete" ? record.commit.hash : record.limit.hash;
+}
+async function confinedNotes(notes, repository, root, vaultPrefix) {
+  if (notes.length > MAX_GIT_HISTORY_NOTES) {
+    throw new GitHistoryError("budget", `Git history accepts at most ${MAX_GIT_HISTORY_NOTES} live notes.`);
+  }
+  const seenIds = new Set;
+  const seenPaths = new Set;
+  const confined = [];
+  for (const note of notes) {
+    checkedNoteIdentity(note);
+    if (seenIds.has(note.id) || seenPaths.has(note.path)) {
+      throw new GitHistoryError("malformed", `Duplicate live note identity ${JSON.stringify(note.id)}.`);
+    }
+    seenIds.add(note.id);
+    seenPaths.add(note.path);
+    let resolvedNote;
+    try {
+      resolvedNote = await realpath(resolve(root, note.path));
+    } catch (error) {
+      throw new GitHistoryError("confinement", `Live note ${JSON.stringify(note.path)} could not be resolved.`, { cause: error });
+    }
+    if (!inside(root, resolvedNote) || !inside(repository, resolvedNote)) {
+      throw new GitHistoryError("confinement", `Live note ${JSON.stringify(note.path)} resolves outside the vault or repository.`);
+    }
+    if (!(await stat(resolvedNote)).isFile()) {
+      throw new GitHistoryError("confinement", `Live note ${JSON.stringify(note.path)} is not a file.`);
+    }
+    confined.push(Object.freeze({
+      id: note.id,
+      path: note.path,
+      repositoryPath: vaultPrefix === "" ? note.path : `${vaultPrefix}/${note.path}`
+    }));
+  }
+  return Object.freeze(confined.toSorted((left, right) => left.id.localeCompare(right.id)));
+}
+async function indexGitHistory(options, dependencies = {}) {
+  const maxCommits = checkedInteger(options.maxCommits, DEFAULT_COMMITS, 1, MAX_GIT_HISTORY_COMMITS, "Git commit limit");
+  const timeoutMs = checkedInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1, MAX_GIT_HISTORY_TIMEOUT_MS, "Git timeout");
+  const outputLimit = checkedInteger(options.maxOutputBytes, DEFAULT_OUTPUT_BYTES, 1024, MAX_GIT_HISTORY_OUTPUT_BYTES, "Git output limit");
+  let repository;
+  let root;
+  try {
+    repository = await realpath(resolve(options.repository));
+    root = await realpath(resolve(options.root));
+  } catch (error) {
+    throw new GitHistoryError("confinement", "Repository and vault roots must resolve.", { cause: error });
+  }
+  if (!(await stat(repository)).isDirectory() || !(await stat(root)).isDirectory()) {
+    throw new GitHistoryError("confinement", "Repository and vault roots must be directories.");
+  }
+  if (!inside(repository, root)) {
+    throw new GitHistoryError("confinement", "Knowledge-base root must resolve inside the repository.");
+  }
+  const vaultPrefix = posixRelative(repository, root);
+  const provider = dependencies.runGit ?? runGitCommand;
+  const budget = {
+    startedAt: Date.now(),
+    timeoutMs,
+    outputLimit,
+    outputBytes: 0
+  };
+  const topLevel = await checkedCommand(provider, repository, ["rev-parse", "--show-toplevel"], budget, options.required ?? false, "Git repository discovery");
+  if (topLevel.status === "unavailable") {
+    return Object.freeze({ ...topLevel, repository, root, vaultPrefix });
+  }
+  let actualTopLevel;
+  try {
+    actualTopLevel = await realpath(singleLine(topLevel.stdout, "Git repository root"));
+  } catch (error) {
+    if (error instanceof GitHistoryError)
+      throw error;
+    throw new GitHistoryError("malformed", "Git returned an unresolved repository root.", { cause: error });
+  }
+  if (actualTopLevel !== repository) {
+    throw new GitHistoryError("confinement", `Git resolved ${JSON.stringify(actualTopLevel)} instead of the requested repository.`);
+  }
+  const headResult = await checkedCommand(provider, repository, ["rev-parse", "--verify", "HEAD"], budget, true, "Git HEAD discovery");
+  if (headResult.status === "unavailable") {
+    throw new GitHistoryError("unavailable", headResult.reason);
+  }
+  const head = singleLine(headResult.stdout, "Git HEAD");
+  if (!objectIdPattern.test(head)) {
+    throw new GitHistoryError("malformed", "Git returned a malformed HEAD object ID.");
+  }
+  const liveNotes = await confinedNotes(options.notes, repository, root, vaultPrefix);
+  if (liveNotes.length === 0) {
+    return Object.freeze({
+      status: "ready",
+      repository,
+      root,
+      vaultPrefix,
+      head,
+      scannedCommits: 0,
+      notes: Object.freeze([])
+    });
+  }
+  const marker = `${commitMarker}-${randomUUID()}`;
+  const pathBudget = { observed: 0 };
+  const metadataResult = await checkedCommand(provider, repository, logArguments(maxCommits, vaultPrefix, marker, head), budget, true, "Git vault history");
+  if (metadataResult.status === "unavailable") {
+    throw new GitHistoryError("unavailable", metadataResult.reason);
+  }
+  const noteIdByRepositoryPath = new Map(liveNotes.map(({ id, repositoryPath }) => [repositoryPath, id]));
+  const vaultCommits = parseSelectedGitHistoryOutput(metadataResult.stdout, marker, new Set(noteIdByRepositoryPath.keys()), pathBudget);
+  const detailsResult = vaultCommits.length === 0 ? null : await checkedCommand(provider, repository, historyArguments(vaultCommits.map(({ hash }) => hash), marker), budget, true, "Git commit path history");
+  if (detailsResult?.status === "unavailable") {
+    throw new GitHistoryError("unavailable", detailsResult.reason);
+  }
+  const detailRecords = detailsResult === null ? [] : parseGitHistoryRecords(detailsResult.stdout, marker, { kind: "limit" }, pathBudget);
+  if (detailRecords.length !== vaultCommits.length || detailRecords.some((record, index) => recordHash(record) !== vaultCommits[index]?.hash)) {
+    throw new GitHistoryError("malformed", "Git returned inconsistent vault and changed-path histories.");
+  }
+  const commits = [];
+  const limitedCommits = [];
+  detailRecords.forEach((detailRecord, index) => {
+    const vaultCommit = vaultCommits[index];
+    if (detailRecord.status === "complete") {
+      commits.push(freezeCommit(detailRecord.commit, false));
+      return;
+    }
+    const affectedNoteIds = Object.freeze(vaultCommit.changedPaths.map((path) => {
+      const noteId = noteIdByRepositoryPath.get(path);
+      if (noteId === undefined) {
+        throw new GitHistoryError("malformed", "Git selected a path outside the live-note set.");
+      }
+      return noteId;
+    }));
+    commits.push(freezeCommit({
+      hash: detailRecord.limit.hash,
+      timestamp: detailRecord.limit.timestamp,
+      subject: detailRecord.limit.subject,
+      changedPaths: vaultCommit.changedPaths
+    }, true));
+    limitedCommits.push(Object.freeze({
+      hash: detailRecord.limit.hash,
+      committedAt: new Date(detailRecord.limit.timestamp * 1000).toISOString(),
+      subject: detailRecord.limit.subject,
+      reason: detailRecord.limit.reason,
+      pathLimit: detailRecord.limit.pathLimit,
+      observedPathRecords: detailRecord.limit.observedPathRecords,
+      affectedNoteIds
+    }));
+  });
+  const commitsByPath = new Map;
+  for (const commit of commits) {
+    for (const path of commit.changedPaths) {
+      const existing = commitsByPath.get(path);
+      if (existing === undefined)
+        commitsByPath.set(path, [commit]);
+      else
+        existing.push(commit);
+    }
+  }
+  const indexedNotes = liveNotes.map((note) => Object.freeze({
+    ...note,
+    commits: Object.freeze([...commitsByPath.get(note.repositoryPath) ?? []])
+  }));
+  return Object.freeze({
+    status: "ready",
+    repository,
+    root,
+    vaultPrefix,
+    head,
+    scannedCommits: detailRecords.length,
+    notes: Object.freeze(indexedNotes),
+    ...limitedCommits.length === 0 ? {} : { limitedCommits: Object.freeze(limitedCommits) }
+  });
+}
+function limitedCommitsForNotes(limitedCommits, noteIds, commitHashes) {
+  if (limitedCommits === undefined || limitedCommits.length === 0)
+    return Object.freeze([]);
+  return Object.freeze(limitedCommits.flatMap((commit) => {
+    if (commitHashes !== null && !commitHashes.has(commit.hash))
+      return [];
+    const affectedNoteIds = Object.freeze(commit.affectedNoteIds.filter((id) => noteIds.has(id)));
+    return affectedNoteIds.length === 0 ? [] : [Object.freeze({ ...commit, affectedNoteIds })];
+  }));
+}
+function validateGitHistoryForNotesOptions(options = {}) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new GitHistoryError("malformed", "Git history options must be an object.");
+  }
+  return Object.freeze({
+    commitsPerNote: checkedInteger(options.commitsPerNote, DEFAULT_COMMITS_PER_NOTE, 1, MAX_COMMITS_PER_NOTE, "Per-note commit limit"),
+    cochangedPathsPerCommit: checkedInteger(options.cochangedPathsPerCommit, DEFAULT_COCHANGED_PATHS, 0, MAX_COCHANGED_PATHS, "Cochanged-path limit")
+  });
+}
+function isIterableObject(value) {
+  return typeof value === "object" && value !== null && Symbol.iterator in value && typeof value[Symbol.iterator] === "function";
+}
+function checkedNoteIds(value, label, countMessage) {
+  if (!Array.isArray(value) && !isIterableObject(value)) {
+    throw new GitHistoryError("malformed", `${label}s must be provided as an array or set.`);
+  }
+  const noteIds = [];
+  let noteIdBytes = 0;
+  for (const noteId of value) {
+    if (noteIds.length >= MAX_GIT_HISTORY_NOTES) {
+      throw new GitHistoryError("budget", countMessage);
+    }
+    if (typeof noteId !== "string") {
+      throw new GitHistoryError("malformed", `${label} ${noteIds.length + 1} must be a string.`);
+    }
+    const noteIdByteLength = Buffer.byteLength(noteId, "utf8");
+    if (noteIdByteLength > MAX_GIT_NOTE_ID_UTF8_BYTES) {
+      throw new GitHistoryError("budget", `${label} ${noteIds.length + 1} must be at most ` + `${MAX_GIT_NOTE_ID_UTF8_BYTES.toLocaleString("en-US")} UTF-8 bytes.`);
+    }
+    noteIdBytes += noteIdByteLength;
+    if (noteIdBytes > MAX_GIT_NOTE_IDS_UTF8_BYTES) {
+      throw new GitHistoryError("budget", `${label}s must total at most ` + `${MAX_GIT_NOTE_IDS_UTF8_BYTES.toLocaleString("en-US")} UTF-8 bytes.`);
+    }
+    noteIds.push(noteId);
+  }
+  return Object.freeze(noteIds);
+}
+function validateGitHistoryForNotesRequest(noteIds, options = {}) {
+  return Object.freeze({
+    noteIds: checkedNoteIds(noteIds, "Git history note ID", `At most ${MAX_GIT_HISTORY_NOTES} note IDs may be requested.`),
+    options: validateGitHistoryForNotesOptions(options)
+  });
+}
+function noteCommit(commit, notePath, cochangedPathsPerCommit) {
+  return Object.freeze({
+    hash: commit.hash,
+    committedAt: commit.committedAt,
+    subject: commit.subject,
+    cochangedPaths: Object.freeze(commit.changedPaths.filter((path) => path !== notePath).slice(0, cochangedPathsPerCommit)),
+    ...commit.changedPathDetailsLimited === true ? { cochangeDetailsLimited: true } : {}
+  });
+}
+function gitHistoryForNotes(index, noteIds, options = {}) {
+  const request = validateGitHistoryForNotesRequest(noteIds, options);
+  if (index.status === "unavailable")
+    return index;
+  const allowed = new Set(request.noteIds);
+  const notes = index.notes.filter((note) => allowed.has(note.id)).map((note) => Object.freeze({
+    id: note.id,
+    path: note.path,
+    commits: Object.freeze(note.commits.slice(0, request.options.commitsPerNote).map((commit) => noteCommit(commit, note.repositoryPath, request.options.cochangedPathsPerCommit)))
+  }));
+  const returnedNoteIds = new Set(notes.map(({ id }) => id));
+  const returnedCommitHashes = new Set(notes.flatMap(({ commits }) => commits.map(({ hash }) => hash)));
+  const limitedCommits = limitedCommitsForNotes(index.limitedCommits, returnedNoteIds, returnedCommitHashes);
+  return Object.freeze({
+    status: "ready",
+    head: index.head,
+    notes: Object.freeze(notes),
+    ...limitedCommits.length === 0 ? {} : { limitedCommits }
+  });
+}
+function normalizedSearch(value) {
+  return value.normalize("NFC").toLocaleLowerCase("en-US");
+}
+function queryTerms(query) {
+  if (typeof query !== "string") {
+    throw new GitHistoryError("malformed", `Git history query must be one to ${MAX_QUERY_LENGTH} characters on one line.`);
+  }
+  const trimmed = query.trim();
+  if (trimmed === "" || trimmed.length > MAX_QUERY_LENGTH || /[\0\r\n]/u.test(trimmed)) {
+    throw new GitHistoryError("malformed", `Git history query must be one to ${MAX_QUERY_LENGTH} characters on one line.`);
+  }
+  const normalized = normalizedSearch(trimmed);
+  const terms = [...new Set(normalized.split(/[^\p{L}\p{N}_./-]+/u).filter(Boolean))].slice(0, 20);
+  return { normalized, terms: Object.freeze(terms) };
+}
+function validateSearchGitHistoryOptions(options) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new GitHistoryError("malformed", "Git history search options must be an object.");
+  }
+  const limit = checkedInteger(options.limit, DEFAULT_SEARCH_LIMIT, 1, MAX_SEARCH_LIMIT, "Git search limit");
+  const provenance = validateGitHistoryForNotesOptions({
+    ...options.commitsPerHit === undefined ? {} : { commitsPerNote: options.commitsPerHit },
+    ...options.cochangedPathsPerCommit === undefined ? {} : { cochangedPathsPerCommit: options.cochangedPathsPerCommit }
+  });
+  const { normalized, terms } = queryTerms(options.query);
+  const checkedAllowed = options.allowedNoteIds === undefined ? null : checkedNoteIds(options.allowedNoteIds, "Git search allowed note ID", `Git search accepts at most ${MAX_GIT_HISTORY_NOTES} allowed note IDs.`);
+  return Object.freeze({
+    query: options.query.trim(),
+    normalizedQuery: normalized,
+    terms,
+    allowedNoteIds: checkedAllowed === null ? null : new Set(checkedAllowed),
+    limit,
+    commitsPerHit: provenance.commitsPerNote,
+    cochangedPathsPerCommit: provenance.cochangedPathsPerCommit
+  });
+}
+function matchStrength(value, normalizedQuery, terms) {
+  const normalized = normalizedSearch(value);
+  if (normalized.includes(normalizedQuery))
+    return 2 + normalizedQuery.length / 1000;
+  if (terms.length === 0)
+    return 0;
+  const matched = terms.filter((term) => normalized.includes(term)).length;
+  return matched / terms.length;
+}
+function scoredCommits(note, normalizedQuery, terms) {
+  const matches = [];
+  note.commits.forEach((commit, index) => {
+    const subjectStrength = matchStrength(commit.subject, normalizedQuery, terms);
+    const matchingPaths = commit.changedPaths.map((path) => ({ path, strength: matchStrength(path, normalizedQuery, terms) })).filter(({ strength }) => strength > 0).toSorted((left, right) => right.strength - left.strength || left.path.localeCompare(right.path));
+    const bestPath = matchingPaths[0]?.strength ?? 0;
+    if (subjectStrength === 0 && bestPath === 0)
+      return;
+    const recency = 1 / (100 + index);
+    matches.push({
+      score: subjectStrength * 4 + bestPath * 2 + recency,
+      commit,
+      matchedSubject: subjectStrength > 0,
+      matchedPaths: Object.freeze(matchingPaths.map(({ path }) => path))
+    });
+  });
+  return Object.freeze(matches.toSorted((left, right) => right.score - left.score || left.commit.hash.localeCompare(right.commit.hash)));
+}
+function searchGitHistory(index, options) {
+  const request = validateSearchGitHistoryOptions(options);
+  if (index.status === "unavailable")
+    return index;
+  const hits = [];
+  for (const note of index.notes) {
+    if (request.allowedNoteIds !== null && !request.allowedNoteIds.has(note.id))
+      continue;
+    const matches = scoredCommits(note, request.normalizedQuery, request.terms);
+    if (matches.length === 0)
+      continue;
+    const score = matches.reduce((total, match, matchIndex) => total + match.score / (matchIndex + 1), 0);
+    hits.push(Object.freeze({
+      id: note.id,
+      path: note.path,
+      score: Number(score.toFixed(6)),
+      commits: Object.freeze(matches.slice(0, request.commitsPerHit).map((match) => Object.freeze({
+        ...noteCommit(match.commit, note.repositoryPath, request.cochangedPathsPerCommit),
+        matchedSubject: match.matchedSubject,
+        matchedPaths: Object.freeze(match.matchedPaths.slice(0, request.cochangedPathsPerCommit))
+      })))
+    }));
+  }
+  hits.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+  const searchableNoteIds = new Set(index.notes.flatMap(({ id }) => request.allowedNoteIds === null || request.allowedNoteIds.has(id) ? [id] : []));
+  const limitedCommits = limitedCommitsForNotes(index.limitedCommits, searchableNoteIds, null);
+  return Object.freeze({
+    status: "ready",
+    head: index.head,
+    query: request.query,
+    hits: Object.freeze(hits.slice(0, request.limit)),
+    ...limitedCommits.length === 0 ? {} : { limitedCommits }
+  });
+}
+
+export { MAX_GIT_HISTORY_COMMITS, MAX_GIT_HISTORY_NOTES, MAX_GIT_HISTORY_OUTPUT_BYTES, MAX_GIT_HISTORY_TIMEOUT_MS, MAX_GIT_PATHS_PER_COMMIT, MAX_GIT_PATH_OBSERVATIONS, MAX_GIT_NOTE_ID_UTF8_BYTES, MAX_GIT_NOTE_IDS_UTF8_BYTES, GitHistoryError, runGitCommand, parseGitHistoryOutput, indexGitHistory, validateGitHistoryForNotesOptions, validateGitHistoryForNotesRequest, gitHistoryForNotes, validateSearchGitHistoryOptions, searchGitHistory };