Skip to content

Commit 405cf66

Browse files
authored
Merge pull request #8 from CoreTrace/feat/analysis-manager
feat: analysis manager
2 parents 46d7ac0 + eb6829a commit 405cf66

17 files changed

Lines changed: 776 additions & 108 deletions

‎pyproject.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ testpaths = ["tests"]
3333
line-length = 100
3434
target-version = "py311"
3535

36+
[tool.ruff.lint.isort]
37+
known-first-party = ["coretrace_python"]
38+
3639
[tool.mypy]
3740
python_version = "3.11"
3841
strict = true
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
"""Analysis infrastructure: typed providers managed as a lazy, cached dependency DAG."""
2+
3+
from coretrace_python.analysis.manager import (
4+
AnalysisError,
5+
AnalysisManager,
6+
CyclicDependencyError,
7+
UndeclaredDependencyError,
8+
UnregisteredAnalysisError,
9+
)
10+
from coretrace_python.analysis.provider import (
11+
Analysis,
12+
AnalysisContext,
13+
AnyAnalysis,
14+
FunctionAnalysis,
15+
TransformationPass,
16+
)
17+
18+
__all__ = [
19+
"Analysis",
20+
"AnalysisContext",
21+
"AnalysisError",
22+
"AnalysisManager",
23+
"AnyAnalysis",
24+
"CyclicDependencyError",
25+
"FunctionAnalysis",
26+
"TransformationPass",
27+
"UndeclaredDependencyError",
28+
"UnregisteredAnalysisError",
29+
]
Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
"""The Analysis Manager: registry, dependency DAG, lazy evaluation, cache, invalidation."""
2+
3+
from __future__ import annotations
4+
5+
from typing import Any, overload
6+
7+
from coretrace_python.analysis.provider import (
8+
Analysis,
9+
AnyAnalysis,
10+
FunctionAnalysis,
11+
R,
12+
TransformationPass,
13+
)
14+
from coretrace_python.hir import nodes
15+
from coretrace_python.source import SourceSpan
16+
17+
18+
class AnalysisError(Exception):
19+
"""Misuse of the analysis registry or dependency declarations."""
20+
21+
22+
class UnregisteredAnalysisError(AnalysisError):
23+
pass
24+
25+
26+
class UndeclaredDependencyError(AnalysisError):
27+
pass
28+
29+
30+
class CyclicDependencyError(AnalysisError):
31+
pass
32+
33+
34+
_CacheKey = tuple[AnyAnalysis, SourceSpan | None]
35+
36+
37+
class AnalysisManager:
38+
"""Compute registered analyses lazily, once, and share their results."""
39+
40+
def __init__(self, module: nodes.Module) -> None:
41+
self._module = module
42+
self._registry: set[AnyAnalysis] = set()
43+
self._cache: dict[_CacheKey, Any] = {}
44+
self._computing: list[AnyAnalysis] = []
45+
46+
@property
47+
def module(self) -> nodes.Module:
48+
return self._module
49+
50+
# ------------------------------------------------------------------ registry
51+
52+
def register(self, *analyses: AnyAnalysis) -> None:
53+
for analysis in analyses:
54+
self._registry.add(analysis)
55+
self._check_acyclic(analysis)
56+
57+
def dependencies(self, analysis: AnyAnalysis) -> frozenset[AnyAnalysis]:
58+
"""Transitive closure of ``analysis.requires``."""
59+
60+
found: set[AnyAnalysis] = set()
61+
pending = list(analysis.requires)
62+
while pending:
63+
dependency = pending.pop()
64+
if dependency not in found:
65+
found.add(dependency)
66+
pending.extend(dependency.requires)
67+
return frozenset(found)
68+
69+
def _check_acyclic(self, root: AnyAnalysis) -> None:
70+
path: list[AnyAnalysis] = []
71+
72+
def visit(analysis: AnyAnalysis) -> None:
73+
if analysis in path:
74+
cycle = [*path[path.index(analysis) :], analysis]
75+
raise CyclicDependencyError(
76+
"dependency cycle: " + " -> ".join(a.name for a in cycle)
77+
)
78+
path.append(analysis)
79+
for dependency in analysis.requires:
80+
visit(dependency)
81+
path.pop()
82+
83+
visit(root)
84+
85+
# ------------------------------------------------------------------ evaluation
86+
87+
@overload
88+
def get(self, analysis: type[Analysis[R]], function: None = None) -> R: ...
89+
90+
@overload
91+
def get(self, analysis: type[FunctionAnalysis[R]], function: nodes.Function) -> R: ...
92+
93+
def get(self, analysis: AnyAnalysis, function: nodes.Function | None = None) -> Any:
94+
self._check_target(analysis, function)
95+
if analysis not in self._registry:
96+
raise UnregisteredAnalysisError(f"analysis {analysis.name!r} is not registered")
97+
if self._computing and analysis not in self._computing[-1].requires:
98+
current = self._computing[-1]
99+
raise UndeclaredDependencyError(
100+
f"{current.name} requests {analysis.name} without declaring it in requires"
101+
)
102+
103+
key = self._key(analysis, function)
104+
if key in self._cache:
105+
return self._cache[key]
106+
107+
self._computing.append(analysis)
108+
try:
109+
if function is None:
110+
assert issubclass(analysis, Analysis)
111+
result = analysis.compute(self)
112+
else:
113+
assert issubclass(analysis, FunctionAnalysis)
114+
result = analysis.compute(self, function)
115+
finally:
116+
self._computing.pop()
117+
self._cache[key] = result
118+
return result
119+
120+
def is_cached(self, analysis: AnyAnalysis, function: nodes.Function | None = None) -> bool:
121+
self._check_target(analysis, function)
122+
return self._key(analysis, function) in self._cache
123+
124+
# ------------------------------------------------------------------ invalidation
125+
126+
def run(self, transformation: type[TransformationPass]) -> None:
127+
"""Run a transformation, then drop every cached result it does not preserve."""
128+
129+
transformation.run(self)
130+
self._cache = {
131+
key: result for key, result in self._cache.items() if key[0] in transformation.preserves
132+
}
133+
134+
# ------------------------------------------------------------------ helpers
135+
136+
@staticmethod
137+
def _check_target(analysis: AnyAnalysis, function: nodes.Function | None) -> None:
138+
if issubclass(analysis, FunctionAnalysis) and function is None:
139+
raise TypeError(f"{analysis.name} is a function analysis and needs a function")
140+
if issubclass(analysis, Analysis) and function is not None:
141+
raise TypeError(f"{analysis.name} is a module analysis and takes no function")
142+
143+
@staticmethod
144+
def _key(analysis: AnyAnalysis, function: nodes.Function | None) -> _CacheKey:
145+
return (analysis, None if function is None else function.span)
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
"""Typed analysis providers and the context they compute in (architecture §8, §12).
2+
3+
An analysis is a class, not an instance: its ``name`` and ``version`` identify cached
4+
results, its ``requires`` declares the dependency DAG, and ``compute`` builds the
5+
result from an ``AnalysisContext``. Read-only analyses never modify shared IR; a
6+
``TransformationPass`` may, and must say what it preserves.
7+
"""
8+
9+
from __future__ import annotations
10+
11+
from abc import ABC, abstractmethod
12+
from typing import Any, ClassVar, Generic, Protocol, TypeVar, overload
13+
14+
from coretrace_python.hir import nodes
15+
16+
R = TypeVar("R")
17+
18+
19+
class Analysis(ABC, Generic[R]):
20+
"""A module-level analysis producing one immutable result per module."""
21+
22+
name: ClassVar[str]
23+
version: ClassVar[int] = 1
24+
requires: ClassVar[frozenset[AnyAnalysis]] = frozenset()
25+
26+
@classmethod
27+
@abstractmethod
28+
def compute(cls, ctx: AnalysisContext) -> R:
29+
raise NotImplementedError
30+
31+
32+
class FunctionAnalysis(ABC, Generic[R]):
33+
"""A function-level analysis producing one result per function, on demand."""
34+
35+
name: ClassVar[str]
36+
version: ClassVar[int] = 1
37+
requires: ClassVar[frozenset[AnyAnalysis]] = frozenset()
38+
39+
@classmethod
40+
@abstractmethod
41+
def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> R:
42+
raise NotImplementedError
43+
44+
45+
AnyAnalysis = type[Analysis[Any]] | type[FunctionAnalysis[Any]]
46+
47+
48+
class TransformationPass(ABC):
49+
"""A pass that may change shared state and therefore invalidates cached results.
50+
51+
Every cached analysis not listed in ``preserves`` is dropped after the pass runs.
52+
"""
53+
54+
name: ClassVar[str]
55+
preserves: ClassVar[frozenset[AnyAnalysis]] = frozenset()
56+
57+
@classmethod
58+
@abstractmethod
59+
def run(cls, ctx: AnalysisContext) -> None:
60+
raise NotImplementedError
61+
62+
63+
class AnalysisContext(Protocol):
64+
"""What an analysis sees while computing: the module and its declared dependencies."""
65+
66+
@property
67+
def module(self) -> nodes.Module: ...
68+
69+
@overload
70+
def get(self, analysis: type[Analysis[R]], function: None = None) -> R: ...
71+
72+
@overload
73+
def get(self, analysis: type[FunctionAnalysis[R]], function: nodes.Function) -> R: ...

‎src/coretrace_python/ir/lowering.py‎

Lines changed: 61 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,15 @@
33
from __future__ import annotations
44

55
from dataclasses import dataclass, field
6-
from typing import NoReturn
7-
6+
from typing import ClassVar, NoReturn
7+
8+
from coretrace_python.analysis import (
9+
Analysis,
10+
AnalysisContext,
11+
AnalysisManager,
12+
AnyAnalysis,
13+
FunctionAnalysis,
14+
)
815
from coretrace_python.hir import nodes
916
from coretrace_python.ir.model import (
1017
BasicBlock,
@@ -25,15 +32,15 @@
2532
Value,
2633
ValueInstruction,
2734
)
28-
from coretrace_python.semantic.imports import analyze_imports
35+
from coretrace_python.semantic import SEMANTIC_ANALYSES
2936
from coretrace_python.semantic.scopes import (
3037
Resolution,
3138
ResolutionKind,
3239
Scope,
3340
ScopeAnalysis,
34-
analyze_scopes,
41+
ScopeTable,
3542
)
36-
from coretrace_python.semantic.symbols import SymbolAnalysis, SymbolId, analyze_symbols
43+
from coretrace_python.semantic.symbols import SymbolAnalysis, SymbolId, SymbolTable
3744

3845

3946
class LoweringError(Exception):
@@ -42,8 +49,8 @@ class LoweringError(Exception):
4249

4350
@dataclass
4451
class _FunctionLowerer:
45-
symbols: SymbolAnalysis
46-
scopes: ScopeAnalysis
52+
symbols: SymbolTable
53+
scopes: ScopeTable
4754
scope: Scope
4855
next_value_id: int = 0
4956
assigned: set[str] = field(default_factory=set)
@@ -151,26 +158,51 @@ def function(self, node: nodes.Function) -> FunctionIR:
151158
return FunctionIR(node.name, parameters, (self.block,), node.span)
152159

153160

161+
class PyIRAnalysis(FunctionAnalysis[FunctionIR]):
162+
"""Lower one function to PyIR on demand."""
163+
164+
name: ClassVar[str] = "ir.pyir"
165+
requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({ScopeAnalysis, SymbolAnalysis})
166+
167+
@classmethod
168+
def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> FunctionIR:
169+
scopes = ctx.get(ScopeAnalysis)
170+
lowerer = _FunctionLowerer(ctx.get(SymbolAnalysis), scopes, scopes.scope_for(function))
171+
return lowerer.function(function)
172+
173+
174+
class ModuleIRAnalysis(Analysis[ModuleIR]):
175+
"""Assemble the PyIR of every top-level function of the module."""
176+
177+
name: ClassVar[str] = "ir.module"
178+
requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({PyIRAnalysis})
179+
180+
@classmethod
181+
def compute(cls, ctx: AnalysisContext) -> ModuleIR:
182+
functions: list[FunctionIR] = []
183+
for statement in ctx.module.body:
184+
if isinstance(statement, nodes.Function):
185+
functions.append(ctx.get(PyIRAnalysis, statement))
186+
elif isinstance(statement, (nodes.Import, nodes.ImportFrom)):
187+
continue
188+
elif (
189+
isinstance(statement, nodes.ExpressionStatement)
190+
and isinstance(statement.expression, nodes.Constant)
191+
and isinstance(statement.expression.value, str)
192+
):
193+
# Permit module docstrings.
194+
continue
195+
else:
196+
raise LoweringError(
197+
f"{statement.span.display()}: "
198+
f"unsupported module syntax: {type(statement).__name__}"
199+
)
200+
return ModuleIR(tuple(functions))
201+
202+
154203
def lower_module(module: nodes.Module) -> ModuleIR:
155-
scopes = analyze_scopes(module)
156-
symbols = analyze_symbols(scopes, analyze_imports(module, scopes))
157-
functions: list[FunctionIR] = []
158-
for statement in module.body:
159-
if isinstance(statement, nodes.Function):
160-
lowerer = _FunctionLowerer(symbols, scopes, scopes.scope_for(statement))
161-
functions.append(lowerer.function(statement))
162-
elif isinstance(statement, (nodes.Import, nodes.ImportFrom)):
163-
continue
164-
elif (
165-
isinstance(statement, nodes.ExpressionStatement)
166-
and isinstance(statement.expression, nodes.Constant)
167-
and isinstance(statement.expression.value, str)
168-
):
169-
# Permit module docstrings.
170-
continue
171-
else:
172-
raise LoweringError(
173-
f"{statement.span.display()}: "
174-
f"unsupported module syntax: {type(statement).__name__}"
175-
)
176-
return ModuleIR(tuple(functions))
204+
"""Lower a whole module through a fresh analysis manager."""
205+
206+
manager = AnalysisManager(module)
207+
manager.register(*SEMANTIC_ANALYSES, PyIRAnalysis, ModuleIRAnalysis)
208+
return manager.get(ModuleIRAnalysis)
Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
"""Semantic analyses computed from PyHIR: imports, symbols and lexical scopes."""
1+
"""Semantic analyses computed from PyHIR: scopes, imports and symbols."""
2+
3+
from coretrace_python.semantic.imports import ImportAnalysis
4+
from coretrace_python.semantic.scopes import ScopeAnalysis
5+
from coretrace_python.semantic.symbols import SymbolAnalysis
6+
7+
SEMANTIC_ANALYSES = (ScopeAnalysis, ImportAnalysis, SymbolAnalysis)
8+
9+
__all__ = ["SEMANTIC_ANALYSES", "ImportAnalysis", "ScopeAnalysis", "SymbolAnalysis"]

0 commit comments

Comments
 (0)