diary-docs 0.1.0__py3-none-any.whl

diary/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

diary/__main__.py

@@ -0,0 +1,3 @@
+from diary.cli import main
+
+main()

diary/aimb/__init__.py

@@ -0,0 +1,48 @@
+"""AIMB — AI Managed Block parser, hasher, and merge for markdown files."""
+
+from .hasher import (
+    compute_block_hash,
+    verify_block_hash,
+    hash_all_blocks,
+    get_stored_hashes,
+    find_changed_blocks,
+)
+from .merge import (
+    ConflictInfo,
+    MergeDecision,
+    apply_replace,
+    decide_block_action,
+    format_conflict_report,
+    generate_block_diff,
+)
+from .parser import (
+    AIMBBlock,
+    parse_aimb_blocks,
+    parse_frontmatter,
+    extract_manual_blocks,
+    has_aimb_blocks,
+    get_block_by_id,
+)
+
+__all__ = [
+    # parser
+    "AIMBBlock",
+    "parse_aimb_blocks",
+    "parse_frontmatter",
+    "extract_manual_blocks",
+    "has_aimb_blocks",
+    "get_block_by_id",
+    # hasher
+    "compute_block_hash",
+    "verify_block_hash",
+    "hash_all_blocks",
+    "get_stored_hashes",
+    "find_changed_blocks",
+    # merge
+    "MergeDecision",
+    "ConflictInfo",
+    "decide_block_action",
+    "generate_block_diff",
+    "format_conflict_report",
+    "apply_replace",
+]

diary/aimb/hasher.py

@@ -0,0 +1,157 @@
+"""AIMB block hasher — SHA256 computation and integrity checking.
+
+Functions
+---------
+compute_block_hash
+    SHA256 hex digest of block content.
+verify_block_hash
+    Compare computed hash against an expected value.
+hash_all_blocks
+    Compute hashes for every AIMB block in markdown content.
+get_stored_hashes
+    Extract the hashes stored in AIMB metadata tags.
+find_changed_blocks
+    Detect blocks whose stored hash differs from the current computed hash.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from .parser import parse_aimb_blocks
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────
+
+
+def _sha256(content: str) -> str:
+    """Return hex-encoded SHA-256 digest of *content*."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+
+def compute_block_hash(content: str) -> str:
+    """Return the SHA-256 hex digest of *content*.
+
+    Parameters
+    ----------
+    content : str
+        The raw text content of an AIMB block (text between the opening
+        ``<!-- ai-managed ... -->`` and closing ``<!-- /ai-managed -->``
+        tags).
+
+    Returns
+    -------
+    str
+        64-character hex-encoded SHA-256 digest.
+
+    Examples
+    --------
+    >>> compute_block_hash("test")
+    "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+    """
+    return _sha256(content)
+
+
+def verify_block_hash(content: str, expected_hash: str) -> bool:
+    """Verify that *content* hashes to *expected_hash*.
+
+    Parameters
+    ----------
+    content : str
+        Raw block content to hash.
+    expected_hash : str
+        Previously recorded hash to compare against.
+
+    Returns
+    -------
+    bool
+        ``True`` if the computed hash matches *expected_hash*.
+    """
+    return compute_block_hash(content) == expected_hash
+
+
+def hash_all_blocks(content: str) -> dict[str, str]:
+    """Compute the hash for every AIMB block in *content*.
+
+    Hashes only the **content** between the opening and closing tags
+    (not the tags themselves).
+
+    Parameters
+    ----------
+    content : str
+        Full markdown content with AIMB blocks.
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of ``{block_id: hash}`` for every AIMB block found.
+        Empty dict if no AIMB blocks exist.
+    """
+    blocks = parse_aimb_blocks(content)
+    return {block.id: compute_block_hash(block.content) for block in blocks}
+
+
+def get_stored_hashes(content: str) -> dict[str, str]:
+    """Extract the hashes stored in AIMB block metadata tags.
+
+    These are the ``hash="..."`` values written into each
+    ``<!-- ai-managed ... -->`` opening tag.
+
+    Parameters
+    ----------
+    content : str
+        Full markdown content with AIMB blocks.
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of ``{block_id: stored_hash}``.
+        Empty dict if no AIMB blocks exist.
+    """
+    blocks = parse_aimb_blocks(content)
+    return {block.id: block.hash for block in blocks}
+
+
+def find_changed_blocks(old_content: str, new_content: str) -> list[dict[str, Any]]:
+    """Find AIMB blocks whose stored hash differs from their current computed hash.
+
+    For each AIMB block:
+    - The **stored hash** is read from the metadata in *old_content*.
+    - The **computed hash** is calculated from the block content in
+      *new_content*.
+
+    Parameters
+    ----------
+    old_content : str
+        Previous version of the markdown content (source of stored hashes).
+    new_content : str
+        Current version of the markdown content (source of block content to
+        hash).
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        A list of dicts, one per changed block, with keys:
+        ``id``, ``old_hash``, ``new_hash``.  Empty list if no blocks
+        changed or no AIMB blocks exist.
+    """
+    stored = get_stored_hashes(old_content)
+    computed = hash_all_blocks(new_content)
+
+    changed: list[dict[str, Any]] = []
+    for block_id, old_hash in stored.items():
+        new_hash = computed.get(block_id)
+        if new_hash is not None and old_hash != new_hash:
+            changed.append(
+                {
+                    "id": block_id,
+                    "old_hash": old_hash,
+                    "new_hash": new_hash,
+                }
+            )
+
+    return changed

diary/aimb/merge.py

@@ -0,0 +1,252 @@
+"""Replace-or-flag conflict resolution for AIMB blocks.
+
+Provides conflict-averse merge logic for AI-Managed Blocks:
+
+- :class:`MergeDecision` — three-way action enum (REPLACE / FLAG_CONFLICT / SKIP)
+- :class:`ConflictInfo` — details about a detected conflict
+- :func:`decide_block_action` — compare stored vs. current hash to decide
+- :func:`generate_block_diff` — unified diff between two block versions
+- :func:`format_conflict_report` — human-readable conflict summary
+- :func:`apply_replace` — update a block's content and its metadata tags
+"""
+
+from __future__ import annotations
+
+import difflib
+import enum
+import re
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any
+
+from .hasher import compute_block_hash
+from .parser import AIMBBlock, get_block_by_id
+
+
+# ── Enum ─────────────────────────────────────────────────────────────────
+
+
+class MergeDecision(enum.Enum):
+    """Action to take for a single AIMB block during a merge.
+
+    +------------------+--------------------------------------------------+
+    | Member           | Meaning                                          |
+    +==================+==================================================+
+    | ``REPLACE``      | No manual edit detected — safe to overwrite.     |
+    +------------------+--------------------------------------------------+
+    | ``FLAG_CONFLICT``| Block was manually edited — needs human review.  |
+    +------------------+--------------------------------------------------+
+    | ``SKIP``         | Block no longer exists in the new content.       |
+    +------------------+--------------------------------------------------+
+    """
+
+    REPLACE = "replace"
+    FLAG_CONFLICT = "flag_conflict"
+    SKIP = "skip"
+
+
+# ── Dataclass ─────────────────────────────────────────────────────────────
+
+
+@dataclass
+class ConflictInfo:
+    """Details about a single merge conflict.
+
+    Attributes
+    ----------
+    block_id : str
+        Block identifier.
+    file_path : str
+        Path to the file containing the conflict.
+    old_hash : str
+        Expected hash (from the stored/snapshot record).
+    current_hash : str
+        Actual hash in the current file metadata.
+    diff_preview : str
+        Unified diff between the stored and current block content.
+    """
+
+    block_id: str
+    file_path: str
+    old_hash: str
+    current_hash: str
+    diff_preview: str = ""
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+
+def decide_block_action(
+    block: AIMBBlock,
+    stored_hash: str,
+    new_content: str,
+) -> MergeDecision:
+    """Decide what to do with *block* when merging.
+
+    Decision logic:
+
+    1. If ``block.hash`` (current metadata) matches *stored_hash* (previous
+       snapshot) → :attr:`MergeDecision.REPLACE` — no manual edits, safe to
+       overwrite.
+    2. If the block's ``id`` is **not** found in *new_content* →
+       :attr:`MergeDecision.SKIP` — the block was removed upstream.
+    3. Otherwise → :attr:`MergeDecision.FLAG_CONFLICT` — the block was
+       manually edited and needs human review.
+
+    Parameters
+    ----------
+    block : AIMBBlock
+        The block as it currently exists in the file (parsed metadata).
+    stored_hash : str
+        The hash recorded when the block was last written (snapshot).
+    new_content : str
+        The full markdown content being merged in (used to check existence).
+
+    Returns
+    -------
+    MergeDecision
+        The recommended action.
+    """
+    # 1. Hashes match → safe to replace
+    if block.hash == stored_hash:
+        return MergeDecision.REPLACE
+
+    # 2. Block no longer present in the incoming content → skip it
+    if get_block_by_id(new_content, block.id) is None:
+        return MergeDecision.SKIP
+
+    # 3. Hashes differ → manual edit detected
+    return MergeDecision.FLAG_CONFLICT
+
+
+def generate_block_diff(content_before: str, content_after: str) -> str:
+    """Return a unified diff string comparing two versions of block content.
+
+    Parameters
+    ----------
+    content_before : str
+        Previous block content.
+    content_after : str
+        Current block content.
+
+    Returns
+    -------
+    str
+        Unified diff (3 context lines).  Returns an empty string when
+        the two contents are identical.
+    """
+    lines_before = content_before.splitlines(keepends=True)
+    lines_after = content_after.splitlines(keepends=True)
+
+    diff = list(
+        difflib.unified_diff(
+            lines_before,
+            lines_after,
+            fromfile="before",
+            tofile="after",
+            n=3,
+        )
+    )
+    return "".join(diff)
+
+
+def format_conflict_report(conflicts: list[ConflictInfo]) -> str:
+    """Format a list of conflicts into a human-readable report string.
+
+    Parameters
+    ----------
+    conflicts : list[ConflictInfo]
+        Zero or more conflict records.
+
+    Returns
+    -------
+    str
+        Markdown-formatted conflict report.  When *conflicts* is empty
+        the report simply states zero conflicts.
+    """
+    lines: list[str] = [
+        "# Merge Conflict Report",
+        "",
+        f"Total conflicts: {len(conflicts)}",
+        "",
+    ]
+
+    for i, c in enumerate(conflicts, 1):
+        lines.append(f"## {i}. Block ``{c.block_id}`` in ``{c.file_path}``")
+        lines.append("")
+        lines.append("| Field | Value |")
+        lines.append("|-------|-------|")
+        lines.append(f"| Stored hash (expected) | ``{c.old_hash}`` |")
+        lines.append(f"| Current hash (in file) | ``{c.current_hash}`` |")
+        lines.append("| Status | Manual edit detected — review required |")
+        lines.append("")
+
+        if c.diff_preview:
+            lines.append("### Diff Preview")
+            lines.append("")
+            lines.append("```diff")
+            lines.append(c.diff_preview.rstrip("\n"))
+            lines.append("```")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def apply_replace(content: str, block_id: str, new_block_content: str) -> str:
+    """Replace the content of an AIMB block in-place.
+
+    1. Locates the ``<!-- ai-managed id="<block_id>" ... -->`` tag pair.
+    2. Replaces the text *between* the open and close tags with
+       *new_block_content*.
+    3. Updates the ``hash`` attribute in the opening tag.
+    4. Updates the ``updated`` attribute to today's date (YYYY-MM-DD).
+
+    Parameters
+    ----------
+    content : str
+        Full markdown content containing the AIMB block.
+    block_id : str
+        The ``id`` of the block to replace.
+    new_block_content : str
+        New content for the block (text that goes between the tags).
+
+    Returns
+    -------
+    str
+        Updated markdown content with the block replaced and its metadata
+        tags refreshed.
+
+    Raises
+    ------
+    ValueError
+        If no AIMB block with *block_id* exists in *content*.
+    """
+    new_hash = compute_block_hash(new_block_content)
+    today = date.today().isoformat()
+
+    escaped_id = re.escape(block_id)
+    pattern = re.compile(
+        r"(<!--\s*ai-managed\s+"
+        r'id="' + escaped_id + r'"\s+)'
+        r'hash="[^"]*"\s+'
+        r'updated="[^"]*"'
+        r"(\s*-->)\s*\n?"
+        r"(.*?)"
+        r"(<!--\s*/ai-managed\s*-->)",
+        re.DOTALL,
+    )
+
+    def _replace(m: re.Match) -> str:
+        opening = m.group(1)
+        sep = m.group(2)
+        close_tag = m.group(4)
+
+        new_opening = f'{opening}hash="{new_hash}" updated="{today}"{sep}\n'
+        return new_opening + new_block_content.rstrip("\n") + "\n" + close_tag
+
+    result, count = pattern.subn(_replace, content, count=1)
+    if count == 0:
+        raise ValueError(
+            f"AIMB block '{block_id}' not found in content"
+        )
+    return result

diary/aimb/parser.py

@@ -0,0 +1,202 @@
+"""AIMB block parser — extracts AI Managed Blocks and manual blocks from markdown content.
+
+AIMB format::
+
+    <!-- ai-managed id="arch" hash="abc123" updated="2024-01-01" -->
+    ... managed content ...
+    <!-- /ai-managed -->
+
+Manual block format::
+
+    <!-- manual -->
+    ... user-only content ...
+    <!-- /manual -->
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+# ── Regex patterns ──────────────────────────────────────────────────────
+
+_AIMB_OPEN_RE = re.compile(
+    r'<!--\s*ai-managed\s+'
+    r'id="([^"]+)"\s+'
+    r'hash="([^"]*)"\s+'
+    r'updated="([^"]*)"\s*'
+    r'-->\s*\n?'
+)
+
+_AIMB_CLOSE_RE = re.compile(r'<!--\s*/ai-managed\s*-->')
+
+# Combined AIMB block (open → content → close)
+_AIMB_BLOCK_RE = re.compile(
+    r'<!--\s*ai-managed\s+'
+    r'id="([^"]+)"\s+'
+    r'hash="([^"]*)"\s+'
+    r'updated="([^"]*)"\s*'
+    r'-->\s*\n?'
+    r'(.*?)'
+    r'<!--\s*/ai-managed\s*-->',
+    re.DOTALL,
+)
+
+_MANUAL_BLOCK_RE = re.compile(
+    r'<!--\s*manual\s*-->\s*\n?'
+    r'(.*?)'
+    r'<!--\s*/manual\s*-->',
+    re.DOTALL,
+)
+
+
+# ── Dataclass ───────────────────────────────────────────────────────────
+
+
+@dataclass
+class AIMBBlock:
+    """A single AI-Managed Block extracted from a markdown file.
+
+    Attributes
+    ----------
+    id : str
+        Unique block identifier (e.g. ``"arch"``, ``"decisions"``).
+    hash : str
+        Content hash recorded when the block was last written.
+    updated : str
+        ISO-8601 date string of last update.
+    content : str
+        Raw markdown content *between* the opening and closing tags
+        (leading/trailing whitespace stripped).
+    start_line : int
+        0-based line index of the opening tag in the source content.
+    end_line : int
+        0-based line index of the closing tag.
+    is_manual : bool
+        ``True`` if this is a user-manual (non-AIMB) block.
+    """
+
+    id: str
+    hash: str
+    updated: str
+    content: str
+    start_line: int = 0
+    end_line: int = 0
+    is_manual: bool = False
+
+
+# ── Public API ─────────────────────────────────────────────────────────
+
+
+def parse_aimb_blocks(content: str) -> list[AIMBBlock]:
+    """Parse all AIMB blocks from *content*.
+
+    Returns a list of :class:`AIMBBlock` instances, one per ``<!--
+    ai-managed ... -->`` / ``<!-- /ai-managed -->`` pair found in the
+    input.  Returns an empty list if no AIMB blocks exist.
+    """
+    lines = content.split("\n")
+    blocks: list[AIMBBlock] = []
+
+    for m in _AIMB_BLOCK_RE.finditer(content):
+        block_id = m.group(1)
+        block_hash = m.group(2)
+        block_updated = m.group(3)
+        block_content = m.group(4).strip("\n")
+
+        # Calculate line positions from the match offsets
+        match_start = m.start()
+        match_end = m.end()
+
+        start_line = _offset_to_line(content, match_start)
+        end_line = _offset_to_line(content, match_end)
+
+        blocks.append(
+            AIMBBlock(
+                id=block_id,
+                hash=block_hash,
+                updated=block_updated,
+                content=block_content,
+                start_line=start_line,
+                end_line=end_line,
+                is_manual=False,
+            )
+        )
+
+    return blocks
+
+
+def parse_frontmatter(content: str) -> dict[str, str]:
+    """Parse YAML-style frontmatter from markdown content.
+
+    Expects content delimited by ``---\\n`` fences at the *very beginning*
+    of the file.  Supports simple ``key: value`` pairs only (no nested
+    YAML, no lists).
+
+    Returns
+    -------
+    dict
+        Parsed frontmatter fields (may be empty).
+    """
+    result: dict[str, str] = {}
+    m = re.match(r"^---\n(.*?)\n---(?:\n|$)", content, re.DOTALL)
+    if not m:
+        return result
+
+    for line in m.group(1).split("\n"):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        kv = re.match(r"(\w[\w_-]*)\s*:\s*(.*)", line)
+        if kv:
+            key = kv.group(1).strip()
+            value = kv.group(2).strip()
+            # Strip optional surrounding quotes
+            if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                value = value[1:-1]
+            result[key] = value
+
+    return result
+
+
+def extract_manual_blocks(content: str) -> list[dict[str, Any]]:
+    """Extract all ``<!-- manual -->`` / ``<!-- /manual -->`` blocks.
+
+    Returns a list of dicts with keys ``content``, ``start_line``,
+    ``end_line``.
+    """
+    blocks: list[dict[str, Any]] = []
+    for m in _MANUAL_BLOCK_RE.finditer(content):
+        block_content = m.group(1).strip("\n")
+        start_line = _offset_to_line(content, m.start())
+        end_line = _offset_to_line(content, m.end())
+        blocks.append(
+            {
+                "content": block_content,
+                "start_line": start_line,
+                "end_line": end_line,
+            }
+        )
+    return blocks
+
+
+def has_aimb_blocks(content: str) -> bool:
+    """Return ``True`` if *content* contains at least one AIMB block."""
+    return _AIMB_OPEN_RE.search(content) is not None
+
+
+def get_block_by_id(content: str, block_id: str) -> AIMBBlock | None:
+    """Return the :class:`AIMBBlock` with the given *block_id*, or ``None``."""
+    for block in parse_aimb_blocks(content):
+        if block.id == block_id:
+            return block
+    return None
+
+
+# ── Internal helpers ───────────────────────────────────────────────────
+
+
+def _offset_to_line(content: str, offset: int) -> int:
+    """Convert a byte/char offset into a 0-based line number."""
+    return content[:offset].count("\n")