codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/sources/requests.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.sources.models import SourceRef, TranscriptApp
+from codealmanac.services.workspaces.roots import (
+    DEFAULT_ALMANAC_ROOT,
+    normalized_almanac_roots,
+)
+
+
+class ResolveSourcesRequest(CodeAlmanacModel):
+    cwd: Path
+    inputs: tuple[str, ...]
+
+    @field_validator("inputs")
+    @classmethod
+    def require_inputs(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if len(value) == 0:
+            raise ValueError("at least one source input is required")
+        return value
+
+
+class DiscoverTranscriptsRequest(CodeAlmanacModel):
+    home: Path
+    apps: tuple[TranscriptApp, ...]
+    almanac_roots: tuple[Path, ...] = (DEFAULT_ALMANAC_ROOT,)
+
+    @field_validator("apps")
+    @classmethod
+    def require_apps(
+        cls,
+        value: tuple[TranscriptApp, ...],
+    ) -> tuple[TranscriptApp, ...]:
+        if len(value) == 0:
+            raise ValueError("at least one transcript app is required")
+        return value
+
+    @field_validator("almanac_roots")
+    @classmethod
+    def validate_almanac_roots(cls, value: tuple[Path, ...]) -> tuple[Path, ...]:
+        return normalized_almanac_roots(value)
+
+
+class SourceRuntimeContext(CodeAlmanacModel):
+    ignored_directories: tuple[Path, ...] = ()
+
+    @field_validator("ignored_directories")
+    @classmethod
+    def validate_ignored_directories(
+        cls,
+        value: tuple[Path, ...],
+    ) -> tuple[Path, ...]:
+        directories: list[Path] = []
+        for directory in value:
+            normalized = normalize_ignored_directory(directory)
+            if normalized not in directories:
+                directories.append(normalized)
+        return tuple(directories)
+
+
+class InspectSourceRuntimeRequest(CodeAlmanacModel):
+    cwd: Path
+    ref: SourceRef
+    context: SourceRuntimeContext = Field(default_factory=SourceRuntimeContext)
+
+
+def normalize_ignored_directory(path: Path) -> Path:
+    if path.is_absolute():
+        raise ValueError("source runtime ignored directories must be repo-relative")
+    if len(path.parts) == 0:
+        raise ValueError("source runtime ignored directories must name a directory")
+    if any(part in {"..", "~"} for part in path.parts):
+        raise ValueError("source runtime ignored directories must stay inside the repo")
+    return Path(*path.parts)

codealmanac/services/sources/service.py

@@ -0,0 +1,351 @@
+from collections.abc import Sequence
+from hashlib import sha256
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from pydantic import AnyHttpUrl, TypeAdapter, ValidationError
+
+from codealmanac.core.errors import ValidationFailed
+from codealmanac.core.paths import normalize_path
+from codealmanac.services.sources.models import (
+    SourceAddress,
+    SourceBrief,
+    SourceKind,
+    SourceProvenanceKind,
+    SourceRef,
+    SourceRuntime,
+    SourceRuntimeStatus,
+    TranscriptCandidate,
+)
+from codealmanac.services.sources.ports import (
+    SourceRuntimeAdapter,
+    TranscriptDiscoveryAdapter,
+)
+from codealmanac.services.sources.requests import (
+    DiscoverTranscriptsRequest,
+    InspectSourceRuntimeRequest,
+    ResolveSourcesRequest,
+)
+
+PULL_REQUEST_PROMPT_HINT = (
+    "Inspect the pull request, diff, commits, reviews, and linked issues before "
+    "deciding whether durable wiki knowledge changed."
+)
+ISSUE_PROMPT_HINT = (
+    "Inspect the issue, linked pull requests, decisions, labels, and comments "
+    "before deciding whether durable wiki knowledge changed."
+)
+GIT_RANGE_PROMPT_HINT = (
+    "Inspect the commit range and changed files before deciding whether durable "
+    "wiki knowledge changed."
+)
+GIT_DIFF_PROMPT_HINT = (
+    "Inspect the diff and current files before deciding whether durable wiki "
+    "knowledge changed."
+)
+WEB_PROMPT_HINT = (
+    "Inspect the web page as source material before deciding whether durable "
+    "wiki knowledge changed."
+)
+DIRECTORY_PROMPT_HINT = (
+    "Inspect the directory as bounded local source material before deciding "
+    "whether durable wiki knowledge changed."
+)
+FILE_PROMPT_HINT = (
+    "Inspect the file as bounded local source material before deciding whether "
+    "durable wiki knowledge changed."
+)
+MISSING_PATH_PROMPT_HINT = (
+    "Resolve the missing local path before attempting to use it as source "
+    "material."
+)
+
+HTTP_URL_ADAPTER = TypeAdapter(AnyHttpUrl)
+
+
+class SourcesService:
+    def __init__(
+        self,
+        transcript_discovery_adapters: Sequence[TranscriptDiscoveryAdapter] = (),
+        runtime_adapters: Sequence[SourceRuntimeAdapter] = (),
+    ):
+        self.transcript_discovery_adapters = tuple(transcript_discovery_adapters)
+        self.runtime_adapters = tuple(runtime_adapters)
+
+    def resolve(self, request: ResolveSourcesRequest) -> tuple[SourceBrief, ...]:
+        return tuple(
+            resolve_address(SourceAddress(raw=raw), request.cwd)
+            for raw in request.inputs
+        )
+
+    def discover_transcripts(
+        self,
+        request: DiscoverTranscriptsRequest,
+    ) -> tuple[TranscriptCandidate, ...]:
+        selected = set(request.apps)
+        candidates: list[TranscriptCandidate] = []
+        for adapter in self.transcript_discovery_adapters:
+            if adapter.app in selected:
+                candidates.extend(adapter.discover(request))
+        return tuple(sorted(candidates, key=transcript_sort_key))
+
+    def inspect_runtime(
+        self,
+        request: InspectSourceRuntimeRequest,
+    ) -> SourceRuntime:
+        for adapter in self.runtime_adapters:
+            if adapter.supports(request.ref):
+                return adapter.inspect(request)
+        return SourceRuntime(
+            ref=request.ref,
+            status=SourceRuntimeStatus.SKIPPED,
+            title=f"No runtime adapter for {request.ref.identity}",
+        )
+
+
+def transcript_sort_key(candidate: TranscriptCandidate) -> tuple[str, str, str]:
+    return (
+        candidate.app.value,
+        str(candidate.transcript_path),
+        candidate.session_id,
+    )
+
+
+def resolve_address(address: SourceAddress, cwd: Path) -> SourceBrief:
+    raw = address.raw
+    if raw.startswith("github:"):
+        return resolve_github_shorthand(raw)
+    if raw.startswith("git:range:"):
+        return resolve_git_range(raw)
+    if raw == "git:diff" or raw.startswith("git:diff:"):
+        return resolve_git_diff(raw)
+    if raw.startswith("transcript:"):
+        return resolve_transcript(raw)
+    parsed = urlsplit(raw)
+    if parsed.scheme in {"http", "https"}:
+        return resolve_url(raw)
+    return resolve_path(raw, cwd)
+
+
+def resolve_github_shorthand(raw: str) -> SourceBrief:
+    parts = raw.split(":")
+    if len(parts) != 3:
+        raise ValidationFailed(f"invalid GitHub source address: {raw}")
+    _, source_type, number_text = parts
+    number = parse_positive_int(number_text, raw)
+    if source_type == "pr":
+        ref = SourceRef(
+            raw=raw,
+            kind=SourceKind.GITHUB_PULL_REQUEST,
+            identity=f"github.pull_request:{number}",
+            number=number,
+        )
+        return SourceBrief(
+            ref=ref,
+            title=f"GitHub pull request #{number}",
+            provenance_kind=SourceProvenanceKind.PR,
+            prompt_hint=PULL_REQUEST_PROMPT_HINT,
+        )
+    if source_type == "issue":
+        ref = SourceRef(
+            raw=raw,
+            kind=SourceKind.GITHUB_ISSUE,
+            identity=f"github.issue:{number}",
+            number=number,
+        )
+        return SourceBrief(
+            ref=ref,
+            title=f"GitHub issue #{number}",
+            provenance_kind=SourceProvenanceKind.ISSUE,
+            prompt_hint=ISSUE_PROMPT_HINT,
+        )
+    raise ValidationFailed(f"unsupported GitHub source address: {raw}")
+
+
+def resolve_git_range(raw: str) -> SourceBrief:
+    revision_range = raw.removeprefix("git:range:").strip()
+    if not revision_range:
+        raise ValidationFailed("git range source requires a revision range")
+    ref = SourceRef(
+        raw=raw,
+        kind=SourceKind.GIT_RANGE,
+        identity=f"git.range:{revision_range}",
+        revision_range=revision_range,
+    )
+    return SourceBrief(
+        ref=ref,
+        title=f"Git range {revision_range}",
+        provenance_kind=SourceProvenanceKind.GIT,
+        prompt_hint=GIT_RANGE_PROMPT_HINT,
+    )
+
+
+def resolve_git_diff(raw: str) -> SourceBrief:
+    target = raw.removeprefix("git:diff").removeprefix(":").strip() or "working-tree"
+    ref = SourceRef(
+        raw=raw,
+        kind=SourceKind.GIT_DIFF,
+        identity=f"git.diff:{target}",
+        revision_range=target,
+    )
+    return SourceBrief(
+        ref=ref,
+        title=f"Git diff {target}",
+        provenance_kind=SourceProvenanceKind.GIT,
+        prompt_hint=GIT_DIFF_PROMPT_HINT,
+    )
+
+
+def resolve_transcript(raw: str) -> SourceBrief:
+    transcript = raw.removeprefix("transcript:").strip()
+    if not transcript:
+        raise ValidationFailed("transcript source requires an identifier or path")
+    ref = SourceRef(
+        raw=raw,
+        kind=SourceKind.TRANSCRIPT,
+        identity=f"transcript:{transcript}",
+        transcript=transcript,
+    )
+    return SourceBrief(
+        ref=ref,
+        title=f"Transcript {transcript}",
+        provenance_kind=SourceProvenanceKind.TRANSCRIPT,
+        prompt_hint=(
+            "Inspect the transcript structurally and preserve only reusable "
+            "project knowledge."
+        ),
+    )
+
+
+def resolve_url(raw: str) -> SourceBrief:
+    url = normalize_http_url(raw)
+    github = parse_github_url(raw, url)
+    if github is not None:
+        return github
+    ref = SourceRef(
+        raw=raw,
+        kind=SourceKind.WEB_URL,
+        identity=url,
+        url=url,
+    )
+    return SourceBrief(
+        ref=ref,
+        title=url,
+        provenance_kind=SourceProvenanceKind.URL,
+        prompt_hint=WEB_PROMPT_HINT,
+    )
+
+
+def normalize_http_url(raw: str) -> str:
+    parsed = urlsplit(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValidationFailed(f"invalid URL source address: {raw}")
+    try:
+        return str(HTTP_URL_ADAPTER.validate_python(raw))
+    except ValidationError as error:
+        raise ValidationFailed(f"invalid URL source address: {raw}") from error
+
+
+def parse_github_url(raw: str, url: str) -> SourceBrief | None:
+    parsed = urlsplit(url)
+    if parsed.netloc.casefold() != "github.com":
+        return None
+    parts = [part for part in parsed.path.split("/") if part]
+    if len(parts) < 4:
+        return None
+    owner, repo, source_type, number_text = parts[:4]
+    if source_type not in {"pull", "issues"}:
+        return None
+    number = parse_positive_int(number_text, raw)
+    repository = f"{owner}/{repo}"
+    if source_type == "pull":
+        url = f"https://github.com/{repository}/pull/{number}"
+        ref = SourceRef(
+            raw=raw,
+            kind=SourceKind.GITHUB_PULL_REQUEST,
+            identity=f"github.pull_request:{repository}#{number}",
+            url=url,
+            repository=repository,
+            number=number,
+        )
+        return SourceBrief(
+            ref=ref,
+            title=f"{repository} pull request #{number}",
+            provenance_kind=SourceProvenanceKind.PR,
+            prompt_hint=PULL_REQUEST_PROMPT_HINT,
+        )
+    url = f"https://github.com/{repository}/issues/{number}"
+    ref = SourceRef(
+        raw=raw,
+        kind=SourceKind.GITHUB_ISSUE,
+        identity=f"github.issue:{repository}#{number}",
+        url=url,
+        repository=repository,
+        number=number,
+    )
+    return SourceBrief(
+        ref=ref,
+        title=f"{repository} issue #{number}",
+        provenance_kind=SourceProvenanceKind.ISSUE,
+        prompt_hint=ISSUE_PROMPT_HINT,
+    )
+
+
+def resolve_path(raw: str, cwd: Path) -> SourceBrief:
+    path = resolve_user_path(raw, cwd)
+    if path.is_dir():
+        kind = SourceKind.PATH_DIRECTORY
+        provenance_kind = SourceProvenanceKind.DIRECTORY
+        title = f"Directory {path}"
+        prompt_hint = DIRECTORY_PROMPT_HINT
+        fingerprint = None
+    elif path.is_file():
+        kind = SourceKind.PATH_FILE
+        provenance_kind = SourceProvenanceKind.FILE
+        title = f"File {path}"
+        prompt_hint = FILE_PROMPT_HINT
+        fingerprint = file_fingerprint(path)
+    else:
+        kind = SourceKind.PATH_UNKNOWN
+        provenance_kind = SourceProvenanceKind.MISSING_PATH
+        title = f"Missing path {path}"
+        prompt_hint = MISSING_PATH_PROMPT_HINT
+        fingerprint = None
+    ref = SourceRef(
+        raw=raw,
+        kind=kind,
+        identity=f"{kind.value}:{path}",
+        path=path,
+        exists=path.exists(),
+        fingerprint=fingerprint,
+    )
+    return SourceBrief(
+        ref=ref,
+        title=title,
+        provenance_kind=provenance_kind,
+        prompt_hint=prompt_hint,
+    )
+
+
+def resolve_user_path(raw: str, cwd: Path) -> Path:
+    path = Path(raw).expanduser()
+    if not path.is_absolute():
+        path = cwd / path
+    return normalize_path(path)
+
+
+def file_fingerprint(path: Path) -> str | None:
+    try:
+        return sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+def parse_positive_int(value: str, raw: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as error:
+        raise ValidationFailed(f"source number must be positive: {raw}") from error
+    if parsed < 1:
+        raise ValidationFailed(f"source number must be positive: {raw}")
+    return parsed

codealmanac/services/tagging/__init__.py

@@ -0,0 +1 @@
+

codealmanac/services/tagging/models.py

@@ -0,0 +1,9 @@
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class TaggingResult(CodeAlmanacModel):
+    slug: str
+    requested_topics: tuple[str, ...]
+    topics_before: tuple[str, ...]
+    topics_after: tuple[str, ...]
+    changed_topics: tuple[str, ...]

codealmanac/services/tagging/requests.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+from typing import Any
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.slug import to_kebab_case
+from codealmanac.core.text import required_text
+
+
+class TagPageRequest(CodeAlmanacModel):
+    cwd: Path
+    slug: str
+    topics: tuple[str, ...]
+    wiki: str | None = None
+
+    @field_validator("slug")
+    @classmethod
+    def require_slug(cls, value: str) -> str:
+        return required_text(value, "page")
+
+    @field_validator("topics", mode="before")
+    @classmethod
+    def canonical_topics(cls, value: Any) -> tuple[str, ...]:
+        if not isinstance(value, list | tuple):
+            raise ValueError("topics must not be empty")
+        topics = tuple(dict.fromkeys(to_kebab_case(str(item)) for item in value))
+        topics = tuple(topic for topic in topics if topic)
+        if not topics:
+            raise ValueError("topics must not be empty")
+        return topics
+
+
+class UntagPageRequest(TagPageRequest):
+    pass

codealmanac/services/tagging/service.py

@@ -0,0 +1,43 @@
+from codealmanac.services.pages.requests import ShowPageRequest
+from codealmanac.services.pages.service import PagesService
+from codealmanac.services.tagging.models import TaggingResult
+from codealmanac.services.tagging.requests import TagPageRequest, UntagPageRequest
+from codealmanac.services.wiki.frontmatter_rewrite import rewrite_page_topics
+
+
+class TaggingService:
+    def __init__(self, pages: PagesService):
+        self.pages = pages
+
+    def tag(self, request: TagPageRequest) -> TaggingResult:
+        page = self.pages.show(
+            ShowPageRequest(cwd=request.cwd, wiki=request.wiki, slug=request.slug)
+        )
+        before = page.topics
+        after = tuple(dict.fromkeys((*before, *request.topics)))
+        rewrite_page_topics(page.file_path, after)
+        changed = tuple(topic for topic in after if topic not in before)
+        return TaggingResult(
+            slug=page.slug,
+            requested_topics=request.topics,
+            topics_before=before,
+            topics_after=after,
+            changed_topics=changed,
+        )
+
+    def untag(self, request: UntagPageRequest) -> TaggingResult:
+        page = self.pages.show(
+            ShowPageRequest(cwd=request.cwd, wiki=request.wiki, slug=request.slug)
+        )
+        before = page.topics
+        remove = set(request.topics)
+        after = tuple(topic for topic in before if topic not in remove)
+        rewrite_page_topics(page.file_path, after)
+        changed = tuple(topic for topic in before if topic not in after)
+        return TaggingResult(
+            slug=page.slug,
+            requested_topics=request.topics,
+            topics_before=before,
+            topics_after=after,
+            changed_topics=changed,
+        )

codealmanac/services/topics/__init__.py

@@ -0,0 +1 @@
+

codealmanac/services/topics/models.py

@@ -0,0 +1,36 @@
+from enum import StrEnum
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class TopicMutationAction(StrEnum):
+    CREATED = "created"
+    UPDATED = "updated"
+    DESCRIBED = "described"
+    LINKED = "linked"
+    ALREADY_LINKED = "already_linked"
+    UNLINKED = "unlinked"
+    NO_EDGE = "no_edge"
+    RENAMED = "renamed"
+    UNCHANGED = "unchanged"
+    DELETED = "deleted"
+
+
+class TopicMutationResult(CodeAlmanacModel):
+    action: TopicMutationAction
+    slug: str
+    parents: tuple[str, ...] = ()
+    description: str | None = None
+
+
+class TopicEdgeMutationResult(CodeAlmanacModel):
+    action: TopicMutationAction
+    child: str
+    parent: str
+
+
+class TopicRewriteMutationResult(CodeAlmanacModel):
+    action: TopicMutationAction
+    slug: str
+    new_slug: str | None = None
+    pages_updated: int = 0

codealmanac/services/topics/requests.py

@@ -0,0 +1,115 @@
+from pathlib import Path
+from typing import Any
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.slug import to_kebab_case
+from codealmanac.core.text import required_text
+
+
+class ListTopicsRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = None
+
+
+class ShowTopicRequest(CodeAlmanacModel):
+    cwd: Path
+    slug: str
+    wiki: str | None = None
+    include_descendants: bool = False
+
+    @field_validator("slug")
+    @classmethod
+    def require_slug(cls, value: str) -> str:
+        return required_text(value, "topic")
+
+
+class CreateTopicRequest(CodeAlmanacModel):
+    cwd: Path
+    name: str
+    parents: tuple[str, ...] = ()
+    wiki: str | None = None
+
+    @field_validator("name")
+    @classmethod
+    def require_name(cls, value: str) -> str:
+        return required_text(value, "topic")
+
+    @field_validator("parents", mode="before")
+    @classmethod
+    def canonical_parents(cls, value: Any) -> tuple[str, ...]:
+        if value is None:
+            return ()
+        if not isinstance(value, list | tuple):
+            raise ValueError("parents must be a list")
+        parents = tuple(dict.fromkeys(to_kebab_case(str(item)) for item in value))
+        return tuple(parent for parent in parents if parent)
+
+
+class DescribeTopicRequest(CodeAlmanacModel):
+    cwd: Path
+    slug: str
+    description: str
+    wiki: str | None = None
+
+    @field_validator("slug")
+    @classmethod
+    def require_slug(cls, value: str) -> str:
+        slug = to_kebab_case(required_text(value, "topic"))
+        if not slug:
+            raise ValueError("topic must contain slug-able characters")
+        return slug
+
+    @field_validator("description")
+    @classmethod
+    def normalize_description(cls, value: str) -> str:
+        return value.strip()
+
+
+class LinkTopicRequest(CodeAlmanacModel):
+    cwd: Path
+    child: str
+    parent: str
+    wiki: str | None = None
+
+    @field_validator("child", "parent")
+    @classmethod
+    def canonical_topic(cls, value: str) -> str:
+        slug = to_kebab_case(required_text(value, "topic"))
+        if not slug:
+            raise ValueError("topic must contain slug-able characters")
+        return slug
+
+
+class UnlinkTopicRequest(LinkTopicRequest):
+    pass
+
+
+class RenameTopicRequest(CodeAlmanacModel):
+    cwd: Path
+    old_slug: str
+    new_slug: str
+    wiki: str | None = None
+
+    @field_validator("old_slug", "new_slug")
+    @classmethod
+    def canonical_topic(cls, value: str) -> str:
+        slug = to_kebab_case(required_text(value, "topic"))
+        if not slug:
+            raise ValueError("topic must contain slug-able characters")
+        return slug
+
+
+class DeleteTopicRequest(CodeAlmanacModel):
+    cwd: Path
+    slug: str
+    wiki: str | None = None
+
+    @field_validator("slug")
+    @classmethod
+    def canonical_topic(cls, value: str) -> str:
+        slug = to_kebab_case(required_text(value, "topic"))
+        if not slug:
+            raise ValueError("topic must contain slug-able characters")
+        return slug