ai-docs-toolkit 0.1.0__py3-none-any.whl

ai_docs_toolkit/context/__init__.py

@@ -0,0 +1,13 @@
+from ai_docs_toolkit.context.markdown_output import (
+    ContextBuildResult,
+    context_project,
+    format_context_json,
+    format_context_markdown,
+)
+
+__all__ = [
+    "ContextBuildResult",
+    "context_project",
+    "format_context_json",
+    "format_context_markdown",
+]

ai_docs_toolkit/context/markdown_output.py

@@ -0,0 +1,470 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from ai_docs_toolkit.core import (
+    ContextSelectionResult,
+    DocumentRegistry,
+    RegistryDocument,
+    ToolkitConfig,
+    build_document_graph,
+    build_document_registry,
+    load_project_config,
+    parse_markdown_text,
+    registry_document_from_parsed,
+    scan_markdown_files,
+    select_context_by_changed_ids,
+    select_context_by_feature,
+    select_context_by_ids,
+    select_context_by_module,
+)
+from ai_docs_toolkit.core.changed_files import (
+    ChangedFileIssue,
+    read_git_changed_files,
+    resolve_changed_document_sources,
+)
+from ai_docs_toolkit.core.config import context_settings_error
+from ai_docs_toolkit.core.context import ContextPolicy
+from ai_docs_toolkit.validation import ValidationMessage
+
+RULE_CHANGED_FILE_NOT_DOCUMENT = "document.context.changed_file_not_document"
+RULE_CHANGED_FILE_OUTSIDE_DOCS = "document.context.changed_file_outside_docs"
+RULE_GIT_CHANGED_FILES_UNAVAILABLE = "document.context.git_changed_files_unavailable"
+
+
+@dataclass(frozen=True)
+class ContextBuildResult:
+    exit_code: int
+    selection: ContextSelectionResult | None
+    registry: DocumentRegistry | None = None
+    warnings: tuple[ValidationMessage, ...] = ()
+    errors: tuple[ValidationMessage, ...] = ()
+    snapshot: dict | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+@dataclass(frozen=True)
+class _ProjectContext:
+    root: Path
+    config: ToolkitConfig
+    documents: tuple[RegistryDocument, ...]
+    errors: tuple[ValidationMessage, ...]
+    file_hashes: dict[str, str]
+    config_hash: str
+
+
+def context_project(
+    *,
+    mode: str,
+    value: str,
+    project_root: str | Path = ".",
+    history: str | None = None,
+    body_budget_bytes: int | None = None,
+    max_depth: int | None = None,
+) -> ContextBuildResult:
+    context_result = _load_project_context(project_root)
+    if isinstance(context_result, ContextBuildResult):
+        return context_result
+    config = context_result.config
+    effective_history = history if history is not None else config.context.history
+    effective_budget = (
+        body_budget_bytes
+        if body_budget_bytes is not None
+        else config.context.body_budget_bytes
+    )
+    effective_depth = max_depth if max_depth is not None else config.context.max_depth
+    if error := context_settings_error(
+        effective_history, effective_budget, effective_depth
+    ):
+        return ContextBuildResult(
+            exit_code=2,
+            selection=None,
+            errors=(
+                ValidationMessage(rule_id="invalid_context_options", message=error),
+            ),
+        )
+    policy = ContextPolicy(
+        effective_history,
+        config.work_history.archive_root,
+        effective_budget or None,
+        effective_depth,
+    )
+    registry = build_document_registry(context_result.documents)
+    errors = [*context_result.errors, *_registry_errors(registry)]
+    warnings = []
+    graph = build_document_graph(registry, project_root=context_result.root)
+    if mode == "id":
+        selection = select_context_by_ids(graph, registry, [value], policy=policy)
+    elif mode == "module":
+        selection = select_context_by_module(graph, registry, value, policy=policy)
+    elif mode == "feature":
+        selection = select_context_by_feature(graph, registry, value, policy=policy)
+    elif mode == "changed":
+        changed = _git_changed_files(context_result.root)
+        source_result = resolve_changed_document_sources(
+            changed.changed_files,
+            config=config,
+            registry=registry,
+            root=context_result.root,
+            outside_docs_rule_id=RULE_CHANGED_FILE_OUTSIDE_DOCS,
+            not_document_rule_id=RULE_CHANGED_FILE_NOT_DOCUMENT,
+        )
+        errors.extend(_changed_file_errors(changed.issues))
+        warnings.extend(
+            _changed_file_warnings((*changed.issues, *source_result.issues))
+        )
+        selection = select_context_by_changed_ids(
+            graph,
+            registry,
+            {
+                id: source_result.changed_files_by_id[id]
+                for id in source_result.source_ids
+            },
+            policy=policy,
+        )
+    else:
+        raise ValueError(f"Unsupported context mode: {mode}")
+    errors.extend(_selection_errors(selection))
+    warnings.extend(_selection_warnings(selection))
+    fingerprint_inputs = {
+        "files": context_result.file_hashes,
+        "config": context_result.config_hash,
+        "mode": mode,
+        "value": value,
+        "history": policy.history,
+        "body_budget_bytes": policy.body_budget_bytes,
+        "max_depth": policy.max_depth,
+        "sources": [asdict(s) for s in selection.sources],
+    }
+    snapshot = {
+        "fingerprint": hashlib.sha256(
+            json.dumps(fingerprint_inputs, sort_keys=True, ensure_ascii=False).encode()
+        ).hexdigest(),
+        "files": {
+            d.path: context_result.file_hashes[d.path] for d in selection.documents
+        },
+    }
+    return ContextBuildResult(
+        exit_code=0 if not errors else 1,
+        selection=selection,
+        registry=registry,
+        warnings=tuple(warnings),
+        errors=tuple(errors),
+        snapshot=snapshot,
+    )
+
+
+def format_context_markdown(result: ContextBuildResult) -> str:
+    lines: list[str] = ["# AI Docs Context Bundle", ""]
+    lines.append("Status: completed" if result.exit_code == 0 else "Status: failed")
+
+    selection = result.selection
+    sources = selection.sources if selection is not None else ()
+    documents = selection.documents if selection is not None else ()
+    lines.append(f"Sources: {len(sources)}")
+    lines.append(f"Documents: {len(documents)}")
+
+    if selection is not None:
+        budget = selection.policy.body_budget_bytes
+        lines.extend(
+            [
+                f"History: {selection.policy.history}",
+                f"Depth: {selection.policy.max_depth}; boundary documents: {selection.boundary_count}",
+                f"Body budget (UTF-8 bytes): {budget if budget else 'unlimited'} (soft)",
+                f"Selected body bytes: {selection.body_bytes}; excess: {selection.excess_bytes}",
+                "Coverage: explicit graph only; read applicable agent/local instructions separately.",
+            ]
+        )
+        if selection.excluded:
+            lines.extend(["", "## Excluded"])
+            lines.extend(
+                f"- {e.document_id} ({e.path}): {', '.join(e.reasons)}"
+                for e in selection.excluded
+            )
+        if selection.historical:
+            lines.extend(["", "## Historical Documents"])
+            lines.extend(
+                f"- {e.document_id}: {', '.join(e.reasons)}"
+                for e in selection.historical
+            )
+
+    if sources:
+        lines.append("")
+        lines.append("## Sources")
+        for source in sources:
+            changed = (
+                f" changed_file={source.changed_file}" if source.changed_file else ""
+            )
+            lines.append(
+                f"- {source.document_id} ({source.type}) {source.path} "
+                f"source={source.source}{changed}"
+            )
+
+    if result.warnings:
+        lines.append("")
+        lines.append("## Warnings")
+        for warning in result.warnings:
+            lines.append(f"- {_message_line(warning)}")
+
+    if result.errors:
+        lines.append("")
+        lines.append("## Errors")
+        for error in result.errors:
+            lines.append(f"- {_message_line(error)}")
+
+    if documents:
+        lines.append("")
+        lines.append("## Documents")
+        for document in documents:
+            lines.append("")
+            lines.append(f"### {document.document_id}")
+            lines.append("")
+            lines.append("```yaml")
+            lines.append(f"type: {document.type}")
+            lines.append(f"path: {document.path}")
+            lines.append(f"group: {document.group}")
+            lines.append(f"distance: {document.distance}")
+            lines.append(f"priority: {document.priority}")
+            lines.append(f"context_role: {document.context_role}")
+            lines.append("reasons:")
+            for reason in document.reasons:
+                path_hint = f" Path {' -> '.join(reason.path)}." if reason.path else ""
+                lines.append(f"  - {reason.message}{path_hint}")
+            lines.append("```")
+            body = _document_body(result.registry, document.document_id)
+            if body:
+                lines.append("")
+                lines.extend(body.splitlines())
+
+    return "\n".join(lines)
+
+
+def format_context_json(result: ContextBuildResult) -> str:
+    selection = result.selection
+    payload = {
+        "sources": [asdict(source) for source in selection.sources]
+        if selection
+        else [],
+        "documents": [_document_payload(document) for document in selection.documents]
+        if selection
+        else [],
+        "warnings": [_message_payload(message) for message in result.warnings],
+    }
+    if selection is not None:
+        payload.update(
+            {
+                "selection": {
+                    "history": selection.policy.history,
+                    "max_depth": selection.policy.max_depth,
+                    "depth_limited": selection.boundary_count > 0,
+                    "boundary_count": selection.boundary_count,
+                    "body_budget_bytes": selection.policy.body_budget_bytes,
+                    "body_bytes": selection.body_bytes,
+                    "excess_bytes": selection.excess_bytes,
+                    "protected_ids": list(selection.protected_ids),
+                    "candidate_count": selection.candidate_count,
+                    "coverage": "explicit_graph_only",
+                },
+                "excluded": [asdict(e) for e in selection.excluded],
+                "historical": [asdict(e) for e in selection.historical],
+                "gaps": [asdict(g) for g in selection.gaps],
+                "snapshot": result.snapshot,
+            }
+        )
+    if result.errors:
+        payload["errors"] = [_message_payload(message) for message in result.errors]
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True)
+
+
+def _load_project_context(
+    project_root: str | Path,
+) -> _ProjectContext | ContextBuildResult:
+    root = Path(project_root).resolve()
+    config_path = root / "ai-docs.config.yaml"
+    config_bytes = config_path.read_bytes() if config_path.exists() else b""
+    config_result = load_project_config(root)
+    if not config_result.ok or config_result.config is None:
+        return ContextBuildResult(
+            exit_code=2,
+            selection=None,
+            errors=tuple(
+                ValidationMessage(
+                    rule_id=error.code,
+                    message=error.message,
+                    path=error.path,
+                )
+                for error in config_result.errors
+            ),
+        )
+
+    if config_bytes != (config_path.read_bytes() if config_path.exists() else b""):
+        return ContextBuildResult(
+            exit_code=1,
+            selection=None,
+            errors=(
+                ValidationMessage(
+                    rule_id="document.context.snapshot_changed",
+                    message="Configuration changed during selection; rerun context.",
+                ),
+            ),
+        )
+    documents: list[RegistryDocument] = []
+    file_hashes = {}
+    errors: list[ValidationMessage] = []
+    for path in scan_markdown_files(config_result.config):
+        display_path = (
+            path.relative_to(root).as_posix()
+            if path.is_relative_to(root)
+            else str(path)
+        )
+        try:
+            data = path.read_bytes()
+            file_hashes[display_path] = hashlib.sha256(data).hexdigest()
+            text = data.decode("utf-8")
+        except (OSError, UnicodeError) as exc:
+            file_hashes[display_path] = "unreadable"
+            errors.append(
+                ValidationMessage(
+                    rule_id="document.context.read_failed",
+                    message=str(exc),
+                    path=str(path),
+                )
+            )
+            continue
+        parse_result = parse_markdown_text(text, path=str(path))
+        if parse_result.document is None:
+            errors.extend(
+                ValidationMessage(
+                    rule_id=f"frontmatter.{error.code}",
+                    message=error.message,
+                    path=error.path,
+                )
+                for error in parse_result.errors
+            )
+            continue
+
+        documents.append(registry_document_from_parsed(parse_result.document))
+
+    return _ProjectContext(
+        root=root,
+        config=config_result.config,
+        documents=tuple(documents),
+        errors=tuple(errors),
+        file_hashes=file_hashes,
+        config_hash=hashlib.sha256(config_bytes).hexdigest(),
+    )
+
+
+def _registry_errors(registry: DocumentRegistry) -> tuple[ValidationMessage, ...]:
+    return tuple(
+        ValidationMessage(
+            rule_id=issue.rule_id,
+            message=issue.message,
+            path=", ".join(str(path) for path in issue.paths),
+            document_id=issue.document_id,
+            severity=issue.severity,
+        )
+        for issue in registry.issues
+    )
+
+
+def _selection_errors(
+    selection: ContextSelectionResult,
+) -> tuple[ValidationMessage, ...]:
+    return tuple(
+        ValidationMessage(
+            rule_id=issue.rule_id,
+            message=issue.message,
+            document_id=issue.document_id,
+            severity=issue.severity,
+        )
+        for issue in selection.issues
+        if issue.severity == "error"
+    )
+
+
+def _selection_warnings(
+    selection: ContextSelectionResult,
+) -> tuple[ValidationMessage, ...]:
+    return tuple(
+        ValidationMessage(
+            rule_id=issue.rule_id,
+            message=issue.message,
+            document_id=issue.document_id,
+            severity=issue.severity,
+        )
+        for issue in selection.issues
+        if issue.severity != "error"
+    )
+
+
+def _changed_file_errors(
+    issues: tuple[ChangedFileIssue, ...],
+) -> tuple[ValidationMessage, ...]:
+    return tuple(
+        _changed_file_message(issue) for issue in issues if issue.severity == "error"
+    )
+
+
+def _changed_file_warnings(
+    issues: tuple[ChangedFileIssue, ...],
+) -> tuple[ValidationMessage, ...]:
+    return tuple(
+        _changed_file_message(issue) for issue in issues if issue.severity != "error"
+    )
+
+
+def _changed_file_message(issue: ChangedFileIssue) -> ValidationMessage:
+    return ValidationMessage(
+        rule_id=issue.rule_id,
+        message=issue.message,
+        path=issue.path,
+        document_id=issue.document_id,
+        severity=issue.severity,
+    )
+
+
+def _document_body(registry: DocumentRegistry | None, document_id: str) -> str:
+    if registry is None:
+        return ""
+    document = registry.get_by_id(document_id)
+    if document is None:
+        return ""
+    return document.body.strip()
+
+
+def _message_line(message: ValidationMessage) -> str:
+    path = f"{message.path} " if message.path else ""
+    document = f"[{message.document_id}] " if message.document_id else ""
+    return f"{path}{document}{message.rule_id}: {message.message}"
+
+
+def _document_payload(document: object) -> dict[str, object]:
+    payload = asdict(document)
+    for reason in payload["reasons"]:
+        if not reason["path"]:
+            reason.pop("path")
+    return payload
+
+
+def _message_payload(message: ValidationMessage) -> dict[str, str | None]:
+    return {
+        "path": message.path,
+        "document_id": message.document_id,
+        "rule_id": message.rule_id,
+        "severity": message.severity,
+        "message": message.message,
+    }
+
+
+def _git_changed_files(root: Path):
+    return read_git_changed_files(
+        root,
+        unavailable_rule_id=RULE_GIT_CHANGED_FILES_UNAVAILABLE,
+    )