documentation-engine 0.1.2__py3-none-any.whl

docsystem/readiness.py

@@ -0,0 +1,132 @@
+"""Read-only adoption readiness evaluation for existing Markdown projects.
+
+This module never writes to the source tree or the projection cache; it only
+re-reads catalog and projection state already produced by `catalog.py` and
+`projection.py` and groups it into the categories an adopting project needs to
+tell apart before running any mutating command.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from docsystem.catalog import (
+    MarkdownCatalog,
+    RelationBoundary,
+    RelationMigration,
+    ValidationIssue,
+    validate_membership,
+    validate_metadata,
+    validate_reachability,
+    validate_sections,
+)
+from docsystem.config import ProjectConfig
+from docsystem.projection import build_projection, projection_status
+
+
+@dataclass(frozen=True)
+class ReadinessReport:
+    """A deterministic snapshot of whether a project can adopt the engine."""
+
+    documentation_root_exists: bool
+    blocking: tuple[ValidationIssue, ...]
+    resolvable_migrations: tuple[RelationMigration, ...]
+    boundaries: tuple[RelationBoundary, ...]
+    stale_pins: tuple[ValidationIssue, ...]
+    projection_present: bool
+    projection_current: bool
+    projection_reason: str
+
+    @property
+    def ready(self) -> bool:
+        """Whether the project is free of blocking structural errors."""
+
+        return self.documentation_root_exists and not self.blocking
+
+    @property
+    def projection_state(self) -> str:
+        if not self.projection_present:
+            return "absent"
+        if self.projection_current:
+            return "current"
+        return "stale"
+
+    def next_command(self, project: str) -> str:
+        """The single safe next command; never a source-mutating default."""
+
+        if not self.documentation_root_exists:
+            return f"docsystem init {project}"
+        if self.blocking:
+            return f"docsystem doctor {project}"
+        if self.resolvable_migrations:
+            return f"docsystem migrate {project}"
+        if self.projection_state != "current":
+            return f"docsystem index {project} --write"
+        return f"docsystem context DOCUMENT_ID {project}"
+
+
+def evaluate_readiness(
+    config: ProjectConfig, catalog: MarkdownCatalog
+) -> ReadinessReport:
+    """Evaluate readiness without writing Markdown, cache or configuration."""
+
+    if not config.documentation_root.is_dir():
+        return ReadinessReport(
+            documentation_root_exists=False,
+            blocking=(),
+            resolvable_migrations=(),
+            boundaries=(),
+            stale_pins=(),
+            projection_present=False,
+            projection_current=False,
+            projection_reason="documentation root does not exist",
+        )
+
+    paths = {
+        document.metadata.document_id: document.path
+        for document in catalog.documents
+        if document.metadata is not None
+    }
+    metadata_issues = validate_metadata(catalog)
+    self_reference_errors = tuple(
+        ValidationIssue(
+            paths[item.source_id],
+            f"legacy metadata.{item.relation} value {item.value!r}: {item.reason}",
+            affects_graph=True,
+        )
+        for item in catalog.relation_boundaries
+        if item.reason == "self reference"
+    )
+    blocking = tuple(
+        sorted(
+            (
+                *validate_membership(catalog),
+                *(issue for issue in metadata_issues if issue.severity != "warning"),
+                *validate_sections(catalog, config),
+                *validate_reachability(catalog, config),
+                *self_reference_errors,
+            ),
+            key=lambda issue: (issue.path.as_posix(), issue.severity, issue.message),
+        )
+    )
+    stale_pins = tuple(
+        issue
+        for issue in metadata_issues
+        if issue.severity == "warning" and issue.target_id is not None
+    )
+    boundaries = tuple(
+        item for item in catalog.relation_boundaries if item.reason != "self reference"
+    )
+    current_projection = build_projection(catalog, config)
+    valid, reason = projection_status(config, current_projection)
+    projection_present = reason != "projection absent"
+    return ReadinessReport(
+        documentation_root_exists=True,
+        blocking=blocking,
+        resolvable_migrations=catalog.relation_migrations,
+        boundaries=boundaries,
+        stale_pins=stale_pins,
+        projection_present=projection_present,
+        projection_current=valid,
+        projection_reason=reason,
+    )

docsystem/sections.py

@@ -0,0 +1,252 @@
+"""Deterministic Markdown ATX heading and section extraction."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+ATX_HEADING_PATTERN = re.compile(
+    r"^ {0,3}(#{1,6})[ \t]+(.+?)(?:[ \t]+#+[ \t]*)?$"
+)
+FENCE_PATTERN = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+EXPLICIT_ANCHOR_PATTERN = re.compile(
+    r"^ {0,3}<a\s+(?:id|name)=([\"'])([^\"']+)\1\s*></a>\s*$",
+    re.IGNORECASE,
+)
+ANCHOR_TAG_START_PATTERN = re.compile(r"^\s*<a\b", re.IGNORECASE)
+ATTRIBUTE_NAME_PATTERN = re.compile(r"(?:^|\s)([^\s=/>]+)(?=\s|=|/|$)")
+
+
+@dataclass(frozen=True)
+class MarkdownSection:
+    """A stable, addressable section in a Markdown source."""
+
+    title: str
+    anchor: str
+    level: int
+    start_line: int
+    end_line: int
+
+
+@dataclass(frozen=True)
+class SectionParseResult:
+    """Addressable sections plus deterministic parser diagnostics."""
+
+    sections: tuple[MarkdownSection, ...]
+    issues: tuple[str, ...]
+
+
+def is_valid_anchor(value: str) -> bool:
+    """Return whether a canonical anchor uses the supported stable syntax."""
+
+    return bool(value) and value[0].isalnum() and all(
+        character.isalnum() or character in "-_.:" for character in value
+    )
+
+
+def heading_anchor(title: str) -> str:
+    """Create a deterministic GitHub-like Unicode heading anchor."""
+
+    characters = [
+        character.casefold()
+        for character in title
+        if character.isalnum() or character in {" ", "-", "_", "\t"}
+    ]
+    return re.sub(r"\s+", "-", "".join(characters)).strip("-")
+
+
+def _is_explicit_anchor_candidate(line: str) -> bool:
+    """Detect id/name attribute tokens without inspecting quoted values."""
+
+    start = ANCHOR_TAG_START_PATTERN.match(line)
+    if start is None:
+        return False
+    opening: list[str] = []
+    quote: str | None = None
+    for character in line[start.end() :]:
+        if quote is not None:
+            if character == quote:
+                quote = None
+            opening.append(" ")
+        elif character in {'"', "'"}:
+            quote = character
+            opening.append(" ")
+        elif character == ">":
+            break
+        else:
+            opening.append(character)
+    names = {
+        match.group(1).casefold()
+        for match in ATTRIBUTE_NAME_PATTERN.finditer("".join(opening))
+    }
+    return bool(names & {"id", "name"})
+
+
+def parse_sections_result(text: str) -> SectionParseResult:
+    """Parse ATX headings and explicit anchors without repairing ambiguity."""
+
+    lines = text.splitlines()
+    headings: list[tuple[str, str, int, int]] = []
+    issues: list[str] = []
+    anchor_counts: dict[str, int] = {}
+    anchor_owners: dict[str, tuple[str, int]] = {}
+    explicit_owners: dict[str, int] = {}
+    pending_anchors: list[tuple[str, int]] = []
+    fence_character: str | None = None
+    fence_length = 0
+
+    def orphan_pending() -> None:
+        for anchor, anchor_line in pending_anchors:
+            issues.append(
+                f"orphaned explicit anchor {anchor!r} at line {anchor_line}; "
+                "it must directly precede an ATX heading"
+            )
+        pending_anchors.clear()
+
+    for line_number, line in enumerate(lines, start=1):
+        fence = FENCE_PATTERN.match(line)
+        if fence_character is None and fence:
+            orphan_pending()
+            marker = fence.group(1)
+            if marker[0] == "`" and "`" in line[fence.end() :]:
+                continue
+            fence_character = marker[0]
+            fence_length = len(marker)
+            continue
+        if fence_character is not None:
+            if (
+                fence is not None
+                and fence.group(1)[0] == fence_character
+                and len(fence.group(1)) >= fence_length
+                and not line[fence.end() :].strip()
+            ):
+                fence_character = None
+                fence_length = 0
+            continue
+
+        explicit_match = EXPLICIT_ANCHOR_PATTERN.match(line)
+        if explicit_match is not None:
+            value = explicit_match.group(2)
+            if not is_valid_anchor(value):
+                orphan_pending()
+                issues.append(
+                    f"malformed explicit anchor {value!r} at line {line_number}"
+                )
+                continue
+            pending_anchors.append((value, line_number))
+            continue
+        if _is_explicit_anchor_candidate(line):
+            orphan_pending()
+            issues.append(f"malformed explicit anchor at line {line_number}")
+            continue
+
+        match = ATX_HEADING_PATTERN.match(line)
+        if match is None:
+            orphan_pending()
+            continue
+        title = match.group(2).strip()
+        explicit = len(pending_anchors) == 1
+        if len(pending_anchors) > 1:
+            rendered = ", ".join(
+                f"{anchor!r} at line {anchor_line}"
+                for anchor, anchor_line in pending_anchors
+            )
+            issues.append(
+                f"multiple explicit anchors before heading at line {line_number}: "
+                f"{rendered}"
+            )
+        if explicit:
+            anchor, anchor_line = pending_anchors[0]
+        else:
+            base_anchor = heading_anchor(title)
+            occurrence = anchor_counts.get(base_anchor, 0)
+            anchor_counts[base_anchor] = occurrence + 1
+            anchor = (
+                base_anchor if occurrence == 0 else f"{base_anchor}-{occurrence}"
+            )
+            anchor_line = line_number
+        pending_anchors.clear()
+
+        owner = anchor_owners.get(anchor)
+        if explicit and anchor in explicit_owners:
+            issues.append(
+                f"duplicate explicit anchor {anchor!r} at line {anchor_line}; "
+                f"first used at line {explicit_owners[anchor]}"
+            )
+        elif owner is not None:
+            owner_kind, owner_line = owner
+            current_kind = "explicit" if explicit else "generated"
+            issues.append(
+                f"anchor collision {anchor!r}: {owner_kind} anchor at line "
+                f"{owner_line} and {current_kind} anchor at line {anchor_line}"
+            )
+        if explicit:
+            explicit_owners.setdefault(anchor, anchor_line)
+        anchor_owners.setdefault(
+            anchor, ("explicit" if explicit else "generated", anchor_line)
+        )
+        headings.append((title, anchor, len(match.group(1)), line_number))
+    orphan_pending()
+
+    sections: list[MarkdownSection] = []
+    for index, (title, anchor, level, start_line) in enumerate(headings):
+        end_line = len(lines)
+        for _, _, next_level, next_line in headings[index + 1 :]:
+            if next_level <= level:
+                end_line = next_line - 1
+                break
+        sections.append(
+            MarkdownSection(title, anchor, level, start_line, end_line)
+        )
+    return SectionParseResult(tuple(sections), tuple(issues))
+
+
+def parse_sections(text: str) -> tuple[MarkdownSection, ...]:
+    """Parse addressable sections while preserving the original public API."""
+
+    return parse_sections_result(text).sections
+
+
+def extract_section(text: str, section: MarkdownSection) -> str:
+    """Return one section including its nested subsections."""
+
+    lines = text.splitlines()
+    return "\n".join(lines[section.start_line - 1 : section.end_line]).rstrip() + "\n"
+
+
+def navigation_issues(
+    sections: tuple[MarkdownSection, ...], extend_through: tuple[str, ...]
+) -> tuple[str, ...]:
+    """Validate document-specific navigation extension anchors."""
+
+    issues: list[str] = []
+    for anchor in extend_through:
+        for section in sections:
+            if section.anchor == anchor and section.level != 2:
+                issues.append(
+                    f"navigation.extend_through anchor {anchor!r} resolves to "
+                    f"H{section.level}, expected H2"
+                )
+    return tuple(issues)
+
+
+def extract_navigation(
+    text: str,
+    sections: tuple[MarkdownSection, ...],
+    extend_through: tuple[str, ...] = (),
+) -> str:
+    """Return the default prefix or extend it through configured H2 sections."""
+
+    first_h2 = next((section for section in sections if section.level == 2), None)
+    lines = text.splitlines()
+    matching = [
+        section
+        for section in sections
+        if section.level == 2 and section.anchor in extend_through
+    ]
+    if matching:
+        end_line = max(section.end_line for section in matching)
+        return "\n".join(lines[:end_line]) + "\n"
+    if first_h2 is None:
+        return text if text.endswith("\n") else f"{text}\n"
+    return "\n".join(lines[: first_h2.start_line - 1]).rstrip() + "\n"