Skip to main content

alpha2_model/
lint.rs

1//! Non-fatal diagnostics: what a valid project probably does not mean to do.
2//!
3//! [`Project::lint`] never refuses a project. Checks are conservative: every reported issue
4//! is certain, and a missed one is not an error.
5
6use crate::animation::Keyed;
7use crate::{
8    Animated, AnimatedPoint, ClipId, CompositionId, Generator, MediaKind, NodeId, Paint, Project,
9    ShapeGeometry, ShapeItem, TrackId, TrackKind,
10};
11use alpha2_media::SourceId;
12use alpha2_time::{FrameRate, MediaTime, TICKS_PER_SECOND, TimeRange};
13use serde::Serialize;
14use std::collections::{HashMap, HashSet};
15
16/// Something in a project that is valid but probably not meant.
17#[derive(Clone, Debug, PartialEq, Serialize)]
18#[serde(tag = "kind", rename_all = "snake_case")]
19#[non_exhaustive]
20pub enum LintIssue {
21    /// A keyframe that no shown time depends on, checked in the owner's own time (timeline,
22    /// composition, or picture time).
23    UnreachedKeyframe {
24        /// What the keyframe animates.
25        owner: LintOwner,
26        /// The animated property as a path, such as `visual.opacity`, `masks[0].feather`,
27        /// `effect.params.radius` or `items[0].transform.opacity`.
28        property: String,
29        /// The keyframe's time.
30        time: MediaTime,
31    },
32    /// A clip wholly covered for its whole time by an opaque full-frame clip on a later track.
33    /// Matte clips are never reported, since they are never composited.
34    HiddenClip {
35        /// The covered clip.
36        clip: ClipId,
37        /// The clip that covers it.
38        by: ClipId,
39    },
40    /// A transition no project frame shows as a mix: shorter than a frame, or about a frame long
41    /// and starting between frames.
42    ShortTransition {
43        /// Its track.
44        track: TrackId,
45        /// Its first clip.
46        from_clip: ClipId,
47        /// Its second clip.
48        to_clip: ClipId,
49    },
50    /// A boundary that is not where a project frame starts, so the change shows at the next
51    /// frame. A frame starts at its exact start rounded down to a tick.
52    OffFrameBoundary {
53        /// Whose boundary.
54        owner: LintOwner,
55        /// Which end.
56        edge: LintEdge,
57        /// The boundary's time.
58        time: MediaTime,
59    },
60    /// A source no render reads: no clip shows it and no `media` node of a shown composition
61    /// reads it.
62    UnusedSource {
63        /// The source.
64        source: SourceId,
65    },
66    /// A high-dynamic-range source in a project whose color pipeline refuses HDR, so rendering
67    /// it fails.
68    HdrSource {
69        /// The source.
70        source: SourceId,
71    },
72    /// A path's subpath without vertices, which draws nothing.
73    EmptySubpath {
74        /// The shapes generator.
75        owner: ShapeLintOwner,
76        /// The empty subpath, like `items[0].path.subpaths[1]` or, in a layout,
77        /// `root.children[0].shape.items[0].path.subpaths[1]`.
78        at: String,
79    },
80    /// A fill or stroke with no geometry before it in its group, which paints nothing.
81    PaintWithoutGeometry {
82        /// The shapes generator.
83        owner: ShapeLintOwner,
84        /// The paint item, like `items[1].items[0]`.
85        at: String,
86    },
87    /// A caption style no cue names and no cue's speaker matches.
88    UnusedCaptionStyle {
89        /// The caption track.
90        track: TrackId,
91        /// The style's name.
92        style: String,
93    },
94    /// A source-anchored data set made from other media: its `made_from` differs from its
95    /// source's current fingerprint ([`Project::stale_data`], where the host compares), or one of
96    /// its times is past the duration its source's fingerprint records ([`Project::lint`]).
97    StaleData {
98        /// The data set.
99        data: crate::DataSetId,
100        /// Its source.
101        source: SourceId,
102    },
103    /// A text animator that sets no property, which changes nothing.
104    EmptyTextAnimator {
105        /// What holds the text.
106        owner: LintOwner,
107        /// The animator, like `style.animators[0]` or, in a layout,
108        /// `root.children[1].text_animators[0]`.
109        at: String,
110    },
111}
112
113/// The shapes or layout generator a shape [`LintIssue`] is about.
114#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
115#[serde(tag = "type", rename_all = "snake_case")]
116#[non_exhaustive]
117pub enum ShapeLintOwner {
118    /// A generated source's.
119    Source {
120        /// The source.
121        source: SourceId,
122    },
123    /// A composition's generator node's.
124    Node {
125        /// The composition.
126        composition: CompositionId,
127        /// The node.
128        node: NodeId,
129    },
130}
131
132/// What a [`LintIssue`] is about.
133#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
134#[serde(tag = "type", rename_all = "snake_case")]
135#[non_exhaustive]
136pub enum LintOwner {
137    /// A clip.
138    Clip {
139        /// The clip.
140        clip: ClipId,
141    },
142    /// A transition.
143    Transition {
144        /// Its track.
145        track: TrackId,
146        /// Its first clip.
147        from_clip: ClipId,
148        /// Its second clip.
149        to_clip: ClipId,
150    },
151    /// A caption cue.
152    Cue {
153        /// Its caption track.
154        track: TrackId,
155        /// Its position among the track's cues.
156        index: usize,
157    },
158    /// A composition's node, whose settings are keyed in composition time.
159    CompositionNode {
160        /// The composition.
161        composition: CompositionId,
162        /// The node.
163        node: NodeId,
164    },
165    /// A generated source, whose shapes or layout tree is keyed in picture time.
166    Source {
167        /// The source.
168        source: SourceId,
169    },
170    /// A caption track, whose style's animators are keyed in each cue's time from its start.
171    CaptionTrack {
172        /// The track.
173        track: TrackId,
174    },
175    /// A timed run of a caption cue, whose times are from the cue's start.
176    CueRun {
177        /// Its caption track.
178        track: TrackId,
179        /// Its cue's position among the track's cues.
180        cue: usize,
181        /// Its position among the cue's runs.
182        run: usize,
183    },
184}
185
186/// The end of a range a [`LintIssue`] is about.
187#[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize)]
188#[serde(rename_all = "snake_case")]
189pub enum LintEdge {
190    /// The start.
191    Start,
192    /// The end.
193    End,
194}
195
196impl Project {
197    /// [`LintIssue::StaleData`] for each source-anchored data set with a `made_from` that
198    /// `is_stale` judges different from its source's current fingerprint, in data order.
199    /// Hosts pass their fingerprint comparison; the model holds no current fingerprints.
200    #[must_use]
201    pub fn stale_data(
202        &self,
203        mut is_stale: impl FnMut(&SourceId, &crate::MediaFingerprint) -> bool,
204    ) -> Vec<LintIssue> {
205        self.data
206            .iter()
207            .filter_map(|set| {
208                let source = set.anchor.source()?;
209                let made_from = set.made_from.as_ref()?;
210                is_stale(source, made_from).then(|| LintIssue::StaleData {
211                    data: set.id.clone(),
212                    source: source.clone(),
213                })
214            })
215            .collect()
216    }
217
218    /// Diagnostics that do not stop the project rendering, in a fixed order: unused sources,
219    /// shapes generators (sources', then composition nodes'), HDR sources, each track's clips,
220    /// transitions and cues, composition nodes, then generated sources' trees.
221    #[must_use]
222    pub fn lint(&self) -> Vec<LintIssue> {
223        let mut issues = Vec::new();
224        let used = self
225            .used_sources()
226            .into_iter()
227            .map(|source| &source.id)
228            .collect::<std::collections::HashSet<_>>();
229        for source in &self.sources {
230            if !used.contains(&source.id) {
231                issues.push(LintIssue::UnusedSource {
232                    source: source.id.clone(),
233                });
234            }
235        }
236        self.lint_shapes(&mut issues);
237        let refused = self.settings.color.hdr == crate::HdrSources::Reject;
238        for source in self.hdr_sources().into_iter().filter(|_| refused) {
239            issues.push(LintIssue::HdrSource {
240                source: source.clone(),
241            });
242        }
243        let mattes = self
244            .timeline
245            .tracks
246            .iter()
247            .flat_map(|track| &track.clips)
248            .filter_map(|clip| clip.matte.as_ref().map(|matte| &matte.source))
249            .collect::<HashSet<_>>();
250        let grid = FrameGrid::new(self);
251        let covers = self.covering_clips(&mattes);
252        for (order, track) in self.timeline.tracks.iter().enumerate() {
253            for clip in &track.clips {
254                let owner = LintOwner::Clip {
255                    clip: clip.id.clone(),
256                };
257                grid.check(&owner, clip.timeline_range, &mut issues);
258                let mut keyframes = Keyframes {
259                    owner: &owner,
260                    shown: &[span(clip.timeline_range)],
261                    issues: &mut issues,
262                };
263                keyframes.check_clip(clip);
264                if track.kind == TrackKind::Video
265                    && !mattes.contains(&clip.id)
266                    && let Some(by) = covering_clip(&covers, order, clip.timeline_range)
267                {
268                    issues.push(LintIssue::HiddenClip {
269                        clip: clip.id.clone(),
270                        by: by.clone(),
271                    });
272                }
273            }
274            for transition in &track.transitions {
275                let owner = LintOwner::Transition {
276                    track: track.id.clone(),
277                    from_clip: transition.from_clip.clone(),
278                    to_clip: transition.to_clip.clone(),
279                };
280                if !grid.shows_mixed(transition.timeline_range) {
281                    issues.push(LintIssue::ShortTransition {
282                        track: track.id.clone(),
283                        from_clip: transition.from_clip.clone(),
284                        to_clip: transition.to_clip.clone(),
285                    });
286                }
287                grid.check(&owner, transition.timeline_range, &mut issues);
288                let mut keyframes = Keyframes {
289                    owner: &owner,
290                    shown: &[span(transition.timeline_range)],
291                    issues: &mut issues,
292                };
293                for (name, value) in &transition.effect.params {
294                    keyframes.check(&format!("effect.params.{name}"), value);
295                }
296            }
297            lint_cues(&grid, track, &mut issues);
298            if let Some(captions) = &track.captions {
299                lint_caption_animators(&track.id, captions, &mut issues);
300            }
301        }
302        self.lint_keyframes_in_other_times(&mut issues);
303        self.lint_text_animators(&mut issues);
304        self.lint_data_past_its_source(&mut issues);
305        issues
306    }
307
308    /// Every source-anchored data set with a time past its source's recorded duration.
309    fn lint_data_past_its_source(&self, issues: &mut Vec<LintIssue>) {
310        for set in &self.data {
311            let Some(source) = set.anchor.source() else {
312                continue;
313            };
314            let duration = self
315                .sources
316                .iter()
317                .find(|candidate| &candidate.id == source)
318                .and_then(|source| source.fingerprint.as_ref()?.duration_ticks);
319            if let (Some(duration), Some(last)) = (duration, set.last_time())
320                && last.ticks() > duration
321            {
322                issues.push(LintIssue::StaleData {
323                    data: set.id.clone(),
324                    source: source.clone(),
325                });
326            }
327        }
328    }
329
330    /// Every text animator that sets nothing, in text generators and layout text nodes.
331    fn lint_text_animators(&self, issues: &mut Vec<LintIssue>) {
332        let lint =
333            |owner: &LintOwner, generator: &Generator, at: &str, issues: &mut Vec<LintIssue>| {
334                match generator {
335                    Generator::Text { style, .. } => {
336                        empty_animators(
337                            owner,
338                            &style.animators,
339                            &format!("{at}style.animators"),
340                            issues,
341                        );
342                    }
343                    Generator::Layout { root } => root.walk(|path, node| {
344                        empty_animators(
345                            owner,
346                            &node.text_animators,
347                            &format!("{at}{path}.text_animators"),
348                            issues,
349                        );
350                    }),
351                    Generator::Fill { .. } | Generator::Shapes { .. } => {}
352                }
353            };
354        for source in &self.sources {
355            if let Some(generator) = &source.generator {
356                let owner = LintOwner::Source {
357                    source: source.id.clone(),
358                };
359                lint(&owner, generator, "", issues);
360            }
361        }
362        for composition in &self.compositions {
363            for node in &composition.nodes {
364                if let crate::NodeOp::Generator { generator } = &node.op {
365                    let owner = LintOwner::CompositionNode {
366                        composition: composition.id.clone(),
367                        node: node.id.clone(),
368                    };
369                    lint(&owner, generator, "generator.", issues);
370                }
371            }
372        }
373    }
374
375    /// Unreached keyframes in the other two time bases: composition nodes' settings in
376    /// composition time and generated sources' trees in picture time. Compositions or sources
377    /// that no clip shows, or whose shown times cannot be bounded, are skipped.
378    fn lint_keyframes_in_other_times(&self, issues: &mut Vec<LintIssue>) {
379        let shown = Shown::of(self);
380        for composition in &self.compositions {
381            let Some(spans) = shown.compositions.get(&composition.id) else {
382                continue;
383            };
384            for node in &composition.nodes {
385                let owner = LintOwner::CompositionNode {
386                    composition: composition.id.clone(),
387                    node: node.id.clone(),
388                };
389                let mut keyframes = Keyframes {
390                    owner: &owner,
391                    shown: spans,
392                    issues,
393                };
394                node_keyed(&node.op, &mut |property, keyed| {
395                    if let Keyed::Times(times) = keyed {
396                        keyframes.check_times(property, times);
397                    }
398                });
399            }
400        }
401        for source in &self.sources {
402            let Some(spans) = shown.sources.get(&source.id) else {
403                continue;
404            };
405            let owner = LintOwner::Source {
406                source: source.id.clone(),
407            };
408            let mut keyframes = Keyframes {
409                owner: &owner,
410                shown: spans,
411                issues,
412            };
413            let mut check = |property: &str, keyed: Keyed<'_>| {
414                if let Keyed::Times(times) = keyed {
415                    keyframes.check_times(property, times);
416                }
417            };
418            match &source.generator {
419                Some(Generator::Shapes { items }) => {
420                    crate::shapes::for_each_keyed_item(items, "items", &mut check);
421                }
422                Some(Generator::Layout { root }) => root.for_each_keyed("root", &mut check),
423                Some(Generator::Text { style, .. }) => {
424                    crate::text_animation::for_each_keyed_animator(
425                        &style.animators,
426                        "style.animators",
427                        &mut check,
428                    );
429                }
430                _ => {}
431            }
432        }
433    }
434
435    /// Empty subpaths and paints without geometry in every shapes generator and layout shape
436    /// node: sources' first, then composition nodes'.
437    fn lint_shapes(&self, issues: &mut Vec<LintIssue>) {
438        let lint = |owner: &ShapeLintOwner, generator: &Generator, issues: &mut Vec<LintIssue>| {
439            match generator {
440                Generator::Shapes { items } => {
441                    lint_shape_items(owner, items, "items", issues);
442                }
443                Generator::Layout { root } => root.walk(|at, node| {
444                    if let Some(shape) = &node.shape {
445                        lint_shape_items(owner, &shape.items, &format!("{at}.shape.items"), issues);
446                    }
447                }),
448                Generator::Fill { .. } | Generator::Text { .. } => {}
449            }
450        };
451        for source in &self.sources {
452            if let Some(generator) = &source.generator {
453                let owner = ShapeLintOwner::Source {
454                    source: source.id.clone(),
455                };
456                lint(&owner, generator, issues);
457            }
458        }
459        for composition in &self.compositions {
460            for node in &composition.nodes {
461                if let crate::NodeOp::Generator { generator } = &node.op {
462                    let owner = ShapeLintOwner::Node {
463                        composition: composition.id.clone(),
464                        node: node.id.clone(),
465                    };
466                    lint(&owner, generator, issues);
467                }
468            }
469        }
470    }
471
472    /// The video-track clips that certainly cover the whole frame opaquely outside their
473    /// transitions: composited (not a matte) and [`is_opaque_full_frame`]. In track then clip
474    /// order.
475    fn covering_clips<'a>(&'a self, mattes: &HashSet<&ClipId>) -> Vec<Cover<'a>> {
476        let sources = self
477            .sources
478            .iter()
479            .map(|source| (&source.id, source))
480            .collect::<HashMap<_, _>>();
481        let mut covers = Vec::new();
482        for (order, track) in self.timeline.tracks.iter().enumerate() {
483            if track.kind != TrackKind::Video {
484                continue;
485            }
486            for clip in &track.clips {
487                if mattes.contains(&clip.id)
488                    || !sources
489                        .get(&clip.source_id)
490                        .is_some_and(|source| is_opaque_full_frame(source, clip))
491                {
492                    continue;
493                }
494                let mixed = track
495                    .transitions
496                    .iter()
497                    .filter(|transition| {
498                        transition.from_clip == clip.id || transition.to_clip == clip.id
499                    })
500                    .map(|transition| transition.timeline_range)
501                    .collect();
502                covers.push(Cover { order, clip, mixed });
503            }
504        }
505        covers
506    }
507}
508
509/// A clip that covers the whole frame opaquely, except during its transitions.
510struct Cover<'a> {
511    /// Its track's position.
512    order: usize,
513    clip: &'a crate::Clip,
514    /// Its transitions' ranges, where it is mixed with another clip.
515    mixed: Vec<TimeRange>,
516}
517
518/// A clip on a track after `order` that covers the frame for all of `range`.
519fn covering_clip<'a>(covers: &[Cover<'a>], order: usize, range: TimeRange) -> Option<&'a ClipId> {
520    covers
521        .iter()
522        .filter(|cover| cover.order > order)
523        .find(|cover| {
524            cover.clip.timeline_range.start() <= range.start()
525                && cover.clip.timeline_range.end() >= range.end()
526                && !cover
527                    .mixed
528                    .iter()
529                    .any(|mixed| mixed.intersection(range).is_some())
530        })
531        .map(|cover| &cover.clip.id)
532}
533
534/// Whether a clip draws an opaque fill over the whole frame: a generated fill of opaque
535/// paint with no transform, blend, mask or composition.
536fn is_opaque_full_frame(source: &crate::MediaSource, clip: &crate::Clip) -> bool {
537    let opaque = source.kind == MediaKind::Generated
538        && matches!(&source.generator, Some(Generator::Fill { paint }) if paint_is_opaque(paint));
539    opaque
540        && clip.visual == crate::VisualProperties::default()
541        && clip.blend_mode == crate::ClipBlendMode::Normal
542        && clip.composition.is_none()
543        && clip.masks.is_empty()
544        && clip.matte.is_none()
545}
546
547fn paint_is_opaque(paint: &Paint) -> bool {
548    match paint {
549        Paint::Solid { color } => color.alpha >= 1.0,
550        Paint::LinearGradient { stops, .. }
551        | Paint::RadialGradient { stops, .. }
552        | Paint::ConicGradient { stops, .. } => stops.iter().all(|stop| stop.color.alpha >= 1.0),
553    }
554}
555
556/// The project's frames as the engine renders them: frame `k` at
557/// [`FrameRate::frame_start`], its exact start rounded down to a tick.
558struct FrameGrid {
559    rate: FrameRate,
560}
561
562impl FrameGrid {
563    fn new(project: &Project) -> Self {
564        Self {
565            rate: project.settings.frame_rate,
566        }
567    }
568
569    fn on_grid(&self, time: MediaTime) -> bool {
570        self.rate
571            .frame_at_or_before(time)
572            .and_then(|frame| self.rate.frame_start(frame))
573            == Some(time)
574    }
575
576    /// Whether a frame shows a transition over `range` as a mix, i.e. the evaluator's progress
577    /// `clamp((t - start + F/2) / D, 0, 1)` is below 1 at some frame start `t` in the range.
578    /// Progress grows with `t`, so the first frame start decides. Unsure counts as shown.
579    fn shows_mixed(&self, range: TimeRange) -> bool {
580        let first = self
581            .rate
582            .frame_at_or_before(range.start())
583            .and_then(|frame| {
584                let start = self.rate.frame_start(frame)?;
585                if start == range.start() {
586                    Some(start)
587                } else {
588                    self.rate.frame_start(frame.checked_add(1)?)
589                }
590            });
591        let Some(first) = first else {
592            return true;
593        };
594        let num = i128::from(self.rate.numerator());
595        let elapsed = i128::from(first.ticks()) - i128::from(range.start().ticks());
596        let duration = i128::from(range.end().ticks()) - i128::from(range.start().ticks());
597        // Scaled by 2 * num, as the evaluator's `centred_progress` is.
598        first < range.end()
599            && 2 * num * elapsed
600                + i128::from(TICKS_PER_SECOND) * i128::from(self.rate.denominator())
601                < 2 * num * duration
602    }
603
604    fn check(&self, owner: &LintOwner, range: TimeRange, issues: &mut Vec<LintIssue>) {
605        for (edge, time) in [
606            (LintEdge::Start, range.start()),
607            (LintEdge::End, range.end()),
608        ] {
609            if !self.on_grid(time) {
610                issues.push(LintIssue::OffFrameBoundary {
611                    owner: owner.clone(),
612                    edge,
613                    time,
614                });
615            }
616        }
617    }
618}
619
620/// Finds keyframes no shown time depends on. `shown` holds every tick span (first, last) the
621/// owner may be shown at.
622struct Keyframes<'a> {
623    owner: &'a LintOwner,
624    shown: &'a [(i64, i64)],
625    issues: &'a mut Vec<LintIssue>,
626}
627
628/// The first and last ticks of `range`.
629fn span(range: TimeRange) -> (i64, i64) {
630    (range.start().ticks(), range.end().ticks() - 1)
631}
632
633impl Keyframes<'_> {
634    fn check_clip(&mut self, clip: &crate::Clip) {
635        let visual = &clip.visual;
636        self.check_point("visual.position", &visual.position);
637        self.check("visual.scale", &visual.scale);
638        self.check("visual.rotation_degrees", &visual.rotation_degrees);
639        self.check("visual.opacity", &visual.opacity);
640        for (index, mask) in clip.masks.iter().enumerate() {
641            self.check_geometry(&format!("masks[{index}].shape"), &mask.shape);
642            self.check(&format!("masks[{index}].feather"), &mask.feather);
643        }
644        self.check("audio.gain", &clip.audio.gain);
645        self.check("audio.pan", &clip.audio.pan);
646    }
647
648    fn check_geometry(&mut self, at: &str, geometry: &ShapeGeometry) {
649        geometry.for_each_keyed(at, &mut |property, keyed| {
650            if let Keyed::Times(times) = keyed {
651                self.check_times(property, times);
652            }
653        });
654    }
655
656    fn check_point(&mut self, property: &str, animated: &AnimatedPoint) {
657        if let AnimatedPoint::Keyframes { keyframes } = animated {
658            let times: Vec<MediaTime> = keyframes.iter().map(|keyframe| keyframe.time).collect();
659            self.check_times(property, &times);
660        }
661    }
662
663    fn check<T>(&mut self, property: &str, animated: &Animated<T>) {
664        if let Animated::Keyframes { keyframes } = animated {
665            let times: Vec<MediaTime> = keyframes.iter().map(|keyframe| keyframe.time).collect();
666            self.check_times(property, &times);
667        }
668    }
669
670    /// Keyframe `i` affects values only strictly between its neighbours' times (open-ended for
671    /// the first and last), so outside every shown tick it has no effect.
672    fn check_times(&mut self, property: &str, times: &[MediaTime]) {
673        for (index, time) in times.iter().enumerate() {
674            let after = index.checked_sub(1).map_or(i64::MIN, |previous| {
675                times[previous].ticks().saturating_add(1)
676            });
677            let before = times
678                .get(index + 1)
679                .map_or(i64::MAX, |next| next.ticks().saturating_sub(1));
680            let reached = self
681                .shown
682                .iter()
683                .any(|&(first, last)| after.max(first) <= before.min(last));
684            if !reached {
685                self.issues.push(LintIssue::UnreachedKeyframe {
686                    owner: self.owner.clone(),
687                    property: property.to_owned(),
688                    time: *time,
689                });
690            }
691        }
692    }
693}
694
695/// Every tick span (first, last) each composition and each generated or composition source
696/// may be shown at.
697///
698/// Composition time comes from a clip's [`crate::ClipComposition`] mapping, a composition
699/// source's picture time, or a parent composition drawing it as a group. Picture time comes
700/// from a clip's source range through its time map, or a media node's `start` plus its
701/// composition's time. Spans may over-cover, so a keyframe outside all of them is certainly
702/// unreached. Anything whose time cannot be represented is left out with all it shows.
703#[derive(Default)]
704struct Shown<'a> {
705    compositions: HashMap<&'a CompositionId, Vec<(i64, i64)>>,
706    sources: HashMap<&'a SourceId, Vec<(i64, i64)>>,
707}
708
709impl<'a> Shown<'a> {
710    fn of(project: &'a Project) -> Self {
711        let (base, unbounded) = Self::clips(project);
712        let mut shown = base.propagated(project);
713        shown.drop_unbounded(project, unbounded);
714        shown
715    }
716
717    /// What the clips show directly (sources at their time-mapped picture times, compositions at
718    /// their mapped times), and the compositions mapped to unrepresentable times.
719    fn clips(project: &'a Project) -> (Self, Vec<&'a CompositionId>) {
720        let mut base = Self::default();
721        let mut unbounded = Vec::new();
722        for clip in project
723            .timeline
724            .tracks
725            .iter()
726            .flat_map(|track| &track.clips)
727        {
728            let picture = match clip.time_map {
729                crate::TimeMap::Freeze { source_time } => {
730                    (source_time.ticks(), source_time.ticks())
731                }
732                crate::TimeMap::Forward | crate::TimeMap::Reverse | crate::TimeMap::Loop { .. } => {
733                    span(clip.source_range)
734                }
735            };
736            base.sources
737                .entry(&clip.source_id)
738                .or_default()
739                .push(picture);
740            if let Some(composition) = &clip.composition {
741                let start = clip.timeline_range.start();
742                let last = MediaTime(clip.timeline_range.end().ticks() - 1);
743                match (
744                    composition.local_time(start, start),
745                    composition.local_time(start, last),
746                ) {
747                    (Some(first), Some(last)) => base
748                        .compositions
749                        .entry(&composition.id)
750                        .or_default()
751                        .push((first.ticks(), last.ticks())),
752                    _ => unbounded.push(&composition.id),
753                }
754            }
755        }
756        (base, unbounded)
757    }
758
759    /// Extends `self` with what it shows in turn: composition sources' compositions, groups'
760    /// compositions, and media nodes' sources. Each pass adds one level; the graph is acyclic,
761    /// so one pass per composition and source reaches every level.
762    fn propagated(self, project: &'a Project) -> Self {
763        let mut shown = Self {
764            compositions: self.compositions.clone(),
765            sources: self.sources.clone(),
766        };
767        shown.normalize();
768        for _ in 0..=project.compositions.len() + project.sources.len() {
769            let mut next = Self {
770                compositions: self.compositions.clone(),
771                sources: self.sources.clone(),
772            };
773            for source in &project.sources {
774                if let (Some(composition), Some(spans)) =
775                    (&source.composition, shown.sources.get(&source.id))
776                {
777                    next.compositions
778                        .entry(composition)
779                        .or_default()
780                        .extend(spans);
781                }
782            }
783            for composition in &project.compositions {
784                let Some(spans) = shown.compositions.get(&composition.id) else {
785                    continue;
786                };
787                for node in &composition.nodes {
788                    match &node.op {
789                        crate::NodeOp::Group { composition, .. } => {
790                            next.compositions
791                                .entry(composition)
792                                .or_default()
793                                .extend(spans);
794                        }
795                        crate::NodeOp::Media { source_id, start } => {
796                            next.sources
797                                .entry(source_id)
798                                .or_default()
799                                .extend(spans.iter().map(|&(first, last)| {
800                                    (
801                                        first.saturating_add(start.ticks()),
802                                        last.saturating_add(start.ticks()),
803                                    )
804                                }));
805                        }
806                        _ => {}
807                    }
808                }
809            }
810            next.normalize();
811            if next.compositions == shown.compositions && next.sources == shown.sources {
812                break;
813            }
814            shown = next;
815        }
816        shown
817    }
818
819    /// Leaves out the compositions in `unbounded` and what they draw (groups' compositions and
820    /// media nodes' sources).
821    fn drop_unbounded(&mut self, project: &'a Project, mut unbounded: Vec<&'a CompositionId>) {
822        while let Some(id) = unbounded.pop() {
823            self.compositions.remove(id);
824            let Some(composition) = project.compositions.iter().find(|held| held.id == *id) else {
825                continue;
826            };
827            for node in &composition.nodes {
828                match &node.op {
829                    crate::NodeOp::Group { composition, .. } => {
830                        if self.compositions.contains_key(composition) {
831                            unbounded.push(composition);
832                        }
833                    }
834                    crate::NodeOp::Media { source_id, .. } => {
835                        self.sources.remove(source_id);
836                        if let Some(inner) = project
837                            .sources
838                            .iter()
839                            .find(|source| source.id == *source_id)
840                            .and_then(|source| source.composition.as_ref())
841                            && self.compositions.contains_key(inner)
842                        {
843                            unbounded.push(inner);
844                        }
845                    }
846                    _ => {}
847                }
848            }
849        }
850    }
851
852    /// Sorts each list and merges spans that meet or touch.
853    fn normalize(&mut self) {
854        fn merge(spans: &mut Vec<(i64, i64)>) {
855            spans.sort_unstable();
856            let mut merged: Vec<(i64, i64)> = Vec::with_capacity(spans.len());
857            for &(first, last) in spans.iter() {
858                match merged.last_mut() {
859                    Some(held) if first <= held.1.saturating_add(1) => held.1 = held.1.max(last),
860                    _ => merged.push((first, last)),
861                }
862            }
863            *spans = merged;
864        }
865        self.compositions.values_mut().for_each(merge);
866        self.sources.values_mut().for_each(merge);
867    }
868}
869
870/// Calls `visit` with each keyframed setting of a node, by its path in the node
871/// (`effect.params.radius`, `generator.items[0].transform.scale`, ...), and its times.
872pub(crate) fn node_keyed(
873    op: &crate::NodeOp,
874    visit: &mut impl FnMut(&str, crate::animation::Keyed<'_>),
875) {
876    use crate::animation::{visit_keyed, visit_keyed_point};
877    let params = |effect: &crate::ClipEffect,
878                  visit: &mut dyn FnMut(&str, crate::animation::Keyed<'_>)| {
879        for (name, value) in &effect.params {
880            visit_keyed(&format!("effect.params.{name}"), value, &mut |at, keyed| {
881                visit(at, keyed);
882            });
883        }
884    };
885    match op {
886        crate::NodeOp::Effect { effect, .. } => params(effect, visit),
887        crate::NodeOp::Transition {
888            effect, progress, ..
889        } => {
890            params(effect, visit);
891            visit_keyed("progress", progress, visit);
892        }
893        crate::NodeOp::Transform { transform, .. } => {
894            visit_keyed_point("transform.position", &transform.position, visit);
895            visit_keyed("transform.scale", &transform.scale, visit);
896            visit_keyed(
897                "transform.rotation_degrees",
898                &transform.rotation_degrees,
899                visit,
900            );
901            visit_keyed("transform.opacity", &transform.opacity, visit);
902        }
903        crate::NodeOp::Merge { layers } => {
904            for (index, layer) in layers.iter().enumerate() {
905                visit_keyed(&format!("layers[{index}].opacity"), &layer.opacity, visit);
906            }
907        }
908        crate::NodeOp::ShapeMask { masks, .. } => {
909            for (index, mask) in masks.iter().enumerate() {
910                mask.shape
911                    .for_each_keyed(&format!("masks[{index}].shape"), visit);
912                visit_keyed(&format!("masks[{index}].feather"), &mask.feather, visit);
913            }
914        }
915        crate::NodeOp::Group { controls, .. } => {
916            for (name, value) in controls {
917                visit_keyed(&format!("controls.{name}"), value, visit);
918            }
919        }
920        crate::NodeOp::Generator { generator } => match generator {
921            Generator::Shapes { items } => {
922                crate::shapes::for_each_keyed_item(items, "generator.items", visit);
923            }
924            Generator::Layout { root } => root.for_each_keyed("generator.root", visit),
925            Generator::Text { style, .. } => crate::text_animation::for_each_keyed_animator(
926                &style.animators,
927                "generator.style.animators",
928                visit,
929            ),
930            Generator::Fill { .. } => {}
931        },
932        crate::NodeOp::Clip {}
933        | crate::NodeOp::Media { .. }
934        | crate::NodeOp::Matte { .. }
935        | crate::NodeOp::GroupInput { .. } => {}
936    }
937}
938
939/// Reports a content tree's empty subpaths and paints with nothing before them, in document
940/// order. Returns whether the items hold any geometry, for an enclosing group's paints.
941fn lint_shape_items(
942    owner: &ShapeLintOwner,
943    items: &[ShapeItem],
944    at: &str,
945    issues: &mut Vec<LintIssue>,
946) -> bool {
947    let mut geometry = false;
948    for (index, item) in items.iter().enumerate() {
949        let at = format!("{at}[{index}]");
950        match item {
951            ShapeItem::Group { items, .. } => {
952                geometry |= lint_shape_items(owner, items, &format!("{at}.items"), issues);
953            }
954            ShapeItem::Rectangle(_) | ShapeItem::Ellipse(_) | ShapeItem::Polystar(_) => {
955                geometry = true;
956            }
957            ShapeItem::Path(path) => {
958                geometry = true;
959                let paths: Vec<&crate::Path> = match &path.path {
960                    Animated::Constant { value } => vec![value],
961                    Animated::Keyframes { keyframes } => {
962                        keyframes.iter().map(|keyframe| &keyframe.value).collect()
963                    }
964                    Animated::Data(_) => Vec::new(),
965                };
966                // Keyframes share their structure, so the first tells.
967                if let Some(first) = paths.first() {
968                    for (subpath, entry) in first.subpaths.iter().enumerate() {
969                        if entry.vertices.is_empty() {
970                            issues.push(LintIssue::EmptySubpath {
971                                owner: owner.clone(),
972                                at: format!("{at}.path.subpaths[{subpath}]"),
973                            });
974                        }
975                    }
976                }
977            }
978            ShapeItem::Fill { .. } | ShapeItem::Stroke(_) => {
979                if !geometry {
980                    issues.push(LintIssue::PaintWithoutGeometry {
981                        owner: owner.clone(),
982                        at,
983                    });
984                }
985            }
986            ShapeItem::Trim(_) => {}
987        }
988    }
989    geometry
990}
991
992/// Each of `animators` that sets nothing, under `at`.
993fn empty_animators(
994    owner: &LintOwner,
995    animators: &[crate::TextAnimator],
996    at: &str,
997    issues: &mut Vec<LintIssue>,
998) {
999    for (index, animator) in animators.iter().enumerate() {
1000        if animator.properties.is_empty() {
1001            issues.push(LintIssue::EmptyTextAnimator {
1002                owner: owner.clone(),
1003                at: format!("{at}[{index}]"),
1004            });
1005        }
1006    }
1007}
1008
1009/// Each cue's timeline range, and each timed run's, against the frame grid.
1010fn lint_cues(grid: &FrameGrid, track: &crate::Track, issues: &mut Vec<LintIssue>) {
1011    for (index, cue) in track
1012        .captions
1013        .iter()
1014        .flat_map(|captions| captions.cues.iter())
1015        .enumerate()
1016    {
1017        let owner = LintOwner::Cue {
1018            track: track.id.clone(),
1019            index,
1020        };
1021        grid.check(&owner, cue.timeline_range, issues);
1022        // A karaoke switch between frames shows at the next frame, so check each run's ends on the
1023        // timeline.
1024        for (run, timed) in cue.text.runs().iter().enumerate() {
1025            let Some(time) = timed.time else {
1026                continue;
1027            };
1028            let start = cue.timeline_range.start().ticks();
1029            let Ok(range) = alpha2_time::TimeRange::new(
1030                MediaTime(start.saturating_add(time.start.ticks())),
1031                MediaTime(start.saturating_add(time.end.ticks())),
1032            ) else {
1033                continue;
1034            };
1035            let owner = LintOwner::CueRun {
1036                track: track.id.clone(),
1037                cue: index,
1038                run,
1039            };
1040            grid.check(&owner, range, issues);
1041        }
1042    }
1043}
1044
1045/// A caption track's animators: keyframes in cue time against every cue's span, empty
1046/// animators, then styles no cue takes.
1047fn lint_caption_animators(
1048    track: &TrackId,
1049    captions: &crate::Captions,
1050    issues: &mut Vec<LintIssue>,
1051) {
1052    let owner = LintOwner::CaptionTrack {
1053        track: track.clone(),
1054    };
1055    let spans = captions
1056        .cues
1057        .iter()
1058        .filter_map(|cue| cue.timeline_range.duration())
1059        .map(|duration| (0, duration.ticks().saturating_sub(1)))
1060        .collect::<Vec<_>>();
1061    let mut keyframes = Keyframes {
1062        owner: &owner,
1063        shown: &spans,
1064        issues,
1065    };
1066    crate::text_animation::for_each_keyed_animator(
1067        &captions.style.animators,
1068        "style.animators",
1069        &mut |property, keyed| {
1070            if let Keyed::Times(times) = keyed {
1071                keyframes.check_times(property, times);
1072            }
1073        },
1074    );
1075    empty_animators(&owner, &captions.style.animators, "style.animators", issues);
1076    for name in captions.styles.keys() {
1077        let used = captions.cues.iter().any(|cue| {
1078            cue.style.as_deref() == Some(name.as_str())
1079                || (cue.style.is_none() && cue.speaker.as_deref() == Some(name.as_str()))
1080        });
1081        if !used {
1082            issues.push(LintIssue::UnusedCaptionStyle {
1083                track: track.clone(),
1084                style: name.clone(),
1085            });
1086        }
1087    }
1088}