feat(guide): coverage reconciler + relabel customer tabs Overview→Customer

scripts/coverage-reconcile.py diffs the code surface (services, agent modules, SPAs) against documented module keys and reports gaps — catches undocumented things (found 15 agent modules + qds-monitor). Also relabeled 63 customer tabs Overview→Customer for role-tab consistency with the fleet pilot. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-01 19:05:40 -04:00
parent 26610bb4f3
commit 871b81474d
64 changed files with 167 additions and 63 deletions
@@ -1,7 +1,7 @@
 ---
 module: analytics.adoons
 title: Adoons Insights
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: analytics.agents
 title: Agents
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: analytics.cash
 title: Cash Intelligence
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: analytics.fleet-health
 title: Fleet Health
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: analytics.incidents
 title: Incident Trends
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: analytics.transactions
 title: Transactions
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: analytics.uptime
 title: Uptime
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: aria.dashboard
 title: Threat Dashboard
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: aria.device-posture
 title: Device Posture
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: aria.ioc-feeds
 title: IOC Feeds
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: aria.ioc-management
 title: IOC Management
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: aria.precursor-alerts
 title: Precursor Alerts
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: aria.threat-events
 title: Threat Events
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: claims.claim-detail
 title: Claim Detail
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: claims.dashboard
 title: Claims Dashboard
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: claims.settings
 title: Settings
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: claims.vendors
 title: Vendors
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: dashboard.cash-stats
 title: Cash Stats
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: dashboard.overview
 title: Fleet Overview
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.agent-profile
 title: Agent Profile
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.agent-scripts
 title: Agent Scripts
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.config-audit
 title: Config Audit
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.device-detail
 title: Device Detail
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.device-groups
 title: Device Groups
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.device-list
 title: Device List
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.map
 title: Map
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: devices.sw-deploy
 title: Software Deployment
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: fleet.dashboard
 title: Fleet Dashboard
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: fleet.modules
 title: Modules
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: incident.dashboard
 title: Dashboard
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: incident.incident-management
 title: Incident Management
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: incident.incident-tracker
 title: Incident Tracker
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: incident.journal-events
 title: Journal Events
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: incident.processing-rules
 title: Processing Rules
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: msp.contact-groups
 title: Contact Groups
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: msp.institution-keys
 title: Institution Keys
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: msp.institutions
 title: Institutions
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: msp.module-allocations
 title: Module Allocations
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: msp.users
 title: Users
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: profile.appearance
 title: Appearance
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: profile.display
 title: Display
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: profile.inbox
 title: Inbox
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: profile.notifications
 title: Notifications
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: profile.profile
 title: Profile
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: profile.security
 title: Security
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: recon.atm-cycle-history
 title: ATM Cycle History
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: recon.cash-forecast
 title: Cash Forecast
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: recon.cash-reconciliation
 title: Cash Reconciliation
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: recon.device-cycle-mgmt
 title: Device Cycle Management
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: recon.recon-rules
 title: Recon Rules
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: reports.builder
 title: Report Builder
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: reports.queries
 title: Saved Queries
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: reports.runs
 title: Run History
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: reports.schedule
 title: Scheduling & Distribution
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: reports.templates
 title: Report Templates
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: transactions.browser
 title: Transactions Browser
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: transactions.customer-journey
 title: Customer Journey
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: transactions.journal-parsing
 title: Journal Parsing Rules
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: transactions.processing-rules
 title: Journal Processing Rules
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: transactions.reparse
 title: Journal Reparse
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: vault.cit-visits
 title: CIT Visits
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: vault.dashboard
 title: Dashboard
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -1,7 +1,7 @@
 ---
 module: vault.import
 title: Import
-tab: Overview
+tab: Customer
 order: 10
 audience: customer
 ---
@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Guide coverage reconciler — diffs the CODE surface against what the guide documents,
+so nothing new (a service, an SPA module, an agent module) stays undocumented.
+
+Run:  python3 hiveops-guide/scripts/coverage-reconcile.py
+Exits 1 if any gaps are found (handy for a session-start check / hook).
+"""
+import os, re, sys, glob
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))  # /source/hiveops-src
+CONTENT = os.path.join(ROOT, "hiveops-guide", "backend", "src", "main", "resources", "content")
+
+# product SPAs that should have per-module role-tab guides (app prefix in the guide)
+PRODUCT_APPS = {
+    "analytics","aria","claims","dashboard","devices","fleet","incident","msp",
+    "profile","recon","reports","transactions","vault",
+}
+# guide app-prefixes that are NOT code-derived (concept / process docs) — skip in the code diff
+NON_CODE_APPS = {"platform","technical","processes"}
+# the 5 role-tabs expected on a product module
+PRODUCT_TABS = {"Customer","Internal","Architect","Testing","Claude"}
+# dir-name (minus hiveops-) → guide app/service key, where they differ
+SERVICE_ALIAS = {"ai":"ai", "recon":"recon"}  # extend as needed
+
+
+def load_guide():
+    """module_key -> set(tab names). Reads frontmatter of every content/**/*.md."""
+    mods = {}
+    for f in glob.glob(os.path.join(CONTENT, "**", "*.md"), recursive=True):
+        txt = open(f, encoding="utf-8").read()
+        m = re.match(r"^---\n(.*?)\n---", txt, re.S)
+        if not m:
+            continue
+        fm = dict(re.findall(r"^(\w+):\s*(.+)$", m.group(1), re.M))
+        key, tab = fm.get("module"), fm.get("tab")
+        if key:
+            mods.setdefault(key, set()).add(tab)
+    return mods
+
+
+def has_backend(repo):
+    return bool(glob.glob(os.path.join(repo, "**", "src", "main", "java", "com", "hiveops"),
+                          recursive=True))
+
+
+def main():
+    guide = load_guide()
+    apps = {k.split(".")[0] for k in guide}
+    gaps = []
+
+    # 1) backend services → expect a technical.<svc> guide
+    for repo in sorted(glob.glob(os.path.join(ROOT, "hiveops-*"))):
+        name = os.path.basename(repo)
+        svc = name[len("hiveops-"):]
+        if svc in ("agent","guide","bom","security-common","template","docs","release",
+                   "devops","integration","smartjournal","tools","adoons"):  # non-service or special
+            continue
+        if not os.path.isdir(repo) or not has_backend(repo):
+            continue
+        if f"technical.{svc}" not in guide:
+            gaps.append(("SERVICE",  f"hiveops-{svc}", f"technical.{svc}"))
+
+    # 2) agent modules → expect an agent.<module> guide
+    for mod in sorted(glob.glob(os.path.join(ROOT, "hiveops-agent", "hiveops-module-*"))):
+        if not os.path.isdir(mod):
+            continue
+        slug = os.path.basename(mod)[len("hiveops-module-"):]
+        if f"agent.{slug}" not in guide:
+            gaps.append(("AGENT MODULE", os.path.basename(mod), f"agent.{slug}"))
+
+    # 3) product modules present but missing role-tabs
+    incomplete = []
+    for key, tabs in sorted(guide.items()):
+        app = key.split(".")[0]
+        if app in PRODUCT_APPS:
+            missing = PRODUCT_TABS - tabs
+            if missing:
+                incomplete.append((key, ",".join(sorted(missing))))
+
+    # 4) product SPAs with no guide content at all
+    for repo in sorted(glob.glob(os.path.join(ROOT, "hiveops-*"))):
+        app = os.path.basename(repo)[len("hiveops-"):]
+        if app in PRODUCT_APPS and app not in apps and os.path.isdir(os.path.join(repo, "frontend")):
+            gaps.append(("SPA", f"hiveops-{app}", f"{app}.* (no modules documented)"))
+
+    # ---- report ----
+    print(f"Guide coverage — {len(guide)} documented modules across {len(apps)} apps\n")
+    if gaps:
+        print(f"❌ {len(gaps)} MISSING (in code, not in guide):")
+        for kind, code, expected in gaps:
+            print(f"   [{kind}] {code}  →  needs  {expected}")
+    else:
+        print("✅ no missing services / agent modules / SPAs")
+    if incomplete:
+        print(f"\n⚠️  {len(incomplete)} product modules missing role-tabs:")
+        for key, miss in incomplete:
+            print(f"   {key}  →  missing: {miss}")
+    print()
+    sys.exit(1 if (gaps or incomplete) else 0)
+
+
+if __name__ == "__main__":
+    main()