milo-guards-code 0.1.3

Reads Python and JavaScript code and says what it is certain to do to files and what it runs, or that it does not understand it.
Documentation

milo-guards-code

Reads Python and JavaScript code and says what it is certain to do to files and what it runs, or that it does not understand it. Part of milo-guards; a reader, not a guard.

A shell line can hand an interpreter code (python3 -c, node -e), and an agent can write a script or run a snippet directly. What matters to a guard is which files the code deletes, writes, reads and moves, and what it runs. This crate reads Python and JavaScript (Node, Bun and Deno) with their own tree-sitter grammars and answers two questions of a piece of code:

  • What is it certain to do? read gives the Acts the code makes, in order: a delete, a write, a read, a move, a program started, an environment changed, each with the paths it names. What the reader cannot follow comes out as Act::Unread, never left out.
  • Does it understand the code? understand holds the code to a strict allow-list: a few plain statements whose every call, name and import is on a short list that only computes. Anything else is Understanding::NotUnderstood, and a caller must not take "no acts" for "does nothing" for such code.

The reader judges nothing. Whether a delete of a path is risky is the caller's: the shell guard of milo-guards turns an act into what it already judges (a delete is rm -rf PATH, a command line a script a shell reads).

Install

Through the front door, where it is the code feature (on by default) and what the shell guard reads inline code with:

[dependencies]
milo-guards = "0.1"

Or on its own:

[dependencies]
milo-guards-code = "0.1"

If your program also links tree-sitter, it has to be on the 0.26 runtime: tree-sitter allows one version per lockfile.

Example

use milo_guards_code::{read, understand, Act, Arg, Language, Understanding};

// A snippet that computes is understood, and does nothing to a file.
let code = "print(1 + 1)";
assert!(read(Language::Python, code).acts.is_empty());
assert_eq!(
    understand(Language::Python, code),
    Understanding::Understood { imports: true },
);

// A delete is an act with the path it names, kept whatever the code is.
let code = "import shutil\nshutil.rmtree('/home/me')";
let reading = read(Language::Python, code);
assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Known(path))] if path == "/home/me"));
assert_eq!(understand(Language::Python, code), Understanding::NotUnderstood);

// A name only known when the code runs is an argument it does not know.
let reading = read(Language::JavaScript, "require('fs').rmSync(process.argv[1])");
assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Unknown(_))]));

Contract

Like every milo-guards crate: no I/O and no environment reads, deterministic (the same input gives the same answer on every machine), no policy (it reports, and what to do with a finding is the caller's), what cannot be read is risky, and nothing it is given makes it panic. The rules are on the repository's guidelines.

License

MIT or Apache-2.0, at your option (LICENSE-MIT, LICENSE-APACHE). Part of milo-guards; the API is on docs.rs.