provenant/
workflow.rs

1// SPDX-FileCopyrightText: Provenant contributors
2// SPDX-License-Identifier: Apache-2.0
3
4use serde_json::{Map as JsonMap, Value as JsonValue};
5use std::path::{Path, PathBuf};
6
7use crate::app::request::{InputMode, ScanRequest};
8use crate::app::scan_pipeline::execute_request;
9use crate::license_detection::DEFAULT_LICENSEDB_URL_TEMPLATE;
10use crate::progress::ProgressMode;
11use crate::scanner::MemoryMode;
12use crate::{Output, ProcessMode};
13
14#[derive(Debug, thiserror::Error)]
15pub enum WorkflowError {
16    #[error("{0}")]
17    InvalidOptions(String),
18    #[error(transparent)]
19    Pipeline(#[from] anyhow::Error),
20}
21
22/// Selects how the workflow facade sources license rules.
23#[derive(Debug, Clone)]
24pub enum LicenseSource {
25    /// Skip license detection entirely.
26    Disabled,
27    /// Use the embedded Provenant license dataset.
28    Embedded,
29    /// Load a custom dataset from a directory containing the expected rules and licenses layout.
30    Directory(PathBuf),
31}
32
33/// High-level configuration for in-process scans through [`scan_path`] and [`scan_paths`].
34///
35/// Defaults stay intentionally conservative: progress is quiet, no scan dimensions are enabled,
36/// input headers are omitted, and ambient `PROVENANT_CACHE` is ignored unless you set
37/// [`ScanOptions::cache_dir`].
38#[derive(Debug, Clone)]
39pub struct ScanOptions {
40    pub progress_mode: ProgressMode,
41    pub process_mode: ProcessMode,
42    pub timeout_seconds: f64,
43    pub max_depth: usize,
44    pub max_in_memory: MemoryMode,
45    pub collect_info: bool,
46    pub detect_license: LicenseSource,
47    pub detect_packages: bool,
48    pub detect_system_packages: bool,
49    pub detect_packages_in_compiled: bool,
50    pub package_only: bool,
51    pub no_assemble: bool,
52    pub detect_copyrights: bool,
53    pub detect_emails: bool,
54    pub detect_urls: bool,
55    pub detect_generated: bool,
56    pub max_emails: usize,
57    pub max_urls: usize,
58    pub include: Vec<String>,
59    pub exclude: Vec<String>,
60    pub include_input_header: bool,
61    pub cache_dir: Option<PathBuf>,
62    pub cache_clear: bool,
63    pub incremental: bool,
64    /// Opt-in trust-mtime mode for warm incremental scans.
65    ///
66    /// When `true`, a cached entry is reused on a size + mtime fingerprint match
67    /// without re-reading and re-hashing the file. Default `false` keeps the
68    /// paranoid full-hash behavior so default scans stay byte-identical.
69    pub cache_trust_mtime: bool,
70    pub reindex: bool,
71    pub no_license_index_cache: bool,
72    pub license_text: bool,
73    pub license_text_diagnostics: bool,
74    pub license_diagnostics: bool,
75    pub unknown_licenses: bool,
76    pub no_sequence_matching: bool,
77    pub license_score: u8,
78    pub filter_clues: bool,
79    pub ignore_author_patterns: Vec<String>,
80    pub ignore_copyright_holder_patterns: Vec<String>,
81    pub only_findings: bool,
82    pub mark_source: bool,
83    pub classify: bool,
84    pub summary: bool,
85    pub license_clarity_score: bool,
86    pub license_references: bool,
87    pub license_url_template: String,
88    pub license_policy: Option<PathBuf>,
89    pub tallies: bool,
90    pub tallies_key_files: bool,
91    pub tallies_with_details: bool,
92    pub facets: Vec<String>,
93    pub tallies_by_facet: bool,
94    pub strip_root: bool,
95    pub full_root: bool,
96    pub header_options: JsonMap<String, JsonValue>,
97    /// Maximum number of files to collect before the walk stops, if any.
98    ///
99    /// Untrusted callers (such as `provenant serve`) set finite ceilings to
100    /// bound denial-of-service exposure; trusted scans leave these unset.
101    pub max_files: Option<usize>,
102    /// Maximum cumulative size of collected files in bytes, if any.
103    pub max_total_bytes: Option<u64>,
104    /// Overall wall-clock budget for the collection pass in seconds, if any.
105    pub scan_deadline_seconds: Option<f64>,
106    /// When `true`, file symlinks whose target escapes the scan root are skipped
107    /// instead of being dereferenced and scanned.
108    pub restrict_out_of_tree_symlinks: bool,
109}
110
111impl Default for ScanOptions {
112    fn default() -> Self {
113        Self {
114            progress_mode: ProgressMode::Quiet,
115            process_mode: ProcessMode::default(),
116            timeout_seconds: 120.0,
117            max_depth: 0,
118            max_in_memory: MemoryMode::Limit(10_000),
119            collect_info: false,
120            detect_license: LicenseSource::Disabled,
121            detect_packages: false,
122            detect_system_packages: false,
123            detect_packages_in_compiled: false,
124            package_only: false,
125            no_assemble: false,
126            detect_copyrights: false,
127            detect_emails: false,
128            detect_urls: false,
129            detect_generated: false,
130            max_emails: 50,
131            max_urls: 50,
132            include: Vec::new(),
133            exclude: Vec::new(),
134            include_input_header: false,
135            cache_dir: None,
136            cache_clear: false,
137            incremental: false,
138            cache_trust_mtime: false,
139            reindex: false,
140            no_license_index_cache: false,
141            license_text: false,
142            license_text_diagnostics: false,
143            license_diagnostics: false,
144            unknown_licenses: false,
145            no_sequence_matching: false,
146            license_score: 0,
147            filter_clues: false,
148            ignore_author_patterns: Vec::new(),
149            ignore_copyright_holder_patterns: Vec::new(),
150            only_findings: false,
151            mark_source: false,
152            classify: false,
153            summary: false,
154            license_clarity_score: false,
155            license_references: false,
156            license_url_template: DEFAULT_LICENSEDB_URL_TEMPLATE.to_string(),
157            license_policy: None,
158            tallies: false,
159            tallies_key_files: false,
160            tallies_with_details: false,
161            facets: Vec::new(),
162            tallies_by_facet: false,
163            strip_root: false,
164            full_root: false,
165            header_options: JsonMap::new(),
166            max_files: None,
167            max_total_bytes: None,
168            scan_deadline_seconds: None,
169            restrict_out_of_tree_symlinks: false,
170        }
171    }
172}
173
174/// Scan a single native filesystem input through the supported high-level workflow facade.
175///
176/// ```
177/// use provenant::workflow::{scan_path, ScanOptions};
178/// use std::fs;
179/// use tempfile::tempdir;
180///
181/// let root = tempdir()?;
182/// let root = root.path();
183/// fs::write(root.join("README.txt"), "hello from doctest\n")?;
184///
185/// let output = scan_path(&root, &ScanOptions::default())?;
186/// assert!(output.files.iter().any(|file| file.path.ends_with("README.txt")));
187/// assert_eq!(output.headers.len(), 1);
188/// assert!(!output.headers[0].options.contains_key("input"));
189/// # Ok::<(), Box<dyn std::error::Error>>(())
190/// ```
191pub fn scan_path(path: impl AsRef<Path>, options: &ScanOptions) -> Result<Output, WorkflowError> {
192    scan_paths([path.as_ref()], options)
193}
194
195/// Scan multiple native filesystem inputs in one in-process workflow run.
196///
197/// Absolute paths are supported as long as they can be resolved through a shared scan root by the
198/// internal pipeline.
199///
200/// ```
201/// use provenant::workflow::{scan_paths, ScanOptions};
202/// use std::fs;
203/// use tempfile::tempdir;
204///
205/// let root = tempdir()?;
206/// let root = root.path();
207/// let left = root.join("left");
208/// let right = root.join("right");
209/// fs::create_dir_all(&left)?;
210/// fs::create_dir_all(&right)?;
211/// fs::write(left.join("one.txt"), "left\n")?;
212/// fs::write(right.join("two.txt"), "right\n")?;
213///
214/// let output = scan_paths([left.as_path(), right.as_path()], &ScanOptions::default())?;
215/// let paths: Vec<_> = output.files.iter().map(|file| file.path.as_str()).collect();
216/// assert!(paths.iter().any(|path| path.ends_with("one.txt")));
217/// assert!(paths.iter().any(|path| path.ends_with("two.txt")));
218/// # Ok::<(), Box<dyn std::error::Error>>(())
219/// ```
220pub fn scan_paths<'a>(
221    paths: impl IntoIterator<Item = &'a Path>,
222    options: &ScanOptions,
223) -> Result<Output, WorkflowError> {
224    let input_paths: Vec<String> = paths
225        .into_iter()
226        .map(|path| path.to_string_lossy().to_string())
227        .collect();
228
229    if input_paths.is_empty() {
230        return Err(WorkflowError::InvalidOptions(
231            "At least one input path is required".to_string(),
232        ));
233    }
234
235    let request = request_for_native_paths(input_paths, options);
236    validate_workflow_request(&request)?;
237
238    execute_request(&request)
239        .map(|executed| executed.output)
240        .map_err(WorkflowError::Pipeline)
241}
242
243fn request_for_native_paths(input_paths: Vec<String>, options: &ScanOptions) -> ScanRequest {
244    let mut header_options = options.header_options.clone();
245    if options.include_input_header {
246        header_options.insert(
247            "input".to_string(),
248            JsonValue::Array(input_paths.iter().cloned().map(JsonValue::String).collect()),
249        );
250    }
251
252    let (license, license_dataset_path) = match &options.detect_license {
253        LicenseSource::Disabled => (false, None),
254        LicenseSource::Embedded => (true, None),
255        LicenseSource::Directory(path) => (true, Some(path.to_string_lossy().to_string())),
256    };
257
258    ScanRequest {
259        input_paths,
260        input_mode: InputMode::Native,
261        output_targets: Vec::new(),
262        output_header_options: header_options,
263        progress_mode: options.progress_mode,
264        process_mode: options.process_mode,
265        timeout_seconds: options.timeout_seconds,
266        quiet: matches!(options.progress_mode, ProgressMode::Quiet),
267        verbose: matches!(options.progress_mode, ProgressMode::Verbose),
268        strip_root: options.strip_root,
269        full_root: options.full_root,
270        include: options.include.clone(),
271        exclude: options.exclude.clone(),
272        paths_files: Vec::new(),
273        respect_process_cache_env: false,
274        cache_dir: options
275            .cache_dir
276            .as_ref()
277            .map(|path| path.to_string_lossy().to_string()),
278        cache_clear: options.cache_clear,
279        incremental: options.incremental,
280        cache_trust_mtime: options.cache_trust_mtime,
281        max_depth: options.max_depth,
282        max_in_memory: options.max_in_memory,
283        info: options.collect_info,
284        package: options.detect_packages,
285        system_package: options.detect_system_packages,
286        package_in_compiled: options.detect_packages_in_compiled,
287        package_only: options.package_only,
288        no_assemble: options.no_assemble,
289        license_dataset_path,
290        reindex: options.reindex,
291        no_license_index_cache: options.no_license_index_cache,
292        license_text: options.license_text,
293        license_text_diagnostics: options.license_text_diagnostics,
294        license_diagnostics: options.license_diagnostics,
295        unknown_licenses: options.unknown_licenses,
296        no_sequence_matching: options.no_sequence_matching,
297        license_score: options.license_score,
298        license_url_template: options.license_url_template.clone(),
299        filter_clues: options.filter_clues,
300        ignore_author: options.ignore_author_patterns.clone(),
301        ignore_copyright_holder: options.ignore_copyright_holder_patterns.clone(),
302        only_findings: options.only_findings,
303        mark_source: options.mark_source,
304        classify: options.classify,
305        summary: options.summary,
306        license_clarity_score: options.license_clarity_score,
307        license_references: options.license_references,
308        license_policy: options
309            .license_policy
310            .as_ref()
311            .map(|path| path.to_string_lossy().to_string()),
312        tallies: options.tallies,
313        tallies_key_files: options.tallies_key_files,
314        tallies_with_details: options.tallies_with_details,
315        facet: options.facets.clone(),
316        tallies_by_facet: options.tallies_by_facet,
317        generated: options.detect_generated,
318        license,
319        copyright: options.detect_copyrights,
320        email: options.detect_emails,
321        max_email: options.max_emails,
322        url: options.detect_urls,
323        max_url: options.max_urls,
324        scan_bounds: crate::app::request::ScanBounds {
325            max_files: options.max_files,
326            max_total_bytes: options.max_total_bytes,
327            deadline_seconds: options.scan_deadline_seconds,
328            restrict_out_of_tree_symlinks: options.restrict_out_of_tree_symlinks,
329        },
330    }
331}
332
333fn validate_workflow_request(request: &ScanRequest) -> Result<(), WorkflowError> {
334    let license_enabled = request.license;
335
336    if request.strip_root && request.full_root {
337        return Err(WorkflowError::InvalidOptions(
338            "strip_root and full_root are mutually exclusive".to_string(),
339        ));
340    }
341
342    if request.license_text && !license_enabled {
343        return Err(WorkflowError::InvalidOptions(
344            "license_text requires detect_license".to_string(),
345        ));
346    }
347
348    if request.license_text_diagnostics && !request.license_text {
349        return Err(WorkflowError::InvalidOptions(
350            "license_text_diagnostics requires license_text".to_string(),
351        ));
352    }
353
354    if request.license_diagnostics && !license_enabled {
355        return Err(WorkflowError::InvalidOptions(
356            "license_diagnostics requires detect_license".to_string(),
357        ));
358    }
359
360    if request.unknown_licenses && !license_enabled {
361        return Err(WorkflowError::InvalidOptions(
362            "unknown_licenses requires detect_license".to_string(),
363        ));
364    }
365
366    if request.license_references && !license_enabled {
367        return Err(WorkflowError::InvalidOptions(
368            "license_references requires detect_license".to_string(),
369        ));
370    }
371
372    if request.license_url_template != DEFAULT_LICENSEDB_URL_TEMPLATE && !license_enabled {
373        return Err(WorkflowError::InvalidOptions(
374            "license_url_template requires detect_license".to_string(),
375        ));
376    }
377
378    if request.package_only && license_enabled {
379        return Err(WorkflowError::InvalidOptions(
380            "package_only cannot be combined with detect_license".to_string(),
381        ));
382    }
383
384    if request.package_only && request.summary {
385        return Err(WorkflowError::InvalidOptions(
386            "package_only cannot be combined with summary".to_string(),
387        ));
388    }
389
390    if request.package_only && request.package {
391        return Err(WorkflowError::InvalidOptions(
392            "package_only cannot be combined with detect_packages".to_string(),
393        ));
394    }
395
396    if request.package_only && request.system_package {
397        return Err(WorkflowError::InvalidOptions(
398            "package_only cannot be combined with detect_system_packages".to_string(),
399        ));
400    }
401
402    if request.summary && !request.classify {
403        return Err(WorkflowError::InvalidOptions(
404            "summary requires classify".to_string(),
405        ));
406    }
407
408    if request.license_clarity_score && !request.classify {
409        return Err(WorkflowError::InvalidOptions(
410            "license_clarity_score requires classify".to_string(),
411        ));
412    }
413
414    if request.tallies_key_files && !(request.tallies && request.classify) {
415        return Err(WorkflowError::InvalidOptions(
416            "tallies_key_files requires tallies and classify".to_string(),
417        ));
418    }
419
420    if request.tallies_by_facet && request.facet.is_empty() {
421        return Err(WorkflowError::InvalidOptions(
422            "tallies_by_facet requires at least one facet definition".to_string(),
423        ));
424    }
425
426    if request.tallies_by_facet && !request.tallies {
427        return Err(WorkflowError::InvalidOptions(
428            "tallies_by_facet requires tallies".to_string(),
429        ));
430    }
431
432    if request.mark_source && !request.info {
433        return Err(WorkflowError::InvalidOptions(
434            "mark_source requires collect_info".to_string(),
435        ));
436    }
437
438    if request.license_score > 100 {
439        return Err(WorkflowError::InvalidOptions(
440            "license_score must be between 0 and 100".to_string(),
441        ));
442    }
443
444    Ok(())
445}
446
447#[cfg(test)]
448mod tests {
449    use super::*;
450    use std::fs;
451
452    #[test]
453    fn scan_path_requires_at_least_one_input() {
454        let result = scan_paths(std::iter::empty::<&Path>(), &ScanOptions::default());
455        assert!(result.is_err());
456    }
457
458    #[test]
459    fn workflow_request_populates_input_header() {
460        let options = ScanOptions {
461            include_input_header: true,
462            ..ScanOptions::default()
463        };
464        let request = request_for_native_paths(vec!["src".to_string()], &options);
465        assert!(request.output_header_options.contains_key("input"));
466    }
467
468    #[test]
469    fn workflow_validation_rejects_license_dependent_flags_without_license() {
470        let options = ScanOptions {
471            license_references: true,
472            ..ScanOptions::default()
473        };
474
475        let request = request_for_native_paths(vec!["src".to_string()], &options);
476        let error = validate_workflow_request(&request).expect_err("validation should fail");
477        assert!(matches!(error, WorkflowError::InvalidOptions(_)));
478        assert!(
479            error
480                .to_string()
481                .contains("license_references requires detect_license")
482        );
483    }
484
485    #[test]
486    fn workflow_validation_rejects_package_only_with_regular_package_modes() {
487        let options = ScanOptions {
488            package_only: true,
489            detect_packages: true,
490            ..ScanOptions::default()
491        };
492
493        let request = request_for_native_paths(vec!["src".to_string()], &options);
494        let error = validate_workflow_request(&request).expect_err("validation should fail");
495        assert!(matches!(error, WorkflowError::InvalidOptions(_)));
496        assert!(
497            error
498                .to_string()
499                .contains("package_only cannot be combined with detect_packages")
500        );
501    }
502
503    #[test]
504    fn workflow_validation_rejects_classify_dependent_flags_without_classify() {
505        let options = ScanOptions {
506            summary: true,
507            ..ScanOptions::default()
508        };
509
510        let request = request_for_native_paths(vec!["src".to_string()], &options);
511        let error = validate_workflow_request(&request).expect_err("validation should fail");
512        assert!(matches!(error, WorkflowError::InvalidOptions(_)));
513        assert!(error.to_string().contains("summary requires classify"));
514    }
515
516    #[test]
517    fn scan_path_runs_a_basic_in_process_scan() {
518        let temp_dir = tempfile::TempDir::new().expect("create temp dir");
519        fs::write(
520            temp_dir.path().join("README.txt"),
521            "hello from workflow facade\n",
522        )
523        .expect("write fixture file");
524
525        let options = ScanOptions {
526            collect_info: true,
527            include_input_header: true,
528            ..ScanOptions::default()
529        };
530
531        let output = scan_path(temp_dir.path(), &options).expect("workflow scan should succeed");
532
533        assert_eq!(output.headers.len(), 1);
534        assert!(!output.files.is_empty());
535        assert!(output.headers[0].options.contains_key("input"));
536    }
537
538    #[test]
539    fn scan_paths_supports_multiple_absolute_inputs() {
540        let temp_dir = tempfile::TempDir::new().expect("create temp dir");
541        let left = temp_dir.path().join("left");
542        let right = temp_dir.path().join("right");
543        fs::create_dir_all(&left).expect("create left dir");
544        fs::create_dir_all(&right).expect("create right dir");
545        fs::write(left.join("one.txt"), "left\n").expect("write left fixture");
546        fs::write(right.join("two.txt"), "right\n").expect("write right fixture");
547
548        let output = scan_paths([left.as_path(), right.as_path()], &ScanOptions::default())
549            .expect("workflow scan should succeed for multiple absolute inputs");
550
551        assert!(
552            output
553                .files
554                .iter()
555                .any(|file| file.path.ends_with("one.txt"))
556        );
557        assert!(
558            output
559                .files
560                .iter()
561                .any(|file| file.path.ends_with("two.txt"))
562        );
563    }
564}
provenant/workflow.rs

provenant/
workflow.rs
