supercov_engine/
ruby_project.rs

1//! Ruby project discovery and ahead-of-run obligation preparation.
2//!
3//! The project runs in place: nothing here copies or rewrites sources. Rust
4//! reads every in-scope `.rb` file once, builds the complete manifest and the
5//! runtime probe plan, and records which files were included, excluded or
6//! unparseable so the run can say exactly what its denominator covers.
7
8use std::{
9    collections::{BTreeMap, BTreeSet},
10    fs,
11    path::{Path, PathBuf},
12};
13
14use serde_json::json;
15
16use crate::{
17    coverage_report::CoverageManifest,
18    integrity::ExplicitIntegrityInputs,
19    ruby_instrumenter::{
20        RUBY_PROBE_PLAN_VERSION, RUBY_PROBE_RECEIVER, RubyFilePlan, RubyProbePlan,
21        build_ruby_obligations,
22    },
23    source_discovery::{SourceScope, SourceScopeEntry, SourceScopeMode, SourceScopeStatus},
24};
25
26pub const UNPARSEABLE_LIMITATION: &str = "ruby-source-unparseable";
27
28/// Directories that never hold the project's own measured source. The list
29/// follows what Ruby coverage tooling conventionally filters for Rails and
30/// gem layouts (Rails `config/` holds boot and environment settings, not
31/// application logic).
32const EXCLUDED_DIRECTORIES: &[&str] = &[
33    ".git",
34    ".hg",
35    ".svn",
36    ".supercov",
37    ".bundle",
38    "node_modules",
39    "vendor",
40    "tmp",
41    "log",
42    "coverage",
43    "config",
44    "db",
45    "bin",
46    "public",
47    "storage",
48    ".yardoc",
49    "doc",
50    "pkg",
51];
52
53const TEST_DIRECTORIES: &[&str] = &["spec", "test", "tests", "features"];
54
55#[derive(Debug, Clone, PartialEq, Eq, Default)]
56pub struct RubyFiles {
57    /// Relative, `/`-separated paths of measured application sources.
58    pub sources: Vec<String>,
59    /// Relative paths of specs, tests and other excluded `.rb` files.
60    pub tests: Vec<String>,
61    pub dependency_files: Vec<PathBuf>,
62    pub configuration_files: Vec<PathBuf>,
63    pub excluded: Vec<(String, &'static str)>,
64}
65
66#[derive(Debug, Clone, PartialEq)]
67pub struct PreparedRubyProject {
68    pub root: PathBuf,
69    pub files: RubyFiles,
70    pub manifest: CoverageManifest,
71    pub plan: RubyProbePlan,
72    pub unparseable: Vec<(String, String)>,
73}
74
75fn is_test_path(relative: &str) -> Option<&'static str> {
76    let mut components = relative.split('/').peekable();
77    let mut file_name = "";
78    while let Some(component) = components.next() {
79        if components.peek().is_none() {
80            file_name = component;
81            break;
82        }
83        if TEST_DIRECTORIES.contains(&component) {
84            return Some("inside a test directory");
85        }
86    }
87    if file_name.ends_with("_spec.rb") || file_name.ends_with("_test.rb") {
88        return Some("test module by name");
89    }
90    if file_name.starts_with("test_") && file_name.ends_with(".rb") {
91        return Some("test module by name");
92    }
93    if matches!(
94        file_name,
95        "spec_helper.rb" | "rails_helper.rb" | "test_helper.rb"
96    ) {
97        return Some("test helper");
98    }
99    None
100}
101
102fn walk(root: &Path, directory: &Path, files: &mut RubyFiles) -> Result<(), String> {
103    let mut entries = fs::read_dir(directory)
104        .map_err(|error| format!("{}: {error}", directory.display()))?
105        .collect::<Result<Vec<_>, _>>()
106        .map_err(|error| error.to_string())?;
107    entries.sort_by_key(fs::DirEntry::file_name);
108    for entry in entries {
109        let path = entry.path();
110        let name = entry
111            .file_name()
112            .into_string()
113            .map_err(|_| format!("Ruby project contains a non-UTF-8 path: {}", path.display()))?;
114        let file_type = entry.file_type().map_err(|error| error.to_string())?;
115        let relative = path
116            .strip_prefix(root)
117            .map_err(|_| format!("path escaped root: {}", path.display()))?
118            .to_string_lossy()
119            .replace('\\', "/");
120        if file_type.is_dir() {
121            if EXCLUDED_DIRECTORIES.contains(&name.as_str()) {
122                files
123                    .excluded
124                    .push((relative, "tooling, dependency or generated directory"));
125                continue;
126            }
127            walk(root, &path, files)?;
128        } else if file_type.is_file() {
129            match name.as_str() {
130                "Gemfile" | "Gemfile.lock" | ".ruby-version" | ".tool-versions" => {
131                    files.dependency_files.push(PathBuf::from(&relative));
132                    continue;
133                }
134                ".rspec" | "Rakefile" | "config.ru" => {
135                    files.configuration_files.push(PathBuf::from(&relative));
136                    continue;
137                }
138                _ => {}
139            }
140            if name.ends_with(".gemspec") {
141                files.dependency_files.push(PathBuf::from(&relative));
142                continue;
143            }
144            if !name.ends_with(".rb") {
145                continue;
146            }
147            match is_test_path(&relative) {
148                Some(reason) => {
149                    files.tests.push(relative.clone());
150                    files.excluded.push((relative, reason));
151                }
152                None => files.sources.push(relative),
153            }
154        }
155        // Symlinks are neither followed nor measured.
156    }
157    Ok(())
158}
159
160pub fn discover_ruby_files(root: &Path) -> Result<RubyFiles, String> {
161    let mut files = RubyFiles::default();
162    walk(root, root, &mut files)?;
163    files.sources.sort();
164    files.tests.sort();
165    files.dependency_files.sort();
166    files.configuration_files.sort();
167    Ok(files)
168}
169
170pub fn prepare_ruby_project(root: &Path) -> Result<PreparedRubyProject, String> {
171    let files = discover_ruby_files(root)?;
172    if files.sources.is_empty() && files.tests.is_empty() {
173        return Err(
174            "no Ruby source files were found under the project root; Supercov measures .rb files outside vendor, db, bin and test directories".into(),
175        );
176    }
177    let mut manifest = CoverageManifest {
178        unmeasured: Vec::new(),
179        decisions: Vec::new(),
180        points: Vec::new(),
181        branches: Vec::new(),
182        limitations: Vec::new(),
183        scope: None,
184    };
185    let mut plan_files = BTreeMap::<String, RubyFilePlan>::new();
186    let mut probes = BTreeMap::new();
187    let mut next_probe = 0u64;
188    let mut limitation_ids = BTreeSet::new();
189    let mut unparseable = Vec::new();
190    for relative in &files.sources {
191        let path = root.join(relative);
192        let source = fs::read(&path).map_err(|error| format!("{}: {error}", path.display()))?;
193        match build_ruby_obligations(relative, &source, &mut next_probe) {
194            Ok(obligations) => {
195                manifest.points.extend(obligations.manifest.points);
196                manifest.decisions.extend(obligations.manifest.decisions);
197                manifest.branches.extend(obligations.manifest.branches);
198                manifest.unmeasured.extend(obligations.manifest.unmeasured);
199                for item in obligations.manifest.limitations {
200                    let id = item
201                        .get("id")
202                        .and_then(serde_json::Value::as_str)
203                        .unwrap_or_default()
204                        .to_owned();
205                    if limitation_ids.insert(id) {
206                        manifest.limitations.push(item);
207                    }
208                }
209                plan_files.insert(relative.clone(), obligations.plan);
210                probes.extend(obligations.probes);
211            }
212            Err(error) => unparseable.push((relative.clone(), error.to_string())),
213        }
214    }
215    if let Some((file, reason)) = unparseable.first()
216        && limitation_ids.insert(UNPARSEABLE_LIMITATION.into())
217    {
218        manifest.limitations.push(json!({
219            "id": UNPARSEABLE_LIMITATION,
220            "kind": "source-scope",
221            "file": file,
222            "line": 1,
223            "column": 0,
224            "source": "",
225            "reason": format!(
226                "{} source file(s) could not be parsed and carry no obligations; first: {file}: {reason}",
227                unparseable.len()
228            )
229        }));
230    }
231    manifest.unmeasured.sort();
232    manifest.unmeasured.dedup();
233    let mut entries = Vec::new();
234    for file in &files.sources {
235        let unparseable_file = unparseable.iter().any(|(path, _)| path == file);
236        entries.push(SourceScopeEntry {
237            file: file.clone(),
238            status: if unparseable_file {
239                SourceScopeStatus::Excluded
240            } else {
241                SourceScopeStatus::Included
242            },
243            reason: if unparseable_file {
244                "could not be parsed".into()
245            } else {
246                "Ruby application source".into()
247            },
248            package_root: None,
249        });
250    }
251    for (file, reason) in &files.excluded {
252        if file.ends_with(".rb") {
253            entries.push(SourceScopeEntry {
254                file: file.clone(),
255                status: SourceScopeStatus::Excluded,
256                reason: (*reason).into(),
257                package_root: None,
258            });
259        }
260    }
261    entries.sort_by(|left, right| left.file.cmp(&right.file));
262    manifest.scope = Some(
263        serde_json::to_value(SourceScope {
264            version: 1,
265            mode: SourceScopeMode::Automatic,
266            roots: vec![".".into()],
267            entries,
268        })
269        .map_err(|error| error.to_string())?,
270    );
271    let mut plan = RubyProbePlan {
272        version: RUBY_PROBE_PLAN_VERSION,
273        root: root.display().to_string(),
274        receiver: RUBY_PROBE_RECEIVER.into(),
275        files: plan_files,
276        probes,
277        probe_obligations: Vec::new(),
278    };
279    plan.probe_obligations = plan.probe_obligations();
280    Ok(PreparedRubyProject {
281        root: root.to_owned(),
282        plan,
283        manifest,
284        files,
285        unparseable,
286    })
287}
288
289pub fn ruby_integrity_inputs(files: &RubyFiles, command: &[String]) -> ExplicitIntegrityInputs {
290    let execution_configuration = command.join("\0").into_bytes();
291    ExplicitIntegrityInputs {
292        source_files: files.sources.iter().map(PathBuf::from).collect(),
293        test_files: files.tests.iter().map(PathBuf::from).collect(),
294        dependency_files: files.dependency_files.clone(),
295        configuration_files: files.configuration_files.clone(),
296        execution_configuration,
297    }
298}
299
300#[cfg(test)]
301mod tests {
302
303    #[test]
304    fn the_ambient_environment_is_not_part_of_run_identity() {
305        // Identity is what the project is, not which shell it was run from.
306        // Folding the environment in meant no two terminals, and no two
307        // machines, ever agreed on the same run. What a project genuinely needs
308        // from its environment it declares in the files that are hashed above.
309        let files = RubyFiles::default();
310        let command = ["rspec".to_owned(), "--format=progress".to_owned()];
311        let inputs = ruby_integrity_inputs(&files, &command);
312        assert_eq!(inputs.execution_configuration, b"rspec\0--format=progress");
313    }
314    use std::time::{SystemTime, UNIX_EPOCH};
315
316    use super::*;
317
318    fn fixture(name: &str) -> PathBuf {
319        let nonce = SystemTime::now()
320            .duration_since(UNIX_EPOCH)
321            .unwrap()
322            .as_nanos();
323        let root = std::env::temp_dir().join(format!(
324            "supercov-ruby-project-{}-{nonce}-{name}",
325            std::process::id()
326        ));
327        fs::create_dir_all(&root).unwrap();
328        root
329    }
330
331    fn write(root: &Path, relative: &str, contents: &str) {
332        let path = root.join(relative);
333        fs::create_dir_all(path.parent().unwrap()).unwrap();
334        fs::write(path, contents).unwrap();
335    }
336
337    #[test]
338    fn separates_sources_tests_and_tooling() {
339        let root = fixture("discover");
340        write(&root, "Gemfile", "source 'https://rubygems.org'\n");
341        write(&root, ".rspec", "--require spec_helper\n");
342        write(&root, "lib/app.rb", "def f(a)\n  a && 1\nend\n");
343        write(&root, "lib/app/version.rb", "VERSION = '1'\n");
344        write(&root, "spec/app_spec.rb", "RSpec.describe 'x' do end\n");
345        write(&root, "spec/spec_helper.rb", "");
346        write(&root, "test/app_test.rb", "");
347        write(&root, "vendor/bundle/gem.rb", "x = 1\n");
348        write(&root, "db/schema.rb", "x = 1\n");
349        write(&root, "broken/old.rb", "def (\n");
350        let project = prepare_ruby_project(&root).unwrap();
351        assert_eq!(
352            project.files.sources,
353            ["broken/old.rb", "lib/app.rb", "lib/app/version.rb"]
354        );
355        assert_eq!(
356            project.files.tests,
357            [
358                "spec/app_spec.rb",
359                "spec/spec_helper.rb",
360                "test/app_test.rb"
361            ]
362        );
363        assert_eq!(project.files.dependency_files, [PathBuf::from("Gemfile")]);
364        assert_eq!(project.files.configuration_files, [PathBuf::from(".rspec")]);
365        assert_eq!(project.unparseable.len(), 1);
366        assert!(project.plan.files.contains_key("lib/app.rb"));
367        assert!(!project.plan.files.contains_key("broken/old.rb"));
368        assert_eq!(project.manifest.limitations.len(), 1);
369        assert_eq!(
370            project.manifest.limitations[0]["id"],
371            UNPARSEABLE_LIMITATION
372        );
373        // Probe keys are unique across files.
374        let keys = project.plan.probes.keys().copied().collect::<Vec<_>>();
375        let unique = keys.iter().collect::<BTreeSet<_>>();
376        assert_eq!(keys.len(), unique.len());
377        fs::remove_dir_all(root).unwrap();
378    }
379}
supercov_engine/ruby_project.rs

supercov_engine/
ruby_project.rs
