Skip to main content

qualia_cli/ingest/
detect.rs

1use std::fs::File;
2use std::io::Read;
3use std::path::Path;
4
5/// Serialization formats supported by the ingest pipeline.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum SemanticFormat {
8    NTriples,
9    NTriplesStar,
10    NQuads,
11    NQuadsStar,
12    Turtle,
13    TurtleStar,
14    TriG,
15    TriGStar,
16    N3,
17    RdfXml,
18    JsonLd,
19    JsonLdStar,
20    CborLd,
21    Kml,
22    Chk,
23    Q42,
24    AgentIntentJsonl,
25    /// 3D mesh asset (Wavefront OBJ, STL, or binary glTF) — geometry → semantic NQuins.
26    Mesh,
27}
28
29impl SemanticFormat {
30    /// Label.
31    pub fn label(self) -> &'static str {
32        match self {
33            SemanticFormat::NTriples => "N-Triples",
34            SemanticFormat::NTriplesStar => "N-Triples-Star",
35            SemanticFormat::NQuads => "N-Quads",
36            SemanticFormat::NQuadsStar => "N-Quads-Star",
37            SemanticFormat::Turtle => "Turtle",
38            SemanticFormat::TurtleStar => "Turtle-Star",
39            SemanticFormat::TriG => "TriG",
40            SemanticFormat::TriGStar => "TriG-Star",
41            SemanticFormat::N3 => "N3",
42            SemanticFormat::RdfXml => "RDF/XML",
43            SemanticFormat::JsonLd => "JSON-LD",
44            SemanticFormat::JsonLdStar => "JSON-LD-Star",
45            SemanticFormat::CborLd => "CBOR-LD",
46            SemanticFormat::Kml => "KML",
47            SemanticFormat::Chk => "CHK",
48            SemanticFormat::Q42 => "Q42",
49            SemanticFormat::AgentIntentJsonl => "Agent-Intent-JSONL",
50            SemanticFormat::Mesh => "Mesh (OBJ/STL/GLB)",
51        }
52    }
53}
54
55/// Detect the serialization format of a file by inspecting its extension and
56/// the first 16 bytes of content (magic bytes).
57///
58/// Extension check runs first (O(1)); magic-byte read is a fallback disambiguation
59/// step that opens the file for at most 16 bytes.  Returns `None` only when
60/// neither heuristic yields a conclusive result.
61pub fn detect_format(path: &Path) -> Option<SemanticFormat> {
62    let ext = path
63        .extension()
64        .and_then(|e| e.to_str())
65        .map(|s| s.to_ascii_lowercase());
66
67    // Read up to 16 magic bytes without allocating more than that.
68    let mut magic = [0u8; 16];
69    let magic_len = File::open(path)
70        .ok()
71        .and_then(|mut f| f.read(&mut magic).ok())
72        .unwrap_or(0);
73    let magic = &magic[..magic_len];
74
75    // ── Magic-byte checks (format-definitive) ────────────────────────────
76
77    // Q42 binary vault
78    if magic.len() >= 3 && &magic[..3] == b"Q42" {
79        return Some(SemanticFormat::Q42);
80    }
81    // QCHK / CHK profile blob
82    if magic.len() >= 4 && &magic[..4] == b"QCHK" {
83        return Some(SemanticFormat::Chk);
84    }
85    // GLB (binary glTF) — "glTF" magic.
86    if magic.starts_with(b"glTF") {
87        return Some(SemanticFormat::Mesh);
88    }
89    // CBOR-LD: standard CBOR self-describe tag 0xd9 0xd9 0xf7
90    if magic.len() >= 3 && magic[0] == 0xd9 && magic[1] == 0xd9 && magic[2] == 0xf7 {
91        return Some(SemanticFormat::CborLd);
92    }
93    // CBOR definite-length map (0xa0–0xb7) — only commit if extension confirms
94    if magic.len() >= 1 && (0xa0..=0xb7).contains(&magic[0]) {
95        if matches!(ext.as_deref(), Some("cbor") | Some("cborld")) {
96            return Some(SemanticFormat::CborLd);
97        }
98    }
99
100    // XML envelope — distinguish KML from RDF/XML by extension
101    let starts_xml =
102        magic.starts_with(b"<?xml") || magic.starts_with(b"<rdf:") || magic.starts_with(b"<RDF:");
103    if starts_xml {
104        return match ext.as_deref() {
105            Some("kml") => Some(SemanticFormat::Kml),
106            _ => Some(SemanticFormat::RdfXml),
107        };
108    }
109
110    // JSON envelope: { or [ — use extension to pick LD vs LD-Star
111    if magic.first().copied() == Some(b'{') || magic.first().copied() == Some(b'[') {
112        return match ext.as_deref() {
113            Some("jsonld-star") | Some("json-ld-star") => Some(SemanticFormat::JsonLdStar),
114            Some("jsonl") => Some(SemanticFormat::AgentIntentJsonl),
115            _ => Some(SemanticFormat::JsonLd),
116        };
117    }
118
119    // ── Extension fallback ────────────────────────────────────────────────
120    match ext.as_deref() {
121        Some("nt") => Some(SemanticFormat::NTriples),
122        Some("nts") | Some("nt-star") => Some(SemanticFormat::NTriplesStar),
123        Some("nq") => Some(SemanticFormat::NQuads),
124        Some("nqs") | Some("nq-star") => Some(SemanticFormat::NQuadsStar),
125        Some("ttl") => Some(SemanticFormat::Turtle),
126        Some("ttls") | Some("ttl-star") => Some(SemanticFormat::TurtleStar),
127        Some("trig") => Some(SemanticFormat::TriG),
128        Some("trigs") | Some("trig-star") => Some(SemanticFormat::TriGStar),
129        Some("n3") => Some(SemanticFormat::N3),
130        Some("rdf") | Some("owl") => Some(SemanticFormat::RdfXml),
131        Some("xml") => Some(SemanticFormat::RdfXml),
132        Some("jsonld") | Some("json-ld") | Some("json") => Some(SemanticFormat::JsonLd),
133        Some("jsonl") => Some(SemanticFormat::AgentIntentJsonl),
134        Some("cbor") | Some("cborld") => Some(SemanticFormat::CborLd),
135        Some("kml") => Some(SemanticFormat::Kml),
136        Some("chk") | Some("qchk") => Some(SemanticFormat::Chk),
137        Some("q42") => Some(SemanticFormat::Q42),
138        Some("obj") | Some("stl") | Some("glb") | Some("gltf") => Some(SemanticFormat::Mesh),
139        _ => None,
140    }
141}
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146    use std::io::Write;
147
148    fn tmp_file(name: &str, content: &[u8]) -> std::path::PathBuf {
149        let path = std::env::temp_dir().join(name);
150        let mut f = std::fs::File::create(&path).expect("create tmp file");
151        f.write_all(content).expect("write tmp file");
152        path
153    }
154
155    #[test]
156    fn detect_by_extension_nt() {
157        let p = tmp_file("test_detect.nt", b"<s> <p> <o> .\n");
158        assert_eq!(detect_format(&p), Some(SemanticFormat::NTriples));
159    }
160
161    #[test]
162    fn detect_by_extension_ttl() {
163        let p = tmp_file("test_detect.ttl", b"@prefix ex: <http://ex.org/> .\n");
164        assert_eq!(detect_format(&p), Some(SemanticFormat::Turtle));
165    }
166
167    #[test]
168    fn detect_by_extension_jsonld() {
169        let p = tmp_file("test_detect.jsonld", b"{\"@context\": {}}");
170        assert_eq!(detect_format(&p), Some(SemanticFormat::JsonLd));
171    }
172
173    #[test]
174    fn detect_by_magic_q42() {
175        let p = tmp_file("test_detect_magic.bin", b"Q42V\x00\x00\x00\x00");
176        assert_eq!(detect_format(&p), Some(SemanticFormat::Q42));
177    }
178
179    #[test]
180    fn detect_by_magic_xml_rdf() {
181        let p = tmp_file("test_detect_magic.rdf", b"<?xml version=\"1.0\"?><rdf:RDF");
182        assert_eq!(detect_format(&p), Some(SemanticFormat::RdfXml));
183    }
184
185    #[test]
186    fn detect_by_magic_kml() {
187        let p = tmp_file("test_detect_magic.kml", b"<?xml version=\"1.0\"?><kml>");
188        assert_eq!(detect_format(&p), Some(SemanticFormat::Kml));
189    }
190
191    #[test]
192    fn detect_by_magic_cbor_ld() {
193        let p = tmp_file("test_detect_magic.cbor", b"\xd9\xd9\xf7\xa1");
194        assert_eq!(detect_format(&p), Some(SemanticFormat::CborLd));
195    }
196
197    #[test]
198    fn detect_json_content_without_ld_extension() {
199        let p = tmp_file(
200            "test_detect_json.json",
201            b"{\"@context\": {}, \"@id\": \"x\"}",
202        );
203        assert_eq!(detect_format(&p), Some(SemanticFormat::JsonLd));
204    }
205
206    #[test]
207    fn detect_unknown_returns_none() {
208        let p = tmp_file("test_detect.xyz", b"some unknown data");
209        assert_eq!(detect_format(&p), None);
210    }
211
212    #[test]
213    fn label_round_trips() {
214        assert_eq!(SemanticFormat::NTriples.label(), "N-Triples");
215        assert_eq!(SemanticFormat::TurtleStar.label(), "Turtle-Star");
216        assert_eq!(SemanticFormat::JsonLdStar.label(), "JSON-LD-Star");
217    }
218}