clawvault 1.11.2 → 2.0.0

package/dashboard/lib/vault-parser.js

@@ -3,6 +3,8 @@ import * as path from 'node:path';
 import matter from 'gray-matter';
 
 export const WIKI_LINK_REGEX = /\[\[([^\]|]+)(\|[^\]]+)?\]\]/g;
+const HASH_TAG_REGEX = /(^|\s)#([\w-]+)/g;
+const MEMORY_GRAPH_INDEX_PATH = ['.clawvault', 'graph-index.json'];
 
 const MARKDOWN_EXT = '.md';
 const IGNORED_DIRECTORIES = new Set([
@@ -11,6 +13,17 @@ const IGNORED_DIRECTORIES = new Set([
   '.trash',
   'node_modules'
 ]);
+const FRONTMATTER_RELATION_FIELDS = [
+  'related',
+  'depends_on',
+  'dependsOn',
+  'blocked_by',
+  'blocks',
+  'owner',
+  'project',
+  'people',
+  'links'
+];
 
 /**
  * Build a graph from markdown notes in a vault.
@@ -20,10 +33,23 @@ const IGNORED_DIRECTORIES = new Set([
 export async function buildVaultGraph(vaultPath, options = {}) {
   const includeDangling = options.includeDangling !== false;
   const root = path.resolve(vaultPath);
+  const preferIndex = options.preferIndex !== false;
+  const validateIndexFreshness = options.validateIndexFreshness !== false;
+
+  if (preferIndex) {
+    const indexedGraph = await loadGraphFromMemoryIndex(root, {
+      includeDangling,
+      validateFreshness: validateIndexFreshness
+    });
+    if (indexedGraph) {
+      return indexedGraph;
+    }
+  }
+
   const markdownFiles = await collectMarkdownFiles(root);
 
   const nodesById = new Map();
-  const edges = [];
+  const edgesByKey = new Map();
   const edgeSet = new Set();
 
   for (const absoluteFilePath of markdownFiles) {
@@ -37,10 +63,13 @@ export async function buildVaultGraph(vaultPath, options = {}) {
       id,
       title: normalizeString(frontmatter.title) || toDisplayTitle(id),
       category: normalizeString(frontmatter.category) || inferCategory(id),
+      type: inferNodeType(id, frontmatter),
       tags: normalizeTags(frontmatter.tags),
       path: toPosixPath(relativePath),
       missing: false,
-      _outboundTargets: extractWikiLinks(parsed.content)
+      _outboundTargets: extractWikiLinks(parsed.content),
+      _frontmatterRelations: extractFrontmatterRelations(frontmatter),
+      _inlineTags: extractInlineTags(parsed.content)
     });
   }
 
@@ -54,55 +83,117 @@ export async function buildVaultGraph(vaultPath, options = {}) {
     idsByBaseName.set(baseName, existing);
   }
 
+  function ensureUnresolvedNode(targetId) {
+    if (nodesById.has(targetId) || !includeDangling) {
+      return;
+    }
+    nodesById.set(targetId, {
+      id: targetId,
+      title: toDisplayTitle(targetId),
+      category: 'unresolved',
+      type: 'unresolved',
+      tags: [],
+      path: null,
+      missing: true,
+      _outboundTargets: [],
+      _frontmatterRelations: [],
+      _inlineTags: []
+    });
+  }
+
+  function addEdge(sourceId, targetId, type, label) {
+    const edgeKey = `${type}:${sourceId}=>${targetId}${label ? `:${label}` : ''}`;
+    if (edgeSet.has(edgeKey)) {
+      return;
+    }
+    edgeSet.add(edgeKey);
+    edgesByKey.set(edgeKey, {
+      source: sourceId,
+      target: targetId,
+      type,
+      label
+    });
+  }
+
   for (const node of nodesById.values()) {
+    const tagSet = new Set([...(node.tags ?? []), ...(node._inlineTags ?? [])]);
+    for (const inlineTag of tagSet) {
+      const tagNodeId = `tag:${inlineTag.toLowerCase()}`;
+      if (!nodesById.has(tagNodeId)) {
+        nodesById.set(tagNodeId, {
+          id: tagNodeId,
+          title: `#${inlineTag}`,
+          category: 'tag',
+          type: 'tag',
+          tags: [],
+          path: null,
+          missing: false,
+          _outboundTargets: [],
+          _frontmatterRelations: [],
+          _inlineTags: []
+        });
+      }
+      addEdge(node.id, tagNodeId, 'tag');
+    }
+
     for (const rawTarget of node._outboundTargets) {
       const targetId = resolveTargetId(rawTarget, {
         idsByLowercase,
         idsByBaseName,
         includeDangling
       });
-
       if (!targetId) {
         continue;
       }
+      ensureUnresolvedNode(targetId);
+      addEdge(node.id, targetId, 'wiki_link');
+    }
 
-      if (!nodesById.has(targetId) && includeDangling) {
-        nodesById.set(targetId, {
-          id: targetId,
-          title: toDisplayTitle(targetId),
-          category: 'unresolved',
-          tags: [],
-          path: null,
-          missing: true,
-          _outboundTargets: []
-        });
-      }
-
-      const edgeKey = `${node.id}=>${targetId}`;
-      if (edgeSet.has(edgeKey)) {
+    for (const relation of node._frontmatterRelations) {
+      const targetId = resolveTargetId(relation.target, {
+        idsByLowercase,
+        idsByBaseName,
+        includeDangling
+      });
+      if (!targetId) {
         continue;
       }
-      edgeSet.add(edgeKey);
-      edges.push({ source: node.id, target: targetId });
+      ensureUnresolvedNode(targetId);
+      addEdge(node.id, targetId, 'frontmatter_relation', relation.field);
     }
   }
 
+  const edges = Array.from(edgesByKey.values());
   const degreeByNodeId = new Map();
   for (const edge of edges) {
     degreeByNodeId.set(edge.source, (degreeByNodeId.get(edge.source) ?? 0) + 1);
     degreeByNodeId.set(edge.target, (degreeByNodeId.get(edge.target) ?? 0) + 1);
   }
 
+  const nodeTypeCounts = {};
   const nodes = Array.from(nodesById.values())
-    .map(({ _outboundTargets, ...node }) => ({
-      ...node,
-      degree: degreeByNodeId.get(node.id) ?? 0
-    }))
+    .map(({ _outboundTargets, _frontmatterRelations, _inlineTags, ...node }) => {
+      nodeTypeCounts[node.type] = (nodeTypeCounts[node.type] ?? 0) + 1;
+      return {
+        ...node,
+        degree: degreeByNodeId.get(node.id) ?? 0
+      };
+    })
     .sort((a, b) => a.id.localeCompare(b.id));
 
+  const edgeTypeCounts = {};
+  for (const edge of edges) {
+    edgeTypeCounts[edge.type] = (edgeTypeCounts[edge.type] ?? 0) + 1;
+  }
+
   edges.sort((a, b) => {
-    const sourceSort = a.source.localeCompare(b.source);
-    return sourceSort !== 0 ? sourceSort : a.target.localeCompare(b.target);
+    const sourceSort = String(a.source).localeCompare(String(b.source));
+    if (sourceSort !== 0) return sourceSort;
+    const targetSort = String(a.target).localeCompare(String(b.target));
+    if (targetSort !== 0) return targetSort;
+    const typeSort = String(a.type || '').localeCompare(String(b.type || ''));
+    if (typeSort !== 0) return typeSort;
+    return String(a.label || '').localeCompare(String(b.label || ''));
   });
 
   return {
@@ -112,11 +203,159 @@ export async function buildVaultGraph(vaultPath, options = {}) {
       generatedAt: new Date().toISOString(),
       nodeCount: nodes.length,
       edgeCount: edges.length,
-      fileCount: markdownFiles.length
+      fileCount: markdownFiles.length,
+      nodeTypeCounts,
+      edgeTypeCounts
+    }
+  };
+}
+
+async function loadGraphFromMemoryIndex(root, options = {}) {
+  const includeDangling = options.includeDangling !== false;
+  const validateFreshness = options.validateFreshness !== false;
+  const indexPath = path.join(root, ...MEMORY_GRAPH_INDEX_PATH);
+
+  let parsed;
+  try {
+    const raw = await fs.readFile(indexPath, 'utf8');
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  const graph = parsed?.graph;
+  if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+    return null;
+  }
+
+  if (validateFreshness) {
+    const fresh = await isIndexFresh(root, parsed);
+    if (!fresh) {
+      return null;
+    }
+  }
+
+  const nodeById = new Map();
+  for (const node of graph.nodes) {
+    const mappedId = fromIndexedNodeId(node?.id, node?.type);
+    if (!mappedId) continue;
+    if (node?.missing && !includeDangling) continue;
+
+    nodeById.set(mappedId, {
+      id: mappedId,
+      title: normalizeString(node?.title) || toDisplayTitle(mappedId),
+      category: normalizeString(node?.category) || 'root',
+      type: normalizeString(node?.type) || 'note',
+      tags: normalizeTags(node?.tags),
+      path: typeof node?.path === 'string' ? toPosixPath(node.path) : null,
+      missing: Boolean(node?.missing),
+      degree: Number(node?.degree ?? 0)
+    });
+  }
+
+  const edges = [];
+  for (const edge of graph.edges) {
+    const source = fromIndexedNodeId(edge?.source);
+    const target = fromIndexedNodeId(edge?.target);
+    if (!source || !target) continue;
+    if (!nodeById.has(source) || !nodeById.has(target)) continue;
+    edges.push({
+      source,
+      target,
+      type: normalizeString(edge?.type) || 'wiki_link',
+      label: normalizeString(edge?.label) || undefined
+    });
+  }
+
+  const degreeByNodeId = new Map();
+  for (const edge of edges) {
+    degreeByNodeId.set(edge.source, (degreeByNodeId.get(edge.source) ?? 0) + 1);
+    degreeByNodeId.set(edge.target, (degreeByNodeId.get(edge.target) ?? 0) + 1);
+  }
+
+  const nodeTypeCounts = {};
+  const nodes = Array.from(nodeById.values())
+    .map((node) => {
+      node.degree = degreeByNodeId.get(node.id) ?? 0;
+      nodeTypeCounts[node.type] = (nodeTypeCounts[node.type] ?? 0) + 1;
+      return node;
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const edgeTypeCounts = {};
+  for (const edge of edges) {
+    edgeTypeCounts[edge.type] = (edgeTypeCounts[edge.type] ?? 0) + 1;
+  }
+
+  edges.sort((a, b) => {
+    const sourceSort = String(a.source).localeCompare(String(b.source));
+    if (sourceSort !== 0) return sourceSort;
+    const targetSort = String(a.target).localeCompare(String(b.target));
+    if (targetSort !== 0) return targetSort;
+    const typeSort = String(a.type || '').localeCompare(String(b.type || ''));
+    if (typeSort !== 0) return typeSort;
+    return String(a.label || '').localeCompare(String(b.label || ''));
+  });
+
+  return {
+    nodes,
+    edges,
+    stats: {
+      generatedAt: normalizeString(graph?.stats?.generatedAt) || new Date().toISOString(),
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      fileCount: Number.isFinite(Number(parsed?.files ? Object.keys(parsed.files).length : graph?.stats?.fileCount))
+        ? Number(parsed?.files ? Object.keys(parsed.files).length : graph?.stats?.fileCount)
+        : 0,
+      nodeTypeCounts,
+      edgeTypeCounts
     }
   };
 }
 
+async function isIndexFresh(root, parsedIndex) {
+  const indexedFiles = parsedIndex?.files;
+  if (!indexedFiles || typeof indexedFiles !== 'object') {
+    return false;
+  }
+
+  const markdownFiles = await collectMarkdownFiles(root);
+  const normalizedCurrent = markdownFiles
+    .map((absolutePath) => toPosixPath(path.relative(root, absolutePath)))
+    .sort((a, b) => a.localeCompare(b));
+  const indexedPaths = Object.keys(indexedFiles).sort((a, b) => a.localeCompare(b));
+
+  if (normalizedCurrent.length !== indexedPaths.length) {
+    return false;
+  }
+
+  for (let index = 0; index < normalizedCurrent.length; index += 1) {
+    if (normalizedCurrent[index] !== indexedPaths[index]) {
+      return false;
+    }
+  }
+
+  for (const relativePath of indexedPaths) {
+    const fragment = indexedFiles[relativePath];
+    const expectedMtime = Number(fragment?.mtimeMs);
+    if (!Number.isFinite(expectedMtime)) {
+      return false;
+    }
+    const absolutePath = path.join(root, relativePath);
+    let stat;
+    try {
+      stat = await fs.stat(absolutePath);
+    } catch {
+      return false;
+    }
+    if (Math.abs(stat.mtimeMs - expectedMtime) > 1) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 async function collectMarkdownFiles(root) {
   const pending = [root];
   const files = [];
@@ -159,6 +398,39 @@ function extractWikiLinks(markdown) {
   return links;
 }
 
+function extractInlineTags(markdown) {
+  const tags = new Set();
+  for (const match of markdown.matchAll(HASH_TAG_REGEX)) {
+    const tag = normalizeString(match[2])?.toLowerCase();
+    if (tag) {
+      tags.add(tag);
+    }
+  }
+  return [...tags];
+}
+
+function extractFrontmatterRelations(frontmatter) {
+  const relations = [];
+  for (const field of FRONTMATTER_RELATION_FIELDS) {
+    const raw = frontmatter?.[field];
+    if (typeof raw === 'string') {
+      for (const target of raw.split(',').map((value) => normalizeWikiTarget(value)).filter(Boolean)) {
+        relations.push({ field, target });
+      }
+      continue;
+    }
+    if (Array.isArray(raw)) {
+      for (const entry of raw) {
+        if (typeof entry !== 'string') continue;
+        for (const target of entry.split(',').map((value) => normalizeWikiTarget(value)).filter(Boolean)) {
+          relations.push({ field, target });
+        }
+      }
+    }
+  }
+  return relations;
+}
+
 function resolveTargetId(target, context) {
   const normalized = normalizeWikiTarget(target);
   if (!normalized) {
@@ -209,6 +481,24 @@ function normalizeWikiTarget(target) {
   return normalizeString(value);
 }
 
+function fromIndexedNodeId(value, nodeType = '') {
+  const raw = normalizeString(value);
+  if (!raw) return '';
+  if (raw.startsWith('note:')) {
+    return raw.slice(5);
+  }
+  if (raw.startsWith('tag:')) {
+    return raw;
+  }
+  if (raw.startsWith('unresolved:')) {
+    return raw.slice('unresolved:'.length) || raw;
+  }
+  if (normalizeString(nodeType).toLowerCase() === 'tag') {
+    return raw.startsWith('tag:') ? raw : `tag:${raw}`;
+  }
+  return raw;
+}
+
 function toNodeId(relativePath) {
   const normalized = toPosixPath(relativePath);
   return normalized.toLowerCase().endsWith(MARKDOWN_EXT)
@@ -221,6 +511,20 @@ function inferCategory(id) {
   return normalizeString(category) || 'root';
 }
 
+function inferNodeType(id, frontmatter) {
+  const category = inferCategory(id).toLowerCase();
+  const explicitType = normalizeString(frontmatter?.type).toLowerCase();
+  if (category.includes('daily') || explicitType === 'daily') return 'daily';
+  if (category === 'observations' || explicitType === 'observation') return 'observation';
+  if (category === 'handoffs' || explicitType === 'handoff') return 'handoff';
+  if (category === 'decisions' || explicitType === 'decision') return 'decision';
+  if (category === 'lessons' || explicitType === 'lesson') return 'lesson';
+  if (category === 'projects' || explicitType === 'project') return 'project';
+  if (category === 'people' || explicitType === 'person') return 'person';
+  if (category === 'commitments' || explicitType === 'commitment') return 'commitment';
+  return 'note';
+}
+
 function normalizeTags(tags) {
   if (Array.isArray(tags)) {
     return tags.map(normalizeString).filter(Boolean);

package/dashboard/lib/vault-parser.test.js

@@ -37,18 +37,32 @@ Linked to [[projects/clawvault|ClawVault Project]] and [[missing-note]].
       expect(decisionNode).toMatchObject({
         title: 'Use ClawVault',
         category: 'decisions',
-        tags: ['architecture', 'memory']
+        tags: ['architecture', 'memory'],
+        type: 'decision'
       });
-      expect(graph.edges).toEqual(
-        expect.arrayContaining([
-          { source: 'decisions/use-clawvault', target: 'projects/clawvault' },
-          { source: 'decisions/use-clawvault', target: 'missing-note' }
-        ])
-      );
+      expect(graph.edges).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          source: 'decisions/use-clawvault',
+          target: 'projects/clawvault',
+          type: 'wiki_link'
+        }),
+        expect.objectContaining({
+          source: 'decisions/use-clawvault',
+          target: 'missing-note',
+          type: 'wiki_link'
+        }),
+        expect.objectContaining({
+          source: 'decisions/use-clawvault',
+          target: 'tag:architecture',
+          type: 'tag'
+        })
+      ]));
       expect(unresolvedNode).toMatchObject({
         missing: true,
         category: 'unresolved'
       });
+      expect(graph.stats.edgeTypeCounts.wiki_link).toBeGreaterThanOrEqual(2);
+      expect(graph.stats.edgeTypeCounts.tag).toBeGreaterThanOrEqual(1);
     } finally {
       fs.rmSync(vaultPath, { recursive: true, force: true });
     }
@@ -62,11 +76,177 @@ Linked to [[projects/clawvault|ClawVault Project]] and [[missing-note]].
 
       const graph = await buildVaultGraph(vaultPath);
 
-      expect(graph.edges).toEqual(
-        expect.arrayContaining([
-          { source: 'research/notes', target: 'projects/clawvault' }
-        ])
+      expect(graph.edges).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          source: 'research/notes',
+          target: 'projects/clawvault',
+          type: 'wiki_link'
+        })
+      ]));
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+
+  it('emits frontmatter relation edges with labels', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(
+        vaultPath,
+        'decisions/db.md',
+        `---
+related:
+  - projects/clawvault
+owner: people/alice
+---
+Decision details`
       );
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# ClawVault');
+      writeVaultFile(vaultPath, 'people/alice.md', '# Alice');
+
+      const graph = await buildVaultGraph(vaultPath);
+      expect(graph.edges).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          source: 'decisions/db',
+          target: 'projects/clawvault',
+          type: 'frontmatter_relation',
+          label: 'related'
+        }),
+        expect.objectContaining({
+          source: 'decisions/db',
+          target: 'people/alice',
+          type: 'frontmatter_relation',
+          label: 'owner'
+        })
+      ]));
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+
+  it('loads graph data from memory graph index when present', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(vaultPath, 'decisions/use-clawvault.md', '# Placeholder');
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# Placeholder project');
+      const decisionMtime = fs.statSync(path.join(vaultPath, 'decisions/use-clawvault.md')).mtimeMs;
+      const projectMtime = fs.statSync(path.join(vaultPath, 'projects/clawvault.md')).mtimeMs;
+      const indexPath = path.join(vaultPath, '.clawvault', 'graph-index.json');
+      fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+      fs.writeFileSync(
+        indexPath,
+        JSON.stringify({
+          schemaVersion: 1,
+          files: {
+            'decisions/use-clawvault.md': {
+              relativePath: 'decisions/use-clawvault.md',
+              mtimeMs: decisionMtime
+            },
+            'projects/clawvault.md': {
+              relativePath: 'projects/clawvault.md',
+              mtimeMs: projectMtime
+            }
+          },
+          graph: {
+            nodes: [
+              {
+                id: 'note:decisions/use-clawvault',
+                title: 'Use ClawVault',
+                type: 'decision',
+                category: 'decisions',
+                tags: ['architecture'],
+                path: 'decisions/use-clawvault.md',
+                missing: false,
+                degree: 1
+              },
+              {
+                id: 'note:projects/clawvault',
+                title: 'ClawVault Project',
+                type: 'project',
+                category: 'projects',
+                tags: [],
+                path: 'projects/clawvault.md',
+                missing: false,
+                degree: 1
+              }
+            ],
+            edges: [
+              {
+                source: 'note:decisions/use-clawvault',
+                target: 'note:projects/clawvault',
+                type: 'frontmatter_relation',
+                label: 'related'
+              }
+            ],
+            stats: { generatedAt: '2026-02-13T00:00:00.000Z' }
+          }
+        }),
+        'utf8'
+      );
+
+      const graph = await buildVaultGraph(vaultPath);
+      expect(graph.nodes.find((node) => node.id === 'decisions/use-clawvault')).toBeTruthy();
+      expect(graph.edges).toEqual([
+        {
+          source: 'decisions/use-clawvault',
+          target: 'projects/clawvault',
+          type: 'frontmatter_relation',
+          label: 'related'
+        }
+      ]);
+      expect(graph.stats.fileCount).toBe(2);
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+
+  it('falls back to markdown parsing when memory graph index is stale', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# ClawVault');
+      writeVaultFile(vaultPath, 'decisions/use-clawvault.md', 'See [[projects/clawvault]].');
+
+      const indexPath = path.join(vaultPath, '.clawvault', 'graph-index.json');
+      fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+      fs.writeFileSync(
+        indexPath,
+        JSON.stringify({
+          schemaVersion: 1,
+          generatedAt: '2026-02-13T00:00:00.000Z',
+          files: {
+            'decisions/use-clawvault.md': { relativePath: 'decisions/use-clawvault.md', mtimeMs: 1 },
+            'projects/clawvault.md': { relativePath: 'projects/clawvault.md', mtimeMs: 1 }
+          },
+          graph: {
+            nodes: [
+              {
+                id: 'note:decisions/use-clawvault',
+                title: 'Old node',
+                type: 'decision',
+                category: 'decisions',
+                tags: [],
+                path: 'decisions/use-clawvault.md',
+                missing: false,
+                degree: 0
+              }
+            ],
+            edges: [],
+            stats: { generatedAt: '2026-02-13T00:00:00.000Z' }
+          }
+        }),
+        'utf8'
+      );
+
+      const graph = await buildVaultGraph(vaultPath);
+      const node = graph.nodes.find((candidate) => candidate.id === 'decisions/use-clawvault');
+      expect(node?.title).not.toBe('Old node');
+      expect(graph.edges).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          source: 'decisions/use-clawvault',
+          target: 'projects/clawvault',
+          type: 'wiki_link'
+        })
+      ]));
     } finally {
       fs.rmSync(vaultPath, { recursive: true, force: true });
     }