@amulet-laboratories/astrolabe 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes are recorded here. This project follows [semantic versioning](https://semver.org).
+The **graph schema** (`schemaVersion` in the serialized output) and the **adapter interface** are the
+two stability contracts; breaking either is a major version bump once the project reaches 1.0.
+
+## [Unreleased]
+
+## [0.4.0]
+
+Renamed to **Astrolabe** (`@amulet-laboratories/astrolabe`), and the first release built to be
+published: it now reads Vue as well as Nuxt, and a round of real-repo testing sharpened its findings.
+
+### Changed
+
+- **Renamed to Astrolabe.** Package `@amulet-laboratories/astrolabe`, CLI command `astrolabe`.
+- **Publish-ready packaging:** `LICENSE`, `publishConfig.access: public`, `repository`/`homepage`/
+  `bugs`, subpath types for the adapters, and `NodeType`/`ViewName` corrected (they were missing
+  `store`, `sitemap`, `cleanup`).
+- **Release engineering:** a Node 22/24 test matrix and an `npm pack` tarball gate in CI, a
+  tag-triggered `npm publish --provenance` workflow, and a README hero + badges. A `v0.4.0` tag is
+  all that stands between here and npm.
+- **Pre-publish lean-up (−231 LOC).** Framework-neutral plumbing (walk, parallel reads, churn,
+  package stack, route names, tag linking) is hoisted into one `adapters/shared.mjs` both adapters
+  build on; the Vue adapter no longer imports from the Nuxt one, so the dependency direction is
+  clean (`adapters → shared → core`). Dead fields and an unused export subpath dropped, `sfc.mjs`
+  moved to `core/`. Verified byte-identical against the Nuxt and Vue baselines.
+
+### Fixed
+
+- **Plugin and middleware bodies are analyzed.** A composable used only from an auth middleware or
+  an analytics plugin no longer reads as "nothing calls it" — their bodies now draw the same
+  `uses`/`fetches`/`reads` edges as pages and components.
+- **The graph diff surfaces a single new finding within an existing category.** Findings are diffed
+  at the (finding, node) grain, so "1 component nothing renders: NewThing" shows even when the
+  orphan-components category already existed — the whole point of the living-docs diff.
+
+### Fixed (from running across real repos — elk, nuxt.com, it-tools …)
+
+- **Fallback component naming** matches Nuxt's prefix rule: `account/AccountAvatar` →
+  `AccountAvatar`, not `AccountAccountAvatar`. This alone cut elk-zone/elk's false orphans from 189
+  to 38 without `.nuxt`.
+- **Test/spec files are never analyzed** (Nuxt side; Vue already did), removing phantom composables.
+- **Unresolvable content sources aren't flagged empty** — a `repository:` (git-fetched) or a
+  variable/array source can't be counted locally, so it's no longer a false "empty collection"
+  (nuxt.com: 5 → 1).
+- **Vue manifest paths resolve correctly regardless of where the manifest sits** (found on
+  antfu/vitesse). A `./…` specifier in `components.d.ts`/`auto-imports.d.ts` is relative to the
+  manifest's own directory, not the project root — so a manifest committed under `src/` (vs. at the
+  root, like it-tools) no longer looks every file up one directory too high. Extensionless TS
+  specifiers (`./stores/user`) also resolve now by trying the source extensions. vitesse: 5 read
+  failures → 0, with render/uses edges wired. Fixture: `test/fixtures/vue-src-manifest`.
+
+### Added
+
+- **The report is executed in CI.** A jsdom smoke test boots the interactive report, switches every
+  view, and opens the command palette — catching runtime errors the bundle's syntax check can't.
+- **Plain Vue (Vite) support — a second adapter.** app-graph now reads non-Nuxt Vue apps too:
+  file-based routes (`src/pages/`), components and composables resolved from the committed unplugin
+  manifests (`components.d.ts` / `auto-imports.d.ts` — accurate on a bare clone, no build needed),
+  and **Pinia stores** as a new node kind. The framework-neutral core is untouched; the Nuxt adapter
+  is unchanged and still wins detection for Nuxt apps. Strong on convention/unplugin Vue; hand-written
+  and dynamic routers are a known next step. Test/spec files and non-`use*` utility modules are
+  excluded (the false-positive classes the Nuxt corpus surfaced).
+- **Two new views.** **Sitemap** lays the graph out from the routes, forward — everything a page
+  reaches, with dead code dropping away. **Cleanup** gathers only what the findings flag as warnings
+  (dead components, uncalled composables, empty collections, render cycles) in one place. Both are
+  pure projections, available in the report and via `--svg --view sitemap|cleanup`.
+- **Command palette (⌘K / Ctrl-K).** Fuzzy jump-to-node over the whole graph, with a visible `⌘K`
+  affordance in the toolbar. Selecting a result moves the camera, panel, and URL like any other pick.
+- **Heat overlay.** When the app is a git repo, a **Heat** toggle shades every file-backed node by
+  how often it changes (commit count), so hotspots — where the risk and the reading are — surface at
+  a glance. Churn also shows per node in the detail panel.
+
+### Changed
+
+- **Edges read as structure, not noise.** In the interactive report, each edge is now tinted by its
+  destination's kind at low opacity, so a dense graph shows the flow (data vs render vs uses) instead
+  of a grey hairball.
+
+### Fixed
+
+- **PascalCase MDC components are traced.** `::QuickAnswer` and `:Icon{}` (PascalCase block/inline
+  MDC) were missed — only kebab-case matched — so a component referenced that way from content was
+  wrongly flagged as an orphan. Found by running the analyzer across a real fleet.
+- **`_`-prefixed content partials are ignored**, matching `@nuxt/content` — they no longer inflate a
+  collection's file count or draw render edges from content that never publishes.
+
+### Added
+
+- **Nuxt layers.** Local `extends` layers are now followed — a base layer's pages, components,
+  composables, layouts, middleware, server routes and content merge into the graph, with the app
+  winning on name collisions. Remote layers are out of scope. (`test/fixtures/layered`.)
+- **Never-crash.** A malformed SFC, config or composable becomes a warning instead of aborting the
+  scan. (`test/fixtures/malformed`.)
+
+### Changed
+
+- **Performance.** Per-directory file reads now fan out in parallel while preserving byte-identical
+  output — a large app scans noticeably faster.
+
+### Added (earlier in this cycle)
+
+- **Living-docs outputs.** `--svg` renders a static SVG of any view server-side (no browser),
+  reusing the interactive report's exact layout engine. `app-graph diff <base> <head>` reports what
+  changed architecturally between two apps or two graph JSONs, as Markdown (for a PR comment) or
+  `--json`. `renderSvg`, `diffGraphs`, `isEmptyDiff` and `formatDiffMarkdown` are exported from the
+  package.
+- A ready-made PR workflow in `examples/architecture-diff.yml` that posts the diff as a sticky
+  comment and uploads the report + SVG.
+
+### Changed
+
+- The client's pure layout and view-projection logic moved to `src/core/layout.mjs` and
+  `src/core/views.mjs` as ESM modules, shared by the browser report and the Node SVG renderer. The
+  interactive report is unchanged in behavior.
+
+## [0.2.0]
+
+Framework-agnostic core with per-framework adapters. No change to what the Nuxt report contains —
+the HTML output is byte-identical to 0.1.0 — but the internals are now a reusable engine.
+
+### Added
+
+- `src/core/` — a framework-neutral engine: the `Graph` builder, the `finalize` pipeline
+  (prune → group → findings → stats), the HTML renderer + client, and `schema.mjs` defining the
+  canonical node/edge vocabulary.
+- `src/adapters/` — the adapter layer. `adapters/nuxt/` holds all Nuxt specifics; `registry.mjs`
+  detects which adapter an app needs.
+- Published TypeScript types (`src/index.d.ts`) for the full public surface, and an `exports` map
+  exposing `.`, `./schema`, and `./adapters/nuxt`.
+- `schemaVersion` on the serialized graph, and a `validateGraph()` conformance checker.
+- `--schema` CLI flag that prints the canonical graph schema.
+- `test/conformance.test.mjs` — the framework-agnostic contract every adapter must pass.
+
+### Changed
+
+- Public entry is now `@amulet-laboratories/app-graph` (`src/index.mjs`); `scan` and `renderHtml`
+  are re-exported from there. Deep imports of `src/scan.mjs` / `src/findings.mjs` have moved under
+  `src/adapters/nuxt/` and `src/core/` respectively.
+
+## [0.1.0]
+
+- Initial Nuxt app-graph analyzer: routes, components, composables, content collections, server
+  routes and external services as one interactive, self-contained HTML diagram, with findings.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amulet Laboratories
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# Astrolabe
+
+[![npm](https://img.shields.io/npm/v/@amulet-laboratories/astrolabe.svg)](https://www.npmjs.com/package/@amulet-laboratories/astrolabe)
+[![CI](https://github.com/Amulet-Laboratories/app-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/Amulet-Laboratories/app-graph/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@amulet-laboratories/astrolabe.svg)](./LICENSE)
+
+Static analyzer that maps a **Nuxt or Vue** app into one interactive diagram — routes, components, composables, stores, content collections, server routes and the external services they talk to, plus the edges between them.
+
+The goal is to open one file and understand an app you've never seen: what the pages are, what each renders, and where its data comes from.
+
+![An Astrolabe report for nuxt/movies](docs/hero.png)
+
+> _One self-contained HTML file for [nuxt/movies](https://github.com/nuxt/movies) — pan, zoom, ⌘K to any node, and the findings the diagram won't make you notice._
+
+## Install
+
+```bash
+# run it without installing
+npx @amulet-laboratories/astrolabe ./my-app --open
+
+# or add it to a project
+npm i -D @amulet-laboratories/astrolabe
+```
+
+```bash
+astrolabe ./my-app --open        # interactive report
+astrolabe ./my-app --svg -o docs/architecture.svg
+astrolabe diff main-graph.json pr-graph.json   # what changed
+```
+
+Or import it:
+
+```js
+import { scan, renderHtml } from '@amulet-laboratories/astrolabe'
+const graph = await scan('./my-app') // typed graph JSON
+```
+
+## Usage
+
+```
+astrolabe [dir] [options]
+astrolabe diff <base> <head> [options]
+
+  dir              Path to the Nuxt or Vue app (default: current directory)
+  diff             Compare two apps or two graph JSON files, base → head
+
+  -o, --out FILE   Output path (default: astrolabe.<html|json|svg>)
+  --json           Emit graph JSON instead of HTML (for diff: JSON not Markdown)
+  --svg            Emit a static SVG snapshot instead of HTML
+  --view NAME      View for --svg: layers (default), render, data, modules, sitemap, cleanup
+  --schema         Print the canonical graph schema and exit
+  --open           Open the result in your default browser
+  -h, --help       Show this help
+```
+
+The HTML is fully self-contained — no network, no build step. Drag to pan, scroll to zoom, click any node to see its file, its data access, and everything connected to it in both directions. The chips along the top filter entity types, and the diagram re-flows to fit whatever is left.
+
+## Living docs
+
+The graph is only useful if it stays current, so three outputs are built to run in CI and keep it honest:
+
+- **A static SVG** (`--svg`) of any view, rendered server-side with no browser — for embedding in a README or a docs page that can't run JavaScript. It uses the exact same layout engine as the interactive report, so the two can't disagree.
+- **A graph diff** (`astrolabe diff base head`) that reports what changed _architecturally_ between two versions — "added 2 routes, a new external service dependency, 1 orphan" — rather than line by line. Each side is either an app directory or a saved `--json` graph. Default output is Markdown for a PR comment; `--json` gives the structured delta.
+- **A ready-made PR workflow** in [`examples/architecture-diff.yml`](examples/architecture-diff.yml): on every pull request it scans base and head, posts the diff as a sticky comment, and uploads the full report + SVG as artifacts.
+
+## Views
+
+There is one graph. A view is a projection of it — which nodes it keeps, which edges it keeps, and what a column means. Everything else (layout, grouping, the detail panel) is shared, so each view is a different question asked of the same data rather than a different diagram.
+
+| View            | The question it answers                                                                                                                                                    |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Layers**      | _What is in this app?_ Every entity, in columns by kind. The overview.                                                                                                     |
+| **Render tree** | _What renders what?_ Only `renders`/`wraps` edges, columns are nesting depth, so the leftmost column is the true entry points.                                             |
+| **Data flow**   | _Where does data come from and where does it end up?_ Every edge reversed, so it reads origin → who reads it → where it surfaces. Nodes that never touch data are dropped. |
+| **Modules**     | _Who consumes what?_ Folders and packages collapsed to one block each, with line weight showing how many references cross between them. A whole app in ~30 boxes.          |
+| **Sitemap**     | _What are the pages, and what powers each?_ Laid out from the routes, forward — everything a page reaches. Whatever no page reaches (dead code) drops away.                |
+| **Cleanup**     | _What's safe to delete?_ Only what the findings flag as warnings — dead components, uncalled composables, empty collections, render cycles — gathered in one place.        |
+
+**Group** buckets nodes inside each column by owner — the directory a file lives in, or the package it came from. Directories already encode how the app is organised (`components/hub`, `server/api/sync`), so this is grouping you wrote rather than grouping the tool invented. It's off in Modules, where the module already _is_ the group.
+
+**Isolate** (in the detail panel, `f`, or Esc to clear) reduces any view to one node plus everything it reaches and everything that reaches it. This is the fastest way to ask "if I change this, what breaks?" It persists across view switches, so you can isolate a collection and then flip to Data flow to see where it surfaces.
+
+## The overview
+
+With nothing selected, the side panel is a briefing on the repo rather than a prompt: size, findings, composition, the most-referenced entities, the largest files, the stack it runs on, and a legend. Every name in it is clickable and jumps to that node.
+
+**Findings** are the things the diagram won't make you notice — dead components, composables nothing calls, endpoints with no handler, render cycles, collections whose glob matched nothing. They're computed once in [`src/core/findings.mjs`](src/core/findings.mjs) and shared by the CLI, `--json`, and the report, so all three can never disagree.
+
+The bar for a finding is that it is **actionable and true**. A confidently wrong finding costs more trust than a missing one earns, so anything the analyzer can't be sure of is worded for what was actually checked — "17 server routes with no fetch call" (which is a fact) rather than "17 dead routes" (which would be a guess, and wrong for redirects reached by an `href`).
+
+## Keyboard
+
+`1`–`6` switch views · `/` search · `g` group · `f` isolate the selection · `Esc` clear
+
+The view, selection and isolation are kept in the URL, so any particular reading of the graph can be shared as a link.
+
+## What it reads
+
+Everything comes from Nuxt's own conventions, so there's nothing to configure:
+
+| Entity                       | Source                                                                                                                      |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Routes                       | `pages/**` file-based routing, including `[param]` and `[...catchall]`                                                      |
+| Components                   | `components/**`, resolved to their auto-import names                                                                        |
+| Composables                  | `composables/**` plus auto-imports from libraries — including their bodies, which is where most apps keep their data access |
+| Content collections          | `content.config.ts` collections, their Zod schema fields, and their file counts (markdown, JSON and YAML alike)             |
+| Server routes                | `server/api/**`, `server/routes/**`, with HTTP method                                                                       |
+| Layouts, middleware, plugins | `layouts/**`, `middleware/**`, `plugins/**`                                                                                 |
+| Stack                        | Nuxt version, modules, dependencies, engines, package manager                                                               |
+| Size                         | non-blank lines per file, aggregated per node and repo                                                                      |
+
+A caller's `` `/api/debate/${slug}/vote` `` and its handler `server/api/debate/[slug]/vote.post.ts` are the same endpoint, so dynamic segments are collapsed to `*` when matching. Without that the caller invents a phantom endpoint and the real handler looks uncalled — two wrong facts from one mismatch.
+
+Edges are extracted per file: `renders` from template tags and from components used in markdown (all three MDC syntaxes — `::block`, `:inline{}`, and plain `<PascalCase />` tags), `queries` from `queryCollection()`, `fetches` from `$fetch`/`useFetch` (splitting internal API routes from external hosts), `uses` from composable calls, `reads` from `useAppConfig`/`useRuntimeConfig`/`useState`, and `wraps`/`guards` from `definePageMeta`.
+
+Because markdown render paths count, a component used only from content is not mistaken for an orphan — and one that really is unused gets flagged as such.
+
+### `.nuxt` makes it sharper
+
+When `.nuxt/` is present (after any `nuxt dev`, `nuxt build`, or `nuxt prepare`), the tool reads `components.d.ts` and `imports.d.ts` for the exact set of auto-imports Nuxt resolved. That's what lets it show **library** components and composables — the ones coming from Rig, `@nuxt/content`, and Nuxt itself — attributed to their package.
+
+Without `.nuxt/`, it falls back to scanning `components/` by convention and prints a warning. You still get your own app's structure; you just lose the library layer.
+
+### Layers
+
+Apps that `extends` a local base layer are followed: the layer's pages, components, composables, layouts, middleware, server routes and content are merged into the graph as if they were the app's own, with the app winning on any name collision (its `pages/index.vue` overrides the layer's). Only local layers — a relative or absolute path — are resolved; remote layers (`github:…`, an npm package) would need a package install and are left out. A layer that itself extends another is followed too.
+
+Library entities that nothing references are dropped: a dependency exports far more than any one app uses, and listing the unused half describes the dependency rather than your app. Unconnected _local_ components are kept and flagged as "Nothing renders this component" — that's a finding, not noise.
+
+## Reading the diagram
+
+Columns run left to right in dependency order: entry and layouts → routes → your components → library components → composables → data and services. Within a column, nodes are ordered by barycenter so connected things line up. Selecting a node dims everything it doesn't touch, which is the fastest way to answer "what does this page actually depend on?"
+
+## Architecture
+
+The engine is split into a framework-neutral **core** and per-framework **adapters**, so
+supporting another framework is adding an adapter rather than changing everything downstream:
+
+| Path                        | What lives there                                                                                                                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/core/`                 | The `Graph` builder, the `finalize` pipeline (prune → group → findings → stats), the HTML renderer + client, and `schema.mjs` — the canonical node/edge vocabulary every adapter targets. Knows about no framework. |
+| `src/adapters/nuxt/`        | Everything Nuxt-specific: file-based routing, `content.config.ts`, `.nuxt/*.d.ts`, SFC parsing. Emits canonical nodes and edges.                                                                                    |
+| `src/adapters/registry.mjs` | Adapter list + `detectAdapter(dir)` — first adapter whose `detect()` matches wins.                                                                                                                                  |
+| `src/index.mjs`             | Public API: `scan(dir)` detects the adapter, runs it, and finalizes; plus `renderHtml`, the schema, and the registry.                                                                                               |
+
+An adapter is a module exporting `{ name, detect(dir), scan(dir) }`, where `scan` returns
+`{ project, graph, warnings }` in the canonical schema. [`test/conformance.test.mjs`](test/conformance.test.mjs)
+is the contract every adapter must pass, independent of any framework — pointing a new adapter at
+it is what proves the core stayed neutral.
+
+## Developing
+
+```bash
+pnpm install
+pnpm test          # vitest, runs against fixture apps in test/fixtures/
+pnpm check         # lint + format + test, what CI runs
+```
+
+Lint and format mirror `@amulet-laboratories/config` rule-for-rule. They're inlined rather than imported because that package isn't published, and its only consumable form (`file:../Rig/config`) has no sibling checkout in CI. Swap to the shared package once it ships to the registry.
+
+### The testing bar
+
+This tool's entire value is being right about a repo. It almost never fails loudly — when it's wrong it reports something false with total confidence, and someone deletes code because of it. So the standard is:
+
+**Every bug gets a fixture, not just a fix.** `test/fixtures/` holds small real Nuxt apps; tests assert against the graph they produce. Each regression test names the false claim it prevents. The bugs already pinned there — composable bodies unparsed, `type: 'data'` collections reported empty, phantom endpoints, missed MDC tags, mis-parsed one-line props — were all found by hand on real repos, and every one would have shipped again without a fixture.
+
+That's also why fixtures beat testing against your own apps: the one-line props bug was invisible across all 8 Amulet repos because they all happen to format multi-line. Fixtures let you write the shape you _don't_ have.
+
+## Limitations
+
+Analysis is lexical, not type-aware. It recognizes the conventional Nuxt call shapes, which is what the diagram is for. Known blind spots, all of which affect what you should conclude from a finding:
+
+- A collection or endpoint named at runtime (`queryCollection(someVar)`, `$fetch(url)`) isn't traced — only literal and template strings are.
+- A component rendered via `<component :is>` isn't traced.
+- **Links aren't traced.** A server route reached by an `href` (a `/go/:slug` redirect) shows no incoming edge, which is why the finding says "no fetch call" rather than "dead".
+- A composable file's data access is attributed to every composable that file exports. Files almost always export one; where they don't, this over-attributes rather than dropping the edge.
+- Dynamic route params are shown as the pattern, not the pages they expand to.
+- Only local `extends` layers are followed. A remote layer (`github:…`, an npm package) is not fetched, so its entities are absent rather than wrong.

package/bin/astrolabe.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+
+import {
+  EDGE_KINDS,
+  NODE_KINDS,
+  renderHtml,
+  renderSvg,
+  scan,
+  SCHEMA_VERSION,
+} from '../src/index.mjs'
+import { diffGraphs, formatDiffMarkdown } from '../src/core/diff.mjs'
+
+const USAGE = `
+astrolabe — map a Nuxt or Vue app's structure into one interactive diagram
+
+  astrolabe [dir] [options]
+  astrolabe diff <base> <head> [options]
+
+  dir              Path to the app (default: current directory)
+  diff             Compare two apps or two graph JSON files, base → head
+
+Options:
+  -o, --out FILE   Output path (default: astrolabe.<html|json|svg>)
+  --json           Emit graph JSON instead of HTML (for diff: JSON not Markdown)
+  --svg            Emit a static SVG snapshot instead of HTML
+  --view NAME      View for --svg: layers (default), render, data, modules, sitemap, cleanup
+  --schema         Print the canonical graph schema and exit
+  --open           Open the result in your default browser
+  -h, --help       Show this help
+`
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    out: { type: 'string', short: 'o' },
+    json: { type: 'boolean', default: false },
+    svg: { type: 'boolean', default: false },
+    view: { type: 'string', default: 'layers' },
+    schema: { type: 'boolean', default: false },
+    open: { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+  },
+})
+
+if (values.help) {
+  console.log(USAGE)
+  process.exit(0)
+}
+
+if (values.schema) {
+  console.log(
+    JSON.stringify(
+      {
+        schemaVersion: SCHEMA_VERSION,
+        nodeKinds: NODE_KINDS,
+        edgeKinds: EDGE_KINDS,
+      },
+      null,
+      2,
+    ),
+  )
+  process.exit(0)
+}
+
+// A `<path>` is either a saved graph JSON or an app directory to scan fresh.
+async function loadGraph(path) {
+  if (path.endsWith('.json')) return JSON.parse(await readFile(resolve(path), 'utf8'))
+  return scan(resolve(path))
+}
+
+if (positionals[0] === 'diff') {
+  const [, base, head] = positionals
+  if (!base || !head) {
+    console.error('astrolabe diff: needs two arguments — <base> <head>')
+    process.exit(1)
+  }
+  try {
+    const d = diffGraphs(await loadGraph(base), await loadGraph(head))
+    const output = values.json ? JSON.stringify(d, null, 2) : formatDiffMarkdown(d)
+    if (values.out) await writeFile(resolve(values.out), output)
+    else console.log(output)
+    // A diff is information, not a failure — always exit 0. Callers that want to
+    // gate a build on it can inspect the --json output themselves.
+    process.exit(0)
+  } catch (err) {
+    console.error(`astrolabe: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+const ext = values.json ? 'json' : values.svg ? 'svg' : 'html'
+const dir = resolve(positionals[0] ?? '.')
+const out = resolve(values.out ?? `astrolabe.${ext}`)
+
+const renderOutput = (graph) => {
+  if (values.json) return JSON.stringify(graph, null, 2)
+  if (values.svg) return renderSvg(graph, { view: values.view })
+  return renderHtml(graph)
+}
+
+try {
+  const graph = await scan(dir)
+  await writeFile(out, renderOutput(graph))
+
+  const counts = graph.nodes.reduce((acc, n) => ((acc[n.type] = (acc[n.type] ?? 0) + 1), acc), {})
+  const summary = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([type, n]) => `${n} ${type}`)
+    .join(', ')
+
+  console.log(`${graph.project.name}: ${summary}`)
+  console.log(
+    `${graph.stats.files} files, ${graph.stats.loc.toLocaleString()} lines, ${graph.edges.length} edges`,
+  )
+
+  for (const f of graph.findings) {
+    const mark = f.severity === 'warn' ? '!' : '·'
+    console.log(`  ${mark} ${f.title}`)
+  }
+
+  console.log(`→ ${out}`)
+  for (const w of graph.warnings) console.warn(`warning: ${w}`)
+
+  if (values.open) {
+    const { spawn } = await import('node:child_process')
+    const cmd =
+      process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
+    spawn(cmd, [out], { detached: true, stdio: 'ignore' }).unref()
+  }
+} catch (err) {
+  console.error(`astrolabe: ${err.message}`)
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@amulet-laboratories/astrolabe",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Astrolabe maps a Nuxt or Vue app into one interactive diagram — routes, components, composables, stores, data sources and the services they talk to — plus the findings the diagram won't make you notice.",
+  "license": "MIT",
+  "packageManager": "pnpm@10.30.2",
+  "author": "Amulet Laboratories",
+  "homepage": "https://github.com/Amulet-Laboratories/astrolabe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Amulet-Laboratories/astrolabe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Amulet-Laboratories/astrolabe/issues"
+  },
+  "keywords": [
+    "nuxt",
+    "vue",
+    "static-analysis",
+    "architecture",
+    "diagram",
+    "dependency-graph",
+    "dead-code",
+    "documentation",
+    "code-visualization"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "astrolabe": "bin/astrolabe.mjs"
+  },
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./schema": {
+      "types": "./src/index.d.ts",
+      "default": "./src/core/schema.mjs"
+    }
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/astrolabe.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "types": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "eslint . && prettier --check . && tsc --noEmit && vitest run"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "jsdom": "^30.0.0",
+    "prettier": "^3.9.5",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}