feat: add triage command — composite risk audit queue (#224)

* feat: add triage command — composite risk audit queue

Merges connectivity (fan-in), complexity (cognitive), churn (commit
count), role classification, and maintainability index into a single
weighted risk score. Ranks symbols to surface the highest-risk areas
for audit.

Scoring: riskScore = w.fanIn×norm(fan_in) + w.complexity×norm(cognitive)
+ w.churn×norm(churn) + w.role×ROLE_WEIGHTS[role] + w.mi×(1−norm(MI))

Supports --sort (risk|complexity|churn|fan-in|mi), --min-score,
--role, --file, --kind, --no-tests, --weights JSON, pagination,
JSON/NDJSON output. Exposed as CLI command and MCP tool.

Impact: 6 functions changed, 5 affected

* fix: log SQL errors in triage catch block instead of silencing them

Impact: 1 functions changed, 1 affected

* fix: add triage to MCP test tool name list

Author: carlos-alm

src/cli.js

@@ -1035,6 +1035,58 @@ program
     });
   });
 
+program
+  .command('triage')
+  .description(
+    'Ranked audit queue by composite risk score (connectivity + complexity + churn + role)',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Max results to return', '20')
+  .option('--sort <metric>', 'Sort metric: risk | complexity | churn | fan-in | mi', 'risk')
+  .option('--min-score <score>', 'Only show symbols with risk score >= threshold')
+  .option('--role <role>', 'Filter by role (entry, core, utility, adapter, leaf, dead)')
+  .option('-f, --file <path>', 'Scope to a specific file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind (function, method, class)')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .option('--weights <json>', 'Custom weights JSON (e.g. \'{"fanIn":1,"complexity":0}\')')
+  .action(async (opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
+    if (opts.role && !VALID_ROLES.includes(opts.role)) {
+      console.error(`Invalid role "${opts.role}". Valid: ${VALID_ROLES.join(', ')}`);
+      process.exit(1);
+    }
+    let weights;
+    if (opts.weights) {
+      try {
+        weights = JSON.parse(opts.weights);
+      } catch {
+        console.error('Invalid --weights JSON');
+        process.exit(1);
+      }
+    }
+    const { triage } = await import('./triage.js');
+    triage(opts.db, {
+      limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      sort: opts.sort,
+      minScore: opts.minScore,
+      role: opts.role,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      weights,
+    });
+  });
+
 program
   .command('owners [target]')
   .description('Show CODEOWNERS mapping for files and functions')

src/index.js

@@ -141,5 +141,7 @@ export {
   moduleBoundariesData,
   structureData,
 } from './structure.js';
+// Triage — composite risk audit
+export { triage, triageData } from './triage.js';
 // Watch mode
 export { watchProject } from './watcher.js';

src/mcp.js

@@ -599,6 +599,43 @@ const BASE_TOOLS = [
       required: ['command', 'targets'],
     },
   },
+  {
+    name: 'triage',
+    description:
+      'Ranked audit queue by composite risk score. Merges connectivity (fan-in), complexity (cognitive), churn (commit count), role classification, and maintainability index into a single weighted score.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sort: {
+          type: 'string',
+          enum: ['risk', 'complexity', 'churn', 'fan-in', 'mi'],
+          description: 'Sort metric (default: risk)',
+        },
+        min_score: {
+          type: 'number',
+          description: 'Only return symbols with risk score >= this threshold (0-1)',
+        },
+        role: {
+          type: 'string',
+          enum: VALID_ROLES,
+          description: 'Filter by role classification',
+        },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: {
+          type: 'string',
+          enum: ['function', 'method', 'class'],
+          description: 'Filter by symbol kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        weights: {
+          type: 'object',
+          description:
+            'Custom scoring weights (e.g. {"fanIn":1,"complexity":0,"churn":0,"role":0,"mi":0})',
+        },
+        ...PAGINATION_PROPS,
+      },
+    },
+  },
   {
     name: 'branch_compare',
     description:
@@ -1091,6 +1128,21 @@ export async function startMCPServer(customDbPath, options = {}) {
           });
           break;
         }
+        case 'triage': {
+          const { triageData } = await import('./triage.js');
+          result = triageData(dbPath, {
+            sort: args.sort,
+            minScore: args.min_score,
+            role: args.role,
+            file: args.file,
+            kind: args.kind,
+            noTests: args.no_tests,
+            weights: args.weights,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.triage, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
+          break;
+        }
         case 'branch_compare': {
           const { branchCompareData, branchCompareMermaid } = await import('./branch-compare.js');
           const bcData = await branchCompareData(args.base, args.target, {

src/paginate.js

@@ -30,6 +30,7 @@ export const MCP_DEFAULTS = {
   manifesto: 50,
   communities: 20,
   structure: 30,
+  triage: 20,
 };
 
 /** Hard cap to prevent abuse via MCP. */