import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import pc from 'picocolors';
import { AnalyzeError } from '../../analyzer/errors.js';
import {
fileOfSymbol,
filesOfTarget,
impactOf,
importPath,
resolveTarget,
routeFor,
symbolRef,
targetLabel,
targetLocation,
testsFor,
usesOf,
whoOf,
type ImpactResult,
type QueryTarget,
type ResolveResult,
type RouteMatch,
type UseSite,
} from '../../shared/query.js';
import type { ReportData } from '../../shared/types.js';
import { getReport } from '../engine.js';
import { ago, capped, createLinker, plural, renderTree, type Linker, type TreeNode } from '../format.js';
import {
ANALYSIS_OPTIONS,
analysisOptions,
explicitRoot,
isTTY,
parseCommandArgs,
Progress,
resolveProjectRoot,
STAGE_LABELS,
UsageError,
type AnalysisValues,
type Command,
type CommandContext,
type ProjectLocation,
} from '../shared.js';
/*
* Terminal answers to everyday reachability questions: `who`, `uses`, `impact`, `path`, `route` and
* `tests-for`. All of them read one analysis (a running `serve`, the warm cache, or a cold run) and
* answer through src/shared/query.ts, the same functions the MCP server and the report UI use.
*/
const COMMON_HELP = `${pc.bold('Common options')}
--root
Project root (default: the nearest folder with a package.json, or
the root of the workspace monorepo it belongs to)
--json Machine-readable output
-e, --exclude Exclude files (gitignore syntax)
--no-git Skip git history
--no-cache Analyze from scratch: skip the warm cache and a running server
-q, --quiet No progress output
-h, --help Show this help
${pc.bold('Targets')}
A file (src/cart/Cart.tsx, or a unique suffix such as Cart.tsx), a symbol (useCart,
CartService.checkout, src/cart/index.ts#useCart), a folder (src/cart/) or a route
('GET /api/cart/:id', or a concrete URL like 'GET /api/cart/42'). Paths may be relative to
the current folder or to the git root. Typos get suggestions.
file:line links open your editor (set CODE_VISUALIZER_EDITOR=cursor|zed|webstorm|none
or a URL template; NO_HYPERLINKS=1 prints plain text).`;
const WHO_HELP = `
${pc.bold('Usage')}
$ code-visualizer who [options]
Who knows this code: CODEOWNERS owners, the people who changed it (recent work
counts more), when they last touched it, and the bus factor.
${pc.bold('Options')}
--limit Number of people to list (default: 5)
${COMMON_HELP}
${pc.bold('Examples')}
$ npx code-visualizer who src/billing/
$ npx code-visualizer who useCart
$ npx code-visualizer who 'GET /api/orders/:id'
`;
const USES_HELP = `
${pc.bold('Usage')}
$ code-visualizer uses [options]
Every place that uses a symbol or file: imports (with the imported names and
line), exact call / render / new sites with the calling function, type references,
and HTTP requests when the target handles a route. Alias: refs.
${pc.bold('Options')}
--limit Files to list in text output (default: 50)
${COMMON_HELP}
${pc.bold('Examples')}
$ npx code-visualizer uses formatPrice
$ npx code-visualizer refs src/cart/CartService.ts#CartService.checkout --json
`;
const IMPACT_HELP = `
${pc.bold('Usage')}
$ code-visualizer impact [options]
What a change to these files, symbols, folders or routes affects: the direct users
(with exact lines), everything that depends on them by distance, routes and pages,
the tests to run (with the command) and the code owners to notify. For a symbol
only its importers and callers count, not the importers of its neighbours.
${pc.bold('Options')}
--depth Import levels to list (default: 3; the rest is counted)
${COMMON_HELP}
${pc.bold('Examples')}
$ npx code-visualizer impact formatDate
$ npx code-visualizer impact src/lib/auth.ts src/lib/session.ts --depth 5
`;
const PATH_HELP = `
${pc.bold('Usage')}
$ code-visualizer path [options]
Why does depend on ? The shortest import chain, with the line and the
imported names of every hop. Symbols stand for their files.
${COMMON_HELP}
${pc.bold('Examples')}
$ npx code-visualizer path src/pages/Checkout.tsx src/db/client.ts
$ npx code-visualizer path CheckoutPage prisma
`;
const ROUTE_HELP = `
${pc.bold('Usage')}
$ code-visualizer route [METHOD] [options]
Which code serves a URL: the matching route, its handler (file:line), middleware,
the code in the project that calls it, and the tests that reach it. Without a
method, every method (and pages) match.
${COMMON_HELP}
${pc.bold('Examples')}
$ npx code-visualizer route GET /api/users/42
$ npx code-visualizer route /checkout
`;
const TESTS_FOR_HELP = `
${pc.bold('Usage')}
$ code-visualizer tests-for [options]
The test files that exercise these files, folders or symbols (through imports, or
HTTP requests for routes), a command that runs exactly those, and the given files
that no test reaches. A symbol stands for its file here; "impact " lists
only the tests that reach the symbol's users.
${COMMON_HELP}
${pc.bold('Examples')}
$ npx code-visualizer tests-for src/cart/
$ npx code-visualizer tests-for $(git diff --name-only) --json
`;
type Values = AnalysisValues & { root?: string; json?: boolean; limit?: string; help?: boolean };
interface QuerySpec {
name: string;
help: string;
minArgs: number;
maxArgs?: number;
/** Command-specific flags. */
options?: Record;
/** A usage problem with the arguments, found before the (slower) analysis. */
validate?(args: string[]): string | undefined;
answer(ctx: QueryContext): number;
}
interface QueryContext {
data: ReportData;
root: string;
values: Values;
args: string[];
out: (line?: string) => void;
err: (line?: string) => void;
json: (value: unknown) => void;
link: Linker;
}
export type { ProjectLocation };
/**
* The project a query run from `cwd` (which may be a sub-folder) is about — the same rule every command
* uses (`resolveProjectRoot` in src/cli/shared.ts): the nearest package.json (or code-visualizer
* configuration), widened to the workspace monorepo it belongs to, else the git root. Undefined outside
* any project.
*/
export function findProjectRoot(cwd: string, home = os.homedir()): ProjectLocation | undefined {
const resolved = resolveProjectRoot(cwd, undefined, home);
return resolved.fallback ? undefined : { root: resolved.root, gitRoot: resolved.gitRoot };
}
const ROUTE_ARG = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|ALL|PAGE)\s/i;
/**
* Turn a filesystem path argument into a project-relative id. Paths are tried relative to the working
* directory, then to the git root (`$(git diff --name-only)` from a sub-folder), then to the project
* root. A trailing `/` (a folder) is kept.
*/
export function toProjectPath(location: ProjectLocation, raw: string, cwd = process.cwd()): string {
if (ROUTE_ARG.test(raw)) return raw;
const hash = raw.indexOf('#');
const pathPart = hash > 0 ? raw.slice(0, hash) : raw;
const rest = hash > 0 ? raw.slice(hash) : '';
if (!(pathPart.includes('/') || pathPart.includes(path.sep) || pathPart.includes('.'))) return raw;
const slash = /[\\/]$/.test(pathPart) && pathPart.length > 1 ? '/' : '';
const bases = [cwd, location.gitRoot, location.root].filter((b): b is string => !!b);
for (const base of path.isAbsolute(pathPart) ? [cwd] : bases) {
const abs = path.resolve(base, pathPart);
if (!fs.existsSync(abs)) continue;
const rel = path.relative(location.root, abs);
if (rel.startsWith('..') || path.isAbsolute(rel)) continue;
return `${rel.split(path.sep).join('/')}${rel && slash}${rest}`;
}
return raw;
}
/** `cviz impact … | head`: stop quietly when the reader of the output goes away. */
const PIPE_GUARDED = new WeakSet();
export function exitOnBrokenPipe(stream: NodeJS.WriteStream): void {
if (PIPE_GUARDED.has(stream) || typeof stream.on !== 'function') return;
PIPE_GUARDED.add(stream);
stream.on('error', (error: NodeJS.ErrnoException) => {
if (error.code !== 'EPIPE') throw error;
process.exit(process.exitCode ?? 0);
});
}
async function runQuery(spec: QuerySpec, { argv, stdout, stderr }: CommandContext): Promise {
let parsed;
try {
parsed = parseCommandArgs(spec.name, argv, { ...ANALYSIS_OPTIONS, json: { type: 'boolean' }, ...(spec.options ?? {}) });
} catch (error) {
stderr.write(`${pc.red('✖')} ${(error as Error).message}\n`);
return 2;
}
const values = parsed.values as Values;
const args = spec.name === 'route' ? parsed.positionals : joinRouteArgs(parsed.positionals);
if (values.help) {
stdout.write(spec.help);
return 0;
}
const usage = (reason: string): number => {
stderr.write(`${pc.red('✖')} ${reason}\n${spec.help}`);
return 2;
};
if (args.length < spec.minArgs) return usage(`${spec.name} needs ${spec.minArgs === 1 ? 'a target' : `${spec.minArgs} targets`}.`);
if (spec.maxArgs !== undefined && args.length > spec.maxArgs) return usage(`${spec.name} takes at most ${plural(spec.maxArgs, 'argument')} (got ${args.length}: ${args.join(' ')}). Quote targets that contain spaces.`);
if (values.depth !== undefined && !spec.options?.depth) return usage(`--depth is an option of impact only.`);
const invalid = spec.validate?.(args);
if (invalid) return usage(invalid);
// The positionals are targets here: the root comes from --root or the folder the query runs in.
const resolved = resolveProjectRoot(process.cwd(), explicitRoot(values, []));
if (resolved.fallback) {
stderr.write(`${pc.red('✖')} Not inside a project (no package.json or git repository here or above). cd into one, or pass --root .\n`);
return 2;
}
const location: ProjectLocation = { root: resolved.root, gitRoot: resolved.gitRoot };
const { root } = location;
exitOnBrokenPipe(stdout);
let options;
try {
// `--depth` is impact's own flag here (the analysis depth only applies to --file reports).
options = analysisOptions({ ...values, root, depth: undefined }, []);
} catch (error) {
if (error instanceof UsageError) {
stderr.write(`${pc.red('✖')} ${error.message}\n`);
return 2;
}
throw error;
}
const progress = new Progress(stderr, isTTY(stderr) && !values.quiet && !values.json);
let data: ReportData;
try {
data = await getReport({ ...options, includeSource: false, history: false, changes: false, onProgress: (stage) => progress.update(STAGE_LABELS[stage]) });
} catch (error) {
progress.stop();
if (error instanceof AnalyzeError) {
stderr.write(`${pc.red('✖')} ${error.message}\n`);
return 1;
}
throw error;
} finally {
progress.stop();
}
const ctx: QueryContext = {
data,
root,
values,
// Route arguments are URLs, not paths (`/app/x` must not become a project file).
args: spec.name === 'route' ? args : args.map((a) => toProjectPath(location, a)),
out: (line = '') => stdout.write(`${line}\n`),
err: (line = '') => stderr.write(`${line}\n`),
json: (value) => stdout.write(`${JSON.stringify(value, null, 2)}\n`),
link: createLinker({ root, stream: stdout }),
};
try {
return spec.answer(ctx);
} catch (error) {
if (error instanceof UsageError) {
ctx.err(`${pc.red('✖')} ${error.message}`);
return 2;
}
throw error;
}
}
/** A query command: its descriptor plus how it answers. */
function queryCommand(meta: Pick, spec: Omit): Command {
return { ...meta, run: (c) => runQuery({ name: meta.name, ...spec }, c) };
}
const METHOD_RE = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|ALL|PAGE)$/i;
/** `GET /api/users/42` typed without quotes arrives as two arguments: keep it one target. */
function joinRouteArgs(args: string[]): string[] {
const out: string[] = [];
for (let i = 0; i < args.length; i++) {
const next = args[i + 1];
if (METHOD_RE.test(args[i]) && next !== undefined && /^(\/|https?:\/\/)/.test(next)) {
out.push(`${args[i].toUpperCase()} ${next}`);
i++;
} else out.push(args[i]);
}
return out;
}
function positiveInt(value: string | undefined, fallback: number, name: string): number {
if (value === undefined) return fallback;
const n = Number(value);
if (!Number.isInteger(n) || n < 1) throw new UsageError(`${name} must be a positive whole number.`);
return n;
}
/** Resolve a target, or explain what was not found (and suggest alternatives) on stderr. */
function resolveQuiet(ctx: QueryContext, input: string): ResolveResult & { input: string } {
const r = resolveTarget(ctx.data, input);
if (r.target && r.alternatives?.length && !ctx.values.json && !ctx.values.quiet) {
ctx.err(pc.dim(` "${input}" also names ${r.alternatives.slice(0, 3).map((id) => id.replace('#', ' › ')).join(', ')}${r.alternatives.length > 3 ? ', …' : ''} — pass path#Name to pick one`));
}
return { ...r, input };
}
/** "Nothing matches" on stderr, with "did you mean" suggestions. */
function explainMissing(ctx: QueryContext, r: { input: string; suggestions: string[] }, warn = false): void {
const mark = warn ? pc.yellow('!') : pc.red('✖');
ctx.err(`${mark} Nothing in ${path.basename(ctx.root)} matches "${r.input}" (files, symbols, folders and routes were searched).`);
if (r.suggestions.length) ctx.err(` Did you mean: ${r.suggestions.map((s) => pc.cyan(s)).join(', ')}?`);
}
/** One JSON error for every input that matched nothing. */
function jsonMissing(ctx: QueryContext, missing: { input: string; suggestions: string[] }[]): void {
if (missing.length === 1) ctx.json({ error: 'not-found', input: missing[0].input, suggestions: missing[0].suggestions });
else ctx.json({ error: 'not-found', inputs: missing.map(({ input, suggestions }) => ({ input, suggestions })) });
}
/** Resolve the one target of a command, or explain (exit 1). */
function resolveOrExplain(ctx: QueryContext, input: string): { target: QueryTarget; alternatives?: string[] } | undefined {
const r = resolveQuiet(ctx, input);
if (r.target) return { target: r.target, alternatives: r.alternatives };
if (ctx.values.json) jsonMissing(ctx, [r]);
explainMissing(ctx, r);
return undefined;
}
/** `formatDate src/utils/format.ts:11` */
function heading(ctx: QueryContext, target: QueryTarget): string {
const label = targetLabel(ctx.data, target);
const loc = targetLocation(ctx.data, target);
if (target.type === 'file' || target.type === 'dir' || !loc.file) return pc.bold(label);
return `${pc.bold(label)} ${pc.dim(ctx.link(loc.file, loc.line))}`;
}
/** `alternatives` (other symbols with the same name) for the JSON answer, when the name was ambiguous. */
const withAlternatives = (alternatives: string[] | undefined): { alternatives?: string[] } => (alternatives?.length ? { alternatives } : {});
/* ----------------------------------- who ----------------------------------- */
function answerWho(ctx: QueryContext): number {
const limit = positiveInt(ctx.values.limit, 5, '--limit');
const resolved = resolveOrExplain(ctx, ctx.args[0]);
if (!resolved) return 1;
const { target } = resolved;
const result = whoOf(ctx.data, target, { limit });
if (ctx.values.json) {
ctx.json({ label: targetLabel(ctx.data, target), ...withAlternatives(resolved.alternatives), ...result });
return 0;
}
ctx.out();
ctx.out(` Who knows ${heading(ctx, target)}${result.files > 1 ? pc.dim(` (${plural(result.files, 'file')})`) : ''}`);
ctx.out();
ctx.out(` ${pc.dim('Owners ')} ${result.owners.length ? result.owners.join(', ') : pc.dim('no CODEOWNERS entry')}`);
if (!result.hasHistory) {
ctx.out(` ${pc.dim('Experts ')} ${pc.dim(ctx.data.git ? 'no commits touch these files yet' : 'no git history (run inside a git repository, without --no-git)')}`);
ctx.out();
return 0;
}
ctx.out(` ${pc.dim('Experts')}`);
const nameWidth = Math.min(28, Math.max(...result.experts.map((e) => e.name.length + (e.me ? 6 : 0))));
const idleDays = (e: { last: number }): number => Math.floor((Date.now() - e.last) / 86_400_000);
for (const e of result.experts) {
const filled = Math.max(1, Math.round(e.share * 10));
const bar = pc.magenta('█'.repeat(filled)) + pc.dim('░'.repeat(10 - filled));
const name = `${e.name}${e.me ? ' (you)' : ''}`.padEnd(nameWidth);
const idle = e.inactive ? ` ${pc.yellow(`inactive ${idleDays(e)}d`)}` : '';
ctx.out(` ${name} ${bar} ${String(Math.round(e.share * 100)).padStart(3)}% ${pc.dim(`${plural(e.commits, 'commit')} · last ${ago(e.last)}`)}${idle}`);
}
if (result.busFactor !== undefined) {
const [top] = result.experts;
let note: string;
if (result.busFactor > 1) note = pc.dim(`${result.busFactor} people made most of the changes (recent work counts more)`);
else if (result.experts.length === 1) note = pc.yellow(`only ${top.name} has changed this code${top.inactive ? ` (inactive ${idleDays(top)}d)` : ''}`);
else note = pc.yellow(`${top.name} made most of the changes (recent work counts more)`);
ctx.out(` ${pc.dim('Bus factor')} ${result.busFactor} ${note}`);
}
const lc = result.lastCommit;
if (lc) {
const subject = lc.subject.length > 72 ? `${lc.subject.slice(0, 71)}…` : lc.subject;
ctx.out(` ${pc.dim('Last touch')} ${ago(lc.date)} by ${lc.author} — ${subject} ${pc.dim(`(${lc.hash.slice(0, 7)}, ${ctx.link(lc.file)})`)}`);
}
ctx.out();
return 0;
}
export const whoCommand = queryCommand(
{ name: 'who', summary: 'Who knows this code: owners, experts, last touch, bus factor' },
{ help: WHO_HELP, minArgs: 1, maxArgs: 1, options: { limit: { type: 'string' } }, answer: answerWho },
);
/* ----------------------------------- uses ---------------------------------- */
const SITE_WORDS: Record = { import: 'import', reexport: 're-export', call: 'call', render: 'render', new: 'new', http: 'HTTP' };
const symbolLabel = (ctx: QueryContext, id: string): string => symbolRef(ctx.data, id)?.label ?? id.slice(id.indexOf('#') + 1);
/** What happens at a use site: `call in Checkout (2 args)`, `import { a, b }`, `GET /api/x in load`. */
function siteWhat(ctx: QueryContext, s: UseSite, targetId?: string): string {
const where = s.symbol ? ` in ${pc.cyan(symbolLabel(ctx, s.symbol))}` : '';
if (s.kind === 'import' || s.kind === 'reexport') {
const named = (s.names ?? []).filter((n) => n !== '*' && n !== 'default');
const parts = [s.names?.includes('default') ? 'default' : '', named.length ? `{ ${named.join(', ')} }` : ''].filter(Boolean);
const what = parts.length ? pc.cyan(parts.join(', ')) : pc.cyan('*') + pc.dim(' (the whole module)');
return `${SITE_WORDS[s.kind]} ${what}${s.typeOnly ? pc.dim(' (type)') : ''}${s.via ? pc.dim(` via ${s.via}`) : ''}`;
}
if (s.kind === 'http') return `${pc.bold(s.method ?? '')} ${s.url ?? ''}${where}`;
const args = s.argc !== undefined && s.kind !== 'render' ? pc.dim(s.argc < 0 ? ' (spread args)' : ` (${plural(s.argc, 'arg')})`) : '';
// For a file or class target, name the symbol that is used.
const which = s.target && s.target !== targetId && s.target.includes('#') ? pc.dim(` → ${symbolLabel(ctx, s.target)}`) : '';
return `${SITE_WORDS[s.kind]}${where}${args}${which}`;
}
function siteText(ctx: QueryContext, s: UseSite, targetId?: string): string {
return `${ctx.link(s.file, s.line, `:${s.line}`)} ${siteWhat(ctx, s, targetId)}`;
}
function answerUses(ctx: QueryContext): number {
const limit = positiveInt(ctx.values.limit, 50, '--limit');
const resolved = resolveOrExplain(ctx, ctx.args[0]);
if (!resolved) return 1;
const { target } = resolved;
const result = usesOf(ctx.data, target);
if (ctx.values.json) {
ctx.json({ label: targetLabel(ctx.data, target), ...withAlternatives(resolved.alternatives), ...result });
return 0;
}
const status = result.files
? `used in ${plural(result.files, 'file')}`
: result.through.length
? 'no direct use found (calls on instances or values passed around are not tracked)'
: 'not used by other analyzed code';
ctx.out();
ctx.out(` ${heading(ctx, target)} ${pc.dim(status)}`);
ctx.out();
const byFile = new Map();
const add = (file: string, node: TreeNode): void => {
const list = byFile.get(file);
if (list) list.push(node);
else byFile.set(file, [node]);
};
const all = [...result.imports, ...result.sites, ...result.http].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
for (const s of all) add(s.file, { label: siteText(ctx, s, target.id) });
// Type and inheritance references: one row per referencing symbol, with what it references.
const refRows = new Map }>();
for (const r of result.refs) {
const kind = r.kind === 'uses' ? 'type reference' : r.kind;
const key = `${r.symbol}\0${kind}`;
const row = refRows.get(key) ?? { file: r.file, kind, symbol: r.symbol, targets: new Set() };
row.targets.add(symbolLabel(ctx, r.target));
refRows.set(key, row);
}
for (const row of refRows.values()) {
const what = target.type === 'symbol' && row.targets.size === 1 && row.targets.has(targetLabel(ctx.data, target)) ? '' : ` → ${[...row.targets].slice(0, 6).join(', ')}${row.targets.size > 6 ? ', …' : ''}`;
add(row.file, { label: `${row.kind} in ${pc.cyan(symbolLabel(ctx, row.symbol))}${pc.dim(what)}` });
}
const files = [...byFile.keys()].sort();
for (const line of capped(files, limit, (f) => [` ${pc.bold(ctx.link(f))}`, ...renderTree(byFile.get(f)!, ' ')].join('\n'))) ctx.out(line);
if (files.length) ctx.out();
if (result.through.length) {
ctx.out(` ${pc.dim(`Reached through other exports (${plural(new Set(result.through.map((s) => s.file)).size, 'file')}):`)}`);
for (const line of capped(result.through, 15, (s) => ` ${ctx.link(s.file, s.line)} ${pc.dim(siteWhat(ctx, s))}`, ' ')) ctx.out(line);
ctx.out();
}
return 0;
}
export const usesCommand = queryCommand(
{ name: 'uses', aliases: ['refs'], summary: 'Where a symbol or file is used: imports, exact call sites, HTTP callers' },
{ help: USES_HELP, minArgs: 1, maxArgs: 1, options: { limit: { type: 'string' } }, answer: answerUses },
);
/* ---------------------------------- impact --------------------------------- */
function printDirect(ctx: QueryContext, result: ImpactResult, files: string[], targetId: string | undefined): void {
const byFile = new Map(result.direct.map((d) => [d.file, d]));
const nodes = files.map((f) => {
const d = byFile.get(f);
const via = d?.via.length ? ` ${pc.cyan(d.via.slice(0, 4).join(', '))}${d.via.length > 4 ? pc.dim(` +${d.via.length - 4}`) : ''}` : '';
const children = (d?.sites ?? [])
.filter((s) => s.kind !== 'import' && s.kind !== 'reexport')
.slice(0, 8)
.map((s) => ({ label: siteText(ctx, s, targetId) }));
return { label: `${ctx.link(f)}${via}`, children };
});
for (const line of capped(nodes, 40, (n) => [` ${n.label}`, ...renderTree(n.children, ' ')].join('\n'), ' ')) ctx.out(line);
}
/** `src/a.ts`, or `formatDate (src/utils/format.ts)` for a symbol id. */
function untestedLabel(ctx: QueryContext, id: string): string {
if (!id.includes('#')) return ctx.link(id);
const ref = symbolRef(ctx.data, id);
return `${ref?.label ?? id.slice(id.indexOf('#') + 1)} ${pc.dim(`(${ctx.link(fileOfSymbol(id), ref?.line)})`)}`;
}
function printImpactExtras(ctx: QueryContext, result: ImpactResult): void {
if (result.routes.length) {
ctx.out(` ${pc.bold('Routes and pages')} ${pc.dim(`(${result.routes.length})`)}`);
for (const line of capped(result.routes, 20, (r) => ` ${r.label} ${pc.dim(ctx.link(r.file, r.line))}`, ' ')) ctx.out(line);
ctx.out();
}
ctx.out(` ${pc.bold('Tests')} ${pc.dim(`(${result.tests.files.length})`)}`);
if (!result.tests.files.length) ctx.out(` ${pc.dim('No test reaches this code or its users.')}`);
for (const line of capped(result.tests.files, 15, (f) => ` ${ctx.link(f)}`, ' ')) ctx.out(line);
if (result.tests.command) ctx.out(` ${pc.dim('$')} ${result.tests.command}`);
if (result.tests.untested.length) ctx.out(` ${pc.yellow('no test reaches:')} ${result.tests.untested.map((u) => untestedLabel(ctx, u)).join(', ')}`);
if (result.owners.length) {
ctx.out();
ctx.out(` ${pc.bold('Owners to notify')}`);
for (const o of result.owners.slice(0, 8)) ctx.out(` ${o.owner} ${pc.dim(plural(o.files.length, 'file'))}`);
}
}
function answerImpact(ctx: QueryContext): number {
const depth = positiveInt(ctx.values.depth, 3, '--depth');
// Unknown inputs (a file deleted in the diff, a typo) are reported; the others are still answered.
const resolved = ctx.args.map((input) => resolveQuiet(ctx, input));
const targets = resolved.flatMap((r) => (r.target ? [r.target] : []));
const missing = resolved.filter((r) => !r.target);
if (!targets.length) {
if (ctx.values.json) jsonMissing(ctx, missing);
for (const m of missing) explainMissing(ctx, m);
return 1;
}
const result = impactOf(ctx.data, targets, { depth });
const alternatives = resolved.flatMap((r) => (r.target ? (r.alternatives ?? []) : []));
if (ctx.values.json) {
const unknown = missing.length ? { unknown: missing.map(({ input, suggestions }) => ({ input, suggestions })) } : {};
ctx.json({ labels: targets.map((t) => targetLabel(ctx.data, t)), ...withAlternatives(alternatives), ...unknown, ...result });
return 0;
}
for (const m of missing) explainMissing(ctx, m, true);
const precision = result.precision === 'symbol' ? pc.green('symbol-precise') : pc.yellow(`file-level${result.precisionNote ? ` — ${result.precisionNote}` : ''}`);
ctx.out();
ctx.out(` Impact of ${targets.map((t) => heading(ctx, t)).join(pc.dim(', '))}`);
ctx.out(` ${pc.dim(`${plural(result.total + (result.truncated ?? 0), 'affected file')} ·`)} ${precision}`);
ctx.out();
if (!result.byDepth.length) ctx.out(` ${pc.dim('Nothing else in the project depends on it.')}`);
for (const level of result.byDepth) {
ctx.out(` ${pc.bold(level.depth === 1 ? 'Direct' : `Depth ${level.depth}`)} ${pc.dim(`(${plural(level.files.length, 'file')})`)}`);
if (level.depth === 1) printDirect(ctx, result, level.files, targets.length === 1 ? targets[0].id : undefined);
else for (const line of capped(level.files, 30, (f) => ` ${ctx.link(f)}`, ' ')) ctx.out(line);
}
if (result.truncated) ctx.out(` ${pc.dim(`+${plural(result.truncated, 'more file')} beyond depth ${depth} (--depth ${depth + 3} lists more)`)}`);
ctx.out();
printImpactExtras(ctx, result);
ctx.out();
return 0;
}
export const impactCommand = queryCommand(
{ name: 'impact', summary: 'What a change affects: users by depth, routes, tests to run, owners' },
{ help: IMPACT_HELP, minArgs: 1, options: { depth: { type: 'string' } }, answer: answerImpact },
);
/* ----------------------------------- path ---------------------------------- */
/** The file a target stands for in an import chain (a symbol's or route handler's file). */
function fileForPath(ctx: QueryContext, target: QueryTarget): string | undefined {
if (target.type === 'file') return target.id;
if (target.type === 'symbol') return fileOfSymbol(target.id);
if (target.type === 'route') {
const files = filesOfTarget(ctx.data, target);
return files[files.length - 1];
}
return undefined;
}
function answerPath(ctx: QueryContext): number {
const ends = ctx.args.slice(0, 2).map((input) => resolveQuiet(ctx, input));
const missing = ends.filter((r) => !r.target);
if (missing.length) {
// One answer for both ends, so --json stays a single document.
if (ctx.values.json) jsonMissing(ctx, missing);
for (const m of missing) explainMissing(ctx, m);
return 1;
}
const [fromT, toT] = ends.map((r) => r.target!);
const from = fileForPath(ctx, fromT);
const to = fileForPath(ctx, toT);
if (!from || !to) throw new UsageError('path needs files, symbols or routes (a folder has no single import chain).');
const forward = importPath(ctx.data, from, to);
const back = forward ? undefined : importPath(ctx.data, to, from);
const result = forward ?? (back ? { ...back, reversed: true } : undefined);
if (ctx.values.json) {
ctx.json({ from, to, found: !!result, ...withAlternatives(ends.flatMap((r) => r.alternatives ?? [])), ...(result ?? { hops: [] }) });
return result ? 0 : 1;
}
if (!result) {
ctx.err(`${pc.yellow('!')} No import chain connects ${from} and ${to} (in either direction).`);
return 1;
}
const end = result.reversed ? from : to;
ctx.out();
if (result.reversed) ctx.out(` ${pc.yellow('!')} ${from} does not import ${to} — but the other way round:`);
ctx.out(` ${pc.bold(result.reversed ? to : from)} → ${pc.bold(end)} ${pc.dim(plural(result.hops.length, 'hop'))}`);
ctx.out();
for (const hop of result.hops) {
const names = hop.names.length ? pc.cyan(hop.names.slice(0, 5).join(', ') + (hop.names.length > 5 ? ', …' : '')) : pc.dim(hop.kind ?? 'import');
ctx.out(` ${ctx.link(hop.source, hop.line)} ${names}${hop.typeOnly ? pc.dim(' (type)') : ''}${hop.kind && hop.kind !== 'import' ? pc.dim(` ${hop.kind}`) : ''}`);
ctx.out(` ${pc.dim('↓')}`);
}
ctx.out(` ${ctx.link(end)}`);
ctx.out();
return 0;
}
export const pathCommand = queryCommand(
{ name: 'path', summary: 'Why A depends on B: the shortest import chain, line by line' },
{ help: PATH_HELP, minArgs: 2, maxArgs: 2, answer: answerPath },
);
/* ---------------------------------- route ---------------------------------- */
function printRoute(ctx: QueryContext, m: RouteMatch): void {
const handler = m.handler;
const name = handler?.symbol ? ` ${pc.cyan(symbolRef(ctx.data, handler.symbol)?.label ?? '')}` : '';
ctx.out(` ${pc.bold(m.label)}${m.exact ? '' : pc.dim(' (base-URL match)')} ${pc.dim(m.route.framework)}`);
if (handler) ctx.out(` ${pc.dim('Handler ')} ${ctx.link(handler.file, handler.line)}${name}`);
if (m.route.file !== handler?.file || (m.route.line && m.route.line !== handler?.line)) ctx.out(` ${pc.dim('Registered')} ${ctx.link(m.route.file, m.route.line)}`);
const app = (a: RouteMatch['appMiddlewares'][number]): string => `${a.label} ${pc.dim(`(${ctx.link(a.file, a.line)})`)}`;
// App-level middleware first (it runs before the route's own), error handlers apart: they run only on failure.
const chain = [...m.appMiddlewares.filter((a) => !a.onError).map(app), ...m.middlewares];
if (chain.length) ctx.out(` ${pc.dim('Middleware')} ${chain.join(pc.dim(' → '))}`);
const onError = m.appMiddlewares.filter((a) => a.onError);
if (onError.length) ctx.out(` ${pc.dim('On error ')} ${onError.map(app).join(pc.dim(', '))}`);
ctx.out(` ${pc.dim('Callers ')} ${m.callers.length ? pc.dim(`(${m.callers.length})`) : pc.dim('none in this project')}`);
for (const line of capped(m.callers, 10, (s) => ` ${ctx.link(s.file, s.line)} ${siteWhat(ctx, s)}`, ' ')) ctx.out(line);
ctx.out(` ${pc.dim('Tests ')} ${m.tests.length ? m.tests.map((t) => ctx.link(t)).join(', ') : pc.yellow('none reach the handler')}`);
ctx.out();
}
/** `route GET /x`, `route 'GET /x'` or `route /x`: the method (if any) and the URL words. */
function routeWords(args: string[]): { method?: string; rest: string[] } {
const words = args.join(' ').trim().split(/\s+/).filter(Boolean);
const method = METHOD_RE.test(words[0] ?? '') ? words[0].toUpperCase() : undefined;
return { method, rest: method ? words.slice(1) : words };
}
function validateRoute(args: string[]): string | undefined {
const { method, rest } = routeWords(args);
if (!rest.length) return `route needs a URL, e.g. "route ${method ?? 'GET'} /api/users/42".`;
if (rest.length > 1) return `route takes one URL, got ${rest.length}: ${rest.join(' ')}.`;
return undefined;
}
function answerRoute(ctx: QueryContext): number {
const { method, rest } = routeWords(ctx.args);
const url = rest[0];
const matches = routeFor(ctx.data, method, url);
if (ctx.values.json) {
ctx.json({ method: method ?? null, url, matches });
return matches.length ? 0 : 1;
}
if (!matches.length) {
const other = method ? routeFor(ctx.data, undefined, url) : [];
ctx.err(`${pc.red('✖')} No route serves ${method ? `${method} ` : ''}${url}.`);
if (other.length) ctx.err(` Other methods match: ${other.map((m) => pc.cyan(m.label)).join(', ')}`);
else if (ctx.data.routes.length) ctx.err(pc.dim(` ${plural(ctx.data.routes.length, 'route')} known — run "code-visualizer report" and open Routes to browse them.`));
return 1;
}
ctx.out();
for (const m of matches.slice(0, 5)) printRoute(ctx, m);
if (matches.length > 5) ctx.out(pc.dim(` +${matches.length - 5} more (use --json)`));
return 0;
}
export const routeCommand = queryCommand(
{ name: 'route', summary: 'Which handler serves a URL: route, middleware, callers, tests' },
{ help: ROUTE_HELP, minArgs: 1, maxArgs: 2, validate: validateRoute, answer: answerRoute },
);
/* -------------------------------- tests-for -------------------------------- */
function answerTestsFor(ctx: QueryContext): number {
const result = testsFor(ctx.data, ctx.args);
const found = result.byPath.length > 0;
if (ctx.values.json) {
ctx.json(result);
return found ? 0 : 1;
}
for (const u of result.unknown) {
const s = resolveTarget(ctx.data, u).suggestions;
ctx.err(`${pc.yellow('!')} "${u}" is not an analyzed file, folder or symbol${s.length ? ` — did you mean ${s.slice(0, 3).map((x) => pc.cyan(x)).join(', ')}?` : '.'}`);
}
if (!found) return 1;
ctx.out();
ctx.out(` ${pc.bold(plural(result.files.length, 'test'))} ${pc.dim(`for ${plural(result.byPath.length, 'path')}`)}`);
for (const line of capped(result.files, 40, (f) => ` ${ctx.link(f)}`, ' ')) ctx.out(line);
if (result.command) ctx.out(` ${pc.dim('$')} ${result.command}`);
else if (result.files.length) ctx.out(` ${pc.dim('(no test runner detected in package.json)')}`);
if (result.untested.length) {
ctx.out();
ctx.out(` ${pc.yellow('No test reaches')} ${pc.dim(`(${result.untested.length})`)}`);
for (const line of capped(result.untested, 20, (f) => ` ${ctx.link(f)}`, ' ')) ctx.out(line);
}
if (ctx.args.some((a) => resolveTarget(ctx.data, a).target?.type === 'symbol')) {
ctx.out();
ctx.out(pc.dim(' Symbols stand for their files here; "impact " lists the tests that reach its users.'));
}
ctx.out();
return 0;
}
export const testsForCommand = queryCommand(
{ name: 'tests-for', summary: 'Tests to run for files, folders or symbols (with the command)' },
{ help: TESTS_FOR_HELP, minArgs: 1, answer: answerTestsFor },
);