Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
// Copyright 2026 Ix Infrastructure Inc.
import { type Command } from "commander";
import chalk from "chalk";
import { createClient } from "../../client/factory.js";
import { clearMapBaseline, clearMapResultCache } from "../config.js";
import { roundFloat, printJson } from "../format.js";
import { llmLine, llmError, llmShortId } from "../llm.js";
import { bootstrap, resolveWorkspaceId } from "../bootstrap.js";
import { configParseError, formatFetchError, renderStructuredError } from "../errors.js";
import { ingestFiles, type IngestFilesSummary } from "./ingest.js";
import { detectSystem } from "../system.js";
import { getRemoteRunner, isCloudReady } from "../remote.js";
import { acquireMapLock, requestMapRerun, takeMapRerun } from "../single-flight.js";
import { canRenderProgress } from "../stderr.js";
import { loadIngestBaseline } from "../ingest-baseline.js";
import { saveMapBaseline } from "../map-baseline.js";
import { loadCachedMap, loadLastMap, resolveMapCacheSlot, saveCachedMap } from "../map-result-cache.js";
import { clearMapStale, markMapStale, mapStaleNotice, readMapStale, type MapStaleState } from "../map-freshness.js";
import { resolveMapRoot } from "../map-root.js";
import { readBackendHealth } from "./upgrade.js";
import { renderWarning } from "../ui.js";
import type { IxClient } from "../../client/api.js";
// Hard wall-clock budget for a single `ix map`. Past this, the shared deadline
// signal aborts every in-flight request and the command exits, so a single
// invocation can never grind for hours against an unhealthy backend. Tunable
// via IX_MAP_DEADLINE_MS; 0 disables the budget.
const DEFAULT_MAP_DEADLINE_MS = 15 * 60 * 1000;
/** The map budget in ms, or undefined when disabled. */
export function mapDeadlineMs(raw = process.env.IX_MAP_DEADLINE_MS): number | undefined {
if (raw === undefined) return DEFAULT_MAP_DEADLINE_MS;
const trimmed = raw.trim();
// Matched, not parsed: `parseInt("15m")` is 15, a 15 ms budget that aborted
// every request of every map. A value that is not a plain number of ms keeps
// the default; empty and 0 keep disabling it, as they did.
if (trimmed !== "" && !/^\d+$/.test(trimmed)) return DEFAULT_MAP_DEADLINE_MS;
const budget = Number.parseInt(trimmed, 10);
if (!Number.isFinite(budget) || budget <= 0) return undefined; // disabled
return budget;
}
export function mapDeadlineSignal(): AbortSignal | undefined {
const budget = mapDeadlineMs();
return budget === undefined ? undefined : AbortSignal.timeout(budget);
}
// Whether an automatically-triggered map should be skipped. Background refresh
// (the editor/agent hooks that re-map on change) is a local-only convenience:
// against a remote backend it would push a write on every change from every
// client, so it is skipped there and remote ingestion stays deliberate. Manual
// `ix map` never sets IX_AUTO_MAP, so it is never skipped. IX_AUTO_MAP_CLOUD=1
// opts the automatic path back in for users who do want remote auto-refresh.
export function shouldSkipAutoMap(opts: { auto: boolean; cloudReady: boolean }): boolean {
if (!opts.auto || !opts.cloudReady) return false;
if (process.env.IX_AUTO_MAP_CLOUD === "1") return false;
return true;
}
/** Optional exit code for callers that must distinguish coalescing from success. */
export function requestedMapCoalesceExitCode(
raw = process.env.IX_MAP_COALESCE_EXIT_CODE,
): number | undefined {
if (raw === undefined) return undefined;
const code = Number(raw);
return Number.isInteger(code) && code >= 1 && code <= 255 ? code : undefined;
}
export function applyRequestedMapCoalesceExitCode(
raw = process.env.IX_MAP_COALESCE_EXIT_CODE,
apply: (code: number) => void = code => { process.exitCode = code; },
): boolean {
const code = requestedMapCoalesceExitCode(raw);
if (code === undefined) return false;
apply(code);
return true;
}
/**
* Whether an automatic `ix map` (IX_AUTO_MAP=1) computes the map even after an
* incremental edit, as it did before CL-13. IX_MAP_EAGER=1 restores that for
* a hook that reads regions straight from `ix map` and cannot run a region
* view to refresh them. An `ix map` run by hand always computes.
*/
export function mapEager(raw = process.env.IX_MAP_EAGER): boolean {
return raw === "1";
}
/**
* The `/v1/map` request for `cwd`: workspace-scoped, or system-scoped when it
* is part of a multi-repo system. Shared by `ix map` and `ensureFreshMap`, so a
* lazily recomputed map asks for exactly what `ix map` would.
*
* A co-ingest system is found locally (`detectSystem`); a SEPARATELY-ingested
* repo that the stitcher joined into a system (Path-2 grouping, Ix#225 Half B)
* has no local marker, so its system_id is looked up from the backend, making
* `ix map <repo>` show the whole stitched system. That lookup is best-effort:
* an unanswered one leaves the map at workspace scope.
*/
export async function resolveMapScope(
client: Pick<IxClient, "workspaceSystem">,
cwd: string,
full: boolean | undefined,
systemId: string | undefined = detectSystem(cwd)?.systemId,
): Promise<{ full?: boolean; workspaceId?: string; systemId?: string }> {
let effectiveSystemId = systemId;
if (!effectiveSystemId) {
const ws = resolveWorkspaceId(cwd);
if (ws) {
const looked = await client.workspaceSystem(ws).catch(() => ({ systemId: null }));
if (looked.systemId) effectiveSystemId = looked.systemId;
}
}
return { full, workspaceId: effectiveSystemId ? undefined : resolveWorkspaceId(cwd), systemId: effectiveSystemId };
}
/** Watch opts into full patches; ordinary `ix map` keeps its topology-only ingest. */
export function mapModeForIngest(raw = process.env.IX_MAP_FULL_INGEST): boolean {
return raw !== "1";
}
export interface MapRegion {
id: string;
label: string;
label_kind: string;
level: number;
file_count: number;
child_region_count: number;
parent_id: string | null;
cohesion: number;
external_coupling: number;
boundary_ratio: number;
confidence: number;
crosscut_score: number;
dominant_signals: string[];
interface_node_count: number;
children?: MapRegion[];
}
interface MapPreflight {
cost: {
file_count: number;
directory_count: number;
directory_quadratic: number;
symbol_estimate: number;
edge_estimate: number;
};
capacity: {
cpu_cores: number;
heap_max_bytes: number;
heap_free_bytes: number;
container_memory: number | null;
disk_free_bytes: number | null;
};
risk: string;
mode: string;
warnings: string[];
duration_ms: number;
}
interface MapPersistence {
region_nodes: number;
file_edges: number;
region_edges: number;
delete_ops: number;
total_ops: number;
}
export interface MapResult {
file_count: number;
region_count: number;
levels: number;
map_rev: number;
regions: MapRegion[];
hierarchy: MapRegion[];
outcome?: string;
preflight?: MapPreflight;
persistence?: MapPersistence;
}
/**
* The fields of a `/v1/map` response that `ix map` reads -- all a reused
* response stores (see `map-result-cache.ts`), so the output of a map served
* from it cannot depend on anything it left out.
*/
export type MapView = Pick<MapResult, "file_count" | "region_count" | "levels" | "map_rev" | "regions" | "outcome">;
/**
* The backend's MapOutcome labels that mean "a map was produced" (MapTypes.scala).
*
* The other two it can send — `local_map_too_large` and `local_map_not_recommended`
* — are guardrail refusals that legitimately carry no regions, so they are left
* out: an empty response is the expected shape there, not a contradiction.
*
* `coupling_unchanged` belongs in this set even though it sounds like a skip.
* The backend answers it with the cached map from the last build's revision
* (`map.copy(outcome = CouplingUnchanged)`), not an empty delta — so an empty
* one is a real empty hierarchy being served from cache, which is exactly the
* state worth catching on a retry.
*/
const COMPLETED_MAP_OUTCOMES = new Set([
"full_local_completed",
"fast_local_completed",
"incremental_completed",
"coupling_unchanged",
]);
/**
* A completed map cannot legitimately contain no files immediately after a
* clean ingest found supported source files. Treat that contradiction as a
* failure instead of telling hooks and agents that an empty hierarchy is
* current.
*/
export function describeEmptyCompletedMap(
result: Pick<MapResult, "file_count" | "region_count" | "regions" | "outcome">,
ingest:
| Pick<
IngestFilesSummary,
"filesDiscovered" | "patchesApplied" | "idempotentPatches" | "filesSkippedAsUnchanged" | "parseErrors" | "commitErrors"
>
| undefined,
): string | undefined {
if (!ingest || ingest.filesDiscovered <= 0 || ingest.parseErrors > 0 || ingest.commitErrors > 0) {
return undefined;
}
if (!result.outcome || !COMPLETED_MAP_OUTCOMES.has(result.outcome)) return undefined;
if (result.file_count !== 0 || result.region_count !== 0 || result.regions.length !== 0) return undefined;
const sourceFiles = ingest.filesDiscovered;
const patches = ingest.patchesApplied;
const files = `${sourceFiles} supported source ${sourceFiles === 1 ? "file" : "files"}`;
const patchWord = patches === 1 ? "patch" : "patches";
const tail = "The source ingest baseline was preserved, so the next 'ix map' can reuse unchanged files.";
// The backend deduplicated every commit, so this run wrote nothing at all —
// and the two sentences below are then both false: nothing was ingested, and
// the language had no chance to be the reason (#527). The observed cause is a
// graph deleted out from under the backend's own patch records: a scoped
// reset used to remove a workspace's nodes and patches while leaving its
// idempotency keys, so the identical re-ingest was accepted as a replay and
// committed nothing (Ix-memory#174). Those keys expire after 24h, which is
// why waiting is a real workaround and worth saying out loud.
// `filesSkippedAsUnchanged === 0` is load-bearing, not a belt-and-braces extra.
// `idempotentPatches >= patches` only says every patch this run *submitted*
// was a replay; it says nothing about the files the run never submitted, and
// those are what disprove the diagnosis. A workspace on a language the
// backend cannot build a hierarchy for skips its 99 clean files, and one
// reverted file whose content was ingested before commits as `Idempotent` —
// giving patches === 1, idempotentPatches === 1, file_count === 0 with a
// graph that is not empty, and a 24-hour wait that changes nothing here. That
// graph is not intact either: the revert was never applied, so it still
// shows the file's content in between. The ingest reports that one itself,
// as `replayedChanges` (F-01).
// A real #527 run skips nothing: the DB-reset guard clears the mtime cache
// and the hash lookup comes back empty, so every file is re-submitted.
if (patches > 0 && ingest.idempotentPatches >= patches && ingest.filesSkippedAsUnchanged === 0) {
return `Backend reported ${result.outcome}, but mapped 0 files after local ingest found ${files}. The backend answered every one of the ${patches} committed ${patchWord} with 'already applied', so this run wrote nothing — the graph is empty because the commits were deduplicated against patch records the backend still holds, not because the source could not be parsed. That is what a workspace whose graph was deleted without its patch records looks like; the records expire within 24 hours, or an upgraded backend clears them with the reset. ${tail}`;
}
return `Backend reported ${result.outcome}, but mapped 0 files after local ingest found ${files} (${patches} ${patchWord} committed). The source graph was ingested, but no architecture hierarchy was created. The active backend may not map this source language yet. ${tail}`;
}
/**
* A completed response that counted files but produced no regions is not a
* hierarchy either. #524: a two-file mixed PHP/JSON workspace maps
* `full_local_completed` with `file_count: 1` and `region_count: 0`, and the
* one class it did count then reports `hasMapData: false`.
*
* The signal is the absent region set, deliberately NOT a coverage ratio of
* mapped files to discovered files. `filesDiscovered` counts every supported
* extension — .md, .json, .yaml, .css — while a hierarchy only ever covers
* files the backend can couple, so a healthy map routinely covers a small
* minority of them: #534 records 381 files of ~7,400 on a real PHP workspace.
* Any ratio threshold rejects that map on every run, and a rejection clears
* the completion marker, so the workspace could never record one again.
*/
export function describeRegionlessCompletedMap(
result: Pick<MapResult, "file_count" | "region_count" | "regions" | "outcome">,
ingest: Pick<IngestFilesSummary, "filesDiscovered" | "patchesApplied" | "parseErrors" | "commitErrors"> | undefined,
): string | undefined {
if (!ingest || ingest.filesDiscovered < 2 || ingest.parseErrors > 0 || ingest.commitErrors > 0) {
return undefined;
}
if (!result.outcome || !COMPLETED_MAP_OUTCOMES.has(result.outcome)) return undefined;
// file_count 0 is the empty-map case above, which has its own diagnosis.
if (result.file_count <= 0) return undefined;
if (result.region_count !== 0 || result.regions.length !== 0) return undefined;
const sourceFiles = ingest.filesDiscovered;
const patches = ingest.patchesApplied;
return `Backend reported ${result.outcome}, but produced 0 regions while mapping ${result.file_count} of ${sourceFiles} supported source files after a clean local ingest (${patches} ${patches === 1 ? "patch" : "patches"} committed). The source graph was ingested, but no architecture hierarchy was created for it. The source ingest baseline was preserved, so the next 'ix map' can reuse unchanged files.`;
}
/**
* Report files the local ingest could not turn into a patch.
*
* `ingestFiles` counts these into `parseErrors` and writes a `[patch build
* error]` line per file, but `ix map` runs it in a silent/machine format on
* every path that matters, so the count is the only surviving signal — and
* until #554 nothing read it. Both completed-map sanity checks above
* deliberately bail out when `parseErrors > 0`, which left a partial map as
* the one failure mode `ix map` never mentioned.
*
* Deliberately not phrased as "the map is incomplete": the same run goes on to
* persist a completed map baseline, so `ix doctor` answers "Completed map for
* this workspace" right after this line prints. That is correct — a file the
* parser cannot handle is normal and must not turn doctor red for ever (#530,
* #536) — so the warning states what is missing rather than contradicting the
* health signal beside it.
*
* Exported for tests; returns the message rather than writing it so the
* formatting is assertable without capturing stderr.
*/
export function describeDroppedFiles(
ingest: Pick<IngestFilesSummary, "parseErrors" | "commitErrors"> | undefined,
): string | undefined {
if (!ingest) return undefined;
const parse = ingest.parseErrors;
const commit = ingest.commitErrors;
if (parse <= 0 && commit <= 0) return undefined;
const parts: string[] = [];
if (parse > 0) parts.push(`${parse} ${parse === 1 ? "file" : "files"} failed to build a patch`);
if (commit > 0) parts.push(`${commit} ${commit === 1 ? "patch" : "patches"} failed to commit`);
return `${parts.join(" and ")} — those files are absent from the graph. Re-run with 'ix ingest' to see the per-file errors.`;
}
function emitDroppedFileWarning(
ingest: Pick<IngestFilesSummary, "parseErrors" | "commitErrors" | "filesTooLarge"> | undefined,
silent: boolean,
): void {
const message = describeDroppedFiles(ingest);
if (message) process.stderr.write(chalk.yellow(` ${message}\n`));
// Not under --silent: an oversized file is counted on every run, not only
// the one that first met it, so a line here would turn the hook surface's
// one summary line into two on every map of such a repo. `silentSummaryLine`
// carries the count as a token instead.
if (silent) return;
const tooLarge = describeTooLargeFiles(ingest);
if (tooLarge) process.stderr.write(chalk.dim(` ${tooLarge}\n`));
}
/**
* The one stderr line `ix map --silent` prints. `too_large=N` appears only
* when files were left out for size, and `map=stale` only when the map was
* deferred after an edit (CL-13), both after every other token, so a repo
* without either keeps the line it always had. Exported for tests.
*/
export function silentSummaryLine(s: {
files: number; systems: number; subsystems: number; modules: number; mapMs: number;
stitch: string; filesTooLarge?: number; mapStale?: boolean;
}): string {
const tooLarge = (s.filesTooLarge ?? 0) > 0 ? ` · too_large=${s.filesTooLarge}` : "";
const stale = s.mapStale ? " · map=stale" : "";
return `map: ${s.files} files · ${s.systems}s/${s.subsystems}ss/${s.modules}m regions · ${s.mapMs}ms${s.stitch}${tooLarge}${stale}\n`;
}
/**
* Files over the 1 MB parse limit are left out of the map. `ix ingest` lists
* them in its summary; `ix map` said nothing, so a large generated or vendored
* file was simply absent from the graph with no hint why.
*/
export function describeTooLargeFiles(
ingest: Pick<IngestFilesSummary, "filesTooLarge"> | undefined,
): string | undefined {
const n = ingest?.filesTooLarge ?? 0;
if (n <= 0) return undefined;
return `${n} file${n === 1 ? "" : "s"} over 1 MB ${n === 1 ? "was" : "were"} not mapped.`;
}
/**
* A completed map with no usable hierarchy invalidates the architecture
* completion baseline. Keeping it would make `ix status` report
* mapCompleted=true for a hierarchy that does not exist. The next run may
* hash-skip unchanged files, so detection is based on discovered supported
* sources rather than only newly committed patches.
*
* Both rejections clear only the architecture marker: the source ingest that
* produced the graph was clean, and clearing its baseline too is what forced a
* full reparse on every retry (#534).
*/
export function invalidateBaselineForIncompleteCompletedMap(
result: Pick<MapResult, "file_count" | "region_count" | "regions" | "outcome">,
ingest:
| Pick<
IngestFilesSummary,
"filesDiscovered" | "patchesApplied" | "idempotentPatches" | "filesSkippedAsUnchanged" | "parseErrors" | "commitErrors"
>
| undefined,
projectRoot: string,
invalidate: (root: string) => void = clearMapBaseline,
): string | undefined {
const message = describeEmptyCompletedMap(result, ingest)
?? describeRegionlessCompletedMap(result, ingest);
if (message) invalidate(projectRoot);
return message;
}
/**
* Persist hierarchy completion only when a non-empty map was actually produced.
*
* "Non-empty" is the whole result, deliberately not the region count alone. A
* single-file workspace maps `1 files · 0s/0ss/0m regions` and that is
* finished, not partial — there is no hierarchy to build over one file, and no
* later `ix map` will produce one. Refusing to record it leaves `ix status`
* reading map_complete=false and `ix doctor` unhealthy for ever, with the
* suggested fix being the command that just ran.
*
* The regionless-with-real-source case is already rejected upstream by
* `describeRegionlessCompletedMap`, which returns before this is reached, and
* which knows the discovered-file count this function does not.
*/
export function persistCompletedMapBaseline(
result: Pick<MapResult, "file_count" | "region_count" | "regions" | "outcome">,
projectRoot: string,
): boolean {
if (result.outcome && !COMPLETED_MAP_OUTCOMES.has(result.outcome)) return false;
if (result.file_count === 0 && result.region_count === 0 && result.regions.length === 0) return false;
const sourceBaseline = loadIngestBaseline(projectRoot);
if (!sourceBaseline) return false;
return saveMapBaseline(projectRoot, sourceBaseline.currentRev);
}
type MapSortMode = "importance" | "confidence" | "size" | "alpha";
export interface MapTextRenderOptions {
level?: string;
minConfidence: string;
maxItems: string;
allItems?: boolean;
sort: string;
graph?: boolean;
list?: boolean;
verbose?: boolean;
}
export function registerMapCommand(program: Command): void {
program
.command("map [path]")
.description("Map the architectural hierarchy of a codebase")
.option("--format <fmt>", "Output format (text|json|llm|silent)", "text")
.option("--level <n>", "Show only regions at this level (1=finest, higher=coarser)")
.option("--min-confidence <n>", "Only show regions above this confidence threshold (0-1)", "0")
.option("--max-items <n>", "Max items to show per section in text output (default: 10)", "10")
.option("--all-items", "Show all items in each section (overrides --max-items)")
.option("--sort <mode>", "Sort mode for text output (importance|confidence|size|alpha)", "importance")
.option("--graph", "Render the hierarchy as a graph/tree view (default)")
.option("--list", "Render the ranked list view instead of the default graph/tree view")
.option("--full", "Force full local map, bypassing automatic safety limits (advanced/testing)")
.option("--remap", "Compute the map now, even from an automatic (hook) run that would defer it")
.option("--verbose", "Show raw confidence/crosscut scores and signals, plus per-file ingest diagnostics (including why a patch failed to commit)")
.option("--silent", "Suppress all output except a one-line summary (useful for LLM hooks)")
.addHelpText(
"after",
`
Runs Louvain community detection on the weighted file coupling graph to infer
a multi-level architectural hierarchy. Persists results to the graph as Region
nodes with IN_REGION edges (top-down: system → subsystem → module → file → symbol).
Levels:
1 = module (fine-grained, ~5-20 files)
2 = subsystem (mid-level, ~20-100 files)
3 = system (top-level architectural regions)
Advanced:
--full Override automatic local safety limits and force the full local map
path. Bypasses automatic downgrade to fast mode and the persistence
safety guardrail. Intended for testing and performance diagnosis.
--silent Skip the full map rendering. Prints one summary line to stderr and
exits. Ideal for LLM hooks and automated workflows where the full
output would waste context tokens.
--remap Compute the map now, even from an automatic run. An \`ix map\`
you run computes the map (and clears a stale one). The automatic
\`ix map\` the editor/agent hooks run after an edit (they set
IX_AUTO_MAP=1) ingests it and defers the map itself: it prints the
last map's regions marked stale (map=stale), and the next region
view (overview, subsystems, locate, impact, explain, view) answers
from them and starts a background refresh. IX_MAP_EAGER=1 makes
automatic runs compute too, as before; IX_MAP_BACKGROUND_REFRESH=0
stops region views starting one.
Examples:
ix map .
ix map --format json
ix map --silent
ix map --remap
ix map --level 2
ix map --min-confidence 0.5
ix map --max-items 10
ix map --sort confidence
ix map --graph
ix map --list
ix map --all-items
ix map . --full
ix map . --full --verbose`
)
.action(async (pathArg: string | undefined, opts: { format: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; list?: boolean; full?: boolean; remap?: boolean; verbose?: boolean; silent?: boolean }) => {
const held: HeldMap = {};
try {
await runMapCommand(pathArg, opts, held);
} finally {
if (held.root) await rerunIfRequested(held.root, held.local === true, opts);
}
});
}
/**
* What a deferred `ix map` (CL-13) adds to its output. `mapStale` says the
* map was not recomputed for this ingest; `regionsAsOf` names the last
* computed map that `file_count`, the regions, `region_count`, `levels`,
* `map_rev` and `outcome` all come from. Shared with the region readers, in
* `map-freshness.ts`, with `mapStaleNotice`; both still exported from here.
*/
export { mapStaleNotice, type MapStaleState };
/** `ix map --format json`. Exported for tests. */
export function mapJsonPayload(
result: MapView,
regions: MapRegion[],
localIngest: Pick<
IngestFilesSummary,
"parseErrors" | "commitErrors" | "stitchSkipped" | "stitchSkippedRule" | "filesTooLarge" | "filesTooLargePaths"
> | undefined,
state: MapStaleState = {},
): Record<string, unknown> {
return {
file_count: result.file_count,
region_count: regions.length,
levels: result.levels,
map_rev: result.map_rev,
outcome: result.outcome,
// CL-13. True when this run deferred the map after an edit: every field
// above and the regions below are the last computed map's, not this
// ingest's, until a region view or `ix map --remap` refreshes them.
// `regions_as_of` names that map ({map_rev, file_count}) and is null when
// the map is fresh. Both always present, like their siblings.
map_stale: state.mapStale === true,
regions_as_of: state.mapStale === true && state.regionsAsOf ? { ...state.regionsAsOf } : null,
// Always present so a consumer can branch on them without a key check.
// A dropped file is silent otherwise: the backend still answers with a
// completed outcome, so `outcome` alone cannot distinguish a whole map
// from one missing every file that failed to build a patch (#554).
parse_errors: localIngest?.parseErrors ?? 0,
commit_errors: localIngest?.commitErrors ?? 0,
// Ix#568. The whole reason this is reported at all is hooks that run
// `ix map` and read the machine output; leaving it only in
// `ix ingest --format json` puts it where those hooks never look.
// `?? null`, not left undefined: JSON.stringify drops an undefined
// value, so a consumer could not tell the field apart from an older
// CLI that never emitted it. Its siblings are always present too.
stitch_skipped: localIngest?.stitchSkipped ?? null,
stitch_skipped_rule: localIngest?.stitchSkippedRule ?? null,
// Files over the 1 MB parse limit, left out of the graph, and up to 20
// of their paths (the count is the whole number). On stderr and in the
// --silent line already; here for the consumers that read this payload.
// Always present, like their siblings.
files_too_large: localIngest?.filesTooLarge ?? 0,
files_too_large_paths: localIngest?.filesTooLargePaths ?? [],
regions: regions.map((r: any) => ({
label: r.label,
level: r.level,
files: r.file_count,
cohesion: roundFloat(r.cohesion),
coupling: roundFloat(r.external_coupling),
confidence: roundFloat(r.confidence),
signals: r.dominant_signals,
})),
};
}
/** Flat one-record-per-line region listing with explicit parent= for the llm format. */
export function renderMapLlm(
result: MapView,
regions: MapRegion[],
ingest?: Pick<
IngestFilesSummary,
"parseErrors" | "commitErrors" | "stitchSkipped" | "stitchSkippedRule" | "filesTooLarge" | "filesTooLargePaths"
>,
state: MapStaleState = {},
): void {
console.log(llmLine("map", [
["files", result.file_count],
["regions", regions.length],
["levels", result.levels],
["rev", result.map_rev],
["outcome", result.outcome],
// CL-13: the map was deferred after an edit, so the record and the region
// rows are the last computed map's; regions_as_of_rev/_files name that
// map. Only when stale, per the zero-drop rule.
["map_stale", state.mapStale ? true : undefined],
["regions_as_of_rev", state.mapStale ? state.regionsAsOf?.map_rev : undefined],
["regions_as_of_files", state.mapStale ? state.regionsAsOf?.file_count : undefined],
// The same signal the json payload carries as parse_errors/commit_errors.
// Agents are told to pass --format llm unconditionally, so leaving it out
// of this record hid the dropped files from the one consumer #554 is about.
// Emitted only when non-zero, per the format's rule that zeros carrying no
// signal are dropped (docs/llm-format.md); a clean ingest says nothing.
["parse_errors", ingest?.parseErrors ? ingest.parseErrors : undefined],
["commit_errors", ingest?.commitErrors ? ingest.commitErrors : undefined],
// Ix#568. `--format llm` and `--silent` are what the hooks this field was
// added for actually read; shipping it only in `--format json` put it
// where they never look.
["stitch_skipped", ingest?.stitchSkipped],
["stitch_skipped_rule", ingest?.stitchSkippedRule],
// Files over the 1 MB parse limit, left out of the graph. Only when there
// are some; the `too_large` rows after this name up to 20 of them.
["files_too_large", ingest?.filesTooLarge ? ingest.filesTooLarge : undefined],
]));
// Its own record too, right after the `map` record: a reader skimming the
// records must not take the last map's counts for this edit's.
if (state.mapStale) console.log(llmLine("diagnostic", [["code", "map_stale"], ["message", mapStaleNotice(state)]]));
for (const path of ingest?.filesTooLarge ? ingest.filesTooLargePaths ?? [] : []) {
console.log(llmLine("too_large", [["path", path]]));
}
for (const r of regions) {
console.log(llmLine("region", [
["id", llmShortId(r.id)],
["kind", r.label_kind],
["label", r.label],
["level", r.level],
["files", r.file_count],
["parent", llmShortId(r.parent_id)],
["children", r.child_region_count > 0 ? r.child_region_count : undefined],
["cohesion", roundFloat(r.cohesion)],
["coupling", roundFloat(r.external_coupling)],
// crosscut_score is emitted only when meaningful (>0.01), matching the
// compact JSON; consumers (e.g. the ix-architecture skill) gate on it.
["crosscut", r.crosscut_score > 0.01 ? roundFloat(r.crosscut_score) : undefined],
["confidence", roundFloat(r.confidence)],
["signals", r.dominant_signals.length > 0 ? r.dominant_signals.join(",") : undefined],
]));
}
}
export function renderMapText(result: MapView, cwd: string, opts: MapTextRenderOptions): void {
const minConf = parseFloat(opts.minConfidence ?? "0");
const levelFilter = opts.level ? parseInt(opts.level, 10) : null;
const parsedMaxItems = parseInt(opts.maxItems ?? "10", 10);
const maxItems = Number.isFinite(parsedMaxItems) && parsedMaxItems > 0 ? parsedMaxItems : 10;
const sortMode = normalizeSortMode(opts.sort);
const showGraph = !opts.list;
let regions = result.regions;
if (levelFilter !== null) regions = regions.filter(r => r.level === levelFilter);
if (minConf > 0) regions = regions.filter(r => r.confidence >= minConf);
console.log(
`\n${chalk.bold("Architectural Map")} — ` +
`${result.file_count} files · ${result.region_count} regions`
);
const topSystem = pickTopSystemName(result.regions, cwd);
if (topSystem) {
console.log(chalk.dim(`System: ${topSystem}`));
}
if (result.outcome === "fast_local_completed") {
console.log(chalk.yellow(" Large system detected") + chalk.dim(" — using Fast Map"));
console.log(chalk.dim(" Reduced coupling model with full region hierarchy output."));
}
if (regions.length === 0) {
console.log(chalk.dim("\n No regions found matching filters."));
return;
}
const regionById = new Map(result.regions.map(r => [r.id, r]));
const CROSSCUT_THRESHOLD = 0.10;
const systemsCount = regions.filter(r => r.label_kind === "system").length;
const subsystemsCount = regions.filter(r => r.label_kind === "subsystem").length;
const modulesCount = regions.filter(r => r.label_kind === "module").length;
const wellDefined = regions.filter(r => r.confidence >= 0.75).length;
const moderate = regions.filter(r => r.confidence >= 0.50 && r.confidence < 0.75).length;
const fuzzy = regions.filter(r => r.confidence < 0.50).length;
const crossCutting = regions.filter(r => r.crosscut_score > CROSSCUT_THRESHOLD).length;
console.log(chalk.dim(
`Scope: ${systemsCount} systems · ${subsystemsCount} subsystems · ${modulesCount} modules`
));
console.log(chalk.dim(
`Clarity: ${wellDefined} well-defined · ${moderate} moderate · ${fuzzy} fuzzy · ${crossCutting} cross-cutting`
));
if (levelFilter === null) {
if (showGraph) {
if (!opts.allItems) {
console.log(chalk.dim(`Showing up to ${maxItems} branches per level. Use --all-items to show everything.`));
}
renderMapTree(regions, maxItems, Boolean(opts.allItems), Boolean(opts.verbose), sortMode);
} else {
if (!opts.allItems) {
console.log(chalk.dim(`Showing the top ${maxItems} subsystems and the top ${maxItems} modules drawn from those subsystems. Use --all-items to show everything.`));
}
renderRankedList(regions, regionById, maxItems, Boolean(opts.allItems), Boolean(opts.verbose), sortMode);
}
} else {
if (!opts.allItems) {
console.log(chalk.dim(`Showing up to ${maxItems} items. Use --all-items to show everything.`));
}
renderLevelList(regions, regionById, levelFilter, maxItems, Boolean(opts.allItems), Boolean(opts.verbose), sortMode);
}
console.log(chalk.dim(`\nLegend: cross-cutting = spans multiple subsystems.`));
if (!opts.verbose) {
console.log(chalk.dim(`Run 'ix map --verbose' for confidence scores and raw metrics. Use --list for the ranked view.`));
}
console.log();
}
/** Render a confidence score as a compact bar: ████░░ (used in --verbose mode) */
function confidenceBar(conf: number): string {
const filled = Math.round(conf * 6);
const bar = "█".repeat(filled) + "░".repeat(6 - filled);
const color = conf >= 0.7 ? chalk.green : conf >= 0.4 ? chalk.yellow : chalk.red;
return color(bar);
}
/** Map a confidence score to a human-readable label. */
function confidenceLabel(conf: number): string {
if (conf >= 0.75) return "Well-defined";
if (conf >= 0.50) return "Moderate";
return "Fuzzy";
}
function pickTopSystemName(regions: MapRegion[], cwd: string): string {
const systems = regions
.filter(r => r.label_kind === "system")
.slice()
.sort((a, b) => b.file_count - a.file_count || b.confidence - a.confidence);
if (systems.length > 0 && systems[0].label.trim().length > 0) {
return systems[0].label;
}
const inferred = cwd.split(/[\\/]/).filter(Boolean).pop() ?? "System";
const compact = inferred.replace(/[^a-zA-Z0-9]+/g, " ").trim();
if (compact.length === 0) return "System";
const parts = compact.split(/\s+/);
if (parts.some(p => p.toLowerCase() === "ix")) return "IX";
if (compact.length <= 4) return compact.toUpperCase();
return parts
.map(part => part[0].toUpperCase() + part.slice(1).toLowerCase())
.join(" ");
}
function normalizeSortMode(input: string | undefined): MapSortMode {
switch ((input ?? "importance").toLowerCase()) {
case "confidence":
return "confidence";
case "size":
return "size";
case "alpha":
return "alpha";
default:
return "importance";
}
}
function compareRegions(a: MapRegion, b: MapRegion, mode: MapSortMode): number {
if (mode === "alpha") {
return a.label.localeCompare(b.label) || b.file_count - a.file_count || b.confidence - a.confidence;
}
if (mode === "confidence") {
return b.confidence - a.confidence || b.file_count - a.file_count || a.label.localeCompare(b.label);
}
return b.file_count - a.file_count || b.confidence - a.confidence || a.label.localeCompare(b.label);
}
function sortRegions(regions: MapRegion[], mode: MapSortMode): MapRegion[] {
return [...regions].sort((a, b) => compareRegions(a, b, mode));
}
function renderMapTree(
regions: MapRegion[],
maxItems: number,
allItems: boolean,
verbose: boolean,
sortMode: MapSortMode,
): void {
const regionById = new Map(regions.map(region => [region.id, region]));
const childrenByParent = new Map<string, MapRegion[]>();
for (const region of regions) {
if (!region.parent_id) continue;
const existing = childrenByParent.get(region.parent_id) ?? [];
existing.push(region);
childrenByParent.set(region.parent_id, existing);
}
const roots = sortRegions(
regions.filter(region => region.label_kind === "system" || region.parent_id === null || !regionById.has(region.parent_id)),
sortMode,
);
const shownRoots = allItems ? roots : roots.slice(0, maxItems);
console.log(`\n${chalk.bold("Architecture Graph")}`);
console.log(chalk.dim(" System → subsystem → module"));
for (const root of shownRoots) {
console.log();
renderTreeNode(root, "", true, 0, childrenByParent, maxItems, allItems, verbose, sortMode);
}
if (!allItems && roots.length > shownRoots.length) {
const remaining = roots.length - shownRoots.length;
console.log(chalk.dim(`\n ... ${remaining} more top-level branches. Use --all-items to show all.`));
}
}
function renderTreeNode(
region: MapRegion,
prefix: string,
isLast: boolean,
depth: number,
childrenByParent: Map<string, MapRegion[]>,
maxItems: number,
allItems: boolean,
verbose: boolean,
sortMode: MapSortMode,
): void {
const branch = depth === 0 ? "●" : isLast ? "└─" : "├─";
console.log(`${prefix}${branch} ${formatRegionLine(region, verbose, depth)}`);
const children = sortRegions(childrenByParent.get(region.id) ?? [], sortMode);
const shownChildren = allItems ? children : children.slice(0, maxItems);
const nextPrefix = depth === 0 ? " " : `${prefix}${isLast ? " " : "│ "}`;
shownChildren.forEach((child, index) => {
renderTreeNode(
child,
nextPrefix,
index === shownChildren.length - 1,
depth + 1,
childrenByParent,
maxItems,
allItems,
verbose,
sortMode,
);
});
if (!allItems && children.length > shownChildren.length) {
const remaining = children.length - shownChildren.length;
console.log(chalk.dim(`${nextPrefix}… ${remaining} more branches under ${region.label}`));
}
}
function renderRankedList(
regions: MapRegion[],
regionById: Map<string, MapRegion>,
maxItems: number,
allItems: boolean,
verbose: boolean,
sortMode: MapSortMode,
): void {
const subsystems = sortRegions(regions.filter(r => r.label_kind === "subsystem"), sortMode);
const shownSubsystems = allItems ? subsystems : subsystems.slice(0, maxItems);
const shownSubsystemIds = new Set(shownSubsystems.map(region => region.id));
const candidateModules = sortRegions(
regions.filter(r => r.label_kind === "module" && (
shownSubsystemIds.size === 0 ||
(r.parent_id !== null && shownSubsystemIds.has(r.parent_id))
)),
sortMode,
);
const shownModules = allItems ? candidateModules : candidateModules.slice(0, maxItems);
if (shownSubsystems.length > 0) {
console.log(`\n${chalk.bold("Subsystems")}`);
printAlignedRows(shownSubsystems.map(region => ({ region, parentLabel: null })), verbose, false);
if (!allItems && subsystems.length > shownSubsystems.length) {
console.log(chalk.dim(` ... ${subsystems.length - shownSubsystems.length} more subsystems. Use --all-items to show all.`));
}
}
if (shownModules.length > 0) {
console.log(`\n${chalk.bold("Modules")}`);
printAlignedRows(
shownModules.map(region => ({
region,
parentLabel: region.parent_id ? regionById.get(region.parent_id)?.label ?? "Unknown" : "Unknown",
})),
verbose,
true,
);
if (!allItems && candidateModules.length > shownModules.length) {
console.log(chalk.dim(` ... ${candidateModules.length - shownModules.length} more modules from the shown subsystems. Use --all-items to show all.`));
}
}
if (shownSubsystems.length === 0 && shownModules.length === 0) {
console.log(chalk.dim("\n No ranked subsystem or module regions found."));
}
}
function renderLevelList(
regions: MapRegion[],
regionById: Map<string, MapRegion>,
level: number,
maxItems: number,
allItems: boolean,
verbose: boolean,
sortMode: MapSortMode,
): void {
const label = level === 3 ? "Systems" : level === 2 ? "Subsystems" : "Modules";
const ranked = sortRegions(regions, sortMode);
const shown = allItems ? ranked : ranked.slice(0, maxItems);
console.log(`\n${chalk.bold(label)}`);
printAlignedRows(
shown.map(region => ({
region,
parentLabel: level === 1 && region.parent_id ? (regionById.get(region.parent_id)?.label ?? "Unknown") : null,
})),
verbose,
level === 1,
);
if (!allItems && ranked.length > shown.length) {
const remaining = ranked.length - shown.length;
console.log(chalk.dim(` ... ${remaining} more ${label.toLowerCase()}. Use --all-items to show all.`));
}
}
function printAlignedRows(
rows: Array<{ region: MapRegion; parentLabel: string | null }>,
verbose: boolean,
includeParent: boolean,
): void {
const nameWidth = Math.max("Name".length, ...rows.map(({ region }) => region.label.length));
const filesWidth = Math.max("Files".length, ...rows.map(({ region }) => String(region.file_count).length));
const confidenceWidth = Math.max(
"Confidence".length,
...rows.map(({ region }) => `${Math.round(region.confidence * 100)}% ${confidenceLabel(region.confidence)}`.length),
);
const parentWidth = includeParent
? Math.max("Parent".length, ...rows.map(({ parentLabel }) => (parentLabel ?? "-").length))
: 0;
const crossWidth = Math.max("Cross".length, ...rows.map(({ region }) => region.crosscut_score > 0.10 ? 3 : 2));
let header = ` ${"Name".padEnd(nameWidth)} ${"Files".padStart(filesWidth)} ${"Confidence".padEnd(confidenceWidth)}`;
if (includeParent) {
header += ` ${"Parent".padEnd(parentWidth)}`;
}
header += ` ${"Cross".padEnd(crossWidth)}`;
console.log(chalk.dim(header));
console.log(chalk.dim(` ${"─".repeat(Math.max(20, visibleWidth(header.trim())))}`));
for (const { region, parentLabel } of rows) {
const confidenceText = `${Math.round(region.confidence * 100)}% ${confidenceLabel(region.confidence)}`;
const confidenceColor = region.confidence >= 0.75 ? chalk.green : region.confidence >= 0.50 ? chalk.yellow : chalk.red;
const crossText = region.crosscut_score > 0.10 ? "yes" : "no";
let line = ` ${chalk.bold(region.label.padEnd(nameWidth))} ${chalk.dim(String(region.file_count).padStart(filesWidth))} ${confidenceColor(confidenceText.padEnd(confidenceWidth))}`;
if (includeParent) {
line += ` ${chalk.dim((parentLabel ?? "-").padEnd(parentWidth))}`;
}
line += ` ${(crossText === "yes" ? chalk.yellow(crossText.padEnd(crossWidth)) : chalk.dim(crossText.padEnd(crossWidth)))}`;
if (verbose) {
line += chalk.dim(` br=${Math.min(region.boundary_ratio, 999.9).toFixed(1)} xcut=${region.crosscut_score.toFixed(2)}`);
}
console.log(line);
}
}
function visibleWidth(text: string): number {
return text.replace(/\x1B\[[0-9;]*m/g, "").length;
}
function formatRegionLine(region: MapRegion, verbose: boolean, depth = 0): string {
const clarity = confidenceLabel(region.confidence);
const clarityColor = region.confidence >= 0.75 ? chalk.green : region.confidence >= 0.50 ? chalk.yellow : chalk.red;
const confPct = Math.round(region.confidence * 100);
const crosscut = region.crosscut_score > 0.10 ? chalk.yellow(" shared") : "";
const levelTag = region.label_kind || (region.level === 3 ? "system" : region.level === 2 ? "subsystem" : "module");
const badge = chalk.bgBlackBright.white(` ${levelTag.toUpperCase()} `);
const signals = region.dominant_signals.slice(0, 2).join(" · ");
if (verbose) {
const bar = confidenceBar(region.confidence);
const metrics = chalk.dim(
`conf=${confPct}% br=${Math.min(region.boundary_ratio, 999.9).toFixed(1)} xcut=${region.crosscut_score.toFixed(2)}`
);
const signalText = signals.length > 0 ? chalk.dim(` ${signals}`) : "";
return `${badge} ${bar} ${chalk.bold(region.label)} ${chalk.dim(`${region.file_count} files`)} ${clarityColor(`${clarity} (${confPct}%)`)} ${metrics}${signalText}${crosscut}`;
}
const fileText = depth === 0 ? chalk.dim(`${region.file_count} files`) : chalk.dim(`${region.file_count}`);
const signalText = signals.length > 0 ? chalk.dim(` ${signals}`) : "";
return `${badge} ${chalk.bold(region.label)} ${fileText} ${clarityColor(`${clarity} ${confPct}%`)}${signalText}${crosscut}`;
}
/** What a map that ran holds when it finishes: the workspace whose lock it took. */
interface HeldMap { root?: string; local?: boolean }
async function runMapCommand(pathArg: string | undefined, opts: { format: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; list?: boolean; full?: boolean; remap?: boolean; verbose?: boolean; silent?: boolean }, held: HeldMap): Promise<void> {
let cwd: string;
try {
cwd = resolveMapRoot(pathArg);
} catch (err: any) {
// Finding the root reads config.yaml. A config that does not parse is not a
// bad path: say what it is, as every other command does.
if (err?.name === "ConfigParseError") {
const broken = configParseError(err.path, err.detail);
if (opts.format === "json") printJson(broken);
else if (opts.format === "llm") console.log(llmError(broken.error, broken.message, [["hint", broken.next ?? ""]]));
else renderStructuredError(broken);
process.exitCode = 1;
return;
}
const message = err?.message ?? "Invalid map path";
if (opts.format === "json") {
printJson({ error: "invalid_map_path", message });
} else if (opts.format === "llm") {
console.log(llmError("invalid_map_path", message));
} else {
console.error(chalk.red("Error:"), message);
}
process.exitCode = 1;
return;
}
const silent = opts.silent === true || opts.format === "silent";
// Single-flight: refuse to stack. Background refresh can fire `ix map`
// repeatedly (e.g. once per change); if a map is slow or the backend is
// unhealthy, those invocations would otherwise pile up and run concurrently
// against the backend. The first map for a workspace holds the lock; any
// concurrent one coalesces and exits 0 here. The lock auto-releases on
// process exit (see single-flight.ts) and a stale lock from a crashed map
// is stolen, so this never wedges.
const mapLock = acquireMapLock(cwd, `ix map ${cwd}`);
if (!mapLock) {
if (!silent && opts.format !== "json" && opts.format !== "llm") {
process.stderr.write(chalk.dim(" Another ix map is already running for this workspace — skipping.\n"));
}
// Tell the holder: this run's reason (an edit, usually) may have come
// after it read the file, so it runs one more ingest before it lets go.
requestMapRerun(cwd);
applyRequestedMapCoalesceExitCode();
return; // coalesce; the in-flight map will refresh the graph
}
// Holding the lock: whatever a map that coalesced before now asked for, this
// run covers -- it has not read the tree yet.
takeMapRerun(cwd);
held.root = cwd;
// Background refresh is a local-only convenience. When invoked
// automatically (IX_AUTO_MAP=1, set by the editor/agent hooks) against a
// remote backend, skip: a remote graph should be fed deliberately, not by
// a write on every change from every client. Manual `ix map` is never
// skipped; opt the automatic path back in with IX_AUTO_MAP_CLOUD=1.
const autoMap = process.env.IX_AUTO_MAP === "1";
const cloudReady = await isCloudReady();
if (shouldSkipAutoMap({ auto: autoMap, cloudReady })) {
if (!silent && opts.format !== "json" && opts.format !== "llm") {
process.stderr.write(chalk.dim(" Skipping automatic map: active backend is remote (run `ix map` manually to refresh it).\n"));
}
return; // lock releases on process exit
}
// Shared wall-clock deadline applied to every backend request this command
// makes (ingest + map), so the whole operation is bounded even if the
// backend stalls on individual long per-request timeouts.
const deadlineSignal = mapDeadlineSignal();
// Auto-detect a multi-repo system (>= 2 child repo roots). When present we
// scope the map to its system_id; otherwise it's an ordinary single-repo map.
const systemId = detectSystem(cwd)?.systemId;
// json and llm are machine formats: suppress progress chatter and route
// ingestion through the quiet path so stdout carries only the result.
const machineFormat = opts.format === "json" || opts.format === "llm";
// Report an error on the right channel: structured record for llm, prose for the rest.
const emitError = (msg: string) => {
if (opts.format === "llm") console.log(llmError("backend_error", msg));
else console.error(chalk.red("Error:"), msg);
};
// Print warning when --full override is active
if (opts.full && !machineFormat && !silent) {
console.log(chalk.yellow("\nWarning"));
console.log(chalk.yellow(" Full local map override enabled.\n"));
console.log(" Ix will ignore automatic local safety limits and attempt full local mapping.");
console.log(" This may take a long time or fail on very large systems.\n");
}
// Ingest the path before mapping so the graph is up to date.
//
// Routing: if Pro is loaded AND the user has an active cloud
// instance configured (isCloudReady === true), route ingestion
// through the cloud pipeline. To force local, switch the active
// instance with `ix instance use local` (or `ix instance bind
// local` to scope to one workspace).
//
// The local backend bootstrap below only runs on the local path —
// cloud ingestion doesn't require a local Ix backend.
const ingestStart = performance.now();
let localIngest: IngestFilesSummary | undefined;
if (cloudReady) {
const runner = getRemoteRunner()!; // isCloudReady guarantees non-null
try {
await runner.runIngestion({
cwd,
silent,
format: (machineFormat || silent) ? "json" : "text",
});
} catch (err: any) {
emitError(formatFetchError(err));
process.exitCode = 1;
return;
}
} else {
try {
await bootstrap(cwd);
} catch (err: any) {
emitError(err.message);
process.exitCode = 1;
return;
}
try {
localIngest = await ingestFiles(cwd, {
recursive: true,
format: (machineFormat || silent) ? "json" : "text",
printSummary: false,
suppressOutput: true,
mapMode: mapModeForIngest(),
deadlineSignal,
// `ix map` has no --debug, so the per-file `[commit error] <uri>`
// detail was unreachable from the command that produced the
// failure — and the failure message told the user to pass a flag
// that does not exist. --verbose is map's equivalent lever.
debug: Boolean(opts.verbose),
});
} catch (err: any) {
emitError(formatFetchError(err));
process.exitCode = 1;
return;
}
// Only a local ingest that got through earns the rerun: after a failed
// one the backend was just seen to be down or out of time.
held.local = true;
}
const ingestMs = Math.round(performance.now() - ingestStart);
// Long-running: with IX_MAP_DEADLINE_MS=0 there is no deadline, and a read
// deadline would then cut off a map whose reads come minutes in.
const client = createClient({ deadlineSignal, longRunning: true });
const mapBarWidth = 25;
const mapStart = performance.now();
// Scope: the co-ingest system found above, a stitched system the backend
// knows of, or the workspace (see `resolveMapScope`).
const mapRequest = await resolveMapScope(client, cwd, opts.full, systemId);
// Reuse the last response when this run's ingest wrote nothing and the
// backend's head revision has not moved since it was computed. Local
// only: a cloud ingest reports no summary, so it cannot vouch for that.
const cacheSlot = localIngest ? await resolveMapCacheSlot(client, mapRequest, () => readBackendHealth(client)) : undefined;
// CL-13: an automatic map (IX_AUTO_MAP=1: the editor/agent hooks and
// `ix watch`) leaves `/v1/map` after an incremental edit for the next
// command that reads regions (`ensureFreshMap`) and prints the last map's
// regions, marked stale. Those hooks read none of them, and the request was
// most of the run. An `ix map` a person or agent runs never defers: it is
// asked for because the map is wanted now, so it computes, and clears the
// marker, as before CL-13. Also not for the first map (nothing is stored),
// --full, --remap or IX_MAP_EAGER=1, a system scope (never stored), a cloud
// ingest, or an ingest that might have left the graph somewhere unexpected
// (`incremental` is false then). An automatic run that changed nothing
// while the map is already stale stays deferred: computing it there would
// only move the cost to the next hook.
const staleBefore = localIngest ? readMapStale(cwd) : null;
const deferAllowed = autoMap && !opts.full && !opts.remap && !mapEager() && !mapRequest.systemId;
const wantsDefer = deferAllowed && cacheSlot !== undefined && localIngest !== undefined
&& (localIngest.incremental || (staleBefore !== null && localIngest.graphUnchanged));
const deferred = wantsDefer ? loadLastMap(cwd, cacheSlot!.key) : undefined;
// A stale map is never served from the no-change cache: its slot can still
// match after an edit that did not move the revision.
const cached = !deferred && staleBefore === null && cacheSlot && localIngest?.graphUnchanged
? loadCachedMap(cwd, cacheSlot)
: undefined;
let result: MapView;
if (deferred) {
result = deferred;
// A new marker for a new edit; an unchanged run keeps the one it found.
// It names the map these regions are from, for the readers'
// `regions_as_of`.
if (localIngest?.incremental) {
markMapStale(cwd, { regionsAsOf: { map_rev: deferred.map_rev, file_count: deferred.file_count } });
}
} else if (cached) {
result = cached;
} else {
// Same gate as the ingest bar: --silent and the machine formats were the
// only ways to avoid this, and neither is available to something merely
// capturing normal output.
const mapInterval = (!machineFormat && !silent && canRenderProgress()) ? setInterval(() => {
const elapsed = performance.now() - mapStart;
const pct = 1 - Math.exp(-elapsed / 4000);
const filled = Math.round(pct * mapBarWidth);
const bar = chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(mapBarWidth - filled));
const pctStr = chalk.cyan(`${Math.min(Math.round(pct * 100), 99)}%`.padStart(4));
process.stderr.write(`\r Computing map... ${bar} ${pctStr}`);
}, 80) : null;
try {
result = await client.map(mapRequest) as MapResult;
} catch (err: any) {
if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }
clearMapResultCache(cwd);
emitError(formatFetchError(err));
process.exitCode = 1;
return;
}
if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }
// Computed: whatever was deferred before is not any more.
clearMapStale(cwd);
}
const mapMs = Math.round(performance.now() - mapStart);
// A deferred map records nothing: its regions are the last map's, already
// recorded when it was computed, and the completed-map marker must not
// claim them for this ingest's revision. `ensureFreshMap` records the map
// it computes.
if (!deferred) {
const emptyMapError = invalidateBaselineForIncompleteCompletedMap(result, localIngest, cwd);
if (emptyMapError) {
emitError(emptyMapError);
process.exitCode = 1;
return;
}
// The cache holds the latest response the backend gave, or nothing: a
// response that is not kept removes the one before it, so a later hit
// can never be older than a miss in between.
if (persistCompletedMapBaseline(result, cwd) && cacheSlot) {
if (!cached) saveCachedMap(cwd, cacheSlot, result);
} else {
clearMapResultCache(cwd);
}
}
const mapStale = deferred !== undefined;
// A deferred map's counts and regions are the last map's. They keep their
// fields, so a consumer reading them still parses, and the map they come
// from is named beside them, so none can be taken for this ingest's. The
// file count stays the last map's too: the backend's count is not one the
// CLI can work out locally (it leaves out files the ingest discovered and
// sent), and a guess would match neither map.
const staleState: MapStaleState = mapStale
? { mapStale, regionsAsOf: { map_rev: result.map_rev, file_count: result.file_count } }
: {};
// stderr, so it reaches a human on the text path and never contaminates
// the JSON/llm payload on stdout. The exit code deliberately stays 0:
// plugins read this command's JSON through runners that discard stdout on
// a non-zero exit, so failing here would hide the very diagnostics the
// caller needs (the #539 lesson).
emitDroppedFileWarning(localIngest, silent);
if (silent) {
const systems = result.regions.filter(r => r.label_kind === "system").length;
const subsystems = result.regions.filter(r => r.label_kind === "subsystem").length;
const modules = result.regions.filter(r => r.label_kind === "module").length;
// Ix#568: `--silent` returns before both format branches AND wins over
// `--format llm`, so it is the one output the hooks this field exists
// for actually see. A skipped stitch deliberately does not move the exit
// code -- without a token here an automated consumer cannot tell a clean
// map from one whose cross-repo edges are up to 15 minutes stale.
// Ix#568. The RULE, not just the fact -- and not for `incomplete`.
//
// `--silent` is the hook surface: one terse line per run. `incomplete`
// fires on nearly every incremental map, so emitting it here would put
// a token on almost every line and make `stitch_skipped` useless as a
// signal, while a consumer that actually needs to know an incremental
// map registered nothing has `--format json` and `--format llm`, which
// both carry it. What stays here is the guard refusing -- the case that
// means a backend is being protected from stacked joins.
const rule = localIngest?.stitchSkippedRule;
const stitch =
rule === undefined || rule === "incomplete" || rule === "run-errors"
? ""
// `stitch_skipped_rule`, not `stitch_skipped`. The json and llm
// formats put the English prose under `stitch_skipped` and the rule
// under `stitch_skipped_rule`, and emitting the RULE under the
// prose key here gave one name two value spaces: a hook matching
// `stitch_skipped=cooling` on this line silently stopped matching
// the moment it was pointed at `--format json`.
: ` · stitch_skipped_rule=${rule}`;
process.stderr.write(silentSummaryLine({
files: result.file_count, systems, subsystems, modules, mapMs, stitch,
filesTooLarge: localIngest?.filesTooLarge, mapStale,
}));
return;
}
// A deferred map says so where its reader looks, not in a dim stderr
// aside: a text map opens with a warning on stdout, an llm map carries a
// `diagnostic code=map_stale` record (`renderMapLlm`).
if (!machineFormat && !mapStale) {
const mapSec = (mapMs / 1000).toFixed(1);
process.stderr.write(chalk.dim(` Mapped in ${mapSec}s\n`));
}
const minConf = parseFloat(opts.minConfidence ?? "0");
const levelFilter = opts.level ? parseInt(opts.level, 10) : null;
const parsedMaxItems = parseInt(opts.maxItems ?? "10", 10);
const maxItems = Number.isFinite(parsedMaxItems) && parsedMaxItems > 0 ? parsedMaxItems : 10;
const sortMode = normalizeSortMode(opts.sort);
let regions = result.regions;
if (levelFilter !== null) regions = regions.filter(r => r.level === levelFilter);
if (minConf > 0) regions = regions.filter(r => r.confidence >= minConf);
if (opts.format === "json") {
printJson(mapJsonPayload(result, regions, localIngest, staleState));
return;
}
if (opts.format === "llm") {
renderMapLlm(result, regions, localIngest, staleState);
return;
}
if (staleState.mapStale) renderWarning(mapStaleNotice(staleState));
renderMapText(result, cwd, opts);
}
/**
* One more ingest when a map that coalesced into this one asked for it (see
* `requestMapRerun`), before the lock is let go. One pass at most: under a
* stream of edits a rerun per request would never finish, and the next edit's
* own map picks up whatever arrives after it. Ingest only -- this run's output
* has already been printed. When the ingest changed the graph, the map is
* marked stale, so the next region view refreshes the hierarchy (CL-13);
* it used to be left stale with nothing to say so.
*/
export async function rerunIfRequested(root: string, local: boolean, opts: { silent?: boolean; format: string }): Promise<void> {
if (!local || !takeMapRerun(root)) return;
try {
const summary = await ingestFiles(root, {
recursive: true,
format: "json",
printSummary: false,
suppressOutput: true,
mapMode: mapModeForIngest(),
// Bounded like the run it follows: its own budget, since the first
// run's may be all but spent.
deadlineSignal: mapDeadlineSignal(),
});
if (!summary.graphUnchanged) markMapStale(root);
} catch (err: any) {
if (opts.silent !== true && opts.format !== "json" && opts.format !== "llm") {
process.stderr.write(chalk.dim(` Re-run for a map that waited on this one failed: ${err?.message ?? err}\n`));
}
}
}