Skip to main content

resopt/
analysis.rs

1use crate::{
2    ImageDifference, ImageInfo, Policy, Resource, ResourceInventory,
3    analyze_image::{self, Context as ImageContext},
4    cache::Cache,
5    filesystem::{contained_file, hash, write_new},
6    image_backend,
7    resources::{bounded_read, inventory_with_options},
8    timings::{Phase, Timings},
9};
10use anyhow::{Context, Result, ensure};
11use serde::{Deserialize, Serialize};
12use std::{
13    collections::{BTreeMap, HashMap},
14    fs,
15    path::{Path, PathBuf},
16    sync::{
17        Arc, Condvar, Mutex, OnceLock,
18        atomic::{AtomicBool, AtomicUsize, Ordering},
19    },
20    time::Instant,
21};
22
23/// Candidate verdicts a user may accept after reviewing the actual result.
24/// Every other rejection is a hard failure that approval cannot bypass.
25pub(crate) const WARNINGS: [&str; 3] = [
26    "alpha_error_exceeds_policy",
27    "transparency_presence_changed",
28    "quality_below_policy",
29];
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
32#[serde(default, deny_unknown_fields)]
33pub struct AnalysisOptions {
34    /// Encoder quality parameters for lossy candidates; not savings percentages.
35    pub qualities: Vec<u8>,
36    pub include_ignored: bool,
37    /// Parallel image workers; 0 selects the CPU count, capped at 8.
38    pub jobs: usize,
39    /// All sizes are included by default, unlike the legacy lossless plan.
40    pub min_input_bytes: u64,
41    pub min_savings_bytes: u64,
42    pub probe_only: bool,
43    /// Lossy HEIC may quantize alpha. 0 requires exact alpha samples.
44    pub max_alpha_error: f32,
45    /// Lowest SSIMULACRA2 score a lossy candidate may have and still be
46    /// recommended. Lower-scoring candidates are kept as reviewable warnings.
47    pub min_score: f64,
48    /// Largest decoded image analyzed; each pixel costs 16 bytes per decode.
49    pub max_pixels: usize,
50    /// oxipng effort for the lossless PNG candidate.
51    pub png_level: u8,
52    /// Allow lossless PNG color-type, bit-depth and palette reductions.
53    pub png_reductions: bool,
54    /// Compare WebP candidates for loose files and Android resources. On by
55    /// default; asset-catalog renditions never receive WebP.
56    pub webp: bool,
57    /// Compare lossy PNG candidates (palette quantization) for PNG sources.
58    /// The file stays a PNG, so names, references and decoders are unaffected.
59    pub lossy_png: bool,
60    /// Also try HEIC at encoder quality 100. Apple's encoder has no lossless
61    /// mode, so this is its closest setting: still lossy, and labelled so.
62    pub heic_near_lossless: bool,
63    /// Overrides the `minSdk` detected from Gradle files.
64    pub android_min_sdk: Option<u32>,
65    /// Persistent result cache directory. `None` disables the cache; the CLI
66    /// passes the per-user cache directory unless `--no-cache` is given.
67    pub cache_dir: Option<PathBuf>,
68}
69impl Default for AnalysisOptions {
70    fn default() -> Self {
71        Self {
72            qualities: vec![75, 85, 95],
73            include_ignored: false,
74            jobs: 0,
75            min_input_bytes: 0,
76            min_savings_bytes: 1,
77            probe_only: false,
78            max_alpha_error: 1.0 / 255.0 + 0.000001,
79            min_score: 80.0,
80            max_pixels: image_backend::DEFAULT_MAX_PIXELS,
81            png_level: Policy::default().png_level,
82            png_reductions: false,
83            webp: true,
84            lossy_png: true,
85            heic_near_lossless: true,
86            android_min_sdk: None,
87            cache_dir: None,
88        }
89    }
90}
91impl AnalysisOptions {
92    pub(crate) fn validate(&self) -> Result<()> {
93        ensure!(
94            self.max_alpha_error.is_finite() && (0.0..=1.0).contains(&self.max_alpha_error),
95            "max_alpha_error must be 0..=1"
96        );
97        ensure!(
98            self.min_score.is_finite() && (0.0..=100.0).contains(&self.min_score),
99            "min_score must be 0..=100"
100        );
101        ensure!(
102            self.jobs <= 16,
103            "jobs must be 0..=16 (0 selects automatically)"
104        );
105        ensure!(
106            self.android_min_sdk.is_none_or(|v| (1..=99).contains(&v)),
107            "android_min_sdk must be 1..=99"
108        );
109        ensure!(
110            (1..=image_backend::MAX_PIXELS_LIMIT).contains(&self.max_pixels),
111            "max_pixels must be 1..={}",
112            image_backend::MAX_PIXELS_LIMIT
113        );
114        self.png_policy().validate()?;
115        ensure!(
116            !self.qualities.is_empty()
117                && self.qualities.len() <= 8
118                && self.qualities.iter().all(|q| (1..=100).contains(q)),
119            "qualities must contain 1..=8 values in 1..=100"
120        );
121        let mut qualities = self.qualities.clone();
122        qualities.sort_unstable();
123        qualities.dedup();
124        ensure!(
125            qualities.len() == self.qualities.len(),
126            "duplicate quality values"
127        );
128        Ok(())
129    }
130
131    pub(crate) fn png_policy(&self) -> Policy {
132        Policy {
133            png_level: self.png_level,
134            reductions: self.png_reductions,
135            ..Policy::default()
136        }
137    }
138
139    pub(crate) fn worker_count(&self) -> usize {
140        if self.jobs > 0 {
141            return self.jobs;
142        }
143        std::thread::available_parallelism()
144            .map_or(2, |n| n.get())
145            .clamp(1, 8)
146    }
147}
148
149#[derive(Debug, Clone, Serialize, Deserialize)]
150pub struct ImageCandidate {
151    pub format: String,
152    pub quality: Option<u8>,
153    pub lossy: bool,
154    pub bytes: u64,
155    pub savings_bytes: u64,
156    pub valid: bool,
157    pub rejection: Option<String>,
158    pub difference: Option<ImageDifference>,
159    pub artifact: Option<PathBuf>,
160    pub preview: Option<PathBuf>,
161    /// SHA-256 of the artifact, checked again before it is applied.
162    #[serde(default, skip_serializing_if = "Option::is_none")]
163    pub sha256: Option<String>,
164    /// Every visual policy threshold this candidate misses. `rejection` holds
165    /// the first one; approval must cover all of them.
166    #[serde(default, skip_serializing_if = "Vec::is_empty")]
167    pub warnings: Vec<String>,
168    /// Facts the reviewer should know, e.g. metadata a conversion does not carry.
169    #[serde(default, skip_serializing_if = "Vec::is_empty")]
170    pub notes: Vec<String>,
171}
172
173impl ImageCandidate {
174    /// A structurally sound candidate that only misses a visual policy threshold.
175    pub(crate) fn is_warning(&self) -> bool {
176        !self.valid
177            && self.lossy
178            && self.artifact.is_some()
179            && self
180                .rejection
181                .as_deref()
182                .is_some_and(|r| WARNINGS.contains(&r))
183    }
184
185    /// Warning kinds that must be approved before this candidate is applied.
186    pub(crate) fn required_warnings(&self) -> Vec<String> {
187        if !self.is_warning() {
188            vec![]
189        } else if self.warnings.is_empty() {
190            // Reports written before `warnings` existed recorded one kind.
191            self.rejection.iter().cloned().collect()
192        } else {
193            self.warnings.clone()
194        }
195    }
196}
197
198#[derive(Debug, Clone, Serialize, Deserialize)]
199pub struct ResourceAnalysis {
200    pub resource: Resource,
201    pub sha256: Option<String>,
202    pub image: Option<ImageInfo>,
203    /// `candidates_available`, `inspected`, `excluded`, `unsupported`, `failed`
204    /// or `not_analyzed` (analysis was cancelled first).
205    pub status: String,
206    pub issues: Vec<String>,
207    pub candidates: Vec<ImageCandidate>,
208    /// A size winner among candidates that passed every policy check.
209    pub smallest_candidate: Option<usize>,
210    pub original_preview: Option<PathBuf>,
211    pub original_artifact: Option<PathBuf>,
212    /// Codec, duration and bitrate of audio/video files, when ffprobe is installed.
213    #[serde(default, skip_serializing_if = "Option::is_none")]
214    pub media: Option<crate::media::MediaInfo>,
215    /// Bounded ZIP contents; entries are never extracted into the project.
216    #[serde(default, skip_serializing_if = "Option::is_none")]
217    pub archive: Option<crate::archive::ArchiveInfo>,
218    #[serde(default, skip_serializing_if = "Option::is_none")]
219    pub vap: Option<crate::vap::VapInfo>,
220    #[serde(default, skip_serializing_if = "Option::is_none")]
221    pub pag: Option<crate::pag::PagInfo>,
222    /// Translation coverage and placeholder checks of a localization file.
223    #[serde(default, skip_serializing_if = "Option::is_none")]
224    pub localization: Option<crate::localization::LocalizationInfo>,
225    /// Canvas, timing and size of an animation, when it could be parsed.
226    #[serde(default, skip_serializing_if = "Option::is_none")]
227    pub animation: Option<AnimationInfo>,
228    /// Scale-invariant fingerprint used to find duplicate and resized images.
229    #[serde(default, skip_serializing_if = "Option::is_none")]
230    pub fingerprint: Option<crate::similarity::Fingerprint>,
231}
232
233impl ResourceAnalysis {
234    pub(crate) fn new(resource: &Resource, status: &str) -> Self {
235        Self {
236            resource: resource.clone(),
237            sha256: None,
238            image: None,
239            status: status.into(),
240            issues: vec![],
241            candidates: vec![],
242            smallest_candidate: None,
243            original_preview: None,
244            original_artifact: None,
245            fingerprint: None,
246            media: None,
247            archive: None,
248            vap: None,
249            pag: None,
250            localization: None,
251            animation: None,
252        }
253    }
254
255    pub(crate) fn recommended_savings(&self) -> u64 {
256        self.smallest_candidate
257            .and_then(|i| self.candidates.get(i))
258            .filter(|c| c.valid && c.artifact.is_some())
259            .map_or(0, |c| c.savings_bytes)
260    }
261}
262
263#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
264pub struct AnimationInfo {
265    pub width: u32,
266    pub height: u32,
267    pub fps: u32,
268    pub frames: usize,
269    /// Frame shown as the thumbnail.
270    pub poster_frame: usize,
271}
272
273#[derive(Debug, Serialize, Deserialize)]
274pub struct AnalysisReport {
275    pub schema_version: u32,
276    pub root: PathBuf,
277    pub backend: String,
278    pub options: AnalysisOptions,
279    pub inventory: ResourceInventory,
280    pub resources: Vec<ResourceAnalysis>,
281    pub status_counts: BTreeMap<String, usize>,
282    /// Sum of recommended candidates only; warning candidates are excluded.
283    pub potential_source_bytes_saved: u64,
284    /// Images that show the same picture (identical, resized or near-duplicate),
285    /// excluding intended variants such as `@2x`/`@3x` or density folders.
286    #[serde(default, skip_serializing_if = "Vec::is_empty")]
287    pub similar_groups: Vec<crate::similarity::SimilarGroup>,
288    /// Analysis stopped early; unfinished resources are `not_analyzed`.
289    #[serde(default)]
290    pub cancelled: bool,
291    #[serde(default, skip_serializing_if = "Option::is_none")]
292    pub performance: Option<Performance>,
293}
294
295#[derive(Debug, Clone, Default, Serialize, Deserialize)]
296pub struct Performance {
297    pub wall_seconds: f64,
298    pub first_result_seconds: Option<f64>,
299    pub workers: usize,
300    pub cache_hits: usize,
301    pub duplicate_reuses: usize,
302    /// Seconds per phase summed over workers (CPU-side, not wall-clock).
303    pub phase_seconds: BTreeMap<String, f64>,
304}
305
306/// Cooperative cancellation shared with the caller.
307#[derive(Clone, Default)]
308pub struct AnalysisControl(Arc<AtomicBool>);
309impl AnalysisControl {
310    pub fn cancel(&self) {
311        self.0.store(true, Ordering::SeqCst);
312    }
313    pub fn is_cancelled(&self) -> bool {
314        self.0.load(Ordering::SeqCst)
315    }
316}
317
318/// Bounds decoded source pixels in flight to one maximum-size image, so adding
319/// workers speeds up ordinary assets without multiplying peak memory.
320pub(crate) struct PixelBudget {
321    capacity: usize,
322    available: Mutex<usize>,
323    released: Condvar,
324}
325pub(crate) struct PixelLease<'a>(&'a PixelBudget, usize);
326impl PixelBudget {
327    pub fn new(capacity: usize) -> Self {
328        Self {
329            capacity,
330            available: Mutex::new(capacity),
331            released: Condvar::new(),
332        }
333    }
334    pub fn acquire(&self, pixels: usize) -> PixelLease<'_> {
335        let wanted = pixels.clamp(1, self.capacity);
336        let mut available = self.available.lock().unwrap_or_else(|e| e.into_inner());
337        while *available < wanted {
338            available = self
339                .released
340                .wait(available)
341                .unwrap_or_else(|e| e.into_inner());
342        }
343        *available -= wanted;
344        PixelLease(self, wanted)
345    }
346}
347impl Drop for PixelLease<'_> {
348    fn drop(&mut self) {
349        *self.0.available.lock().unwrap_or_else(|e| e.into_inner()) += self.1;
350        self.0.released.notify_all();
351    }
352}
353
354/// Read-only analysis of all inventoried resources, with lossy candidates staged
355/// solely for review. This report is deliberately not an executable apply plan.
356pub fn analyze(
357    root: impl AsRef<Path>,
358    out: impl AsRef<Path>,
359    options: AnalysisOptions,
360) -> Result<AnalysisReport> {
361    analyze_with_progress(root, out, options, |_, _| {})
362}
363
364pub fn analyze_with_progress(
365    root: impl AsRef<Path>,
366    out: impl AsRef<Path>,
367    options: AnalysisOptions,
368    progress: impl Fn(usize, usize) + Sync,
369) -> Result<AnalysisReport> {
370    analyze_with_observer(
371        root,
372        out,
373        options,
374        &AnalysisControl::default(),
375        |_, _, done, total| progress(done, total),
376    )
377}
378
379type Shared = Arc<OnceLock<(usize, ResourceAnalysis)>>;
380
381pub(crate) fn analyze_with_observer(
382    root: impl AsRef<Path>,
383    out: impl AsRef<Path>,
384    options: AnalysisOptions,
385    control: &AnalysisControl,
386    progress: impl Fn(usize, &ResourceAnalysis, usize, usize) + Sync,
387) -> Result<AnalysisReport> {
388    let started = Instant::now();
389    options.validate()?;
390    if !options.probe_only && image_backend::image_backend_available() {
391        image_backend::check_encoders()?;
392    }
393    let timings = Timings::default();
394    let inventory = timings.time(Phase::Scan, || {
395        inventory_with_options(
396            root,
397            crate::ScanOptions {
398                include_ignored: options.include_ignored,
399            },
400        )
401    })?;
402    let out = out.as_ref();
403    let parent = fs::canonicalize(
404        out.parent()
405            .filter(|p| !p.as_os_str().is_empty())
406            .unwrap_or(Path::new(".")),
407    )?;
408    let out = parent.join(out.file_name().context("output directory has no name")?);
409    ensure!(
410        !out.starts_with(&inventory.root),
411        "analysis output must be outside the scanned project"
412    );
413    fs::create_dir(&out).context("analysis output must be a new directory")?;
414    for folder in ["candidates", "previews", "originals"] {
415        fs::create_dir(out.join(folder))?;
416    }
417    if inventory
418        .assets
419        .iter()
420        .any(|r| matches!(r.format.as_str(), "pag" | "tcmp4"))
421    {
422        crate::pag::write_runtime(&out)?;
423    }
424    let cache = options
425        .cache_dir
426        .as_ref()
427        .filter(|_| !options.probe_only)
428        .and_then(|directory| Cache::open(directory).ok());
429    let min_sdk = options
430        .android_min_sdk
431        .or(inventory.android_min_sdk.as_ref().map(|sdk| sdk.level));
432    let workers = options.worker_count();
433    let budget = PixelBudget::new(options.max_pixels);
434    let context = ImageContext {
435        root: &inventory.root,
436        out: &out,
437        options: &options,
438        min_sdk,
439        timings: &timings,
440        control,
441        budget: &budget,
442    };
443    let total = inventory.assets.len();
444    let complete = AtomicUsize::new(0);
445    let cache_hits = AtomicUsize::new(0);
446    let duplicate_reuses = AtomicUsize::new(0);
447    let first_result = OnceLock::new();
448    let in_flight: Mutex<HashMap<String, Shared>> = Mutex::new(HashMap::new());
449    let finish = |index: usize, result: ResourceAnalysis| {
450        if result.status == "candidates_available" {
451            first_result.get_or_init(|| started.elapsed().as_secs_f64());
452        }
453        let done = complete.fetch_add(1, Ordering::Relaxed) + 1;
454        progress(index, &result, done, total);
455        (index, result)
456    };
457
458    // Rows that need no image work are published first so the inventory is
459    // visible immediately; images follow largest-first because they hold most
460    // of the savings.
461    // Localization files are compared across languages, so they are parsed
462    // together on one thread next to the image workers.
463    let (localization, rest): (Vec<usize>, Vec<usize>) =
464        (0..total).partition(|&index| crate::localization::is_candidate(&inventory.assets[index]));
465    let (mut work, settled): (Vec<usize>, Vec<usize>) = rest.into_iter().partition(|&index| {
466        let resource = &inventory.assets[index];
467        resource.support == "optimizable"
468            || matches!(
469                resource.format.as_str(),
470                "zip" | "mp4" | "vap" | "pag" | "tcmp4"
471            )
472            || (resource.kind == "image" && options.probe_only)
473            || (is_media(resource) && crate::media::ffprobe_available())
474    });
475    work.sort_by_key(|&index| std::cmp::Reverse(inventory.assets[index].bytes));
476    let mut indexed: Vec<(usize, ResourceAnalysis)> = settled
477        .into_iter()
478        .map(|index| finish(index, settled_row(&inventory.assets[index])))
479        .collect();
480
481    let analyze_one = |index: usize| -> ResourceAnalysis {
482        let resource = &inventory.assets[index];
483        if control.is_cancelled() {
484            return ResourceAnalysis::new(resource, "not_analyzed");
485        }
486        if is_media(resource) && resource.format != "mp4" {
487            // Inspection only: spawning ffprobe runs on the worker pool so it
488            // never delays image results.
489            let mut row = settled_row(resource);
490            if let Ok(path) = contained_file(&inventory.root, &resource.path) {
491                row.media = timings.time(Phase::Decode, || crate::media::probe(&path));
492            }
493            return row;
494        }
495        let read = timings.time(Phase::Hash, || {
496            contained_file(&inventory.root, &resource.path)
497                .and_then(|path| bounded_read(&path))
498                .map(|bytes| {
499                    let digest = hash(&bytes);
500                    (bytes, digest)
501                })
502        });
503        let (bytes, digest) = match read {
504            Ok(read) => read,
505            Err(error) => {
506                let mut failed = ResourceAnalysis::new(resource, "failed");
507                failed.issues.push(format!("{error:#}"));
508                return failed;
509            }
510        };
511        if matches!(resource.format.as_str(), "pag" | "tcmp4") {
512            let mut row = ResourceAnalysis::new(resource, "inspected");
513            row.sha256 = Some(digest);
514            match crate::pag::inspect(&bytes) {
515                Ok(info) => {
516                    row.resource.kind = "animation".into();
517                    row.resource.format = "pag".into();
518                    let artifact = PathBuf::from(format!("originals/{index}.pag"));
519                    match write_new(&out.join(&artifact), &bytes) {
520                        Ok(()) => row.original_artifact = Some(artifact),
521                        Err(error) => row.issues.push(format!("preview_unavailable: {error:#}")),
522                    }
523                    row.pag = Some(info);
524                }
525                Err(error) => {
526                    row.status = "failed".into();
527                    row.issues.push(format!("{error:#}"));
528                }
529            }
530            return row;
531        }
532        if matches!(resource.format.as_str(), "mp4" | "vap") {
533            let mut row = settled_row(resource);
534            row.sha256 = Some(digest);
535            match crate::vap::inspect(&bytes) {
536                Ok(Some(info)) => {
537                    row.issues.clear();
538                    row.status = "inspected".into();
539                    row.resource.kind = "animation".into();
540                    row.resource.format = "vap".into();
541                    let artifact = PathBuf::from(format!("originals/{index}.mp4"));
542                    match write_new(&out.join(&artifact), &bytes) {
543                        Ok(()) => row.original_artifact = Some(artifact),
544                        Err(error) => row.issues.push(format!("preview_unavailable: {error:#}")),
545                    }
546                    row.vap = Some(info);
547                }
548                Ok(None) => {
549                    if let Ok(path) = contained_file(&inventory.root, &resource.path) {
550                        row.media = crate::media::probe(&path);
551                    }
552                }
553                Err(error) => {
554                    row.status = "failed".into();
555                    row.issues.push(format!("{error:#}"));
556                }
557            }
558            return row;
559        }
560        // Archive previews have their own entry paths; do not reuse image-cache manifests.
561        if resource.format == "zip" {
562            return crate::archive::analyze(&context, resource, index, &bytes, &digest);
563        }
564        let compute = |own_index: usize| {
565            #[cfg(target_os = "macos")]
566            {
567                objc2::rc::autoreleasepool(|_| {
568                    analyze_image::analyze(&context, resource, own_index, &bytes, &digest)
569                })
570            }
571            #[cfg(not(target_os = "macos"))]
572            {
573                analyze_image::analyze(&context, resource, own_index, &bytes, &digest)
574            }
575        };
576        if options.probe_only {
577            return compute(index);
578        }
579        let key = match Cache::key(
580            &digest,
581            &analyze_image::policy_key(resource, min_sdk),
582            &options,
583        ) {
584            Ok(key) => key,
585            Err(_) => return compute(index),
586        };
587        // Identical content under an identical policy is analyzed once per run.
588        let slot = in_flight
589            .lock()
590            .unwrap_or_else(|e| e.into_inner())
591            .entry(key.clone())
592            .or_default()
593            .clone();
594        let mut computed_here = false;
595        let (owner, shared) = slot.get_or_init(|| {
596            computed_here = true;
597            if let Some(cache) = &cache
598                && let Some(mut hit) = timings.time(Phase::Cache, || cache.load(&key, &out, index))
599                && restore_original_artifact(&mut hit, &out, index, &bytes, resource).is_ok()
600            {
601                cache_hits.fetch_add(1, Ordering::Relaxed);
602                hit.resource = resource.clone();
603                return (index, hit);
604            }
605            let result = compute(index);
606            if let Some(cache) = &cache
607                && matches!(result.status.as_str(), "candidates_available" | "inspected")
608            {
609                let _ = timings.time(Phase::Cache, || cache.store(&key, &result, &out, index));
610            }
611            (index, result)
612        });
613        if computed_here || *owner == index {
614            return shared.clone();
615        }
616        if matches!(shared.status.as_str(), "failed" | "not_analyzed") {
617            return compute(index);
618        }
619        duplicate_reuses.fetch_add(1, Ordering::Relaxed);
620        let mut reused = shared.clone();
621        reused.resource = resource.clone();
622        reused
623    };
624    // Plain threads pulling from a shared queue, not a rayon pool: oxipng uses
625    // rayon internally, and a rayon worker that waits on nested work runs other
626    // queued tasks on the same stack. With a task already holding a pixel lease
627    // or initializing a shared duplicate slot, that re-entrancy deadlocked.
628    let next = AtomicUsize::new(0);
629    let finished = Mutex::new(Vec::with_capacity(work.len()));
630    std::thread::scope(|scope| {
631        if !localization.is_empty() {
632            scope.spawn(|| {
633                let rows = timings.time(Phase::Localization, || {
634                    localization_rows(&inventory, &localization, control)
635                });
636                let rows: Vec<_> = rows
637                    .into_iter()
638                    .map(|(index, row)| finish(index, row))
639                    .collect();
640                finished
641                    .lock()
642                    .unwrap_or_else(|e| e.into_inner())
643                    .extend(rows);
644            });
645        }
646        for _ in 0..workers.min(work.len()).max(1) {
647            scope.spawn(|| {
648                while let Some(&index) = work.get(next.fetch_add(1, Ordering::Relaxed)) {
649                    let done = finish(index, analyze_one(index));
650                    finished
651                        .lock()
652                        .unwrap_or_else(|e| e.into_inner())
653                        .push(done);
654                }
655            });
656        }
657    });
658    indexed.extend(finished.into_inner().unwrap_or_else(|e| e.into_inner()));
659    indexed.sort_by_key(|(index, _)| *index);
660    let resources: Vec<_> = indexed.into_iter().map(|(_, result)| result).collect();
661    let mut status_counts = BTreeMap::new();
662    let mut savings = 0;
663    for resource in &resources {
664        *status_counts.entry(resource.status.clone()).or_insert(0) += 1;
665        savings += resource.recommended_savings();
666    }
667    if let Some(cache) = &cache {
668        let _ = cache.prune(crate::cache::DEFAULT_MAX_BYTES);
669    }
670    let similar_groups = crate::similarity::group(&resources);
671    // Fingerprints exist for grouping (and the cache); the report keeps the groups.
672    let resources: Vec<_> = resources
673        .into_iter()
674        .map(|resource| ResourceAnalysis {
675            fingerprint: None,
676            ..resource
677        })
678        .collect();
679    let mut report = AnalysisReport {
680        schema_version: 2,
681        root: inventory.root.clone(),
682        backend: if image_backend::image_backend_available() {
683            "Apple ImageIO + CoreGraphics sRGB float comparison; bundled oxipng and libwebp"
684        } else {
685            "Portable PNG and WebP (bundled oxipng and libwebp); JPEG/HEIC require macOS"
686        }
687        .into(),
688        options,
689        inventory,
690        resources,
691        status_counts,
692        potential_source_bytes_saved: savings,
693        similar_groups,
694        cancelled: control.is_cancelled(),
695        performance: None,
696    };
697    let html = timings.time(Phase::Report, || crate::report::render_html(&report))?;
698    report.performance = Some(Performance {
699        wall_seconds: started.elapsed().as_secs_f64(),
700        first_result_seconds: first_result.get().copied(),
701        workers,
702        cache_hits: cache_hits.load(Ordering::Relaxed),
703        duplicate_reuses: duplicate_reuses.load(Ordering::Relaxed),
704        phase_seconds: timings.snapshot(),
705    });
706    write_new(&out.join("analysis.json"), &serde_json::to_vec(&report)?)?;
707    write_new(&out.join("report.html"), html.as_bytes())?;
708    Ok(report)
709}
710
711/// Rows for localization candidates. Files that turn out not to hold strings
712/// get their ordinary inventory row.
713fn localization_rows(
714    inventory: &ResourceInventory,
715    indexes: &[usize],
716    control: &AnalysisControl,
717) -> Vec<(usize, ResourceAnalysis)> {
718    use crate::localization::{Parsed, parse, rows};
719    // Tables span files, so a stop request applies to the whole pass: a
720    // partial table would compare languages against the wrong source.
721    if control.is_cancelled() {
722        return indexes
723            .iter()
724            .map(|&index| {
725                (
726                    index,
727                    ResourceAnalysis::new(&inventory.assets[index], "not_analyzed"),
728                )
729            })
730            .collect();
731    }
732    let mut parsed = vec![];
733    let mut other = vec![];
734    for &index in indexes {
735        let resource = &inventory.assets[index];
736        match parse(&inventory.root, resource, index) {
737            Parsed::File(file) => parsed.push(file),
738            Parsed::NotLocalization => other.push((index, settled_row(resource))),
739            Parsed::Unsupported(reason) => {
740                let mut row = ResourceAnalysis::new(resource, "unsupported");
741                row.issues.push(reason);
742                other.push((index, row));
743            }
744            Parsed::Failed(error) => {
745                let mut failed = ResourceAnalysis::new(resource, "failed");
746                failed.issues.push(error);
747                other.push((index, failed));
748            }
749        }
750    }
751    other.extend(rows(&inventory.assets, parsed));
752    other
753}
754
755fn is_media(resource: &Resource) -> bool {
756    matches!(resource.kind.as_str(), "audio" | "video") && resource.conversion_exclusion.is_none()
757}
758
759/// Inventory rows that need no decoding.
760fn settled_row(resource: &Resource) -> ResourceAnalysis {
761    if let Some(reason) = &resource.conversion_exclusion {
762        let mut row = ResourceAnalysis::new(resource, "excluded");
763        row.issues.push(reason.clone());
764        return row;
765    }
766    let mut row = ResourceAnalysis::new(resource, "unsupported");
767    if is_media(resource) && !crate::media::ffprobe_available() {
768        row.issues.push("ffprobe_not_installed".into());
769    }
770    row.issues.push(if resource.kind == "image" {
771        format!("{}_decoding_requires_macos_imageio", resource.format)
772    } else {
773        format!("{}_optimization_backend_not_implemented", resource.kind)
774    });
775    row
776}
777
778/// Cached entries omit the original artifact because it is the source itself.
779fn restore_original_artifact(
780    hit: &mut ResourceAnalysis,
781    out: &Path,
782    index: usize,
783    bytes: &[u8],
784    resource: &Resource,
785) -> Result<()> {
786    if hit.status == "candidates_available" {
787        let artifact = PathBuf::from(format!("originals/{index}.{}", resource.format));
788        crate::filesystem::write_artifact(&out.join(&artifact), bytes)?;
789        hit.original_artifact = Some(artifact);
790    }
791    Ok(())
792}
793
794#[cfg(test)]
795mod tests {
796    use super::*;
797
798    #[test]
799    fn pixel_budget_serializes_oversized_work_without_deadlock() {
800        let budget = PixelBudget::new(100);
801        let peak = AtomicUsize::new(0);
802        let current = AtomicUsize::new(0);
803        std::thread::scope(|scope| {
804            for _ in 0..6 {
805                scope.spawn(|| {
806                    // Requests above capacity are clamped instead of waiting forever.
807                    let _lease = budget.acquire(1_000);
808                    let now = current.fetch_add(1, Ordering::SeqCst) + 1;
809                    peak.fetch_max(now, Ordering::SeqCst);
810                    std::thread::sleep(std::time::Duration::from_millis(5));
811                    current.fetch_sub(1, Ordering::SeqCst);
812                });
813            }
814        });
815        assert_eq!(peak.load(Ordering::SeqCst), 1);
816        let _a = budget.acquire(60);
817        let _b = budget.acquire(40);
818    }
819
820    #[test]
821    fn options_reject_out_of_range_policy_values() {
822        for options in [
823            AnalysisOptions {
824                min_score: 101.0,
825                ..Default::default()
826            },
827            AnalysisOptions {
828                min_score: f64::NAN,
829                ..Default::default()
830            },
831            AnalysisOptions {
832                jobs: 17,
833                ..Default::default()
834            },
835            AnalysisOptions {
836                android_min_sdk: Some(0),
837                ..Default::default()
838            },
839        ] {
840            assert!(options.validate().is_err());
841        }
842        assert!(AnalysisOptions::default().validate().is_ok());
843        assert!((1..=8).contains(&AnalysisOptions::default().worker_count()));
844    }
845}