rvlib-shipkit 0.1.0

package/src/wiki/scan-md.ts

@@ -0,0 +1,108 @@
+// Generic markdown-repo scanner → MdGraph, so any repo gets a graph with zero
+// custom parsing. Detected link forms (fenced code is invisible):
+//   @path              eager — loaded with the file that names it
+//   → path.md          lazy  — resolved from the scan root, then file-relative
+//   [text](path.md)    lazy  — file-relative
+//   `path.md`          lazy  — file-relative, then from the scan root
+// Depth = 0-1 BFS from the index (eager edge keeps depth, lazy adds 1);
+// unreachable files stay in the graph with no depth (lint-md.ts turns those,
+// plus dangling refs, into failures — the graph itself is a viewer).
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { dirname, join, relative, resolve } from 'path'
+import type { MdEdge, MdGraph, MdNode } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+
+export type ScanMdConfig = {
+    root: string // absolute dir to scan
+    index?: string // root-relative entry the BFS starts from (default: index.md AND README.md, both)
+    skipDirs?: string[] // dir names to skip on top of node_modules/.git/dist/tmp
+}
+
+export type MdDanglingRef = { from: string; token: string } // an @/→/[](…) ref whose target is not in the scan
+export type MdScan = {
+    graph: MdGraph
+    index: string | null // resolved entrypoint(s), ' + '-joined when both defaults exist; null = none found
+    dangling: MdDanglingRef[]
+}
+
+export function scanMdGraph(cfg: ScanMdConfig): MdGraph {
+    return scanMd(cfg).graph
+}
+
+export function scanMd(cfg: ScanMdConfig): MdScan {
+    const skip = new Set(['node_modules', '.git', 'dist', 'tmp', ...(cfg.skipDirs ?? [])])
+    const files: string[] = []
+    const walk = (rel: string) => {
+        for (const e of readdirSync(join(cfg.root, rel))) {
+            const r = rel === '' ? e : `${rel}/${e}`
+            if (statSync(join(cfg.root, r)).isDirectory()) {
+                if (!skip.has(e) && !e.startsWith('.')) walk(r)
+            } else if (e.endsWith('.md')) files.push(r)
+        }
+    }
+    walk('')
+    files.sort()
+    const inGraph = new Set(files)
+
+    const resolveRef = (fromRel: string, token: string): string | null => {
+        for (const cand of [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]) {
+            const rel = relative(cfg.root, cand)
+            if (!rel.startsWith('..') && inGraph.has(rel)) return rel
+        }
+        return null
+    }
+    const edgesOf = (rel: string): MdEdge[] => {
+        const raw = readFileSync(join(cfg.root, rel), 'utf8')
+        const body = raw.startsWith('---\n') ? raw.slice(4).replace(/^[\s\S]*?^---\s*$/m, '') : raw
+        const spans: string[] = []
+        const prose = body.replace(/^```[\s\S]*?^```\s*$/gm, '').replace(/`([^`\n]+)`/g, (_, s: string) => { spans.push(s); return ' ' })
+        const out: MdEdge[] = []
+        // strict: @/→/[](…) are deliberate wiki refs — a miss is a dangling ref.
+        // Backtick spans mention paths casually (other repos, deleted examples) — resolve or ignore, never fail.
+        const push = (token: string, eager: boolean, strict: boolean) => {
+            const to = resolveRef(rel, token)
+            if (to != null && to !== rel) out.push({ from: rel, to, eager })
+            else if (to == null && strict) dangling.push({ from: rel, token })
+        }
+        for (const m of prose.matchAll(/(?:^|[\s(])@([\w][\w./-]*\.md)/gm)) push(m[1]!, true, true)
+        for (const m of prose.matchAll(/→\s*([\w][\w./-]*\.md)\b/g)) push(m[1]!, false, true)
+        for (const m of prose.matchAll(/\]\(([^)\s:]+\.md)\)/g)) push(m[1]!, false, true)
+        for (const s of spans) for (const m of s.matchAll(/[\w][\w./-]*\.md/g)) push(m[0], false, false)
+        return out
+    }
+    const dangling: MdDanglingRef[] = []
+    const edges: MdEdge[] = []
+    const seen = new Set<string>()
+    for (const f of files) for (const e of edgesOf(f)) {
+        const key = `${e.from}>${e.to}:${e.eager}`
+        if (!seen.has(key)) { seen.add(key); edges.push(e) }
+    }
+
+    // explicit index = the only entry; default = index.md AND README.md both
+    // seed the walk (a repo readme is an entrypoint too, never an orphan)
+    const seeds = (cfg.index != null ? [cfg.index] : ['index.md', 'README.md']).filter((s) => inGraph.has(s))
+    const depths = new Map<string, number>()
+    {
+        const deque: string[] = []
+        for (const s of seeds) { depths.set(s, 0); deque.push(s) }
+        while (deque.length > 0) {
+            const cur = deque.shift()!
+            for (const e of edges) {
+                if (e.from !== cur) continue
+                const d = depths.get(cur)! + (e.eager ? 0 : 1)
+                const known = depths.get(e.to)
+                if (known != null && known <= d) continue
+                depths.set(e.to, d)
+                if (e.eager) deque.unshift(e.to)
+                else deque.push(e.to)
+            }
+        }
+    }
+    const nodes: MdNode[] = files.map((f) => ({
+        id: f,
+        label: f.replace(/\.md$/, '').split('/').at(-1)!,
+        group: f.includes('/') ? f.split('/')[0]! : null,
+        eager: depths.get(f) === 0,
+        ...(depths.has(f) ? { depth: depths.get(f)! } : {}),
+    }))
+    return { graph: { nodes, edges }, index: seeds.join(' + ') || null, dangling }
+}

package/src/wiki/serve-graph.ts

@@ -0,0 +1,19 @@
+// Local graph server: `load()` runs on EVERY request, so a reload always shows
+// the wiki as it is on disk right now — no stale exports, no build step.
+import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
+import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+
+export type ServeMdGraphConfig = { port: number; load: () => MdGraph; title?: string }
+
+// routes: `/` the interactive graph · `/graph.json` the raw graph data
+export function serveMdGraph(cfg: ServeMdGraphConfig) {
+    return Bun.serve({
+        port: cfg.port,
+        fetch(req) {
+            const path = new URL(req.url).pathname
+            if (path === '/') return new Response(graphHtml(cfg.load(), { title: cfg.title }), { headers: { 'content-type': 'text/html; charset=utf-8' } })
+            if (path === '/graph.json') return Response.json(cfg.load())
+            return new Response('not found', { status: 404 })
+        },
+    })
+}