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

supercov_engine/
ruby_project.rs
