Was macht Xylem?
Du wirst ein Repository in eine quellengestützte Karte verwandeln. Sie hat vier Ansichten, in einer statischen Zwei-Dateien-Website (index.html und deep-view.json):
| Ansicht | Zeigt |
|---|---|
| Erkunden | Komponenten (die Teile des Systems) und die Verbindungen zwischen ihnen, gruppiert in Schichten |
| Kundenreisen | Jede Reise, die ein Benutzer unternehmen kann, animiert über der Architektur: Anfragen, Antworten und beschriftete Übergaben |
| Zustandsübersicht | Jede deklarierte Zustandsdimension im abgebildeten Bereich, ihre Zustände und die Übergänge, die Reisen tatsächlich nehmen |
| Code | Jede abgebildete Funktion als Kachel in ihrer Region, mit ihren Entscheidungen, Aufrufen und Aufrufern sowie Reispfaden, die auf Funktionsebene verfolgt werden |
Die Methode ist wichtiger als die Seite. Jede Behauptung ist an Datei:Zeile gebunden. Jede Verbindung ist real. Wo der Code etwas nicht klären kann, sagt die Karte das, anstatt zu raten.
Grundregeln (gelten in jeder Phase)
- Beleg oder nichts. Jede Komponente, Einheit, Entscheidung, Kante, jeder Zustand und jede Aktion sollte
Datei:Zeilezitieren. Wenn du es nicht zitieren kannst, markiere es alsUNVERIFIEDoder lasse es weg. Dies ist eine Verpflichtung des Autors/Reviewers: automatisierte Prüfungen erzwingen den Architekturbeleg und tiefe Quellorte, nicht jede Zustands-/Aktionszitation oder -erklärung. - IDs vergeben; niemals Entitäten oder Verbindungen erfinden. Verwende die Datei-Positions-IDs des Gerüsts; manuell vergebene IDs müssen ebenfalls eindeutig und stabil sein. Regionsübergreifende Kanten müssen über eine deklarierte Architekturverbindung laufen. Fehlt eine, dokumentiere einen
diagram_gapund verifiziere ihn im Code, bevor du ihn mit Beleg hinzufügst. - Ehrliche Lücken sind besser als unmögliche Pfade. Wenn ein Reiseergebnis nicht eindeutig aus der Quelle zurückverfolgt werden kann, schreibe
{"unavailable": "<spezifischer Grund>"}. Kopiere niemals den Erfolgspfad in ein Fehlerergebnis. Verkette niemals Verzweigungen, die nicht beide wahr sein können. - Sage, was es ist. Verfolgungen sind statische Quellpfade, keine Aufzeichnungen von echten Abläufen. Kennzeichne sie so auf der Seite.
- Schreibgeschützt. Bearbeite niemals das Ziel-Repository. Schreibe alles in
.xylem/(oder einen vom Benutzer benannten Ordner). - Datenschutz. Sende keine Repository-Inhalte an einen externen Dienst, es sei denn, der Benutzer bittet darum. Die Website stellt nur Same-Origin-Anfragen für ihre Daten und optionale Videos. Sie stellt keine externen Anfragen; liefere sie auf Loopback zur Offline-Nutzung aus.
Ausgabelayout
.xylem/
census.json # jede Definition, die im Code gefunden wurde (scripts/census.py)
architecture.json # Phase 1
journeys.json # Phase 2
deep.json # Phase 3 (Funktionskarte)
validation.json # Ausgabe von scripts/validate.py
reviews/ # Cross-Review-Berichte (Phase 6)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
Formate für jede Datei befinden sich in references/schemas.md. Lese es, bevor du JSON schreibst.
Phasen und Prüfpunkte
Führe die Phasen in der Reihenfolge aus. Jede Phase endet mit einem Prüfpunkt. Fahre nicht fort, bis der Prüfpunkt bestanden ist oder der Benutzer eine dokumentierte Lücke akzeptiert hat. Führe in einem explizit autorisierten Testlauf fehlschlagende Artefakte und Protokolle unverändert weiter und fahre nur innerhalb dieses Testumfangs fort; kennzeichne nachfolgende Ausgaben als vorläufig. Ein strukturelles Bestehen begründet keine vollständige semantische Abdeckung.
Phase 0: Census (deterministisch)
python scripts/census.py <repo> --out .xylem/census.json [--exclude verzeichnis ...]
Dies inventarisiert benannte Definitionen mit Python AST, einem Standard-Bibliotheks-JS/TS-Token-Walker und approximativen Regexes für andere unterstützte Sprachen. scannedFiles enthält Quelldateien ohne Definitionen. JS/TS deckt generische Pfeile, konkrete mehrzeilige/berechnete Methoden, Überladungssignaturen, lexikalische Funktions-/Klasseneigentümer, Regex-Literale und Template-Interpolationen ab; anonyme Callbacks sind keine Census-Einheiten. Es ist ein gemessenes Inventar, kein Beweis für die gesamte Sprachsyntax. Qualifiziere es mit einem unabhängigen Parser oder Quellstichprobe, bevor du Vollständigkeit beanspruchst. Spätere Prozentsätze beschreiben nur dieses Inventar.
Prüfpunkt: Die Census-Zahlen sehen im Verhältnis zur Repository-Größe plausibel aus. Ausgeschlossene Pfade sind begründet, z. B. generierter Code oder node_modules.
Phase 1: Architektur
Lese die Einstiegspunkte, Build-Dateien, Hauptmodule und Prozessgrenzen. Schreibe dann architecture.json:
- Schichten: z. B. Shell, UI, Server, Domain, Speicher, Worker, Extern;
- Komponenten: jede mit
id,layer,files[], einer klaren Verantwortung undprocessType; - Verbindungen: jede
{from, to, label, kind}, wobeikindspawn, ipc, http, file, data oder uses ist; - Flows: die wichtigsten End-to-End-Abläufe als geordnete Komponentenschritte.
Prüfpunkt: python scripts/validate.py .xylem --only architecture besteht. Jeder Eintrag in scannedFiles gehört zu einer Komponente oder hat einen begründeten architecture.meta.fileExclusions-Eintrag. Belegpfade und -zeilen müssen unter dem Belegstammverzeichnis existieren.
Phase 2: Journeys und Zustände
Schreibe journeys.json. Arbeite sie aus der UI, den Routen, CLI-Befehlen, Jobs und Fehlerpfaden heraus:
- stateDimensions: jede unabhängige Zustandsmaschine;
- screens: jeder Bildschirm;
- actions: jede Benutzeraktion und Systemtransition mit ihren Ergebnissen, dem exakten Text, den der Benutzer sieht, und Rückgängig;
- journeys: Startzustände plus Schritte.
Jede Aktion trägt eine geordnete Architektur-Verfolgung (abwechselnd Komponente und Verbindung). Rückwege verwenden {"connection": [a, b], "direction": "reply"}. Wenn der nächste Schritt nicht dort beginnt, wo der letzte endete, trägt der Schritt transition.handoff mit einem Typ und Label: user, timer, queue, continuation, lifecycle oder download. Decke glückliche, unglückliche, Wiederherstellungs- und Randfälle ab.
Prüfpunkt: validate.py --only journeys besteht:
- jede Reise wiederholt sich durch gültige Ergebnisse;
- keine stillen Sprünge (jede Aufleuchtung wird über eine Leitung, eine Antwort oder eine beschriftete Übergabe erreicht);
- keine verwaisten Zustände.
Phase 3: Funktionsebene (endgültige Auflösung)
- Erzeuge einen Entwurf der Karte aus dem Census:
python scripts/scaffold_deep.py .xylem
Er schreibt deep.json. Der Entwurf enthält zugewiesene Census-Einheiten, Python-Entscheidungen aus dem AST und heuristische JS/TS-if-, while-, for-, switch- und geklammerte catch-Punkte. JS/TS erhebt keinen Anspruch auf ein vollständiges Inventar von Ternär-, Berechnungs- oder Kurzschlussentscheidungen. Kommentare, Literalinhalte und Kind-Deklarationen sind von jedem Körper ausgeschlossen. Generische Aufrufe behalten unterschiedliche Aufrufpositionen. Aufrufkanten verwenden source: heuristic und confidence: name-resolved; unaufgelöste Namen sind keine erfundenen Verbindungen. Verfeinere gegen die Quelle; Namensauflösung ist keine Typauflösung.
2. Verfeinere den Entwurf durch Lesen des Codes:
- geschäftslesbare
summarypro Einheit, geschrieben aus dem Körper, nicht aus dem Namen; - für jede Entscheidung eine
plain-Frage („Ist diese Datei größer als 16 MiB?“) plus den exakten Code-test, einekind(branch, calculation, loop oder unconditional) und korrekte Nachfolger. Einreturnoderraisebeendet den Pfad. Die normalen und Fehler-Fortsetzungen eines Try-Blocks sind getrennt, und eine ausstehende Ausnahme führtfinallyaus und propagiert dann. Wenn du dir unsicher bist, markiere den Nachfolger alsunresolved; niemals alsverified; risk-Tags nur für Entscheidungen, die direkt einen bekannten Defekt implementieren.
- Schreibe
actionTraces: für jede Reiseaktion und jedes Ergebnis die geordneten Ausführungsereignisse{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.eventist eines von call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally oder resume. Siehe Schemas für Aktivierungsrahmen, Terminalereignisse und unterstützte Wiederholungsgrenzen.- Beginne beim tatsächlichen Initiator, z. B. einem UI-Handler, einer Route oder einem Job.
- Folge Aufrufen, Rückgaben und Prozessgrenzen. Eine Ablehnung muss den tatsächlichen Fehlerpfad zurück zum Benutzer verfolgen. Es darf niemals mit „gespeichert“ oder „erfolgreich“ fortfahren.
- Wo der Pfad nicht bekannt ist, gib
{"event": "unknown", "note": "..."}aus oder markiere das gesamte Ergebnis alsunavailable.
Große Repositories: Teile Phase 3 nach Codebereich auf mehrere Agenten auf, die jeweils deep-<part>.json im gleichen Format schreiben, und führe sie dann mit scripts/merge_deep.py zusammen. Gleiche IDs durch Datei und Definitionszeile ab, niemals durch Namensähnlichkeit.
Prüfpunkt: validate.py besteht die vollständige Menge:
- jede Census-Definition ausgegeben oder explizit mit einem Grund ausgeschlossen; ausgegebene Abdeckung und Ausschlussbuchhaltung sind getrennte Zähler;
- jeder Kantenendpunkt löst auf;
- jede regionsübergreifende Kante reitet auf einer Verbindung;
- Entscheidungsnachfolger lösen auf;
- Verfolgungsreferenzen sind gültig;
- Selektor-Konsistenz: keine Aktivierung trifft sich gegenseitig ausschließende Entscheidungen für unveränderte Werte. Quellenschreibvorgänge können einen Wert ändern; ein Iterationslabel allein kann keine Einschränkungen zurücksetzen. Unterstützte Grammatik und Grenzen sind im Schema. Beispiel:
x==='a'ja und dannx==='b'ja, oder ein Wert ausgeschlossen und dann durchincludes()erforderlich. Korrigiere die Verfolgung oder ziehe sie aufunavailablezurück und nenne den Konflikt.
Phase 4: Erstelle die Seite
python scripts/build_site.py .xylem
Dies schreibt site/index.html und site/deep-view.json. Videos sind optional: lege videos/<journeyId>.mp4 plus videos/manifest.json zuerst in .xylem/ ab (siehe Schemas). Liefere site/ über HTTP aus, um es anzusehen, z. B. python -m http.server -d .xylem/site. Eine file://-Seite kann die Daten der Code-Ansicht nicht laden.
Prüfpunkt: Öffne die Seite und überprüfe jeden Modus einmal:
- keine Konsolenfehler;
- Telefonbreite (420 px) hat keinen horizontalen Scrollbalken;
- Tastatur- und Dunkelmodus funktionieren.
Phase 5: Optionale Echtbildschirmaufnahmen
Wenn die App eine UI hat, die du lokal ausführen kannst, nimm Reisen mit Playwright auf. Ein Starter ist scripts/record_journey.example.mjs. Regeln für Aufnahmen:
- treibe die echte UI an, ohne gemockte Antworten;
- füge eine Beschriftung pro Schritt hinzu;
- beschleunige Leerlaufwartezeiten und beschrifte die Beschleunigung;
- nimm
atSecpro Schritt inmanifest.jsonauf; - markiere Teilaufnahmen als teilweise.
Der Viewer synchronisiert ein Video mit der Karte, sodass das Video zur Uhr wird.
Phase 6: Cross-Review-Rat
Verwende nach Möglichkeit zwei unabhängige Prüfer: zwei verschiedene Modelle oder Agenten, oder zumindest einen frischen Kontext ohne Zugriff auf die Schlussfolgerungen des Autors. Folge references/protocol.md:
- der Autor bewertet seine eigene Arbeit nie selbst;
- der Prüfer erhält Dateien und Code, niemals die Schlussfolgerungen des Autors;
- der Prüfer führt den unabhängigen Prüfer aus und prüft Behauptungen stichprobenartig gegen die Quelle: die einzige Stichprobenregel in protocol.md (alle verfügbaren Elemente unterhalb ihrer Minima);
- Ergebnisse gehen in
reviews/<pruefer>-<runde>.mdmit Schweregrad, Beleg und einer konkreten Korrektur; - Abnahmeprüfpunkt: eine explizite ACCEPT-, REJECT- oder BLOCKED-Entscheidung für Architektur, Reisen, Tiefe, Seite/Daten und das eingefrorene Bundle. Nur wesentliche Mängel rechtfertigen REJECT: eine falsche Schlussfolgerung, ein unmöglicher Pfad oder eine blockierte Kernaufgabe. Deklarierte Grenzen, ehrliche
unavailable-Marker und die statische Natur von Verfolgungen sind kein Grund zur Ablehnung; - verwende ein begrenztes Review-Budget; stoppe mit REJECT/BLOCKED und aufbewahrtem Beleg, wenn ungelöst. Überprüfe das exakte gebaute Artefakt erneut, nicht eine Beschreibung davon.
Prüfpunkt: Alle Artefakte des eingefrorenen Bundles sind durch unabhängige Überprüfung akzeptiert. Erfinde niemals Pfade, um eine Stichprobenquote zu erfüllen.
Phase 7: Veröffentlichen und Berichten
Teile dem Benutzer mit, was in der Seite ist, mit echten Zahlen:
- Funktionen, Entscheidungen, Reisen und verfolgte Ergebnisse;
- wie viele Ergebnisse nicht verfügbar sind und warum;
- was cross-reviewed wurde.
Berichte Grenzen klar.
Skripte
| Skript | Zweck |
|---|---|
census.py | Mehrsprachiger Definitions-Census (der Nenner der Abdeckung) |
scaffold_deep.py | Entwurf einer Funktionsebene aus Census und Architektur |
merge_deep.py | Zusammenführen von Teilkarten; Abgleich von IDs nach Datei und Zeile |
validate.py | Jeder Prüfpunkt: Schema, Referenzen, Abdeckung, stille Sprünge, Nachfolger, Selektor-Konsistenz |
build_site.py | Exportieren der kompakten Code-Ansichtsdaten und Erstellen der Einzelseite-Website |
record_journey.example.mjs | Playwright-Startvorlage für Echtbildschirm-Reisevideos |
Die Python-Skripte benötigen Python 3.9+ und nur die Standardbibliothek. Optionale .mjs-Browser/Aufnahme-Helfer benötigen ein separat verfügbares Playwright. Die Seite verwendet keine Frameworks oder externe Anfragen.