sitting_duck

Quellcode-ASTs aus 27 Programmiersprachen mit tree-sitter-Grammatiken, Musterabgleich und struktureller Suche parsen und analysieren

Maintainer: teaguesterling

Installation und Laden

INSTALL sitting_duck FROM community;
LOAD sitting_duck;

Beispiel

-- Parse Python code and find function definitions
SELECT name, start_line, peek
FROM parse_ast('
def hello():
    return "hello world"
def greet(name):
    print(f"Hello, {name}!")
    return name
', 'python')
WHERE is_function_definition(semantic_type);

-- Pattern matching: find eval() calls and capture arguments
SELECT captures['X'].peek as dangerous_input, file_path, start_line
FROM ast_match('code', 'eval(__X__)', 'python');

-- Pattern matching with variadic wildcards
SELECT captures['F'].name as func_name, captures['Y'].peek as return_value
FROM ast_match('code',
    'def __F__(__):
    %__<BODY*>__%
    return __Y__', 'python');

-- Security audit: find dangerous function calls
SELECT * FROM ast_security_audit('code')
WHERE risk_level = 'high';

-- Function complexity metrics
SELECT name, cyclomatic, max_depth, lines
FROM ast_function_metrics('code')
WHERE cyclomatic > 10;

-- Cross-language analysis with semantic types
SELECT language, COUNT(*) as functions
FROM read_ast(['src/**/*.py', 'src/**/*.js', 'src/**/*.go'])
WHERE is_function_definition(semantic_type)
GROUP BY language;

Über sitting_duck

Sitting Duck ist eine DuckDB-Erweiterung zum Parsen von Quellcode in Abstract Syntax Trees (ASTs) mit tree-sitter-Grammatiken. Sie bietet eine leistungsstarke SQL-Schnittstelle, um Codestruktur über 25+ Programmiersprachen zu analysieren, zu durchsuchen und zu verstehen.

Dokumentation: https://sitting-duck.readthedocs.io/

Kernfunktionen

Musterabgleich: Finden Sie Codestrukturen per Pattern-by-Example-Matching mit Wildcards:

-- Recursive wildcards for deep matching
SELECT * FROM ast_match('code', 'class __C__: %__<**>__% def __M__(self): %__<BODY*>__%', 'python');

-- Optional and negation wildcards
SELECT * FROM ast_match('code', 'def __F__(__<?ARGS>__): %__<BODY*>__%', 'python');

See: https://sitting-duck.readthedocs.io/en/latest/guide/pattern-matching/

CSS-Selektor-Abfragen (v1.6.0, erweitert in v1.7.0+): Fragen Sie AST-Knoten mit CSS-Selektor-Syntax ab — bootstrapped mit der eigenen CSS-Grammatik von Sitting Duck:

SELECT name FROM ast_select('src/*.py', '.func:has(.call#execute):not(:has(try_statement))');

-- v1.7.0: :match (current-node) vs :contains (subtree) structural patterns
SELECT name FROM ast_select('src/*.py', '.func:contains("db.execute()")');
SELECT name FROM ast_select('src/*.py', 'call:match("db.execute()")');

-- v1.7.2: parse once, query many — orders of magnitude faster for interactive use
CREATE TABLE my_ast AS SELECT * FROM read_ast('src/**/*.py');
SELECT * FROM ast_select_from('my_ast', '.class:named');
SELECT * FROM ast_select_from('my_ast', '.func:has(return_statement)');

Unterstützt Typselektoren, #name, .semantic (ca. 80 Aliasse), Kombinatoren, :has(), :not(), strukturelle Muster :match() / :contains(), Scope-/Call-Graph-Pseudoklassen und Pseudoelement-Navigation. Nackter Typabgleich: if trifft if + if_statement + if_clause.

v1.10.0 fügt zur Laufzeit ladbare tree-sitter-Grammatiken hinzu (register_language(), standardmäßig aus hinter sitting_duck_enable_runtime_grammars), ast_to_blocks (Codestruktur als duck_blocks-Dokumente darstellen) sowie ast_patch/ast_replace (AST-verankertes Source-Patching und selektorgesteuertes Umschreiben in SQL).

v1.9.0 härtet die Selektor-Engine: keine still-leeren Ergebnisse mehr (Selektoren, die die Engine nicht umsetzen kann, werfen jetzt einen klaren Fehler statt 0 Zeilen), #name an Call-Knoten bindet einheitlich über alle 27 Grammatiken, und NULL-Spalten matchen nicht mehr zu viel oder zu wenig.

Filterung zur Parse-Zeit (v1.8.0): max_depth := und prune := verkleinern den AST zur Parse-Zeit, mit automatischer Tree-Heilung:

SELECT * FROM read_ast('file.py', max_depth := 2);
SELECT * FROM read_ast('src/**/*.py', prune := ['syntax', 'comments', 'punctuation']);

Prune-Richtlinien: syntax, comments, literals, imports, types, punctuation, unnamed, leaves, internal.

Call-Graph-Makros (v1.8.0):

• ast_get_calls(source) - Aufrufe mit Caller-Zuordnung und Typklassifikation
• ast_call_graph(source) - aggregierter Caller→Callee-Graph mit Aufrufzahlen
• ast_find_references(source, name) - symbolische Referenzauflösung mit Scope-Kette

Tabellenfunktionen:

• read_ast(file_pattern, language := NULL) - Quelldateien in AST-Zeilen parsen (parallel)
• parse_ast(content, language) - Quellcode-Zeichenketten parsen (Tabellenfunktion)
• parse_ast_list(content, language) - Quellcode-Zeichenketten parsen (Skalar, gibt LIST zurück; v1.7.0)
• ast_match(source, pattern, lang) - Musterabgleich für die Codesuche
• ast_select(source, css_selector) - CSS-Selektor-Abfragen
• ast_select_from(table_name, selector) - CSS-Selektoren auf vorgeparsten Tabellen (v1.7.2)
• ast_type_map(language) - Knotentyp-Entdeckung über Sprachen hinweg

Extraktionssuffix v1.7.0: Jeder Extraktionsparameter (context, source, structure, peek) kann ein Suffix +schema erhalten, das den vollen Spaltensatz im Ausgabeschema als NULLs behält, ohne sie zu berechnen:

-- Keep peek column in schema but skip its computation
SELECT name, peek FROM read_ast('file.py', peek := 'none+schema');

Ermöglicht SQL-Makros, stabile Schemas zu deklarieren, unabhängig davon, welche Spalten sie füllen.

Relationale Prädikate (v1.5.0):

• ast_has(source, parent_type, child_type) - Enthaltensein prüfen
• ast_inside(source, child_type, parent_type, parent_name) - Knoten in bestimmten Eltern finden
• ast_precedes(source, before_type, after_type) - Ordnungsprädikate
• ast_follows(source, after_type, before_type) - Ordnungsprädikate
• ast_not_has(source, parent_type, child_type) - negiertes Enthaltensein

Analysemakros (dateipfadbasiert):

• ast_definitions(source) - Alle benannten Definitionen mit Kategorien
• ast_function_metrics(source) - Zyklomatische Komplexität, Nesting-Tiefe, Zeilenzahlen
• ast_security_audit(source) - gefährliche Funktionsaufrufmuster erkennen
• ast_dead_code(source) - potenziell ungenutzte Funktionen/Klassen finden
• ast_nesting_analysis(source) - tief verschachtelten Code identifizieren
• ast_definition_parent(table) - nächsten Definitionsvorfahren je Knoten auflösen

Baumnavigation:

• ast_descendants(table, node_id) - Teilbaum holen (O(1) über descendant_count)
• ast_ancestors(table, node_id) - Pfad vom Knoten zur Wurzel
• ast_children(table, node_id) - unmittelbare Kinder
• ast_function_scope(table, node_id) - Funktionskörper ohne verschachtelte Funktionen

Semantische Prädikate: Sprachenübergreifende Filterung mit normalisierten Typen:

• is_function_definition(st), is_class_definition(st), is_variable_definition(st)
• is_function_call(st), is_literal(st), is_conditional(st), is_loop(st)

Unterstützte Sprachen (27)

AST-Schema

Jeder geparste Knoten enthält:

• type, name - Knotentyp und extrahierter Bezeichner
• semantic_type - Normalisierter Typ für sprachübergreifende Abfragen
• file_path, language - Quellort
• start_line, end_line, depth - Position und Verschachtelung
• descendant_count - Für O(1)-Teilbaumabfragen
• peek - Konfigurierbare Quellvorschau
• qualified_name - Scope-basierter, dateiweit eindeutiger Pfad (Format C[User] F[__init__]; v1.7.0)
• signature_type, parameters, modifiers, annotations - Native Extraktion (v1.8.0: modifiers[] befüllt für Python, JS, TS, Rust, Kotlin, Swift, Dart, C#; Flag IS_EXPORTED für Sichtbarkeit auf Dateiebene)
• scope - STRUCT<current, function, class, module, stack> (v1.7.4); ersetzt die Spalten scope_id / scope_stack aus v1.7.2. scope.function beantwortet „in welcher Funktion bin ich?“ als einzelnes Spaltenlesen.

Vollständiges Schema: https://sitting-duck.readthedocs.io/en/latest/api/output-schema/

Anwendungsfälle

• Sicherheitsaudit – gefährliche Muster finden (eval, exec, SQL-Injection)
• Codequalität – Komplexitätsmetriken, Erkennung toten Codes, Nesting-Analyse
• Refactoring – musterbasiertes Codesuchen in großen Codebasen
• Dokumentation – Funktionssignaturen und Struktur extrahieren
• KI-Workflows – strukturiertes Codeverständnis für LLM-Werkzeuge

GitHub: https://github.com/teaguesterling/sitting_duck

Hinzugefügte Funktionen

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen