graphglot 0.1.4__py3-none-any.whl

graphglot/__init__.py

@@ -0,0 +1,5 @@
+"""GraphGlot - A Graph Query Language Toolkit."""
+
+from importlib.metadata import version
+
+__version__ = version("graphglot")

graphglot/analysis/__init__.py

@@ -0,0 +1,11 @@
+"""Semantic analysis module for GQL queries."""
+
+from graphglot.analysis.analyzer import SemanticAnalyzer
+from graphglot.analysis.models import AnalysisContext, AnalysisResult, SemanticDiagnostic
+
+__all__ = [
+    "AnalysisContext",
+    "AnalysisResult",
+    "SemanticAnalyzer",
+    "SemanticDiagnostic",
+]

graphglot/analysis/analyzer.py

@@ -0,0 +1,68 @@
+"""Semantic analyzer — runs registered rules and collects diagnostics."""
+
+from __future__ import annotations
+
+import typing as t
+
+from graphglot.analysis.models import AnalysisContext, AnalysisResult
+from graphglot.analysis.rules import RULE_REGISTRY, STRUCTURAL_RULES
+
+if t.TYPE_CHECKING:
+    from graphglot.ast.base import Expression
+    from graphglot.dialect.base import Dialect
+    from graphglot.lineage.models import LineageGraph
+    from graphglot.typing.annotator import ExternalContext
+
+
+class SemanticAnalyzer:
+    """Orchestrates semantic analysis rules against an AST."""
+
+    def analyze(
+        self,
+        expression: Expression,
+        dialect: Dialect,
+        lineage: LineageGraph | None = None,
+        annotate_types: bool = True,
+        external_context: ExternalContext | None = None,
+        disabled_rules: set[str] | None = None,
+    ) -> AnalysisResult:
+        """Run all registered analysis rules and collect feature usage.
+
+        When *annotate_types* is True (the default), a :class:`TypeAnnotator`
+        pass runs before the rules so that ``_resolved_type`` is available on
+        every AST node.
+
+        *external_context* is forwarded to the :class:`TypeAnnotator` so that
+        user-supplied parameter types (e.g. graph or binding-table parameters)
+        are available during type inference.
+
+        *disabled_rules* is an optional set of rule IDs (feature IDs for
+        feature-gated rules, or structural rule names) to skip entirely.
+        """
+
+        if annotate_types:
+            from graphglot.typing import TypeAnnotator
+
+            TypeAnnotator(dialect=dialect, external_context=external_context).annotate(expression)
+
+        ctx = AnalysisContext(expression=expression, dialect=dialect, lineage=lineage)
+        result = AnalysisResult()
+        for feature_id, rule_fn in RULE_REGISTRY.items():
+            if disabled_rules and feature_id in disabled_rules:
+                continue
+            rule_diagnostics = rule_fn(ctx)
+            if not rule_diagnostics:
+                continue
+            result.features.add(feature_id)
+            if not dialect.is_feature_supported(feature_id):
+                result.diagnostics.extend(rule_diagnostics)
+
+        # Structural rules always fire (not feature-gated).
+        for rule_id, rule_fn in STRUCTURAL_RULES.items():
+            if disabled_rules and rule_id in disabled_rules:
+                continue
+            rule_diagnostics = rule_fn(ctx)
+            if rule_diagnostics:
+                result.diagnostics.extend(rule_diagnostics)
+
+        return result

graphglot/analysis/models.py

@@ -0,0 +1,81 @@
+"""Data models for semantic analysis."""
+
+from __future__ import annotations
+
+import typing as t
+
+from dataclasses import dataclass, field
+
+from graphglot.error import Diagnostic, Severity, Span
+
+if t.TYPE_CHECKING:
+    from graphglot.ast.base import Expression
+    from graphglot.dialect.base import Dialect
+    from graphglot.lineage.models import LineageGraph
+
+
+@dataclass
+class AnalysisContext:
+    """Context passed to each analysis rule."""
+
+    expression: Expression
+    dialect: Dialect
+    lineage: LineageGraph | None = None
+
+
+@dataclass
+class SemanticDiagnostic:
+    """A single diagnostic emitted by a semantic analysis rule."""
+
+    feature_id: str
+    message: str
+    node: Expression | None = None
+    line: int | None = field(default=None, init=False)
+    col: int | None = field(default=None, init=False)
+    span: Span | None = field(default=None, init=False)
+
+    def __post_init__(self) -> None:
+        cur = self.node
+        while cur is not None:
+            start_tok = getattr(cur, "_start_token", None)
+            if start_tok is not None:
+                self.line = start_tok.line
+                self.col = start_tok.col
+                end_tok = getattr(cur, "_end_token", None) or start_tok
+                self.span = Span(
+                    start_line=start_tok.line,
+                    start_column=start_tok.col,
+                    end_line=end_tok.line,
+                    end_column=end_tok.col,
+                    start_offset=start_tok.start,
+                    end_offset=end_tok.end + 1,
+                )
+                return
+            cur = getattr(cur, "_parent", None)
+
+    def __str__(self) -> str:
+        pos = f" (line {self.line}, col {self.col})" if self.line is not None else ""
+        return f"[{self.feature_id}] {self.message}{pos}"
+
+    def to_diagnostic(self) -> Diagnostic:
+        return Diagnostic(
+            code=self.feature_id,
+            message=self.message,
+            severity=Severity.ERROR,
+            phase="analysis",
+            span=self.span,
+            node=self.node,
+        )
+
+
+@dataclass
+class AnalysisResult:
+    """Result of running semantic analysis on an expression."""
+
+    diagnostics: list[SemanticDiagnostic] = field(default_factory=list)
+    features: set[str] = field(default_factory=set)
+
+    @property
+    def ok(self) -> bool:
+        """True when no diagnostics were emitted."""
+        return len(self.diagnostics) == 0

graphglot/analysis/rules/__init__.py

@@ -0,0 +1,24 @@
+"""Rule registry for semantic analysis."""
+
+import graphglot.analysis.rules.scope_rules as scope_rules
+import graphglot.analysis.rules.scope_validator as scope_validator
+import graphglot.analysis.rules.structural_rules as structural_rules
+
+from graphglot.analysis.rules._registry import (
+    RULE_REGISTRY,
+    STRUCTURAL_RULES,
+    AnalysisRuleFn,
+    analysis_rule,
+    structural_rule,
+)
+
+__all__ = [
+    "RULE_REGISTRY",
+    "STRUCTURAL_RULES",
+    "AnalysisRuleFn",
+    "analysis_rule",
+    "scope_rules",
+    "scope_validator",
+    "structural_rule",
+    "structural_rules",
+]

graphglot/analysis/rules/_registry.py

@@ -0,0 +1,36 @@
+"""Core registry data structures and decorators for analysis rules."""
+
+from __future__ import annotations
+
+import typing as t
+
+from graphglot.analysis.models import AnalysisContext, SemanticDiagnostic
+
+AnalysisRuleFn = t.Callable[[AnalysisContext], list[SemanticDiagnostic]]
+
+RULE_REGISTRY: dict[str, AnalysisRuleFn] = {}
+STRUCTURAL_RULES: dict[str, AnalysisRuleFn] = {}
+
+
+def analysis_rule(feature_id: str):
+    """Register a function as the analysis rule for a feature.
+
+    Rules fire when the feature is **absent** from the dialect — if the dialect
+    supports the feature, the restriction doesn't apply.
+    """
+
+    def decorator(fn: AnalysisRuleFn) -> AnalysisRuleFn:
+        RULE_REGISTRY[feature_id] = fn
+        return fn
+
+    return decorator
+
+
+def structural_rule(rule_id: str):
+    """Register a rule that always fires (not feature-gated)."""
+
+    def decorator(fn: AnalysisRuleFn) -> AnalysisRuleFn:
+        STRUCTURAL_RULES[rule_id] = fn
+        return fn
+
+    return decorator