quilchoom 0.1.0__py3-none-any.whl

quilchoom/__init__.py

@@ -0,0 +1,3 @@
+"""
+Quilchoom development documentation and evidence system.
+"""

quilchoom/application/__init__.py

@@ -0,0 +1 @@
+"""Application use cases for Quilchoom."""

quilchoom/application/apply_correction.py

@@ -0,0 +1,75 @@
+"""
+Applies corrections to existing knowledge claims.
+"""
+
+from uuid import UUID
+
+from quilchoom.application.errors import (
+    CorrectionProjectMismatchError,
+    SelfReplacementError,
+)
+from quilchoom.domain.correction import Correction
+from quilchoom.domain.knowledge_claim import ClaimStatus
+from quilchoom.infrastructure.database.errors import KnowledgeClaimNotFoundError
+from quilchoom.infrastructure.database.repositories import (
+    CorrectionRepository,
+    KnowledgeClaimRepository,
+)
+
+
+def apply_correction(
+    project_id: UUID,
+    target_claim_id: UUID,
+    reason: str,
+    claim_repository: KnowledgeClaimRepository,
+    correction_repository: CorrectionRepository,
+    replacement_claim_id: UUID | None = None,
+) -> Correction:
+    target_claim = claim_repository.get_by_id(target_claim_id)
+
+    if target_claim is None:
+        raise KnowledgeClaimNotFoundError(
+            f"Target knowledge claim not found: {target_claim_id}"
+        )
+
+    if target_claim.project_id != project_id:
+        raise CorrectionProjectMismatchError(
+            f"Target knowledge claim belongs to a different project: {target_claim.project_id}"
+        )
+
+    if replacement_claim_id is not None:
+        if replacement_claim_id == target_claim_id:
+            raise SelfReplacementError(
+                f"Claim cannot be used as its own replacement: {replacement_claim_id}"
+            )
+
+        replacement_claim = claim_repository.get_by_id(replacement_claim_id)
+
+        if replacement_claim is None:
+            raise KnowledgeClaimNotFoundError(
+                f"Replacement knowledge claim not found: {replacement_claim_id}"
+            )
+
+        if replacement_claim.project_id != project_id:
+            raise CorrectionProjectMismatchError(
+                f"Replacement knowledge claim belongs to a different project: {replacement_claim.project_id}"
+            )
+
+    if replacement_claim_id is not None:
+        new_status = ClaimStatus.CORRECTED
+    else:
+        new_status = ClaimStatus.INVALIDATED
+
+    correction = Correction(
+        project_id=project_id,
+        target_claim_id=target_claim.id,
+        reason=reason,
+        replacement_claim_id=replacement_claim_id,
+    )
+
+    correction_repository.save_with_claim_status_update(
+        correction=correction,
+        status=new_status,
+    )
+
+    return correction

quilchoom/application/capture_commit.py

@@ -0,0 +1,68 @@
+"""
+Captures a Git commit as an Event and its supporting Evidence.
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from quilchoom.domain.event import Event
+from quilchoom.domain.evidence import Evidence
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.database.repositories import (
+    EventRepository,
+    EvidenceRepository,
+)
+from quilchoom.infrastructure.git.repository import inspect_commit
+
+
+def capture_commit(
+    project: Project,
+    repository_path: Path,
+    commit_sha: str,
+    event_repository: EventRepository,
+    evidence_repository: EvidenceRepository,
+) -> tuple[Event, Evidence]:
+    commit = inspect_commit(repository_path, commit_sha)
+
+    existing_event = event_repository.get_by_source_reference(
+        project.id,
+        "git",
+        commit.sha,
+    )
+
+    existing_evidence = evidence_repository.get_by_reference(
+        project.id,
+        "git",
+        commit.sha,
+    )
+
+    if existing_event is not None and existing_evidence is not None:
+        return existing_event, existing_evidence
+
+    event = existing_event or Event(
+        project_id=project.id,
+        type="git_commit",
+        timestamp=commit.timestamp,
+        summary=commit.message,
+        source="git",
+        source_reference=commit.sha,
+    )
+    evidence = existing_evidence or Evidence(
+        project_id=project.id,
+        type="git_diff",
+        content=commit.diff,
+        reference=commit.sha,
+        captured_at=datetime.now(UTC),
+        source="git",
+    )
+
+    if existing_event is None and existing_evidence is None:
+        event_repository.save_with_evidence(event, evidence)
+
+    elif existing_event is None:
+        event_repository.save(event)
+
+    elif existing_evidence is None:
+        evidence_repository.save(evidence)
+
+    return event, evidence

quilchoom/application/capture_repository.py

@@ -0,0 +1,53 @@
+"""
+Captures uncaptured Git commits for a Quilchoom project.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from quilchoom.application.capture_commit import capture_commit
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.database.repositories import (
+    EventRepository,
+    EvidenceRepository,
+)
+from quilchoom.infrastructure.git.repository import list_commit_shas
+
+
+@dataclass(frozen=True)
+class CaptureResult:
+    """Represents the result of capturing repository development activity."""
+
+    discovered_commits: int
+    captured_commits: int
+
+
+def capture_repository(
+    project: Project,
+    repository_path: Path,
+    event_repository: EventRepository,
+    evidence_repository: EvidenceRepository,
+) -> CaptureResult:
+    commit_shas = list_commit_shas(repository_path)
+
+    existing_evidence = evidence_repository.list_for_project(project.id)
+
+    references = {
+        evidence.reference for evidence in existing_evidence if evidence.source == "git"
+    }
+
+    uncaptured = [sha for sha in commit_shas if sha not in references]
+
+    for sha in uncaptured:
+        capture_commit(
+            project=project,
+            repository_path=repository_path,
+            commit_sha=sha,
+            event_repository=event_repository,
+            evidence_repository=evidence_repository,
+        )
+
+    return CaptureResult(
+        discovered_commits=len(commit_shas),
+        captured_commits=len(uncaptured),
+    )

quilchoom/application/check_document_staleness.py

@@ -0,0 +1,26 @@
+"""
+Determines whether a document version relies on outdated knowledge claims.
+"""
+
+from quilchoom.domain.document import DocumentVersion
+from quilchoom.domain.knowledge_claim import ClaimStatus
+from quilchoom.infrastructure.database.errors import KnowledgeClaimNotFoundError
+from quilchoom.infrastructure.database.repositories import KnowledgeClaimRepository
+
+
+def is_document_version_stale(
+    version: DocumentVersion,
+    claim_repository: KnowledgeClaimRepository,
+) -> bool:
+    for claim_id in version.claim_ids:
+        claim = claim_repository.get_by_id(claim_id)
+
+        if claim is None:
+            raise KnowledgeClaimNotFoundError(
+                f"Knowledge claim referenced by document version not found: {claim_id}"
+            )
+
+        if claim.status != ClaimStatus.ACTIVE:
+            return True
+
+    return False

quilchoom/application/check_knowledge_status.py

@@ -0,0 +1,24 @@
+"""
+Determines whether a project has captured evidence awaiting interpretation.
+"""
+
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.database.repositories import (
+    EvidenceRepository,
+    InterpretationRunRepository,
+)
+
+
+def count_pending_evidence(
+    project: Project,
+    evidence_repository: EvidenceRepository,
+    run_repository: InterpretationRunRepository,
+) -> int:
+    """Counts captured evidence that has not yet been interpreted."""
+
+    evidence = evidence_repository.list_for_project(project.id)
+    interpreted_ids = run_repository.list_interpreted_evidence_ids(project.id)
+
+    pending_ids = {item.id for item in evidence if item.id not in interpreted_ids}
+
+    return len(pending_ids)

quilchoom/application/create_document_version.py

@@ -0,0 +1,45 @@
+"""
+Creates new versions of existing documentation artifacts.
+"""
+
+from uuid import UUID
+
+from quilchoom.domain.document import DocumentVersion, DocumentVersionOrigin
+from quilchoom.infrastructure.database.errors import DocumentNotFoundError
+from quilchoom.infrastructure.database.repositories import (
+    DocumentRepository,
+    DocumentVersionRepository,
+)
+
+
+def create_document_version(
+    document_id: UUID,
+    content: str,
+    origin: DocumentVersionOrigin,
+    claim_ids: list[UUID],
+    document_repository: DocumentRepository,
+    version_repository: DocumentVersionRepository,
+) -> DocumentVersion:
+    target_document = document_repository.get_by_id(document_id)
+
+    if target_document is None:
+        raise DocumentNotFoundError(f"Target document not found: {document_id}")
+
+    latest_version = version_repository.get_latest(document_id)
+
+    if latest_version is not None:
+        version_number = latest_version.version_number + 1
+
+    else:
+        version_number = 1
+
+    version = DocumentVersion(
+        document_id=document_id,
+        version_number=version_number,
+        content=content,
+        origin=origin,
+        claim_ids=claim_ids,
+    )
+    version_repository.save(version)
+
+    return version

quilchoom/application/errors.py

@@ -0,0 +1,47 @@
+"""
+Defines application-level errors for Quilchoom.
+"""
+
+
+class ProjectInitializationError(Exception):
+    """Raised when a Quilchoom project cannot be initialized."""
+
+
+class ProjectRuntimeError(Exception):
+    """Raised when an existing Quilchoom project cannot be loaded."""
+
+
+class HistoryReconstructionError(Exception):
+    """Raised when a project's development history cannot be reconstructed."""
+
+
+class CorrectionProjectMismatchError(Exception):
+    """Raised when a correction references a claim from another project."""
+
+
+class SelfReplacementError(Exception):
+    """Raised when a claim is used as its own replacement."""
+
+
+class InterpretationProjectMismatchError(Exception):
+    """Raised when interpretation inputs belong to different projects."""
+
+
+class InvalidCandidateEvidenceError(Exception):
+    """Raised when an interpretation candidate references unavailable evidence."""
+
+
+class NoActiveClaimsError(Exception):
+    """Raised when document generation has no active knowledge claims."""
+
+
+class InvalidGeneratedClaimError(Exception):
+    """Raised when generated document provenance references an unavailable claim."""
+
+
+class DocumentUnavailableError(Exception):
+    """Raised when a requested project document has not been generated."""
+
+
+class DocumentVersionUnavailableError(Exception):
+    """Raised when a requested document version does not exist."""

quilchoom/application/generate_document.py

@@ -0,0 +1,84 @@
+"""
+Generates documentation artifacts from active project knowledge.
+"""
+
+from quilchoom.application.create_document_version import create_document_version
+from quilchoom.application.errors import InvalidGeneratedClaimError, NoActiveClaimsError
+from quilchoom.domain.document import Document, DocumentVersion, DocumentVersionOrigin
+from quilchoom.domain.knowledge_claim import ClaimStatus
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.database.repositories import (
+    DocumentRepository,
+    DocumentVersionRepository,
+    KnowledgeClaimRepository,
+)
+from quilchoom.interfaces.document_generator import (
+    DocumentGenerationContext,
+    DocumentGenerator,
+)
+
+
+def generate_document(
+    project: Project,
+    key: str,
+    kind: str,
+    generator: DocumentGenerator,
+    document_repository: DocumentRepository,
+    version_repository: DocumentVersionRepository,
+    claim_repository: KnowledgeClaimRepository,
+) -> DocumentVersion:
+    existing_document = document_repository.get_by_key(project.id, key)
+
+    if existing_document is None:
+        document = Document(
+            project_id=project.id,
+            key=key,
+            kind=kind,
+        )
+
+    else:
+        document = existing_document
+
+    claims = claim_repository.list_for_project(project.id)
+    active_claims = [claim for claim in claims if claim.status == ClaimStatus.ACTIVE]
+
+    if not active_claims:
+        raise NoActiveClaimsError(
+            f"No active knowledge claims available for project: {project.id}"
+        )
+
+    context = DocumentGenerationContext(
+        project=project,
+        document=document,
+        claims=active_claims,
+    )
+    result = generator.generate(context)
+
+    allowed_claim_ids = {claim.id for claim in active_claims}
+
+    for claim_id in result.claim_ids:
+        if claim_id not in allowed_claim_ids:
+            raise InvalidGeneratedClaimError(
+                f"Generated document references unavailable claim: {claim_id}"
+            )
+
+    if existing_document is None:
+        version = DocumentVersion(
+            document_id=document.id,
+            version_number=1,
+            content=result.content,
+            origin=DocumentVersionOrigin.GENERATED,
+            claim_ids=result.claim_ids,
+        )
+        document_repository.save_with_initial_version(document, version)
+
+        return version
+
+    return create_document_version(
+        document_id=document.id,
+        content=result.content,
+        origin=DocumentVersionOrigin.GENERATED,
+        claim_ids=result.claim_ids,
+        document_repository=document_repository,
+        version_repository=version_repository,
+    )

quilchoom/application/get_document_version.py

@@ -0,0 +1,48 @@
+"""
+Retrieves a requested version of a project document.
+"""
+
+from quilchoom.application.errors import (
+    DocumentUnavailableError,
+    DocumentVersionUnavailableError,
+)
+from quilchoom.domain.document import DocumentVersion
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.database.repositories import (
+    DocumentRepository,
+    DocumentVersionRepository,
+)
+
+
+def get_document_version(
+    project: Project,
+    key: str,
+    version_number: int | None,
+    document_repository: DocumentRepository,
+    version_repository: DocumentVersionRepository,
+) -> DocumentVersion:
+    """Retrieves the latest or requested version of a project document."""
+
+    document = document_repository.get_by_key(project_id=project.id, key=key)
+
+    if document is None:
+        raise DocumentUnavailableError(f"Document not found: {key}")
+
+    if version_number is None:
+        version = version_repository.get_latest(document_id=document.id)
+
+    else:
+        version = version_repository.get_by_version_number(
+            document_id=document.id, version_number=version_number
+        )
+
+    if version is None:
+        if version_number is None:
+            raise DocumentVersionUnavailableError("Latest document version not found")
+
+        else:
+            raise DocumentVersionUnavailableError(
+                f"Document version not found: {version_number}"
+            )
+
+    return version

quilchoom/application/get_project_status.py

@@ -0,0 +1,110 @@
+"""
+Determines the current local workflow status of a Quilchoom project.
+"""
+
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from quilchoom.application.check_document_staleness import (
+    is_document_version_stale,
+)
+from quilchoom.application.check_knowledge_status import count_pending_evidence
+from quilchoom.domain.knowledge_claim import ClaimStatus
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.database.repositories import (
+    DocumentRepository,
+    DocumentVersionRepository,
+    EvidenceRepository,
+    InterpretationRunRepository,
+    KnowledgeClaimRepository,
+)
+from quilchoom.infrastructure.git.repository import list_commit_shas
+
+
+class DocumentState(str, Enum):
+    """Defines the freshness state of a generated project document."""
+
+    CURRENT = "current"
+    STALE = "stale"
+
+
+class DocumentStatus(BaseModel):
+    """Represents the current status of a generated project document."""
+
+    key: str
+    kind: str
+    version_number: int
+    state: DocumentState
+
+
+class ProjectStatus(BaseModel):
+    """Represents the current local workflow status of a Quilchoom project."""
+
+    total_commits: int
+    pending_commits: int
+    pending_evidence: int
+    active_claims: int
+    documents: list[DocumentStatus]
+
+
+def get_project_status(
+    project: Project,
+    repository_root: Path,
+    evidence_repository: EvidenceRepository,
+    run_repository: InterpretationRunRepository,
+    claim_repository: KnowledgeClaimRepository,
+    document_repository: DocumentRepository,
+    version_repository: DocumentVersionRepository,
+) -> ProjectStatus:
+    """Determines the current local workflow status of a project."""
+
+    commit_shas = list_commit_shas(repository_root)
+
+    evidence = evidence_repository.list_for_project(project.id)
+
+    captured_commit_shas = {item.reference for item in evidence if item.source == "git"}
+
+    total_commits = len(commit_shas)
+    pending_commits = sum(1 for sha in commit_shas if sha not in captured_commit_shas)
+
+    pending_evidence = count_pending_evidence(
+        project=project,
+        evidence_repository=evidence_repository,
+        run_repository=run_repository,
+    )
+
+    claims = claim_repository.list_for_project(project.id)
+    active_claims = sum(1 for claim in claims if claim.status == ClaimStatus.ACTIVE)
+
+    documents = document_repository.list_for_project(project.id)
+
+    document_statuses: list[DocumentStatus] = []
+
+    for document in documents:
+        latest_version = version_repository.get_latest(document.id)
+
+        if latest_version is None:
+            continue
+
+        stale = is_document_version_stale(
+            version=latest_version,
+            claim_repository=claim_repository,
+        )
+
+        document_status = DocumentStatus(
+            key=document.key,
+            kind=document.kind,
+            version_number=latest_version.version_number,
+            state=(DocumentState.STALE if stale else DocumentState.CURRENT),
+        )
+        document_statuses.append(document_status)
+
+    return ProjectStatus(
+        total_commits=total_commits,
+        pending_commits=pending_commits,
+        pending_evidence=pending_evidence,
+        active_claims=active_claims,
+        documents=document_statuses,
+    )

quilchoom/application/initialize_project.py

@@ -0,0 +1,53 @@
+"""
+Initializes a Quilchoom project from a Git repository.
+"""
+
+from pathlib import Path
+
+from quilchoom.application.errors import ProjectInitializationError
+from quilchoom.domain.project import Project
+from quilchoom.infrastructure.config import write_default_config
+from quilchoom.infrastructure.database.connection import create_database_engine
+from quilchoom.infrastructure.database.migrations import upgrade_database
+from quilchoom.infrastructure.database.repositories import ProjectRepository
+from quilchoom.infrastructure.filesystem.workspace import initialize_workspace
+from quilchoom.infrastructure.git.repository import find_repository_root
+
+
+def initialize_project(repository_path: Path | None = None) -> Project:
+    repo_root = find_repository_root(repository_path)
+
+    if repo_root is None:
+        raise ProjectInitializationError()
+
+    workspace = initialize_workspace(repo_root)
+
+    config_path = workspace / "config.toml"
+    write_default_config(config_path)
+
+    db_path = workspace / "quilchoom.db"
+    upgrade_database(db_path)
+
+    db_engine = create_database_engine(db_path)
+
+    project_repository = ProjectRepository(db_engine)
+    existing_project = project_repository.get()
+
+    if existing_project is not None:
+        if existing_project.repository_path == repo_root:
+            return existing_project
+
+        updated_project = project_repository.update_repository_path(
+            existing_project.id,
+            repo_root,
+        )
+
+        return updated_project
+
+    project = Project(
+        name=repo_root.name,
+        repository_path=repo_root,
+    )
+    project_repository.save(project)
+
+    return project