adapter library
Programmatischer Zugriff auf den Ductus-Dart-Adapter (SPEC §7).
Bewusst getrennt von package:ductus/ductus.dart: Die Annotationen
bleiben abhängigkeitsfrei; nur diese Bibliothek zieht analyzer & Co.
Classes
- ActionCandidate
-
Eine
@journey:action/@JourneyAction, derenfromggf. erst nach dem Scan aller Dateien über die umschließende Klasse aufgelöst wird (DD §B.3). - AdapterConfig
- AnnotationResolution
- Löst nicht-literale konstante Annotation-Argumente auf (Weg D).
- AutoRouteDerivation
- GoRouterDerivation
- GraphEdge
- Transition (SPEC §6.3). id ist bis zur Id-Generierung im Merger optional.
- GraphFlow
- Benannter Flow (SPEC §6.4). source/sourceRef sind nur intern für die Merge-Präzedenz relevant und werden nicht serialisiert.
- GraphNode
- Screen- oder Decision-Node (der Dart-Adapter emittiert keine Action-Nodes, DD §B.2).
- ManualExtraction
- Ergebnis eines manuellen Eingabewegs für eine Datei.
- MergeResult
- RawBlock
-
Ein roher
@journey:-Block: Typ, Rohtext, Startzeile (1-basiert). - ScannedFile
- Eine geparste Quelldatei. relPath ist projekt-relativ mit '/'-Separatoren und dient überall als deterministischer Sortierschlüssel.
- SourceKind
- Herkunft eines Graph-Elements (SPEC §6.2).
- SourceRef
- Rückverweis in den Quellcode (SPEC §6.2). file ist immer projekt-relativ mit '/'-Separatoren.
Constants
- adapterVersion → const String
-
Muss mit
version:in pubspec.yaml übereinstimmen (DD §H) — abgesichert durch einen Regressionstest in test/cli_integration_test.dart. - builderAdapterName → const String
- meta.adapters-Name des build_runner-Builders (Weg D).
- builderArtifactFileName → const String
-
Artefakt des build_runner-Builders im Projekt-Root des Zielpakets (Weg D).
NICHT zu verwechseln mit
ductus_graph.g.json— das ist die Debug-Datei, die das Adapter-CLI bei jedem Scan schreibt. - cliAdapterName → const String
-
meta.adapters-Name des Adapter-CLI (Scan via
dart run ductus:adapter). - schemaVersion → const String
- supportedSchemaMajor → const int
- Vom Adapter unterstützte Schema-Major-Version (V6/NFR7, wie im Core).
-
validTriggers
→ const Set<
String> - Gültige Trigger-Werte (SPEC §6.3).
Functions
-
deriveAutoRoute(
List< ScannedFile> files, void warn(String)) → AutoRouteDerivation -
Leitet Screens aus
@RoutePage()-Klassen ab;AutoRoute(page:, path:)- Einträge liefern die Pfad-Zuordnung. -
deriveGoRouter(
List< ScannedFile> files, void warn(String), {Map<String, String> manualScreenClasses = const {}, Map<String, String> extraClassToScreen = const {}, Map<String, String> extraPathToScreen = const {}}) → GoRouterDerivation - Leitet Screens, Flows (ShellRoute), Redirect-Decisions und Navigations-Kanten aus go_router-Konfigurationen ab.
-
encodeCanonicalGraph(
{required List< GraphFlow> flows, required List<GraphNode> nodes, required List<GraphEdge> edges, String adapterName = cliAdapterName}) → String -
Kanonisches Graph-JSON nach DD §C: rekursiv sortierte Schlüssel,
2-Space-Indent, LF, abschließender Zeilenumbruch, kein
generatedAt. -
extractAnnotations(
ScannedFile file, void warn(String), List< String> errors, {AnnotationResolution? resolution}) → ManualExtraction - Extrahiert alle Journey-Annotationen einer Datei.
-
humanize(
String id) → String - Humanisierte Id: '-'→' ', erster Buchstabe groß.
-
isSupportedSchemaVersion(
String version) → bool - V6-Logik wie im Core: „major.minor“ mit unterstütztem Major ⇒ kompatibel (Minor-Erweiterungen sind rückwärtskompatibel zu pflegen, SPEC §6).
-
mergeGraph(
{required List< GraphNode> nodes, required List<GraphEdge> edges, required List<GraphFlow> flows}) → MergeResult - Merged Nodes/Edges/Flows aller Quellen. Konflikte zwischen manuellen Quellen führen zu einer AdapterException mit allen Fundstellen.
-
parseComments(
ScannedFile file, void warn(String), List< String> errors) → ManualExtraction -
Parst alle
@journey:-Blöcke einer Datei. Warnungen (unbekannte Keys, unbekannte Trigger/Typen) viawarn; fatale Probleme (fehlende Pflichtfelder, nicht auflösbaresfrom) landen inerrors. -
readBuilderArtifact(
String projectDir) → String - Liest das Builder-Artefakt und liefert den Dateiinhalt byte-genau für stdout. Fehlende Datei, ungültiges JSON oder eine inkompatible schemaVersion (V6-Logik wie im Core) werfen eine AdapterException.
-
runAdapter(
{required String projectDir, AdapterConfig config = const AdapterConfig(), required void warn(String)}) → String -
Führt die komplette Extraktion aus und liefert das kanonische Graph-JSON.
Diagnostik geht über
warn(stderr); Fehler werfen AdapterException. -
runPipeline(
{required List< ScannedFile> files, AdapterConfig config = const AdapterConfig(), required void warn(String), AnnotationResolution? resolution, String adapterName = cliAdapterName}) → String -
Pipeline auf bereits gescannten Dateien — gemeinsame Basis von Adapter-CLI
und build_runner-Builder (Weg D). Gleiche Merge-/Sortier-/
Serialisierungslogik für beide Zubringer (Paritätsgarantie): Unterschiede
entstehen nur durch
resolution(zusätzlich aufgelöste Werte) undadapterName(meta.adapters-Eintrag). -
scanProject(
String projectDir, AdapterConfig config, void warn(String)) → List< ScannedFile> - Liefert alle .dart-Dateien unter den include-Mustern, deterministisch nach relativem Pfad sortiert und parse-only analysiert.
-
screenIdFromClassName(
String className) → String - 'UserProfileScreen' -> 'user-profile' (Screen/Page-Suffix entfällt).
-
slugFromPath(
String path) → String - Pfad-Slug nach DD §G: führendes '/' weg, '/'→'-', ':param' entfällt, leer → 'root'.
-
splitBlocks(
String content) → List< RawBlock> -
Zerlegt eine Datei zeilenbasiert in
@journey:-Blöcke: Start in einer Kommentarzeile, Fortsetzung in unmittelbar folgenden Kommentarzeilen, Ende an Nicht-Kommentar-Zeile oder neuem@journey:-Block.
Exceptions / Errors
- AdapterException
- Fehler, der den Adapter mit Exit ≠0 beendet; messages gehen auf stderr.