use std::collections::BTreeMap;
use std::fs;
use std::path::Path;
use proc_macro2::{TokenStream, TokenTree};
pub use syn;
pub struct ModuleFile {
pub name: String,
pub source: String,
pub ast: syn::File,
}
pub struct ModuleTree {
pub files: Vec<ModuleFile>,
}
pub struct ModuleAudit {
pub declared: Vec<String>,
pub violations: Vec<String>,
}
fn module_attribute_violation(attribute: &syn::Attribute) -> Option<String> {
let path = attribute.path();
if path.is_ident("cfg") || path.is_ident("doc") || path.is_ident("allow") {
return None;
}
Some(format!(
"module declaration carries a refused attribute: {}",
path.segments
.iter()
.map(|segment| segment.ident.to_string())
.collect::<Vec<_>>()
.join("::")
))
}
fn audit_items(items: &[syn::Item], root: bool, audit: &mut ModuleAudit) {
for item in items {
match item {
syn::Item::Mod(module) => {
for attribute in &module.attrs {
if let Some(violation) = module_attribute_violation(attribute) {
audit
.violations
.push(format!("mod {}: {violation}", module.ident));
}
}
match &module.content {
None if root => audit.declared.push(module.ident.to_string()),
None => audit.violations.push(format!(
"mod {}: file submodule below the root widens the tree",
module.ident
)),
Some((_, inner)) => audit_items(inner, false, audit),
}
}
syn::Item::Macro(invocation) => audit.violations.push(format!(
"item-position macro invocation is refused: {}",
invocation
.mac
.path
.segments
.iter()
.map(|segment| segment.ident.to_string())
.collect::<Vec<_>>()
.join("::")
)),
syn::Item::Impl(implementation) => {
for member in &implementation.items {
if matches!(member, syn::ImplItem::Macro(_)) {
audit
.violations
.push("impl-position macro invocation is refused".to_string());
}
}
}
syn::Item::Trait(definition) => {
for member in &definition.items {
if matches!(member, syn::TraitItem::Macro(_)) {
audit
.violations
.push("trait-position macro invocation is refused".to_string());
}
}
}
_ => {}
}
}
}
#[must_use]
pub fn audit_module_items(ast: &syn::File, root: bool) -> ModuleAudit {
let mut audit = ModuleAudit {
declared: Vec::new(),
violations: Vec::new(),
};
audit_items(&ast.items, root, &mut audit);
audit
}
fn refuse_symlink(path: &Path, violations: &mut Vec<String>) -> bool {
match fs::symlink_metadata(path) {
Ok(metadata) if metadata.file_type().is_symlink() => {
violations.push(format!("{}: symlink escapes the tree", path.display()));
false
}
Ok(_) => true,
Err(error) => {
violations.push(format!("{}: {error}", path.display()));
false
}
}
}
fn load_file(dir: &Path, name: &str, violations: &mut Vec<String>) -> Option<ModuleFile> {
let path = dir.join(name);
if !refuse_symlink(&path, violations) {
return None;
}
let source = match fs::read_to_string(&path) {
Ok(source) => source,
Err(error) => {
violations.push(format!("{name}: read failed: {error}"));
return None;
}
};
match syn::parse_file(&source) {
Ok(ast) => Some(ModuleFile {
name: name.to_string(),
source,
ast,
}),
Err(error) => {
violations.push(format!("{name}: parse failed: {error}"));
None
}
}
}
pub fn load_module_tree(dir: &Path) -> Result<ModuleTree, Vec<String>> {
let mut violations = Vec::new();
let mut files = Vec::new();
let mut declared = Vec::new();
if !refuse_symlink(dir, &mut violations) {
return Err(violations);
}
if let Some(root) = load_file(dir, "mod.rs", &mut violations) {
let audit = audit_module_items(&root.ast, true);
declared = audit.declared;
violations.extend(audit.violations.into_iter().map(|v| format!("mod.rs: {v}")));
files.push(root);
}
for module in &declared {
let name = format!("{module}.rs");
if let Some(file) = load_file(dir, &name, &mut violations) {
let audit = audit_module_items(&file.ast, false);
violations.extend(audit.violations.into_iter().map(|v| format!("{name}: {v}")));
files.push(file);
}
}
match fs::read_dir(dir) {
Ok(entries) => {
for entry in entries {
let entry = match entry {
Ok(entry) => entry,
Err(error) => {
violations.push(format!("module directory entry: {error}"));
continue;
}
};
let name = entry.file_name().to_string_lossy().into_owned();
if !refuse_symlink(&entry.path(), &mut violations) {
continue;
}
if entry.path().is_dir() {
violations.push(format!("{name}/: subdirectory widens the tree"));
} else if !files.iter().any(|file| file.name == name) {
violations.push(format!("{name}: undeclared file in the module directory"));
}
}
}
Err(error) => violations.push(format!("module directory: {error}")),
}
if violations.is_empty() {
Ok(ModuleTree { files })
} else {
Err(violations)
}
}
pub fn file_module_binding(parent: &syn::File, name: &str) -> Result<(), Vec<String>> {
let mut violations = Vec::new();
let mut bindings = 0usize;
for item in &parent.items {
let syn::Item::Mod(module) = item else {
continue;
};
if module.ident != name {
continue;
}
bindings += 1;
for attribute in &module.attrs {
if let Some(violation) = module_attribute_violation(attribute) {
violations.push(format!("mod {name}: {violation}"));
}
}
if module.content.is_some() {
violations.push(format!(
"mod {name}: inline body bypasses the audited directory"
));
}
}
if bindings != 1 {
violations.push(format!(
"mod {name}: expected exactly one declaration, found {bindings}"
));
}
if violations.is_empty() {
Ok(())
} else {
Err(violations)
}
}
pub fn struct_fields<'ast>(ast: &'ast syn::File, name: &str) -> Result<&'ast syn::Fields, String> {
fn find<'ast>(items: &'ast [syn::Item], name: &str, found: &mut Vec<&'ast syn::Fields>) {
for item in items {
match item {
syn::Item::Struct(declaration) if declaration.ident == name => {
found.push(&declaration.fields);
}
syn::Item::Mod(module) => {
if let Some((_, inner)) = &module.content {
find(inner, name, found);
}
}
_ => {}
}
}
}
let mut found = Vec::new();
find(&ast.items, name, &mut found);
match found.as_slice() {
[fields] => Ok(fields),
[] => Err(format!("struct {name} is not declared")),
_ => Err(format!("struct {name} is declared more than once")),
}
}
pub struct MacroSurface {
pub invocations: Vec<(String, usize)>,
pub attributes: Vec<(String, usize)>,
pub derives: Vec<(String, usize)>,
}
fn spelled(ident: &proc_macro2::Ident) -> String {
let raw = ident.to_string();
raw.strip_prefix("r#")
.map_or_else(|| raw.clone(), ToString::to_string)
}
fn read_path(trees: &[TokenTree], start: usize) -> Option<(String, usize, usize)> {
let Some(TokenTree::Ident(first)) = trees.get(start) else {
return None;
};
let mut segments = vec![spelled(first)];
let line = first.span().start().line;
let mut index = start + 1;
while let (
Some(TokenTree::Punct(left)),
Some(TokenTree::Punct(right)),
Some(TokenTree::Ident(next)),
) = (trees.get(index), trees.get(index + 1), trees.get(index + 2))
{
if left.as_char() == ':'
&& right.as_char() == ':'
&& left.spacing() == proc_macro2::Spacing::Joint
{
segments.push(spelled(next));
index += 3;
} else {
break;
}
}
Some((segments.join("::"), line, index))
}
fn record_attribute(group: &proc_macro2::Group, surface: &mut MacroSurface) {
let trees: Vec<TokenTree> = group.stream().into_iter().collect();
let Some((name, line, next)) = read_path(&trees, 0) else {
return;
};
surface.attributes.push((name.clone(), line));
if name == "derive"
&& let Some(TokenTree::Group(traits)) = trees.get(next)
{
let inner: Vec<TokenTree> = traits.stream().into_iter().collect();
let mut cursor = 0;
while cursor < inner.len() {
if let Some((path, path_line, after)) = read_path(&inner, cursor) {
surface.derives.push((path, path_line));
cursor = after;
} else {
cursor += 1;
}
}
}
scan_macro_surface(&trees, surface);
}
fn scan_macro_surface(trees: &[TokenTree], surface: &mut MacroSurface) {
let mut index = 0;
while index < trees.len() {
match &trees[index] {
TokenTree::Punct(punct) if punct.as_char() == '#' => {
let mut next = index + 1;
if let Some(TokenTree::Punct(bang)) = trees.get(next)
&& bang.as_char() == '!'
{
next += 1;
}
if let Some(TokenTree::Group(group)) = trees.get(next)
&& group.delimiter() == proc_macro2::Delimiter::Bracket
{
record_attribute(group, surface);
index = next + 1;
continue;
}
index += 1;
}
TokenTree::Ident(_) => {
let (path, line, next) =
read_path(trees, index).expect("read_path accepts an identifier");
if let (Some(TokenTree::Punct(bang)), Some(TokenTree::Group(_))) =
(trees.get(next), trees.get(next + 1))
&& bang.as_char() == '!'
{
surface.invocations.push((path, line));
}
index = next;
}
TokenTree::Group(group) => {
let inner: Vec<TokenTree> = group.stream().into_iter().collect();
scan_macro_surface(&inner, surface);
index += 1;
}
TokenTree::Punct(_) | TokenTree::Literal(_) => index += 1,
}
}
}
#[must_use]
pub fn use_bindings(ast: &syn::File) -> Vec<(String, String, usize)> {
use syn::spanned::Spanned as _;
fn walk_tree(
tree: &syn::UseTree,
prefix: &mut Vec<String>,
bindings: &mut Vec<(String, String, usize)>,
) {
match tree {
syn::UseTree::Path(path) => {
prefix.push(spelled(&path.ident));
walk_tree(&path.tree, prefix, bindings);
let _ = prefix.pop();
}
syn::UseTree::Name(name) => {
let mut full = prefix.clone();
full.push(spelled(&name.ident));
bindings.push((
spelled(&name.ident),
full.join("::"),
name.ident.span().start().line,
));
}
syn::UseTree::Rename(rename) => {
let mut full = prefix.clone();
full.push(spelled(&rename.ident));
bindings.push((
spelled(&rename.rename),
full.join("::"),
rename.rename.span().start().line,
));
}
syn::UseTree::Glob(glob) => {
let mut full = prefix.clone();
full.push("*".to_string());
bindings.push(("*".to_string(), full.join("::"), glob.span().start().line));
}
syn::UseTree::Group(group) => {
for item in &group.items {
walk_tree(item, prefix, bindings);
}
}
}
}
fn walk_items(items: &[syn::Item], bindings: &mut Vec<(String, String, usize)>) {
for item in items {
match item {
syn::Item::Use(import) => {
walk_tree(&import.tree, &mut Vec::new(), bindings);
}
syn::Item::ExternCrate(external) => {
let bound = external
.rename
.as_ref()
.map_or(&external.ident, |(_, rename)| rename);
bindings.push((
spelled(bound),
spelled(&external.ident),
bound.span().start().line,
));
}
syn::Item::Mod(module) => {
if let Some((_, inner)) = &module.content {
walk_items(inner, bindings);
}
}
_ => {}
}
}
}
let mut bindings = Vec::new();
walk_items(&ast.items, &mut bindings);
bindings
}
#[must_use]
pub fn use_statement_count(ast: &syn::File) -> usize {
fn walk(items: &[syn::Item]) -> usize {
items
.iter()
.map(|item| match item {
syn::Item::Use(_) => 1,
syn::Item::Mod(module) => {
module.content.as_ref().map_or(0, |(_, inner)| walk(inner))
}
_ => 0,
})
.sum()
}
walk(&ast.items)
}
pub fn macro_surface(source: &str) -> Result<MacroSurface, String> {
let stream: TokenStream = source
.parse()
.map_err(|error| format!("lex failed: {error}"))?;
let trees: Vec<TokenTree> = stream.into_iter().collect();
let mut surface = MacroSurface {
invocations: Vec::new(),
attributes: Vec::new(),
derives: Vec::new(),
};
scan_macro_surface(&trees, &mut surface);
Ok(surface)
}
fn collect_identifier(stream: TokenStream, identifier: &str, lines: &mut Vec<usize>) {
for tree in stream {
match tree {
TokenTree::Ident(ident) => {
let spelled = ident.to_string();
if spelled.strip_prefix("r#").unwrap_or(&spelled) == identifier {
lines.push(ident.span().start().line);
}
}
TokenTree::Group(group) => {
collect_identifier(group.stream(), identifier, lines);
}
TokenTree::Punct(_) | TokenTree::Literal(_) => {}
}
}
}
pub fn identifier_lines(source: &str, identifier: &str) -> Result<Vec<usize>, String> {
let stream: TokenStream = source
.parse()
.map_err(|error| format!("lex failed: {error}"))?;
let mut lines = Vec::new();
collect_identifier(stream, identifier, &mut lines);
Ok(lines)
}
pub fn identifier_line_census(
source: &str,
identifier: &str,
) -> Result<BTreeMap<String, usize>, String> {
let mut lines = identifier_lines(source, identifier)?;
lines.sort_unstable();
lines.dedup();
let text: Vec<&str> = source.lines().collect();
let mut census = BTreeMap::new();
for line in lines {
let content = text
.get(line - 1)
.map_or_else(String::new, |content| content.trim().to_string());
*census.entry(content).or_insert(0) += 1;
}
Ok(census)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn raw_strings_cannot_mask_an_occurrence() {
let source = "fn f(&mut self) { let _ = r#\"\" // \"#; self.counters.clear(); }\n";
assert_eq!(
identifier_lines(source, "counters").expect("lexes"),
vec![1]
);
}
#[test]
fn raw_identifiers_resolve_to_the_same_site() {
let source = "fn f(&mut self) { self.r#counters.clear(); }\n";
assert_eq!(
identifier_lines(source, "counters").expect("lexes"),
vec![1]
);
let banned = "fn f() { r#include!(\"../elsewhere.rs\"); }\n";
assert_eq!(identifier_lines(banned, "include").expect("lexes"), vec![1]);
}
#[test]
fn comments_and_strings_produce_no_occurrence() {
let source = "// counters\n/* counters */\nfn f() { let _ = \"counters\"; }\n";
assert_eq!(
identifier_lines(source, "counters").expect("lexes"),
Vec::<usize>::new()
);
}
#[test]
fn path_attributes_are_refused() {
let ast = syn::parse_file("#[path = \"../elsewhere.rs\"]\nmod extra;\n").expect("parses");
let audit = audit_module_items(&ast, true);
assert_eq!(audit.violations.len(), 1);
assert!(audit.violations[0].contains("path"));
}
#[test]
fn cfg_attr_on_modules_is_refused() {
let ast = syn::parse_file("#[cfg_attr(unix, path = \"../elsewhere.rs\")]\nmod extra;\n")
.expect("parses");
let audit = audit_module_items(&ast, true);
assert_eq!(audit.violations.len(), 1);
}
#[test]
fn item_position_macros_are_refused() {
let ast = syn::parse_file("include!(\"../elsewhere.rs\");\n").expect("parses");
let audit = audit_module_items(&ast, true);
assert_eq!(audit.violations.len(), 1);
assert!(audit.violations[0].contains("include"));
}
#[test]
fn macro_surface_sees_every_position() {
let source = "#[evil_attr]\nfn f() { evil!(self); let _ = also_evil![1]; }\n\
#[derive(Clone, Evil)]\nstruct S;\n";
let surface = macro_surface(source).expect("lexes");
let invocations: Vec<&str> = surface
.invocations
.iter()
.map(|(name, _)| name.as_str())
.collect();
assert_eq!(invocations, ["evil", "also_evil"]);
let attributes: Vec<&str> = surface
.attributes
.iter()
.map(|(name, _)| name.as_str())
.collect();
assert_eq!(attributes, ["evil_attr", "derive"]);
let derives: Vec<&str> = surface
.derives
.iter()
.map(|(name, _)| name.as_str())
.collect();
assert_eq!(derives, ["Clone", "Evil"]);
}
#[test]
fn qualified_spellings_stay_qualified() {
let source = "#[kani::proof]\n#[derive(evil::Error)]\n\
fn f() { evil::assert!(true); #[attr(nested!(1))] struct T; }\n";
let surface = macro_surface(source).expect("lexes");
let invocations: Vec<&str> = surface
.invocations
.iter()
.map(|(name, _)| name.as_str())
.collect();
assert_eq!(invocations, ["evil::assert", "nested"]);
let attributes: Vec<&str> = surface
.attributes
.iter()
.map(|(name, _)| name.as_str())
.collect();
assert_eq!(attributes, ["kani::proof", "derive", "attr"]);
let derives: Vec<&str> = surface
.derives
.iter()
.map(|(name, _)| name.as_str())
.collect();
assert_eq!(derives, ["evil::Error"]);
}
#[test]
fn use_bindings_report_renames_and_globs() {
let ast = syn::parse_file(
"use evil::assert;\nuse evil::{prelude::*, Error as Failure};\n\
mod inner { use evil::assert_eq; }\n",
)
.expect("parses");
let bindings: Vec<(String, String)> = use_bindings(&ast)
.into_iter()
.map(|(name, path, _)| (name, path))
.collect();
assert_eq!(
bindings,
[
("assert".to_string(), "evil::assert".to_string()),
("*".to_string(), "evil::prelude::*".to_string()),
("Failure".to_string(), "evil::Error".to_string()),
("assert_eq".to_string(), "evil::assert_eq".to_string()),
]
);
}
#[test]
fn raw_aliases_normalize_in_use_bindings() {
let ast = syn::parse_file("use evil::assert as r#assert;\n").expect("parses");
let bindings: Vec<(String, String)> = use_bindings(&ast)
.into_iter()
.map(|(name, path, _)| (name, path))
.collect();
assert_eq!(
bindings,
[("assert".to_string(), "evil::assert".to_string())]
);
}
#[test]
fn parent_binding_refuses_redirection_and_inline_bodies() {
let redirected =
syn::parse_file("#[path = \"../elsewhere/mod.rs\"]\nmod guarded;\n").expect("parses");
assert!(file_module_binding(&redirected, "guarded").is_err());
let inline = syn::parse_file("mod guarded { pub struct S;\n}\n").expect("parses");
assert!(file_module_binding(&inline, "guarded").is_err());
let doubled =
syn::parse_file("mod guarded;\n#[cfg(test)]\nmod guarded;\n").expect("parses");
assert!(file_module_binding(&doubled, "guarded").is_err());
let plain = syn::parse_file("mod guarded;\n").expect("parses");
assert!(file_module_binding(&plain, "guarded").is_ok());
}
#[test]
fn multiline_visibility_is_structural_not_textual() {
let ast = syn::parse_file("pub struct S {\n pub(crate)\n field: u32,\n}\n")
.expect("parses");
let fields = struct_fields(&ast, "S").expect("declared once");
let field = fields.iter().next().expect("one field");
assert!(!matches!(field.vis, syn::Visibility::Inherited));
}
}