keepm 0.2.0__py3-none-any.whl

keepm/markdown.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import datetime as dt
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+import yaml
+
+from keepm.models import MemoryDocument, MemoryLink
+
+VALID_TYPES = {"user", "feedback", "project", "reference"}
+LINK_RE = re.compile(
+    r"^\s*-\s+(?:(?P<relation>[A-Za-z0-9_-]+)\s+)?"
+    r"\[\[(?P<target>[^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]",
+    re.MULTILINE,
+)
+WIKILINK_RE = re.compile(
+    r"\[\[(?P<target>[^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]"
+)
+
+
+def slug_filename(name: str) -> str:
+    slug = name.casefold().strip().replace(" ", "-")
+    slug = re.sub(r"[^\w-]", "", slug, flags=re.UNICODE)
+    slug = re.sub(r"[-_]+", "-", slug).strip("-")
+    if not slug:
+        raise ValueError("memory name cannot produce a filename")
+    return f"{slug}.md"
+
+
+def _date_string(value: object) -> str:
+    if isinstance(value, dt.datetime):
+        value = value.date()
+    if isinstance(value, dt.date):
+        return value.isoformat()
+    text = str(value)
+    try:
+        dt.date.fromisoformat(text)
+    except ValueError as error:
+        raise ValueError("date must be YYYY-MM-DD") from error
+    return text
+
+
+def _has_protocol_label(body: str, label: str) -> bool:
+    pattern = rf"(?im)^\s*(?:\*\*)?{re.escape(label)}(?:\*\*)?\s*[:：](?:\*\*)?"
+    return re.search(pattern, body) is not None
+
+
+def parse_memory(path: Path, text: str) -> MemoryDocument:
+    normalized = text.lstrip("\ufeff").replace("\r\n", "\n").replace("\r", "\n")
+    if not normalized.startswith("---\n"):
+        raise ValueError(f"{path}: missing YAML frontmatter")
+    closing = normalized.find("\n---\n", 4)
+    if closing < 0:
+        raise ValueError(f"{path}: unclosed YAML frontmatter")
+
+    try:
+        loaded = yaml.safe_load(normalized[4:closing]) or {}
+    except yaml.YAMLError as error:
+        raise ValueError(f"{path}: invalid YAML frontmatter: {error}") from error
+    if not isinstance(loaded, Mapping):
+        raise ValueError(f"{path}: YAML frontmatter must be a mapping")
+    metadata = dict(loaded)
+    body = normalized[closing + 5 :].lstrip("\n")
+
+    required = ("id", "name", "description", "type", "scope", "created", "updated")
+    missing = [key for key in required if metadata.get(key) in (None, "")]
+    if missing:
+        raise ValueError(f"{path}: missing required fields: {', '.join(missing)}")
+
+    memory_type = str(metadata["type"])
+    if memory_type not in VALID_TYPES:
+        raise ValueError(f"{path}: invalid type: {memory_type}")
+    try:
+        created = _date_string(metadata["created"])
+        updated = _date_string(metadata["updated"])
+    except ValueError as error:
+        raise ValueError(f"{path}: {error}") from error
+
+    if memory_type in {"feedback", "project"}:
+        if not _has_protocol_label(body, "Why"):
+            raise ValueError(f"{path}: type {memory_type} requires Why:")
+        if not _has_protocol_label(body, "How to apply"):
+            raise ValueError(f"{path}: type {memory_type} requires How to apply:")
+
+    raw_tags = metadata.get("tags", []) or []
+    if not isinstance(raw_tags, list):
+        raise ValueError(f"{path}: tags must be a YAML list")
+    tags = tuple(str(tag).lstrip("#") for tag in raw_tags)
+
+    raw_pinned = metadata.get("pinned", False)
+    if not isinstance(raw_pinned, bool):
+        raise ValueError(f"{path}: pinned must be true or false")
+
+    links: list[MemoryLink] = []
+    relation_spans: list[tuple[int, int]] = []
+    for match in LINK_RE.finditer(body):
+        links.append(
+            MemoryLink(
+                target=match.group("target").strip(),
+                relation_type=match.group("relation") or "links_to",
+            )
+        )
+        relation_spans.append(match.span())
+    for match in WIKILINK_RE.finditer(body):
+        if any(start <= match.start() < end for start, end in relation_spans):
+            continue
+        links.append(MemoryLink(target=match.group("target").strip()))
+    deduplicated_links = tuple(
+        {
+            (link.relation_type, link.target.casefold()): link
+            for link in links
+        }.values()
+    )
+    return MemoryDocument(
+        id=str(metadata["id"]),
+        name=str(metadata["name"]),
+        description=str(metadata["description"]),
+        type=memory_type,
+        scope=str(metadata["scope"]),
+        created=created,
+        updated=updated,
+        body=body,
+        path=path,
+        tags=tags,
+        pinned=raw_pinned,
+        links=deduplicated_links,
+    )
+
+
+def render_memory(document: MemoryDocument) -> str:
+    metadata = {
+        "id": document.id,
+        "name": document.name,
+        "description": document.description,
+        "type": document.type,
+        "scope": document.scope,
+        "tags": list(document.tags),
+        "pinned": document.pinned,
+        "created": document.created,
+        "updated": document.updated,
+    }
+    frontmatter = yaml.safe_dump(
+        metadata,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+    ).strip()
+    body = document.body.rstrip()
+    separator = "\n\n" if body else "\n"
+    return f"---\n{frontmatter}\n---{separator}{body}\n"

keepm/models.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryLink:
+    target: str
+    relation_type: str = "links_to"
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryDocument:
+    id: str
+    name: str
+    description: str
+    type: str
+    scope: str
+    created: str
+    updated: str
+    body: str
+    path: Path
+    tags: tuple[str, ...] = ()
+    pinned: bool = False
+    links: tuple[MemoryLink, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class SearchHit:
+    id: str
+    name: str
+    description: str
+    scope: str
+    path: Path
+    snippet: str
+    rank: float
+    pinned: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class SyncReport:
+    new: int = 0
+    modified: int = 0
+    deleted: int = 0
+    moved: int = 0
+    unchanged: int = 0
+    errors: tuple[str, ...] = field(default_factory=tuple)

keepm/projects.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import re
+import subprocess
+import tomllib
+from collections.abc import Sequence
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+
+def normalize_project_name(name: str) -> str:
+    normalized = re.sub(r"[^a-z0-9_-]", "", name.lower().replace(" ", "-"))
+    normalized = re.sub(r"[-_]+", "-", normalized).strip("-")
+    if not normalized:
+        raise ValueError("project name is empty after normalization")
+    return normalized
+
+
+def resolve_workspace(
+    client_roots: Sequence[str] | None,
+    workspace_path: str | None,
+    cwd: Path,
+) -> Path:
+    if client_roots:
+        first = client_roots[0]
+        parsed = urlparse(first)
+        value = unquote(parsed.path) if parsed.scheme == "file" else first
+        return Path(value).expanduser().resolve()
+    if workspace_path:
+        return Path(workspace_path).expanduser().resolve()
+    return cwd.expanduser().resolve()
+
+
+def resolve_project_name(workspace: Path) -> str:
+    override = workspace / ".keepm.toml"
+    if override.is_file():
+        data = tomllib.loads(override.read_text(encoding="utf-8"))
+        if data.get("project"):
+            return normalize_project_name(str(data["project"]))
+
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            cwd=workspace,
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        result = None
+
+    if result and result.returncode == 0 and result.stdout.strip():
+        remote_name = result.stdout.strip().rstrip("/").rsplit("/", 1)[-1]
+        remote_name = remote_name.rsplit(":", 1)[-1].removesuffix(".git")
+        return normalize_project_name(remote_name)
+    return normalize_project_name(workspace.name)