Skip to content

Commit 2a68b5b

Browse files
authored
Merge pull request #49 from CoreTrace/feat/pyir-leftovers
feat: PyIR imports and schema version
2 parents c3bdfc4 + cb11b00 commit 2a68b5b

7 files changed

Lines changed: 183 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,8 @@ assignment, list, tuple and dict literals, `and`/`or`, chained comparisons, keyw
139139
arguments, `with`, `assert`, `try`/`except`/`else`/`finally`, `await`, `yield`,
140140
`if`/`elif`/`else`, `while`, `for`, `break`, `continue` and `raise`. Blocks inside a `try`
141141
body carry exception edges to the handlers; `finally` is modelled on the normal path only. Methods of module-level classes are analysed like functions; other module-level
142-
code is skipped. A function using syntax outside this subset is reported by `--check` as
142+
code is skipped. An import inside a function is shown where it runs, as an `import`
143+
instruction naming the module, the bound name and the canonical symbol. A function using syntax outside this subset is reported by `--check` as
143144
an `unsupported-syntax` note and the other functions are still analysed. Each function is
144145
emitted as its control-flow graph: one block per basic block, ending in an explicit
145146
terminator (`branch`, `jump`, `return`, `raise`, `for_next`). Add `--ssa` to print the

‎src/coretrace_python/engine.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@
6666
discover_sources,
6767
project_symbol,
6868
)
69+
from coretrace_python.ir import PYIR_SCHEMA_VERSION
6970
from coretrace_python.ir.defuse import DefUseAnalysis
7071
from coretrace_python.ir.lowering import (
7172
LoweringError,
@@ -501,6 +502,7 @@ def _configuration_key(
501502
return fingerprint(
502503
__version__,
503504
str(HIR_SCHEMA_VERSION),
505+
str(PYIR_SCHEMA_VERSION),
504506
str(FINDING_SCHEMA_VERSION),
505507
str(PLUGIN_API_VERSION),
506508
*(
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
"""Python-aware intermediate representation."""
22

3-
from coretrace_python.ir.model import BasicBlock, FunctionIR, ModuleIR, Value
3+
from coretrace_python.ir.model import PYIR_SCHEMA_VERSION, BasicBlock, FunctionIR, ModuleIR, Value
44

5-
__all__ = ["BasicBlock", "FunctionIR", "ModuleIR", "Value"]
5+
__all__ = ["PYIR_SCHEMA_VERSION", "BasicBlock", "FunctionIR", "ModuleIR", "Value"]

‎src/coretrace_python/ir/lowering.py‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
GetItem,
3838
GetIter,
3939
Global,
40+
Import,
4041
Instruction,
4142
Jump,
4243
LoadLocal,
@@ -230,8 +231,20 @@ def statement(self, node: nodes.Statement) -> None:
230231
if isinstance(node, nodes.ExpressionStatement):
231232
self.expression(node.expression)
232233
return
233-
if isinstance(node, nodes.Pass | nodes.Global | nodes.Import | nodes.ImportFrom):
234-
# Declarations and imports are already applied by the semantic analyses.
234+
if isinstance(node, nodes.Import | nodes.ImportFrom):
235+
# The binding is already applied by the semantic analyses; the instruction
236+
# records that the import runs here (§39 rule 3).
237+
module = "." * node.level + (node.module or "") if isinstance(node, nodes.ImportFrom) else ""
238+
for alias in node.names:
239+
bound = alias.as_name or alias.name.partition(".")[0]
240+
symbol = self.symbols.resolve(self.scope.id, bound)
241+
if symbol is None:
242+
self.fail(node, f"unresolved import of {bound!r}")
243+
written = alias.name if isinstance(node, nodes.Import) else module
244+
self.emit_effect(Import(None, alias.span, written, symbol, bound))
245+
return
246+
if isinstance(node, nodes.Pass | nodes.Global):
247+
# Declarations are already applied by the semantic analyses.
235248
return
236249
self.fail(node)
237250

‎src/coretrace_python/ir/model.py‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@
88
from coretrace_python.semantic.symbols import SymbolId
99
from coretrace_python.source import SourceSpan
1010

11+
# Bumped whenever the instruction set or its meaning changes; part of the cache key.
12+
PYIR_SCHEMA_VERSION = 1
13+
1114

1215
@dataclass(frozen=True)
1316
class Value:
@@ -266,6 +269,18 @@ class Assert(Operands):
266269
message: Value | None
267270

268271

272+
@dataclass(frozen=True)
273+
class Import(Operands):
274+
"""An import executed where it stands: ``module`` as written (relative dots
275+
included), the canonical ``symbol_id`` bound and the local ``name`` it binds."""
276+
277+
result: None
278+
location: SourceSpan
279+
module: str
280+
symbol_id: SymbolId
281+
name: str
282+
283+
269284
ValueInstruction: TypeAlias = (
270285
Constant
271286
| Global
@@ -289,7 +304,7 @@ class Assert(Operands):
289304
| Await
290305
| Yield
291306
)
292-
EffectInstruction: TypeAlias = StoreLocal | SetAttr | SetItem | WithExit | Assert
307+
EffectInstruction: TypeAlias = StoreLocal | SetAttr | SetItem | WithExit | Assert | Import
293308
Instruction: TypeAlias = ValueInstruction | EffectInstruction
294309

295310

‎src/coretrace_python/ir/printer.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
GetItem,
1919
GetIter,
2020
Global,
21+
Import,
2122
Instruction,
2223
Jump,
2324
LoadLocal,
@@ -99,6 +100,8 @@ def _instruction(instruction: Instruction) -> str:
99100
f"set_item {_value(instruction.object)}, {_value(instruction.key)}, "
100101
f"{_value(instruction.value)}"
101102
)
103+
if isinstance(instruction, Import):
104+
return f'import "{instruction.module}" as "{instruction.name}" @{instruction.symbol_id}'
102105
if isinstance(instruction, Assert):
103106
message = "" if instruction.message is None else f", {_value(instruction.message)}"
104107
return f"assert {_value(instruction.test)}{message}"

‎tests/test_pyir_imports.py‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
"""Acceptance tests for the last PyIR leftovers (``docs/architecture.md`` §6, §39 rule 3;
2+
roadmap issue #13).
3+
4+
An import inside a function runs where it stands, so PyIR shows it: an ``Import``
5+
effect instruction names the module as written, the canonical symbol bound and the local
6+
name. Uses of that name keep resolving to ``Symbol`` values, as before. Module-level
7+
imports are applied by the semantic analyses and lower to nothing, since ``ModuleIR``
8+
holds functions only. ``PYIR_SCHEMA_VERSION`` versions the instruction set and is part of
9+
the persistent cache key.
10+
11+
Expected to remain red until ``ir.model.Import`` and ``PYIR_SCHEMA_VERSION`` exist.
12+
"""
13+
14+
from __future__ import annotations
15+
16+
from pathlib import Path
17+
18+
import pytest
19+
20+
from coretrace_python import engine
21+
from coretrace_python.cli import main
22+
from coretrace_python.frontend import build_hir
23+
from coretrace_python.ir.lowering import lower_module
24+
from coretrace_python.ir.model import FunctionIR, Instruction, Symbol
25+
from coretrace_python.source import SourceManager
26+
27+
try:
28+
from coretrace_python.ir import PYIR_SCHEMA_VERSION
29+
from coretrace_python.ir.model import Import
30+
except ImportError as error: # pragma: no cover - red until the instruction lands
31+
MISSING = error
32+
else:
33+
MISSING = None
34+
35+
36+
@pytest.fixture(autouse=True)
37+
def require_imports() -> None:
38+
if MISSING is not None:
39+
pytest.fail(f"PyIR imports are not implemented yet: {MISSING}")
40+
41+
42+
REPO = Path(__file__).resolve().parent.parent
43+
PLUGINS = REPO / "plugins"
44+
45+
46+
def lower(text: str, *, ssa: bool = False, name: str = "ir.py") -> FunctionIR:
47+
module = lower_module(build_hir(SourceManager().add_source(name, text)), ssa=ssa)
48+
return module.functions[0]
49+
50+
51+
def instructions(function: FunctionIR, kind: type[Instruction]) -> list[Instruction]:
52+
return [i for block in function.blocks for i in block.instructions if isinstance(i, kind)]
53+
54+
55+
# --------------------------------------------------------------------------- instruction
56+
57+
58+
def test_local_imports_lower_to_import_instructions() -> None:
59+
function = lower("def f():\n import os\n import os.path as p\n return os.system, p.join\n")
60+
61+
imports = instructions(function, Import)
62+
63+
assert [(i.module, str(i.symbol_id), i.name) for i in imports] == [
64+
("os", "python.os", "os"),
65+
("os.path", "python.os.path", "p"),
66+
]
67+
assert all(i.result is None and i.operands() == () for i in imports)
68+
assert imports[0].location.start_line == 2
69+
assert [str(s.symbol_id) for s in instructions(function, Symbol)] == ["python.os.system", "python.os.path.join"]
70+
71+
72+
def test_from_imports_and_relative_imports_are_faithful(tmp_path: Path) -> None:
73+
function = lower("def f():\n from subprocess import run as launch\n return launch\n")
74+
(launch,) = instructions(function, Import)
75+
assert (launch.module, str(launch.symbol_id), launch.name) == ("subprocess", "python.subprocess.run", "launch")
76+
77+
package = tmp_path / "pkg"
78+
package.mkdir()
79+
(package / "__init__.py").write_text("", encoding="utf-8")
80+
(package / "helpers.py").write_text("def go():\n pass\n", encoding="utf-8")
81+
(package / "main.py").write_text("def f():\n from . import helpers\n from .helpers import go\n return go\n", encoding="utf-8")
82+
module = lower_module(build_hir(SourceManager().load_file(package / "main.py")))
83+
relative = instructions(module.functions[0], Import)
84+
85+
assert [(i.module, str(i.symbol_id), i.name) for i in relative] == [
86+
(".", "python.pkg.helpers", "helpers"),
87+
(".helpers", "python.pkg.helpers.go", "go"),
88+
]
89+
90+
91+
def test_imports_come_before_the_uses_and_survive_ssa() -> None:
92+
function = lower("def f(x):\n if x:\n import os\n os.system(x)\n", ssa=True)
93+
94+
(block,) = [b for b in function.blocks if instructions_of(b, Import)]
95+
kinds = [type(i).__name__ for i in block.instructions]
96+
97+
assert kinds.index("Import") < kinds.index("Symbol")
98+
99+
100+
def instructions_of(block, kind): # type: ignore[no-untyped-def]
101+
return [i for i in block.instructions if isinstance(i, kind)]
102+
103+
104+
def test_module_level_imports_lower_to_nothing() -> None:
105+
function = lower("import os\n\ndef f():\n return os.system\n")
106+
assert instructions(function, Import) == []
107+
108+
109+
def test_emit_ir_prints_imports(tmp_path: Path, capsys) -> None: # type: ignore[no-untyped-def]
110+
source = tmp_path / "late.py"
111+
source.write_text("def f():\n import json as j\n return j\n", encoding="utf-8")
112+
113+
assert main(["--emit-ir", str(source)]) == 0
114+
assert capsys.readouterr().out == (
115+
"func @f() {\n"
116+
"entry:\n"
117+
' import "json" as "j" @python.json\n'
118+
" %0 = symbol @python.json\n"
119+
" return %0\n"
120+
"}\n"
121+
)
122+
123+
124+
def test_analyses_see_through_local_imports() -> None:
125+
findings = engine.check(
126+
SourceManager().add_source("late.py", "def f():\n import os\n os.system(input())\n"), [PLUGINS]
127+
)
128+
assert [(f.rule_id, f.span.start_line) for f in findings] == [("command-injection", 3)]
129+
130+
131+
# --------------------------------------------------------------------------- schema version
132+
133+
134+
def test_pyir_schema_version_is_exported_and_keys_the_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
135+
from coretrace_python.ir import model
136+
137+
assert PYIR_SCHEMA_VERSION == model.PYIR_SCHEMA_VERSION >= 1
138+
(tmp_path / "app.py").write_text("x = 1\n", encoding="utf-8")
139+
before = engine.analyze_project(tmp_path).keys["app"]
140+
141+
monkeypatch.setattr(engine, "PYIR_SCHEMA_VERSION", PYIR_SCHEMA_VERSION + 1)
142+
143+
assert engine.analyze_project(tmp_path).keys["app"] != before

0 commit comments

Comments
 (0)