@controlfront/detect 0.0.1

package/src/utils/buildFileChanges.js

@@ -0,0 +1,372 @@
+/**
+ * buildFileChanges.js
+ *
+ * Produce per-changed-file "file change rows" from the current snapshot's enriched changed_files.
+ *
+ * This is intentionally a PURE transform:
+ * - It does not read DB state.
+ * - It does not attempt to compute cross-commit sequencing (prev_idx/deltas).
+ *   Those can be computed later server-side (window functions) or in report queries.
+ *
+ * Output shape matches the `public.file_changes` table columns closely.
+ * 
+ * FIELD SEMANTICS:
+ * - idx: Per-commit index (0-based), stable within this commit's changed files
+ * - prev_idx: Cross-commit sequence (set server-side via window function)
+ * - lines_changed: Actual changed lines (from blame or diff stats)
+ * - change_size: Total magnitude (insertions + deletions)
+ * - insertions/deletions: Raw git diff stats
+ * - author_id: Current commit author (who is touching the file)
+ * - prev_top_author_id: Previous top author (whose code is being touched)
+ * - is_overwrite: True when prev_top_author_id differs from author_id
+ * 
+ * COMPUTED POST-INSERT (not in this transform):
+ * - changes_last_7_days, changes_last_30_days
+ * - unique_authors_last_30_days
+ * - days_since_last_change
+ * - avg_change_size_last_26_weeks
+ * - avg_weeks_between_changes
+ */
+
+function toIsoDate(value) {
+  if (!value) return null;
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return null;
+  return d.toISOString();
+}
+
+function pickPath(cf) {
+  return (
+    (cf && typeof cf.path === "string" && cf.path) ||
+    (cf && typeof cf.file === "string" && cf.file) ||
+    (cf && typeof cf.to === "string" && cf.to) ||
+    (cf && typeof cf.from === "string" && cf.from) ||
+    null
+  );
+}
+
+function safeNumber(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string") {
+    const s = v.trim();
+    if (!s) return null;
+    const n = Number(s);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function safePercentage(v) {
+  const n = safeNumber(v);
+  if (n === null) return null;
+  // Clamp to valid percentage range
+  return Math.max(0, Math.min(100, n));
+}
+
+function inferFileClass(path) {
+  if (!path || typeof path !== "string") return null;
+  const p = path.toLowerCase();
+
+  if (p.endsWith(".md") || p.endsWith(".mdx")) return "docs";
+  if (
+    p.includes("design-tokens") ||
+    p.includes("/tokens/") ||
+    p.endsWith(".tokens.json")
+  )
+    return "tokens";
+
+  if (
+    p.endsWith(".json") ||
+    p.endsWith(".yaml") ||
+    p.endsWith(".yml") ||
+    p.endsWith(".toml") ||
+    p.endsWith(".ini") ||
+    p.endsWith(".lock") ||
+    p.endsWith("package.json") ||
+    p.endsWith("tsconfig.json") ||
+    p.endsWith("eslint.config.js") ||
+    p.endsWith(".eslintrc") ||
+    p.endsWith(".eslintrc.js") ||
+    p.endsWith(".eslintrc.json") ||
+    p.endsWith(".prettierrc") ||
+    p.endsWith(".prettierrc.json") ||
+    p.endsWith(".prettierrc.js")
+  ) {
+    return "config";
+  }
+
+  if (p.endsWith(".tsx") || p.endsWith(".jsx")) return "ui";
+  if (p.endsWith(".ts") || p.endsWith(".js")) return "code";
+  
+  if (
+    p.endsWith(".css") ||
+    p.endsWith(".scss") ||
+    p.endsWith(".sass") ||
+    p.endsWith(".less") ||
+    p.endsWith(".styl")
+  ) {
+    return "style";
+  }
+
+  return null;
+}
+
+function pickDiffStats(cf) {
+  // Support a few possible shapes coming from enrichment.
+  const ds = cf?.diff_stats || cf?.diffStats || cf?.numstat || null;
+  const insertions = safeNumber(ds?.insertions ?? ds?.added ?? ds?.ins ?? null);
+  const deletions = safeNumber(ds?.deletions ?? ds?.removed ?? ds?.del ?? null);
+
+  // numstat can emit '-' for binary; represent that as nulls and diffStatsOk=false.
+  const binary =
+    ds?.insertions === "-" ||
+    ds?.deletions === "-" ||
+    ds?.added === "-" ||
+    ds?.removed === "-";
+
+  const diffStatsOk = !binary && (insertions !== null || deletions !== null);
+
+  return {
+    insertions,
+    deletions,
+    diffStatsOk,
+    changeSize:
+      insertions !== null || deletions !== null
+        ? (insertions || 0) + (deletions || 0)
+        : null,
+  };
+}
+
+function computeConfidence({
+  blameCoveragePct,
+  diffStatsOk,
+  linesChanged,
+  status,
+  isOverwrite,
+  prevTopAuthorPct,
+}) {
+  // Deterministic confidence model derived from a small set of observable signals.
+  // Intended meaning: "How reliable are the attribution + magnitude signals for this row?"
+  //
+  // Signals:
+  // - blameCoveragePct (primary)
+  // - diffStatsOk (supports magnitude, esp. config/lockfiles)
+  // - linesChanged (guards against M + 0)
+  // - overwrite strength (only when isOverwrite): depends on blame coverage + prev top author dominance
+  //
+  // RETURNS: float 0.0..1.0 (matches schema: confidence real)
+
+  const bc = safeNumber(blameCoveragePct); // accepts numeric-ish strings like "40.1"
+  const topPct = safeNumber(prevTopAuthorPct);
+  const lc = safeNumber(linesChanged);
+
+  // New files: attribution to commit author is reliable, but overwrite/prior-author signals are N/A.
+  if (status === "A") {
+    return 0.7;
+  }
+
+  let c = 0;
+
+  // blame coverage contribution (0..0.75)
+  if (bc === null) c += 0.05;
+  else if (bc >= 95) c += 0.75;
+  else if (bc >= 75) c += 0.6;
+  else if (bc >= 50) c += 0.45;
+  else if (bc > 0) c += 0.25;
+
+  // diff stats contribution (0..0.2)
+  if (diffStatsOk) c += 0.2;
+
+  // non-zero magnitude contribution (0..0.1)
+  if (lc !== null && lc > 0) c += 0.1;
+
+  // overwrite strength contribution (0..0.15)
+  // We only award this when we can actually judge overwrite with meaningful blame coverage.
+  // Strength increases when the previous top author dominated the changed lines.
+  if (isOverwrite) {
+    const validBc = safePercentage(blameCoveragePct);
+    const validTopPct = safePercentage(prevTopAuthorPct);
+    
+    if (validBc !== null && validBc > 0 && validTopPct !== null && validTopPct > 0) {
+      // Both values are already 0-100, calculate strength
+      const strength = (validTopPct / 100) * (validBc / 100);
+      c += 0.15 * strength;
+    }
+  }
+
+  // clamp 0..1
+  if (c < 0) c = 0;
+  if (c > 1) c = 1;
+  return c;
+}
+
+/**
+ * Infer overwrite vs previous author based on blame_stats for the change ranges.
+ * This matches the spirit of your current node model:
+ * - if we have meaningful blame coverage and a prev top author that differs from the commit author => overwrite.
+ */
+function computeOverwrite(cf, commitAuthorId) {
+  const blame = cf && cf.blame_stats ? cf.blame_stats : null;
+  const coverage = safePercentage(blame && blame.coverage_pct);
+  const top =
+    blame && blame.prev_authors && Array.isArray(blame.prev_authors.top)
+      ? blame.prev_authors.top[0]
+      : null;
+
+  const prevTopAuthorId =
+    top && typeof top.author_id === "string" ? top.author_id : null;
+  const prevTopAuthorPct = safePercentage(top && top.pct);
+
+  // Can only judge overwrite if:
+  // 1. We have blame coverage (file existed before)
+  // 2. We have a previous top author
+  // 3. We have a commit author to compare against
+  const canJudge =
+    coverage !== null && coverage > 0 && prevTopAuthorId && commitAuthorId;
+  const isOverwrite = !!(canJudge && prevTopAuthorId !== commitAuthorId);
+
+  return {
+    isOverwrite,
+    prevTopAuthorId,
+    prevTopAuthorPct,
+    blameCoveragePct: coverage,
+  };
+}
+
+/**
+ * Returns rows for insertion/upsert into public.file_changes
+ */
+export function buildFileChanges({ commit, changedFiles, snapshotId = null }) {
+  console.log("🧩 buildFileChanges:start");
+
+  if (!commit || !commit.timestamp) {
+    return [];
+  }
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return [];
+  }
+
+  const commitTsIso = toIsoDate(commit.timestamp);
+  if (!commitTsIso) {
+    return [];
+  }
+
+  const commitSha = (commit && commit.sha) || null;
+  const commitAuthorId =
+    (commit && typeof commit.author_id === "string" && commit.author_id) ||
+    (changedFiles[0] && changedFiles[0].commit_author_id) ||
+    null;
+
+  const rows = changedFiles
+    .map((cf, i) => {
+      const path = pickPath(cf);
+      if (!path) return null;
+
+      const status = typeof cf.status === "string" ? cf.status : null;
+
+      const { insertions, deletions, diffStatsOk, changeSize } = pickDiffStats(cf);
+
+      // For new files (status "A"), there's no previous version to blame
+      // For modified files, we may have blame_stats.lines_changed
+      const blameLines = safeNumber(cf?.blame_stats?.lines_changed);
+      
+      // lines_changed: represents the actual lines that changed in the file
+      // - For new files: prefer diff stats (total lines added)
+      // - For modified files: prefer blame stats (actual changed lines) when available
+      // - Fallback to diff stats sum, then cf.lines_changed
+      const linesChanged =
+        status === "A"
+          ? changeSize ?? safeNumber(cf?.lines_changed) ?? null
+          : blameLines ?? changeSize ?? safeNumber(cf?.lines_changed) ?? null;
+
+      const locFile =
+        safeNumber(cf?.indicators?.loc) ?? safeNumber(cf?.loc) ?? null;
+
+      // For new files, there is no previous author (isOverwrite will be false)
+      const {
+        isOverwrite,
+        prevTopAuthorId,
+        prevTopAuthorPct,
+        blameCoveragePct,
+      } = status === "A" 
+        ? { isOverwrite: false, prevTopAuthorId: null, prevTopAuthorPct: null, blameCoveragePct: null }
+        : computeOverwrite(cf, commitAuthorId);
+
+      const fileClass =
+        (cf && typeof cf.class === "string" && cf.class) ||
+        (cf && typeof cf.file_class === "string" && cf.file_class) ||
+        inferFileClass(path);
+
+      // Extract dependency information from enriched changed_files
+      const imports = Array.isArray(cf.imports) ? cf.imports : [];
+      const importedBy = Array.isArray(cf.imported_by) ? cf.imported_by : [];
+      const importCount = imports.length;
+      const importedByCount = importedBy.length;
+
+      // Minimal event typing at "single commit" granularity
+      const eventType = isOverwrite ? "overwrite" : "normal";
+
+      return {
+        // Core identification
+        path,
+        file_class: fileClass,
+        idx: i, // Per-commit index (0-based, stable within this commit)
+
+        // Commit context
+        snapshot_id: snapshotId,
+        commit_sha: commitSha || (cf && cf.commit_sha) || null,
+        commit_timestamp: commitTsIso,
+        author_id: (cf && cf.commit_author_id) || commitAuthorId || null, // Current commit author (touching)
+
+        // Change metadata
+        status, // Git status: A (added), M (modified), D (deleted), R (renamed)
+        lines_changed: linesChanged, // Semantic: actual changed lines (blame or diff)
+        insertions: insertions, // Raw git: lines inserted
+        deletions: deletions, // Raw git: lines deleted
+        change_size: changeSize ?? linesChanged, // Total magnitude (prefer ins+del, fallback to lines_changed)
+        diff_stats_ok: !!diffStatsOk, // True if diff stats are valid (not binary)
+
+        // File metrics
+        loc_file: locFile, // Lines of code in the file
+
+        // Attribution & blame
+        blame_coverage_pct: blameCoveragePct, // Percentage of changed lines with blame data (0-100)
+        blame_ok: blameCoveragePct !== null && blameCoveragePct > 0,
+        prev_top_author_id: prevTopAuthorId, // Previous top author (whose code is being touched)
+        prev_top_author_pct: prevTopAuthorPct, // % of changed lines owned by prev author (0-100)
+
+        // Derived signals
+        is_overwrite: isOverwrite, // True when prev_top_author_id differs from author_id
+        confidence: computeConfidence({
+          blameCoveragePct,
+          diffStatsOk: !!diffStatsOk,
+          linesChanged,
+          status,
+          isOverwrite,
+          prevTopAuthorPct,
+        }), // Confidence score 0.0-1.0
+
+        // Dependency tracking
+        imports: imports, // Array of file paths this file imports
+        imported_by: importedBy, // Array of file paths that import this file
+        import_count: importCount, // Number of imports (for quick queries)
+        imported_by_count: importedByCount, // Fan-in (how many files depend on this)
+
+        // Cross-commit sequencing (computed server-side via window functions)
+        prev_idx: null, // Index of previous change to this file
+        delta_lines_changed: null, // Change in lines_changed vs previous
+        delta_time_seconds: null, // Time delta vs previous change
+        author_changed: null, // True if author_id differs from previous
+
+        // Event classification
+        event_type: eventType, // "overwrite" | "normal" (can extend: "refactor", "cleanup", etc.)
+      };
+    })
+    .filter(Boolean);
+
+  console.log("🧩 buildFileChanges:end");
+
+  return rows;
+}
+
+export default buildFileChanges;