@dev-loops/core 0.1.0

package/src/debt/remediation-to-issue.mjs

@@ -0,0 +1,121 @@
+// ============================================================================
+// Remediation item → GitHub issue bridge
+//
+// Converts a shaped remediation_item into a GitHub issue via `gh issue create`
+// so the debt pipeline can feed into the existing dev-loop execution path.
+// ============================================================================
+
+import { execFileSync } from "node:child_process";
+import { RemediationItemSchema } from "./debt-finding.mjs";
+
+// ============================================================================
+// Payload builder
+// ============================================================================
+
+/**
+ * Convert a remediation_item artifact into a GitHub-issue-compatible payload
+ * with structured body, acceptance criteria, and debt labels.
+ *
+ * @param {object} remediationItem — RemediationItemSchema-valid artifact
+ * @returns {{ title: string, body: string, labels: string[] }}
+ */
+export function remediationToIssuePayload(remediationItem) {
+  const parsed = RemediationItemSchema.parse(remediationItem);
+  const acSection = parsed.acceptanceCriteria
+    .map((ac, i) => `${i + 1}. ${ac}`)
+    .join("\n");
+
+  const body = [
+    `## Remediation Item`,
+    ``,
+    `**Finding ID:** ${parsed.findingId}`,
+    `**Score:** ${parsed.score}`,
+    `**Primary file:** ${parsed.primaryFilePath || "N/A"}`,
+    ``,
+    `### Description`,
+    parsed.description,
+    ``,
+    `### Acceptance Criteria`,
+    acSection,
+    ``,
+    `### Source`,
+    `Generated by debt pipeline from ${parsed.signalIds.length} signal(s).`,
+  ].join("\n");
+
+  return {
+    title: parsed.title,
+    body,
+    labels: ["workflow"],
+  };
+}
+
+// ============================================================================
+// Error message extraction
+// ============================================================================
+
+/**
+ * Coerce an error's stderr into a string.
+ * gh may write a Buffer or Uint8Array when execFileSync throws.
+ */
+function errorMessage(err) {
+  if (typeof err.stderr === "string" && err.stderr.length > 0) {
+    return err.stderr.trim();
+  }
+  if (err.stderr && typeof err.stderr.toString === "function") {
+    const s = err.stderr.toString("utf-8").trim();
+    if (s.length > 0) return s;
+  }
+  if (err.message) return err.message;
+  return "gh issue create failed";
+}
+
+// ============================================================================
+// GitHub issue creation
+// ============================================================================
+
+/**
+ * Create a GitHub issue from a remediation_item artifact.
+ *
+ * Calls `gh issue create` with the generated payload. The issue is assigned
+ * to @me via --assignee.
+ *
+ * @param {object} remediationItem — RemediationItemSchema-valid artifact
+ * @param {{ owner: string, name: string }} repo — parsed repository identifier
+ * @returns {{ ok: true, issueNumber: number, issueUrl: string } | { ok: false, error: string }}
+ */
+export function createRemediationIssue(remediationItem, repo) {
+  const { title, body, labels } = remediationToIssuePayload(remediationItem);
+
+  try {
+    const args = [
+      "issue", "create",
+      "--title", title,
+      "--body", body,
+      "--assignee", "@me",
+      "--repo", `${repo.owner}/${repo.name}`,
+    ];
+
+    for (const label of labels) {
+      args.push("--label", label);
+    }
+
+    const result = execFileSync("gh", args, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    // gh issue create output is typically the issue URL, e.g.
+    // https://github.com/owner/name/issues/123
+    const url = result;
+    const match = url.match(/\/issues\/(\d+)/);
+    const issueNumber = match ? parseInt(match[1], 10) : null;
+
+    if (!issueNumber) {
+      return { ok: false, error: `Could not parse issue number from gh output: ${url}` };
+    }
+
+    return { ok: true, issueNumber, issueUrl: url };
+  } catch (err) {
+    return { ok: false, error: errorMessage(err) };
+  }
+}

package/src/debt/score.mjs

@@ -0,0 +1,127 @@
+// ============================================================================
+// Debt signal cluster scoring model
+//
+// Transforms a cluster of debt_signal objects into a numeric 0-100 score.
+//
+// Three dimensions:
+//   - Frequency: how many signals in the cluster, capped and normalized
+//   - Severity: average severity hint value from signal source metadata
+//   - Impact: blast-radius / churn-risk heuristic based on signal properties
+//
+// Guarantees:
+//   - Deterministic: same inputs → same score
+//   - Monotonicity: higher frequency/severity/impact → higher or equal score
+//   - Boundary handling: zero inputs, single-signal clusters, max clusters
+//
+// Severity mapping (canonical):
+//   info=1, low=2, medium=3, high=4, critical=5
+//
+// Weights are hardcoded constants in this slice; not configurable.
+// The formula is: score = frequencyScore * 0.35 + severityScore * 0.40 + impactScore * 0.25
+// clamped to 0-100.
+// ============================================================================
+
+/**
+ * Map a DebtSignalSeverity string to a numeric weight 1-5.
+ * Returns 1 for unrecognized values (defensive).
+ *
+ * @param {string} severityHint
+ * @returns {number}
+ */
+function severityWeight(severityHint) {
+  const map = { info: 1, low: 2, medium: 3, high: 4, critical: 5 };
+  return map[severityHint] ?? 1;
+}
+
+/**
+ * Compute the frequency score component (0-100).
+ * Uses a logarithmic cap so the first few signals matter most.
+ * 1 signal → 20, 3 signals → 58, 5 signals → 76, 10 signals → 100.
+ *
+ * @param {number} signalCount
+ * @returns {number}
+ */
+function frequencyScore(signalCount) {
+  if (signalCount <= 0) return 0;
+  if (signalCount === 1) return 20;
+  // Logarithmic scaling: 20 + 80 * log2(count) / log2(10), capped at 100
+  const raw = 20 + 80 * (Math.log2(signalCount) / Math.log2(10));
+  return Math.min(100, Math.round(raw));
+}
+
+/**
+ * Compute the severity score component (0-100).
+ * Average severity weight mapped: 1→20, 3→60, 5→100.
+ *
+ * @param {Array<{ severityHint: string }>} signals
+ * @returns {number}
+ */
+function severityScore(signals) {
+  if (signals.length === 0) return 0;
+  const total = signals.reduce((sum, s) => sum + severityWeight(s.severityHint), 0);
+  const avg = total / signals.length;
+  return Math.round(avg * 20); // 1..5 → 20..100
+}
+
+/**
+ * Compute the impact score component (0-100).
+ * Heuristic based on:
+ *   - file presence: signals with known file paths are more actionable (+30 base if any)
+ *   - confidence: average signal confidence boosts impact
+ *   - signalKind diversity: more unique categories = broader blast radius
+ * Returns 0 for empty clusters.
+ *
+ * @param {Array<{ location?: { filePath?: string }, confidence?: number, signalKind?: string }>} signals
+ * @returns {number}
+ */
+function impactScore(signals) {
+  if (signals.length === 0) return 0;
+
+  let score = 0;
+
+  // File presence: +30 if any signal has a file path
+  const hasFilePath = signals.some(s => s.location?.filePath);
+  if (hasFilePath) score += 30;
+
+  // Confidence boost: average confidence * 40
+  const confidences = signals.map(s => s.confidence ?? 1);
+  const avgConfidence = confidences.reduce((a, b) => a + b, 0) / confidences.length;
+  score += Math.round(avgConfidence * 40);
+
+  // Category diversity: unique signalKinds * 5, capped at 30
+  const uniqueKinds = new Set(signals.map(s => s.signalKind).filter(Boolean));
+  const diversityBonus = Math.min(30, uniqueKinds.size * 5);
+  score += diversityBonus;
+
+  return Math.min(100, score);
+}
+
+/**
+ * Weight constant — keeps module self-documenting and testable.
+ * @type {{ frequency: number, severity: number, impact: number }}
+ */
+export const SCORE_WEIGHTS = Object.freeze({
+  frequency: 0.35,
+  severity: 0.40,
+  impact: 0.25,
+});
+
+/**
+ * Score a cluster of debt_signal objects.
+ *
+ * @param {Array<{ severityHint: string, location?: { filePath?: string }, confidence?: number, signalKind?: string }>} signals — array of debt_signal-compatible objects
+ * @returns {number} integer score 0-100
+ */
+export function scoreCluster(signals) {
+  if (!Array.isArray(signals) || signals.length === 0) return 0;
+
+  const freq = frequencyScore(signals.length);
+  const sev = severityScore(signals);
+  const imp = impactScore(signals);
+
+  const raw = freq * SCORE_WEIGHTS.frequency +
+              sev * SCORE_WEIGHTS.severity +
+              imp * SCORE_WEIGHTS.impact;
+
+  return Math.min(100, Math.max(0, Math.round(raw)));
+}

package/src/debt/shape.mjs

@@ -0,0 +1,214 @@
+// ============================================================================
+// Debt finding shaping rules
+//
+// Turns each scored debt_finding into exactly one outcome:
+//   - remediation_item: bounded, PR-sized fix with clear acceptance criteria
+//   - debt_epic: cross-cutting, needs decomposition before execution
+//   - defer: acknowledged, scheduled for future review
+//   - watch: low confidence, needs more signals before action
+//   - dismiss: false positive or already fixed
+//
+// Thresholds are hardcoded constants in this slice; not configurable.
+// Exported for contract tests that verify predicate boundaries.
+//
+// Actionable outcomes (remediation_item, debt_epic) are gated on having
+// at least one filePath. Theme-only clusters without file paths are
+// downgraded to watch regardless of score.
+// ============================================================================
+
+// ============================================================================
+// Threshold constants
+// ============================================================================
+
+/** Score >= ITEM_THRESHOLD → eligible for remediation_item or debt_epic */
+export const ITEM_THRESHOLD = 65;
+
+/** Score >= DEFER_THRESHOLD → defer */
+export const DEFER_THRESHOLD = 50;
+
+/** Score >= WATCH_THRESHOLD → watch */
+export const WATCH_THRESHOLD = 30;
+
+/** Below WATCH_THRESHOLD → dismiss */
+
+/** Signals above this count → debt_epic (even with score >= ITEM_THRESHOLD) */
+export const EPIC_SIGNAL_COUNT_THRESHOLD = 3;
+
+// ============================================================================
+// Shape outcome
+// ============================================================================
+
+/** @typedef {"remediation_item"|"debt_epic"|"defer"|"watch"|"dismiss"} ShapeOutcome */
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Deterministic epoch constant for timestamp fallback.
+ * "1970-01-01T00:00:00.000Z"
+ */
+const EPOCH_TS = "1970-01-01T00:00:00.000Z";
+
+/**
+ * Pass through finding timestamps. Falls back to epoch when finding
+ * timestamps are missing — never uses wall-clock time.
+ *
+ * @param {object} finding — enriched debt_finding with createdAt/updatedAt
+ * @returns {{ createdAt: string, updatedAt: string }}
+ */
+function deriveTimestamps(finding) {
+  return {
+    createdAt: finding.createdAt || EPOCH_TS,
+    updatedAt: finding.updatedAt || finding.createdAt || EPOCH_TS,
+  };
+}
+
+/**
+ * Check whether a finding has actionable file paths.
+ *
+ * @param {object} finding — enriched debt_finding
+ * @returns {boolean}
+ */
+function hasFilePaths(finding) {
+  const paths = finding.locationSummary?.filePaths;
+  return Array.isArray(paths) && paths.length > 0;
+}
+
+// ============================================================================
+// Pure predicate: classify a finding into a shape outcome
+// ============================================================================
+
+/**
+ * Determine the shape outcome for a debt_finding.
+ * Actionable outcomes (remediation_item, debt_epic) require at least
+ * one filePath; theme-only clusters without file paths are downgraded
+ * to watch.
+ *
+ * @param {object} finding — debt_finding shape with at least { score, _signalCount, signalIds }
+ * @returns {ShapeOutcome}
+ */
+function classifyShape(finding) {
+  const score = finding.score ?? 0;
+  const signalCount = finding._signalCount ?? (finding.signalIds?.length ?? 1);
+
+  if (score >= ITEM_THRESHOLD && hasFilePaths(finding)) {
+    return signalCount > EPIC_SIGNAL_COUNT_THRESHOLD ? "debt_epic" : "remediation_item";
+  }
+  if (score >= ITEM_THRESHOLD) {
+    // High score but no file paths — downgrade to watch
+    return "watch";
+  }
+  if (score >= DEFER_THRESHOLD) return "defer";
+  if (score >= WATCH_THRESHOLD) return "watch";
+  return "dismiss";
+}
+
+// ============================================================================
+// Artifact builders
+// ============================================================================
+
+/**
+ * Build a remediation_item artifact from a finding.
+ * Uses structured _categories from the cluster.
+ *
+ * @param {object} finding — enriched debt_finding with _categories array
+ * @returns {object} RemediationItemSchema-compatible shape
+ */
+function buildRemediationItem(finding) {
+  const cats = (finding._categories && finding._categories.length > 0)
+    ? finding._categories.join(", ")
+    : "unknown";
+  const { createdAt, updatedAt } = deriveTimestamps(finding);
+  return {
+    kind: "remediation_item",
+    findingId: finding.id,
+    title: finding.title,
+    description: finding.description || `Remediation for finding ${finding.id}`,
+    acceptanceCriteria: [
+      `Address ${cats} issues in affected files`,
+      `Verify no regression in existing test suite`,
+      `Maintain >= 90% coverage`,
+    ],
+    score: finding.score ?? 0,
+    primaryFilePath: finding.locationSummary?.primaryFilePath,
+    filePaths: finding.locationSummary?.filePaths,
+    signalIds: finding.signalIds,
+    sourceType: "debt_pipeline",
+    createdAt,
+    updatedAt,
+  };
+}
+
+/**
+ * Build a debt_epic artifact from a finding.
+ *
+ * @param {object} finding — enriched debt_finding
+ * @returns {object} DebtEpicSchema-compatible shape
+ */
+function buildDebtEpic(finding) {
+  const { createdAt, updatedAt } = deriveTimestamps(finding);
+  return {
+    kind: "debt_epic",
+    findingId: finding.id,
+    title: finding.title,
+    description: finding.description || `Epic for finding ${finding.id}`,
+    score: finding.score ?? 0,
+    filePaths: finding.locationSummary?.filePaths,
+    signalIds: finding.signalIds,
+    estimatedItems: Math.ceil((finding._signalCount ?? 1) / 2),
+    createdAt,
+    updatedAt,
+  };
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Shape a single enriched finding into its outcome.
+ *
+ * Returns an object with { outcome, artifact } where artifact is defined
+ * for remediation_item and debt_epic outcomes, and null for defer/watch/dismiss.
+ *
+ * @param {object} finding — enriched debt_finding (with _signalCount)
+ * @returns {{ outcome: ShapeOutcome, artifact: object|null }}
+ */
+export function shapeFinding(finding) {
+  const outcome = classifyShape(finding);
+
+  let artifact = null;
+  if (outcome === "remediation_item") {
+    artifact = buildRemediationItem(finding);
+  } else if (outcome === "debt_epic") {
+    artifact = buildDebtEpic(finding);
+  }
+
+  return { outcome, artifact };
+}
+
+/**
+ * Shape an array of enriched findings, returning the outcome + artifact for each.
+ *
+ * @param {Array<object>} findings — enriched debt_finding array
+ * @returns {Array<{ outcome: ShapeOutcome, artifact: object|null, findingId: string }>}
+ */
+export function shapeFindings(findings) {
+  return findings.map(f => {
+    const { outcome, artifact } = shapeFinding(f);
+    return { outcome, artifact, findingId: f.id };
+  });
+}
+
+/**
+ * Run the full pipeline: cluster → score → shape, return shaped artifacts.
+ *
+ * @param {Array<object>} signals — debt_signal-compatible array
+ * @returns {Array<{ outcome: ShapeOutcome, artifact: object|null, findingId: string }>}
+ */
+export async function runPipeline(signals) {
+  const { clusterSignalsEnriched } = await import("./cluster.mjs");
+  const findings = clusterSignalsEnriched(signals);
+  return shapeFindings(findings);
+}