cawdev-cli 0.9.0

package/README.md

@@ -0,0 +1,175 @@
+# tools
+
+Plain Node, **zero dependencies**, by design (see `CLAUDE.md`): stdio JSON-RPC
+and spawning processes are Node's home turf, and a file with no dependencies is
+one you can read before running it against your repositories.
+
+Everything here reads `CAWDEV_URL`, `CAWDEV_TOKEN` and optionally
+`CAWDEV_PROJECT` from the environment or a `.env` at the repository root —
+**read on every call**, so editing `.env` needs no restart.
+
+Mint a token in the console under **Agent tokens**. It needs `roadmap:write`
+and `changelog:write` on the project you are exporting.
+
+## The generated files
+
+`ROADMAP.md` and `CHANGELOG.md` at the repository root are **exports**. Editing
+them by hand is lost at the next export. Change the entry in the console or
+through MCP, then regenerate:
+
+```sh
+node tools/roadmap/export.mjs cawdev
+node tools/changelog/export.mjs cawdev
+```
+
+Both are byte-stable: the same data produces the same bytes, so a regenerated
+file shows a diff only when the roadmap actually changed. CI proves
+export → import → export is a fixed point.
+
+### Where a section goes in the file
+
+An entry's `section` is a planning decision and lives in the database. The
+**order** the sections appear in is prose layout, and lives beside the exporter
+as `SECTION_ORDER` in `tools/roadmap/export.mjs`. `Considering` and `Declined`
+are not in that list: they are derived from status by `sectionOf`, and always
+come last.
+
+A section that is not in `SECTION_ORDER` is **appended, and named in the note
+the exporter prints** under its per-status counts, along with the number of
+entries it holds. It is a note rather than a failure — a new phase is
+legitimate, and an exporter that refused one would block the release that
+introduced it — but it should not arrive unannounced. Silence is how the list
+fell three sections behind and `"Roadmap"`, the fallback for an entry with no
+section of its own, became a junk drawer holding eight built features (R45).
+
+When you see the note: add the section to `SECTION_ORDER` in the position it
+should read in, or give those entries a section that is already there. Sections
+are renamed, merged and unfiled from the console's **Sections** dialog on the
+roadmap board (R264), and that dialog cannot reach this file: after a rename,
+update `SECTION_ORDER` too, or the note will list the new name.
+
+## `tools/roadmap/import.mjs`
+
+The one-time move from a hand-written `ROADMAP.md` into the platform, and the
+other half of that fixed point.
+
+```sh
+node tools/roadmap/import.mjs cawdev --file ROADMAP.md
+```
+
+It is **idempotent enough to re-run after a partial failure**: entries that
+already exist are updated rather than duplicated. It refuses to start when
+preserving ids is impossible — ids are permanent, and silently renumbering them
+would break every commit message that points at one.
+
+## `roadmap.mjs` (repository root)
+
+```sh
+node roadmap.mjs           # shape: ids unique, statuses legal, required fields present
+node roadmap.mjs --live    # also: SHIPPED versions are real tags, CODING and
+                           # REVIEW branches exist, and the file matches the database
+node roadmap.mjs --live --project cawdev   # when CAWDEV_PROJECT is not set
+```
+
+Both forms run in CI. The shape checks catch what a review forgets — an entry
+that says `CODING` without naming a branch, an entry that says `MERGED` without
+naming the merge, a `Related:` pointing at nothing. `--live` catches the claims a
+file cannot check about itself: that a version someone wrote down was in fact
+tagged, and that the file is still the export it says it is. A `REVIEW` entry's
+branch is checked like a `CODING` one — the status claims there is something to
+read. A `MERGED` entry is checked against neither tags nor branches, because its
+branch is meant to have been deleted.
+
+That last one re-runs `tools/roadmap/export.mjs` into a temporary file and
+compares the bytes. It goes through the exporter rather than rendering a second
+copy of it, so the two cannot drift apart. A difference fails and names the
+entries — missing here, missing there, or changed — with the remedy. If every
+entry agrees and the bytes still differ, the preamble or the section layout was
+edited by hand.
+
+It needs a `CAWDEV_TOKEN` and a project. Without them it prints a note saying it
+was skipped and the git checks still run; a check that cannot answer says so
+rather than passing (R41). If the token is set and the platform rejects it or is
+down, that is not "cannot answer" — it fails, with the API's own message.
+
+## Tests
+
+```sh
+node --test "tools/**/*.test.mjs"
+```
+
+`tools/lib/roadmap-format.test.mjs` covers the parse/render round trip. If those
+two stop agreeing, the generated file churns on every export and its diff stops
+meaning "the roadmap changed".
+
+`tools/lib/usage.test.mjs` covers what a turn reports. One of its tests asserts
+that **no dollar figure reaches a transcript**: the CLI quotes list prices, and
+a subscription does not work that way.
+
+`tools/lib/tool-rules.test.mjs` covers the matcher for what a run may do (R51).
+Every assertion of `false` in it is asserting that somebody gets asked a
+question they may have answered before — the cheap failure. The expensive one is
+a `true` nobody intended.
+
+`tools/mcp/approve.test.mjs` drives the real server over stdio against a faked
+platform, and pins the shape Claude Code reads back: a permission decision is
+JSON in the result text, and getting it wrong does not fail loudly — it stops a
+session, which is the failure R51 exists to end.
+
+`tools/runner/control.test.mjs` covers the socket a daemon offers (R52) on a
+real socket, including the backlog somebody attaching to an hour-old session
+needs, and that an unknown command is ignored rather than obeyed — that socket
+is a read-only view on purpose.
+
+`tools/runner/attach.test.mjs` covers the rendering arithmetic, which is where a
+terminal UI goes wrong silently: transcripts carry the agent's ANSI colour, and
+measuring it as plain text wraps the pane into nonsense.
+
+`tools/runner/workspaces.test.mjs` is R47 against the real daemon: two coding
+runs on one project, at the same time, in different checkouts, each reporting
+which. Getting that gate wrong is expensive in both directions — too tight and a
+machine with three checkouts still runs one session, too loose and two agents
+share a working copy.
+
+`tools/runner/test-platform.mjs` is the cawdev those two tests register with.
+Not a test itself, and not production code: it is a fake platform with a queue,
+shared because two fakes drift.
+
+`tools/runner/daemon-boot.test.mjs` starts the **real daemon** against a faked
+platform and a fake agent command. It is the only test of the first ten seconds
+— registering, the R51 permission-flag probe, opening the socket, and removing
+it again on the way out — a path that otherwise needs a `runner:operate` token
+to reach at all.
+
+## `tools/mcp/`
+
+The MCP server an agent talks to — zero dependencies, stdio JSON-RPC.
+`tools/mcp/README.md` covers setting it up in a repository, and is also written
+for the agent that reads it: it teaches the working method (branch first,
+`CODING` names the branch before the first commit, `roadmap_where` when in
+doubt).
+
+`tools/mcp/smoke.mjs` drives the server the way a client does — spawn, write
+lines to stdin, read lines from stdout — because the parts most likely to break
+are the transport and the framing. CI runs it against the compose stack.
+
+## `tools/runner/`
+
+The daemon that claims queued runs and spawns a real agent CLI in a working
+copy. `tools/runner/README.md` covers running one.
+
+## `tools/console/`
+
+`console-smoke.mjs` is the end-to-end test for the console's half of the loop
+(R12): start a run on an entry, watch the messages, answer the question from the
+inbox, see the finish report carrying the branch — all over the endpoints the
+browser calls, on a real session cookie. Point it at a **scratch project**: it
+creates an entry, cancels any live run, and declines the entry afterwards.
+
+```sh
+node tools/console/console-smoke.mjs scratch
+```
+
+Unlike everything else here it signs in rather than using `CAWDEV_TOKEN`, because
+starting a run and answering a question are both a *person's* acts — an agent
+cannot do either, so the test cannot bootstrap itself from a token.

package/lib/ansi.mjs

@@ -0,0 +1,224 @@
+// Colour in a terminal, and the good manners around it — R62.
+//
+// Zero dependencies, like everything in tools/. That is not austerity for its
+// own sake: a colour library is a supply chain, and what it does for us is
+// thirty lines of escape codes that have not changed since 1979.
+//
+// Three rules, and the second two are the ones people forget:
+//
+//   1. Say what the terminal can hear. Truecolor where it advertises it, the
+//      256-colour cube where it does not, nothing where colour is unwanted.
+//   2. **Never carry meaning in colour alone.** Every state that has a colour
+//      here also has a word beside it, because a pipe, a CI log and a
+//      red-green reader are all normal.
+//   3. **Measure what is visible, not what is written.** A coloured string is
+//      longer than it looks, and padding it by `length` is how a table stops
+//      lining up the moment anything in it goes red.
+
+/**
+ * Whether to colour at all, and how richly.
+ *
+ * `NO_COLOR` is honoured for any value, which is what the convention asks
+ * (no-color.org): its presence is the signal, not its contents. `FORCE_COLOR`
+ * overrides in the other direction, for the case this is piped somewhere that
+ * does understand escapes — a file somebody will `less -R`, a CI log viewer.
+ */
+export function colourDepth(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR !== undefined) return 0;
+  if (env.FORCE_COLOR !== undefined) {
+    // `FORCE_COLOR=` with nothing after it means ON, which is how people
+    // usually write it. `Number('')` is 0, so reading this numerically without
+    // saying so first silences colour for exactly the person who asked for it.
+    const asked = env.FORCE_COLOR.trim();
+    if (asked === '') return 3;
+    if (asked === '0' || asked.toLowerCase() === 'false') return 0;
+    const level = Number(asked);
+    return Number.isFinite(level) ? Math.min(3, Math.max(0, level)) : 3;
+  }
+  if (!stream?.isTTY) return 0;
+  if (env.TERM === 'dumb') return 0;
+  if (env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit') return 3;
+  if (/-256(color)?$/i.test(env.TERM ?? '')) return 2;
+  return env.TERM ? 1 : 0;
+}
+
+/** The nearest colour the terminal can actually show. */
+function code(depth, [r, g, b], basic) {
+  if (depth >= 3) return `\x1b[38;2;${r};${g};${b}m`;
+  if (depth === 2) return `\x1b[38;5;${cube(r, g, b)}m`;
+  return `\x1b[${basic}m`;
+}
+
+/**
+ * A 24-bit colour in the 256-colour cube.
+ *
+ * The greys are a separate ramp and are worth using: rounding a near-grey into
+ * the 6×6×6 cube gives it a colour cast, which on the dim text this file is
+ * mostly used for reads as "the terminal is broken".
+ */
+function cube(r, g, b) {
+  if (Math.abs(r - g) < 12 && Math.abs(g - b) < 12) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return 232 + Math.round(((r - 8) / 247) * 23);
+  }
+  const axis = (value) => Math.round((value / 255) * 5);
+  return 16 + 36 * axis(r) + 6 * axis(g) + axis(b);
+}
+
+/**
+ * A painter bound to one terminal's abilities.
+ *
+ * Every colour names a **basic fallback** as well as its true value, so a
+ * 16-colour terminal gets something deliberate rather than whatever the cube
+ * rounds to.
+ */
+export function painter(depth = colourDepth()) {
+  const on = depth > 0;
+  const wrap = (open) => (text) => (on ? `${open}${text}\x1b[0m` : String(text));
+  const ink = (rgb, basic) => wrap(code(depth, rgb, basic));
+
+  return {
+    depth,
+    enabled: on,
+
+    // cawdev's own mark, from cawdev-mark.svg. Used for the logo and nowhere
+    // else: the brand is not a status.
+    violet: ink([0x4b, 0x3f, 0xd4], 35),
+    violetLight: ink([0x75, 0x68, 0xe3], 95),
+    amber: ink([0xf0, 0xa2, 0x2e], 33),
+
+    /**
+     * The working palette, in Claude Code's warm register rather than the
+     * console's violet: this is a terminal tool sitting beside the CLI it
+     * drives, and matching that is what makes it look like it belongs.
+     * One place to change if that judgement changes.
+     */
+    accent: ink([0xd9, 0x77, 0x57], 33),
+    success: ink([0x71, 0xa5, 0x78], 32),
+    warn: ink([0xd9, 0xa0, 0x57], 33),
+    danger: ink([0xc0, 0x62, 0x62], 31),
+    muted: ink([0x8a, 0x86, 0x82], 90),
+    text: ink([0xd4, 0xd0, 0xcc], 37),
+
+    bold: wrap('\x1b[1m'),
+    dim: wrap('\x1b[2m'),
+    reverse: wrap('\x1b[7m'),
+    /** Plain, for a value that should not compete with the label beside it. */
+    plain: (text) => String(text),
+  };
+}
+
+/**
+ * A string's width on screen, ignoring escape sequences.
+ *
+ * The one function everything that lines up depends on. Padding by `length`
+ * counts the escapes, so a coloured cell is silently ~10 characters wide and
+ * the column after it walks.
+ */
+export function visibleWidth(text) {
+  return stripAnsi(String(text)).length;
+}
+
+export function stripAnsi(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '');
+}
+
+/** Pads to `width` by what is visible, never by what is written. */
+export function padVisible(text, width) {
+  const short = width - visibleWidth(text);
+  return short > 0 ? `${text}${' '.repeat(short)}` : text;
+}
+
+/**
+ * A row of keys, and whatever was just said, in the room there is.
+ *
+ * **Whole keys are dropped rather than a key being cut in half.** At sixty
+ * columns this row ended `x c`, and at forty `y/`, which is not a shorter list
+ * — it is a list with a typo at the end of it. The status goes first, because
+ * it is a sentence about something that already happened; then keys from the
+ * right, where the rarer ones are.
+ *
+ * Here rather than in the terminal client since R83, because the client is no
+ * longer the only thing that draws one: every select widget ends in a row of
+ * keys, and two implementations of "drop from the right" is two chances to get
+ * the arithmetic wrong.
+ */
+export function keyList(keys, status, width, ink = painter(3)) {
+  const parts = Array.isArray(keys) ? [...keys] : [String(keys)];
+  const said = status ? `  ${ink.warn(status)}` : '';
+  const join = (of, tail) => of.join(ink.muted(' · ')) + (of.length < parts.length ? ink.muted(' …') : '') + tail;
+
+  if (visibleWidth(join(parts, said)) <= width) {
+    return join(parts, said);
+  }
+  const shown = [...parts];
+  while (shown.length > 1 && visibleWidth(join(shown, '')) > width) {
+    shown.pop();
+  }
+  return join(shown, '');
+}
+
+/**
+ * Wraps to a width, keeping escape sequences where they fall.
+ *
+ * Here rather than in the terminal client because rule 3 above is what it is
+ * for: a transcript carries the agent's own colour (R23), and wrapping it by
+ * `length` breaks every coloured line forty characters early.
+ */
+export function wrap(text, width) {
+  const lines = [];
+  for (const paragraph of String(text).split('\n')) {
+    if (visibleWidth(paragraph) <= width) {
+      lines.push(paragraph);
+      continue;
+    }
+    let current = '';
+    let visible = 0;
+    for (let i = 0; i < paragraph.length; i++) {
+      const escape = /^\x1b\[[0-9;?]*[a-zA-Z]/.exec(paragraph.slice(i));
+      if (escape) {
+        current += escape[0];
+        i += escape[0].length - 1;
+        continue;
+      }
+      current += paragraph[i];
+      visible += 1;
+      if (visible >= width) {
+        lines.push(current);
+        current = '';
+        visible = 0;
+      }
+    }
+    if (current) {
+      // Trailing escapes with nothing after them — the reset at the end of a
+      // coloured line — belong to the line they close, not to a new empty one.
+      // Without this every coloured line is followed by a blank.
+      if (visible === 0 && lines.length) {
+        lines[lines.length - 1] += current;
+      } else {
+        lines.push(current);
+      }
+    }
+  }
+  return lines;
+}
+
+/** Cuts to a width without cutting an escape sequence in half. */
+export function clip(text, width) {
+  if (visibleWidth(text) <= width) return text;
+  let out = '';
+  let visible = 0;
+  for (let i = 0; i < text.length && visible < width; i++) {
+    const escape = /^\x1b\[[0-9;?]*[a-zA-Z]/.exec(text.slice(i));
+    if (escape) {
+      out += escape[0];
+      i += escape[0].length - 1;
+      continue;
+    }
+    out += text[i];
+    visible += 1;
+  }
+  return `${out}\x1b[0m`;
+}

package/lib/cawdev.mjs

@@ -0,0 +1,104 @@
+// A tiny cawdev API client. Plain Node, zero dependencies — see CLAUDE.md:
+// a zero-dep file is one anyone can read before running it against their
+// repositories, and every tool here is meant to be read.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Reads CAWDEV_URL / CAWDEV_TOKEN / CAWDEV_PROJECT from the environment, or
+ * from a .env beside the repository root.
+ *
+ * Read on every call rather than cached at import: editing .env should not
+ * need a restart. (R8's MCP server keeps the same rule — dycrypt learned it
+ * the hard way, and losing it is how an agent ends up writing to the wrong
+ * platform for an hour.)
+ */
+export async function readConfig(startDirectory = process.cwd()) {
+  const fromEnv = {
+    url: process.env.CAWDEV_URL,
+    token: process.env.CAWDEV_TOKEN,
+    project: process.env.CAWDEV_PROJECT,
+  };
+
+  const fromFile = await readDotEnv(startDirectory);
+  const config = {
+    url: (fromEnv.url ?? fromFile.CAWDEV_URL ?? 'http://localhost:4200').replace(/\/+$/, ''),
+    token: fromEnv.token ?? fromFile.CAWDEV_TOKEN,
+    project: fromEnv.project ?? fromFile.CAWDEV_PROJECT,
+    // Where each value came from, so a surprising result can be traced.
+    source: {
+      url: fromEnv.url ? 'environment' : fromFile.CAWDEV_URL ? '.env' : 'default',
+      token: fromEnv.token ? 'environment' : fromFile.CAWDEV_TOKEN ? '.env' : 'unset',
+      project: fromEnv.project ? 'environment' : fromFile.CAWDEV_PROJECT ? '.env' : 'unset',
+    },
+  };
+  return config;
+}
+
+async function readDotEnv(startDirectory) {
+  let directory = resolve(startDirectory);
+  for (let depth = 0; depth < 5; depth++) {
+    try {
+      const text = await readFile(join(directory, '.env'), 'utf8');
+      const values = {};
+      for (const line of text.split('\n')) {
+        const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+        if (match) values[match[1]] = match[2].replace(/^["']|["']$/g, '');
+      }
+      return values;
+    } catch {
+      const parent = dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return {};
+}
+
+/** Throws with the API's own message, which is the one that explains the rule. */
+export async function call(config, path, { method = 'GET', body } = {}) {
+  if (!config.token) {
+    throw new Error(
+      'No CAWDEV_TOKEN. Mint one in the console under Agent tokens, then put it in ' +
+        'the environment or a .env file.',
+    );
+  }
+
+  const response = await fetch(`${config.url}${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      ...(body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const text = await response.text();
+  const parsed = text ? safeJson(text) : null;
+
+  if (!response.ok) {
+    const detail = parsed?.message ?? text ?? `HTTP ${response.status}`;
+    throw new Error(`${method} ${path} -> ${response.status}: ${detail}`);
+  }
+  return parsed;
+}
+
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** Resolves the project slug, preferring an explicit argument. */
+export function resolveProject(config, explicit) {
+  const slug = explicit ?? config.project;
+  if (!slug) {
+    throw new Error(
+      'No project. Pass one as an argument, or set CAWDEV_PROJECT in the environment or .env.',
+    );
+  }
+  return slug;
+}

package/lib/code-map.mjs

@@ -0,0 +1,164 @@
+// The shape of a codebase: which files exist, and which of them reach for which
+// others — R77's Map tab.
+//
+// **Pure, and deliberately so.** Everything here takes text and returns data, so
+// the hard part — resolving a written import to a file that exists — can be
+// tested without a repository, a daemon or a network. The runner does the
+// reading; this does the thinking.
+//
+// **Why not CodeGraph.** R76 says use it rather than rebuild it, and that still
+// holds for what R76 is for: symbols and call paths, queried by an agent over
+// MCP, one question at a time. This is a different graph for a different
+// consumer — every file and every edge at once, laid out for a person to look
+// at — and R76's own text names that as the case where rebuilding is right: "if
+// the graph it exposes over MCP is not the graph the next entry needs". An
+// import edge is also the one thing a reader can check by opening the file,
+// which a call path inferred through a parser is not.
+
+/** Files we can honestly extract dependencies from. Others are drawn with no edges. */
+const READABLE = /\.(java|mjs|js|ts|tsx|jsx)$/;
+
+/** What counts as a source file at all — the map's population. */
+const SOURCE = /\.(java|mjs|js|ts|tsx|jsx|html|css|sql|yaml|yml)$/;
+
+/**
+ * Java imports.
+ *
+ * <p>All of them, including `java.util.List`; the resolver drops the ones that
+ * point outside the repository. Filtering here would need this function to know
+ * what the project is called, which is the resolver's business.
+ */
+function javaImports(text) {
+  const found = [];
+  for (const line of text.split('\n')) {
+    const match = /^\s*import\s+(?:static\s+)?([\w.]+)\s*;/.exec(line);
+    if (match) {
+      found.push(match[1]);
+    }
+  }
+  return found;
+}
+
+/** ESM imports and re-exports, which in this corpus are always relative. */
+function esmImports(text) {
+  const found = [];
+  const pattern = /(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    found.push(match[1]);
+  }
+  return found;
+}
+
+/** `a/b/c.ts` + `../d` -> `a/d`. Null when it is not relative, or climbs out. */
+export function resolveRelative(from, specifier) {
+  if (!specifier.startsWith('.')) {
+    return null;
+  }
+  const parts = from.split('/').slice(0, -1);
+  for (const step of specifier.split('/')) {
+    if (step === '.' || step === '') continue;
+    if (step === '..') {
+      if (!parts.length) return null;
+      parts.pop();
+      continue;
+    }
+    parts.push(step);
+  }
+  return parts.join('/');
+}
+
+/**
+ * The file a specifier means, or null.
+ *
+ * <p>Null is the honest answer and is kept as one: a specifier resolving to
+ * nothing in this repository is a dependency on something outside it, and
+ * inventing a node for it would fill the map with somebody else's libraries.
+ */
+function resolveIn(known, base) {
+  if (!base) {
+    return null;
+  }
+  if (known.has(base)) {
+    return base;
+  }
+  for (const suffix of ['.ts', '.tsx', '.js', '.mjs', '.jsx']) {
+    if (known.has(base + suffix)) {
+      return base + suffix;
+    }
+  }
+  for (const suffix of ['/index.ts', '/index.js', '/index.mjs']) {
+    if (known.has(base + suffix)) {
+      return base + suffix;
+    }
+  }
+  return null;
+}
+
+/**
+ * A Java class name to the file that declares it.
+ *
+ * <p>By package path rather than by class name: two packages may each hold a
+ * `Runner`, and picking whichever was read first would draw an edge to the
+ * wrong one — a lie a reader cannot see. `a.b.C` is `.../a/b/C.java`, and
+ * indexing by the tail after `/java/` is what copes with `src/main/java` in
+ * front of it.
+ */
+function resolveJava(byJavaPath, name) {
+  return byJavaPath.get(name.replace(/\./g, '/') + '.java') ?? null;
+}
+
+/**
+ * The map: every source file, and every edge between two of them.
+ *
+ * @param files `[{path, text}]`. `text` may be absent for a file whose
+ *   dependencies are not read — it is still drawn, because a map missing the
+ *   CSS is a map of somewhere else.
+ */
+export function codeMapOf(files) {
+  const paths = files.map((each) => each.path).filter((path) => SOURCE.test(path));
+  const known = new Set(paths);
+
+  const byJavaPath = new Map();
+  for (const path of paths) {
+    if (!path.endsWith('.java')) continue;
+    const at = path.indexOf('/java/');
+    byJavaPath.set(at === -1 ? path : path.slice(at + '/java/'.length), path);
+  }
+
+  // Nested rather than a composite key: a delimiter is a character somebody's
+  // filename eventually contains.
+  const out = new Map();
+  for (const file of files) {
+    if (!file.text || !READABLE.test(file.path) || !known.has(file.path)) {
+      continue;
+    }
+    const targets = file.path.endsWith('.java')
+      ? javaImports(file.text).map((name) => resolveJava(byJavaPath, name))
+      : esmImports(file.text).map(
+          (specifier) => resolveIn(known, resolveRelative(file.path, specifier)));
+
+    for (const to of targets) {
+      // A file importing itself is a re-export shim, not a dependency, and a
+      // self-loop is a circle drawn on top of a box.
+      if (!to || to === file.path) continue;
+      if (!out.has(file.path)) {
+        out.set(file.path, new Map());
+      }
+      const mine = out.get(file.path);
+      mine.set(to, (mine.get(to) ?? 0) + 1);
+    }
+  }
+
+  const edges = [];
+  for (const [from, targets] of out) {
+    for (const [to, weight] of targets) {
+      edges.push({ from, to, weight });
+    }
+  }
+
+  return {
+    files: paths.sort().map((path) => ({ path, dir: path.split('/').slice(0, -1).join('/') })),
+    edges,
+  };
+}