/repo-map: Repository Map

Created by IOTA - Joseph Bryant. https://iotallc.github.io/

This file is a skill guide. It tells the model in IOTA how to do the job step by step. It is not a compiled program and it does not install anything. To use it, paste its text into an IOTA chat and then give your request, or read it and follow the steps yourself.

Purpose

Index a codebase so you can ask "where is X handled?" and get file paths with line numbers, and draw a Mermaid diagram of how folders and modules depend on each other. It uses retrieval (RAG): code is split into chunks, embedded locally, and the closest chunks are passed to the model with their locations.

When to use

• You joined a project, or came back to an old one, and need to find things quickly.
• You want a picture of module dependencies before a refactor.
• Before /fix-build on a large project, to find related files.

When not to use

• Tiny projects with a handful of files. Just open them.
• Generated code, minified bundles, or vendored libraries. They are skipped by default.
• Questions about runtime behavior ("why is this slow?"). The map shows structure, not performance.

Requirements

• Python 3.10 or later with numpy.
• A local embedding model served by IOTA, or sentence-transformers with a model already downloaded (for example all-MiniLM-L6-v2). Embedding models are separate from the chat model.
• Chat model: Gemma 3 4B answers "where is" questions well when given the chunks. Explaining design across many files is better with Gemma 3 12B or 27B or a Nemotron model.
• Disk: about 2 KB per chunk for vectors plus the text.

Inputs

Step-by-step procedure

1. List files with the include and exclude rules. Skip files over 1 MB and files that look binary (contain a NUL byte in the first 8 KB). Report the file count by extension.

2. Chunk by structure. Split at function or class boundaries when possible, else every 60 lines with 10 lines of overlap. Keep the file path and start and end lines with each chunk.

   import re
   from pathlib import Path
   
   BOUNDARY = re.compile(r"^\s*(def |class |public |private |internal |protected |fun |function |export |func |fn )")
   
   def chunks(path: Path, max_lines: int = 60, overlap: int = 10):
       lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
       start = 0
       while start < len(lines):
           end = min(start + max_lines, len(lines))
           # try to end at a boundary within the last 20 lines of the window
           for j in range(end - 1, max(start + 20, end - 20), -1):
               if BOUNDARY.match(lines[j]):
                   end = j
                   break
           text = "\n".join(lines[start:end])
           if text.strip():
               yield {"file": str(path), "start": start + 1, "end": end, "text": text}
           if end >= len(lines):
               break
           start = max(end - overlap, start + 1)

3. Embed and store. Write vectors to .iota/repo-map/index.npz and metadata to meta.jsonl inside the repo (ask first; offer a folder outside the repo instead). Add .iota/ to .gitignore only with permission.

   import json
   import numpy as np
   from sentence_transformers import SentenceTransformer
   
   def build(chunks_list, out_dir: Path, model_name="all-MiniLM-L6-v2"):
       model = SentenceTransformer(model_name)   # must already be downloaded for offline use
       texts = [f"{c['file']}\n{c['text']}" for c in chunks_list]
       vecs = model.encode(texts, batch_size=32, normalize_embeddings=True, show_progress_bar=True)
       out_dir.mkdir(parents=True, exist_ok=True)
       np.savez_compressed(out_dir / "index.npz", vecs=vecs.astype("float32"))
       with open(out_dir / "meta.jsonl", "w", encoding="utf-8") as f:
           for c in chunks_list:
               f.write(json.dumps(c) + "\n")

   For offline use set HF_HUB_OFFLINE=1 so the library does not try to download.

4. Keep it fresh. Store each file's modified time and size in files.json. On the next run, re-embed only changed files and drop deleted ones.

5. Answer "where is X". Embed the question, take the top 8 chunks by cosine similarity, then boost chunks whose text contains exact identifiers from the question (words in CamelCase, snake_case, or quotes).

   def search(question, model, vecs, meta, k=8):
       q = model.encode([question], normalize_embeddings=True)[0]
       scores = vecs @ q
       words = set(re.findall(r"[A-Za-z_][A-Za-z0-9_]{3,}", question))
       for i, m in enumerate(meta):
           if any(w in m["text"] for w in words if not w.islower()):
               scores[i] += 0.15
       top = np.argsort(-scores)[:k]
       return [(float(scores[i]), meta[i]) for i in top]

   Prompt for the chat model:

   Question: {question}
   Below are code excerpts with their file and line range. Answer only from
   these excerpts. Name the most relevant file and line range first, then up
   to three others. If the excerpts do not answer the question, say so.
   
   [1] {file}:{start}-{end}
   {text}
   ...

6. Draw the dependency diagram. Parse imports per language and roll them up to the folder level (two levels deep by default) so the diagram stays readable.

Only keep edges between modules inside the repo. Then write Mermaid:

def mermaid(edges: dict[tuple[str, str], int]) -> str:
    ids = {}
    def nid(name):
        return ids.setdefault(name, f"n{len(ids)}")
    lines = ["graph LR"]
    for (a, b), n in sorted(edges.items(), key=lambda e: -e[1])[:60]:
        lines.append(f'  {nid(a)}["{a}"] -->|{n}| {nid(b)}["{b}"]')
    return "\n".join(lines)

graph LR
  n0["src/App"] -->|14| n1["src/Core"]
  n2["tests"] -->|9| n1["src/Core"]
  n1["src/Core"] -->|3| n3["src/Data"]

Output format

• "Where" answers: a ranked list of file:start-end with one line on why each matters, followed by the model's short explanation.
• Map: repo-map.md with the Mermaid block, a table of modules with file counts, and a list of cycles.
• Index files under .iota/repo-map/ (or the folder the user chose).

Safety and confirmation rules

• Read only on source files. The only writes are the index folder and repo-map.md, after the user agrees on the location.
• Skip files that look like secrets: .env, *.pfx, *.pem, *.key, id_rsa*, secrets.*, appsettings.*.json with Password or ConnectionString keys. Report that they were skipped.
• Never overwrite an existing repo-map.md without asking.
• Nothing leaves the PC.

Quality checks

• Every cited line range exists and the cited text matches the file at search time (re-read before answering).
• The diagram has at most 60 edges; if more exist, the skill rolls up one more folder level.
• Answers say "not found in the index" instead of guessing.

Examples

1. "Where is the CSV export?" Returns src/Core/Export/CsvWriter.cs:12-58 first, then the button handler in MainWindow.xaml.cs:88-104.
2. "/repo-map diagram" on a three project .NET solution. Shows App to Core, Tests to Core, and Core to Data, no cycles.
3. "Which files read the config file?" Finds the loader and two callers, notes one call site in a test.

Troubleshooting

Limitations

• Import parsing is pattern based. Reflection, dependency injection, and dynamic imports are not seen.
• Very large monorepos take a while to embed the first time.
• The model can only answer from retrieved chunks; broad "how does the whole app work" questions get a partial answer.

Changelog

• 1.0 (October 2026): First release. Structure aware chunking, local embeddings, identifier boost, Mermaid dependency map.