Skip to content

notque/vexjoy-agent / skills/meta/docs-sync-checker

docs-sync-checker

Verified

Detect documentation drift against filesystem state.

FileKindSize
SKILL.mdskill md11.6 KB
references/documentation-structure.mdmarkdown2.9 KB
references/integration-guide.mdmarkdown2.8 KB
references/sync-rules.mdmarkdown2.0 KB
scripts/generate_report.pyexecutablescript10.4 KB
scripts/parse_docs.pyexecutablescript10.6 KB
scripts/scan_tools.pyexecutablescript14.1 KB
scripts/validate.pyexecutablescript8.1 KB

scripts/generate_report.py

View on GitHub
#!/usr/bin/env python3
"""
Report generation script for docs-sync-checker skill.
Creates human-readable markdown reports from sync issues.
"""

__version__ = "1.0.0"

import argparse
import json
import sys
from datetime import datetime
from pathlib import Path
from typing import Any, Dict


class ReportGenerator:
    """Generate sync reports from issues data."""

    def __init__(self, strict: bool = False):
        self.strict = strict

    def generate_suggested_fix_markdown(self, issue: Dict[str, Any]) -> str:
        """Return the fix parse_docs.py attached to the issue."""
        return issue.get("suggested_fix", "")

    def generate_markdown_report(self, issues_data: Dict[str, Any], scan_results: Dict[str, Any] = None) -> str:
        """
        Generate human-readable markdown report.
        """
        issues = issues_data.get("issues", {})
        summary = issues_data.get("summary", {})

        lines = []

        # Header
        lines.append("# Documentation Sync Report")
        lines.append("")
        lines.append(f"**Generated**: {datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S')} UTC")

        if scan_results:
            lines.append(f"**Repository**: {scan_results.get('repo_root', 'N/A')}")

        # Status
        total_issues = summary.get("total_issues", 0)
        if total_issues == 0:
            lines.append("**Status**: ✅ ALL IN SYNC")
        else:
            lines.append(f"**Status**: ⚠️ {total_issues} ISSUES FOUND")

        lines.append("")

        # Summary
        lines.append("## Summary")
        lines.append("")

        if scan_results:
            total_tools = scan_results.get("summary", {}).get("total_tools", 0)
            skills_count = scan_results.get("summary", {}).get("skills_count", 0)
            agents_count = scan_results.get("summary", {}).get("agents_count", 0)
            commands_count = scan_results.get("summary", {}).get("commands_count", 0)

            lines.append(
                f"- **Total Tools**: {total_tools} ({skills_count} skills, {agents_count} agents, {commands_count} commands)"
            )

        lines.append(f"- **Missing Entries**: {summary.get('missing_entries', 0)} HIGH priority")
        lines.append(f"- **Stale Entries**: {summary.get('stale_entries', 0)} MEDIUM priority")

        if total_issues > 0 and scan_results:
            total_tools = scan_results.get("summary", {}).get("total_tools", 1)
            sync_score = ((total_tools - total_issues) / total_tools) * 100
            lines.append(
                f"- **Sync Score**: {sync_score:.0f}% ({total_tools - total_issues}/{total_tools} tools properly documented)"
            )

        lines.append("")
        lines.append("---")
        lines.append("")

        # Missing Entries
        missing = issues.get("missing_entries", [])
        if missing:
            lines.append("## ⚠️ HIGH Priority Issues")
            lines.append("")
            lines.append(f"### Missing Entries ({len(missing)})")
            lines.append("")
            lines.append("Tools exist but are NOT documented in required files:")
            lines.append("")

            for i, issue in enumerate(missing, 1):
                tool_type = issue["tool_type"].capitalize()
                tool_name = issue["tool_name"]
                tool_path = issue["tool_path"]
                missing_from = ", ".join(issue["missing_from"])

                lines.append(f"#### {i}. {tool_type}: {tool_name}")
                lines.append(f"**Path**: `{tool_path}`")
                lines.append(f"**Missing from**: {missing_from}")  # security-review: ignore (markdown report line, not SQL)  # fmt: skip
                lines.append("")

                # Suggested fixes for each location
                for location in issue["missing_from"]:
                    suggested_fix = self.generate_suggested_fix_markdown(issue)
                    if suggested_fix:
                        lines.append(f"**Suggested Fix for {location}**: {suggested_fix}")
                        lines.append("")

            lines.append("---")
            lines.append("")

        # Stale Entries
        stale = issues.get("stale_entries", [])
        if stale:
            lines.append("## MEDIUM Priority Issues")
            lines.append("")
            lines.append(f"### Stale Entries ({len(stale)})")
            lines.append("")
            lines.append("Documented tools that NO LONGER EXIST in filesystem:")
            lines.append("")

            for i, issue in enumerate(stale, 1):
                tool_type = issue["tool_type"].capitalize()
                tool_name = issue["tool_name"]
                documented_in = ", ".join(issue["documented_in"])

                lines.append(f"#### {i}. {tool_type}: {tool_name}")
                lines.append(f"**Documented in**: {documented_in}")
                lines.append("")
                lines.append("**Suggested Fix**:")
                fix = issue.get("suggested_fix") or f"Remove the entry for {tool_name} from {documented_in}"
                lines.append(f"- {fix}")
                lines.append("")

            lines.append("---")
            lines.append("")

        # Recommendations
        if total_issues > 0:
            lines.append("## Recommendations")
            lines.append("")

            if missing:
                lines.append(f"1. **Add missing entries** for new tools ({len(missing)} tools)")
            if stale:
                lines.append(f"2. **Remove stale entries** for deleted tools ({len(stale)} tools)")
            lines.append("3. **Run this check** before committing documentation changes")
            lines.append("4. **Integrate with CI/CD** to prevent future drift")
            lines.append("")
        else:
            lines.append("## Status: All Clear! ✅")
            lines.append("")
            lines.append("All tools are properly documented. No sync issues detected.")
            lines.append("")

        # Files Checked
        if issues_data.get("files_parsed"):
            lines.append("---")
            lines.append("")
            lines.append("## Files Checked")
            lines.append("")

            documented = issues_data.get("documented", {})
            for file_path, tools in documented.items():
                count = len(tools) if tools else 0
                lines.append(f"- ✅ {file_path} (parsed {count} entries)")

        # Next Steps
        if total_issues > 0:
            lines.append("")
            lines.append("---")
            lines.append("")
            lines.append("## Next Steps")
            lines.append("")
            lines.append("```bash")
            lines.append("# Review suggested fixes above")
            lines.append("# Regenerate generated catalogs; edit docs/REFERENCE.md by hand")
            lines.append("# Re-run sync checker to verify")
            lines.append(
                "python3 skills/meta/docs-sync-checker/scripts/scan_tools.py --repo-root . --output /tmp/scan.json"
            )
            lines.append(
                "python3 skills/meta/docs-sync-checker/scripts/parse_docs.py --repo-root . --scan-results /tmp/scan.json --output /tmp/issues.json"
            )
            lines.append("python3 skills/meta/docs-sync-checker/scripts/generate_report.py --issues /tmp/issues.json")
            lines.append("```")

        return "\n".join(lines)

    def generate_json_report(self, issues_data: Dict[str, Any], scan_results: Dict[str, Any] = None) -> str:
        """
        Generate machine-readable JSON report.
        """
        report = {
            "generated_at": datetime.utcnow().isoformat() + "Z",
            "summary": issues_data.get("summary", {}),
            "issues": issues_data.get("issues", {}),
            "report_version": __version__,
        }

        if scan_results:
            report["scan_summary"] = scan_results.get("summary", {})

        return json.dumps(report, indent=2, ensure_ascii=False)


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Generate documentation sync report", formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("--issues", type=Path, help="Path to issues JSON from parse_docs.py")
    parser.add_argument("--scan-results", type=Path, help="Path to scan results JSON from scan_tools.py")
    parser.add_argument("--output", type=Path, help="Output file (default: stdout)")
    parser.add_argument(
        "--format", choices=["markdown", "json"], default="markdown", help="Output format (default: markdown)"
    )
    parser.add_argument("--strict", action="store_true", help="Exit with error code if issues found (for CI/CD)")

    args = parser.parse_args()

    try:
        # Load issues data
        issues_data = {}
        if args.issues:
            with open(args.issues, "r", encoding="utf-8") as f:
                issues_data = json.load(f)
        else:
            # If no issues file, run the pipeline inline
            print("Error: --issues parameter required", file=sys.stderr)
            print("Run scan_tools.py and parse_docs.py first", file=sys.stderr)
            sys.exit(1)

        # Load scan results (optional)
        scan_results = None
        if args.scan_results:
            with open(args.scan_results, "r", encoding="utf-8") as f:
                scan_results = json.load(f)

        # Generate report
        generator = ReportGenerator(strict=args.strict)

        if args.format == "markdown":
            report_content = generator.generate_markdown_report(issues_data, scan_results)
        else:
            report_content = generator.generate_json_report(issues_data, scan_results)

        # Output report
        if args.output:
            args.output.parent.mkdir(parents=True, exist_ok=True)
            with open(args.output, "w", encoding="utf-8") as f:
                f.write(report_content)
            print(f"Report written to: {args.output}", file=sys.stderr)
        else:
            print(report_content)

        # Exit code for CI/CD
        total_issues = issues_data.get("summary", {}).get("total_issues", 0)
        if args.strict and total_issues > 0:
            print(f"\nERROR: {total_issues} sync issues found (strict mode)", file=sys.stderr)
            sys.exit(1)

        sys.exit(0)

    except Exception as e:
        print(
            json.dumps({"status": "error", "error_type": type(e).__name__, "message": str(e)}, indent=2),
            file=sys.stderr,
        )
        sys.exit(2)


if __name__ == "__main__":
    main()
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall