@grafema/util 0.3.0-beta

package/src/knowledge/git-queries.ts

@@ -0,0 +1,269 @@
+/**
+ * Git Query Functions for KnowledgeBase
+ *
+ * Provides analytical queries over git data (COMMIT, AUTHOR nodes)
+ * stored in the KnowledgeBase. Operates on KBNode arrays loaded from
+ * YAML files into the KB index.
+ *
+ * COMMIT nodes carry raw YAML fields: hash, message, author_ref, date, files.
+ * AUTHOR nodes carry: name, emails, aliases.
+ * These are accessed via type assertion since they're extra properties
+ * on KBNode objects loaded from YAML frontmatter.
+ */
+
+import type { KBNode } from './types.js';
+import type { KnowledgeBase } from './KnowledgeBase.js';
+
+// -- Public result types --
+
+export interface ChurnEntry {
+  path: string;
+  changeCount: number;
+  totalAdded: number;
+  totalRemoved: number;
+}
+
+export interface CoChangeEntry {
+  path: string;
+  coChangeCount: number;
+  support: number;
+}
+
+export interface OwnershipEntry {
+  authorId: string;
+  authorName: string;
+  commits: number;
+  linesAdded: number;
+  linesRemoved: number;
+}
+
+export interface ArchaeologyEntry {
+  path: string;
+  lastCommitHash: string;
+  lastCommitDate: string;
+  lastAuthor: string;
+  firstCommitDate: string;
+  firstAuthor: string;
+}
+
+// -- Internal raw-data accessors --
+
+interface RawCommitFile {
+  path: string;
+  added: number;
+  removed: number;
+}
+
+function getCommitHash(node: KBNode): string {
+  return (node as any).hash ?? '';
+}
+
+function getCommitDate(node: KBNode): string {
+  return (node as any).date ?? '';
+}
+
+function getCommitFiles(node: KBNode): RawCommitFile[] {
+  return (node as any).files ?? [];
+}
+
+function getCommitAuthorRef(node: KBNode): string {
+  return (node as any).author_ref ?? '';
+}
+
+function getAuthorName(node: KBNode): string {
+  return (node as any).name ?? '';
+}
+
+// -- Query functions --
+
+/**
+ * Compute file churn: how many commits touch each file and total lines added/removed.
+ *
+ * @param kb - KnowledgeBase instance (must be loaded)
+ * @param opts.limit - Return only the top N entries
+ * @param opts.since - ISO date string; only consider commits on or after this date
+ * @returns Churn entries sorted by changeCount descending
+ */
+export async function getChurn(
+  kb: KnowledgeBase,
+  opts?: { limit?: number; since?: string },
+): Promise<ChurnEntry[]> {
+  const commits = await kb.queryNodes({ type: 'COMMIT' });
+
+  const filtered = opts?.since
+    ? commits.filter(c => getCommitDate(c) >= opts.since!)
+    : commits;
+
+  const map = new Map<string, ChurnEntry>();
+
+  for (const commit of filtered) {
+    for (const file of getCommitFiles(commit)) {
+      let entry = map.get(file.path);
+      if (!entry) {
+        entry = { path: file.path, changeCount: 0, totalAdded: 0, totalRemoved: 0 };
+        map.set(file.path, entry);
+      }
+      entry.changeCount += 1;
+      entry.totalAdded += file.added;
+      entry.totalRemoved += file.removed;
+    }
+  }
+
+  const sorted = Array.from(map.values()).sort((a, b) => b.changeCount - a.changeCount);
+
+  return opts?.limit ? sorted.slice(0, opts.limit) : sorted;
+}
+
+/**
+ * Find files that frequently change together with the given file.
+ *
+ * For every commit that touches `filePath`, counts how many of those commits
+ * also touch each other file. `support` is the ratio of co-change count to
+ * the total number of commits touching `filePath`.
+ *
+ * @param kb - KnowledgeBase instance (must be loaded)
+ * @param filePath - The file to find co-changes for
+ * @param opts.minSupport - Minimum support threshold (default 0.1 = 10%)
+ * @returns Co-change entries sorted by coChangeCount descending
+ */
+export async function getCoChanges(
+  kb: KnowledgeBase,
+  filePath: string,
+  opts?: { minSupport?: number },
+): Promise<CoChangeEntry[]> {
+  const commits = await kb.queryNodes({ type: 'COMMIT' });
+  const minSupport = opts?.minSupport ?? 0.1;
+
+  // Find commits that touch the target file
+  const touchingCommits = commits.filter(c =>
+    getCommitFiles(c).some(f => f.path === filePath),
+  );
+
+  const totalTouching = touchingCommits.length;
+  if (totalTouching === 0) return [];
+
+  // Count co-occurrences of other files
+  const coMap = new Map<string, number>();
+
+  for (const commit of touchingCommits) {
+    for (const file of getCommitFiles(commit)) {
+      if (file.path === filePath) continue;
+      coMap.set(file.path, (coMap.get(file.path) ?? 0) + 1);
+    }
+  }
+
+  const entries: CoChangeEntry[] = [];
+
+  for (const [path, count] of coMap) {
+    const support = count / totalTouching;
+    if (support >= minSupport) {
+      entries.push({ path, coChangeCount: count, support });
+    }
+  }
+
+  return entries.sort((a, b) => b.coChangeCount - a.coChangeCount);
+}
+
+/**
+ * Compute ownership of a file: who committed changes and how much.
+ *
+ * Groups commits touching `filePath` by author_ref, sums commit count and
+ * lines added/removed. Looks up author names from AUTHOR nodes in the KB.
+ *
+ * @param kb - KnowledgeBase instance (must be loaded)
+ * @param filePath - The file to compute ownership for
+ * @returns Ownership entries sorted by commits descending
+ */
+export async function getOwnership(
+  kb: KnowledgeBase,
+  filePath: string,
+): Promise<OwnershipEntry[]> {
+  const commits = await kb.queryNodes({ type: 'COMMIT' });
+  const authors = await kb.queryNodes({ type: 'AUTHOR' });
+
+  // Build author name lookup: id -> name
+  const authorNameById = new Map<string, string>();
+  for (const author of authors) {
+    authorNameById.set(author.id, getAuthorName(author));
+  }
+
+  // Accumulate per-author stats
+  const map = new Map<string, { commits: number; linesAdded: number; linesRemoved: number }>();
+
+  for (const commit of commits) {
+    const files = getCommitFiles(commit);
+    const fileEntry = files.find(f => f.path === filePath);
+    if (!fileEntry) continue;
+
+    const authorRef = getCommitAuthorRef(commit);
+    let stats = map.get(authorRef);
+    if (!stats) {
+      stats = { commits: 0, linesAdded: 0, linesRemoved: 0 };
+      map.set(authorRef, stats);
+    }
+    stats.commits += 1;
+    stats.linesAdded += fileEntry.added;
+    stats.linesRemoved += fileEntry.removed;
+  }
+
+  const entries: OwnershipEntry[] = [];
+
+  for (const [authorId, stats] of map) {
+    entries.push({
+      authorId,
+      authorName: authorNameById.get(authorId) ?? authorId,
+      commits: stats.commits,
+      linesAdded: stats.linesAdded,
+      linesRemoved: stats.linesRemoved,
+    });
+  }
+
+  return entries.sort((a, b) => b.commits - a.commits);
+}
+
+/**
+ * Dig into the history of a file: when it was first created, last modified, and by whom.
+ *
+ * @param kb - KnowledgeBase instance (must be loaded)
+ * @param filePath - The file to investigate
+ * @returns Archaeology entry with first/last commit info, or empty strings if no commits found
+ */
+export async function getArchaeology(
+  kb: KnowledgeBase,
+  filePath: string,
+): Promise<ArchaeologyEntry> {
+  const commits = await kb.queryNodes({ type: 'COMMIT' });
+
+  // Filter to commits touching this file
+  const touching = commits.filter(c =>
+    getCommitFiles(c).some(f => f.path === filePath),
+  );
+
+  if (touching.length === 0) {
+    return {
+      path: filePath,
+      lastCommitHash: '',
+      lastCommitDate: '',
+      lastAuthor: '',
+      firstCommitDate: '',
+      firstAuthor: '',
+    };
+  }
+
+  // Sort by date ascending
+  const sorted = touching.sort((a, b) =>
+    getCommitDate(a).localeCompare(getCommitDate(b)),
+  );
+
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+
+  return {
+    path: filePath,
+    lastCommitHash: getCommitHash(last),
+    lastCommitDate: getCommitDate(last),
+    lastAuthor: getCommitAuthorRef(last),
+    firstCommitDate: getCommitDate(first),
+    firstAuthor: getCommitAuthorRef(first),
+  };
+}

package/src/knowledge/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Knowledge Base — persistent knowledge layer for Grafema
+ */
+
+export { KnowledgeBase } from './KnowledgeBase.js';
+export { SemanticAddressResolver, parseSemanticAddress } from './SemanticAddressResolver.js';
+export type { ResolverBackend } from './SemanticAddressResolver.js';
+export { parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge } from './parser.js';
+export type {
+  KBNodeType,
+  KBLifecycle,
+  KBScope,
+  KBNodeBase,
+  KBDecision,
+  KBFact,
+  KBSession,
+  KBNode,
+  KBEdge,
+  KBStats,
+  KBQueryFilter,
+  ParsedSemanticAddress,
+  ResolvedAddress,
+  DanglingCodeRef,
+} from './types.js';
+export { parseYamlArrayFile } from './parser.js';
+export { GitIngest, parseGitLog, normalizeAuthors } from './git-ingest.js';
+export type { RawCommit, FileChange, AuthorEntry, CommitEntry, IngestResult, Meta } from './git-ingest.js';
+export { getChurn, getCoChanges, getOwnership, getArchaeology } from './git-queries.js';
+export type { ChurnEntry, CoChangeEntry, OwnershipEntry, ArchaeologyEntry } from './git-queries.js';

package/src/knowledge/parser.ts

@@ -0,0 +1,294 @@
+/**
+ * Knowledge Base Parser
+ *
+ * Parses markdown files with YAML frontmatter into KBNode objects.
+ * Serializes KBNode objects back to markdown format.
+ */
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from 'fs';
+import { dirname } from 'path';
+import type { KBNode, KBNodeType, KBEdge, KBLifecycle, KBDecision, KBFact, KBSession, KBScope } from './types.js';
+
+const VALID_TYPES: KBNodeType[] = ['DECISION', 'FACT', 'SESSION', 'COMMIT', 'FILE_CHANGE', 'AUTHOR', 'TICKET', 'INCIDENT'];
+const ID_PATTERN = /^kb:[a-z_]+:[a-z0-9_-]+$/;
+
+/**
+ * Split markdown content into YAML frontmatter and body.
+ */
+export function parseFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith('---\n') && !trimmed.startsWith('---\r\n')) {
+    throw new Error('Missing frontmatter: file must start with ---');
+  }
+
+  // Find closing --- delimiter
+  const firstNewline = trimmed.indexOf('\n');
+  const rest = trimmed.slice(firstNewline + 1);
+  const closingIndex = rest.indexOf('\n---');
+
+  if (closingIndex === -1) {
+    throw new Error('Missing frontmatter: no closing --- delimiter found');
+  }
+
+  const yamlContent = rest.slice(0, closingIndex);
+  const body = rest.slice(closingIndex + 4).replace(/^\r?\n/, ''); // skip \n--- and leading newline
+
+  const frontmatter = parseYaml(yamlContent) as Record<string, unknown>;
+  if (!frontmatter || typeof frontmatter !== 'object') {
+    throw new Error('Invalid frontmatter: YAML must be an object');
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Derive lifecycle from file path.
+ * declared/ → declared, derived/ → derived, synced/ → synced
+ */
+function deriveLifecycle(filePath: string): KBLifecycle {
+  if (filePath.includes('/derived/') || filePath.includes('\\derived\\')) return 'derived';
+  if (filePath.includes('/synced/') || filePath.includes('\\synced\\')) return 'synced';
+  return 'declared'; // default
+}
+
+/**
+ * Validate and construct a typed KBNode from parsed frontmatter and body.
+ */
+export function parseKBNode(frontmatter: Record<string, unknown>, body: string, filePath: string): KBNode {
+  // Required: id
+  const id = frontmatter.id;
+  if (typeof id !== 'string' || !id) {
+    throw new Error(`Missing required field "id" in ${filePath}`);
+  }
+  if (!ID_PATTERN.test(id)) {
+    throw new Error(`Invalid ID format "${id}" in ${filePath}. Must match kb:<type>:<slug> (lowercase, hyphens, underscores, digits)`);
+  }
+
+  // Required: type
+  const type = frontmatter.type;
+  if (typeof type !== 'string' || !VALID_TYPES.includes(type as KBNodeType)) {
+    throw new Error(`Invalid or missing type "${type}" in ${filePath}. Must be one of: ${VALID_TYPES.join(', ')}`);
+  }
+
+  const lifecycle = deriveLifecycle(filePath);
+
+  // Base node
+  const base: KBNode = {
+    id: id as string,
+    type: type as KBNodeType,
+    projections: Array.isArray(frontmatter.projections) ? frontmatter.projections as string[] : [],
+    created: String(frontmatter.created ?? ''),
+    content: body.trim(),
+    filePath,
+    lifecycle,
+  };
+
+  // Optional base fields
+  if (frontmatter.subtype) base.subtype = String(frontmatter.subtype);
+  if (frontmatter.scope) base.scope = frontmatter.scope as KBScope;
+  if (frontmatter.source) base.source = String(frontmatter.source);
+  if (Array.isArray(frontmatter.relates_to)) base.relates_to = frontmatter.relates_to as string[];
+
+  // Type-specific fields
+  switch (type) {
+    case 'DECISION': {
+      const decision = base as KBDecision;
+      decision.status = (frontmatter.status as KBDecision['status']) ?? 'proposed';
+      if (frontmatter.effective_from) decision.effective_from = String(frontmatter.effective_from);
+      if (frontmatter.effective_until) decision.effective_until = String(frontmatter.effective_until);
+      if (Array.isArray(frontmatter.applies_to)) decision.applies_to = frontmatter.applies_to as string[];
+      if (frontmatter.superseded_by) decision.superseded_by = String(frontmatter.superseded_by);
+      return decision;
+    }
+    case 'FACT': {
+      const fact = base as KBFact;
+      if (frontmatter.confidence) fact.confidence = frontmatter.confidence as KBFact['confidence'];
+      if (frontmatter.superseded_by) fact.superseded_by = String(frontmatter.superseded_by);
+      return fact;
+    }
+    case 'SESSION': {
+      const session = base as KBSession;
+      if (frontmatter.task_id) session.task_id = String(frontmatter.task_id);
+      if (frontmatter.session_path) session.session_path = String(frontmatter.session_path);
+      if (Array.isArray(frontmatter.produced)) session.produced = frontmatter.produced as string[];
+      return session;
+    }
+    default:
+      return base;
+  }
+}
+
+/**
+ * Serialize a KBNode back to markdown with YAML frontmatter.
+ */
+export function serializeKBNode(node: KBNode): string {
+  // Build frontmatter object (exclude computed/internal fields)
+  const fm: Record<string, unknown> = {
+    id: node.id,
+    type: node.type,
+  };
+
+  // Decision-specific
+  if (node.type === 'DECISION') {
+    const d = node as KBDecision;
+    fm.status = d.status;
+    if (d.applies_to?.length) fm.applies_to = d.applies_to;
+    if (d.effective_from) fm.effective_from = d.effective_from;
+    if (d.effective_until) fm.effective_until = d.effective_until;
+    if (d.superseded_by) fm.superseded_by = d.superseded_by;
+  }
+
+  // Fact-specific
+  if (node.type === 'FACT') {
+    const f = node as KBFact;
+    if (f.confidence) fm.confidence = f.confidence;
+    if (f.superseded_by) fm.superseded_by = f.superseded_by;
+  }
+
+  // Session-specific
+  if (node.type === 'SESSION') {
+    const s = node as KBSession;
+    if (s.task_id) fm.task_id = s.task_id;
+    if (s.session_path) fm.session_path = s.session_path;
+    if (s.produced?.length) fm.produced = s.produced;
+  }
+
+  // Common optional fields
+  if (node.subtype) fm.subtype = node.subtype;
+  if (node.scope) fm.scope = node.scope;
+  if (node.projections.length > 0) fm.projections = node.projections;
+  if (node.source) fm.source = node.source;
+  if (node.relates_to?.length) fm.relates_to = node.relates_to;
+  fm.created = node.created;
+
+  const yamlStr = stringifyYaml(fm, { lineWidth: 0 }).trimEnd();
+  const body = node.content ? `\n${node.content}\n` : '\n';
+
+  return `---\n${yamlStr}\n---\n${body}`;
+}
+
+/**
+ * Parse edges.yaml file into KBEdge array.
+ */
+export function parseEdgesFile(filePath: string): KBEdge[] {
+  if (!existsSync(filePath)) return [];
+
+  const content = readFileSync(filePath, 'utf-8');
+  const parsed = parseYaml(content);
+
+  if (!parsed) return [];
+  if (!Array.isArray(parsed)) {
+    throw new Error(`edges.yaml must be a YAML array, got ${typeof parsed}`);
+  }
+
+  return parsed.map((entry: unknown, i: number) => {
+    if (!entry || typeof entry !== 'object') {
+      throw new Error(`Edge at index ${i} is not an object`);
+    }
+    const e = entry as Record<string, unknown>;
+    if (!e.type || !e.from || !e.to) {
+      throw new Error(`Edge at index ${i} missing required fields (type, from, to)`);
+    }
+    const edge: KBEdge = {
+      type: String(e.type),
+      from: String(e.from),
+      to: String(e.to),
+    };
+    if (e.evidence) edge.evidence = String(e.evidence);
+    return edge;
+  });
+}
+
+/**
+ * Parse a YAML file containing an array of node objects (e.g., commits/2026-03.yaml, authors.yaml).
+ * Each entry must have at least a `type` field. ID is generated based on type:
+ * - COMMIT → kb:commit:<short-hash>
+ * - AUTHOR → kb:author:<slug>
+ * - Others → kb:<type>:<index>
+ */
+export function parseYamlArrayFile(filePath: string): KBNode[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const parsed = parseYaml(content);
+
+  if (!Array.isArray(parsed)) {
+    throw new Error(`YAML array file must contain an array, got ${typeof parsed} in ${filePath}`);
+  }
+
+  return parsed.map((entry: unknown, index: number) => {
+    if (!entry || typeof entry !== 'object') {
+      throw new Error(`Entry at index ${index} is not an object in ${filePath}`);
+    }
+    const e = entry as Record<string, unknown>;
+
+    const type = e.type;
+    if (typeof type !== 'string' || !VALID_TYPES.includes(type as KBNodeType)) {
+      throw new Error(`Invalid or missing type "${type}" at index ${index} in ${filePath}. Must be one of: ${VALID_TYPES.join(', ')}`);
+    }
+
+    // Generate ID based on type
+    let id: string;
+    switch (type) {
+      case 'COMMIT':
+        id = `kb:commit:${String(e.hash ?? '').slice(0, 8)}`;
+        break;
+      case 'AUTHOR': {
+        if (typeof e.id === 'string' && e.id.startsWith('kb:author:')) {
+          id = e.id;
+        } else if (typeof e.id === 'string') {
+          id = `kb:author:${e.id}`;
+        } else {
+          const name = String(e.name ?? '');
+          id = `kb:author:${name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')}`;
+        }
+        break;
+      }
+      default:
+        id = `kb:${type.toLowerCase()}:${index}`;
+        break;
+    }
+
+    const base: KBNode = {
+      id,
+      type: type as KBNodeType,
+      projections: Array.isArray(e.projections) ? e.projections as string[] : [],
+      created: type === 'COMMIT' ? (String(e.date ?? '').split('T')[0]) : '',
+      content: '',
+      filePath,
+      lifecycle: 'derived' as KBLifecycle,
+    };
+
+    // Spread all entry fields onto the node, preserving base fields
+    const node: KBNode = { ...e, ...base } as KBNode;
+
+    return node;
+  });
+}
+
+/**
+ * Append an edge to the edges.yaml file.
+ */
+export function appendEdge(filePath: string, edge: KBEdge): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const entry: Record<string, string> = {
+    type: edge.type,
+    from: edge.from,
+    to: edge.to,
+  };
+  if (edge.evidence) entry.evidence = edge.evidence;
+
+  const yamlEntry = stringifyYaml([entry], { lineWidth: 0 }).trimEnd();
+
+  if (!existsSync(filePath)) {
+    // New file — write with comment header
+    const header = '# Knowledge Graph edges\n# Format: {type, from, to, evidence?}\n\n';
+    appendFileSync(filePath, header + yamlEntry + '\n', 'utf-8');
+  } else {
+    // Append to existing file
+    appendFileSync(filePath, '\n' + yamlEntry + '\n', 'utf-8');
+  }
+}