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. पार्स

एक भाषा-विशिष्ट पार्सर निर्देशिका को स्कैन करता है, प्रत्येक फ़ाइल को tree-sitter AST में पार्स करता है, और निम्नलिखित निकालता है:

- **नोड्स** — फंक्शन, मेथड, क्लास, स्ट्रक्ट, इंटरफ़ेस, ट्रेट, एनम, मॉड्यूल, नेमस्पेस
- **एजेज़** — कॉल, इनहेरिटेंस, इम्प्लीमेंटेशन, कंटेनमेंट, इम्पोर्ट्स
- **मेटाडेटा** — टाइप एनोटेशन, साइक्लोमैटिक कॉम्प्लेक्सिटी, ब्रांचेज़, डॉकस्ट्रिंग्स, एक्सेप्शन टाइप्स

### समर्थित भाषाएँ

| भाषा | एक्सटेंशन | मुख्य कंस्ट्रक्ट |
| --- | --- | --- |
| Python | `.py` | फंक्शन, क्लास, मेथड |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | फंक्शन, क्लास, एरो फंक्शन |
| TypeScript | `.ts`, `.tsx` | फंक्शन, क्लास, इंटरफ़ेस, एनम |
| PHP | `.php` | फंक्शन, क्लास, इंटरफ़ेस, ट्रेट |
| Ruby | `.rb` | मेथड, क्लास, मॉड्यूल |
| C | `.c`, `.h` | फंक्शन, स्ट्रक्ट, एनम |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | फंक्शन, क्लास, स्ट्रक्ट, नेमस्पेस |
| C# | `.cs` | मेथड, क्लास, इंटरफ़ेस, स्ट्रक्ट, एनम, नेमस्पेस |
| Java | `.java` | मेथड, क्लास, इंटरफ़ेस, एनम |
| Go | `.go` | फंक्शन, मेथड, स्ट्रक्ट, इंटरफ़ेस |
| Rust | `.rs` | फंक्शन, स्ट्रक्ट, ट्रेट, एनम, इम्प्ल ब्लॉक्स |
| Solidity | `.sol` | कॉन्ट्रैक्ट्स, इंटरफ़ेसेज़, लाइब्रेरीज़, फंक्शन, मॉडिफ़ायर्स, स्ट्रक्ट, एनम |
| Cairo | `.cairo` | फंक्शन, ट्रेट, स्ट्रक्ट, एनम, इम्प्ल ब्लॉक्स, StarkNet कॉन्ट्रैक्ट्स |
| Circom | `.circom` | टेम्प्लेट्स, फंक्शन, सिग्नल्स, कम्पोनेंट्स |
| Haskell | `.hs` | फंक्शन, डेटा टाइप्स, टाइप क्लासेज़, इंस्टेंसेज़ |
| Erlang | `.erl` | फंक्शन, रिकॉर्ड्स, बिहेवियर्स, मॉड्यूल्स |
| Miden Assembly | `.masm` | प्रोसीजर्स, एंट्रीपॉइंट्स, कॉन्स्टेंट्स, इनवोकेशन्स |
| Swift | `.swift` | फंक्शन, क्लास, स्ट्रक्ट, एनम, प्रोटोकॉल, एक्सटेंशन्स |
| Objective-C | `.m`, `.mm`, `.h` | C फंक्शन, क्लास, मेथड (सेलेक्टर-आधारित नामकरण) |
| Kotlin | `.kt`, `.kts` | फंक्शन, क्लास, इंटरफ़ेसेज़, डेटा क्लास, ऑब्जेक्ट्स, मेथड |
| Dart | `.dart` | फंक्शन, क्लास, एब्स्ट्रैक्ट क्लास, मेथड, कंस्ट्रक्टर्स |
| Move | `.move` | मॉड्यूल्स, फंक्शन्स, इम्पोर्ट्स, डायरेक्ट कॉल्स |
| Tact | `.tact` | कॉन्ट्रैक्ट्स, स्ट्रक्ट्स, रिसीवर्स, फंक्शन्स |
| Func | `.fc`, `.func` | फंक्शन्स, इन्क्लूड्स, डायरेक्ट कॉल्स |
| Sway | `.sw` | एबीआई इंटरफ़ेसेज़, स्ट्रक्ट्स, इम्प्ल मेथड, फंक्शन्स |
| Rego | `.rego` | पैकेजेज़, इम्पोर्ट्स, पॉलिसी रूल्स, रूल कॉल्स |
| Proto | `.proto` | सर्विसेज़, आरपीसी, मैसेजेज़, फील्ड्स, एनम |
| Thrift | `.thrift` | सर्विसेज़, फंक्शन्स, स्ट्रक्ट्स, फील्ड्स, एनम |
| GraphQL | `.graphql`, `.gql` | ऑब्जेक्ट टाइप्स, रूट ऑपरेशन्स, फील्ड्स, एनम |
| SQL | `.sql` | स्कीमा, टेबल्स, व्यूज़, फंक्शन्स, प्रोसीजर्स |```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

**Node kinds:** `function`, `method`, `class`, `module`, `struct`, `interface`, `trait`, `enum`, `namespace`, `contract`, `library`, `template`, `proxy`

**Node origins:** `source`, `proxy`, `binary`, `synthetic`

**Edge kinds:** `calls`, `inherits`, `implements`, `contains`, `imports`, `resolves_to`, `type_uses`, `specializes`, `corresponds_to`

**Edge confidence:** `certain`, `inferred`, `uncertain`

अनसुलझे कॉल को प्रॉक्सी नोड्स के रूप में मूर्त रूप दिया जाता है जैसे कि
`proxy.unresolved:<raw-symbol>` ताकि ट्रैवर्सल परिणाम यह दिखा सकें कि स्रोत विश्लेषण ने कहाँ रिज़ॉल्यूशन खो दिया है, बजाय उस एज को चुपचाप छोड़ने के। बाइनरी विश्लेषण समर्थन बाहरी JSON कॉल ग्राफ़ आयात करता है; Trailmark स्वयं एक्सीक्यूटेबल को डिसअसेंबल नहीं करता है।

### उदाहरण ग्राफ़

यह 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

## स्थापना

नीचे दिए गए उदाहरण वर्तमान विकास शाखा का अनुसरण करते हैं। नवीनतम प्रकाशित पैकेज के लिए, PyPI से स्थापित करें। यहाँ वर्णित सटीक सुविधा सेट के लिए, एक चेकआउट से स्थापित करें और `uv run` के माध्यम से कमांड चलाएँ।```bash
# Latest published release
uv pip install trailmark

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

### एंट्रीपॉइंट का पता लगाना

Trailmark स्वचालित रूप से `graph.entrypoints` को भरता है ताकि `attack_surface()`, टेन्ट प्रसार, और विशेषाधिकार-सीमा पार करने के लिए डेटा उपलब्ध हो। पता लगाना चार स्तरों में चलता है, प्रत्येक पिछले को ओवरराइड करता है:

1. **सामान्य `main` ह्यूरिस्टिक।** किसी भी भाषा में `main` नामक कोई भी फ़ंक्शन। `user_input` / `trusted_internal` / `low` के रूप में टैग किया गया।
2. **फ्रेमवर्क-जागरूक स्कैन।** प्रति भाषा डेकोरेटर, विशेषता और दृश्यता पैटर्न — नीचे दी गई तालिका देखें।
3. **pyproject.toml [project.scripts] ।** स्पष्ट CLI लक्ष्यों को उन्नत ट्रस्ट/एसेट वर्गीकरण मिलता है।
4. **रिपॉजिटरी-स्थानीय ओवरराइड फ़ाइल।** `.trailmark/entrypoints.toml` में हाथ से क्यूरेट किए गए एंट्रीपॉइंट हमेशा जीतते हैं।

फ्रेमवर्क कवरेज:

| भाषा | पता लगाए गए फ्रेमवर्क |
| --- | --- |
| 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 + पुरानी एनोटेशन |
| Rust | actix-web, rocket, FFI exports (`#[no_mangle]`, `pub extern "C"`), async-main attributes |
| Solidity | `external` / `public` दृश्यता |
| Cairo / StarkNet | `#[external]`, `#[view]`, `#[l1_handler]`, `#[constructor]` |
| Circom | `component main` घोषणाएँ |
| Miden Assembly | `export.<name>` निर्देश |
| Haskell | शीर्ष-स्तरीय `main ::` / `main =` |
| Erlang | `-export([...])` में सूचीबद्ध फ़ंक्शन |
| Swift | `@main` ऐप विशेषता |
| Objective-C | `UIApplicationDelegate` लाइफसाइकिल सेलेक्टर (उदाहरण के लिए `application:openURL:options:`) |
| Kotlin | Spring MVC / WebFlux एनोटेशन (Java के साथ साझा), Android घटक लाइफसाइकिल विधियाँ (`onCreate`, `onReceive`, `onBind`, ...) |
| Dart | `@pragma('vm:entry-point')` नेटिव-कॉलेबल मार्कर |
| Go | `http.HandleFunc` / `http.Handle` stdlib पंजीकरण, gin/chi/echo-शैली `<router>.GET/POST/...` हैंडलर पंजीकरण |
| Ruby | Rails कंट्रोलर एक्शन ( `ApplicationController` / `ActionController::*` को प्राप्त करने वाले वर्ग), Sidekiq वर्कर `perform` विधियाँ |
| C / C++ | `extern "C"` लिंकेज, `__attribute__((visibility("default")))`, `__declspec(dllexport)` |

ह्यूरिस्टिक्स जो कुछ भी छोड़ देते हैं, उसके लिए प्रोजेक्ट रूट में `.trailmark/entrypoints.toml` में स्पष्ट रूप से एंट्रीपॉइंट घोषित करें। फ़ाइल एकल-नोड और नियम-आधारित दोनों प्रविष्टियों का समर्थन करती है:```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"

References may be exact node IDs or unique names/suffixes. Ambiguous references,
unknown internal endpoints, invalid enum values, and malformed TOML raise
`ValueError`. Setting `external = true` explicitly permits unresolved endpoints
and creates proxy nodes. This file is a stable public configuration interface.

### Analysis limitations

- `entrypoint_paths_to()` reports call-graph reachability, not attacker-controlled
  data flow. Use preanalysis taint results as a coarse separate signal; Trailmark
  does not yet perform interprocedural taint analysis.
- TypeScript resolves direct calls and straightforward receivers assigned with
  `new ConcreteClass()`. Interface dispatch through manifests, computed property
  names, dependency-injection containers, and other dynamic mechanisms remains
  best-effort.
- SQL support is PostgreSQL-oriented and extracts schemas, tables, views,
  functions, procedures, and routine/view dependencies. It is not a complete
  SQL dialect validator or query-semantic analyzer.

### Programmatic API```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")

## लाइसेंस

Apache-2.0