@try-works/dsh-memory 0.1.19 → 0.1.20

package/src/history.js

@@ -1,226 +1,226 @@
-// Commit-history shard: what actually changed in a repository, and when.
-//
-// The codebase map says what a module IS; this says how it CHANGED. It is a workspace-only
-// layered kind (history.md index over history/<day>.md), one file per calendar day, so a
-// long-lived repo produces many small readable files instead of one growing log.
-//
-// Ingestion is incremental per workspace behind a hash watermark in state/history.json: only
-// commits the store has not recorded are turned into entries.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { allocateId } from './entry.js'
-import { appendToTopic, layerIndexPath, layerText, rebuildLayerIndex, readLayerTopics } from './layers.js'
-import { updateIndex } from './fts.js'
-
-/** Field/record separators git writes for us, chosen so a commit body cannot forge them. */
-const FIELD_SEP = '\u001f'
-const RECORD_SEP = '\u001e'
-/** How many commits one ingest pass will record. */
-export const DEFAULT_HISTORY_LIMIT = 40
-
-export function historyStatePath(root) { return join(root, 'state', 'history.json') }
-
-export function readHistoryState(root) {
-  try { return JSON.parse(readFileSync(historyStatePath(root), 'utf8')) } catch { return {} }
-}
-
-export function writeHistoryState(root, value) {
-  mkdirSync(join(root, 'state'), { recursive: true })
-  writeFileSync(historyStatePath(root), JSON.stringify(value, null, 2) + '\n')
-}
-
-/**
- * Parse log output produced with a FIELD_SEP-delimited pretty format.
- * @returns {{hash: string, date: string, subject: string, body: string, files: string[]}[]}
- */
-export function parseGitLog(text) {
-  const out = []
-  for (const record of String(text ?? '').split(RECORD_SEP)) {
-    if (record.trim() === '') continue
-    const parts = record.split(FIELD_SEP)
-    if (parts.length < 4) continue
-    // Format: hash FS iso FS subject FS body FS, then (with --name-only) the changed
-    // files, so everything from parts[4] on is the file list.
-    const files = []
-    for (const chunk of parts.slice(4)) {
-      for (const line of chunk.split('\n')) {
-        const file = line.trim().replace(/^--\s+/, '')
-        if (file !== '') files.push(file)
-      }
-    }
-    out.push({
-      hash: String(parts[0] ?? '').trim(),
-      date: String(parts[1] ?? '').trim(),
-      subject: String(parts[2] ?? '').trim(),
-      body: String(parts[3] ?? '').trim(),
-      files,
-    })
-  }
-  return out
-}
-/**
- * The pretty format used for ingest. FS ends the body and RECORD_SEP ends the commit, so
- * --name-only appends the changed files inside the same record and neither a subject nor a
- * commit body can forge a boundary.
- */
-export const HISTORY_FORMAT = '%x1e%H%x1f%cI%x1f%s%x1f%b%x1f'
-
-/** Calendar day (YYYY-MM-DD) of a git ISO date, in UTC. */
-export function dayOf(iso) {
-  const text = String(iso ?? '').trim()
-  if (text === '') return 'unknown'
-  const date = new Date(text)
-  if (Number.isNaN(date.getTime())) return text.slice(0, 10) || 'unknown'
-  return date.toISOString().slice(0, 10)
-}
-
-/** Heading for a commit entry: the subject, clipped, with the short hash. */
-export function commitHeading(commit) {
-  const subject = String(commit.subject ?? '').trim() || '(no subject)'
-  const short = String(commit.hash ?? '').slice(0, 8)
-  const clipped = subject.length > 80 ? subject.slice(0, 77) + '...' : subject
-  return clipped + ' (' + short + ')'
-}
-
-/**
- * Render one commit as a Format-2 block, the same shape every other layer uses so the
- * parser, ledger, ranking and search work on history entries unchanged.
- * @param commit - parsed commit.
- * @param id - allocated entry id.
- * @param options.summary - optional note describing why the change mattered.
- */
-export function renderCommitEntry(commit, id, options = {}) {
-  const body = []
-  body.push('Commit: ' + commit.hash)
-  if (commit.body) body.push('', commit.body)
-  if (commit.files.length) {
-    body.push('', 'Files (' + commit.files.length + '):')
-    for (const file of commit.files.slice(0, 40)) body.push('- ' + file)
-    if (commit.files.length > 40) body.push('- (+' + (commit.files.length - 40) + ' more)')
-  }
-  if (options.summary) body.push('', 'Why it mattered: ' + options.summary)
-  return [
-    '## ' + commitHeading(commit),
-    '',
-    '**Id:** ' + id,
-    '**Source:** git:' + String(commit.hash ?? '').slice(0, 12),
-    '**Date:** ' + commit.date,
-    '**Updated:** ' + commit.date,
-    '**Importance:** ' + (options.importance ?? 2),
-    '**Status:** active',
-    '**Format:** 2',
-    '',
-    body.join('\n'),
-  ].join('\n')
-}
-
-/**
- * Group unseen commits by the day file they belong in and keep only what the limit allows.
- * @param commits - parsed commits, any order.
- * @param seen - Set of hashes already recorded.
- * @param limit - maximum new commits to take.
- * @returns {{day: string, commits: object[]}[]} day groups in chronological order.
- */
-export function planHistoryIngest(commits, seen, limit = DEFAULT_HISTORY_LIMIT) {
-  const fresh = commits.filter((commit) => commit.hash && !seen.has(commit.hash)).slice(0, limit)
-  const byDay = new Map()
-  for (const commit of fresh) {
-    const day = dayOf(commit.date)
-    if (!byDay.has(day)) byDay.set(day, [])
-    byDay.get(day).push(commit)
-  }
-  return [...byDay.entries()]
-    .sort((a, b) => a[0].localeCompare(b[0]))
-    .map(([day, group]) => ({ day, commits: group.sort((a, b) => String(a.date).localeCompare(String(b.date))) }))
-}
-
-/**
- * Ingest new commits of one repository into that workspace history layer.
- *
- * Incremental in two layers: the git range starts at the last recorded commit when the
- * watermark is still reachable, and the seen-set drops anything already recorded even if the
- * range had to fall back (a rebase or force-push rewrites history and breaks the ancestor
- * walk). Only new commits are appended, so a re-ingest of the same range is a no-op.
- *
- * @param root - memory store root.
- * @param workspace - workspace key.
- * @param repoPath - local repository to read.
- * @param run - git runner: (argv, opts) => { code, stdout, stderr }.
- * @param options.limit - maximum new commits to record in this pass.
- * @returns a summary of what was recorded.
- */
-export async function ingestHistory(root, workspace, repoPath, run, options = {}) {
-  const limit = options.limit ?? DEFAULT_HISTORY_LIMIT
-  if (!looksLikeRepo(repoPath)) return { ok: false, reason: 'not a git repository', repoPath, added: 0 }
-  const state = readHistoryState(root)
-  const record = state[workspace] ?? { hashes: [], head: undefined }
-  // Two guards, because bookkeeping alone is not enough. The hash watermark is fast but
-  // bounded (and a rewound watermark, a fresh clone or an expired window would re-add
-  // commits), so the layer itself is also read: a commit already written is never written
-  // twice, whatever the bookkeeping says.
-  const seen = new Set(options.allHashes ? [] : record.hashes)
-  for (const hash of recordedCommits(root, workspace)) seen.add(hash)
-  const range = record.head ? [record.head + '..HEAD'] : []
-  const argv = ['log', '--date=iso-strict', '--pretty=format:' + HISTORY_FORMAT, '--name-only', '-n', String(limit)]
-  const result = await run([...argv, ...range], { cwd: repoPath })
-  // The runner may report either `code` or `exitCode` (GitRunner and ctx.subprocess differ).
-  // Reading only one silently treated every successful range query as a failure, so each
-  // ingest re-read the whole log and reported fellBack.
-  const failed = (outcome) => (outcome?.exitCode ?? outcome?.code ?? 1) !== 0
-  const fallback = range.length > 0 && failed(result)
-  const output = fallback ? await run(argv, { cwd: repoPath }) : result
-  const commits = parseGitLog(output.stdout ?? '')
-  const plan = planHistoryIngest(commits, seen, limit)
-  let added = 0
-  const touched = new Set()
-  for (const group of plan) {
-    for (const commit of group.commits) {
-      const heading = commitHeading(commit)
-      const id = allocateId(layerText(root, 'workspace', workspace, 'history'), workspace, 'history')
-      const block = renderCommitEntry(commit, id, options.renderOptions ?? {})
-      touched.add(appendToTopic(root, 'workspace', workspace, 'history', group.day, block))
-      seen.add(commit.hash)
-      added += 1
-    }
-  }
-  if (added > 0) {
-    rebuildLayerIndex(root, 'workspace', workspace, 'history')
-    // Index what this pass wrote. Without this the entries exist on disk but are
-    // invisible to search until some unrelated write triggers a reindex.
-    updateIndex(root, [...touched, layerIndexPath(root, 'workspace', workspace, 'history')])
-  }
-  const head = await run(['rev-parse', 'HEAD'], { cwd: repoPath })
-  const headHash = (head.stdout ?? '').trim()
-  const bounded = [...seen].slice(-500)
-  state[workspace] = {
-    repoPath,
-    head: headHash !== '' ? headHash : record.head,
-    hashes: bounded,
-    updatedAt: new Date().toISOString(),
-    ...(output === result ? {} : { fellBack: true }),
-  }
-  writeHistoryState(root, state)
-  return { ok: true, repoPath, added, skipped: commits.length - added, fellBack: fallback, head: state[workspace].head }
-}
-
-/**
- * Commit hashes already present in a workspace history layer, read from the entries
- * themselves. This is the authoritative record: state/history.json is an optimisation.
- * @returns a Set of full hashes.
- */
-export function recordedCommits(root, workspace) {
-  const found = new Set()
-  for (const topic of readLayerTopics(root, 'workspace', workspace, 'history')) {
-    for (const match of topic.text.matchAll(/^Commit: ([0-9a-f]{7,40})$/gm)) found.add(match[1])
-  }
-  return found
-}
-
-/** Commits already recorded for a workspace, from bookkeeping only. */
-export function recordedHashes(root, workspace) {
-  return new Set(readHistoryState(root)[workspace]?.hashes ?? [])
-}
-/** True when a path looks like a repository the store can read history from. */
-export function looksLikeRepo(path) {
-  return typeof path === 'string' && path !== '' && existsSync(join(path, '.git'))
-}
+// Commit-history shard: what actually changed in a repository, and when.
+//
+// The codebase map says what a module IS; this says how it CHANGED. It is a workspace-only
+// layered kind (history.md index over history/<day>.md), one file per calendar day, so a
+// long-lived repo produces many small readable files instead of one growing log.
+//
+// Ingestion is incremental per workspace behind a hash watermark in state/history.json: only
+// commits the store has not recorded are turned into entries.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { allocateId } from './entry.js'
+import { appendToTopic, layerIndexPath, layerText, rebuildLayerIndex, readLayerTopics } from './layers.js'
+import { updateIndex } from './fts.js'
+
+/** Field/record separators git writes for us, chosen so a commit body cannot forge them. */
+const FIELD_SEP = '\u001f'
+const RECORD_SEP = '\u001e'
+/** How many commits one ingest pass will record. */
+export const DEFAULT_HISTORY_LIMIT = 40
+
+export function historyStatePath(root) { return join(root, 'state', 'history.json') }
+
+export function readHistoryState(root) {
+  try { return JSON.parse(readFileSync(historyStatePath(root), 'utf8')) } catch { return {} }
+}
+
+export function writeHistoryState(root, value) {
+  mkdirSync(join(root, 'state'), { recursive: true })
+  writeFileSync(historyStatePath(root), JSON.stringify(value, null, 2) + '\n')
+}
+
+/**
+ * Parse log output produced with a FIELD_SEP-delimited pretty format.
+ * @returns {{hash: string, date: string, subject: string, body: string, files: string[]}[]}
+ */
+export function parseGitLog(text) {
+  const out = []
+  for (const record of String(text ?? '').split(RECORD_SEP)) {
+    if (record.trim() === '') continue
+    const parts = record.split(FIELD_SEP)
+    if (parts.length < 4) continue
+    // Format: hash FS iso FS subject FS body FS, then (with --name-only) the changed
+    // files, so everything from parts[4] on is the file list.
+    const files = []
+    for (const chunk of parts.slice(4)) {
+      for (const line of chunk.split('\n')) {
+        const file = line.trim().replace(/^--\s+/, '')
+        if (file !== '') files.push(file)
+      }
+    }
+    out.push({
+      hash: String(parts[0] ?? '').trim(),
+      date: String(parts[1] ?? '').trim(),
+      subject: String(parts[2] ?? '').trim(),
+      body: String(parts[3] ?? '').trim(),
+      files,
+    })
+  }
+  return out
+}
+/**
+ * The pretty format used for ingest. FS ends the body and RECORD_SEP ends the commit, so
+ * --name-only appends the changed files inside the same record and neither a subject nor a
+ * commit body can forge a boundary.
+ */
+export const HISTORY_FORMAT = '%x1e%H%x1f%cI%x1f%s%x1f%b%x1f'
+
+/** Calendar day (YYYY-MM-DD) of a git ISO date, in UTC. */
+export function dayOf(iso) {
+  const text = String(iso ?? '').trim()
+  if (text === '') return 'unknown'
+  const date = new Date(text)
+  if (Number.isNaN(date.getTime())) return text.slice(0, 10) || 'unknown'
+  return date.toISOString().slice(0, 10)
+}
+
+/** Heading for a commit entry: the subject, clipped, with the short hash. */
+export function commitHeading(commit) {
+  const subject = String(commit.subject ?? '').trim() || '(no subject)'
+  const short = String(commit.hash ?? '').slice(0, 8)
+  const clipped = subject.length > 80 ? subject.slice(0, 77) + '...' : subject
+  return clipped + ' (' + short + ')'
+}
+
+/**
+ * Render one commit as a Format-2 block, the same shape every other layer uses so the
+ * parser, ledger, ranking and search work on history entries unchanged.
+ * @param commit - parsed commit.
+ * @param id - allocated entry id.
+ * @param options.summary - optional note describing why the change mattered.
+ */
+export function renderCommitEntry(commit, id, options = {}) {
+  const body = []
+  body.push('Commit: ' + commit.hash)
+  if (commit.body) body.push('', commit.body)
+  if (commit.files.length) {
+    body.push('', 'Files (' + commit.files.length + '):')
+    for (const file of commit.files.slice(0, 40)) body.push('- ' + file)
+    if (commit.files.length > 40) body.push('- (+' + (commit.files.length - 40) + ' more)')
+  }
+  if (options.summary) body.push('', 'Why it mattered: ' + options.summary)
+  return [
+    '## ' + commitHeading(commit),
+    '',
+    '**Id:** ' + id,
+    '**Source:** git:' + String(commit.hash ?? '').slice(0, 12),
+    '**Date:** ' + commit.date,
+    '**Updated:** ' + commit.date,
+    '**Importance:** ' + (options.importance ?? 2),
+    '**Status:** active',
+    '**Format:** 2',
+    '',
+    body.join('\n'),
+  ].join('\n')
+}
+
+/**
+ * Group unseen commits by the day file they belong in and keep only what the limit allows.
+ * @param commits - parsed commits, any order.
+ * @param seen - Set of hashes already recorded.
+ * @param limit - maximum new commits to take.
+ * @returns {{day: string, commits: object[]}[]} day groups in chronological order.
+ */
+export function planHistoryIngest(commits, seen, limit = DEFAULT_HISTORY_LIMIT) {
+  const fresh = commits.filter((commit) => commit.hash && !seen.has(commit.hash)).slice(0, limit)
+  const byDay = new Map()
+  for (const commit of fresh) {
+    const day = dayOf(commit.date)
+    if (!byDay.has(day)) byDay.set(day, [])
+    byDay.get(day).push(commit)
+  }
+  return [...byDay.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([day, group]) => ({ day, commits: group.sort((a, b) => String(a.date).localeCompare(String(b.date))) }))
+}
+
+/**
+ * Ingest new commits of one repository into that workspace history layer.
+ *
+ * Incremental in two layers: the git range starts at the last recorded commit when the
+ * watermark is still reachable, and the seen-set drops anything already recorded even if the
+ * range had to fall back (a rebase or force-push rewrites history and breaks the ancestor
+ * walk). Only new commits are appended, so a re-ingest of the same range is a no-op.
+ *
+ * @param root - memory store root.
+ * @param workspace - workspace key.
+ * @param repoPath - local repository to read.
+ * @param run - git runner: (argv, opts) => { code, stdout, stderr }.
+ * @param options.limit - maximum new commits to record in this pass.
+ * @returns a summary of what was recorded.
+ */
+export async function ingestHistory(root, workspace, repoPath, run, options = {}) {
+  const limit = options.limit ?? DEFAULT_HISTORY_LIMIT
+  if (!looksLikeRepo(repoPath)) return { ok: false, reason: 'not a git repository', repoPath, added: 0 }
+  const state = readHistoryState(root)
+  const record = state[workspace] ?? { hashes: [], head: undefined }
+  // Two guards, because bookkeeping alone is not enough. The hash watermark is fast but
+  // bounded (and a rewound watermark, a fresh clone or an expired window would re-add
+  // commits), so the layer itself is also read: a commit already written is never written
+  // twice, whatever the bookkeeping says.
+  const seen = new Set(options.allHashes ? [] : record.hashes)
+  for (const hash of recordedCommits(root, workspace)) seen.add(hash)
+  const range = record.head ? [record.head + '..HEAD'] : []
+  const argv = ['log', '--date=iso-strict', '--pretty=format:' + HISTORY_FORMAT, '--name-only', '-n', String(limit)]
+  const result = await run([...argv, ...range], { cwd: repoPath })
+  // The runner may report either `code` or `exitCode` (GitRunner and ctx.subprocess differ).
+  // Reading only one silently treated every successful range query as a failure, so each
+  // ingest re-read the whole log and reported fellBack.
+  const failed = (outcome) => (outcome?.exitCode ?? outcome?.code ?? 1) !== 0
+  const fallback = range.length > 0 && failed(result)
+  const output = fallback ? await run(argv, { cwd: repoPath }) : result
+  const commits = parseGitLog(output.stdout ?? '')
+  const plan = planHistoryIngest(commits, seen, limit)
+  let added = 0
+  const touched = new Set()
+  for (const group of plan) {
+    for (const commit of group.commits) {
+      const heading = commitHeading(commit)
+      const id = allocateId(layerText(root, 'workspace', workspace, 'history'), workspace, 'history')
+      const block = renderCommitEntry(commit, id, options.renderOptions ?? {})
+      touched.add(appendToTopic(root, 'workspace', workspace, 'history', group.day, block))
+      seen.add(commit.hash)
+      added += 1
+    }
+  }
+  if (added > 0) {
+    rebuildLayerIndex(root, 'workspace', workspace, 'history')
+    // Index what this pass wrote. Without this the entries exist on disk but are
+    // invisible to search until some unrelated write triggers a reindex.
+    updateIndex(root, [...touched, layerIndexPath(root, 'workspace', workspace, 'history')])
+  }
+  const head = await run(['rev-parse', 'HEAD'], { cwd: repoPath })
+  const headHash = (head.stdout ?? '').trim()
+  const bounded = [...seen].slice(-500)
+  state[workspace] = {
+    repoPath,
+    head: headHash !== '' ? headHash : record.head,
+    hashes: bounded,
+    updatedAt: new Date().toISOString(),
+    ...(output === result ? {} : { fellBack: true }),
+  }
+  writeHistoryState(root, state)
+  return { ok: true, repoPath, added, skipped: commits.length - added, fellBack: fallback, head: state[workspace].head }
+}
+
+/**
+ * Commit hashes already present in a workspace history layer, read from the entries
+ * themselves. This is the authoritative record: state/history.json is an optimisation.
+ * @returns a Set of full hashes.
+ */
+export function recordedCommits(root, workspace) {
+  const found = new Set()
+  for (const topic of readLayerTopics(root, 'workspace', workspace, 'history')) {
+    for (const match of topic.text.matchAll(/^Commit: ([0-9a-f]{7,40})$/gm)) found.add(match[1])
+  }
+  return found
+}
+
+/** Commits already recorded for a workspace, from bookkeeping only. */
+export function recordedHashes(root, workspace) {
+  return new Set(readHistoryState(root)[workspace]?.hashes ?? [])
+}
+/** True when a path looks like a repository the store can read history from. */
+export function looksLikeRepo(path) {
+  return typeof path === 'string' && path !== '' && existsSync(join(path, '.git'))
+}