Downloads 824this week

GitHub stars 12

Extension repository on GitHub

Extension descriptor (YAML)

Parse and analyze source code ASTs from 27 programming languages with tree-sitter grammars, pattern matching, and structural search

Installing and Loading

INSTALL sitting_duck FROM community;
LOAD sitting_duck;

Example

-- 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;

About sitting_duck

Sitting Duck is a DuckDB extension for parsing source code into Abstract Syntax Trees (ASTs) using tree-sitter grammars. It provides a powerful SQL interface to analyze, search, and understand code structure across 25+ programming languages.

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

Core Features

Pattern Matching: Find code structures using pattern-by-example matching with 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/

Table Functions:

• read_ast(file_pattern, language := NULL) - Parse source files into AST rows
• parse_ast(content, language) - Parse source code strings
• ast_match(source, pattern, lang) - Pattern matching for code search

Relational Predicates (v1.5.0):

• ast_has(source, parent_type, child_type) - Check containment relationships
• ast_inside(source, child_type, parent_type, parent_name) - Find nodes inside specific parents
• ast_precedes(source, before_type, after_type) - Ordering predicates
• ast_follows(source, after_type, before_type) - Ordering predicates
• ast_not_has(source, parent_type, child_type) - Negated containment

Analysis Macros (file-path based):

• ast_definitions(source) - All named definitions with categories
• ast_function_metrics(source) - Cyclomatic complexity, nesting depth, line counts
• ast_security_audit(source) - Detect dangerous function call patterns
• ast_dead_code(source) - Find potentially unused functions/classes
• ast_nesting_analysis(source) - Identify deeply nested code
• ast_definition_parent(table) - Resolve nearest definition ancestor per node

Tree Navigation:

• ast_descendants(table, node_id) - Get subtree (O(1) using descendant_count)
• ast_ancestors(table, node_id) - Path from node to root
• ast_children(table, node_id) - Immediate children
• ast_function_scope(table, node_id) - Function body excluding nested functions

Semantic Predicates: Cross-language filtering with normalized types:

• 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)

Supported Languages (27)

AST Schema

Each parsed node includes:

• type, name - Node type and extracted identifier
• semantic_type - Normalized type for cross-language queries
• file_path, language - Source location
• start_line, end_line, depth - Position and nesting
• descendant_count - For O(1) subtree queries
• peek - Configurable source preview
• qualified_name, signature_type, parameters, modifiers, annotations - Native extraction

Full schema: https://sitting-duck.readthedocs.io/en/latest/api/output-schema/

Use Cases

• Security auditing - Find dangerous patterns (eval, exec, SQL injection)
• Code quality - Complexity metrics, dead code detection, nesting analysis
• Refactoring - Pattern-based code search across large codebases
• Documentation - Extract function signatures and structure
• AI workflows - Structured code understanding for LLM tools

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

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings

This extension does not add any settings.