Skip to main content

pqty_fls/
lib.rs

1//! Convert kpathsea `.fls` recorder output into an engine-neutral
2//! `pqty.trace/v1` artifact.
3//!
4//! The adapter reads `INPUT` records, resolves relative paths against recorder
5//! `PWD` records, and classifies every input through caller-supplied
6//! [`RootMapping`] values. The most specific matching root wins. Unmapped
7//! inputs and equally specific roots with conflicting scopes fail closed.
8//! `OUTPUT` records are ignored; a generated file that is later read appears
9//! as an `INPUT` and can be classified under an output root.
10//!
11//! Paths are normalized lexically rather than canonicalized through the
12//! filesystem. This preserves the identity of a mounted package root whose
13//! files may be symlinks into pqty's content-addressed store.
14//!
15//! # Example
16//!
17//! ```no_run
18//! use std::path::Path;
19//! use pqty_fls::{RootMapping, TraceScope, adapt_fls};
20//!
21//! # fn main() -> Result<(), pqty_fls::AdapterError> {
22//! let working_directory = Path::new("/work/paper");
23//! let roots = [
24//!     RootMapping::new("/work/paper", TraceScope::Project, working_directory)?,
25//!     RootMapping::new("/work/pqty-texmf", TraceScope::Package, working_directory)?,
26//!     RootMapping::new("/work/paper/build", TraceScope::Output, working_directory)?,
27//! ];
28//! let recorder = "\
29//! PWD /work/paper
30//! INPUT ./main.tex
31//! INPUT /work/pqty-texmf/tex/latex/foo/foo.sty
32//! ";
33//! let trace = adapt_fls(
34//!     recorder,
35//!     working_directory,
36//!     &roots,
37//!     Some("my-renderer/1.0".to_string()),
38//!     None,
39//! )?;
40//! assert_eq!(trace.inputs.len(), 2);
41//! # Ok(())
42//! # }
43//! ```
44//!
45//! Artifact Protocol v1 is the stable process-integration boundary. The Rust
46//! API follows this crate's SemVer compatibility; while the major version is
47//! zero, minor releases may contain breaking Rust API changes.
48
49#![deny(missing_docs)]
50
51use std::collections::BTreeMap;
52use std::fmt;
53use std::path::{Component, Path, PathBuf};
54
55use serde::Serialize;
56
57/// Schema identifier emitted by [`adapt_fls`].
58pub const TRACE_SCHEMA: &str = "pqty.trace/v1";
59
60/// Engine-neutral input trace produced from a TeX recorder file.
61#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
62pub struct InputTrace {
63    /// Artifact schema identifier; always [`TRACE_SCHEMA`].
64    pub schema: String,
65    /// Optional adapter name and version.
66    #[serde(skip_serializing_if = "Option::is_none")]
67    pub producer: Option<String>,
68    /// Fingerprint of the package environment mounted for the recorded run.
69    #[serde(skip_serializing_if = "Option::is_none")]
70    pub environment_fingerprint: Option<String>,
71    /// Deterministically ordered, deduplicated recorder inputs.
72    pub inputs: Vec<ObservedInput>,
73}
74
75/// One input file observed by the TeX recorder.
76#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
77pub struct ObservedInput {
78    /// Basename requested or opened by the engine.
79    pub requested: String,
80    /// Path relative to the matching classification root.
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub resolved: Option<String>,
83    /// Ownership boundary assigned by the matching root.
84    pub scope: TraceScope,
85    /// Resource category inferred from the filename extension.
86    #[serde(skip_serializing_if = "Option::is_none")]
87    pub kind: Option<ResourceKind>,
88}
89
90/// Ownership boundary assigned to a recorder input.
91#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
92#[serde(rename_all = "kebab-case")]
93pub enum TraceScope {
94    /// File owned by the locked package environment.
95    Package,
96    /// File owned by project source.
97    Project,
98    /// File supplied by the TeX engine or its configuration.
99    Engine,
100    /// Generated build output subsequently read by the engine.
101    Output,
102}
103
104/// Engine-neutral category inferred for a recorder input.
105#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
106#[serde(rename_all = "kebab-case")]
107pub enum ResourceKind {
108    /// TeX source, package, class, or configuration file.
109    Tex,
110    /// Bibliography database or style file.
111    Bibliography,
112    /// TeX font metric file.
113    FontMetric,
114    /// Virtual font file.
115    VirtualFont,
116    /// Type 1 font program.
117    Type1Font,
118    /// OpenType font program.
119    OpenTypeFont,
120    /// TrueType font program or collection.
121    TrueTypeFont,
122    /// Font map fragment.
123    Map,
124    /// Font encoding file.
125    Encoding,
126    /// Hyphenation pattern file.
127    Hyphenation,
128    /// Precompiled TeX format.
129    Format,
130    /// Native executable or shared library.
131    Binary,
132    /// Any resource not covered by a more specific category.
133    Data,
134}
135
136/// A native filesystem root and the ownership scope assigned beneath it.
137#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct RootMapping {
139    /// Absolute, lexically normalized classification root.
140    pub root: PathBuf,
141    /// Scope assigned to matching recorder inputs.
142    pub scope: TraceScope,
143}
144
145impl RootMapping {
146    /// Create a root mapping, resolving relative roots against `relative_to`.
147    ///
148    /// # Errors
149    ///
150    /// Returns [`AdapterError::Usage`] when the resulting root is not absolute.
151    pub fn new(
152        root: impl AsRef<Path>,
153        scope: TraceScope,
154        relative_to: impl AsRef<Path>,
155    ) -> Result<Self, AdapterError> {
156        let root = absolute_lexical(root.as_ref(), relative_to.as_ref());
157        if !root.is_absolute() {
158            return Err(AdapterError::Usage(format!(
159                "classification root is not absolute: {}",
160                root.display()
161            )));
162        }
163        Ok(Self { root, scope })
164    }
165}
166
167/// Error returned while configuring or converting a recorder trace.
168#[derive(Debug)]
169pub enum AdapterError {
170    /// A filesystem or stream operation failed.
171    Io {
172        /// Path associated with the failed operation.
173        path: PathBuf,
174        /// Underlying I/O error.
175        source: std::io::Error,
176    },
177    /// A root, fingerprint, or recorder record violated the adapter contract.
178    Usage(String),
179    /// Trace or environment JSON could not be encoded or decoded.
180    Json(serde_json::Error),
181}
182
183impl fmt::Display for AdapterError {
184    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
185        match self {
186            Self::Io { path, source } => write!(formatter, "{}: {source}", path.display()),
187            Self::Usage(message) => formatter.write_str(message),
188            Self::Json(error) => write!(formatter, "{error}"),
189        }
190    }
191}
192
193impl std::error::Error for AdapterError {}
194
195impl From<serde_json::Error> for AdapterError {
196    fn from(value: serde_json::Error) -> Self {
197        Self::Json(value)
198    }
199}
200
201/// Convert kpathsea recorder contents into a deterministic pqty input trace.
202///
203/// Paths are normalized lexically rather than canonicalized through the
204/// filesystem. A pqty TEXMF commonly contains symlinks into its content store;
205/// following those symlinks would lose the mounted package-root identity.
206pub fn adapt_fls(
207    contents: &str,
208    fallback_working_directory: &Path,
209    roots: &[RootMapping],
210    producer: Option<String>,
211    environment_fingerprint: Option<String>,
212) -> Result<InputTrace, AdapterError> {
213    if roots.is_empty() {
214        return Err(AdapterError::Usage(
215            "at least one classification root is required".to_string(),
216        ));
217    }
218    if let Some(fingerprint) = environment_fingerprint.as_deref() {
219        validate_fingerprint(fingerprint)?;
220    }
221
222    let fallback_working_directory = absolute_lexical(
223        fallback_working_directory,
224        &std::env::current_dir().map_err(|source| AdapterError::Io {
225            path: PathBuf::from("."),
226            source,
227        })?,
228    );
229    let mut working_directory = fallback_working_directory;
230    let mut inputs: BTreeMap<(u8, String, String), ObservedInput> = BTreeMap::new();
231
232    for (index, raw_line) in contents.lines().enumerate() {
233        let line_number = index + 1;
234        if let Some(path) = raw_line.strip_prefix("PWD ") {
235            if path.is_empty() {
236                return Err(AdapterError::Usage(format!(
237                    "empty PWD record at recorder line {line_number}"
238                )));
239            }
240            working_directory = absolute_lexical(Path::new(path), &working_directory);
241            continue;
242        }
243        let Some(path) = raw_line.strip_prefix("INPUT ") else {
244            continue;
245        };
246        if path.is_empty() {
247            return Err(AdapterError::Usage(format!(
248                "empty INPUT record at recorder line {line_number}"
249            )));
250        }
251
252        let absolute = absolute_lexical(Path::new(path), &working_directory);
253        let classification = classify(&absolute, roots).map_err(|error| {
254            AdapterError::Usage(format!(
255                "{error} at recorder line {line_number}: {}",
256                absolute.display()
257            ))
258        })?;
259        let requested = absolute
260            .file_name()
261            .and_then(|name| name.to_str())
262            .filter(|name| !name.is_empty())
263            .ok_or_else(|| {
264                AdapterError::Usage(format!(
265                    "recorder input has no filename at line {line_number}: {}",
266                    absolute.display()
267                ))
268            })?
269            .to_string();
270        let mut resolved = slash_path(&classification.relative)?;
271        if classification.scope == TraceScope::Package {
272            resolved = resolved
273                .strip_prefix("texmf-dist/")
274                .unwrap_or(&resolved)
275                .to_string();
276        }
277        if resolved.is_empty() {
278            return Err(AdapterError::Usage(format!(
279                "classification root names a file, not a directory: {}",
280                classification.root.display()
281            )));
282        }
283        let input = ObservedInput {
284            requested: requested.clone(),
285            resolved: Some(resolved.clone()),
286            scope: classification.scope,
287            kind: Some(resource_kind(&resolved)),
288        };
289        inputs
290            .entry((scope_rank(classification.scope), resolved, requested))
291            .or_insert(input);
292    }
293
294    Ok(InputTrace {
295        schema: TRACE_SCHEMA.to_string(),
296        producer,
297        environment_fingerprint,
298        inputs: inputs.into_values().collect(),
299    })
300}
301
302#[derive(Debug)]
303struct Classification<'a> {
304    root: &'a Path,
305    relative: PathBuf,
306    scope: TraceScope,
307}
308
309fn classify<'a>(path: &Path, roots: &'a [RootMapping]) -> Result<Classification<'a>, AdapterError> {
310    let mut matches = roots
311        .iter()
312        .filter_map(|mapping| {
313            path.strip_prefix(&mapping.root)
314                .ok()
315                .map(|relative| (mapping, relative.to_path_buf()))
316        })
317        .collect::<Vec<_>>();
318    if matches.is_empty() {
319        return Err(AdapterError::Usage(
320            "recorder input is outside every declared root".to_string(),
321        ));
322    }
323    matches.sort_by(|(left, _), (right, _)| {
324        right
325            .root
326            .components()
327            .count()
328            .cmp(&left.root.components().count())
329            .then_with(|| left.root.cmp(&right.root))
330    });
331    let specificity = matches[0].0.root.components().count();
332    let most_specific = matches
333        .iter()
334        .take_while(|(mapping, _)| mapping.root.components().count() == specificity)
335        .collect::<Vec<_>>();
336    let scope = most_specific[0].0.scope;
337    if most_specific
338        .iter()
339        .any(|(mapping, _)| mapping.scope != scope)
340    {
341        let roots = most_specific
342            .iter()
343            .map(|(mapping, _)| format!("{}={}", scope_name(mapping.scope), mapping.root.display()))
344            .collect::<Vec<_>>()
345            .join(", ");
346        return Err(AdapterError::Usage(format!(
347            "recorder input matches equally specific roots with different scopes ({roots})"
348        )));
349    }
350    Ok(Classification {
351        root: &most_specific[0].0.root,
352        relative: most_specific[0].1.clone(),
353        scope,
354    })
355}
356
357fn validate_fingerprint(fingerprint: &str) -> Result<(), AdapterError> {
358    let digest = fingerprint.strip_prefix("sha256:").unwrap_or_default();
359    if digest.len() == 64
360        && digest
361            .bytes()
362            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
363    {
364        Ok(())
365    } else {
366        Err(AdapterError::Usage(format!(
367            "invalid environment fingerprint: {fingerprint}"
368        )))
369    }
370}
371
372fn absolute_lexical(path: &Path, relative_to: &Path) -> PathBuf {
373    let joined = if path.is_absolute() {
374        path.to_path_buf()
375    } else {
376        relative_to.join(path)
377    };
378    lexical_normalize(&joined)
379}
380
381fn lexical_normalize(path: &Path) -> PathBuf {
382    let mut normalized = PathBuf::new();
383    for component in path.components() {
384        match component {
385            Component::Prefix(prefix) => normalized.push(prefix.as_os_str()),
386            Component::RootDir => normalized.push(component.as_os_str()),
387            Component::CurDir => {}
388            Component::ParentDir => {
389                normalized.pop();
390            }
391            Component::Normal(part) => normalized.push(part),
392        }
393    }
394    normalized
395}
396
397fn slash_path(path: &Path) -> Result<String, AdapterError> {
398    path.to_str()
399        .map(|path| path.replace('\\', "/"))
400        .ok_or_else(|| {
401            AdapterError::Usage(format!(
402                "classified input cannot be represented as a Portable Path: {}",
403                path.display()
404            ))
405        })
406}
407
408fn scope_rank(scope: TraceScope) -> u8 {
409    match scope {
410        TraceScope::Package => 0,
411        TraceScope::Project => 1,
412        TraceScope::Engine => 2,
413        TraceScope::Output => 3,
414    }
415}
416
417fn scope_name(scope: TraceScope) -> &'static str {
418    match scope {
419        TraceScope::Package => "package",
420        TraceScope::Project => "project",
421        TraceScope::Engine => "engine",
422        TraceScope::Output => "output",
423    }
424}
425
426fn resource_kind(path: &str) -> ResourceKind {
427    match Path::new(path)
428        .extension()
429        .and_then(|extension| extension.to_str())
430        .unwrap_or_default()
431        .to_ascii_lowercase()
432        .as_str()
433    {
434        "tex" | "sty" | "cls" | "ltx" | "def" | "cfg" | "clo" | "fd" => ResourceKind::Tex,
435        "bib" | "bst" | "bbx" | "cbx" => ResourceKind::Bibliography,
436        "tfm" => ResourceKind::FontMetric,
437        "vf" => ResourceKind::VirtualFont,
438        "pfb" | "pfa" => ResourceKind::Type1Font,
439        "otf" => ResourceKind::OpenTypeFont,
440        "ttf" | "ttc" => ResourceKind::TrueTypeFont,
441        "map" => ResourceKind::Map,
442        "enc" => ResourceKind::Encoding,
443        "pat" | "hyp" => ResourceKind::Hyphenation,
444        "fmt" => ResourceKind::Format,
445        "exe" | "dll" | "so" | "dylib" => ResourceKind::Binary,
446        _ => ResourceKind::Data,
447    }
448}
449
450#[cfg(test)]
451mod tests {
452    use crate::{RootMapping, TRACE_SCHEMA, TraceScope, adapt_fls, slash_path};
453    #[cfg(windows)]
454    use std::path::Path;
455    use std::path::PathBuf;
456
457    fn fixture_root(path: &str) -> PathBuf {
458        std::env::current_dir()
459            .unwrap()
460            .join("adapter-platform-fixture")
461            .join(path)
462    }
463
464    fn roots() -> Vec<RootMapping> {
465        vec![
466            RootMapping::new(
467                fixture_root("project"),
468                TraceScope::Project,
469                fixture_root("fallback"),
470            )
471            .unwrap(),
472            RootMapping::new(
473                fixture_root("project/build"),
474                TraceScope::Output,
475                fixture_root("fallback"),
476            )
477            .unwrap(),
478            RootMapping::new(
479                fixture_root("pqty"),
480                TraceScope::Package,
481                fixture_root("fallback"),
482            )
483            .unwrap(),
484            RootMapping::new(
485                fixture_root("system/texmf"),
486                TraceScope::Package,
487                fixture_root("fallback"),
488            )
489            .unwrap(),
490            RootMapping::new(
491                fixture_root("system/texmf/fonts"),
492                TraceScope::Engine,
493                fixture_root("fallback"),
494            )
495            .unwrap(),
496            RootMapping::new(
497                fixture_root("system/config"),
498                TraceScope::Engine,
499                fixture_root("fallback"),
500            )
501            .unwrap(),
502        ]
503    }
504
505    #[test]
506    fn converts_inputs_with_longest_root_classification_and_deduplication() {
507        let project = fixture_root("project");
508        let recorder = format!(
509            "PWD {}\n\
510             INPUT ./main.tex\n\
511             INPUT {}\n\
512             INPUT {}\n\
513             INPUT {}\n\
514             INPUT {}\n\
515             INPUT {}\n\
516             INPUT {}\n\
517             OUTPUT {}\n",
518            project.display(),
519            fixture_root("project/build/main.aux").display(),
520            fixture_root("pqty/tex/latex/foo/foo.sty").display(),
521            fixture_root("pqty/tex/latex/foo/foo.sty").display(),
522            fixture_root("system/texmf/tex/latex/bar/bar.sty").display(),
523            fixture_root("system/texmf/fonts/tfm/public/cm/cmr10.tfm").display(),
524            fixture_root("system/config/web2c/texmf.cnf").display(),
525            fixture_root("project/build/main.pdf").display(),
526        );
527        let trace = adapt_fls(
528            &recorder,
529            &fixture_root("fallback"),
530            &roots(),
531            Some("pqty-fls/test".to_string()),
532            Some(format!("sha256:{}", "01".repeat(32))),
533        )
534        .unwrap();
535
536        assert_eq!(trace.schema, TRACE_SCHEMA);
537        assert_eq!(trace.inputs.len(), 6);
538        assert_eq!(trace.inputs[0].scope, TraceScope::Package);
539        assert_eq!(
540            trace.inputs[0].resolved.as_deref(),
541            Some("tex/latex/bar/bar.sty")
542        );
543        assert_eq!(trace.inputs[1].scope, TraceScope::Package);
544        assert_eq!(
545            trace.inputs[1].resolved.as_deref(),
546            Some("tex/latex/foo/foo.sty")
547        );
548        assert_eq!(trace.inputs[2].scope, TraceScope::Project);
549        assert_eq!(trace.inputs[2].resolved.as_deref(), Some("main.tex"));
550        assert_eq!(trace.inputs[3].scope, TraceScope::Engine);
551        assert_eq!(trace.inputs[4].scope, TraceScope::Engine);
552        assert_eq!(trace.inputs[5].scope, TraceScope::Output);
553    }
554
555    #[test]
556    fn strips_a_texmf_dist_prefix_for_package_roots() {
557        let texlive = fixture_root("texlive");
558        let roots = vec![
559            RootMapping::new(&texlive, TraceScope::Package, fixture_root("fallback")).unwrap(),
560        ];
561        let trace = adapt_fls(
562            &format!(
563                "INPUT {}\n",
564                texlive.join("texmf-dist/tex/latex/foo/foo.sty").display()
565            ),
566            &fixture_root("fallback"),
567            &roots,
568            None,
569            None,
570        )
571        .unwrap();
572        assert_eq!(
573            trace.inputs[0].resolved.as_deref(),
574            Some("tex/latex/foo/foo.sty")
575        );
576    }
577
578    #[test]
579    fn golden_v1_trace_is_a_real_adapter_output() {
580        let package = fixture_root("pqty");
581        let roots = vec![
582            RootMapping::new(&package, TraceScope::Package, fixture_root("fallback")).unwrap(),
583        ];
584        let trace = adapt_fls(
585            &format!(
586                "INPUT {}\n",
587                package.join("tex/latex/foo/foo.sty").display()
588            ),
589            &fixture_root("fallback"),
590            &roots,
591            Some("pqty-fls 0.1.0".to_string()),
592            Some(
593                "sha256:95ea8e9b9a2b0b5478a49763e115d9adb5f0a66d2f340f235bb28b08bbeb434a"
594                    .to_string(),
595            ),
596        )
597        .unwrap();
598        let golden: serde_json::Value =
599            serde_json::from_str(include_str!("../tests/golden/v1/trace.json")).unwrap();
600        assert_eq!(serde_json::to_value(trace).unwrap(), golden);
601    }
602
603    #[test]
604    fn rejects_unmapped_inputs() {
605        let unknown = fixture_root("unknown/foo.sty");
606        let error = adapt_fls(
607            &format!("INPUT {}\n", unknown.display()),
608            &fixture_root("project"),
609            &roots(),
610            None,
611            None,
612        )
613        .unwrap_err();
614        assert!(error.to_string().contains("outside every declared root"));
615        assert!(error.to_string().contains("recorder line 1"));
616    }
617
618    #[test]
619    fn rejects_equally_specific_conflicting_roots() {
620        let same = fixture_root("same");
621        let roots = vec![
622            RootMapping::new(&same, TraceScope::Package, fixture_root("fallback")).unwrap(),
623            RootMapping::new(&same, TraceScope::Engine, fixture_root("fallback")).unwrap(),
624        ];
625        let error = adapt_fls(
626            &format!("INPUT {}\n", same.join("foo.sty").display()),
627            &fixture_root("fallback"),
628            &roots,
629            None,
630            None,
631        )
632        .unwrap_err();
633        assert!(error.to_string().contains("different scopes"));
634    }
635
636    #[test]
637    fn rejects_invalid_environment_fingerprints() {
638        let error = adapt_fls(
639            "",
640            &fixture_root("fallback"),
641            &roots(),
642            None,
643            Some("latest".to_string()),
644        )
645        .unwrap_err();
646        assert!(
647            error
648                .to_string()
649                .contains("invalid environment fingerprint")
650        );
651    }
652
653    #[cfg(unix)]
654    #[test]
655    fn rejects_non_utf8_portable_paths() {
656        use std::ffi::OsString;
657        use std::os::unix::ffi::OsStringExt;
658
659        let path = PathBuf::from(OsString::from_vec(vec![b'f', 0x80]));
660        assert!(
661            slash_path(&path)
662                .unwrap_err()
663                .to_string()
664                .contains("Portable Path")
665        );
666    }
667
668    #[cfg(windows)]
669    #[test]
670    fn rejects_non_utf8_portable_paths() {
671        use std::ffi::OsString;
672        use std::os::windows::ffi::OsStringExt;
673
674        let path = PathBuf::from(OsString::from_wide(&[0xD800]));
675        assert!(
676            slash_path(&path)
677                .unwrap_err()
678                .to_string()
679                .contains("Portable Path")
680        );
681    }
682
683    #[cfg(windows)]
684    #[test]
685    fn converts_drive_letter_roots_to_portable_trace_paths() {
686        let roots = vec![
687            RootMapping::new(
688                Path::new(r"C:\work\project"),
689                TraceScope::Project,
690                Path::new(r"C:\work"),
691            )
692            .unwrap(),
693            RootMapping::new(
694                Path::new(r"C:\pqty\texmf"),
695                TraceScope::Package,
696                Path::new(r"C:\work"),
697            )
698            .unwrap(),
699        ];
700        let trace = adapt_fls(
701            "PWD C:\\work\\project\nINPUT C:\\pqty\\texmf\\tex\\latex\\foo\\foo.sty\n",
702            Path::new(r"C:\work\project"),
703            &roots,
704            None,
705            None,
706        )
707        .unwrap();
708        assert_eq!(
709            trace.inputs[0].resolved.as_deref(),
710            Some("tex/latex/foo/foo.sty")
711        );
712        assert!(!trace.inputs[0].resolved.as_deref().unwrap().contains(':'));
713        assert!(!trace.inputs[0].resolved.as_deref().unwrap().contains('\\'));
714    }
715}