Skip to main content

ankit_builder/
apkg.rs

1//! .apkg file generation.
2//!
3//! Creates Anki package files that can be imported directly into Anki.
4
5use std::collections::HashMap;
6use std::io::Write;
7use std::path::Path;
8use std::time::{SystemTime, UNIX_EPOCH};
9
10use rusqlite::Connection;
11use tempfile::TempDir;
12use zip::ZipWriter;
13use zip::write::SimpleFileOptions;
14
15use crate::error::Result;
16use crate::schema::DeckDefinition;
17use crate::sql::{DEFAULT_CONF, DEFAULT_DCONF, FIELD_SEPARATOR, SCHEMA};
18
19/// Builder for creating .apkg files from deck definitions.
20pub struct ApkgBuilder {
21    definition: DeckDefinition,
22    media_base_path: Option<std::path::PathBuf>,
23}
24
25impl ApkgBuilder {
26    /// Create a new builder from a deck definition.
27    pub fn new(definition: DeckDefinition) -> Self {
28        Self {
29            definition,
30            media_base_path: None,
31        }
32    }
33
34    /// Set the base path for resolving media file paths.
35    pub fn media_base_path(mut self, path: impl AsRef<Path>) -> Self {
36        self.media_base_path = Some(path.as_ref().to_path_buf());
37        self
38    }
39
40    /// Build the .apkg file and write it to the specified path.
41    pub fn write_to_file(&self, path: impl AsRef<Path>) -> Result<()> {
42        let temp_dir = TempDir::new()?;
43        let db_path = temp_dir.path().join("collection.anki2");
44
45        // Create and populate the SQLite database
46        let conn = Connection::open(&db_path)?;
47        self.create_database(&conn)?;
48
49        // Create the ZIP file
50        let file = std::fs::File::create(path)?;
51        let mut zip = ZipWriter::new(file);
52
53        // Add the database file
54        let options =
55            SimpleFileOptions::default().compression_method(zip::CompressionMethod::Deflated);
56        zip.start_file("collection.anki2", options)?;
57        let db_bytes = std::fs::read(&db_path)?;
58        zip.write_all(&db_bytes)?;
59
60        // Add media manifest and files
61        let media_manifest = self.build_media_manifest()?;
62        zip.start_file("media", options)?;
63        zip.write_all(media_manifest.as_bytes())?;
64
65        // Add media files with numeric names
66        for (index, media) in self.definition.media.iter().enumerate() {
67            let source_path = self.resolve_media_path(&media.path)?;
68            let content = std::fs::read(&source_path)?;
69            zip.start_file(index.to_string(), options)?;
70            zip.write_all(&content)?;
71        }
72
73        zip.finish()?;
74        Ok(())
75    }
76
77    /// Create the SQLite database with all content.
78    fn create_database(&self, conn: &Connection) -> Result<()> {
79        // Create schema
80        conn.execute_batch(SCHEMA)?;
81
82        // Generate timestamps and IDs
83        let now = current_timestamp();
84        let now_ms = now * 1000;
85
86        // Build model and deck JSON
87        let models_json = self.build_models_json(now);
88        let decks_json = self.build_decks_json(now);
89
90        // Insert collection row
91        conn.execute(
92            "INSERT INTO col (id, crt, mod, scm, ver, dty, usn, ls, conf, models, decks, dconf, tags)
93             VALUES (1, ?, ?, ?, 11, 0, -1, 0, ?, ?, ?, ?, '{}')",
94            rusqlite::params![now, now_ms, now_ms, DEFAULT_CONF, models_json, decks_json, DEFAULT_DCONF],
95        )?;
96
97        // Insert notes and cards
98        let mut note_id_gen = now_ms;
99        let mut card_id_gen = now_ms;
100
101        for note_def in &self.definition.notes {
102            let model = self.definition.get_model(&note_def.model).unwrap();
103            let deck = self.definition.get_deck(&note_def.deck).unwrap();
104            let deck_id = deck.id.unwrap_or_else(|| generate_id(&deck.name));
105            let model_id = model.id.unwrap_or_else(|| generate_id(&model.name));
106
107            // Insert note
108            let note_id = note_id_gen;
109            note_id_gen += 1;
110
111            let guid = note_def
112                .guid
113                .clone()
114                .unwrap_or_else(|| generate_guid(note_id));
115
116            // Convert markdown fields to HTML before storing
117            let html_fields = note_def.fields_as_html(&model.markdown_fields);
118            let fields_str = model
119                .fields
120                .iter()
121                .map(|f| html_fields.get(f).cloned().unwrap_or_default())
122                .collect::<Vec<_>>()
123                .join(&FIELD_SEPARATOR.to_string());
124            let sort_field = note_def
125                .fields_ordered(model)
126                .get(model.sort_field_index())
127                .cloned()
128                .unwrap_or_default();
129            let checksum = compute_checksum(&sort_field);
130
131            conn.execute(
132                "INSERT INTO notes (id, guid, mid, mod, usn, tags, flds, sfld, csum, flags, data)
133                 VALUES (?, ?, ?, ?, -1, ?, ?, ?, ?, 0, '')",
134                rusqlite::params![
135                    note_id,
136                    guid,
137                    model_id,
138                    now,
139                    note_def.tags_string(),
140                    fields_str,
141                    sort_field,
142                    checksum
143                ],
144            )?;
145
146            // Insert cards (one per template)
147            for (ord, _template) in model.templates.iter().enumerate() {
148                let card_id = card_id_gen;
149                card_id_gen += 1;
150
151                conn.execute(
152                    "INSERT INTO cards (id, nid, did, ord, mod, usn, type, queue, due, ivl, factor, reps, lapses, left, odue, odid, flags, data)
153                     VALUES (?, ?, ?, ?, ?, -1, 0, 0, ?, 0, 0, 0, 0, 0, 0, 0, 0, '')",
154                    rusqlite::params![card_id, note_id, deck_id, ord as i64, now, card_id_gen],
155                )?;
156            }
157        }
158
159        Ok(())
160    }
161
162    /// Build the models JSON for the col table.
163    fn build_models_json(&self, now: i64) -> String {
164        let mut models: HashMap<String, serde_json::Value> = HashMap::new();
165
166        for model in &self.definition.models {
167            let model_id = model.id.unwrap_or_else(|| generate_id(&model.name));
168
169            let fields: Vec<serde_json::Value> = model
170                .fields
171                .iter()
172                .enumerate()
173                .map(|(i, name)| {
174                    serde_json::json!({
175                        "name": name,
176                        "ord": i,
177                        "sticky": false,
178                        "rtl": false,
179                        "font": "Arial",
180                        "size": 20,
181                        "media": []
182                    })
183                })
184                .collect();
185
186            let templates: Vec<serde_json::Value> = model
187                .templates
188                .iter()
189                .enumerate()
190                .map(|(i, t)| {
191                    serde_json::json!({
192                        "name": t.name,
193                        "ord": i,
194                        "qfmt": t.front,
195                        "afmt": t.back,
196                        "bqfmt": "",
197                        "bafmt": "",
198                        "did": null,
199                        "bfont": "",
200                        "bsize": 0
201                    })
202                })
203                .collect();
204
205            let model_obj = serde_json::json!({
206                "id": model_id,
207                "name": model.name,
208                "type": 0,
209                "mod": now,
210                "usn": -1,
211                "sortf": model.sort_field_index(),
212                "did": null,
213                "tmpls": templates,
214                "flds": fields,
215                "css": model.css.clone().unwrap_or_else(default_css),
216                "latexPre": "\\documentclass[12pt]{article}\n\\special{papersize=3in,5in}\n\\usepackage{amssymb,amsmath}\n\\pagestyle{empty}\n\\setlength{\\parindent}{0in}\n\\begin{document}\n",
217                "latexPost": "\\end{document}",
218                "latexsvg": false,
219                "req": build_requirements(&model.templates, &model.fields)
220            });
221
222            models.insert(model_id.to_string(), model_obj);
223        }
224
225        serde_json::to_string(&models).unwrap()
226    }
227
228    /// Build the decks JSON for the col table.
229    fn build_decks_json(&self, now: i64) -> String {
230        let mut decks: HashMap<String, serde_json::Value> = HashMap::new();
231
232        // Always include the default deck
233        decks.insert(
234            "1".to_string(),
235            serde_json::json!({
236                "id": 1,
237                "mod": now,
238                "name": "Default",
239                "usn": -1,
240                "lrnToday": [0, 0],
241                "revToday": [0, 0],
242                "newToday": [0, 0],
243                "timeToday": [0, 0],
244                "collapsed": false,
245                "browserCollapsed": false,
246                "desc": "",
247                "dyn": 0,
248                "conf": 1,
249                "extendNew": 10,
250                "extendRev": 50
251            }),
252        );
253
254        for deck in &self.definition.decks {
255            let deck_id = deck.id.unwrap_or_else(|| generate_id(&deck.name));
256            let deck_obj = serde_json::json!({
257                "id": deck_id,
258                "mod": now,
259                "name": deck.name,
260                "usn": -1,
261                "lrnToday": [0, 0],
262                "revToday": [0, 0],
263                "newToday": [0, 0],
264                "timeToday": [0, 0],
265                "collapsed": false,
266                "browserCollapsed": false,
267                "desc": deck.description.clone().unwrap_or_default(),
268                "dyn": 0,
269                "conf": 1,
270                "extendNew": 10,
271                "extendRev": 50
272            });
273
274            decks.insert(deck_id.to_string(), deck_obj);
275        }
276
277        serde_json::to_string(&decks).unwrap()
278    }
279
280    /// Build the media manifest JSON.
281    fn build_media_manifest(&self) -> Result<String> {
282        let manifest: HashMap<String, &str> = self
283            .definition
284            .media
285            .iter()
286            .enumerate()
287            .map(|(i, m)| (i.to_string(), m.name.as_str()))
288            .collect();
289
290        Ok(serde_json::to_string(&manifest).unwrap())
291    }
292
293    /// Resolve a media file path.
294    fn resolve_media_path(&self, path: &str) -> Result<std::path::PathBuf> {
295        let path = Path::new(path);
296        if path.is_absolute() {
297            Ok(path.to_path_buf())
298        } else if let Some(ref base) = self.media_base_path {
299            Ok(base.join(path))
300        } else {
301            Ok(path.to_path_buf())
302        }
303    }
304}
305
306/// Get current Unix timestamp in seconds.
307fn current_timestamp() -> i64 {
308    SystemTime::now()
309        .duration_since(UNIX_EPOCH)
310        .unwrap()
311        .as_secs() as i64
312}
313
314/// Generate a stable ID from a string (for models and decks).
315fn generate_id(name: &str) -> i64 {
316    use std::collections::hash_map::DefaultHasher;
317    use std::hash::{Hash, Hasher};
318
319    let mut hasher = DefaultHasher::new();
320    name.hash(&mut hasher);
321    // Ensure positive and reasonable size
322    (hasher.finish() & 0x7FFF_FFFF_FFFF) as i64
323}
324
325/// Generate a GUID for a note.
326fn generate_guid(note_id: i64) -> String {
327    // Base91 encoding similar to Anki
328    const CHARS: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!#$%&()*+,-./:;<=>?@[]^_`{|}~";
329    let mut n = note_id as u64;
330    let mut result = String::new();
331    while n > 0 {
332        result.push(CHARS[(n % 91) as usize] as char);
333        n /= 91;
334    }
335    result
336}
337
338/// Compute a checksum for the sort field.
339fn compute_checksum(sort_field: &str) -> i64 {
340    use std::collections::hash_map::DefaultHasher;
341    use std::hash::{Hash, Hasher};
342
343    // Strip HTML and compute hash
344    let text = strip_html(sort_field);
345    let mut hasher = DefaultHasher::new();
346    text.hash(&mut hasher);
347    (hasher.finish() & 0xFFFFFFFF) as i64
348}
349
350/// Simple HTML stripping.
351fn strip_html(s: &str) -> String {
352    let mut result = String::new();
353    let mut in_tag = false;
354
355    for c in s.chars() {
356        match c {
357            '<' => in_tag = true,
358            '>' => in_tag = false,
359            _ if !in_tag => result.push(c),
360            _ => {}
361        }
362    }
363
364    result
365}
366
367/// Build model requirements (which fields must be non-empty for each template).
368fn build_requirements(
369    templates: &[crate::schema::TemplateDef],
370    fields: &[String],
371) -> Vec<serde_json::Value> {
372    templates
373        .iter()
374        .enumerate()
375        .map(|(ord, template)| {
376            // Find fields referenced in the front template
377            let referenced: Vec<usize> = fields
378                .iter()
379                .enumerate()
380                .filter(|(_, f)| template.front.contains(&format!("{{{{{}}}}}", f)))
381                .map(|(i, _)| i)
382                .collect();
383
384            if referenced.is_empty() {
385                // If no fields detected, require first field
386                serde_json::json!([ord, "any", [0]])
387            } else {
388                serde_json::json!([ord, "any", referenced])
389            }
390        })
391        .collect()
392}
393
394/// Default CSS for cards.
395fn default_css() -> String {
396    r#".card {
397    font-family: arial;
398    font-size: 20px;
399    text-align: center;
400    color: black;
401    background-color: white;
402}"#
403    .to_string()
404}
405
406#[cfg(test)]
407mod tests {
408    use super::*;
409    use crate::schema::DeckDefinition;
410    use tempfile::tempdir;
411
412    #[test]
413    fn test_generate_guid() {
414        let guid = generate_guid(1234567890);
415        assert!(!guid.is_empty());
416        // Should be deterministic
417        assert_eq!(guid, generate_guid(1234567890));
418    }
419
420    #[test]
421    fn test_generate_id() {
422        let id = generate_id("Test Model");
423        assert!(id > 0);
424        // Should be deterministic
425        assert_eq!(id, generate_id("Test Model"));
426        // Different names should give different IDs
427        assert_ne!(id, generate_id("Other Model"));
428    }
429
430    #[test]
431    fn test_strip_html() {
432        assert_eq!(strip_html("<b>Hello</b> World"), "Hello World");
433        assert_eq!(strip_html("No HTML"), "No HTML");
434        assert_eq!(strip_html("<div><p>Nested</p></div>"), "Nested");
435    }
436
437    #[test]
438    fn test_write_apkg() {
439        let toml = r#"
440[package]
441name = "Test"
442
443[[models]]
444name = "Basic"
445fields = ["Front", "Back"]
446
447[[models.templates]]
448name = "Card 1"
449front = "{{Front}}"
450back = "{{Back}}"
451
452[[decks]]
453name = "Test Deck"
454
455[[notes]]
456deck = "Test Deck"
457model = "Basic"
458
459[notes.fields]
460Front = "Question"
461Back = "Answer"
462"#;
463
464        let def = DeckDefinition::parse(toml).unwrap();
465        let builder = ApkgBuilder::new(def);
466
467        let dir = tempdir().unwrap();
468        let path = dir.path().join("test.apkg");
469
470        builder.write_to_file(&path).unwrap();
471
472        // Verify the file exists and is a valid ZIP
473        assert!(path.exists());
474        let file = std::fs::File::open(&path).unwrap();
475        let archive = zip::ZipArchive::new(file).unwrap();
476
477        // Check expected files
478        let file_names: Vec<_> = archive.file_names().collect();
479        assert!(file_names.contains(&"collection.anki2"));
480        assert!(file_names.contains(&"media"));
481    }
482}