dsh-model-everything 0.4.1 → 0.5.1

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/wrap.js

@@ -0,0 +1,87 @@
+/**
+ * Wrapping: turning one endless column into a page.
+ *
+ * A chain of twelve boxes has twelve layers, and layering alone draws it as a single column taller than anything a
+ * reader can take in - a strip, not a drawing. Graphviz and ELK both answer this with a wrapping pass: cut the layer
+ * sequence into bands and stand the bands side by side, so reading order becomes "down the page, then the next
+ * column", the way text wraps.
+ *
+ * The cut is chosen, not guessed: each candidate number of bands is scored by how close the packed page gets to the
+ * aspect ratio a page and a landscape screen share, and the best one wins. A drawing that is already close to that
+ * shape is left alone - wrapping exists for the strip, not for every tall drawing.
+ *
+ * Pure: layer sizes in, band ranges and offsets out. The caller applies them.
+ */
+/** The aspect ratio a page and a landscape screen share. */
+const PAGE_ASPECT = 1.6;
+/** A drawing shorter than this many layers is read better stacked, whatever its proportions. */
+const MIN_LAYERS_TO_WRAP = 4;
+/** A drawing that is not this tall relative to its width is not a strip. */
+const STRIP_RATIO = 2;
+/** The height of a run of layers with the gap between them. */
+function runHeight(layerHeight, first, last, gap) {
+    let total = 0;
+    for (let index = first; index <= last; index += 1) {
+        total += layerHeight[index];
+        if (index < last)
+            total += gap;
+    }
+    return total;
+}
+/** The width of a run of layers: the widest layer sets it. */
+function runWidth(layerWidth, first, last) {
+    let widest = 0;
+    for (let index = first; index <= last; index += 1)
+        widest = Math.max(widest, layerWidth[index]);
+    return widest;
+}
+/** How far the packed page is from the target shape, in log space so half and double count the same. */
+function shapeError(width, height, aspect) {
+    if (width <= 0 || height <= 0)
+        return Infinity;
+    const ratio = Math.max(width, height) / Math.min(width, height);
+    return Math.abs(Math.log(ratio / aspect));
+}
+export function planBands(layerWidth, layerHeight, gap, aspect = PAGE_ASPECT) {
+    const count = layerWidth.length;
+    if (count === 0)
+        return { bands: [], width: 0, height: 0 };
+    const single = {
+        bands: [{ first: 0, last: count - 1, offsetX: 0 }],
+        width: runWidth(layerWidth, 0, count - 1),
+        height: runHeight(layerHeight, 0, count - 1, gap),
+    };
+    if (count < MIN_LAYERS_TO_WRAP || single.height <= single.width * STRIP_RATIO)
+        return single;
+    const columnGap = gap * 2;
+    let best = single;
+    let bestError = shapeError(single.width, single.height, aspect);
+    for (let bands = 2; bands < count; bands += 1) {
+        const base = Math.floor(count / bands);
+        const extra = count % bands;
+        const ranges = [];
+        let cursor = 0;
+        for (let band = 0; band < bands; band += 1) {
+            const size = base + (band < extra ? 1 : 0);
+            ranges.push({ first: cursor, last: cursor + size - 1 });
+            cursor += size;
+        }
+        let width = columnGap * (bands - 1);
+        let height = 0;
+        for (const range of ranges) {
+            width += runWidth(layerWidth, range.first, range.last);
+            height = Math.max(height, runHeight(layerHeight, range.first, range.last, gap));
+        }
+        if (shapeError(width, height, aspect) >= bestError)
+            continue;
+        const planned = [];
+        let offsetX = 0;
+        for (const range of ranges) {
+            planned.push({ first: range.first, last: range.last, offsetX });
+            offsetX += runWidth(layerWidth, range.first, range.last) + columnGap;
+        }
+        best = { bands: planned, width, height };
+        bestError = shapeError(width, height, aspect);
+    }
+    return best;
+}

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 }),
                 });
             }

package/lib/types/client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The Client half: a lazy factory the page binds to this package's name.
+ *
+ * Everything that decides anything lives in `render/`; this file only turns shapes into React elements and
+ * registers them where the page offers a seat. Two seats are used, and they fail independently:
+ *
+ * - `tool.call.toolview` replaces the card of a tool whose result this package can draw;
+ * - `sidebar.right.pane.tab` is the whiteboard: a tab that renders whatever the reader pastes, with no tool
+ *   and no host data at all, so it keeps working when the card seat does not.
+ *
+ * This module is not a page script: it exports the factory, and `scripts/build-client.mjs` wraps the
+ * compiled output in `window.__ModuleLoader__.load(...)`, which is the loader contract itself.
+ */
+import { type Palette, type PaletteMode } from './render/palette.js';
+export interface ReactLike {
+    createElement: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+    useState?: <T>(initial: T) => [T, (next: T) => void];
+}
+export interface SlotContext {
+    slots: {
+        inject: (slot: string, callback: () => unknown) => unknown;
+        register: (options: Record<string, unknown>, component: unknown) => unknown;
+    };
+    get?: (service: string) => unknown;
+}
+export interface PluginShape {
+    inject: string[];
+    apply: (ctx: SlotContext) => void;
+    /** The whiteboard mount, with its scheduler injectable. `apply` calls this with the default. */
+    mount: (ctx: SlotContext, options?: MountOptions) => unknown;
+}
+/** A settled tool call, as the host hands it to a view. */
+export interface ToolCallProps {
+    phase?: string;
+    toolName?: string;
+    block?: {
+        args?: unknown;
+        result?: unknown;
+    };
+}
+/** Tool names this package answers. A key that never dispatches simply never renders. */
+export declare const TOOL_NAMES: string[];
+/**
+ * Which surface the page is painting the drawing on.
+ *
+ * The host publishes its palette as private CSS variables, so naming them here would break on the next theme.
+ * The one fact that cannot drift is the rendered background: read it, and fall back to the media query, then
+ * to light. Never throws - a view that cannot read the document still draws.
+ */
+export declare function themeMode(): PaletteMode;
+/** The whiteboard's seat key, in both the tab registry and the body slot. */
+export declare const WHITEBOARD_ID = "model-everything-diagram";
+/** What the whiteboard opens with: a diagram the reader can edit rather than an empty box. */
+export declare const WHITEBOARD_SAMPLE: string;
+/**
+ * The view for one tool name.
+ *
+ * The drawing is emitted as markup, so React receives it through `dangerouslySetInnerHTML`. That is safe
+ * only because the writer escapes every value that came from a report or a model, which the render suite
+ * pins with an injection case.
+ */
+export declare function viewFor(React: ReactLike, overrides?: Partial<Palette>): (props: ToolCallProps) => unknown;
+/**
+ * The whiteboard: paste a diagram, get a drawing, zoom it.
+ *
+ * It holds no host data, which is the point: it is a place to think about a diagram while writing one, and
+ * it cannot be broken by a change to any tool's result shape. The source it draws is whatever is in its own
+ * box.
+ */
+export declare function whiteboardFor(React: ReactLike, overrides?: Partial<Palette>): () => unknown;
+export interface MountOptions {
+    /** Injected so the suite can drive the poll without waiting. Defaults to `setTimeout`. */
+    schedule?: (run: () => void, delay: number) => unknown;
+}
+/**
+ * Register the whiteboard tab once the sidebar's optional services are ready.
+ *
+ * The slot can be declared before `sidebarRightTabs` exists - the host composes services and seats in an
+ * order this plugin does not control - and a single `ctx.get` there is a race that loses the tab silently.
+ * So it polls, like the reference implementation does, and stops after a bounded number of attempts.
+ */
+export declare function mountWhiteboard(React: ReactLike, ctx: SlotContext, options?: MountOptions): unknown;
+export default function factory(require: (name: string) => unknown): PluginShape;

package/lib/types/diagram-diff-tool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The structural diff tool: two drawings, compared by containment.
+ *
+ * One job per file: this module declares the tool and nothing else, so the documentation generator that walks
+ * `*-tool` modules finds it, and so a change to the drawing never touches the reviewing.
+ */
+export declare const DIAGRAM_DIFF_TOOL_NAME = "diagram_diff";
+export declare const diagramDiffTool: import("@deepseek-ai/dsh-tools").ToolDefinition;