Skip to main content

harn_modules/
source_documents.rs

1//! Portable source names with an immutable, host-private file lookup.
2use serde::{Deserialize, Serialize};
3use sha2::{Digest, Sha256};
4use std::collections::{BTreeMap, BTreeSet};
5use std::path::{Component, Path, PathBuf};
6
7use crate::{normalize_path, stdlib_module_name, ModuleGraph};
8
9/// A host-private cached mapping, never part of the portable IR.
10#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(deny_unknown_fields)]
12pub struct SourceDocumentRecord {
13    pub document: String,
14    pub path: PathBuf,
15}
16
17/// A source name is opaque. Only this graph-owned map can resolve it to a file.
18#[derive(Clone, Debug)]
19pub struct SourceDocuments {
20    documents: BTreeMap<PathBuf, String>,
21    physical: BTreeMap<String, PathBuf>,
22}
23
24impl SourceDocuments {
25    /// Retain only real physical mappings in the compilation manifest.
26    pub fn records(&self) -> Vec<SourceDocumentRecord> {
27        self.physical
28            .iter()
29            .map(|(document, path)| SourceDocumentRecord {
30                document: document.clone(),
31                path: path.clone(),
32            })
33            .collect()
34    }
35
36    /// Restore a previously validated host manifest without resolving imports.
37    /// The host must also bind this exact census to its validated source files.
38    pub fn from_records(records: Vec<SourceDocumentRecord>) -> Result<Self, SourceDocumentError> {
39        if records.is_empty() {
40            return Err(SourceDocumentError::InvalidRecords);
41        }
42        let mut result = Self {
43            documents: BTreeMap::new(),
44            physical: BTreeMap::new(),
45        };
46        for record in records {
47            if !record.path.is_absolute()
48                || record
49                    .path
50                    .components()
51                    .any(|component| matches!(component, Component::ParentDir | Component::CurDir))
52                || !valid_document(&record.document)
53                || result.documents.contains_key(&record.path)
54                || result.physical.contains_key(&record.document)
55            {
56                return Err(SourceDocumentError::InvalidRecords);
57            }
58            result.insert(record.path, record.document)?;
59        }
60        Ok(result)
61    }
62
63    /// Look up an exact module path from the graph; do not resolve new aliases.
64    pub fn document_for(&self, path: &Path) -> Option<&str> {
65        self.documents.get(path).map(String::as_str)
66    }
67
68    /// Resolve a known real source. Synthetic stdlib names grant no disk access.
69    pub fn resolve(&self, document: &str) -> Option<&Path> {
70        self.physical.get(document).map(PathBuf::as_path)
71    }
72
73    pub fn physical_paths(&self) -> impl Iterator<Item = &Path> {
74        self.physical.values().map(PathBuf::as_path)
75    }
76
77    fn insert(&mut self, path: PathBuf, document: String) -> Result<(), SourceDocumentError> {
78        if self
79            .physical
80            .get(&document)
81            .is_some_and(|existing| existing != &path)
82        {
83            return Err(SourceDocumentError::DocumentCollision(document));
84        }
85        self.physical.insert(document.clone(), path.clone());
86        self.documents.insert(path, document);
87        Ok(())
88    }
89}
90
91#[derive(Clone, Debug, PartialEq, Eq)]
92pub enum SourceDocumentError {
93    UnknownEntry,
94    InvalidRecords,
95    InvalidPath(PathBuf),
96    UnavailablePackageRoot(String),
97    UnmappedPackageScope(PathBuf),
98    DocumentCollision(String),
99}
100
101impl std::fmt::Display for SourceDocumentError {
102    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
103        match self {
104            Self::UnknownEntry => formatter.write_str("entry is not a real module in this graph"),
105            Self::InvalidRecords => {
106                formatter.write_str("source records are empty, malformed, or ambiguous")
107            }
108            Self::InvalidPath(path) => {
109                write!(formatter, "source path cannot be named: {}", path.display())
110            }
111            Self::UnavailablePackageRoot(alias) => {
112                write!(formatter, "package root is unavailable: {alias}")
113            }
114            Self::UnmappedPackageScope(path) => write!(
115                formatter,
116                "package source has no resolved import route: {}",
117                path.display()
118            ),
119            Self::DocumentCollision(document) => write!(
120                formatter,
121                "multiple source files have document identity {document}"
122            ),
123        }
124    }
125}
126
127impl std::error::Error for SourceDocumentError {}
128
129impl ModuleGraph {
130    /// Name the complete resolved graph without exposing machine-specific roots.
131    ///
132    /// Package aliases and roots come from the snapshots retained by the import
133    /// resolver. Canonical path dependencies therefore keep their package name
134    /// even when their actual directory lies outside the entry's project.
135    pub fn source_documents(&self, entry: &Path) -> Result<SourceDocuments, SourceDocumentError> {
136        let entry = normalize_path(entry);
137        if !entry.is_absolute() || !self.modules.contains_key(&entry) {
138            return Err(SourceDocumentError::UnknownEntry);
139        }
140        let entry_directory = entry.parent().ok_or(SourceDocumentError::UnknownEntry)?;
141        // Several aliases can refer to the same canonical package. They share
142        // one document namespace; the source graph already has one module for
143        // that physical file and one defining scope for its imports.
144        let mut packages = BTreeMap::<PathBuf, BTreeSet<String>>::new();
145        for snapshot in &self._package_snapshots {
146            for alias in snapshot.package_names() {
147                let root = snapshot.packages_root().join(alias);
148                let root = root
149                    .canonicalize()
150                    .map_err(|_| SourceDocumentError::UnavailablePackageRoot(alias.clone()))?;
151                if !root.is_dir() {
152                    return Err(SourceDocumentError::UnavailablePackageRoot(alias.clone()));
153                }
154                packages.entry(root).or_default().insert(alias.clone());
155            }
156        }
157        // An entry executed from a package is still the local source root of
158        // this compilation. Its own modules need no incoming package edge.
159        packages.retain(|root, _| !entry.starts_with(root));
160
161        let mut result = SourceDocuments {
162            documents: BTreeMap::new(),
163            physical: BTreeMap::new(),
164        };
165        let paths = self.module_paths();
166        let mut pending = BTreeSet::new();
167        for path in &paths {
168            if let Some(module) = stdlib_module_name(path) {
169                let document = format!("harn:synthetic/std/{}", encode_path(Path::new(module))?);
170                result.documents.insert(path.clone(), document);
171                continue;
172            }
173            if !path.is_absolute() {
174                return Err(SourceDocumentError::InvalidPath(path.clone()));
175            }
176            if package_root(&packages, path).is_none() {
177                let document = format!(
178                    "harn:source/{}",
179                    relative_document_path(entry_directory, path)?
180                );
181                result.insert(path.clone(), document.clone())?;
182                pending.insert((document, path.clone()));
183            }
184        }
185
186        // Use only edges already resolved by ModuleGraph. A package namespace
187        // commits to its portable incoming scope, so the same alias in two
188        // dependency scopes cannot collide. The ordered frontier picks one
189        // deterministic route for aliases of the same canonical package and
190        // visits cycles once. No cache directory or lockfile path enters it.
191        let mut namespaces = BTreeMap::<PathBuf, String>::new();
192        while let Some((importer_document, importer)) = pending.pop_first() {
193            for import in self.imports_for_module(&importer) {
194                let Some(path) = import.resolved_path else {
195                    continue;
196                };
197                if result.documents.contains_key(&path) || !self.modules.contains_key(&path) {
198                    continue;
199                }
200                let Some((root, aliases)) = package_root(&packages, &path) else {
201                    continue;
202                };
203                let namespace = namespaces.entry(root.clone()).or_insert_with(|| {
204                    let alias = aliases.first().expect("snapshot package alias");
205                    let mut hash = Sha256::new();
206                    hash.update(b"harn-source-package-route-v1\0");
207                    hash.update(importer_document.as_bytes());
208                    hash.update(b"\0");
209                    hash.update(alias.as_bytes());
210                    format!("harn:package/{alias}/{}/", hex::encode(hash.finalize()))
211                });
212                let relative = path.strip_prefix(root).expect("matched package root");
213                let document = format!("{namespace}{}", encode_path(relative)?);
214                result.insert(path.clone(), document.clone())?;
215                pending.insert((document, path));
216            }
217        }
218        if let Some(path) = paths
219            .into_iter()
220            .find(|path| !result.documents.contains_key(path))
221        {
222            return Err(SourceDocumentError::UnmappedPackageScope(path));
223        }
224        Ok(result)
225    }
226}
227
228fn package_root<'a>(
229    packages: &'a BTreeMap<PathBuf, BTreeSet<String>>,
230    path: &Path,
231) -> Option<(&'a PathBuf, &'a BTreeSet<String>)> {
232    packages
233        .iter()
234        .filter(|(root, _)| path.starts_with(root))
235        .max_by_key(|(root, _)| root.components().count())
236}
237
238fn valid_document(document: &str) -> bool {
239    let path = if let Some(path) = document.strip_prefix("harn:source/") {
240        path
241    } else if let Some(package) = document.strip_prefix("harn:package/") {
242        let mut parts = package.splitn(3, '/');
243        let Some(alias) = parts.next() else {
244            return false;
245        };
246        let Some(digest) = parts.next() else {
247            return false;
248        };
249        let Some(path) = parts.next() else {
250            return false;
251        };
252        if !crate::package_snapshot::is_valid_package_name(alias)
253            || digest.len() != 64
254            || !digest
255                .bytes()
256                .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
257        {
258            return false;
259        }
260        path
261    } else {
262        return false;
263    };
264    path.split('/').all(|segment| {
265        if segment.is_empty() || matches!(segment, "." | "..") {
266            return false;
267        }
268        let mut bytes = segment.bytes();
269        while let Some(byte) = bytes.next() {
270            if byte == b'%' {
271                for _ in 0..2 {
272                    if !bytes
273                        .next()
274                        .is_some_and(|hex| hex.is_ascii_digit() || (b'A'..=b'F').contains(&hex))
275                    {
276                        return false;
277                    }
278                }
279            } else if !(byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'~')) {
280                return false;
281            }
282        }
283        true
284    })
285}
286
287fn relative_document_path(base: &Path, path: &Path) -> Result<String, SourceDocumentError> {
288    let base_components = base.components().collect::<Vec<_>>();
289    let path_components = path.components().collect::<Vec<_>>();
290    // Different Windows volumes have no entry-relative spelling. Refuse instead
291    // of embedding an absolute drive or assigning an unstable fallback name.
292    if base_components.first() != path_components.first() {
293        return Err(SourceDocumentError::InvalidPath(path.to_path_buf()));
294    }
295    let common = base_components
296        .iter()
297        .zip(&path_components)
298        .take_while(|(a, b)| a == b)
299        .count();
300    let mut relative = PathBuf::new();
301    for _ in common..base_components.len() {
302        relative.push("..");
303    }
304    for component in &path_components[common..] {
305        relative.push(component.as_os_str());
306    }
307    encode_path(&relative)
308}
309
310const SOURCE_SEGMENT: &percent_encoding::AsciiSet = &percent_encoding::NON_ALPHANUMERIC
311    .remove(b'-')
312    .remove(b'_')
313    .remove(b'.')
314    .remove(b'~');
315
316fn encode_path(path: &Path) -> Result<String, SourceDocumentError> {
317    let mut names = Vec::new();
318    for component in path.components() {
319        match component {
320            // Keep parent components opaque so URI consumers cannot collapse
321            // them into a different namespace. They never grant filesystem access.
322            Component::ParentDir => names.push("%2E%2E".to_owned()),
323            Component::Normal(name) => {
324                let name = name
325                    .to_str()
326                    .ok_or_else(|| SourceDocumentError::InvalidPath(path.to_path_buf()))?;
327                names.push(percent_encoding::utf8_percent_encode(name, SOURCE_SEGMENT).to_string());
328            }
329            Component::CurDir => {}
330            Component::RootDir | Component::Prefix(_) => {
331                return Err(SourceDocumentError::InvalidPath(path.to_path_buf()));
332            }
333        }
334    }
335    if names.is_empty() {
336        return Err(SourceDocumentError::InvalidPath(path.to_path_buf()));
337    }
338    Ok(names.join("/"))
339}
340
341#[cfg(test)]
342#[path = "source_documents_tests.rs"]
343mod tests;