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(
171    root: &Path,
172    roots: Option<&crate::source_discovery::ExplicitSourceRoots>,
173) -> Result<PreparedRubyProject, String> {
174    let mut files = discover_ruby_files(root)?;
175    if let Some(roots) = roots {
176        roots.narrow(&mut files.sources, &mut files.excluded, String::as_str);
177        roots.refuse_if_empty(files.sources.len(), "Ruby")?;
178    }
179    if files.sources.is_empty() && files.tests.is_empty() {
180        return Err(
181            "no Ruby source files were found under the project root; Supercov measures .rb files outside vendor, db, bin and test directories".into(),
182        );
183    }
184    let mut manifest = CoverageManifest {
185        unmeasured: Vec::new(),
186        decisions: Vec::new(),
187        points: Vec::new(),
188        branches: Vec::new(),
189        limitations: Vec::new(),
190        scope: None,
191        assertion_sites: Vec::new(),
192    };
193    let mut plan_files = BTreeMap::<String, RubyFilePlan>::new();
194    let mut probes = BTreeMap::new();
195    let mut next_probe = 0u64;
196    let mut limitation_ids = BTreeSet::new();
197    let mut unparseable = Vec::new();
198    for relative in &files.sources {
199        let path = root.join(relative);
200        let source = fs::read(&path).map_err(|error| format!("{}: {error}", path.display()))?;
201        match build_ruby_obligations(relative, &source, &mut next_probe) {
202            Ok(obligations) => {
203                manifest.points.extend(obligations.manifest.points);
204                manifest.decisions.extend(obligations.manifest.decisions);
205                manifest.branches.extend(obligations.manifest.branches);
206                manifest.unmeasured.extend(obligations.manifest.unmeasured);
207                for item in obligations.manifest.limitations {
208                    let id = item
209                        .get("id")
210                        .and_then(serde_json::Value::as_str)
211                        .unwrap_or_default()
212                        .to_owned();
213                    if limitation_ids.insert(id) {
214                        manifest.limitations.push(item);
215                    }
216                }
217                plan_files.insert(relative.clone(), obligations.plan);
218                probes.extend(obligations.probes);
219            }
220            Err(error) => unparseable.push((relative.clone(), error.to_string())),
221        }
222    }
223    if let Some((file, reason)) = unparseable.first()
224        && limitation_ids.insert(UNPARSEABLE_LIMITATION.into())
225    {
226        manifest.limitations.push(json!({
227            "id": UNPARSEABLE_LIMITATION,
228            "kind": "source-scope",
229            "file": file,
230            "line": 1,
231            "column": 0,
232            "source": "",
233            "reason": format!(
234                "{} source file(s) could not be parsed and carry no obligations; first: {file}: {reason}",
235                unparseable.len()
236            )
237        }));
238    }
239    manifest.unmeasured.sort();
240    manifest.unmeasured.dedup();
241    let mut entries = Vec::new();
242    for file in &files.sources {
243        let unparseable_file = unparseable.iter().any(|(path, _)| path == file);
244        entries.push(SourceScopeEntry {
245            file: file.clone(),
246            status: if unparseable_file {
247                SourceScopeStatus::Excluded
248            } else {
249                SourceScopeStatus::Included
250            },
251            reason: if unparseable_file {
252                "could not be parsed".into()
253            } else {
254                "Ruby application source".into()
255            },
256            package_root: None,
257        });
258    }
259    for (file, reason) in &files.excluded {
260        if file.ends_with(".rb") {
261            entries.push(SourceScopeEntry {
262                file: file.clone(),
263                status: SourceScopeStatus::Excluded,
264                reason: (*reason).into(),
265                package_root: None,
266            });
267        }
268    }
269    entries.sort_by(|left, right| left.file.cmp(&right.file));
270    manifest.scope = Some(
271        serde_json::to_value(SourceScope {
272            version: 1,
273            mode: if roots.is_some() {
274                SourceScopeMode::Explicit
275            } else {
276                SourceScopeMode::Automatic
277            },
278            roots: match roots {
279                Some(roots) => roots.local_roots().map_err(|error| error.to_string())?,
280                None => vec![".".into()],
281            },
282            entries,
283        })
284        .map_err(|error| error.to_string())?,
285    );
286    let mut plan = RubyProbePlan {
287        version: RUBY_PROBE_PLAN_VERSION,
288        root: root.display().to_string(),
289        receiver: RUBY_PROBE_RECEIVER.into(),
290        files: plan_files,
291        probes,
292        probe_obligations: Vec::new(),
293    };
294    plan.probe_obligations = plan.probe_obligations();
295    Ok(PreparedRubyProject {
296        root: root.to_owned(),
297        plan,
298        manifest,
299        files,
300        unparseable,
301    })
302}
303
304pub fn ruby_integrity_inputs(files: &RubyFiles, command: &[String]) -> ExplicitIntegrityInputs {
305    let execution_configuration = command.join("\0").into_bytes();
306    ExplicitIntegrityInputs {
307        source_files: files.sources.iter().map(PathBuf::from).collect(),
308        test_files: files.tests.iter().map(PathBuf::from).collect(),
309        dependency_files: files.dependency_files.clone(),
310        configuration_files: files.configuration_files.clone(),
311        execution_configuration,
312    }
313}
314
315#[cfg(test)]
316mod tests {
317
318    #[test]
319    fn the_ambient_environment_is_not_part_of_run_identity() {
320        // Identity is what the project is, not which shell it was run from.
321        // Folding the environment in meant no two terminals, and no two
322        // machines, ever agreed on the same run. What a project genuinely needs
323        // from its environment it declares in the files that are hashed above.
324        let files = RubyFiles::default();
325        let command = ["rspec".to_owned(), "--format=progress".to_owned()];
326        let inputs = ruby_integrity_inputs(&files, &command);
327        assert_eq!(inputs.execution_configuration, b"rspec\0--format=progress");
328    }
329    use std::time::{SystemTime, UNIX_EPOCH};
330
331    use super::*;
332
333    fn fixture(name: &str) -> PathBuf {
334        let nonce = SystemTime::now()
335            .duration_since(UNIX_EPOCH)
336            .unwrap()
337            .as_nanos();
338        let root = std::env::temp_dir().join(format!(
339            "supercov-ruby-project-{}-{nonce}-{name}",
340            std::process::id()
341        ));
342        fs::create_dir_all(&root).unwrap();
343        root
344    }
345
346    fn write(root: &Path, relative: &str, contents: &str) {
347        let path = root.join(relative);
348        fs::create_dir_all(path.parent().unwrap()).unwrap();
349        fs::write(path, contents).unwrap();
350    }
351
352    fn explicit_roots(root: &Path, roots: &[&str]) -> crate::source_discovery::ExplicitSourceRoots {
353        let roots = roots
354            .iter()
355            .map(|root| (*root).to_owned())
356            .collect::<Vec<_>>();
357        crate::source_discovery::ExplicitSourceRoots::resolve(root, &roots).unwrap()
358    }
359
360    #[test]
361    fn explicit_roots_narrow_ruby_to_the_code_they_name() {
362        // `third_party`, not `vendor`: vendor is already left out by default,
363        // and a test that passed for that reason would prove nothing.
364        let root = fixture("explicit-roots");
365        write(&root, "Gemfile", "source 'https://rubygems.org'\n");
366        write(&root, "lib/app.rb", "def f(a)\n  a && 1\nend\n");
367        write(&root, "third_party/dep.rb", "def g\n  1\nend\n");
368
369        let project = prepare_ruby_project(&root, Some(&explicit_roots(&root, &["lib"]))).unwrap();
370        assert_eq!(project.files.sources, ["lib/app.rb"], "{:?}", project.files);
371        assert!(
372            project
373                .files
374                .excluded
375                .contains(&("third_party/dep.rb".into(), "outside explicit source roots")),
376            "{:?}",
377            project.files.excluded
378        );
379        let scope: crate::source_discovery::SourceScope =
380            serde_json::from_value(project.manifest.scope.clone().unwrap()).unwrap();
381        assert_eq!(
382            scope.mode,
383            crate::source_discovery::SourceScopeMode::Explicit
384        );
385        assert_eq!(scope.roots, ["lib"]);
386
387        // A single file is a root as well.
388        let project =
389            prepare_ruby_project(&root, Some(&explicit_roots(&root, &["third_party/dep.rb"])))
390                .unwrap();
391        assert_eq!(project.files.sources, ["third_party/dep.rb"]);
392        fs::remove_dir_all(root).ok();
393    }
394
395    #[test]
396    fn separates_sources_tests_and_tooling() {
397        let root = fixture("discover");
398        write(&root, "Gemfile", "source 'https://rubygems.org'\n");
399        write(&root, ".rspec", "--require spec_helper\n");
400        write(&root, "lib/app.rb", "def f(a)\n  a && 1\nend\n");
401        write(&root, "lib/app/version.rb", "VERSION = '1'\n");
402        write(&root, "spec/app_spec.rb", "RSpec.describe 'x' do end\n");
403        write(&root, "spec/spec_helper.rb", "");
404        write(&root, "test/app_test.rb", "");
405        write(&root, "vendor/bundle/gem.rb", "x = 1\n");
406        write(&root, "db/schema.rb", "x = 1\n");
407        write(&root, "broken/old.rb", "def (\n");
408        let project = prepare_ruby_project(&root, None).unwrap();
409        assert_eq!(
410            project.files.sources,
411            ["broken/old.rb", "lib/app.rb", "lib/app/version.rb"]
412        );
413        assert_eq!(
414            project.files.tests,
415            [
416                "spec/app_spec.rb",
417                "spec/spec_helper.rb",
418                "test/app_test.rb"
419            ]
420        );
421        assert_eq!(project.files.dependency_files, [PathBuf::from("Gemfile")]);
422        assert_eq!(project.files.configuration_files, [PathBuf::from(".rspec")]);
423        assert_eq!(project.unparseable.len(), 1);
424        assert!(project.plan.files.contains_key("lib/app.rb"));
425        assert!(!project.plan.files.contains_key("broken/old.rb"));
426        assert_eq!(project.manifest.limitations.len(), 1);
427        assert_eq!(
428            project.manifest.limitations[0]["id"],
429            UNPARSEABLE_LIMITATION
430        );
431        // Probe keys are unique across files.
432        let keys = project.plan.probes.keys().copied().collect::<Vec<_>>();
433        let unique = keys.iter().collect::<BTreeSet<_>>();
434        assert_eq!(keys.len(), unique.len());
435        fs::remove_dir_all(root).unwrap();
436    }
437}
supercov_engine/ruby_project.rs

supercov_engine/
ruby_project.rs
