okf-schema 0.2.0__py3-none-any.whl

okf_schema/__init__.py

@@ -0,0 +1,5 @@
+"""okf-schema — CLI tool and Python library for OKF bundle management."""
+
+from importlib.metadata import version
+
+__version__ = version("okf_schema")

okf_schema/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal infrastructure modules for okf-schema."""

okf_schema/_internal/models.py

@@ -0,0 +1,94 @@
+"""Data models for okf-schema validation and reporting."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Finding:
+    """A single validation finding (error or warning)."""
+
+    code: str
+    message: str
+    path: Path | None = None
+
+
+@dataclass
+class Report:
+    """Aggregated validation report for an OKF bundle."""
+
+    errors: list[Finding] = field(default_factory=list)
+    warnings: list[Finding] = field(default_factory=list)
+
+    @property
+    def is_conformant(self) -> bool:
+        """Return True if the report contains no errors."""
+        return len(self.errors) == 0
+
+    def add_error(self, code: str, message: str, path: Path | None = None) -> None:
+        """Append an error finding to the report."""
+        self.errors.append(Finding(code, message, path))
+
+    def add_warning(self, code: str, message: str, path: Path | None = None) -> None:
+        """Append a warning finding to the report."""
+        self.warnings.append(Finding(code, message, path))
+
+
+@dataclass
+class ConceptInfo:
+    """Extracted metadata from an OKF concept file."""
+
+    title: str
+    description: str
+    type: str
+
+
+@dataclass
+class SearchResult:
+    """Result from searching an OKF bundle."""
+
+    path: str
+    type: str
+    title: str
+
+
+@dataclass
+class BundleStats:
+    """Statistics for an OKF bundle."""
+
+    total_files: int
+    total_concepts: int
+    files_without_frontmatter: int
+    total_size: int
+    total_links: int
+    broken_links: int
+    types_distribution: dict[str, int]
+    tags_distribution: dict[str, int]
+    directories: int
+
+
+@dataclass
+class ConceptSummary:
+    """Summary of a single concept in an OKF bundle."""
+
+    path: str
+    type: str
+    title: str
+
+
+@dataclass
+class ConceptDetail:
+    """Detailed view of a single concept file."""
+
+    frontmatter: dict
+    body: str
+
+
+@dataclass
+class IndexUpdate:
+    """Record of an index.md update operation."""
+
+    path: str
+    action: str

okf_schema/_internal/utils.py

@@ -0,0 +1,93 @@
+"""Shared utilities for OKF bundle processing."""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+from okf_schema._internal.models import ConceptInfo
+from okf_schema._internal.yaml import extract_frontmatter, parse_yaml
+
+RESERVED_FILES = {"index.md", "log.md"}
+ISO8601_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+MARKDOWN_LINK_RE = re.compile(r"!?\[([^\]]*)\]\(([^)]+)\)")
+
+
+def collect_markdown_files(bundle: Path) -> Iterable[Path]:
+    """Yield every ``.md`` file under *bundle*, sorted alphabetically."""
+    for path in sorted(bundle.rglob("*.md")):
+        if path.is_file():
+            yield path
+
+
+def resolve_link(target: str, source: Path, bundle_root: Path) -> Path | None:
+    """Resolve a markdown link target to an absolute path.
+
+    Returns ``None`` for external URLs (``https://``, ``mailto:``, etc.).
+    Absolute paths starting with ``/`` are resolved relative to
+    *bundle_root*. Relative paths are resolved relative to *source*'s
+    parent directory.
+    """
+    if "://" in target or target.startswith("mailto:"):
+        return None
+
+    if target.startswith("/"):
+        resolved = bundle_root / target.lstrip("/")
+    else:
+        resolved = source.parent / target
+
+    with contextlib.suppress(OSError):
+        resolved = resolved.resolve()
+
+    return resolved
+
+
+def find_broken_links(body: str, source: Path, bundle_root: Path) -> list[str]:
+    """Find broken internal links in markdown body text.
+
+    Returns a list of link targets that do not exist on disk.
+    External links are skipped. Directories are accepted as valid targets.
+    """
+    broken: list[str] = []
+    for _text, target in MARKDOWN_LINK_RE.findall(body):
+        resolved = resolve_link(target, source, bundle_root)
+        if resolved is None:
+            continue  # external link — can't check
+        if not resolved.exists():
+            broken.append(target)
+    return broken
+
+
+def has_markdown_files(dir_path: Path) -> bool:
+    """Return True if *dir_path* or any descendant contains ``.md`` files."""
+    if not dir_path.is_dir():
+        return False
+    return any(item.is_file() for item in dir_path.rglob("*.md"))
+
+
+def get_concept_info(path: Path) -> ConceptInfo:
+    """Extract title, description, and type from a concept file.
+
+    Falls back to a title derived from the file stem (replacing ``-`` and
+    ``_`` with spaces, title-cased) when frontmatter is missing or
+    incomplete.
+    """
+    text = path.read_text(encoding="utf-8")
+    fm_text, _body = extract_frontmatter(text)
+
+    fallback_title = path.stem.replace("-", " ").replace("_", " ").title()
+    info = ConceptInfo(title=fallback_title, description="", type="")
+
+    if fm_text is not None:
+        frontmatter = parse_yaml(fm_text)
+        if frontmatter is not None:
+            if frontmatter.get("title"):
+                info.title = str(frontmatter["title"]).strip()
+            if frontmatter.get("description"):
+                info.description = str(frontmatter["description"]).strip()
+            if frontmatter.get("type"):
+                info.type = str(frontmatter["type"]).strip()
+
+    return info

okf_schema/_internal/yaml.py

@@ -0,0 +1,98 @@
+"""YAML helpers using ruamel.yaml for OKF frontmatter handling."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import cast
+
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+
+def make_yaml() -> YAML:
+    """Return a configured ruamel.yaml instance for round-trip parsing.
+
+    Configures ``preserve_quotes=True`` and ``default_flow_style=False``
+    so that formatting and comments are retained during load/dump cycles.
+    """
+    y = YAML()
+    y.preserve_quotes = True
+    y.default_flow_style = False
+    return y
+
+
+def _normalize_yaml_value(value: object) -> object:
+    """Recursively convert YAML-native types to JSON-compatible primitives.
+
+    ruamel.yaml parses ISO 8601 dates as ``datetime.date`` and
+    ``datetime.datetime`` objects.  JSON Schema validators expect
+    ``type: string`` fields to be actual strings, so we transparently
+    convert them to ISO 8601 strings here.
+    """
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {k: _normalize_yaml_value(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_normalize_yaml_value(item) for item in value]
+    return value
+
+
+def extract_frontmatter(text: str) -> tuple[str | None, str]:
+    """Extract YAML frontmatter from markdown text.
+
+    Frontmatter is delimited by ``---`` at the start of the file and a
+    closing ``---`` on its own line. Returns ``(frontmatter_yaml, body)``
+    or ``(None, text)`` when no valid frontmatter block is found.
+    """
+    if not text.startswith("---"):
+        return None, text
+
+    end_marker = "\n---"
+    end_idx = text.find(end_marker, 3)
+    if end_idx == -1:
+        return None, text
+
+    fm_text = text[3:end_idx]
+    body = text[end_idx + len(end_marker) :]
+    if body.startswith("\n"):
+        body = body[1:]
+    return fm_text, body
+
+
+def parse_yaml(yaml_text: str) -> dict | None:
+    """Parse YAML text into a plain dict.
+
+    Uses :func:`make_yaml` for consistent configuration. Returns ``None``
+    when the text is not valid YAML or does not parse to a mapping.
+
+    Date and datetime values are automatically converted to ISO 8601
+    strings so that JSON Schema ``type: string`` validation works
+    transparently for unquoted YAML dates.
+    """
+    y = make_yaml()
+    try:
+        data = y.load(yaml_text)
+    except YAMLError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    # ruamel.yaml returns CommentedMap — convert to plain dict
+    # and normalize native datetime types to strings
+    return cast(dict, _normalize_yaml_value(dict(data)))
+
+
+def dump_yaml(data: dict) -> str:
+    """Serialize a dict to a YAML string.
+
+    Uses :func:`make_yaml` so that quotes and comments are preserved
+    when round-tripping through :func:`parse_yaml`.
+    """
+    from io import StringIO
+
+    y = make_yaml()
+    buf = StringIO()
+    y.dump(data, buf)
+    return buf.getvalue()