nfrgate 0.1.0__py3-none-any.whl

nfr_gate/analysis/base.py

@@ -0,0 +1,67 @@
+"""Language-agnostic core of the AST parsing pipeline. `LanguageAnalyzer` is
+the Strategy interface (technical_implementation_spec.md §C.1) — the pipeline
+that walks a `DiffContext` for constructs of interest never imports a
+concrete language analyzer, only this interface, so adding Go or Java later
+means adding a new `languages/*.py` file, not touching this one.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from tree_sitter import Language, Tree
+
+if TYPE_CHECKING:
+    # Deferred to avoid a circular import: constructs.py imports DiffContext
+    # from this module. Safe at type-check time only because of the
+    # `from __future__ import annotations` above (annotations are strings,
+    # never evaluated at runtime).
+    from nfr_gate.analysis.constructs import Construct
+    from nfr_gate.domain.models.finding import Finding, FindingCategory
+
+
+@dataclass(frozen=True)
+class DiffContext:
+    file_path: str
+    language: str
+    tree: Tree
+    source_bytes: bytes
+    changed_line_ranges: list[tuple[int, int]]  # from diff_parser.FileDiff.added_line_ranges
+
+
+class LanguageAnalyzer(ABC):
+    language: str
+
+    @property
+    @abstractmethod
+    def ts_language(self) -> Language:
+        """The compiled tree-sitter grammar, needed to build Query objects
+        against this language's node types."""
+
+    @abstractmethod
+    def parse(self, source: bytes) -> Tree: ...
+
+
+class RuleEvaluator(ABC):
+    """Strategy interface: one implementation per static-analyzable (or
+    static-component-of-'both') rule code. The pipeline calls every
+    applicable evaluator with the *same* pre-computed construct list from
+    constructs.find_constructs() — evaluators do not run their own queries,
+    so adding a 5th rule never means re-parsing or re-querying the diff."""
+
+    rule_code: str
+    category: "FindingCategory"
+    languages: frozenset[str]
+
+    def applies_to(self, language: str) -> bool:
+        return language in self.languages
+
+    @abstractmethod
+    def evaluate(self, ctx: DiffContext, constructs: list["Construct"]) -> list["Finding"]:
+        """Implementations filter `constructs` to the kind(s) and
+        `in_diff=True` entries they care about, and return one Finding per
+        construct they have an opinion on. Constructs the rule doesn't
+        apply to are simply not represented in the output — evaluate()
+        never raises or returns a placeholder for "not applicable"."""

nfr_gate/analysis/cli.py

@@ -0,0 +1,83 @@
+"""Sprint 2 done-when demo:
+
+    python -m nfr_gate.analysis.cli <diff_file> <source_file>
+
+Given a PR diff and the post-change source file it targets (as the CI job
+would have from a real checkout — see diff_parser.py's docstring for why the
+diff itself isn't used to reconstruct content), parses the file to an AST,
+prints the syntax tree, lists every construct of interest the query files
+find (flagging which fall inside lines the diff actually added), and runs
+every registered rule evaluator against them, printing the resulting
+normalized Findings — this is the full parse -> construct -> Finding
+pipeline end to end, not just the parsing half.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from nfr_gate.analysis.base import DiffContext
+from nfr_gate.analysis.constructs import find_constructs
+from nfr_gate.analysis.diff_parser import parse_unified_diff
+from nfr_gate.analysis.languages.python_analyzer import PythonAnalyzer
+from nfr_gate.analysis.rules.registry import rules_for_language
+
+
+def analyze(diff_path: Path, source_path: Path) -> None:
+    file_diffs = parse_unified_diff(diff_path.read_text())
+    if not file_diffs:
+        raise SystemExit(f"No file diffs found in {diff_path}")
+    file_diff = file_diffs[0]  # sample diff touches exactly one file
+
+    analyzer = PythonAnalyzer()
+    source_bytes = source_path.read_bytes()
+    tree = analyzer.parse(source_bytes)
+
+    ctx = DiffContext(
+        file_path=file_diff.file_path,
+        language=analyzer.language,
+        tree=tree,
+        source_bytes=source_bytes,
+        changed_line_ranges=file_diff.added_line_ranges,
+    )
+
+    print(f"=== Parsed {ctx.file_path} ({len(source_bytes)} bytes, {tree.root_node.end_point[0] + 1} lines) ===")
+    print(f"Changed line ranges from diff: {ctx.changed_line_ranges}")
+    print()
+    print("=== Syntax tree (S-expression) ===")
+    print(str(tree.root_node))
+    print()
+
+    constructs = find_constructs(ctx, analyzer.ts_language)
+    in_diff_count = sum(c.in_diff for c in constructs)
+    print(f"=== Constructs found: {len(constructs)} ({in_diff_count} within changed lines) ===")
+    for c in sorted(constructs, key=lambda c: c.start_line):
+        marker = "DIFF" if c.in_diff else "    "
+        first_line = c.snippet.splitlines()[0]
+        print(f"[{marker}] {c.kind:<16} L{c.start_line}-{c.end_line}  {first_line}")
+    print()
+
+    findings = [
+        finding
+        for rule in rules_for_language(analyzer.language)
+        for finding in rule.evaluate(ctx, constructs)
+    ]
+    print(f"=== Findings: {len(findings)} ===")
+    for f in sorted(findings, key=lambda f: (f.line_number or 0, f.rule_code)):
+        print(
+            f"[{f.result:<7}] {f.rule_code}  L{f.line_number}  "
+            f"confidence={f.confidence:.2f}  {f.evidence.splitlines()[0]}"
+        )
+        if f.reasoning:
+            print(f"           {f.reasoning}")
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        raise SystemExit("usage: python -m nfr_gate.analysis.cli <diff_file> <source_file>")
+    analyze(Path(sys.argv[1]), Path(sys.argv[2]))
+
+
+if __name__ == "__main__":
+    main()

nfr_gate/analysis/constructs.py

@@ -0,0 +1,113 @@
+"""Runs the tree-sitter query files in queries/{language}/ against a parsed
+AST and yields the constructs of interest they find. This is deliberately
+construct identification only — no confidence score, no pass/fail, no
+normalized Finding — that's the next task (normalized finding interface +
+rule evaluators). This module just answers "where are the outbound calls,
+catch blocks, and route definitions," restricted to lines the diff touched.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+
+from tree_sitter import Language, Node, Query, QueryCursor
+
+from nfr_gate.analysis.base import DiffContext
+from nfr_gate.analysis.diff_parser import line_in_ranges
+
+QUERIES_DIR = Path(__file__).parent / "queries"
+
+# Per language: (query filename stem, capture name for the whole construct,
+# construct kind). `kind` is the language-agnostic label rule evaluators
+# filter on — languages whose grammar has no direct equivalent of a
+# Python-style except block (Go) still produce a `catch_block`-kind
+# construct from whatever their own error-handling idiom's query finds
+# (Go: an `if err != nil { ... }` block), so rule logic that filters on
+# `kind` doesn't need to know which language it's looking at.
+CONSTRUCT_QUERIES: dict[str, list[tuple[str, str, str]]] = {
+    "python": [
+        ("outbound_calls", "outbound_call", "external_call"),
+        ("exception_handlers", "catch_block", "catch_block"),
+        ("route_definitions", "route_definition", "route_definition"),
+        ("retry_blocks", "sleep_call", "sleep_call"),
+        ("span_calls", "span_call", "span_call"),
+        ("metric_label_calls", "metric_label_call", "metric_label_call"),
+    ],
+    "java": [
+        ("outbound_calls", "outbound_call", "external_call"),
+        ("exception_handlers", "catch_block", "catch_block"),
+        ("retry_blocks", "sleep_call", "sleep_call"),
+        ("route_definitions", "route_definition", "route_definition"),
+        ("span_calls", "span_call", "span_call"),
+        ("metric_label_calls", "metric_label_call", "metric_label_call"),
+    ],
+    "go": [
+        ("outbound_calls", "outbound_call", "external_call"),
+        ("error_checks", "error_check_block", "catch_block"),
+        ("retry_blocks", "sleep_call", "sleep_call"),
+        ("route_definitions", "route_definition", "route_definition"),
+        ("span_calls", "span_call", "span_call"),
+        ("metric_label_calls", "metric_label_call", "metric_label_call"),
+    ],
+}
+
+
+@dataclass(frozen=True)
+class Construct:
+    kind: str  # 'external_call' | 'catch_block' | 'route_definition' | 'sleep_call' | 'span_call' | 'metric_label_call'
+    file_path: str
+    start_line: int  # 1-indexed
+    end_line: int
+    snippet: str
+    in_diff: bool  # whether this construct falls within a changed line range
+    node: Node = field(repr=False, compare=False)
+    # Rule evaluators need the actual node (to inspect arguments, walk
+    # parents for an enclosing span/loop, etc.) — constructs.py only finds
+    # *where* things are; rule-specific inspection stays in analysis/rules/.
+
+
+@lru_cache(maxsize=None)
+def _load_query(ts_language: Language, language: str, query_name: str) -> Query:
+    # Query compilation is real, non-trivial work (parses the .scm pattern
+    # itself). The query text is static per (language, query_name) — a CI
+    # run touching N files must not recompile the same 3 queries N times.
+    # Cached for the life of the process, keyed by object identity of
+    # ts_language, which is stable for a given LanguageAnalyzer instance.
+    path = QUERIES_DIR / language / f"{query_name}.scm"
+    return Query(ts_language, path.read_text())
+
+
+def find_constructs(ctx: DiffContext, ts_language: Language) -> list[Construct]:
+    """Runs every registered query for ctx.language and returns every match,
+    tagged with whether it falls inside a line range the diff actually added.
+    Callers that only care about new code (e.g. static rule evaluators, which
+    should not re-flag pre-existing gaps) filter on `in_diff`."""
+    results: list[Construct] = []
+
+    for query_name, capture_name, kind in CONSTRUCT_QUERIES.get(ctx.language, []):
+        query = _load_query(ts_language, ctx.language, query_name)
+        cursor = QueryCursor(query)
+        matches = cursor.matches(ctx.tree.root_node)
+
+        for _pattern_index, captures in matches:
+            for node in captures.get(capture_name, []):
+                start_line = node.start_point[0] + 1
+                end_line = node.end_point[0] + 1
+                results.append(
+                    Construct(
+                        kind=kind,
+                        file_path=ctx.file_path,
+                        start_line=start_line,
+                        end_line=end_line,
+                        snippet=node.text.decode("utf-8", errors="replace"),
+                        in_diff=any(
+                            line_in_ranges(line, ctx.changed_line_ranges)
+                            for line in range(start_line, end_line + 1)
+                        ),
+                        node=node,
+                    )
+                )
+
+    return results

nfr_gate/analysis/diff_parser.py

@@ -0,0 +1,73 @@
+"""Parses a unified diff (`git diff` / `diff -u` format, same shape a PR diff
+arrives in from GitHub/GitLab) into, per file, the line ranges that were
+actually added — nothing more. It does not reconstruct file content: the
+pipeline reads the real post-change source from the checked-out repo and
+uses this module only to know which lines in that source are new, so rule
+evaluators can skip untouched code instead of re-flagging pre-existing gaps
+on every PR that happens to touch the same file.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_HUNK_HEADER_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+
+
+@dataclass(frozen=True)
+class FileDiff:
+    file_path: str
+    added_line_ranges: list[tuple[int, int]]  # 1-indexed, inclusive, in the NEW file
+
+
+def parse_unified_diff(diff_text: str) -> list[FileDiff]:
+    files: list[FileDiff] = []
+    current_path: str | None = None
+    current_ranges: list[list[int]] = []
+    new_line_no: int | None = None
+
+    def flush() -> None:
+        nonlocal current_path, current_ranges
+        if current_path is not None:
+            files.append(FileDiff(current_path, [tuple(r) for r in current_ranges]))
+        current_path, current_ranges = None, []
+
+    for line in diff_text.splitlines():
+        if line.startswith("+++ "):
+            flush()
+            path = line[4:].strip()
+            current_path = path[2:] if path.startswith("b/") else path
+            new_line_no = None
+            continue
+
+        if line.startswith("--- ") or line.startswith("diff ") or line.startswith("index "):
+            continue
+
+        hunk_match = _HUNK_HEADER_RE.match(line)
+        if hunk_match:
+            new_line_no = int(hunk_match.group(3))
+            continue
+
+        if current_path is None or new_line_no is None:
+            continue
+
+        if line.startswith("\\"):  # ""
+            continue
+        if line.startswith("+"):
+            if current_ranges and current_ranges[-1][1] == new_line_no - 1:
+                current_ranges[-1][1] = new_line_no
+            else:
+                current_ranges.append([new_line_no, new_line_no])
+            new_line_no += 1
+        elif line.startswith("-"):
+            pass  # removed line: doesn't exist in the new file, don't advance the counter
+        else:
+            new_line_no += 1  # context line
+
+    flush()
+    return files
+
+
+def line_in_ranges(line: int, ranges: list[tuple[int, int]]) -> bool:
+    return any(start <= line <= end for start, end in ranges)

nfr_gate/analysis/languages/go_analyzer.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import tree_sitter_go as tsgo
+from tree_sitter import Language, Parser, Tree
+
+from nfr_gate.analysis.base import LanguageAnalyzer
+
+
+class GoAnalyzer(LanguageAnalyzer):
+    language = "go"
+
+    def __init__(self) -> None:
+        self._ts_language = Language(tsgo.language())
+        self._parser = Parser(self._ts_language)
+
+    @property
+    def ts_language(self) -> Language:
+        return self._ts_language
+
+    def parse(self, source: bytes) -> Tree:
+        return self._parser.parse(source)

nfr_gate/analysis/languages/java_analyzer.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import tree_sitter_java as tsjava
+from tree_sitter import Language, Parser, Tree
+
+from nfr_gate.analysis.base import LanguageAnalyzer
+
+
+class JavaAnalyzer(LanguageAnalyzer):
+    language = "java"
+
+    def __init__(self) -> None:
+        self._ts_language = Language(tsjava.language())
+        self._parser = Parser(self._ts_language)
+
+    @property
+    def ts_language(self) -> Language:
+        return self._ts_language
+
+    def parse(self, source: bytes) -> Tree:
+        return self._parser.parse(source)

nfr_gate/analysis/languages/python_analyzer.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import tree_sitter_python as tspython
+from tree_sitter import Language, Parser, Tree
+
+from nfr_gate.analysis.base import LanguageAnalyzer
+
+
+class PythonAnalyzer(LanguageAnalyzer):
+    language = "python"
+
+    def __init__(self) -> None:
+        self._ts_language = Language(tspython.language())
+        self._parser = Parser(self._ts_language)
+
+    @property
+    def ts_language(self) -> Language:
+        return self._ts_language
+
+    def parse(self, source: bytes) -> Tree:
+        return self._parser.parse(source)

nfr_gate/analysis/languages/registry.py

@@ -0,0 +1,33 @@
+"""Maps a file extension to the LanguageAnalyzer that handles it — the one
+place that needs to know which languages exist. constructs.py, the rule
+evaluators, and the CI pipeline are all parameterized by `language: str`
+and don't care how a file got mapped to one, so adding a fourth language
+is additive here, not a change to any of them.
+"""
+
+from __future__ import annotations
+
+from nfr_gate.analysis.base import LanguageAnalyzer
+from nfr_gate.analysis.languages.go_analyzer import GoAnalyzer
+from nfr_gate.analysis.languages.java_analyzer import JavaAnalyzer
+from nfr_gate.analysis.languages.python_analyzer import PythonAnalyzer
+
+# Instantiated once at import time — building a tree-sitter Parser per file
+# would be the same wasted-repeated-work pattern the query cache in
+# constructs.py already exists to avoid.
+_ANALYZERS: dict[str, LanguageAnalyzer] = {
+    ".py": PythonAnalyzer(),
+    ".java": JavaAnalyzer(),
+    ".go": GoAnalyzer(),
+}
+
+
+def analyzer_for_path(file_path: str) -> LanguageAnalyzer | None:
+    for ext, analyzer in _ANALYZERS.items():
+        if file_path.endswith(ext):
+            return analyzer
+    return None
+
+
+def supported_extensions() -> list[str]:
+    return list(_ANALYZERS.keys())

nfr_gate/analysis/queries/go/error_checks.scm

@@ -0,0 +1,22 @@
+; Go has no exception/catch construct — the idiomatic equivalent of "did
+; this error path get handled" is `if err != nil { ... }`. This query
+; matches that shape specifically (excludes `== nil`, i.e. the success
+; branch) and maps to the SAME construct kind ("catch_block") that
+; except_clause/catch_clause map to in Python/Java, so rule L2's logic
+; doesn't need to know which language it's looking at — only that a
+; "catch_block"-kind construct's body might or might not contain a
+; structured log call.
+;
+; #match? on "err" is a substring match, matching Go's near-universal
+; convention of naming error variables err/writeErr/parseErr/etc. — not a
+; guarantee every err-shaped comparison is really an error check, but a
+; defensible heuristic for v1.
+
+(if_statement
+  condition: (binary_expression
+    left: (identifier) @_err_ident
+    "!="
+    right: (nil))
+  consequence: (block) @_consequence
+  (#match? @_err_ident "err")
+) @error_check_block

nfr_gate/analysis/queries/go/metric_label_calls.scm

@@ -0,0 +1,9 @@
+; Matches `.With(...)` calls — the standard prometheus client_golang idiom
+; for attaching a `prometheus.Labels{...}` composite literal to a metric
+; before incrementing/observing it. M3 inspects the argument text for
+; unbounded-looking keys, not the query's job.
+
+(call_expression
+  function: (selector_expression field: (field_identifier) @_method)
+  (#eq? @_method "With")
+) @metric_label_call

nfr_gate/analysis/queries/go/outbound_calls.scm

@@ -0,0 +1,13 @@
+; Matches "obj.Method(...)"-shaped calls where the receiver is a plain
+; identifier: client.Post(...), db.Query(...). Deliberately requires the
+; operand to be a bare identifier (not a chained selector like
+; resp.Body.Close()), which cuts some of the false-positive rate the
+; Python/Java versions of this heuristic carry, as a side effect rather
+; than a deliberate precision fix — still not a whitelist of real
+; HTTP/DB clients. Consumed by rules T1 and R1.
+
+(call_expression
+  function: (selector_expression
+    operand: (identifier) @callee_object
+    field: (field_identifier) @callee_method)
+) @outbound_call

nfr_gate/analysis/queries/go/retry_blocks.scm

@@ -0,0 +1,14 @@
+; Matches time.Sleep(...) — the standard Go retry-delay idiom. Consumed by
+; rule R2 (retry_without_backoff). Classifying the delay expression's shape
+; (fixed vs. backoff-shaped) happens in Python against the captured node —
+; see analysis/rules/go/retry_backoff_rule.py, which has to account for
+; Go's `N * time.Second` idiom meaning a FIXED delay, not backoff, unlike a
+; bare arithmetic expression in Python.
+
+(call_expression
+  function: (selector_expression
+    operand: (identifier) @_sleep_object
+    field: (field_identifier) @_sleep_method)
+  (#eq? @_sleep_object "time")
+  (#eq? @_sleep_method "Sleep")
+) @sleep_call

nfr_gate/analysis/queries/go/route_definitions.scm

@@ -0,0 +1,16 @@
+; Matches an inline HTTP handler registration: router.GET/POST/PUT/DELETE/
+; PATCH("path", func(...) {...}) (Gin-style) or http.HandleFunc("path",
+; func(...) {...}) (stdlib). Deliberately scoped to the INLINE-func-literal
+; shape only — a handler registered by name reference
+; (router.GET("/charge", chargeHandler)) is not resolved to its declaration
+; elsewhere in the file; that needs call-graph resolution this pass doesn't
+; have. Consumed by rules M1 (missing_latency_metric) and M2
+; (missing_outcome_metric).
+
+(call_expression
+  function: (selector_expression field: (field_identifier) @_method)
+  arguments: (argument_list
+    (interpreted_string_literal)
+    (func_literal) @_handler)
+  (#match? @_method "^(GET|POST|PUT|DELETE|PATCH|HandleFunc)$")
+) @route_definition

nfr_gate/analysis/queries/go/span_calls.scm

@@ -0,0 +1,10 @@
+; Matches `.Start(...)` calls — the same method name is_wrapped_in_span/
+; has_preceding_call already key on for T1/R1's "was a span set up
+; earlier in this function" check, but captured here as its own construct
+; so T2 can inspect what happens to *this specific* span (are attributes
+; ever set on it), independent of whether an outbound call follows it.
+
+(call_expression
+  function: (selector_expression field: (field_identifier) @_method)
+  (#eq? @_method "Start")
+) @span_call

nfr_gate/analysis/queries/java/exception_handlers.scm

@@ -0,0 +1,3 @@
+; Every catch clause, empty or not. Consumed by rule L2 (structured logging).
+
+(catch_clause) @catch_block

nfr_gate/analysis/queries/java/metric_label_calls.scm

@@ -0,0 +1,10 @@
+; Matches Micrometer's `.tag(key, value)` / `.tags(k1, v1, k2, v2, ...)`
+; calls — the standard way to attach dimensions to a metric in Java's
+; dominant metrics library. M3 inspects the string-literal argument text
+; for unbounded-looking keys, not the query's job — this query only finds
+; the call.
+
+(method_invocation
+  name: (identifier) @_method
+  (#match? @_method "^(tag|tags)$")
+) @metric_label_call

nfr_gate/analysis/queries/java/outbound_calls.scm

@@ -0,0 +1,14 @@
+; Matches "obj.method(...)"-shaped method invocations where the receiver is
+; a plain identifier: client.send(...), httpClient.execute(...). Requiring
+; a bare identifier (not `object: (_)`) excludes fluent builder chains
+; (`HttpRequest.newBuilder().uri(...).POST(...).build()`) from each being
+; flagged as a separate outbound call — matches the same restriction
+; already applied in the Go query, for the same reason. Still a broad
+; heuristic, not a whitelist of known HTTP/DB clients — carries the same
+; general false-positive risk as the Python/Go versions.
+; Consumed by rules T1 and R1.
+
+(method_invocation
+  object: (identifier)
+  name: (identifier) @callee_method
+) @outbound_call

nfr_gate/analysis/queries/java/retry_blocks.scm

@@ -0,0 +1,9 @@
+; Matches Thread.sleep(...) — the standard Java retry-delay idiom. Consumed
+; by rule R2 (retry_without_backoff).
+
+(method_invocation
+  object: (identifier) @_sleep_object
+  name: (identifier) @_sleep_method
+  (#eq? @_sleep_object "Thread")
+  (#eq? @_sleep_method "sleep")
+) @sleep_call

nfr_gate/analysis/queries/java/route_definitions.scm

@@ -0,0 +1,13 @@
+; Matches a Spring-style route handler: a method_declaration annotated with
+; @GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@PatchMapping/
+; @RequestMapping, with or without a path argument (marker_annotation vs.
+; annotation — Spring allows a bare @GetMapping mapping to the class-level
+; @RequestMapping's base path). Consumed by rules M1 (missing_latency_metric)
+; and M2 (missing_outcome_metric), mirroring python/route_definitions.scm.
+
+(method_declaration
+  (modifiers
+    [(annotation name: (identifier) @_annotation_name)
+     (marker_annotation name: (identifier) @_annotation_name)])
+  (#match? @_annotation_name "^(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|RequestMapping)$")
+) @route_definition

nfr_gate/analysis/queries/java/span_calls.scm

@@ -0,0 +1,11 @@
+; Matches `.startSpan()` — the call that actually creates a span in Java's
+; OTel API (`tracer.spanBuilder("name").startSpan()`), as distinct from
+; is_wrapped_in_span's textual check on the enclosing try-with-resources's
+; `makeCurrent()` call. T2 needs to inspect what happens around *this*
+; call (is an attribute ever set on the resulting span), which
+; outbound_calls.scm's capture doesn't give direct access to.
+
+(method_invocation
+  name: (identifier) @_method
+  (#eq? @_method "startSpan")
+) @span_call

nfr_gate/analysis/queries/python/exception_handlers.scm

@@ -0,0 +1,5 @@
+; Matches every except clause, empty or not. Whether it actually logs is the
+; rule evaluator's job (L1: no_swallowed_exception), not the query's — this
+; query's only job is to find the construct.
+
+(except_clause) @catch_block

nfr_gate/analysis/queries/python/metric_label_calls.scm

@@ -0,0 +1,11 @@
+; Matches `.labels(...)` / `.tags(...)` calls — the standard way both
+; prometheus_client and most StatsD-style clients attach dimensions to a
+; metric. M3 inspects the keyword argument *names* passed here for
+; unbounded-looking fields (user_id, email, a raw URL, ...), not the query's
+; job — this query only finds the call.
+
+(call
+  function: (attribute
+    attribute: (identifier) @_method)
+  (#match? @_method "^(labels|tags)$")
+) @metric_label_call

nfr_gate/analysis/queries/python/outbound_calls.scm

@@ -0,0 +1,12 @@
+; Matches "obj.method(...)"-shaped calls: requests.get(...), httpx.post(...),
+; db_client.execute(...), payment_client.charge(...). This is a heuristic,
+; not a whitelist of known HTTP/DB clients — bare function calls (print(),
+; len()) are excluded by requiring an attribute-access callee, which is
+; deliberately broad for v1 rather than tuned per-library. Consumed by rules
+; T1 (trace_span_missing) and R1 (missing_timeout) per rubric_store/definitions.
+
+(call
+  function: (attribute
+    object: (identifier) @callee_object
+    attribute: (identifier) @callee_method)
+) @outbound_call

nfr_gate/analysis/queries/python/retry_blocks.scm

@@ -0,0 +1,14 @@
+; Matches calls to time.sleep(...) / asyncio.sleep(...) — the delay
+; mechanism a retry loop uses between attempts. Consumed by rule R2
+; (retry_without_backoff). Whether this is actually inside a retry loop
+; (vs. e.g. a one-off startup delay) and what the delay argument's shape
+; implies about backoff is decided in Python by walking the node directly
+; (see analysis/rules/retry_backoff_rule.py) — this query's only job is to
+; find candidate sleep calls.
+
+(call
+  function: (attribute
+    object: (identifier) @_sleep_object
+    attribute: (identifier) @_sleep_method)
+  (#match? @_sleep_method "^sleep$")
+) @sleep_call