dsh-model-everything 0.4.0 → 0.5.0

package/lib/render/svg.js

@@ -0,0 +1,107 @@
+/**
+ * Shapes to SVG markup.
+ *
+ * The one module that knows tags, so it is also the one place where a shape can silently disappear if a
+ * writer forgets a case: the writer table has an entry per shape kind, and the caller counts the drops
+ * instead of hiding them.
+ *
+ * Three containers read this output - an inline card, a full-screen view, and a sidebar tab - so the markup
+ * carries no size of its own beyond its `viewBox`: the container decides how large the drawing is, and the
+ * same string serves a thumbnail and a whiteboard.
+ *
+ * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
+ */
+/** One decimal place is enough at any zoom, and it keeps the markup readable. */
+const n = (value) => {
+    const rounded = Math.round(value * 10) / 10;
+    return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+};
+const escape = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const writers = {
+    // A boundary is a dashed rectangle with its name in the top-left corner, drawn under everything else.
+    group: (shape, colours) => {
+        const stroke = colours[shape.colour];
+        // The id travels in the markup so a container can fold a boundary by delegation, without re-deriving which
+        // group a click landed on from its position or its label.
+        return ('<g data-group-id="' + escape(shape.id) + '" style="cursor:pointer">' +
+            '<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
+            '" rx="8" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-dasharray="4 3" />' +
+            '<text x="' + n(shape.x + 6) + '" y="' + n(shape.y + 12) + '" font-size="10" fill="' + stroke + '">' + escape(shape.label) + '</text>' +
+            '</g>');
+    },
+    box: (shape, colours) => {
+        const stroke = colours[shape.colour];
+        const width = shape.initial ? 2.5 : 1;
+        return ('<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
+            '" rx="6" fill="' + colours.surface + '" stroke="' + stroke + '" stroke-width="' + n(width) + '" />' +
+            '<text x="' + n(shape.x + shape.width / 2) + '" y="' + n(shape.y + shape.height / 2 + 4) +
+            '" font-size="11" text-anchor="middle" fill="' + stroke + '">' + escape(shape.label) + '</text>');
+    },
+    link: (shape, colours) => {
+        const stroke = colours[shape.colour];
+        const arrow = arrowHead(shape.x1, shape.y1, shape.x2, shape.y2, stroke);
+        return ('<line x1="' + n(shape.x1) + '" y1="' + n(shape.y1) + '" x2="' + n(shape.x2) + '" y2="' + n(shape.y2) +
+            '" stroke="' + stroke + '" stroke-width="1" />' + arrow + edgeLabel(shape.label, shape.labelX, shape.labelY, colours));
+    },
+    path: (shape, colours) => {
+        const stroke = colours[shape.colour];
+        const points = shape.points.map((point) => n(point.x) + ',' + n(point.y)).join(' ');
+        const last = shape.points[shape.points.length - 1];
+        const before = shape.points[shape.points.length - 2] ?? last;
+        return ('<polyline points="' + points + '" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-linejoin="round" />' +
+            arrowHead(before.x, before.y, last.x, last.y, stroke) + edgeLabel(shape.label, shape.labelX, shape.labelY, colours));
+    },
+    title: (shape, colours) => {
+        return '<text x="' + n(shape.x) + '" y="' + n(shape.y) + '" font-size="12" fill="' + colours[shape.colour] + '">' + escape(shape.text) + '</text>';
+    },
+    caption: (shape, colours) => {
+        const colour = colours[shape.colour];
+        const lines = shape.lines
+            .map((line, index) => '<tspan x="' + n(shape.x) + '" dy="' + (index === 0 ? 0 : 15) + '">' + escape(line) + '</tspan>')
+            .join('');
+        return '<text x="' + n(shape.x) + '" y="' + n(shape.y + 11) + '" font-size="10" fill="' + colour + '">' + lines + '</text>';
+    },
+};
+/** A small filled triangle at the end of a segment, pointing along it. */
+function arrowHead(x1, y1, x2, y2, stroke) {
+    const length = Math.hypot(x2 - x1, y2 - y1);
+    if (length < 1)
+        return '';
+    const ux = (x2 - x1) / length;
+    const uy = (y2 - y1) / length;
+    const size = 7;
+    const half = 3.2;
+    const baseX = x2 - ux * size;
+    const baseY = y2 - uy * size;
+    const left = n(baseX - uy * half) + ',' + n(baseY + ux * half);
+    const right = n(baseX + uy * half) + ',' + n(baseY - ux * half);
+    return '<polygon points="' + n(x2) + ',' + n(y2) + ' ' + left + ' ' + right + '" fill="' + stroke + '" />';
+}
+/** An edge label, or nothing when the edge carries no event. */
+function edgeLabel(label, x, y, colours) {
+    // Total on purpose: a malformed edge must lose its label, not the whole drawing.
+    if (typeof label !== 'string' || label === '')
+        return '';
+    return '<text x="' + n(x) + '" y="' + n(y) + '" font-size="10" fill="' + colours.muted + '">' + escape(label) + '</text>';
+}
+export function toSvg(canvas, colours, label) {
+    let dropped = 0;
+    const body = [];
+    for (const shape of canvas.shapes) {
+        const writer = writers[shape.kind];
+        if (writer === undefined) {
+            dropped += 1;
+            continue;
+        }
+        body.push(writer(shape, colours));
+    }
+    const header = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' + n(canvas.width) + ' ' + n(canvas.height) +
+        '" width="' + n(canvas.width) + '" height="' + n(canvas.height) + '" role="img"' +
+        (label === undefined ? '' : ' aria-label="' + escape(label) + '"') +
+        ' font-family="system-ui, -apple-system, Segoe UI, sans-serif">';
+    // The surface is part of the drawing, not the container's business: a page that paints its own layers - a
+    // wallpaper, a themed panel - would otherwise change the contrast of a picture it knows nothing about.
+    const background = '<rect x="0" y="0" width="' + n(canvas.width) + '" height="' + n(canvas.height) +
+        '" fill="' + colours.background + '" />';
+    return { markup: header + background + body.join('') + '</svg>', dropped };
+}

package/lib/render/viewmodel.js

@@ -0,0 +1,126 @@
+/**
+ * What a tool card shows, reduced to a drawing.
+ *
+ * The input is what the host hands a settled tool view: a phase and a block whose shape differs per phase.
+ * A settled call carries the paired call's arguments as a **lazy view** (`PartialArguments`) and the result
+ * as content blocks, so nothing here reads `block.args.model`: the view is asked, and the report text is
+ * parsed for the two facts a drawing needs. Every reader is total - an absent field removes a shape rather
+ * than throwing, because the same view renders during streaming.
+ *
+ * Pure. Everything decided here is a fact a test can assert: which nodes exist, which edges, why they are
+ * coloured the way they are.
+ */
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+const array = (value) => (Array.isArray(value) ? value : []);
+const text = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+/** The report text a settled call carries, joined: a card reads words, not blocks. */
+function reportText(content) {
+    const parts = [];
+    for (const entry of array(content)) {
+        const block = record(entry);
+        const body = text(block?.text);
+        if (body !== undefined)
+            parts.push(body);
+    }
+    return parts.join(String.fromCharCode(10));
+}
+/** Two facts out of this plugin's own report format: the verdict, and the first error it named. */
+function readReport(content) {
+    const body = reportText(content);
+    if (body === '')
+        return {};
+    const verdict = /verdict=(\w+)/.exec(body)?.[1];
+    const named = /\[error\/([A-Z0-9_]+)\]\s*(.*)/.exec(body);
+    if (named !== null)
+        return { verdict, code: named[1], message: named[2] };
+    const first = /first error:\s*([A-Z0-9_]+)/.exec(body);
+    return first === null ? { verdict } : { verdict, code: first[1] };
+}
+/**
+ * The `model` argument out of the host's lazy arguments view.
+ *
+ * A settled call exposes `value(key)`; a plain object (a test, or an older shape) is read directly. The
+ * view answers `undefined` until the field closes, which is exactly when a drawing should be attempted.
+ */
+function readModel(args) {
+    const view = record(args);
+    if (view === undefined)
+        return undefined;
+    const read = view.value;
+    if (typeof read === 'function')
+        return record(read('model'));
+    return record(view.model);
+}
+/** The states of a model: a machine, or nothing when the call carried none. */
+function machineOf(model) {
+    if (model === undefined)
+        return undefined;
+    const states = array(model.states).map(record).filter((entry) => entry !== undefined && typeof entry.id === 'string');
+    if (states.length === 0)
+        return undefined;
+    const edges = array(model.transitions)
+        .map(record)
+        .filter((entry) => entry !== undefined && typeof entry.from === 'string' && typeof entry.to === 'string')
+        .map((entry) => ({ from: String(entry.from), to: String(entry.to), label: text(entry.event) ?? '' }));
+    return {
+        nodes: states.map((state) => ({ id: String(state.id), role: 'normal' })),
+        edges,
+        ...(typeof model.init === 'string' ? { init: model.init } : {}),
+    };
+}
+/** The caption: the verdict, then the first error's code and message when the report named one. */
+function captionOf(report) {
+    const verdict = report.verdict ?? 'no report yet';
+    if (report.code === undefined)
+        return verdict;
+    const message = report.message ?? '';
+    return verdict + ' — ' + report.code + (message === '' ? '' : ': ' + message);
+}
+/**
+ * Which nodes the report blames.
+ *
+ * A finding names a state inside its message as `"x"`; matching that is a heuristic, so it only ever *adds*
+ * emphasis and never decides the verdict.
+ */
+function blame(nodes, report) {
+    if (report.message === undefined)
+        return nodes;
+    const message = report.message;
+    // Whole words only: a report does not quote the state, and a state called `do` must not match `done`.
+    const named = nodes
+        .filter((node) => {
+        const escaped = node.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp('(?<![A-Za-z0-9_])' + escaped + '(?![A-Za-z0-9_])').test(message);
+    })
+        .map((node) => node.id);
+    if (named.length === 0)
+        return nodes;
+    return nodes.map((node) => (named.includes(node.id) ? { ...node, role: 'error' } : node));
+}
+export function viewModel(input) {
+    const block = record(input.block);
+    const title = text(block?.name) ?? text(input.toolName) ?? 'tool';
+    const report = readReport(block?.content);
+    // A shape that still carries a parsed report object is read from there; it is what older callers pass.
+    const parsed = record(block?.result);
+    const findings = array(parsed?.findings).map(record);
+    const firstError = findings.find((finding) => finding?.severity === 'error');
+    const merged = {
+        verdict: text(parsed?.verdict) ?? report.verdict,
+        ...(report.code === undefined && typeof firstError?.code === 'string' ? { code: firstError.code } : { code: report.code }),
+        ...(report.message === undefined && typeof firstError?.message === 'string' ? { message: firstError.message } : { message: report.message }),
+    };
+    const caption = captionOf(merged);
+    const machine = machineOf(readModel(block?.args));
+    if (machine === undefined) {
+        return { kind: 'none', title, nodes: [], edges: [], caption };
+    }
+    return {
+        kind: 'machine',
+        title,
+        ...(machine.init === undefined ? {} : { init: machine.init }),
+        nodes: blame(machine.nodes, merged),
+        edges: machine.edges,
+        caption,
+    };
+}

package/lib/render/write.js

@@ -0,0 +1,14 @@
+/**
+ * Writing a drawing to disk: the CLI's job, kept out of the renderer.
+ *
+ * `render/index.ts` is bundled into the page as well as run in Node, so it may not import a filesystem;
+ * everything that touches one lives here, where only the host reaches it.
+ */
+import { writeFileSync } from 'node:fs';
+import { render } from './index.js';
+/** Write the drawing where a document can link to it. Returns the path, the byte count and the render. */
+export function writeSvg(input, path, overrides = {}, options = {}) {
+    const rendered = render(input, overrides, options);
+    writeFileSync(path, rendered.markup, 'utf8');
+    return { path, bytes: rendered.markup.length, rendered };
+}

package/lib/scan.js

@@ -18,6 +18,55 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { extname, relative, resolve } from 'node:path';
 import { OptionShapeError } from './option-shape.js';
+/** `tsconfig.json` allows comments and trailing commas; this reads the subset it needs without a parser. */
+function parseJsonc(text) {
+    const withoutComments = stripCComments(text);
+    const withoutTrailingCommas = withoutComments.replaceAll(/,\s*([}\]])/g, '$1');
+    try {
+        return JSON.parse(withoutTrailingCommas);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The aliases a TypeScript or JavaScript tree declares in its own `tsconfig.json`/`jsconfig.json`.
+ *
+ * Read rather than asked for: the project already states how it resolves `@/x`, and asking a caller to
+ * repeat it is how a scan silently loses half its edges.
+ */
+function readAliases(root) {
+    for (const name of ['tsconfig.json', 'jsconfig.json']) {
+        let text;
+        try {
+            text = readFileSync(resolve(root, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseJsonc(text);
+        if (typeof parsed !== 'object' || parsed === null)
+            continue;
+        const options = parsed.compilerOptions;
+        if (typeof options !== 'object' || options === null)
+            continue;
+        const compiler = options;
+        const baseUrl = typeof compiler.baseUrl === 'string' ? compiler.baseUrl.replaceAll(String.fromCharCode(92), '/').replace(/^\.\//, '') : undefined;
+        const aliases = [];
+        if (typeof compiler.paths === 'object' && compiler.paths !== null) {
+            for (const [pattern, targets] of Object.entries(compiler.paths)) {
+                if (!Array.isArray(targets))
+                    continue;
+                const cleaned = targets.filter((target) => typeof target === 'string').map((target) => (baseUrl === undefined ? target : normalise([baseUrl, target])));
+                if (cleaned.length === 0)
+                    continue;
+                aliases.push({ prefix: pattern.replace(/\*$/, ''), targets: cleaned.map((target) => target.replace(/\*$/, '')) });
+            }
+        }
+        return { aliases, ...(baseUrl === undefined ? {} : { baseUrl }) };
+    }
+    return { aliases: [] };
+}
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'out', 'coverage', '.next', '.cache', 'target', 'vendor', '__pycache__', '.venv', 'venv']);
 const LIMITS = { files: 5000, bytes: 2_000_000 };
 /** Strip comments so a commented-out include is not an edge. */
@@ -64,7 +113,14 @@ const JS_LIKE = {
     extract(text) {
         const source = stripCComments(text);
         const { local, external } = specifiers(source, [/(?:^|[^.\w])from\s*['"]([^'"]+)['"]/g, /(?:^|[^.\w])import\s*\(\s*['"]([^'"]+)['"]\s*\)/g, /(?:^|[^.\w])require\s*\(\s*['"]([^'"]+)['"]\s*\)/g, /(?:^|[^.\w])import\s*['"]([^'"]+)['"]/g]);
-        return { local, external: external.filter((name) => !name.startsWith('node:')) };
+        // `@/x`, `~/x` and `#x` are project-internal by convention: a path alias, a subpath import. Counting
+        // them as packages made a tree full of aliases look like it had one external dependency and almost no
+        // internal edges - the quietest way for a scan to be wrong.
+        const aliasShaped = (name) => name.startsWith('@/') || name.startsWith('~/') || name.startsWith('#');
+        // A call whose target is not a literal cannot be resolved from the source at all. Counting it is the
+        // honest move: the graph is missing those edges and the report says how many.
+        const dynamic = [...source.matchAll(/(?:^|[^.\w])import\s*\(\s*[^'"\s)]|(?:^|[^.\w])require\s*\(\s*[^'"\s)]/g)].length;
+        return { local: [...local, ...external.filter(aliasShaped)], external: external.filter((name) => !name.startsWith('node:') && !aliasShaped(name)), dynamic };
     },
 };
 const C_LIKE = {
@@ -418,6 +474,23 @@ function resolveSpecifier(language, fromId, specifier, index) {
     }
     if (specifier.startsWith('/'))
         return undefined;
+    if (!specifier.startsWith('.')) {
+        // A bare specifier is resolved the way the project declares it: a path alias first, then `baseUrl`.
+        // That is also the only way a bare specifier can be project-internal, so the same helper decides
+        // whether one is an edge or a package.
+        const declared = resolveDeclared(language, specifier, index);
+        if (declared !== undefined)
+            return declared;
+    }
+    // A C/C++ include that is not beside the importing file is usually found through an include directory
+    // the build already knows about, so `compile_commands.json` is read rather than asked for.
+    if (language.name === 'c' && !specifier.startsWith('.')) {
+        for (const directory of index.includeDirs) {
+            const hit = tryFiles(normalise([directory, specifier]), language.extensions, index);
+            if (hit !== undefined)
+                return hit;
+        }
+    }
     const base = joinPath(fromId, specifier);
     const extension = extname(base);
     const stem = extension === '' ? base : base.slice(0, -extension.length);
@@ -429,6 +502,149 @@ function resolveSpecifier(language, fromId, specifier, index) {
     return candidates.find((candidate) => index.files.has(candidate));
 }
 // ------------------------------------------------------------------------------------------------ scan --
+/**
+ * A bare specifier that the project itself declares: a `paths` alias, or a file under `baseUrl`.
+ *
+ * `@/lib/a` is not a package, and counting it as one dropped the edge without saying so. Returns
+ * undefined when nothing is declared for it, which leaves the caller free to treat it as external.
+ */
+function resolveDeclared(language, specifier, index) {
+    // A workspace package is the project too: `import { x } from '@acme/ui'` in a monorepo is an edge, not
+    // an external dependency. The name comes from the package's own manifest.
+    for (const [name, directory] of index.workspaces) {
+        if (specifier !== name && !specifier.startsWith(name + '/'))
+            continue;
+        const rest = specifier === name ? '' : specifier.slice(name.length + 1);
+        const hit = tryFiles(normalise([directory, rest]), language.extensions, index)
+            ?? tryFiles(normalise([directory]), language.extensions, index)
+            ?? tryFiles(normalise([directory, 'src']), language.extensions, index);
+        if (hit !== undefined)
+            return hit;
+    }
+    for (const alias of index.aliases) {
+        if (!specifier.startsWith(alias.prefix))
+            continue;
+        const rest = specifier.slice(alias.prefix.length);
+        for (const target of alias.targets) {
+            const hit = tryFiles(normalise([target + rest]), language.extensions, index);
+            if (hit !== undefined)
+                return hit;
+        }
+    }
+    if (index.baseUrl !== undefined) {
+        return tryFiles(normalise([index.baseUrl, specifier]), language.extensions, index);
+    }
+    return undefined;
+}
+/**
+ * Does this package-language specifier name something this tree owns?
+ *
+ * `com.acme.b.B` in a tree whose top level is `com/`, and `example.com/proj/pkg/b` in a module whose
+ * `go.mod` says `module example.com/proj`, are both internal: if they do not resolve, the reference is
+ * broken. `java.util.List` and `lodash` are not.
+ */
+function isInternalSpecifier(specifier, roots) {
+    const head = specifier.replaceAll('\\', '/').split(/[/.]/).filter(Boolean)[0];
+    if (head === undefined)
+        return false;
+    return roots.some((root) => root === head || specifier.startsWith(root + '/') || specifier.startsWith(root + '.'));
+}
+/** Workspace packages declared by the root manifest, so a monorepo's own names resolve inside the tree. */
+function readWorkspaces(root) {
+    const names = new Map();
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return names;
+    }
+    if (typeof manifest !== 'object' || manifest === null)
+        return names;
+    const declared = manifest.workspaces;
+    const patterns = Array.isArray(declared)
+        ? declared
+        : typeof declared === 'object' && declared !== null && Array.isArray(declared.packages)
+            ? (declared.packages)
+            : [];
+    for (const pattern of patterns) {
+        if (typeof pattern !== 'string' || pattern.includes('*'))
+            continue;
+        const directory = pattern.replace(/^\.\//, '').replace(/\/$/, '');
+        try {
+            const entry = JSON.parse(readFileSync(resolve(root, directory, 'package.json'), 'utf8'));
+            if (typeof entry.name === 'string' && entry.name !== '')
+                names.set(entry.name, directory);
+        }
+        catch {
+            continue;
+        }
+    }
+    return names;
+}
+/** `-I`/`-isystem` directories from `compile_commands.json`, kept inside the scanned tree. */
+function readIncludeDirs(root) {
+    let entries;
+    try {
+        entries = JSON.parse(readFileSync(resolve(root, 'compile_commands.json'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(entries))
+        return [];
+    const dirs = new Set();
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        const declared = typeof record.directory === 'string' ? record.directory.replaceAll(String.fromCharCode(92), '/') : '.';
+        const base = declared.startsWith('/') || /^[A-Za-z]:/.test(declared) ? declared : resolve(root, declared).replaceAll(String.fromCharCode(92), '/');
+        const args = Array.isArray(record.arguments)
+            ? record.arguments.filter((argument) => typeof argument === 'string')
+            : typeof record.command === 'string'
+                ? record.command.split(/\s+/)
+                : [];
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            let value;
+            if (argument === '-I' || argument === '-isystem')
+                value = args[index + 1];
+            else if (argument.startsWith('-I'))
+                value = argument.slice(2);
+            else if (argument.startsWith('-isystem'))
+                value = argument.slice(8);
+            if (value === undefined || value === '')
+                continue;
+            const absolute = value.startsWith('/') || /^[A-Za-z]:/.test(value) ? value : base + '/' + value;
+            const local = relative(root, absolute).replaceAll(String.fromCharCode(92), '/');
+            if (local.startsWith('..'))
+                continue;
+            dirs.add(local === '' ? '.' : local);
+        }
+    }
+    return [...dirs].sort();
+}
+/** The package roots this tree owns: `module` from `go.mod`, and the top-level names on disk. */
+function internalRootsOf(root, directories) {
+    const roots = new Set();
+    for (const directory of directories) {
+        const head = directory.split('/')[0];
+        if (head !== undefined && head !== '')
+            roots.add(head);
+    }
+    try {
+        for (const line of readFileSync(resolve(root, 'go.mod'), 'utf8').split(String.fromCharCode(10)).map((entry) => entry.trim())) {
+            const match = /^module\s+(\S+)/.exec(line);
+            if (match?.[1] !== undefined)
+                roots.add(match[1]);
+        }
+    }
+    catch {
+        // No go.mod: the top-level names are the whole set.
+    }
+    return [...roots].sort();
+}
 export function scanDependencyGraph(root) {
     if (typeof root !== 'string' || root.trim() === '') {
         throw new OptionShapeError('STRUCTURE_OPTION_INVALID', 'repoPath must be a non-empty path to a directory or a single source file.');
@@ -444,7 +660,7 @@ export function scanDependencyGraph(root) {
     }
     if (stat.isFile()) {
         const id = relative(resolve('/'), absolute).slice(1).replaceAll('\\', '/');
-        return { nodes: [id], edges: [], filesRead: 1, unresolved: [], packages: [], languages: [] };
+        return { nodes: [id], edges: [], filesRead: 1, unresolved: [], packages: [], dynamic: 0, languages: [] };
     }
     if (!stat.isDirectory()) {
         throw new OptionShapeError('STRUCTURE_OPTION_INVALID', 'repoPath must be a directory or a source file.');
@@ -494,24 +710,35 @@ export function scanDependencyGraph(root) {
     const byDotted = new Map();
     for (const directory of directories)
         byDotted.set(directory.replaceAll('/', '.'), directory);
-    const index = { files: fileSet, directories, byDotted };
+    const index = {
+        files: fileSet,
+        directories,
+        byDotted,
+        ...readAliases(absolute),
+        workspaces: readWorkspaces(absolute),
+        includeDirs: readIncludeDirs(absolute),
+        internalRoots: internalRootsOf(absolute, directories),
+    };
     const edges = [];
     const seen = new Set();
     const unresolved = [];
     const packages = new Set();
     const nodeSet = new Set();
+    let dynamic = 0;
     for (const id of files) {
         const language = languageOf(id);
-        const { local, external } = language.extract(contents.get(id) ?? '');
+        const { local, external, dynamic: dynamicHere } = language.extract(contents.get(id) ?? '');
+        dynamic += dynamicHere ?? 0;
         const nodeOf = (fileId) => (language.granularity === 'package' ? (dirOf(fileId) === '' ? '.' : dirOf(fileId)) : fileId);
         const from = nodeOf(id);
         nodeSet.add(from);
         for (const specifier of local) {
             const target = resolveSpecifier(language, id, specifier, index);
             if (target === undefined) {
-                // A package language names modules by a path this tree may not contain. That is an external
-                // dependency, not a broken reference, so it is counted rather than reported as unresolved.
-                if (language.granularity === 'package') {
+                // A package language names modules by a path this tree may or may not contain. When the path
+                // starts at a root this tree owns - the `go.mod` module, a top-level package directory - it is a
+                // broken reference and has to be reported; anything else is an external dependency.
+                if (language.granularity === 'package' && !isInternalSpecifier(specifier, index.internalRoots)) {
                     const name = specifier.split(/[/.]/).filter(Boolean)[0];
                     if (name !== undefined)
                         packages.add(name);
@@ -533,6 +760,19 @@ export function scanDependencyGraph(root) {
             edges.push({ from, to });
         }
         for (const specifier of external) {
+            const internal = language.granularity === 'file' ? resolveDeclared(language, specifier, index) : undefined;
+            if (internal !== undefined) {
+                const target = nodeOf(internal);
+                nodeSet.add(target);
+                if (target !== from) {
+                    const key = from + '' + target;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        edges.push({ from, to: target });
+                    }
+                }
+                continue;
+            }
             const name = specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split(/[/.:]/)[0];
             if (name !== undefined && name !== '')
                 packages.add(name);
@@ -543,5 +783,5 @@ export function scanDependencyGraph(root) {
         .sort((a, b) => b.files - a.files);
     edges.sort((a, b) => (a.from === b.from ? a.to.localeCompare(b.to) : a.from.localeCompare(b.to)));
     unresolved.sort();
-    return { nodes: [...nodeSet].sort(), edges, filesRead: files.length, unresolved, packages: [...packages].sort(), languages };
+    return { nodes: [...nodeSet].sort(), edges, filesRead: files.length, unresolved, packages: [...packages].sort(), dynamic, languages };
 }

package/lib/structure-tool.js

@@ -34,7 +34,7 @@ export const umlStructureTool = defineTool({
         },
         repoPath: {
             type: 'string',
-            description: 'Directory or single source file to scan instead of drawing the diagram yourself. Reads the import construct of C/C++, Python, TypeScript/JavaScript, Go, Rust, Java/Kotlin/Scala, C#, PHP, Ruby, Lua, Zig, Dart and Elixir, building a file graph for file languages and a package graph for package languages (Go, Java, C#). The graph is reviewed by the same checks; `diagram` and `diagrams` are then ignored.',
+            description: 'Directory or single source file to scan instead of drawing the diagram yourself. Reads the import construct of C/C++, Python, TypeScript/JavaScript, Go, Rust, Java/Kotlin/Scala, C#, PHP, Ruby, Lua, Zig, Dart and Elixir, building a file graph for file languages and a package graph for package languages (Go, Java, C#). Path aliases come from the project own `tsconfig.json`/`jsconfig.json` (`baseUrl` and `paths`), a monorepo package name from the root `package.json` workspaces, and C include directories from `compile_commands.json`. A project-internal specifier that resolves to nothing is listed as unresolved rather than counted as an external package, and an import whose target is computed at run time is counted rather than guessed. The graph is reviewed by the same checks; `diagram` and `diagrams` are then ignored.',
         },
         matrix: {
             type: 'json',
@@ -105,7 +105,7 @@ export const umlStructureTool = defineTool({
                 return reviewStructure({
                     diagram: '',
                     graph,
-                    scan: { files: scanned.filesRead, unresolved: scanned.unresolved.length, packages: scanned.packages.length, languages: scanned.languages.map((entry) => entry.language) },
+                    scan: { files: scanned.filesRead, unresolved: scanned.unresolved.length, packages: scanned.packages.length, dynamic: scanned.dynamic, languages: scanned.languages.map((entry) => entry.language) },
                     ...(args.matrix === undefined ? {} : { matrix: args.matrix }),
                 });
             }