---
id: trailmark
version: "0.5.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# trailmark — Parse source code into a queryable graph of functions, classes, calls, and semantic annotations

License: permissive · Maintenance: active · Downloads: 77.2K/mo

## What it is and what it does

Trailmark converts source code into a queryable directed graph of semantic entities—functions, classes, methods, calls, and annotations—across multiple programming languages. It uses tree-sitter for language-agnostic AST parsing and rustworkx for graph storage and traversal, extracting nodes (functions, classes, structs, etc.), edges (calls, inheritance, imports), and metadata (type annotations, cyclomatic complexity, exception types, docstrings). The package operates in three phases: parse (walk directories and extract code structure), index (load into a rustworkx graph with bidirectional mappings), and query (provide a high-level API for graph traversal and analysis).

The QueryEngine exposes methods to find callers, callees, transitive reachability, call paths between functions, complexity hotspots, entrypoint paths, and attack surface. It also supports semantic annotations (adding custom metadata to nodes), structural diffs between graphs, and integration with SARIF and weAudit findings. This makes it useful for security analysis, code review, impact assessment, and identifying gaps between code assumptions and test coverage.

Use it for:

- Map call chains from user-controlled entrypoints to sensitive functions for security auditing.
- Identify functions with high cyclomatic complexity and trace which code paths reach them.
- Analyze cross-file dependencies and detect circular imports or unexpected coupling.
- Augment static-analysis findings (SARIF, weAudit) with transitive reachability context.
- Generate attack-surface reports showing which functions are reachable from external inputs.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Parses source code into a queryable graph of functions, classes, calls, and semantic annotations using tree-sitter and rustworkx for security and code-structure analysis.

Yes, if you need multi-language code-structure analysis for security or code-review workflows. The package is actively maintained, has no known vulnerabilities, and covers multiple languages. The Python 3.12 requirement and early version number (0.5.0) mean it is not yet universally deployable, but the low install friction and permissive license make it a reasonable choice for teams already on modern Python. Verify performance and accuracy for your specific codebase before relying on it for critical security decisions.

## Install

pip install trailmark
uv add trailmark
poetry add trailmark

## Installing trailmark

Before you install: Low install friction with a pure-wheel distribution. Active maintenance (last commit 2026-07-28) and recent releases. Requires Python 3.12+, which is current but not yet universal in production environments.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

pip install trailmark

from trailmark import parse_directory

graph = parse_directory('/path/to/code', language='python')
engine = graph.query_engine()
callers = engine.callers_of('module:function')

Requires Python 3.12 or later; tree-sitter language packs must be installed for each language you parse.

Verify before relying:

- Number of supported languages and their specific coverage beyond what the description excerpt lists.
- Performance characteristics and scalability limits for large codebases.
- Whether the package is production-ready or still in active research/development phase.
- Accuracy and coverage of cross-file call resolution and type inference across all supported languages.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 77.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

code graph parsing, static analysis AST, function call graph, source code structure query, multi-language code analysis, security code mapping, call path analysis, static-analysis, code-graph, security-audit

[View on SkillFed](https://skillfed.io/packages/trailmark) · [View on PyPI](https://pypi.org/project/trailmark/)