decl-lang 0.4.7

Decl — a declarative language for describing, generating, and validating structured data: the `decl` CLI (check / evaluate / validate / fmt) and the `decl-lsp` language server, implemented natively in Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
//! Packages, decl.toml, and decl.lock (§8.6–8.7) — a port of the
//! reference implementation's package.ts: exact-pinned dependencies,
//! fail-closed manifests, content-hashed reproducibility. Conventions:
//! dependency packages live under `<root>/decl_modules/<name>/` in a flat
//! layout, and the lock file is line-based `name version sha256` in name
//! order.
use crate::semantics::{json_str, read_json, Diag, Value};
use regex::Regex;
use sha2::{Digest, Sha256};
use std::path::{Path, PathBuf};
use std::rc::Rc;

const SEMANTIC: [&str; 2] = ["name", "version"];
const METADATA: [&str; 5] = [
    "description",
    "license",
    "authors",
    "repository",
    "keywords",
];

fn name_re() -> Regex {
    Regex::new(r"^[a-z][a-z0-9_-]*$").unwrap()
}
fn version_re() -> Regex {
    Regex::new(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$").unwrap()
}

#[derive(Clone, Debug)]
/// a `decl.toml` (§8.6)
pub struct Manifest {
    /// the package's name
    pub name: String,
    /// its version, an exact semantic version
    pub version: String,
    /// declaration order, like the reference's Map
    pub dependencies: Vec<(String, String)>,
}
impl Manifest {
    /// Whether the manifest declares a dependency of that name.
    pub fn has_dep(&self, n: &str) -> bool {
        self.dependencies.iter().any(|(d, _)| d == n)
    }
}

/// Read a manifest, fail-closed (D28): an unknown field is E3011, a range pin
/// E3012, a missing file E3004 — each reported through `report` with the code
/// and the message. `None` when the manifest cannot be used.
pub fn parse_manifest(path: &Path, report: &mut dyn FnMut(&str, String)) -> Option<Manifest> {
    let shown = path.display().to_string();
    let Ok(src) = std::fs::read_to_string(path) else {
        report("E3004", format!("manifest not found: {shown}"));
        return None;
    };
    let (name_re, version_re) = (name_re(), version_re());
    let comment = Regex::new(r"#.*$").unwrap();
    let sec_re = Regex::new(r"^\[([^\]]+)\]$").unwrap();
    let kv_re = Regex::new(r"^([A-Za-z0-9_-]+)\s*=\s*(.+)$").unwrap();
    let mut fields: Vec<(String, String)> = vec![];
    let mut deps: Vec<(String, String)> = vec![];
    let mut section: Option<String> = None;
    let mut ok = true;
    for line0 in src.split('\n') {
        let line = comment.replace(line0, "").trim().to_string();
        if line.is_empty() {
            continue;
        }
        if let Some(sec) = sec_re.captures(&line) {
            let s = sec[1].to_string();
            if s != "dependencies" {
                report(
                    "E3011",
                    format!("manifest {shown}: unknown section [{s}] (fail-closed, D28)"),
                );
                ok = false;
            }
            section = Some(s);
            continue;
        }
        let Some(kv) = kv_re.captures(&line) else {
            report(
                "E3011",
                format!("manifest {shown}: unparseable line \"{line}\""),
            );
            ok = false;
            continue;
        };
        let key = kv[1].to_string();
        let raw = kv[2].trim().to_string();
        let value: Option<String> = if raw.starts_with('"') {
            match read_json(&raw.replace('\\', "\\\\")) {
                Ok(Value::Str(s)) => Some(s.to_string()),
                Ok(_) => None,
                Err(_) => {
                    report(
                        "E3011",
                        format!("manifest {shown}: unparseable line \"{line}\""),
                    );
                    ok = false;
                    continue;
                }
            }
        } else {
            Some(raw.clone())
        };
        match section.as_deref() {
            Some("dependencies") => {
                if !name_re.is_match(&key) {
                    report(
                        "E3013",
                        format!("manifest {shown}: invalid package name {key}"),
                    );
                    ok = false;
                    continue;
                }
                match &value {
                    Some(v) if version_re.is_match(v) => deps.push((key, v.clone())),
                    _ => {
                        report("E3012", format!("manifest {shown}: dependency {key} = {raw} is not an exact semantic-version pin"));
                        ok = false;
                    }
                }
            }
            None => {
                if !SEMANTIC.contains(&key.as_str()) && !METADATA.contains(&key.as_str()) {
                    report(
                        "E3011",
                        format!("manifest {shown}: unknown field {key} (fail-closed, D28)"),
                    );
                    ok = false;
                    continue;
                }
                if let Some(v) = value {
                    fields.push((key, v));
                }
            }
            _ => {}
        }
    }
    let field = |k: &str| {
        fields
            .iter()
            .rev()
            .find(|(n, _)| n == k)
            .map(|(_, v)| v.clone())
            .unwrap_or_default()
    };
    let (name, version) = (field("name"), field("version"));
    if !name_re.is_match(&name) {
        report(
            "E3013",
            format!("manifest {shown}: invalid package name {}", json_str(&name)),
        );
        ok = false;
    }
    if !version_re.is_match(&version) {
        report(
            "E3012",
            format!(
                "manifest {shown}: version {} is not an exact triple",
                json_str(&version)
            ),
        );
        ok = false;
    }
    if ok {
        Some(Manifest {
            name,
            version,
            dependencies: deps,
        })
    } else {
        None
    }
}

/// content hash: SHA-256 over the package's module files in canonical path order (§8.7)
pub fn package_hash(dir: &Path) -> String {
    fn walk(d: &Path, out: &mut Vec<PathBuf>) {
        let Ok(rd) = std::fs::read_dir(d) else { return };
        let mut names: Vec<String> = rd
            .flatten()
            .map(|e| e.file_name().to_string_lossy().to_string())
            .collect();
        names.sort();
        for e in names {
            let p = d.join(&e);
            if e == "decl_modules" {
                continue;
            }
            if p.is_dir() {
                walk(&p, out);
            } else if e.ends_with(".decl") {
                out.push(p);
            }
        }
    }
    let mut files = vec![];
    walk(dir, &mut files);
    files.sort();
    let mut h = Sha256::new();
    for f in files {
        let rel = f
            .strip_prefix(dir)
            .unwrap_or(&f)
            .components()
            .map(|c| c.as_os_str().to_string_lossy().to_string())
            .collect::<Vec<_>>()
            .join("/");
        h.update(rel.as_bytes());
        h.update(b"\0");
        h.update(std::fs::read(&f).unwrap_or_default());
        h.update(b"\0");
    }
    // the digest as lowercase hex (sha2 0.11 no longer formats its array)
    h.finalize().iter().map(|b| format!("{b:02x}")).collect()
}

#[derive(Clone, Debug)]
/// a dependency resolved to a directory
pub struct ResolvedPackage {
    /// its name
    pub name: String,
    /// its version
    pub version: String,
    /// where it lives
    pub dir: PathBuf,
    /// the content hash of its files, the one the lock records
    pub hash: String,
}

/// maps a package specifier, from a directory, to the package's path or to a (code, message) diagnostic
pub type Resolver = Rc<dyn Fn(&str, &Path) -> Result<PathBuf, (String, String)>>;

/// the closed set of packages an entry file's manifest reaches (§8.6)
pub struct PackageUniverse {
    /// the directory holding `decl.toml`
    pub root_dir: PathBuf,
    /// that manifest
    pub manifest: Manifest,
    /// closed dependency set (root excluded), in resolution order
    pub packages: Vec<ResolvedPackage>,
    /// the resolver over the closed set
    pub resolver: Resolver,
    /// the manifest and resolution diagnostics
    pub diags: Vec<Diag>,
}
impl PackageUniverse {
    /// The resolved package of that name, when the closed set has it.
    pub fn package(&self, n: &str) -> Option<&ResolvedPackage> {
        self.packages.iter().find(|p| p.name == n)
    }
}

/// the enclosing package root (the nearest ancestor with decl.toml)
pub fn find_package_root(from_file: &Path) -> Option<PathBuf> {
    let abs = std::path::absolute(from_file).unwrap_or_else(|_| from_file.to_path_buf());
    let mut dir = abs.parent()?.to_path_buf();
    loop {
        if dir.join("decl.toml").exists() {
            return Some(dir);
        }
        let up = dir.parent()?.to_path_buf();
        if up == dir {
            return None;
        }
        dir = up;
    }
}

/// Open the package universe of an entry file: the manifest found upward from
/// it, its dependencies resolved to a closed set. `None` when no manifest
/// governs the entry.
pub fn open_package_universe(entry_file: &Path) -> Option<PackageUniverse> {
    let mut diags: Vec<Diag> = vec![];
    let root_dir = find_package_root(entry_file)?; // not in a package: relative imports only
    let mut report =
        |code: &str, message: String| diags.push(Diag::error(message, String::new(), Some(code)));
    let Some(manifest) = parse_manifest(&root_dir.join("decl.toml"), &mut report) else {
        return Some(PackageUniverse {
            root_dir,
            manifest: Manifest {
                name: "?".into(),
                version: "0.0.0".into(),
                dependencies: vec![],
            },
            packages: vec![],
            resolver: Rc::new(|_, _| Err(("E3011".into(), "unusable manifest".into()))),
            diags,
        });
    };

    // resolve the closed dependency set (flat decl_modules layout);
    // conflicting versions for one package are E3014 against both requirers
    let mut packages: Vec<ResolvedPackage> = vec![];
    let mut required_by: Vec<(String, String, String)> = vec![]; // dep, version, by
    fn visit(
        m: &Manifest,
        root_dir: &Path,
        packages: &mut Vec<ResolvedPackage>,
        required_by: &mut Vec<(String, String, String)>,
        report: &mut dyn FnMut(&str, String),
    ) {
        for (dep, ver) in &m.dependencies {
            if let Some((_, pv, pby)) = required_by.iter().find(|(d, _, _)| d == dep) {
                if pv != ver {
                    report(
                        "E3014",
                        format!(
                            "package {dep} required at {pv} (by {pby}) and {ver} (by {})",
                            m.name
                        ),
                    );
                    continue;
                }
            }
            if let Some(e) = required_by.iter_mut().find(|(d, _, _)| d == dep) {
                *e = (dep.clone(), ver.clone(), m.name.clone());
            } else {
                required_by.push((dep.clone(), ver.clone(), m.name.clone()));
            }
            if packages.iter().any(|p| &p.name == dep) {
                continue;
            }
            let dir = root_dir.join("decl_modules").join(dep);
            let Some(dm) = parse_manifest(&dir.join("decl.toml"), report) else {
                continue;
            };
            if &dm.name != dep {
                report(
                    "E3013",
                    format!(
                        "package at {} names itself {}, expected {dep}",
                        dir.display(),
                        dm.name
                    ),
                );
            }
            if &dm.version != ver {
                report(
                    "E3016",
                    format!(
                        "package {dep}: manifest version {} differs from required pin {ver}",
                        dm.version
                    ),
                );
            }
            packages.push(ResolvedPackage {
                name: dep.clone(),
                version: dm.version.clone(),
                dir: dir.clone(),
                hash: package_hash(&dir),
            });
            visit(&dm, root_dir, packages, required_by, report);
        }
    }
    visit(
        &manifest,
        &root_dir,
        &mut packages,
        &mut required_by,
        &mut report,
    );

    let resolver: Resolver = {
        let root_dir = root_dir.clone();
        let manifest = manifest.clone();
        let packages = packages.clone();
        Rc::new(move |spec: &str, from_dir: &Path| {
            let (pkg, rest) = match spec.find('/') {
                Some(i) => (&spec[..i], &spec[i + 1..]),
                None => (spec, ""),
            };
            // which package does the importing file belong to?
            let from_abs = std::path::absolute(from_dir).unwrap_or_else(|_| from_dir.to_path_buf());
            let from_pkg_dir = packages
                .iter()
                .find(|p| from_abs.starts_with(&p.dir))
                .map(|p| p.dir.clone())
                .unwrap_or_else(|| root_dir.clone());
            let from_manifest = if from_pkg_dir == root_dir {
                Some(manifest.clone())
            } else {
                parse_manifest(&from_pkg_dir.join("decl.toml"), &mut |_, _| {})
            };
            let from_name = from_manifest
                .as_ref()
                .map(|m| m.name.clone())
                .unwrap_or_else(|| "?".into());
            if !from_manifest.map(|m| m.has_dep(pkg)).unwrap_or(false) {
                return Err((
                    "E3010".into(),
                    format!("package {pkg} not declared in [dependencies] of {from_name}"),
                ));
            }
            let Some(p) = packages.iter().find(|p| p.name == pkg) else {
                return Err((
                    "E3004".into(),
                    format!("package {pkg} could not be resolved"),
                ));
            };
            Ok(if rest.is_empty() {
                p.dir.clone()
            } else {
                p.dir.join(rest)
            })
        })
    };
    Some(PackageUniverse {
        root_dir,
        manifest,
        packages,
        resolver,
        diags,
    })
}

// ---------------- decl.lock (§8.7) ----------------
/// The lock file's text (§8.7): one line per package, `name version hash`, sorted by name.
pub fn lock_text(u: &PackageUniverse) -> String {
    let mut ps: Vec<&ResolvedPackage> = u.packages.iter().collect();
    ps.sort_by(|a, b| a.name.cmp(&b.name));
    let lines: Vec<String> = ps
        .iter()
        .map(|p| format!("{} {} {}", p.name, p.version, p.hash))
        .collect();
    if lines.is_empty() {
        String::new()
    } else {
        lines.join("\n") + "\n"
    }
}
/// Write the lock file into the package root; returns its path.
pub fn write_lock(u: &PackageUniverse) -> PathBuf {
    let path = u.root_dir.join("decl.lock");
    let _ = std::fs::write(&path, lock_text(u));
    path
}
/// fail-closed verification: missing entry, version drift, or hash
/// mismatch stops resolution — never a silent re-resolve
pub fn verify_lock(u: &PackageUniverse) -> Vec<Diag> {
    let path = u.root_dir.join("decl.lock");
    let Ok(text) = std::fs::read_to_string(&path) else {
        return vec![];
    };
    let mut out = vec![];
    let mut report =
        |code: &str, message: String| out.push(Diag::error(message, String::new(), Some(code)));
    let mut locked: Vec<(String, String, String)> = vec![];
    for line in text.split('\n') {
        if line.trim().is_empty() {
            continue;
        }
        let parts: Vec<&str> = line.split_whitespace().collect();
        locked.push((
            parts[0].to_string(),
            parts.get(1).unwrap_or(&"").to_string(),
            parts.get(2).unwrap_or(&"").to_string(),
        ));
    }
    for p in &u.packages {
        let Some((_, v, h)) = locked.iter().find(|(n, _, _)| *n == p.name) else {
            report("E3015", format!("lock: missing entry for {}", p.name));
            continue;
        };
        if *v != p.version {
            report(
                "E3016",
                format!(
                    "lock: {} version {v} differs from manifest {}",
                    p.name, p.version
                ),
            );
        } else if *h != p.hash {
            report("E3017", format!("lock: {} content-hash mismatch", p.name));
        }
    }
    out
}