kiwiskil 0.1.0__tar.gz

kiwiskil-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: kiwiskil
+Version: 0.1.0
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: litellm>=1.35
+Requires-Dist: jinja2>=3.1
+Requires-Dist: tomli-w>=1.0

kiwiskil-0.1.0/README.md

@@ -0,0 +1,124 @@
+# kiwiskil
+
+> Chat with your codebase using any LLM.
+
+kiwiskil generates a checked-in structural wiki and skill files from any codebase. It enables LLM agents to navigate code without reading source files — using a knowledge graph built from your repo and checked into git.
+
+---
+
+## How it works
+
+1. **AST parsing** extracts symbols, imports, and call graphs from your source files (deterministic, free)
+2. **LiteLLM** adds one-line descriptions per symbol using any provider you configure
+3. **A density-based grouper** organises files into wiki pages by logical density, not directory structure
+4. **A pre-commit hook** keeps the wiki in sync — every commit includes updated wiki pages atomically
+5. **A skill file** is generated at `.indexer/skills/codebase.md` so any LLM agent can navigate your codebase via structured tools
+
+The wiki is plain markdown checked into your repo. No cloud service, no search index, no lock-in.
+
+---
+
+## Install
+
+```bash
+pip install kiwiskil
+```
+
+---
+
+## Quick start
+
+```bash
+# In any git repo
+kiwiskil init       # creates .indexer.toml, installs pre-commit hook, appends CLAUDE.md
+kiwiskil run        # generates wiki/ and .indexer/skills/codebase.md
+```
+
+On every subsequent commit, the pre-commit hook runs `kiwiskil run --staged` automatically — only changed files are re-indexed.
+
+---
+
+## CLI
+
+```bash
+kiwiskil init              # set up config, hook, and CLAUDE.md
+kiwiskil run               # smart: incremental if indexed before, full if not
+kiwiskil run --force       # force full re-index
+kiwiskil run --staged      # incremental on staged files only (used by hook)
+kiwiskil status            # show last indexed commit, stale files, stats
+kiwiskil hook install      # manually install pre-commit hook
+kiwiskil hook remove       # remove pre-commit hook
+```
+
+---
+
+## Output
+
+### `wiki/INDEX.md`
+Top-level map of the entire codebase — which wiki page covers which files, and the entry points for each.
+
+### `wiki/<group>.md`
+One page per logical folder cluster. Each page contains:
+- **Modules** — files covered
+- **Key Symbols** — functions, classes, methods with one-line descriptions
+- **Relationships** — what this group calls, what calls it, what it imports
+- **Entry Points** — symbols with no callers (architectural roots)
+
+### `.indexer/skills/codebase.md`
+A skill file compatible with Claude Code, Cursor, Copilot, and other LLM agents. Drop it into your agent's skill directory to unlock:
+
+- `find_module(query)` — search wiki pages by keyword
+- `get_symbol(id)` — look up any symbol by component ID (`file::Class.method`)
+- `trace_callers(symbol_id)` — find what calls a given symbol
+- `what_changed(since_commit)` — list changed files with their wiki pages
+- `entry_points()` — list all architectural entry points
+
+---
+
+## Configuration
+
+`.indexer.toml` is created by `kiwiskil init` and checked into the repo:
+
+```toml
+[llm]
+provider = "anthropic/claude-sonnet-4-6"  # any LiteLLM-compatible model string
+api_key_env = "ANTHROPIC_API_KEY"         # env var name, not the key itself
+
+[indexer]
+wiki_dir = "wiki"
+ignore = ["node_modules", ".venv", "dist", "build", "__pycache__", "*.test.*"]
+max_tokens_per_batch = 8000
+
+[hooks]
+pre_commit = true
+synthesize_commit_message = true
+```
+
+Any LiteLLM-compatible provider works: OpenAI, Anthropic, Gemini, Ollama, local models.
+
+---
+
+## Commit message synthesis
+
+When running as a pre-commit hook, kiwiskil synthesises a commit message from the code changes and prints it to stdout. You can use it, edit it, or ignore it — your choice.
+
+---
+
+## Design principles
+
+- **Structural facts only** — wiki pages contain symbols, relationships, and entry points. No prose summaries, no architectural opinions. The client LLM draws its own conclusions.
+- **Checked in, not served** — the wiki is plain markdown in your repo. It travels with your code, is tracked by git, and is readable by humans and agents alike.
+- **Incremental by default** — git diff + content hash manifest means only changed files are re-processed on each commit.
+- **Provider-agnostic** — LiteLLM means you can use any model, local or cloud, without changing the tool.
+
+---
+
+## Supported languages
+
+Python (stdlib `ast`). JS, TS, Go, Rust, Java, Ruby support planned via tree-sitter.
+
+---
+
+## License
+
+MIT

kiwiskil-0.1.0/indexer/ast_parser.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+import ast, json, hashlib
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+@dataclass
+class ASTNode:
+    id: str                          # "rel/path.py::Class.method"
+    type: str                        # "function" | "method" | "class"
+    file: str                        # repo-relative path
+    line_start: int
+    line_end: int
+    docstring: Optional[str]
+    imports: list[str] = field(default_factory=list)
+    calls: list[str] = field(default_factory=list)
+    # called_by is intentionally empty at parse time;
+    # populated in a later cross-reference pass by cli.py
+    called_by: list[str] = field(default_factory=list)
+
+def _rel(path: Path, repo_root: Path) -> str:
+    try:
+        return str(path.relative_to(repo_root))
+    except ValueError:
+        return str(path)
+
+def _extract_imports(tree: ast.Module) -> list[str]:
+    imports = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            mod = node.module or ""
+            for alias in node.names:
+                imports.append(f"{mod}.{alias.name}" if mod else alias.name)
+    return imports
+
+def _extract_calls(func_node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
+    calls = []
+    for node in ast.walk(func_node):
+        if isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name):
+                calls.append(node.func.id)
+            elif isinstance(node.func, ast.Attribute):
+                calls.append(node.func.attr)
+    return list(set(calls))
+
+def _get_class_method_ids(tree: ast.Module) -> set[int]:
+    """Return AST node ids of functions that are direct children of a class body."""
+    ids = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    ids.add(id(item))
+    return ids
+
+def parse_file(path: Path, repo_root: Path) -> list[ASTNode]:
+    """Parse a Python file and return ASTNode list. Returns [] on syntax error."""
+    try:
+        source = path.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except (SyntaxError, OSError):
+        return []
+
+    rel_path = _rel(path, repo_root)
+    file_imports = _extract_imports(tree)
+    method_ids = _get_class_method_ids(tree)
+    nodes: list[ASTNode] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            nodes.append(ASTNode(
+                id=f"{rel_path}::{node.name}",
+                type="class",
+                file=rel_path,
+                line_start=node.lineno,
+                line_end=node.end_lineno or node.lineno,
+                docstring=ast.get_docstring(node),
+                imports=list(file_imports),
+                calls=[],
+            ))
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    nodes.append(ASTNode(
+                        id=f"{rel_path}::{node.name}.{item.name}",
+                        type="method",
+                        file=rel_path,
+                        line_start=item.lineno,
+                        line_end=item.end_lineno or item.lineno,
+                        docstring=ast.get_docstring(item),
+                        imports=list(file_imports),
+                        calls=_extract_calls(item),
+                    ))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if id(node) not in method_ids:
+                nodes.append(ASTNode(
+                    id=f"{rel_path}::{node.name}",
+                    type="function",
+                    file=rel_path,
+                    line_start=node.lineno,
+                    line_end=node.end_lineno or node.lineno,
+                    docstring=ast.get_docstring(node),
+                    imports=list(file_imports),
+                    calls=_extract_calls(node),
+                ))
+
+    return nodes
+
+
+def compute_hash_short(path: Path) -> str:
+    """Returns first 16 chars of sha256 hex digest — used for cache filenames only."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+
+
+def load_cached_nodes(repo_root: Path, file_hash: str) -> Optional[list[ASTNode]]:
+    p = repo_root / ".indexer" / "cache" / f"{file_hash}.json"
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text())
+        return [ASTNode(**n) for n in data]
+    except (json.JSONDecodeError, TypeError, KeyError):
+        return None  # corrupted cache — caller will re-parse
+
+
+def save_cached_nodes(repo_root: Path, file_hash: str, nodes: list[ASTNode]) -> None:
+    p = repo_root / ".indexer" / "cache" / f"{file_hash}.json"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps([asdict(n) for n in nodes], indent=2))

kiwiskil-0.1.0/indexer/cli.py

@@ -0,0 +1,259 @@
+# indexer/cli.py
+from __future__ import annotations
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from indexer.config import Config, load_config, save_config
+from indexer.manifest import load_manifest, save_manifest, compute_hash, FileEntry
+from indexer.git import (
+    staged_files, all_tracked_files, current_commit,
+    changed_files_since, is_git_repo
+)
+from indexer.ast_parser import parse_file, load_cached_nodes, save_cached_nodes, compute_hash_short
+from indexer.llm import describe_nodes, synthesize_commit_message
+from indexer.grouper import density_group
+from indexer.wiki import build_page, build_index, write_page, write_index, PageContext, IndexEntry, TEMPLATES_DIR
+from indexer.hooks import install_hook, remove_hook
+
+CLAUDEMD_SNIPPET = """
+## Codebase Navigation
+
+This repo is indexed. Before reading source files:
+- Load `wiki/INDEX.md` for the full structure map
+- Use `.indexer/skills/codebase.md` as a skill for structured lookup tools
+- Wiki pages are in `wiki/` — grouped by logical density, not mirroring directory structure exactly
+- Component IDs follow `file::Class.method` format throughout
+"""
+
+
+@click.group()
+def main():
+    pass
+
+
+@main.command()
+def init():
+    """Create .indexer.toml, install pre-commit hook, append to CLAUDE.md."""
+    root = Path.cwd()
+    cfg = load_config(root)
+    save_config(root, cfg)
+    click.echo(f"Created {root / '.indexer.toml'}")
+
+    if is_git_repo(root) and cfg.pre_commit:
+        install_hook(root)
+        click.echo("Installed pre-commit hook.")
+
+    claude_md = root / "CLAUDE.md"
+    if claude_md.exists():
+        existing = claude_md.read_text()
+        if "Codebase Navigation" not in existing:
+            claude_md.write_text(existing + "\n" + CLAUDEMD_SNIPPET)
+            click.echo("Appended to CLAUDE.md.")
+    else:
+        claude_md.write_text(CLAUDEMD_SNIPPET.lstrip())
+        click.echo("Created CLAUDE.md.")
+
+
+@main.command()
+@click.option("--staged", is_flag=True, help="Incremental: only staged files (used by hook)")
+@click.option("--force", is_flag=True, help="Force full re-index regardless of manifest")
+def run(staged: bool, force: bool):
+    """Index the codebase and generate wiki pages."""
+    root = Path.cwd()
+    cfg = load_config(root)
+    manifest = load_manifest(root)
+
+    # Determine which files to process
+    if staged:
+        candidates = staged_files(root)
+    elif force or manifest.last_indexed_commit is None:
+        candidates = [f for f in all_tracked_files(root) if _is_indexable(f, cfg)]
+    else:
+        git_changed = changed_files_since(root, manifest.last_indexed_commit) if is_git_repo(root) else []
+        all_files = [f for f in all_tracked_files(root) if _is_indexable(f, cfg)]
+        stale = manifest.stale_files(root, all_files)
+        candidates = list(set(git_changed + stale))
+
+    candidates = [f for f in candidates if _is_indexable(f, cfg)]
+
+    if not candidates:
+        click.echo("Nothing to index.")
+        return
+
+    click.echo(f"Indexing {len(candidates)} file(s)...")
+
+    # Parse AST (use cache for unchanged files, fresh parse for changed)
+    all_nodes = []
+    for rel_path in candidates:
+        abs_path = root / rel_path
+        file_hash = compute_hash_short(abs_path)
+        cached = load_cached_nodes(root, file_hash)
+        if cached is not None:
+            all_nodes.extend(cached)
+        else:
+            nodes = parse_file(abs_path, root)
+            save_cached_nodes(root, file_hash, nodes)
+            all_nodes.extend(nodes)
+
+    if not all_nodes:
+        click.echo("No symbols found.")
+        return
+
+    # Cross-reference pass: populate called_by from calls graph
+    # Note: calls stores bare function/method names (e.g. "sign_payload"), not full component IDs.
+    # This is best-effort: correctly links calls within the same codebase batch.
+    call_index: dict[str, list[str]] = {}
+    for node in all_nodes:
+        for callee_name in node.calls:
+            call_index.setdefault(callee_name, []).append(node.id)
+    for node in all_nodes:
+        # Match by bare name (last part of component ID after "::")
+        bare_name = node.id.split("::")[-1]
+        node.called_by = call_index.get(bare_name, [])
+
+    # LLM: describe nodes in batches by token budget
+    descriptions: dict[str, str] = {}
+    batch, batch_size = [], 0
+    for node in all_nodes:
+        node_size = len(node.docstring or "") + len(" ".join(node.calls)) + 50
+        if batch_size + node_size > cfg.max_tokens_per_batch and batch:
+            descriptions.update(describe_nodes(batch, cfg))
+            batch, batch_size = [], 0
+        batch.append(node)
+        batch_size += node_size
+    if batch:
+        descriptions.update(describe_nodes(batch, cfg))
+
+    # Group files → wiki page labels
+    groups = density_group(candidates)
+    group_nodes: dict[str, list] = {}
+    for node in all_nodes:
+        group = groups.get(node.file, node.file)
+        group_nodes.setdefault(group, []).append(node)
+
+    # Write wiki pages
+    wiki_dir = root / cfg.wiki_dir
+    index_entries = []
+    for group_label, nodes in group_nodes.items():
+        ctx = PageContext(
+            group_label=group_label,
+            files=list({n.file for n in nodes}),
+            nodes=nodes,
+            descriptions=descriptions,
+        )
+        content = build_page(ctx)
+        page_path = write_page(wiki_dir, group_label, content)
+        entry_points = [n.id.split("::")[-1] for n in nodes if not n.called_by]
+        index_entries.append(IndexEntry(
+            path=str(page_path.relative_to(root)),
+            covers=", ".join(sorted({n.file for n in nodes})),
+            entry_points=entry_points,
+        ))
+
+    # Write INDEX.md
+    commit = current_commit(root) or "unknown"
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    index_content = build_index(index_entries, commit, today)
+    write_index(wiki_dir, index_content)
+
+    # Write skill file
+    from jinja2 import Environment, FileSystemLoader
+    skill_dir = root / ".indexer" / "skills"
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    env = Environment(loader=FileSystemLoader(str(TEMPLATES_DIR)), trim_blocks=True, lstrip_blocks=True)
+    skill_content = env.get_template("skill.md.j2").render(wiki_dir=cfg.wiki_dir)
+    (skill_dir / "codebase.md").write_text(skill_content)
+
+    # Update manifest
+    now = datetime.now(timezone.utc).isoformat()
+    for rel_path in candidates:
+        abs_path = root / rel_path
+        if abs_path.exists():
+            file_hash = compute_hash(abs_path)
+            group = groups.get(rel_path, rel_path)
+            manifest.files[rel_path] = FileEntry(
+                hash=file_hash,
+                wiki_page=f"{cfg.wiki_dir}/{group}.md",
+                component_ids=[n.id for n in all_nodes if n.file == rel_path],
+            )
+    manifest.last_indexed_commit = commit
+    manifest.indexed_at = now
+
+    # Prune manifest entries for files no longer tracked by git
+    if is_git_repo(root):
+        tracked = set(all_tracked_files(root))
+        stale_keys = [k for k in manifest.files if k not in tracked]
+        for k in stale_keys:
+            del manifest.files[k]
+
+    save_manifest(root, manifest)
+
+    # Synthesize commit message
+    if cfg.synthesize_commit_message and staged:
+        msg = synthesize_commit_message(candidates, descriptions, cfg)
+        if msg:
+            click.echo(f"\nSuggested commit message:\n  {msg}")
+
+    # Auto-stage wiki + manifest when running as pre-commit hook
+    if staged and is_git_repo(root):
+        subprocess.run(["git", "add", cfg.wiki_dir, ".indexer/manifest.json"], cwd=root)
+
+    click.echo(f"Done. Wiki written to {wiki_dir}/")
+
+
+@main.command()
+def status():
+    """Show last indexed commit, stale files, manifest stats."""
+    root = Path.cwd()
+    cfg = load_config(root)
+    manifest = load_manifest(root)
+
+    click.echo(f"Last indexed commit: {manifest.last_indexed_commit or 'never'}")
+    click.echo(f"Indexed at:          {manifest.indexed_at or 'n/a'}")
+    click.echo(f"Tracked files:       {len(manifest.files)}")
+
+    if is_git_repo(root):
+        all_files = [f for f in all_tracked_files(root) if _is_indexable(f, cfg)]
+        stale = manifest.stale_files(root, all_files)
+        click.echo(f"Stale files:         {len(stale)}")
+        if stale:
+            for f in stale[:10]:
+                click.echo(f"  {f}")
+
+
+@main.group()
+def hook():
+    """Manage the pre-commit hook."""
+    pass
+
+
+@hook.command("install")
+def hook_install():
+    """Install the pre-commit hook in the current repo."""
+    root = Path.cwd()
+    install_hook(root)
+    click.echo("Pre-commit hook installed.")
+
+
+@hook.command("remove")
+def hook_remove():
+    """Remove the pre-commit hook from the current repo."""
+    root = Path.cwd()
+    remove_hook(root)
+    click.echo("Pre-commit hook removed.")
+
+
+def _is_indexable(path: str, cfg: Config) -> bool:
+    from fnmatch import fnmatch
+    p = Path(path)
+    if p.suffix not in {".py", ".js", ".ts", ".jsx", ".tsx", ".java", ".go", ".rb", ".rs"}:
+        return False
+    for pattern in cfg.ignore:
+        if any(fnmatch(part, pattern) for part in p.parts):
+            return False
+        if fnmatch(path, pattern):
+            return False
+    return True

kiwiskil-0.1.0/indexer/config.py

@@ -0,0 +1,49 @@
+# indexer/config.py
+from __future__ import annotations
+import tomllib
+import tomli_w
+from dataclasses import dataclass, field
+from pathlib import Path
+
+FILENAME = ".indexer.toml"
+
+@dataclass
+class Config:
+    provider: str = "anthropic/claude-sonnet-4-6"
+    api_key_env: str = "ANTHROPIC_API_KEY"
+    wiki_dir: str = "wiki"
+    ignore: list[str] = field(default_factory=lambda: [
+        "node_modules", ".venv", "dist", "build", "__pycache__", "*.test.*"
+    ])
+    max_tokens_per_batch: int = 8000
+    pre_commit: bool = True
+    synthesize_commit_message: bool = True
+
+def load_config(repo_root: Path) -> Config:
+    path = repo_root / FILENAME
+    if not path.exists():
+        return Config()
+    defaults = Config()
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    llm = data.get("llm", {})
+    idx = data.get("indexer", {})
+    hooks = data.get("hooks", {})
+    return Config(
+        provider=llm.get("provider", defaults.provider),
+        api_key_env=llm.get("api_key_env", defaults.api_key_env),
+        wiki_dir=idx.get("wiki_dir", defaults.wiki_dir),
+        ignore=list(idx.get("ignore", defaults.ignore)),
+        max_tokens_per_batch=idx.get("max_tokens_per_batch", defaults.max_tokens_per_batch),
+        pre_commit=hooks.get("pre_commit", defaults.pre_commit),
+        synthesize_commit_message=hooks.get("synthesize_commit_message", defaults.synthesize_commit_message),
+    )
+
+def save_config(repo_root: Path, cfg: Config) -> None:
+    data = {
+        "llm": {"provider": cfg.provider, "api_key_env": cfg.api_key_env},
+        "indexer": {"wiki_dir": cfg.wiki_dir, "ignore": cfg.ignore, "max_tokens_per_batch": cfg.max_tokens_per_batch},
+        "hooks": {"pre_commit": cfg.pre_commit, "synthesize_commit_message": cfg.synthesize_commit_message},
+    }
+    with open(repo_root / FILENAME, "wb") as f:
+        tomli_w.dump(data, f)

kiwiskil-0.1.0/indexer/git.py

@@ -0,0 +1,38 @@
+# indexer/git.py
+from __future__ import annotations
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+def _run(cmd: list[str], cwd: Path) -> str:
+    try:
+        result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+        return result.stdout.strip()
+    except (FileNotFoundError, OSError):
+        return ""
+
+def current_commit(repo_root: Path) -> Optional[str]:
+    out = _run(["git", "rev-parse", "HEAD"], cwd=repo_root)
+    return out if out else None
+
+def staged_files(repo_root: Path) -> list[str]:
+    out = _run(["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"], cwd=repo_root)
+    return [line for line in out.splitlines() if line]
+
+def changed_files_since(repo_root: Path, since_commit: str) -> list[str]:
+    out = _run(["git", "diff", "--name-only", "--diff-filter=ACM", since_commit, "HEAD"], cwd=repo_root)
+    return [line for line in out.splitlines() if line]
+
+def all_tracked_files(repo_root: Path) -> list[str]:
+    out = _run(["git", "ls-files"], cwd=repo_root)
+    return [line for line in out.splitlines() if line]
+
+def is_git_repo(repo_root: Path) -> bool:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            cwd=repo_root, capture_output=True
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, OSError):
+        return False

kiwiskil-0.1.0/indexer/grouper.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+from collections import defaultdict
+from pathlib import Path
+
+
+def density_group(files: list[str], merge_threshold: int = 6) -> dict[str, str]:
+    """
+    Maps each file path to a wiki page label (a folder path string).
+
+    Algorithm:
+    1. Count files reachable under each folder prefix.
+    2. Walk from the deepest folder upward. If a folder has fewer than
+       merge_threshold files reachable under it, merge it into its parent.
+    3. The resolved group for each file is the shallowest folder whose
+       subtree count >= merge_threshold, or the top-level folder if none qualify.
+
+    Returns: dict mapping file_path -> wiki_page_label (a folder string)
+    """
+    if not files:
+        return {}
+
+    def folder_of(f: str) -> str:
+        parent = str(Path(f).parent)
+        return "." if parent == "." else parent
+
+    def prefixes(folder: str) -> list[str]:
+        """All ancestor folder prefixes from deepest to shallowest."""
+        if folder == ".":
+            return ["."]
+        parts = folder.split("/")
+        return ["/".join(parts[:i]) for i in range(len(parts), 0, -1)]
+
+    # Count how many files fall under each prefix
+    prefix_count: dict[str, int] = defaultdict(int)
+    for f in files:
+        folder = folder_of(f)
+        for prefix in prefixes(folder):
+            prefix_count[prefix] += 1
+
+    def resolve_group(f: str) -> str:
+        folder = folder_of(f)
+        all_prefixes = prefixes(folder)
+
+        # Walk from deepest to shallowest, find first prefix that meets threshold
+        for prefix in all_prefixes:
+            if prefix_count[prefix] >= merge_threshold:
+                return prefix
+
+        # None met threshold — use the shallowest non-root prefix, or "." for root
+        # For files at depth, merge to immediate parent folder
+        if len(all_prefixes) > 1:
+            return all_prefixes[-2]  # parent of deepest
+        return "."  # root level
+
+    return {f: resolve_group(f) for f in files}