1use 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#[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#[derive(Clone, Debug)]
19pub struct SourceDocuments {
20 documents: BTreeMap<PathBuf, String>,
21 physical: BTreeMap<String, PathBuf>,
22}
23
24impl SourceDocuments {
25 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 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 pub fn document_for(&self, path: &Path) -> Option<&str> {
65 self.documents.get(path).map(String::as_str)
66 }
67
68 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 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 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 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 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 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 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;