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,
}