Newer
Older
gnexus-book / server / app / storage / freshness.py
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,
    }