karajan-code 2.8.0 → 2.9.0

package/src/audit/sonar-findings.js

@@ -0,0 +1,81 @@
+/**
+ * Sonar findings collector for `kj audit` (KJC-TSK-0361).
+ *
+ * The audit pipeline already pays for SonarQube to exist (kj run + the
+ * SonarStage drive a full scan and gate the pipeline on its result). When
+ * the user runs `kj audit`, we don't want to pay for *another* full scan
+ * (~1-3 min) — we want to read whatever Sonar already knows. This module
+ * does exactly that: ping the configured Sonar host, and if it's
+ * reachable, fetch the current open-issue list + quality-gate status via
+ * the existing sonar/api.js helpers. Both results are best-effort: a
+ * sonar-down host or a never-scanned project quietly returns
+ * `{available: false, reason: "..."}` and the audit continues without
+ * the section.
+ *
+ * Why this matters: the LLM auditor was previously asked to find issues
+ * by reading source code, but Sonar already produces them with rule IDs
+ * (squid:S1234), severity, and line precision. Feeding those in lets the
+ * LLM cross-reference its own findings (high-confidence overlap) and
+ * focus its tokens on patterns Sonar can't see (architecture, naming,
+ * API design).
+ */
+
+import { isSonarReachable } from "../sonar/manager.js";
+import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+
+/**
+ * Collect deterministic Sonar findings for the audit prompt.
+ *
+ * @param {object} config - resolved Karajan config (must have config.sonarqube.host)
+ * @param {object} [logger] - optional logger for warn-level traces
+ * @returns {Promise<{available: boolean, reason?: string, issues?: object[], total?: number, qualityGate?: object}>}
+ */
+export async function collectSonarFindings(config, logger = null) {
+  const sonarConfig = config?.sonarqube || {};
+  const host = sonarConfig.host || "http://localhost:9000";
+  const healthcheckSeconds = sonarConfig.timeouts?.healthcheckSeconds ?? 5;
+
+  // Ping first — avoids surfacing a 30-second timeout into audit runtime
+  // when Docker is simply down or the user opted out of Sonar.
+  const reachable = await isSonarReachable(host, healthcheckSeconds).catch(() => false);
+  if (!reachable) {
+    if (logger?.warn) logger.warn(`sonar audit input skipped: host ${host} not reachable`);
+    return { available: false, reason: `sonar host ${host} not reachable` };
+  }
+
+  let issuesResult;
+  try {
+    issuesResult = await getOpenIssues(config);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`sonar audit input: getOpenIssues failed: ${err?.message || err}`);
+    return { available: false, reason: `getOpenIssues failed: ${err?.message || err}` };
+  }
+
+  let qualityGate = null;
+  try {
+    const qg = await getQualityGateStatus(config);
+    if (qg?.ok) qualityGate = { status: qg.status, conditions: qg.conditions };
+  } catch { /* gate is optional context */ }
+
+  return {
+    available: true,
+    issues: issuesResult.issues || [],
+    total: issuesResult.total || 0,
+    qualityGate,
+  };
+}
+
+/**
+ * Group Sonar issues by severity, preserving Sonar's canonical ordering.
+ * Used by the prompt builder to render the findings section.
+ */
+export function groupIssuesBySeverity(issues) {
+  const order = ["BLOCKER", "CRITICAL", "MAJOR", "MINOR", "INFO"];
+  const groups = Object.fromEntries(order.map(s => [s, []]));
+  for (const issue of issues || []) {
+    const sev = issue.severity || "INFO";
+    if (groups[sev]) groups[sev].push(issue);
+    else groups.INFO.push(issue);
+  }
+  return groups;
+}

package/src/audit/webperf-input.js

@@ -0,0 +1,90 @@
+/**
+ * WebPerf input collector for `kj audit` (KJC-TSK-0360).
+ *
+ * Two modes:
+ *   - "static-hints": no live measurement available, but the project is
+ *     frontend so the LLM should look for frontend-perf patterns in the
+ *     source (bundle bloat, render-blocking, image opt, lazy loading).
+ *     This is the common path because `kj audit` runs against a code
+ *     tree, not a live preview server.
+ *   - "cwv-result": a Core Web Vitals measurement was supplied (either
+ *     via config.webperf.lastResult, or in the future via a `kj webperf`
+ *     command that drives Chrome DevTools MCP). evaluateCwv from
+ *     src/webperf/cwv-gate.js produces a structured verdict the prompt
+ *     renders verbatim.
+ *
+ * The "live measurement" path is intentionally NOT wired here: the
+ * audit's LLM sub-agent is forbidden from MCP tool use (SUBAGENT_PREAMBLE
+ * in src/prompts/audit.js), and spawning Chrome / launching a preview
+ * server during a read-only audit is out of scope. When a future
+ * `kj webperf` command exists, it can write the result into
+ * `config.webperf.lastResult` and this collector will surface it.
+ */
+
+import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
+
+/**
+ * Decide what (if anything) to feed the audit prompt about web perf.
+ *
+ * @param {object|null} stack - detectProjectStack output (null when unknown)
+ * @param {object} [config] - resolved Karajan config (config.webperf may carry a stale CWV result)
+ * @returns {{available: boolean, mode?: 'static-hints'|'cwv-result', cwv?: object, reason?: string}}
+ */
+export function collectWebPerfInput(stack, config = {}) {
+  const webperfConfig = config?.webperf || {};
+  const lastResult = webperfConfig.lastResult || null;
+
+  if (lastResult && typeof lastResult === "object" && lastResult.metrics) {
+    const verdict = evaluateCwv(lastResult.metrics, lastResult.thresholds || webperfConfig.thresholds);
+    return {
+      available: true,
+      mode: "cwv-result",
+      url: lastResult.url || webperfConfig.url || null,
+      capturedAt: lastResult.capturedAt || null,
+      cwv: verdict,
+      thresholds: lastResult.thresholds || webperfConfig.thresholds || CWV_THRESHOLDS,
+    };
+  }
+
+  // No live measurement → static hints only when the project actually has
+  // a frontend layer to audit. Backend-only projects get nothing.
+  const isFrontendish = !stack || stack.isFrontend === true || stack.isFullstack === true;
+  if (!isFrontendish) {
+    return { available: false, reason: "project is backend-only — no frontend-perf hints to give" };
+  }
+
+  return { available: true, mode: "static-hints" };
+}
+
+/**
+ * Render a CWV verdict (from collectWebPerfInput's cwv-result mode) as
+ * concise prompt-friendly markdown. Kept independent from the prompt
+ * builder so it stays unit-testable in isolation.
+ */
+export function formatCwvVerdict(input) {
+  if (!input || input.mode !== "cwv-result" || !input.cwv) return null;
+  const { cwv, url, capturedAt } = input;
+  const lines = [];
+  if (url) lines.push(`- Target URL: ${url}`);
+  if (capturedAt) lines.push(`- Captured: ${capturedAt}`);
+  lines.push(`- Verdict: ${cwv.pass ? "PASS" : "FAIL"}`);
+  if (Object.keys(cwv.scores || {}).length) {
+    lines.push("- Scores:");
+    for (const [metric, score] of Object.entries(cwv.scores)) {
+      lines.push(`  - ${metric.toUpperCase()}: ${score.value} (${score.rating})`);
+    }
+  }
+  if (cwv.blocking?.length) {
+    lines.push("- Blocking metrics (above poor threshold):");
+    for (const b of cwv.blocking) {
+      lines.push(`  - ${b.metric.toUpperCase()} ${b.value} > ${b.threshold}`);
+    }
+  }
+  if (cwv.advisory?.length) {
+    lines.push("- Advisory metrics (between good and poor):");
+    for (const a of cwv.advisory) {
+      lines.push(`  - ${a.metric.toUpperCase()} ${a.value} > good=${a.threshold}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/canvas/schema.js

@@ -51,7 +51,7 @@ const Operation = v.looseObject({
   acceptance: v.pipe(v.array(AcceptanceTest), v.minLength(1)),
 });
 
-export const CanvasSchema = v.looseObject({
+const CanvasSchema = v.looseObject({
   // Title is the project / feature name. The planner uses it as the
   // plan name unless the user overrides on prompt.
   title: NonEmptyString,

package/src/checks/binaries.js

@@ -60,7 +60,7 @@ function createCoreBinaryCheck(bin) {
 /**
  * Docker check. Manual strategy (platform-dependent install).
  */
-export function createDockerCheck() {
+function createDockerCheck() {
   return {
     name: "docker",
     label: "Docker",
@@ -80,7 +80,7 @@ export function createDockerCheck() {
 /**
  * Serena MCP (optional). Prompt strategy: we know how to install it.
  */
-export function createSerenaCheck() {
+function createSerenaCheck() {
   return {
     name: "serena",
     label: "Serena MCP",

package/src/checks/ci.js

@@ -37,7 +37,7 @@ function createWorkflowCheck(workflow) {
   };
 }
 
-export function createGhCliCheck() {
+function createGhCliCheck() {
   return {
     name: "ci:gh",
     label: "CI: gh CLI",
@@ -55,7 +55,7 @@ export function createGhCliCheck() {
   };
 }
 
-export function createGhSecretsCheck() {
+function createGhSecretsCheck() {
   return {
     name: "ci:secrets",
     label: "CI: GitHub secrets",

package/src/checks/config-files.js

@@ -20,7 +20,7 @@ import { STRATEGY } from "./types.js";
 /**
  * kj.config.yml presence check.
  */
-export function createConfigFileCheck() {
+function createConfigFileCheck() {
   return {
     name: "config",
     label: "Config file",
@@ -42,7 +42,7 @@ export function createConfigFileCheck() {
 /**
  * Review rules (.md) informational check.
  */
-export function createReviewRulesCheck() {
+function createReviewRulesCheck() {
   return {
     name: "review-rules",
     label: "Reviewer rules (.md)",
@@ -63,7 +63,7 @@ export function createReviewRulesCheck() {
 /**
  * Coder rules (.md) informational check.
  */
-export function createCoderRulesCheck() {
+function createCoderRulesCheck() {
   return {
     name: "coder-rules",
     label: "Coder rules (.md)",
@@ -104,7 +104,7 @@ function findDuplicateTomlKeys(content) {
 /**
  * Claude config (~/.claude.json) validity.
  */
-export function createClaudeConfigCheck() {
+function createClaudeConfigCheck() {
   return {
     name: "agent-config:claude",
     label: "Agent config: claude (~/.claude.json)",
@@ -135,7 +135,7 @@ export function createClaudeConfigCheck() {
 /**
  * Codex config (~/.codex/config.toml) validity.
  */
-export function createCodexConfigCheck() {
+function createCodexConfigCheck() {
   return {
     name: "agent-config:codex",
     label: "Agent config: codex (~/.codex/config.toml)",
@@ -173,7 +173,7 @@ export function createCodexConfigCheck() {
 /**
  * KJ config (~/.karajan/kj.config.yml) YAML validity (separate from existence).
  */
-export function createKjConfigYamlCheck() {
+function createKjConfigYamlCheck() {
   return {
     name: "agent-config:karajan",
     label: "Agent config: karajan (kj.config.yml)",

package/src/checks/dir-setup.js

@@ -15,6 +15,10 @@ const REQUIRED_DIRS = [
   "logs",
 ];
 
+/**
+ * @internal Exported for dynamic import from tests/checks/dir-setup.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createKarajanDirsCheck() {
   return {
     name: "karajan-dirs",

package/src/checks/mcp-health.js

@@ -86,6 +86,9 @@ async function pingMcpStdio(command, args) {
 /**
  * karajan-mcp health — stdio server bundled with this package.
  * Strategy: auto (we can re-spawn it ourselves).
+ *
+ * @internal Exported for dynamic import from tests/checks/mcp-health.test.js.
+ * Knip false positive.
  */
 export function createKarajanMcpCheck() {
   return {
@@ -121,6 +124,9 @@ export function createKarajanMcpCheck() {
 /**
  * Serena MCP — external tool the user installs themselves. Warn only when
  * enabled in config. Strategy: manual (we don't manage its lifecycle).
+ *
+ * @internal Exported for dynamic import from tests/checks/mcp-health.test.js.
+ * Knip false positive.
  */
 export function createSerenaMcpCheck() {
   return {

package/src/checks/ports.js

@@ -24,6 +24,10 @@ function extractPortFromHost(host, fallback) {
   return m ? Number(m[1]) : fallback;
 }
 
+/**
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createSonarPortCheck() {
   return {
     name: "port:sonar",
@@ -133,6 +137,10 @@ export function createSonarPortCheck() {
   };
 }
 
+/**
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createHuBoardPortCheck() {
   return {
     name: "port:hu-board",

package/src/checks/rtk.js

@@ -8,7 +8,7 @@ import { getInstallCommand } from "../utils/os-detect.js";
 import { withDocLink } from "../utils/doc-links.js";
 import { STRATEGY } from "./types.js";
 
-export function createRtkCheck() {
+function createRtkCheck() {
   return {
     name: "rtk",
     label: "RTK (Rust Token Killer)",

package/src/checks/skills.js

@@ -8,10 +8,14 @@ import { isOpenSkillsAvailable } from "../skills/openskills-client.js";
 import { runCommand } from "../utils/process.js";
 import { STRATEGY } from "./types.js";
 
-export function skillsEnabled(config) {
+function skillsEnabled(config) {
   return config?.skills?.enabled !== false;
 }
 
+/**
+ * @internal Exported for dynamic import from tests/checks/skills.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createOpenSkillsCheck() {
   return {
     name: "openskills",

package/src/checks/sonar.js

@@ -26,7 +26,7 @@ function sonarHost(config) {
  * Informative check: Sonar enabled/disabled status.
  * Produces an OK result with disabled description when Sonar is off.
  */
-export function createSonarStatusCheck() {
+function createSonarStatusCheck() {
   return {
     name: "sonarqube",
     label: "SonarQube",

package/src/checks/system.js

@@ -14,7 +14,7 @@ function getPackageVersion() {
   return JSON.parse(readFileSync(pkgPath, "utf8")).version;
 }
 
-export function createKarajanVersionCheck() {
+function createKarajanVersionCheck() {
   return {
     name: "karajan",
     label: "Karajan Code",
@@ -26,7 +26,7 @@ export function createKarajanVersionCheck() {
   };
 }
 
-export function createGitRepoCheck() {
+function createGitRepoCheck() {
   return {
     name: "git",
     label: "Git repository",

package/src/checks/tokens.js

@@ -146,4 +146,4 @@ export function getTokenChecks(config) {
 }
 
 // Re-export for tests that need to introspect the mapping.
-export { PROVIDER_TO_CLI, normalizeProvider };
+export { normalizeProvider };

package/src/checks/types.js

@@ -91,15 +91,3 @@ export const STRATEGY = Object.freeze({
   NONE: "none",
 });
 
-export const SEVERITY = Object.freeze({
-  FAIL: "fail",
-  WARN: "warn",
-  INFO: "info",
-});
-
-/**
- * Whether the final status blocks the pipeline (for preflight).
- */
-export function isBlocking(status) {
-  return status === STATUS.FAIL || status === STATUS.TIMEOUT;
-}

package/src/cli/register-meta.js

@@ -90,10 +90,16 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Analyze codebase health (read-only)")
     .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
-    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
+    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing,accessibility (default: all; accessibility auto-skipped on detected backend-only projects)", "all")
     .option("--json", "Output raw JSON")
     .option("--agent-readiness", "Score the repo for AI-agent readability (llms.txt, SKILL.md coverage, page token budgets, robots allowlist, heading hierarchy). LLM-free; uses [path] or cwd as the audit target. See issue #542.")
     .option("--path <dir>", "Path to audit (used with --agent-readiness; defaults to cwd)")
+    .option("--no-sonar", "Skip the SonarQube findings collector (faster, less context). Sonar findings are also skipped automatically when SonarQube is unreachable.")
+    .option("--no-osv", "Skip the OSV-Scanner vulnerability collector. Findings are also skipped automatically when osv-scanner is not installed.")
+    .option("--no-semgrep", "Skip the Semgrep SAST collector. Findings are also skipped automatically when semgrep is not installed (install via 'pipx install semgrep' or 'brew install semgrep').")
+    .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
+    .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
+    .option("-y, --yes", "Auto-confirm the 'Continue with LLM analysis?' prompt. Useful in scripts that want the full audit non-interactively. CI/non-TTY paths already auto-confirm without this flag.")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
         let resolvedTask = task;
@@ -101,12 +107,20 @@ export function registerMeta(program, { pkgVersion }) {
           const { readTaskFile } = await import("../utils/task-file.js");
           resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
         }
+        // commander resolves --no-sonar to flags.sonar=false (negation flag).
+        // We translate to the explicit `noSonar: true` shape AuditRole expects.
         await auditCommand({
           task: resolvedTask || "Analyze the full codebase",
           config, logger,
           dimensions: flags.dimensions, json: flags.json,
           agentReadiness: Boolean(flags.agentReadiness),
           path: flags.path,
+          noSonar: flags.sonar === false,
+          noOsv: flags.osv === false,
+          noSemgrep: flags.semgrep === false,
+          reportFile: flags.reportFile || null,
+          deterministicOnly: Boolean(flags.deterministicOnly),
+          yes: Boolean(flags.yes),
         });
       });
     });