campfire-cli 0.1.0__py3-none-any.whl

campfire_cli/app/document/service/document_rule_service.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.app.document.service.frontmatter_formatter import ordered_keys
+from campfire_cli.app.document.service.profile_registry import ProfileRegistry
+from campfire_cli.common.documents.document_types import prefixed_name
+from campfire_cli.common.documents.markdown import parse_document
+
+DATE_RE = re.compile(r"\d{4}-\d{2}-\d{2}")
+
+
+class DocumentRuleService:
+    """Single entry point for document and template contract validation."""
+
+    def __init__(self, type_config: dict[str, Any], schema: dict[str, Any]) -> None:
+        self._type_config = type_config
+        self._schema = schema
+        self._profiles = ProfileRegistry(type_config, schema)
+
+    def check_document(self, root: Path, path: Path) -> list[dict[str, Any]]:
+        relative = path.relative_to(root).as_posix()
+        parsed = parse_document(path.read_text(encoding="utf-8"))
+        if not parsed.has_frontmatter:
+            return [{"code": "frontmatter-missing", "path": relative}]
+        frontmatter = parsed.frontmatter
+        issues: list[dict[str, Any]] = []
+        document_type = frontmatter.get("type")
+        types = self._type_config.get("types", {})
+        if isinstance(document_type, list):
+            issues.append(
+                {
+                    "code": "document-type-multiple",
+                    "path": relative,
+                    "field": "type",
+                    "actual": document_type,
+                    "allowed": sorted(types),
+                }
+            )
+        elif not isinstance(document_type, str) or not document_type:
+            issues.append({"code": "document-type-missing", "path": relative, "field": "type"})
+        elif document_type not in types:
+            issues.append(
+                {
+                    "code": "document-type-invalid",
+                    "path": relative,
+                    "detail": str(document_type),
+                    "field": "type",
+                    "actual": document_type,
+                    "allowed": sorted(types),
+                }
+            )
+        elif not path.name.startswith(types[document_type]["prefix"]):
+            issues.append(
+                {
+                    "code": "document-prefix-mismatch",
+                    "path": relative,
+                    "detail": types[document_type]["prefix"],
+                    "field": "filename",
+                    "actual": path.name,
+                    "allowed": [types[document_type]["prefix"]],
+                }
+            )
+        elif prefixed_name(path.name, document_type, self._type_config) != path.name:
+            issues.append(
+                {
+                    "code": "document-name-bracket-category",
+                    "path": relative,
+                    "field": "filename",
+                    "actual": path.name,
+                    "allowed": [prefixed_name(path.name, document_type, self._type_config)],
+                }
+            )
+        rules = self._rules(document_type, path, frontmatter)
+        actual_order = list(frontmatter)
+        expected_order = ordered_keys(
+            [(key, []) for key in actual_order], list(rules["field_order"])
+        )
+        if actual_order != expected_order:
+            issues.append(
+                {
+                    "code": "frontmatter-field-order-invalid",
+                    "path": relative,
+                    "field": "frontmatter",
+                    "actual": actual_order,
+                    "allowed": expected_order,
+                }
+            )
+        conditional = {
+            field
+            for condition in rules["conditional_required"]
+            if all(frontmatter.get(key) == value for key, value in condition["when"].items())
+            for field in condition["require"]
+        }
+        for field in dict.fromkeys([*rules["required"], *conditional]):
+            if field not in frontmatter:
+                issues.append(
+                    {
+                        "code": "frontmatter-field-missing",
+                        "path": relative,
+                        "detail": field,
+                        "field": field,
+                    }
+                )
+                continue
+            value = frontmatter[field]
+            if value is None or value == "" or field in conditional and not value:
+                issues.append(
+                    {
+                        "code": "frontmatter-field-empty",
+                        "path": relative,
+                        "detail": field,
+                        "field": field,
+                        "actual": value,
+                    }
+                )
+        for field in frontmatter:
+            if rules["unknown_fields"] == "report" and field not in rules["allowed"]:
+                issues.append(
+                    {
+                        "code": "frontmatter-field-not-allowed",
+                        "path": relative,
+                        "detail": field,
+                        "field": field,
+                        "actual": frontmatter[field],
+                        "allowed": rules["allowed"],
+                    }
+                )
+        for field in rules["lists"]:
+            if field in frontmatter and not isinstance(frontmatter[field], list):
+                issues.append(
+                    {
+                        "code": "frontmatter-list-invalid",
+                        "path": relative,
+                        "detail": field,
+                        "field": field,
+                        "actual": frontmatter[field],
+                        "allowed": ["list"],
+                    }
+                )
+        for field in rules["dates"]:
+            value = frontmatter.get(field)
+            if value is not None and not DATE_RE.fullmatch(str(value)):
+                issues.append(
+                    {
+                        "code": "frontmatter-date-invalid",
+                        "path": relative,
+                        "detail": field,
+                        "field": field,
+                        "actual": value,
+                        "allowed": ["YYYY-MM-DD"],
+                    }
+                )
+        for field, allowed in rules["enums"].items():
+            value = frontmatter.get(field)
+            if value is not None and value not in allowed:
+                issues.append(
+                    {
+                        "code": "frontmatter-enum-invalid",
+                        "path": relative,
+                        "detail": f"{field}={value}",
+                        "field": field,
+                        "actual": value,
+                        "allowed": allowed,
+                    }
+                )
+        issues.extend(self._state_invariants(relative, path, document_type, frontmatter))
+        return issues
+
+    def check_collection(self, root: Path, paths: list[Path]) -> list[dict[str, Any]]:
+        """Validate invariants that require seeing more than one document."""
+        current_documents: dict[tuple[str, str, str, str], list[str]] = {}
+        for path in paths:
+            frontmatter = parse_document(path.read_text(encoding="utf-8")).frontmatter
+            document_type = frontmatter.get("type")
+            if document_type not in {"moc", "product-spec"}:
+                continue
+            if frontmatter.get("status") != "current":
+                continue
+            project = frontmatter.get("project")
+            domain = frontmatter.get("domain")
+            if not project or not domain:
+                continue
+            physical_domain = path.parent.relative_to(root).as_posix()
+            key = (physical_domain, str(project), str(domain), str(document_type))
+            current_documents.setdefault(key, []).append(path.relative_to(root).as_posix())
+        issues: list[dict[str, Any]] = []
+        for (_physical, project, domain, document_type), matches in sorted(
+            current_documents.items()
+        ):
+            if len(matches) < 2:
+                continue
+            issues.append(
+                {
+                    "code": "project-doc-current-conflict",
+                    "path": matches[0],
+                    "detail": f"{project}/{domain}/{document_type}",
+                    "actual": sorted(matches),
+                    "allowed": ["one-current-document"],
+                }
+            )
+        return issues
+
+    def check_templates(self, root: Path, skills_root: Path) -> list[dict[str, Any]]:
+        if not skills_root.is_dir():
+            return []
+        issues: list[dict[str, Any]] = []
+        for path in sorted(skills_root.rglob("*.md")):
+            parsed = parse_document(path.read_text(encoding="utf-8"))
+            document_type = parsed.frontmatter.get("type")
+            if not parsed.has_frontmatter or document_type not in self._type_config.get(
+                "types", {}
+            ):
+                continue
+            rules = self._rules(document_type, path, parsed.frontmatter)
+            for field, allowed in rules["enums"].items():
+                value = parsed.frontmatter.get(field)
+                if value is not None and value not in allowed:
+                    issues.append(
+                        {
+                            "code": "template-enum-invalid",
+                            "path": path.relative_to(root).as_posix(),
+                            "detail": f"{field}={value}",
+                            "field": field,
+                            "actual": value,
+                            "allowed": allowed,
+                        }
+                    )
+        return issues
+
+    def known_fields(self) -> set[str]:
+        return self._profiles.known_fields()
+
+    def validate_patch(
+        self,
+        root: Path,
+        path: Path,
+        current: dict[str, Any],
+        patch: dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        """Validate values a restructure would write, without requiring unrelated fields."""
+        merged = {**current, **patch}
+        rules = self._rules(merged.get("type"), path, merged)
+        relative = path.relative_to(root).as_posix()
+        issues: list[dict[str, Any]] = []
+        for field in patch:
+            if rules["unknown_fields"] == "report" and field not in rules["allowed"]:
+                issues.append(
+                    {
+                        "code": "frontmatter-field-not-allowed",
+                        "path": relative,
+                        "detail": field,
+                        "field": field,
+                        "actual": patch[field],
+                        "allowed": rules["allowed"],
+                    }
+                )
+        for field in rules["lists"]:
+            if field in patch and not isinstance(patch[field], list):
+                issues.append(
+                    {"code": "frontmatter-list-invalid", "path": relative, "detail": field}
+                )
+        for field in rules["dates"]:
+            value = patch.get(field)
+            if value is not None and not DATE_RE.fullmatch(str(value)):
+                issues.append(
+                    {"code": "frontmatter-date-invalid", "path": relative, "detail": field}
+                )
+        for field, allowed in rules["enums"].items():
+            value = patch.get(field)
+            if value is not None and value not in allowed:
+                issues.append(
+                    {
+                        "code": "frontmatter-enum-invalid",
+                        "path": relative,
+                        "detail": f"{field}={value}",
+                        "field": field,
+                        "actual": value,
+                        "allowed": allowed,
+                    }
+                )
+        return issues
+
+    def _rules(self, document_type: Any, path: Path, frontmatter: dict[str, Any]) -> dict[str, Any]:
+        return self._profiles.resolve(document_type, frontmatter, path).model_dump()
+
+    @staticmethod
+    def _state_invariants(
+        relative: str,
+        path: Path,
+        document_type: Any,
+        frontmatter: dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        issues: list[dict[str, Any]] = []
+        status = frontmatter.get("status")
+        lifecycle = frontmatter.get("lifecycle")
+        in_archive = "archive" in path.parts
+        if in_archive != (status == "archived" and lifecycle == "archived") and (
+            in_archive or status == "archived" or lifecycle == "archived"
+        ):
+            issues.append({"code": "document-archive-state-mismatch", "path": relative})
+        if document_type != "task":
+            return issues
+        if status == "draft":
+            issues.append({"code": "task-status-draft-invalid", "path": relative})
+        if lifecycle not in {"completed", "archived"} and frontmatter.get("completed"):
+            issues.append(
+                {
+                    "code": "task-completed-date-premature",
+                    "path": relative,
+                    "detail": str(lifecycle),
+                }
+            )
+        return issues

campfire_cli/app/document/service/document_scanner.py

@@ -0,0 +1,38 @@
+"""Discover documents in the configured managed scope."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.common.documents.document_types import safe_path
+
+
+def exempt_document(path: Path, config: dict[str, Any]) -> bool:
+    """Return whether a Markdown file is owned by another app or explicitly unmanaged."""
+    return path.name in set(config.get("exempt_basenames", []))
+
+
+def iter_documents(root: Path, config: dict[str, Any]) -> list[Path]:
+    root = root.resolve()
+    ignored = set(config.get("ignored_directories", []))
+    documents: set[Path] = set()
+    space_marker = config.get("space_marker", "_空间.md")
+    spaces = [
+        marker.parent.relative_to(root).as_posix() for marker in root.glob(f"*/{space_marker}")
+    ]
+    if spaces:
+        inboxes = [value for value in config.get("scope_roots", []) if value.startswith("_收件箱/")]
+        scope_roots = [*spaces, *inboxes]
+    else:
+        scope_roots = config.get("scope_roots", [])
+    for raw_root in scope_roots:
+        scope = safe_path(root, raw_root)
+        if not scope.exists():
+            continue
+        for path in scope.rglob("*.md"):
+            relative = path.relative_to(root)
+            if exempt_document(path, config) or any(part in ignored for part in relative.parts):
+                continue
+            documents.add(path.resolve())
+    return sorted(documents, key=lambda path: str(path.relative_to(root)).casefold())

campfire_cli/app/document/service/document_service.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.app.document.service.document_rule_service import DocumentRuleService
+from campfire_cli.app.document.service.document_scanner import exempt_document
+from campfire_cli.app.document.service.frontmatter_formatter import format_text
+from campfire_cli.app.document.service.profile_registry import ProfileRegistry
+from campfire_cli.common.documents.markdown import parse_document
+from campfire_cli.common.exceptions import ConfigurationError, GovernanceBlockedError
+from campfire_cli.common.filesystem import atomic_write, safe_path
+from campfire_cli.common.governance import capture_snapshot, optimistic_write_lock
+from campfire_cli.config.settings import WorkspaceSettings
+
+
+class DocumentService:
+    def __init__(self, settings: WorkspaceSettings) -> None:
+        self._settings = settings
+        self._rules = DocumentRuleService(settings.document_types, settings.frontmatter_schema)
+        self._profiles = ProfileRegistry(settings.document_types, settings.frontmatter_schema)
+
+    def check(self, relative_path: str) -> dict[str, Any]:
+        path = self._document_path(relative_path)
+        if self._is_exempt(path):
+            return self._not_applicable(relative_path, path)
+        issues = self._rules.check_document(self._settings.vault_root, path)
+        return {
+            "status": "ok" if not issues else "needs-review",
+            "workspace_id": self._settings.workspace_id,
+            "path": relative_path,
+            "issue_count": len(issues),
+            "issues": issues,
+        }
+
+    def inspect(self, relative_path: str) -> dict[str, Any]:
+        path = self._document_path(relative_path)
+        if self._is_exempt(path):
+            return self._not_applicable(relative_path, path)
+        parsed = parse_document(path.read_text(encoding="utf-8"))
+        document_type = parsed.frontmatter.get("type")
+        profile = self._profiles.resolve(document_type, parsed.frontmatter, path)
+        domain_id: str | None = None
+        current = path.parent
+        while current == self._settings.vault_root or self._settings.vault_root in current.parents:
+            marker = current / "_领域.md"
+            if marker.is_file():
+                value = parse_document(marker.read_text(encoding="utf-8")).frontmatter.get(
+                    "domain_id"
+                )
+                domain_id = value if isinstance(value, str) else None
+                break
+            if current == self._settings.vault_root:
+                break
+            current = current.parent
+        issues = self._rules.check_document(self._settings.vault_root, path)
+        return {
+            "status": "ok" if not issues else "needs-review",
+            "workspace_id": self._settings.workspace_id,
+            "path": relative_path,
+            "domain_id": domain_id,
+            "type": document_type if isinstance(document_type, str) else None,
+            "profile": profile.model_dump(),
+            "issues": issues,
+        }
+
+    def format(self, relative_path: str, confirm: bool = False) -> dict[str, Any]:
+        path = self._document_path(relative_path)
+        if self._is_exempt(path):
+            return self._not_applicable(relative_path, path)
+        original = path.read_text(encoding="utf-8")
+        parsed = parse_document(original)
+        if not parsed.has_frontmatter:
+            return {
+                "status": "blocked",
+                "workspace_id": self._settings.workspace_id,
+                "path": relative_path,
+                "write_performed": False,
+                "issues": [{"code": "frontmatter-missing", "path": relative_path}],
+            }
+        profile = self._profiles.resolve(parsed.frontmatter.get("type"), parsed.frontmatter, path)
+        formatted, errors = format_text(original, list(profile.field_order))
+        if errors:
+            return {
+                "status": "blocked",
+                "workspace_id": self._settings.workspace_id,
+                "path": relative_path,
+                "write_performed": False,
+                "issues": [{"code": code, "path": relative_path} for code in errors],
+            }
+        changed = formatted != original
+        if changed and confirm:
+            snapshot = capture_snapshot(self._settings.vault_root, [path])
+            with optimistic_write_lock(
+                self._settings.state_root, snapshot, self._settings.vault_root
+            ) as concurrent:
+                if concurrent:
+                    raise GovernanceBlockedError(
+                        "文档在格式化期间发生变化：" + ", ".join(concurrent)
+                    )
+                atomic_write(path, formatted)
+        return {
+            "status": "formatted" if changed and confirm else "planned" if changed else "current",
+            "workspace_id": self._settings.workspace_id,
+            "path": relative_path,
+            "profile": profile.name,
+            "write_performed": changed and confirm,
+        }
+
+    def _document_path(self, relative_path: str) -> Path:
+        path = safe_path(self._settings.vault_root, relative_path)
+        if not path.is_file() or path.suffix.lower() != ".md":
+            raise ConfigurationError(f"Markdown 文档不存在：{relative_path}")
+        return path
+
+    def _not_applicable(self, relative_path: str, path: Path) -> dict[str, Any]:
+        marker_commands = {
+            self._settings.governance.get("space_marker", "_空间.md"): "workspace space check",
+            self._settings.governance.get("domain_marker", "_领域.md"): "workspace domain check",
+        }
+        return {
+            "status": "not-applicable",
+            "workspace_id": self._settings.workspace_id,
+            "path": relative_path,
+            "reason": "document-exempt",
+            "owner_command": marker_commands.get(path.name),
+            "issues": [],
+        }
+
+    def _is_exempt(self, path: Path) -> bool:
+        relative = path.relative_to(self._settings.vault_root)
+        collaboration_root = self._settings.governance.get("collaboration_root", "_协作")
+        if relative.parts and relative.parts[0] == collaboration_root:
+            return True
+        markers = {
+            self._settings.governance.get("space_marker", "_空间.md"),
+            self._settings.governance.get("domain_marker", "_领域.md"),
+        }
+        return path.name in markers or exempt_document(path, self._settings.document_types)

campfire_cli/app/document/service/document_type_service.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+from campfire_cli.app.document.repository.document_type_repository import (
+    DocumentTypeRepository,
+)
+
+
+class DocumentTypeService:
+    def __init__(
+        self,
+        workspace_id: str,
+        repository: DocumentTypeRepository,
+    ) -> None:
+        self._workspace_id = workspace_id
+        self._repository = repository
+
+    def list_types(self) -> dict[str, Any]:
+        contract = self._repository.load()
+        return {
+            "status": "ok",
+            "workspace_id": self._workspace_id,
+            "types": [
+                {"name": name, **definition}
+                for name, definition in contract.get("types", {}).items()
+            ],
+        }

campfire_cli/app/document/service/frontmatter_apply.py

@@ -0,0 +1,98 @@
+"""
+SPEC:
+  name: frontmatter_apply
+  purpose: 执行已逐字段审批的 frontmatter 治理计划
+  default_env_file: none
+  env_override: none
+  idempotent: true
+  behavior:
+    - 仅写入 approved true 且 value 非 null 的字段
+    - 保留正文与未审批字段
+  safety:
+    - 预检存在问题时不写入
+    - 不移动、改名或删除文件，不编造字段值
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.app.document.service.profile_registry import ProfileRegistry
+from campfire_cli.common.documents.document_types import safe_path, set_frontmatter_scalar
+
+
+def render(value: Any) -> str:
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, list):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+def preflight(
+    root: Path, plan: dict[str, Any], type_config: dict[str, Any], schema: dict[str, Any]
+) -> tuple[list[tuple[Path, dict[str, Any]]], list[dict[str, str]]]:
+    profiles = ProfileRegistry(type_config, schema)
+    operations = []
+    issues = []
+    for item in plan.get("items", []):
+        profile_name = item.get("profile", "base")
+        if profile_name not in {profile.name for profile in profiles.list()}:
+            issues.append(
+                {
+                    "code": "frontmatter-profile-invalid",
+                    "path": str(item.get("path", "")),
+                }
+            )
+            continue
+        allowed = set(profiles.get(profile_name).allowed)
+        try:
+            path = safe_path(root, item.get("path", ""))
+        except (ValueError, TypeError):
+            issues.append(
+                {"code": "frontmatter-plan-path-invalid", "path": str(item.get("path", ""))}
+            )
+            continue
+        approved = {
+            k: v.get("value")
+            for k, v in item.get("fields", {}).items()
+            if v.get("approved") is True
+        }
+        if not approved:
+            continue
+        if not path.is_file():
+            issues.append({"code": "frontmatter-source-missing", "path": item.get("path", "")})
+        for field, value in approved.items():
+            if field not in allowed:
+                issues.append(
+                    {
+                        "code": "frontmatter-field-unknown",
+                        "path": item.get("path", ""),
+                        "detail": field,
+                    }
+                )
+            if value is None:
+                issues.append(
+                    {
+                        "code": "frontmatter-approved-null",
+                        "path": item.get("path", ""),
+                        "detail": field,
+                    }
+                )
+        operations.append((path, approved))
+    return operations, issues
+
+
+def apply(operations: list[tuple[Path, dict[str, Any]]]) -> int:
+    changed = 0
+    for path, fields in operations:
+        original = path.read_text(encoding="utf-8")
+        updated = original
+        for field, value in fields.items():
+            updated = set_frontmatter_scalar(updated, field, render(value))
+        if updated != original:
+            path.write_text(updated, encoding="utf-8")
+            changed += 1
+    return changed