feat(staleness): add check_workspace_staleness convenience helper + bump 0.14.0 (#39)

Adds a thin public wrapper that locates `.help/` under a workspace,
loads the manifest, and runs check_staleness — returning an empty
StalenessReport when no manifest is present.

Motivates the attune-gui staleness model fix: the GUI currently uses
mtime > 14 days as a stale signal and disagrees with attune-author's
content-drift definition. With this helper, the GUI can call one
function with just a workspace path instead of duplicating the
manifest-load + `.help/` convention.

Also fixes the stale __version__ string in __init__.py (was pinned
at 0.11.1 through the 0.12/0.13 releases).

3 new tests cover: parity with the direct API, empty-report-on-missing
manifest, and features= filter passthrough.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

CHANGELOG.md

@@ -15,6 +15,18 @@ changes land, not at tag time.
 
 ### Added
 
+- **`check_workspace_staleness` public helper.** New convenience
+  wrapper that takes a workspace path, locates `.help/` under it,
+  loads the manifest, and runs `check_staleness` — returning an
+  empty `StalenessReport` when no manifest is present. Lets
+  downstream tools (attune-gui, future CLIs) ask "is this
+  workspace's templates stale?" without duplicating the
+  manifest-load + `.help/` convention. The underlying
+  `check_staleness` API is unchanged. Exported from
+  `attune_author` top-level. Also fixes the stale
+  `__version__` string in `__init__.py` (was pinned at `0.11.1`
+  through the 0.12/0.13 releases).
+
 - **Polish fact-check Phase 4 — tutorial code-fence static
   check.** Polished tutorials (`docs/tutorials/*.md`) now have
   their ```python code fences extracted, syntax-checked with

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "attune-author"
-version = "0.13.0"
+version = "0.14.0"
 description = "Documentation authoring and maintenance for the attune ecosystem — generate, maintain, and validate help content with AI assistance."
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.10"

src/attune_author/__init__.py

@@ -5,10 +5,15 @@
 attune-help (reader) and attune-ai (full dev workflows).
 """
 
-__version__ = "0.11.1"
+__version__ = "0.14.0"
 
 from attune_author.manifest import Feature, Manifest, load_manifest
-from attune_author.staleness import StalenessReport, check_staleness, compute_source_hash
+from attune_author.staleness import (
+    StalenessReport,
+    check_staleness,
+    check_workspace_staleness,
+    compute_source_hash,
+)
 
 __all__ = [
     # Manifest
@@ -18,5 +23,6 @@
     # Staleness
     "StalenessReport",
     "check_staleness",
+    "check_workspace_staleness",
     "compute_source_hash",
 ]

src/attune_author/staleness.py

@@ -22,7 +22,7 @@
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from attune_author.manifest import Feature, FeatureManifest, is_safe_feature_name
+from attune_author.manifest import Feature, FeatureManifest, is_safe_feature_name, load_manifest
 
 logger = logging.getLogger(__name__)
 
@@ -456,6 +456,40 @@ def check_staleness(
     return StalenessReport(help_entries=help_entries, doc_entries=doc_entries)
 
 
+def check_workspace_staleness(
+    workspace: str | Path,
+    features: list[str] | None = None,
+) -> StalenessReport:
+    """Check staleness for a workspace using the conventional ``.help/`` layout.
+
+    Convenience wrapper for callers that just have a project root and
+    want the answer to "are any templates/docs out of date?" without
+    knowing the manifest loader or where ``.help/`` lives. The workspace
+    serves as both the project root (for resolving source globs) and
+    the parent of ``.help/`` (for the manifest and template hashes).
+
+    If ``<workspace>/.help/features.yaml`` is absent, returns an empty
+    report rather than raising — a workspace without a manifest has no
+    templates to be stale about.
+
+    Args:
+        workspace: Project root containing ``.help/`` (typically a git
+            repo root).
+        features: Optional list of feature names to check. Defaults to
+            all features in the manifest.
+
+    Returns:
+        StalenessReport (empty if no manifest is present).
+    """
+    root = Path(workspace)
+    help_dir = root / ".help"
+    try:
+        manifest = load_manifest(help_dir)
+    except FileNotFoundError:
+        return StalenessReport()
+    return check_staleness(manifest, help_dir, root, features=features)
+
+
 def _infer_kind(feat: Feature, path_field: str) -> str:
     """Infer the doc kind for a path field.
 

tests/test_staleness.py

@@ -12,6 +12,7 @@
     StalenessReport,
     _read_frontmatter_value,
     check_staleness,
+    check_workspace_staleness,
     compute_source_hash,
     parse_doc_footer,
 )
@@ -118,6 +119,38 @@ def test_filter_by_feature_name(self, help_dir: Path, project_root: Path) -> Non
         assert report.help_entries[0].feature == "auth"
 
 
+class TestCheckWorkspaceStaleness:
+    """Tests for check_workspace_staleness() convenience helper."""
+
+    def test_matches_direct_call(self, help_dir: Path, project_root: Path) -> None:
+        """Helper produces the same report as the explicit-args API."""
+        # help_dir fixture creates .help/ under tmp_path; project_root == tmp_path.
+        manifest = load_manifest(help_dir)
+        direct = check_staleness(manifest, help_dir, project_root)
+        via_helper = check_workspace_staleness(project_root)
+
+        assert via_helper.stale_count == direct.stale_count
+        assert sorted(e.feature for e in via_helper.help_entries) == sorted(
+            e.feature for e in direct.help_entries
+        )
+
+    def test_empty_report_when_no_manifest(self, tmp_path: Path) -> None:
+        """A workspace without .help/features.yaml yields an empty report, not a raise."""
+        report = check_workspace_staleness(tmp_path)
+
+        assert isinstance(report, StalenessReport)
+        assert report.help_entries == []
+        assert report.doc_entries == []
+        assert report.stale_count == 0
+
+    def test_propagates_feature_filter(self, help_dir: Path, project_root: Path) -> None:
+        """features= filter narrows the report just like the underlying API."""
+        report = check_workspace_staleness(project_root, features=["auth"])
+
+        assert len(report.help_entries) == 1
+        assert report.help_entries[0].feature == "auth"
+
+
 class TestProjectDocFooterStaleness:
     """Integration: project-doc generator writes a footer that check_staleness reads.