@karajan-family/code 4.21.0

package/src/sonar/credentials.js

@@ -0,0 +1,60 @@
+/**
+ * Load SonarQube credentials from ~/.karajan/sonar-credentials.json.
+ *
+ * File format (any subset):
+ * {
+ *   "user": "admin",
+ *   "password": "your-password",
+ *   "token": "squ_..."
+ * }
+ *
+ * Returns { user, password, token } with each field null when missing.
+ *
+ * The `token` field is consumed by resolveSonarTokenAsync as the
+ * lowest-priority fallback. Until v2.7.5 it was not extracted here, which
+ * meant a token persisted to the credentials file by `kj init` was never
+ * actually used at scan time — Karajan would silently fall back to the
+ * stale token in kj.config.yml or fail with a 401.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+const CREDENTIALS_FILENAME = "sonar-credentials.json";
+
+export async function loadSonarCredentials() {
+  try {
+    const filePath = path.join(getKarajanHome(), CREDENTIALS_FILENAME);
+    const raw = await fs.readFile(filePath, "utf8");
+    const data = JSON.parse(raw);
+    return {
+      user: data.user || null,
+      password: data.password || null,
+      token: data.token || null
+    };
+  } catch { /* credentials file may not exist */
+    return { user: null, password: null, token: null };
+  }
+}
+
+export function credentialsPath() {
+  return path.join(getKarajanHome(), CREDENTIALS_FILENAME);
+}
+
+/**
+ * Save a generated token to ~/.karajan/sonar-credentials.json so it persists across sessions.
+ * Merges with existing credentials (preserves user/password if present).
+ */
+export async function saveSonarToken(token) {
+  const filePath = path.join(getKarajanHome(), CREDENTIALS_FILENAME);
+  let existing = {};
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    existing = JSON.parse(raw);
+  } catch { /* file may not exist */ }
+  existing.token = token;
+  const dir = getKarajanHome();
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(existing, null, 2), { encoding: "utf8", mode: 0o600 });
+}

package/src/sonar/discovery.js

@@ -0,0 +1,124 @@
+/**
+ * Discover running SonarQube containers regardless of the user's
+ * config. The point: never bother the user about port 9000 being
+ * "occupied by an unknown process" — if there's a Sonar already up
+ * somewhere, just point at it and move on.
+ *
+ * The previous preflight check insisted on owning port 9000 by name
+ * (`karajan-sonarqube`). If you happened to have a `sonarqube` from
+ * another project running on 9000 (or had pulled a different image
+ * tag), we'd error out asking the user to "stop the conflicting
+ * process". That's busywork — Sonar is Sonar; reuse what's there.
+ *
+ * The discovery strategy:
+ *   1. List Docker containers whose image looks like sonarqube
+ *      (image-name regex / ancestor filter — covers `sonarqube`,
+ *      `sonarqube:community`, `sonarqube:lts`, `sonarqube:9.9`, …).
+ *   2. Parse the published host port (`0.0.0.0:9001->9000/tcp`).
+ *   3. Optionally HTTP-probe to confirm it's actually serving
+ *      `/api/system/status` so a misnamed image can't hijack us.
+ */
+
+import { runCommand } from "../utils/process.js";
+import { isSonarReachable } from "./manager.js";
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+/**
+ * @typedef {Object} DiscoveredSonar
+ * @property {boolean} found
+ * @property {string} [containerName]
+ * @property {string} [image]
+ * @property {number} [port]    - host port (what we connect to)
+ * @property {string} [host]    - http://localhost:<port>
+ * @property {boolean} [reachable] - true after a successful HTTP probe
+ */
+
+/**
+ * Parse the Ports column from `docker ps`. Looks for any host binding
+ * that maps to the container's `internalPort` (default 9000).
+ * Examples:
+ *   "0.0.0.0:9000->9000/tcp"        → 9000
+ *   "127.0.0.1:9001->9000/tcp"      → 9001
+ *   "9000/tcp"                      → null (no host binding)
+ *   "0.0.0.0:9000->9000/tcp, 9092/tcp" → 9000
+ *
+ * @param {string} portsStr
+ * @param {number} [internalPort=9000]
+ * @returns {number|null}
+ */
+export function extractHostPort(portsStr, internalPort = 9000) {
+  if (!portsStr) return null;
+  const re = new RegExp(
+    `(?:0\\.0\\.0\\.0|127\\.0\\.0\\.1|::|\\[::\\]):(\\d+)\\s*->\\s*${escapeRegExp(internalPort)}\\/tcp`,
+    "g"
+  );
+  const matches = [...portsStr.matchAll(re)];
+  if (matches.length === 0) return null;
+  // Prefer the smallest port number (likeliest the "main" binding);
+  // arbitrary but deterministic.
+  return Math.min(...matches.map((m) => Number(m[1])));
+}
+
+/**
+ * Run `docker ps` with a list-of-images filter and parse the result.
+ * Returns the FIRST container with a usable host port, or null.
+ *
+ * @returns {Promise<DiscoveredSonar|null>}
+ */
+async function dockerPsForSonar() {
+  // List all running containers with their image so we can image-match
+  // ourselves. Cheap (single docker call) and tolerant of image tags.
+  const res = await runCommand("docker", [
+    "ps",
+    "--format", "{{.ID}}|{{.Names}}|{{.Image}}|{{.Ports}}",
+  ]);
+  if (res.exitCode !== 0 || !res.stdout?.trim()) return null;
+
+  const lines = res.stdout.trim().split("\n");
+  for (const line of lines) {
+    const [, name, image, ports] = line.split("|");
+    if (!image) continue;
+    if (!/sonarqube/i.test(image)) continue;
+    const port = extractHostPort(ports, 9000);
+    if (!port) continue;
+    return {
+      found: true,
+      containerName: name,
+      image,
+      port,
+      host: `http://localhost:${port}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Public entry point: find a usable, reachable Sonar.
+ *
+ * `probe`: when true (default) HTTP-pings `/api/system/status` to
+ * confirm the container is actually serving Sonar. Tests can disable
+ * the probe for hermetic mocking.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.probe=true]
+ * @param {number} [opts.healthcheckSeconds=5]
+ * @returns {Promise<DiscoveredSonar>}
+ */
+export async function discoverRunningSonar(opts = {}) {
+  const { probe = true, healthcheckSeconds = 5 } = opts;
+  let candidate;
+  try {
+    candidate = await dockerPsForSonar();
+  } catch {
+    candidate = null;
+  }
+  if (!candidate) return { found: false };
+  if (!probe) return { ...candidate, reachable: true };
+  let reachable;
+  try {
+    reachable = await isSonarReachable(candidate.host, healthcheckSeconds);
+  } catch {
+    reachable = false;
+  }
+  return { ...candidate, reachable };
+}

package/src/sonar/enforcer.js

@@ -0,0 +1,19 @@
+export function shouldBlockByProfile({ gateStatus, profile = "pragmatic" }) {
+  if (profile === "paranoid") {
+    return gateStatus !== "OK";
+  }
+
+  return gateStatus === "ERROR";
+}
+
+export function summarizeIssues(issues) {
+  const bySeverity = issues.reduce((acc, issue) => {
+    const severity = issue.severity || "UNKNOWN";
+    acc[severity] = (acc[severity] || 0) + 1;
+    return acc;
+  }, {});
+
+  return Object.entries(bySeverity)
+    .map(([severity, count]) => `${severity}: ${count}`)
+    .join(", ");
+}

package/src/sonar/issue-filter.js

@@ -0,0 +1,12 @@
+// @deprecated — moved to src/audit/issue-filter.js (v2.17.0). This shim
+// re-exports the generalised filter so existing imports keep working. All
+// Sonar-specific behaviour (default `tool="sonar"`, legacy
+// `// karajan-sonar-ignore: <rule>` markers) is preserved by the new module.
+//
+// New code should import from "../audit/issue-filter.js" directly.
+
+export {
+  filterFalsePositives,
+  hasInlineIgnore,
+  DEFAULT_FALSE_POSITIVES,
+} from "../audit/issue-filter.js";

package/src/sonar/manager.js

@@ -0,0 +1,181 @@
+import fs from "node:fs/promises";
+import { ensureDir } from "../utils/fs.js";
+import { runCommand } from "../utils/process.js";
+import { getKarajanHome, getSonarComposePath } from "../utils/paths.js";
+import { loadConfig } from "../config.js";
+
+const KARAJAN_HOME = getKarajanHome();
+const COMPOSE_PATH = getSonarComposePath();
+
+function normalizeSonarConfig(sonarqube = {}) {
+  const timeouts = sonarqube.timeouts || {};
+  return {
+    host: sonarqube.host || "http://localhost:9000",
+    external: sonarqube.external === true,
+    containerName: sonarqube.container_name || "karajan-sonarqube",
+    network: sonarqube.network || "karajan_sonar_net",
+    volumes: {
+      data: sonarqube?.volumes?.data || "karajan_sonar_data",
+      logs: sonarqube?.volumes?.logs || "karajan_sonar_logs",
+      extensions: sonarqube?.volumes?.extensions || "karajan_sonar_extensions"
+    },
+    timeouts: {
+      healthcheckSeconds: Number(timeouts.healthcheck_seconds) > 0 ? Number(timeouts.healthcheck_seconds) : 5,
+      composeUpMs: Number(timeouts.compose_up_ms) > 0 ? Number(timeouts.compose_up_ms) : 5 * 60 * 1000,
+      composeControlMs: Number(timeouts.compose_control_ms) > 0 ? Number(timeouts.compose_control_ms) : 2 * 60 * 1000,
+      logsMs: Number(timeouts.logs_ms) > 0 ? Number(timeouts.logs_ms) : 30 * 1000
+    }
+  };
+}
+
+function buildComposeTemplate(sonarConfig) {
+  return `services:
+  sonarqube:
+    image: sonarqube:community
+    container_name: ${sonarConfig.containerName}
+    ports:
+      - "9000:9000"
+    volumes:
+      - ${sonarConfig.volumes.data}:/opt/sonarqube/data
+      - ${sonarConfig.volumes.logs}:/opt/sonarqube/logs
+      - ${sonarConfig.volumes.extensions}:/opt/sonarqube/extensions
+    environment:
+      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
+    networks:
+      - ${sonarConfig.network}
+    restart: unless-stopped
+
+volumes:
+  ${sonarConfig.volumes.data}:
+  ${sonarConfig.volumes.logs}:
+  ${sonarConfig.volumes.extensions}:
+
+networks:
+  ${sonarConfig.network}:
+    name: ${sonarConfig.network}
+`;
+}
+
+export async function ensureComposeFile(sonarqube = null) {
+  const sonarConfig = sonarqube ? normalizeSonarConfig(sonarqube) : normalizeSonarConfig((await loadConfig()).config.sonarqube);
+  const composeTemplate = buildComposeTemplate(sonarConfig);
+  await ensureDir(KARAJAN_HOME);
+  await fs.writeFile(COMPOSE_PATH, composeTemplate, "utf8");
+  return COMPOSE_PATH;
+}
+
+export async function isSonarReachable(host, healthcheckSeconds = 5) {
+  const timeout = Number(healthcheckSeconds) > 0 ? String(Number(healthcheckSeconds)) : "5";
+  const res = await runCommand("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", timeout, `${host}/api/system/status`]);
+  return res.exitCode === 0 && res.stdout.trim().startsWith("2");
+}
+
+export async function sonarUp(hostOverride = null) {
+  const { config } = await loadConfig();
+  const sonarConfig = normalizeSonarConfig(config.sonarqube);
+  const host = hostOverride || sonarConfig.host;
+
+  if (await isSonarReachable(host, sonarConfig.timeouts.healthcheckSeconds)) {
+    return { exitCode: 0, stdout: `SonarQube already reachable at ${host}, skipping container start.`, stderr: "" };
+  }
+
+  if (sonarConfig.external) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `Configured external SonarQube is not reachable at ${host}.`
+    };
+  }
+
+  // Discover-before-spawn (v2.7.5): if there's already a SonarQube
+  // container running anywhere — even under a different name on a
+  // different port — reuse it instead of spinning up a second one.
+  // Avoids the user accidentally accumulating Sonar containers across
+  // projects, and matches what the port preflight check already does.
+  const { discoverRunningSonar } = await import("./discovery.js");
+  const discovered = await discoverRunningSonar({
+    healthcheckSeconds: sonarConfig.timeouts.healthcheckSeconds,
+  });
+  if (discovered.found && discovered.reachable) {
+    return {
+      exitCode: 0,
+      stdout: `Reusing existing SonarQube container "${discovered.containerName}" at ${discovered.host} (skipping container start).`,
+      stderr: "",
+      reusedHost: discovered.host,
+    };
+  }
+
+  const compose = await ensureComposeFile(config.sonarqube);
+  return runCommand("docker", ["compose", "-f", compose, "up", "-d"], { timeout: sonarConfig.timeouts.composeUpMs });
+}
+
+export async function sonarDown() {
+  const { config } = await loadConfig();
+  const sonarConfig = normalizeSonarConfig(config.sonarqube);
+  if (sonarConfig.external) {
+    return { exitCode: 0, stdout: "sonarqube.external=true, skipping Docker stop.", stderr: "" };
+  }
+  const compose = await ensureComposeFile(config.sonarqube);
+  return runCommand("docker", ["compose", "-f", compose, "stop"], { timeout: sonarConfig.timeouts.composeControlMs });
+}
+
+export async function sonarStatus() {
+  const { config } = await loadConfig();
+  const sonarConfig = normalizeSonarConfig(config.sonarqube);
+  const host = sonarConfig.host;
+
+  if (sonarConfig.external) {
+    if (await isSonarReachable(host, sonarConfig.timeouts.healthcheckSeconds)) {
+      return { exitCode: 0, stdout: `external SonarQube running at ${host}`, stderr: "" };
+    }
+    return { exitCode: 1, stdout: "", stderr: `external SonarQube is not reachable at ${host}` };
+  }
+
+  const containerRes = await runCommand("docker", ["ps", "--filter", `name=${sonarConfig.containerName}`, "--format", "{{.Status}}"]);
+  if (containerRes.stdout?.trim()) return containerRes;
+
+  if (await isSonarReachable(host, sonarConfig.timeouts.healthcheckSeconds)) {
+    return { exitCode: 0, stdout: `external SonarQube running at ${host}`, stderr: "" };
+  }
+
+  return containerRes;
+}
+
+export async function sonarLogs() {
+  const { config } = await loadConfig();
+  const sonarConfig = normalizeSonarConfig(config.sonarqube);
+  if (sonarConfig.external) {
+    return { exitCode: 1, stdout: "", stderr: "sonarqube.external=true, Docker logs are not available." };
+  }
+  return runCommand("docker", ["logs", "--tail", "100", sonarConfig.containerName], { timeout: sonarConfig.timeouts.logsMs });
+}
+
+const MIN_MAP_COUNT = 262144;
+
+export async function checkVmMaxMapCount(platform) {
+  if (platform === "darwin" || platform === "win32") {
+    return { ok: true, reason: "vm.max_map_count check not required on this platform" };
+  }
+
+  const res = await runCommand("sysctl", ["vm.max_map_count"]);
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: "Could not read vm.max_map_count",
+      fix: `sudo sysctl -w vm.max_map_count=${MIN_MAP_COUNT}`
+    };
+  }
+
+  const match = /=\s*(\d+)/.exec(res.stdout);
+  const current = match ? Number(match[1]) : 0;
+
+  if (current >= MIN_MAP_COUNT) {
+    return { ok: true, reason: `vm.max_map_count = ${current}` };
+  }
+
+  return {
+    ok: false,
+    reason: `vm.max_map_count = ${current} (needs >= ${MIN_MAP_COUNT})`,
+    fix: `sudo sysctl -w vm.max_map_count=${MIN_MAP_COUNT} && echo "vm.max_map_count=${MIN_MAP_COUNT}" | sudo tee -a /etc/sysctl.conf`
+  };
+}

package/src/sonar/project-key.js

@@ -0,0 +1,120 @@
+import crypto from "node:crypto";
+import { runCommand } from "../utils/process.js";
+
+function slug(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._:-]+/g, "-")
+    .replaceAll(/-{2,}/g, "-")
+    .replaceAll(/(^-+)|(-+$)/g, "");
+}
+
+function normalizeProjectKey(value) {
+  const out = slug(value);
+  if (!out) return "kj-default";
+  return /[a-z]/.test(out) ? out : `kj-${out}`;
+}
+
+function digest(input) {
+  return crypto.createHash("sha1").update(String(input)).digest("hex").slice(0, 12);
+}
+
+function parseScpLikeRemote(remoteUrl) {
+  // Example: git@github.com:owner/repo.git
+  const match = /^(?:[^@]+@)?([^:]+):(.+)$/.exec(String(remoteUrl || "").trim());
+  if (!match) return null;
+  return { host: match[1], path: match[2] };
+}
+
+function parseUrlLikeRemote(remoteUrl) {
+  try {
+    const parsed = new URL(String(remoteUrl || "").trim());
+    return { host: parsed.hostname, path: parsed.pathname.replace(/^\/+/, "") };
+  } catch { /* not a valid URL */
+    return null;
+  }
+}
+
+function canonicalRepoId(remoteUrl) {
+  const raw = String(remoteUrl || "").trim();
+  if (!raw) return null;
+
+  const parsed = raw.includes("://") ? parseUrlLikeRemote(raw) : (parseScpLikeRemote(raw) || parseUrlLikeRemote(raw));
+  if (!parsed) return null;
+
+  const host = String(parsed.host || "").trim().toLowerCase();
+  const cleanPath = String(parsed.path || "")
+    .trim()
+    .replaceAll(/(^\/+)|(\/+$)/g, "")
+    .replace(/\.git$/i, "")
+    .toLowerCase();
+  const segments = cleanPath.split("/").filter(Boolean);
+  if (!host || segments.length < 2) return null;
+
+  // Keep full repository path (owner/subgroups/repo) to avoid collisions in nested groups.
+  return `${host}/${segments.join("/")}`;
+}
+
+export async function resolveSonarProjectKey(config, options = {}) {
+  const explicit = String(
+    options.projectKey || process.env.KJ_SONAR_PROJECT_KEY || config?.sonarqube?.project_key || ""
+  ).trim();
+  if (explicit) {
+    return normalizeProjectKey(explicit);
+  }
+
+  const remote = await runCommand("git", ["config", "--get", "remote.origin.url"]);
+  const remoteUrl = String(remote.stdout || "").trim();
+  if (remote.exitCode !== 0 || !remoteUrl) {
+    throw new Error(
+      "Missing git remote.origin.url. Configure remote origin or set sonarqube.project_key explicitly."
+    );
+  }
+
+  const repoId = canonicalRepoId(remoteUrl);
+  if (!repoId) {
+    throw new Error(
+      "Unable to parse git remote.origin.url. Use a valid SSH/HTTPS remote or set sonarqube.project_key explicitly."
+    );
+  }
+
+  const repo = slug(repoId.split("/").pop());
+  return normalizeProjectKey(`kj-${repo}-${digest(repoId)}`);
+}
+
+/**
+ * Non-throwing predicate: can a Sonar project key be resolved for `config`?
+ *
+ * Used by callers (audit collector, run-loop SonarStage) that want to skip
+ * the Sonar work cleanly instead of letting `resolveSonarProjectKey` throw
+ * "Missing git remote.origin.url" deep inside the scanner. The scanner's
+ * thrown error is fine for an explicit `kj sonar` call (the user asked
+ * for it), but for implicit pipeline gates it produces a noisy "Sonar
+ * scan failed" loop in fresh /tmp/... repos.
+ *
+ * Returns true when EITHER:
+ *   - an explicit `project_key` is set (env var, config, or per-call option),
+ *   - OR `git config --get remote.origin.url` succeeds with a non-empty value.
+ *
+ * Side-effect-free apart from the git probe.
+ *
+ * @param {object} config
+ * @param {object} [options]
+ * @param {string} [options.projectKey]
+ * @returns {Promise<boolean>}
+ */
+export async function canResolveSonarProjectKey(config, options = {}) {
+  const explicit = String(
+    options.projectKey || process.env.KJ_SONAR_PROJECT_KEY || config?.sonarqube?.project_key || ""
+  ).trim();
+  if (explicit) return true;
+  // try/catch (instead of `.catch(...)`) tolerates two legitimate test
+  // realities: a runCommand mock that returns undefined, and a real
+  // promise rejection from a missing git binary. Either way we treat
+  // it as "no remote available" and let the caller skip Sonar cleanly.
+  let remote;
+  try { remote = await runCommand("git", ["config", "--get", "remote.origin.url"]); }
+  catch { return false; }
+  if (!remote) return false;
+  return remote.exitCode === 0 && String(remote.stdout || "").trim().length > 0;
+}