Trailmark

स्रोत कोड को फ़ंक्शन, क्लास, कॉल और सुरक्षा विश्लेषण के लिए सिमैंटिक एनोटेशन के क्वेरी करने योग्य ग्राफ़ में पार्स करें।

Trailmark भाषा-अज्ञेय AST पार्सिंग के लिए tree-sitter और उच्च-प्रदर्शन ग्राफ़ ट्रैवर्सल के लिए rustworkx का उपयोग करता है। दीर्घकालिक दृष्टि इस ग्राफ़ को म्यूटेशन टेस्टिंग और कवरेज-निर्देशित फ़ज़िंग के साथ जोड़कर उपयोगकर्ता इनपुट से पहुँच योग्य धारणाओं और टेस्ट कवरेज के बीच अंतराल की पहचान करना है।

यह कैसे काम करता है

Trailmark तीन चरणों में काम करता है: पार्स, इंडेक्स, और क्वेरी।```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. पार्स

एक भाषा-विशिष्ट पार्सर निर्देशिका को स्कैन करता है, प्रत्येक फ़ाइल को 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

नोड आईडी असंदिग्ध लुकअप के लिए module:function, module:Class, या module:Class.method योजना का पालन करती हैं। निर्देशिका पार्सिंग उन बेयर क्रॉस-फ़ाइल कॉलों को हल करती है जहाँ एक अद्वितीय परिभाषा मौजूद होती है; अस्पष्ट क्रॉस-फ़ाइल कॉलों को उनके मूल सर्वोत्तम-प्रयास लक्ष्य पर छोड़ दिया जाता है और uncertain चिह्नित किया जाता है। एज कॉन्फिडेंस को certain (प्रत्यक्ष कॉल, self.method()), inferred (गैर-स्वयं ऑब्जेक्ट पर गुण एक्सेस), या uncertain (गतिशील डिस्पैच या अस्पष्ट समाधान) के रूप में टैग किया जाता है।

2. सूचकांक

GraphStore CodeGraph को एक rustworkx PyDiGraph में लोड करता है और तेज़ ट्रैवर्सल के लिए द्विदिश आईडी/सूचकांक मैपिंग बनाता है।

3. क्वेरी

QueryEngine अनुक्रमित ग्राफ पर एक उच्च-स्तरीय API प्रदान करता है:

Method	Description
callers_of(name)	नामित लक्ष्य के प्रत्यक्ष कॉलर
callees_of(name)	नामित स्रोत के प्रत्यक्ष कैलीज़
ancestors_of(name)	वे सभी फ़ंक्शन जो संक्रामक रूप से लक्ष्य तक पहुँच सकते हैं (ऊपरी स्लाइस)
reachable_from(name)	स्रोत से संक्रामक रूप से पहुँच योग्य प्रत्येक फ़ंक्शन
paths_between(src, dst)	दो नोड्स के बीच सभी सरल कॉल पथ
connect_subgraphs(source, target)	दो नामित उप-ग्राफ्स को जोड़ने वाले पथ
entrypoint_paths_to(name)	किसी भी पहचाने गए प्रवेश बिंदु से लक्ष्य तक पथ
attack_surface()	प्रवेश बिंदु जो विश्वास स्तर, संपत्ति मूल्य, और पार्सर विशेषताओं से टैग किए गए हैं (जब मौजूद हों)
complexity_hotspots(n)	चक्रीय जटिलता ≥ n वाले फ़ंक्शन
functions_that_raise(exc)	ऐसे फ़ंक्शन जिनकी पार्सर-पहचानित अपवाद सूची में exc शामिल है
generic_parameters(name)	एक नोड द्वारा घोषित जेनेरिक प्रकार पैरामीटर
type_references(name)	पैरामीटर, रिटर्न, अपवाद, और जेनेरिक-बाउंड प्रकार संदर्भ
annotate(name, kind, description, source)	एक नोड में एक सिमेंटिक एनोटेशन जोड़ें
annotations_of(name, kind=None)	एक नोड के लिए एनोटेशन प्राप्त करें, वैकल्पिक रूप से kind द्वारा फ़िल्टर किया गया
nodes_with_annotation(kind)	दिए गए एनोटेशन kind से टैग किया गया प्रत्येक नोड
clear_annotations(name, kind=None)	एक नोड से एनोटेशन हटाएं
diff_against(other)	इस इंजन के ग्राफ बनाम दूसरे का संरचनात्मक अंतर
preanalysis()	अंतर्निहित प्री-एनालिसिस पास चलाएं और एनोटेशन/उप-ग्राफ संग्रहीत करें
augment_sarif(path)	SARIF निष्कर्षों को ग्राफ में मर्ज करें
augment_weaudit(path)	weAudit निष्कर्षों को ग्राफ में मर्ज करें
augment_binary(path)	एक बाहरी बाइनरी-विश्लेषण ग्राफ JSON फ़ाइल को मर्ज करें
findings(kind=None)	निष्कर्ष-शैली एनोटेशन वाले नोड लौटाएं
subgraph(name)	एक नामित उप-ग्राफ में नोड लौटाएं
subgraph_edges(name)	एक नामित उप-ग्राफ के अंदर प्रेरित किनारे लौटाएं
subgraph_names()	ग्राफ पर वर्तमान में प्रत्येक नामित उप-ग्राफ की सूची बनाएं
summary()	नोड गणना, किनारे गणना, निर्भरताएँ
to_json()	पूर्ण ग्राफ निर्यात

डेटा मॉडल```mermaid

classDiagram class CodeGraph { language: str root_path: str nodes: dict[str, CodeUnit] edges: list[CodeEdge] annotations: dict[str, list[Annotation]] entrypoints: dict[str, EntrypointTag] dependencies: list[str] add_annotation(node_id, annotation) clear_annotations(node_id, kind=None) merge(other) }