Add DSON URL parsing and library lookup

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

2 files changed, 189 insertions, 0 deletions

diff --git a/generat3d/library.py b/generat3d/library.py
new file mode 100644
index 0000000..ea12794
--- /dev/null
+++ b/generat3d/library.py
@@ -0,0 +1,98 @@
+# generat3D - evaluate Daz DSON scenes and write .dbz files
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gzip
+import json
+import os
+from pathlib import Path
+from urllib.parse import unquote
+
+from . import Error
+
+
+def parse_url(url):
+    """Split a DSON URL "node:/path/file.dsf#id?prop" into (node, path, id, prop)."""
+    node = ""
+    if not url.startswith(("/", "#")) and ":" in url:
+        node, url = url.split(":", 1)
+    url, _, prop = url.partition("?")
+    path, _, ident = url.partition("#")
+    return unquote(node), unquote(path), unquote(ident), prop
+
+
+def read_dson(path):
+    """Parse a plain or gzipped DSON file."""
+    try:
+        data = Path(path).read_bytes()
+        if data[:2] == b"\x1f\x8b":
+            data = gzip.decompress(data)
+        return json.loads(data)
+    except (OSError, EOFError, ValueError) as e:
+        raise Error(f"{path}: {e}") from None
+
+
+def _find_nocase(base, parts, want_dir=False):
+    for part in parts:
+        try:
+            names = {n.lower(): n for n in os.listdir(base)}
+        except OSError:
+            return None
+        name = names.get(part.lower())
+        if name is None:
+            return None
+        base = base / name
+    return base if (base.is_dir() if want_dir else base.is_file()) else None
+
+
+class Library:
+    def __init__(self, roots):
+        self.roots = [Path(r) for r in roots]
+        self._docs = {}
+
+    def _locate(self, rel, want_dir):
+        for root in self.roots:
+            p = root / rel
+            if p.is_dir() if want_dir else p.is_file():
+                yield root, p
+                continue
+            p = _find_nocase(root, rel.split("/"), want_dir)
+            if p:
+                yield root, p
+
+    def find(self, path):
+        """File for a library path like "/data/x.dsf", first root wins, or None."""
+        return next((p for _, p in self._locate(path.strip("/"), False)), None)
+
+    def load(self, path):
+        """Parsed DSON document for a library path. Error if missing or broken."""
+        key = path.lower()
+        if key not in self._docs:
+            f = self.find(path)
+            if f is None:
+                raise Error(f"not found in library roots: {path}")
+            self._docs[key] = read_dson(f)
+        return self._docs[key]
+
+    def walk(self, path):
+        """Library paths of every .dsf under a library directory, across all roots."""
+        seen = {}
+        for root, base in self._locate(path.strip("/"), True):
+            for f in sorted(base.rglob("*")):
+                if f.is_file() and f.suffix.lower() == ".dsf":
+                    lp = "/" + f.relative_to(root).as_posix()
+                    seen.setdefault(lp.lower(), lp)
+        return list(seen.values())
diff --git a/tests/test_library.py b/tests/test_library.py
new file mode 100644
index 0000000..84fa3cc
--- /dev/null
+++ b/tests/test_library.py
@@ -0,0 +1,91 @@
+# generat3D - evaluate Daz DSON scenes and write .dbz files
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gzip
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from generat3d import Error
+from generat3d.library import Library, parse_url, read_dson
+
+
+class ParseUrlTest(unittest.TestCase):
+    def test_full(self):
+        self.assertEqual(
+            parse_url("lShldrBend:/data/Daz%203D/G9.dsf#lShldrBend?center_point/x"),
+            ("lShldrBend", "/data/Daz 3D/G9.dsf", "lShldrBend", "center_point/x"))
+
+    def test_path_and_id(self):
+        self.assertEqual(parse_url("/data/a%20b.dsf#m1"), ("", "/data/a b.dsf", "m1", ""))
+
+    def test_local_ref(self):
+        self.assertEqual(parse_url("#hip"), ("", "", "hip", ""))
+
+    def test_node_with_local_ref(self):
+        self.assertEqual(parse_url("Fig:#Tall?value"), ("Fig", "", "Tall", "value"))
+
+
+class LibraryTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        base = Path(self.tmp.name)
+        self.r1, self.r2 = base / "r1", base / "r2"
+        (self.r1 / "data/Vendor/Fig/Morphs").mkdir(parents=True)
+        (self.r2 / "data/vendor/fig").mkdir(parents=True)
+        (self.r1 / "data/Vendor/Fig/Morphs/A.dsf").write_text('{"a": 1}')
+        (self.r2 / "data/vendor/fig/B.dsf").write_bytes(gzip.compress(b'{"b": 2}'))
+        (self.r2 / "data/vendor/fig/Bad.dsf").write_text("{nope")
+        self.lib = Library([self.r1, self.r2])
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_exact_match(self):
+        self.assertEqual(self.lib.find("/data/Vendor/Fig/Morphs/A.dsf"),
+                         self.r1 / "data/Vendor/Fig/Morphs/A.dsf")
+
+    def test_case_insensitive_second_root(self):
+        self.assertEqual(self.lib.find("/data/Vendor/Fig/B.dsf"),
+                         self.r2 / "data/vendor/fig/B.dsf")
+
+    def test_missing(self):
+        self.assertIsNone(self.lib.find("/data/Nope.dsf"))
+
+    def test_load_gzip_and_cache(self):
+        doc = self.lib.load("/data/Vendor/Fig/B.dsf")
+        self.assertEqual(doc, {"b": 2})
+        self.assertIs(self.lib.load("/data/vendor/fig/b.dsf"), doc)
+
+    def test_load_missing_is_fatal(self):
+        with self.assertRaisesRegex(Error, "not found in library roots: /data/Nope.dsf"):
+            self.lib.load("/data/Nope.dsf")
+
+    def test_broken_json_names_file(self):
+        with self.assertRaisesRegex(Error, "Bad.dsf"):
+            self.lib.load("/data/Vendor/Fig/Bad.dsf")
+
+    def test_walk_merges_roots(self):
+        self.assertEqual(sorted(self.lib.walk("/data/Vendor/Fig")),
+                         ["/data/Vendor/Fig/Morphs/A.dsf",
+                          "/data/vendor/fig/B.dsf", "/data/vendor/fig/Bad.dsf"])
+
+    def test_read_dson_plain(self):
+        p = Path(self.tmp.name) / "x.duf"
+        p.write_text(json.dumps({"x": 1}))
+        self.assertEqual(read_dson(p), {"x": 1})