1#![deny(missing_docs)]
50
51use std::collections::BTreeMap;
52use std::fmt;
53use std::path::{Component, Path, PathBuf};
54
55use serde::Serialize;
56
57pub const TRACE_SCHEMA: &str = "pqty.trace/v1";
59
60#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
62pub struct InputTrace {
63 pub schema: String,
65 #[serde(skip_serializing_if = "Option::is_none")]
67 pub producer: Option<String>,
68 #[serde(skip_serializing_if = "Option::is_none")]
70 pub environment_fingerprint: Option<String>,
71 pub inputs: Vec<ObservedInput>,
73}
74
75#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
77pub struct ObservedInput {
78 pub requested: String,
80 #[serde(skip_serializing_if = "Option::is_none")]
82 pub resolved: Option<String>,
83 pub scope: TraceScope,
85 #[serde(skip_serializing_if = "Option::is_none")]
87 pub kind: Option<ResourceKind>,
88}
89
90#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
92#[serde(rename_all = "kebab-case")]
93pub enum TraceScope {
94 Package,
96 Project,
98 Engine,
100 Output,
102}
103
104#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
106#[serde(rename_all = "kebab-case")]
107pub enum ResourceKind {
108 Tex,
110 Bibliography,
112 FontMetric,
114 VirtualFont,
116 Type1Font,
118 OpenTypeFont,
120 TrueTypeFont,
122 Map,
124 Encoding,
126 Hyphenation,
128 Format,
130 Binary,
132 Data,
134}
135
136#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct RootMapping {
139 pub root: PathBuf,
141 pub scope: TraceScope,
143}
144
145impl RootMapping {
146 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#[derive(Debug)]
169pub enum AdapterError {
170 Io {
172 path: PathBuf,
174 source: std::io::Error,
176 },
177 Usage(String),
179 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
201pub 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}