@pablocm90/visual-review 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo
+
+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

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# visual-review
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Draws what a change did to the structure of a repo: the Rust crates and their dependencies, the web modules and files and their imports, and the web calls to API routes, before and after, with added, removed and modified parts coloured. A renamed crate, module or file is one node that says what it was called ("was domain"), and a test that moved to another file says where it went. Changed files outside those (tools, plans, CI, config) are listed below the graph with their patches.
+
+It reads Rust (Cargo workspaces) and TypeScript/JavaScript, and links `fetch` calls to axum routes. More languages are planned.
+
+## Before the first run
+
+- Node `^22.20.0 || >=24.8.0`.
+- macOS or Linux. 0.1 doesn't run on Windows.
+- `git`.
+- `cargo` on your `PATH` for Rust crates, which come from `cargo metadata`. Without it, the Rust stacks are skipped and the page says so.
+- For PRs, the GitHub CLI, logged in with `gh auth login`, and a git remote that points at the PR's repository. Any name works, so a fork's `origin` beside an `upstream` is fine.
+
+Nothing needs installing in the reviewed repo.
+
+## Run it
+
+In Claude Code, add the plugin once:
+
+```
+/plugin marketplace add pablocm90/visual-review
+/plugin install visual-review@pablocm90
+```
+
+Then, from anywhere in the repo (as `/visual-review:visual-review` when another skill or command already takes the name):
+
+| Command | Reviews |
+|---|---|
+| `/visual-review 42` | PR #42, from where it branched off its base to its head |
+| `/visual-review main..my-branch` | a range of commits |
+| `/visual-review` | your uncommitted work against `HEAD` |
+
+Claude builds the page, writes structural notes and flags onto it, and opens it in your browser. Selecting a crate, module, file or edge opens its note and patches in a panel beside the graph; drag the divider between them, or focus it and use the arrow keys, to give either side more room.
+
+Without Claude, run the CLI with the same argument. It builds the page with no notes and prints its path:
+
+```sh
+npx @pablocm90/visual-review 42
+```
+
+## When detection misreads a repo
+
+Stacks are detected: a Cargo workspace at the repo root, and every `package.json` whose source root holds TS/JS files. A `visual-review.config.json` at the repo root overrides that. It is read from the reviewed head revision, or from your checkout when the head has none, and applies to both sides.
+
+```json
+{
+  "$schema": "https://unpkg.com/@pablocm90/visual-review@0.1/dist/config.schema.json",
+  "stacks": {
+    "web": { "boxes": ["modules/*"], "label": "Web app" },
+    "e2e": false,
+    "api": { "reader": "rust", "root": "backend" },
+    "gen": { "reader": "typescript", "root": "tools/gen", "sourceRoot": "lib" }
+  },
+  "linkers": {
+    "fetch-axum": { "from": ["web"], "to": ["api"] }
+  }
+}
+```
+
+- Stacks are keyed by the id the page draws: a package's directory, a root package's name, or `rust`.
+- `false` drops a stack, and `label` relabels it.
+- `reader` with `root` adds a stack that detection missed (`rust` or `typescript`).
+- TS stacks also take `sourceRoot`, and `boxes`: folder globs under the source root, each matched folder one box. The deepest match wins, and other files keep one box per first folder.
+- `linkers.fetch-axum` draws the `fetch` calls of TS stacks to the routes of Rust crates that depend on axum, and lists calls no route matches. `from` and `to` limit it to those stacks, and `false` turns it off.
+
+A key that names no detected stack, an unknown field, or a field the stack's reader doesn't take fails the review, naming the file and the field.
+
+## Notes
+
+A notes file is JSON in notes version 1, whose schema is [`notes.schema.json`](https://unpkg.com/@pablocm90/visual-review@0.1/dist/notes.schema.json) (give that URL as `$schema`). Beside `version`, `summary` holds a few `{ text, target? }` items on the change as a whole and `tests` a sentence on what the tests pin; `notes` maps a node id, or `<from> -> <to>` for an edge, to `{ text, flag? }`, where `flag` labels a structural concern.
+
+`--notes <file>` with the same argument fills the notes into the page already written for it. A missing or unknown `version`, an unknown key, an id the graph doesn't have, or a changed part without a note fails it, naming the file.
+
+## Where pages go
+
+Pages go to `.reviews/` at the repo root, which git ignores. Each page is named by its range, for example `<sha>..<sha>.html` for a PR, with its data (`.json`) and Claude's notes (`.notes.json`) beside it. Only the 20 most recently written pages are kept. Pages aren't hosted: each person runs the review they want to see.
+
+## License
+
+MIT

package/dist/api-paths.d.ts

@@ -0,0 +1,18 @@
+import type { DanglingCall, Links } from './linker.ts';
+export type WebCall = DanglingCall;
+type CallingFile = {
+    readonly from: string;
+    readonly text: string;
+};
+export declare const webCalls: (files: ReadonlyArray<CallingFile>) => ReadonlyArray<WebCall>;
+type Route = {
+    readonly to: string;
+    readonly path: string;
+};
+type CallGraphOptions = {
+    readonly calls: ReadonlyArray<WebCall>;
+    readonly routes: ReadonlyArray<Route>;
+};
+export declare const callGraph: ({ calls, routes }: CallGraphOptions) => Links;
+export declare const apiRoutes: (text: string) => ReadonlyArray<string>;
+export {};

package/dist/api-paths.js

@@ -0,0 +1,22 @@
+const FETCH_LITERAL = /fetch\(\s*(['"`])(.*?)\1/g;
+const LEADING_ORIGIN = /^\$\{[^}]*\}/;
+const ROUTE_LITERAL = /\.route\(\s*"([^"]*)"/g;
+export const webCalls = (files) => files.flatMap(({ from, text }) => [...text.matchAll(FETCH_LITERAL)]
+    .map(([, , literal = '']) => literal.replace(LEADING_ORIGIN, ''))
+    .filter(path => !path.includes('${'))
+    .map(path => ({ from, path })));
+export const callGraph = ({ calls, routes }) => {
+    const routed = calls.flatMap(({ from, path }) => routes.filter(route => route.path === path).map(({ to }) => ({ from, to, path })));
+    const pairs = new Map(routed.map(({ from, to }) => [JSON.stringify([from, to]), { from, to }]));
+    return {
+        edges: [...pairs.values()].map(({ from, to }) => ({
+            from,
+            to,
+            via: [
+                ...new Set(routed.filter(other => other.from === from && other.to === to).map(({ path }) => path)),
+            ],
+        })),
+        dangling: calls.filter(({ path }) => !routes.some(route => route.path === path)),
+    };
+};
+export const apiRoutes = (text) => [...text.matchAll(ROUTE_LITERAL)].map(([, path = '']) => path);

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs, promisify } from 'node:util';
+import { diffGraphs, splitPatches } from './diff-graphs.js';
+import { notesProblems, readNotes } from './notes.js';
+import { onPath } from './on-path.js';
+import { pruneReviews } from './prune-reviews.js';
+import { readPullRequest } from './pull-request.js';
+import { readRange } from './read-range.js';
+import { notReadLine } from './skipped.js';
+import { snapshotWorkingTree } from './working-tree.js';
+const slot = (id, content) => `<script type="application/json" id="${id}">${content}</script>`;
+const fillSlot = (html, id, value) => html.replace(new RegExp(slot(id, '[\\s\\S]*?')), () => slot(id, JSON.stringify(value).replaceAll('<', '\\u003c')));
+const isDirectoryOrMissing = (path) => lstat(path).then(stats => stats.isDirectory(), () => true);
+const parseRange = (range) => {
+    const match = /^(.+?)\.\.(.+)$/.exec(range);
+    if (!match?.[1] || !match[2])
+        throw new Error('Usage: visual-review [<from>..<to> | <pr number>]');
+    return { from: match[1], to: match[2] };
+};
+const requireOnPath = (command, installFrom) => {
+    if (!onPath(command))
+        throw new Error(`${command} not found on PATH: install it from ${installFrom}`);
+};
+const rangeOf = async (repo, argument) => {
+    if (argument === undefined) {
+        return { range: 'HEAD..worktree', from: 'HEAD', to: await snapshotWorkingTree(repo) };
+    }
+    if (/^\d+$/.test(argument)) {
+        requireOnPath('gh', 'https://cli.github.com');
+        const { from, to, ...pullRequest } = await readPullRequest({ repo, number: Number(argument) });
+        return { range: `${from}..${to}`, from, to, pullRequest };
+    }
+    return { range: argument, ...parseRange(argument) };
+};
+const viewerWith = async (review) => fillSlot(await readFile(join(import.meta.dirname, '..', 'dist', 'viewer.html'), 'utf8'), 'review-data', review);
+const fillNotes = async ({ range, page, data, notesFile }) => {
+    const notes = await readNotes(notesFile);
+    const review = JSON.parse(await readFile(data, 'utf8').catch(() => {
+        throw new Error(`No page for ${range} yet: run visual-review without --notes first`);
+    }));
+    const problems = notesProblems({ diff: review.diff, notes });
+    if (problems.length > 0) {
+        throw new Error(`Notes in ${notesFile} don't match the graph:\n${problems.join('\n')}`);
+    }
+    await writeFile(page, fillSlot(await readFile(page, 'utf8'), 'review-notes', notes));
+};
+const writeReview = async (args) => {
+    const { positionals, values } = parseArgs({
+        args: [...args],
+        allowPositionals: true,
+        options: { notes: { type: 'string' } },
+    });
+    requireOnPath('git', 'https://git-scm.com/downloads');
+    const repo = (await promisify(execFile)('git', ['rev-parse', '--show-toplevel'])).stdout.trim();
+    const { range, from, to, ...pullRequest } = await rangeOf(repo, positionals[0]);
+    const directory = join(repo, '.reviews');
+    if (!(await isDirectoryOrMissing(directory)))
+        throw new Error(`${directory} is not a directory, so no page is written into it`);
+    const name = range.replaceAll('/', '_');
+    const page = join(directory, `${name}.html`);
+    const data = join(directory, `${name}.json`);
+    if (values.notes !== undefined) {
+        await fillNotes({ range, page, data, notesFile: values.notes });
+        return page;
+    }
+    const reading = await readRange({ repo, from, to });
+    reading.skipped.forEach(skip => {
+        console.error(notReadLine(skip));
+    });
+    const diff = diffGraphs(reading);
+    const { drawn, undrawn } = splitPatches({ diff, patches: reading.patches });
+    const review = {
+        range,
+        ...pullRequest,
+        diff,
+        dangling: reading.danglingCalls,
+        patches: drawn,
+        undrawn,
+        tests: reading.tests,
+        ...(reading.skipped.length === 0 ? {} : { skipped: reading.skipped }),
+    };
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, '.gitignore'), '*\n');
+    await writeFile(data, JSON.stringify(review));
+    await writeFile(page, await viewerWith(review));
+    await pruneReviews({ directory, keep: 20 });
+    return page;
+};
+writeReview(process.argv.slice(2)).then(page => console.log(page), (error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import type { GraphNode } from './graph.ts';
+export declare const CONFIG_FILE = "visual-review.config.json";
+export declare const READERS: readonly ['rust', 'typescript'];
+export type ReaderName = (typeof READERS)[number];
+export declare const LINKERS: readonly ['fetch-axum'];
+export type LinkerName = (typeof LINKERS)[number];
+export declare const folderOf: (path: string) => string;
+declare const StackSchema: z.ZodObject<{
+    reader: z.ZodOptional<z.ZodEnum<{
+        rust: "rust";
+        typescript: "typescript";
+    }>>;
+    root: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    sourceRoot: z.ZodOptional<z.ZodString>;
+    boxes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const ConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    stacks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        reader: z.ZodOptional<z.ZodEnum<{
+            rust: "rust";
+            typescript: "typescript";
+        }>>;
+        root: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        sourceRoot: z.ZodOptional<z.ZodString>;
+        boxes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>]>>>;
+    linkers: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        "fetch-axum": "fetch-axum";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        from: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        to: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>]>>>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare const configJsonSchema: () => z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    stacks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        reader: z.ZodOptional<z.ZodEnum<{
+            rust: "rust";
+            typescript: "typescript";
+        }>>;
+        root: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        sourceRoot: z.ZodOptional<z.ZodString>;
+        boxes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>]>>>;
+    linkers: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        "fetch-axum": "fetch-axum";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        from: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        to: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>]>>>;
+}, z.core.$strict>>;
+export declare const stackSettings: (config: Config, stack: string) => z.infer<typeof StackSchema>;
+type AddedStack = {
+    readonly stack: string;
+    readonly root: string;
+};
+type AddedStacksOptions = {
+    readonly config: Config;
+    readonly reader: ReaderName;
+    readonly detected: ReadonlyMap<string, string>;
+    readonly taken: ReadonlySet<string>;
+};
+export declare const addedStacks: ({ config, reader, detected, taken, }: AddedStacksOptions) => ReadonlyArray<AddedStack>;
+export declare const configuredNodes: (config: Config, nodes: ReadonlyArray<GraphNode>) => ReadonlyArray<GraphNode>;
+type DrawnStack = {
+    readonly stack: string;
+    readonly reader: {
+        readonly name: ReaderName;
+        readonly stackFields: ReadonlyArray<string>;
+    };
+};
+type LinkerReaders = {
+    readonly name: LinkerName;
+    readonly from: ReaderName;
+    readonly to: ReaderName;
+};
+export declare const checkConfig: (config: Config, stacks: ReadonlyArray<DrawnStack>, linkers: ReadonlyArray<LinkerReaders>) => void;
+export declare const parseConfig: (text: string) => Config;
+export {};

package/dist/config.js

@@ -0,0 +1,150 @@
+import { normalize } from 'node:path';
+import { z } from 'zod';
+export const CONFIG_FILE = 'visual-review.config.json';
+export const READERS = ['rust', 'typescript'];
+export const LINKERS = ['fetch-axum'];
+export const folderOf = (path) => normalize(path).replace(/\/$/, '');
+const folderInside = (parent) => z.string().refine(path => !`${folderOf(path)}/`.startsWith('../'), {
+    message: `must be a folder inside ${parent}`,
+});
+const StackSchema = z
+    .strictObject({
+    reader: z
+        .enum(READERS)
+        .optional()
+        .describe('With root, adds a stack detection missed, read by this reader'),
+    root: folderInside('the repo')
+        .optional()
+        .describe('With reader, the folder of the added stack, relative to the repo'),
+    label: z.string().optional().describe("The stack's label on the page; its id stays"),
+    sourceRoot: folderInside("the stack's root")
+        .optional()
+        .describe("TS stacks: the folder under the stack's root that holds its sources"),
+    boxes: z
+        .array(z.string())
+        .optional()
+        .describe('TS stacks: folder globs under the source root, each matched folder a box; other files box by first folder'),
+})
+    .refine(({ reader, root }) => (reader === undefined) === (root === undefined), {
+    message: 'give both reader and root, or neither',
+});
+const LinkerSchema = z.strictObject({
+    from: z
+        .array(z.string())
+        .optional()
+        .describe("The stacks it reads from, by drawn id; every stack of its from reader's by default"),
+    to: z
+        .array(z.string())
+        .optional()
+        .describe("The stacks it links to, by drawn id; every stack of its to reader's by default"),
+});
+const ConfigSchema = z.strictObject({
+    $schema: z.string().optional(),
+    stacks: z
+        .record(z.string(), z.union([z.literal(false), StackSchema], {
+        error: 'Invalid input: expected false or an object',
+    }))
+        .default({})
+        .describe('Stacks by the id the page draws; false drops one'),
+    linkers: z
+        .partialRecord(z.enum(LINKERS), z.union([z.literal(false), LinkerSchema], {
+        error: 'Invalid input: expected false or an object',
+    }))
+        .default({})
+        .describe('Linkers by name; false turns one off'),
+});
+export const configJsonSchema = () => z.toJSONSchema(ConfigSchema, { io: 'input' });
+export const stackSettings = (config, stack) => config.stacks[stack] || {};
+export const addedStacks = ({ config, reader, detected, taken, }) => {
+    const added = Object.entries(config.stacks).flatMap(([stack, settings]) => settings && settings.reader === reader && settings.root !== undefined
+        ? [{ stack, root: settings.root }]
+        : []);
+    const problems = added.flatMap(({ stack, root }) => {
+        const other = detected.get(folderOf(root));
+        const detectedAt = [...detected].find(([, id]) => id === stack)?.[0];
+        return [
+            ...(other === undefined
+                ? []
+                : [
+                    `${CONFIG_FILE}: stacks.${stack}.root: ${root} is detected as stack ${other}; set stacks.${other} instead`,
+                ]),
+            ...(detectedAt === undefined
+                ? []
+                : [
+                    `${CONFIG_FILE}: stacks.${stack} is detected at ${detectedAt}; add the stack under another key, or drop its reader and root`,
+                ]),
+            ...(taken.has(stack)
+                ? [
+                    `${CONFIG_FILE}: stacks.${stack} is drawn by another reader; add the stack under another key, or drop its reader and root`,
+                ]
+                : []),
+        ];
+    });
+    if (problems.length > 0)
+        throw new Error(problems.join('\n'));
+    return added;
+};
+export const configuredNodes = (config, nodes) => nodes.map(node => ({ ...node, label: stackSettings(config, node.id).label ?? node.label }));
+const OWN_FIELDS = ['reader', 'root', 'label'];
+const undetectedIn = (config, stacks) => Object.keys(config.stacks)
+    .filter(stack => !stacks.some(drawn => drawn.stack === stack))
+    .map(stack => {
+    const { reader, root } = stackSettings(config, stack);
+    return reader === undefined
+        ? `${CONFIG_FILE}: stacks.${stack} names no detected stack; give it reader and root to add one`
+        : `${CONFIG_FILE}: stacks.${stack}.root: ${root} holds no ${reader} stack on either side`;
+});
+const untakenIn = (config, stacks) => [
+    ...new Set(stacks.flatMap(({ stack, reader }) => Object.keys(stackSettings(config, stack))
+        .filter(field => !OWN_FIELDS.includes(field) && !reader.stackFields.includes(field))
+        .map(field => `${CONFIG_FILE}: stacks.${stack}.${field} is not taken by the ${reader.name} reader`))),
+];
+const unlinkableIn = (config, stacks, linkers) => linkers.flatMap(linker => {
+    const settings = config.linkers[linker.name] || {};
+    return ['from', 'to'].flatMap(end => (settings[end] ?? []).flatMap(stack => {
+        if (config.stacks[stack] === false)
+            return [
+                `${CONFIG_FILE}: linkers.${linker.name}.${end}: ${stack} is dropped by stacks.${stack}`,
+            ];
+        return stacks.some(drawn => drawn.stack === stack && drawn.reader.name === linker[end])
+            ? []
+            : [
+                `${CONFIG_FILE}: linkers.${linker.name}.${end}: ${stack} names no ${linker[end]} stack on either side`,
+            ];
+    }));
+});
+export const checkConfig = (config, stacks, linkers) => {
+    const problems = [
+        ...undetectedIn(config, stacks),
+        ...untakenIn(config, stacks),
+        ...unlinkableIn(config, stacks, linkers),
+    ];
+    if (problems.length > 0)
+        throw new Error(problems.join('\n'));
+};
+const jsonIn = (text) => {
+    try {
+        return JSON.parse(text.replace(/^\uFEFF/, ''));
+    }
+    catch (error) {
+        throw new Error(`${CONFIG_FILE}: ${String(error)}`);
+    }
+};
+const withinUnions = (issue) => {
+    if (issue.code !== 'invalid_union')
+        return [issue];
+    const within = issue.errors
+        .flat()
+        .filter(({ path }) => path.length > 0)
+        .map(inner => ({ ...inner, path: [...issue.path, ...inner.path] }));
+    return within.length > 0 ? within : [issue];
+};
+export const parseConfig = (text) => {
+    const result = ConfigSchema.safeParse(jsonIn(text));
+    if (result.success)
+        return result.data;
+    throw new Error(result.error.issues
+        .flatMap(withinUnions)
+        .map(({ path, message }) => [CONFIG_FILE, ...(path.length === 0 ? [] : [path.join('.')]), message].join(': '))
+        .join('\n'));
+};

package/dist/config.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "stacks": {
+      "default": {},
+      "description": "Stacks by the id the page draws; false drops one",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "boolean",
+            "const": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "reader": {
+                "description": "With root, adds a stack detection missed, read by this reader",
+                "type": "string",
+                "enum": [
+                  "rust",
+                  "typescript"
+                ]
+              },
+              "root": {
+                "description": "With reader, the folder of the added stack, relative to the repo",
+                "type": "string"
+              },
+              "label": {
+                "description": "The stack's label on the page; its id stays",
+                "type": "string"
+              },
+              "sourceRoot": {
+                "description": "TS stacks: the folder under the stack's root that holds its sources",
+                "type": "string"
+              },
+              "boxes": {
+                "description": "TS stacks: folder globs under the source root, each matched folder a box; other files box by first folder",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "linkers": {
+      "default": {},
+      "description": "Linkers by name; false turns one off",
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "enum": [
+          "fetch-axum"
+        ]
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "boolean",
+            "const": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "from": {
+                "description": "The stacks it reads from, by drawn id; every stack of its from reader's by default",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "to": {
+                "description": "The stacks it links to, by drawn id; every stack of its to reader's by default",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/dist/crate-graph.d.ts

@@ -0,0 +1,8 @@
+import type { Graph } from './graph.ts';
+export declare const crateId: (name: string) => string;
+export declare const crateGraph: (metadataJson: string) => Graph;
+export declare const crateRoots: (metadataJson: string) => {
+    crate: string;
+    directory: string;
+    roots: string[];
+}[];

package/dist/crate-graph.js

@@ -0,0 +1,51 @@
+import { dirname, relative } from 'node:path';
+import { z } from 'zod';
+const CargoMetadataSchema = z.object({
+    workspace_root: z.string(),
+    packages: z.array(z.object({
+        name: z.string(),
+        manifest_path: z.string(),
+        dependencies: z.array(z.object({ path: z.string().optional() })),
+        targets: z.array(z.object({ kind: z.array(z.string()), src_path: z.string() })),
+    })),
+});
+const rustStack = { id: 'rust', kind: 'stack', label: 'rust', path: '' };
+export const crateId = (name) => `${rustStack.id}/crate/${name}`;
+export const crateGraph = (metadataJson) => {
+    const metadata = CargoMetadataSchema.parse(JSON.parse(metadataJson));
+    const crates = metadata.packages.map(pkg => ({
+        ...pkg,
+        directory: dirname(pkg.manifest_path),
+    }));
+    const idByDirectory = new Map(crates.map(pkg => [pkg.directory, crateId(pkg.name)]));
+    return {
+        nodes: [
+            rustStack,
+            ...crates.map((pkg) => ({
+                id: crateId(pkg.name),
+                kind: 'package',
+                label: pkg.name,
+                parent: rustStack.id,
+                path: relative(metadata.workspace_root, pkg.directory),
+            })),
+        ],
+        edges: crates.flatMap(pkg => {
+            const targets = new Set(pkg.dependencies.flatMap(dependency => {
+                const to = idByDirectory.get(dependency.path);
+                return to === undefined ? [] : [to];
+            }));
+            return [...targets].map(to => ({ from: crateId(pkg.name), to }));
+        }),
+    };
+};
+const NOT_A_ROOT = new Set(['test', 'bench', 'example', 'custom-build']);
+export const crateRoots = (metadataJson) => {
+    const metadata = CargoMetadataSchema.parse(JSON.parse(metadataJson));
+    return metadata.packages.map(pkg => ({
+        crate: pkg.name,
+        directory: relative(metadata.workspace_root, dirname(pkg.manifest_path)),
+        roots: pkg.targets
+            .filter(target => !target.kind.some(kind => NOT_A_ROOT.has(kind)))
+            .map(target => relative(metadata.workspace_root, target.src_path)),
+    }));
+};

package/dist/crate-modules.d.ts

@@ -0,0 +1,8 @@
+import { type Graph } from './graph.ts';
+type CrateModulesOptions = {
+    readonly crate: string;
+    readonly roots: ReadonlyArray<string>;
+    readonly sources: Readonly<Record<string, string>>;
+};
+export declare const crateModules: ({ crate, roots, sources }: CrateModulesOptions) => Graph;
+export {};