infernoflow 0.32.5 → 0.32.6

package/dist/lib/commands/explain.mjs

@@ -283,11 +283,13 @@ export async function explainCommand(rawArgs) {
   const dryRun  = args.includes("--dry-run");
   const jsonMode = args.includes("--json");
 
-  const capId = args.find(a => !a.startsWith("--"));
+  const arg = args.find(a => !a.startsWith("--"));
 
-  if (!capId) {
-    console.error(red("✗ Usage: infernoflow explain <capability-id> [--dry-run] [--json]"));
-    console.error(gray("  Example: infernoflow explain user-auth"));
+  if (!arg) {
+    console.error(red("✗ Usage: infernoflow explain <capability-id|file-path> [--dry-run] [--json]"));
+    console.error(gray("  Examples:"));
+    console.error(gray("    infernoflow explain CreateTask"));
+    console.error(gray("    infernoflow explain src/components/TaskComposer.jsx"));
     process.exit(1);
   }
 
@@ -299,75 +301,138 @@ export async function explainCommand(rawArgs) {
   const rawCaps = loadJson(path.join(infernoDir, "capabilities.json"));
   if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
 
-  const cap = allCaps.find(c => c.id === capId);
-  if (!cap) {
-    console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
-    console.error(gray("  Run: infernoflow stability — to list all capability IDs"));
-    process.exit(1);
-  }
+  // Detect if arg is a file path and resolve to capability IDs
+  const isFilePath = arg.includes("/") || arg.includes("\\") || /\.\w+$/.test(arg);
 
-  // Load scan + graph
-  const scanData  = loadJson(path.join(infernoDir, "scan.json"));
-  const graph     = loadJson(path.join(infernoDir, "graph.json"));
-  const scanEntry = scanData?.capabilities?.find(c => c.id === capId);
+  let capIdsToExplain = [];
 
-  // Git history
-  const files       = scanEntry?.codeAnalysis?.sourceFiles || [];
-  const firstCommit = getFirstCommit(files[0], cwd);
-  const recentHistory = getRecentHistory(files[0], cwd);
+  if (isFilePath) {
+    // Look up which capabilities are mapped to this file via scan.json
+    const scanData = loadJson(path.join(infernoDir, "scan.json"));
+    const scanCaps = scanData?.capabilities || [];
+    const relTarget = path.relative(cwd, path.resolve(cwd, arg));
 
-  // Scenarios
-  const scenarios = findScenarios(capId, infernoDir);
+    for (const entry of scanCaps) {
+      const sourceFiles = entry.codeAnalysis?.sourceFiles || [];
+      const matched = sourceFiles.some(f =>
+        f === relTarget || f.endsWith(relTarget) || relTarget.endsWith(f)
+      );
+      if (matched) capIdsToExplain.push(entry.id);
+    }
 
-  // Build prompt
-  const prompt = buildPrompt(capId, cap, scanEntry, graph, allCaps, scenarios, firstCommit, recentHistory);
+    if (capIdsToExplain.length === 0) {
+      // scan.json may not exist yet — try capability-map.json
+      const capMap = loadJson(path.join(infernoDir, "capability-map.json"));
+      if (capMap) {
+        const relNorm = relTarget.replace(/\\/g, "/");
+        for (const [capId, files] of Object.entries(capMap)) {
+          const fileList = Array.isArray(files) ? files : [files];
+          if (fileList.some(f => f === relNorm || f.endsWith(relNorm) || relNorm.endsWith(f))) {
+            capIdsToExplain.push(capId);
+          }
+        }
+      }
+    }
 
-  if (dryRun && !jsonMode) {
-    console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
-    console.log(gray("  ──────────────────────────────────────────────────────────────"));
-    printExplain(capId, cap, "", null, true);
-    console.log(bold("  Prompt that would be sent to AI:"));
-    console.log();
-    console.log(prompt.split("\n").map(l => "    " + l).join("\n"));
-    console.log();
-    return;
+    if (capIdsToExplain.length === 0) {
+      console.error(red(`✗ No capabilities found mapped to "${arg}"`));
+      console.error(gray("  Run: infernoflow scan — to build the source-file → capability map"));
+      console.error(gray("  Then retry: infernoflow explain " + arg));
+      process.exit(1);
+    }
+
+    if (!jsonMode) {
+      console.log(gray(`\n  infernoflow explain  →  ${bold(arg)}`));
+      console.log(gray(`  Found ${capIdsToExplain.length} mapped capability${capIdsToExplain.length > 1 ? "ies" : "y"}: ${capIdsToExplain.join(", ")}`));
+      console.log();
+    }
+  } else {
+    capIdsToExplain = [arg];
   }
 
-  // Call AI
-  let narrative = null;
-  let provider  = null;
+  // Explain each capability
+  const jsonResults = [];
+  for (const capId of capIdsToExplain) {
+    const cap = allCaps.find(c => c.id === capId);
+    if (!cap) {
+      if (!jsonMode) {
+        console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
+        console.error(gray("  Run: infernoflow stability — to list all capability IDs"));
+      }
+      continue;
+    }
 
-  if (!dryRun) {
-    try {
-      const result = await callAI(prompt, cwd);
-      if (result?.text) {
-        narrative = result.text.trim();
-        provider  = result.provider;
+    // Load scan + graph for this cap
+    const scanData  = loadJson(path.join(infernoDir, "scan.json"));
+    const graph     = loadJson(path.join(infernoDir, "graph.json"));
+    const scanEntry = scanData?.capabilities?.find(c => c.id === capId);
+
+    // Git history
+    const files          = scanEntry?.codeAnalysis?.sourceFiles || [];
+    const firstCommit    = getFirstCommit(files[0], cwd);
+    const recentHistory  = getRecentHistory(files[0], cwd);
+
+    // Scenarios
+    const scenarios = findScenarios(capId, infernoDir);
+
+    // Build prompt
+    const prompt = buildPrompt(capId, cap, scanEntry, graph, allCaps, scenarios, firstCommit, recentHistory);
+
+    if (dryRun && !jsonMode) {
+      console.log(gray(`  ── ${bold(capId)} ──────────────────────────────────────────────────────`));
+      printExplain(capId, cap, "", null, true);
+      if (capIdsToExplain.length === 1) {
+        console.log(bold("  Prompt that would be sent to AI:"));
+        console.log();
+        console.log(prompt.split("\n").map(l => "    " + l).join("\n"));
       }
-    } catch {}
-  }
+      console.log();
+      continue;
+    }
+
+    // Call AI
+    let narrative = null;
+    let provider  = null;
+
+    if (!dryRun) {
+      try {
+        const result = await callAI(prompt, cwd);
+        if (result?.text) {
+          narrative = result.text.trim();
+          provider  = result.provider;
+        }
+      } catch {}
+    }
+
+    if (!narrative) {
+      narrative = buildFallback(capId, cap, scanEntry, graph, allCaps, scenarios);
+      provider  = null;
+    }
 
-  // Fallback if no AI
-  if (!narrative) {
-    narrative = buildFallback(capId, cap, scanEntry, graph, allCaps, scenarios);
-    provider  = null;
+    if (jsonMode) {
+      jsonResults.push({
+        capId,
+        name:      cap.name || cap.title,
+        stability: stability(cap),
+        narrative,
+        provider:  provider || "fallback",
+        sourceFiles: files,
+        scenarios:   scenarios.map(s => s.scenarioId || s.description),
+        firstCommit,
+      });
+    } else {
+      if (!isFilePath) {
+        console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
+        console.log(gray("  ──────────────────────────────────────────────────────────────"));
+      }
+      printExplain(capId, cap, narrative, provider, false);
+    }
   }
 
   if (jsonMode) {
-    console.log(JSON.stringify({
-      capId,
-      name:      cap.name || cap.title,
-      stability: stability(cap),
-      narrative,
-      provider:  provider || "fallback",
-      sourceFiles: files,
-      scenarios:   scenarios.map(s => s.scenarioId || s.description),
-      firstCommit,
-    }, null, 2));
+    const out = capIdsToExplain.length === 1 ? jsonResults[0] : jsonResults;
+    console.log(JSON.stringify(out, null, 2));
     return;
   }
 
-  console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
-  console.log(gray("  ──────────────────────────────────────────────────────────────"));
-  printExplain(capId, cap, narrative, provider, false);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infernoflow",
-  "version": "0.32.5",
+  "version": "0.32.6",
   "description": "The forge for liquid code - keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {