opy_rs/manifest/
mod.rs

1//! The OPY semantic compatibility manifest (issue #109).
2//!
3//! This module owns the Wright-authored, reference-validated semantic table
4//! that the frontend resolves builtin names, member functions, receiver
5//! categories, signatures/arity, parameter enum-domain identities, and
6//! non-contextual source aliases against — the authoritative replacement for
7//! the hardcoded `KNOWN_ENUMS` table and the semantic catalog-coverage gap
8//! behind `unknown-action`/`unknown-value`/`unsupported-member` emission
9//! failures.
10//!
11//! * The data lives in [`data/manifest.json`](data/manifest.json) (schema
12//!   v1, per the compatibility-manifest spec).
13//! * Every entry records the pinned-oracle probe that validates it
14//!   (`probes/probes.json`); `probes/validate.py` runs each probe against the
15//!   pinned OverPy 9.7.10 oracle and verifies accept/reject, emission hash,
16//!   and diagnostic category deterministically.
17//! * `catalogId` links each entry to the Workshop emission catalog by
18//!   canonical identity without duplicating localization/output spelling
19//!   data. The wright repository cross-checks every declared id against its
20//!   emission catalog; opy-rs does not copy the catalog itself.
21//!
22//! Ownership boundary: the **function**, **alias**, and **module** tables are
23//! OPY *source-language API* metadata (OverPy's documented language API;
24//! Wright-authored, probe-validated) and are not Workshop content data.
25//! Workshop *content/catalog* data — enum member lists, settings keys,
26//! mode/team/hero/map names — is Workshop-owned and is not carried here:
27//! `param.domain` and the contextual-domain machinery are catalog *identity*
28//! links only (no member validation), and validation that would need the
29//! canonical Workshop enum catalog is `lowering-dependent` (issue #8),
30//! never approximated.
31//!
32//! The manifest is language-compatibility metadata, not runtime content data
33//! (issue #96 stays deferred), and it is Wright-authored data validated
34//! against observed oracle behavior — never a mechanical conversion of
35//! OverPy's GPL-3.0 data files (ADR-0004, `docs/licensing.md` in the wright
36//! repository).
37
38use std::collections::{HashMap, HashSet};
39use std::sync::OnceLock;
40
41use serde::{Deserialize, Serialize};
42
43/// The embedded schema-v1 manifest data.
44pub const MANIFEST_DATA: &str = include_str!("data/manifest.json");
45
46/// The embedded probe evidence record for the manifest data.
47pub const PROBES_DATA: &str = include_str!("probes/probes.json");
48
49/// The pinned reference identity the manifest data is validated against.
50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
51pub struct Reference {
52    pub name: String,
53    pub version: String,
54    #[serde(rename = "contentCommit")]
55    pub content_commit: String,
56    pub integrity: String,
57}
58
59/// Provenance of the manifest data.
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
61pub struct Provenance {
62    pub generator: String,
63    pub license: String,
64    pub reviewed: bool,
65}
66
67/// The kind of a builtin function entry.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
69#[serde(rename_all = "camelCase")]
70pub enum FunctionKind {
71    /// A generic action (`chaseOverTime(...)` as a statement).
72    Action,
73    /// A generic value (`isGameInProgress()` in an expression).
74    Value,
75    /// An action called on a receiver (`eventPlayer.setMoveSpeed(100)`).
76    MemberAction,
77    /// A value called on a receiver (`eventPlayer.isAlive()`).
78    MemberValue,
79}
80
81/// How the frontend-owned function identity connects to Workshop lowering.
82///
83/// `canonical` entries carry a `catalogId`; the other variants are explicit
84/// reasons why a source-level function does not have a direct catalog entry.
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
86#[serde(rename_all = "kebab-case")]
87pub enum CatalogLink {
88    #[default]
89    Canonical,
90    SpecialLowering,
91    LegacyAlias,
92    CatalogGap,
93}
94
95impl FunctionKind {
96    /// Whether this kind is an action (statement-position builtin).
97    pub fn is_action(self) -> bool {
98        matches!(self, FunctionKind::Action | FunctionKind::MemberAction)
99    }
100
101    /// Whether this kind is a value (expression-position builtin).
102    pub fn is_value(self) -> bool {
103        matches!(self, FunctionKind::Value | FunctionKind::MemberValue)
104    }
105
106    /// Whether this kind is a receiver member function.
107    pub fn is_member(self) -> bool {
108        matches!(self, FunctionKind::MemberAction | FunctionKind::MemberValue)
109    }
110}
111
112/// The declared receiver category of a member function.
113///
114/// `Player` is the metadata category for player-oriented members (the pinned
115/// reference does not type-check those receivers, so the frontend does not
116/// reject them); `Variable` and `String` are enforced where the reference
117/// semantics are clear (`.append` requires an assignable receiver, `.format`
118/// requires a string literal).
119#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
120#[serde(rename_all = "PascalCase")]
121pub enum ReceiverCategory {
122    Player,
123    Variable,
124    String,
125    Vector,
126    Any,
127}
128
129impl ReceiverCategory {
130    /// A human-readable description of the category for diagnostics.
131    pub fn describe(self) -> &'static str {
132        match self {
133            ReceiverCategory::Player => "a player-valued expression",
134            ReceiverCategory::Variable => "an assignable variable",
135            ReceiverCategory::String => "a string literal",
136            ReceiverCategory::Vector => "a vector-valued expression",
137            ReceiverCategory::Any => "any expression",
138        }
139    }
140}
141
142/// A parameter default that the frontend expands: a function call, enum
143/// member (`"MEMBER"`), or scalar (`0.016`).
144#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
145#[serde(untagged)]
146pub enum ParamDefault {
147    Call { call: String },
148    EnumMember(String),
149    Bool(bool),
150    Number(f64),
151}
152
153/// One ordered parameter of a function entry.
154#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
155#[serde(rename_all = "camelCase")]
156pub struct Param {
157    pub name: String,
158    /// The enum domain this parameter requires, when it is an enum argument.
159    #[serde(default)]
160    pub domain: Option<String>,
161    /// An explicit default the frontend may expand; see [`ParamDefault`].
162    #[serde(default)]
163    pub default: Option<ParamDefault>,
164    /// Whether the argument is omittable without an emitted expansion
165    /// (`"optional": true`; the reference accepts the short form).
166    #[serde(default)]
167    pub optional: bool,
168    /// Whether the argument must be passed as a keyword (`name = expr`):
169    /// the reference `chase` form requires its 3rd argument to be
170    /// `rate = ...` or `duration = ...` (issue #110).
171    #[serde(default)]
172    pub keyword_only: bool,
173    /// Whether the argument can only be passed positionally (keyword
174    /// binding is rejected): the reference `chase` form's leading arguments
175    /// (issue #110).
176    #[serde(default)]
177    pub positional_only: bool,
178    /// Additional accepted keyword spellings for this parameter (the
179    /// reference `chase` form accepts both `rate` and `duration` for its
180    /// 3rd argument).
181    #[serde(default)]
182    pub alternate_names: Vec<String>,
183    /// Whether the argument must be a variable reference (a global variable
184    /// or a player variable); the chase family requires a variable first
185    /// argument to select the global/player emission form.
186    #[serde(default)]
187    pub variable: bool,
188}
189
190/// One builtin function entry (generic action/value or member function).
191#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
192#[serde(rename_all = "camelCase")]
193pub struct Function {
194    pub id: String,
195    pub kind: FunctionKind,
196    /// The receiver category of member functions.
197    #[serde(default)]
198    pub receiver: Option<ReceiverCategory>,
199    #[serde(default)]
200    pub params: Vec<Param>,
201    /// Whether the argument count is unbounded (`.format` placeholders).
202    #[serde(default)]
203    pub unbounded: bool,
204    /// Whether keyword arguments are accepted (`name = expr`). Defaults to
205    /// `true` (the reference's `parseArgs` applies to every workshop
206    /// function); entries the reference routes around that mechanism
207    /// (`range`, `random.*`, `.format`) declare `"keywordArgs": false`
208    /// (issue #110).
209    #[serde(default = "default_keyword_args")]
210    pub keyword_args: bool,
211    /// The canonical Workshop catalog id this entry emits through; absent
212    /// when emission is special-cased or not yet catalog-covered.
213    #[serde(default)]
214    #[serde(rename = "catalogId")]
215    pub catalog_id: Option<String>,
216    /// The explicit reason a source-level function has no direct catalog id.
217    #[serde(default)]
218    pub catalog_link: CatalogLink,
219    /// The probe ids that validate this entry against the pinned oracle.
220    #[serde(default)]
221    pub evidence: Vec<String>,
222}
223
224impl Function {
225    /// The (minimum, maximum) argument count: the first parameter with a
226    /// default makes every following parameter optional; `unbounded` entries
227    /// accept any count.
228    pub fn arity_bounds(&self) -> (usize, Option<usize>) {
229        if self.unbounded {
230            return (0, None);
231        }
232        let first_default = self
233            .params
234            .iter()
235            .position(|param| param.default.is_some() || param.optional);
236        let min = first_default.unwrap_or(self.params.len());
237        (min, Some(self.params.len()))
238    }
239}
240
241fn default_keyword_args() -> bool {
242    true
243}
244
245/// A non-contextual source alias: a pure name rewrite to a declared entry.
246#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
247#[serde(rename_all = "camelCase")]
248pub struct Alias {
249    pub source: String,
250    pub target: String,
251    pub kind: AliasKind,
252    #[serde(default)]
253    pub evidence: Vec<String>,
254}
255
256/// The alias target class; `functionAlias` targets a generic function,
257/// `memberAlias` a member function.
258#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
259#[serde(rename_all = "camelCase")]
260pub enum AliasKind {
261    FunctionAlias,
262    MemberAlias,
263}
264
265/// One recorded probe in the embedded evidence record.
266#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
267#[serde(rename_all = "camelCase")]
268pub struct Probe {
269    pub id: String,
270    pub source: String,
271    pub sha256: String,
272    pub expect: String,
273    #[serde(default)]
274    pub output_sha256: Option<String>,
275    #[serde(default)]
276    pub diagnostic_contains: Option<String>,
277}
278
279/// A validation failure while loading the manifest.
280#[derive(Debug, Clone, PartialEq, Eq)]
281pub struct ManifestError(pub String);
282
283impl std::fmt::Display for ManifestError {
284    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
285        f.write_str(&self.0)
286    }
287}
288
289impl std::error::Error for ManifestError {}
290
291/// The validated OPY semantic compatibility manifest.
292#[derive(Debug, Clone)]
293pub struct Manifest {
294    pub schema_version: u32,
295    pub reference: Reference,
296    pub functions: Vec<Function>,
297    pub aliases: Vec<Alias>,
298    pub provenance: Provenance,
299    /// The recorded probe evidence (`probes/probes.json`).
300    pub probes: Vec<Probe>,
301    by_function: HashMap<String, usize>,
302    by_member: HashMap<String, usize>,
303    alias_by_source: HashMap<String, usize>,
304    /// The declared enum-domain identities: every `param.domain` and
305    /// contextual option domain in the function table. Identity links only —
306    /// member lists are Workshop-owned catalog content and are not carried
307    /// here (lowering-dependent validation, #8).
308    domain_identities: HashSet<String>,
309}
310
311#[derive(Serialize, Deserialize)]
312#[serde(rename_all = "camelCase")]
313struct ManifestFile {
314    schema_version: u32,
315    reference: Reference,
316    #[serde(default)]
317    functions: Vec<Function>,
318    #[serde(default)]
319    aliases: Vec<Alias>,
320    provenance: Provenance,
321}
322
323#[derive(Serialize, Deserialize)]
324#[serde(rename_all = "camelCase")]
325struct ProbesFile {
326    schema_version: u32,
327    #[serde(default)]
328    probes: Vec<Probe>,
329}
330
331impl Manifest {
332    /// Parse and validate manifest data plus its probe evidence record.
333    pub fn load(manifest_json: &str, probes_json: &str) -> Result<Manifest, ManifestError> {
334        let file: ManifestFile = serde_json::from_str(manifest_json)
335            .map_err(|error| ManifestError(format!("manifest data: {error}")))?;
336        if file.schema_version != 1 {
337            return Err(ManifestError(format!(
338                "unsupported manifest schemaVersion {}",
339                file.schema_version
340            )));
341        }
342        let probes_file: ProbesFile = serde_json::from_str(probes_json)
343            .map_err(|error| ManifestError(format!("probes data: {error}")))?;
344        if probes_file.schema_version != 1 {
345            return Err(ManifestError(format!(
346                "unsupported probes schemaVersion {}",
347                probes_file.schema_version
348            )));
349        }
350        let mut manifest = Manifest {
351            schema_version: file.schema_version,
352            reference: file.reference.clone(),
353            functions: Vec::new(),
354            aliases: Vec::new(),
355            provenance: file.provenance.clone(),
356            probes: probes_file.probes,
357            by_function: HashMap::new(),
358            by_member: HashMap::new(),
359            alias_by_source: HashMap::new(),
360            domain_identities: HashSet::new(),
361        };
362        manifest.validate(file)?;
363        Ok(manifest)
364    }
365
366    fn validate(&mut self, file: ManifestFile) -> Result<(), ManifestError> {
367        // Probe ids must be unique and must record the accept probes the
368        // entries reference.
369        let mut probes: HashMap<&str, &Probe> = HashMap::new();
370        for probe in &self.probes {
371            if probes.insert(&probe.id, probe).is_some() {
372                return Err(ManifestError(format!("duplicate probe id '{}'", probe.id)));
373            }
374        }
375
376        // Functions: unique ids, member-only receiver/kind combinations,
377        // declared enum domains, declared enum-default members, and probe
378        // evidence that records acceptance.
379        for function in &file.functions {
380            if self.by_function.contains_key(&function.id) {
381                return Err(ManifestError(format!(
382                    "duplicate function id '{}'",
383                    function.id
384                )));
385            }
386            match function.kind {
387                FunctionKind::MemberAction | FunctionKind::MemberValue => {
388                    if function.receiver.is_none() {
389                        return Err(ManifestError(format!(
390                            "member function '{}' declares no receiver category",
391                            function.id
392                        )));
393                    }
394                }
395                FunctionKind::Action | FunctionKind::Value => {
396                    if function.receiver.is_some() {
397                        return Err(ManifestError(format!(
398                            "non-member function '{}' declares a receiver category",
399                            function.id
400                        )));
401                    }
402                }
403            }
404            for param in function.params.iter() {
405                if let Some(domain) = &param.domain {
406                    // A parameter may declare the function's own contextual
407                    // domain (`chase`'s `ChaseReeval`): it resolves only in
408                    // this signature's context and is not a standalone
409                    // identity.
410                    let is_contextual = crate::lower::policy::is_contextual_domain(domain);
411                    if !is_contextual {
412                        self.domain_identities.insert(domain.clone());
413                    }
414                } else if matches!(param.default, Some(ParamDefault::EnumMember(_))) {
415                    return Err(ManifestError(format!(
416                        "function '{}' parameter '{}' has an enum-member default but no \
417                         declared domain",
418                        function.id, param.name
419                    )));
420                }
421                if param.keyword_only && param.positional_only {
422                    return Err(ManifestError(format!(
423                        "function '{}' parameter '{}' cannot be both keyword-only and \
424                         positional-only",
425                        function.id, param.name
426                    )));
427                }
428                for alternate in &param.alternate_names {
429                    if alternate == &param.name {
430                        return Err(ManifestError(format!(
431                            "function '{}' parameter '{}' repeats its name as an \
432                             alternate keyword spelling",
433                            function.id, param.name
434                        )));
435                    }
436                    if function.params.iter().any(|other| {
437                        !std::ptr::eq(other, param)
438                            && (&other.name == alternate
439                                || other.alternate_names.contains(alternate))
440                    }) {
441                        return Err(ManifestError(format!(
442                            "function '{}' alternate keyword spelling '{alternate}' \
443                             collides with another parameter",
444                            function.id
445                        )));
446                    }
447                }
448            }
449            match (&function.catalog_id, function.catalog_link) {
450                (Some(_), CatalogLink::Canonical)
451                | (None, CatalogLink::SpecialLowering)
452                | (None, CatalogLink::LegacyAlias)
453                | (None, CatalogLink::CatalogGap) => {}
454                (Some(id), link) => {
455                    return Err(ManifestError(format!(
456                        "function '{}' has catalogId '{id}' but catalogLink is {:?}",
457                        function.id, link
458                    )));
459                }
460                (None, CatalogLink::Canonical) => {
461                    return Err(ManifestError(format!(
462                        "function '{}' has no catalogId or explicit catalogLink reason",
463                        function.id
464                    )));
465                }
466            }
467            crate::lower::policy::validate(function).map_err(ManifestError)?;
468            if let Some(contextual) = crate::lower::policy::contextual_domain(&function.id) {
469                for option in contextual.options {
470                    self.domain_identities.insert(option.domain.to_string());
471                }
472            }
473            self.check_evidence(&function.id, &function.evidence, &probes)?;
474            if function.kind.is_member() {
475                self.by_member
476                    .insert(function.id.clone(), self.functions.len());
477            } else {
478                self.by_function
479                    .insert(function.id.clone(), self.functions.len());
480            }
481            self.functions.push(function.clone());
482        }
483
484        // Aliases: unique sources, declared targets of the matching class,
485        // no collision with declared function ids.
486        for alias in &file.aliases {
487            if self.alias_by_source.contains_key(&alias.source) {
488                return Err(ManifestError(format!(
489                    "duplicate alias source '{}'",
490                    alias.source
491                )));
492            }
493            if self.by_function.contains_key(&alias.source)
494                || self.by_member.contains_key(&alias.source)
495            {
496                return Err(ManifestError(format!(
497                    "alias source '{}' collides with a declared function",
498                    alias.source
499                )));
500            }
501            match alias.kind {
502                AliasKind::FunctionAlias => {
503                    if self.function(&alias.target).is_none() {
504                        return Err(ManifestError(format!(
505                            "alias '{}' targets '{}' which is not a generic function",
506                            alias.source, alias.target
507                        )));
508                    }
509                }
510                AliasKind::MemberAlias => {
511                    if self.member(&alias.target).is_none() {
512                        return Err(ManifestError(format!(
513                            "alias '{}' targets '{}' which is not a member function",
514                            alias.source, alias.target
515                        )));
516                    }
517                }
518            }
519            self.check_evidence(&alias.source, &alias.evidence, &probes)?;
520            self.alias_by_source
521                .insert(alias.source.clone(), self.aliases.len());
522            self.aliases.push(alias.clone());
523        }
524
525        Ok(())
526    }
527
528    fn check_evidence(
529        &self,
530        owner: &str,
531        evidence: &[String],
532        probes: &HashMap<&str, &Probe>,
533    ) -> Result<(), ManifestError> {
534        if evidence.is_empty() {
535            return Err(ManifestError(format!(
536                "entry '{owner}' records no oracle probe evidence"
537            )));
538        }
539        for probe_id in evidence {
540            let probe = probes.get(probe_id.as_str()).ok_or_else(|| {
541                ManifestError(format!(
542                    "entry '{owner}' references undeclared probe '{probe_id}'"
543                ))
544            })?;
545            if probe.expect != "success" {
546                return Err(ManifestError(format!(
547                    "entry '{owner}' references probe '{probe_id}' which does not record \
548                     oracle acceptance"
549                )));
550            }
551        }
552        Ok(())
553    }
554
555    /// The built-in manifest, loaded once from the embedded data.
556    pub fn builtin() -> Result<&'static Manifest, ManifestError> {
557        static MANIFEST: OnceLock<Result<Manifest, ManifestError>> = OnceLock::new();
558        MANIFEST
559            .get_or_init(|| Manifest::load(MANIFEST_DATA, PROBES_DATA))
560            .as_ref()
561            .map_err(Clone::clone)
562    }
563
564    /// A generic (non-member) function by source name, alias-aware.
565    pub fn resolve_function(&self, name: &str) -> Option<&Function> {
566        self.function(name).or_else(|| {
567            let alias = self.alias_by_source.get(name)?;
568            let alias = &self.aliases[*alias];
569            (alias.kind == AliasKind::FunctionAlias)
570                .then(|| self.function(&alias.target))
571                .flatten()
572        })
573    }
574
575    /// A member function by source name, alias-aware.
576    pub fn resolve_member(&self, name: &str) -> Option<&Function> {
577        self.member(name).or_else(|| {
578            let alias = self.alias_by_source.get(name)?;
579            let alias = &self.aliases[*alias];
580            (alias.kind == AliasKind::MemberAlias)
581                .then(|| self.member(&alias.target))
582                .flatten()
583        })
584    }
585
586    /// The function entry with the given id, if declared.
587    pub fn function(&self, id: &str) -> Option<&Function> {
588        self.by_function.get(id).map(|i| &self.functions[*i])
589    }
590
591    /// The member function entry with the given id, if declared.
592    pub fn member(&self, id: &str) -> Option<&Function> {
593        self.by_member.get(id).map(|i| &self.functions[*i])
594    }
595
596    /// Whether the name is a declared enum-domain identity: a `param.domain`
597    /// or contextual option domain in the function table. These are OPY
598    /// signature metadata (catalog identity links); the domain *member
599    /// lists* are Workshop-owned catalog content and are not carried here,
600    /// so member validation is `lowering-dependent` (issue #8).
601    pub fn domain_identity(&self, name: &str) -> bool {
602        self.domain_identities.contains(name)
603    }
604}
605
606/// Canonicalize manifest data: parse, validate, and re-serialize
607/// deterministically (object keys sorted, stable formatting). Re-running on
608/// the same input produces byte-identical output, so the data is
609/// reproducible and the committed file must equal its canonical form.
610pub fn canonicalize(manifest_json: &str, probes_json: &str) -> Result<String, ManifestError> {
611    Manifest::load(manifest_json, probes_json)?;
612    let value: serde_json::Value = serde_json::from_str(manifest_json)
613        .map_err(|error| ManifestError(format!("manifest data: {error}")))?;
614    serde_json::to_string_pretty(&value)
615        .map(|mut out| {
616            out.push('\n');
617            out
618        })
619        .map_err(|error| ManifestError(format!("cannot serialize manifest: {error}")))
620}
621
622#[cfg(test)]
623mod tests {
624    use super::*;
625
626    #[test]
627    fn builtin_manifest_loads_and_validates() {
628        let manifest = Manifest::builtin().expect("embedded manifest must validate");
629        assert_eq!(manifest.schema_version, 1);
630        assert_eq!(manifest.reference.name, "overpy");
631        assert_eq!(manifest.reference.version, "9.7.10");
632        assert_eq!(
633            manifest.reference.content_commit,
634            "889d9749d1def17f146548cbddb94ea1ab015847"
635        );
636        assert!(!manifest.functions.is_empty());
637        assert!(!manifest.aliases.is_empty());
638        // Enum-domain *identities* come from the function signatures
639        // (param.domain / contextual option domains); member lists are
640        // Workshop-owned catalog content and are not carried here. Every
641        // member entry declares a receiver; every entry has evidence.
642        for domain in ["Invis", "ChaseTimeReeval", "Team", "LosCheck", "Color"] {
643            assert!(manifest.domain_identity(domain), "{domain}");
644        }
645        assert_eq!(
646            manifest
647                .function("chase")
648                .expect("chase entry")
649                .catalog_link,
650            CatalogLink::SpecialLowering
651        );
652        assert_eq!(
653            manifest
654                .member("getHero")
655                .expect("getHero entry")
656                .catalog_link,
657            CatalogLink::Canonical
658        );
659        assert!(
660            !manifest.domain_identity("ChaseReeval"),
661            "contextual domains are not standalone identities"
662        );
663        for function in &manifest.functions {
664            assert!(!function.evidence.is_empty(), "{}", function.id);
665            if function.kind.is_member() {
666                assert!(function.receiver.is_some(), "{}", function.id);
667            }
668        }
669    }
670
671    #[test]
672    fn manifest_data_is_canonical() {
673        // The committed data file must equal its deterministic canonical
674        // rewrite (the `build` path), so the data pipeline is reproducible.
675        let canonical = canonicalize(MANIFEST_DATA, PROBES_DATA).expect("canonicalizes");
676        assert_eq!(canonical, MANIFEST_DATA, "manifest.json must be canonical");
677        // Idempotency: re-canonicalizing the canonical form is byte-stable.
678        assert_eq!(
679            canonicalize(&canonical, PROBES_DATA).expect("re-canonicalizes"),
680            canonical
681        );
682    }
683
684    #[test]
685    fn manifest_omits_contextual_lowering_policy() {
686        assert!(!MANIFEST_DATA.contains("\"contextualDomain\""));
687        assert!(!MANIFEST_DATA.contains("\"context\": \"forIterable\""));
688    }
689
690    #[test]
691    fn validation_rejects_duplicates_and_missing_evidence() {
692        fn mutate(mutate: impl FnOnce(&mut ManifestFile)) -> Result<Manifest, ManifestError> {
693            let mut file: ManifestFile = serde_json::from_str(MANIFEST_DATA).unwrap();
694            mutate(&mut file);
695            Manifest::load(&serde_json::to_string(&file).unwrap(), PROBES_DATA)
696        }
697        // duplicate function id
698        let error = mutate(|file| file.functions.push(file.functions[0].clone()))
699            .expect_err("duplicate function id must fail");
700        assert!(error.0.contains("duplicate function id"));
701        // A direct catalog link must be explicit about being canonical.
702        let error = mutate(|file| file.functions[0].catalog_link = CatalogLink::CatalogGap)
703            .expect_err("canonical catalog id must not carry a gap reason");
704        assert!(error.0.contains("catalogLink"));
705        // entry without evidence
706        let error = mutate(|file| file.functions[0].evidence.clear())
707            .expect_err("missing evidence must fail");
708        assert!(error.0.contains("no oracle probe evidence"));
709        // enum-member default without a declared domain is a data-integrity
710        // error (the default cannot be expanded without an identity)
711        let error = mutate(|file| {
712            file.functions[0].params.push(Param {
713                name: "bad".to_string(),
714                domain: None,
715                default: Some(ParamDefault::EnumMember("X".to_string())),
716                optional: false,
717                keyword_only: false,
718                positional_only: false,
719                alternate_names: Vec::new(),
720                variable: false,
721            })
722        })
723        .expect_err("enum default without a domain must fail");
724        assert!(error.0.contains("no declared domain"));
725    }
726
727    #[test]
728    fn arity_bounds_follow_defaults_and_unbounded() {
729        let manifest = Manifest::builtin().expect("builtin");
730        let chase = manifest.function("chaseOverTime").expect("entry");
731        assert_eq!(chase.arity_bounds(), (3, Some(4)));
732        let radius = manifest.function("getPlayersInRadius").expect("entry");
733        assert_eq!(radius.arity_bounds(), (2, Some(4)));
734        let status = manifest.member("setStatusEffect").expect("entry");
735        assert_eq!(status.arity_bounds(), (3, Some(3)));
736        let format = manifest.member("format").expect("entry");
737        assert_eq!(format.arity_bounds(), (0, None));
738        let range = manifest.function("range").expect("entry");
739        assert_eq!(range.arity_bounds(), (1, Some(3)));
740        assert_eq!(
741            crate::lower::policy::function_context(&range.id),
742            Some(crate::lower::policy::FunctionContext::ForIterable)
743        );
744    }
745
746    #[test]
747    fn aliases_resolve_to_declared_targets() {
748        let manifest = Manifest::builtin().expect("builtin");
749        let alias = manifest
750            .resolve_function("stopChasingVariable")
751            .expect("alias");
752        assert_eq!(alias.id, "stopChasingVariable");
753        assert!(alias.kind.is_action());
754        let member = manifest.resolve_member("getCurrentHero").expect("alias");
755        assert_eq!(member.id, "getHero");
756        assert!(member.kind.is_value());
757        // Unknown names stay unresolved.
758        assert!(manifest.resolve_function("frobnicate").is_none());
759        assert!(manifest.resolve_member("frobnicate").is_none());
760    }
761}
opy_rs/manifest/mod.rs

opy_rs/manifest/
mod.rs
