interpretthis 0.1.0

Sandboxed Python AST interpreter for untrusted and LLM-generated code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

// Copyright 2026 Thomas Santerre and Moderately AI Inc.
//
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Build script: discover `tests/integration/parity_corpus/**/*.py` snippets at
//! compile time and emit one `#[test]` per file into a generated Rust source
//! that `tests/integration/parity_corpus_runner.rs` includes.
//!
//! Compile-time discovery (vs. runtime walking + `libtest-mimic`) is chosen
//! because it lets each `.py` snippet appear as a distinct
//! `parity::<topic>::<name>` entry in `cargo nextest run` output — the
//! standard `#[test]` mechanism — without pulling a new dependency into the
//! crate. The trade-off is that adding or removing a snippet triggers a
//! rebuild of the test binary; the `cargo:rerun-if-changed` directives below
//! make that detection accurate so no manual touch is needed.

use std::{
    collections::BTreeMap,
    env,
    error::Error,
    fmt::Write as _,
    fs,
    path::{Path, PathBuf},
};

type BuildResult<T = ()> = Result<T, Box<dyn Error>>;

fn main() -> BuildResult {
    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR")?);
    let corpus_root = manifest_dir.join("tests/integration/parity_corpus");

    // Re-run when the corpus tree changes. We watch the root explicitly so
    // newly-added topic directories trigger regeneration; the `.py` watchers
    // are added per-file inside the walk.
    println!("cargo:rerun-if-changed=tests/integration/parity_corpus");
    println!("cargo:rerun-if-changed=build.rs");

    let mut tree = TopicTree::default();
    if corpus_root.is_dir() {
        walk(&corpus_root, &corpus_root, &mut tree)?;
    }

    let out_dir = PathBuf::from(env::var("OUT_DIR")?);
    let generated = out_dir.join("parity_corpus_generated.rs");
    let mut output = String::new();
    output.push_str(GENERATED_HEADER);
    tree.emit(&mut output, 0)?;
    fs::write(&generated, output)?;
    Ok(())
}

const GENERATED_HEADER: &str = "// AUTO-GENERATED by build.rs. Do not edit by hand.\n//\n// Each `#[test]` here corresponds to one `.py` snippet under\n// `tests/integration/parity_corpus/`. The snippet's bytes are embedded via\n// `include_str!` so the test binary is self-contained.\n\n";

/// Nested directory tree of corpus topics, each leaf carrying the absolute
/// paths of `.py` files it contains.
#[derive(Default)]
struct TopicTree {
    children: BTreeMap<String, Self>,
    snippets: BTreeMap<String, PathBuf>,
}

impl TopicTree {
    fn emit(&self, out: &mut String, depth: usize) -> BuildResult {
        let indent = "    ".repeat(depth);
        for (snippet_name, snippet_path) in &self.snippets {
            let path_literal = snippet_path.to_string_lossy().replace('\\', "/");
            let fn_ident = rustify_ident(snippet_name)?;
            writeln!(out, "{indent}#[test]")?;
            writeln!(out, "{indent}fn {fn_ident}() {{")?;
            writeln!(out, "{indent}    let code = include_str!(\"{path_literal}\");")?;
            writeln!(
                out,
                "{indent}    crate::parity_corpus_runner::run_parity_test(module_path!(), \"{snippet_name}\", code);"
            )?;
            writeln!(out, "{indent}}}")?;
            writeln!(out)?;
        }
        for (child_name, child) in &self.children {
            let module_ident = rustify_ident(child_name)?;
            writeln!(out, "{indent}pub mod {module_ident} {{")?;
            child.emit(out, depth + 1)?;
            writeln!(out, "{indent}}}")?;
            writeln!(out)?;
        }
        Ok(())
    }
}

fn walk(root: &Path, current: &Path, tree: &mut TopicTree) -> BuildResult {
    let read = fs::read_dir(current)?;
    let mut entries: Vec<PathBuf> = read.filter_map(Result::ok).map(|entry| entry.path()).collect();
    entries.sort();
    for path in entries {
        if path.is_dir() {
            let name = path
                .file_name()
                .and_then(|name| name.to_str())
                .ok_or_else(|| format!("non-utf8 directory name at {}", path.display()))?;
            check_ident(name, "topic directory")?;
            let child = tree.children.entry(name.to_string()).or_default();
            walk(root, &path, child)?;
            continue;
        }
        let Some(ext) = path.extension().and_then(|ext| ext.to_str()) else {
            continue;
        };
        if ext != "py" {
            continue;
        }
        let rel = path
            .strip_prefix(root)
            .map_err(|err| format!("path {} not under root: {err}", path.display()))?;
        println!(
            "cargo:rerun-if-changed=tests/integration/parity_corpus/{}",
            rel.to_string_lossy().replace('\\', "/")
        );
        let stem = path
            .file_stem()
            .and_then(|stem| stem.to_str())
            .ok_or_else(|| format!("non-utf8 file stem at {}", path.display()))?;
        check_ident(stem, "snippet file")?;
        let prior = tree.snippets.insert(stem.to_string(), path.clone());
        if prior.is_some() {
            return Err(format!(
                "duplicate snippet name `{stem}` in {}; rename one of the files",
                current.display()
            )
            .into());
        }
    }
    Ok(())
}

/// Reject names that wouldn't generate valid Rust identifiers. Topic
/// directories and snippet file stems share the same snake_case-and-digits
/// constraint.
fn check_ident(name: &str, kind: &str) -> BuildResult {
    let valid_chars =
        name.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_');
    if !valid_chars {
        return Err(format!("{kind} `{name}` is not snake_case; rename it").into());
    }
    if name.starts_with(|c: char| c.is_ascii_digit()) {
        return Err(format!("{kind} `{name}` starts with a digit; Rust identifiers cannot").into());
    }
    Ok(())
}

/// Wrap a snake_case identifier with `r#` when it collides with a Rust
/// keyword (`match`, `type`, `for`, `if`, …). The corpus directory layout
/// mirrors Python concepts and several of those concepts share names with
/// Rust keywords; raw identifiers let those names round-trip cleanly into
/// generated module / fn declarations.
fn rustify_ident(name: &str) -> BuildResult<String> {
    // Rust 2024 reserved keywords. The list is the strict / reserved set
    // pulled from the Rust reference; raw identifiers cannot wrap `self`,
    // `Self`, `super`, `crate`, or `_`, so those four are rejected here.
    const KEYWORDS: &[&str] = &[
        "as", "async", "await", "break", "const", "continue", "do", "dyn", "else", "enum",
        "extern", "false", "fn", "for", "gen", "if", "impl", "in", "let", "loop", "match", "mod",
        "move", "mut", "pub", "ref", "return", "static", "struct", "trait", "true", "try", "type",
        "unsafe", "use", "where", "while", "yield", "abstract", "become", "box", "final", "macro",
        "override", "priv", "typeof", "unsized", "virtual",
    ];
    const BANNED: &[&str] = &["self", "Self", "super", "crate", "_"];
    if BANNED.contains(&name) {
        return Err(format!(
            "corpus path component `{name}` collides with a Rust identifier that cannot be raw-escaped; rename it",
        )
        .into());
    }
    if KEYWORDS.contains(&name) { Ok(format!("r#{name}")) } else { Ok(name.to_string()) }
}