Quelldateien annotieren

PUT-Workflow-Annotationen zu Quelldateien hinzufügen, sodass putior strukturierte Workflow-Daten extrahieren und Mermaid-Diagramme generieren kann.

Wann verwenden

• Nach der Codebase-Analyse mit

  analyze-codebase-workflow

  mit vorhandenem Annotationsplan
• Workflow-Dokumentation zu neuen oder bestehenden Quelldateien hinzufügen
• Auto-erkannte Workflows mit manuellen Beschriftungen und Verbindungen anreichern
• Datenpipelines, ETL-Prozesse oder mehrstufige Berechnungen dokumentieren

Eingaben

• Erforderlich: Zu annotierende Quelldateien
• Erforderlich: Annotationsplan oder Kenntnis der Workflow-Schritte
• Optional: Stil-Präferenz: einzeilig oder mehrzeilig (Standard: einzeilig)
• Optional: Ob

  put_generate()

  für Skeleton-Generierung verwendet werden soll (Standard: ja)

Vorgehensweise

Schritt 1: Kommentar-Präfix bestimmen

Jede Sprache hat ein spezifisches Kommentar-Präfix für PUT-Annotationen.

get_comment_prefix()

verwenden, um das korrekte zu finden.

library(putior)

# Häufige Präfixe
get_comment_prefix("R")    # "#"
get_comment_prefix("py")   # "#"
get_comment_prefix("sql")  # "--"
get_comment_prefix("js")   # "//"
get_comment_prefix("ts")   # "//"
get_comment_prefix("go")   # "//"
get_comment_prefix("rs")   # "//"
get_comment_prefix("m")    # "%"
get_comment_prefix("lua")  # "--"

Erwartet: Ein String wie

"#"

,

"--"

,

"//"

oder

"%"

.

Zeilen- und Block-Kommentare: putior erkennt Annotationen sowohl in Zeilen-Kommentaren (

//

,

#

,

--

) als auch in C-Stil-Block-Kommentaren (

/* */

,

/** */

). Für JS/TS werden sowohl

//

als auch

/* */

-Blöcke gescannt. Python-Triple-Quote-Strings (

''' '''

) werden nicht erkannt — für Python

#

verwenden.

Bei Fehler: Wenn die Erweiterung nicht erkannt wird, ist die Dateisprache möglicherweise nicht unterstützt.

get_supported_extensions()

für die vollständige Liste prüfen. Für nicht unterstützte Sprachen

#

als konventionellen Standard verwenden.

Schritt 2: Annotations-Skeletons generieren

put_generate()

verwenden, um Annotations-Templates basierend auf auto-erkanntem I/O zu erstellen.

# Vorschläge in der Konsole ausgeben
put_generate("./src/etl/")

# Einzeiliger Stil (Standard)
put_generate("./src/etl/", style = "single")

# Mehrzeiliger Stil für komplexe Annotationen
put_generate("./src/etl/", style = "multiline")

# In Zwischenablage kopieren zum Einfügen
put_generate("./src/etl/", output = "clipboard")

Beispiel-Ausgabe für eine R-Datei:

# put id:'extract_data', label:'Extract Customer Data', input:'customers.csv', output:'raw_data.internal'

Beispiel-Ausgabe für SQL:

-- put id:'load_data', label:'Load Customer Table', output:'customers'

Erwartet: Eine oder mehrere Annotations-Kommentarzeilen pro Quelldatei, vorausgefüllt mit erkannten Funktionsnamen und I/O.

Bei Fehler: Wenn keine Vorschläge generiert werden, enthält die Datei möglicherweise keine erkennbaren I/O-Muster. Annotationen manuell basierend auf dem Verständnis des Codes schreiben.

Schritt 3: Annotationen verfeinern

Die generierten Skeletons bearbeiten, um genaue Beschriftungen, Verbindungen und Metadaten hinzuzufügen.

Annotationssyntax-Referenz:

<prefix> put id:'unique_id', label:'Menschenlesbare Beschriftung', input:'datei1.csv, datei2.rds', output:'ergebnis.parquet, zusammenfassung.internal'

Felder:

• id

  (erforderlich): Eindeutige Kennung, für Knotenverbindungen verwendet

• label

  (erforderlich): Menschenlesbare Beschreibung, im Diagramm angezeigt

• input

  : Komma-getrennte Liste von Input-Dateien oder -Variablen

• output

  : Komma-getrennte Liste von Output-Dateien oder -Variablen

• .internal

  -Erweiterung: Markiert In-Memory-Variablen (nicht zwischen Skripten persistiert)

• node_type

  : Steuert Mermaid-Knotenform und CSS-Klassen-Styling. Werte:

  • "input"

    — Stadion-Form

    ([...])

    für Datenquellen und Konfiguration

  • "output"

    — Subroutinen-Form

    [[...]]

    für generierte Artefakte

  • "process"

    — Rechteck

    [...]

    für Verarbeitungsschritte (Standard)

  • "decision"

    — Raute

    {...}

    für bedingte Logik

  • "start"

    /

    "end"

    — Stadion-Form

    ([...])

    für Einstiegs-/Endknoten

Beispiel mit

node_type

:

# put id:'config', label:'Load Config', node_type:'input', output:'config.internal'
# put id:'transform', label:'Apply Rules', node_type:'process', input:'config.internal', output:'result.rds'
# put id:'report', label:'Generate Report', node_type:'output', input:'result.rds'

Mehrzeilige Syntax (für komplexe Annotationen):

# put id:'complex_step', \
#   label:'Mehrzeilige Beschriftung', \
#   input:'data.csv, config.yaml', \
#   output:'result.parquet'

Dateiübergreifender Datenfluss (Skripte über dateibasiertes I/O verbinden):

# Skript 1: extract.R
# put id:'extract', label:'Daten extrahieren', output:'raw_data.internal, raw_data.rds'
data <- read.csv("source.csv")
saveRDS(data, "raw_data.rds")

# Skript 2: transform.R
# put id:'transform', label:'Daten transformieren', input:'raw_data.rds', output:'clean_data.parquet'
data <- readRDS("raw_data.rds")
arrow::write_parquet(clean, "clean_data.parquet")

Erwartet: Annotationen mit genauen IDs, Beschriftungen und I/O-Feldern verfeinert, die den tatsächlichen Datenfluss widerspiegeln.

Bei Fehler: Wenn I/O unklar ist,

.internal

-Erweiterung für In-Memory-Intermediate-Werte und explizite Dateinamen für persistierte Daten verwenden.

Schritt 4: Annotationen in Dateien einfügen

Annotationen am Anfang jeder Datei oder unmittelbar über dem relevanten Code-Block platzieren.

Platzierungskonventionen:

1. Datei-Level-Annotation: Am Anfang der Datei platzieren, nach eventueller Shebang-Zeile oder Datei-Header-Kommentar
2. Block-Level-Annotation: Unmittelbar über dem beschriebenen Code-Block platzieren
3. Mehrere Annotationen pro Datei: Für Dateien mit unterschiedlichen Workflow-Phasen verwenden

Beispiel-Platzierung in einer R-Datei:

#!/usr/bin/env Rscript
# ETL-Extraktionsskript
#
# put id:'read_source', label:'Quelldaten einlesen', input:'raw_data.csv', output:'df.internal'

df <- read.csv("raw_data.csv")

# put id:'clean_data', label:'Bereinigen und validieren', input:'df.internal', output:'clean.rds'

df_clean <- df[complete.cases(df), ]
saveRDS(df_clean, "clean.rds")

Das Edit-Tool verwenden, um Annotationen in bestehende Dateien einzufügen, ohne umgebenden Code zu stören.

Erwartet: Annotationen an geeigneten Stellen in jeder Quelldatei eingefügt.

Bei Fehler: Wenn Annotationen die Syntax-Hervorhebung im Editor stören, sicherstellen, dass das Kommentar-Präfix für die Sprache korrekt ist. PUT-Annotationen sind Standard-Kommentare und sollten die Code-Ausführung nicht beeinflussen.

Schritt 5: Annotationen validieren

putiors Validierung ausführen, um Annotationssyntax und Konnektivität zu prüfen.

# Annotierte Dateien scannen
workflow <- put("./src/", validate = TRUE)

# Auf Validierungsprobleme prüfen
print(workflow)
cat(sprintf("Gesamtknoten: %d\n", nrow(workflow)))

# Verbindungen durch Prüfung von Input/Output-Überschneidung verifizieren
inputs <- unlist(strsplit(workflow$input, ",\\s*"))
outputs <- unlist(strsplit(workflow$output, ",\\s*"))
connected <- intersect(inputs, outputs)
cat(sprintf("Verbundene Datenflüsse: %d\n", length(connected)))

# Diagramm generieren zur visuellen Inspektion
cat(put_diagram(workflow, theme = "github", show_source_info = TRUE))

# Mit auto-erkannten Daten zusammenführen für maximale Abdeckung
merged <- put_merge("./src/", merge_strategy = "supplement")
cat(put_diagram(merged, theme = "github"))

Erwartet: Alle Annotationen werden ohne Fehler geparst. Das Diagramm zeigt einen verbundenen Workflow.

put_merge()

füllt Lücken aus der Auto-Erkennung.

Bei Fehler: Häufige Validierungsprobleme:

• Fehlende schließende Anführungszeichen:

  id:'name

  →

  id:'name'

• Doppelte Anführungszeichen innerhalb:

  id:"name"

  →

  id:'name'

• Doppelte IDs über Dateien hinweg: jede

  id

  muss innerhalb des gesamten gescannten Verzeichnisses eindeutig sein
• Backslash-Fortsetzung auf der falschen Zeile:

  \

  muss das letzte Zeichen vor dem Zeilenumbruch sein

Block comment syntax (for

//

-prefix languages only: JS, TS, Go, Rust, C, C++, Java, etc.):

Languages that use

//

for line comments also support PUT annotations inside

/* */

and

/** */

block comments. Use

* put

as the line prefix inside the block body:

/* put id:'init', label:'Initialize Config', output:'config.internal' */

/**
 * put id:'process', \
 *   label:'Process Records', \
 *   input:'config.internal, records.json', \
 *   output:'results.json'
 */
function processRecords(config, records) {
  // ...
}

JSDoc-style annotations are particularly useful when documenting workflow steps alongside API documentation:

/**
 * Transform raw sensor data into normalized readings.
 * put id:'normalize', label:'Normalize Sensor Data', input:'raw_readings.json', output:'normalized.parquet'
 */
export function normalizeSensorData(readings: SensorReading[]): NormalizedData {
  // ...
}

Note: Block comment annotations are not supported for

#

-prefix languages (R, Python, Shell) or

--

-prefix languages (SQL, Lua). Use only line comments for those languages.

Validierung

• Jede annotierte Datei hat syntaktisch gültige PUT-Annotationen

• put("./src/")

  gibt einen DataFrame mit der erwarteten Knotenanzahl zurück
• Keine doppelten

  id

  -Werte im gescannten Verzeichnis

• put_diagram()

  erzeugt ein verbundenes Flowchart (nicht nur isolierte Knoten)
• Mehrzeilige Annotationen (wenn verwendet) werden korrekt mit Backslash-Fortsetzung geparst

• .internal

  -Variablen erscheinen nur als Outputs, nie als dateiübergreifende Inputs

Haeufige Stolperfallen

• Anführungszeichen-Verschachtelungsfehler: PUT-Annotationen verwenden einfache Anführungszeichen:

  id:'name'

  . Doppelte Anführungszeichen verursachen Parsing-Probleme in String-Kontexten.
• Doppelte IDs: Jede

  id

  muss innerhalb des gescannten Bereichs global eindeutig sein. Namenskonvention wie

  <skript>_<schritt>

  verwenden (z. B.

  extract_read

  ,

  transform_clean

  ).

• .internal

  als dateiübergreifender Input:

  .internal

  -Variablen existieren nur während der Skript-Ausführung. Um Daten zwischen Skripten zu übergeben, ein persistiertes Dateiformat als Output eines Skripts und Input des nächsten verwenden.
• Fehlende Verbindungen: Wenn das Diagramm getrennte Knoten zeigt, prüfen, dass Output-Dateinamen in einer Annotation exakt mit Input-Dateinamen in einer anderen übereinstimmen (einschließlich Erweiterungen).
• Falsches Kommentar-Präfix:

  #

  in einer SQL-Datei oder

  //

  in Python zu verwenden, lässt die Annotation als Code statt als Kommentar behandelt werden.
• Vergessene Mehrzeilige Fortsetzung: Bei mehrzeiligen Annotationen muss jede fortgesetzte Zeile mit

  \

  enden und die nächste Zeile muss mit dem Kommentar-Präfix beginnen.
• Python-Triple-Quote-Strings: putior scannt Python-Triple-Quote-Strings nicht. Immer

  #

  für Python-PUT-Annotationen verwenden.

Verwandte Skills

• analyze-codebase-workflow

  — Voraussetzung: erzeugt den Annotationsplan, dem dieses Skill folgt

• generate-workflow-diagram

  — nächster Schritt: endgültiges Diagramm aus Annotationen generieren

• install-putior

  — putior muss vor dem Annotieren installiert sein

• configure-putior-mcp

  — MCP-Tools bieten interaktive Annotationshilfe
• Files excluded via

  exclude

  parameter do not appear in the workflow (e.g.,

  put("./src/", exclude = "test_")

  skips test helpers)