ihebEllouz/project-class-architect

Project Class Architect

Verwandelt ein Repository in ein interaktives UML-Klassendiagramm, das ein Entwickler erkunden kann, anstatt hunderte Dateien zu lesen. Die Analyse ist evidenzbasiert: jede Klasse, jedes Attribut, jede Methode und jede Beziehung im Diagramm verweist auf die Datei und Zeile, aus der sie stammt. Nichts wird erfunden; heuristische Funde werden als inferred (abgeleitet) gekennzeichnet.

Alle Pfade in dieser Datei sind relativ zum Skill-Verzeichnis (dem Ordner, der diese SKILL.md enthält).

Voraussetzungen

• Node.js 18+ (node --version). Die Skripte haben keine Abhängigkeiten: Führen Sie für diesen Skill niemals npm install aus.
• Lesezugriff auf das Repository. Die Analyse ändert niemals Quelldateien; sie schreibt nur in ihren Ausgabeordner.
• Falls Node.js nicht verfügbar ist, verwenden Sie den am Ende beschriebenen Fallback.

Arbeitsablauf

1. Repository identifizieren

Verwenden Sie den absoluten Pfad des Projekts, über das der Benutzer spricht (normalerweise der aktuelle Arbeitsbereich). Befehle unten werden vom Skill-Verzeichnis aus ausgeführt, daher würde ein relativer Pfad wie . auf den Skill selbst verweisen.

2. Diagramm generieren

node scripts/class-architect.js generate "/absolute/path/to/repo"

Nützliche Optionen (siehe die CLI-Referenz für alle):

Bedarf	Option
Autor in der Fußzeile	--author "Name" --author-role "Software Engineer"
Diagrammtitel	--title "Billing Service"
Nur einen Teil eines großen Repos	--include "src/main/java/com/acme/billing/**" (wiederholbar)
Ordner überspringen	--exclude "legacy/**" (wiederholbar)
Sprachen einschränken	--languages java,sql
Auch Tests analysieren	--include-tests
Startansicht / -layout	--view classes|er|overview|packages --layout grouped|layered|hierarchical|grid
Benutzerdefinierter Ausgabeordner	--out "/path/to/output" (Standard: <repo>/.class-architect)
Lokale Pfade aus dem HTML entfernen	--hide-root (deaktiviert "Im Editor öffnen"-Links)

Der Befehl gibt eine JSON-Zusammenfassung auf stdout aus (Fortschritt geht nach stderr). Exit-Codes: 0 Erfolg, 1 Verwendungsfehler, 2 keine analysierbaren Quelldateien, 3 Modellvalidierung fehlgeschlagen (nichts geschrieben), 4 interner Fehler.

3. Ergebnis prüfen

Lesen Sie die JSON-Zusammenfassung (status, outputs, summary.counts, summary.insights, summary.edits, validation). Im Ausgabeordner geschriebene Ausgaben:

• diagram.html - das interaktive Diagramm (öffnen Sie es in einem Browser; es funktioniert offline).
• report.md / report.json - gescannte Dateien, Klassen, Interfaces, Enums, Beziehungen, abgeleitete Beziehungen, ungelöste Referenzen, ausgeschlossene Dateien mit Gründen, Warnungen, Erkenntnisse.
• model.json - das UML-Modell (einzige Quelle der Wahrheit); overlay.json - Benutzerbearbeitungen, falls vorhanden.

Wenn der Exit-Code 2 ist, passen Sie --include / --languages an und nennen Sie, welche Ordner ausgeschlossen wurden und warum (aus dem JSON details). Wenn der Exit-Code 3 ist, melden Sie die Validierungsfehler; bearbeiten Sie das Modell nicht von Hand, um sie zu verstecken.

Bei Repositorys mit Hunderten von Klassen öffnet sich das Diagramm in der Übersicht (Module) und ermöglicht dem Benutzer, in Module und Pakete hinabzusteigen; Sie können auch fokussierte Diagramme mit --include für einen begrenzten Kontext erstellen.

4. Diagramm dem Benutzer präsentieren

• Geben Sie den Pfad von diagram.html (und seine file://-URL aus outputs.diagramUrl) an. Versuchen Sie nicht, einen Browser zu starten, es sei denn, der Benutzer fragt danach und Ihre Umgebung erlaubt es.
• Fassen Sie nur zusammen, was der Bericht sagt: Anzahl der Klassen/Interfaces/Enums/Beziehungen, erkannte Frameworks, Abhängigkeitszyklen, Architekturerkenntnisse, ungelöste Referenzen und Warnungen. Zitieren Sie Klassennamen genau.
• Erwähnen Sie, dass mit inferred markierte Beziehungen (Namenskonventionen, Go-Strukturelles Typsystem) überprüft werden sollten und dass abgeleitete Tabellen-/Spaltennamen als abgeleitet markiert sind.
• Weisen Sie auf die Hauptinteraktionen hin: Klicken Sie auf eine Klasse oder Linie, um sie zu inspizieren (mit Quelldatei und Zeile), Suche (/), Filter, Ansichten (Übersicht, Pakete, Klassen, Datenbank-ER), die Lupe (L), Bearbeitungsmodus (E), Erkenntnisse, Export. Details: die Anleitung zum interaktiven Diagramm.

5. Nach Code-Änderungen aktualisieren

Führen Sie den gleichen Befehl erneut aus. Er:

• analysiert nur geänderte Dateien erneut (inkrementeller Cache),
• behält jede Benutzerbearbeitung (aus overlay.json und aus Bearbeitungen, die der Benutzer mit der Schaltfläche "Speichern" in diagram.html gespeichert hat),
• meldet Bearbeitungen, deren Ziel aus dem Code verschwunden ist, als orphaned (verwaist) (beibehalten, niemals stillschweigend gelöscht) und Bearbeitungen, die mit einer Quelländerung in Konflikt stehen,
• hebt hinzugefügte/entfernte/geänderte Klassen im Vergleich zum vorherigen Durchlauf hervor,
• behält ein Backup des vorherigen Diagramms (diagram.prev.html).

Wenn der Benutzer eine Kopie des Diagramms an anderer Stelle heruntergeladen hat, übergeben Sie diese mit --edits "/path/to/saved-diagram.html".

6. Optional: Dokumentationsabschnitte

Das Diagramm kann zusätzliche Dokumentation darunter anzeigen (Tabellen, Abläufe, Schritte, Enum-Gitter, Banner-Notizen) unter Verwendung der Komponenten der ursprünglichen Vorlage. Fügen Sie nur Fakten hinzu, die Sie im Code überprüft haben, und zitieren Sie die Quelldatei. Schreiben Sie eine JSON-Datei gemäß der Konfigurationsanleitung und übergeben Sie --notes notes.json.

Regeln

• Ändern, formatieren oder "reparieren" Sie niemals den analysierten Quellcode als Teil dieses Skills.
• Erfinden Sie niemals Klassen, Member oder Beziehungen, und präsentieren Sie niemals eine inferred-Beziehung als sicher.
• Löschen oder überschreiben Sie niemals overlay.json oder ein vom Benutzer gespeichertes diagram.html: das CLI führt sie für Sie zusammen.
• Der Ausgabeordner .class-architect/ wird generiert; schlagen Sie vor, ihn zu .gitignore hinzuzufügen, es sei denn, der Benutzer möchte das Diagramm committen.
• Laden Sie das Diagramm oder das Modell nirgendwo hoch: Sie können proprietäre Code-Strukturen enthalten.

Fallback, wenn Skripte nicht ausgeführt werden können

Wenn Node.js 18+ nicht verfügbar ist oder die Befehlsausführung nicht erlaubt ist:

1. Lesen Sie die relevanten Quelldateien und schreiben Sie ein Modell-JSON von Hand gemäß der UML-Modell-Referenz. Fügen Sie nur Elemente ein, die Sie im Code gesehen haben, mit source.file und source.line; setzen Sie confidence: "inferred" für alles, was nicht explizit ist.
2. Kopieren Sie templates/viewer.html an den Ort, an dem der Benutzer das Diagramm haben möchte (z.B. class-diagram.html).
3. Ersetzen Sie in der Kopie den Text null innerhalb von <script type="application/json" id="pca-data">null</script> durch {"model": <Ihr Modell>, "overlay": null, "meta": {"title": "<Projektname>"}}, wobei Sie < als < innerhalb des JSON schreiben.
4. Alternativ: Sagen Sie dem Benutzer, dass er templates/viewer.html öffnen und model.json auf die Seite ziehen soll.

Layout, Interaktionen und Exporte funktionieren dann im Browser genau wie bei einem generierten Diagramm; nur die automatische Extraktion, Änderungserkennung und der Validierungsbericht fehlen. Sagen Sie klar, dass das Modell von Hand geschrieben wurde.

Andere Befehle

node scripts/class-architect.js analyze "/abs/repo"                       # Modell + Bericht, kein HTML
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor

Referenzdateien (nur bei Bedarf lesen)

• references/CLI.md - jeder Befehl, jede Option, jede Ausgabe und jeder Exit-Code.
• references/INTERACTIVE-DIAGRAM.md - was der Benutzer im Diagramm tun kann, Tastenkürzel.
• references/RELATIONSHIPS.md - wie jede Beziehungsart und Multiplizität bestimmt wird, Nachweise und Konfidenz.
• references/LANGUAGES.md - unterstützte Sprachen, Frameworks und ORMs, und was extrahiert wird.
• references/CONFIGURATION.md - class-architect.config.json, externe Entitäten, Schwellenwerte, Dokumentationsnotizen.
• references/UML-MODEL.md - das Modellformat (für den Fallback oder für andere Tools).
• references/LIMITATIONS.md - bekannte Einschränkungen, die bei Bedarf erwähnt werden sollten.