diff --git a/server/app/main.py b/server/app/main.py index c40202d..f6d4118 100644 --- a/server/app/main.py +++ b/server/app/main.py @@ -25,6 +25,7 @@ make_inventory_repository, make_pending_change_repository, ) +from .storage.freshness import build_freshness_report_db from .storage.protocols import ( DocsRepositoryProtocol, InventoryRepositoryProtocol, @@ -213,6 +214,8 @@ @app.get("/health/freshness") def freshness(settings: Settings = Depends(get_settings)) -> dict[str, object]: + if settings.storage_backend == "db": + return build_freshness_report_db(Database.from_settings(settings)) return build_freshness_report(settings) diff --git a/server/app/mcp_server.py b/server/app/mcp_server.py index 8fc4e82..0dfddd4 100644 --- a/server/app/mcp_server.py +++ b/server/app/mcp_server.py @@ -25,6 +25,7 @@ make_inventory_repository, make_pending_change_repository, ) +from .storage.freshness import build_freshness_report_db from .storage.validation import validate_database from .validation import validate_repository @@ -220,7 +221,10 @@ def check_freshness() -> dict[str, object]: """Return freshness/staleness report for deciding what documentation needs review.""" - return build_freshness_report(_settings()) + settings = _settings() + if settings.storage_backend == "db": + return build_freshness_report_db(Database.from_settings(settings)) + return build_freshness_report(settings) def git_status() -> dict[str, Any]: diff --git a/server/app/storage/freshness.py b/server/app/storage/freshness.py new file mode 100644 index 0000000..b702c69 --- /dev/null +++ b/server/app/storage/freshness.py @@ -0,0 +1,78 @@ +from __future__ import annotations + +import posixpath +from typing import Any + +from sqlalchemy import select +from sqlalchemy.orm import Session + +from ..freshness import REQUIRED_FRONTMATTER, _is_stale +from .db import Database +from .db_repositories import latest_doc_rows +from .models import Document, InventoryItem + + +def build_freshness_report_db(database: Database) -> dict[str, object]: + with database.session() as session: + return _build_report(session) + + +def _build_report(session: Session) -> dict[str, object]: + issues: list[dict[str, str]] = [] + documents = session.execute(latest_doc_rows(session)).all() + + for document, version in documents: + slug = document.slug + if slug == "README.md" or slug.startswith("server/"): + continue + + frontmatter = version.frontmatter or {} + missing = sorted(REQUIRED_FRONTMATTER - set(frontmatter)) + if missing: + issues.append( + { + "path": slug, + "severity": "warning", + "code": "missing-frontmatter-fields", + "message": "Missing frontmatter fields: " + ", ".join(missing), + } + ) + continue + + if _is_stale(str(frontmatter["last_reviewed"]), str(frontmatter["review_interval"])): + issues.append( + { + "path": slug, + "severity": "warning", + "code": "stale-document", + "message": "Document is past its review interval", + } + ) + + document_slugs = set(session.scalars(select(Document.slug)).all()) + items = session.scalars( + select(InventoryItem) + .where(InventoryItem.deleted_at.is_(None)) + .order_by(InventoryItem.type, InventoryItem.position, InventoryItem.item_id) + ).all() + for item in items: + docs_value = (item.data or {}).get("docs") + if not isinstance(docs_value, str) or not docs_value: + continue + target = posixpath.normpath(posixpath.join("40-inventory", docs_value)) + if target not in document_slugs: + issues.append( + { + "path": f"40-inventory/{item.type}.yml", + "severity": "error", + "code": "missing-doc-link-target", + "message": f"docs target does not exist: {docs_value}", + } + ) + + return { + "status": "ok" if not issues else "issues", + "document_count": len(documents), + "issue_count": len(issues), + "issues": issues, + }