Tracemoor

Adopt an existing codebase

This section covers the first steps with a codebase that Tracemoor has not seen before: create an exploration for it, run the first analysis, check what the analysis recognised, and find the important parts. Most functions used here have their own topics in other sections. This section puts them in order.

Project and exploration

The project is the source code, usually a Git repository. The exploration is a separate folder in which Tracemoor keeps what it knows and writes about that project: the analysis cache, chat sessions, projectdocs, specs, docs and settings.

Tracemoor reads the project and writes to the exploration. Creating an exploration adds nothing to the project folder. Some functions write into the project on purpose, for example run.toml from Run and build or the recovery pointer from sharing an exploration.

Example: the project ~/development/Weatherreport has the exploration ~/CodeExplorerData/weatherreport. Both are Git repositories with their own history and their own remote.

flowchart LR
    P["Project<br/>source code, own Git repository"]
    E["Exploration<br/>analysis cache, sessions,<br/>projectdocs, specs, docs, settings"]
    E -- reads --> P

The analysis cache and the chat sessions stay on the machine. projectdocs, specs, docs and the project hints can be shared with a team through the exploration's own Git remote. What is shared lists every file.

The steps

  1. Create an exploration for the project, from a local folder or by cloning it from GitHub or Bitbucket.
  2. Run the first analysis. Exclude generated code and test fixtures before the analysis starts, then check the project profile that Tracemoor detected.
  3. Find your way in the codebase: entry points, hotspots, structural findings, questions to the AI.
  4. Record what you learn in projectdocs, anchored to the code it is about.
  5. Optional: generate specs from the code to describe the current behaviour.

Languages and project types lists what the analysis understands. To work on two codebases side by side, see Work in several windows.

The index

The analysis parses every source file with tree-sitter and builds the index: symbols, calls, imports, entry points, clusters, findings, a text index of string literals and UI labels, and the interface index of HTTP endpoints, messages and commands. Graph, search, gutter, the Call Chain Explorer and the AI's tools all read the index instead of the files.

The index lives in the exploration on this machine and can be rebuilt from the source at any time. Keep the index current describes how it follows changes.