@rahmantech/knl-view 0.0.0-stage → 0.1.0

package/server/graph/model.js

@@ -0,0 +1,157 @@
+// Directed graph (DAG) data model for knowledges-view: knowledge nodes and
+// decision nodes.
+
+export class GraphNode {
+  constructor({ id, title, type = 'knowledge', path = '', metadata = {} }) {
+    this.id = id
+    this.title = title || id
+    this.type = type // 'knowledge' | 'decision'
+    this.path = path
+    this.metadata = metadata
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      title: this.title,
+      type: this.type,
+      path: this.path,
+      metadata: this.metadata
+    }
+  }
+}
+
+export class GraphEdge {
+  constructor({ from, to, type, metadata = {} }) {
+    this.from = from
+    this.to = to
+    this.type = type // 'depends_on' | 'references' | 'supersedes' | 'related_to' | 'affects_knowledge'
+    this.metadata = metadata
+  }
+
+  toJSON() {
+    return {
+      from: this.from,
+      to: this.to,
+      type: this.type,
+      metadata: this.metadata
+    }
+  }
+}
+
+export class DirectedGraph {
+  constructor() {
+    this.nodes = new Map()
+    this.edges = []
+    this.outgoing = new Map() // nodeId -> Array of edges
+    this.incoming = new Map() // nodeId -> Array of edges
+  }
+
+  addNode(node) {
+    if (!node || !node.id) return
+    this.nodes.set(node.id, node)
+    if (!this.outgoing.has(node.id)) this.outgoing.set(node.id, [])
+    if (!this.incoming.has(node.id)) this.incoming.set(node.id, [])
+  }
+
+  addEdge(edge) {
+    if (!edge || !edge.from || !edge.to) return
+    // Make sure the nodes exist in the outgoing/incoming maps
+    if (!this.outgoing.has(edge.from)) this.outgoing.set(edge.from, [])
+    if (!this.incoming.has(edge.to)) this.incoming.set(edge.to, [])
+
+    this.edges.push(edge)
+    this.outgoing.get(edge.from).push(edge)
+    this.incoming.get(edge.to).push(edge)
+  }
+
+  getNode(id) {
+    return this.nodes.get(id) || null
+  }
+
+  getOutgoingEdges(id) {
+    return this.outgoing.get(id) || []
+  }
+
+  getIncomingEdges(id) {
+    return this.incoming.get(id) || []
+  }
+
+  // Radius-based N-hop sub-graph extraction (cheap enough to feed to an LLM).
+  //
+  // `direction` selects which edges the BFS may walk, mechanically relative
+  // to the edges themselves, never interpreted as cause and effect:
+  //   'out':  edges leaving the target (what it supersedes / depends_on / affects)
+  //   'in':   edges entering the target (what references or replaces it)
+  //   'both': the default; the full neighborhood as before
+  // Each returned node carries `via`: how it connects to the center
+  // ('center', 'in', 'out', or 'in+out' when reachable both ways).
+  extractSubGraph(startId, maxHops = 2, direction = 'both') {
+    const walkOut = direction !== 'in'
+    const walkIn = direction !== 'out'
+    const reachedVia = new Map() // id -> 'in' | 'out' | 'in+out' | 'center'
+    const setVia = (id, via) => {
+      const prev = reachedVia.get(id)
+      if (prev === undefined) reachedVia.set(id, via)
+      else if (prev !== via && prev !== 'center' && via !== 'center') reachedVia.set(id, 'in+out')
+    }
+    setVia(startId, 'center')
+    const collectedEdges = []
+    const seenEdges = new Set()
+    const queue = [{ id: startId, hop: 0 }]
+
+    while (queue.length > 0) {
+      const { id, hop } = queue.shift()
+      if (hop >= maxHops) continue
+
+      if (walkOut) {
+        for (const edge of this.getOutgoingEdges(id)) {
+          const edgeKey = `${edge.from}->${edge.to}:${edge.type}`
+          if (!seenEdges.has(edgeKey)) {
+            seenEdges.add(edgeKey)
+            collectedEdges.push(edge)
+          }
+          if (!reachedVia.has(edge.to)) {
+            queue.push({ id: edge.to, hop: hop + 1 })
+          }
+          setVia(edge.to, 'out')
+        }
+      }
+
+      if (walkIn) {
+        for (const edge of this.getIncomingEdges(id)) {
+          const edgeKey = `${edge.from}->${edge.to}:${edge.type}`
+          if (!seenEdges.has(edgeKey)) {
+            seenEdges.add(edgeKey)
+            collectedEdges.push(edge)
+          }
+          if (!reachedVia.has(edge.from)) {
+            queue.push({ id: edge.from, hop: hop + 1 })
+          }
+          setVia(edge.from, 'in')
+        }
+      }
+    }
+
+    const subNodes = []
+    for (const [id, via] of reachedVia) {
+      const node = this.getNode(id)
+      if (node) subNodes.push({ ...node.toJSON(), via })
+    }
+
+    return {
+      center: startId,
+      maxHops,
+      direction,
+      nodes: subNodes,
+      edges: collectedEdges.map(e => e.toJSON())
+    }
+  }
+
+  toJSON() {
+    return {
+      nodes: Array.from(this.nodes.values()).map(n => n.toJSON()),
+      edges: this.edges.map(e => e.toJSON())
+    }
+  }
+}

package/server/graph/parser.js

@@ -0,0 +1,326 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { GraphNode, GraphEdge, DirectedGraph } from './model.js'
+
+const MD_EXTS = new Set(['.md', '.markdown', '.prd'])
+
+/**
+ * Simple (YAML-like) frontmatter extraction and the first heading.
+ */
+export function extractFrontmatterAndTitle(content) {
+  let metadata = {}
+  let body = content
+  let title = null
+
+  if (content.startsWith('---')) {
+    const endIdx = content.indexOf('\n---', 3)
+    if (endIdx !== -1) {
+      const rawFm = content.slice(3, endIdx).trim()
+      body = content.slice(endIdx + 4)
+      metadata = parseSimpleYaml(rawFm)
+    }
+  }
+
+  if (metadata.title) {
+    title = String(metadata.title).trim()
+  } else {
+    // Take the first H1 as the title
+    const match = body.match(/^#\s+(.+)$/m)
+    if (match) {
+      title = match[1].trim()
+    }
+  }
+
+  return { metadata, body, title }
+}
+
+function parseSimpleYaml(text) {
+  const result = {}
+  const lines = text.split('\n')
+  for (const line of lines) {
+    const match = line.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.*)$/)
+    if (!match) continue
+    const key = match[1].trim()
+    let val = match[2].trim()
+
+    // Handle array format [a, b, c]
+    if (val.startsWith('[') && val.endsWith(']')) {
+      const items = val.slice(1, -1).split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
+      result[key] = items
+    } else {
+      // Strip quotes when present
+      val = val.replace(/^['"]|['"]$/g, '')
+      result[key] = val
+    }
+  }
+  return result
+}
+
+/**
+ * Parse a knowledge Markdown file (e.g. docs/xxx.md or features/xxx.md).
+ */
+export function parseKnowledgeContent(relPath, content) {
+  const { metadata, body, title } = extractFrontmatterAndTitle(content)
+  const id = relPath.replace(/\\/g, '/')
+  const node = new GraphNode({
+    id,
+    title: title || path.basename(relPath),
+    type: 'knowledge',
+    path: id,
+    metadata
+  })
+
+  const edges = []
+
+  // Parse dependencies from the frontmatter
+  const deps = Array.isArray(metadata.depends_on) ? metadata.depends_on : (metadata.depends_on ? [metadata.depends_on] : [])
+  for (const dep of deps) {
+    edges.push(new GraphEdge({
+      from: id,
+      to: String(dep).trim(),
+      type: 'depends_on'
+    }))
+  }
+
+  // Parse references from the frontmatter
+  const refs = Array.isArray(metadata.references) ? metadata.references : (metadata.references ? [metadata.references] : [])
+  for (const ref of refs) {
+    edges.push(new GraphEdge({
+      from: id,
+      to: String(ref).trim(),
+      type: 'references'
+    }))
+  }
+
+  // Parse plain markdown links [text](target.md)
+  const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g
+  let linkMatch
+  while ((linkMatch = linkRegex.exec(body)) !== null) {
+    const targetUrl = linkMatch[2].trim()
+    // Ignore external web links (http/https/mailto)
+    if (!targetUrl.startsWith('http://') && !targetUrl.startsWith('https://') && !targetUrl.startsWith('mailto:') && !targetUrl.startsWith('#')) {
+      const cleanTarget = targetUrl.split('#')[0].split('?')[0].replace(/^\.\//, '')
+      if (cleanTarget) {
+        const docDir = path.dirname(relPath).replace(/\\/g, '/')
+        const resolvedTarget = (docDir && docDir !== '.' && !cleanTarget.startsWith('/'))
+          ? path.posix.normalize(`${docDir}/${cleanTarget}`)
+          : cleanTarget.replace(/^\//, '')
+
+        if (resolvedTarget && resolvedTarget !== id) {
+          edges.push(new GraphEdge({
+            from: id,
+            to: resolvedTarget,
+            type: 'references',
+            metadata: { text: linkMatch[1] }
+          }))
+        }
+      }
+    }
+  }
+
+  return { node, edges }
+}
+
+/**
+ * Parse decision blocks from a decision file (decisionskills format: <!-- decision:start -->).
+ */
+export function parseDecisionBlocks(relPath, content) {
+  const nodes = []
+  const edges = []
+
+  const blockRegex = /<!--\s*decision:start\s*-->([\s\S]*?)<!--\s*decision:end\s*-->/g
+  let match
+
+  while ((match = blockRegex.exec(content)) !== null) {
+    const rawBlock = match[1]
+    const parsed = parseSingleDecisionBlock(relPath, rawBlock)
+    if (parsed) {
+      nodes.push(parsed.node)
+      edges.push(...parsed.edges)
+    }
+  }
+
+  return { nodes, edges }
+}
+
+// Helper for list fields that may repeat: the lines "- references: a" then
+// "- references: b" produce [a, b], not just [b].
+function appendList(existing, val) {
+  const items = val.split(',').map(s => s.trim().replace(/^`|`$/g, '')).filter(Boolean)
+  return existing.concat(items.filter((item) => !existing.includes(item)))
+}
+
+function parseSingleDecisionBlock(relPath, rawBlock) {  const lines = rawBlock.split('\n')
+  let title = 'Untitled Decision'
+  let id = null
+  let decidedAt = null
+  let scope = null
+  let tags = []
+  let supersedes = []
+  let related = []
+  let references = []
+  let decisionText = ''
+
+  let currentSection = null
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+
+    // Title heading (## Title)
+    if (trimmed.startsWith('## ')) {
+      title = trimmed.slice(3).trim()
+      continue
+    }
+
+    // Section header (### Section)
+    if (trimmed.startsWith('### ')) {
+      currentSection = trimmed.slice(4).trim().toLowerCase()
+      continue
+    }
+
+    // Metadata bullet items (- Field: Value)
+    const metaMatch = trimmed.match(/^-\s+([^:]+):\s*(.*)$/)
+    if (metaMatch && !currentSection) {
+      const field = metaMatch[1].trim().toLowerCase()
+      const val = metaMatch[2].trim().replace(/^`|`$/g, '')
+
+      if (val === 'none' || !val) continue
+
+      if (field === 'id') id = val
+      else if (field === 'decided at') decidedAt = val
+      else if (field === 'scope') scope = val
+      else if (field === 'tags') tags = val.split(',').map(s => s.trim().replace(/^`|`$/g, '')).filter(Boolean)
+      // List fields may repeat across lines; the second line appends,
+      // it does not overwrite the first.
+      else if (field === 'supersedes') supersedes = appendList(supersedes, val)
+      else if (field === 'related') related = appendList(related, val)
+      else if (field === 'references') references = appendList(references, val)
+      continue
+    }
+
+    // Body content per section
+    if (currentSection === 'decision' && trimmed) {
+      decisionText += (decisionText ? ' ' : '') + trimmed
+    }
+  }
+
+  if (!id) return null
+
+  const node = new GraphNode({
+    id,
+    title,
+    type: 'decision',
+    path: relPath.replace(/\\/g, '/'),
+    metadata: {
+      decided_at: decidedAt,
+      scope,
+      tags,
+      decision: decisionText
+    }
+  })
+
+  const edges = []
+
+  for (const sup of supersedes) {
+    edges.push(new GraphEdge({
+      from: id,
+      to: sup,
+      type: 'supersedes'
+    }))
+  }
+
+  for (const rel of related) {
+    edges.push(new GraphEdge({
+      from: id,
+      to: rel,
+      type: 'related_to'
+    }))
+  }
+
+  // References are resolved relative to the decision file's own folder,
+  // the same rule markdown links follow: a decision in decisions/2026-10.md
+  // writing `ref/DEC-x.md` points at decisions/ref/DEC-x.md. Absolute and
+  // URL-shaped values are kept as-is.
+  const docDir = path.posix.dirname(relPath.replace(/\\/g, '/'))
+  for (const ref of references) {
+    const isUrl = /^[a-z][a-z0-9+.-]*:\/\//i.test(ref)
+    const isDocRef = !isUrl && (ref.endsWith('.md') || ref.includes('/'))
+    let target = ref
+    if (isDocRef && !ref.startsWith('/')) {
+      target = (docDir && docDir !== '.')
+        ? path.posix.normalize(`${docDir}/${ref}`)
+        : ref.replace(/^\//, '')
+    }
+    edges.push(new GraphEdge({
+      from: id,
+      to: target,
+      type: isDocRef ? 'affects_knowledge' : 'references'
+    }))
+  }
+
+  return { node, edges }
+}
+
+/**
+ * Build the full graph recursively from the knowledge base root folder (.knowledges).
+ */
+export async function buildGraphFromRoot(rootAbs) {
+  const graph = new DirectedGraph()
+  await walkDir(rootAbs, '', async (absPath, relPath) => {
+    const ext = path.extname(absPath).toLowerCase()
+    if (!MD_EXTS.has(ext)) return
+
+    let content
+    try {
+      content = await fs.readFile(absPath, 'utf8')
+    } catch {
+      return
+    }
+
+    const normRel = relPath.replace(/\\/g, '/')
+
+    // Check whether this is a decision file (under the decisions/ folder)
+    if (normRel.startsWith('decisions/')) {
+      const { nodes, edges: decisionEdges } = parseDecisionBlocks(normRel, content)
+      for (const n of nodes) graph.addNode(n)
+      for (const e of decisionEdges) graph.addEdge(e)
+      // A decision file with no blocks is a plain document (for example
+      // reference material under decisions/ref/): keep it in the graph as
+      // a knowledge node so decisions can point at it by path.
+      if (nodes.length === 0) {
+        const { node } = parseKnowledgeContent(normRel, content)
+        graph.addNode(node)
+      }
+    } else {
+      const { node, edges } = parseKnowledgeContent(normRel, content)
+      graph.addNode(node)
+      for (const e of edges) graph.addEdge(e)
+    }
+  })
+
+  return graph
+}
+
+async function walkDir(baseDir, currentRel, visitor) {
+  let entries
+  try {
+    entries = await fs.readdir(path.join(baseDir, currentRel), { withFileTypes: true })
+  } catch {
+    return
+  }
+
+  for (const ent of entries) {
+    if (ent.name.startsWith('.')) {
+      continue
+    }
+
+    const nextRel = currentRel ? path.join(currentRel, ent.name) : ent.name
+    const fullPath = path.join(baseDir, nextRel)
+
+    if (ent.isDirectory()) {
+      await walkDir(baseDir, nextRel, visitor)
+    } else if (ent.isFile()) {
+      await visitor(fullPath, nextRel)
+    }
+  }
+}