diary-docs 0.1.0__py3-none-any.whl

diary/sync/engine.py

@@ -0,0 +1,404 @@
+"""Sync orchestrator — integrates git_utils, indexer, detector, merge, and protocol.
+
+The :func:`run_sync` function is the main entry point for the diary sync
+pipeline.  It ties together branch detection, re-indexing, change detection,
+AIMB conflict resolution, and report generation into a single callable API.
+
+Usage::
+
+    from diary.sync.engine import SyncConfig, run_sync
+
+    config = SyncConfig(workspace_path=Path("."))
+    result = run_sync(config)
+    if result.success:
+        print(result.report)
+    else:
+        for err in result.errors:
+            print(err)
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from diary.aimb.merge import (
+    MergeDecision,
+    decide_block_action,
+    generate_block_diff,
+)
+from diary.aimb.parser import parse_aimb_blocks
+from diary.git_utils import (
+    get_current_branch,
+    is_git_repo,
+    sanitize_branch_name,
+)
+from diary.indexer.indexer import run_index
+from diary.sync.detector import (
+    ChangeType,
+    classify_changes,
+    detect_code_changes,
+    detect_doc_changes,
+)
+from diary.sync.protocol import (
+    ChangeEntry,
+    ConflictEntry,
+    SyncReport,
+    SyncStats,
+    serialize_report,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SyncConfig:
+    """Configuration for a single sync run.
+
+    Parameters
+    ----------
+    workspace_path : Path
+        Root of the workspace / repository to sync.
+    dry_run : bool
+        If ``True``, report changes to stdout without modifying any files
+        (default ``False``).
+    force : bool
+        If ``True``, skip safety prompts (default ``False``).
+    branch_override : str | None
+        Explicit branch name to use instead of auto-detecting from git.
+    output_path : str | None
+        File path to write the serialised report to instead of stdout.
+    """
+
+    workspace_path: Path
+    dry_run: bool = False
+    force: bool = False
+    branch_override: str | None = None
+    output_path: str | None = None
+
+
+@dataclass
+class SyncResult:
+    """Result produced by a single call to :func:`run_sync`.
+
+    Parameters
+    ----------
+    success : bool
+        ``True`` when the sync completed without errors.
+    report : SyncReport | None
+        The generated sync report, or ``None`` if pre-flight checks failed.
+    errors : list[str]
+        Human-readable error / warning messages collected during the run.
+    """
+
+    success: bool
+    report: SyncReport | None = None
+    errors: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _git_show(workspace_path: Path, file_path: str) -> str:
+    """Return the committed content of *file_path* at HEAD.
+
+    Returns an empty string when the file is not tracked or on error.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "show", f"HEAD:{file_path}"],
+            capture_output=True,
+            text=True,
+            cwd=str(workspace_path),
+        )
+        if result.returncode == 0:
+            return result.stdout
+    except (FileNotFoundError, OSError):
+        pass
+    return ""
+
+
+def _resolve_branch(config: SyncConfig) -> tuple[str, list[str]]:
+    """Resolve the effective branch name.
+
+    Returns
+    -------
+    tuple[str, list[str]]
+        ``(branch_name, warnings)``
+    """
+    warnings: list[str] = []
+
+    if config.branch_override:
+        return config.branch_override, warnings
+
+    branch = get_current_branch(config.workspace_path)
+    if not branch:
+        warnings.append("Could not detect current branch — using 'unknown'")
+        return "unknown", warnings
+
+    if branch == "HEAD":
+        warnings.append(
+            "Detached HEAD state detected — using 'detached' for index isolation. "
+            "The knowledge database will be stored as knowledge-detached.db"
+        )
+        return "detached", warnings
+
+    return branch, warnings
+
+
+def _build_change_entries(classification: dict) -> list[ChangeEntry]:
+    """Convert classified :class:`~diary.sync.detector.DetectedChange` objects
+    into protocol :class:`~diary.sync.protocol.ChangeEntry` instances."""
+    entries: list[ChangeEntry] = []
+    for _type_name, changes in classification.get("by_type", {}).items():
+        for change in changes:
+            entries.append(
+                ChangeEntry(
+                    file_path=change.file_path,
+                    change_type=change.change_type.value,
+                    affected_docs=list(change.affected_aimb_blocks),
+                    confidence=change.confidence,
+                )
+            )
+    return entries
+
+
+def _resolve_conflicts(
+    workspace_path: Path,
+    doc_changes: list,
+) -> tuple[list[ConflictEntry], list[str]]:
+    """Detect merge conflicts for changed AIMB blocks.
+
+    For each documented change classified as ``AIMB_BLOCK_CHANGED``, compare
+    the current block hash (in the working tree) against the committed hash
+    (from git HEAD).  If they differ, the block was manually edited since the
+    last AI write, and we flag it as a conflict.
+
+    Returns
+    -------
+    tuple[list[ConflictEntry], list[str]]
+        ``(conflict_entries, errors)``
+    """
+    conflicts: list[ConflictEntry] = []
+    errors: list[str] = []
+
+    for change in doc_changes:
+        if change.change_type != ChangeType.AIMB_BLOCK_CHANGED:
+            continue
+
+        file_path = workspace_path / change.file_path
+        if not file_path.is_file():
+            continue
+
+        # Read current working-tree content
+        try:
+            current_content = file_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            errors.append(f"Cannot read {change.file_path}: {exc}")
+            continue
+
+        # Get committed version from git HEAD
+        committed_content = _git_show(workspace_path, change.file_path)
+        if not committed_content:
+            # File is new (not yet committed) — no conflict possible
+            continue
+
+        # Parse AIMB blocks from both versions
+        committed_blocks = parse_aimb_blocks(committed_content)
+        committed_hashes = {b.id: b.hash for b in committed_blocks}
+
+        current_blocks = parse_aimb_blocks(current_content)
+        current_by_id = {b.id: b for b in current_blocks}
+
+        for block_id in change.affected_aimb_blocks:
+            stored_hash = committed_hashes.get(block_id)
+            if stored_hash is None:
+                # Block didn't exist in committed version — can't conflict
+                continue
+
+            block = current_by_id.get(block_id)
+            if block is None:
+                # Block was removed from the working tree — skip
+                continue
+
+            decision = decide_block_action(block, stored_hash, current_content)
+            if decision == MergeDecision.REPLACE:
+                # Hashes match — no manual edit, safe to overwrite
+                continue
+            if decision == MergeDecision.SKIP:
+                # Block marked for removal — skip
+                continue
+
+            # FLAG_CONFLICT — build a diff preview between the two versions
+            committed_block = None
+            for cb in committed_blocks:
+                if cb.id == block_id:
+                    committed_block = cb
+                    break
+
+            diff_preview = ""
+            if committed_block is not None:
+                diff_preview = generate_block_diff(committed_block.content, block.content)
+
+            conflicts.append(
+                ConflictEntry(
+                    file_path=change.file_path,
+                    block_id=block_id,
+                    old_hash=stored_hash,
+                    current_hash=block.hash,
+                    diff_preview=diff_preview,
+                )
+            )
+
+    return conflicts, errors
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def run_sync(config: SyncConfig) -> SyncResult:
+    """Execute a full sync cycle.
+
+    Pipeline steps
+    --------------
+    1. **Pre-flight checks** — verify the workspace is a git repository.
+    2. **Branch detection** — resolve the current branch (detached HEAD is
+       handled gracefully and mapped to ``"detached"``).
+    3. **Re-indexing** — rebuild the per-branch knowledge index via
+       :func:`~diary.indexer.indexer.run_index`.
+    4. **Change detection** — scan for code changes and documentation changes
+       via :func:`~diary.sync.detector.detect_code_changes` and
+       :func:`~diary.sync.detector.detect_doc_changes`.
+    5. **Classification** — group and summarise all detected changes via
+       :func:`~diary.sync.detector.classify_changes`.
+    6. **AIMB merge decisions** — for each changed documentation block, call
+       :func:`~diary.aimb.merge.decide_block_action` to detect conflicts.
+    7. **Build report** — construct a :class:`~diary.sync.protocol.SyncReport`
+       with change entries, conflicts, and aggregate statistics.
+    8. **Output** — serialise the report to JSON and write it to stdout (or
+       to a file if ``config.output_path`` is set).
+       If ``config.dry_run`` is ``True``, no files are modified.
+
+    Parameters
+    ----------
+    config : SyncConfig
+        Sync configuration.
+
+    Returns
+    -------
+    SyncResult
+    """
+    errors: list[str] = []
+    start_time = time.monotonic()
+
+    # ── 1. Pre-flight checks ────────────────────────────────
+    if not is_git_repo(config.workspace_path):
+        msg = (
+            f"Not a git repository: {config.workspace_path}\n"
+            "Run ``git init`` to initialise a repository, or set "
+            "``workspace_path`` to a valid git workspace."
+        )
+        errors.append(msg)
+        logger.error(msg)
+        return SyncResult(success=False, errors=errors)
+
+    # ── 2. Branch detection ─────────────────────────────────
+    branch, branch_warnings = _resolve_branch(config)
+    errors.extend(branch_warnings)
+
+    for w in branch_warnings:
+        logger.warning(w)
+
+    sanitized = sanitize_branch_name(branch)
+
+    # ── 3. Re-indexing ──────────────────────────────────────
+    logger.info("Re-indexing workspace for branch '%s'", branch)
+    try:
+        db = run_index(config.workspace_path, branch_name=sanitized)
+    except Exception as exc:
+        msg = f"Indexing failed: {exc}"
+        errors.append(msg)
+        logger.error(msg)
+        return SyncResult(success=False, errors=errors)
+
+    # ── 4. Change detection ─────────────────────────────────
+    logger.info("Detecting code changes")
+    code_changes = detect_code_changes(config.workspace_path, db)
+
+    logger.info("Detecting documentation changes")
+    doc_changes = detect_doc_changes(config.workspace_path)
+
+    all_changes = code_changes + doc_changes
+
+    # ── 5. Classification ───────────────────────────────────
+    classification = classify_changes(all_changes)
+    logger.info("Sync classification: %s", classification.get("summary", "unknown"))
+
+    # ── 6. AIMB merge decisions ─────────────────────────────
+    conflict_entries, conflict_errors = _resolve_conflicts(
+        config.workspace_path,
+        doc_changes,
+    )
+    errors.extend(conflict_errors)
+
+    # ── 7. Build report ─────────────────────────────────────
+    row = db.conn.execute("SELECT COUNT(*) FROM files").fetchone()
+    files_scanned = row[0] if row else 0
+
+    duration_ms = int((time.monotonic() - start_time) * 1000)
+
+    change_entries = _build_change_entries(classification)
+
+    # Count unique doc files with detected changes
+    doc_paths: set[str] = set()
+    for change in doc_changes:
+        doc_paths.add(change.file_path)
+    docs_updated = len(doc_paths)
+
+    report = SyncReport(
+        branch=branch,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        changes=change_entries,
+        conflicts=conflict_entries,
+        stats=SyncStats(
+            files_scanned=files_scanned,
+            docs_updated=docs_updated,
+            conflicts=len(conflict_entries),
+            duration_ms=duration_ms,
+        ),
+    )
+
+    # ── 8. Output ───────────────────────────────────────────
+    serialized = serialize_report(report)
+
+    if config.output_path:
+        output = Path(config.output_path)
+        try:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(serialized, encoding="utf-8")
+            logger.info("Report written to %s", output)
+        except OSError as exc:
+            msg = f"Cannot write report to {output}: {exc}"
+            errors.append(msg)
+            logger.error(msg)
+    else:
+        print(serialized)
+
+    # Clean up database handle
+    db.close()
+
+    success = len(errors) == 0
+    return SyncResult(success=success, report=report, errors=errors)

diary/sync/protocol.py

@@ -0,0 +1,176 @@
+"""JSON protocol schema for AI agent communication during diary sync.
+
+This module defines the data structures and serialization helpers
+that format sync results into JSON consumed by the ``/diary-sync``
+AI agent command.
+"""
+
+import dataclasses
+import json
+from dataclasses import dataclass, field
+from typing import Any, get_type_hints
+
+
+# ── Data classes ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class ChangeEntry:
+    """A single code change detected during the sync scan."""
+
+    file_path: str
+    change_type: str  # e.g. "modified", "added", "deleted"
+    affected_docs: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+
+
+@dataclass
+class ConflictEntry:
+    """A documentation block that was edited on both sides since last sync."""
+
+    file_path: str
+    block_id: str
+    old_hash: str
+    current_hash: str
+    diff_preview: str
+
+
+@dataclass
+class SyncStats:
+    """Aggregate counters for a single sync run."""
+
+    files_scanned: int = 0
+    docs_updated: int = 0
+    conflicts: int = 0
+    duration_ms: int = 0
+
+
+@dataclass
+class SyncReport:
+    """Top-level report produced after a sync scan completes."""
+
+    branch: str
+    timestamp: str  # ISO-8601
+    changes: list[ChangeEntry] = field(default_factory=list)
+    conflicts: list[ConflictEntry] = field(default_factory=list)
+    stats: SyncStats = field(default_factory=SyncStats)
+
+
+# ── Serialization ───────────────────────────────────────────────────────────
+
+
+def _from_dict(cls: type[Any], data: dict[str, Any]) -> Any:
+    """Recursively build a dataclass (and nested dataclasses) from *data*."""
+    if not dataclasses.is_dataclass(cls):
+        return data
+
+    field_types = {f.name: f.type for f in dataclasses.fields(cls)}
+    kwargs: dict[str, Any] = {}
+
+    for fname, ftype in field_types.items():
+        if fname not in data:
+            continue
+        raw = data[fname]
+
+        # list[X] – try to unwrap the origin
+        origin = getattr(ftype, "__origin__", None)
+        if origin is list:
+            args = getattr(ftype, "__args__", (Any,))
+            elem_type = args[0] if args else Any
+            if dataclasses.is_dataclass(elem_type):
+                kwargs[fname] = [_from_dict(elem_type, item) for item in raw]
+            elif isinstance(raw, list):
+                kwargs[fname] = raw
+            else:
+                kwargs[fname] = raw
+        elif dataclasses.is_dataclass(ftype):
+            kwargs[fname] = _from_dict(ftype, raw)
+        else:
+            kwargs[fname] = raw
+
+    return cls(**kwargs)
+
+
+def serialize_report(report: SyncReport) -> str:
+    """Serialize *report* to a pretty-printed JSON string."""
+    return json.dumps(dataclasses.asdict(report), indent=2)
+
+
+def parse_report(json_str: str) -> SyncReport:
+    """Deserialize a JSON string back into a ``SyncReport`` instance."""
+    raw: dict[str, Any] = json.loads(json_str)
+    return _from_dict(SyncReport, raw)
+
+
+# ── AI prompt generation ────────────────────────────────────────────────────
+
+
+def get_ai_update_prompt(report: SyncReport) -> str:
+    """Generate a natural-language instruction string for an AI agent.
+
+    The prompt describes every change and conflict recorded in *report* so
+    that an AI agent can understand which documentation blocks need updating
+    and which ones require manual conflict resolution.
+    """
+    lines: list[str] = []
+    lines.append("## DIARY Sync Update Instructions")
+    lines.append("")
+    lines.append(f"**Branch:** {report.branch}")
+    lines.append(f"**Timestamp:** {report.timestamp}")
+    lines.append(f"**Files scanned:** {report.stats.files_scanned}")
+    lines.append(f"**Docs updated:** {report.stats.docs_updated}")
+    lines.append(f"**Duration:** {report.stats.duration_ms} ms")
+    lines.append("")
+
+    if report.changes:
+        lines.append("### Documentation Updates Required")
+        lines.append("")
+        lines.append(
+            "The following code changes need corresponding documentation updates:"
+        )
+        lines.append("")
+        for ch in report.changes:
+            lines.append(f"- **{ch.file_path}** ({ch.change_type})")
+            if ch.affected_docs:
+                lines.append(f"  - Affected docs: {', '.join(ch.affected_docs)}")
+            lines.append(f"  - Confidence: {ch.confidence:.0%}")
+            lines.append("")
+    else:
+        lines.append("*No documentation updates required.*")
+        lines.append("")
+
+    if report.conflicts:
+        lines.append("### Conflicts Detected (Manual Resolution Required)")
+        lines.append("")
+        lines.append(
+            "The following documentation blocks have been edited on both "
+            "sides since the last sync and need manual review:"
+        )
+        lines.append("")
+        for cf in report.conflicts:
+            lines.append(f"- **{cf.file_path}** — block `{cf.block_id}`")
+            lines.append(f"  - Old hash: `{cf.old_hash}`")
+            lines.append(f"  - Current hash: `{cf.current_hash}`")
+            lines.append(f"  - Diff preview: {cf.diff_preview}")
+            lines.append("")
+    else:
+        lines.append("*No conflicts detected.*")
+        lines.append("")
+
+    lines.append("### Action Items")
+    lines.append("")
+    if report.changes:
+        lines.append(
+            "1. For each change listed above, update the corresponding "
+            "documentation block to reflect the new code."
+        )
+    if report.conflicts:
+        lines.append(
+            "2. For each conflict, manually review the diff preview and "
+            "decide which version to keep (or merge both)."
+        )
+    if not report.changes and not report.conflicts:
+        lines.append("No action required — everything is up to date.")
+    lines.append("")
+
+    return "\n".join(lines)

diary/templates.py

@@ -0,0 +1,102 @@
+from datetime import date
+from pathlib import Path
+
+
+def aimb_wrap_body(content: str, filename: str) -> str:
+    """Wrap body content (after frontmatter) in an AI-managed block.
+
+    Args:
+        content: Full file content including frontmatter.
+        filename: Filename (e.g. ``index.md``) — the stem becomes the AIMB id.
+
+    Returns:
+        Content with an ``<!-- ai-managed … -->`` wrapper around everything
+        after the first YAML frontmatter block.
+    """
+    today = date.today().isoformat()
+    aimb_id = Path(filename).stem
+    opening = f'<!-- ai-managed id="{aimb_id}" hash="init" updated="{today}" -->'
+    closing = "<!-- /ai-managed -->"
+
+    if content.startswith("---"):
+        parts = content.split("---", 2)
+        if len(parts) == 3:
+            _, front, body = parts
+            body = body.strip("\n")
+            return f"---{front}---\n\n{opening}\n{body}\n\n{closing}\n"
+    return f"{opening}\n{content}\n\n{closing}\n"
+
+
+MKDOCS_TEMPLATE = """\
+site_name: {project_name}
+site_description: Technical documentation and knowledge base for {project_name}
+
+nav:
+  - Pendahuluan:
+    - Beranda: index.md
+    - Tujuan: objectives.md
+  - Panduan Umum:
+    - Panduan Menulis Docs: structure/index.md
+  - Technical Documentation:
+    - Overview: techdocs/index.md
+    - Arsitektur: techdocs/architecture.md
+    - API Contracts: techdocs/api-contracts.md
+    - Deployment Flow: techdocs/deployment.md
+    - ADR Log: techdocs/adr.md
+    - Development Guide: techdocs/development-guide.md
+  - Product Documentation:
+    - Overview: product/index.md
+    - User Guide: product/user-guide.md
+    - Modules: product/modules.md
+  - Ops & Governance:
+    - Overview: ops-governance/index.md
+    - Runbooks: ops-governance/runbooks.md
+    - Security: ops-governance/security.md
+  - Knowledge Base:
+    - Overview: knowledge-base/index.md
+    - FAQ: knowledge-base/faq.md
+    - Troubleshooting: knowledge-base/troubleshooting.md
+
+plugins:
+  - techdocs-core
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - tables
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+"""
+
+
+CATALOG_TEMPLATE = """\
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: {project_name}
+  title: {project_title}
+  description: Documentation site for {project_name}
+  annotations:
+    backstage.io/techdocs-ref: dir:.
+    gitlab.com/project-id: '0'
+    gitlab.com/instance: gitlab.example.com
+    gitlab.com/project-slug: group/{project_name}
+  tags: []
+spec:
+  type: documentation
+  lifecycle: production
+  owner: unknown
+"""