@amulet-laboratories/astrolabe 0.4.0

package/src/core/sfc.mjs

@@ -0,0 +1,134 @@
+import { parse } from '@vue/compiler-sfc'
+
+import { sliceBalanced, topLevelKeys } from './syntax.mjs'
+
+const ELEMENT = 1
+
+/** kebab-case / PascalCase tags both resolve to one auto-import name. */
+export function normalizeTag(tag) {
+  return tag
+    .replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())
+    .replace(/^./, (c) => c.toUpperCase())
+}
+
+/**
+ * Parse a Vue SFC into the two things the graph cares about: which components
+ * its template renders, and what its script reaches out to for data.
+ */
+export function parseSfc(source, file) {
+  const { descriptor } = parse(source, { filename: file })
+  const script = [descriptor.script?.content, descriptor.scriptSetup?.content]
+    .filter(Boolean)
+    .join('\n')
+
+  return {
+    tags: descriptor.template?.ast ? collectTags(descriptor.template.ast) : new Set(),
+    ...parseScript(script),
+  }
+}
+
+function collectTags(ast, found = new Set()) {
+  for (const node of ast.children ?? []) {
+    if (node.type === ELEMENT && node.tag) found.add(node.tag)
+    // Recurse through branches too — v-if/v-for wrap children in their own nodes.
+    collectTags(node, found)
+    for (const branch of node.branches ?? []) collectTags(branch, found)
+  }
+  return found
+}
+
+/**
+ * Pull data-access out of a <script> body by pattern. This is deliberately
+ * lexical rather than a full type-aware trace: it catches the conventional
+ * Nuxt call shapes, which is what a reader of the diagram is looking for.
+ */
+export function parseScript(script) {
+  const strip = script.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n]*/g, '$1')
+
+  const collections = new Set()
+  for (const [, name] of strip.matchAll(
+    /queryCollection(?:Navigation|ItemSurroundings)?\s*\(\s*['"]([^'"]+)['"]/g,
+  )) {
+    collections.add(name)
+  }
+
+  const endpoints = new Set()
+  const externals = new Set()
+  for (const [, url] of strip.matchAll(
+    /(?:\$fetch|useFetch|useLazyFetch)\s*(?:<[^>]*>)?\s*\(\s*[`'"]([^`'"]+)[`'"]/g,
+  )) {
+    if (/^https?:\/\//.test(url)) externals.add(hostOf(url))
+    else endpoints.add(url.split('?')[0])
+  }
+
+  const calls = new Set()
+  for (const [, name] of strip.matchAll(/\b(use[A-Z]\w*)\s*\(/g)) calls.add(name)
+
+  return {
+    collections,
+    endpoints,
+    externals,
+    calls,
+    meta: parsePageMeta(strip),
+    usesAppConfig: /\buseAppConfig\s*\(/.test(strip),
+    usesRuntimeConfig: /\buseRuntimeConfig\s*\(/.test(strip),
+    usesState: /\buseState\s*\(/.test(strip),
+    props: parseProps(strip),
+  }
+}
+
+/** Props from either the type form `defineProps<{…}>()` or the runtime form `defineProps({…})`. */
+function parseProps(script) {
+  const props = []
+  for (const m of script.matchAll(/defineProps\s*[<(]/g)) {
+    const start = script.indexOf('{', m.index)
+    if (start === -1) continue
+    props.push(...topLevelKeys(sliceBalanced(script, start, '{', '}')))
+  }
+  return props
+}
+
+function parsePageMeta(script) {
+  const block = script.match(/definePageMeta\s*\(\s*\{([\s\S]*?)\}\s*\)/)?.[1]
+  if (!block) return { middleware: [] }
+  // middleware takes either a single name or an array of them.
+  const mw = block.match(/middleware\s*:\s*(\[[^\]]*\]|['"][\w-]+['"])/)?.[1]
+  return {
+    layout: block.match(/layout\s*:\s*['"]([^'"]+)['"]/)?.[1],
+    middleware: mw ? [...mw.matchAll(/['"]([\w-]+)['"]/g)].map((m) => m[1]) : [],
+  }
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host
+  } catch {
+    return url
+  }
+}
+
+/**
+ * MDC lets markdown render Vue components. Those edges are invisible to a
+ * template scan but are real render paths — miss them and a component rendered
+ * only from content looks like an orphan.
+ *
+ * Three syntaxes, all in use: `::block`, `:inline{}`, and ordinary tag syntax
+ * (`<ProductCardWrapper />`). MDC accepts a component name in either case in
+ * every form — `::quick-answer` and `::QuickAnswer` both resolve — so the block
+ * and inline patterns match both, and `normalizeTag` folds them to one name.
+ * The tag patterns are shaped so plain HTML — div, br, img — can never match: a
+ * component tag is either PascalCase or contains a dash.
+ */
+export function parseMdcComponents(markdown) {
+  const body = markdown
+    .replace(/^---\n[\s\S]*?\n---\n/, '')
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]*`/g, '')
+
+  const found = new Set()
+  for (const [, name] of body.matchAll(/^\s*::+([A-Za-z][\w-]*)/gm)) found.add(name)
+  for (const [, name] of body.matchAll(/(?<!:):([A-Za-z][\w-]*)\{/g)) found.add(name)
+  for (const [, name] of body.matchAll(/<([A-Z][A-Za-z0-9]*)[\s/>]/g)) found.add(name)
+  for (const [, name] of body.matchAll(/<([a-z][a-z0-9]*(?:-[a-z0-9]+)+)[\s/>]/g)) found.add(name)
+  return found
+}

package/src/core/svg.mjs

@@ -0,0 +1,102 @@
+/**
+ * Render a scanned graph to a static SVG, server-side, with no browser.
+ *
+ * It reuses the exact projection and layout the interactive report uses
+ * (`views.mjs` + `layout.mjs`), so an embedded SVG and the live diagram can
+ * never disagree about structure. The point is living docs: a graph that embeds
+ * in a README or a docs page that can't run JavaScript, regenerated in CI.
+ */
+import { computeLayout, edgePath, NODE_H, NODE_W } from './layout.mjs'
+import { TYPES, VIEWS } from './views.mjs'
+
+// Concrete colours for a standalone file. The interactive report reads these
+// from CSS custom properties in styles.css; these mirror its light theme.
+const PALETTE = {
+  entry: '#8b7cc8',
+  route: '#2f6fd0',
+  component: '#2e9e73',
+  lib: '#9a9a90',
+  composable: '#d08a2f',
+  store: '#7b61c9',
+  collection: '#c05a8a',
+  server: '#c0563f',
+  external: '#7a7a72',
+  config: '#4b8fa8',
+}
+
+const colorOf = (n) => PALETTE[TYPES[n.type]?.color] ?? '#888888'
+const truncate = (s, max) => (s.length > max ? `${s.slice(0, max - 1)}…` : s)
+const esc = (s) =>
+  String(s).replace(
+    /[&<>"]/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c],
+  )
+
+const MARGIN = 24
+
+/**
+ * Serialize `graph` (the shape `scan()` returns) into an SVG string for one
+ * view. `view` is any of the report's views; `group` buckets by owner exactly
+ * as the interactive Group toggle does.
+ */
+export function renderSvg(graph, { view = 'layers', group = true } = {}) {
+  const v = VIEWS[view]
+  if (!v) throw new Error(`Unknown view "${view}" — one of: ${Object.keys(VIEWS).join(', ')}`)
+
+  const state = { view, group, types: new Set(Object.keys(TYPES)), focus: null }
+  const proj = v.project(graph, state)
+  const grouping = group && v.grouping !== false
+  const layout = computeLayout(proj, { ...state, group: grouping })
+  const byId = new Map(proj.nodes.map((n) => [n.id, n]))
+
+  const width = Math.ceil(layout.width + MARGIN * 2)
+  const height = Math.ceil(layout.height + MARGIN * 2)
+  const parts = []
+
+  for (const e of proj.edges) {
+    const stroke = colorOf(byId.get(e.to))
+    const weight = e.weight > 1 ? Math.min(6, 1 + Math.log2(e.weight)).toFixed(2) : 1
+    parts.push(
+      `<path d="${edgePath(e, layout)}" fill="none" stroke="${stroke}" stroke-opacity="0.35" stroke-width="${weight}"/>`,
+    )
+  }
+
+  for (const c of layout.active) {
+    const x = layout.xs.get(c)
+    const name = proj.title(c) ?? `Column ${c}`
+    parts.push(
+      `<text x="${x}" y="16" class="col">${esc(name)} (${layout.cols.get(c).length})</text>`,
+    )
+    parts.push(`<line x1="${x}" y1="26" x2="${x + NODE_W}" y2="26" class="rule"/>`)
+  }
+
+  for (const h of layout.headers) {
+    parts.push(`<text x="${h.x + 2}" y="${h.y}" class="grp">${esc(h.text)}</text>`)
+  }
+
+  for (const n of proj.nodes) {
+    const { x, y } = layout.pos.get(n.id)
+    parts.push(
+      `<g transform="translate(${x},${y})">` +
+        `<rect width="${NODE_W}" height="${NODE_H}" rx="4" fill="#ffffff" stroke="#d8d8d8"/>` +
+        `<rect width="3" height="${NODE_H}" rx="1.5" fill="${colorOf(n)}"/>` +
+        `<text x="10" y="${NODE_H / 2 + 4}" class="lbl">${esc(truncate(n.label, 24))}</text>` +
+        `</g>`,
+    )
+  }
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="ui-sans-serif, system-ui, -apple-system, sans-serif">
+<style>
+text { fill: #1c1c1c }
+.col { font-size: 11px; font-weight: 600; fill: #555555 }
+.grp { font-size: 10px; fill: #8a8a8a }
+.lbl { font-size: 12px }
+.rule { stroke: #e4e4e2 }
+</style>
+<rect width="${width}" height="${height}" fill="#fbfbfa"/>
+<g transform="translate(${MARGIN},${MARGIN})">
+${parts.join('\n')}
+</g>
+</svg>
+`
+}

package/src/core/syntax.mjs

@@ -0,0 +1,59 @@
+/**
+ * Small brace-aware scanners shared by the SFC and config parsers.
+ *
+ * These exist because line-oriented regexes quietly get the wrong answer on
+ * code that happens to be formatted on one line — `{ title?: string; size?:
+ * number }` reported one prop instead of two. Counting delimiters costs a few
+ * lines and stops formatting from changing the result.
+ */
+
+/** The balanced `open`…`close` span starting at `start`, inclusive. */
+export function sliceBalanced(str, start, open, close) {
+  let depth = 0
+  for (let i = start; i < str.length; i++) {
+    if (str[i] === open) depth++
+    else if (str[i] === close && --depth === 0) return str.slice(start, i + 1)
+  }
+  return str.slice(start)
+}
+
+// Only these nest. Angle brackets are deliberately excluded: `=>` in a function
+// type would otherwise read as a closing bracket and unbalance everything.
+const OPEN = '{(['
+const CLOSE = '})]'
+
+/**
+ * Keys declared at the top level of an object-ish body — `{ a: X; b?: Y }` →
+ * ['a', 'b']. Nested keys are skipped, so `{ a: { b: X } }` yields only 'a'.
+ * Works the same whether the source is one line or twenty.
+ */
+export function topLevelKeys(body) {
+  const keys = []
+  let depth = 0
+  let token = ''
+
+  for (const char of body) {
+    if (OPEN.includes(char)) {
+      depth++
+      token = ''
+      continue
+    }
+    if (CLOSE.includes(char)) {
+      depth--
+      token = ''
+      continue
+    }
+    if (depth !== 1) continue
+
+    if (/[\w$]/.test(char)) {
+      token += char
+    } else if (char === ':' || char === '?') {
+      // A name immediately followed by `:` or `?:` is a key declaration.
+      if (token) keys.push(token)
+      token = ''
+    } else {
+      token = ''
+    }
+  }
+  return keys
+}

package/src/core/views.mjs

@@ -0,0 +1,304 @@
+/**
+ * A view is a projection of the one underlying graph: which nodes it keeps,
+ * which edges it keeps, and what a column means. Everything downstream —
+ * layout, drawing, the detail panel — is shared, so adding a view means
+ * answering those three questions and nothing else.
+ */
+
+export const TYPES = {
+  entry: { col: 0, label: 'Entry', color: 'entry' },
+  layout: { col: 0, label: 'Layout', color: 'entry' },
+  middleware: { col: 0, label: 'Middleware', color: 'entry' },
+  plugin: { col: 0, label: 'Plugin', color: 'entry' },
+  route: { col: 1, label: 'Route', color: 'route' },
+  component: { col: 2, label: 'Component', color: 'component' },
+  'lib-component': { col: 3, label: 'Library component', color: 'lib' },
+  composable: { col: 4, label: 'Composable', color: 'composable' },
+  store: { col: 4, label: 'Store', color: 'store' },
+  collection: { col: 5, label: 'Content collection', color: 'collection' },
+  server: { col: 5, label: 'Server route', color: 'server' },
+  external: { col: 5, label: 'External service', color: 'external' },
+  config: { col: 5, label: 'Config', color: 'config' },
+}
+
+const LAYER_TITLES = [
+  'Entry & layouts',
+  'Routes',
+  'Components',
+  'Library',
+  'Composables',
+  'Data & services',
+]
+export const EDGE_VERB = {
+  renders: 'renders',
+  uses: 'uses',
+  queries: 'queries',
+  fetches: 'fetches',
+  reads: 'reads',
+  wraps: 'wraps',
+  guards: 'guards',
+  depends: 'depends on',
+}
+
+const STRUCTURE_KINDS = new Set(['renders', 'wraps'])
+const SOURCE_TYPES = new Set(['collection', 'server', 'external', 'config'])
+
+export const groupKey = (n) => n.meta.group ?? n.type
+
+export function adjacency(edges) {
+  const out = new Map()
+  const inc = new Map()
+  for (const e of edges) {
+    if (!out.has(e.from)) out.set(e.from, [])
+    out.get(e.from).push(e.to)
+    if (!inc.has(e.to)) inc.set(e.to, [])
+    inc.get(e.to).push(e.from)
+  }
+  return { out, inc }
+}
+
+/**
+ * Depth of each node as its longest path from a root. Longest rather than
+ * shortest so a component used at depth 1 and depth 4 sits after everything
+ * that renders it, which is what keeps edges pointing forwards. Iteration is
+ * bounded because a render cycle would otherwise never settle.
+ */
+function longestPath(nodes, edges, maxDepth = 24) {
+  const depth = new Map(nodes.map((n) => [n.id, 0]))
+  for (let pass = 0; pass < nodes.length; pass++) {
+    let changed = false
+    for (const e of edges) {
+      if (!depth.has(e.from) || !depth.has(e.to)) continue
+      const next = Math.min(depth.get(e.from) + 1, maxDepth)
+      if (next > depth.get(e.to)) {
+        depth.set(e.to, next)
+        changed = true
+      }
+    }
+    if (!changed) break
+  }
+  return depth
+}
+
+function subgraph(G, keep, edgeFilter = () => true) {
+  const nodes = G.nodes.filter((n) => keep(n))
+  const ids = new Set(nodes.map((n) => n.id))
+  const edges = G.edges.filter((e) => ids.has(e.from) && ids.has(e.to) && edgeFilter(e))
+  return { nodes, edges }
+}
+
+export const VIEWS = {
+  layers: {
+    name: 'Layers',
+    hint: 'Every entity, arranged by kind. The whole app at once.',
+    project(G, state) {
+      const { nodes, edges } = subgraph(G, (n) => state.types.has(n.type))
+      return { nodes, edges, col: (n) => TYPES[n.type].col, title: (c) => LAYER_TITLES[c] }
+    },
+  },
+
+  render: {
+    name: 'Render tree',
+    hint: 'What renders what, from entry points down. Depth is nesting depth.',
+    project(G, state) {
+      const keep = new Set(['entry', 'layout', 'route', 'component', 'lib-component'])
+      // Markdown renders components too (MDC). Drop the collections that do and
+      // those components lose their only parent, then masquerade as entry
+      // points — so content collections that render something belong here.
+      const renderers = new Set()
+      for (const e of G.edges) {
+        if (STRUCTURE_KINDS.has(e.kind)) renderers.add(e.from)
+      }
+      const { nodes, edges } = subgraph(
+        G,
+        (n) =>
+          state.types.has(n.type) &&
+          (keep.has(n.type) || (n.type === 'collection' && renderers.has(n.id))),
+        (e) => STRUCTURE_KINDS.has(e.kind),
+      )
+      const depth = longestPath(nodes, edges)
+      return {
+        nodes,
+        edges,
+        col: (n) => depth.get(n.id),
+        title: (c) => (c === 0 ? 'Entry points' : `Nested depth ${c}`),
+      }
+    },
+  },
+
+  data: {
+    name: 'Data flow',
+    hint: 'Every edge reversed, so data reads left to right: origin → who reads it → where it surfaces.',
+    project(G, state) {
+      // Keep only what can actually reach a data source, walking backwards from
+      // each source. A purely presentational component has no place here.
+      const { inc } = adjacency(G.edges)
+      const keep = new Set(G.nodes.filter((n) => SOURCE_TYPES.has(n.type)).map((n) => n.id))
+      const stack = [...keep]
+      while (stack.length) {
+        for (const from of inc.get(stack.pop()) ?? []) {
+          if (!keep.has(from)) {
+            keep.add(from)
+            stack.push(from)
+          }
+        }
+      }
+      const picked = subgraph(G, (n) => keep.has(n.id) && state.types.has(n.type))
+      // Reversed: the dependency graph points consumer → source, but data
+      // travels the other way.
+      const edges = picked.edges.map((e) => ({
+        from: e.to,
+        to: e.from,
+        kind: e.kind,
+        reversed: true,
+      }))
+      const depth = longestPath(picked.nodes, edges)
+      return {
+        nodes: picked.nodes,
+        edges,
+        col: (n) => depth.get(n.id),
+        title: (c) =>
+          ['Data origin', 'Read directly by', 'Surfaced by'][c] ?? `Surfaced by · ${c - 1}`,
+      }
+    },
+  },
+
+  modules: {
+    name: 'Modules',
+    hint: 'Folders and packages as single blocks. Line weight is how many references cross between them.',
+    // The module is the group, so grouping again would just repeat every label.
+    grouping: false,
+    project(G, state) {
+      const groups = new Map()
+      for (const n of G.nodes) {
+        if (!state.types.has(n.type)) continue
+        const k = groupKey(n)
+        if (!groups.has(k)) groups.set(k, [])
+        groups.get(k).push(n)
+      }
+
+      const nodes = []
+      const moduleOf = new Map()
+      for (const [key, members] of groups) {
+        const id = `module:${key}`
+        for (const m of members) moduleOf.set(m.id, id)
+        const kinds = tally(members.map((m) => m.type))
+        nodes.push({
+          id,
+          type: kinds[0][0],
+          label: key,
+          file: null,
+          meta: {
+            module: true,
+            group: key,
+            members: members.length,
+            kinds: kinds.map(([t, n]) => `${n} ${TYPES[t].label.toLowerCase()}`),
+            names: members.map((m) => m.label).sort(),
+            // A module's column is where its members mostly live, so the
+            // aggregate still reads left-to-right like the layer view.
+            col: Math.round(mean(members.map((m) => TYPES[m.type].col))),
+          },
+        })
+      }
+
+      const agg = new Map()
+      for (const e of G.edges) {
+        const from = moduleOf.get(e.from)
+        const to = moduleOf.get(e.to)
+        if (!from || !to || from === to) continue
+        const key = `${from}|${to}`
+        if (!agg.has(key)) agg.set(key, { from, to, kind: 'depends', weight: 0 })
+        agg.get(key).weight++
+      }
+
+      return {
+        nodes,
+        edges: [...agg.values()],
+        col: (n) => n.meta.col,
+        title: (c) => LAYER_TITLES[c],
+      }
+    },
+  },
+
+  sitemap: {
+    name: 'Sitemap',
+    hint: 'Every page and everything it pulls in, laid out from the routes. Whatever a page never reaches — dead code — drops away.',
+    project(G, state) {
+      // Walk forward from the routes; keep only what a page can actually reach.
+      const { out } = adjacency(G.edges)
+      const keep = new Set(G.nodes.filter((n) => n.type === 'route').map((n) => n.id))
+      const stack = [...keep]
+      while (stack.length) {
+        for (const to of out.get(stack.pop()) ?? []) {
+          if (!keep.has(to)) {
+            keep.add(to)
+            stack.push(to)
+          }
+        }
+      }
+      // Drop wraps/guards so routes are the true left-most spine, not layouts.
+      const { nodes, edges } = subgraph(
+        G,
+        (n) => keep.has(n.id) && state.types.has(n.type),
+        (e) => e.kind !== 'wraps' && e.kind !== 'guards',
+      )
+      const depth = longestPath(nodes, edges)
+      return {
+        nodes,
+        edges,
+        col: (n) => depth.get(n.id),
+        title: (c) => (c === 0 ? 'Pages' : c === 1 ? 'Renders & uses' : `Reached · ${c}`),
+      }
+    },
+  },
+
+  cleanup: {
+    name: 'Cleanup',
+    hint: 'Only what the findings flag — dead components, uncalled composables, empty collections, render cycles — gathered in one place.',
+    // Each flagged node stands on its own; grouping would just repeat kinds.
+    grouping: false,
+    project(G, state) {
+      // Only warnings — genuine remove-candidates. Info findings (a static
+      // route, a webhook with no caller) are normal, not cleanup.
+      const flagged = new Set(
+        (G.findings ?? []).filter((f) => f.severity === 'warn').flatMap((f) => f.nodes),
+      )
+      const { nodes, edges } = subgraph(G, (n) => flagged.has(n.id) && state.types.has(n.type))
+      return { nodes, edges, col: (n) => TYPES[n.type].col, title: (c) => LAYER_TITLES[c] }
+    },
+  },
+}
+
+function tally(items) {
+  const counts = new Map()
+  for (const it of items) counts.set(it, (counts.get(it) ?? 0) + 1)
+  return [...counts].sort((a, b) => b[1] - a[1])
+}
+
+const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length
+
+/**
+ * Isolate one node: keep only what it reaches and what reaches it. This is the
+ * "who consumes what" question asked of a single entity.
+ */
+export function applyFocus(proj, focusId) {
+  if (!focusId || !proj.nodes.some((n) => n.id === focusId)) return proj
+  const { out, inc } = adjacency(proj.edges)
+  const keep = new Set([focusId])
+  for (const dir of [out, inc]) {
+    const stack = [focusId]
+    while (stack.length) {
+      for (const next of dir.get(stack.pop()) ?? []) {
+        if (!keep.has(next)) {
+          keep.add(next)
+          stack.push(next)
+        }
+      }
+    }
+  }
+  return {
+    ...proj,
+    nodes: proj.nodes.filter((n) => keep.has(n.id)),
+    edges: proj.edges.filter((e) => keep.has(e.from) && keep.has(e.to)),
+  }
+}