@amulet-laboratories/astrolabe 0.4.0

package/src/adapters/nuxt/project.mjs

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { buildStack, pkgOf } from '../shared.mjs'
+
+const CONFIG_NAMES = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs']
+
+/** Whether `dir` looks like a Nuxt app — the presence of a nuxt.config. */
+export function detect(dir) {
+  const root = resolve(dir)
+  return CONFIG_NAMES.some((n) => existsSync(join(root, n)))
+}
+
+/**
+ * Locate the Nuxt app at `dir` and resolve the conventions that change where
+ * everything lives: srcDir (Nuxt 4 nests the app under app/) and whether
+ * component auto-import names carry their directory as a prefix.
+ */
+export function loadProject(dir) {
+  const root = resolve(dir)
+  const configName = CONFIG_NAMES.find((n) => existsSync(join(root, n)))
+  if (!configName) {
+    throw new Error(`No nuxt.config found in ${root} — is this a Nuxt app?`)
+  }
+  const configRaw = readFileSync(join(root, configName), 'utf8')
+  const srcDir = resolveSrcDir(root, configRaw)
+
+  let pkg = {}
+  try {
+    pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+  } catch {
+    // A Nuxt app without a readable package.json is unusual but not fatal.
+  }
+
+  // Layers this app extends. The main app is the first source and wins on any
+  // name collision; layers add whatever the app itself doesn't define.
+  const layers = resolveLayers(root, configRaw)
+
+  return {
+    root,
+    srcDir,
+    configName,
+    configRaw,
+    name: pkg.name || root.split('/').pop(),
+    description: pkg.description || '',
+    modules: parseModules(configRaw),
+    stack: buildStack(pkg),
+    pathPrefix: !/pathPrefix\s*:\s*false/.test(configRaw),
+    nuxtDir: existsSync(join(root, '.nuxt')) ? join(root, '.nuxt') : null,
+    layers,
+    // Every place to look for app code, main first. Scanners iterate this so a
+    // layer's pages/components/etc. land in the graph just like the app's own.
+    sources: [{ root, srcDir }, ...layers],
+  }
+}
+
+/** Nuxt 4 defaults srcDir to app/; an explicit srcDir in the config wins. */
+function resolveSrcDir(root, configRaw) {
+  const explicit = configRaw.match(/srcDir\s*:\s*['"]([^'"]+)['"]/)?.[1]
+  if (explicit) return resolve(root, explicit)
+  if (existsSync(join(root, 'app', 'pages')) || existsSync(join(root, 'app', 'app.vue'))) {
+    return join(root, 'app')
+  }
+  return root
+}
+
+/**
+ * Resolve `extends` to a flat list of `{ root, srcDir }` layers, depth-first so
+ * a nearer layer precedes a farther one. Only *local* layers (a relative or
+ * absolute path) are followed — remote layers (`github:…`, an npm package) would
+ * need a package install to resolve and are out of scope. A layer may itself
+ * extend further layers; a seen-set stops cycles and re-visits.
+ */
+function resolveLayers(root, configRaw, seen = new Set(), depth = 0) {
+  if (depth > 8) return []
+  const out = []
+  for (const spec of parseExtends(configRaw)) {
+    if (!spec.startsWith('.') && !spec.startsWith('/')) continue
+    const layerRoot = resolve(root, spec)
+    if (seen.has(layerRoot) || !existsSync(layerRoot)) continue
+    seen.add(layerRoot)
+    const cfg = CONFIG_NAMES.map((n) => join(layerRoot, n)).find(existsSync)
+    const layerRaw = cfg ? readFileSync(cfg, 'utf8') : ''
+    out.push({ root: layerRoot, srcDir: resolveSrcDir(layerRoot, layerRaw) })
+    out.push(...resolveLayers(layerRoot, layerRaw, seen, depth + 1))
+  }
+  return out
+}
+
+/** The layer specifiers in an `extends: '…'` or `extends: ['…', ['…', {}]]`. */
+function parseExtends(configRaw) {
+  const block = configRaw.match(/extends\s*:\s*(\[[\s\S]*?\]|['"][^'"]+['"])/)?.[1]
+  if (!block) return []
+  return [...block.matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1])
+}
+
+function parseModules(configRaw) {
+  const block = configRaw.match(/modules\s*:\s*\[([\s\S]*?)\]/)?.[1]
+  if (!block) return []
+  return [...block.matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1])
+}
+
+/**
+ * `.nuxt/components.d.ts` is the ground truth for auto-imported components:
+ * it names every component Nuxt resolved, including ones from node_modules
+ * (Rig, MDC prose components) that a convention scan of components/ can't see.
+ * Only present after `nuxt prepare` / `nuxt dev` has run.
+ */
+export function readGeneratedComponents(project) {
+  if (!project.nuxtDir) return null
+  const file = join(project.nuxtDir, 'components.d.ts')
+  if (!existsSync(file)) return null
+
+  const map = new Map()
+  const raw = readFileSync(file, 'utf8')
+  const re = /export const (\w+)\s*:\s*typeof import\("([^"]+)"\)/g
+  for (const [, name, spec] of raw.matchAll(re)) {
+    // Nuxt emits a Lazy* alias for every component; it's the same node.
+    if (name.startsWith('Lazy')) continue
+    if (map.has(name)) continue
+    map.set(name, classifySpecifier(spec, project))
+  }
+  return map.size ? map : null
+}
+
+/**
+ * Auto-imported composables/utils, keyed by name. Nuxt writes these as
+ * `export { a, b } from '<specifier>'`, where the specifier is a virtual
+ * module (#app/...), a bare package (@amulet-laboratories/rig), or a relative
+ * path into node_modules — each of which classifies differently.
+ */
+export function readGeneratedImports(project) {
+  if (!project.nuxtDir) return null
+  const file = join(project.nuxtDir, 'imports.d.ts')
+  if (!existsSync(file)) return null
+
+  const map = new Map()
+  const raw = readFileSync(file, 'utf8')
+  const re = /export\s*\{([^}]*)\}\s*from\s*'([^']+)'/g
+  for (const [, names, spec] of raw.matchAll(re)) {
+    const info = classifySpecifier(spec, project)
+    for (const part of names.split(',')) {
+      // Handle `foo as bar` — the local name is what appears in source. split()
+      // never yields an empty array, so pop() is always a string.
+      const name = part
+        .trim()
+        .split(/\s+as\s+/)
+        .pop()
+        .trim()
+      if (name && !map.has(name)) map.set(name, info)
+    }
+  }
+  return map.size ? map : null
+}
+
+function classifySpecifier(spec, project) {
+  if (spec.startsWith('#')) return { file: spec, origin: 'framework', pkg: spec.split('/')[0] }
+  if (spec.startsWith('.')) {
+    const file = resolve(project.nuxtDir, spec)
+    return { file, ...originOf(file) }
+  }
+  const pkg = spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0]
+  return { file: spec, origin: 'library', pkg }
+}
+
+/**
+ * Classify a resolved component/composable file: code you own vs. code a
+ * dependency brought in. The graph leans on this to keep your app's own
+ * structure visually dominant.
+ */
+export function originOf(file) {
+  if (!file.includes('node_modules')) return { origin: 'local', pkg: null }
+  return { origin: 'library', pkg: pkgOf(file) }
+}

package/src/adapters/registry.mjs

@@ -0,0 +1,23 @@
+/**
+ * The adapter registry. An adapter is a module exporting `{ name, detect, scan }`:
+ * `detect(dir)` returns whether it recognizes the app, and `scan(dir)` returns
+ * `{ project, graph, warnings }` in the canonical schema. Adding a framework is
+ * adding a module here — the core never imports an adapter directly.
+ *
+ * Order is priority: the first adapter whose `detect` passes wins, so more
+ * specific frameworks should precede more general ones.
+ */
+import * as nuxt from './nuxt/index.mjs'
+import * as vue from './vue/index.mjs'
+
+// Nuxt before Vue: a Nuxt app also has `vue`, so the more specific adapter wins.
+export const ADAPTERS = [nuxt, vue]
+
+export function detectAdapter(dir) {
+  const found = ADAPTERS.find((a) => a.detect(dir))
+  if (!found) {
+    const names = ADAPTERS.map((a) => a.name).join(', ')
+    throw new Error(`No supported framework found in ${dir} — looked for: ${names}`)
+  }
+  return found
+}

package/src/adapters/shared.mjs

@@ -0,0 +1,191 @@
+/**
+ * Framework-neutral plumbing shared by the adapters. Nuxt is Vue-with-more, so
+ * both adapters build on this: filesystem walking, parallel reads with warnings,
+ * git churn, the package stack, file-based route names, and the tag→render
+ * linking. Anything framework-specific stays in the adapter; this is the kit.
+ */
+import { execFile } from 'node:child_process'
+import { readFile, readdir } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { promisify } from 'node:util'
+
+import { normalizeTag } from '../core/sfc.mjs'
+
+const execFileAsync = promisify(execFile)
+
+/** Colocated tests aren't app source — never analyze them (found on real repos). */
+export const isTest = (file) => /\.(test|spec)\./.test(file) || /(^|\/)__tests__\//.test(file)
+
+/** Non-blank lines. A rough but honest proxy for how much code a file is. */
+export const countLoc = (source) => source.split('\n').filter((l) => l.trim()).length
+
+/** The package a node_modules file belongs to, pnpm layout included. */
+export function pkgOf(file) {
+  const m = file.match(/node_modules\/(?:\.pnpm\/[^/]+\/node_modules\/)?((?:@[^/]+\/)?[^/]+)/)
+  return m ? m[1] : 'unknown'
+}
+
+/** A node_modules file shortened to its package-relative path. */
+export const shortenPkgPath = (file) =>
+  file.match(/node_modules\/(?:\.pnpm\/[^/]+\/node_modules\/)?(.+)$/)?.[1] ?? file
+
+/** A shareable path for a node: repo-relative, or short package path for deps. */
+export const rel = (file, root) =>
+  file.includes('node_modules') ? shortenPkgPath(file) : relative(root, file)
+
+/**
+ * Walk a directory returning repo-relative paths of files matching `exts`.
+ * Missing directories yield an empty list — most app dirs are optional.
+ */
+export async function walk(dir, exts, root) {
+  const out = []
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      out.push(...(await walk(full, exts, root)))
+    } else if (exts.some((e) => entry.name.endsWith(e))) {
+      out.push(relative(root, full))
+    }
+  }
+  return out.sort()
+}
+
+/**
+ * Read `paths` in parallel and hand each result to `fn(path, source, i)` in
+ * array order, so a parallelized scan produces byte-identical output to a serial
+ * one. A read failure or a throw inside `fn` becomes a warning — keyed by
+ * `label(path)` — rather than aborting the whole scan: one malformed file must
+ * never cost the report.
+ */
+export async function readEach(paths, warnings, fn, label = (p) => p) {
+  const sources = await Promise.all(paths.map((p) => readFile(p, 'utf8').catch(() => null)))
+  paths.forEach((path, i) => {
+    if (sources[i] === null) {
+      warnings.push(`could not read ${label(path)}`)
+      return
+    }
+    try {
+      fn(path, sources[i], i)
+    } catch (err) {
+      warnings.push(`skipped ${label(path)}: ${err.message}`)
+    }
+  })
+}
+
+/** `readEach` over every non-test file under `dir` matching `exts`, walk() order. */
+export async function eachFile(dir, exts, warnings, fn) {
+  const files = (await walk(dir, exts, dir)).filter((f) => !isTest(f))
+  await readEach(
+    files.map((f) => join(dir, f)),
+    warnings,
+    (full, source, i) => fn(files[i], source),
+    (full) => relative(dir, full),
+  )
+}
+
+/** pages/category/[slug].vue → /category/:slug (file-based routing). */
+export function routeFromFile(file) {
+  const segments = file.replace(/\.vue$/, '').split('/')
+  const parts = []
+  for (const seg of segments) {
+    if (seg === 'index') continue
+    if (seg.startsWith('[...')) parts.push(`*${seg.slice(4, -1)}`)
+    else if (seg.startsWith('[')) parts.push(`:${seg.slice(1, -1)}`)
+    else parts.push(seg)
+  }
+  return `/${parts.join('/')}`
+}
+
+/** Wire a template's tags into `renders` edges, creating library-component nodes. */
+export function linkTags(g, fromId, tags, components) {
+  for (const tag of tags) {
+    const name = normalizeTag(tag.replace(/^Lazy/, ''))
+    const info = components.get(name)
+    if (!info) continue
+    const id = `component:${name}`
+    if (info.origin === 'library') {
+      g.node(id, {
+        type: 'lib-component',
+        label: name,
+        file: shortenPkgPath(info.file),
+        meta: { origin: 'library', pkg: info.pkg },
+      })
+    }
+    g.edge(fromId, id, 'renders')
+  }
+}
+
+/**
+ * How many commits have touched each file under `root`, keyed by root-relative
+ * path — a cheap proxy for churn / hotspots. One `git log` for the whole tree.
+ * Returns null when `root` isn't a git work tree or git is missing, so churn is
+ * always optional and never fatal.
+ */
+export async function gitChurn(root) {
+  let prefix, log
+  try {
+    ;[prefix, log] = await Promise.all([
+      execFileAsync('git', ['-C', root, 'rev-parse', '--show-prefix'], { maxBuffer: 1 << 20 }),
+      execFileAsync('git', ['-C', root, 'log', '--format=', '--name-only'], { maxBuffer: 1 << 28 }),
+    ])
+  } catch {
+    return null
+  }
+  return tallyNameOnly(log.stdout, prefix.stdout.trim())
+}
+
+/**
+ * Count each path in `git log --name-only` output, keeping only paths under
+ * `prefix` (the scanned dir's location within the repo) and re-rooting them to
+ * match the graph's repo-relative `file` fields. Pure, so it can be tested.
+ */
+export function tallyNameOnly(stdout, prefix = '') {
+  const counts = new Map()
+  for (const raw of stdout.split('\n')) {
+    const line = raw.trim()
+    if (!line || (prefix && !line.startsWith(prefix))) continue
+    const rel = prefix ? line.slice(prefix.length) : line
+    counts.set(rel, (counts.get(rel) ?? 0) + 1)
+  }
+  return counts
+}
+
+/**
+ * What an app is built on. Runtime dependencies first — they say more about the
+ * app than the toolchain does — with a headline framework version pulled out.
+ */
+export function buildStack(pkg) {
+  const deps = Object.entries(pkg.dependencies ?? {}).map(([name, version]) => ({
+    name,
+    version,
+    dev: false,
+  }))
+  const devDeps = Object.entries(pkg.devDependencies ?? {}).map(([name, version]) => ({
+    name,
+    version,
+    dev: true,
+  }))
+  const all = [...deps, ...devDeps]
+  return {
+    nuxt: all.find((d) => d.name === 'nuxt')?.version ?? null,
+    packageManager: pkg.packageManager ?? null,
+    node: pkg.engines?.node ?? null,
+    dependencies: all.sort((a, b) => Number(a.dev) - Number(b.dev) || a.name.localeCompare(b.name)),
+  }
+}
+
+/** Annotate each file-backed node with its commit count (the heat overlay). */
+export async function annotateChurn(g, root) {
+  const churn = await gitChurn(root)
+  if (!churn) return
+  for (const node of g.nodes.values()) {
+    if (node.file && churn.has(node.file)) node.meta.churn = churn.get(node.file)
+  }
+}

package/src/adapters/vue/index.mjs

@@ -0,0 +1,211 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { Graph } from '../../core/graph.mjs'
+import { normalizeTag, parseScript, parseSfc } from '../../core/sfc.mjs'
+import {
+  annotateChurn,
+  countLoc,
+  eachFile,
+  isTest,
+  linkTags,
+  readEach,
+  rel,
+  routeFromFile,
+  walk,
+} from '../shared.mjs'
+import { detect, loadProject } from './project.mjs'
+
+export const name = 'vue'
+export { detect }
+
+/**
+ * Read a plain Vue (Vite) app into the canonical graph. Reuses the Nuxt/Vue SFC
+ * parsing and file-route conventions; adds Pinia stores and Vue-flavoured data
+ * access, and drops the Nuxt-only pieces (content collections, Nitro server
+ * routes). Accurate on a bare clone because the unplugin manifests are committed.
+ */
+export async function scan(dir) {
+  const project = loadProject(dir)
+  const g = new Graph()
+  const warnings = []
+
+  const components = await resolveComponents(project)
+  if (!project.components) {
+    warnings.push(
+      'No components.d.ts found — falling back to a flat scan of src/components/. ' +
+        'Commit the unplugin manifest (or run the build) for exact auto-import names.',
+    )
+  }
+  const composables = await resolveComposables(project)
+  const ctx = { components, composables, stores: new Set() }
+
+  for (const [name, info] of components) {
+    if (info.origin === 'local') {
+      g.node(`component:${name}`, {
+        type: 'component',
+        label: name,
+        file: rel(info.file, project.root),
+        meta: { origin: 'local' },
+      })
+    }
+  }
+  for (const [name, info] of composables) {
+    g.node(`composable:${name}`, {
+      type: 'composable',
+      label: name,
+      file: rel(info.file, project.root),
+      meta: { origin: info.origin, pkg: info.pkg, loc: info.loc },
+    })
+  }
+
+  await scanStores(project, g, ctx, warnings)
+  await scanPages(project, g, ctx, warnings)
+  await scanComponentBodies(project, g, ctx, warnings)
+  await scanComposableBodies(project, g, ctx, warnings)
+  await scanEntry(project, g, ctx, warnings)
+
+  await annotateChurn(g, project.root)
+
+  return { project, graph: g, warnings }
+}
+
+async function resolveComponents(project) {
+  if (project.components) return project.components
+  const map = new Map()
+  const dir = join(project.srcDir, 'components')
+  for (const file of await walk(dir, ['.vue'], dir)) {
+    const name = normalizeTag(
+      file
+        .replace(/\.vue$/, '')
+        .split('/')
+        .pop(),
+    )
+    if (!map.has(name)) map.set(name, { file: join(dir, file), origin: 'local', pkg: null })
+  }
+  return map
+}
+
+/**
+ * App composables: the `use*` auto-imports the manifest lists, plus a scan of
+ * composables/ for `export const use…`. Only `use*` exports become nodes — a
+ * utility module that exports plain helpers is not a phantom composable (the
+ * false positive the Nuxt corpus surfaced), and test files are skipped.
+ */
+async function resolveComposables(project) {
+  const map = new Map(project.autoImports ?? [])
+  const dir = join(project.srcDir, 'composables')
+  for (const file of await walk(dir, ['.ts', '.js', '.mts'], dir)) {
+    if (isTest(file)) continue
+    const full = join(dir, file)
+    const source = await readFile(full, 'utf8').catch(() => null)
+    if (source == null) continue
+    for (const [, name] of source.matchAll(
+      /export\s+(?:const|function|async function)\s+(use[A-Z]\w*)/g,
+    )) {
+      if (!map.has(name))
+        map.set(name, { file: full, origin: 'local', pkg: null, loc: countLoc(source) })
+    }
+  }
+  return map
+}
+
+/** Pinia stores: `export const useXStore = defineStore('id', …)`. */
+async function scanStores(project, g, ctx, warnings) {
+  const dir = join(project.srcDir, 'stores')
+  await eachFile(dir, ['.ts', '.js', '.mts'], warnings, (file, source) => {
+    for (const [, useName, id] of source.matchAll(
+      /export\s+const\s+(use\w+)\s*=\s*defineStore\s*\(\s*['"`]([^'"`]+)/g,
+    )) {
+      const nid = `store:${useName}`
+      g.node(nid, {
+        type: 'store',
+        label: id,
+        file: rel(join(dir, file), project.root),
+        meta: { id, loc: countLoc(source) },
+      })
+      ctx.stores.add(useName)
+      linkScript(g, nid, parseScript(source), ctx)
+    }
+  })
+}
+
+async function scanPages(project, g, ctx, warnings) {
+  const dir = join(project.srcDir, 'pages')
+  await eachFile(dir, ['.vue'], warnings, (file, source) => {
+    const route = routeFromFile(file)
+    const id = `route:${route}`
+    const parsed = parseSfc(source, join(dir, file))
+    g.node(id, {
+      type: 'route',
+      label: route,
+      file: rel(join(dir, file), project.root),
+      meta: { dynamic: /[[\]]/.test(file), props: parsed.props, loc: countLoc(source) },
+    })
+    linkTags(g, id, parsed.tags, ctx.components)
+    linkScript(g, id, parsed, ctx)
+  })
+}
+
+async function scanComponentBodies(project, g, ctx, warnings) {
+  const locals = [...ctx.components].filter(([, info]) => info.origin === 'local')
+  await readEach(
+    locals.map(([, info]) => info.file),
+    warnings,
+    (file, source, i) => {
+      const [name, info] = locals[i]
+      const id = `component:${name}`
+      const parsed = parseSfc(source, info.file)
+      const node = g.nodes.get(id)
+      if (node) node.meta = { ...node.meta, props: parsed.props, loc: countLoc(source) }
+      linkTags(g, id, parsed.tags, ctx.components)
+      linkScript(g, id, parsed, ctx)
+    },
+    (file) => rel(file, project.root),
+  )
+}
+
+async function scanComposableBodies(project, g, ctx, warnings) {
+  const byFile = new Map()
+  for (const [name, info] of ctx.composables) {
+    if (info.origin !== 'local') continue
+    if (!byFile.has(info.file)) byFile.set(info.file, [])
+    byFile.get(info.file).push(name)
+  }
+  await readEach(
+    [...byFile.keys()],
+    warnings,
+    (file, source) => {
+      const parsed = parseScript(source)
+      for (const name of byFile.get(file)) linkScript(g, `composable:${name}`, parsed, ctx)
+    },
+    (file) => rel(file, project.root),
+  )
+}
+
+async function scanEntry(project, g, ctx, warnings) {
+  const appFile = join(project.srcDir, 'App.vue')
+  await readEach([appFile], warnings, (file, source) => {
+    const parsed = parseSfc(source, appFile)
+    g.node('entry:App', {
+      type: 'entry',
+      label: 'App.vue',
+      file: rel(appFile, project.root),
+      meta: { loc: countLoc(source) },
+    })
+    linkTags(g, 'entry:App', parsed.tags, ctx.components)
+    linkScript(g, 'entry:App', parsed, ctx)
+  })
+}
+
+/** Data access, Vue-flavoured: composable/store calls, and external hosts. */
+function linkScript(g, fromId, parsed, ctx) {
+  for (const name of parsed.calls) {
+    if (ctx.composables.has(name)) g.edge(fromId, `composable:${name}`, 'uses')
+    else if (ctx.stores.has(name)) g.edge(fromId, `store:${name}`, 'uses')
+  }
+  for (const host of parsed.externals) {
+    g.node(`external:${host}`, { type: 'external', label: host, meta: {} })
+    g.edge(fromId, `external:${host}`, 'fetches')
+  }
+}