@archora/core 1.1.0

package/src/git/computeTemporalCoupling.ts

@@ -0,0 +1,114 @@
+// Temporal coupling detector.
+//
+// Two modules are "temporally coupled" when they consistently change in the
+// same commit. We compute a symmetric score:
+//
+//   coupling(a, b) = min( cooccurrences / commits(a),
+//                         cooccurrences / commits(b) )
+//
+// Using `min` instead of `max` (or asymmetric scores) keeps the metric
+// conservative: if `a` changes 100 times and `b` only 5 times, and they
+// always co-change, the score isn't 100% (which the asymmetric view would
+// suggest) — it's 0.05 in the `a` direction. We surface only pairs where
+// BOTH directions agree, which is what `min` captures.
+//
+// We skip mass-edit commits (lockfile bumps, format-everything PRs) because
+// every pair in such a commit gets a free co-occurrence which dilutes the
+// signal.
+
+import type { GitHistory, TemporalCoupling, TemporalCouplingThresholds } from './types';
+import type { DependencyEdge, ModuleNode } from '../analyzer/types';
+
+export interface ComputeTemporalCouplingInput {
+  modules: ModuleNode[];
+  edges: DependencyEdge[];
+  history: GitHistory;
+  thresholds?: TemporalCouplingThresholds;
+}
+
+const DEFAULTS: Required<TemporalCouplingThresholds> = {
+  minCoOccurrences: 3,
+  minScore: 0.5,
+  maxPairs: 100,
+  commitFanOutCap: 50,
+};
+
+export function computeTemporalCoupling(input: ComputeTemporalCouplingInput): TemporalCoupling[] {
+  const t = { ...DEFAULTS, ...(input.thresholds ?? {}) };
+  const moduleIds = new Set(input.modules.map((m) => m.id));
+
+  const commitsByModule = new Map<string, number>();
+  // Pair key = `${a}\x00${b}` with a < b lexically.
+  const coOccurrences = new Map<string, number>();
+
+  for (const commit of input.history.commits) {
+    const touched = collectTouchedModules(commit, moduleIds);
+    if (touched.length === 0) continue;
+    if (touched.length > t.commitFanOutCap) continue;
+    for (const m of touched) {
+      commitsByModule.set(m, (commitsByModule.get(m) ?? 0) + 1);
+    }
+    // Pair contribution. `touched` is sorted in `collectTouchedModules`.
+    for (let i = 0; i < touched.length; i++) {
+      for (let j = i + 1; j < touched.length; j++) {
+        const key = `${touched[i]}\x00${touched[j]}`;
+        coOccurrences.set(key, (coOccurrences.get(key) ?? 0) + 1);
+      }
+    }
+  }
+
+  const staticPairs = collectStaticPairs(input.edges);
+  const out: TemporalCoupling[] = [];
+  for (const [key, n] of coOccurrences) {
+    if (n < t.minCoOccurrences) continue;
+    const sep = key.indexOf('\x00');
+    const a = key.slice(0, sep);
+    const b = key.slice(sep + 1);
+    const ca = commitsByModule.get(a);
+    const cb = commitsByModule.get(b);
+    if (!ca || !cb) continue;
+    const scoreA = n / ca;
+    const scoreB = n / cb;
+    const score = Math.min(scoreA, scoreB);
+    if (score < t.minScore) continue;
+    const hidden = !staticPairs.has(key);
+    out.push({ a, b, coOccurrences: n, scoreA, scoreB, score, hidden });
+  }
+
+  // Hidden couplings first (most informative), then by score, then by
+  // co-occurrences, then alphabetically — stable across runs.
+  out.sort((x, y) => {
+    if (x.hidden !== y.hidden) return x.hidden ? -1 : 1;
+    if (y.score !== x.score) return y.score - x.score;
+    if (y.coOccurrences !== x.coOccurrences) return y.coOccurrences - x.coOccurrences;
+    return x.a.localeCompare(y.a) || x.b.localeCompare(y.b);
+  });
+
+  if (out.length > t.maxPairs) out.length = t.maxPairs;
+  return out;
+}
+
+function collectTouchedModules(
+  commit: GitHistory['commits'][number],
+  validIds: Set<string>,
+): string[] {
+  const touched = new Set<string>();
+  for (const change of commit.changes) {
+    if (validIds.has(change.path)) touched.add(change.path);
+    if (change.renamedFrom && validIds.has(change.renamedFrom)) {
+      touched.add(change.renamedFrom);
+    }
+  }
+  return [...touched].sort();
+}
+
+function collectStaticPairs(edges: DependencyEdge[]): Set<string> {
+  const out = new Set<string>();
+  for (const e of edges) {
+    if (e.from === e.to) continue;
+    const a = e.from < e.to ? e.from : e.to;
+    const b = e.from < e.to ? e.to : e.from;
+    out.add(`${a}\x00${b}`);
+  }
+  return out;
+}

package/src/git/index.ts

@@ -0,0 +1,24 @@
+// Git barrel. Node-only consumers (CLI, scripts) can import the
+// entire module; browser bundles only ever pull `parseGitLog` / `computeChurn`
+// (pure, no `node:*`) via deep imports if needed.
+
+export type {
+  ChurnAuthor,
+  ChurnByModule,
+  ChurnMetric,
+  GitCommit,
+  GitFileChange,
+  GitHistory,
+} from './types';
+export { parseGitLog, expandRename } from './parseGitLog';
+export { computeChurn, type ComputeChurnInput } from './computeChurn';
+export {
+  computeTemporalCoupling,
+  type ComputeTemporalCouplingInput,
+} from './computeTemporalCoupling';
+export {
+  readGitHistory,
+  expandSince,
+  GitNotAvailableError,
+  type ReadGitHistoryOptions,
+} from './readGitHistory';

package/src/git/parseGitLog.ts

@@ -0,0 +1,124 @@
+// Pure parser for the output of:
+//
+//   git log --no-merges --numstat --date=iso-strict \
+//           --pretty=format:'__FS_COMMIT__%x01%H%x01%h%x01%aN%x01%aE%x01%aI%x01%s'
+//
+// We use a sentinel (`__FS_COMMIT__`) at the start of each commit's header
+// line so we can split the output without worrying about newlines in
+// subjects (`%s` is single-line by definition, but renames in --numstat
+// without `-z` produce path strings of the form "{old => new}" which we
+// handle directly).
+//
+// Each commit yields:
+//
+//   __FS_COMMIT__<SOH>sha<SOH>short<SOH>name<SOH>email<SOH>date<SOH>subject\n
+//   <numstat>\t<numstat>\t<path>\n           (zero or more)
+//   ...
+
+import type { GitCommit, GitFileChange } from './types';
+
+const COMMIT_SENTINEL = '__FS_COMMIT__';
+const HEADER_SEP = '\x01';
+const NUMSTAT_RE = /^(\d+|-)\t(\d+|-)\t(.+)$/u;
+
+export function parseGitLog(raw: string): GitCommit[] {
+  if (!raw) return [];
+  const out: GitCommit[] = [];
+  // Split on the sentinel; the first segment is empty (raw starts with it).
+  const segments = raw.split(COMMIT_SENTINEL);
+  for (const segment of segments) {
+    if (!segment) continue;
+    const newlineIdx = segment.indexOf('\n');
+    const headerLine = newlineIdx === -1 ? segment : segment.slice(0, newlineIdx);
+    const header = parseHeader(headerLine);
+    if (!header) continue;
+    const changes: GitFileChange[] = [];
+    if (newlineIdx !== -1) {
+      const tail = segment.slice(newlineIdx + 1);
+      for (const line of tail.split('\n')) {
+        if (!line) continue;
+        const change = parseNumstatLine(line);
+        if (change) changes.push(change);
+      }
+    }
+    out.push({ ...header, changes });
+  }
+  return out;
+}
+
+interface ParsedHeader {
+  sha: string;
+  shortSha: string;
+  authorName: string;
+  author: string;
+  authoredAt: string;
+  subject: string;
+}
+
+function parseHeader(line: string): ParsedHeader | null {
+  // Leading HEADER_SEP comes from the `%x01` in the format string after the
+  // sentinel. Trim it and split.
+  const trimmed = line.startsWith(HEADER_SEP) ? line.slice(1) : line;
+  const parts = trimmed.split(HEADER_SEP);
+  if (parts.length < 6) return null;
+  const [sha, shortSha, authorName, email, authoredAt, ...rest] = parts;
+  if (!sha || sha.length < 7) return null;
+  return {
+    sha,
+    shortSha: shortSha ?? sha.slice(0, 7),
+    authorName: authorName ?? '',
+    author: (email ?? '').toLowerCase(),
+    authoredAt: authoredAt ?? '',
+    subject: rest.join(HEADER_SEP),
+  };
+}
+
+const RENAME_PATH_RE = /^(.*)\{([^{}]*?)\s*=>\s*([^{}]*?)\}(.*)$/u;
+
+function parseNumstatLine(line: string): GitFileChange | null {
+  const m = NUMSTAT_RE.exec(line);
+  if (!m) return null;
+  const rawPath = m[3]!;
+  const added = m[1] === '-' ? null : Number(m[1]);
+  const removed = m[2] === '-' ? null : Number(m[2]);
+  // Rename: "src/old/file.ts => src/new/file.ts" or "src/{old => new}/file.ts".
+  if (rawPath.includes(' => ')) {
+    const expanded = expandRename(rawPath);
+    if (expanded) {
+      return { path: expanded.to, renamedFrom: expanded.from, added, removed };
+    }
+  }
+  return { path: rawPath, added, removed };
+}
+
+interface ExpandedRename {
+  from: string;
+  to: string;
+}
+
+export function expandRename(spec: string): ExpandedRename | null {
+  const braced = RENAME_PATH_RE.exec(spec);
+  if (braced) {
+    const [, prefix = '', oldPart = '', newPart = '', suffix = ''] = braced;
+    const from = collapseSlashes(`${prefix}${oldPart}${suffix}`);
+    const to = collapseSlashes(`${prefix}${newPart}${suffix}`);
+    if (!from || !to) return null;
+    return { from, to };
+  }
+  // Whole-path rename: "old/path => new/path".
+  const arrowIdx = spec.indexOf(' => ');
+  if (arrowIdx !== -1) {
+    return {
+      from: spec.slice(0, arrowIdx),
+      to: spec.slice(arrowIdx + ' => '.length),
+    };
+  }
+  return null;
+}
+
+function collapseSlashes(p: string): string {
+  // Brace expansions like `src/{ => new}/foo.ts` produce `src//foo.ts` — fold
+  // doubled slashes that result from empty segments. We preserve a single
+  // leading slash if it was present.
+  return p.replace(/\/+/gu, '/');
+}

package/src/git/readGitHistory.ts

@@ -0,0 +1,130 @@
+// Node-only thin wrapper around `git log`. Browsers can't shell out, so this
+// module is imported lazily by Node consumers (CLI, optional Tauri bridge).
+// Keeping the spawn isolated here means `parseGitLog` and `computeChurn`
+// stay pure and trivially testable.
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseGitLog } from './parseGitLog';
+import type { GitHistory } from './types';
+
+export interface ReadGitHistoryOptions {
+  /** Repo root. We require `<root>/.git` to exist. */
+  rootPath: string;
+  /** Lookback window. Either a parseable git `--since` string ("90 days ago",
+   *  ISO date) or a relative shorthand we expand: "90d", "12w", "6m", "1y". */
+  since?: string;
+  /**
+   * Hard cap on commits, applied by git via `--max-count`. 0/undefined means
+   * no cap. Useful on monorepos where 90 days = 50k commits and parsing eats
+   * memory.
+   */
+  maxCommits?: number;
+  /** Include merge commits? Default: false. Merges inflate temporal coupling
+   *  noise without adding signal for Archora. */
+  includeMerges?: boolean;
+  /** Override the git executable (mostly for tests/CI). */
+  gitBin?: string;
+}
+
+const DEFAULT_SINCE = '90d';
+
+const FORMAT = '__FS_COMMIT__\x01%H\x01%h\x01%aN\x01%aE\x01%aI\x01%s';
+
+export class GitNotAvailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GitNotAvailableError';
+  }
+}
+
+/**
+ * Run `git log` against `rootPath` and parse the output. Throws
+ * `GitNotAvailableError` when the path is not a git repo or git is missing.
+ * All other errors propagate as-is.
+ */
+export async function readGitHistory(options: ReadGitHistoryOptions): Promise<GitHistory> {
+  const { rootPath } = options;
+  if (!existsSync(join(rootPath, '.git'))) {
+    throw new GitNotAvailableError(`Not a git repository: ${rootPath}`);
+  }
+  const since = expandSince(options.since ?? DEFAULT_SINCE);
+  const args: string[] = [
+    'log',
+    '--no-merges',
+    '--numstat',
+    '--date=iso-strict',
+    `--pretty=format:${FORMAT}`,
+    `--since=${since}`,
+  ];
+  if (options.includeMerges) {
+    // Replace `--no-merges` with nothing.
+    const idx = args.indexOf('--no-merges');
+    if (idx !== -1) args.splice(idx, 1);
+  }
+  if (options.maxCommits && options.maxCommits > 0) {
+    args.push(`--max-count=${options.maxCommits}`);
+  }
+
+  const stdout = await runGit(options.gitBin ?? 'git', args, rootPath);
+  const commits = parseGitLog(stdout);
+  const until = new Date().toISOString();
+  return {
+    since,
+    until,
+    commits,
+    includesMerges: !!options.includeMerges,
+  };
+}
+
+const SHORTHAND_RE = /^(\d+)([dwmy])$/u;
+
+export function expandSince(input: string): string {
+  const m = SHORTHAND_RE.exec(input.trim());
+  if (!m) return input;
+  const n = Number(m[1]);
+  switch (m[2]) {
+    case 'd':
+      return `${n} days ago`;
+    case 'w':
+      return `${n} weeks ago`;
+    case 'm':
+      return `${n} months ago`;
+    case 'y':
+      return `${n} years ago`;
+    default:
+      return input;
+  }
+}
+
+function runGit(gitBin: string, args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(gitBin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (err) => {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') {
+        reject(new GitNotAvailableError(`git executable not found (tried "${gitBin}").`));
+        return;
+      }
+      reject(err);
+    });
+    child.on('close', (exit) => {
+      if (exit !== 0) {
+        reject(new Error(`git log failed (exit ${exit}): ${stderr.trim() || 'unknown error'}`));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}

package/src/git/types.ts

@@ -0,0 +1,119 @@
+// Git history types.
+//
+// Archora reads `git log` once per scan and feeds the result into the
+// analyzer as `AnalyzeOptions.gitHistory`. Everything in this file is plain
+// data: no IO, no Node dependencies. The reader (`readGitHistory.ts`) and
+// the parser (`parseGitLog.ts`) hydrate these shapes.
+
+import type { ModuleId } from '../analyzer/types';
+
+export interface GitCommit {
+  /** Full SHA. */
+  sha: string;
+  /** Short SHA, first 7 chars by convention. Stored alongside `sha` so callers
+   *  don't have to recompute. */
+  shortSha: string;
+  /** Author email (lowercased on read for stable grouping). */
+  author: string;
+  /** Author display name as written in the commit. */
+  authorName: string;
+  /** ISO-8601 timestamp of the author date (commit date is ignored — author
+   *  date survives rebase/cherry-pick which is what we want for churn). */
+  authoredAt: string;
+  subject: string;
+  /**
+   * Files changed by this commit, normalized to repo-root-relative paths
+   * with `/` separators. Renames are recorded as the new path; the old path
+   * is in `renamedFrom`.
+   */
+  changes: GitFileChange[];
+}
+
+export interface GitFileChange {
+  path: string;
+  /** Renames record the previous path here. Otherwise undefined. */
+  renamedFrom?: string;
+  /** Lines added in this file in this commit. `null` for binary changes. */
+  added: number | null;
+  /** Lines removed in this file in this commit. `null` for binary. */
+  removed: number | null;
+}
+
+export interface GitHistory {
+  /** Range covered by this history. */
+  since: string; // ISO date string
+  until: string; // ISO date string
+  /** Commits in reverse-chronological order. */
+  commits: GitCommit[];
+  /** Inclusive of merges? Reader filters merges by default; surface here so
+   *  consumers know what they're looking at. */
+  includesMerges: boolean;
+}
+
+/**
+ * Per-module churn aggregate. Computed by `computeChurn` from `GitHistory`
+ * once we know which paths map to which `ModuleId`s.
+ */
+export interface ChurnMetric {
+  moduleId: ModuleId;
+  /** Number of commits that touched this module in the window. */
+  commits: number;
+  /** Sum of `added + removed`, ignoring binary files. */
+  linesChanged: number;
+  /** Number of distinct authors. */
+  authorCount: number;
+  /** ISO timestamp of the most recent commit touching this module. */
+  lastTouchedAt: string;
+  /** Author distribution sorted by commit count desc, then alphabetic.
+   *  Capped at top 5; remaining authors collapsed into a single
+   *  `{ author: '__other__', commits: N }` entry when present. */
+  authors: ChurnAuthor[];
+}
+
+export interface ChurnAuthor {
+  author: string;
+  commits: number;
+}
+
+/** Aggregate keyed by `ModuleId`. Modules with zero touches are omitted. */
+export type ChurnByModule = Record<ModuleId, ChurnMetric>;
+
+/**
+ * One pair of modules that change together more often than baseline.
+ * The pair is ordered (`a < b` lexically) so a coupling is unique
+ * by `${a}\0${b}`.
+ */
+export interface TemporalCoupling {
+  a: ModuleId;
+  b: ModuleId;
+  /** Commits that touched both `a` and `b`. */
+  coOccurrences: number;
+  /** `coOccurrences / commits(a)`. */
+  scoreA: number;
+  /** `coOccurrences / commits(b)`. */
+  scoreB: number;
+  /** `min(scoreA, scoreB)` — the symmetric, conservative score. Sorting key. */
+  score: number;
+  /**
+   * True when there is no static import edge between `a` and `b` in either
+   * direction. These are the "surprising" couplings — the actually
+   * informative ones, because the static graph already exposes the rest.
+   */
+  hidden: boolean;
+}
+
+export interface TemporalCouplingThresholds {
+  /** Minimum co-occurrences required to consider a pair. Default 3. */
+  minCoOccurrences?: number;
+  /** Minimum `score` (symmetric) to surface. Default 0.5 — at least 50% of
+   *  the rarer module's commits also touched the other. */
+  minScore?: number;
+  /** Hard cap on emitted pairs. Default 100. */
+  maxPairs?: number;
+  /**
+   * Per-commit fan-out cap: commits that touch more than this many files
+   * are skipped (mass renames, lockfile bumps, format-everything passes).
+   * Default 50.
+   */
+  commitFanOutCap?: number;
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+export { analyze, type AnalyzeOptions, type FileSource } from './analyzer/index';
+export {
+  buildArchitectureSignals,
+  applySignalSuppressions,
+  canSignalFailCi,
+  projectSignalsToRecommendations,
+  reconcileSignalLifecycle,
+  type ApplySignalSuppressionsResult,
+  type BuildArchitectureSignalsInput,
+  type BuildArchitectureSignalsResult,
+  type CanSignalFailCiOptions,
+  type ReconcileSignalLifecycleResult,
+} from './analyzer/index';
+// NOTE: cache module is intentionally NOT re-exported from this barrel.
+// `cache/index.ts` imports `node:crypto` / `node:fs` / `node:v8` / `node:os`
+// at the top level - including it here would force Vite to externalize those
+// for browser builds and throw at runtime as soon as anything in the front-end
+// touches `@/core` (barrel imports cascade into every re-export, even unused
+// ones). Node-side consumers (CLI, scripts) import directly from
+// `@archora/core/cache` via the package's `exports` map.
+export type * from './analyzer/types';
+export {
+  buildJsonReport,
+  type ReportEnvelope,
+  type BuildReportOptions,
+} from './report/buildJsonReport';
+export {
+  buildFixPlan,
+  type FixPlanReport,
+  type FixPlanFinding,
+  type FixPlanRepairGroup,
+  type BuildFixPlanOptions,
+} from './report/buildFixPlan';
+export { diffScans, type ScanDiff, type ChangedModule, type ScanDiffSummary } from './diff/index';
+export { compileGlob } from './analyzer/discover';
+export {
+  loadArchoraConfig,
+  loadArchoraConfigWithDiagnostics,
+  resolveGeneratedPatterns,
+  GENERATED_PRESETS,
+  type ArchoraConfig,
+  type ConfigDiagnostic,
+  type ConfigDiagnosticSeverity,
+  type LoadArchoraConfigResult,
+  type DynamicLoaderConfig,
+  type AnalysisConfig,
+  type ArchitectureBudgetConfig,
+  type GeneratedPolicy,
+  type GeneratedPreset,
+} from './config/frontScopeConfig';
+export {
+  detectLayer,
+  detectLayerViolations,
+  recomputeLayers,
+  validateLayerOverride,
+  LAYER_ORDER,
+  type Layer,
+  type LayerOverrides,
+  type LayerOverrideError,
+  type RecomputeLayersInput,
+  type RecomputeLayersOutput,
+} from './analyzer/layers';
+export {
+  search,
+  parseQuery,
+  isEmpty as isEmptyQuery,
+  type SearchResult,
+  type SearchOptions,
+  type MatchKind,
+  type SearchPrefix,
+  type ParsedQuery,
+} from './search/index';
+export {
+  suggestContracts,
+  type SuggestContractsInput,
+  type SuggestedContracts,
+} from './analyzer/suggestContracts';
+// Git history. Same pattern as `cache`: the Node-only
+// `readGitHistory` lives in `./git/readGitHistory` and must NOT be
+// re-exported from this barrel (it imports `node:child_process` and would
+// break browser bundles). Pure helpers are safe — they import only types.
+export { parseGitLog, expandRename } from './git/parseGitLog';
+export { computeChurn, type ComputeChurnInput } from './git/computeChurn';
+export {
+  computeTemporalCoupling,
+  type ComputeTemporalCouplingInput,
+} from './git/computeTemporalCoupling';
+export {
+  buildGeneratedConfigSnippet,
+  buildIgnoreSnippet,
+  buildLayerOverrideSnippet,
+  buildDynamicLoaderSnippet,
+  buildProjectPolicyPresetSnippet,
+  type ProjectPolicyPreset,
+} from './codegen/configSnippets';
+export {
+  buildInitialArchoraConfig,
+  buildInitialArchoraConfigJson,
+  type BuildInitialArchoraConfigInput,
+  type InitialArchoraConfigResult,
+  type InitialArchoraDetection,
+} from './codegen/initConfig';
+export {
+  buildExplainView,
+  buildImpactView,
+  buildLifecycleHygieneView,
+  buildMatrixView,
+  buildOwnershipView,
+  buildReviewRiskView,
+  buildSemanticSurfaceView,
+  buildSignalBaselineView,
+  buildTrendView,
+  countBaselineSignals,
+  findModuleMatches,
+  resolveImpactTarget,
+  type BuildMatrixViewOptions,
+  type GuidedReviewAction,
+  type ExplainCycleDetails,
+  type ExplainCycleEdge,
+  type ExplainView,
+  type ImpactView,
+  type LifecycleHygieneItem,
+  type LifecycleHygieneView,
+  type LifecycleRiskModule,
+  type MatrixCell,
+  type MatrixEdge,
+  type MatrixGrouping,
+  type MatrixView,
+  type OwnershipArea,
+  type OwnershipView,
+  type ReviewRiskView,
+  type SemanticSurfaceModule,
+  type SemanticSurfaceView,
+  type SideEffectOwner,
+  type SignalBaselineView,
+  type TrendView,
+} from './views/analyzerViews';