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

class CodeUnit {
    id: str
    name: str
    kind: NodeKind
    location: SourceLocation
    parameters: tuple[Parameter]
    return_type: TypeRef
    exception_types: tuple[TypeRef]
    cyclomatic_complexity: int
    branches: tuple[BranchInfo]
    docstring: str
}

class CodeEdge {
    source_id: str
    target_id: str
    kind: EdgeKind
    confidence: EdgeConfidence
}

class Annotation {
    kind: AnnotationKind
    description: str
    source: str
}

class EntrypointTag {
    kind: EntrypointKind
    trust_level: TrustLevel
    description: str
    asset_value: AssetValue
}

CodeGraph "1" *-- "*" CodeUnit
CodeGraph "1" *-- "*" CodeEdge
CodeGraph "1" *-- "*" Annotation
CodeGraph "1" *-- "*" EntrypointTag

**Tipos de nodos:** `function`, `method`, `class`, `module`, `struct`, `interface`, `trait`, `enum`, `namespace`, `contract`, `library`, `template`, `proxy`

**Orígenes de nodos:** `source`, `proxy`, `binary`, `synthetic`

**Tipos de aristas:** `calls`, `inherits`, `implements`, `contains`, `imports`, `resolves_to`, `type_uses`, `specializes`, `corresponds_to`

**Confianza de aristas:** `certain`, `inferred`, `uncertain`

Las llamadas no resueltas se materializan como nodos proxy como
`proxy.unresolved:<raw-symbol>` para que los resultados de recorrido puedan mostrar dónde el análisis de fuente perdió resolución en lugar de eliminar silenciosamente esa arista. El soporte de análisis binario importa gráficos de llamadas JSON externos; Trailmark no desensambla ejecutables por sí mismo.

### Ejemplo de Grafo

Dado este código Python:```python
class Auth:
    def verify(self, token: str) -> bool:
        return self._check_sig(token)

    def _check_sig(self, token: str) -> bool:
        ...

def handle_request(req: Request) -> Response:
    auth = Auth()
    if auth.verify(req.token):
        return process(req)
    return deny()

classDef fn fill:#007bff26,stroke:#007bff,color:#007bff
classDef cls fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

class HR,P,D fn
class A,AV,CS cls

## Instalación

Los ejemplos a continuación siguen la rama de desarrollo actual. Para el paquete publicado más reciente, instálelo desde PyPI. Para el conjunto exacto de características descrito aquí, instale desde un checkout y ejecute comandos mediante `uv run`.```bash
# Latest published release
uv pip install trailmark

# Current checkout / development branch
uv sync --all-groups

### Detección de puntos de entrada

Trailmark llena automáticamente `graph.entrypoints` para que `attack_surface()`, la propagación de datos contaminados y el cruce de límites de privilegios tengan datos con los que trabajar. La detección se ejecuta en cuatro capas, cada una anula la anterior:

1. **Heurística genérica `main`.** Cualquier función llamada `main` en cualquier lenguaje. Etiquetada como `user_input` / `trusted_internal` / `low`.
2. **Escaneo consciente del framework.** Patrones de decoradores, atributos y visibilidad por lenguaje — vea la tabla a continuación.
3. **`pyproject.toml [project.scripts]`.** Destinos CLI explícitos obtienen una clasificación de confianza/activos mejorada.
4. **Archivo de anulación local del repositorio.** Los puntos de entrada seleccionados manualmente en `.trailmark/entrypoints.toml` siempre ganan.

Cobertura de frameworks:

| Lenguaje | Frameworks detectados |
| --- | --- |
| Python | Flask, FastAPI, aiohttp, Click, Typer, Celery |
| JavaScript / TypeScript | NestJS, Next.js (App Router + Pages API), AWS Lambda |
| Java | Spring MVC / WebFlux, JAX-RS, Kafka listeners, servlets |
| C# | ASP.NET Core, Azure Functions |
| PHP | Symfony `#[Route]` attributes + legacy annotations |
| Rust | actix-web, rocket, FFI exports (`#[no_mangle]`, `pub extern "C"`), async-main attributes |
| Solidity | `external` / `public` visibility |
| Cairo / StarkNet | `#[external]`, `#[view]`, `#[l1_handler]`, `#[constructor]` |
| Circom | `component main` declarations |
| Miden Assembly | `export.<name>` directives |
| Haskell | top-level `main ::` / `main =` |
| Erlang | funciones listadas en `-export([...])` |
| Swift | atributo de aplicación `@main` |
| Objective-C | selectores de ciclo de vida de `UIApplicationDelegate` (ej. `application:openURL:options:`) |
| Kotlin | anotaciones de Spring MVC / WebFlux (compartidas con Java), métodos del ciclo de vida de componentes de Android (`onCreate`, `onReceive`, `onBind`, ...) |
| Dart | marcadores `@pragma('vm:entry-point')` invocables nativamente |
| Go | registros de `http.HandleFunc` / `http.Handle` de la stdlib, registros de manejadores `<router>.GET/POST/...` estilo gin/chi/echo |
| Ruby | acciones de controlador de Rails (clases que heredan de `ApplicationController` / `ActionController::*`), métodos `perform` de trabajadores Sidekiq |
| C / C++ | enlace `extern "C"`, `__attribute__((visibility("default")))`, `__declspec(dllexport)` |

Para cualquier cosa que las heurísticas no detecten, declare puntos de entrada explícitamente en `.trailmark/entrypoints.toml` en la raíz del proyecto. El archivo admite entradas tanto de nodo único como basadas en reglas:```toml
# Single-node entry
[[entrypoint]]
node = "my_module:handle_request"  # node id, or "module.path:function"
kind = "api"                       # user_input | api | database | file_system | third_party
trust = "untrusted_external"       # untrusted_external | semi_trusted_external | trusted_internal
asset_value = "high"               # high | medium | low
description = "HTTP POST /auth"

# Rule: every PHP script under public_html/ is a web-exposed entrypoint.
[[entrypoint]]
file_glob = "public_html/**/*.php"
kind = "user_input"
trust = "untrusted_external"
asset_value = "high"
description = "Web-exposed PHP script"

# Rule: any function that takes a PSR-7 request object.
[[entrypoint]]
param_type = "ServerRequestInterface"
kind = "api"
trust = "untrusted_external"
asset_value = "high"
description = "PSR-7 HTTP handler"

# Rule: functions named `handle_*`.
[[entrypoint]]
name_regex = "^handle_"
kind = "api"
trust = "untrusted_external"

# Rule: conditions compose with AND — web.py files AND name starts with handle_.
[[entrypoint]]
file_glob = "public/*.py"
name_regex = "^handle_"
kind = "api"
trust = "untrusted_external"

Las referencias pueden ser IDs de nodo exactos o nombres/sufijos únicos. Las referencias ambiguas,
los endpoints internos desconocidos, los valores de enum no válidos y el TOML mal formado lanzan
`ValueError`. Establecer `external = true` explícitamente permite endpoints no resueltos
y crea nodos proxy. Este archivo es una interfaz de configuración pública estable.

### Limitaciones del análisis

- `entrypoint_paths_to()` informa sobre la alcanzabilidad del grafo de llamadas, no sobre el flujo de datos
  controlado por el atacante. Utilice los resultados de taint del preanálisis como una señal separada gruesa; Trailmark
  aún no realiza análisis de taint interprocedimental.
- TypeScript resuelve llamadas directas y receptores simples asignados con
  `new ConcreteClass()`. El envío de interfaces a través de manifiestos, nombres de propiedades computadas,
  contenedores de inyección de dependencias y otros mecanismos dinámicos sigue siendo un esfuerzo máximo.
- El soporte SQL está orientado a PostgreSQL y extrae esquemas, tablas, vistas,
  funciones, procedimientos y dependencias de rutinas/vistas. No es un validador completo
  de dialecto SQL ni un analizador semántico de consultas.

### API programática```python
from trailmark.parse import parse_directory, parse_file
from trailmark.query.api import QueryEngine

# Parse-only API: get the raw CodeGraph without building GraphStore/QueryEngine.
graph = parse_file("path/to/file.py")
graph = parse_directory("path/to/project", language="auto")

# Single-language (default) or auto-detect + merge across all languages
engine = QueryEngine.from_directory("path/to/project")
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine = QueryEngine.from_directory("path/to/project", language="python,rust")

# Direct neighbors
engine.callers_of("handle_request")
engine.callees_of("handle_request")

# Transitive slicing — who could reach this sink, or what could it reach?
engine.ancestors_of("Auth._check_sig")
engine.reachable_from("handle_request")

# Attack-surface paths from any detected entrypoint
engine.entrypoint_paths_to("Auth._check_sig")

# All call paths between two nodes
engine.paths_between("handle_request", "Auth._check_sig")

# Functions with cyclomatic complexity >= 10
engine.complexity_hotspots(10)

# What functions can raise a given exception? (uses parser-detected
# exception_types; no runtime tracing required)
engine.functions_that_raise("PermissionError")

# Add and query semantic annotations
from trailmark.models.annotations import AnnotationKind

engine.annotate(
    "handle_request",
    AnnotationKind.ASSUMPTION,
    "Caller has already authenticated the session token",
    source="llm",
)
engine.annotations_of("handle_request")
engine.nodes_with_annotation(AnnotationKind.FINDING)

# Diff against an earlier snapshot of the same codebase
before = QueryEngine.from_directory("before/")
diff = engine.diff_against(before)
# diff contains: summary_delta, nodes {added/removed/modified},
# edges {added/removed}, entrypoints {added/removed/modified}

# Run the built-in audit-oriented preanalysis passes
engine.preanalysis()
engine.findings()
engine.subgraph_names()

# Programmatic augmentation hooks for external tooling
engine.augment_sarif("results.sarif")
engine.augment_weaudit("findings.json")

## Licencia

Apache-2.0