Skip to content

Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.

14.9 KB
Raw Blame
#!/usr/bin/env python3
"""Pre-commit quality gate for blog posts.

The gate analyzes blog posts with the existing analyzer and fails when a score
is below the configured threshold.

The default threshold of 70 is the analyze_blog.py quality threshold. It is not
the 90-point delivery gate: the independent review in blog_preflight.py
(gate 4) requires an overall score of at least 90 before an article ships.

Path handling is deliberately strict:

- A file named on the command line is never silently skipped. A missing or
  unreadable path is an error, a file without blog frontmatter (a title plus a
  description or date) fails, and a file inside docs/, skills/, tests/,
  templates/ or references/ is still analyzed.
- A directory named on the command line is scanned recursively. The scan skips
  files without blog frontmatter, and skips the docs/, skills/, tests/,
  templates/ and references/ trees of the claude-blog repository itself.
- Hook mode (``--select``) and ``--staged`` receive every changed Markdown file
  from Git or pre-commit, so they apply the filter and skip non-posts.
- The docs/, skills/, tests/, templates/ and references/ exclusion applies only
  inside a checkout of claude-blog (a ``.claude-plugin/plugin.json`` named
  ``claude-blog`` above the file). In any other repository a post under docs/
  is gated like any other post.
- Whatever is skipped is counted in the output, so a pass is never silent
  about what it did not check.

Exit codes: 0 pass, 1 a post failed the gate, 2 usage error or a path that is
missing or not a file.
"""

from __future__ import annotations

import argparse
import json
import os
import subprocess
import sys
from pathlib import Path
from typing import Any

SCRIPTS_DIR = Path(__file__).resolve().parent
sys.path.insert(0, str(SCRIPTS_DIR))

import analyze_blog  # noqa: E402

DEFAULT_THRESHOLD = 70
EXCLUDED_DIRS = {"skills", "docs", "references", "templates", "tests"}
BLOG_SUFFIXES = {".md", ".mdx"}
MIN_THRESHOLD = 1
MAX_THRESHOLD = 100
MISSING_FRONTMATTER = (
    "missing blog frontmatter: a post needs a title plus a description or date"
)


def _is_claude_blog_root(directory: Path) -> bool:
    """Return True when directory is the root of a claude-blog checkout."""
    manifest = directory / ".claude-plugin" / "plugin.json"
    try:
        data = json.loads(manifest.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, ValueError):
        return False
    return isinstance(data, dict) and data.get("name") == "claude-blog"


def _find_claude_blog_root(path: Path) -> Path | None:
    """Return the claude-blog checkout root above path (lexically), if any."""
    absolute_path = Path(os.path.abspath(os.fspath(path)))
    for parent in absolute_path.parents:
        if _is_claude_blog_root(parent):
            return parent
    return None


def is_excluded_path(file_path: str | Path, root: Path | None = None) -> bool:
    """Return True when the path is inside one of claude-blog's own non-post trees.

    The exclusion applies only when the file sits in a claude-blog checkout:
    ``root`` (when given) or the nearest ancestor holding a claude-blog
    ``.claude-plugin/plugin.json``. Everywhere else nothing is excluded.
    """
    absolute_path = Path(os.path.abspath(os.fspath(file_path)))
    if root is None:
        repo_root = _find_claude_blog_root(absolute_path)
    else:
        candidate = Path(os.path.abspath(os.fspath(root)))
        repo_root = candidate if _is_claude_blog_root(candidate) else None
    if repo_root is None:
        return False
    try:
        policy_path = absolute_path.relative_to(repo_root)
    except ValueError:
        return False
    parent_parts = {part.lower() for part in policy_path.parts[:-1]}
    return bool(parent_parts & EXCLUDED_DIRS)


def has_blog_frontmatter(file_path: str | Path) -> bool:
    """Return True when a Markdown file has blog post frontmatter keys."""
    path = Path(file_path)
    content = path.read_text(encoding="utf-8")

    frontmatter = analyze_blog.extract_frontmatter(content)
    normalized = {key.lower(): value for key, value in frontmatter.items()}
    return bool(
        normalized.get("title")
        and (normalized.get("description") or normalized.get("date"))
    )


def skip_reason(file_path: str | Path, root: Path | None = None) -> str | None:
    """Return why a path is not gated as a blog post, or None when it is one."""
    path = Path(file_path)
    if path.suffix.lower() not in BLOG_SUFFIXES:
        return "not a Markdown file"
    if is_excluded_path(path, root):
        return "inside a claude-blog docs, skills, tests, templates or references tree"
    if not path.is_file():
        return "not a regular file"
    try:
        if not has_blog_frontmatter(path):
            return "no blog frontmatter"
    except (OSError, UnicodeDecodeError):
        return None
    return None


def is_blog_post(file_path: str | Path, root: Path | None = None) -> bool:
    """Return True when a path should be gated as a blog post."""
    return skip_reason(file_path, root) is None


def _git(*args: str) -> bytes:
    """Run git and return stdout bytes, raising RuntimeError on failure."""
    result = subprocess.run(
        ["git", *args], check=False, capture_output=True
    )
    if result.returncode != 0:
        message = result.stderr.decode("utf-8", "replace").strip()
        raise RuntimeError(message or "Unable to read staged files")
    return result.stdout


def _staged_files() -> list[str]:
    """Read staged file paths from Git (deleted files are not gate inputs).

    Uses NUL-separated output so names with spaces or non-ASCII characters are
    not quoted, and resolves each name against the repository top level, since
    Git prints paths relative to it whatever the current directory is.
    """
    toplevel = Path(_git("rev-parse", "--show-toplevel").decode("utf-8", "replace").strip())
    raw = _git("diff", "--cached", "--name-only", "-z", "--diff-filter=ACMR")
    names = [item for item in raw.decode("utf-8", "surrogateescape").split("\0") if item]
    return [_display_path(toplevel / name) for name in names]


def _display_path(path: Path) -> str:
    """Prefer a path relative to the current directory; keep it absolute if that fails."""
    try:
        return os.path.relpath(path)
    except ValueError:
        return str(path)


def _input_error(path: str, reason: str) -> dict[str, Any]:
    """Build a failing result for an explicit path that cannot be checked."""
    message = f"Could not check {path}: {reason}"
    return {
        "file": path,
        "score": 0,
        "passed": False,
        "issues": [{"category": "input", "severity": "high", "issue": message}],
        "error": message,
    }


def _dedupe(paths: list[str]) -> list[str]:
    """Preserve the first occurrence of each path."""
    seen: set[str] = set()
    deduped: list[str] = []
    for path in paths:
        key = str(Path(path).resolve(strict=False))
        if key not in seen:
            seen.add(key)
            deduped.append(path)
    return deduped


def _frontmatter_ok(path: Path) -> bool:
    """Return False only when the file is readable and lacks blog frontmatter."""
    try:
        return has_blog_frontmatter(path)
    except (OSError, UnicodeDecodeError):
        return True


def _top_high_severity_issues(
    issues: list[dict[str, Any]], limit: int = 3
) -> list[dict[str, Any]]:
    return [issue for issue in issues if issue.get("severity") == "high"][:limit]


def _safe_analyze_file(path: Path) -> dict[str, Any]:
    """Run the shared analyzer and convert file read failures into JSON errors."""
    try:
        return analyze_blog.analyze_file(str(path))
    except (OSError, UnicodeDecodeError) as exc:
        return {"error": f"Could not analyze {path}: {exc}"}


def analyze_post(file_path: str | Path, threshold: int) -> dict[str, Any]:
    """Analyze a selected post and return gate-oriented result data."""
    path = Path(file_path)
    result = _safe_analyze_file(path)
    error_message = result.get("error")
    if "error" not in result and not _frontmatter_ok(path):
        error_message = MISSING_FRONTMATTER
        result = {"error": error_message}
    if "error" in result:
        score = 0
        issues = [
            {
                "category": "analyzer",
                "severity": "high",
                "issue": error_message,
            }
        ]
    else:
        score = result["score"]["total"]
        issues = result["score"].get("issues", [])

    output = {
        "file": str(path),
        "score": score,
        "passed": score >= threshold,
        "issues": _top_high_severity_issues(issues),
    }
    if error_message:
        output["error"] = error_message
    return output


def _skipped_summary(skipped: dict[str, str]) -> str:
    """Describe skipped files, grouped by reason, for the text output."""
    reasons: dict[str, int] = {}
    for reason in skipped.values():
        reasons[reason] = reasons.get(reason, 0) + 1
    detail = "; ".join(f"{count} {reason}" for reason, count in sorted(reasons.items()))
    return f"{len(skipped)} file(s) skipped ({detail})."


def _format_text(
    results: list[dict[str, Any]],
    failures: list[dict[str, Any]],
    threshold: int,
    skipped: dict[str, str] | None = None,
) -> str:
    skipped = skipped or {}
    note = f"\n{_skipped_summary(skipped)}" if skipped else ""
    if not failures:
        if results:
            return f"Blog quality gate passed: {len(results)} post(s) checked.{note}"
        return f"Blog quality gate passed: no blog posts to check.{note}"

    lines = [
        f"Blog quality gate failed: {len(failures)} post(s) below score {threshold}.",
    ]
    for failure in failures:
        lines.append(f"{failure['file']}: score {failure['score']}/100")
        if failure.get("error"):
            lines.append(f"  {failure['error']}")
        if failure["issues"]:
            for issue in failure["issues"]:
                lines.append(
                    f"  [{issue.get('severity', 'high')}] "
                    f"{issue.get('category', 'general')}: {issue.get('issue', '')}"
                )
        else:
            lines.append("  No high severity issues reported.")
    if skipped:
        lines.append(_skipped_summary(skipped))
    return "\n".join(lines)


def _format_json(
    results: list[dict[str, Any]],
    failures: list[dict[str, Any]],
    threshold: int,
    skipped: dict[str, str] | None = None,
) -> str:
    errors = [result["error"] for result in results if result.get("error")]
    payload = {
        "threshold": threshold,
        "checked": results,
        "failures": failures,
        "skipped": [
            {"file": path, "reason": reason} for path, reason in (skipped or {}).items()
        ],
    }
    if errors:
        payload["error"] = "; ".join(errors)
    return json.dumps(payload, indent=2, sort_keys=True)


def _threshold_arg(value: str) -> int:
    """Parse --threshold and reject values that would make the gate meaningless."""
    try:
        number = int(value)
    except ValueError:
        raise argparse.ArgumentTypeError(f"threshold must be an integer, got {value!r}")
    if not MIN_THRESHOLD <= number <= MAX_THRESHOLD:
        raise argparse.ArgumentTypeError(
            f"threshold must be between {MIN_THRESHOLD} and {MAX_THRESHOLD}, got {number}"
        )
    return number


def expand_directory(directory: Path) -> list[str]:
    """List every Markdown candidate under a directory; main() filters and counts skips."""
    return [
        str(candidate)
        for candidate in sorted(directory.rglob("*"))
        if candidate.suffix.lower() in BLOG_SUFFIXES
    ]


def build_parser() -> argparse.ArgumentParser:
    """Build the command line parser."""
    parser = argparse.ArgumentParser(
        description=(
            "Block commits when blog posts score below the analyzer quality "
            f"threshold (default {DEFAULT_THRESHOLD}, the analyze_blog.py quality "
            "threshold, not the 90-point delivery gate in blog_preflight.py). "
            "Files named on the command line are always checked; directories "
            "are scanned."
        )
    )
    parser.add_argument(
        "files",
        nargs="*",
        help="Markdown or MDX files (always checked) or directories (scanned)",
    )
    parser.add_argument(
        "--threshold",
        type=_threshold_arg,
        default=DEFAULT_THRESHOLD,
        help=(
            f"Minimum accepted analyzer score, {MIN_THRESHOLD} to {MAX_THRESHOLD} "
            f"(default {DEFAULT_THRESHOLD}, the analyzer quality threshold)"
        ),
    )
    parser.add_argument(
        "--select",
        action="store_true",
        help=(
            "Hook mode: treat the listed files as candidates and skip those that "
            "are not blog posts (for pre-commit, which passes every Markdown file)"
        ),
    )
    parser.add_argument(
        "--format",
        choices=("text", "json"),
        default="text",
        help="Output format",
    )
    parser.add_argument(
        "--staged",
        action="store_true",
        help="Also check Markdown and MDX files staged in Git",
    )
    return parser


def main(argv: list[str] | None = None) -> int:
    """Run the quality gate and return a process exit code."""
    parser = build_parser()
    args = parser.parse_args(argv)

    explicit: list[str] = []
    candidates: list[str] = []
    problems: list[dict[str, Any]] = []
    for raw in args.files:
        path = Path(raw)
        if path.is_dir():
            candidates.extend(expand_directory(path))
        elif args.select:
            if not path.exists():
                problems.append(_input_error(raw, "path does not exist"))
            else:
                candidates.append(raw)
        elif not path.exists():
            problems.append(_input_error(raw, "path does not exist"))
        elif not path.is_file():
            problems.append(_input_error(raw, "path is not a file or directory"))
        else:
            explicit.append(raw)

    if args.staged:
        try:
            candidates.extend(_staged_files())
        except RuntimeError as exc:
            print(f"Blog quality gate error: {exc}", file=sys.stderr)
            return 2

    if not args.files and not args.staged:
        parser.error("no files given: name Markdown files or directories, or pass --staged")

    selected = list(explicit)
    skipped: dict[str, str] = {}
    for path in candidates:
        reason = skip_reason(path)
        if reason is None:
            selected.append(path)
        else:
            skipped[path] = reason
    selected = _dedupe(selected)
    results = [analyze_post(path, args.threshold) for path in selected]
    results.extend(problems)
    failures = [result for result in results if not result["passed"]]

    if args.format == "json":
        print(_format_json(results, failures, args.threshold, skipped))
    else:
        print(_format_text(results, failures, args.threshold, skipped))

    if problems:
        return 2
    return 1 if failures else 0


if __name__ == "__main__":
    sys.exit(main())