If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/CoatiSoftware/Sourcetrail shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 4y ago

• 19 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live CoatiSoftware/Sourcetrail repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/CoatiSoftware/Sourcetrail.

What it runs against: a local clone of CoatiSoftware/Sourcetrail — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in CoatiSoftware/Sourcetrail | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1638 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of CoatiSoftware/Sourcetrail. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/CoatiSoftware/Sourcetrail.git
#   cd Sourcetrail
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of CoatiSoftware/Sourcetrail and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "CoatiSoftware/Sourcetrail(\\.git)?\\b" \\
  && ok "origin remote is CoatiSoftware/Sourcetrail" \\
  || miss "origin remote is not CoatiSoftware/Sourcetrail (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "DOCUMENTATION.md" \\
  && ok "DOCUMENTATION.md" \\
  || miss "missing critical file: DOCUMENTATION.md"
test -f "bin/app/data/ProjectSettings_template.xml" \\
  && ok "bin/app/data/ProjectSettings_template.xml" \\
  || miss "missing critical file: bin/app/data/ProjectSettings_template.xml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1638 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1608d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/CoatiSoftware/Sourcetrail"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Sourcetrail is a free, offline-capable source code explorer that visualizes code dependencies and enables interactive navigation through unfamiliar codebases. It parses C, C++, Java, and Python source code, builds a queryable database, and renders interactive graphs of function calls, class hierarchies, and includes—helping developers understand large projects without leaving the IDE. Monolithic desktop application: source code organized under src/ with language-specific parsers (C++/Java/Python), a SQLite-backed project database layer, Qt-based GUI under bin/app/data/gui/ (CSS-styled views: code_view, bookmark_view, graph_view), and embedded indexer. Build system: CMake (cross-platform); GUI resources (fonts, color schemes, templates) committed to bin/app/data/.

Software engineers onboarding to unfamiliar C/C++/Java/Python codebases, code reviewers needing rapid dependency understanding, and legacy code maintainers who need to map call graphs and symbol relationships before making changes.

Archived but stable: the project was frozen end-of-2021 by original maintainers (see blog reference in README), indicating it reached feature-complete status but is no longer receiving active development. CI/CD via Travis CI (Linux) and AppVeyor (Windows) shows historical production-grade setup. Not abandoned by community—it's archived by design after successful release cycle.

Primary risk is the archived status—no security patches, no dependency updates, and no active issue triage since 2021. The codebase is large (3.3M lines C++, 1.7M lines Java) and multi-platform, increasing maintenance burden if forked. However, zero external runtime dependencies (self-contained toolchain) reduces supply-chain risk compared to typical projects.

Nothing—project is archived. Last activity was end-of-2021. No open PRs, no active milestones. Community forks may exist, but the canonical repository accepts no new features or bug fixes from original maintainers.

git clone https://github.com/CoatiSoftware/Sourcetrail.git
cd Sourcetrail
mkdir build && cd build
cmake ..
cmake --build . --config Release
./bin/Sourcetrail

Requires CMake 3.9+, C++11 compiler, Qt 5.9+, and platform-specific SDKs (LLVM for C/C++, Java JDK for Java parsing). See CONTRIBUTING.md and DOCUMENTATION.md for detailed setup.

Daily commands: After build (see howDoIStart), the executable is ./bin/Sourcetrail (or .exe on Windows). Launch GUI, create a new project via File > New Project, configure source paths, and run indexing. No separate dev server—it's a single-process desktop app.

• CMakeLists.txt — Master build configuration for this cross-platform C++ project; understanding the build system is essential for compilation and dependency management.
• README.md — Explains that Sourcetrail is archived as of end-2021; critical context for contributors evaluating whether to fork or maintain.
• DOCUMENTATION.md — Primary reference for getting started, architecture overview, and development workflow for all contributor onboarding.
• bin/app/data/ProjectSettings_template.xml — Template for project configuration; essential for understanding how Sourcetrail parses and stores indexing metadata.
• CONTRIBUTING.md — Contributor guidelines covering code standards, submission process, and development environment setup.
• .clang-format — Code style enforcement for C++ codebase; all pull requests must conform to this formatting standard.
• CHANGELOG.md — Historical record of features, fixes, and breaking changes; essential for understanding evolution and version compatibility.

• Language Parser (C++/Java/Python) (Likely Clang (C/C++), ANTLR or equiv. (Java/Python)) — Reads source files, performs lexical/syntactic/semantic analysis, extracts symbol definitions and cross-references
  • Failure mode: Parser crash or incorrect symbol extraction leads to incomplete/corrupted index and user-visible graph anomalies
• Indexing Engine (C++ core, ProjectSettings_template.xml configuration) — Orchestrates parsing pipeline, deduplicates symbols, builds relationship graph, persists to local database
  • Failure mode: Index corruption or partial parse results in inconsistent symbol navigation and broken cross-references
• Graph Visualizer (Qt graphics framework, CSS styling (graph_view.css)) — Lays out and renders interactive dependency graph with zoom, pan, and node selection; updates in response to user actions
  • Failure mode: Poor layout performance or rendering glitches degrade user

Add Support for a New Programming Language

1. Create a new language parser module in the indexing engine following the plugin architecture used by C++, Java, and Python parsers (CMakeLists.txt)
2. Define language-specific indexing rules and symbol mapping in a new language configuration section (bin/app/data/ProjectSettings_template.xml)
3. Add language icon to the graph view icon set for consistent visual representation (bin/app/data/gui/icon/cpp_icon.png)
4. Update DOCUMENTATION.md with supported language syntax and any language-specific limitations (DOCUMENTATION.md)

Customize the Visual Theme

1. Create a new XML color scheme file in the color_schemes directory following the existing dark/bright/solarized patterns (bin/app/data/color_schemes/dark.xml)
2. Define CSS styling rules that reference the color variables from the scheme (bin/app/data/gui/graph_view/graph_view.css)
3. Update code view, bookmark view, and other component stylesheets to use consistent theme variables (bin/app/data/gui/code_view/code_view.css)

Add a New UI View Component

1. Create a new subdirectory under bin/app/data/gui/ with the component name (e.g., my_view) (bin/app/data/gui/bookmark_view/bookmark_view.css)
2. Write component-specific CSS styling rules matching the application's design system (bin/app/data/gui/graph_view/graph_view.css)
3. Add required PNG icons to an images/ subdirectory following naming conventions (bin/app/data/gui/graph_view/images/annotation.png)
4. Register the new view in CMakeLists.txt to include it in the build (CMakeLists.txt)

• C++ with Qt/CMake — Provides cross-platform GUI capability (Windows/macOS/Linux) with native performance required for large codebase analysis and interactive graph rendering.
• Multiple Language Parsers (C++, Java, Python) — Supports diverse language ecosystems; uses existing parsers (likely Clang for C/C++, ANTLR or equivalent for Java/Python) to enable fast, accurate symbol indexing.
• Embedded XML Configuration — ProjectSettings_template.xml and color schemes use XML for human-readable, extensible configuration without external dependencies.
• CSS-based UI Theming — Separates styling from logic, enabling dark/bright/solarized themes without code changes; reduces UI maintenance burden.

• Archived project (end of 2021)

  • Why: Authors decided to discontinue active maintenance and new feature development.
  • Consequence: No ongoing security updates, language support enhancements, or bug fixes from original team; community forks must assume maintenance responsibility.

• Offline-first architecture

  • Why: Enables analysis of proprietary/sensitive codebases without cloud upload or network dependency.
  • Consequence: Cannot provide collaborative, cloud-based code exploration; indexing is local and machine-specific.

• Cross-platform single codebase (C++)

  • Why: One compiled binary serves all platforms (Windows, macOS, Linux), reducing maintenance effort.
  • Consequence: Platform-specific bugs require careful testing; some native features may be unavailable or less optimized per platform.

• Real-time collaborative code exploration (single-user, local analysis only)
• Cloud-based indexing or multi-user workspace sharing
• Active development and new feature releases (archived project)
• Support for languages beyond C, C++, Java, Python (as of archive date)
• IDE plugin architecture for integrated development environments
• Vulnerability scanning or static security analysis

1. Archive status: repository no longer accepts contributions or maintains dependencies—forks required for modern compilers/Qt versions. 2. LLVM dependency: C/C++ indexing requires LLVM/Clang linked at build time; version mismatches cause cryptic parser failures. 3. Platform-specific builds: CMake script has conditional logic for Windows (MSVC/Visual Studio), Linux (GCC), and macOS (Clang); cross-compilation is fragile. 4. Qt version pinning: requires Qt 5.9+; Qt 6 migrations would need GUI rework (signals/slots signatures changed). 5. Project file format: existing .srctrlprj projects from newer forks may not load in archived version; XML schema not versioned.

• Abstract Syntax Tree (AST) traversal — Sourcetrail's entire indexing pipeline walks ASTs produced by language parsers (LLVM for C++, ANTLR for Python/Java) to extract symbols and relationships; understanding AST nodes is critical for parser debugging.
• Symbol database normalization — The SQLite backend (src/lib/component/storage/) must deduplicate and normalize qualified names across translation units (e.g., std::vector vs vector in different includes); fundamental to query correctness.
• Graph rendering (force-directed layout) — The interactive dependency graph in src/lib/gui/graphics/ likely uses force-directed algorithms to position nodes; understanding physics-based layout helps optimize performance for large call graphs.
• Translation unit (TU) semantics in C++ — C/C++ parsers must handle one-definition-rule (ODR), inline functions, and extern declarations correctly; Sourcetrail's C++ indexer must merge symbols across TUs without creating duplicates.
• Query optimization for large graphs — Projects with millions of symbols require efficient SQLite queries (indexes, join order); the storage layer must balance query speed vs. memory overhead for interactive responsiveness.
• Cross-platform UI abstraction (Qt framework) — Sourcetrail runs identically on Windows/macOS/Linux via Qt; understanding signal/slot patterns and platform-specific quirks (file dialogs, rendering backends) is essential for GUI contributions.
• Incremental indexing and caching — Large codebases need incremental re-indexing on file changes; Sourcetrail must cache parsed ASTs and detect deltas efficiently rather than re-parse the entire project.

• LLVM/llvm-project — Sourcetrail's C/C++ indexing depends on LLVM/Clang; understanding AST handling here is essential for parser improvements.
• CoatiSoftware/SourcetrailDB — Companion SDK allowing custom language extensions; developers building custom parsers will plugin into this SourcetrailDB database format.
• ctags/ctags — Alternative symbol indexing tool; Sourcetrail users sometimes fall back to ctags for languages Sourcetrail doesn't support (Go, Rust).
• woboq/codebrowser — Similar code exploration tool generating static HTML; comparison point for architecture and HTML-based visualization vs Qt GUI approach.
• tomtom-international/oss-reproducible-builds — Best practices for reproducible builds across platforms; relevant to Sourcetrail's multi-OS CI/AppVeyor/Travis setup.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Migrate from Travis CI and AppVeyor to GitHub Actions for unified CI/CD

The repo uses outdated CI services (.travis.yml and appveyor.yml). GitHub Actions is now the standard for GitHub projects, offering better integration, faster builds, and reduced maintenance. This modernizes the build pipeline and makes contributions easier to validate.

• [ ] Create .github/workflows/build-linux.yml to replace .travis.yml (build on Linux with CMake)
• [ ] Create .github/workflows/build-windows.yml to replace appveyor.yml (build on Windows with MSVC)
• [ ] Create .github/workflows/build-macos.yml for macOS builds (currently missing)
• [ ] Test workflows with actual build commands from existing CI configs
• [ ] Document new workflow status badges in README.md
• [ ] Remove or archive .travis.yml and appyeyor.yml after validation

Add comprehensive CMakeLists.txt documentation and build troubleshooting guide

The repo has CMakeLists.txt as the build entry point but DOCUMENTATION.md and CONTRIBUTING.md lack specific build instructions for each platform. New contributors struggle with complex C++ builds. Adding platform-specific build guides with dependency lists would reduce friction.

• [ ] Review CMakeLists.txt to identify all required dependencies (Qt, Clang, Boost, etc.)
• [ ] Create BUILDING.md with Windows, Linux, and macOS build steps with dependency installation commands
• [ ] Document required compiler versions and supported OS versions
• [ ] Add troubleshooting section for common CMake errors
• [ ] Link BUILDING.md from README.md and CONTRIBUTING.md
• [ ] Include examples of out-of-source builds and common CMake flags

Create unit test suite for core analyzer modules with CMake test integration

The project lacks visible test infrastructure despite being a code analysis tool. Adding a CMake-integrated test suite for the indexer/parser core would catch regressions early and give contributors confidence when modifying critical analysis logic.

• [ ] Create test/ directory structure with subdirs for parser, indexer, and utility tests
• [ ] Add GoogleTest or Catch2 as a CMake dependency with ENABLE_TESTS option
• [ ] Write initial tests for source file parser (likely in src/lib/analyzer)
• [ ] Integrate tests into CMakeLists.txt with add_test() commands
• [ ] Configure CI workflows to run tests on each commit
• [ ] Document test running instructions in CONTRIBUTING.md (e.g., cmake -DENABLE_TESTS=ON)

• Add syntax highlighting for Python 3.9+ features: The Python parser in src/lib/component/py/ uses ANTLR but the grammar may not recognize walrus operator (:=), match statements, or type hints from PEP 604. Update the grammar and add test cases.
• Document build prerequisites per OS in DOCUMENTATION.md: README and CONTRIBUTING.md lack explicit lists of required packages for Ubuntu/CentOS/macOS (LLVM version, Qt path, CMake flags). Add a BUILD_SETUP.md with copy-paste commands.
• Add unit tests for CxxParser edge cases: src/lib/component/cxx/ has no dedicated test files visible in repo; parsers handle macros, lambdas, templates—add test cases for C++17/20 syntax to prevent regressions.

The Sourcetrail codebase presents a moderate security posture, primarily constrained by its archived status with no active maintenance since 2021. While no obvious code-level vulnerabilities are apparent from the file structure analysis, the lack of active security updates represents a significant long-term risk. The absence of visible dependency information prevents comprehensive vulnerability assessment. Users should treat this as legacy software and consider alternatives for new projects. For organizations continuing to use Sourcetrail, maintaining their own security patches and conducting regular audits is essential.

• Medium · Archived Project with No Active Maintenance — Repository root - README.md indicates archived status. The project was officially archived by the original authors and maintainers by the end of 2021. This means there are no active security updates, bug fixes, or vulnerability patches being released. Any vulnerabilities discovered after the archive date will not be addressed. Fix: Users should be aware that this is legacy software. Consider using actively maintained alternatives for production environments. If continued use is necessary, perform your own security audits and maintain a fork with security patches.
• Medium · Missing Dependency Information — Repository root - Dependencies/Package file content is empty. No package management files (package.json, requirements.txt, pom.xml, Cargo.toml, conanfile.txt, etc.) or dependency lock files are visible in the provided file structure. This makes it impossible to assess whether the project uses insecure or outdated dependencies. Fix: Provide CMakeLists.txt analysis and any third-party library lists to identify specific dependency versions. Run dependency scanning tools like OWASP Dependency-Check or Snyk on the actual codebase.
• Low · Incomplete README - Broken Image Link — README.md. The README.md file contains an incomplete/broken image link: '![","Sourcetrail User Interface"](docs/readme/user_interface.png' - missing closing parenthesis. While not a direct security issue, it indicates potential quality control gaps. Fix: Fix the markdown syntax to properly close the image link.
• Low · No Visible Security Policy — Repository root. No SECURITY.md or security policy file is visible in the provided file structure. For an archived project, this may be acceptable, but users should be informed about the lack of security support. Fix: Consider adding a SECURITY.md file documenting that the project is archived and not accepting security patches.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.