documentation-engine 0.1.2__py3-none-any.whl

docsystem/config.py

@@ -0,0 +1,216 @@
+"""Project configuration loading and validation."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from docsystem.sections import is_valid_anchor
+
+CONFIG_FILENAME = ".docsystem.toml"
+PREFIX_PATTERN = re.compile(r"^[A-Z][A-Z0-9]{1,15}$")
+DEFAULT_CONFIG = """\
+version = 1
+
+[documentation]
+root = "plan"
+language = "en"
+
+[areas]
+foundation = "foundation"
+architecture = "architecture"
+decisions = "decisions"
+roadmap = "roadmap"
+scratch = "scratch"
+reviews = "reviews"
+experiments = "experiments"
+modules = "modules"
+
+[identifiers]
+document = "DOC"
+decision = "DEC"
+roadmap = "RM"
+
+[catalog]
+exclude = []
+
+[navigation]
+extend_through = []
+
+[relations]
+legacy_paths = "strict"
+snapshot_types = []
+
+[projection]
+format = "sharded-json"
+keep_generations = 2
+"""
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    project_root: Path
+    documentation_root: Path
+    language: str
+    areas: dict[str, PurePosixPath]
+    identifiers: dict[str, str]
+    projection_format: str
+    keep_generations: int
+    catalog_exclusions: tuple[str, ...] = ()
+    navigation_extend_through: tuple[str, ...] = ()
+    legacy_relation_mode: str = "strict"
+    snapshot_document_types: tuple[str, ...] = ()
+
+
+def _relative_path(value: object, field: str) -> PurePosixPath:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{field} must be a non-empty string")
+    path = PurePosixPath(value)
+    if path.is_absolute() or ".." in path.parts:
+        raise ValueError(f"{field} must be a project-relative path")
+    return path
+
+
+def _catalog_exclusions(raw: object) -> tuple[str, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, dict):
+        raise ValueError("catalog must be a table")
+    values = raw.get("exclude", [])
+    if not isinstance(values, list):
+        raise ValueError("catalog.exclude must be a list")
+
+    patterns: list[str] = []
+    seen: set[str] = set()
+    for index, value in enumerate(values):
+        field = f"catalog.exclude[{index}]"
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{field} must be a non-empty string")
+        if "\\" in value:
+            raise ValueError(f"{field} must use POSIX '/' separators")
+        path = PurePosixPath(value)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(
+                f"{field} must be relative to the documentation root"
+            )
+        normalized = path.as_posix()
+        if normalized in seen:
+            raise ValueError(
+                f"catalog.exclude contains duplicate normalized pattern "
+                f"{normalized!r}"
+            )
+        seen.add(normalized)
+        patterns.append(normalized)
+    return tuple(patterns)
+
+
+def _navigation_anchors(raw: object) -> tuple[str, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, dict):
+        raise ValueError("navigation must be a table")
+    values = raw.get("extend_through", [])
+    if not isinstance(values, list):
+        raise ValueError("navigation.extend_through must be a list")
+
+    anchors: list[str] = []
+    seen: set[str] = set()
+    for index, value in enumerate(values):
+        field = f"navigation.extend_through[{index}]"
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{field} must be a non-empty string")
+        if not is_valid_anchor(value):
+            raise ValueError(f"{field} has unsupported anchor syntax")
+        if value in seen:
+            raise ValueError(
+                f"navigation.extend_through contains duplicate anchor {value!r}"
+            )
+        seen.add(value)
+        anchors.append(value)
+    return tuple(anchors)
+
+
+def _relations_policy(raw: object) -> tuple[str, tuple[str, ...]]:
+    if raw is None:
+        return "strict", ()
+    if not isinstance(raw, dict):
+        raise ValueError("relations must be a table")
+    mode = raw.get("legacy_paths", "strict")
+    if mode not in {"strict", "resolve-with-warning"}:
+        raise ValueError(
+            "relations.legacy_paths must be 'strict' or 'resolve-with-warning'"
+        )
+    types = raw.get("snapshot_types", [])
+    if not isinstance(types, list) or any(
+        not isinstance(item, str) or not item.strip() for item in types
+    ):
+        raise ValueError("relations.snapshot_types must be a list of non-empty strings")
+    if len(set(types)) != len(types):
+        raise ValueError("relations.snapshot_types must be unique")
+    return mode, tuple(types)
+
+
+def load_config(project_root: Path) -> ProjectConfig:
+    root = project_root.resolve()
+    config_path = root / CONFIG_FILENAME
+    if not config_path.is_file():
+        raise ValueError(f"configuration not found: {config_path}")
+    with config_path.open("rb") as handle:
+        raw = tomllib.load(handle)
+
+    if raw.get("version") != 1:
+        raise ValueError("unsupported configuration version")
+    documentation = raw.get("documentation")
+    areas = raw.get("areas")
+    identifiers = raw.get("identifiers")
+    projection = raw.get("projection")
+    if not all(isinstance(item, dict) for item in (documentation, areas, identifiers, projection)):
+        raise ValueError("documentation, areas, identifiers and projection tables are required")
+
+    documentation_path = _relative_path(documentation.get("root"), "documentation.root")
+    language = documentation.get("language")
+    if not isinstance(language, str) or not language:
+        raise ValueError("documentation.language must be a non-empty string")
+
+    normalized_areas = {
+        str(role): _relative_path(path, f"areas.{role}") for role, path in areas.items()
+    }
+    if len(set(normalized_areas.values())) != len(normalized_areas):
+        raise ValueError("area paths must be unique")
+
+    normalized_identifiers: dict[str, str] = {}
+    for role, prefix in identifiers.items():
+        if not isinstance(prefix, str) or not PREFIX_PATTERN.fullmatch(prefix):
+            raise ValueError(f"identifiers.{role} has an invalid prefix")
+        normalized_identifiers[str(role)] = prefix
+    if len(set(normalized_identifiers.values())) != len(normalized_identifiers):
+        raise ValueError("identifier prefixes must be unique")
+
+    catalog_exclusions = _catalog_exclusions(raw.get("catalog"))
+    navigation_extend_through = _navigation_anchors(raw.get("navigation"))
+    legacy_relation_mode, snapshot_document_types = _relations_policy(
+        raw.get("relations")
+    )
+
+    projection_format = projection.get("format")
+    if projection_format != "sharded-json":
+        raise ValueError("only sharded-json projection is supported")
+    keep_generations = projection.get("keep_generations")
+    if not isinstance(keep_generations, int) or not 1 <= keep_generations <= 20:
+        raise ValueError("projection.keep_generations must be between 1 and 20")
+
+    return ProjectConfig(
+        project_root=root,
+        documentation_root=root / documentation_path,
+        language=language,
+        areas=normalized_areas,
+        identifiers=normalized_identifiers,
+        projection_format=projection_format,
+        keep_generations=keep_generations,
+        catalog_exclusions=catalog_exclusions,
+        navigation_extend_through=navigation_extend_through,
+        legacy_relation_mode=legacy_relation_mode,
+        snapshot_document_types=snapshot_document_types,
+    )

docsystem/mcp_server.py

@@ -0,0 +1,324 @@
+"""Thin MCP (Model Context Protocol) adapter over the `docsystem` CLI.
+
+The adapter translates MCP tool calls into the same CLI invocations the
+agent contract documents, running them in a subprocess so it can never
+bypass the core's validation, projection-fallback or output contracts.
+Only read-only commands are exposed; mutating operations (`init`,
+`migrate --apply`, `index --write`) stay with the human or calling system,
+matching `docs/agent-contract.md`.
+
+Structured (object) tools surface any successful-exit CLI stderr -- most
+importantly the `projection stale/corrupt; using direct Markdown` fallback
+warning -- under a `diagnostics` key, so a client never loses that signal.
+Text tools (`read_document`, `impact`) keep returning the CLI stdout unchanged
+for compatibility. Their packet variants (`read_document_packet`,
+`impact_packet`) expose the same stdout together with successful-exit
+diagnostics in a structured envelope.
+
+The `mcp` package is an optional dependency: install `documentation-engine[mcp]`
+to run the server (`docsystem-mcp` or `python -m docsystem.mcp_server`). The
+tool functions themselves are plain Python and work without it.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+
+def _invoke(
+    arguments: list[str], *, allow_failure_payload: bool = False
+) -> tuple[str, str]:
+    """Run a CLI command, returning its stdout and stderr.
+
+    A non-zero exit raises `RuntimeError` carrying the CLI diagnostics, so a
+    client never mistakes a failure for data. The one exception is a command
+    that prints a payload while exiting non-zero (for example `readiness`
+    reporting a legitimate "not ready" state): with `allow_failure_payload`
+    that payload is returned instead of raising.
+    """
+
+    result = subprocess.run(
+        [sys.executable, "-m", "docsystem", *arguments],
+        capture_output=True,
+        encoding="utf-8",
+        text=True,
+    )
+    if result.returncode != 0 and not (allow_failure_payload and result.stdout.strip()):
+        message = result.stderr.strip() or result.stdout.strip()
+        raise RuntimeError(message or f"docsystem {' '.join(arguments)} failed")
+    return result.stdout, result.stderr
+
+
+def _run_cli(arguments: list[str], *, allow_failure_payload: bool = False) -> str:
+    stdout, _ = _invoke(arguments, allow_failure_payload=allow_failure_payload)
+    return stdout
+
+
+def _text_packet(arguments: list[str]) -> dict:
+    """Run a text CLI command and preserve successful-exit diagnostics."""
+
+    stdout, stderr = _invoke(arguments)
+    payload = {"schema_version": 1, "text": stdout}
+    diagnostics = _diagnostics(stderr)
+    if diagnostics:
+        payload["diagnostics"] = diagnostics
+    return payload
+
+
+def _diagnostics(stderr: str) -> list[str]:
+    """Return non-empty successful-exit stderr lines, in CLI order."""
+
+    return [line for line in stderr.splitlines() if line.strip()]
+
+
+def _json_tool(
+    arguments: list[str], *, allow_failure_payload: bool = False
+) -> dict:
+    """Run a `--json` CLI command and decode its structured payload.
+
+    On a successful exit the CLI can still print diagnostics to stderr -- most
+    importantly the `WARNING: projection ...; using direct Markdown` note when
+    a `context`/read command falls back from a stale or corrupt projection.
+    Those lines would otherwise be lost, so they are surfaced deterministically
+    under a `diagnostics` key. The key is present only when the CLI emitted
+    such diagnostics, keeping every other payload byte-identical to the CLI's
+    `--json` output.
+    """
+
+    stdout, stderr = _invoke(arguments, allow_failure_payload=allow_failure_payload)
+    payload = json.loads(stdout)
+    diagnostics = _diagnostics(stderr)
+    if diagnostics:
+        payload["diagnostics"] = diagnostics
+    return payload
+
+
+def readiness(project: str) -> dict:
+    """Report adoption readiness for a project as a structured object.
+
+    Read-only. `ready` is false while blocking errors remain; `next_command`
+    names the single safe next step. Always pass the project root explicitly.
+    """
+
+    return _json_tool(["readiness", project, "--json"], allow_failure_payload=True)
+
+
+def catalog(project: str, explain: bool = False) -> dict:
+    """List cataloged Markdown documents and their logical roles.
+
+    Read-only. With `explain`, classifies every Markdown source under the
+    documentation root as included, excluded or unmapped.
+    """
+
+    arguments = ["catalog", project, "--json"]
+    if explain:
+        arguments.insert(2, "--explain")
+    return _json_tool(arguments)
+
+
+def migration_report(project: str) -> dict:
+    """Report resolvable legacy relation migrations and explicit boundaries.
+
+    Read-only dry run: `resolved` rows are safe path-to-ID migration
+    candidates; `boundaries` (external URLs, resources) are human decisions
+    and must never be converted into invented document IDs.
+    """
+
+    return _json_tool(["migration-report", project, "--json"])
+
+
+def changes(project: str) -> dict:
+    """Report documents and sections changed since the selected projection."""
+
+    return _json_tool(["changes", project, "--json"])
+
+
+def context(
+    project: str,
+    document_id: str,
+    depth: int = 1,
+    include_related: bool = False,
+    include: list[str] | None = None,
+    anchor: str | None = None,
+    outline: bool = False,
+    assume_known: list[str] | None = None,
+    since: str | None = None,
+) -> dict:
+    """Build a deterministic, inspectable context packet for a document.
+
+    Read-only. The packet reports exactly what was included and omitted —
+    never a silent token-budget truncation. Expand coverage with `depth`,
+    `include_related` or explicit `include` selections (`ID` or `ID#anchor`)
+    instead of assuming omitted material is irrelevant. Set `outline` for a
+    map-first packet of per-section `lines`/`bytes` sizes with no document
+    content, to budget tokens before fetching; `outline` cannot combine with
+    `anchor` or `include`. Declare documents already held with
+    `assume_known` (`ID@REV`, repeatable): a document at the declared
+    revision has its content omitted, a mismatch keeps it. Request a delta
+    against a retained projection generation with `since` (full hash or
+    unique >=12-char prefix): unchanged documents are omitted and changed
+    ones carry only their changed sections. `since` cannot combine with
+    `assume_known`, and neither combines with `outline`. If the CLI serves
+    the packet by falling back from a stale or corrupt projection to direct
+    Markdown, the fallback warning is surfaced under `diagnostics`.
+    """
+
+    arguments = ["context", document_id, project, "--depth", str(depth), "--json"]
+    if include_related:
+        arguments.append("--include-related")
+    if anchor is not None:
+        arguments.extend(["--anchor", anchor])
+    for item in include or []:
+        arguments.extend(["--include", item])
+    if outline:
+        arguments.append("--outline")
+    for item in assume_known or []:
+        arguments.extend(["--assume-known", item])
+    if since is not None:
+        arguments.extend(["--since", since])
+    return _json_tool(arguments)
+
+
+def read_document(
+    project: str,
+    document_id: str,
+    anchor: str | None = None,
+    navigation: bool = False,
+    list_sections: bool = False,
+) -> str:
+    """Read a Markdown document, navigation prefix or section by stable ID.
+
+    Read-only. `anchor` returns one section; `navigation` returns the
+    navigation prefix; `list_sections` returns tab-separated section rows
+    (`anchor`, `Hn`, `start:end`, `title`) in document order.
+    """
+
+    arguments = ["read", document_id, project]
+    if anchor is not None:
+        arguments.extend(["--anchor", anchor])
+    elif navigation:
+        arguments.append("--navigation")
+    elif list_sections:
+        arguments.append("--list")
+    return _run_cli(arguments)
+
+
+def read_document_packet(
+    project: str,
+    document_id: str,
+    anchor: str | None = None,
+    navigation: bool = False,
+    list_sections: bool = False,
+) -> dict:
+    """Read a document and return text plus successful-exit diagnostics.
+
+    This is the structured counterpart to `read_document`: it preserves the
+    exact CLI stdout under `text` and adds `diagnostics` when the CLI emitted
+    non-fatal stderr, such as projection fallback warnings.
+    """
+
+    arguments = ["read", document_id, project]
+    if anchor is not None:
+        arguments.extend(["--anchor", anchor])
+    elif navigation:
+        arguments.append("--navigation")
+    elif list_sections:
+        arguments.append("--list")
+    return _text_packet(arguments)
+
+
+def dependencies(
+    project: str, document_id: str, reverse: bool = False
+) -> list[dict]:
+    """List forward (or, with `reverse`, incoming) semantic dependency edges.
+
+    Read-only. Fails closed with an error instead of returning a silently
+    incomplete graph when metadata errors affect the answer.
+    """
+
+    arguments = ["dependencies", document_id, project]
+    if reverse:
+        arguments.append("--reverse")
+    rows: list[dict] = []
+    for line in _run_cli(arguments).splitlines():
+        relation, peer_id, expected = line.split("\t")
+        rows.append(
+            {
+                "relation": relation,
+                "peer_id": peer_id,
+                "expected_revision": None if expected == "-" else int(expected),
+            }
+        )
+    return rows
+
+
+def impact(project: str, document_id: str) -> str:
+    """Report reverse metadata impact for a document as a Markdown table.
+
+    Read-only. Distinguishes semantic, related-navigation, freshness-pin and
+    configured historical-snapshot relations.
+    """
+
+    return _run_cli(["impact", document_id, project])
+
+
+def impact_packet(project: str, document_id: str) -> dict:
+    """Report reverse metadata impact with text plus non-fatal diagnostics."""
+
+    return _text_packet(["impact", document_id, project])
+
+
+def agent_instructions(project: str) -> dict:
+    """Return the deterministic agent-rules snippet for AGENTS.md/CLAUDE.md.
+
+    Read-only: derived from the project's `.docsystem.toml` plus the
+    engine's stable agent contract, never from parsing
+    `docs/setup-guide.md`, so the pasted snippet cannot drift from the
+    project's actually configured areas and identifiers. Works even when
+    the documentation root itself is missing, since only configuration is
+    read.
+    """
+
+    return _json_tool(["agent-instructions", project, "--json"])
+
+
+_TOOLS = (
+    readiness,
+    catalog,
+    migration_report,
+    changes,
+    context,
+    read_document,
+    read_document_packet,
+    dependencies,
+    impact,
+    impact_packet,
+    agent_instructions,
+)
+
+
+def build_server():
+    """Create the FastMCP server with every read-only tool registered."""
+
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as error:
+        raise RuntimeError(
+            "the MCP adapter requires the optional 'mcp' dependency; "
+            "install it with: pip install 'documentation-engine[mcp]'"
+        ) from error
+    server = FastMCP("docsystem")
+    for tool in _TOOLS:
+        server.tool()(tool)
+    return server
+
+
+def main() -> int:
+    build_server().run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())