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

ai_docs_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""AI Docs Toolkit package baseline."""
+
+__version__ = "0.1.0b1"

ai_docs_toolkit/__main__.py

@@ -0,0 +1,4 @@
+from ai_docs_toolkit.cli import main
+
+
+raise SystemExit(main())

ai_docs_toolkit/cli/__init__.py

@@ -0,0 +1,232 @@
+from ai_docs_toolkit import __version__
+from ai_docs_toolkit.context import (
+    context_project,
+    format_context_json,
+    format_context_markdown,
+)
+from ai_docs_toolkit.graph import GraphFilters, format_graph_json, graph_project
+from ai_docs_toolkit.impact import (
+    format_impact_human,
+    format_impact_json,
+    impact_changed_project,
+    impact_project,
+)
+from ai_docs_toolkit.validation import (
+    format_human_validation_result,
+    format_json_validation_result,
+    validate_project_human,
+)
+
+
+def _help_text() -> str:
+    return "\n".join(
+        [
+            f"ai-docs {__version__}",
+            "",
+            "Usage:",
+            "  ai-docs --help",
+            "  ai-docs --version",
+            "  ai-docs validate",
+            "  ai-docs validate --json",
+            "  ai-docs graph --format json [--type TYPE] [--module MODULE] [--id ID]",
+            "  ai-docs impact (--id ID | --changed) [--format json]",
+            "  ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json]",
+        ]
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv) if argv is not None else None
+
+    if args is None:
+        import sys
+
+        args = sys.argv[1:]
+
+    if not args or "--help" in args or "-h" in args:
+        print(_help_text())
+        return 0
+
+    if "--version" in args or "-V" in args:
+        print(__version__)
+        return 0
+
+    if args == ["validate"]:
+        result = validate_project_human(".")
+        print(format_human_validation_result(result))
+        return result.exit_code
+
+    if args == ["validate", "--json"] or args == ["--json", "validate"]:
+        result = validate_project_human(".")
+        print(format_json_validation_result(result))
+        return result.exit_code
+
+    graph_filters = _parse_graph_args(args)
+    if graph_filters is not None:
+        result = graph_project(".", filters=graph_filters)
+        print(format_graph_json(result))
+        return result.exit_code
+
+    impact_args = _parse_impact_args(args)
+    if impact_args is not None:
+        impact_mode, impact_source_ids, impact_format = impact_args
+        result = (
+            impact_changed_project(".")
+            if impact_mode == "changed"
+            else impact_project(impact_source_ids, ".")
+        )
+        print(
+            format_impact_json(result)
+            if impact_format == "json"
+            else format_impact_human(result)
+        )
+        return result.exit_code
+
+    context_args = _parse_context_args(args)
+    if context_args is not None:
+        context_mode, context_value, context_format = context_args
+        result = context_project(mode=context_mode, value=context_value, project_root=".")
+        print(
+            format_context_json(result)
+            if context_format == "json"
+            else format_context_markdown(result)
+        )
+        return result.exit_code
+
+    if args and args[0] == "graph":
+        import sys
+
+        print("Usage: ai-docs graph --format json", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "impact":
+        import sys
+
+        print("Usage: ai-docs impact (--id ID | --changed) [--format json]", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "context":
+        import sys
+
+        print(
+            "Usage: ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    import sys
+
+    print(f"Unknown command or option: {' '.join(args)}", file=sys.stderr)
+    print("Run `ai-docs --help` for usage.", file=sys.stderr)
+    return 3
+
+
+def _parse_graph_args(args: list[str]) -> GraphFilters | None:
+    if not args or args[0] != "graph":
+        return None
+
+    values = args[1:]
+    if len(values) < 2 or values[:2] != ["--format", "json"]:
+        return None
+
+    document_type: str | None = None
+    module: str | None = None
+    document_id: str | None = None
+    index = 2
+    while index < len(values):
+        option = values[index]
+        if index + 1 >= len(values):
+            return None
+
+        value = values[index + 1]
+        if option == "--type":
+            document_type = value
+        elif option == "--module":
+            module = value
+        elif option == "--id":
+            document_id = value
+        else:
+            return None
+        index += 2
+
+    return GraphFilters(
+        document_type=document_type,
+        module=module,
+        document_id=document_id,
+    )
+
+
+def _parse_impact_args(args: list[str]) -> tuple[str, tuple[str, ...], str] | None:
+    if not args or args[0] != "impact":
+        return None
+
+    values = args[1:]
+    if len(values) not in (1, 2, 3, 4):
+        return None
+
+    if len(values) == 2 and values[0] == "--id":
+        return ("id", (values[1],), "human")
+
+    if len(values) == 4 and values[0] == "--id" and values[2:] == ["--format", "json"]:
+        return ("id", (values[1],), "json")
+
+    if len(values) == 4 and values[:2] == ["--format", "json"] and values[2] == "--id":
+        return ("id", (values[3],), "json")
+
+    if values == ["--changed", "--format", "json"]:
+        return ("changed", (), "json")
+
+    if values == ["--format", "json", "--changed"]:
+        return ("changed", (), "json")
+
+    if values == ["--changed"]:
+        return ("changed", (), "human")
+
+    return None
+
+
+def _parse_context_args(args: list[str]) -> tuple[str, str, str] | None:
+    if not args or args[0] != "context":
+        return None
+
+    values = args[1:]
+    if len(values) not in (1, 2, 3, 4):
+        return None
+
+    if values == ["--changed"]:
+        return ("changed", "", "markdown")
+
+    if values == ["--changed", "--format", "json"]:
+        return ("changed", "", "json")
+
+    if values == ["--format", "json", "--changed"]:
+        return ("changed", "", "json")
+
+    if len(values) == 2:
+        option, value = values
+        mode = _context_mode(option)
+        if mode is not None and value:
+            return (mode, value, "markdown")
+        return None
+
+    if values[2:] == ["--format", "json"]:
+        mode = _context_mode(values[0])
+        if mode is not None and values[1]:
+            return (mode, values[1], "json")
+
+    if values[:2] == ["--format", "json"]:
+        mode = _context_mode(values[2])
+        if mode is not None and values[3]:
+            return (mode, values[3], "json")
+
+    return None
+
+
+def _context_mode(option: str) -> str | None:
+    if option == "--id":
+        return "id"
+    if option == "--module":
+        return "module"
+    if option == "--feature":
+        return "feature"
+    return None

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,325 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from dataclasses import dataclass
+from pathlib import Path
+
+from ai_docs_toolkit.core.changed_files import (
+    ChangedFileIssue,
+    read_git_changed_files,
+    resolve_changed_document_sources,
+)
+from ai_docs_toolkit.core import (
+    ContextSelectionResult,
+    DocumentRegistry,
+    RegistryDocument,
+    ToolkitConfig,
+    build_document_graph,
+    build_document_registry,
+    load_project_config,
+    parse_markdown_file,
+    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.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, ...] = ()
+
+    @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, ...]
+
+
+def context_project(
+    *,
+    mode: str,
+    value: str,
+    project_root: str | Path = ".",
+) -> ContextBuildResult:
+    context_result = _load_project_context(project_root)
+    if isinstance(context_result, ContextBuildResult):
+        return context_result
+
+    registry = build_document_registry(context_result.documents)
+    errors = [*context_result.errors, *_registry_errors(registry)]
+    graph = build_document_graph(registry, project_root=context_result.root)
+
+    if mode == "id":
+        selection = select_context_by_ids(graph, registry, [value])
+    elif mode == "module":
+        selection = select_context_by_module(graph, registry, value)
+    elif mode == "feature":
+        selection = select_context_by_feature(graph, registry, value)
+    elif mode == "changed":
+        changed_result = _git_changed_files(context_result.root)
+        errors.extend(_changed_file_errors(changed_result.issues))
+        source_result = resolve_changed_document_sources(
+            changed_result.changed_files,
+            config=context_result.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,
+        )
+        source_ids = source_result.source_ids
+        changed_files_by_id = source_result.changed_files_by_id
+        warnings = [*_changed_file_warnings((*changed_result.issues, *source_result.issues))]
+        selection = select_context_by_changed_ids(
+            graph,
+            registry,
+            {document_id: changed_files_by_id[document_id] for document_id in source_ids},
+        )
+        errors.extend(_selection_errors(selection))
+        warnings.extend(_selection_warnings(selection))
+        return ContextBuildResult(
+            exit_code=0 if not errors else 1,
+            selection=selection,
+            registry=registry,
+            warnings=tuple(warnings),
+            errors=tuple(errors),
+        )
+    else:
+        raise ValueError(f"Unsupported context mode: {mode}")
+
+    errors.extend(_selection_errors(selection))
+    warnings = _selection_warnings(selection)
+    return ContextBuildResult(
+        exit_code=0 if not errors else 1,
+        selection=selection,
+        registry=registry,
+        warnings=warnings,
+        errors=tuple(errors),
+    )
+
+
+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 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:
+                lines.append(f"  - {reason.message}")
+            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 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_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
+            ),
+        )
+
+    documents: list[RegistryDocument] = []
+    errors: list[ValidationMessage] = []
+    for path in scan_markdown_files(config_result.config):
+        parse_result = parse_markdown_file(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),
+    )
+
+
+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)
+    payload["reasons"] = [asdict(reason) for reason in document.reasons]
+    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,
+    )