circle-ir-ai 2.21.0 → 2.26.0

package/dist/cache/verify-cache.js

@@ -0,0 +1,103 @@
+/**
+ * Verify Cache
+ *
+ * Persistent on-disk cache for LLM verification batch results
+ * (cognium-ai#152, P1 of epic #155). Sits in front of the in-memory
+ * `_verifierDedupCache` from verification.ts (#138 step 3) so that
+ * identical `(file SHA, pair-set)` requests survive across processes,
+ * CI runs, and developer iterations — not just within one process.
+ *
+ * Built on top of `ClassificationCache<BatchVerificationResult>` (which
+ * already carries the cognium-ai#151 model-fingerprint key dimension),
+ * with verify-specific key construction:
+ *
+ *   content    = SHA-256(code) + '\\0' + pairsFingerprint
+ *   classifier = 'verify-batch'
+ *   fingerprint = getPhaseModelFingerprint(config)  // includes verify model
+ *
+ * Cache directory: `.cognium/cache/verify/` (separate from the
+ * discovery-phase `.cognium/cache/` so a `rm -rf .cognium/cache/verify/`
+ * only nukes verifier entries).
+ *
+ * Invalidation matrix (acceptance criteria #152):
+ *   - Edit one file in a project   → only that file's entries invalidate
+ *     (file SHA-256 is part of the cache content key)
+ *   - Add a new sink to the engine → existing entries still hit if the
+ *     new sink doesn't change the pair-set for that file
+ *   - Change verification model    → entire cache invalidates
+ *     (model fingerprint is part of the singleton key)
+ *
+ * Env toggles:
+ *   LLM_VERIFY_CACHE=0  → disable persistent verify cache (in-memory
+ *                         dedup from #138 still applies)
+ */
+import * as crypto from 'crypto';
+import * as path from 'path';
+import { ClassificationCache } from './classification-cache.js';
+import { getDefaultLLMConfig, getPhaseModelFingerprint } from '../llm/config.js';
+const VERIFY_CACHE_SUBDIR = path.join('.cognium', 'cache', 'verify');
+/**
+ * Module-scoped singleton — distinct from the discovery-phase singleton
+ * in `classification-cache.ts` so the two phases can carry different
+ * model fingerprints (e.g. cheap discovery + strong verifier) without
+ * thrashing each other's cache instance.
+ */
+let _instance = null;
+let _instanceFingerprint = '';
+/**
+ * Get the verify-phase persistent cache, keyed by per-phase model
+ * fingerprint. When `LLM_VERIFY_CACHE=0` returns a disabled cache that
+ * no-ops on get/set (callers don't need to branch).
+ */
+export function getVerifyCache(config = getDefaultLLMConfig()) {
+    const enabled = process.env.LLM_VERIFY_CACHE !== '0';
+    const fingerprint = getPhaseModelFingerprint(config);
+    if (!_instance || _instanceFingerprint !== fingerprint || _instance.getModelFingerprint() !== fingerprint) {
+        _instance = new ClassificationCache({
+            cacheDir: path.join(process.cwd(), VERIFY_CACHE_SUBDIR),
+            modelFingerprint: fingerprint,
+            enabled,
+        });
+        _instanceFingerprint = fingerprint;
+    }
+    return _instance;
+}
+/** Reset the module-scoped singleton — test-only. */
+export function resetVerifyCache() {
+    _instance = null;
+    _instanceFingerprint = '';
+}
+/**
+ * Stable sort over the source/sink pair-set; never mutates the caller's
+ * arrays. Mirrors `_serializeVerifierPairs` in verification.ts so
+ * persistent + in-memory dedup agree on what counts as "the same call".
+ */
+function serializeVerifyPairs(input) {
+    const sources = [...input.sources]
+        .map((s) => `${s.line}|${s.type}|${s.variable ?? ''}`)
+        .sort();
+    const sinks = [...input.sinks]
+        .map((s) => `${s.line}|${s.type}|${s.cwe}|${s.method ?? ''}`)
+        .sort();
+    return JSON.stringify({ sources, sinks });
+}
+/**
+ * Compute the `(content, classifier)` tuple for the underlying
+ * ClassificationCache. The fingerprint dimension is folded in by the
+ * cache itself (see classification-cache.ts:computeKey).
+ *
+ * Components:
+ *   - file SHA-256 — file edit invalidates only that file's entry
+ *   - pairs fingerprint — sort-invariant over the source/sink set
+ *   - classifier 'verify-batch' — namespace for future
+ *     'verify-pair' / 'verify-flow' tiers without collision
+ */
+export function computeVerifyCacheKey(input) {
+    const fileSha = crypto.createHash('sha256').update(input.code).digest('hex');
+    const pairsFp = crypto.createHash('sha256').update(serializeVerifyPairs(input)).digest('hex');
+    return {
+        content: `${fileSha}\0${pairsFp}`,
+        classifier: 'verify-batch',
+    };
+}
+//# sourceMappingURL=verify-cache.js.map

package/dist/cache/verify-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-cache.js","sourceRoot":"","sources":["../../src/cache/verify-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAkB,MAAM,kBAAkB,CAAC;AAGjG,MAAM,mBAAmB,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAErE;;;;;GAKG;AACH,IAAI,SAAS,GAAwD,IAAI,CAAC;AAC1E,IAAI,oBAAoB,GAAG,EAAE,CAAC;AAE9B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAoB,mBAAmB,EAAE;IAEzC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,GAAG,CAAC;IACrD,MAAM,WAAW,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAErD,IAAI,CAAC,SAAS,IAAI,oBAAoB,KAAK,WAAW,IAAI,SAAS,CAAC,mBAAmB,EAAE,KAAK,WAAW,EAAE,CAAC;QAC1G,SAAS,GAAG,IAAI,mBAAmB,CAA0B;YAC3D,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,mBAAmB,CAAC;YACvD,gBAAgB,EAAE,WAAW;YAC7B,OAAO;SACR,CAAC,CAAC;QACH,oBAAoB,GAAG,WAAW,CAAC;IACrC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,gBAAgB;IAC9B,SAAS,GAAG,IAAI,CAAC;IACjB,oBAAoB,GAAG,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,KAA6B;IACzD,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;SAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;SACrD,IAAI,EAAE,CAAC;IACV,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;SAC5D,IAAI,EAAE,CAAC;IACV,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA6B;IAE7B,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9F,OAAO;QACL,OAAO,EAAE,GAAG,OAAO,KAAK,OAAO,EAAE;QACjC,UAAU,EAAE,cAAc;KAC3B,CAAC;AACJ,CAAC"}

package/dist/cluster/cluster.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Cluster Layer — Foundation
+ *
+ * Top-of-pipeline file clustering (cognium-ai#154, P4 of epic #155).
+ * Groups files in a repo by their static structural fingerprint (CK
+ * metrics + import/annotation set) so downstream passes can apply
+ * per-cluster policy bundles ("library bootstrap" vs "controller
+ * surface" vs "data-access shim") instead of one-size-fits-all
+ * discovery/verification.
+ *
+ * This file ships the **foundation only**:
+ *   - `extractClusterVector(circleIr)` — pull CK vector from analyze() output
+ *   - `clusterFiles(inputs)` — deterministic k-medoids, returns
+ *     `Map<filePath, clusterId>` per acceptance #1
+ *   - distance functions (Euclidean on normalized CK + Jaccard on
+ *     imports/annotations) + the k-medoids loop itself
+ *   - `ClusterPolicy` type so downstream wiring can land in a
+ *     follow-up without re-declaring shape
+ *
+ * **Explicitly out of scope here** (tracked as follow-up tickets):
+ *   - `meta.json.files[*].clusterId` field — needs scan-emit schema
+ *     migration (Acceptance #3)
+ *   - top-100 HIGH/CRIT reduction validation (Acceptance #4)
+ *   - CWE-Bench-Java regression check (Acceptance #5)
+ *   - `--cluster-policy <profile>` CLI flag in cognium-ai
+ *     (Acceptance #6)
+ *   - LLM cluster labeling pass (optional future per the issue)
+ *
+ * The split is deliberate: P1-P3 of epic #155 were single-shot
+ * cache wins; P4's policy bundles + the two benchmark validation
+ * gates need empirical tuning that can't complete in a single
+ * release cycle. Foundation-first lets cognium-ai start consuming
+ * `clusterFiles()` as an opaque grouping signal while the policy
+ * resolver is iterated separately.
+ *
+ * **Determinism:** k-medoids is seeded from a digest of (sorted
+ * file paths || vector signature) so re-runs on the same input
+ * produce the same cluster assignments. Tie-breaking on equal
+ * distances falls back to lexicographic path order.
+ */
+import type { CircleIR } from 'circle-ir';
+/**
+ * Per-file structural fingerprint used as the clustering signal.
+ * CK metrics default to 0 when circle-ir's metric pass didn't run
+ * (e.g. procedural-only files, languages without classes).
+ */
+export interface ClusterVector {
+    cbo: number;
+    rfc: number;
+    lcom: number;
+    dit: number;
+    noc: number;
+    wmc: number;
+    imports: string[];
+    publicSurface: number;
+    annotations: string[];
+}
+export interface ClusterInput {
+    filePath: string;
+    vector: ClusterVector;
+}
+export interface ClusterAssignment {
+    filePath: string;
+    clusterId: number;
+}
+export interface ClusterResult {
+    k: number;
+    assignments: ClusterAssignment[];
+    /** Medoid file path per cluster id (index = clusterId). */
+    medoids: string[];
+    /** Iterations until convergence (for tuning visibility). */
+    iterations: number;
+}
+/**
+ * Downstream policy bundle attached to a cluster. Shape locked here
+ * so wiring tickets can land without re-negotiating the contract;
+ * default policy ("application", everything on) is what consumers
+ * should apply until cluster-specific overrides ship.
+ */
+export type ContextProfile = 'application' | 'library' | 'framework' | 'tool';
+export interface ClusterPolicy {
+    contextProfile: ContextProfile;
+    /** Discovery source kinds permitted; empty array = all. */
+    sourceWhitelist: string[];
+    /** Verification sink classes permitted; empty array = all. */
+    sinkWhitelist: string[];
+    /** When false, downstream LLM passes skip this cluster entirely. */
+    llmEnabled: boolean;
+}
+export declare const DEFAULT_CLUSTER_POLICY: ClusterPolicy;
+/**
+ * Extract a ClusterVector from a single-file `CircleIR` analyze()
+ * result. Missing metrics default to 0 — the cluster vector is
+ * structural, so a procedural file with no CK numbers will land
+ * in the "low-complexity" cluster naturally (it's a valid signal,
+ * not missing data).
+ */
+export declare function extractClusterVector(circleIr: CircleIR): ClusterVector;
+/**
+ * Per-axis max-normalize the CK + publicSurface scalars across the
+ * input set. Max-normalize (rather than z-score) is deliberate:
+ * cluster boundaries should be robust to outliers (one god-class
+ * with WMC=400 shouldn't squash everything else into the same
+ * cluster), and max-normalize gives a clean [0,1] domain that
+ * combines naturally with Jaccard.
+ *
+ * Returns the maxima so callers can normalize new vectors against
+ * the same scale (e.g. for the k-medoids loop on the same set).
+ */
+export declare function computeNormalization(inputs: ClusterInput[]): {
+    cboMax: number;
+    rfcMax: number;
+    lcomMax: number;
+    ditMax: number;
+    nocMax: number;
+    wmcMax: number;
+    publicSurfaceMax: number;
+};
+/** Euclidean distance on the max-normalized CK + publicSurface scalars. */
+export declare function euclideanCkDistance(a: ClusterVector, b: ClusterVector, norm: ReturnType<typeof computeNormalization>): number;
+/**
+ * Jaccard distance on two string sets (1 - |intersection|/|union|).
+ * Returns 0 when both sets are empty (semantically: nothing
+ * distinguishes them on this axis).
+ */
+export declare function jaccardDistance(a: string[], b: string[]): number;
+/**
+ * Combined per-pair distance. Weights mirror the issue's signal
+ * vector ordering (CK is the primary signal; imports + annotations
+ * are tiebreakers). Total is in [0,1] so it composes cleanly with
+ * other metric-space algorithms.
+ *
+ * Weights chosen to sum to 1:
+ *   0.6 — CK + publicSurface Euclidean (clamped to 1 by sqrt of 7
+ *         normalized components, since each (a-b)/max is in [-1,1])
+ *   0.2 — imports Jaccard
+ *   0.2 — annotations Jaccard
+ *
+ * Euclidean is divided by sqrt(7) to renormalize to [0,1] before
+ * weighting — without this, the CK term can exceed 1 and the total
+ * stops being a proper [0,1] distance.
+ */
+export declare function mixedDistance(a: ClusterVector, b: ClusterVector, norm: ReturnType<typeof computeNormalization>): number;
+interface KMedoidsOptions {
+    /** Desired cluster count. Clamped to `[1, inputs.length]`. */
+    k: number;
+    /** Maximum iterations before bailing. Default 50. */
+    maxIter?: number;
+    /** Override the deterministic seed (test-only). */
+    seed?: number;
+}
+/**
+ * PAM-lite k-medoids on `inputs`.
+ *
+ * 1. Seed selection ("build" phase): pick the medoid that minimizes
+ *    total distance to all points, then iteratively pick the point
+ *    that maximizes minimum distance to existing medoids. This is
+ *    deterministic given the seed and degenerates gracefully when
+ *    `inputs.length <= k`.
+ * 2. Assignment: each point joins its closest medoid (lex path
+ *    tiebreak on equal distances).
+ * 3. Swap phase: for each cluster, find the point that minimizes
+ *    intra-cluster distance and promote it to medoid. Repeat until
+ *    no medoid changes (or `maxIter` hits).
+ *
+ * Complexity is O(n^2 * iter) on the distance matrix. For the
+ * top-100 sweep (n ≈ 5000 per repo at the high end) this is ~25M
+ * pairwise computations per iteration — fine for the <2s budget
+ * in Acceptance #2 because distances are scalar arithmetic on
+ * a 9-dim vector.
+ */
+export declare function clusterFiles(inputs: ClusterInput[], options: KMedoidsOptions): ClusterResult;
+export {};
+//# sourceMappingURL=cluster.d.ts.map

package/dist/cluster/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../src/cluster/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,WAAW,CAAC;AAMvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,sBAAsB,EAAE,aAKpC,CAAC;AAsBF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAyDtE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAYA;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,GAC5C,MAAM,CAWR;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAShE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,GAC5C,MAAM,CAKR;AAwCD,UAAU,eAAe;IACvB,8DAA8D;IAC9D,CAAC,EAAE,MAAM,CAAC;IACV,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,EAAE,eAAe,GACvB,aAAa,CAsJf"}

package/dist/cluster/cluster.js

@@ -0,0 +1,392 @@
+/**
+ * Cluster Layer — Foundation
+ *
+ * Top-of-pipeline file clustering (cognium-ai#154, P4 of epic #155).
+ * Groups files in a repo by their static structural fingerprint (CK
+ * metrics + import/annotation set) so downstream passes can apply
+ * per-cluster policy bundles ("library bootstrap" vs "controller
+ * surface" vs "data-access shim") instead of one-size-fits-all
+ * discovery/verification.
+ *
+ * This file ships the **foundation only**:
+ *   - `extractClusterVector(circleIr)` — pull CK vector from analyze() output
+ *   - `clusterFiles(inputs)` — deterministic k-medoids, returns
+ *     `Map<filePath, clusterId>` per acceptance #1
+ *   - distance functions (Euclidean on normalized CK + Jaccard on
+ *     imports/annotations) + the k-medoids loop itself
+ *   - `ClusterPolicy` type so downstream wiring can land in a
+ *     follow-up without re-declaring shape
+ *
+ * **Explicitly out of scope here** (tracked as follow-up tickets):
+ *   - `meta.json.files[*].clusterId` field — needs scan-emit schema
+ *     migration (Acceptance #3)
+ *   - top-100 HIGH/CRIT reduction validation (Acceptance #4)
+ *   - CWE-Bench-Java regression check (Acceptance #5)
+ *   - `--cluster-policy <profile>` CLI flag in cognium-ai
+ *     (Acceptance #6)
+ *   - LLM cluster labeling pass (optional future per the issue)
+ *
+ * The split is deliberate: P1-P3 of epic #155 were single-shot
+ * cache wins; P4's policy bundles + the two benchmark validation
+ * gates need empirical tuning that can't complete in a single
+ * release cycle. Foundation-first lets cognium-ai start consuming
+ * `clusterFiles()` as an opaque grouping signal while the policy
+ * resolver is iterated separately.
+ *
+ * **Determinism:** k-medoids is seeded from a digest of (sorted
+ * file paths || vector signature) so re-runs on the same input
+ * produce the same cluster assignments. Tie-breaking on equal
+ * distances falls back to lexicographic path order.
+ */
+import * as crypto from 'crypto';
+export const DEFAULT_CLUSTER_POLICY = {
+    contextProfile: 'application',
+    sourceWhitelist: [],
+    sinkWhitelist: [],
+    llmEnabled: true,
+};
+// ───────────────────────────────────────────────────────────────────
+// CK vector extraction
+// ───────────────────────────────────────────────────────────────────
+/**
+ * Names emitted by circle-ir's CK metric passes. Mirrored from
+ * the JSDoc on `MetricValue` in circle-ir's public type surface
+ * (canonical: "CBO" | "RFC" | "LCOM" | "DIT" | "NOC" | "WMC").
+ * Matching is case-insensitive because metric-pass authors have
+ * historically used both casings.
+ */
+const CK_METRIC_KEYS = ['CBO', 'RFC', 'LCOM', 'DIT', 'NOC', 'WMC'];
+function findMetric(metrics, name) {
+    if (!metrics)
+        return 0;
+    const lower = name.toLowerCase();
+    const hit = metrics.find((m) => m.name.toLowerCase() === lower);
+    return hit ? hit.value : 0;
+}
+/**
+ * Extract a ClusterVector from a single-file `CircleIR` analyze()
+ * result. Missing metrics default to 0 — the cluster vector is
+ * structural, so a procedural file with no CK numbers will land
+ * in the "low-complexity" cluster naturally (it's a valid signal,
+ * not missing data).
+ */
+export function extractClusterVector(circleIr) {
+    const metrics = circleIr.metrics?.metrics;
+    // Import package signatures — keep top-2 segments (e.g.
+    // `java.util.List` → `java.util`) so unrelated imports of
+    // different leaf types in the same package don't artificially
+    // increase Jaccard distance. circle-ir's `ImportInfo` carries
+    // `from_package` (the canonical package path) and falls back to
+    // `imported_name` when `from_package` is null (wildcard / default
+    // imports).
+    const imports = Array.from(new Set((circleIr.imports ?? [])
+        .map((imp) => {
+        const raw = imp.from_package ?? imp.imported_name ?? '';
+        const parts = raw.split('.');
+        return parts.length >= 2 ? parts.slice(0, 2).join('.') : raw;
+    })
+        .filter((s) => s.length > 0)));
+    // Class-level annotations (Java: `@RestController`, `@Service`,
+    // `@Entity`; Python: `@app.route` would surface here if circle-ir
+    // attaches it to the class node). Pulled from `types[*].annotations`.
+    const annotations = Array.from(new Set((circleIr.types ?? [])
+        .flatMap((t) => t.annotations ?? [])
+        .filter((s) => typeof s === 'string' && s.length > 0)));
+    // Public surface = count of types + methods that aren't explicitly
+    // marked private. `TypeInfo` has no visibility field in circle-ir's
+    // surface (all top-level types count as "public-ish" for clustering
+    // purposes); methods carry `modifiers: string[]` from which we pull
+    // the visibility token.
+    let publicSurface = 0;
+    for (const t of circleIr.types ?? []) {
+        publicSurface++;
+        for (const m of t.methods ?? []) {
+            if (!(m.modifiers ?? []).includes('private'))
+                publicSurface++;
+        }
+    }
+    return {
+        cbo: findMetric(metrics, 'CBO'),
+        rfc: findMetric(metrics, 'RFC'),
+        lcom: findMetric(metrics, 'LCOM'),
+        dit: findMetric(metrics, 'DIT'),
+        noc: findMetric(metrics, 'NOC'),
+        wmc: findMetric(metrics, 'WMC'),
+        imports,
+        publicSurface,
+        annotations,
+    };
+}
+// ───────────────────────────────────────────────────────────────────
+// Distance functions
+// ───────────────────────────────────────────────────────────────────
+/**
+ * Per-axis max-normalize the CK + publicSurface scalars across the
+ * input set. Max-normalize (rather than z-score) is deliberate:
+ * cluster boundaries should be robust to outliers (one god-class
+ * with WMC=400 shouldn't squash everything else into the same
+ * cluster), and max-normalize gives a clean [0,1] domain that
+ * combines naturally with Jaccard.
+ *
+ * Returns the maxima so callers can normalize new vectors against
+ * the same scale (e.g. for the k-medoids loop on the same set).
+ */
+export function computeNormalization(inputs) {
+    const max = (sel) => Math.max(1, ...inputs.map((i) => sel(i.vector)));
+    return {
+        cboMax: max((v) => v.cbo),
+        rfcMax: max((v) => v.rfc),
+        lcomMax: max((v) => v.lcom),
+        ditMax: max((v) => v.dit),
+        nocMax: max((v) => v.noc),
+        wmcMax: max((v) => v.wmc),
+        publicSurfaceMax: max((v) => v.publicSurface),
+    };
+}
+/** Euclidean distance on the max-normalized CK + publicSurface scalars. */
+export function euclideanCkDistance(a, b, norm) {
+    const dx = [
+        (a.cbo - b.cbo) / norm.cboMax,
+        (a.rfc - b.rfc) / norm.rfcMax,
+        (a.lcom - b.lcom) / norm.lcomMax,
+        (a.dit - b.dit) / norm.ditMax,
+        (a.noc - b.noc) / norm.nocMax,
+        (a.wmc - b.wmc) / norm.wmcMax,
+        (a.publicSurface - b.publicSurface) / norm.publicSurfaceMax,
+    ];
+    return Math.sqrt(dx.reduce((acc, x) => acc + x * x, 0));
+}
+/**
+ * Jaccard distance on two string sets (1 - |intersection|/|union|).
+ * Returns 0 when both sets are empty (semantically: nothing
+ * distinguishes them on this axis).
+ */
+export function jaccardDistance(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    const sa = new Set(a);
+    const sb = new Set(b);
+    let intersect = 0;
+    for (const x of sa)
+        if (sb.has(x))
+            intersect++;
+    const union = sa.size + sb.size - intersect;
+    if (union === 0)
+        return 0;
+    return 1 - intersect / union;
+}
+/**
+ * Combined per-pair distance. Weights mirror the issue's signal
+ * vector ordering (CK is the primary signal; imports + annotations
+ * are tiebreakers). Total is in [0,1] so it composes cleanly with
+ * other metric-space algorithms.
+ *
+ * Weights chosen to sum to 1:
+ *   0.6 — CK + publicSurface Euclidean (clamped to 1 by sqrt of 7
+ *         normalized components, since each (a-b)/max is in [-1,1])
+ *   0.2 — imports Jaccard
+ *   0.2 — annotations Jaccard
+ *
+ * Euclidean is divided by sqrt(7) to renormalize to [0,1] before
+ * weighting — without this, the CK term can exceed 1 and the total
+ * stops being a proper [0,1] distance.
+ */
+export function mixedDistance(a, b, norm) {
+    const ck = euclideanCkDistance(a, b, norm) / Math.sqrt(7);
+    const importsD = jaccardDistance(a.imports, b.imports);
+    const annotationsD = jaccardDistance(a.annotations, b.annotations);
+    return 0.6 * ck + 0.2 * importsD + 0.2 * annotationsD;
+}
+// ───────────────────────────────────────────────────────────────────
+// Seeded PRNG (deterministic across runs)
+// ───────────────────────────────────────────────────────────────────
+/**
+ * Mulberry32 — fast, well-distributed seeded PRNG. We don't need
+ * cryptographic randomness here, just reproducibility across runs
+ * for the same input set. Seed is derived from a digest of the
+ * sorted (path || vector) signatures so adding/removing files
+ * changes the seed but reordering inputs does not.
+ */
+function mulberry32(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function deriveSeed(inputs) {
+    const sig = inputs
+        .map((i) => `${i.filePath}\0${i.vector.cbo},${i.vector.rfc},${i.vector.lcom},${i.vector.dit},${i.vector.noc},${i.vector.wmc},${i.vector.publicSurface}`)
+        .sort()
+        .join('|');
+    const hash = crypto.createHash('sha256').update(sig).digest();
+    return hash.readUInt32BE(0);
+}
+/**
+ * PAM-lite k-medoids on `inputs`.
+ *
+ * 1. Seed selection ("build" phase): pick the medoid that minimizes
+ *    total distance to all points, then iteratively pick the point
+ *    that maximizes minimum distance to existing medoids. This is
+ *    deterministic given the seed and degenerates gracefully when
+ *    `inputs.length <= k`.
+ * 2. Assignment: each point joins its closest medoid (lex path
+ *    tiebreak on equal distances).
+ * 3. Swap phase: for each cluster, find the point that minimizes
+ *    intra-cluster distance and promote it to medoid. Repeat until
+ *    no medoid changes (or `maxIter` hits).
+ *
+ * Complexity is O(n^2 * iter) on the distance matrix. For the
+ * top-100 sweep (n ≈ 5000 per repo at the high end) this is ~25M
+ * pairwise computations per iteration — fine for the <2s budget
+ * in Acceptance #2 because distances are scalar arithmetic on
+ * a 9-dim vector.
+ */
+export function clusterFiles(inputs, options) {
+    const k = Math.max(1, Math.min(options.k, inputs.length));
+    const maxIter = options.maxIter ?? 50;
+    if (inputs.length === 0) {
+        return { k: 0, assignments: [], medoids: [], iterations: 0 };
+    }
+    // Sort by path so ties are broken lexicographically regardless of
+    // input order.
+    const sorted = [...inputs].sort((a, b) => a.filePath.localeCompare(b.filePath));
+    const n = sorted.length;
+    const norm = computeNormalization(sorted);
+    // Precompute distance matrix (symmetric, diagonal zero).
+    const dist = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const d = mixedDistance(sorted[i].vector, sorted[j].vector, norm);
+            dist[i][j] = d;
+            dist[j][i] = d;
+        }
+    }
+    // Build phase — deterministic seed init.
+    const seed = options.seed ?? deriveSeed(sorted);
+    const rng = mulberry32(seed);
+    const medoidIdx = [];
+    // First medoid: minimize total distance to all points (1-medoid PAM).
+    let bestSum = Infinity;
+    let bestIdx = 0;
+    for (let i = 0; i < n; i++) {
+        let sum = 0;
+        for (let j = 0; j < n; j++)
+            sum += dist[i][j];
+        if (sum < bestSum || (sum === bestSum && sorted[i].filePath < sorted[bestIdx].filePath)) {
+            bestSum = sum;
+            bestIdx = i;
+        }
+    }
+    medoidIdx.push(bestIdx);
+    // Remaining medoids: maximize min-distance to existing medoids.
+    // RNG breaks ties on equally-far candidates for deterministic but
+    // non-degenerate seeding when the set has structural symmetry.
+    while (medoidIdx.length < k) {
+        let bestPick = -1;
+        let bestMinDist = -1;
+        const candidates = [];
+        for (let i = 0; i < n; i++) {
+            if (medoidIdx.includes(i))
+                continue;
+            let minD = Infinity;
+            for (const m of medoidIdx) {
+                if (dist[i][m] < minD)
+                    minD = dist[i][m];
+            }
+            if (minD > bestMinDist) {
+                bestMinDist = minD;
+                bestPick = i;
+                candidates.length = 0;
+                candidates.push(i);
+            }
+            else if (minD === bestMinDist) {
+                candidates.push(i);
+            }
+        }
+        if (bestPick === -1)
+            break;
+        // Tiebreak: lex-first wins; if rng() < 0.5, allow a randomized
+        // alternative from the tied set. This preserves determinism
+        // (same seed → same pick) while avoiding pathological pile-ups
+        // on highly-symmetric inputs.
+        if (candidates.length > 1 && rng() < 0.5) {
+            candidates.sort((a, b) => sorted[a].filePath.localeCompare(sorted[b].filePath));
+            bestPick = candidates[Math.floor(rng() * candidates.length)];
+        }
+        else {
+            // Default: lex-first.
+            bestPick = candidates.reduce((best, c) => (sorted[c].filePath < sorted[best].filePath ? c : best), candidates[0]);
+        }
+        medoidIdx.push(bestPick);
+    }
+    // Iterate: assign → swap → check convergence.
+    let assignment = new Array(n).fill(0);
+    let iterations = 0;
+    for (let iter = 0; iter < maxIter; iter++) {
+        iterations = iter + 1;
+        // Assign each point to closest medoid (lex tiebreak via medoid order).
+        for (let i = 0; i < n; i++) {
+            let bestC = 0;
+            let bestD = dist[i][medoidIdx[0]];
+            for (let c = 1; c < medoidIdx.length; c++) {
+                const d = dist[i][medoidIdx[c]];
+                if (d < bestD ||
+                    (d === bestD && sorted[medoidIdx[c]].filePath < sorted[medoidIdx[bestC]].filePath)) {
+                    bestD = d;
+                    bestC = c;
+                }
+            }
+            assignment[i] = bestC;
+        }
+        // Swap: for each cluster, find the point that minimizes
+        // intra-cluster distance and promote it.
+        const newMedoids = [...medoidIdx];
+        for (let c = 0; c < medoidIdx.length; c++) {
+            const members = [];
+            for (let i = 0; i < n; i++)
+                if (assignment[i] === c)
+                    members.push(i);
+            if (members.length === 0)
+                continue;
+            let bestM = newMedoids[c];
+            let bestCost = Infinity;
+            for (const m of members) {
+                let cost = 0;
+                for (const other of members)
+                    cost += dist[m][other];
+                if (cost < bestCost || (cost === bestCost && sorted[m].filePath < sorted[bestM].filePath)) {
+                    bestCost = cost;
+                    bestM = m;
+                }
+            }
+            newMedoids[c] = bestM;
+        }
+        // Check convergence (medoid set stable).
+        let changed = false;
+        for (let c = 0; c < newMedoids.length; c++) {
+            if (newMedoids[c] !== medoidIdx[c]) {
+                changed = true;
+                break;
+            }
+        }
+        medoidIdx.length = 0;
+        medoidIdx.push(...newMedoids);
+        if (!changed)
+            break;
+    }
+    const assignments = sorted.map((inp, i) => ({
+        filePath: inp.filePath,
+        clusterId: assignment[i],
+    }));
+    return {
+        k: medoidIdx.length,
+        assignments,
+        medoids: medoidIdx.map((i) => sorted[i].filePath),
+        iterations,
+    };
+}
+//# sourceMappingURL=cluster.js.map