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
feat(cli): add --detailed flag to ix subsystems --list (#209)
Jason Cornell51ebcac90c39
diff --git a/ix-cli/package-lock.json b/ix-cli/package-lock.jsonindex 369f1722..f097c3fa 100644--- a/ix-cli/package-lock.json+++ b/ix-cli/package-lock.json@@ -1,12 +1,12 @@{"name": "@ix/cli",- "version": "0.5.1",+ "version": "0.6.1","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@ix/cli",- "version": "0.5.1",+ "version": "0.6.1","dependencies": {"chalk": "^5.3.0","commander": "^12.0.0",diff --git a/ix-cli/package.json b/ix-cli/package.jsonindex 77b4b4fb..ea937282 100644--- a/ix-cli/package.json+++ b/ix-cli/package.json@@ -1,6 +1,6 @@{"name": "@ix/cli",- "version": "0.6.0",+ "version": "0.6.1","type": "module","description": "Ix Memory — Persistent Memory for LLM Systems","main": "dist/index.js",diff --git a/ix-cli/src/cli/commands/subsystems.ts b/ix-cli/src/cli/commands/subsystems.tsindex be500ac2..6d2de6df 100644--- a/ix-cli/src/cli/commands/subsystems.ts+++ b/ix-cli/src/cli/commands/subsystems.ts@@ -1,6 +1,6 @@import type { Command } from "commander";import chalk from "chalk";-import { IxClient } from "../../client/api.js";+import { IxClient, type ListSubsystemsOptions } from "../../client/api.js";import { getEndpoint } from "../config.js";import { roundFloat } from "../format.js";import { renderMapText, type MapResult } from "./map.js";@@ -33,12 +33,26 @@ interface UnknownSubsystemTargetResult {suggestions?: string[];}+interface SubsystemListResult {+ scores: SubsystemScore[];+ pagination?: Record<string, unknown>;+ autoPaginated: boolean;+}++const DETAILED_PAGE_LIMIT = 200;+export function registerSubsystemsCommand(program: Command): void {program.command("subsystems [target]").description("Show the persisted architectural map saved by 'ix map'").option("--format <fmt>", "Output format (text|json)", "text").option("--list", "List stored subsystem health scores instead of the persisted architecture map")+ .option("--detailed", "Include member files and enriched call/import edges (requires --list)")+ .option("--limit <n>", "Max regions per page in detailed mode (default: 200 when auto-paging)")+ .option("--offset <n>", "Skip N regions in detailed mode (disables auto-pagination)")+ .option("--regions <list>", "Comma-separated region IDs or names to scope detailed listing")+ .option("--edge-cap <n>", "Max edges per direction per region in detailed mode")+ .option("--member-file-cap <n>", "Max member files per region in detailed mode").option("--target <target>", "Scope subsystem output to a persisted architecture region").option("--pick <n>", "Resolve an ambiguous region target by numbered candidate").option("--level <n>", "Filter to level (1=module, 2=subsystem, 3=system)")@@ -57,6 +71,10 @@ ingestion or clustering.Examples:ix subsystemsix subsystems --list+ ix subsystems --list --detailed+ ix subsystems --list --detailed --format json+ ix subsystems --list --detailed --regions "Conflict,Branch"+ ix subsystems --list --detailed --limit 50 --offset 100ix subsystems apiix subsystems --target "Cli / Client"ix subsystems api --pick 2@@ -64,7 +82,26 @@ Examples:ix subsystems --level 2ix subsystems --graphix subsystems --format json`)- .action(async (positionalTarget: string | undefined, opts: { format: string; list?: boolean; target?: string; pick?: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; verbose?: boolean; explain?: boolean }) => {+ .action(async (positionalTarget: string | undefined, opts: {+ format: string;+ list?: boolean;+ detailed?: boolean;+ limit?: string;+ offset?: string;+ regions?: string;+ edgeCap?: string;+ memberFileCap?: string;+ target?: string;+ pick?: string;+ level?: string;+ minConfidence: string;+ maxItems: string;+ allItems?: boolean;+ sort: string;+ graph?: boolean;+ verbose?: boolean;+ explain?: boolean;+ }) => {const client = new IxClient(getEndpoint());const target = resolveSubsystemTarget(positionalTarget, opts.target);const pick = parsePickOption(opts.pick);@@ -89,6 +126,17 @@ Examples:process.exitCode = 1;return;}+ if (opts.detailed && !opts.list) {+ console.error(chalk.red("Error:"), "--detailed requires --list.");+ process.exitCode = 1;+ return;+ }+ const detailedQuery = parseDetailedListQuery(opts);+ if (detailedQuery.error) {+ console.error(chalk.red("Error:"), detailedQuery.error);+ process.exitCode = 1;+ return;+ }if (!target.value && pick.value !== undefined) {console.error(chalk.red("Error:"), "--pick requires a target.");process.exitCode = 1;@@ -101,33 +149,45 @@ Examples:}if (opts.list) {- let result: any;+ let result: SubsystemListResult;try {- result = await client.listSubsystems();+ result = await loadSubsystemScores(client, detailedQuery.value ?? {});// Auto-trigger scoring if no persisted scores exist yet- if ((result.scores ?? []).length === 0) {- result = await client.scoreSubsystems();+ if (result.scores.length === 0) {+ await client.scoreSubsystems();+ result = await loadSubsystemScores(client, detailedQuery.value ?? {});}} catch (err: any) {console.error(chalk.red("Error:"), err.message);process.exitCode = 1;return;}- const scores: SubsystemScore[] = result.scores ?? [];++ warnSubsystemListTruncation(result);++ const scores: SubsystemScore[] = result.scores;const filtered = opts.level? scores.filter(s => s.level === parseInt(opts.level!, 10)): scores;if (opts.format === "json") {- const compact = filtered.map(s => ({- name: s.name,- level: s.level,- health: roundFloat(s.health_score),- files: s.file_count,- chunks_per_file: roundFloat(s.chunk_density),- smell_files: s.smell_files,- }));- console.log(JSON.stringify({ scores: compact }, null, 2));+ if (opts.detailed) {+ console.log(JSON.stringify(buildDetailedListPayload(filtered, result.pagination), null, 2));+ } else {+ const compact = filtered.map(s => ({+ name: s.name,+ level: s.level,+ health: roundFloat(s.health_score),+ files: s.file_count,+ chunks_per_file: roundFloat(s.chunk_density),+ smell_files: s.smell_files,+ }));+ console.log(JSON.stringify({ scores: compact }, null, 2));+ }+ return;+ }+ if (opts.detailed) {+ console.log(JSON.stringify(buildDetailedListPayload(filtered, result.pagination), null, 2));return;}printScores(filtered);@@ -299,6 +359,173 @@ function parsePickOption(rawPick: string | undefined): { value?: number; error?:return { value };}+function parseOptionalIntOption(name: string, raw: string | undefined): { value?: number; error?: string } {+ if (raw === undefined) return {};+ const value = Number.parseInt(raw, 10);+ if (!Number.isFinite(value) || value < 0) {+ return { error: `Invalid ${name} value.` };+ }+ return { value };+}++function parseDetailedListQuery(opts: {+ detailed?: boolean;+ limit?: string;+ offset?: string;+ regions?: string;+ edgeCap?: string;+ memberFileCap?: string;+}): { value?: ListSubsystemsOptions; error?: string } {+ const hasDetailedParams = opts.limit !== undefined+ || opts.offset !== undefined+ || opts.regions !== undefined+ || opts.edgeCap !== undefined+ || opts.memberFileCap !== undefined;++ if (hasDetailedParams && !opts.detailed) {+ return { error: "--limit, --offset, --regions, --edge-cap, and --member-file-cap require --detailed." };+ }++ const limit = parseOptionalIntOption("--limit", opts.limit);+ if (limit.error) return { error: limit.error };+ const offset = parseOptionalIntOption("--offset", opts.offset);+ if (offset.error) return { error: offset.error };+ const edgeCap = parseOptionalIntOption("--edge-cap", opts.edgeCap);+ if (edgeCap.error) return { error: edgeCap.error };+ const memberFileCap = parseOptionalIntOption("--member-file-cap", opts.memberFileCap);+ if (memberFileCap.error) return { error: memberFileCap.error };++ const regions = opts.regions?.trim();+ if (regions === "") {+ return { error: "Invalid --regions value." };+ }++ return {+ value: {+ detailed: opts.detailed,+ limit: limit.value,+ offset: offset.value,+ regions: regions || undefined,+ edgeCap: edgeCap.value,+ memberFileCap: memberFileCap.value,+ },+ };+}++async function loadSubsystemScores(+ client: IxClient,+ query: ListSubsystemsOptions,+): Promise<SubsystemListResult> {+ if (!query.detailed) {+ const result = await client.listSubsystems();+ return { scores: result.scores ?? [], autoPaginated: false };+ }++ const explicitPage = query.offset !== undefined || Boolean(query.regions);+ if (explicitPage) {+ const page = await client.listSubsystems({+ ...query,+ limit: query.limit,+ });+ return {+ scores: page.scores ?? [],+ pagination: page.pagination,+ autoPaginated: false,+ };+ }++ const pageLimit = query.limit ?? DETAILED_PAGE_LIMIT;+ const allScores: SubsystemScore[] = [];+ let offset = 0;+ let lastPagination: Record<string, unknown> | undefined;++ while (true) {+ const page = await client.listSubsystems({+ ...query,+ limit: pageLimit,+ offset,+ });+ const scores: SubsystemScore[] = page.scores ?? [];+ allScores.push(...scores);+ lastPagination = page.pagination;++ const returned = typeof lastPagination?.returned === "number"+ ? lastPagination.returned+ : scores.length;+ const limit = typeof lastPagination?.limit === "number"+ ? lastPagination.limit+ : pageLimit;++ if (returned < limit) break;+ offset += returned;+ }++ return {+ scores: allScores,+ pagination: lastPagination+ ? { ...lastPagination, offset: 0, returned: allScores.length }+ : undefined,+ autoPaginated: true,+ };+}++function buildDetailedListPayload(+ scores: SubsystemScore[],+ pagination?: Record<string, unknown>,+): { scores: SubsystemScore[]; pagination?: Record<string, unknown> } {+ const payload: { scores: SubsystemScore[]; pagination?: Record<string, unknown> } = { scores };+ if (pagination) payload.pagination = pagination;+ return payload;+}++function warnSubsystemListTruncation(result: SubsystemListResult): void {+ const pagination = result.pagination;+ if (pagination && !result.autoPaginated) {+ const returned = pagination.returned;+ const limit = pagination.limit;+ const offset = pagination.offset;+ if (typeof returned === "number" && typeof limit === "number" && returned === limit) {+ const nextOffset = typeof offset === "number" ? offset + returned : returned;+ console.error(+ chalk.yellow(+ `Warning: Showing ${returned} regions (page full). More may exist — omit --offset to auto-fetch all pages, or use --offset ${nextOffset}.`+ )+ );+ }+ }++ const truncated = result.scores.filter(scoreHasTruncatedEdges);+ if (truncated.length === 0) return;++ const names = truncated.slice(0, 5).map((score) => score.name).join(", ");+ const suffix = truncated.length > 5 ? ` and ${truncated.length - 5} more` : "";+ console.error(+ chalk.yellow(+ `Warning: ${truncated.length} region(s) have truncated edges or member files (${names}${suffix}). Use --edge-cap or --member-file-cap to raise caps, or --regions to scope.`+ )+ );+}++function scoreHasTruncatedEdges(score: SubsystemScore): boolean {+ const record = score as SubsystemScore & Record<string, unknown>;+ const checks: Array<[string, string]> = [+ ["calls_out", "calls_out_total"],+ ["calls_in", "calls_in_total"],+ ["imports_out", "imports_out_total"],+ ["imports_in", "imports_in_total"],+ ["member_files", "member_files_total"],+ ];++ for (const [field, totalField] of checks) {+ const items = record[field];+ const total = record[totalField];+ if (typeof total === "number" && Array.isArray(items) && total > items.length) {+ return true;+ }+ }+ return false;+}+function renderSubsystemError(body: unknown, explain: boolean = false): void {if (isAmbiguousSubsystemResult(body)) {console.error(`Ambiguous target "${body.target_query}". Multiple architecture regions matched:\n`);diff --git a/ix-cli/src/client/api.ts b/ix-cli/src/client/api.tsindex 3872710c..d0828378 100644--- a/ix-cli/src/client/api.ts+++ b/ix-cli/src/client/api.ts@@ -9,6 +9,15 @@ import type {PatchCommitResult,} from "./types.js";+export interface ListSubsystemsOptions {+ detailed?: boolean;+ limit?: number;+ offset?: number;+ regions?: string;+ edgeCap?: number;+ memberFileCap?: number;+}+export class IxClient {constructor(private endpoint: string = "http://localhost:8090") {}@@ -249,8 +258,16 @@ export class IxClient {return this.post("/v1/subsystems/score", {});}- async listSubsystems(): Promise<any> {- return this.get("/v1/subsystems");+ async listSubsystems(opts?: ListSubsystemsOptions): Promise<any> {+ const params = new URLSearchParams();+ if (opts?.detailed) params.set("detailed", "true");+ if (opts?.limit !== undefined) params.set("limit", String(opts.limit));+ if (opts?.offset !== undefined) params.set("offset", String(opts.offset));+ if (opts?.regions) params.set("regions", opts.regions);+ if (opts?.edgeCap !== undefined) params.set("edge_cap", String(opts.edgeCap));+ if (opts?.memberFileCap !== undefined) params.set("member_file_cap", String(opts.memberFileCap));+ const qs = params.toString();+ return this.get(`/v1/subsystems${qs ? `?${qs}` : ""}`);}async getSubsystemMap(opts?: { target?: string; pick?: number }): Promise<any> {