Trailmark

Analiza el código fuente en grafos consultables de funciones, clases, llamadas y anotaciones semánticas para el análisis de seguridad.

Trailmark utiliza tree-sitter para el análisis AST independiente del lenguaje y rustworkx para el recorrido de grafos de alto rendimiento. La visión a largo plazo es combinar este grafo con pruebas de mutación y fuzzing guiado por cobertura para identificar brechas entre las suposiciones y la cobertura de pruebas que son alcanzables desde la entrada del usuario.

Cómo funciona

Trailmark opera en tres fases: parse, index y query.```mermaid flowchart TD A["Source Files"] --> B["tree-sitter Parser"] B --> C["CodeGraph (nodes + edges)"] C --> D["rustworkx GraphStore"] D --> E["QueryEngine"] E --> F["JSON / Summary / Hotspots"]

classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817

class A src
class B parse
class C,D data
class E,F query

### 1. Análisis

Un analizador específico para cada lenguaje recorre el directorio, analiza cada archivo en un AST de tree-sitter y extrae:

- **Nodos** — funciones, métodos, clases, estructuras, interfaces, traits, enums, módulos, espacios de nombres
- **Aristas** — llamadas, herencia, implementación, contención, importaciones
- **Metadatos** — anotaciones de tipo, complejidad ciclomática, ramas, docstrings, tipos de excepción

### Lenguajes admitidos

| Lenguaje | Extensiones | Constructos clave |
| --- | --- | --- |
| Python | `.py` | funciones, clases, métodos |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | funciones, clases, funciones flecha |
| TypeScript | `.ts`, `.tsx` | funciones, clases, interfaces, enums |
| PHP | `.php` | funciones, clases, interfaces, traits |
| Ruby | `.rb` | métodos, clases, módulos |
| C | `.c`, `.h` | funciones, structs, enums |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | funciones, clases, structs, espacios de nombres |
| C# | `.cs` | métodos, clases, interfaces, structs, enums, espacios de nombres |
| Java | `.java` | métodos, clases, interfaces, enums |
| Go | `.go` | funciones, métodos, structs, interfaces |
| Rust | `.rs` | funciones, structs, traits, enums, bloques impl |
| Solidity | `.sol` | contratos, interfaces, librerías, funciones, modificadores, structs, enums |
| Cairo | `.cairo` | funciones, traits, structs, enums, bloques impl, contratos StarkNet |
| Circom | `.circom` | templates, funciones, señales, componentes |
| Haskell | `.hs` | funciones, tipos de datos, clases de tipos, instancias |
| Erlang | `.erl` | funciones, registros, behaviours, módulos |
| Miden Assembly | `.masm` | procedimientos, puntos de entrada, constantes, invocaciones |
| Swift | `.swift` | funciones, clases, structs, enums, protocolos, extensiones |
| Objective-C | `.m`, `.mm`, `.h` | funciones C, clases, métodos (nombramiento basado en selectores) |
| Kotlin | `.kt`, `.kts` | funciones, clases, interfaces, clases de datos, objetos, métodos |
| Dart | `.dart` | funciones, clases, clases abstractas, métodos, constructores |
| Move | `.move` | módulos, funciones, importaciones, llamadas directas |
| Tact | `.tact` | contratos, structs, receptores, funciones |
| Func | `.fc`, `.func` | funciones, includes, llamadas directas |
| Sway | `.sw` | interfaces ABI, structs, métodos impl, funciones |
| Rego | `.rego` | paquetes, importaciones, reglas de política, llamadas a reglas |
| Proto | `.proto` | servicios, RPCs, mensajes, campos, enums |
| Thrift | `.thrift` | servicios, funciones, structs, campos, enums |
| GraphQL | `.graphql`, `.gql` | tipos de objeto, operaciones raíz, campos, enums |
| SQL | `.sql` | esquemas, tablas, vistas, funciones, procedimientos |```mermaid
flowchart TD
    subgraph "Per-File Parsing"
        F["Source file"] --> TS["tree-sitter AST"]
        TS --> EX["Extract nodes"]
        TS --> EC["Extract call edges"]
        TS --> EB["Count branches"]
        TS --> ET["Resolve types"]
    end

    EX --> CG["CodeGraph"]
    EC --> CG
    EB --> CG
    ET --> CG

    classDef src fill:#007bff26,stroke:#007bff,color:#007bff
    classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
    classDef extract fill:#ffc10726,stroke:#e6a817,color:#e6a817
    classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

    class F src
    class TS parse
    class EX,EC,EB,ET extract
    class CG data

Los IDs de nodo siguen el esquema module:function, module:Class o module:Class.method para una búsqueda inequívoca. El análisis de directorios resuelve llamadas entre archivos sin prefijo cuando existe una definición única; las llamadas ambiguas entre archivos se dejan en su destino original de mejor esfuerzo y se marcan como uncertain. La confianza de los bordes se etiqueta como certain (llamadas directas, self.method()), inferred (acceso a atributos en objetos que no son self), o uncertain (despacho dinámico o resolución ambigua).

2. Index

El GraphStore carga el CodeGraph en un PyDiGraph de rustworkx y construye asignaciones bidireccionales de ID/índice para una navegación rápida.

3. Query

El QueryEngine proporciona una API de alto nivel sobre el gráfico indexado: