ledgercore 0.1.0__py3-none-any.whl

ledgercore/__init__.py

@@ -0,0 +1,109 @@
+"""ledgercore: generic ledger and storage primitives."""
+
+from ledgercore.atomic import atomic_create_text, atomic_write_text
+from ledgercore.errors import (
+    AtomicWriteError,
+    FrontMatterError,
+    IdFormatError,
+    JsonStoreError,
+    LedgerCoreError,
+    PathValidationError,
+    StorageError,
+    YamlStoreError,
+)
+from ledgercore.frontmatter import (
+    iter_markdown_files,
+    iter_source_files,
+    read_front_matter_document,
+    write_front_matter_document,
+)
+from ledgercore.ids import (
+    LedgerIdFormat,
+    LedgerIdParts,
+    NumericIdFormat,
+    next_prefixed_id,
+    parse_prefixed_number,
+    slugify_ref,
+)
+from ledgercore.refs import (
+    LedgerResourceRef,
+    RefStyle,
+    is_resource_ref,
+    normalize_kind,
+    normalize_ref_token,
+    parse_global_ref,
+    parse_local_ref,
+    parse_resource_ref,
+)
+from ledgercore.io import (
+    content_hash,
+    ensure_dir,
+    merge_text,
+    normalize_newlines,
+    read_text,
+    summarize_text,
+    write_text,
+)
+from ledgercore.jsonio import load_json_array, load_json_object, write_json
+from ledgercore.paths import (
+    ConfigLocator,
+    find_config_upwards,
+    is_relative_to,
+    locate_config,
+    resolve_config_relative_path,
+    resolve_relative_child,
+    validate_relative_posix_path,
+)
+from ledgercore.time import utc_now_iso
+from ledgercore.yamlio import load_yaml_object, write_yaml
+
+__all__ = [
+    "atomic_create_text",
+    "atomic_write_text",
+    "AtomicWriteError",
+    "FrontMatterError",
+    "IdFormatError",
+    "JsonStoreError",
+    "LedgerCoreError",
+    "PathValidationError",
+    "StorageError",
+    "YamlStoreError",
+    "iter_markdown_files",
+    "iter_source_files",
+    "read_front_matter_document",
+    "write_front_matter_document",
+    "LedgerIdFormat",
+    "LedgerIdParts",
+    "NumericIdFormat",
+    "next_prefixed_id",
+    "parse_prefixed_number",
+    "slugify_ref",
+    "LedgerResourceRef",
+    "RefStyle",
+    "is_resource_ref",
+    "normalize_kind",
+    "normalize_ref_token",
+    "parse_global_ref",
+    "parse_local_ref",
+    "parse_resource_ref",
+    "content_hash",
+    "ensure_dir",
+    "merge_text",
+    "normalize_newlines",
+    "read_text",
+    "summarize_text",
+    "write_text",
+    "load_json_array",
+    "load_json_object",
+    "write_json",
+    "ConfigLocator",
+    "find_config_upwards",
+    "is_relative_to",
+    "locate_config",
+    "resolve_config_relative_path",
+    "resolve_relative_child",
+    "validate_relative_posix_path",
+    "utc_now_iso",
+    "load_yaml_object",
+    "write_yaml",
+]

ledgercore/atomic.py

@@ -0,0 +1,124 @@
+"""Atomic file write utilities for ledgercore."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from ledgercore.errors import AtomicWriteError
+
+
+def _should_fsync(fast_io_env_var: str | None) -> bool:
+    if fast_io_env_var is None:
+        return True
+    return not os.environ.get(fast_io_env_var, "")
+
+
+def _fsync_dir(path: Path) -> None:
+    try:
+        fd = os.open(path, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _cleanup_tmp(tmp_fd: int | None, tmp_path: Path | None) -> None:
+    if tmp_fd is not None:
+        try:
+            os.close(tmp_fd)
+        except OSError:
+            pass
+    if tmp_path is not None:
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass
+
+
+def atomic_write_text(
+    path: Path,
+    contents: str,
+    *,
+    normalize: bool = False,
+    fsync: bool = True,
+    fast_io_env_var: str | None = None,
+) -> None:
+    """Write text to a file atomically using a temp file and os.replace."""
+    if normalize:
+        contents = contents.replace("\r\n", "\n").replace("\r", "\n")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    do_fsync = fsync and _should_fsync(fast_io_env_var)
+
+    tmp_fd: int | None = None
+    tmp_path: Path | None = None
+    try:
+        tmp_fd, tmp_name = tempfile.mkstemp(
+            dir=str(path.parent),
+            prefix=".ledgercore-tmp-",
+        )
+        tmp_path = Path(tmp_name)
+        with os.fdopen(tmp_fd, "wb") as f:
+            f.write(contents.encode("utf-8"))
+            if do_fsync:
+                f.flush()
+                os.fsync(f.fileno())
+        tmp_fd = None  # closed by fdopen context manager
+        os.replace(tmp_name, str(path))
+        tmp_path = None
+        if do_fsync:
+            _fsync_dir(path.parent)
+    except OSError as exc:
+        _cleanup_tmp(tmp_fd, tmp_path)
+        raise AtomicWriteError(f"Atomic write failed for {path}") from exc
+
+
+def atomic_create_text(
+    path: Path,
+    contents: str,
+    *,
+    fsync: bool = True,
+    fast_io_env_var: str | None = None,
+) -> None:
+    """Create a new file atomically using O_CREAT|O_EXCL for race safety.
+
+    Fails with AtomicWriteError if the target already exists or if a
+    concurrent process creates the file between the check and the write.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    do_fsync = fsync and _should_fsync(fast_io_env_var)
+
+    try:
+        fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError as exc:
+        raise AtomicWriteError(f"Target already exists: {path}") from exc
+    except OSError as exc:
+        raise AtomicWriteError(f"Atomic create failed for {path}") from exc
+
+    try:
+        encoded = contents.encode("utf-8")
+        os.write(fd, encoded)
+        if do_fsync:
+            os.fsync(fd)
+    except OSError as exc:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        try:
+            path.unlink()
+        except OSError:
+            pass
+        raise AtomicWriteError(f"Atomic create failed for {path}") from exc
+
+    try:
+        os.close(fd)
+    except OSError as exc:
+        raise AtomicWriteError(f"Atomic create failed for {path}") from exc
+
+    if do_fsync:
+        _fsync_dir(path.parent)

ledgercore/errors.py

@@ -0,0 +1,40 @@
+"""Generic error hierarchy for ledgercore."""
+
+
+class LedgerCoreError(Exception):
+    """Base exception for all ledgercore errors."""
+
+    code: str = "LEDGERCORE_ERROR"
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class StorageError(LedgerCoreError):
+    """Base exception for storage-related errors."""
+
+
+class AtomicWriteError(StorageError):
+    """Raised when an atomic write operation fails."""
+
+
+class FrontMatterError(StorageError):
+    """Raised when front matter parsing or writing fails."""
+
+
+class JsonStoreError(StorageError):
+    """Raised when a JSON store operation fails."""
+
+
+class YamlStoreError(StorageError):
+    """Raised when a YAML store operation fails."""
+
+
+class PathValidationError(StorageError):
+    """Raised when a path fails validation."""
+
+
+class IdFormatError(LedgerCoreError):
+    """Raised when an ID does not match the expected format."""

ledgercore/frontmatter.py

@@ -0,0 +1,151 @@
+"""YAML front matter read/write and file iteration for ledgercore."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+from ledgercore.errors import FrontMatterError
+
+BodyMode = Literal["preserve", "ensure-single-final-newline"]
+
+_FRONT_MATTER_DELIM = "---"
+
+
+def read_front_matter_document(path: Path) -> tuple[dict[str, object], str]:
+    """Read a YAML front matter document, returning (metadata, body)."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise FrontMatterError(f"Cannot read {path}: {exc}") from exc
+
+    raw = raw.replace("\r\n", "\n").replace("\r", "\n")
+
+    if not raw.startswith(_FRONT_MATTER_DELIM + "\n"):
+        raise FrontMatterError(
+            f"Document must start with '---' followed by a newline: {path}"
+        )
+
+    rest = raw[len(_FRONT_MATTER_DELIM) + 1 :]
+
+    # Look for closing --- followed by newline and body
+    close_with_body = rest.find("\n" + _FRONT_MATTER_DELIM + "\n")
+    # Look for closing --- at the very end of the document (no trailing body)
+    close_at_end = rest.endswith("\n" + _FRONT_MATTER_DELIM)
+    # Look for closing --- right at the start of rest (empty YAML block with body)
+    close_immediate_with_body = -1
+    if rest.startswith(_FRONT_MATTER_DELIM + "\n"):
+        close_immediate_with_body = 0
+    # Look for closing --- as the entirety of rest (empty YAML, no body)
+    close_immediate_at_end = rest == _FRONT_MATTER_DELIM
+
+    if close_with_body >= 0:
+        yaml_block = rest[:close_with_body]
+        body_start = close_with_body + len("\n" + _FRONT_MATTER_DELIM + "\n")
+        body = rest[body_start:]
+    elif close_immediate_with_body >= 0:
+        yaml_block = ""
+        body = rest[len(_FRONT_MATTER_DELIM) + 1 :]
+    elif close_immediate_at_end:
+        yaml_block = ""
+        body = ""
+    elif close_at_end:
+        yaml_block = rest[: len(rest) - len("\n" + _FRONT_MATTER_DELIM)]
+        body = ""
+    else:
+        raise FrontMatterError(f"No closing '---' delimiter found in {path}")
+
+    if not yaml_block.strip():
+        metadata: dict[str, object] = {}
+    else:
+        try:
+            loaded = yaml.safe_load(yaml_block)
+        except yaml.YAMLError as exc:
+            raise FrontMatterError(f"Invalid YAML in {path}: {exc}") from exc
+        if loaded is None:
+            metadata = {}
+        elif isinstance(loaded, dict):
+            metadata = loaded
+        else:
+            raise FrontMatterError(
+                f"YAML front matter must be a mapping,"
+                f" got {type(loaded).__name__}: {path}"
+            )
+
+    return metadata, body
+
+
+def write_front_matter_document(
+    path: Path,
+    metadata: Mapping[str, object],
+    body: str,
+    *,
+    body_mode: BodyMode = "preserve",
+    atomic: bool = True,
+) -> None:
+    """Write a YAML front matter document."""
+    yaml_block = yaml.safe_dump(
+        dict(metadata),
+        allow_unicode=True,
+        sort_keys=False,
+    )
+    if not yaml_block.endswith("\n"):
+        yaml_block += "\n"
+
+    if body_mode == "ensure-single-final-newline":
+        if body and not body.endswith("\n"):
+            body = body + "\n"
+        elif body.endswith("\n\n"):
+            body = body.rstrip("\n") + "\n"
+
+    content = f"{_FRONT_MATTER_DELIM}\n{yaml_block}{_FRONT_MATTER_DELIM}\n{body}"
+
+    if atomic:
+        from ledgercore.atomic import atomic_write_text
+
+        atomic_write_text(path, content)
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+
+def iter_source_files(
+    directory: Path,
+    extensions: tuple[str, ...],
+    *,
+    recursive: bool = True,
+) -> list[Path]:
+    """Iterate source files matching given extensions in sorted order."""
+    if not directory.is_dir():
+        return []
+    ext_lower = {e.lower() for e in extensions}
+    if recursive:
+        paths = [
+            p
+            for p in directory.rglob("*")
+            if p.is_file() and p.suffix.lower() in ext_lower
+        ]
+    else:
+        paths = [
+            p
+            for p in directory.iterdir()
+            if p.is_file() and p.suffix.lower() in ext_lower
+        ]
+    return sorted(paths)
+
+
+def iter_markdown_files(
+    directory: Path,
+    *,
+    recursive: bool = False,
+) -> list[Path]:
+    """Iterate markdown files in sorted order."""
+    return iter_source_files(directory, (".md",), recursive=recursive)
+
+
+# Compatibility aliases
+read_markdown_front_matter = read_front_matter_document
+write_markdown_front_matter = write_front_matter_document

ledgercore/ids.py

@@ -0,0 +1,208 @@
+"""Prefixed numeric ID formatting and slug utilities for ledgercore."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LedgerIdParts:
+    """Parsed components of a ledger ID."""
+
+    prefix: str
+    number: int
+    segment: str | None
+
+
+@dataclass(frozen=True)
+class LedgerIdFormat:
+    """Configurable prefixed numeric ID format with optional segment support.
+
+    Supports ID patterns like:
+      task-0001         (prefix="task")
+      plan-0001         (prefix="plan")
+      al_0013           (prefix="al", separator="_")
+      al_content_0013   (prefix="al", separator="_", segment_separator="_")
+    """
+
+    prefix: str
+    separator: str = "-"
+    width: int = 4
+    segment_separator: str | None = None
+    segment_required: bool = False
+
+    def format(self, number: int, *, segment: str | None = None) -> str:
+        """Format a number (and optional segment) as an ID string."""
+        _validate_number(number)
+        padded = f"{number:0{self.width}d}"
+        if segment is not None:
+            seg_sep = (
+                self.segment_separator if self.segment_separator else self.separator
+            )
+            return f"{self.prefix}{seg_sep}{segment}{self.separator}{padded}"
+        return f"{self.prefix}{self.separator}{padded}"
+
+    def parse(self, value: str) -> int:
+        """Parse an ID string and return the numeric part."""
+        return self.parse_parts(value).number
+
+    def parse_parts(self, value: str) -> LedgerIdParts:
+        """Parse an ID string and return all components."""
+        # Try simple pattern first (prefix + sep + number)
+        simple = self._build_simple_pattern()
+        m = simple.fullmatch(value)
+        if m:
+            return LedgerIdParts(
+                prefix=self.prefix,
+                number=int(m.group("number")),
+                segment=None,
+            )
+        # If segment support is enabled, try segmented pattern
+        if self.segment_separator is not None:
+            seg = self._build_segmented_pattern()
+            m = seg.fullmatch(value)
+            if m:
+                return LedgerIdParts(
+                    prefix=self.prefix,
+                    number=int(m.group("number")),
+                    segment=m.group("segment"),
+                )
+        raise ValueError(
+            f"ID '{value}' does not match format "
+            f"prefix='{self.prefix}' separator='{self.separator}'"
+        )
+
+    def next(
+        self,
+        existing_ids: Iterable[str],
+        *,
+        segment: str | None = None,
+    ) -> str:
+        """Return the next ID not present in existing_ids."""
+        max_num = 0
+        for eid in existing_ids:
+            try:
+                parts = self.parse_parts(eid)
+            except ValueError:
+                continue
+            if segment is not None and parts.segment != segment:
+                continue
+            if segment is None and parts.segment is not None:
+                continue
+            if parts.number > max_num:
+                max_num = parts.number
+        return self.format(max_num + 1, segment=segment)
+
+    def is_valid(self, value: object) -> bool:
+        """Check whether a value is a valid ID for this format."""
+        if not isinstance(value, str):
+            return False
+        try:
+            parts = self.parse_parts(value)
+            if parts.segment is not None and self.segment_required is False:
+                return True
+            if parts.segment is None and self.segment_required:
+                return False
+            return True
+        except ValueError:
+            return False
+
+    def filename(self, value: str, *, extension: str) -> str:
+        """Convert an ID to a filename with the given extension."""
+        return f"{value}{extension}"
+
+    def _build_simple_pattern(self) -> re.Pattern[str]:
+        sep = re.escape(self.separator)
+        return re.compile(rf"^{re.escape(self.prefix)}{sep}(?P<number>\d+)$")
+
+    def _build_segmented_pattern(self) -> re.Pattern[str]:
+        assert self.segment_separator is not None
+        seg_sep = re.escape(self.segment_separator)
+        sep = re.escape(self.separator)
+        return re.compile(
+            rf"^{re.escape(self.prefix)}"
+            rf"{seg_sep}(?P<segment>[a-zA-Z0-9_-]+)"
+            rf"{sep}(?P<number>\d+)$"
+        )
+
+
+@dataclass(frozen=True)
+class NumericIdFormat:
+    """Configurable prefixed numeric ID format (legacy compatibility)."""
+
+    prefix: str
+    separator: str = "-"
+    width: int = 4
+
+    def format(self, number: int) -> str:
+        """Format a number as a prefixed, zero-padded ID string."""
+        return f"{self.prefix}{self.separator}{number:0{self.width}d}"
+
+    def parse(self, value: str) -> int:
+        """Parse a prefixed ID string and return the numeric part."""
+        expected_prefix = f"{self.prefix}{self.separator}"
+        if not value.startswith(expected_prefix):
+            raise ValueError(f"ID '{value}' does not match prefix '{expected_prefix}'")
+        num_str = value[len(expected_prefix) :]
+        if not num_str.isdigit():
+            raise ValueError(f"Numeric part of ID '{value}' is not a valid number")
+        return int(num_str)
+
+    def next(self, existing_ids: Iterable[str]) -> str:
+        """Return the next ID not present in existing_ids."""
+        max_num = 0
+        expected_prefix = f"{self.prefix}{self.separator}"
+        for eid in existing_ids:
+            if not eid.startswith(expected_prefix):
+                continue
+            num_str = eid[len(expected_prefix) :]
+            if num_str.isdigit():
+                num = int(num_str)
+                if num > max_num:
+                    max_num = num
+        return self.format(max_num + 1)
+
+
+def _validate_number(number: int) -> None:
+    """Validate that number is a positive integer and not a boolean."""
+    if isinstance(number, bool):
+        raise ValueError("Number must not be a boolean")
+    if number <= 0:
+        raise ValueError(f"Number must be positive, got {number}")
+
+
+def parse_prefixed_number(
+    value: str,
+    *,
+    prefix: str,
+    separator: str = "-",
+    width: int = 4,
+) -> int:
+    """Parse a prefixed numeric ID string and return the number."""
+    fmt = NumericIdFormat(prefix=prefix, separator=separator, width=width)
+    return fmt.parse(value)
+
+
+def next_prefixed_id(
+    prefix: str,
+    existing_ids: Iterable[str],
+    *,
+    separator: str = "-",
+    width: int = 4,
+) -> str:
+    """Return the next prefixed ID given existing IDs."""
+    fmt = NumericIdFormat(prefix=prefix, separator=separator, width=width)
+    return fmt.next(existing_ids)
+
+
+_slug_non_alpha = re.compile(r"[^a-z0-9]+")
+
+
+def slugify_ref(value: str, *, empty: str = "item") -> str:
+    """Lowercase, trim, collapse non-alphanumeric runs to dashes."""
+    slug = _slug_non_alpha.sub("-", value.strip().lower()).strip("-")
+    if not slug:
+        return empty
+    return slug

ledgercore/io.py

@@ -0,0 +1,64 @@
+"""Text I/O utilities for ledgercore."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+
+def normalize_newlines(text: str) -> str:
+    """Convert CRLF and CR to LF."""
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def ensure_dir(path: Path) -> None:
+    """Create parent directories as needed."""
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def read_text(path: Path, *, normalize: bool = True) -> str:
+    """Read UTF-8 text from a file."""
+    if normalize:
+        text = path.read_text(encoding="utf-8")
+        return normalize_newlines(text)
+    return path.read_bytes().decode("utf-8")
+
+
+def write_text(path: Path, text: str, *, normalize: bool = True) -> None:
+    """Write UTF-8 text to a file, creating parent directories."""
+    if normalize:
+        text = normalize_newlines(text)
+    ensure_dir(path.parent)
+    path.write_text(text, encoding="utf-8")
+
+
+def content_hash(text: str) -> str:
+    """Return a stable SHA-256 hex digest of UTF-8 text."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def summarize_text(text: str, max_chars: int = 80) -> str:
+    """Collapse whitespace and truncate safely."""
+    collapsed = re.sub(r"\s+", " ", text).strip()
+    if len(collapsed) <= max_chars:
+        return collapsed
+    truncated = collapsed[:max_chars]
+    if truncated.rfind(" ") > max_chars // 2:
+        truncated = truncated[: truncated.rfind(" ")]
+    return truncated.rstrip() + "..."
+
+
+def merge_text(current: str, incoming: str, *, prepend: bool = False) -> str:
+    """Combine text blocks without introducing excessive blank lines."""
+    cur = current.strip()
+    inc = incoming.strip()
+    if not cur:
+        return inc
+    if not inc:
+        return cur
+    if prepend:
+        parts = [inc, cur]
+    else:
+        parts = [cur, inc]
+    return "\n\n".join(parts)