diff --git a/plasma-engine/src/apply.rs b/plasma-engine/src/apply.rs index 284b003..27474a1 100644 --- a/plasma-engine/src/apply.rs +++ b/plasma-engine/src/apply.rs @@ -9,7 +9,7 @@ // already present is skipped, not repeated. use crate::action::{Action, Plan}; -use plasma_parser::audit::header::{comment_prefix, extract_spdx_raw_from_content}; +use plasma_parser::audit::header::{extract_spdx_raw_from_content, format_header}; use serde::{Deserialize, Serialize}; use std::fs; use std::path::Path; @@ -114,9 +114,12 @@ fn add_spdx_header( .extension() .and_then(|e| e.to_str()) .unwrap_or(""); - let prefix = comment_prefix(ext); - let header = format!( - "{prefix} SPDX-License-Identifier: {license}\n{prefix} Copyright (c) {year} {author}\n\n" + let header = format_header( + ext, + &[ + format!("SPDX-License-Identifier: {license}"), + format!("Copyright (c) {year} {author}"), + ], ); if opts.backup { diff --git a/plasma-engine/src/ast.rs b/plasma-engine/src/ast.rs index 9d10099..a3ebd2a 100644 --- a/plasma-engine/src/ast.rs +++ b/plasma-engine/src/ast.rs @@ -8,7 +8,8 @@ // rules carry an explicit severity, and the condition vocabulary is // license-agnostic. -use crate::finding::Severity; +use crate::{eval::glob_matches, finding::Severity}; +use plasma_parser::audit::header::PROSE_EXTENSIONS; use serde::{Deserialize, Serialize}; /// Schema/policy version as a major.minor pair. @@ -211,6 +212,78 @@ impl Policy { } } +impl Policy { + /// Whether any rule checks the header of a prose file (`.adoc`, `.md`), + /// so callers know to collect prose headers before evaluating. + pub fn needs_prose_headers(&self) -> bool { + let added = self + .overlays + .iter() + .flat_map(|o| &o.effects) + .flat_map(|e| match e { + OverlayEffect::AddRules { rules } => rules.as_slice(), + _ => &[], + }); + self.rules + .iter() + .chain(added) + .filter(|r| matches!(r.resource, Resource::Header)) + .any(|r| match &r.subject { + Subject::File { path } => is_prose_path(path), + Subject::FilePattern { patterns } => patterns.iter().any(|p| can_match_prose(p)), + _ => false, + }) + } +} + +fn is_prose_path(p: &str) -> bool { + p.ends_with(".adoc") || p.ends_with(".md") +} + +fn can_match_prose(pattern: &str) -> bool { + if glob::Pattern::new(pattern).is_err() { + return false; + } + + // The stem and directories are unknown. The extension can start at a + // token boundary or inside a wildcard, so test the glob tails that could + // consume the extension, starting with the shortest. + let mut tokens = Vec::new(); + let mut rest = pattern; + while let Some(c) = rest.chars().next() { + tokens.push((rest, c != '*')); + rest = match c { + '[' => { + // A class may have an initial literal ']', after an optional '!'. + let body = &rest[1..]; + let body = body.strip_prefix('!').unwrap_or(body); + let body = body.strip_prefix(']').unwrap_or(body); + body.split_once(']').expect("validated glob class").1 + } + '*' if rest.starts_with("**") => { + let tail = &rest[2..]; + tail.strip_prefix(std::path::is_separator).unwrap_or(tail) + } + _ => &rest[c.len_utf8()..], + }; + } + + PROSE_EXTENSIONS.iter().any(|ext| { + let suffix = format!(".{ext}"); + let mut required = 0; + for &(tail, consumes_char) in tokens.iter().rev() { + required += usize::from(consumes_char); + if required > suffix.len() { + break; + } + if glob_matches(tail, &suffix) { + return true; + } + } + false + }) +} + fn condition_needs_content(c: &Condition) -> bool { match c { Condition::FileMatchesPattern { .. } => true, diff --git a/plasma-engine/src/eval.rs b/plasma-engine/src/eval.rs index 5fc8bbc..39e20d4 100644 --- a/plasma-engine/src/eval.rs +++ b/plasma-engine/src/eval.rs @@ -122,7 +122,7 @@ fn expand_subject(subject: &Subject, facts: &FactSet) -> Vec { /// /// `**/` prefixes also match zero directories: "**/*.rs" matches both /// "src/main.rs" and "main.rs". -fn glob_matches(pattern: &str, path: &str) -> bool { +pub(crate) fn glob_matches(pattern: &str, path: &str) -> bool { match glob::Pattern::new(pattern) { Ok(p) => { if p.matches(path) { diff --git a/plasma-engine/src/facts.rs b/plasma-engine/src/facts.rs index 094d171..41aa941 100644 --- a/plasma-engine/src/facts.rs +++ b/plasma-engine/src/facts.rs @@ -9,7 +9,7 @@ // implementation can reproduce identical facts. All collections are // BTree-ordered so downstream evaluation is deterministic. -use plasma_parser::audit::header::{extract_spdx_raw_from_content, is_auditable}; +use plasma_parser::audit::header::{extract_spdx_raw_from_content, is_auditable, is_prose}; use serde::{Deserialize, Serialize}; use std::collections::{BTreeMap, BTreeSet}; use std::fs; @@ -44,6 +44,9 @@ pub struct CollectOptions { /// content-aware conditions like `file-matches-pattern`). Off by /// default so the standard snapshot stays lean. pub contents: bool, + /// Also record SPDX headers of prose files (`.adoc`, `.md`) in + /// `spdx_headers`. Off by default so the standard snapshot is unchanged. + pub prose_headers: bool, } /// A deterministic snapshot of repository state. @@ -117,7 +120,7 @@ pub fn collect_opts(root: &Path, opts: &CollectOptions) -> Result\n# Notes\n", + ) + .unwrap(); + fs::write(dir.path().join("bare.md"), "# Bare\n").unwrap(); + + let default = collect(dir.path()).unwrap(); + assert!(!default.spdx_headers.contains_key("guide.adoc")); + + let prose = collect_opts( + dir.path(), + &CollectOptions { + prose_headers: true, + ..CollectOptions::default() + }, + ) + .unwrap(); + let cc = Some("CC-BY-SA-4.0".to_string()); + assert_eq!(prose.spdx_headers.get("guide.adoc"), Some(&cc)); + assert_eq!(prose.spdx_headers.get("notes.md"), Some(&cc)); + assert_eq!(prose.spdx_headers.get("bare.md"), Some(&None)); + } + #[test] fn test_cargo_version_metadata() { let dir = tempfile::tempdir().unwrap(); @@ -245,7 +280,14 @@ mod tests { assert!(!json.contains("file_contents")); // Opt-in: contents present. - let full = collect_opts(dir.path(), &CollectOptions { contents: true }).unwrap(); + let full = collect_opts( + dir.path(), + &CollectOptions { + contents: true, + ..CollectOptions::default() + }, + ) + .unwrap(); assert_eq!( full.file_contents.get("a.rs"), Some(&"fn main() {}\n".to_string()) @@ -263,7 +305,14 @@ mod tests { fs::write(dir.path().join("big.txt"), &big).unwrap(); fs::write(dir.path().join("small.txt"), "ok\n").unwrap(); - let facts = collect_opts(dir.path(), &CollectOptions { contents: true }).unwrap(); + let facts = collect_opts( + dir.path(), + &CollectOptions { + contents: true, + ..CollectOptions::default() + }, + ) + .unwrap(); // Both files are listed… assert!(facts.files.contains("big.txt")); assert!(facts.files.contains("small.txt")); diff --git a/plasma-parser/src/audit/header.rs b/plasma-parser/src/audit/header.rs index deced8e..0cfce64 100644 --- a/plasma-parser/src/audit/header.rs +++ b/plasma-parser/src/audit/header.rs @@ -18,6 +18,10 @@ pub const AUDITABLE_EXTENSIONS: &[&str] = &[ "sh", "bash", "zsh", "toml", "yaml", "yml", "ncl", "nix", "scm", "v", "ada", "adb", "ads", ]; +/// Prose file extensions. Not audited by `plasma audit`; their headers are +/// collected into facts only when a policy asks for them. +pub const PROSE_EXTENSIONS: &[&str] = &["adoc", "md"]; + /// Returns the comment prefix for a given file extension. pub fn comment_prefix(ext: &str) -> &'static str { match ext { @@ -28,15 +32,36 @@ pub fn comment_prefix(ext: &str) -> &'static str { "ex" | "exs" | "gleam" | "nim" | "py" | "rb" | "sh" | "bash" | "zsh" | "toml" | "yaml" | "yml" | "ncl" | "nix" | "jl" => "#", "scm" => ";;", + "adoc" => "//", _ => "//", } } +/// Render header comment lines for a file extension, ending with a blank +/// line. Markdown has no line comment, so each line becomes an HTML comment. +pub fn format_header(ext: &str, lines: &[String]) -> String { + let mut out = String::new(); + for line in lines { + if ext == "md" { + out.push_str(&format!("\n")); + } else { + out.push_str(&format!("{} {line}\n", comment_prefix(ext))); + } + } + out.push('\n'); + out +} + /// Check whether a file extension is auditable. pub fn is_auditable(ext: &str) -> bool { AUDITABLE_EXTENSIONS.contains(&ext) } +/// Returns true if the extension is a prose format (AsciiDoc or Markdown). +pub fn is_prose(ext: &str) -> bool { + PROSE_EXTENSIONS.contains(&ext) +} + /// Extract the SPDX-License-Identifier from a file's header. /// /// Returns `None` if the file has no SPDX header within the first @@ -60,6 +85,11 @@ pub fn extract_spdx_from_content(content: &str) -> Option { pub fn extract_spdx_raw_from_content(content: &str) -> Option { for line in content.lines().take(MAX_HEADER_LINES) { let trimmed = line.trim(); + // Markdown HTML comment: + let trimmed = match trimmed.strip_prefix("").unwrap_or(inner).trim(), + None => trimmed, + }; // Strip comment prefixes. let stripped = trimmed .strip_prefix("//") @@ -80,6 +110,43 @@ pub fn extract_spdx_raw_from_content(content: &str) -> Option { mod tests { use super::*; + #[test] + fn test_format_header_markdown_round_trips() { + let h = format_header("md", &["SPDX-License-Identifier: CC-BY-SA-4.0".to_string()]); + assert_eq!(h, "\n\n"); + assert_eq!( + extract_spdx_raw_from_content(&h).as_deref(), + Some("CC-BY-SA-4.0") + ); + } + + #[test] + fn test_format_header_asciidoc() { + let h = format_header( + "adoc", + &["SPDX-License-Identifier: CC-BY-SA-4.0".to_string()], + ); + assert_eq!(h, "// SPDX-License-Identifier: CC-BY-SA-4.0\n\n"); + } + + #[test] + fn test_extract_markdown_html_comment_header() { + let content = "\n# Title\n"; + assert_eq!( + extract_spdx_raw_from_content(content).as_deref(), + Some("CC-BY-SA-4.0") + ); + } + + #[test] + fn test_extract_asciidoc_header() { + let content = "// SPDX-License-Identifier: CC-BY-SA-4.0\n= Title\n"; + assert_eq!( + extract_spdx_raw_from_content(content).as_deref(), + Some("CC-BY-SA-4.0") + ); + } + #[test] fn test_extract_rust_header() { let content = "// SPDX-License-Identifier: PPMPL-1.0-or-later\n// Copyright (c) 2026\n"; diff --git a/src/audit.rs b/src/audit.rs index d906a81..df01d00 100644 --- a/src/audit.rs +++ b/src/audit.rs @@ -6,7 +6,7 @@ // expectations from .plasma.toml when present). use anyhow::{Context, Result}; -use plasma_parser::audit::header::comment_prefix; +use plasma_parser::audit::header::format_header; use plasma_parser::audit::{scan_repo, AuditStatus}; use plasma_parser::spdx::parse_spdx_expr; use plasma_parser::zone::boundary::parse_plasma_toml; @@ -42,10 +42,12 @@ pub fn run(path: &str, license: &str, fix: bool) -> Result<()> { AuditStatus::MissingHeader if fix => { let full_path = root.join(&file.path); let ext = file.path.extension().and_then(|e| e.to_str()).unwrap_or(""); - let prefix = comment_prefix(ext); - let header = format!( - "{prefix} SPDX-License-Identifier: {}\n{prefix} Copyright (c) 2026 CHANGE-ME\n\n", - file.expected_license + let header = format_header( + ext, + &[ + format!("SPDX-License-Identifier: {}", file.expected_license), + "Copyright (c) 2026 CHANGE-ME".to_string(), + ], ); let content = fs::read_to_string(&full_path) .with_context(|| format!("cannot read {}", full_path.display()))?; diff --git a/src/check.rs b/src/check.rs index 6e44d1a..8ae087b 100644 --- a/src/check.rs +++ b/src/check.rs @@ -35,6 +35,7 @@ pub fn run(opts: &CheckOptions) -> Result { Path::new(opts.path), &CollectOptions { contents: policy.needs_content(), + prose_headers: policy.needs_prose_headers(), }, ) .with_context(|| format!("failed to collect facts from {}", opts.path))?; diff --git a/src/facts_cmd.rs b/src/facts_cmd.rs index c9810e2..388d528 100644 --- a/src/facts_cmd.rs +++ b/src/facts_cmd.rs @@ -9,11 +9,12 @@ use anyhow::{Context, Result}; use plasma_engine::{collect_opts, CollectOptions}; use std::path::Path; -pub fn run(path: &str, with_contents: bool) -> Result<()> { +pub fn run(path: &str, with_contents: bool, with_prose_headers: bool) -> Result<()> { let facts = collect_opts( Path::new(path), &CollectOptions { contents: with_contents, + prose_headers: with_prose_headers, }, ) .with_context(|| format!("failed to collect facts from {path}"))?; diff --git a/src/fix.rs b/src/fix.rs index 620380e..964c988 100644 --- a/src/fix.rs +++ b/src/fix.rs @@ -38,6 +38,7 @@ pub fn run(opts: &FixOptions) -> Result { Path::new(opts.path), &CollectOptions { contents: policy.needs_content(), + prose_headers: policy.needs_prose_headers(), }, ) .with_context(|| format!("failed to collect facts from {}", opts.path))?; diff --git a/src/main.rs b/src/main.rs index 2f163ef..2e356bb 100644 --- a/src/main.rs +++ b/src/main.rs @@ -90,6 +90,9 @@ enum Commands { /// Also include text-file contents (for content-aware policies) #[arg(long)] with_contents: bool, + /// Also record SPDX headers of prose files (.adoc, .md) + #[arg(long)] + with_prose_headers: bool, }, /// Compare two fact snapshots (exit 0 identical, 1 differ). @@ -225,8 +228,9 @@ fn run(cli: Cli) -> Result<()> { Commands::Facts { path, with_contents, + with_prose_headers, } => { - facts_cmd::run(&path, with_contents)?; + facts_cmd::run(&path, with_contents, with_prose_headers)?; } Commands::Diff { before, diff --git a/tests/check_selftest.rs b/tests/check_selftest.rs index e37527d..9b345e3 100644 --- a/tests/check_selftest.rs +++ b/tests/check_selftest.rs @@ -72,3 +72,54 @@ fn policy_validate_accepts_bundled_policy() { String::from_utf8_lossy(&output.stderr) ); } + +#[test] +fn check_collects_prose_headers_for_matching_globs() { + let repo = tempfile::tempdir().unwrap(); + let docs = repo.path().join("docs"); + std::fs::create_dir(&docs).unwrap(); + std::fs::write( + docs.join("guide.md"), + "\n", + ) + .unwrap(); + std::fs::write( + docs.join("reference.adoc"), + "// SPDX-License-Identifier: MPL-2.0\n", + ) + .unwrap(); + let policy = repo.path().join("policy.toml"); + + for (pattern, passes) in [("docs/**", 2), ("docs/*.md", 1), ("docs/*.m[d]", 1)] { + std::fs::write( + &policy, + format!( + r#" +schema_version = {{ major = 0, minor = 1 }} +id = "prose-headers" +version = {{ major = 0, minor = 1 }} + +[[rules]] +id = "prose-header-required" +modality = "obligation" +subject = {{ type = "file-pattern", patterns = ["{pattern}"] }} +resource = {{ type = "header" }} +action = {{ type = "present" }} +"# + ), + ) + .unwrap(); + + let output = plasma() + .arg("check") + .arg(repo.path()) + .arg("--policy") + .arg(&policy) + .args(["--format", "json"]) + .output() + .unwrap(); + let evaluation: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap(); + assert!(output.status.success(), "{pattern}: {evaluation}"); + assert_eq!(evaluation["summary"]["passes"], passes, "{pattern}"); + } +}