@amulet-laboratories/astrolabe 0.4.0

package/src/adapters/nuxt/index.mjs

@@ -0,0 +1,541 @@
+import { readFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+
+import { Graph } from '../../core/graph.mjs'
+import { normalizeTag, parseMdcComponents, parseScript, parseSfc } from '../../core/sfc.mjs'
+import { sliceBalanced, topLevelKeys } from '../../core/syntax.mjs'
+import {
+  annotateChurn,
+  countLoc,
+  eachFile,
+  isTest,
+  linkTags,
+  readEach,
+  rel,
+  routeFromFile,
+  shortenPkgPath,
+  walk,
+} from '../shared.mjs'
+import { detect, loadProject, readGeneratedComponents, readGeneratedImports } from './project.mjs'
+
+// Composables from these packages are framework plumbing (useRoute, useHead,
+// useAsyncData). Their data-access is already drawn as typed edges, so drawing
+// them as nodes too would bury the app's own code in noise.
+const FRAMEWORK = /^(nuxt|vue|vue-router|h3|nitropack|@nuxt\/|@unhead|@vue\/|#)/
+
+/** This adapter handles any directory with a nuxt.config. */
+export const name = 'nuxt'
+export { detect }
+
+/**
+ * Read a Nuxt app into a canonical graph. Returns the raw graph plus its
+ * project metadata and warnings; the shared finalize pipeline (prune, group,
+ * findings, stats) runs in core, identically for every adapter.
+ */
+export async function scan(dir) {
+  const project = loadProject(dir)
+  const g = new Graph()
+  const warnings = []
+
+  const generatedComponents = readGeneratedComponents(project)
+  const generatedImports = readGeneratedImports(project)
+  if (!generatedComponents) {
+    warnings.push(
+      'No .nuxt/components.d.ts found — falling back to scanning components/. ' +
+        'Run `nuxt prepare` for exact auto-import names and library components.',
+    )
+  }
+
+  // Independent filesystem walks — overlap their I/O. Only resolveComposables
+  // pushes warnings, and all node insertion happens after, so order is stable.
+  const [componentsByName, composablesByName] = await Promise.all([
+    resolveComponents(project, generatedComponents),
+    resolveComposables(project, generatedImports, warnings),
+  ])
+
+  // Nodes for things that exist on disk, before any edges are drawn.
+  for (const [name, info] of componentsByName) {
+    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 composablesByName) {
+    g.node(`composable:${name}`, {
+      type: 'composable',
+      label: name,
+      file: rel(info.file, project.root),
+      meta: { origin: info.origin, pkg: info.pkg, loc: info.loc },
+    })
+  }
+
+  const collections = await scanContentConfig(project, g)
+  await scanLayouts(project, g, componentsByName, composablesByName, warnings)
+  // Before pages, so a page's definePageMeta middleware can link to real nodes.
+  await scanMiddlewareAndPlugins(project, g, composablesByName, warnings)
+  await scanPages(project, g, componentsByName, composablesByName, warnings)
+  await scanComponentBodies(project, g, componentsByName, composablesByName, warnings)
+  await scanComposableBodies(project, g, composablesByName, warnings)
+  await scanServer(project, g, warnings)
+  await scanContentFiles(project, g, collections, componentsByName, warnings)
+
+  await annotateChurn(g, project.root)
+
+  return { project, graph: g, warnings }
+}
+
+/**
+ * Collapse a route's dynamic segments to `*` so the two ways of writing the
+ * same endpoint land on one node: a caller's template literal
+ * (`/api/debate/${slug}/vote`) and its handler file
+ * (server/api/debate/[slug]/vote.post.ts → `/api/debate/:slug/vote`). Without
+ * this the caller invents a phantom endpoint and the real handler looks
+ * uncalled — two wrong facts from one mismatch.
+ */
+const canonicalRoute = (path) =>
+  path
+    .replace(/\$\{[^}]*\}/g, '*')
+    .replace(/:[A-Za-z_]\w*/g, '*')
+    .replace(/\*\*/g, '*')
+    .replace(/\/{2,}/g, '/')
+    .replace(/(.)\/$/, '$1')
+
+const serverId = (path) => `server:${canonicalRoute(path)}`
+
+/** What @nuxt/content accepts as a source file across page and data collections. */
+const CONTENT_EXTS = ['.md', '.json', '.yml', '.yaml', '.csv']
+
+/**
+ * Nuxt's fallback auto-import name for a component path: directory segments
+ * PascalCased and concatenated, but a segment is absorbed when the next already
+ * starts with it — account/AccountAvatar → AccountAvatar, not AccountAccountAvatar
+ * (the false-orphan bug real repos surfaced). Only used without .nuxt.
+ */
+export function componentName(segments, pathPrefix) {
+  const parts = (pathPrefix ? segments : [segments.at(-1)]).map(normalizeTag)
+  const out = []
+  for (const seg of parts) {
+    if (out.length && seg.toLowerCase().startsWith(out.at(-1).toLowerCase()))
+      out[out.length - 1] = seg
+    else out.push(seg)
+  }
+  return out.join('')
+}
+
+/**
+ * Every root to look for app code in: the app itself, then each layer it
+ * extends. Main is first, so a node it defines wins — a layer only fills in what
+ * the app doesn't. For an app with no `extends`, this is just the app.
+ */
+const sourcesOf = (project) => project.sources ?? [{ root: project.root, srcDir: project.srcDir }]
+
+async function resolveComponents(project, generated) {
+  const map = new Map()
+  if (generated) {
+    for (const [name, info] of generated) map.set(name, info)
+    return map
+  }
+  // Fallback: mirror Nuxt's own naming rules over components/, across the app
+  // and its layers. Main is scanned first and wins on any name collision.
+  for (const src of sourcesOf(project)) {
+    const dir = join(src.srcDir, 'components')
+    for (const file of await walk(dir, ['.vue'], dir)) {
+      if (isTest(file)) continue
+      const name = componentName(file.replace(/\.vue$/, '').split('/'), project.pathPrefix)
+      if (!map.has(name)) map.set(name, { file: join(dir, file), origin: 'local', pkg: null })
+    }
+  }
+  return map
+}
+
+async function resolveComposables(project, generated, warnings) {
+  const map = new Map()
+  for (const src of sourcesOf(project)) {
+    const dir = join(src.srcDir, 'composables')
+    await eachFile(dir, ['.ts', '.js', '.mts'], warnings, (file, source) => {
+      const full = join(dir, file)
+      const exported = [
+        ...source.matchAll(/export\s+(?:const|function|async function)\s+(use[A-Z]\w*)/g),
+      ]
+      const names = exported.length
+        ? exported.map((m) => m[1])
+        : [basename(file).replace(/\.\w+$/, '')]
+      for (const name of names)
+        if (!map.has(name))
+          map.set(name, { file: full, origin: 'local', pkg: null, loc: countLoc(source) })
+    })
+  }
+  if (generated) {
+    for (const [name, info] of generated) {
+      if (map.has(name) || !name.startsWith('use')) continue
+      if (info.origin === 'library' && info.pkg && !FRAMEWORK.test(info.pkg)) map.set(name, info)
+    }
+  }
+  return map
+}
+
+/** Wire one parsed script's data-access into typed edges out of `fromId`. */
+function linkScript(g, fromId, parsed, composablesByName) {
+  for (const name of parsed.collections) {
+    g.node(`collection:${name}`, { type: 'collection', label: name, meta: {} })
+    g.edge(fromId, `collection:${name}`, 'queries')
+  }
+  for (const url of parsed.endpoints) {
+    const id = serverId(url)
+    g.node(id, { type: 'server', label: url, meta: { inferred: true } })
+    g.edge(fromId, id, 'fetches')
+  }
+  for (const host of parsed.externals) {
+    g.node(`external:${host}`, { type: 'external', label: host, meta: {} })
+    g.edge(fromId, `external:${host}`, 'fetches')
+  }
+  for (const name of parsed.calls) {
+    if (composablesByName.has(name)) g.edge(fromId, `composable:${name}`, 'uses')
+  }
+  if (parsed.usesAppConfig) {
+    g.node('config:appConfig', { type: 'config', label: 'appConfig', meta: {} })
+    g.edge(fromId, 'config:appConfig', 'reads')
+  }
+  if (parsed.usesRuntimeConfig) {
+    g.node('config:runtimeConfig', { type: 'config', label: 'runtimeConfig', meta: {} })
+    g.edge(fromId, 'config:runtimeConfig', 'reads')
+  }
+  if (parsed.usesState) {
+    g.node('config:useState', { type: 'config', label: 'useState (shared)', meta: {} })
+    g.edge(fromId, 'config:useState', 'reads')
+  }
+}
+
+async function scanPages(project, g, componentsByName, composablesByName, warnings) {
+  const sources = sourcesOf(project)
+  for (let s = 0; s < sources.length; s++) {
+    const isLayer = s > 0
+    const dir = join(sources[s].srcDir, 'pages')
+    await eachFile(dir, ['.vue'], warnings, (file, source) => {
+      const full = join(dir, file)
+      const route = routeFromFile(file)
+      const id = `route:${route}`
+      // A route the app defines overrides a layer's.
+      if (isLayer && g.has(id)) return
+      const parsed = parseSfc(source, full)
+
+      g.node(id, {
+        type: 'route',
+        label: route,
+        file: rel(full, project.root),
+        meta: {
+          dynamic: /[[\]]/.test(file),
+          props: parsed.props,
+          layout: parsed.meta.layout ?? 'default',
+          loc: countLoc(source),
+        },
+      })
+      linkTags(g, id, parsed.tags, componentsByName)
+      linkScript(g, id, parsed, composablesByName)
+
+      const layout = parsed.meta.layout ?? 'default'
+      if (layout !== 'false' && g.has(`layout:${layout}`)) g.edge(`layout:${layout}`, id, 'wraps')
+
+      for (const name of parsed.meta.middleware ?? []) {
+        if (g.has(`middleware:${name}`)) g.edge(`middleware:${name}`, id, 'guards')
+      }
+    })
+  }
+
+  // app.vue is the true entry point; without pages/ it's the whole app. The
+  // app's own wins; failing that, the nearest layer that defines one.
+  for (const src of sourcesOf(project)) {
+    const appFile = join(src.srcDir, 'app.vue')
+    const app = await readFile(appFile, 'utf8').catch(() => null)
+    if (!app) continue
+    try {
+      const parsed = parseSfc(app, appFile)
+      g.node('entry:app', {
+        type: 'entry',
+        label: 'app.vue',
+        file: rel(appFile, project.root),
+        meta: { loc: countLoc(app) },
+      })
+      linkTags(g, 'entry:app', parsed.tags, componentsByName)
+      linkScript(g, 'entry:app', parsed, composablesByName)
+    } catch (err) {
+      warnings.push(`skipped app.vue: ${err.message}`)
+    }
+    break
+  }
+}
+
+async function scanLayouts(project, g, componentsByName, composablesByName, warnings) {
+  const sources = sourcesOf(project)
+  for (let s = 0; s < sources.length; s++) {
+    const isLayer = s > 0
+    const dir = join(sources[s].srcDir, 'layouts')
+    await eachFile(dir, ['.vue'], warnings, (file, source) => {
+      const full = join(dir, file)
+      const name = file.replace(/\.vue$/, '')
+      const id = `layout:${name}`
+      if (isLayer && g.has(id)) return
+      const parsed = parseSfc(source, full)
+      g.node(id, {
+        type: 'layout',
+        label: name,
+        file: rel(full, project.root),
+        meta: { loc: countLoc(source) },
+      })
+      linkTags(g, id, parsed.tags, componentsByName)
+      linkScript(g, id, parsed, composablesByName)
+    })
+  }
+}
+
+/**
+ * Composables are where a well-structured app keeps its data access, so
+ * skipping their bodies leaves every endpoint they call looking uncalled.
+ *
+ * Edges attach to every composable a file exports. Files almost always export
+ * one, and attributing a file's fetch to all of its exports is a smaller error
+ * than dropping the edge entirely.
+ */
+async function scanComposableBodies(project, g, composablesByName, warnings) {
+  const byFile = new Map()
+  for (const [name, info] of composablesByName) {
+    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, composablesByName)
+    },
+    (file) => rel(file, project.root),
+  )
+}
+
+async function scanComponentBodies(project, g, componentsByName, composablesByName, warnings) {
+  const locals = [...componentsByName].filter(([, info]) => info.origin === 'local')
+  await readEach(
+    locals.map(([, info]) => info.file),
+    warnings,
+    (file, source, i) => {
+      const [name] = locals[i]
+      const id = `component:${name}`
+      const parsed = parseSfc(source, file)
+      const node = g.nodes.get(id)
+      if (node) node.meta = { ...node.meta, props: parsed.props, loc: countLoc(source) }
+      linkTags(g, id, parsed.tags, componentsByName)
+      linkScript(g, id, parsed, composablesByName)
+    },
+    (file) => rel(file, project.root),
+  )
+}
+
+async function scanServer(project, g, warnings) {
+  const sources = sourcesOf(project)
+  for (let s = 0; s < sources.length; s++) {
+    const isLayer = s > 0
+    for (const base of ['api', 'routes']) {
+      const dir = join(sources[s].root, 'server', base)
+      await eachFile(dir, ['.ts', '.js', '.mts'], warnings, (file, source) => {
+        const full = join(dir, file)
+        const { method, path } = serverRoute(file, base)
+        const id = serverId(path)
+        // A handler the app already provides overrides a layer's. Only a real
+        // (non-inferred) handler blocks; an inferred node still wants filling in.
+        if (isLayer && g.has(id) && !g.nodes.get(id).meta.inferred) return
+
+        // A caller may have created this node already from a fetch string. Either
+        // way the handler file is the better source of truth for every field.
+        const node = g.node(id, { type: 'server', meta: {} })
+        node.label = path
+        node.file = rel(full, project.root)
+        node.meta = { ...node.meta, method, loc: countLoc(source) }
+        delete node.meta.inferred
+
+        const parsed = parseScript(source)
+        for (const host of parsed.externals) {
+          g.node(`external:${host}`, { type: 'external', label: host, meta: {} })
+          g.edge(id, `external:${host}`, 'fetches')
+        }
+        for (const name of parsed.collections) {
+          g.node(`collection:${name}`, { type: 'collection', label: name, meta: {} })
+          g.edge(id, `collection:${name}`, 'queries')
+        }
+        if (parsed.usesRuntimeConfig) {
+          g.node('config:runtimeConfig', { type: 'config', label: 'runtimeConfig', meta: {} })
+          g.edge(id, 'config:runtimeConfig', 'reads')
+        }
+      })
+    }
+  }
+}
+
+async function scanMiddlewareAndPlugins(project, g, composablesByName, warnings) {
+  for (const src of sourcesOf(project)) {
+    const specs = [
+      { dir: join(src.srcDir, 'middleware'), type: 'middleware' },
+      { dir: join(src.srcDir, 'plugins'), type: 'plugin' },
+      { dir: join(src.root, 'server', 'middleware'), type: 'middleware' },
+    ]
+    for (const { dir, type } of specs) {
+      await eachFile(dir, ['.ts', '.js', '.mts', '.vue'], warnings, (file, source) => {
+        const full = join(dir, file)
+        const name = file.replace(/\.(ts|js|mts|vue)$/, '')
+        const server = full.includes('/server/')
+        // g.node is first-wins, so the app's file beats a layer's of the same name.
+        const id = `${type}:${server ? 'server-' : ''}${name}`
+        g.node(id, {
+          type,
+          label: server ? `${name} (server)` : name,
+          file: rel(full, project.root),
+          meta: {},
+        })
+        // Middleware and plugins call composables, fetch endpoints and read
+        // config too — skipping their bodies made a composable used only from
+        // an auth middleware or an analytics plugin look uncalled.
+        const parsed = full.endsWith('.vue') ? parseSfc(source, full) : parseScript(source)
+        linkScript(g, id, parsed, composablesByName)
+      })
+    }
+  }
+}
+
+/** Content collections are declared, not discovered — read them from config. */
+async function scanContentConfig(project, g) {
+  const found = new Map()
+  for (const src of sourcesOf(project)) {
+    const raw = await readFile(join(src.root, 'content.config.ts'), 'utf8').catch(() => null)
+    if (!raw) continue
+    for (const m of raw.matchAll(/(\w+)\s*:\s*defineCollection\s*\(/g)) {
+      const name = m[1]
+      if (found.has(name)) continue // the app's collection wins over a layer's
+      const block = sliceBalanced(raw, m.index + m[0].length - 1, '(', ')')
+      const source = block.match(
+        /source\s*:\s*(?:['"]([^'"]+)['"]|\{[^}]*include\s*:\s*['"]([^'"]+)['"])/,
+      )
+      const info = {
+        type: block.match(/type\s*:\s*['"](\w+)['"]/)?.[1] ?? 'page',
+        source: source ? (source[1] ?? source[2]) : null,
+        // "empty" is only honest when the source is a local glob we can actually
+        // count. A `repository:` (fetched from git), or a source we can't resolve
+        // to a glob — a variable, an array of sources — has no countable local
+        // files, so it must not be flagged empty. Real on nuxt.com's docs, whose
+        // collections point at `source: [docsV3Source, …]` github repositories.
+        remote: /\brepository\s*:/.test(block) || (/\bsource\s*:/.test(block) && !source),
+        fields: schemaFields(block),
+      }
+      found.set(name, info)
+      g.node(`collection:${name}`, {
+        type: 'collection',
+        label: name,
+        file: 'content.config.ts',
+        meta: info,
+      })
+    }
+  }
+  return found
+}
+
+function schemaFields(block) {
+  const start = block.indexOf('z.object(')
+  if (start === -1) return []
+  return topLevelKeys(sliceBalanced(block, block.indexOf('{', start), '{', '}'))
+}
+
+/**
+ * Markdown drives two edges worth drawing: which collection a file belongs to,
+ * and which components its MDC body renders.
+ */
+async function scanContentFiles(project, g, collections, componentsByName, warnings) {
+  const counts = new Map()
+  // A collection's source glob collapses to a fixed path prefix; precompute the
+  // [name, prefix] list once instead of rebuilding it and re-running the regex
+  // for every content file (an app can have thousands). Kept in collection
+  // order, so `.find` still selects the same collection a per-file scan would.
+  const prefixes = [...collections].map(([name, info]) => [
+    name,
+    info.source ? info.source.replace(/\*\*?.*$/, '') : null,
+  ])
+
+  // `type: 'data'` collections are JSON or YAML, not markdown. Walking only .md
+  // reports those collections as empty when they hold hundreds of files.
+  for (const src of sourcesOf(project)) {
+    const dir = join(src.root, 'content')
+    // @nuxt/content ignores files and directories prefixed with `_` — they're
+    // partials, not published pages. Counting them would inflate a collection's
+    // file total and draw render edges from content that never renders.
+    const files = (await walk(dir, CONTENT_EXTS, dir)).filter(
+      (f) => !f.split('/').some((seg) => seg.startsWith('_')),
+    )
+    if (!files.length) continue
+
+    // Only markdown renders components, so only markdown needs reading. Fan the
+    // reads out, but process files below in walk order so node insertion — and
+    // therefore the serialized output — stays identical to a serial scan.
+    const md = files.filter((f) => f.endsWith('.md'))
+    const mdSources = await Promise.all(
+      md.map((f) => readFile(join(dir, f), 'utf8').catch(() => null)),
+    )
+    const sourceOf = new Map(md.map((f, i) => [f, mdSources[i]]))
+
+    for (const file of files) {
+      const collection =
+        prefixes.find(([, prefix]) => prefix != null && file.startsWith(prefix))?.[0] ??
+        file.split('/')[0]
+
+      counts.set(collection, (counts.get(collection) ?? 0) + 1)
+      const id = `collection:${collection}`
+      if (!g.has(id)) g.node(id, { type: 'collection', label: collection, meta: {} })
+
+      if (!file.endsWith('.md')) continue
+      const raw = sourceOf.get(file)
+      if (raw == null) {
+        warnings.push(`could not read ${file}`)
+        continue
+      }
+      try {
+        for (const tag of parseMdcComponents(raw)) {
+          const name = normalizeTag(tag)
+          const info = componentsByName.get(name)
+          if (!info) continue
+          if (info.origin === 'library') {
+            g.node(`component:${name}`, {
+              type: 'lib-component',
+              label: name,
+              file: shortenPkgPath(info.file),
+              meta: { origin: 'library', pkg: info.pkg },
+            })
+          }
+          g.edge(id, `component:${name}`, 'renders')
+        }
+      } catch (err) {
+        warnings.push(`skipped ${file}: ${err.message}`)
+      }
+    }
+  }
+
+  for (const [name, count] of counts) {
+    const node = g.nodes.get(`collection:${name}`)
+    if (node) node.meta = { ...node.meta, files: count }
+  }
+}
+
+function serverRoute(file, base) {
+  const withoutExt = file.replace(/\.(ts|js|mts)$/, '')
+  const methodMatch = withoutExt.match(/\.(get|post|put|patch|delete|head|options)$/)
+  const method = methodMatch ? methodMatch[1].toUpperCase() : 'ALL'
+  const clean = withoutExt
+    .replace(/\.(get|post|put|patch|delete|head|options)$/, '')
+    .replace(/\/index$/, '')
+    .split('/')
+    .map((s) => (s.startsWith('[...') ? `**` : s.startsWith('[') ? `:${s.slice(1, -1)}` : s))
+    .join('/')
+  return { method, path: `/${base === 'api' ? 'api/' : ''}${clean}` }
+}