codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/wiki/paths.py

@@ -0,0 +1,42 @@
+import re
+
+
+def looks_like_dir(raw: str) -> bool:
+    return raw.strip().replace("\\", "/").endswith("/")
+
+
+def normalize_reference_path(raw: str, is_dir: bool) -> str:
+    return normalize_reference_shape(raw, is_dir).casefold()
+
+
+def normalize_reference_path_preserving_case(raw: str, is_dir: bool) -> str:
+    return normalize_reference_shape(raw, is_dir)
+
+
+def normalize_reference_shape(raw: str, is_dir: bool) -> str:
+    text = raw.strip().replace("\\", "/")
+    while text.startswith("./"):
+        text = text[2:]
+    text = re.sub(r"/+", "/", text)
+    text = text.lstrip("/")
+    if ".." in text.split("/"):
+        return ""
+    text = text.rstrip("/")
+    if is_dir and text:
+        return f"{text}/"
+    return text
+
+
+def parent_folder_prefixes(file_path: str) -> list[str]:
+    prefixes: list[str] = []
+    cursor = 0
+    while True:
+        index = file_path.find("/", cursor)
+        if index == -1:
+            return prefixes
+        prefixes.append(file_path[: index + 1])
+        cursor = index + 1
+
+
+def escape_glob_meta(input_path: str) -> str:
+    return re.sub(r"([*?\[])", r"[\1]", input_path)

codealmanac/services/wiki/service.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+from codealmanac.manual import ManualLibrary
+from codealmanac.services.wiki.templates import (
+    gitignore_runtime_block,
+    starter_page,
+    starter_readme,
+    starter_topics_yaml,
+)
+from codealmanac.services.workspaces.service import WorkspacesService
+
+
+class WikiService:
+    def __init__(self, workspaces: WorkspacesService, manual: ManualLibrary):
+        self.workspaces = workspaces
+        self.manual = manual
+
+    def initialize(self, workspace_id: str) -> None:
+        workspace = self.workspaces.get(workspace_id)
+        almanac_path = workspace.almanac_path
+        pages_path = almanac_path / "pages"
+        manual_path = almanac_path / "manual"
+        almanac_path.mkdir(parents=True, exist_ok=True)
+        pages_path.mkdir(parents=True, exist_ok=True)
+        manual_path.mkdir(parents=True, exist_ok=True)
+        write_if_missing(almanac_path / "README.md", starter_readme())
+        write_if_missing(almanac_path / "topics.yaml", starter_topics_yaml())
+        write_if_missing(pages_path / "getting-started.md", starter_page())
+        self.manual.install_missing(manual_path)
+        ensure_root_gitignore(workspace.root_path, workspace.almanac_root)
+
+
+def write_if_missing(path: Path, body: str) -> None:
+    if path.exists():
+        return
+    path.write_text(body, encoding="utf-8")
+
+
+def ensure_root_gitignore(root_path: Path, almanac_root: Path) -> None:
+    path = root_path / ".gitignore"
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    lines = {line.strip() for line in existing.splitlines()}
+    missing = [
+        line
+        for line in gitignore_runtime_block(almanac_root)
+        if line not in lines
+    ]
+    if len(missing) == 0:
+        return
+    header = "# codealmanac"
+    block_lines = []
+    if header not in lines:
+        block_lines.append(header)
+    block_lines.extend(missing)
+    block = "\n".join(block_lines) + "\n"
+    separator = "" if existing == "" else "\n" if existing.endswith("\n") else "\n\n"
+    path.write_text(f"{existing}{separator}{block}", encoding="utf-8")

codealmanac/services/wiki/templates.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+
+
+def starter_readme() -> str:
+    return """# CodeAlmanac Wiki
+
+This is the living wiki for this repository. It records the durable knowledge
+the code cannot say: decisions, flows, invariants, incidents, gotchas, and
+project context that future agents should not rediscover from scratch.
+
+## Notability Bar
+
+Write a page when it preserves non-obvious knowledge that will help a future
+agent work safely in this codebase.
+
+Good pages explain:
+
+- a decision that took research or trial-and-error
+- a cross-file flow
+- an invariant or gotcha not visible from one file
+- an external dependency as this repo uses it
+- a product or operational constraint that shapes future work
+
+Do not write pages that restate nearby code.
+
+## Topic Taxonomy
+
+Topics live in `topics.yaml`. Pages live in `pages/`.
+
+## Manual
+
+Read `manual/README.md` before creating, reorganizing, or substantially
+rewriting pages. The manual is bundled with CodeAlmanac and copied here by
+`codealmanac init` and `codealmanac build`.
+
+## Links
+
+Use `[[page-slug]]` for page links and `[[src/path.py]]` for file references.
+"""
+
+
+def starter_topics_yaml() -> str:
+    return """topics:
+  - slug: concepts
+    title: Concepts
+    description: Core vocabulary and mental models for this codebase
+    parents: []
+"""
+
+
+def starter_page() -> str:
+    return """---
+title: Getting Started
+topics: [concepts]
+sources: []
+status: active
+---
+
+# Getting Started
+
+This starter page marks the wiki as initialized. Replace it with the first
+durable reading path for this repository.
+"""
+
+
+def gitignore_runtime_block(almanac_root: Path) -> list[str]:
+    root = almanac_root.as_posix().rstrip("/")
+    return [
+        f"{root}/index.db",
+        f"{root}/index.db-wal",
+        f"{root}/index.db-shm",
+        f"{root}/jobs/",
+    ]

codealmanac/services/wiki/topics.py

@@ -0,0 +1,266 @@
+from io import StringIO
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+import yaml as pyyaml
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from yaml import YAMLError
+
+from codealmanac.core.errors import ValidationFailed
+from codealmanac.core.slug import to_kebab_case
+
+
+class TopicDefinition(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    slug: str
+    title: str | None = None
+    description: str | None = None
+    parents: tuple[str, ...] = ()
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def canonical_slug(cls, value: Any) -> str:
+        return to_kebab_case(str(value))
+
+    @field_validator("title", "description", mode="before")
+    @classmethod
+    def optional_text(cls, value: Any) -> str | None:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        return None
+
+    @field_validator("parents", mode="before")
+    @classmethod
+    def parent_slugs(cls, value: Any) -> tuple[str, ...]:
+        if not isinstance(value, list | tuple):
+            return ()
+        parents: list[str] = []
+        for item in value:
+            slug = to_kebab_case(str(item))
+            if slug:
+                parents.append(slug)
+        return tuple(dict.fromkeys(parents))
+
+
+class TopicsYaml(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    topics: tuple[TopicDefinition, ...] = ()
+
+
+def load_topics_yaml(almanac_path: Path) -> tuple[TopicDefinition, ...]:
+    path = almanac_path / "topics.yaml"
+    if not path.is_file():
+        return ()
+    try:
+        parsed = pyyaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, YAMLError):
+        return ()
+    if not isinstance(parsed, dict):
+        return ()
+    try:
+        model = TopicsYaml.model_validate(parsed)
+    except ValidationError:
+        return ()
+    return tuple(topic for topic in model.topics if topic.slug)
+
+
+class TopicsYamlFile:
+    def __init__(
+        self,
+        path: Path,
+        data: CommentedMap,
+        topics: CommentedSeq,
+        line_ending: str,
+    ):
+        self.path = path
+        self.data = data
+        self.topics = topics
+        self.line_ending = line_ending
+
+    @property
+    def definitions(self) -> tuple[TopicDefinition, ...]:
+        try:
+            model = TopicsYaml.model_validate(self.data)
+        except ValidationError as error:
+            raise ValidationFailed(f"invalid topics.yaml: {error}") from error
+        return tuple(topic for topic in model.topics if topic.slug)
+
+    def has_entry(self, slug: str) -> bool:
+        return self.entry_for(slug) is not None
+
+    def ensure_topic(self, slug: str, title: str | None = None) -> None:
+        if self.has_entry(slug):
+            return
+        entry = CommentedMap()
+        entry["slug"] = slug
+        entry["title"] = title or title_for_slug(slug)
+        entry["parents"] = CommentedSeq()
+        self.topics.append(entry)
+
+    def set_description(self, slug: str, description: str | None) -> None:
+        entry = self.required_entry(slug)
+        if description:
+            entry["description"] = description
+            return
+        if "description" in entry:
+            del entry["description"]
+
+    def maybe_update_default_title(self, slug: str, title: str) -> None:
+        entry = self.required_entry(slug)
+        default_title = title_for_slug(slug)
+        current_title = entry.get("title")
+        if current_title in (None, default_title) and title != default_title:
+            entry["title"] = title
+
+    def add_parent(self, child: str, parent: str) -> bool:
+        entry = self.required_entry(child)
+        parents = parent_sequence(entry)
+        if parent in {str(item) for item in parents}:
+            return False
+        parents.append(parent)
+        entry["parents"] = parents
+        return True
+
+    def remove_parent(self, child: str, parent: str) -> bool:
+        entry = self.entry_for(child)
+        if entry is None:
+            return False
+        parents = parent_sequence(entry)
+        removed = False
+        for index in range(len(parents) - 1, -1, -1):
+            if str(parents[index]) == parent:
+                del parents[index]
+                removed = True
+        entry["parents"] = parents
+        return removed
+
+    def rename_topic(self, old_slug: str, new_slug: str) -> bool:
+        changed = False
+        entry = self.entry_for(old_slug)
+        if entry is not None:
+            entry["slug"] = new_slug
+            if entry.get("title") == title_for_slug(old_slug):
+                entry["title"] = title_for_slug(new_slug)
+            changed = True
+        for item in self.topics:
+            if not isinstance(item, CommentedMap):
+                continue
+            parents = parent_sequence(item)
+            next_parents = replace_parent_slug(parents, old_slug, new_slug)
+            if next_parents != tuple(str(parent) for parent in parents):
+                item["parents"] = CommentedSeq(next_parents)
+                changed = True
+        return changed
+
+    def delete_topic(self, slug: str) -> bool:
+        changed = False
+        for index in range(len(self.topics) - 1, -1, -1):
+            item = self.topics[index]
+            if (
+                isinstance(item, CommentedMap)
+                and to_kebab_case(str(item.get("slug"))) == slug
+            ):
+                del self.topics[index]
+                changed = True
+        for item in self.topics:
+            if not isinstance(item, CommentedMap):
+                continue
+            parents = parent_sequence(item)
+            next_parents = tuple(
+                str(parent) for parent in parents if str(parent) != slug
+            )
+            if next_parents != tuple(str(parent) for parent in parents):
+                item["parents"] = CommentedSeq(next_parents)
+                changed = True
+        return changed
+
+    def write(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        yaml = YAML(typ="rt")
+        yaml.preserve_quotes = True
+        output = StringIO()
+        yaml.dump(self.data, output)
+        text = output.getvalue()
+        if self.line_ending != "\n":
+            text = text.replace("\n", self.line_ending)
+        temporary = self.path.with_name(f".{self.path.name}.{uuid4().hex}.tmp")
+        temporary.write_text(text, encoding="utf-8")
+        temporary.replace(self.path)
+
+    def required_entry(self, slug: str) -> CommentedMap:
+        entry = self.entry_for(slug)
+        if entry is None:
+            raise ValidationFailed(f'topic "{slug}" is missing from topics.yaml')
+        return entry
+
+    def entry_for(self, slug: str) -> CommentedMap | None:
+        for item in self.topics:
+            if (
+                isinstance(item, CommentedMap)
+                and to_kebab_case(str(item.get("slug"))) == slug
+            ):
+                return item
+        return None
+
+
+def load_topics_file(almanac_path: Path) -> TopicsYamlFile:
+    path = almanac_path / "topics.yaml"
+    raw = read_topics_text(path)
+    line_ending = "\r\n" if "\r\n" in raw else "\n"
+    yaml = YAML(typ="rt")
+    yaml.preserve_quotes = True
+    try:
+        parsed = yaml.load(raw) if raw.strip() else CommentedMap()
+    except Exception as error:
+        raise ValidationFailed(f"invalid topics.yaml: {path}") from error
+    if parsed is None:
+        parsed = CommentedMap()
+    if not isinstance(parsed, CommentedMap):
+        raise ValidationFailed(f"topics.yaml must be a YAML mapping: {path}")
+    topics = parsed.get("topics")
+    if topics is None:
+        topics = CommentedSeq()
+        parsed["topics"] = topics
+    if not isinstance(topics, CommentedSeq):
+        raise ValidationFailed(f"topics.yaml topics must be a list: {path}")
+    file = TopicsYamlFile(path, parsed, topics, line_ending)
+    _ = file.definitions
+    return file
+
+
+def read_topics_text(path: Path) -> str:
+    if not path.is_file():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def parent_sequence(entry: CommentedMap) -> CommentedSeq:
+    existing = entry.get("parents")
+    if isinstance(existing, CommentedSeq):
+        return existing
+    sequence = CommentedSeq()
+    if isinstance(existing, list):
+        sequence.extend(to_kebab_case(str(item)) for item in existing)
+    return sequence
+
+
+def replace_parent_slug(
+    parents: CommentedSeq,
+    old_slug: str,
+    new_slug: str,
+) -> tuple[str, ...]:
+    replaced: list[str] = []
+    for parent in parents:
+        next_parent = new_slug if str(parent) == old_slug else str(parent)
+        if next_parent not in replaced:
+            replaced.append(next_parent)
+    return tuple(replaced)
+
+
+def title_for_slug(slug: str) -> str:
+    return " ".join(part.capitalize() for part in slug.split("-") if part)

codealmanac/services/wiki/wikilinks.py

@@ -0,0 +1,58 @@
+import re
+
+from codealmanac.core.slug import to_kebab_case
+from codealmanac.services.wiki.models import (
+    CrossWikiLink,
+    FileLink,
+    FileReference,
+    FolderLink,
+    PageLink,
+    Wikilink,
+    WikilinkKind,
+)
+from codealmanac.services.wiki.paths import (
+    looks_like_dir,
+    normalize_reference_path,
+    normalize_reference_path_preserving_case,
+)
+
+
+def classify_wikilink(raw: str) -> Wikilink | None:
+    target = raw.split("|", maxsplit=1)[0].strip()
+    if not target:
+        return None
+
+    first_colon = target.find(":")
+    first_slash = target.find("/")
+
+    if first_colon != -1 and (first_slash == -1 or first_colon < first_slash):
+        wiki = target[:first_colon].strip()
+        slug = target[first_colon + 1 :].strip()
+        if not wiki or not slug:
+            return None
+        return CrossWikiLink(kind=WikilinkKind.CROSS_WIKI, wiki=wiki, target=slug)
+
+    if first_slash != -1:
+        is_dir = looks_like_dir(target)
+        normalized = normalize_reference_path(target, is_dir)
+        original = normalize_reference_path_preserving_case(target, is_dir)
+        if not normalized:
+            return None
+        ref = FileReference(path=normalized, original_path=original, is_dir=is_dir)
+        if is_dir:
+            return FolderLink(kind=WikilinkKind.FOLDER, ref=ref)
+        return FileLink(kind=WikilinkKind.FILE, ref=ref)
+
+    slug = to_kebab_case(target)
+    if not slug:
+        return None
+    return PageLink(kind=WikilinkKind.PAGE, target=slug)
+
+
+def extract_wikilinks(body: str) -> tuple[Wikilink, ...]:
+    links: list[Wikilink] = []
+    for match in re.finditer(r"\[\[([^\]\n]+)\]\]", body):
+        link = classify_wikilink(match.group(1))
+        if link is not None:
+            links.append(link)
+    return tuple(links)

codealmanac/services/workspaces/__init__.py

@@ -0,0 +1 @@
+

codealmanac/services/workspaces/models.py

@@ -0,0 +1,124 @@
+from datetime import datetime
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import Field, field_validator, model_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.services.workspaces.roots import (
+    DEFAULT_ALMANAC_ROOT,
+    validate_almanac_root_field,
+)
+
+
+class Workspace(CodeAlmanacModel):
+    workspace_id: str
+    name: str
+    description: str
+    root_path: Path
+    almanac_root: Path = Field(default=DEFAULT_ALMANAC_ROOT)
+    almanac_path: Path
+    registered_at: datetime
+
+    @field_validator("workspace_id")
+    @classmethod
+    def require_workspace_id(cls, value: str) -> str:
+        return required_text(value, "workspace_id")
+
+    @field_validator("name")
+    @classmethod
+    def require_name(cls, value: str) -> str:
+        return required_text(value, "workspace name")
+
+    @field_validator("almanac_root")
+    @classmethod
+    def validate_almanac_root(cls, value: Path) -> Path:
+        return validate_almanac_root_field(value)
+
+    @model_validator(mode="after")
+    def validate_almanac_path_matches_root(self) -> "Workspace":
+        expected = self.root_path / self.almanac_root
+        if self.almanac_path != expected:
+            raise ValueError("workspace almanac_path must match root_path/almanac_root")
+        return self
+
+
+class WorkspaceRegistryEntry(CodeAlmanacModel):
+    name: str
+    description: str = ""
+    path: Path
+    almanac_root: Path = Field(default=DEFAULT_ALMANAC_ROOT)
+    registered_at: datetime
+    workspace_id: str
+
+    @field_validator("name")
+    @classmethod
+    def require_name(cls, value: str) -> str:
+        return required_text(value, "workspace name")
+
+    @field_validator("almanac_root")
+    @classmethod
+    def validate_almanac_root(cls, value: Path) -> Path:
+        return validate_almanac_root_field(value)
+
+    def to_workspace(self) -> Workspace:
+        return Workspace(
+            workspace_id=self.workspace_id,
+            name=self.name,
+            description=self.description,
+            root_path=self.path,
+            almanac_root=self.almanac_root,
+            almanac_path=self.path / self.almanac_root,
+            registered_at=self.registered_at,
+        )
+
+
+class WorkspaceRegistryStatus(StrEnum):
+    AVAILABLE = "available"
+    MISSING_REPO = "missing_repo"
+    MISSING_ALMANAC = "missing_almanac"
+
+
+class WorkspaceListItem(CodeAlmanacModel):
+    workspace: Workspace
+    status: WorkspaceRegistryStatus
+
+
+class WorkspaceListResult(CodeAlmanacModel):
+    items: tuple[WorkspaceListItem, ...]
+
+
+class DropWorkspaceResult(CodeAlmanacModel):
+    dropped: tuple[Workspace, ...]
+
+
+class WorkspacePathState(StrEnum):
+    ADDED = "added"
+    COPIED = "copied"
+    DELETED = "deleted"
+    MODIFIED = "modified"
+    RENAMED = "renamed"
+    TYPE_CHANGED = "type_changed"
+    UNMERGED = "unmerged"
+    UNTRACKED = "untracked"
+    UNKNOWN = "unknown"
+
+
+class WorkspacePathChange(CodeAlmanacModel):
+    path: Path
+    state: WorkspacePathState
+    status: str
+    fingerprint: str | None = None
+
+    @field_validator("status")
+    @classmethod
+    def require_status(cls, value: str) -> str:
+        return required_text(value, "workspace path status")
+
+
+class WorkspaceChangeSnapshot(CodeAlmanacModel):
+    root_path: Path
+    available: bool
+    changes: tuple[WorkspacePathChange, ...] = ()
+    unavailable_reason: str | None = None

codealmanac/services/workspaces/ports.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+from typing import Protocol
+
+from codealmanac.services.workspaces.models import WorkspaceChangeSnapshot
+
+
+class WorkspaceChangeProbe(Protocol):
+    def snapshot(self, root_path: Path) -> WorkspaceChangeSnapshot:
+        """Return the current observable local change state for a workspace."""