@chigichan24/crune 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Kazuki CHIGITA]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,155 @@
+<div align="center">
+  <img src="public/favicon.svg" alt="crune logo" width="80" height="80" />
+  <h1>crune</h1>
+  <p><strong>Claude Code Rune — Traces linger, skills emerge</strong></p>
+</div>
+
+Decipher the traces etched in past sessions and resurrect them as reusable skills. crune is a static web dashboard that analyzes Claude Code session logs, providing session playback, analytics, a semantic knowledge graph, and skill synthesis.
+
+## Features
+
+- **Session Playback** --- Turn-by-turn conversation replay with minimap navigation, tool call inspection, and subagent branch expansion
+- **Overview Dashboard** --- Activity heatmap, project distribution, tool usage trends, duration distribution, model usage, and top edited files
+- **Semantic Knowledge Graph** --- TF-IDF + Tool-IDF + structural features, Truncated SVD, agglomerative clustering, Louvain community detection, Brandes centrality ([algorithm details](docs/knowledge-graph-algorithm.md))
+- **Tacit Knowledge** --- Extracted workflow patterns, tool sequences, and pain points (long sessions, hot files)
+- **Session Summarization** --- Automatic session summary and classification (no LLM required)
+- **Skill Synthesis** --- Synthesize reusable skill definitions from the knowledge graph ([algorithm details](docs/skill-generation-algorithm.md))
+
+### Overview Dashboard
+
+<img src="docs/overview.png" alt="Overview Dashboard" width="800" />
+
+### Session Playback
+
+<img src="docs/playback.png" alt="Session Playback" width="800" />
+
+### Semantic Knowledge Graph (Rune)
+
+<img src="docs/rune.png" alt="Knowledge Graph" width="800" />
+
+## Quick Start
+
+```bash
+npm install
+
+# Analyze Claude Code session logs (~/.claude/projects/)
+npm run analyze-sessions
+
+# Start dev server
+npm run dev
+```
+
+## Data Pipeline
+
+`npm run analyze-sessions` reads JSONL session files from `~/.claude/projects/` and outputs structured JSON to `public/data/sessions/`.
+
+```
+~/.claude/projects/**/*.jsonl
+  -> parse & build turns
+  -> extract metadata, subagents, linked plans
+  -> session summarization (centrality-based representative prompt, workType classification)
+  -> TF-IDF + Tool-IDF + structural features -> Truncated SVD -> agglomerative clustering -> Louvain
+  -> skill synthesis (reusability score top-N -> claude -p)
+  -> output:
+       public/data/sessions/index.json      (session list)
+       public/data/sessions/overview.json   (cross-session analytics + knowledge graph)
+       public/data/sessions/detail/*.json   (individual session playback data)
+```
+
+Custom paths:
+
+```bash
+npm run analyze-sessions -- --sessions-dir /path/to/sessions --output-dir /path/to/output
+```
+
+## Session Summarization
+
+The session list displays auto-generated summaries, processed entirely locally without LLM.
+
+- **Representative prompt selection**: Selects the most representative prompt from plan mode turns using Jaccard centrality with position weighting
+- **workType classification**: Automatically classifies each session into one of four types:
+  - `investigation` --- Exploratory, read-heavy sessions
+  - `implementation` --- Edit/write-heavy coding sessions
+  - `debugging` --- Bash-heavy sessions with edits
+  - `planning` --- Plan mode sessions with few tool calls
+- **Keyword extraction**: Extracts top keywords from session prompts
+- **Scope estimation**: Infers the session scope from the common directory prefix of edited files
+
+## Skill Synthesis
+
+Synthesizes reusable skill definitions from knowledge graph analysis. Follows the [anthropics/skills](https://github.com/anthropics/skills) format.
+
+- **Pre-synthesis**: Automatically synthesizes the top 5 skill candidates via `claude -p` during `analyze-sessions`
+- **Instant display**: Synthesized skills are immediately viewable and copyable in the UI
+- **On-demand re-synthesis**: The re-synthesis button generates a full version enriched with graph context (connected topics, community, centrality)
+- **Local server**: `npm run skill-server` starts the synthesis API server (localhost:3456)
+
+Synthesis options:
+
+```bash
+# Specify model (e.g. haiku for speed)
+npm run analyze-sessions -- --synthesis-model haiku
+
+# Change number of candidates to synthesize (default: 5)
+npm run analyze-sessions -- --synthesis-count 10
+
+# Skip LLM synthesis (graph construction only)
+npm run analyze-sessions -- --skip-synthesis
+```
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start Vite dev server |
+| `npm run build` | Type-check + production build |
+| `npm run preview` | Preview production build |
+| `npm run lint` | Run ESLint |
+| `npm run analyze-sessions` | Run data pipeline |
+| `npm run skill-server` | Skill synthesis local server (localhost:3456) |
+| `npm run dev:full` | skill-server + Vite dev server together |
+
+### Synthesis options for analyze-sessions
+
+| Flag | Description |
+|------|-------------|
+| `--synthesis-model <model>` | Model to use for synthesis (e.g. `haiku` for speed) |
+| `--synthesis-count <n>` | Number of candidates to synthesize (default: 5) |
+| `--skip-synthesis` | Skip LLM synthesis |
+
+## Tech Stack
+
+- React 19 + TypeScript 5.9
+- Vite 8
+- Chart.js + react-chartjs-2
+- react-force-graph-2d (d3-force)
+- Plain CSS (no CSS-in-JS, no Tailwind)
+
+## Project Structure
+
+```
+src/
+  components/
+    overview/     # Dashboard cards, session list, charts
+    playback/     # Session replay, tool call blocks, subagent branches
+    knowledge/    # Force graph, node detail, tacit knowledge, skill synthesis
+  hooks/          # Data fetching (useSessionIndex, useSessionDetail, useSessionOverview)
+  types/          # TypeScript type definitions
+scripts/
+  analyze-sessions.ts        # JSONL -> JSON pipeline
+  session-summarizer.ts      # Session summarization (local NLP)
+  skill-synthesizer.ts       # Skill synthesis (claude -p)
+  skill-server.ts            # Synthesis HTTP server
+  knowledge-graph-builder.ts # Semantic embedding + graph construction
+public/
+  data/sessions/             # Generated JSON (gitignored)
+```
+
+## Prerequisites
+
+- Node.js >= 18
+- Claude Code session logs at `~/.claude/projects/`
+
+## License
+
+Apache-2.0 license

package/bin/crune.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist-cli/cli.js";

package/dist-cli/__tests__/cli.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { parseCliArgs } from "../cli.js";
+describe("parseCliArgs", () => {
+    it("returns defaults when no args given", () => {
+        const result = parseCliArgs(["node", "cli.ts"]);
+        expect(result.sessionsDir).toMatch(/\.claude\/projects$/);
+        expect(result.outputDir).toMatch(/skills$/);
+        expect(result.count).toBe(5);
+        expect(result.model).toBeUndefined();
+        expect(result.skipSynthesis).toBe(false);
+        expect(result.dryRun).toBe(false);
+    });
+    it("sets sessionsDir with --sessions-dir", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--sessions-dir", "/tmp/sessions"]);
+        expect(result.sessionsDir).toBe("/tmp/sessions");
+    });
+    it("sets outputDir with --output-dir", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--output-dir", "/tmp/out"]);
+        expect(result.outputDir).toBe("/tmp/out");
+    });
+    it("sets count with --count", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--count", "3"]);
+        expect(result.count).toBe(3);
+    });
+    it("clamps count to minimum of 1", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--count", "0"]);
+        expect(result.count).toBe(1);
+    });
+    it("sets model with --model", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--model", "haiku"]);
+        expect(result.model).toBe("haiku");
+    });
+    it("sets skipSynthesis with --skip-synthesis", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--skip-synthesis"]);
+        expect(result.skipSynthesis).toBe(true);
+    });
+    it("sets dryRun with --dry-run", () => {
+        const result = parseCliArgs(["node", "cli.ts", "--dry-run"]);
+        expect(result.dryRun).toBe(true);
+    });
+    it("handles multiple flags combined", () => {
+        const result = parseCliArgs([
+            "node",
+            "cli.ts",
+            "--sessions-dir",
+            "/tmp/sessions",
+            "--output-dir",
+            "/tmp/out",
+            "--count",
+            "10",
+            "--model",
+            "sonnet",
+            "--skip-synthesis",
+            "--dry-run",
+        ]);
+        expect(result.sessionsDir).toBe("/tmp/sessions");
+        expect(result.outputDir).toBe("/tmp/out");
+        expect(result.count).toBe(10);
+        expect(result.model).toBe("sonnet");
+        expect(result.skipSynthesis).toBe(true);
+        expect(result.dryRun).toBe(true);
+    });
+});

package/dist-cli/__tests__/clustering.test.js

@@ -0,0 +1,200 @@
+import { describe, it, expect } from "vitest";
+import { cosineSimilarity, cosineDistance, agglomerativeClusteringFromDistMatrix, findElbowThreshold, clusterWithThresholdFromDistMatrix, splitOversizedClusters, } from "../knowledge-graph-builder.js";
+// Helper: create an L2-normalized Float64Array from raw values
+function normalized(...values) {
+    const norm = Math.sqrt(values.reduce((s, v) => s + v * v, 0));
+    return new Float64Array(values.map((v) => v / norm));
+}
+// Helper: build a distance map with key format `${min}:${max}`
+function buildDistMap(entries) {
+    const m = new Map();
+    for (const [i, j, d] of entries) {
+        const lo = Math.min(i, j);
+        const hi = Math.max(i, j);
+        m.set(`${lo}:${hi}`, d);
+    }
+    return m;
+}
+// ─── cosineSimilarity ───────────────────────────────────────────────────────
+describe("cosineSimilarity", () => {
+    it("returns ~1.0 for identical normalized vectors", () => {
+        const v = normalized(1, 2, 3);
+        expect(cosineSimilarity(v, v)).toBeCloseTo(1.0, 10);
+    });
+    it("returns ~0.0 for orthogonal normalized vectors", () => {
+        const a = normalized(1, 0, 0);
+        const b = normalized(0, 1, 0);
+        expect(cosineSimilarity(a, b)).toBeCloseTo(0.0, 10);
+    });
+});
+// ─── cosineDistance ──────────────────────────────────────────────────────────
+describe("cosineDistance", () => {
+    it("equals 1 - cosineSimilarity", () => {
+        const a = normalized(1, 2, 3);
+        const b = normalized(3, 2, 1);
+        const sim = cosineSimilarity(a, b);
+        const dist = cosineDistance(a, b);
+        expect(dist).toBeCloseTo(1 - sim, 10);
+    });
+    it("returns ~0.0 for identical vectors", () => {
+        const v = normalized(4, 5, 6);
+        expect(cosineDistance(v, v)).toBeCloseTo(0.0, 10);
+    });
+    it("returns ~1.0 for orthogonal vectors", () => {
+        const a = normalized(1, 0);
+        const b = normalized(0, 1);
+        expect(cosineDistance(a, b)).toBeCloseTo(1.0, 10);
+    });
+});
+// ─── agglomerativeClusteringFromDistMatrix ──────────────────────────────────
+describe("agglomerativeClusteringFromDistMatrix", () => {
+    it("returns [] for 0 sessions", () => {
+        const result = agglomerativeClusteringFromDistMatrix([], new Map());
+        expect(result).toEqual([]);
+    });
+    it("returns [[0]] for 1 session", () => {
+        const result = agglomerativeClusteringFromDistMatrix(["s0"], new Map());
+        expect(result).toEqual([[0]]);
+    });
+    it("groups 2 close sessions apart from 1 distant session", () => {
+        // Sessions 0 and 1 are very close (dist 0.05), session 2 is far from both
+        const dist = buildDistMap([
+            [0, 1, 0.05],
+            [0, 2, 0.95],
+            [1, 2, 0.95],
+        ]);
+        const clusters = agglomerativeClusteringFromDistMatrix(["s0", "s1", "s2"], dist);
+        // Should produce 2 clusters: one with {0,1} and one with {2}
+        expect(clusters.length).toBe(2);
+        const sorted = clusters
+            .map((c) => [...c].sort((a, b) => a - b))
+            .sort((a, b) => a[0] - b[0]);
+        expect(sorted).toEqual([[0, 1], [2]]);
+    });
+});
+// ─── findElbowThreshold ─────────────────────────────────────────────────────
+describe("findElbowThreshold", () => {
+    it("returns 0.7 for fewer than 3 distances", () => {
+        expect(findElbowThreshold([])).toBe(0.7);
+        expect(findElbowThreshold([0.5])).toBe(0.7);
+        expect(findElbowThreshold([0.3, 0.6])).toBe(0.7);
+    });
+    it("detects a jump and returns a value in [0.3, 0.9]", () => {
+        const distances = [0.1, 0.2, 0.8, 0.9];
+        const threshold = findElbowThreshold(distances);
+        expect(threshold).toBeGreaterThanOrEqual(0.3);
+        expect(threshold).toBeLessThanOrEqual(0.9);
+    });
+    it("clamps to 0.3 when all distances are very small", () => {
+        const distances = [0.01, 0.02, 0.03, 0.04, 0.05];
+        const threshold = findElbowThreshold(distances);
+        expect(threshold).toBe(0.3);
+    });
+    it("clamps to 0.9 when all distances are very large", () => {
+        const distances = [0.91, 0.95, 0.99, 1.0, 1.2];
+        const threshold = findElbowThreshold(distances);
+        expect(threshold).toBe(0.9);
+    });
+});
+// ─── clusterWithThresholdFromDistMatrix ─────────────────────────────────────
+describe("clusterWithThresholdFromDistMatrix", () => {
+    it("returns [] for n=0", () => {
+        expect(clusterWithThresholdFromDistMatrix(0, new Map(), 0.5)).toEqual([]);
+    });
+    it("returns [[0]] for n=1", () => {
+        expect(clusterWithThresholdFromDistMatrix(1, new Map(), 0.5)).toEqual([[0]]);
+    });
+    it("merges pairs below threshold", () => {
+        // 0-1 close, 2 far
+        const dist = buildDistMap([
+            [0, 1, 0.1],
+            [0, 2, 0.8],
+            [1, 2, 0.8],
+        ]);
+        const clusters = clusterWithThresholdFromDistMatrix(3, dist, 0.5);
+        expect(clusters.length).toBe(2);
+        const flat = clusters.map((c) => [...c].sort()).sort((a, b) => a[0] - b[0]);
+        expect(flat).toEqual([[0, 1], [2]]);
+    });
+    it("keeps all singletons when threshold is very low", () => {
+        const dist = buildDistMap([
+            [0, 1, 0.5],
+            [0, 2, 0.6],
+            [1, 2, 0.7],
+        ]);
+        const clusters = clusterWithThresholdFromDistMatrix(3, dist, 0.01);
+        expect(clusters.length).toBe(3);
+    });
+    it("merges everything when threshold is very high", () => {
+        const dist = buildDistMap([
+            [0, 1, 0.3],
+            [0, 2, 0.4],
+            [1, 2, 0.5],
+        ]);
+        const clusters = clusterWithThresholdFromDistMatrix(3, dist, 2.0);
+        expect(clusters.length).toBe(1);
+        expect([...clusters[0]].sort()).toEqual([0, 1, 2]);
+    });
+});
+// ─── splitOversizedClusters ─────────────────────────────────────────────────
+describe("splitOversizedClusters", () => {
+    it("passes through clusters that are under maxSize", () => {
+        const clusters = [[0, 1], [2, 3]];
+        const dist = buildDistMap([
+            [0, 1, 0.2],
+            [2, 3, 0.3],
+            [0, 2, 0.8],
+            [0, 3, 0.8],
+            [1, 2, 0.8],
+            [1, 3, 0.8],
+        ]);
+        const result = splitOversizedClusters(clusters, 100, dist);
+        // maxSize = max(10, floor(100 * 0.25)) = 25, both clusters are size 2
+        expect(result).toEqual([[0, 1], [2, 3]]);
+    });
+    it("splits an oversized cluster", () => {
+        // Create a cluster of 12 members with totalSessions=20, ratio=0.25
+        // maxSize = max(10, floor(20 * 0.25)) = 10, so cluster of 12 is oversized
+        const bigCluster = Array.from({ length: 12 }, (_, i) => i);
+        const smallCluster = [12, 13];
+        // Build distances: two groups within the big cluster
+        // Group A (0-5): close to each other, far from group B
+        // Group B (6-11): close to each other, far from group A
+        const dist = new Map();
+        for (let i = 0; i < 14; i++) {
+            for (let j = i + 1; j < 14; j++) {
+                const groupI = i < 6 ? "A" : i < 12 ? "B" : "S";
+                const groupJ = j < 6 ? "A" : j < 12 ? "B" : "S";
+                let d;
+                if (groupI === groupJ) {
+                    d = 0.1; // same group: close
+                }
+                else {
+                    d = 0.9; // different group: far
+                }
+                dist.set(`${i}:${j}`, d);
+            }
+        }
+        const result = splitOversizedClusters([bigCluster, smallCluster], 20, dist);
+        // The small cluster should pass through
+        // The big cluster should be split into at least 2 sub-clusters
+        expect(result.length).toBeGreaterThanOrEqual(3); // at least 2 from split + 1 small
+        // All original indices should be present
+        const allIndices = result.flat().sort((a, b) => a - b);
+        expect(allIndices).toEqual(Array.from({ length: 14 }, (_, i) => i));
+    });
+    it("respects custom maxClusterRatio", () => {
+        // 5 members, totalSessions=10, ratio=0.3 -> maxSize = max(10, floor(10*0.3)) = 10
+        // So cluster of 5 is fine with ratio 0.3
+        const clusters = [[0, 1, 2, 3, 4]];
+        const dist = new Map();
+        for (let i = 0; i < 5; i++) {
+            for (let j = i + 1; j < 5; j++) {
+                dist.set(`${i}:${j}`, 0.2);
+            }
+        }
+        const result = splitOversizedClusters(clusters, 10, dist, 0.3);
+        // maxSize = max(10, 3) = 10, cluster size 5 <= 10, so no split
+        expect(result).toEqual([[0, 1, 2, 3, 4]]);
+    });
+});