@amulet-laboratories/astrolabe 0.4.0

package/src/core/findings.mjs

@@ -0,0 +1,147 @@
+/**
+ * Findings are things worth telling someone about a repo that the diagram
+ * alone won't make them notice: dead code, endpoints with no handler, render
+ * cycles. Pure function over the serialized graph so the CLI, --json output and
+ * the HTML report all say exactly the same thing.
+ *
+ * The bar for a finding is that it is *actionable* and *true*. Anything the
+ * analyzer can't be sure about belongs in the notes, not here — a confidently
+ * wrong finding costs more trust than a missing one earns.
+ */
+export function computeFindings(nodes, edges) {
+  const incoming = new Map()
+  const outgoing = new Map()
+  for (const e of edges) {
+    if (!incoming.has(e.to)) incoming.set(e.to, [])
+    incoming.get(e.to).push(e)
+    if (!outgoing.has(e.from)) outgoing.set(e.from, [])
+    outgoing.get(e.from).push(e)
+  }
+
+  const isLocal = (n) => n.meta.origin !== 'library' && !n.meta.pkg
+  const unreferenced = (n) => !incoming.get(n.id)?.length
+  const found = []
+  const add = (id, severity, nodeList, title, detail) => {
+    if (nodeList.length)
+      found.push({
+        id,
+        severity,
+        title: title(nodeList.length),
+        detail,
+        nodes: nodeList.map((n) => n.id),
+      })
+  }
+
+  add(
+    'orphan-components',
+    'warn',
+    nodes.filter((n) => n.type === 'component' && isLocal(n) && unreferenced(n)),
+    (n) => `${n} component${n === 1 ? '' : 's'} nothing renders`,
+    'No page, layout, component or markdown file references these. Likely dead code.',
+  )
+
+  add(
+    'unused-composables',
+    'warn',
+    nodes.filter((n) => n.type === 'composable' && isLocal(n) && unreferenced(n)),
+    (n) => `${n} composable${n === 1 ? '' : 's'} nothing calls`,
+    'Defined under composables/ but never called. The file may still be imported for its types, so check before deleting it.',
+  )
+
+  add(
+    'missing-handlers',
+    'warn',
+    nodes.filter((n) => n.type === 'server' && n.meta.inferred),
+    (n) => `${n} endpoint${n === 1 ? '' : 's'} with no handler file`,
+    'Something fetches these paths but no matching file exists under server/. Either the path is wrong, or the route is served from elsewhere.',
+  )
+
+  add(
+    'dead-server-routes',
+    'info',
+    nodes.filter((n) => n.type === 'server' && !n.meta.inferred && unreferenced(n)),
+    (n) => `${n} server route${n === 1 ? '' : 's'} with no fetch call`,
+    'No $fetch or useFetch in this app targets these. Normal for webhooks, cron targets, public APIs, and redirects reached by an href — this is not a dead-code claim.',
+  )
+
+  add(
+    'empty-collections',
+    'warn',
+    nodes.filter((n) => n.type === 'collection' && n.file && !n.meta.files && !n.meta.remote),
+    (n) => `${n} content collection${n === 1 ? '' : 's'} with no files`,
+    'Declared in content.config.ts but its source glob matched nothing.',
+  )
+
+  add(
+    'static-routes',
+    'info',
+    nodes.filter(
+      (n) => n.type === 'route' && !(outgoing.get(n.id) ?? []).some((e) => DATA_KINDS.has(e.kind)),
+    ),
+    (n) => `${n} route${n === 1 ? '' : 's'} read no data`,
+    'These pages query no collection, call no endpoint and read no config — fully static.',
+  )
+
+  for (const cycle of renderCycles(nodes, edges)) {
+    found.push({
+      id: `render-cycle:${cycle.join('>')}`,
+      severity: 'warn',
+      title: 'Render cycle',
+      detail: cycle.map((id) => id.split(':').pop()).join(' → '),
+      nodes: cycle,
+    })
+  }
+
+  const order = { warn: 0, info: 1 }
+  return found.sort(
+    (a, b) => order[a.severity] - order[b.severity] || b.nodes.length - a.nodes.length,
+  )
+}
+
+const DATA_KINDS = new Set(['queries', 'fetches', 'reads'])
+
+/**
+ * Cycles in the render graph, via depth-first search for a back edge to a node
+ * still on the current path. A component that transitively renders itself is
+ * either intentional recursion or an infinite loop; either way it's worth
+ * knowing about.
+ */
+function renderCycles(nodes, edges) {
+  const out = new Map()
+  for (const e of edges) {
+    if (e.kind !== 'renders') continue
+    if (!out.has(e.from)) out.set(e.from, [])
+    out.get(e.from).push(e.to)
+  }
+
+  const WHITE = 0
+  const GREY = 1
+  const BLACK = 2
+  const colour = new Map(nodes.map((n) => [n.id, WHITE]))
+  const path = []
+  const seen = new Set()
+  const cycles = []
+
+  const visit = (id) => {
+    colour.set(id, GREY)
+    path.push(id)
+    for (const next of out.get(id) ?? []) {
+      if (colour.get(next) === GREY) {
+        const cycle = path.slice(path.indexOf(next))
+        // Same cycle found from different entry points is one cycle.
+        const key = [...cycle].sort().join('|')
+        if (!seen.has(key)) {
+          seen.add(key)
+          cycles.push(cycle)
+        }
+      } else if (colour.get(next) === WHITE) {
+        visit(next)
+      }
+    }
+    path.pop()
+    colour.set(id, BLACK)
+  }
+
+  for (const n of nodes) if (colour.get(n.id) === WHITE) visit(n.id)
+  return cycles
+}

package/src/core/graph.mjs

@@ -0,0 +1,148 @@
+import { computeFindings } from './findings.mjs'
+
+/**
+ * The graph builder every adapter writes into, plus the finalize pipeline that
+ * turns a freshly-scanned graph into the serialized report shape. Nothing here
+ * knows about any framework: an adapter produces framework-specific nodes and
+ * edges in the canonical vocabulary (see schema.mjs), and this file does the
+ * universal post-processing — prune, group, findings, stats — that every
+ * adapter's output goes through identically.
+ */
+export class Graph {
+  constructor() {
+    this.nodes = new Map()
+    this.edges = new Map()
+  }
+
+  node(id, data) {
+    if (!this.nodes.has(id)) this.nodes.set(id, { id, ...data, meta: data.meta ?? {} })
+    return this.nodes.get(id)
+  }
+
+  has(id) {
+    return this.nodes.has(id)
+  }
+
+  edge(from, to, kind) {
+    if (from === to) return
+    const key = `${from}|${to}|${kind}`
+    if (!this.edges.has(key)) this.edges.set(key, { from, to, kind })
+  }
+
+  serialize() {
+    return { nodes: [...this.nodes.values()], edges: [...this.edges.values()] }
+  }
+}
+
+/**
+ * Turn an adapter's result — `{ project, graph, warnings }` — into the report
+ * shape the CLI, `--json`, and the HTML renderer all consume. The order here is
+ * load-bearing: prune before grouping so a dropped node never seeds a group,
+ * and findings/stats run on the serialized form so they see exactly what ships.
+ */
+export function finalize({ project, graph, warnings }) {
+  prune(graph)
+  assignGroups(graph)
+  const { nodes, edges } = graph.serialize()
+  return {
+    project: publicProject(project),
+    warnings,
+    nodes,
+    edges,
+    findings: computeFindings(nodes, edges),
+    stats: statsOf(nodes),
+  }
+}
+
+/**
+ * An adapter carries internals (absolute paths, raw config source) that have no
+ * business in a report someone may share. Only these fields ship — this is the
+ * canonical project shape every adapter is expected to fill.
+ */
+function publicProject(project) {
+  return {
+    name: project.name,
+    description: project.description,
+    root: project.root,
+    modules: project.modules,
+    stack: project.stack,
+  }
+}
+
+function statsOf(nodes) {
+  const local = nodes.filter((n) => n.meta.loc)
+  return {
+    files: local.length,
+    loc: local.reduce((sum, n) => sum + n.meta.loc, 0),
+    contentFiles: nodes
+      .filter((n) => n.type === 'collection')
+      .reduce((sum, n) => sum + (n.meta.files ?? 0), 0),
+  }
+}
+
+/**
+ * Every node gets an owner: the package it came from, or the directory it
+ * lives in. Directories already encode how the app is organised
+ * (components/hub, server/api/sync), so this is grouping the author wrote
+ * rather than grouping we invented.
+ */
+function assignGroups(g) {
+  for (const node of g.nodes.values()) {
+    node.meta.group =
+      node.meta.pkg ?? SYNTHETIC_GROUP[node.type] ?? (node.file ? dirGroup(node.file) : node.type)
+  }
+}
+
+/**
+ * Types whose home is conceptual rather than a directory. Collections are
+ * declared in content.config.ts, so grouping them by file would file them
+ * under the repo root alongside nothing else.
+ */
+const SYNTHETIC_GROUP = {
+  collection: 'content',
+  config: 'config',
+  external: 'external services',
+}
+
+/**
+ * Directory of a file, minus dynamic segments, capped in depth — otherwise
+ * server/api/games/debate/[slug] becomes its own group of one and the grouping
+ * says nothing.
+ */
+function dirGroup(file, depth = 3) {
+  const parts = file
+    .split('/')
+    .slice(0, -1)
+    .filter((p) => !p.startsWith('['))
+  return parts.slice(0, depth).join('/') || 'root'
+}
+
+/**
+ * Drop unconnected library nodes. A dependency exports far more than any one
+ * app uses (Rig ships ~30 composables), and listing the unused ones describes
+ * the dependency rather than this app. Unconnected *local* nodes stay — a
+ * component nothing renders is a finding, not noise.
+ */
+function prune(g) {
+  const touched = new Set()
+  for (const e of g.edges.values()) {
+    touched.add(e.from)
+    touched.add(e.to)
+  }
+  for (const [id, node] of g.nodes) {
+    if (touched.has(id)) continue
+    const fromLibrary = node.meta.origin === 'library'
+    if (
+      node.type === 'lib-component' ||
+      node.type === 'external' ||
+      (node.type === 'composable' && fromLibrary)
+    ) {
+      g.nodes.delete(id)
+    }
+  }
+
+  // An edge to a pruned or never-created node would render as a dangling line.
+  for (const [key, e] of g.edges) {
+    if (!g.nodes.has(e.from) || !g.nodes.has(e.to)) g.edges.delete(key)
+  }
+}

package/src/core/layout.mjs

@@ -0,0 +1,141 @@
+/**
+ * One layout engine for every view. It takes a projection (nodes, edges, and a
+ * rule for which column a node belongs to) and produces coordinates.
+ *
+ * Columns come from the view. Vertical order is barycenter: repeatedly place
+ * each node near the average position of its neighbours, which pulls connected
+ * things onto the same rows and takes most of the crossings out.
+ *
+ * Pure: no DOM. The browser client and the Node-side SVG renderer both import
+ * it, so the interactive diagram and a static export can never lay out
+ * differently.
+ */
+import { adjacency, groupKey } from './views.mjs'
+
+export const NODE_W = 190
+export const NODE_H = 26
+const ROW_GAP = 8
+const ROW_H = NODE_H + ROW_GAP
+const COL_GAP = 78
+const GROUP_H = 20
+const TOP = 44
+const BARY_PASSES = 6
+
+export function computeLayout(proj, state) {
+  const cols = new Map()
+  for (const n of proj.nodes) {
+    const c = proj.col(n) ?? 0
+    if (!cols.has(c)) cols.set(c, [])
+    cols.get(c).push(n)
+  }
+
+  const active = [...cols.keys()].sort((a, b) => a - b)
+  const { out, inc } = adjacency(proj.edges)
+
+  const order = new Map()
+  const reindex = () => {
+    for (const list of cols.values()) list.forEach((n, i) => order.set(n.id, i))
+  }
+  for (const c of active) cols.get(c).sort(byGroupThenLabel)
+  reindex()
+
+  for (let pass = 0; pass < BARY_PASSES; pass++) {
+    // Alternate which side we average against, so ordering information
+    // propagates both down and back up the columns.
+    const backward = pass % 2 === 1
+    for (const c of backward ? [...active].reverse() : active) {
+      const neighbours = backward ? out : inc
+      const list = cols.get(c)
+      const bary = new Map()
+      for (const n of list) {
+        const near = (neighbours.get(n.id) ?? [])
+          .map((id) => order.get(id))
+          .filter((v) => v !== undefined)
+        bary.set(
+          n.id,
+          near.length ? near.reduce((a, b) => a + b, 0) / near.length : order.get(n.id),
+        )
+      }
+      list.sort(state.group ? byGroupBarycenter(bary, groupMeans(list, bary)) : byBarycenter(bary))
+      reindex()
+    }
+  }
+
+  // Drop empty columns so a filtered or shallow view has no dead space.
+  const xs = new Map()
+  let x = 0
+  for (const c of active) {
+    xs.set(c, x)
+    x += NODE_W + COL_GAP
+  }
+
+  const pos = new Map()
+  const headers = []
+  let bottom = TOP
+  for (const c of active) {
+    let y = TOP
+    let current = null
+    for (const n of cols.get(c)) {
+      const key = groupKey(n)
+      if (state.group && key !== current) {
+        headers.push({ x: xs.get(c), y: y + GROUP_H - 7, text: key })
+        y += GROUP_H
+        current = key
+      }
+      pos.set(n.id, { x: xs.get(c), y })
+      y += ROW_H
+    }
+    bottom = Math.max(bottom, y)
+  }
+
+  return { cols, active, xs, pos, headers, width: Math.max(x - COL_GAP, NODE_W), height: bottom }
+}
+
+const byGroupThenLabel = (a, b) =>
+  groupKey(a).localeCompare(groupKey(b)) || a.label.localeCompare(b.label)
+const byBarycenter = (bary) => (a, b) =>
+  bary.get(a.id) - bary.get(b.id) || a.label.localeCompare(b.label)
+
+/** Average barycenter of each group, so a group can be placed as one block. */
+function groupMeans(list, bary) {
+  const acc = new Map()
+  for (const n of list) {
+    const key = groupKey(n)
+    if (!acc.has(key)) acc.set(key, [])
+    acc.get(key).push(bary.get(n.id))
+  }
+  return new Map([...acc].map(([key, vs]) => [key, vs.reduce((a, b) => a + b, 0) / vs.length]))
+}
+
+/**
+ * With grouping on, a group is ordered as a block — placed at its members'
+ * average position — and members are ordered within it. Without this the
+ * barycenter pass would interleave groups and the headers would be a lie.
+ */
+function byGroupBarycenter(bary, means) {
+  return (a, b) => {
+    const ga = groupKey(a)
+    const gb = groupKey(b)
+    if (ga !== gb) return means.get(ga) - means.get(gb) || ga.localeCompare(gb)
+    return bary.get(a.id) - bary.get(b.id) || a.label.localeCompare(b.label)
+  }
+}
+
+/**
+ * The cubic-bezier path for one edge between two laid-out nodes. Backwards or
+ * same-column edges bow out to the right rather than cutting back through the
+ * boxes between them. Shared by the interactive client and the SVG export.
+ */
+export function edgePath(e, layout) {
+  const a = layout.pos.get(e.from)
+  const b = layout.pos.get(e.to)
+  const y1 = a.y + NODE_H / 2
+  const y2 = b.y + NODE_H / 2
+  if (b.x <= a.x) {
+    const bulge = a.x + NODE_W + 26
+    return `M${a.x + NODE_W},${y1} C${bulge},${y1} ${bulge},${y2} ${b.x + NODE_W},${y2}`
+  }
+  const x1 = a.x + NODE_W
+  const mid = (x1 + b.x) / 2
+  return `M${x1},${y1} C${mid},${y1} ${mid},${y2} ${b.x},${y2}`
+}

package/src/core/render.mjs

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs'
+
+/**
+ * Assembles the single-file HTML report. The client lives as ordinary files
+ * rather than template strings, and is inlined here — the output has to work
+ * over file:// with no server and no network.
+ *
+ * `views.mjs` and `layout.mjs` are real ESM modules, imported unchanged by the
+ * Node-side SVG renderer so the interactive diagram and a static export share
+ * one layout engine. For the browser they're inlined into one classic script:
+ * their `import`/`export` keywords are stripped and they run in a shared scope,
+ * which is exactly the environment they were written for.
+ */
+const read = (name) => readFileSync(new URL(`./${name}`, import.meta.url), 'utf8')
+
+// Turn a shared ESM module into a fragment safe to concatenate into the one
+// classic <script>: drop imports (the dependency is inlined just above) and the
+// `export` keyword (the declaration stays, now a plain top-level binding).
+const inlineModule = (name) => {
+  const stripped = read(name)
+    .replace(/^\s*import[^\n]*\n/gm, '')
+    .replace(/^export\s+(?=(?:const|function|class|let|var)\b)/gm, '')
+  // The strip only handles single-line imports and `export <decl>`. A surviving
+  // module keyword (a multi-line import, an `export {…}` re-export, `export
+  // default`) would silently produce a broken browser bundle — fail loudly.
+  const leftover = stripped.match(/^\s*(?:import|export)\b/m)
+  if (leftover) {
+    throw new Error(`inlineModule(${name}): unstripped module statement "${leftover[0].trim()}"`)
+  }
+  return stripped
+}
+
+// Order matters: views defines TYPES/adjacency, layout imports them, then the
+// browser-only scripts (overview, app) drive the page off those globals.
+const CLIENT = [
+  inlineModule('views.mjs'),
+  inlineModule('layout.mjs'),
+  read('client/overview.js'),
+  read('client/app.js'),
+]
+
+export function renderHtml({ project, nodes, edges, warnings, findings, stats }) {
+  const payload = JSON.stringify({ project, nodes, edges, warnings, findings, stats })
+    // Keep the JSON from terminating the <script> that carries it.
+    .replace(/</g, '\\u003c')
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(project.name)} — app graph</title>
+<style>${read('client/styles.css')}</style>
+</head>
+<body>
+<header id="bar">
+  <div id="title">
+    <strong>${escapeHtml(project.name)}</strong>
+    <span id="subtitle">${escapeHtml(project.description || (project.stack?.nuxt ? 'Nuxt application' : 'Vue application'))}</span>
+  </div>
+  <div id="views" role="tablist"></div>
+  <div id="tools">
+    <label id="group-label"><input type="checkbox" id="group" checked> Group</label>
+    <input id="search" type="search" placeholder="Search…" autocomplete="off" spellcheck="false">
+    <button id="reset" type="button">Reset</button>
+  </div>
+</header>
+<div id="chips-row">
+  <div id="chips"></div>
+  <div id="focus-note" hidden>Isolated: <span></span><button id="focus-clear" type="button" title="Clear (Esc)">✕</button></div>
+</div>
+<main>
+  <div id="canvas">
+    <svg id="svg"><g id="viewport"><g id="links"></g><g id="cols"></g><g id="nodes"></g></g></svg>
+    <div id="warnings"></div>
+    <div id="hint"></div>
+  </div>
+  <aside id="panel"><div id="panel-body" class="overview"></div></aside>
+</main>
+<script id="data" type="application/json">${payload}</script>
+<script>${CLIENT.join('\n')}</script>
+</body>
+</html>
+`
+}
+
+function escapeHtml(s) {
+  return String(s).replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
+  )
+}

package/src/core/schema.mjs

@@ -0,0 +1,67 @@
+/**
+ * The canonical graph vocabulary — the contract between adapters and the core.
+ *
+ * An adapter's whole job is to read a framework's conventions and emit nodes
+ * and edges in *these* kinds. The core (findings, layout, render, client) is
+ * written against this vocabulary and nothing else, so a new framework becomes
+ * a new adapter rather than a change to everything downstream.
+ *
+ * The kinds below were derived from Nuxt but named for what they are in any web
+ * app, so other adapters map onto them: a SvelteKit `+page.svelte` is a `route`,
+ * a `.svelte` file a `component`, a `load` function or store a `composable`, a
+ * `+server.ts` an `endpoint` (`server`), and so on.
+ */
+
+/** Bumped when the shape of a serialized graph changes in a breaking way. */
+export const SCHEMA_VERSION = 1
+
+/** The canonical node kinds and their human labels. */
+export const NODE_KINDS = {
+  entry: { label: 'Entry' },
+  layout: { label: 'Layout' },
+  middleware: { label: 'Middleware' },
+  plugin: { label: 'Plugin' },
+  route: { label: 'Route' },
+  component: { label: 'Component' },
+  'lib-component': { label: 'Library component' },
+  composable: { label: 'Composable' },
+  store: { label: 'Store' },
+  collection: { label: 'Content collection' },
+  server: { label: 'Server route' },
+  external: { label: 'External service' },
+  config: { label: 'Config' },
+}
+
+/** The canonical edge kinds. (The verb each reads as lives in the client's EDGE_VERB.) */
+export const EDGE_KINDS = {
+  renders: 'renders',
+  wraps: 'wraps',
+  guards: 'guards',
+  uses: 'uses',
+  queries: 'queries',
+  fetches: 'fetches',
+  reads: 'reads',
+}
+
+/**
+ * Assert an adapter produced a well-formed graph before the core touches it.
+ * Cheap structural checks only — every claim here is something a broken adapter
+ * would get wrong, and catching it at the seam beats a confusing render later.
+ * Returns the list of problems ([] when the graph conforms).
+ */
+export function validateGraph({ nodes, edges }) {
+  const problems = []
+  const ids = new Set()
+  for (const n of nodes ?? []) {
+    if (!n.id) problems.push(`node without an id: ${JSON.stringify(n)}`)
+    else if (ids.has(n.id)) problems.push(`duplicate node id: ${n.id}`)
+    else ids.add(n.id)
+    if (!NODE_KINDS[n.type]) problems.push(`unknown node kind "${n.type}" on ${n.id}`)
+  }
+  for (const e of edges ?? []) {
+    if (!EDGE_KINDS[e.kind]) problems.push(`unknown edge kind "${e.kind}" (${e.from} → ${e.to})`)
+    if (!ids.has(e.from)) problems.push(`edge from missing node: ${e.from}`)
+    if (!ids.has(e.to)) problems.push(`edge to missing node: ${e.to}`)
+  }
+  return problems
+}