kirograph 0.17.0 → 0.20.0

package/dist/bin/installer/steering.js

@@ -70,6 +70,14 @@ KiroGraph builds a semantic knowledge graph of your codebase. Use its MCP tools
 | What columns does this dataset have? | \`kirograph_data_describe\` |
 | Query rows with filters | \`kirograph_data_query\` |
 | Aggregate data (sum, avg, count) | \`kirograph_data_aggregate\` |
+| Are there vulnerable dependencies? | \`kirograph_security\` |
+| Which CVEs affect my project? | \`kirograph_vulns\` |
+| Is this vulnerability reachable? | \`kirograph_reachability\` |
+| What licenses do my dependencies use? | \`kirograph_licenses\` |
+| Are dependencies outdated? | \`kirograph_staleness\` |
+| Generate SBOM/VEX | \`kirograph_sbom\` / \`kirograph_vex\` |
+| Add a private CVE | \`kirograph_vuln_add\` |
+| Find structural code patterns? | \`kirograph_live_search\` |
 
 ---
 
@@ -266,6 +274,32 @@ kirograph_package(package: "src/services", includeFiles: false)
 
 ---
 
+## Workflow steering files
+
+KiroGraph installs task-specific steering files in \`.kiro/steering/\`. They are not always active \u2014 load them on demand.
+
+**In Kiro IDE:** type \`/kirograph-review\`, \`/kirograph-security\`, etc. to activate a workflow for the current session.
+
+**In Kiro CLI / other agents:** when the user asks for a specific workflow or you recognize the intent, read the file directly:
+
+\`\`\`
+Read file: .kiro/steering/kirograph-security.md
+Read file: .kiro/steering/kirograph-review.md
+\`\`\`
+
+| User intent | File to load |
+|-------------|-------------|
+| security audit, check vulnerabilities, CVE review | \`.kiro/steering/kirograph-security.md\` *(requires enableSecurity)* |
+| code review, review this PR | \`.kiro/steering/kirograph-review.md\` |
+| debug, trace this bug, root cause | \`.kiro/steering/kirograph-debug.md\` |
+| architecture, understand structure, package map | \`.kiro/steering/kirograph-architecture.md\` *(requires enableArchitecture)* |
+| onboard, understand this codebase | \`.kiro/steering/kirograph-onboard.md\` |
+| refactor, rename, safe refactoring | \`.kiro/steering/kirograph-refactor.md\` |
+
+Each file contains numbered steps, exact tool calls, and an interpretation reference. Follow the steps in order.
+
+---
+
 ## If \`.kirograph/\` does NOT exist
 
 Ask the user: "This project doesn't have KiroGraph initialized. Run \`kirograph init -i\` to build a code knowledge graph for faster exploration?"
@@ -342,6 +376,18 @@ function buildSteeringContent(opts) {
     content = content.replace("| Run a command with token savings | `kirograph_exec` |\n", "");
     content = content.replace("| Check token savings stats | `kirograph_gain` |\n", "");
   }
+  if (!opts?.enableSecurity) {
+    content = content.replace("| Are there vulnerable dependencies? | `kirograph_security` |\n", "");
+    content = content.replace("| Which CVEs affect my project? | `kirograph_vulns` |\n", "");
+    content = content.replace("| Is this vulnerability reachable? | `kirograph_reachability` |\n", "");
+    content = content.replace("| What licenses do my dependencies use? | `kirograph_licenses` |\n", "");
+    content = content.replace("| Are dependencies outdated? | `kirograph_staleness` |\n", "");
+    content = content.replace("| Generate SBOM/VEX | `kirograph_sbom` / `kirograph_vex` |\n", "");
+    content = content.replace("| Add a private CVE | `kirograph_vuln_add` |\n", "");
+  }
+  if (!opts?.enablePatterns) {
+    content = content.replace("| Find structural code patterns? | `kirograph_live_search` |\n", "");
+  }
   const caveman = cavemanMode && cavemanMode !== "off" ? import_caveman.CAVEMAN_RULES[cavemanMode] : null;
   if (caveman) {
     content = content.trimEnd() + "\n\n" + caveman + "\n";
@@ -415,6 +461,72 @@ kirograph_data_aggregate(dataset: "data-orders", groupBy: ["region"], metrics: [
 `;
     content = content.trimEnd() + "\n\n" + dataSection.trim() + "\n";
   }
+  if (opts?.enablePatterns) {
+    const patternsSection = `
+## Pattern Matching
+
+KiroGraph can search for structural code patterns using @ast-grep/napi.
+
+**Available tools (only when enablePatterns: true and @ast-grep/napi installed):**
+- \`kirograph_live_search\` \u2014 search for any AST pattern across the codebase at query time
+
+**CLI commands:**
+- \`kirograph pattern "<pattern>"\` \u2014 live structural search
+- \`kirograph pattern --list\` \u2014 browse bundled SAST rules
+- \`kirograph pattern --library <id>\` \u2014 run a specific library rule
+
+**When to use:** When you need to find code patterns that can't be expressed as symbol names or semantic queries \u2014 "all eval() calls", "all SQL string concatenation", "all readFile with request parameters".
+`;
+    content = content.trimEnd() + "\n\n" + patternsSection.trim() + "\n";
+  }
+  if (opts?.enableSecurity) {
+    const securitySection = `
+## Security
+
+KiroGraph scans dependency manifests across 14 ecosystems for known vulnerabilities, performs
+call-graph reachability analysis, tracks exploitation probability (EPSS), checks license
+compliance, and monitors dependency staleness.
+
+**Available tools:**
+- \`kirograph_security\` \u2014 overview: dep count, CVE count, verdict breakdown, stale warnings
+- \`kirograph_vulns\` \u2014 list CVEs with severity, EPSS score, reachability verdict, fix suggestion
+- \`kirograph_reachability\` \u2014 deep-dive: call paths, entry points, affected layers for one CVE or package
+- \`kirograph_licenses\` \u2014 list dependency licenses; flag policy violations (deny/warn by SPDX pattern)
+- \`kirograph_staleness\` \u2014 identify outdated dependencies (staleness score 0.0\u20131.0)
+- \`kirograph_sbom\` \u2014 export CycloneDX 1.5 SBOM for compliance/auditing
+- \`kirograph_vex\` \u2014 export CycloneDX 1.5 VEX with reachability-derived analysis states
+- \`kirograph_vuln_add\` \u2014 manually register a private/internal CVE not in public databases
+
+**Proactive triggers \u2014 run \`kirograph_security\` when:**
+- You or the user add/update/remove a dependency
+- Before a production deploy or release branch cut
+- The user asks about security, compliance, or "is it safe to upgrade X"
+- \`kirograph_context\` surfaces a \u26A0 Security warning in its output
+
+**Interpreting verdicts:**
+- \`affected\` \u2014 a call path exists from an entry point to the vulnerable code. Act on this.
+- \`not_affected\` \u2014 no reachable path found, no unresolved imports. Strong signal: likely safe.
+- \`under_investigation\` \u2014 traversal hit unresolved symbols (dynamic dispatch, reflection). Treat with caution.
+
+**Interpreting EPSS scores** (shown by \`kirograph_vulns\`):
+- \`>= 0.5\` \u2014 actively exploited or very likely to be. Patch immediately regardless of CVSS.
+- \`0.1 \u2013 0.5\` \u2014 elevated risk. Prioritize over low-EPSS vulns with higher CVSS.
+- \`< 0.1\` \u2014 low exploitation probability. Use CVSS + reachability for triage.
+
+**Recommended workflow:**
+1. \`kirograph_security\` \u2014 get the big picture before diving in
+2. \`kirograph_vulns --verdict affected\` \u2014 focus only on confirmed reachable CVEs
+3. For each high-EPSS or high-CVSS result: \`kirograph_reachability <cve>\` to see exact call paths
+4. \`kirograph_licenses --policy\` \u2014 check for license violations before shipping
+5. \`kirograph_staleness --threshold 0.5\` \u2014 flag severely outdated dependencies
+6. Fix, then \`kirograph_vulns --refresh\` to re-query OSV and confirm resolution
+7. \`kirograph_vex\` / \`kirograph_sbom\` for compliance artifacts
+
+**Staleness score guide:** 0.0 = current; 0.3+ = worth reviewing; 0.7+ = significantly behind.
+A high staleness score alone is not a security issue, but old dependencies accumulate CVEs over time.
+`;
+    content = content.trimEnd() + "\n\n" + securitySection.trim() + "\n";
+  }
   return content;
 }
 function writeSteering(kiroDir, opts) {
@@ -424,6 +536,382 @@ function writeSteering(kiroDir, opts) {
   const resolvedOpts = typeof opts === "string" ? { cavemanMode: opts } : opts ?? {};
   fs.writeFileSync(steeringPath, buildSteeringContent(resolvedOpts));
   console.log(`  \u2713 Steering file written to ${steeringPath}`);
+  writeWorkflowSteering(steeringDir, resolvedOpts);
+}
+function writeWorkflowSteering(steeringDir, opts) {
+  const workflows = {
+    "kirograph-review.md": `---
+inclusion: manual
+---
+
+# KiroGraph: Code Review Workflow
+
+Follow these steps for a structured, risk-aware code review using the knowledge graph.
+
+## Steps
+
+1. **Understand the change scope**
+   \`\`\`
+   kirograph_context(task: "<describe what changed>")
+   \`\`\`
+
+2. **Analyze blast radius**
+   For each key symbol that was modified:
+   \`\`\`
+   kirograph_impact(symbol: "<changed symbol>", depth: 2)
+   \`\`\`
+
+3. **Check test coverage**
+   \`\`\`
+   kirograph_callers(symbol: "<changed symbol>")
+   \`\`\`
+   Look for test files among the callers. Flag untested changes.
+
+4. **Look for surprising coupling**
+   \`\`\`
+   kirograph_surprising(limit: 10)
+   \`\`\`
+
+5. **Produce findings** grouped by risk level (high/medium/low) with:
+   - What changed and why it matters
+   - Test coverage status
+   - Suggested improvements
+   - Overall merge recommendation
+`,
+    "kirograph-debug.md": `---
+inclusion: manual
+---
+
+# KiroGraph: Debug Workflow
+
+Follow these steps to systematically trace and debug issues using the knowledge graph.
+
+## Steps
+
+1. **Find related code**
+   \`\`\`
+   kirograph_search(query: "<error message or symptom keywords>")
+   \`\`\`
+
+2. **Get full context**
+   \`\`\`
+   kirograph_context(task: "<describe the bug>")
+   \`\`\`
+
+3. **Trace the call chain**
+   \`\`\`
+   kirograph_callers(symbol: "<suspected function>")
+   kirograph_callees(symbol: "<suspected function>")
+   \`\`\`
+
+4. **Check what changed recently**
+   \`\`\`
+   kirograph_diff()
+   \`\`\`
+
+5. **Understand blast radius**
+   \`\`\`
+   kirograph_impact(symbol: "<root cause symbol>", depth: 3)
+   \`\`\`
+
+## Tips
+- Check both callers and callees to understand the full context
+- Recent changes (via diff) are the most common source of new issues
+- Use \`kirograph_path\` to trace how two symbols are connected
+`,
+    "kirograph-architecture.md": `---
+inclusion: manual
+---
+
+# KiroGraph: Architecture Exploration Workflow
+
+Follow these steps to understand the high-level structure of the codebase.
+
+## Steps
+
+1. **Get project overview**
+   \`\`\`
+   kirograph_status()
+   \`\`\`
+
+2. **View architecture**
+   \`\`\`
+   kirograph_architecture()
+   \`\`\`
+
+3. **Check coupling health**
+   \`\`\`
+   kirograph_coupling(sortBy: "instability")
+   \`\`\`
+
+4. **Find core abstractions**
+   \`\`\`
+   kirograph_hotspots(limit: 20)
+   \`\`\`
+
+5. **Detect hidden dependencies**
+   \`\`\`
+   kirograph_surprising(limit: 15)
+   \`\`\`
+
+6. **Check for cycles**
+   \`\`\`
+   kirograph_circular_deps()
+   \`\`\`
+
+## Interpretation
+- High Ca (afferent) = load-bearing, risky to change interface
+- High Ce (efferent) = depends on many things, safe to refactor internals
+- Surprising edges = hidden coupling that may break during refactoring
+`,
+    "kirograph-onboard.md": `---
+inclusion: manual
+---
+
+# KiroGraph: Onboarding Workflow
+
+Follow these steps to quickly understand a new codebase.
+
+## Steps
+
+1. **Project overview**
+   \`\`\`
+   kirograph_status()
+   \`\`\`
+
+2. **File structure**
+   \`\`\`
+   kirograph_files(format: "tree", maxDepth: 2)
+   \`\`\`
+
+3. **Key entry points**
+   \`\`\`
+   kirograph_hotspots(limit: 15)
+   \`\`\`
+
+4. **Architecture layers**
+   \`\`\`
+   kirograph_architecture()
+   \`\`\`
+
+5. **Explore a specific area**
+   \`\`\`
+   kirograph_context(task: "<area you want to understand>")
+   \`\`\`
+
+6. **Understand a key symbol**
+   \`\`\`
+   kirograph_node(symbol: "<symbol name>", includeCode: true)
+   \`\`\`
+
+## Tips
+- Start broad (status, files, hotspots) then narrow down
+- Use \`kirograph_type_hierarchy\` to understand inheritance patterns
+- Use \`kirograph_callees\` on entry points to trace execution flow
+`,
+    "kirograph-refactor.md": `---
+inclusion: manual
+---
+
+# KiroGraph: Refactoring Workflow
+
+Follow these steps to plan and execute safe refactoring.
+
+## Steps
+
+1. **Understand what you're changing**
+   \`\`\`
+   kirograph_node(symbol: "<target symbol>", includeCode: true)
+   \`\`\`
+
+2. **Check blast radius**
+   \`\`\`
+   kirograph_impact(symbol: "<target symbol>", depth: 3)
+   \`\`\`
+
+3. **Find all callers (rename preview)**
+   \`\`\`
+   kirograph_callers(symbol: "<target symbol>", limit: 50)
+   \`\`\`
+
+4. **Check for cycles that might complicate the refactor**
+   \`\`\`
+   kirograph_circular_deps()
+   \`\`\`
+
+5. **Find dead code to clean up**
+   \`\`\`
+   kirograph_dead_code(limit: 30)
+   \`\`\`
+
+6. **Verify after changes**
+   Run \`kirograph sync\` then:
+   \`\`\`
+   kirograph_diff()
+   \`\`\`
+
+## Safety Checks
+- Always check \`kirograph_impact\` before major refactors
+- Use \`kirograph_callers\` as a rename preview (all locations that reference the symbol)
+- After changes, use \`kirograph_diff\` to verify only intended symbols changed
+`
+  };
+  if (opts?.enableArchitecture) {
+    fs.writeFileSync(path.join(steeringDir, "kirograph-architecture.md"), workflows["kirograph-architecture.md"]);
+  }
+  for (const [filename, content] of Object.entries(workflows)) {
+    if (filename === "kirograph-architecture.md") continue;
+    fs.writeFileSync(path.join(steeringDir, filename), content);
+  }
+  if (opts?.enableSecurity) {
+    fs.writeFileSync(path.join(steeringDir, "kirograph-security.md"), `---
+inclusion: manual
+---
+
+# KiroGraph: Security Audit Workflow
+
+Follow these steps for a structured security audit using the knowledge graph.
+Activate this workflow before a release, after adding dependencies, or when asked to review security posture.
+
+## Steps
+
+### 1. Overview
+\`\`\`
+kirograph_security()
+\`\`\`
+Note: total dependencies, vulnerability count, verdict breakdown, stale warning count.
+
+### 2. Triage reachable vulnerabilities
+\`\`\`
+kirograph_vulns(verdict: "affected")
+\`\`\`
+Focus only on confirmed reachable CVEs. Sort output by EPSS score (exploitation probability) first, then CVSS severity.
+
+**Act immediately on:** EPSS >= 0.5 (actively exploited). Patch regardless of CVSS.
+**Prioritize:** EPSS 0.1\u20130.5 over low-EPSS high-CVSS entries.
+**Low urgency:** EPSS < 0.1 \u2014 use CVSS + reachability for triage.
+
+### 3. Deep-dive reachability for critical CVEs
+For each high-priority CVE from step 2:
+\`\`\`
+kirograph_reachability(target: "<CVE-ID or package name>")
+\`\`\`
+This shows: exact call paths from entry points, affected architectural layers, distinct path count.
+
+- \`affected\` verdict with known entry points \u2192 fix this dependency
+- \`not_affected\` \u2192 no reachable path, document and move on
+- \`under_investigation\` \u2192 unresolved symbols, treat conservatively
+
+### 4. Check for under-investigation CVEs
+\`\`\`
+kirograph_vulns(verdict: "under_investigation")
+\`\`\`
+For each: run \`kirograph_reachability\` to see what symbols are unresolved. If you can determine
+the symbol is not called, you can downgrade to not_affected manually.
+
+### 5. License compliance
+\`\`\`
+kirograph_licenses(policy: true)
+\`\`\`
+Review any DENY violations \u2014 these must be resolved before shipping.
+WARN violations should be documented and approved by the team.
+
+### 6. Dependency staleness
+\`\`\`
+kirograph_staleness(threshold: 0.5)
+\`\`\`
+Score guide: 0.3+ = worth reviewing, 0.7+ = significantly behind.
+Cross-reference with step 2 results: stale + vulnerable = highest priority.
+
+### 7. Refresh data if needed
+If vulnerability data looks stale (flagged in step 1) or dependencies changed recently:
+\`\`\`
+kirograph_vulns(refresh: true)
+\`\`\`
+
+### 8. Export compliance artifacts
+\`\`\`
+kirograph_sbom()   // Software Bill of Materials
+kirograph_vex()    // Vulnerability Exploitability eXchange
+\`\`\`
+
+## Interpretation Reference
+
+| Signal | Meaning | Action |
+|--------|---------|--------|
+| \`affected\` + EPSS >= 0.5 | Actively exploited, reachable | Patch immediately |
+| \`affected\` + CVSS >= 9.0 | Critical, reachable | Patch this sprint |
+| \`affected\` + CVSS 7.0\u20138.9 | High, reachable | Plan fix within 2 weeks |
+| \`not_affected\` | No reachable path found | Document, no action needed |
+| \`under_investigation\` | Reachability unclear | Manual review required |
+| Stale >= 0.7 | Very outdated | Review for accumulated CVEs |
+| License DENY | Policy violation | Must resolve before release |
+`);
+    console.log(`  \u2713 Security workflow steering file written`);
+  }
+  if (opts?.enablePatterns) {
+    fs.writeFileSync(path.join(steeringDir, "kirograph-patterns.md"), `---
+inclusion: manual
+---
+
+# KiroGraph: Pattern Search Workflow
+
+Use this workflow to find structural code patterns using AST matching.
+Activate with \`/kirograph-patterns\` in Kiro IDE or CLI.
+
+## Steps
+
+### 1. Browse available rules
+\`\`\`
+kirograph_live_search(pattern: "--list")
+\`\`\`
+Or use the CLI: \`kirograph pattern --list\`
+
+### 2. Search for a specific structural pattern
+\`\`\`
+kirograph_live_search(pattern: "eval($X)", language: "typescript")
+\`\`\`
+
+### 3. Run a bundled library rule
+\`\`\`
+kirograph pattern --library sql-injection-concat-js
+\`\`\`
+
+### 4. Add a custom rule
+Create a YAML file in your \`patternLibraryPath\` directory:
+\`\`\`yaml
+id: my-custom-rule
+language: [javascript, typescript]
+severity: high
+owaspCategory: A03
+description: Custom pattern description
+fixHint: How to fix this issue.
+rule:
+  pattern: dangerousFunction($ARG)
+\`\`\`
+
+## Pattern syntax examples
+
+| Pattern | Matches |
+|---------|---------|
+| \`eval($X)\` | Any eval() call |
+| \`$OBJ.query($A + $B)\` | String concat in any query method |
+| \`fs.$F(req.$P, $$$)\` | Any fs method with request param |
+| \`createHash('md5')\` | Hardcoded MD5 usage |
+
+## Interpretation
+
+- Findings mean the pattern was found in the AST \u2014 not a false positive from symbol name matching
+- Check the surrounding context: \`kirograph_node(symbol: "...", includeCode: true)\`
+- Use \`kirograph_callers\` to understand how the affected function is reached
+`);
+    console.log(`  \u2713 Patterns workflow steering file written`);
+  }
+  const written = ["review", "debug", "onboard", "refactor"];
+  if (opts?.enableArchitecture) written.push("architecture");
+  if (opts?.enableSecurity) written.push("security");
+  if (opts?.enablePatterns) written.push("patterns");
+  console.log(`  \u2713 Workflow steering files written (${written.join(", ")})`);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {