Parse-Befehl
codeknit parse liest Quelldateien und schreibt deren Symbole (und optional Beziehungen zwischen ihnen) als .skt-Dateien oder JSON. Dieser Leitfaden behandelt die häufigsten Anwendungsfälle. Für die vollständige Liste der von allen Befehlen gemeinsam genutzten Flags siehe die CLI-Flags-Referenz. Für die Ausgabesyntax siehe die Referenz zum Ausgabeformat.
Ein Projekt zum ersten Mal parsen
Abschnitt betitelt „Ein Projekt zum ersten Mal parsen“codeknit parse ./srccodeknit schreibt chunkweise .skt-Dateien nach ./skeleton/: map_001.skt, map_002.skt und so weiter. Öffnen Sie die Chunks selektiv, anstatt alles auf einmal zu laden.
Um an einen anderen Ort zu schreiben, übergeben Sie das Ausgabeverzeichnis als zweites Argument:
codeknit parse ./src ./outputVerwenden Sie nicht das Quellverzeichnis oder eines seiner übergeordneten Verzeichnisse als Ausgabeverzeichnis.
Einen Ausgabemodus wählen
Abschnitt betitelt „Einen Ausgabemodus wählen“Wählen Sie einen Modus mit --output-mode.
| Modus | Verwenden Sie ihn, wenn | Ergebnis |
|---|---|---|
directory-flat |
Die meisten Projekte parsen (Standard) | map_001.skt, map_002.skt, … |
directory-tree |
Sie die Struktur einer einzelnen Datei nachschlagen möchten | Eine .skt-Datei pro Quelldatei, die den Quellbaum widerspiegelt |
inline |
Eine einzelne Datei parsen oder an ein anderes Tool weiterleiten | Ausgabe auf stdout; es wird kein Ausgabeverzeichnis verwendet |
Im Baummodus behalten die Dateinamen die Quelldateierweiterung: src/foo.c wird zu src/foo.c.skt, und src/foo.h wird zu src/foo.h.skt. Große Dateien werden in foo.c_part1.skt, foo.c_part2.skt usw. aufgeteilt.
codeknit parse ./src --output-mode directory-treeVermeiden Sie inline für ein ganzes Projekt. Es schreibt alles auf stdout und kann Ihr Terminal oder ein LLM-Kontextfenster überfluten.
Weitere Informationen zur Auswahl eines Modus finden Sie unter Ausgabemodi.
Erneutes Parsen desselben Projekts
Abschnitt betitelt „Erneutes Parsen desselben Projekts“codeknit weigert sich, in ein Verzeichnis zu schreiben, das bereits generierte Ausgabe für das ausgewählte Format enthält. Dies verhindert, dass veraltete und frische Chunks vermischt werden. Fügen Sie --clean hinzu, um die vorherige Ausgabe zu ersetzen:
codeknit parse ./src --clean--clean löscht nichts im Voraus. codeknit generiert die neue Ausgabe in einem Staging-Verzeichnis und ersetzt die alten generierten Dateien erst, nachdem die Generierung erfolgreich war. Wenn die Generierung fehlschlägt oder der Prozess unterbrochen wird, bleibt die vorherige Ausgabe erhalten oder wird beim nächsten Lauf wiederhergestellt. Dateien im Ausgabeverzeichnis, die codeknit nicht generiert hat, bleiben erhalten. Wenn eine von ihnen mit einem generierten Pfad kollidiert, schlägt der Lauf fehl.
Im JSON-Modus gelten dieselben Regeln für codeknit.json.
Fallstrick: gemischte Chunks. Symbol-IDs (S1, S2, …) und Beziehungsergebnisse können sich zwischen Läufen und Versionen ändern. Nach dem Upgrade auf 0.5.0 generieren Sie die gesamte Ausgabemenge mit --clean neu. Kombinieren Sie niemals Chunks aus verschiedenen Läufen.
Eine einzelne Datei parsen
Abschnitt betitelt „Eine einzelne Datei parsen“Richten Sie parse auf die Datei und verwenden Sie den inline-Modus:
codeknit parse ./src/main.go --output-mode inlineWenn Sie eine reguläre Quelldatei explizit auswählen, überspringt codeknit die Ignorieren-Datei- und Testdatei-Filterung dafür. Include/Exclude-Muster und die Größenbeschränkung gelten weiterhin.
JSON für Skripte abrufen
Abschnitt betitelt „JSON für Skripte abrufen“codeknit parse ./src --output-mode inline --format json --edgesDas JSON-Dokument enthält die Felder der obersten Ebene files, symbols, edges (weggelassen, wenn keine vorhanden sind) und errors (weggelassen, wenn keine vorhanden sind). Ein kleines Beispiel:
{ "files": ["app.go"], "symbols": [ { "id": "app.go::User", "short_id": "S1", "name": "User", "file": "app.go", "category": "type", "kind": "struct", "signature": "type User struct", "span": [3, 3] }, { "id": "app.go::Save", "short_id": "S2", "name": "Save", "file": "app.go", "category": "callable", "kind": "function", "signature": "Save(u: S1)", "span": [5, 5] } ], "edges": [ { "from": "app.go::Save", "from_short": "S2", "to": "app.go::User", "to_short": "S1", "kind": "references" } ]}Um das JSON auf die Festplatte zu schreiben, lassen Sie --output-mode inline weg. In den Verzeichnismodi geht JSON nach codeknit.json. JSON ist ein einzelnes Dokument und wird nicht nach Zeilenanzahl aufgeteilt.
Beziehungen einbeziehen
Abschnitt betitelt „Beziehungen einbeziehen“Standardmäßig enthält die Ausgabe nur den Abschnitt [symbols], was Tokens spart. Fügen Sie --edges hinzu, wenn Sie wissen müssen, was was aufruft, enthält, erbt oder referenziert:
codeknit parse ./src --edgesUnsichere Beziehungen lesen
Abschnitt betitelt „Unsichere Beziehungen lesen“Codeknit analysiert Syntax ohne Compiler, sodass einige Beziehungen nicht hergestellt werden können. Jede Kante gibt an, wie sicher sie ist:
S8 --references--> S5S10 --references[unresolved]--> string, boolS11 --calls[ambiguous]--> Helper [candidates=S12, S15]--kind-->ist eine aufgelöste Beziehung.--kind[unresolved]-->bedeutet, dass codeknit das Ziel nicht herstellen konnte.--kind[ambiguous]-->bedeutet, dass mehr als ein Ziel möglich bleibt. Kandidaten-IDs werden aufgelistet, wenn verfügbar.
Kandidaten sind mögliche Ziele, keine bestätigten Abhängigkeiten. Bekannte Endpunkte verwenden ShortIDs. Ein nicht aufgelöstes Ziel ohne passendes Symbol kann als Name relativ zur Quelldatei erscheinen.
In JSON tragen unsichere Kanten resolution ("unresolved" oder "ambiguous") und, wenn verfügbar, candidates als vollständige Symbol-IDs. Sie lassen to_short weg.
Für C und C++ werden #include-Direktiven zu meta/file- und meta/include-Symbolen, sodass ihre Kanten ShortIDs haben. Dies zeichnet die Direktive so auf, wie sie geschrieben wurde. Es bedeutet nicht, dass codeknit die Header-Datei gefunden hat.
Graphmetriken schließen unsichere Kanten aus und melden, wie viele ausgeschlossen wurden. Der HTML-Graph-Viewer zeigt eine Anzahl unsicherer Beziehungen an und zeichnet sie nicht. Um einzelne unsichere Kanten zu inspizieren, verwenden Sie --edges bei parse. Siehe Graph-Befehle für diese Berichte.
Die Kantensyntax finden Sie in der Referenz zum Ausgabeformat. Auflösungsregeln und -grenzen finden Sie in der Referenz zur Sprachunterstützung.
Ausgabegröße reduzieren
Abschnitt betitelt „Ausgabegröße reduzieren“Um wiederholte Tokens zu komprimieren, fügen Sie --minify hinzu:
codeknit parse ./src --minifyDies schreibt ein Wörterbuch nach dict.skt (oder einen [dict]-Abschnitt inline). Ersetzen Sie Codes wie d0 und d1 durch ihre Wörterbuchwerte beim Lesen. Beziehungstypen werden ebenfalls codiert, aber Auflösungslabels wie [unresolved] bleiben lesbar.
Um die Chunk-Größe zu steuern, verwenden Sie --max-lines (Standard 500):
- Im Modus
directory-flatist es ein Zielwert. Ein Quellblock wird nie aufgeteilt, sodass ein Chunk ihn um einen Block überschreiten kann. - Im Modus
directory-treeist es eine harte Grenze für jeden Quell-Chunk. Das Minimum ist3. Jeder Chunk wiederholt seine[symbols]- und## source-path-Header.
C++-Header mit der Endung .h parsen
Abschnitt betitelt „C++-Header mit der Endung .h parsen“Codeknit parst .h-Dateien standardmäßig als C. Für C++-Header mit dieser Erweiterung setzen Sie --header-language cpp:
codeknit parse ./src --header-language cppDas Flag betrifft nur .h-Dateien. Dateien mit den Endungen .hpp und .hxx werden bereits als C++ geparst, und andere Erweiterungen behalten ihre üblichen Parser.
Steuern, welche Dateien gescannt werden
Abschnitt betitelt „Steuern, welche Dateien gescannt werden“Alle fünf Quellcode-verarbeitenden Befehle akzeptieren diese Flags. Sie sind vollständig in der CLI-Flags-Referenz aufgeführt.
codeknit parse ./src --include '**/*.go' --exclude '**/generated/' --strict--include GLOBund--exclude GLOBsind wiederholbare, gitignore-artige Muster relativ zum Eingabeverzeichnis. Setzen Sie sie in Anführungszeichen, damit Ihre Shell sie nicht expandiert. Ausschlüsse haben Vorrang. Einschlüsse überschreiben nicht.gitignore, Testdatei-Filterung oder integrierte Ausschlüsse.--max-file-size BYTESüberspringt größere Dateien. Der Standardwert ist10485760(10 MiB).0deaktiviert die Grenze.--strictschlägt fehl, bevor eine Ausgabe geschrieben wird, wenn der Scan oder das Parsen unvollständig ist. Der Standardwert istfalse.
Codeknit überspringt und meldet Symlinks und nicht reguläre Dateien. Übergeordnete .gitignore-Regeln gelten unabhängig von Ihrem Arbeitsverzeichnis.
Fallstrick: Teilresultate. Nicht lesbare Pfade, zu große Dateien, übersprungene Symlinks und Syntaxwarnungen machen eine Analyse unvollständig. Ohne --strict behält codeknit die nutzbaren Ergebnisse und meldet die Probleme:
- auf stderr,
- im JSON-Feld
errors, oder - im SKT-Abschnitt
[errors](inline oder inwarnings.sktin Verzeichnismodi).
Eine Eingabe ohne ausgewählte unterstützte Quellen oder ein Lauf, bei dem jede gelesene Quelle fehlschlägt, beendet sich immer erfolglos. Für genaue Garantien siehe Analysezuverlässigkeit.
Parse-Flags
Abschnitt betitelt „Parse-Flags“Diese Flags sind spezifisch für parse. Gemeinsame Flags finden Sie in der CLI-Flags-Referenz.
| Flag | Standard | Beschreibung |
|---|---|---|
--output-mode |
directory-flat |
Ausgabemodus: inline, directory-flat oder directory-tree. |
--format |
skt |
Ausgabeformat: skt oder json. |
--header-language |
c |
Parser für .h-Dateien: c oder cpp. Andere Erweiterungen bleiben unverändert. |
--max-lines |
500 |
Zeilenziel für flache Ausgabe; harte Grenze (Minimum 3) für jeden Baum-Quell-Chunk. |
--collect-test |
false |
Testdateien einbeziehen. |
--minify |
false |
Wörterbuchbasierte Komprimierung verwenden. |
--edges |
false |
Den Abschnitt [edges] einbeziehen (standardmäßig deaktiviert, um Tokens zu sparen). |
--clean |
false |
Vorherige generierte Ausgabe ersetzen, erst nach erfolgreicher Generierung. |
--workers |
NumCPU |
Maximale Anzahl gleichzeitiger Parsing-Goroutinen. |
--verbose |
false |
Fortschrittsinformationen ausgeben. |
- Verwenden Sie
directory-flatfür die meisten Projekte und lesen Sie nur die Chunks, die Sie benötigen. - Verwenden Sie
--minifybei großen Codebasen, um Tokens zu sparen. - Übergeben Sie
--edgesnur, wenn Sie Beziehungsdaten benötigen. - Überprüfen Sie die getestete Fähigkeitsmatrix und bekannte Grenzen, bevor Sie sich auf die Extraktion für eine bestimmte Sprache verlassen.