@lh8ppl/claude-memory-kit 0.1.0 → 0.1.2

package/src/merge-facts.mjs

@@ -1,213 +1,213 @@
-// Fact consolidation (Task 10, refactored in cleanup-layer-2-cross-module-drift).
-// Single public boundary: mergeFacts(opts) → result. See design §3.4.
-//
-// Uses shared modules: tier-paths, frontmatter, audit-log, result-shapes.
-// Composes writeFact() to create the new merged fact, then moves A + B into
-// archive/superseded/ with superseded_by injected. See CLAUDE.md "Shared
-// modules" rule.
-
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { join } from 'node:path';
-import {
-  VALID_TIERS,
-  ID_PATTERN,
-  resolveTierRoot,
-  resolveFactDir,
-} from './tier-paths.mjs';
-import { parse, format } from './frontmatter.mjs';
-import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
-import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.mjs';
-import { writeFact } from './write-fact.mjs';
-
-function listLiveFactFiles(factDir) {
-  if (!existsSync(factDir)) return [];
-  const out = [];
-  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
-    if (!entry.name.endsWith('.md')) continue;
-    if (entry.name === 'INDEX.md') continue;
-    out.push(entry.name);
-  }
-  return out;
-}
-
-function findLiveFactById(factDir, id) {
-  if (!existsSync(factDir)) return null;
-  for (const filename of listLiveFactFiles(factDir)) {
-    const p = join(factDir, filename);
-    if (!statSync(p).isFile()) continue;
-    const { frontmatter, body } = parse(readFileSync(p, 'utf8'));
-    if (frontmatter?.id === id && !frontmatter.deleted_at) {
-      return { id, path: p, frontmatter, body };
-    }
-  }
-  return null;
-}
-
-function moveToSuperseded(match, supersededBy) {
-  const supersededDir = join(match.factDir, 'archive', 'superseded');
-  mkdirSync(supersededDir, { recursive: true });
-  const newPath = join(supersededDir, `${match.id}.md`);
-  const { frontmatter, body } = parse(readFileSync(match.path, 'utf8'));
-  const updated = {
-    superseded_by: supersededBy,
-    ...(frontmatter ?? {}),
-  };
-  writeFileSync(newPath, format({ frontmatter: updated, body }), 'utf8');
-  unlinkSync(match.path);
-  return newPath;
-}
-
-export function mergeFacts(opts = {}) {
-  const {
-    idA,
-    idB,
-    mergedBody,
-    mergedTitle,
-    mergedSlug,
-    mergedType,
-    writeSource,
-    trust,
-    sourceFile,
-    sourceLine,
-    sourceSha1,
-    mergedTags,
-    projectRoot,
-    userDir,
-    now,
-  } = opts;
-
-  const errors = [];
-  if (!idA || !ID_PATTERN.test(idA)) errors.push('idA: must be a valid citation ID');
-  if (!idB || !ID_PATTERN.test(idB)) errors.push('idB: must be a valid citation ID');
-  if (idA && idB && idA === idB) {
-    return errorResult({
-      category: ERROR_CATEGORIES.SCHEMA,
-      errors: [`idA and idB are the same (${idA}); cannot merge a fact with itself`],
-    });
-  }
-  if (!mergedBody || typeof mergedBody !== 'string' || !mergedBody.length) {
-    errors.push('mergedBody: required, non-empty string');
-  }
-  if (!mergedTitle || typeof mergedTitle !== 'string') {
-    errors.push('mergedTitle: required, non-empty string');
-  }
-  // Layer-2 review S4: removed the redundant `mergedSlug` truthy check. The
-  // downstream writeFact owns all slug validation (pattern + presence).
-  // Inconsistent layering disappears; bad slugs surface from writeFact with
-  // a clear schema error.
-  //
-  // Layer-2 review S3: writeSource is now REQUIRED (no compressor default).
-  // Compressor was the most-suspicious default — Task 23 auto-extract and
-  // Task 24 memory-write are NOT compressor-driven. Forcing the caller to
-  // pick avoids accidentally tagging human-curated merges as 'compressor'.
-  if (!writeSource || typeof writeSource !== 'string') {
-    errors.push('writeSource: required (no default). Pick one of user-explicit/auto-extract/compressor/manual-edit/imported.');
-  }
-  if (errors.length > 0) {
-    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
-  }
-
-  const tierA = idA[0];
-  const tierB = idB[0];
-  if (tierA !== tierB) {
-    return errorResult({
-      category: ERROR_CATEGORIES.SCHEMA,
-      errors: [
-        `cross-tier merge not supported: idA tier (${tierA}) ≠ idB tier (${tierB}). Promote one side to the same tier first.`,
-      ],
-    });
-  }
-  const tier = tierA;
-  if (!VALID_TIERS.has(tier)) {
-    return errorResult({
-      category: ERROR_CATEGORIES.SCHEMA,
-      errors: [`invalid tier prefix on ids: ${tier}`],
-    });
-  }
-
-  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
-  const factDir = resolveFactDir(tier, tierRoot);
-
-  const matchA = findLiveFactById(factDir, idA);
-  const matchB = findLiveFactById(factDir, idB);
-  if (!matchA || !matchB) {
-    const missing = [];
-    if (!matchA) missing.push(idA);
-    if (!matchB) missing.push(idB);
-    return notFoundResult({
-      errors: [`no live fact found for ${missing.join(', ')}`],
-    });
-  }
-  matchA.factDir = factDir;
-  matchB.factDir = factDir;
-
-  const typeC =
-    mergedType ?? matchA.frontmatter.type ?? matchB.frontmatter.type;
-
-  const writeResult = writeFact({
-    tier,
-    type: typeC,
-    slug: mergedSlug,
-    title: mergedTitle,
-    body: mergedBody,
-    writeSource,
-    trust: trust ?? 'high',
-    sourceFile: sourceFile ?? matchA.frontmatter.source_file ?? 'merge',
-    sourceLine: sourceLine ?? 1,
-    sourceSha1: sourceSha1 ?? matchA.frontmatter.source_sha1 ?? 'merged',
-    mergedFrom: [idA, idB],
-    tags: mergedTags,
-    projectRoot,
-    userDir,
-  });
-  if (writeResult.action === 'error') {
-    return errorResult({
-      category: writeResult.errorCategory,
-      errors: writeResult.errors,
-    });
-  }
-  // PR-1 blocker B1 fix preserved: writeFact dedup'd to an existing unrelated
-  // fact → return collision error rather than silently retargeting A and B.
-  if (writeResult.action !== 'created') {
-    return errorResult({
-      category: ERROR_CATEGORIES.COLLISION,
-      errors: [
-        `merged body collides with existing fact ${writeResult.id} (writeFact returned ${writeResult.action}${writeResult.skipReason ? ': ' + writeResult.skipReason : ''}); choose a different mergedBody`,
-      ],
-    });
-  }
-
-  const supersededA = moveToSuperseded(matchA, writeResult.id);
-  const supersededB = moveToSuperseded(matchB, writeResult.id);
-
-  const ts = now ?? nowIso();
-  appendAuditEntry(tierRoot, {
-    ts,
-    action: 'merged',
-    tier,
-    id: writeResult.id,
-    reasonCode: REASON_CODES.CURATED_MERGE,
-    paths: {
-      after: writeResult.path,
-      archive: [supersededA, supersededB],
-    },
-    extra: { mergedFrom: [idA, idB] },
-  });
-
-  return {
-    action: 'merged',
-    id: writeResult.id,
-    tier,
-    path: writeResult.path,
-    supersededPaths: [supersededA, supersededB],
-  };
-}
+// Fact consolidation (Task 10, refactored in cleanup-layer-2-cross-module-drift).
+// Single public boundary: mergeFacts(opts) → result. See design §3.4.
+//
+// Uses shared modules: tier-paths, frontmatter, audit-log, result-shapes.
+// Composes writeFact() to create the new merged fact, then moves A + B into
+// archive/superseded/ with superseded_by injected. See CLAUDE.md "Shared
+// modules" rule.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+  VALID_TIERS,
+  ID_PATTERN,
+  resolveTierRoot,
+  resolveFactDir,
+} from './tier-paths.mjs';
+import { parse, format } from './frontmatter.mjs';
+import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.mjs';
+import { writeFact } from './write-fact.mjs';
+
+function listLiveFactFiles(factDir) {
+  if (!existsSync(factDir)) return [];
+  const out = [];
+  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    out.push(entry.name);
+  }
+  return out;
+}
+
+function findLiveFactById(factDir, id) {
+  if (!existsSync(factDir)) return null;
+  for (const filename of listLiveFactFiles(factDir)) {
+    const p = join(factDir, filename);
+    if (!statSync(p).isFile()) continue;
+    const { frontmatter, body } = parse(readFileSync(p, 'utf8'));
+    if (frontmatter?.id === id && !frontmatter.deleted_at) {
+      return { id, path: p, frontmatter, body };
+    }
+  }
+  return null;
+}
+
+function moveToSuperseded(match, supersededBy) {
+  const supersededDir = join(match.factDir, 'archive', 'superseded');
+  mkdirSync(supersededDir, { recursive: true });
+  const newPath = join(supersededDir, `${match.id}.md`);
+  const { frontmatter, body } = parse(readFileSync(match.path, 'utf8'));
+  const updated = {
+    superseded_by: supersededBy,
+    ...(frontmatter ?? {}),
+  };
+  writeFileSync(newPath, format({ frontmatter: updated, body }), 'utf8');
+  unlinkSync(match.path);
+  return newPath;
+}
+
+export function mergeFacts(opts = {}) {
+  const {
+    idA,
+    idB,
+    mergedBody,
+    mergedTitle,
+    mergedSlug,
+    mergedType,
+    writeSource,
+    trust,
+    sourceFile,
+    sourceLine,
+    sourceSha1,
+    mergedTags,
+    projectRoot,
+    userDir,
+    now,
+  } = opts;
+
+  const errors = [];
+  if (!idA || !ID_PATTERN.test(idA)) errors.push('idA: must be a valid citation ID');
+  if (!idB || !ID_PATTERN.test(idB)) errors.push('idB: must be a valid citation ID');
+  if (idA && idB && idA === idB) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`idA and idB are the same (${idA}); cannot merge a fact with itself`],
+    });
+  }
+  if (!mergedBody || typeof mergedBody !== 'string' || !mergedBody.length) {
+    errors.push('mergedBody: required, non-empty string');
+  }
+  if (!mergedTitle || typeof mergedTitle !== 'string') {
+    errors.push('mergedTitle: required, non-empty string');
+  }
+  // Layer-2 review S4: removed the redundant `mergedSlug` truthy check. The
+  // downstream writeFact owns all slug validation (pattern + presence).
+  // Inconsistent layering disappears; bad slugs surface from writeFact with
+  // a clear schema error.
+  //
+  // Layer-2 review S3: writeSource is now REQUIRED (no compressor default).
+  // Compressor was the most-suspicious default — Task 23 auto-extract and
+  // Task 24 memory-write are NOT compressor-driven. Forcing the caller to
+  // pick avoids accidentally tagging human-curated merges as 'compressor'.
+  if (!writeSource || typeof writeSource !== 'string') {
+    errors.push('writeSource: required (no default). Pick one of user-explicit/auto-extract/compressor/manual-edit/imported.');
+  }
+  if (errors.length > 0) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
+  }
+
+  const tierA = idA[0];
+  const tierB = idB[0];
+  if (tierA !== tierB) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [
+        `cross-tier merge not supported: idA tier (${tierA}) ≠ idB tier (${tierB}). Promote one side to the same tier first.`,
+      ],
+    });
+  }
+  const tier = tierA;
+  if (!VALID_TIERS.has(tier)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`invalid tier prefix on ids: ${tier}`],
+    });
+  }
+
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+
+  const matchA = findLiveFactById(factDir, idA);
+  const matchB = findLiveFactById(factDir, idB);
+  if (!matchA || !matchB) {
+    const missing = [];
+    if (!matchA) missing.push(idA);
+    if (!matchB) missing.push(idB);
+    return notFoundResult({
+      errors: [`no live fact found for ${missing.join(', ')}`],
+    });
+  }
+  matchA.factDir = factDir;
+  matchB.factDir = factDir;
+
+  const typeC =
+    mergedType ?? matchA.frontmatter.type ?? matchB.frontmatter.type;
+
+  const writeResult = writeFact({
+    tier,
+    type: typeC,
+    slug: mergedSlug,
+    title: mergedTitle,
+    body: mergedBody,
+    writeSource,
+    trust: trust ?? 'high',
+    sourceFile: sourceFile ?? matchA.frontmatter.source_file ?? 'merge',
+    sourceLine: sourceLine ?? 1,
+    sourceSha1: sourceSha1 ?? matchA.frontmatter.source_sha1 ?? 'merged',
+    mergedFrom: [idA, idB],
+    tags: mergedTags,
+    projectRoot,
+    userDir,
+  });
+  if (writeResult.action === 'error') {
+    return errorResult({
+      category: writeResult.errorCategory,
+      errors: writeResult.errors,
+    });
+  }
+  // PR-1 blocker B1 fix preserved: writeFact dedup'd to an existing unrelated
+  // fact → return collision error rather than silently retargeting A and B.
+  if (writeResult.action !== 'created') {
+    return errorResult({
+      category: ERROR_CATEGORIES.COLLISION,
+      errors: [
+        `merged body collides with existing fact ${writeResult.id} (writeFact returned ${writeResult.action}${writeResult.skipReason ? ': ' + writeResult.skipReason : ''}); choose a different mergedBody`,
+      ],
+    });
+  }
+
+  const supersededA = moveToSuperseded(matchA, writeResult.id);
+  const supersededB = moveToSuperseded(matchB, writeResult.id);
+
+  const ts = now ?? nowIso();
+  appendAuditEntry(tierRoot, {
+    ts,
+    action: 'merged',
+    tier,
+    id: writeResult.id,
+    reasonCode: REASON_CODES.CURATED_MERGE,
+    paths: {
+      after: writeResult.path,
+      archive: [supersededA, supersededB],
+    },
+    extra: { mergedFrom: [idA, idB] },
+  });
+
+  return {
+    action: 'merged',
+    id: writeResult.id,
+    tier,
+    path: writeResult.path,
+    supersededPaths: [supersededA, supersededB],
+  };
+}