Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

11.1 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import type { Command } from "commander";
import chalk from "chalk";
import { IxClient } from "../../client/api.js";
import { createClient } from "../../client/factory.js";
import { activeReadScope, ensureReadScope } from "../resolve.js";
import { llmLine } from "../llm.js";
import { normalizePathSeparators } from "../path-match.js";
import { printJson } from "../format.js";
import { mapLimit } from "../../client/request-memo.js";

type Metric = "dependents" | "callers" | "importers" | "members";

/** Render `ix rank` as llm records: a header line then one `entity` row per result (rank = line order). */
export function renderRankLlm(
  metric: string, kind: string, scope: string | null,
  results: Array<{ name: string; kind: string; score: number }>,
  evaluated: number, diagnostics: string[],
): string[] {
  const lines = [llmLine("rank", [
    ["metric", metric], ["kind", kind], ["scope", scope ?? undefined],
    ["evaluated", evaluated], ["returned", results.length],
  ])];
  for (const d of diagnostics) lines.push(llmLine("diagnostic", [["message", d]]));
  for (const r of results) {
    lines.push(llmLine("entity", [["name", r.name], ["kind", r.kind], ["score", r.score]]));
  }
  return lines;
}

const METRIC_CONFIG: Record<Metric, { direction: string; predicates: string[] }> = {
  dependents: { direction: "in", predicates: ["CALLS", "IMPORTS", "REFERENCES"] },
  callers: { direction: "in", predicates: ["CALLS", "REFERENCES"] },
  importers: { direction: "in", predicates: ["IMPORTS"] },
  members: { direction: "out", predicates: ["CONTAINS"] },
};

const VALID_METRICS = Object.keys(METRIC_CONFIG) as Metric[];

/** Get source URI from a node, checking common locations */
export function getSourceUri(node: any): string {
  return (
    node.provenance?.sourceUri ??
    node.provenance?.source_uri ??
    node.attrs?.sourceUri ??
    node.attrs?.source_uri ??
    ""
  );
}

/**
 * Apply path inclusion and exclusion filters to a list of nodes.
 *
 * Both sides go through `normalizePathSeparators`, so `--path src\cli` (what a
 * Windows user types) matches the `src/cli` that is actually stored. Case is
 * left alone — see `path-match.ts` and Ix#636.
 */
export function applyPathFilters(
  nodes: any[],
  includePath?: string,
  excludePath?: string
): any[] {
  let result = nodes;
  if (includePath) {
    const needle = normalizePathSeparators(includePath);
    result = result.filter((node: any) => normalizePathSeparators(getSourceUri(node)).includes(needle));
  }
  if (excludePath) {
    const needle = normalizePathSeparators(excludePath);
    result = result.filter((node: any) => !normalizePathSeparators(getSourceUri(node)).includes(needle));
  }
  return result;
}

/** Filter nodes by excluding specified kinds */
export function applyKindExclusion(nodes: any[], excludeKinds: string[]): any[] {
  if (excludeKinds.length === 0) return nodes;
  const excluded = new Set(excludeKinds);
  return nodes.filter((node: any) => !excluded.has(node.kind));
}

/** Pluralize an entity kind for display */
export function pluralize(kind: string): string {
  if (kind.endsWith("ss") || kind.endsWith("ch") || kind.endsWith("sh") || kind.endsWith("x")) return kind + "es";
  if (kind.endsWith("s")) return kind + "es";
  if (kind.endsWith("y") && !/[aeiou]y$/i.test(kind)) return kind.slice(0, -1) + "ies";
  return kind + "s";
}

interface ScoredEntity {
  id: string;
  name: string;
  kind: string;
  score: number;
}

/**
 * Requests in flight while scoring. The same peak load as the old batches of
 * 20, but a sliding window: a batch waited for its slowest expand before the
 * next one started, so one slow node held nineteen slots idle. Measured on the
 * Ix repository's graph (1284 functions): 4.3 s to ~1.9 s, same requests.
 */
const SCORE_CONCURRENCY = 20;

/** Score all candidates, a bounded number at a time, in candidate order. */
async function scoreAllCandidates(
  candidates: any[],
  config: { direction: string; predicates: string[] },
  client: IxClient,
  diagnostics: string[],
  entityKind: string,
): Promise<ScoredEntity[]> {
  const failed = new Array<boolean>(candidates.length).fill(false);
  const results = await mapLimit(candidates, SCORE_CONCURRENCY, async (node: any, index): Promise<ScoredEntity> => {
    try {
      const result = await client.expand(node.id, {
        direction: config.direction,
        predicates: config.predicates,
      });
      const seen = new Set<string>();
      for (const n of result.nodes) seen.add(n.id);
      return {
        id: node.id,
        name: node.name || node.attrs?.name || "(unnamed)",
        kind: node.kind || entityKind,
        score: seen.size,
      };
    } catch {
      failed[index] = true;
      return {
        id: node.id,
        name: node.name || node.attrs?.name || "(unnamed)",
        kind: node.kind || entityKind,
        score: 0,
      };
    }
  });
  // In candidate order, not in the order the failures happened to land.
  candidates.forEach((node: any, index) => {
    if (failed[index]) diagnostics.push(`Failed to expand entity ${node.id}`);
  });
  return results;
}

export function registerRankCommand(program: Command): void {
  program
    .command("rank")
    .description("Rank entities by graph-derived importance (dependents, callers, importers, members)")
    .requiredOption("--by <metric>", `Metric to rank by (${VALID_METRICS.join(", ")})`)
    .requiredOption("--kind <kind>", "Entity kind to rank (e.g. class, method, module)")
    .option("--top <n>", "Number of results to return", "10")
    .option("--path <path>", "Filter entities by source path substring")
    .option("--exclude-path <path>", "Exclude entities whose source path contains this substring")
    .option("--exclude-kind <kinds>", "Comma-separated kinds to exclude from results")
    .option("--format <fmt>", "Output format (text|json|llm)", "text")
    .addHelpText(
      "after",
      `\nExamples:
  ix rank --by dependents --kind class --top 10
  ix rank --by callers --kind method --top 20
  ix rank --by importers --kind module --top 10
  ix rank --by members --kind class --top 20
  ix rank --by dependents --kind class --path memory-layer --top 10
  ix rank --by dependents --kind class --exclude-path test --top 10
  ix rank --by dependents --kind class --exclude-kind config_entry --top 10
  ix rank --format json --by dependents --kind class`
    )
    .action(
      async (opts: {
        by: string;
        kind: string;
        top: string;
        path?: string;
        excludePath?: string;
        excludeKind?: string;
        format: string;
      }) => {
        const metric = opts.by as Metric;
        if (!VALID_METRICS.includes(metric)) {
          console.error(
            `Error: invalid metric "${opts.by}". Must be one of: ${VALID_METRICS.join(", ")}`
          );
          process.exit(1);
        }

        const topN = parseInt(opts.top, 10);
        const isJson = opts.format === "json";
        const client = createClient();
        const diagnostics: string[] = [];

        // 1. Fetch all entities of the given kind
        await ensureReadScope(client); // fold in a Path-2 stitched system (Ix#225 Half B)
        // The backend's scope is a raw AQL CONTAINS against source_uri, which is
        // always POSIX — send the separator-normalized needle or a Windows-style
        // --path silently matches nothing server-side too (Ix#636).
        const scopeNeedle = opts.path ? normalizePathSeparators(opts.path) : undefined;
        const allNodes = await client.listByKind(opts.kind, { limit: 2000, scope: scopeNeedle, ...activeReadScope() });

        if (allNodes.length === 0) {
          if (opts.format === "llm") {
            for (const line of renderRankLlm(metric, opts.kind, opts.path ?? null, [], 0, ["No entities found for the given kind."])) console.log(line);
          } else if (isJson) {
            printJson({
              metric,
              kind: opts.kind,
              scope: opts.path ?? null,
              results: [],
              summary: { evaluated: 0, totalCandidates: 0, returned: 0 },
              diagnostics: ["No entities found for the given kind."],
            });
          } else {
            console.log(chalk.dim("No entities found for the given kind."));
          }
          return;
        }

        // 2. Apply path inclusion filter
        let candidates = applyPathFilters(allNodes, opts.path, opts.excludePath);

        // 3. Apply kind exclusion filter
        const excludeKinds = opts.excludeKind ? opts.excludeKind.split(",").map(s => s.trim()) : [];
        candidates = applyKindExclusion(candidates, excludeKinds);

        if (candidates.length === 0) {
          const filterDesc = [
            opts.path ? `path "${opts.path}"` : null,
            opts.excludePath ? `exclude-path "${opts.excludePath}"` : null,
            excludeKinds.length > 0 ? `exclude-kind "${excludeKinds.join(",")}"` : null,
          ].filter(Boolean).join(", ");
          if (opts.format === "llm") {
            for (const line of renderRankLlm(metric, opts.kind, opts.path ?? null, [], 0, [`No entities matched filters: ${filterDesc}.`])) console.log(line);
          } else if (isJson) {
            printJson({
              metric,
              kind: opts.kind,
              scope: opts.path ?? null,
              results: [],
              summary: { evaluated: 0, totalCandidates: 0, returned: 0 },
              diagnostics: [`No entities matched filters: ${filterDesc}.`],
            });
          } else {
            console.log(chalk.dim(`No entities matched filters: ${filterDesc}.`));
          }
          return;
        }

        // 4. Score ALL candidates (batched for performance)
        const config = METRIC_CONFIG[metric];
        const scored = await scoreAllCandidates(candidates, config, client, diagnostics, opts.kind);

        // 6. Sort descending, take top N
        scored.sort((a, b) => b.score - a.score);
        const results = scored.slice(0, topN);

        // 7. Output
        if (opts.format === "llm") {
          for (const line of renderRankLlm(metric, opts.kind, opts.path ?? null, results.map(r => ({ name: r.name, kind: r.kind, score: r.score })), candidates.length, diagnostics)) console.log(line);
        } else if (isJson) {
          printJson({
            metric,
            kind: opts.kind,
            scope: scopeNeedle,
            results: results.map(r => ({ name: r.name, kind: r.kind, score: r.score })),
            summary: { evaluated: candidates.length, returned: results.length },
            diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
          });
        } else {
          console.log(chalk.bold(`Top ${results.length} ${pluralize(opts.kind)} by ${metric}:`));
          const maxNameLen = Math.max(...results.map((r) => r.name.length), 1);
          for (let i = 0; i < results.length; i++) {
            const r = results[i];
            const rank = String(i + 1).padStart(4);
            const name = r.name.padEnd(maxNameLen);
            console.log(`${rank}. ${name}  ${r.score}`);
          }
          if (diagnostics.length > 0) {
            console.log(chalk.dim(`\n${diagnostics.join("\n")}`));
          }
        }
      }
    );
}