Skip to main content

vibe/
lexicon_pin.rs

1//! Lexicon pack pin + diagnose hooks (G-LEXICON-0).
2//!
3//! `lexicon:` is **not** an EBNF production. The pin is package metadata:
4//! a comment/header `// lexicon: "packId@SemVer"` and/or
5//! `const lexicon = "packId@SemVer";`.
6//!
7//! [`diagnose`](crate::diagnose) stays parse+check only (no disk, no invoke).
8//! Missing / unknown pack at the `GraphDatabase.lexicon_manifest` seam is
9//! documented here as DiagnoseReport JSON: **held / not yet** (`E300`) +
10//! `suggested_fix` that names “open lexicon pack”. Alias rows ride in
11//! `suggested_fix` as JSON `{from, to, framing}`. Living framing is never
12//! rewritten as artifact on upgrade.
13//!
14//! No Host widen. No dotted `qualia.*`. No in-binary WordNet.
15
16use crate::diagnose::DiagnoseReport;
17use crate::error::{DiagCode, Diagnostic};
18use crate::span::Span;
19
20/// Soft why-text for missing / unknown pack. Never "broken".
21pub const HELD_OPEN_PACK: &str = "held / not yet — open lexicon pack";
22
23/// Example pin matching `docs/manuals/standards/lexicon-pack-manifest-example.json`.
24pub const EXAMPLE_PIN: &str = "en-core@0.1.0";
25
26/// Live bind id (already in `ALL_BOUND`). Catalog-honest; not a new Host method.
27pub const LEXICON_MANIFEST_ID: &str = "GraphDatabase.lexicon_manifest";
28
29/// Recorded `lexicon: "packId@SemVer"` pin.
30#[derive(Debug, Clone, PartialEq, Eq)]
31pub struct LexiconPin {
32    pub pack_id: String,
33    pub pack_semver: String,
34}
35
36impl LexiconPin {
37    /// Parses.
38    pub fn parse(raw: &str) -> Option<Self> {
39        let raw = raw.trim().trim_matches('"').trim_end_matches(';').trim();
40        if raw.is_empty() {
41            return None;
42        }
43        let (pack_id, pack_semver) = raw.split_once('@')?;
44        let pack_id = pack_id.trim();
45        let pack_semver = pack_semver.trim();
46        if pack_id.is_empty() || !looks_like_semver(pack_semver) {
47            return None;
48        }
49        Some(Self {
50            pack_id: pack_id.to_string(),
51            pack_semver: pack_semver.to_string(),
52        })
53    }
54
55    /// `pin-str` form.
56    pub fn as_pin_str(&self) -> String {
57        format!("{}@{}", self.pack_id, self.pack_semver)
58    }
59}
60
61fn looks_like_semver(s: &str) -> bool {
62    let mut parts = s.split('.');
63    let major = parts.next().unwrap_or("");
64    let minor = parts.next().unwrap_or("");
65    let patch = parts.next().unwrap_or("");
66    !major.is_empty()
67        && major.chars().all(|c| c.is_ascii_digit())
68        && !minor.is_empty()
69        && minor.chars().all(|c| c.is_ascii_digit())
70        && !patch.is_empty()
71        && patch.chars().next().is_some_and(|c| c.is_ascii_digit())
72}
73
74/// Pack framing — living senses must not be Thing-washed as artifact.
75#[derive(Debug, Clone, Copy, PartialEq, Eq)]
76pub enum LexiconFraming {
77    LivingShacl,
78    ArtifactOwl,
79    Mixed,
80}
81
82impl LexiconFraming {
83    /// `str` form.
84    pub fn as_str(self) -> &'static str {
85        match self {
86            Self::LivingShacl => "living-SHACL",
87            Self::ArtifactOwl => "artifact-OWL",
88            Self::Mixed => "mixed",
89        }
90    }
91
92    /// Parses.
93    pub fn parse(raw: &str) -> Option<Self> {
94        match raw.trim() {
95            "living-SHACL" | "living_shacl" | "living" => Some(Self::LivingShacl),
96            "artifact-OWL" | "artifact_owl" | "artifact" => Some(Self::ArtifactOwl),
97            "mixed" => Some(Self::Mixed),
98            _ => None,
99        }
100    }
101}
102
103/// Alias row for migrate / `suggested_fix` (shape doc).
104#[derive(Debug, Clone, PartialEq, Eq)]
105pub struct AliasRow {
106    pub from: String,
107    pub to: String,
108    pub framing: LexiconFraming,
109}
110
111impl AliasRow {
112    /// Converts to json.
113    pub fn to_json(&self) -> String {
114        format!(
115            "{{\"from\":\"{}\",\"to\":\"{}\",\"framing\":\"{}\"}}",
116            escape_json(&self.from),
117            escape_json(&self.to),
118            self.framing.as_str()
119        )
120    }
121}
122
123/// Scan comment/header `lexicon: "packId@SemVer"` and `const lexicon = "…"`.
124pub fn parse_lexicon_pin_from_source(src: &str) -> Option<LexiconPin> {
125    for line in src.lines() {
126        let t = trim_line_comment(line);
127        if let Some(pin) = extract_lexicon_pragma(t) {
128            return Some(pin);
129        }
130        if let Some(pin) = extract_const_lexicon(t) {
131            return Some(pin);
132        }
133    }
134    None
135}
136
137fn trim_line_comment(line: &str) -> &str {
138    let t = line.trim();
139    t.strip_prefix("//").map(str::trim).unwrap_or(t)
140}
141
142fn extract_lexicon_pragma(t: &str) -> Option<LexiconPin> {
143    let rest = t.strip_prefix("lexicon:")?.trim();
144    LexiconPin::parse(rest)
145}
146
147fn extract_const_lexicon(t: &str) -> Option<LexiconPin> {
148    let rest = t.strip_prefix("const")?.trim();
149    let rest = rest.strip_prefix("lexicon")?.trim();
150    let rest = rest.strip_prefix('=')?.trim();
151    LexiconPin::parse(rest)
152}
153
154/// Expected DiagnoseReport when `lexicon_manifest` is missing / unknown.
155///
156/// `diagnose()` does not invoke the host. Neo maps the live E300 onto this shape.
157pub fn missing_pack_report(span: Span, message: impl Into<String>) -> DiagnoseReport {
158    let message = message.into();
159    let error = Diagnostic::new(DiagCode::E300, span, message).with_fix(HELD_OPEN_PACK);
160    DiagnoseReport {
161        valid: false,
162        kind: "module",
163        errors: vec![error.clone()],
164        error: Some(error),
165    }
166}
167
168/// Pin-aware diagnose hook for Neo (no disk).
169///
170/// `pack_available = false` → held / not yet + open-pack `suggested_fix`.
171/// `pack_available = true` → valid module; caller records the pin separately.
172pub fn diagnose_lexicon_pin(src: &str, pack_available: bool) -> DiagnoseReport {
173    match parse_lexicon_pin_from_source(src) {
174        None => DiagnoseReport {
175            valid: true,
176            kind: "module",
177            error: None,
178            errors: Vec::new(),
179        },
180        Some(_) if pack_available => DiagnoseReport {
181            valid: true,
182            kind: "module",
183            error: None,
184            errors: Vec::new(),
185        },
186        Some(pin) => missing_pack_report(
187            Span::point(0),
188            format!("lexicon pack not found (pin {})", pin.as_pin_str()),
189        ),
190    }
191}
192
193/// Encode alias rows as `suggested_fix` JSON array.
194pub fn alias_rows_suggested_fix(rows: &[AliasRow]) -> String {
195    let mut s = String::from("[");
196    for (i, row) in rows.iter().enumerate() {
197        if i > 0 {
198            s.push(',');
199        }
200        s.push_str(&row.to_json());
201    }
202    s.push(']');
203    s
204}
205
206/// Round-trip alias rows out of a `suggested_fix` JSON array (or mixed text).
207pub fn parse_alias_rows_json(src: &str) -> Vec<AliasRow> {
208    let mut rows = Vec::new();
209    let mut rest = src;
210    while let Some(start) = rest.find('{') {
211        let from_here = &rest[start..];
212        let Some(end) = from_here.find('}') else {
213            break;
214        };
215        let obj = &from_here[..=end];
216        if let (Some(from), Some(to), Some(fr)) = (
217            json_string_field(obj, "from"),
218            json_string_field(obj, "to"),
219            json_string_field(obj, "framing"),
220        ) {
221            if let Some(framing) = LexiconFraming::parse(&fr) {
222                rows.push(AliasRow { from, to, framing });
223            }
224        }
225        rest = &from_here[1..];
226    }
227    rows
228}
229
230/// Held report whose `suggested_fix` is alias-row JSON (migrate / upgrade).
231pub fn alias_migrate_report(span: Span, rows: &[AliasRow]) -> DiagnoseReport {
232    let fix = alias_rows_suggested_fix(rows);
233    let error = Diagnostic::new(
234        DiagCode::E300,
235        span,
236        "lexicon pack upgrade held — alias map required",
237    )
238    .with_fix(fix);
239    DiagnoseReport {
240        valid: false,
241        kind: "module",
242        errors: vec![error.clone()],
243        error: Some(error),
244    }
245}
246
247/// Upgrade remap: living-SHACL never becomes artifact-OWL.
248pub fn apply_upgrade_framing(
249    existing: LexiconFraming,
250    requested: LexiconFraming,
251) -> LexiconFraming {
252    if existing == LexiconFraming::LivingShacl && requested == LexiconFraming::ArtifactOwl {
253        LexiconFraming::LivingShacl
254    } else {
255        requested
256    }
257}
258
259/// Applies upgrade-map.
260pub fn apply_upgrade_map(rows: &[AliasRow], requested: &[LexiconFraming]) -> Vec<AliasRow> {
261    rows.iter()
262        .zip(requested.iter().copied().chain(std::iter::repeat(
263            requested.last().copied().unwrap_or(LexiconFraming::Mixed),
264        )))
265        .map(|(row, req)| AliasRow {
266            from: row.from.clone(),
267            to: row.to.clone(),
268            framing: apply_upgrade_framing(row.framing, req),
269        })
270        .collect()
271}
272
273/// `true` when living content was rewritten as an artifact.
274pub fn living_rewritten_as_artifact(before: &[AliasRow], after: &[AliasRow]) -> bool {
275    before.iter().any(|old| {
276        old.framing == LexiconFraming::LivingShacl
277            && after
278                .iter()
279                .any(|new| new.from == old.from && new.framing == LexiconFraming::ArtifactOwl)
280    })
281}
282
283fn json_string_field(obj: &str, key: &str) -> Option<String> {
284    let needle = format!("\"{key}\":");
285    let idx = obj.find(&needle)?;
286    let rest = obj[idx + needle.len()..].trim_start();
287    let rest = rest.strip_prefix('"')?;
288    let mut out = String::new();
289    let mut chars = rest.chars();
290    while let Some(c) = chars.next() {
291        match c {
292            '\\' => {
293                if let Some(n) = chars.next() {
294                    out.push(n);
295                }
296            }
297            '"' => break,
298            c => out.push(c),
299        }
300    }
301    Some(out)
302}
303
304fn escape_json(value: &str) -> String {
305    let mut out = String::new();
306    for c in value.chars() {
307        match c {
308            '"' => out.push_str("\\\""),
309            '\\' => out.push_str("\\\\"),
310            '\n' => out.push_str("\\n"),
311            c => out.push(c),
312        }
313    }
314    out
315}
316
317/// Minimal pack-manifest field read (fixture / example JSON; no serde).
318#[derive(Debug, Clone, PartialEq, Eq)]
319pub struct PackManifest {
320    pub pack_id: String,
321    pub pack_semver: String,
322    pub framing: LexiconFraming,
323    pub uplift_from: String,
324    pub concept_ids: Vec<String>,
325}
326
327/// Parses pack-manifest-json.
328pub fn parse_pack_manifest_json(raw: &str) -> Option<PackManifest> {
329    let pack_id = json_string_field(raw, "packId")?;
330    let pack_semver = json_string_field(raw, "packSemVer")?;
331    let framing = LexiconFraming::parse(&json_string_field(raw, "framing")?)?;
332    let uplift_from = json_string_field(raw, "upliftFrom").unwrap_or_default();
333    let concept_ids = parse_string_array_field(raw, "conceptIds");
334    Some(PackManifest {
335        pack_id,
336        pack_semver,
337        framing,
338        uplift_from,
339        concept_ids,
340    })
341}
342
343fn parse_string_array_field(raw: &str, key: &str) -> Vec<String> {
344    let needle = format!("\"{key}\":");
345    let Some(idx) = raw.find(&needle) else {
346        return Vec::new();
347    };
348    let rest = raw[idx + needle.len()..].trim_start();
349    let Some(rest) = rest.strip_prefix('[') else {
350        return Vec::new();
351    };
352    let end = rest.find(']').unwrap_or(rest.len());
353    rest[..end]
354        .split(',')
355        .filter_map(|part| {
356            let s = part.trim().trim_matches('"');
357            if s.is_empty() {
358                None
359            } else {
360                Some(s.to_string())
361            }
362        })
363        .collect()
364}
365
366#[cfg(test)]
367mod tests {
368    use super::*;
369
370    #[test]
371    fn pin_parses_en_core() {
372        let pin = LexiconPin::parse(EXAMPLE_PIN).unwrap();
373        assert_eq!(pin.pack_id, "en-core");
374        assert_eq!(pin.pack_semver, "0.1.0");
375        assert_eq!(pin.as_pin_str(), EXAMPLE_PIN);
376    }
377
378    #[test]
379    fn held_voice_never_says_broken() {
380        let r = missing_pack_report(Span::point(0), "lexicon pack not found");
381        let json = r.to_json();
382        assert!(!r.valid);
383        assert_eq!(r.error.as_ref().unwrap().code, DiagCode::E300);
384        assert!(json.contains("\"error_code\":\"E300\""));
385        assert!(json.contains("held / not yet"));
386        assert!(json.contains("open lexicon pack"));
387        assert!(!json.to_ascii_lowercase().contains("broken"));
388        assert!(json.contains("\"suggested_fix\""));
389        assert!(json.contains("\"errors\":["));
390    }
391
392    #[test]
393    fn alias_rows_round_trip() {
394        let rows = [
395            AliasRow {
396                from: "arrive".into(),
397                to: "concept:arrive".into(),
398                framing: LexiconFraming::LivingShacl,
399            },
400            AliasRow {
401                from: "volume".into(),
402                to: "concept:volume".into(),
403                framing: LexiconFraming::ArtifactOwl,
404            },
405        ];
406        let fix = alias_rows_suggested_fix(&rows);
407        let back = parse_alias_rows_json(&fix);
408        assert_eq!(back, rows);
409    }
410
411    #[test]
412    fn living_not_rewritten_as_artifact() {
413        let before = [AliasRow {
414            from: "person".into(),
415            to: "concept:person".into(),
416            framing: LexiconFraming::LivingShacl,
417        }];
418        let after = apply_upgrade_map(&before, &[LexiconFraming::ArtifactOwl]);
419        assert_eq!(after[0].framing, LexiconFraming::LivingShacl);
420        assert!(!living_rewritten_as_artifact(&before, &after));
421    }
422}