Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_austenite/src/eval/import.rs

17.5 KiB, 9 runs

created by r1870400018:63212, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1// SPDX-License-Identifier: Apache-2.0
2// Original work copyright (c) the Typst project authors (typst-eval `import.rs`, typst-syntax `path.rs` and typst-library `foundations/path.rs` and `diag.rs`, version 0.15.1).
3// Modified for Austenite: ported to Hematite's types, IR and error handling.
4// U10 owns this file: paths, `import` and `include`, and reading the files they name. Every path is
5// resolved within a root, the project's or a package's, as Typst 0.15.1 resolves it: relative to the
6// directory of the file it is written in, or with a leading `/` to that file's root, and never out of the
7// root. A module is evaluated once and cached by its vfs path; re-entering one still on `World::route` is
8// a cycle. Semantics and wording are ported from typst-syntax `path.rs`, typst-library
9// `foundations/path.rs` and `diag.rs`, and typst-eval `import.rs`, all 0.15.1, Apache-2.0.
10
11use crate::diag::{
12 message_of,
13 Diagnostic,
14 DiagnosticKind,
15};
16use crate::eval::content::Content;
17use crate::eval::eval::eval_module;
18use crate::eval::lib::foundations::repr;
19use crate::eval::package::{
20 self,
21 Manifest,
22 PackageSpec,
23 DEFAULT_NAMESPACE,
24 MANIFEST,
25};
26use crate::eval::value::{
27 Module,
28 Value,
29};
30use crate::eval::Engine;
31use crate::syntax::{
32 FileId,
33 Span,
34};
35use crate::vfs;
36
37use oxedyne_fe2o3_core::prelude::*;
38
39use std::io;
40use std::path::{
41 Path,
42 PathBuf,
43};
44use std::sync::Arc;
45
46/// The root a path lives under.
47#[derive(Clone, Debug, PartialEq, Eq, Hash)]
48pub enum Root {
49 Project,
50 Package(PackageSpec),
51}
52
53impl Root {
54 fn kind(&self) -> &'static str {
55 match self {
56 Root::Project => "project",
57 Root::Package(_) => "package",
58 }
59 }
60}
61
62/// A path within its root, as Typst's `path` value holds one: absolute within the root and normalised,
63/// `/src/lib.typ`, with no empty, `.` or `..` segment.
64#[derive(Clone, Debug, PartialEq, Eq, Hash)]
65pub struct RootedPath {
66 pub root: Root,
67 pub vpath: String,
68}
69
70/// Why a path cannot be formed within its root.
71#[derive(Clone, Copy, Debug, PartialEq, Eq)]
72pub enum PathError {
73 Escapes, // a `..` above the root
74 Backslash, // not a separator in Typst, and not portable
75}
76
77impl RootedPath {
78 /// The rooted path of a file loaded from vfs path `path`: in a package when under a package's root,
79 /// else in the project. `None` for a project file outside `project_root`.
80 pub fn of(path: &Path, project_root: &Path) -> Option<Self> {
81 if let Some((spec, rel)) = PackageSpec::of_path(path) {
82 return Some(Self { root: Root::Package(spec), vpath: fmt!("/{}", rel) });
83 }
84 let rel = match path.strip_prefix(project_root) {
85 Ok(r) => r,
86 Err(_) => return None,
87 };
88 let mut segs = Vec::new();
89 for c in rel.components() {
90 match c.as_os_str().to_str() {
91 Some(s) => segs.push(s.to_string()),
92 None => return None,
93 }
94 }
95 Some(Self { root: Root::Project, vpath: fmt!("/{}", segs.join("/")) })
96 }
97
98 /// Resolves `path` as written in this file: against the file's directory, or against the root when it
99 /// starts with `/`.
100 pub fn resolve(&self, path: &str) -> Result<Self, PathError> {
101 let dir = match self.vpath.rfind('/') {
102 Some(i) => &self.vpath[..i],
103 None => "",
104 };
105 let vpath = ok!(join_vpath(dir, path));
106 Ok(Self { root: self.root.clone(), vpath })
107 }
108
109 /// Where the file is in the vfs: under the project root, or under the package's own root.
110 pub fn vfs(&self, project_root: &Path) -> PathBuf {
111 let rel = self.vpath.trim_start_matches('/');
112 let base = match &self.root {
113 Root::Project => project_root.to_path_buf(),
114 Root::Package(spec) => spec.root(),
115 };
116 if rel.is_empty() { base } else { base.join(rel) }
117 }
118
119 /// Typst's `repr` of a `path` value: always the absolute form, and never the package.
120 pub fn repr(&self) -> String {
121 fmt!("path({})", repr(&Value::str(self.vpath.clone())))
122 }
123}
124
125// Typst's `VirtualPath::join`: the components of `path` applied in turn to the segments of `base`. A
126// leading `/` restarts at the root, empty and `.` segments do nothing, and a `..` with nothing left to
127// remove would leave the root.
128fn join_vpath(base: &str, path: &str) -> Result<String, PathError> {
129 let mut segs: Vec<&str> = base.split('/').filter(|s| !s.is_empty()).collect();
130 for (i, s) in path.split('/').enumerate() {
131 match s {
132 "" if i == 0 && !path.is_empty() => segs.clear(),
133 "" | "." => (),
134 ".." => if segs.pop().is_none() { return Err(PathError::Escapes); },
135 s if s.contains('\\') => return Err(PathError::Backslash),
136 s => segs.push(s),
137 }
138 }
139 Ok(fmt!("/{}", segs.join("/")))
140}
141
142/// The rooted path of the file `from`, which a path written in it resolves against.
143pub fn within(engine: &mut Engine, from: FileId, span: Span) -> Outcome<RootedPath> {
144 if from == FileId::DETACHED {
145 return Err(engine.error(DiagnosticKind::Type, span, "cannot access file system from here"));
146 }
147 let path = match engine.world.source(from) {
148 Some(s) => s.path.clone(),
149 None => return Err(err!("No source with id {} is loaded.", from.0; Missing, Input)),
150 };
151 match RootedPath::of(&path, &engine.world.root) {
152 Some(r) => Ok(r),
153 None => Err(engine.error(DiagnosticKind::Type, span, "source file must be contained in project root")),
154 }
155}
156
157/// Resolves `path` as written in the file `from`, within that file's root.
158pub fn resolve(engine: &mut Engine, path: &str, from: FileId, span: Span) -> Outcome<RootedPath> {
159 let base = res!(within(engine, from, span));
160 match base.resolve(path) {
161 Ok(p) => Ok(p),
162 Err(e) => Err(path_error(engine, span, e, &base.root, path)),
163 }
164}
165
166/// The vfs path a path written in `from` names.
167pub fn resolve_path(engine: &mut Engine, spec: &str, from: FileId, span: Span) -> Outcome<PathBuf> {
168 let p = res!(resolve(engine, spec, from, span));
169 Ok(p.vfs(&engine.world.root))
170}
171
172// Typst's message for a path that cannot be formed, with its hints.
173fn path_error(engine: &mut Engine, span: Span, e: PathError, root: &Root, written: &str) -> Error<ErrTag> {
174 match e {
175 PathError::Escapes => fail(engine, DiagnosticKind::Type, span,
176 fmt!("path `{}` would escape the {} root", repr(&Value::str(written)), root.kind()),
177 vec![fmt!("cannot access files outside of the {} sandbox", root.kind())]),
178 PathError::Backslash => fail(engine, DiagnosticKind::Type, span, "path must not contain a backslash".to_string(), vec![
179 fmt!("use forward slashes instead: `{}`", repr(&Value::str(written.replace('\\', "/")))),
180 "in earlier Typst versions, backslashes indicated path separators on Windows".to_string(),
181 "this behavior is no longer supported as it is not portable".to_string(),
182 ]),
183 }
184}
185
186/// Reads the file at a vfs path, failing as Typst does: not found (naming where it looked), a directory,
187/// or access denied. The error is a `MissingFile`.
188pub fn read_file(engine: &mut Engine, path: &Path, span: Span) -> Outcome<Vec<u8>> {
189 read_file_as(engine, DiagnosticKind::MissingFile, path, span)
190}
191
192/// Checks that the file at a vfs path can be read, without reading it: what Typst's `image(path)` does at
193/// the call, where it loads the file. The error is the one `read_file` gives.
194pub fn require_file(engine: &mut Engine, path: &Path, span: Span) -> Outcome<()> {
195 engine.world.note(path);
196 if vfs::is_file(path) {
197 return Ok(());
198 }
199 let _ = res!(read_file(engine, path, span));
200 Ok(())
201}
202
203// As `read_file`, with the kind a failure carries: a manifest that cannot be read is the package's fault,
204// not a document's missing file.
205fn read_file_as(engine: &mut Engine, kind: DiagnosticKind, path: &Path, span: Span) -> Outcome<Vec<u8>> {
206 engine.world.note(path);
207 if vfs::is_dir(path) {
208 return Err(fail(engine, kind, span, "failed to load file (is a directory)".to_string(), Vec::new()));
209 }
210 match vfs::read(path) {
211 Ok(b) => Ok(b),
212 Err(e) => Err(fail(engine, kind, span, file_error(path, &e), Vec::new())),
213 }
214}
215
216/// Typst's message for a file that could not be read.
217pub fn file_error(path: &Path, e: &io::Error) -> String {
218 match e.kind() {
219 io::ErrorKind::NotFound => fmt!("file not found (searched at {})", package::display(path)),
220 io::ErrorKind::PermissionDenied => "failed to load file (access denied)".to_string(),
221 io::ErrorKind::IsADirectory => "failed to load file (is a directory)".to_string(),
222 _ => fmt!("failed to load file ({})", e),
223 }
224}
225
226// The source at a vfs path, parsed and added to the world on first use. A leading byte-order mark is
227// dropped, as Typst drops it.
228fn load_source(engine: &mut Engine, path: &Path, span: Span) -> Outcome<FileId> {
229 if let Some(s) = engine.world.sources.iter().find(|s| s.path == path) {
230 return Ok(s.id);
231 }
232 let bytes = res!(read_file(engine, path, span));
233 let text = match String::from_utf8(bytes) {
234 Ok(t) => t,
235 Err(_) => return Err(fail(engine, DiagnosticKind::Encoding, span, "file is not valid UTF-8".to_string(), Vec::new())),
236 };
237 let text = match text.strip_prefix('\u{feff}') {
238 Some(t) => t.to_string(),
239 None => text,
240 };
241 engine.world.add_source(path.to_path_buf(), text)
242}
243
244/// `import spec`: the evaluated module, from the cache when already evaluated.
245pub fn import_module(engine: &mut Engine, spec: &str, from: FileId, span: Span) -> Outcome<Arc<Module>> {
246 let mark = engine.diags.len();
247 let out = import_spec(engine, spec, from, span);
248 if out.is_err() {
249 trace(engine, mark, span, fmt!("while importing `{}`", spec));
250 }
251 out
252}
253
254/// `include spec`: the module's content.
255pub fn include(engine: &mut Engine, spec: &str, from: FileId, span: Span) -> Outcome<Content> {
256 let mark = engine.diags.len();
257 match import_spec(engine, spec, from, span) {
258 Ok(m) => Ok(m.content.clone()),
259 Err(e) => {
260 trace(engine, mark, span, fmt!("while including `{}`", spec));
261 Err(e)
262 }
263 }
264}
265
266/// `import path(..)`: the module at a rooted path.
267pub fn import_path(engine: &mut Engine, path: &RootedPath, span: Span) -> Outcome<Arc<Module>> {
268 let at = path.vfs(&engine.world.root);
269 import_file(engine, &at, span)
270}
271
272fn import_spec(engine: &mut Engine, spec: &str, from: FileId, span: Span) -> Outcome<Arc<Module>> {
273 if spec.starts_with('@') {
274 return match package::parse_spec(spec) {
275 Ok(p) => import_package(engine, &p, span),
276 Err(e) => Err(engine.error(DiagnosticKind::Type, span, message_of(&e))),
277 };
278 }
279 let path = res!(resolve_path(engine, spec, from, span));
280 import_file(engine, &path, span)
281}
282
283// A module by its vfs path: from the cache, or loaded and evaluated on the route. Loading comes first, so
284// a missing file is reported as missing even when the import would also close a cycle, as in Typst.
285fn import_file(engine: &mut Engine, path: &Path, span: Span) -> Outcome<Arc<Module>> {
286 if let Some(m) = engine.world.modules.get(path) {
287 return Ok(m.clone());
288 }
289 let id = res!(load_source(engine, path, span));
290 if let Some(at) = engine.world.route.iter().position(|p| p == path) {
291 // Typst's message is the bare "cyclic import"; the hint names the files that close the cycle.
292 let root = engine.world.root.clone();
293 let chain: Vec<String> = engine.world.route[at..].iter().map(|p| shown(&root, p))
294 .chain(std::iter::once(shown(&root, path))).collect();
295 return Err(fail(engine, DiagnosticKind::Type, span, "cyclic import".to_string(),
296 vec![fmt!("the import chain is {}", chain.join(" -> "))]));
297 }
298 engine.world.route.push(path.to_path_buf());
299 // A module nests as a call does, so a chain of imports is bounded as Typst bounds its route: by the
300 // call depth, never by the stack.
301 let out = match engine.enter_call(span) {
302 Ok(()) => {
303 let out = eval_module(engine, id);
304 engine.exit_call();
305 out
306 }
307 Err(e) => Err(e),
308 };
309 engine.world.route.pop();
310 let module = Arc::new(res!(out));
311 engine.world.modules.insert(path.to_path_buf(), module.clone());
312 Ok(module)
313}
314
315// A package's module, named by its manifest, as its entrypoint evaluates. It is cached under the
316// package's root, a directory, which no file's module can share.
317fn import_package(engine: &mut Engine, spec: &PackageSpec, span: Span) -> Outcome<Arc<Module>> {
318 let key = spec.root();
319 if let Some(m) = engine.world.modules.get(&key) {
320 return Ok(m.clone());
321 }
322 let (name, entry) = res!(resolve_package(engine, spec, span));
323 let module = res!(import_file(engine, &entry, span));
324 let named = Arc::new(Module {
325 name: Arc::new(name),
326 scope: module.scope.clone(),
327 content: module.content.clone(),
328 });
329 engine.world.modules.insert(key, named.clone());
330 Ok(named)
331}
332
333/// A package's name and the vfs path of its entrypoint, read from its manifest and checked as Typst
334/// checks them. Every failure is reported at the import.
335pub fn resolve_package(engine: &mut Engine, spec: &PackageSpec, span: Span) -> Outcome<(String, PathBuf)> {
336 if package::find(spec).is_none() {
337 return Err(not_found(engine, spec, span));
338 }
339 let manifest = RootedPath { root: Root::Package(spec.clone()), vpath: fmt!("/{}", MANIFEST) };
340 let at = manifest.vfs(&engine.world.root);
341 let bytes = res!(read_file_as(engine, DiagnosticKind::Package, &at, span));
342 let text = match std::str::from_utf8(&bytes) {
343 Ok(t) => t,
344 Err(_) => return Err(fail(engine, DiagnosticKind::Package, span, "file is not valid UTF-8".to_string(), Vec::new())),
345 };
346 let read = match Manifest::parse(text) {
347 Ok(m) => m,
348 Err(m) => return Err(fail(engine, DiagnosticKind::Package, span,
349 fmt!("package manifest is malformed ({})", m), Vec::new())),
350 };
351 if let Err(m) = read.validate(spec) {
352 return Err(fail(engine, DiagnosticKind::Package, span, m, Vec::new()));
353 }
354 // The entrypoint is resolved like a path written in the manifest, so it stays within the package.
355 let entry = match manifest.resolve(&read.entrypoint) {
356 Ok(p) => p,
357 Err(e) => return Err(path_error(engine, span, e, &manifest.root, &read.entrypoint)),
358 };
359 Ok((read.name, entry.vfs(&engine.world.root)))
360}
361
362// A package the host did not supply. Typst says "package found, but version .. does not exist" when its
363// registry holds other versions; here the host's store is the registry, and only for its namespace.
364fn not_found(engine: &mut Engine, spec: &PackageSpec, span: Span) -> Error<ErrTag> {
365 let others: Vec<(u32, u32, u32)> = package::versions(&spec.namespace, &spec.name)
366 .into_iter().filter(|v| *v != spec.version).collect();
367 let message = match others.last() {
368 Some(latest) if spec.namespace == DEFAULT_NAMESPACE => fmt!(
369 "package found, but version {} does not exist (latest is {})",
370 package::version_text(spec.version), package::version_text(*latest)),
371 _ => fmt!("package not found (searched for {})", spec),
372 };
373 let mut hints = vec!["the host did not supply it, and Austenite never downloads a package".to_string()];
374 if !others.is_empty() {
375 let listed: Vec<String> = others.iter().map(|v| package::version_text(*v)).collect();
376 hints.push(fmt!("the host supplied {} {}", if listed.len() == 1 { "version" } else { "versions" },
377 listed.join(", ")));
378 }
379 let mut d = Diagnostic::error(DiagnosticKind::Package, span, message.clone()).needing(spec.to_string());
380 for h in hints {
381 d = d.with_hint(h);
382 }
383 engine.diags.push(d);
384 err!("{}", message; Input, Invalid)
385}
386
387// A file as a diagnostic names it: relative to the project root, or by its package path.
388fn shown(root: &Path, path: &Path) -> String {
389 match path.strip_prefix(root) {
390 Ok(rel) => rel.display().to_string(),
391 Err(_) => package::display(path),
392 }
393}
394
395// Records an error with its hints at `span` and returns it, as `Engine::error` does for a bare message.
396fn fail(engine: &mut Engine, kind: DiagnosticKind, span: Span, message: String, hints: Vec<String>) -> Error<ErrTag> {
397 let mut d = Diagnostic::error(kind, span, message.clone());
398 for h in hints {
399 d = d.with_hint(h);
400 }
401 engine.diags.push(d);
402 err!("{}", message; Input, Invalid)
403}
404
405// Typst's import tracepoint: every error the import raised outside its own span, such as one inside the
406// imported file, notes the import it came through.
407fn trace(engine: &mut Engine, mark: usize, span: Span, text: String) {
408 if let Some(recorded) = engine.diags.get_mut(mark..) {
409 for d in recorded.iter_mut() {
410 let inside = d.span.file == span.file && span.start <= d.span.start && d.span.end <= span.end;
411 if d.is_error() && !inside {
412 d.trace.push((span, text.clone()));
413 }
414 }
415 }
416}
417
418#[cfg(test)]
419mod tests {
420 use super::*;
421
422 #[test]
423 fn paths_join_as_typst_virtual_paths_do() {
424 let j = |b: &str, p: &str| join_vpath(b, p);
425 assert_eq!(j("/src", "works.bib"), Ok("/src/works.bib".to_string()));
426 assert_eq!(j("/src", ""), Ok("/src".to_string()));
427 assert_eq!(j("/src", "."), Ok("/src".to_string()));
428 assert_eq!(j("/src", ".."), Ok("/".to_string()));
429 assert_eq!(j("/src", "../.."), Err(PathError::Escapes));
430 assert_eq!(j("/src", "a\\b"), Err(PathError::Backslash));
431 assert_eq!(j("/src", "/a///b/"), Ok("/a/b".to_string()));
432 assert_eq!(j("/src", "./x/../y.typ"), Ok("/src/y.typ".to_string()));
433 assert_eq!(j("/src", "/../x"), Err(PathError::Escapes));
434 assert_eq!(j("", "hello/.../world"), Ok("/hello/.../world".to_string()));
435 }
436
437 #[test]
438 fn rooted_paths_map_to_the_vfs_and_back() -> Outcome<()> {
439 let spec = res!(package::parse_spec("@local/demo:0.1.0"));
440 let file = RootedPath { root: Root::Package(spec.clone()), vpath: "/src/lib.typ".to_string() };
441 let at = file.vfs(Path::new("/proj"));
442 assert_eq!(at, PathBuf::from("@local/demo:0.1.0/src/lib.typ"));
443 assert_eq!(RootedPath::of(&at, Path::new("/proj")), Some(file.clone()));
444 assert_eq!(file.resolve("/data/d.txt").map(|p| p.vpath), Ok("/data/d.txt".to_string()));
445 assert_eq!(file.resolve("../../x.txt"), Err(PathError::Escapes));
446 let main = RootedPath { root: Root::Project, vpath: "/ch/a.typ".to_string() };
447 assert_eq!(main.vfs(Path::new("/proj")), PathBuf::from("/proj/ch/a.typ"));
448 assert_eq!(RootedPath::of(Path::new("/proj/ch/a.typ"), Path::new("/proj")), Some(main));
449 assert_eq!(RootedPath::of(Path::new("/elsewhere/a.typ"), Path::new("/proj")), None);
450 Ok(())
451 }
452}