Scripts: #include and the other preprocessor lines run, and $.evalFile runs a file

Before a script runs, `script.run` reads its preprocessor lines (`#` or
`//@` at the start of a line, outside strings and comments):

- `#include` and `//@include` put another file's text in place of the
  line, looked for beside the including file, then in each
  `#includepath` folder, then in each `JSINCLUDE` folder. A later
  `#includepath` replaces the list.
- `#script` names the run unless `name` is given; `#target` takes any
  value; `#strict off` is taken. `#strict on`, `#targetengine` and
  `#engine` are refused as unsupported, and any other `#name` as
  unknown.

`$.evalFile(path, timeout?)` runs a file in the same global environment
and returns its last value, `$.fileName` is the file being run and
`$.includePath` the include folders.

A script run from a file reads these files only in its folder and the
folders below it. Paths with a `..` name, links or junctions that lead
out, device names, streams and network paths are refused; a script
given as text reads none. A run reads at most 64 files 16 levels deep,
32 MiB of source in all and 1,024 paths looked up. An error in an
included or evaluated file is reported at that file's line and column,
and the report's new `file` field names it.

Docs: docs/mcp.md (script.run, Script Console), docs/target-app-parity.md.

crates/engine/src/script/include.rs

@@ -0,0 +1,431 @@
+//! A script's preprocessor lines, read before it runs, as the public guide lists them
+//! (<https://extendscript.docsforadobe.dev/extendscript-tools-features/preprocessor-directives/>):
+//! `#include` and `//@include` put the text of another file in place of the line, `#includepath`
+//! sets the folders `#include` looks in, `#script` names the run, and `#target` and `#strict off`
+//! are accepted. The same lines are read in a file `$.evalFile` runs.
+//!
+//! VectorCraft's own rules:
+//!
+//! - A line counts only at the start of a line (blanks before it), outside strings and comments, as
+//!   the lexer reads it, and each file must be a whole script on its own.
+//! - An included file is looked for beside the file that includes it, then in each `#includepath`
+//!   folder in turn (a relative one is relative to that same file's folder), then in each folder of
+//!   the `JSINCLUDE` environment variable. A later `#includepath` replaces the list.
+//! - Files are read through the script's [`ScriptScope`]: a refused path ends the run, except a
+//!   `JSINCLUDE` folder outside the scope, which is passed over.
+//! - `#target` takes any value and changes nothing. `#targetengine`, `#engine` and `#strict on` are
+//!   refused as unsupported, and any other `#name` as unknown; `//@name` with another name stays a
+//!   comment.
+//! - A run reads at most [`MAX_DEPTH`] levels of nested files, [`MAX_FILES`] files,
+//!   [`MAX_TOTAL_BYTES`] of source in all (the script's own included) and 8 MiB a file, and looks up
+//!   at most [`MAX_PROBES`] paths. A file may be included again once its earlier inclusion has
+//!   ended; one that includes itself, directly or not, is an error.
+//!
+//! The expanded source keeps a [`SourceMap`], so an error is reported at the line and column of
+//! the file it is in.
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use vectorcraft_js::{DirectiveName, Options};
+
+use crate::file_access::{ScriptRead, ScriptScope};
+
+/// The most files nested inside each other, below the script.
+pub const MAX_DEPTH: usize = 16;
+/// The most files a run includes or evaluates.
+pub const MAX_FILES: usize = 64;
+/// The most bytes of source a run reads, its own included.
+pub const MAX_TOTAL_BYTES: usize = 32 << 20;
+/// The most paths a run looks up for its files.
+pub const MAX_PROBES: usize = 1024;
+/// The longest value a preprocessor line may have, in bytes.
+const MAX_VALUE_BYTES: usize = 4096;
+
+/// Where the lines of an expanded source came from: file 0 is the file expanded, the others the
+/// files it included.
+#[derive(Clone, Debug, Default)]
+pub(crate) struct SourceMap {
+    files: Vec<Arc<str>>,
+    segments: Vec<Segment>,
+}
+
+/// From line `out_line` of the expanded source on, the lines are those of file `file` from line
+/// `line`; on `out_line` itself the columns are `shift` units further right.
+#[derive(Clone, Copy, Debug)]
+struct Segment {
+    out_line: u32,
+    file: usize,
+    line: u32,
+    shift: u32,
+}
+
+impl SourceMap {
+    /// Line `line`, column `column` of the expanded source → the file it is in (its index and name)
+    /// and the line and column there.
+    pub(crate) fn locate(&self, line: u32, column: u32) -> (usize, Arc<str>, u32, u32) {
+        let at = self.segments.partition_point(|s| s.out_line <= line);
+        let Some(seg) = at.checked_sub(1).and_then(|i| self.segments.get(i)) else {
+            return (0, self.files.first().cloned().unwrap_or_else(|| Arc::from("")), line, column);
+        };
+        let column = if line == seg.out_line { column.saturating_sub(seg.shift).max(1) } else { column };
+        let name = self.files.get(seg.file).cloned().unwrap_or_else(|| Arc::from(""));
+        (seg.file, name, seg.line.saturating_add(line - seg.out_line), column)
+    }
+}
+
+/// How a preprocessor failure ends the run.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum FailKind {
+    /// A line that is not a valid preprocessor line, or a file that is not a valid script.
+    Syntax,
+    /// A file that is missing, refused or unreadable, or a cycle.
+    Error,
+    /// One of the run's limits.
+    Limit,
+}
+
+/// A preprocessor failure, at line `line`, column `column` of the file `file` (index `index` of
+/// the expansion's [`SourceMap`]).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Failure {
+    pub kind: FailKind,
+    pub message: String,
+    pub index: usize,
+    pub file: Arc<str>,
+    pub line: u32,
+    pub column: u32,
+}
+
+/// A source with its preprocessor lines read: the text to run, where its lines came from, and the
+/// name its `#script` line gave.
+pub(crate) struct Expanded {
+    pub source: String,
+    pub map: SourceMap,
+    pub name: Option<String>,
+}
+
+/// A file being run: its name for people and the folder its relative paths start from (none for a
+/// script given as text).
+struct Frame {
+    shown: Arc<str>,
+    dir: Option<PathBuf>,
+}
+
+/// The files of one run: its scope, the `#includepath` list, what it has read and the files open
+/// now, innermost last.
+pub(crate) struct Files {
+    scope: ScriptScope,
+    jsinclude: Vec<PathBuf>,
+    include_path: Vec<String>,
+    files: usize,
+    bytes: usize,
+    probes: usize,
+    /// The real paths of the files open now, for cycles.
+    chain: Vec<PathBuf>,
+    /// How many of them are below the script.
+    levels: usize,
+    /// The files `$.evalFile` is running, the script first.
+    frames: Vec<Frame>,
+}
+
+/// The output being built: its UTF-16 text, the line it is on, the units since that line began,
+/// and whether its last unit is a carriage return.
+struct Out {
+    units: Vec<u16>,
+    line: u32,
+    column: u32,
+    after_cr: bool,
+    map: SourceMap,
+}
+
+impl Out {
+    fn emit(&mut self, text: &[u16]) {
+        for &u in text {
+            match u {
+                0x0A if self.after_cr => self.column = 0,
+                0x0A | 0x0D | 0x2028 | 0x2029 => {
+                    self.line = self.line.saturating_add(1);
+                    self.column = 0;
+                }
+                _ => self.column = self.column.saturating_add(1),
+            }
+            self.after_cr = u == 0x0D;
+        }
+        self.units.extend_from_slice(text);
+    }
+
+    /// The lines from here on come from file `file`, from its line `line`.
+    fn begin(&mut self, file: usize, line: u32) {
+        self.map.segments.push(Segment { out_line: self.line, file, line, shift: self.column });
+    }
+
+    /// Ends the line the output is on, unless it has just ended.
+    fn end_line(&mut self) {
+        if self.after_cr || !matches!(self.units.last(), Some(0x0A | 0x2028 | 0x2029)) {
+            self.emit(&[0x0A]);
+        }
+    }
+}
+
+/// A file's text read as a script: a byte order mark is left out, and compiled scripts and bytes
+/// that are not UTF-8 are refused.
+fn decode(bytes: &[u8], value: &str) -> Result<String, String> {
+    if bytes.starts_with(b"@JSXBIN@") {
+        return Err(format!("script file is compiled: {value}"));
+    }
+    let text = std::str::from_utf8(bytes).map_err(|_| format!("script file is not UTF-8 text: {value}"))?;
+    Ok(text.strip_prefix('\u{feff}').unwrap_or(text).to_string())
+}
+
+/// `value` without the single or double quotes around it, or `None` when a quote is not closed.
+fn unquote(value: &str) -> Option<&str> {
+    match value.chars().next() {
+        Some(q @ ('"' | '\'')) => value.get(1..).and_then(|v| v.strip_suffix(q)),
+        _ => Some(value),
+    }
+}
+
+/// The folder the file at `path` is in, without Windows' `\\?\` prefix: under that prefix `..` and
+/// `/` in the names joined to it would be read as plain characters.
+fn folder_of(path: &Path) -> Option<PathBuf> {
+    path.parent().map(|p| crate::cmd::findfiles::plain(p.to_path_buf()))
+}
+
+/// Does the path `p` have a `..` name, with `/` or `\` between names?
+fn has_parent(p: &str) -> bool {
+    p.split(['/', '\\']).any(|name| name == "..")
+}
+
+/// A real path as people read it.
+fn display(path: &Path) -> Arc<str> {
+    Arc::from(crate::cmd::findfiles::plain(path.to_path_buf()).to_string_lossy().as_ref())
+}
+
+impl Files {
+    /// The files of a run of the script at `path` (`None` for a script given as text), with the
+    /// `JSINCLUDE` folders `jsinclude`.
+    pub(crate) fn new(path: Option<&str>, jsinclude: Vec<PathBuf>) -> Self {
+        let real = path.and_then(|p| std::fs::canonicalize(p).ok());
+        let dir = real.as_deref().and_then(folder_of);
+        Self {
+            scope: dir.as_deref().map(ScriptScope::of_folder).unwrap_or_default(),
+            jsinclude,
+            include_path: Vec::new(),
+            files: 0,
+            bytes: 0,
+            probes: 0,
+            chain: real.into_iter().collect(),
+            levels: 0,
+            frames: vec![Frame { shown: Arc::from(path.unwrap_or_default()), dir }],
+        }
+    }
+
+    /// The `JSINCLUDE` folders of this process: absolute folders separated by `;`.
+    pub(crate) fn jsinclude_env() -> Vec<PathBuf> {
+        #[cfg(test)]
+        if let Some(list) = super::TEST_JSINCLUDE.with(|t| t.borrow().clone()) {
+            return list;
+        }
+        std::env::var("JSINCLUDE").map(|v| v.split(';').map(str::trim).filter(|p| !p.is_empty()).map(PathBuf::from).collect()).unwrap_or_default()
+    }
+
+    /// The file being run now, as `$.fileName` gives it (empty for a script given as text).
+    pub(crate) fn file_name(&self) -> String {
+        self.frames.last().map(|f| f.shown.to_string()).unwrap_or_default()
+    }
+
+    /// The `#includepath` list, as `$.includePath` gives it.
+    pub(crate) fn include_path(&self) -> String {
+        self.include_path.join(";")
+    }
+
+    /// The script's own text, `text`, with its preprocessor lines read.
+    pub(crate) fn expand_script(&mut self, text: &str) -> Result<Expanded, Failure> {
+        self.bytes = self.bytes.saturating_add(text.len());
+        let shown = self.frames.first().map(|f| f.shown.clone()).unwrap_or_else(|| Arc::from(""));
+        let dir = self.frames.first().and_then(|f| f.dir.clone());
+        self.expand(shown, dir, text, true)
+    }
+
+    /// The file `path` names for `$.evalFile`, relative to the file being run now, read and with its
+    /// preprocessor lines read. It becomes the file being run until [`Files::end_eval`].
+    pub(crate) fn eval_file(&mut self, path: &str) -> Result<Expanded, Failure> {
+        let current = self.frames.last().map(|f| f.shown.clone()).unwrap_or_else(|| Arc::from(""));
+        let fail = |kind, message: String| Failure { kind, message, index: 0, file: current.clone(), line: 0, column: 0 };
+        let dir = self.frames.last().and_then(|f| f.dir.clone());
+        let (real, bytes) = self.open(path, dir.as_deref(), false).map_err(|(kind, message)| fail(kind, message))?;
+        let text = self.admit(&real, bytes, path).map_err(|(kind, message)| fail(kind, message))?;
+        let shown = display(&real);
+        self.chain.push(real.clone());
+        self.levels += 1;
+        self.frames.push(Frame { shown: shown.clone(), dir: folder_of(&real) });
+        let r = self.expand(shown, folder_of(&real), &text, false);
+        if r.is_err() {
+            self.end_eval();
+        }
+        r
+    }
+
+    /// The file `$.evalFile` ran has ended.
+    pub(crate) fn end_eval(&mut self) {
+        if self.frames.len() > 1 {
+            self.frames.pop();
+            self.chain.pop();
+            self.levels = self.levels.saturating_sub(1);
+        }
+    }
+
+    /// Checks a file read at `real` against the run's limits and the files open now, and decodes
+    /// it. `value` is the path as the script wrote it.
+    fn admit(&mut self, real: &Path, bytes: Vec<u8>, value: &str) -> Result<String, (FailKind, String)> {
+        if self.chain.iter().any(|p| p == real) {
+            return Err((FailKind::Error, format!("include cycle: {value}")));
+        }
+        if self.levels >= MAX_DEPTH {
+            return Err((FailKind::Limit, format!("include depth limit ({MAX_DEPTH}) reached")));
+        }
+        if self.files >= MAX_FILES {
+            return Err((FailKind::Limit, format!("include file limit ({MAX_FILES}) reached")));
+        }
+        if self.bytes.saturating_add(bytes.len()) > MAX_TOTAL_BYTES {
+            return Err((FailKind::Limit, "script source limit reached (32 MiB)".to_string()));
+        }
+        self.files += 1;
+        self.bytes += bytes.len();
+        decode(&bytes, value).map_err(|m| (FailKind::Error, m))
+    }
+
+    /// Finds and reads the file `value` names, from the file in folder `dir`; with `search`, also in
+    /// the `#includepath` and `JSINCLUDE` folders.
+    fn open(&mut self, value: &str, dir: Option<&Path>, search: bool) -> Result<(PathBuf, Vec<u8>), (FailKind, String)> {
+        let path = Path::new(value);
+        let refused = || (FailKind::Error, format!("script file read refused: {value}"));
+        // A script given as text has no folder, and so no file it may read.
+        let Some(dir) = dir.filter(|_| !has_parent(value)) else { return Err(refused()) };
+        // Each candidate, and whether the scope's refusal passes it over.
+        let mut candidates: Vec<(Option<PathBuf>, bool)> = vec![(Some(dir.join(path)), false)];
+        if search && !path.is_absolute() {
+            candidates.extend(self.include_path.iter().map(|p| ((!has_parent(p)).then(|| dir.join(p).join(path)), false)));
+            candidates.extend(self.jsinclude.iter().filter(|p| p.is_absolute()).map(|p| (Some(p.join(path)), true)));
+        }
+        for (candidate, passed_over_when_refused) in candidates {
+            let Some(candidate) = candidate else { return Err(refused()) };
+            self.probes += 1;
+            if self.probes > MAX_PROBES {
+                return Err((FailKind::Limit, format!("include search limit ({MAX_PROBES} paths) reached")));
+            }
+            match self.scope.read(&candidate, crate::script::MAX_SOURCE_BYTES) {
+                Ok(found) => return Ok(found),
+                Err(ScriptRead::Missing) => {}
+                Err(ScriptRead::Refused) if passed_over_when_refused => {}
+                Err(ScriptRead::Refused) => return Err(refused()),
+                Err(ScriptRead::TooLarge) => return Err((FailKind::Limit, format!("script file is too large: {value}"))),
+                Err(ScriptRead::Failed(e)) => return Err((FailKind::Error, format!("cannot read script file {value}: {e}"))),
+            }
+        }
+        Err((FailKind::Error, format!("include file not found: {value}")))
+    }
+
+    /// `text`, the file `shown` in folder `dir`, with its preprocessor lines read. With `script`,
+    /// its `#script` line names the run.
+    fn expand(&mut self, shown: Arc<str>, dir: Option<PathBuf>, text: &str, script: bool) -> Result<Expanded, Failure> {
+        let mut out = Out { units: Vec::with_capacity(text.len()), line: 1, column: 0, after_cr: false, map: SourceMap::default() };
+        let mut name = None;
+        self.file(&mut out, shown, dir.as_deref(), text, script, &mut name)?;
+        let source = String::from_utf16(&out.units).map_err(|_| Failure {
+            kind: FailKind::Syntax,
+            message: "the script is not valid text".into(),
+            index: 0,
+            file: out.map.files.first().cloned().unwrap_or_else(|| Arc::from("")),
+            line: 0,
+            column: 0,
+        })?;
+        Ok(Expanded { source, map: out.map, name })
+    }
+
+    /// Adds file `shown` (in folder `dir`, with text `text`) to `out`, its included files in place
+    /// of their lines.
+    fn file(
+        &mut self,
+        out: &mut Out,
+        shown: Arc<str>,
+        dir: Option<&Path>,
+        text: &str,
+        script: bool,
+        name: &mut Option<String>,
+    ) -> Result<(), Failure> {
+        let index = out.map.files.len();
+        out.map.files.push(shown.clone());
+        let units: Vec<u16> = text.encode_utf16().collect();
+        out.begin(index, 1);
+        // A source with neither `#` nor `@` has no preprocessor line.
+        if !units.iter().any(|&u| u == u16::from(b'#') || u == u16::from(b'@')) {
+            out.emit(&units);
+            return Ok(());
+        }
+        let fail = |kind, message: String, line, column| Failure { kind, message, index, file: shown.clone(), line, column };
+        let options = Options { preprocessor_lines: true, max_source_units: MAX_TOTAL_BYTES, ..Options::default() };
+        let program = vectorcraft_js::parse_utf16(&units, &options).map_err(|e| fail(FailKind::Syntax, e.message, e.line, e.column))?;
+        let mut cursor = 0usize;
+        for d in &program.directives {
+            let (start, end) = (d.span.start as usize, d.span.end as usize);
+            let line_start =
+                units.get(..start).and_then(|u| u.iter().rposition(|&c| matches!(c, 0x0A | 0x0D | 0x2028 | 0x2029))).map_or(0, |i| i + 1);
+            let column = u32::try_from(start - line_start + 1).unwrap_or(u32::MAX);
+            let at = |kind, message: String| fail(kind, message, d.line, column);
+            out.emit(units.get(cursor..start).unwrap_or_default());
+            cursor = end;
+            let label = format!("{}{}", d.form, d.name);
+            if d.value.len() > MAX_VALUE_BYTES {
+                return Err(at(FailKind::Syntax, format!("the value of {label} is too long")));
+            }
+            let value = unquote(&d.value).ok_or_else(|| at(FailKind::Syntax, format!("unterminated quote in {label}")))?;
+            match d.known {
+                Some(DirectiveName::Include) => {
+                    if value.is_empty() {
+                        return Err(at(FailKind::Syntax, format!("{label} needs a file name")));
+                    }
+                    let (real, bytes) = self.open(value, dir, true).map_err(|(kind, message)| at(kind, message))?;
+                    let included = self.admit(&real, bytes, value).map_err(|(kind, message)| at(kind, message))?;
+                    self.chain.push(real.clone());
+                    self.levels += 1;
+                    let r = self.file(out, display(&real), folder_of(&real).as_deref(), &included, false, name);
+                    self.chain.pop();
+                    self.levels -= 1;
+                    r?;
+                    out.end_line();
+                    out.begin(index, d.line);
+                }
+                Some(DirectiveName::IncludePath) => {
+                    self.include_path = value.split(';').map(str::trim).filter(|p| !p.is_empty()).map(str::to_string).collect();
+                }
+                Some(DirectiveName::Script) => {
+                    if value.is_empty() {
+                        return Err(at(FailKind::Syntax, format!("{label} needs a name")));
+                    }
+                    if script && index == 0 {
+                        *name = Some(value.to_string());
+                    }
+                }
+                Some(DirectiveName::Target) => {
+                    if value.is_empty() {
+                        return Err(at(FailKind::Syntax, format!("{label} needs a value")));
+                    }
+                }
+                Some(DirectiveName::Strict) => match value.to_ascii_lowercase().as_str() {
+                    "off" => {}
+                    "on" => return Err(at(FailKind::Syntax, format!("unsupported strict checking: {label} on"))),
+                    _ => return Err(at(FailKind::Syntax, format!("{label} takes on or off"))),
+                },
+                Some(DirectiveName::TargetEngine) => return Err(at(FailKind::Syntax, format!("unsupported script directive: {label}"))),
+                None if d.name.eq_ignore_ascii_case("engine") => {
+                    return Err(at(FailKind::Syntax, format!("unsupported script directive: {label}")));
+                }
+                None => return Err(at(FailKind::Syntax, format!("unknown script directive: {label}"))),
+            }
+        }
+        out.emit(units.get(cursor..).unwrap_or_default());
+        Ok(())
+    }
+}

crates/engine/src/script/mod.rs

@@ -23,12 +23,18 @@
 //! and the 64 levels, 16 MiB and 1,048,576 entries of [`vectorcraft_js::DataLimits`]'s default,
 //! and the console's ([`console`]).
 //!
+//! Before a run starts, its preprocessor lines are read ([`include`]): included files take the
+//! place of their lines, and an error in one is reported at its own file, line and column.
+//! `$.evalFile(path)` runs another file in the same global environment and gives its last value,
+//! `$.fileName` is the file being run and `$.includePath` the `#includepath` list.
+//!
 //! A run writes to the Script Console with `$.write` and `$.writeln`, and `vc.log` adds a line
 //! there too. The session's console gets a start line, the run's output, its uncaught error, an end
 //! line and a report line; the run's report holds its own output and error, its time, its host
 //! calls by kind and its slowest commands.
 
 pub mod console;
+pub mod include;
 
 use std::cell::{Cell, RefCell};
 use std::collections::HashMap;
@@ -131,7 +137,11 @@ pub(crate) fn refused_text(id: &str) -> String {
 
 /// A request to run a script.
 pub(crate) struct Request {
+    /// The run's name; unless `name_given`, a `#script` line in the script replaces it.
     pub name: String,
+    pub name_given: bool,
+    /// The file the script was read from, which its included files are read beside.
+    pub file: Option<String>,
     pub source: String,
     pub args: Map<String, Value>,
     pub fuel: u64,
@@ -468,8 +478,20 @@ struct Host {
     commands: RefCell<HashMap<&'static str, (u64, u128, u128)>>,
     /// The time the run's slices took, in nanoseconds.
     run_nanos: Cell<u128>,
+    /// The files the run reads: its includes and `$.evalFile`'s.
+    files: RefCell<include::Files>,
+    /// Where the lines of the script's expanded source came from.
+    script_map: RefCell<include::SourceMap>,
+    /// The same for each source `$.evalFile` gave, in order.
+    eval_maps: RefCell<Vec<include::SourceMap>>,
+    /// The last error `$.evalFile` raised for a file it could not run, with the file, line and
+    /// column that error is at.
+    eval_failure: RefCell<Option<EvalFailure>>,
 }
 
+/// An error `$.evalFile` raised, as thrown, and the file, line and column it is at.
+type EvalFailure = (String, Arc<str>, u32, u32);
+
 /// A run's host calls by kind, as its report gives them in `hostCallCounts`.
 #[derive(Default)]
 struct Counts {
@@ -899,6 +921,8 @@ fn each_line(text: &str, mut done: impl FnMut(String, bool)) {
 
 /// The `$` object: `$.write(...values)` writes the values to the Script Console as `String(value)`
 /// gives them, one after another, and `$.writeln(...values)` does the same and ends the line.
+/// `$.evalFile(path[, timeout])` runs a file and gives its last value, `$.fileName` is the file
+/// being run and `$.includePath` the `#includepath` list.
 fn dollar_object(host: &Rc<Host>) -> Vec<(String, HostItem)> {
     let writer = |end: bool| {
         let h = host.clone();
@@ -910,7 +934,67 @@ fn dollar_object(host: &Rc<Host>) -> Vec<(String, HostItem)> {
             Ok(Data::Undefined)
         }))
     };
-    vec![("write".into(), writer(false)), ("writeln".into(), writer(true))]
+    let getter = |read: fn(&include::Files) -> String| {
+        let h = host.clone();
+        HostItem::Getter(function(move |_| {
+            let text = read(&h.files.borrow());
+            h.charge_call(text.len() as u64 + 2)?;
+            Ok(Data::String(text))
+        }))
+    };
+    let eval_file = {
+        let h = host.clone();
+        let end = host.clone();
+        HostItem::Evaluator { source: function(move |a| eval_file(&h, a)), end: Rc::new(move || end.files.borrow_mut().end_eval()) }
+    };
+    vec![
+        ("write".into(), writer(false)),
+        ("writeln".into(), writer(true)),
+        ("evalFile".into(), eval_file),
+        ("fileName".into(), getter(include::Files::file_name)),
+        ("includePath".into(), getter(include::Files::include_path)),
+    ]
+}
+
+/// `$.evalFile(path[, timeout])`: the source of the file `path` names, relative to the file being
+/// run, with its preprocessor lines read, which the interpreter then runs. `timeout`, in
+/// milliseconds, is taken and not waited on: the file is read at once.
+fn eval_file(host: &Host, args: Vec<Data>) -> std::result::Result<Data, HostError> {
+    let Some(Data::String(path)) = args.first().filter(|p| !matches!(p, Data::String(s) if s.is_empty())) else {
+        return Err(HostError::Type(EVAL_NO_PATH.to_string()));
+    };
+    match args.get(1) {
+        None | Some(Data::Undefined) => {}
+        Some(Data::Number(ms)) if ms.is_finite() && *ms >= 0.0 => {}
+        Some(Data::Number(_)) => return Err(HostError::Range(EVAL_TIMEOUT.to_string())),
+        Some(_) => return Err(HostError::Type(EVAL_TIMEOUT.to_string())),
+    }
+    if args.len() > 2 {
+        return Err(HostError::Type(EVAL_ARGUMENTS.to_string()));
+    }
+    host.charge_call(path.len() as u64 + 2)?;
+    let expanded = host.files.borrow_mut().eval_file(path).map_err(|f| {
+        let message = if f.line > 0 { format!("{}:{}:{}: {}", f.file, f.line, f.column, f.message) } else { f.message };
+        if f.line > 0 {
+            *host.eval_failure.borrow_mut() = Some((message.clone(), f.file.clone(), f.line, f.column));
+        }
+        match f.kind {
+            include::FailKind::Limit => HostError::Abort(message),
+            include::FailKind::Syntax => HostError::Syntax(message),
+            include::FailKind::Error => HostError::Error(message),
+        }
+    })?;
+    // A file without preprocessor lines is parsed here first, so its syntax error names its place.
+    let options = vectorcraft_js::Options { max_source_units: include::MAX_TOTAL_BYTES, ..vectorcraft_js::Options::default() };
+    if let Err(e) = vectorcraft_js::parse(&expanded.source, &options) {
+        host.files.borrow_mut().end_eval();
+        let (_, file, line, column) = expanded.map.locate(e.line, e.column);
+        let message = format!("{file}:{line}:{column}: {}", e.message);
+        *host.eval_failure.borrow_mut() = Some((message.clone(), file, line, column));
+        return Err(HostError::Syntax(message));
+    }
+    host.eval_maps.borrow_mut().push(expanded.map);
+    Ok(Data::String(expanded.source))
 }
 
 fn function(f: impl Fn(Vec<Data>) -> std::result::Result<Data, HostError> + 'static) -> HostFunction {
@@ -974,21 +1058,67 @@ fn kind_id(kind: &RunErrorKind) -> &'static str {
 }
 
 /// `message`, with what to do about a failure that comes from a script written for another program.
-fn explained(kind: &RunErrorKind, message: &str, source: &str, line: u32) -> String {
+fn explained(kind: &RunErrorKind, message: &str) -> String {
     const HOST_OBJECTS: &[&str] = &["app", "alert", "confirm", "prompt", "File", "Folder", "Window", "BridgeTalk", "activeDocument", "documents"];
     let names_host_object =
         message.strip_prefix("ReferenceError: ").is_some_and(|m| HOST_OBJECTS.iter().any(|o| m.split_whitespace().next() == Some(o)));
-    let directive =
-        *kind == RunErrorKind::Syntax && line > 0 && source.lines().nth(line as usize - 1).is_some_and(|l| l.trim_start().starts_with('#'));
     if *kind == RunErrorKind::Thrown && names_host_object {
         format!("{message} (scripts here use the `vc` object; objects other applications give their scripts are not available)")
-    } else if directive {
-        format!("{message} (preprocessor lines such as `#target` and `#include` are not read yet)")
     } else {
         message.to_string()
     }
 }
 
+/// The error of a run that stopped in its preprocessor lines (`f`), as the realm gives its own.
+fn preprocessor_error(f: include::Failure) -> (RunError, Option<Arc<str>>) {
+    let (kind, message) = match f.kind {
+        include::FailKind::Syntax if f.line > 0 => {
+            (RunErrorKind::Syntax, format!("SyntaxError: {} (line {}, column {})", f.message, f.line, f.column))
+        }
+        include::FailKind::Syntax => (RunErrorKind::Syntax, format!("SyntaxError: {}", f.message)),
+        include::FailKind::Error => (RunErrorKind::Thrown, format!("Error: {}", f.message)),
+        include::FailKind::Limit => (RunErrorKind::Limit(LimitKind::Host), f.message),
+    };
+    let file = (f.index > 0).then_some(f.file);
+    (RunError { kind, message, line: f.line, column: f.column }, file)
+}
+
+/// `e`, which the realm raised in source `tag` ([`Realm::error_source`]), at the line and column of
+/// the file it is in, with that file's name unless it is the script's own.
+fn located(host: &Host, tag: u32, e: &RunError) -> (RunError, Option<Arc<str>>) {
+    let map = |m: &include::SourceMap, own: bool| {
+        let (index, file, line, column) = m.locate(e.line, e.column);
+        let message = if e.kind == RunErrorKind::Syntax { relocated(&e.message, e.line, e.column, line, column) } else { e.message.clone() };
+        (RunError { kind: e.kind.clone(), message, line, column }, (!own || index > 0).then_some(file))
+    };
+    // An error `$.evalFile` raised for a file it could not run is at that file's place.
+    if let Some((_, file, line, column)) = host.eval_failure.borrow().as_ref().filter(|(thrown, ..)| e.message.contains(thrown.as_str())) {
+        let message = if e.kind == RunErrorKind::Syntax { relocated(&e.message, e.line, e.column, *line, *column) } else { e.message.clone() };
+        return (RunError { kind: e.kind.clone(), message, line: *line, column: *column }, Some(file.clone()));
+    }
+    if e.line == 0 {
+        return (e.clone(), None);
+    }
+    match tag {
+        0 => map(&host.script_map.borrow(), true),
+        n if n != vectorcraft_js::UNKNOWN_SOURCE => match host.eval_maps.borrow().get(n as usize - 1) {
+            Some(m) => map(m, false),
+            None => (e.clone(), None),
+        },
+        _ => (e.clone(), None),
+    }
+}
+
+/// A syntax error's `message`, which ends with its place `(line L, column C)`, with the place
+/// given as `line`, `column`.
+fn relocated(message: &str, old_line: u32, old_column: u32, line: u32, column: u32) -> String {
+    let old = format!(" (line {old_line}, column {old_column})");
+    match message.strip_suffix(&old) {
+        Some(m) => format!("{m} (line {line}, column {column})"),
+        None => message.to_string(),
+    }
+}
+
 impl Session {
     /// Is a script running? While one is, the commands that change anything are refused.
     pub fn script_running(&self) -> bool {
@@ -1091,8 +1221,8 @@ impl Session {
         Ok(())
     }
 
-    /// Begins a run of `request`.
-    pub(crate) fn script_start(&mut self, request: Request) -> Result<()> {
+    /// Begins a run of `request`. → the run's name.
+    pub(crate) fn script_start(&mut self, request: Request) -> Result<String> {
         self.settle_for_script()?;
         // In a build where a fault ends the program, every unsaved document has a copy first.
         if self.script_copy_first && self.docs.iter().any(DocState::is_dirty) && cmd::recovery::save_copies(self).is_err() {
@@ -1103,8 +1233,14 @@ impl Session {
         self.script_high_water.retain(|uid, _| open.contains(uid));
         self.script_stop.clear();
         self.script_report = None;
+        let mut files = include::Files::new(request.file.as_deref(), include::Files::jsinclude_env());
+        let expanded = files.expand_script(&request.source);
+        let name = match &expanded {
+            Ok(include::Expanded { name: Some(name), .. }) if !request.name_given => name.clone(),
+            _ => request.name,
+        };
         let limits = Limits { fuel: request.fuel, heap_bytes: HEAP_BYTES, ..Limits::default() };
-        let options = Options { max_source_units: MAX_SOURCE_BYTES.saturating_mul(2), ..Options::default() };
+        let options = Options { max_source_units: include::MAX_TOTAL_BYTES.saturating_mul(2), ..Options::default() };
         let mut realm = Realm::with_options(options, limits);
         realm.share_interrupt(&self.script_stop);
         realm.set_data_limits(DataLimits::default());
@@ -1126,34 +1262,45 @@ impl Session {
             log_bytes: Cell::new(0),
             written: RefCell::new(Vec::new()),
             run: self.script_runs,
-            name: console::line_name(&request.name),
+            name: console::line_name(&name),
             console: RefCell::default(),
             pending: RefCell::default(),
             counts: Counts::default(),
             commands: RefCell::default(),
             run_nanos: Cell::new(0),
+            files: RefCell::new(files),
+            script_map: RefCell::default(),
+            eval_maps: RefCell::default(),
+            eval_failure: RefCell::default(),
         });
         let args = to_data(&Value::Object(request.args), &DataLimits::default(), 0, &mut (0, 0))
             .map_err(|place| EngineError::BadParams { cmd: "script.run".into(), msg: format!("`args{place}` is nested more than 64 levels deep") })?;
         let line = console::ConsoleLine { run: host.run, name: host.name.clone(), entry: console::Entry::Start };
         self.script_console.push(line, false);
-        let started = realm
-            .define_host_object("vc", vc_object(&host, args))
-            .and_then(|()| realm.define_host_object("$", dollar_object(&host)))
-            .and_then(|()| realm.start(&request.source));
-        if let Err(e) = started {
-            let mut report = failure_report(&request.name, &e, &request.source, &host, 0, 0);
+        let started = match expanded {
+            Err(f) => Err(preprocessor_error(f)),
+            Ok(expanded) => {
+                *host.script_map.borrow_mut() = expanded.map;
+                realm
+                    .define_host_object("vc", vc_object(&host, args))
+                    .and_then(|()| realm.define_host_object("$", dollar_object(&host)))
+                    .and_then(|()| realm.start(&expanded.source))
+                    .map_err(|e| located(&host, realm.error_source(), &e))
+            }
+        };
+        if let Err((e, file)) = started {
+            let mut report = failure_report(&name, &e, file.as_deref(), &host, 0, 0);
             close_run(self, &host, &mut report, ending(&e.kind));
             let message = failure_text(&report);
             self.script_report = Some(report);
             return Err(EngineError::Other(message));
         }
         let scope = crate::file_access::ScopeHandle::capture();
-        let job = Job { realm, host, world: World::working(self), start_uids: open, name: request.name, scope };
+        let job = Job { realm, host, world: World::working(self), start_uids: open, name: name.clone(), scope };
         let id = NEXT_JOB.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         JOBS.with(|jobs| jobs.borrow_mut().insert(id, job));
         self.script_key = Some(JobKey(id));
-        Ok(())
+        Ok(name)
     }
 
     /// Advances the running script by one slice. `None` while it is still running; otherwise the
@@ -1194,7 +1341,8 @@ impl Session {
 
     fn script_failed(&mut self, job: Job, e: &RunError) -> Result<Value> {
         let fuel_left = job.realm.fuel_left();
-        let mut report = failure_report(&job.name, e, "", &job.host, fuel_left, job.realm.limits().fuel.saturating_sub(fuel_left));
+        let (e, file) = located(&job.host, job.realm.error_source(), e);
+        let mut report = failure_report(&job.name, &e, file.as_deref(), &job.host, fuel_left, job.realm.limits().fuel.saturating_sub(fuel_left));
         close_run(self, &job.host, &mut report, ending(&e.kind));
         drop(job);
         raise_ids(self);
@@ -1308,13 +1456,16 @@ const TOO_MANY_ARGUMENTS: &str = "vc.run: takes a command id and an object of pa
 const PARAMS_NOT_OBJECT: &str = "vc.run: the parameters must be an object";
 const LOG_FULL: &str = "vc.log: the log of this run is full";
 const NO_RECOVERY_COPY: &str = "a recovery copy could not be written, so the script was not run";
+const EVAL_NO_PATH: &str = "$.evalFile requires a file path";
+const EVAL_TIMEOUT: &str = "$.evalFile: the timeout must be a finite number of milliseconds, 0 or more";
+const EVAL_ARGUMENTS: &str = "$.evalFile: takes a file path and a timeout";
 
-/// The report of a run that failed.
-fn failure_report(name: &str, e: &RunError, source: &str, host: &Host, fuel_left: u64, fuel_used: u64) -> Value {
-    json!({
+/// The report of a run that failed; `file` is the included file the error is in.
+fn failure_report(name: &str, e: &RunError, file: Option<&str>, host: &Host, fuel_left: u64, fuel_used: u64) -> Value {
+    let mut report = json!({
         "ok": false,
         "kind": kind_id(&e.kind),
-        "message": explained(&e.kind, &e.message, source, e.line),
+        "message": explained(&e.kind, &e.message),
         "name": name,
         "line": e.line,
         "column": e.column,
@@ -1323,7 +1474,11 @@ fn failure_report(name: &str, e: &RunError, source: &str, host: &Host, fuel_left
         "fuelLeft": fuel_left,
         "fuelUsed": fuel_used,
         "hostCalls": host.calls.get(),
-    })
+    });
+    if let (Some(file), Some(o)) = (file, report.as_object_mut()) {
+        o.insert("file".into(), json!(file));
+    }
+    report
 }
 
 /// How the run that failed with `kind` ended, as its console end line gives it.
@@ -1361,8 +1516,11 @@ fn close_run(s: &mut Session, host: &Host, report: &mut Value, ending: console::
     if report["ok"] == false {
         let (line, column) = (report["line"].as_u64().unwrap_or(0), report["column"].as_u64().unwrap_or(0));
         let message = report["message"].as_str().unwrap_or_default();
-        let text =
-            if line > 0 { format!("{}:{line}:{column}: {message}", host.name) } else { format!("{}: location unavailable: {message}", host.name) };
+        let text = match report["file"].as_str() {
+            Some(file) if line > 0 => format!("{}: {file}:{line}:{column}: {message}", host.name),
+            _ if line > 0 => format!("{}:{line}:{column}: {message}", host.name),
+            _ => format!("{}: location unavailable: {message}", host.name),
+        };
         each_line(&text, |line, cut| line_to(s, host, console::Entry::Error(line), cut));
     }
     let timing = clock().is_some();
@@ -1386,7 +1544,11 @@ fn close_run(s: &mut Session, host: &Host, report: &mut Value, ending: console::
 fn failure_text(report: &Value) -> String {
     let s = |k: &str| report[k].as_str().unwrap_or_default();
     let (line, column) = (report["line"].as_u64().unwrap_or(0), report["column"].as_u64().unwrap_or(0));
-    let at = if line > 0 { format!(" line {line}, column {column}") } else { String::new() };
+    let at = match report["file"].as_str() {
+        Some(file) if line > 0 => format!(" line {line}, column {column} of {file}"),
+        _ if line > 0 => format!(" line {line}, column {column}"),
+        _ => String::new(),
+    };
     let written = report["written"].as_array().map_or(0, Vec::len);
     let kept = if written > 0 {
         let paths: Vec<&str> = report["written"].as_array().into_iter().flatten().filter_map(Value::as_str).collect();
@@ -1454,4 +1616,6 @@ thread_local! {
     pub(crate) static PANIC_IN_SLICE: Cell<bool> = const { Cell::new(false) };
     /// Tests: the objects a run may add in place of [`GROWTH_OBJECTS`].
     pub(crate) static TEST_GROWTH: Cell<Option<u64>> = const { Cell::new(None) };
+    /// Tests: the `JSINCLUDE` folders in place of the environment's.
+    pub(crate) static TEST_JSINCLUDE: RefCell<Option<Vec<std::path::PathBuf>>> = const { RefCell::new(None) };
 }