dgconvert 0.1.0__py3-none-any.whl

dgconvert/__init__.py

@@ -0,0 +1,5 @@
+"""dgconvert — a helper library for building dgpkm-compatible seeds."""
+
+from importlib.metadata import version as _version
+
+__version__ = _version("dgconvert")

dgconvert/body_snatchers.py

@@ -0,0 +1,39 @@
+"""Body-snatcher (find/replace) content transforms, sourced from a
+seed's own docufig.seed.yaml.
+
+`bodySnatchers` is a required field in dgpkm's own seed config JSON
+Schema (validated by `dgpkm doctor schema seed`), not a decorative
+one -- so it's read directly from that already-schema-validated
+manifest rather than requiring a seed's own Python code to keep a
+second, hand-maintained copy in sync (a real, seen-in-practice failure
+mode: a seed's manifest drifting out of sync with its own Python-side
+transform table after a code-only change, caught only by a direct
+question, not by any tooling).
+
+Generalized out of two seeds' identical apply_body_snatchers once a
+second seed needed the exact same shape a first one already had --
+the same "second consumer" trigger this library's other modules were
+each generalized under.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+def load(seed_config_path: Path) -> tuple[tuple[str, str], ...]:
+    """Reads bodySnatchers from a seed's docufig.seed.yaml. Each entry's
+    {find, replace} shape matches dgpkm's own seed config JSON Schema
+    exactly. A missing bodySnatchers key (defensive -- the schema
+    requires it, but this shouldn't hard-fail a caller that hasn't
+    validated yet) behaves like an empty list."""
+    data = yaml.safe_load(seed_config_path.read_text(encoding="utf-8")) or {}
+    return tuple((s["find"], s["replace"]) for s in data.get("bodySnatchers", []))
+
+
+def apply(text: str, snatchers: tuple[tuple[str, str], ...]) -> str:
+    for find, replace in snatchers:
+        text = text.replace(find, replace)
+    return text

dgconvert/dgpkm.py

@@ -0,0 +1,62 @@
+"""Wraps the `dgpkm` binary for verification.
+
+`dgpkm doctor backlinks` and `dgpkm doctor schema <type>` always exit 0,
+even when they report findings -- findings are only visible in
+stdout/stderr text ("Found N broken link(s)", "✗ ..."). This module
+parses that text so the converter can fail loudly (non-zero exit) when a
+conversion isn't doctor-clean, which dgpkm itself won't do for you.
+
+Generalized beyond its original prototype in one way: `verify`'s schema
+check is now optional (`check_schema=None` skips it) since not every
+consumer has a `docufig.seed.json` to validate -- a standalone
+converter tool can write straight into a greenhouse's root garden,
+not a separate seed.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+
+def dgpkm_bin() -> str:
+    return os.environ.get("DGPKM_BIN", "dgpkm")
+
+
+def _run(args: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [dgpkm_bin(), *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def verify(root: Path, *, check_schema: str | None = "seed") -> list[str]:
+    """Run dgpkm doctor checks against the garden at `root`. Returns a list
+    of human-readable problem descriptions (empty = clean).
+
+    `check_schema` names the config type to pass to `dgpkm doctor schema
+    <type>` (e.g. "seed" for a `docufig.seed.json`); pass None to skip
+    that check entirely for a tool that has no such config file.
+    """
+    problems: list[str] = []
+
+    backlinks = _run(["doctor", "backlinks"], root)
+    if backlinks.returncode != 0:
+        problems.append(f"dgpkm doctor backlinks failed to run:\n{backlinks.stderr}")
+    elif "All backlinks are valid" not in backlinks.stdout:
+        problems.append(f"backlinks: broken links found\n{backlinks.stdout}")
+
+    if check_schema:
+        schema = _run(["doctor", "schema", check_schema], root)
+        if schema.returncode != 0:
+            problems.append(f"dgpkm doctor schema {check_schema} failed to run:\n{schema.stderr}")
+        elif "✓" not in schema.stdout or "✗" in schema.stderr:
+            problems.append(
+                f"{check_schema} config schema invalid:\n{schema.stdout}{schema.stderr}"
+            )
+
+    return problems

dgconvert/frontmatter.py

@@ -0,0 +1,121 @@
+"""Single-line frontmatter emission, and a naive line-based parser kept
+only for reading back this module's own prior output.
+
+Historically dgpkm's frontmatter reader was itself naive -- a raw
+`strings.SplitN(content, "---", 3)` plus a
+per-line `key.partition(":")` scanner -- so this emitter avoided a real
+YAML library entirely and just sanitized every value to a single line.
+dgpkm's reader is now real YAML both directions
+(`go.yaml.in/yaml/v4`, a line-anchored frontmatter split), which
+surfaced a real bug here: an *unquoted* value that happens to look like
+another YAML type (`title: 2022-09-09` parses as a date, not a string;
+`desc: A | B: C` breaks the scanner outright on the embedded `:`) was
+silently wrong. `emit_note` now runs every known-field value through
+`yaml.safe_dump` (preserving `int`s as real YAML integers so
+`updated`/`created` still round-trip as numbers) so quoting is decided
+correctly by the same library dgpkm itself now uses, while keeping
+`sanitize()`'s single-line collapse and `---`-neutralization as a
+defense-in-depth measure. `parse_note` below stays naive -- it only
+reads back `id`/`created`/`sourceFileHash` for incremental hash-checking
+(dgconvert.incremental), and none of those three fields are ever
+ambiguous enough for `yaml.safe_dump` to quote in practice (hex digests,
+real ints, and Dendron/TGDP's actual id formats) -- but a value in that
+position that *did* need quoting would round-trip with the quote
+characters still literally in it here.
+
+Generalized out of a first seed's own emitter once a second, independent
+consumer needed the same thing.
+"""
+
+from __future__ import annotations
+
+import yaml
+
+KEY_ORDER = (
+    "id",
+    "title",
+    "desc",
+    "canonicalUrl",
+    "license",
+    "sourceFileHash",
+    "sourceFileUrl",
+    "sourceRelease",
+    "sourceContributors",
+    "generator",
+    "frontmatterVersion",
+    "updated",
+    "created",
+    # dgpkm's own native "status" field, for a source format whose items
+    # have a task-like status to map onto it (e.g. an imported vault's
+    # own task notes). dgpkm's other two optional native fields, "type"
+    # (a YAML list) and "alias", aren't added here: no current caller
+    # sets them, and "type"'s list value would need emit_note's
+    # single-line-scalar sanitize() to grow flow-sequence handling first
+    # -- add both once a real caller needs them, not speculatively.
+    "status",
+)
+
+
+def sanitize(value: object) -> str:
+    """Collapse to a single line; neutralize dgpkm's frontmatter delimiter."""
+    text = " ".join(str(value).split())
+    return text.replace("---", "—")
+
+
+def _dump_line(key: str, value: object) -> str:
+    return yaml.safe_dump(
+        {key: value}, default_flow_style=False, sort_keys=False, allow_unicode=True
+    ).rstrip("\n")
+
+
+def emit_note(
+    frontmatter: dict[str, object], body: str, extra: dict[str, object] | None = None
+) -> str:
+    """Emits a dgpkm-compatible note. `frontmatter`'s keys are limited to
+    KEY_ORDER's known fields. String values are single-line-collapsed and
+    `---`-neutralized via `sanitize()` first; non-string values (e.g. the
+    `updated`/`created` ints) pass through unchanged so they stay real
+    YAML numbers. Either way, the final line is produced by
+    `yaml.safe_dump`, so a value that happens to look like another YAML
+    type (a bare date, a string containing an unescaped `:`) is quoted
+    correctly instead of corrupting the frontmatter block.
+
+    `extra` carries arbitrary passthrough keys beyond KEY_ORDER -- e.g. a
+    source format's own per-note provenance/task fields dgpkm doesn't
+    model natively. Extra values may additionally be nested (dicts/lists)
+    -- dgpkm's frontmatter reader is real YAML both directions
+    (go.yaml.in/yaml/v4). Keys are sorted for deterministic output,
+    matching how dgpkm's own writer orders its equivalent `Extra` map.
+    """
+    lines = ["---"]
+    for key in KEY_ORDER:
+        if key in frontmatter and frontmatter[key] not in (None, ""):
+            value = frontmatter[key]
+            if isinstance(value, str):
+                value = sanitize(value)
+            lines.append(_dump_line(key, value))
+    if extra:
+        for key in sorted(extra):
+            value = extra[key]
+            if value is None or value == "":
+                continue
+            lines.append(_dump_line(key, value))
+    lines.append("---")
+    return "\n".join(lines) + "\n\n" + body.rstrip("\n") + "\n"
+
+
+def parse_note(text: str) -> tuple[dict[str, str], str]:
+    """Mirror dgpkm's parseNote: SplitN(content, "---", 3) then `key: value`
+    lines split on the first colon."""
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        raise ValueError("missing frontmatter (no '---' delimited block)")
+    _, fm_text, body = parts
+    frontmatter: dict[str, str] = {}
+    for line in fm_text.splitlines():
+        if not line.strip():
+            continue
+        key, sep, value = line.partition(":")
+        if sep:
+            frontmatter[key.strip()] = value.strip()
+    return frontmatter, body.strip()

dgconvert/incremental.py

@@ -0,0 +1,117 @@
+"""Generic incremental-conversion driver.
+
+Generalized out of a first seed's own conversion loop once a second,
+independent consumer needed the same create/skip/update/delete shape.
+
+State lives in each note's own frontmatter (a `sourceFileHash` key), not a
+separate cache file: unchanged hash -> skip entirely (byte-identical file
+untouched); changed hash -> rewrite in place (same id, same created,
+bumped updated); source gone -> delete the note and report it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import frontmatter as fm
+
+# Called only for a new-or-changed item (never for an unchanged skip).
+# Receives the previous note's id/created if one existed (None for a
+# brand-new note) so a rewritten note keeps its identity. Returns
+# (frontmatter, body, extra); frontmatter may set "created"/"updated" as
+# this item's source-derived defaults -- convert() only overrides
+# "created" when an old value exists, and always overrides "id" (when an
+# old value exists) and "sourceFileHash".
+BuildFn = Callable[
+    ["str | None", "int | None"], "tuple[dict[str, object], str, dict[str, object] | None]"
+]
+
+
+@dataclass(frozen=True)
+class ConvertItem:
+    slug: str
+    source_hash: str
+    build: BuildFn
+
+
+@dataclass
+class ConvertResult:
+    counts: dict[str, int] = field(
+        default_factory=lambda: {"created": 0, "updated": 0, "unchanged": 0, "deleted": 0}
+    )
+    deleted: list[str] = field(default_factory=list)
+
+
+def read_existing(notes_dir: Path, glob_patterns: Iterable[str]) -> dict[str, dict[str, str]]:
+    """Reads back every previously-emitted note matching glob_patterns,
+    keyed by slug (filename stem) -> its parsed frontmatter dict."""
+    existing: dict[str, dict[str, str]] = {}
+    if notes_dir.is_dir():
+        for pattern in glob_patterns:
+            for path in notes_dir.glob(pattern):
+                frontmatter, _ = fm.parse_note(path.read_text(encoding="utf-8"))
+                existing[path.stem] = frontmatter
+    return existing
+
+
+def convert(
+    notes_dir: Path,
+    items: Iterable[ConvertItem],
+    existing: dict[str, dict[str, str]],
+    *,
+    now_ms: int,
+    stable_id: Callable[[str], str],
+) -> ConvertResult:
+    """Runs the create/skip/update/delete loop, writing/deleting files
+    under `notes_dir`. `existing` is `read_existing`'s output -- passed in
+    rather than read internally so callers can glob exactly the slugs
+    their own hierarchy owns."""
+    result = ConvertResult()
+    desired_slugs: set[str] = set()
+    notes_dir.mkdir(parents=True, exist_ok=True)
+
+    for item in items:
+        desired_slugs.add(item.slug)
+        old = existing.get(item.slug)
+
+        if old and old.get("sourceFileHash") == item.source_hash:
+            result.counts["unchanged"] += 1
+            continue
+
+        # Only trust `old` for identity (id/created) if it actually carries
+        # a sourceFileHash -- i.e. it was itself written by a prior run of
+        # *this* incremental pipeline, not some unrelated pre-existing note
+        # that happens to occupy the same slug (e.g. `dgpkm init`'s own
+        # bootstrap notes/root.md, before any converter has ever run).
+        # Otherwise a foreign note's id/created would get silently adopted
+        # as if it were this item's own prior state.
+        own_old = old if (old and old.get("sourceFileHash")) else None
+        old_id = (own_old or {}).get("id") or None
+        old_created_raw = (own_old or {}).get("created")
+        old_created = int(old_created_raw) if old_created_raw else None
+
+        built_fm, body, extra = item.build(old_id, old_created)
+
+        note_id = old_id or built_fm.get("id") or stable_id(item.slug)
+        created = old_created or built_fm.get("created") or now_ms
+        merged_fm: dict[str, object] = {
+            **built_fm,
+            "id": note_id,
+            "created": created,
+            "updated": built_fm.get("updated", now_ms),
+            "sourceFileHash": item.source_hash,
+        }
+        (notes_dir / f"{item.slug}.md").write_text(
+            fm.emit_note(merged_fm, body, extra=extra), encoding="utf-8"
+        )
+        result.counts["updated" if old else "created"] += 1
+
+    deleted = sorted(set(existing) - desired_slugs)
+    for slug in deleted:
+        (notes_dir / f"{slug}.md").unlink()
+        result.counts["deleted"] += 1
+    result.deleted = deleted
+
+    return result

dgconvert/links.py

@@ -0,0 +1,59 @@
+"""Markdown link scanning and rewriting.
+
+dgpkm's markdown-link extractor is
+`\\]\\(\\.?\\/?([^#\\)]+)\\.md(#[^\\)]*)?\\)` -- it matches ANY `](....md)`
+or `](....md#anchor)`, including full http(s) URLs, and treats the captured
+path as a note slug to validate. `doctor backlinks` then reports it broken
+if no note has that exact "slug". A link to unconverted or external content
+that happens to bare-end in ".md" must therefore carry a query string --
+appending one defeats the regex, since it requires ".md" to be immediately
+followed by "#" or the closing paren. This is confirmed necessary against
+real converted content: some source formats reference other projects'
+CHANGELOG.md/README.md by full https URL with no query string.
+
+Generalized out of a first seed's own link-rewriting module, unmodified,
+once a second, independent consumer needed the same thing.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)\s]+)\)")
+_BARE_MD_RE = re.compile(r"\.md(#[^?]*)?$")
+
+Resolver = Callable[[str, str], "str | None"]
+
+
+def defeat_md_regex(href: str) -> str:
+    """Append a harmless query string if href bare-ends in .md or .md#anchor."""
+    if "?" in href:
+        return href
+    match = _BARE_MD_RE.search(href)
+    if not match:
+        return href
+    anchor = match.group(1) or ""
+    base = href[: match.start()]
+    return f"{base}.md?ref_type=tags{anchor}"
+
+
+def rewrite_links(body: str, resolve: Resolver) -> str:
+    """resolve(text, href) -> replacement markdown-link string, or None to
+    leave the original link untouched (beyond the generic http(s) fixup
+    below)."""
+
+    def _sub(match: re.Match[str]) -> str:
+        text, href = match.group(1), match.group(2)
+        if href.startswith(("mailto:", "#")):
+            return match.group(0)
+        replacement = resolve(text, href)
+        if replacement is not None:
+            return replacement
+        if href.startswith(("http://", "https://")):
+            fixed = defeat_md_regex(href)
+            if fixed != href:
+                return f"[{text}]({fixed})"
+        return match.group(0)
+
+    return LINK_RE.sub(_sub, body)

dgconvert/slugs.py

@@ -0,0 +1,20 @@
+"""Slug joining and dgpkm link builders (alias-after only -- dgpkm cannot
+parse Dendron's alias-first on-disk form).
+
+Generalized out of a first seed's own slug module, unmodified, once a
+second, independent consumer needed the same thing.
+"""
+
+from __future__ import annotations
+
+
+def slug(*parts: str) -> str:
+    return ".".join(p.strip(".") for p in parts if p)
+
+
+def wikilink(target_slug: str, anchor: str | None = None, alias: str | None = None) -> str:
+    frag = f"#{anchor}" if anchor else ""
+    if alias and alias != target_slug:
+        safe_alias = alias.replace("|", "/").replace("]]", ")")
+        return f"[[{target_slug}{frag}|{safe_alias}]]"
+    return f"[[{target_slug}{frag}]]"

dgconvert-0.1.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: dgconvert
+Version: 0.1.0
+Summary: Helper library for building dgpkm-compatible seeds (frontmatter, slugs, link rewriting, dgpkm doctor verification)
+Project-URL: Homepage, https://github.com/ScriptAutomate/dgconvert
+Project-URL: Repository, https://github.com/ScriptAutomate/dgconvert
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+# dgconvert
+
+A small Python **helper library** for building
+[dgpkm](https://github.com/ScriptAutomate/dgpkm)-compatible **seeds**
+(pre-created gardens, ready to plant into a greenhouse).
+
+`dgconvert` is not a task runner. Each seed repo owns its own
+`docufig.seed.json` and its own plain-Python conversion script;
+`dgconvert` supplies the pieces every seed needs regardless of source
+format — dotted-slug file naming, single-line frontmatter with stable
+ids, markdown-link → dgpkm-wikilink rewriting, and a wrapper that
+verifies output with `dgpkm doctor`.
+
+See `DESIGN.md` for the full architecture and the verified
+dgpkm-compatibility constraints it's built against. The library was
+generalized out of a first seed's own inline conversion code once a
+second, independent seed needed the same pieces.
+
+## Installing
+
+```bash
+uv add dgconvert
+# or
+pip install dgconvert
+```
+
+## Development
+
+Managed with [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/),
+using [Spec Kit](https://github.com/github/spec-kit) for feature specs
+(`specs/`, `.specify/`) — unlike seed repos, which don't use Spec Kit:
+
+```bash
+just            # list tasks
+just sync       # uv sync
+just test       # uv run pytest
+just check      # format + lint
+```
+
+Container-based development mirrors dgpkm: set `USE_CONTAINER_DEV` to
+`podman`, `docker`, or `container`, then `just build-devcontainer` once and
+every build/test recipe runs inside the dev container automatically.
+
+## License
+
+[MIT](LICENSE)

dgconvert-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+dgconvert/__init__.py,sha256=rNzJg-RSjn_T-XVkP_9eXzgWl7caxwe68a86cBUH62U,163
+dgconvert/body_snatchers.py,sha256=U3MovEeprdSqK5bLm9bhkfhhetVhHsSJnOdz490z9Ps,1629
+dgconvert/dgpkm.py,sha256=VhhgqcKwHVZU5xJROlXKRXqfL4wUCpB1vOU-muYj9v0,2291
+dgconvert/frontmatter.py,sha256=DPoscMdLVVgUVEQuFHAkKLKN6gmqmkC-bsUql18HduI,5059
+dgconvert/incremental.py,sha256=1eOA0WGAzf-iZzWaU6yL-jVC2jxMTlxCgmDarJY3BVQ,4474
+dgconvert/links.py,sha256=-eRHr-CIvZAF7hSF-b2J-XpZTWFuJGV9t_WqqsR4wAg,2189
+dgconvert/slugs.py,sha256=QcSFkrVR80vzPrl7gOMX7sAwSWBgZD1XIRln6BS5qVc,698
+dgconvert-0.1.0.dist-info/METADATA,sha256=gYX4jOXCvX4Ax-BVs95AowkIiQ0OltTXlzV4hebEB_M,2190
+dgconvert-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+dgconvert-0.1.0.dist-info/licenses/LICENSE,sha256=iVk1IgRYica_g42kpWgHz9xFsghhc2_DjNyonzLWpMI,1071
+dgconvert-0.1.0.dist-info/RECORD,,

dgconvert-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dgconvert-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScriptAutomate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.