Skip to main content

qualia_semantic_library/
reorganize.rs

1//! Reorganise the library: derive a clean, browsable on-disk layout from
2//! container metadata. Containers are content-addressed (`<doc_id>.hmc`), which
3//! is great for dedup but unreadable for a human. This produces a parallel,
4//! human-facing tree organised by topic/tag with descriptive filenames, while
5//! the content-addressed store stays the source of truth.
6//!
7//! Default operation is **copy** (non-destructive). Moving is opt-in.
8
9use std::path::{Path, PathBuf};
10
11use crate::container::HMC_EXTENSION;
12use crate::library::{Entry, Library};
13
14/// A single planned placement.
15pub struct PlacementOp {
16    pub from: PathBuf,
17    pub to: PathBuf,
18    pub category: String,
19}
20
21#[derive(Clone, Copy)]
22pub enum ApplyMode {
23    /// Copy the container to its organised location (source store untouched).
24    Copy,
25    /// Move it (the organised tree becomes the only copy).
26    Move,
27}
28
29/// Build a placement plan rooting an organised tree at `out_root`.
30/// `<out_root>/<category>/<safe_title>__<id8>.hmc`.
31pub fn plan(library: &Library, out_root: &Path) -> Vec<PlacementOp> {
32    library
33        .entries
34        .iter()
35        .map(|e| {
36            let category = category_for(e);
37            let id8: String = e.manifest.doc_id.chars().take(8).collect();
38            let filename = format!("{}__{}.{}", safe_title(e.title()), id8, HMC_EXTENSION);
39            let to = out_root.join(&category).join(filename);
40            PlacementOp {
41                from: e.path.clone(),
42                to,
43                category,
44            }
45        })
46        .collect()
47}
48
49/// Execute a plan. Returns the number of placements performed.
50pub fn apply(plan: &[PlacementOp], mode: ApplyMode) -> anyhow::Result<usize> {
51    let mut n = 0;
52    for op in plan {
53        if let Some(parent) = op.to.parent() {
54            std::fs::create_dir_all(parent)?;
55        }
56        if op.to.exists() {
57            continue;
58        }
59        match mode {
60            ApplyMode::Copy => {
61                std::fs::copy(&op.from, &op.to)?;
62            }
63            ApplyMode::Move => {
64                // rename across volumes can fail; fall back to copy+remove.
65                if std::fs::rename(&op.from, &op.to).is_err() {
66                    std::fs::copy(&op.from, &op.to)?;
67                    std::fs::remove_file(&op.from)?;
68                }
69            }
70        }
71        n += 1;
72    }
73    Ok(n)
74}
75
76/// Choose a category folder for an entry. First explicit tag wins; otherwise a
77/// coarse keyword heuristic over the title; otherwise "unsorted".
78fn category_for(e: &Entry) -> String {
79    if let Some(tag) = e.manifest.tags.first() {
80        return safe_component(tag);
81    }
82    let t = e.title().to_ascii_lowercase();
83    const BUCKETS: &[(&str, &[&str])] = &[
84        (
85            "logic",
86            &[
87                "logic",
88                "modal",
89                "deontic",
90                "defeasible",
91                "proof",
92                "inference",
93                "argument",
94            ],
95        ),
96        (
97            "algebra",
98            &[
99                "algebra", "category", "tensor", "matrix", "group", "lattice", "topology",
100            ],
101        ),
102        (
103            "optimization",
104            &["optim", "convex", "gradient", "linear program", "newton"],
105        ),
106        (
107            "ml",
108            &[
109                "neural",
110                "transformer",
111                "attention",
112                "embedding",
113                "learning",
114                "nlp",
115                "language model",
116            ],
117        ),
118        (
119            "crypto",
120            &[
121                "zero-knowledge",
122                "zk",
123                "snark",
124                "elliptic",
125                "lattice-based",
126                "signature",
127                "homomorphic",
128            ],
129        ),
130        (
131            "semantic-web",
132            &[
133                "ontology",
134                "rdf",
135                "shacl",
136                "owl",
137                "sparql",
138                "knowledge graph",
139            ],
140        ),
141        (
142            "numerics",
143            &[
144                "numerical",
145                "finite element",
146                "spectral",
147                "interpolation",
148                "quadrature",
149                "ode",
150                "pde",
151            ],
152        ),
153    ];
154    for (bucket, kws) in BUCKETS {
155        if kws.iter().any(|k| t.contains(k)) {
156            return bucket.to_string();
157        }
158    }
159    "unsorted".to_string()
160}
161
162/// Make a human-readable but filesystem-safe title.
163fn safe_title(title: &str) -> String {
164    let s = safe_component(title);
165    let truncated: String = s.chars().take(80).collect();
166    if truncated.is_empty() {
167        "untitled".to_string()
168    } else {
169        truncated
170    }
171}
172
173fn safe_component(s: &str) -> String {
174    s.chars()
175        .map(|c| {
176            if c.is_alphanumeric() || c == '-' || c == '_' {
177                c
178            } else {
179                '_'
180            }
181        })
182        .collect::<String>()
183        .trim_matches('_')
184        .to_string()
185}