@llman-sdd/core 0.3.0 → 0.5.0

package/src/report/graph/analysis.ts

@@ -0,0 +1,152 @@
+import { parseDeps } from './deps.ts';
+import { collectActiveNodes, collectArchivedNodes, collectNodes, proposalFor } from './nodes.ts';
+import {
+  GraphError,
+  type DepEdge,
+  type GraphFsIo,
+  type GraphNode,
+  type ScopeKind,
+} from './types.ts';
+
+interface RelationMaps {
+  depends: Map<string, string[]>;
+  reverse: Map<string, string[]>;
+  nodeSet: Set<string>;
+}
+
+function buildMaps(io: GraphFsIo, root: string, nodes: GraphNode[]): RelationMaps {
+  const depends = new Map<string, string[]>();
+  const reverse = new Map<string, string[]>();
+  const nodeSet = new Set<string>();
+  for (const node of nodes) {
+    nodeSet.add(node.id);
+    if (!node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      depends.set(node.id, [...(depends.get(node.id) ?? []), dep]);
+      reverse.set(dep, [...(reverse.get(dep) ?? []), node.id]);
+    }
+  }
+  return { depends, reverse, nodeSet };
+}
+
+export function buildDefaultNodes(
+  io: GraphFsIo,
+  root: string,
+  kinds: ScopeKind[],
+  depth: number,
+  maxScanDepth?: number,
+): GraphNode[] {
+  const nodes = collectNodes(io, root, kinds, maxScanDepth);
+  // depth 0 = 仅 scope 内节点(human-readable graph):不拉取任何依赖 target。
+  if (depth <= 0) return nodes;
+
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const all = collectNodes(io, root, ['active', 'archived'], maxScanDepth);
+  const allMap = new Map(all.map((n) => [n.id, n]));
+
+  // BFS 沿 depends_on 从 scope 根展开 depth 层(depth 1 即现状的一层依赖拉取;
+  // N >= 2 递归展开)。拉入的依赖 target 若不在 scope 作为节点保留
+  // (present/archived 标记由 allMap 已知节点提供,未知 id 记为 phantom)。
+  let frontier = nodes.filter((n) => n.present).map((n) => n.id);
+  for (let level = 0; level < depth && frontier.length > 0; level++) {
+    const next: string[] = [];
+    for (const id of frontier) {
+      const node = allMap.get(id);
+      if (node === undefined || !node.present) continue;
+      for (const dep of parseDeps(proposalFor(io, root, node))) {
+        if (nodeIds.has(dep)) continue;
+        nodeIds.add(dep);
+        next.push(dep);
+        const existing = allMap.get(dep);
+        if (existing !== undefined) nodes.push(existing);
+        else nodes.push({ id: dep, archived: false, present: false });
+      }
+    }
+    frontier = next;
+  }
+  return nodes;
+}
+
+export function collectEdges(io: GraphFsIo, root: string, nodes: GraphNode[]): DepEdge[] {
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const edges: DepEdge[] = [];
+  for (const node of nodes) {
+    if (!node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      if (nodeIds.has(dep)) edges.push({ from: node.id, to: dep });
+    }
+  }
+  return edges;
+}
+
+export function connectedComponents(nodeIds: string[], edges: DepEdge[]): string[][] {
+  if (nodeIds.length === 0) return [];
+  const parent = new Map<string, string>(nodeIds.map((id) => [id, id]));
+  const find = (x: string): string => {
+    let root = parent.get(x) ?? x;
+    while (parent.get(root) !== root) root = parent.get(root) ?? root;
+    return root;
+  };
+  const union = (a: string, b: string): void => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  for (const edge of edges) union(edge.from, edge.to);
+  const groups = new Map<string, string[]>();
+  for (const id of nodeIds) {
+    const root = find(id);
+    groups.set(root, [...(groups.get(root) ?? []), id]);
+  }
+  return [...groups.values()].toSorted((a, b) => b.length - a.length);
+}
+
+/** Seed neighborhood: bidirectional BFS (depends_on + reverse) over both sets. */
+export function buildSeedNeighborhood(
+  io: GraphFsIo,
+  root: string,
+  seedId: string,
+  maxDepth: number,
+  maxScanDepth?: number,
+): GraphNode[] {
+  const resolved = resolveSeedId(io, root, seedId, maxScanDepth);
+  const allNodes = collectNodes(io, root, ['active', 'archived'], maxScanDepth);
+  const nodeMap = new Map(allNodes.map((n) => [n.id, n]));
+  if (!nodeMap.has(resolved)) {
+    const prefix = resolved.split('-')[0] ?? '';
+    const suggestions = [...nodeMap.keys()].filter((k) => k.startsWith(prefix));
+    const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : '';
+    throw new GraphError(`change '${seedId}' not found.${hint}`);
+  }
+  const maps = buildMaps(io, root, allNodes);
+  const visited = new Set<string>([resolved]);
+  const queue: [string, number][] = [[resolved, 0]];
+  while (queue.length > 0) {
+    const [current, depth] = queue.shift() as [string, number];
+    if (depth >= maxDepth) continue;
+    const neighbors = [...(maps.depends.get(current) ?? []), ...(maps.reverse.get(current) ?? [])];
+    for (const neighbor of neighbors) {
+      if (maps.nodeSet.has(neighbor) && !visited.has(neighbor)) {
+        visited.add(neighbor);
+        queue.push([neighbor, depth + 1]);
+      }
+    }
+  }
+  const result = [...visited]
+    .filter((id) => nodeMap.has(id))
+    .map((id) => nodeMap.get(id) as GraphNode);
+  result.sort((a, b) => a.id.localeCompare(b.id));
+  return result;
+}
+
+function resolveSeedId(io: GraphFsIo, root: string, seedId: string, maxScanDepth?: number): string {
+  const active = collectActiveNodes(io, root, maxScanDepth);
+  const archived = collectArchivedNodes(io, root);
+  const all = [...active.map((n) => n.id), ...archived.map((n) => n.id)];
+  if (all.includes(seedId)) return seedId;
+  const viaPrefix = all.filter((id) => id.startsWith(seedId));
+  if (viaPrefix.length === 1) return viaPrefix[0] ?? seedId;
+  const viaArchivedPrefix = archived.map((n) => n.id).filter((id) => id.startsWith(seedId));
+  if (viaArchivedPrefix.length === 1) return viaArchivedPrefix[0] ?? seedId;
+  return seedId;
+}

package/src/report/graph/deps.ts

@@ -0,0 +1,30 @@
+/** Extract depends_on entries (flow + block styles, r30). */
+import { extractFrontmatter } from '../../change/frontmatter.ts';
+
+export function parseDeps(proposal: string): string[] {
+  const fm = extractFrontmatter(proposal);
+  const deps: string[] = [];
+  if (!fm) return deps;
+  let inDeps = false;
+  for (const line of fm.split('\n')) {
+    const flow = line.match(/^depends_on:\s*\[([^\]]*)\]\s*$/u);
+    if (flow) {
+      for (const item of flow[1]?.split(',') ?? []) {
+        const dep = item.trim().replaceAll(/^['"]|['"]$/gu, '');
+        if (dep !== '' && !/^[0-9]+$/u.test(dep)) deps.push(dep);
+      }
+      inDeps = false;
+      continue;
+    }
+    if (/^depends_on:\s*$/u.test(line)) {
+      inDeps = true;
+      continue;
+    }
+    if (inDeps) {
+      const m = line.match(/^\s*-\s+(\S+)/u);
+      if (m?.[1] && !/^[0-9]+$/u.test(m[1])) deps.push(m[1]);
+      else if (line.trim() !== '') inDeps = false;
+    }
+  }
+  return deps;
+}

package/src/report/graph/graphData.ts

@@ -0,0 +1,53 @@
+import { buildDefaultNodes, buildSeedNeighborhood, collectEdges } from './analysis.ts';
+import {
+  GraphError,
+  type GraphDataIr,
+  type GraphEdgeIr,
+  type GraphFsIo,
+  type GraphNode,
+  type GraphNodeIr,
+  type GraphOptions,
+  type ScopeKind,
+} from './types.ts';
+
+export function parseScope(scope: string): ScopeKind[] {
+  if (scope === 'all') return ['active', 'archived'];
+  const kinds: ScopeKind[] = [];
+  for (const part of scope.split(',')) {
+    const t = part.trim();
+    if (t === 'active') kinds.push('active');
+    else if (t === 'archived') kinds.push('archived');
+    else {
+      throw new GraphError(
+        `Unknown scope: '${t}'. Supported: active, archived, all (or comma-separated like active,archived)`,
+      );
+    }
+  }
+  if (kinds.length === 0) throw new GraphError('Scope cannot be empty');
+  return kinds;
+}
+
+/** Structured graph IR (cli-output-cleanup): same traversal graphMermaid
+ * renders, exposed for `graph --output json|toon`. Empty-node cases yield an
+ * empty nodes array (the mermaid placeholder line is a render concern). */
+export function graphData(io: GraphFsIo, root: string, opts: GraphOptions = {}): GraphDataIr {
+  const scope = opts.scope ?? 'active';
+  const kinds = parseScope(scope);
+
+  let nodes: GraphNode[];
+  if (opts.seed !== undefined) {
+    nodes = buildSeedNeighborhood(io, root, opts.seed, opts.depth ?? 1, opts.maxScanDepth);
+  } else {
+    nodes = buildDefaultNodes(io, root, kinds, opts.depth ?? 1, opts.maxScanDepth);
+  }
+  const irNodes: GraphNodeIr[] = nodes.map((n) => ({
+    id: n.id,
+    archived: n.archived,
+    present: n.present,
+  }));
+  const irEdges: GraphEdgeIr[] =
+    nodes.length === 0
+      ? []
+      : collectEdges(io, root, nodes).map((e) => ({ from: e.from, to: e.to }));
+  return { scope, nodes: irNodes, edges: irEdges };
+}

package/src/report/graph/nodes.ts

@@ -0,0 +1,130 @@
+import { frozenCardIdOf, isFrozenCard } from '../../archive/frozenCard.ts';
+import { CHANGES_DIR } from '../../change/lifecycle.ts';
+import type { GraphFsIo, GraphNode, ScopeKind } from './types.ts';
+
+function extractArchivedId(name: string): string | null {
+  const m = name.match(/^\d{4}-\d{2}-\d{2}-(.+)$/u);
+  return m ? (m[1] ?? null) : null;
+}
+
+/** Active nodes: dirs (recursively, depth-limited) with a proposal.md (r58). */
+export function collectActiveNodes(
+  io: GraphFsIo,
+  root: string,
+  maxScanDepth?: number,
+): GraphNode[] {
+  const out: GraphNode[] = [];
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return out;
+  const maxDepth = maxScanDepth ?? 8;
+  const visit = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        out.push({ id: name, archived: false, present: true });
+      } else if (depth < maxDepth) {
+        visit(child, depth + 1);
+      }
+    }
+  };
+  visit(changesDir, 1);
+  return out;
+}
+
+/**
+ * Archived nodes: dated dirs (as before) plus flat frozen cards
+ * `<YYYY-MM-DD>-<id>.yaml` (r54 extension — cards are archived changes whose
+ * body lives in the cold backup; the card filename carries the id).
+ */
+export function collectArchivedNodes(io: GraphFsIo, root: string): GraphNode[] {
+  const archiveDir = `${root}/${CHANGES_DIR}/archive`;
+  if (!io.exists(archiveDir) || !io.isDirectory(archiveDir)) return [];
+  const out: GraphNode[] = [];
+  const seen = new Set<string>();
+  for (const name of io.listDir(archiveDir)) {
+    const child = `${archiveDir}/${name}`;
+    if (io.isDirectory(child)) {
+      const id = extractArchivedId(name);
+      if (id !== null && !seen.has(id)) {
+        seen.add(id);
+        out.push({ id, archived: true, present: true });
+      }
+    } else if (isFrozenCard(name)) {
+      const id = frozenCardIdOf(name);
+      if (id !== null && !seen.has(id)) {
+        seen.add(id);
+        out.push({ id, archived: true, present: true });
+      }
+    }
+  }
+  return out;
+}
+
+export function collectNodes(
+  io: GraphFsIo,
+  root: string,
+  kinds: ScopeKind[],
+  maxScanDepth?: number,
+): GraphNode[] {
+  const combined: GraphNode[] = [];
+  const seen = new Set<string>();
+  for (const kind of kinds) {
+    const nodes =
+      kind === 'active'
+        ? collectActiveNodes(io, root, maxScanDepth)
+        : collectArchivedNodes(io, root);
+    for (const node of nodes) {
+      if (!seen.has(node.id)) {
+        seen.add(node.id);
+        combined.push(node);
+      }
+    }
+  }
+  return combined;
+}
+
+export function proposalFor(io: GraphFsIo, root: string, node: GraphNode): string {
+  if (node.archived) {
+    const archiveDir = `${root}/${CHANGES_DIR}/archive`;
+    // latest matching strategy: pick the newest date-prefixed dir
+    let best = '';
+    let bestDate = '';
+    for (const name of io.listDir(archiveDir)) {
+      const id = isFrozenCard(name) ? frozenCardIdOf(name) : extractArchivedId(name);
+      if (id !== node.id) continue;
+      const date = name.slice(0, 10);
+      if (best === '' || date > bestDate) {
+        best = name;
+        bestDate = date;
+      }
+    }
+    const p = `${archiveDir}/${best}/proposal.md`;
+    if (io.exists(p)) return io.readText(p);
+    // Frozen card fallback (r54): dir gone, body in cold backup — read the
+    // card (frontmatter incl. depends_on) so dependency edges survive freeze.
+    const card = isFrozenCard(best) ? `${archiveDir}/${best}` : `${archiveDir}/${best}.yaml`;
+    if (io.exists(card)) return io.readText(card);
+    return '';
+  }
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  const found: string[] = [];
+  const visit = (dir: string): void => {
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        // leaf change dir — do not descend further
+        if (name === node.id) found.push(`${child}/proposal.md`);
+        continue;
+      }
+      visit(child);
+    }
+  };
+  visit(changesDir);
+  if (found.length === 0) return '';
+  return io.readText(found[0] ?? '');
+}

package/src/report/graph/render.ts

@@ -0,0 +1,83 @@
+import {
+  buildDefaultNodes,
+  buildSeedNeighborhood,
+  collectEdges,
+  connectedComponents,
+} from './analysis.ts';
+import { parseScope } from './graphData.ts';
+import type { DepEdge, GraphFsIo, GraphNode, GraphOptions } from './types.ts';
+
+function componentLabel(nodes: GraphNode[], ids: Set<string>): string {
+  const comp = nodes.filter((n) => ids.has(n.id));
+  const allActive = comp.every((n) => !n.archived && n.present);
+  const allArchived = comp.every((n) => n.archived);
+  if (allActive) return 'Active';
+  if (allArchived) return 'Done';
+  return 'Mixed';
+}
+
+const sanitize = (id: string): string => id.replaceAll('-', '_');
+
+export function graphMermaid(io: GraphFsIo, root: string, opts: GraphOptions = {}): string[] {
+  const scope = opts.scope ?? 'active';
+  const kinds = parseScope(scope);
+
+  let nodes: GraphNode[];
+  if (opts.seed !== undefined) {
+    nodes = buildSeedNeighborhood(io, root, opts.seed, opts.depth ?? 1, opts.maxScanDepth);
+  } else {
+    nodes = buildDefaultNodes(io, root, kinds, opts.depth ?? 1, opts.maxScanDepth);
+  }
+
+  if (nodes.length === 0) {
+    return [
+      'flowchart TD',
+      opts.seed !== undefined
+        ? `    empty["Change '${opts.seed}' not found or has no relationships"]`
+        : `    empty["No changes in scope '${scope}'"]`,
+    ];
+  }
+
+  const edges = collectEdges(io, root, nodes);
+  const nodeIds = nodes.map((n) => n.id);
+  const components = connectedComponents(nodeIds, edges);
+  const hasArchived = nodes.some((n) => n.archived);
+  const hasMissing = nodes.some((n) => !n.present);
+
+  const lines = ['flowchart TD'];
+  if (components.length > 1) {
+    components.forEach((comp, idx) => {
+      const ids = new Set(comp);
+      const label = componentLabel(nodes, ids);
+      lines.push(`    subgraph sg${idx + 1}["${label}"]`);
+      renderNodesAndEdges(nodes, edges, ids, lines, true);
+      lines.push('    end');
+    });
+  } else {
+    renderNodesAndEdges(nodes, edges, new Set(nodeIds), lines, false);
+  }
+  if (hasArchived) lines.push('    classDef archived fill:#d4edda,stroke:#28a745,color:#333');
+  if (hasMissing) lines.push('    classDef missing fill:#f8d7da,stroke:#dc3545,color:#333');
+  return lines;
+}
+
+function renderNodesAndEdges(
+  nodes: GraphNode[],
+  edges: DepEdge[],
+  ids: Set<string>,
+  lines: string[],
+  indented: boolean,
+): void {
+  const pad = indented ? '        ' : '    ';
+  for (const node of nodes) {
+    if (!ids.has(node.id)) continue;
+    if (!node.present) lines.push(`${pad}${sanitize(node.id)}["${node.id} ⚠ missing"]:::missing`);
+    else if (node.archived)
+      lines.push(`${pad}${sanitize(node.id)}["${node.id} ✓ done"]:::archived`);
+    else lines.push(`${pad}${sanitize(node.id)}["${node.id}"]`);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) continue;
+    lines.push(`${pad}${sanitize(edge.from)} -->|depends on| ${sanitize(edge.to)}`);
+  }
+}

package/src/report/graph/types.ts

@@ -0,0 +1,47 @@
+export interface GraphFsIo {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  listDir(path: string): string[];
+  isDirectory(path: string): boolean;
+}
+
+export interface GraphNode {
+  id: string;
+  archived: boolean;
+  /** true = directory on disk; false = phantom (frozen/removed dependency). */
+  present: boolean;
+}
+
+export interface DepEdge {
+  from: string;
+  to: string;
+}
+
+export class GraphError extends Error {}
+
+export type ScopeKind = 'active' | 'archived';
+
+export interface GraphOptions {
+  scope?: string;
+  depth?: number;
+  seed?: string;
+  /** r58: max recursion depth when scanning changes/ for proposals (default 8). */
+  maxScanDepth?: number;
+}
+
+export interface GraphNodeIr {
+  id: string;
+  archived: boolean;
+  present: boolean;
+}
+
+export interface GraphEdgeIr {
+  from: string;
+  to: string;
+}
+
+export interface GraphDataIr {
+  scope: string;
+  nodes: GraphNodeIr[];
+  edges: GraphEdgeIr[];
+}