Jd Docs

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Add a new area to an existing Johnny.Decimal documentation structure.

Usage:
    uv run jd_add_area.py --prefix 40 --name operations
    uv run jd_add_area.py --prefix 40 --name operations --description "Deployment, monitoring, runbooks"
    uv run jd_add_area.py --prefix 40 --name operations --dry-run
"""

import argparse
import json
import re
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    AREA_DESCRIPTIONS,
    AREA_NAME_PATTERN,
    DEFAULT_CONFIG,
    find_area_by_prefix,
    find_git_root,
    resolve_config,
)
from jd_index import re_index


def validate_prefix(prefix: str) -> tuple[bool, str | None]:
    """Validate prefix is two digits and a multiple of 10."""
    if not re.match(r"^[0-9]{2}$", prefix):
        return False, f"Prefix must be exactly two digits, got '{prefix}'"
    num = int(prefix)
    if num % 10 != 0:
        return False, f"Prefix '{prefix}' is not a multiple of 10 (convention: 00, 10, 20, ..., 90)"
    return True, None


def validate_name(name: str) -> tuple[bool, str | None]:
    """Validate area name is kebab-case."""
    test_name = f"00-{name}"
    if not AREA_NAME_PATTERN.match(test_name):
        return False, f"Name '{name}' is not valid kebab-case (lowercase letters, numbers, hyphens)"
    return True, None


def check_prefix_available(
    prefix: str,
    docs_dir: Path,
    config: dict,
) -> tuple[bool, str | None]:
    """Check if prefix is not already taken in config or on disk."""
    # Check config
    areas = config.get("areas", {})
    if prefix in areas:
        return False, f"Prefix '{prefix}' already in config as '{prefix}-{areas[prefix]}'"

    # Check on disk
    existing = find_area_by_prefix(docs_dir, prefix)
    if existing:
        return False, f"Prefix '{prefix}' already exists on disk as '{existing.name}'"

    return True, None


def create_area(
    docs_dir: Path,
    prefix: str,
    name: str,
    description: str,
    dry_run: bool,
) -> list[Path]:
    """Create area directory and README stub. Returns created paths."""
    created: list[Path] = []
    area_dir = docs_dir / f"{prefix}-{name}"

    if area_dir.exists():
        print(f"  Exists (skip): {area_dir}/")
        return created

    if dry_run:
        print(f"  Would create: {area_dir}/")
    else:
        area_dir.mkdir(parents=True, exist_ok=True)
    created.append(area_dir)

    # Create README stub
    readme_path = area_dir / "README.md"
    title = name.replace("-", " ").title()
    desc = description or AREA_DESCRIPTIONS.get(prefix, f"Documentation for {title.lower()}")

    content = f"""# {prefix} — {title}

{desc}.

## Documents

_No documents yet._
"""
    if dry_run:
        print(f"  Would create: {readme_path}")
    else:
        readme_path.write_text(content)
    created.append(readme_path)

    return created


def update_config_areas(
    config_path: Path,
    prefix: str,
    name: str,
    dry_run: bool,
) -> bool:
    """Add new area to .jd-config.json. Create config if missing."""
    if config_path.exists():
        with open(config_path) as f:
            config = json.load(f)
    else:
        config = dict(DEFAULT_CONFIG)

    areas = config.get("areas", {})
    areas[prefix] = name
    # Sort areas by prefix
    config["areas"] = dict(sorted(areas.items()))

    if dry_run:
        action = "Would update" if config_path.exists() else "Would create"
        print(f"  {action}: {config_path}")
        print(f"    + \"{prefix}\": \"{name}\"")
    else:
        with open(config_path, "w") as f:
            json.dump(config, f, indent=2)
            f.write("\n")
        action = "Updated" if config_path.exists() else "Created"
        print(f"  {action}: {config_path}")

    return True


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Add a new area to a Johnny.Decimal documentation structure"
    )
    parser.add_argument(
        "--prefix",
        "-p",
        required=True,
        help="Two-digit area prefix (e.g., '40')",
    )
    parser.add_argument(
        "--name",
        "-n",
        required=True,
        help="Area name in kebab-case (e.g., 'operations')",
    )
    parser.add_argument(
        "--description",
        "-D",
        default=None,
        help="Purpose description for README stub",
    )
    parser.add_argument(
        "--dir",
        "-d",
        default=None,
        help="Docs directory (default: from config or 'docs')",
    )
    parser.add_argument(
        "--config",
        "-c",
        default=None,
        help="Path to .jd-config.json (auto-detected if not specified)",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Show what would be created without writing",
    )

    args = parser.parse_args()
    base_path = Path.cwd()

    # Validate inputs
    valid, err = validate_prefix(args.prefix)
    if not valid:
        print(f"Error: {err}")
        return 1

    valid, err = validate_name(args.name)
    if not valid:
        print(f"Error: {err}")
        return 1

    # Load config
    config = resolve_config(args.config, base_path)

    # Resolve docs directory
    if args.dir:
        docs_dir = Path(args.dir)
        if not docs_dir.is_absolute():
            docs_dir = base_path / docs_dir
    else:
        docs_dir = base_path / config.get("root", "docs")

    if not docs_dir.exists():
        print(f"Error: Docs directory does not exist: {docs_dir}")
        print("Run jd_init.py first to create the structure.")
        return 1

    # Check availability
    valid, err = check_prefix_available(args.prefix, docs_dir, config)
    if not valid:
        print(f"Error: {err}")
        return 1

    # Execute
    mode = "(dry-run)" if args.dry_run else ""
    print(f"Adding area {args.prefix}-{args.name} {mode}")
    print()

    # Create directory and README
    created = create_area(
        docs_dir, args.prefix, args.name,
        args.description or "", args.dry_run,
    )

    # Update config
    git_root = find_git_root(base_path)
    config_path = (git_root or base_path) / ".jd-config.json"
    if args.config:
        config_path = Path(args.config)
        if not config_path.is_absolute():
            config_path = base_path / config_path

    print()
    update_config_areas(config_path, args.prefix, args.name, args.dry_run)

    # Re-index
    print()
    print("Re-indexing...")
    # Reload config after update
    if not args.dry_run:
        config = resolve_config(str(config_path) if config_path.exists() else None, base_path)
    re_index(docs_dir, config, args.dry_run)

    if created:
        print(f"\n{'Would create' if args.dry_run else 'Created'}: {len(created)} items")

    return 0


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

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Move or add a file to a Johnny.Decimal area directory.

Usage:
    uv run jd_add.py docs/roadmap.md 00
    uv run jd_add.py docs/roadmap.md 00-getting-started
    uv run jd_add.py "docs/My Design Doc.md" 20 --name design-doc.md
    uv run jd_add.py docs/roadmap.md 00 --dry-run
"""

import argparse
import re
import shutil
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    find_area_by_prefix,
    normalize_filename,
    resolve_config,
)
from jd_index import re_index


def resolve_target_area(
    target: str,
    docs_dir: Path,
) -> tuple[Path | None, str | None]:
    """Resolve target to an area directory path.

    Accepts prefix ("20") or full name ("20-architecture").
    Returns (area_path, error_message).
    """
    # Try as a prefix (two digits)
    if re.match(r"^[0-9]{2}$", target):
        area = find_area_by_prefix(docs_dir, target)
        if area:
            return area, None
        return None, f"No area with prefix '{target}' found in {docs_dir}"

    # Try as a full directory name
    area_path = docs_dir / target
    if area_path.is_dir():
        return area_path, None

    # Try as prefix-name pattern
    if re.match(r"^[0-9]{2}-", target):
        area_path = docs_dir / target
        if not area_path.exists():
            return None, f"Area directory '{target}' does not exist in {docs_dir}"

    return None, f"Cannot resolve target '{target}' to an area directory"


def find_cross_references(
    old_path: Path,
    docs_dir: Path,
) -> list[tuple[Path, int, str]]:
    """Search docs for markdown references to old_path.

    Returns list of (file, line_number, line_content).
    """
    refs: list[tuple[Path, int, str]] = []

    # Build patterns to search for
    old_name = old_path.name
    # Relative path from docs root
    try:
        old_relative = old_path.relative_to(docs_dir)
    except ValueError:
        old_relative = None

    patterns = [old_name]
    if old_relative:
        patterns.append(str(old_relative))
        patterns.append(f"./{old_relative}")

    for md_file in docs_dir.rglob("*.md"):
        if md_file == old_path:
            continue
        try:
            with open(md_file) as f:
                for lineno, line in enumerate(f, 1):
                    for pattern in patterns:
                        if pattern in line:
                            refs.append((md_file, lineno, line.rstrip()))
                            break  # Only report each line once
        except (OSError, UnicodeDecodeError):
            continue

    return refs


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Move or add a file to a Johnny.Decimal area directory"
    )
    parser.add_argument(
        "file",
        help="Path to the file to move",
    )
    parser.add_argument(
        "target",
        help="Target area by prefix ('20') or full name ('20-architecture')",
    )
    parser.add_argument(
        "--name",
        "-n",
        default=None,
        help="Override the output filename (auto-normalized if not provided)",
    )
    parser.add_argument(
        "--dir",
        "-d",
        default=None,
        help="Docs directory (default: from config or 'docs')",
    )
    parser.add_argument(
        "--config",
        "-c",
        default=None,
        help="Path to .jd-config.json (auto-detected if not specified)",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Preview without writing",
    )

    args = parser.parse_args()
    base_path = Path.cwd()

    # Resolve source file
    src = Path(args.file)
    if not src.is_absolute():
        src = base_path / src

    if not src.exists():
        print(f"Error: File not found: {src}")
        return 1

    if not src.is_file():
        print(f"Error: Not a file: {src}")
        return 1

    # Load config
    config = resolve_config(args.config, base_path)

    # Resolve docs directory
    if args.dir:
        docs_dir = Path(args.dir)
        if not docs_dir.is_absolute():
            docs_dir = base_path / docs_dir
    else:
        docs_dir = base_path / config.get("root", "docs")

    if not docs_dir.exists():
        print(f"Error: Docs directory does not exist: {docs_dir}")
        return 1

    # Resolve target area
    area_dir, err = resolve_target_area(args.target, docs_dir)
    if err:
        print(f"Error: {err}")
        return 1

    # Determine output filename
    if args.name:
        out_name = normalize_filename(args.name)
    else:
        out_name = normalize_filename(src.name)

    dst = area_dir / out_name

    # Check for conflicts
    if dst.exists():
        print(f"Error: File already exists: {dst}")
        print(f"Use --name to specify a different filename.")
        return 1

    # Execute
    mode = "(dry-run)" if args.dry_run else ""
    print(f"Moving file to {area_dir.name}/ {mode}")
    print()
    print(f"  Source:      {src}")
    print(f"  Destination: {dst}")
    if src.name != out_name:
        print(f"  Renamed:     {src.name} -> {out_name}")

    if not args.dry_run:
        shutil.move(str(src), str(dst))
        print(f"\n  Moved successfully.")

    # Check for cross-references
    refs = find_cross_references(src, docs_dir)
    if refs:
        print(f"\nCross-references found ({len(refs)} occurrence(s)):")
        print("These files reference the old path and may need updating:")
        print()
        for ref_file, lineno, line in refs[:10]:
            try:
                rel = ref_file.relative_to(docs_dir)
            except ValueError:
                rel = ref_file
            print(f"  {rel}:{lineno}: {line.strip()[:100]}")
        if len(refs) > 10:
            print(f"  ... and {len(refs) - 10} more")

        # Suggest the new relative path
        try:
            new_rel = dst.relative_to(docs_dir)
            old_rel = src.relative_to(docs_dir)
            print(f"\nSuggested replacement: '{old_rel}' -> '{new_rel}'")
        except ValueError:
            pass
    else:
        print("\nNo cross-references found.")

    # Re-index
    if not args.dry_run:
        print("\nRe-indexing...")
        re_index(docs_dir, config, dry_run=False)
    elif args.dry_run:
        print("\nWould re-index after move.")

    return 0


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

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Classify files into Johnny.Decimal areas using keyword heuristics.

Usage:
    uv run jd_classify.py docs/roadmap.md docs/api-design.md
    uv run jd_classify.py docs/*.md
    uv run jd_classify.py docs/*.md --move --yes
    uv run jd_classify.py docs/*.md --no-content
    uv run jd_classify.py docs/*.md --diataxis
    uv run jd_classify.py docs/*.md --diataxis-move --move --dry-run
"""

import argparse
import json
import re
import shutil
import sys
from dataclasses import dataclass, field
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    DEFAULT_AREAS,
    DIATAXIS_QUADRANT_TO_PREFIX,
    find_area_by_prefix,
    normalize_filename,
    resolve_config,
)
from jd_index import re_index

def _get_diataxis_classifier():
    """Try to import diataxis classify_file. Returns None if unavailable.

    Uses importlib to avoid module name collisions (both skills have shared.py).
    """
    import importlib.util

    diataxis_scripts = Path(__file__).resolve().parent.parent.parent / "diataxis" / "scripts"
    classify_path = diataxis_scripts / "diataxis_classify.py"
    shared_path = diataxis_scripts / "shared.py"

    if not classify_path.is_file() or not shared_path.is_file():
        return None

    try:
        # Load diataxis shared module under a unique name to avoid collision
        shared_spec = importlib.util.spec_from_file_location("diataxis_shared", shared_path)
        shared_mod = importlib.util.module_from_spec(shared_spec)
        sys.modules["diataxis_shared"] = shared_mod
        shared_spec.loader.exec_module(shared_mod)

        # Temporarily make diataxis shared importable as "shared" for diataxis_classify
        orig_shared = sys.modules.get("shared")
        sys.modules["shared"] = shared_mod

        classify_spec = importlib.util.spec_from_file_location("diataxis_classify", classify_path)
        classify_mod = importlib.util.module_from_spec(classify_spec)
        classify_spec.loader.exec_module(classify_mod)

        # Restore original shared module
        if orig_shared is not None:
            sys.modules["shared"] = orig_shared
        else:
            del sys.modules["shared"]

        return classify_mod.classify_file
    except Exception:
        return None


# Expanded keyword table for classification
CLASSIFICATION_KEYWORDS: dict[str, list[str]] = {
    "00": [
        "mvp", "requirements", "roadmap", "phase", "setup", "getting-started",
        "execution-plan", "next-steps", "checklist", "onboarding", "quickstart",
        "quick-start", "install", "installation", "tutorial",
    ],
    "10": [
        "product", "branding", "features", "priority", "design-system",
        "editor", "spec", "ux", "ui", "wireframe", "mockup", "prototype",
        "user-story", "persona", "journey",
    ],
    "20": [
        "architecture", "tech-stack", "integration", "structure", "refactor",
        "strategy", "stack", "system-design", "api", "schema", "database",
        "infrastructure", "convention", "pattern", "ddd", "deployment",
    ],
    "30": [
        "research", "resources", "analysis", "investigation", "alternatives",
        "sources", "audit", "spike", "benchmark", "comparison", "evaluation",
        "reference", "study", "exploration",
    ],
    "90": [
        "archive", "old", "deprecated", "historical", "retrospective",
        "v0", "v1", "legacy", "retired", "obsolete",
    ],
}


@dataclass
class ClassificationResult:
    """Result of classifying a single file."""

    file_path: Path
    suggested_prefix: str = ""
    suggested_area: str = ""
    confidence: str = "low"  # high, medium, low
    score: float = 0.0
    reason: str = ""
    filename_matches: list[str] = field(default_factory=list)
    content_matches: list[str] = field(default_factory=list)
    diataxis_quadrant: str = ""       # populated when --diataxis is used
    diataxis_confidence: str = ""     # populated when --diataxis is used


def _parse_first_heading(filepath: Path) -> str:
    """Extract the first markdown heading from a file."""
    try:
        with open(filepath) as f:
            for line in f:
                line = line.strip()
                if line.startswith("# "):
                    return line[2:].strip().lower()
    except (OSError, UnicodeDecodeError):
        pass
    return ""


def _read_first_n_lines(filepath: Path, n: int = 50) -> str:
    """Read the first N lines of a file as lowercase text."""
    try:
        lines = []
        with open(filepath) as f:
            for i, line in enumerate(f):
                if i >= n:
                    break
                lines.append(line.lower())
        return " ".join(lines)
    except (OSError, UnicodeDecodeError):
        return ""


def _match_keywords(
    text: str,
    segments: set[str],
    keywords: dict[str, list[str]],
) -> dict[str, tuple[float, list[str]]]:
    """Match text against keyword table.

    Returns dict of prefix -> (score, matched_keywords).
    Checks both full-text containment and segment-level matching.
    """
    scores: dict[str, tuple[float, list[str]]] = {}
    for prefix, kws in keywords.items():
        matched = []
        for kw in kws:
            if kw in text or kw in segments:
                matched.append(kw)
        if matched:
            # 0.5 for first match, +0.1 per additional, cap at 0.7
            score = min(0.5 + 0.1 * (len(matched) - 1), 0.7)
            scores[prefix] = (score, matched)
    return scores


def classify_file(
    filepath: Path,
    config: dict,
    scan_content: bool = True,
) -> ClassificationResult:
    """Classify a file by combining filename and content signals."""
    result = ClassificationResult(file_path=filepath)
    areas = config.get("areas", DEFAULT_AREAS)

    # Prepare filename for matching
    stem = filepath.stem.lower()
    # Normalize separators to hyphens for segment splitting
    normalized_stem = re.sub(r"[_ ]+", "-", stem)
    segments = set(normalized_stem.split("-"))

    # Pass 1: Filename analysis
    filename_scores = _match_keywords(
        normalized_stem, segments, CLASSIFICATION_KEYWORDS,
    )
    for prefix, (_, kws) in filename_scores.items():
        result.filename_matches.extend(kws)

    # Pass 2: Content analysis (optional)
    content_scores: dict[str, tuple[float, list[str]]] = {}
    if scan_content and filepath.suffix.lower() == ".md" and filepath.is_file():
        heading = _parse_first_heading(filepath)
        body = _read_first_n_lines(filepath, 50)

        # Heading matches (weight 0.3)
        heading_segments = set(re.sub(r"[_ ]+", "-", heading).split("-"))
        heading_scores = _match_keywords(heading, heading_segments, CLASSIFICATION_KEYWORDS)

        # Body matches (weight 0.1 per match, cap 0.3)
        body_segments = set(re.sub(r"[_ ]+", "-", body).split("-"))
        body_scores = _match_keywords(body, body_segments, CLASSIFICATION_KEYWORDS)

        for prefix in set(list(heading_scores) + list(body_scores)):
            h_score = heading_scores.get(prefix, (0, []))[0] * 0.3 / 0.5  # Normalize: max 0.3
            h_kws = heading_scores.get(prefix, (0, []))[1]

            b_raw = body_scores.get(prefix, (0, []))[0]
            b_score = min(b_raw * 0.1 / 0.5, 0.3)  # Normalize: max 0.3
            b_kws = body_scores.get(prefix, (0, []))[1]

            combined_score = h_score + b_score
            combined_kws = list(set(h_kws + b_kws))
            content_scores[prefix] = (min(combined_score, 0.5), combined_kws)

            result.content_matches.extend(combined_kws)

    # Deduplicate content matches
    result.content_matches = list(set(result.content_matches))

    # Combine scores
    all_prefixes = set(list(filename_scores) + list(content_scores))
    combined: dict[str, float] = {}
    for prefix in all_prefixes:
        fn_score = filename_scores.get(prefix, (0, []))[0]
        ct_score = content_scores.get(prefix, (0, []))[0]
        # Agreement bonus when both signals point to same area
        bonus = 0.15 if fn_score > 0 and ct_score > 0 else 0
        combined[prefix] = min(fn_score + ct_score + bonus, 1.0)

    if not combined:
        result.reason = "No keyword matches"
        return result

    # Pick the best
    best_prefix = max(combined, key=lambda k: combined[k])
    result.score = combined[best_prefix]
    result.suggested_prefix = best_prefix
    result.suggested_area = f"{best_prefix}-{areas.get(best_prefix, 'unknown')}"

    if result.score >= 0.7:
        result.confidence = "high"
    elif result.score >= 0.4:
        result.confidence = "medium"
    else:
        result.confidence = "low"

    # Build reason string
    reasons = []
    fn_kws = filename_scores.get(best_prefix, (0, []))[1]
    ct_kws = [k for k in content_scores.get(best_prefix, (0, []))[1] if k not in fn_kws]
    if fn_kws:
        reasons.append(f"Filename: {', '.join(repr(k) for k in fn_kws[:3])}")
    if ct_kws:
        reasons.append(f"Content: {', '.join(repr(k) for k in ct_kws[:3])}")
    result.reason = "; ".join(reasons) if reasons else "Weak keyword match"

    return result


def format_table(results: list[ClassificationResult], show_diataxis: bool = False) -> str:
    """Format classification results as a human-readable table."""
    # Calculate column widths
    file_w = max(len("File"), max(len(r.file_path.name) for r in results))
    area_w = max(len("Suggested Area"), max(len(r.suggested_area or "(unknown)") for r in results))
    conf_w = len("Confidence")

    if show_diataxis:
        quad_w = max(len("Quadrant"), max(len(r.diataxis_quadrant or "-") for r in results))
        qconf_w = len("Q. Conf")
        header = (
            f"{'File':<{file_w}} | {'Suggested Area':<{area_w}} | "
            f"{'Confidence':<{conf_w}} | {'Quadrant':<{quad_w}} | "
            f"{'Q. Conf':<{qconf_w}} | Reason"
        )
        sep = (
            f"{'-' * file_w}-+-{'-' * area_w}-+-{'-' * conf_w}-+-"
            f"{'-' * quad_w}-+-{'-' * qconf_w}-+{'-' * 30}"
        )
    else:
        header = f"{'File':<{file_w}} | {'Suggested Area':<{area_w}} | {'Confidence':<{conf_w}} | Reason"
        sep = f"{'-' * file_w}-+-{'-' * area_w}-+-{'-' * conf_w}-+{'-' * 30}"

    lines = [header, sep]
    for r in results:
        area = r.suggested_area or "(unknown)"
        if show_diataxis:
            quadrant = r.diataxis_quadrant or "-"
            qconf = r.diataxis_confidence or "-"
            lines.append(
                f"{r.file_path.name:<{file_w}} | {area:<{area_w}} | "
                f"{r.confidence:<{conf_w}} | {quadrant:<{quad_w}} | "
                f"{qconf:<{qconf_w}} | {r.reason}"
            )
        else:
            lines.append(
                f"{r.file_path.name:<{file_w}} | {area:<{area_w}} | {r.confidence:<{conf_w}} | {r.reason}"
            )
    return "\n".join(lines)


def format_json(results: list[ClassificationResult], show_diataxis: bool = False) -> str:
    """Format classification results as JSON."""
    data = []
    for r in results:
        entry = {
            "file": str(r.file_path),
            "suggested_area": r.suggested_area,
            "suggested_prefix": r.suggested_prefix,
            "confidence": r.confidence,
            "score": round(r.score, 2),
            "reason": r.reason,
            "filename_matches": r.filename_matches,
            "content_matches": r.content_matches,
        }
        if show_diataxis:
            entry["diataxis_quadrant"] = r.diataxis_quadrant
            entry["diataxis_confidence"] = r.diataxis_confidence
        data.append(entry)
    return json.dumps(data, indent=2)


def move_files(
    results: list[ClassificationResult],
    docs_dir: Path,
    config: dict,
    dry_run: bool,
) -> list[tuple[Path, Path]]:
    """Move files to their suggested areas. Returns list of (src, dst) pairs."""
    moved: list[tuple[Path, Path]] = []

    for r in results:
        if r.confidence == "low" or not r.suggested_prefix:
            print(f"  Skip (low confidence): {r.file_path.name} — flag for Claude review")
            continue

        area_dir = find_area_by_prefix(docs_dir, r.suggested_prefix)
        if not area_dir:
            print(f"  Skip (area not found): {r.file_path.name} — {r.suggested_area} doesn't exist")
            continue

        new_name = normalize_filename(r.file_path.name)
        dst = area_dir / new_name

        if dst.exists():
            print(f"  Skip (conflict): {r.file_path.name} — {dst.name} already exists in {area_dir.name}/")
            continue

        if dry_run:
            print(f"  Would move: {r.file_path.name} -> {area_dir.name}/{new_name}")
        else:
            shutil.move(str(r.file_path), str(dst))
            print(f"  Moved: {r.file_path.name} -> {area_dir.name}/{new_name}")
        moved.append((r.file_path, dst))

    return moved


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Classify files into Johnny.Decimal areas using keyword heuristics"
    )
    parser.add_argument(
        "files",
        nargs="+",
        help="File paths to classify",
    )
    parser.add_argument(
        "--move",
        action="store_true",
        help="Move files to suggested areas (high/medium confidence only)",
    )
    parser.add_argument(
        "--yes",
        "-y",
        action="store_true",
        help="Skip confirmation prompt when using --move",
    )
    parser.add_argument(
        "--no-content",
        action="store_true",
        help="Disable content scanning (filename-only classification)",
    )
    parser.add_argument(
        "--dir",
        "-d",
        default=None,
        help="Docs directory (default: from config or 'docs')",
    )
    parser.add_argument(
        "--config",
        "-c",
        default=None,
        help="Path to .jd-config.json (auto-detected if not specified)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        dest="json_output",
        help="Output results as JSON",
    )
    parser.add_argument(
        "--diataxis",
        action="store_true",
        help="Show Diataxis quadrant classification alongside JD area",
    )
    parser.add_argument(
        "--diataxis-move",
        action="store_true",
        help="With --move, route files to Diataxis areas (41-44) instead of JD areas",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Preview move operations without executing",
    )

    args = parser.parse_args()
    base_path = Path.cwd()

    # Load config
    config = resolve_config(args.config, base_path)

    # Resolve docs directory
    if args.dir:
        docs_dir = Path(args.dir)
        if not docs_dir.is_absolute():
            docs_dir = base_path / docs_dir
    else:
        docs_dir = base_path / config.get("root", "docs")

    # Resolve and validate file paths
    files: list[Path] = []
    for f in args.files:
        p = Path(f)
        if not p.is_absolute():
            p = base_path / p
        if not p.exists():
            print(f"Warning: File not found: {f}", file=sys.stderr)
            continue
        if not p.is_file():
            continue
        files.append(p)

    if not files:
        print("Error: No valid files to classify")
        return 1

    # Classify
    scan_content = not args.no_content
    results = [classify_file(f, config, scan_content) for f in files]

    # Diataxis classification (if requested)
    show_diataxis = args.diataxis or args.diataxis_move
    if show_diataxis:
        diataxis_classify = _get_diataxis_classifier()
        if diataxis_classify:
            for r in results:
                dx_result = diataxis_classify(r.file_path, config, scan_content)
                r.diataxis_quadrant = dx_result.primary_quadrant
                r.diataxis_confidence = dx_result.confidence
        else:
            print("Note: Diataxis skill not found, quadrant column will be empty",
                  file=sys.stderr)

    # Override prefix for --diataxis-move
    if args.diataxis_move and args.move:
        for r in results:
            if r.diataxis_quadrant and r.diataxis_quadrant in DIATAXIS_QUADRANT_TO_PREFIX:
                dx_prefix = DIATAXIS_QUADRANT_TO_PREFIX[r.diataxis_quadrant]
                dx_area_dir = find_area_by_prefix(docs_dir, dx_prefix)
                if dx_area_dir:
                    r.suggested_prefix = dx_prefix
                    r.suggested_area = dx_area_dir.name
                else:
                    print(f"  Note: {dx_prefix}-* area not found for {r.file_path.name}, "
                          f"keeping JD area {r.suggested_area}", file=sys.stderr)

    # Output
    if args.json_output:
        print(format_json(results, show_diataxis))
    else:
        print(format_table(results, show_diataxis))

        # Summary (human-readable only)
        high = sum(1 for r in results if r.confidence == "high")
        medium = sum(1 for r in results if r.confidence == "medium")
        low = sum(1 for r in results if r.confidence == "low")
        print(f"\nSummary: {high} high, {medium} medium, {low} low confidence")

        if low > 0:
            print(f"  {low} file(s) need Claude review (low confidence)")

    # Move if requested
    if args.move:
        moveable = [r for r in results if r.confidence != "low" and r.suggested_prefix]
        if not moveable:
            print("\nNo files to move (all low confidence).")
            return 0

        if not args.yes and not args.dry_run:
            print(f"\nAbout to move {len(moveable)} file(s). Proceed? [y/N] ", end="")
            try:
                answer = input().strip().lower()
            except EOFError:
                answer = "n"
            if answer not in ("y", "yes"):
                print("Aborted.")
                return 0

        print()
        moved = move_files(results, docs_dir, config, args.dry_run)

        if moved and not args.dry_run:
            print("\nRe-indexing...")
            re_index(docs_dir, config, dry_run=False)

        print(f"\n{'Would move' if args.dry_run else 'Moved'}: {len(moved)} file(s)")

    return 0


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

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Generate or update a README.md index for a Johnny.Decimal docs directory.

Usage:
    uv run jd_index.py --dir docs
    uv run jd_index.py --dir docs --format tree
    uv run jd_index.py --dir docs --dry-run
"""

import argparse
import re
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    AREA_DESCRIPTIONS_SHORT,
    is_ignored,
    resolve_config,
)

START_MARKER = "<!-- JD:INDEX:START -->"
END_MARKER = "<!-- JD:INDEX:END -->"


def parse_doc_title(filepath: Path) -> str:
    """Extract the first heading from a markdown file."""
    try:
        with open(filepath) as f:
            for line in f:
                line = line.strip()
                if line.startswith("# "):
                    # Remove the # prefix and any leading numbering
                    title = line[2:].strip()
                    # Remove common prefixes like "00 —" or "ADR-0001:"
                    title = re.sub(r"^[0-9]{2,4}\s*[-—:]\s*", "", title)
                    return title
    except (OSError, UnicodeDecodeError):
        pass
    # Fallback: derive from filename
    name = filepath.stem.replace("-", " ").replace("_", " ").title()
    return name


def scan_areas(docs_dir: Path, ignore: list[str]) -> list[dict]:
    """Scan all J.D area directories and their contents."""
    areas = []

    for item in sorted(docs_dir.iterdir()):
        if not item.is_dir():
            continue
        if is_ignored(item.name, ignore):
            continue
        if not re.match(r"^[0-9]{2}-", item.name):
            continue

        prefix = item.name[:2]
        name = item.name[3:]  # After "NN-"

        # Collect documents and subdirectories in a single pass
        entries = list(item.iterdir())
        docs = []
        for doc in sorted(e for e in entries if e.is_file()):
            if doc.suffix.lower() == ".md" and doc.name.lower() != "readme.md":
                if not is_ignored(doc.name, ignore):
                    title = parse_doc_title(doc)
                    docs.append({
                        "path": doc,
                        "name": doc.name,
                        "title": title,
                    })

        subdirs = [d for d in entries if d.is_dir() and not is_ignored(d.name, ignore)]

        desc = AREA_DESCRIPTIONS_SHORT.get(prefix, "")

        areas.append({
            "prefix": prefix,
            "name": name,
            "folder": item.name,
            "path": item,
            "docs": docs,
            "subdirs": subdirs,
            "description": desc,
            "doc_count": len(docs),
        })

    return areas


def generate_table_index(areas: list[dict]) -> str:
    """Generate a table-format index."""
    lines = [
        "| Prefix | Area | Docs | Description |",
        "|--------|------|------|-------------|",
    ]

    for area in areas:
        folder = area["folder"]
        desc = area["description"]
        count = area["doc_count"]
        count_str = f"{count} doc{'s' if count != 1 else ''}" if count > 0 else "—"
        lines.append(f"| `{area['prefix']}-` | [`{folder}/`](./{folder}/) | {count_str} | {desc} |")

    return "\n".join(lines)


def generate_tree_index(areas: list[dict]) -> str:
    """Generate a tree-format index with document listings."""
    lines = []

    for area in areas:
        folder = area["folder"]
        desc = area["description"]
        title = area["name"].replace("-", " ").title()
        lines.append(f"- **[`{folder}/`](./{folder}/)** — {desc or title}")

        for doc in area["docs"]:
            rel_path = f"./{folder}/{doc['name']}"
            lines.append(f"  - [{doc['title']}]({rel_path})")

        if area["subdirs"]:
            for subdir in area["subdirs"]:
                lines.append(f"  - `{subdir.name}/` (directory)")

    return "\n".join(lines)


def update_readme(
    docs_dir: Path,
    index_content: str,
    dry_run: bool,
) -> bool:
    """Update README.md with the generated index.

    Uses marker comments to preserve custom content.
    Returns True if changes were made.
    """
    readme_path = docs_dir / "README.md"

    if not readme_path.exists():
        # Generate minimal README with index
        content = f"""# Documentation

## Documentation Index

{START_MARKER}

{index_content}

{END_MARKER}
"""
        if dry_run:
            print(f"Would create: {readme_path}")
            print()
            print(content)
        else:
            readme_path.write_text(content)
            print(f"Created: {readme_path}")
        return True

    # Read existing README
    existing = readme_path.read_text()

    # Check for markers
    if START_MARKER in existing and END_MARKER in existing:
        # Replace content between markers
        pattern = re.compile(
            rf"{re.escape(START_MARKER)}.*?{re.escape(END_MARKER)}",
            re.DOTALL,
        )
        new_content = f"{START_MARKER}\n\n{index_content}\n\n{END_MARKER}"
        updated = pattern.sub(new_content, existing, count=1)

        if updated == existing:
            print("Index is already up to date.")
            return False

        if dry_run:
            print(f"Would update: {readme_path}")
            print()
            print("--- Index content ---")
            print(index_content)
            print("--- End ---")
        else:
            readme_path.write_text(updated)
            print(f"Updated: {readme_path}")
        return True
    else:
        # No markers found — append index with markers
        section = f"""
{START_MARKER}

{index_content}

{END_MARKER}
"""
        if dry_run:
            print(f"Would append index to: {readme_path}")
            print("(No markers found — adding markers and index)")
            print()
            print("--- Index content ---")
            print(index_content)
            print("--- End ---")
        else:
            with open(readme_path, "a") as f:
                f.write(section)
            print(f"Appended index to: {readme_path}")
            print("Tip: Move the index markers to the desired position in your README")
        return True


def re_index(docs_dir: Path, config: dict, dry_run: bool) -> None:
    """Regenerate the README index for a docs directory.

    Convenience wrapper used by other jd-docs scripts after mutations.
    """
    ignore = config.get("ignore", ["adr", "*.pdf"])
    fmt = config.get("readme_format", "table")

    areas = scan_areas(docs_dir, ignore)
    if not areas:
        return

    if fmt == "tree":
        index_content = generate_tree_index(areas)
    else:
        index_content = generate_table_index(areas)

    update_readme(docs_dir, index_content, dry_run)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Generate or update a README.md index for Johnny.Decimal docs"
    )
    parser.add_argument(
        "--dir",
        "-d",
        required=True,
        help="Docs directory to index",
    )
    parser.add_argument(
        "--format",
        "-f",
        choices=["table", "tree"],
        default=None,
        help="Index format (default: from config or 'table')",
    )
    parser.add_argument(
        "--config",
        "-c",
        default=None,
        help="Path to .jd-config.json (auto-detected if not specified)",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Print index without writing",
    )

    args = parser.parse_args()

    # Resolve directory
    docs_dir = Path(args.dir)
    if not docs_dir.is_absolute():
        docs_dir = Path.cwd() / docs_dir

    if not docs_dir.exists():
        print(f"Error: Directory does not exist: {docs_dir}")
        return 1

    # Load config
    config = resolve_config(args.config, Path.cwd())

    ignore = config.get("ignore", ["adr", "*.pdf"])
    fmt = args.format or config.get("readme_format", "table")

    # Scan areas
    areas = scan_areas(docs_dir, ignore)

    if not areas:
        print(f"No J.D areas found in: {docs_dir}")
        print("Expected directories matching NN-name pattern (e.g., 00-getting-started/)")
        return 1

    print(f"Scanning: {docs_dir}")
    print(f"Format: {fmt}")
    print(f"Areas found: {len(areas)}")
    total_docs = sum(a["doc_count"] for a in areas)
    print(f"Total documents: {total_docs}")
    print()

    # Generate index
    if fmt == "tree":
        index_content = generate_tree_index(areas)
    else:
        index_content = generate_table_index(areas)

    # Update README
    try:
        update_readme(docs_dir, index_content, args.dry_run)
    except OSError as e:
        print(f"Error writing README: {e}")
        return 1

    return 0


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

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Scaffold a Johnny.Decimal documentation structure.

Usage:
    uv run jd_init.py                          # Create docs/ with defaults
    uv run jd_init.py --root docs/skrebe       # Product sub-tree
    uv run jd_init.py --init-config            # Also create .jd-config.json
    uv run jd_init.py --dry-run                # Preview only
    uv run jd_init.py --diataxis               # Include Diataxis areas (41-44)
"""

import argparse
import json
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    AREA_DESCRIPTIONS,
    DEFAULT_AREAS,
    DEFAULT_CONFIG,
    DIATAXIS_AREAS,
    find_git_root,
    resolve_config,
)


def generate_root_readme(project_name: str, areas: dict[str, str]) -> str:
    """Generate the docs root README.md content."""
    lines = [
        f"# {project_name} Documentation",
        "",
        "[Brief project description]",
        "",
        "## Quick Start",
        "",
    ]

    if "00" in areas:
        lines.append("- [Getting started guide](./00-getting-started/)")
        lines.append("")

    lines.extend([
        "## Documentation Index",
        "",
        "<!-- JD:INDEX:START -->",
        "",
        "| Prefix | Area | Purpose |",
        "|--------|------|---------|",
    ])

    for prefix in sorted(areas.keys()):
        name = areas[prefix]
        folder = f"{prefix}-{name}"
        desc = AREA_DESCRIPTIONS.get(prefix, "")
        lines.append(f"| `{prefix}-` | [`{folder}/`](./{folder}/) | {desc} |")

    lines.extend([
        "",
        "<!-- JD:INDEX:END -->",
        "",
        "## Folder Convention",
        "",
        "Documentation uses the [Johnny.Decimal](https://johnnydecimal.com/) numbering system.",
        "Numeric prefixes ensure folders sort in a logical order:",
        "",
        "- `00-09` — Getting started and immediate work",
        "- `10-19` — Product decisions",
        "- `20-29` — Architecture and technical design",
        "- `30-39` — Research and reference material",
    ])

    # Include Diataxis range if those areas are present
    if any(k in ("41", "42", "43", "44") for k in areas):
        lines.append("- `41-44` — Diataxis quadrants (tutorials, how-to, reference, explanation)")

    lines.extend([
        "- `90-99` — Archive",
        "",
        "This convention provides consistent sorting and helps developers",
        "and LLMs quickly locate documentation.",
        "",
    ])

    return "\n".join(lines)


def generate_area_readme(prefix: str, name: str) -> str:
    """Generate a per-area README.md content."""
    title = name.replace("-", " ").title()
    desc = AREA_DESCRIPTIONS.get(prefix, f"Documentation for {title.lower()}")

    return f"""# {prefix} — {title}

{desc}.

## Documents

_No documents yet._
"""


def scaffold_structure(
    root: Path,
    areas: dict[str, str],
    project_name: str,
    dry_run: bool,
) -> list[Path]:
    """Create J.D directory structure with README stubs.

    Returns list of created paths.
    """
    created: list[Path] = []

    # Create root directory
    if not root.exists():
        if dry_run:
            print(f"  Would create: {root}/")
        else:
            root.mkdir(parents=True, exist_ok=True)
        created.append(root)

    # Create root README.md
    readme_path = root / "README.md"
    if not readme_path.exists():
        content = generate_root_readme(project_name, areas)
        if dry_run:
            print(f"  Would create: {readme_path}")
        else:
            readme_path.write_text(content)
        created.append(readme_path)
    else:
        print(f"  Exists (skip): {readme_path}")

    # Create area directories and READMEs
    for prefix in sorted(areas.keys()):
        name = areas[prefix]
        area_dir = root / f"{prefix}-{name}"

        if not area_dir.exists():
            if dry_run:
                print(f"  Would create: {area_dir}/")
            else:
                area_dir.mkdir(parents=True, exist_ok=True)
            created.append(area_dir)

        area_readme = area_dir / "README.md"
        if not area_readme.exists():
            content = generate_area_readme(prefix, name)
            if dry_run:
                print(f"  Would create: {area_readme}")
            else:
                area_readme.write_text(content)
            created.append(area_readme)
        else:
            print(f"  Exists (skip): {area_readme}")

    return created


def create_config(base_path: Path, dry_run: bool) -> Path | None:
    """Write .jd-config.json with defaults."""
    config_path = base_path / ".jd-config.json"

    if config_path.exists():
        print(f"  Exists (skip): {config_path}")
        return None

    if dry_run:
        print(f"  Would create: {config_path}")
        return config_path

    with open(config_path, "w") as f:
        json.dump(DEFAULT_CONFIG, f, indent=2)
        f.write("\n")

    return config_path


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Scaffold a Johnny.Decimal documentation structure"
    )
    parser.add_argument(
        "--root",
        "-r",
        default=None,
        help="Docs root directory (default: from config or 'docs')",
    )
    parser.add_argument(
        "--product",
        "-p",
        default=None,
        help="Product name for sub-tree (e.g., 'skrebe')",
    )
    parser.add_argument(
        "--config",
        "-c",
        default=None,
        help="Path to .jd-config.json (auto-detected if not specified)",
    )
    parser.add_argument(
        "--init-config",
        action="store_true",
        help="Create .jd-config.json with defaults",
    )
    parser.add_argument(
        "--diataxis",
        action="store_true",
        help="Include Diataxis quadrant areas (41-44) alongside standard areas",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Show what would be created without writing",
    )

    args = parser.parse_args()
    base_path = Path.cwd()

    # Load config
    config = resolve_config(args.config, base_path)
    if args.config and not Path(args.config).exists():
        # resolve_config prints warning, but init needs hard error
        config_path = Path(args.config)
        if not config_path.is_absolute():
            config_path = base_path / config_path
        if not config_path.exists():
            print(f"Error: Config file not found: {config_path}")
            return 1

    areas = config.get("areas", DEFAULT_AREAS)

    # Include Diataxis quadrant areas if requested
    if args.diataxis:
        areas = {**areas, **DIATAXIS_AREAS}

    # Determine root directory
    if args.root:
        root = Path(args.root)
        if not root.is_absolute():
            root = base_path / root
    else:
        root = base_path / config.get("root", "docs")

    # Handle product sub-tree
    if args.product:
        root = root / args.product

    # Derive project name from git root or directory
    git_root = find_git_root(base_path)
    project_name = (git_root or base_path).name.replace("-", " ").replace("_", " ").title()

    # Optionally create config file
    if args.init_config:
        config_target = git_root or base_path
        if args.dry_run:
            print("Config:")
        create_config(config_target, args.dry_run)
        if args.dry_run:
            print()

    # Scaffold
    mode = "(dry-run)" if args.dry_run else ""
    print(f"Scaffolding J.D structure at: {root}/ {mode}")
    print()

    created = scaffold_structure(root, areas, project_name, args.dry_run)

    if not created:
        print("\nNothing to create — structure already exists.")
    else:
        print(f"\n{'Would create' if args.dry_run else 'Created'}: {len(created)} items")

    if not args.dry_run and created:
        print(f"\nNext: Run jd_validate.py --dir {root} to verify the structure")

    return 0


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

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Validate a Johnny.Decimal documentation structure.

Usage:
    uv run jd_validate.py --dir docs
    uv run jd_validate.py --dir docs/skrebe --strict
    uv run jd_validate.py --dir docs --config .jd-config.json
"""

import argparse
import re
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    AREA_NAME_PATTERN,
    DEFAULT_AREAS,
    ROOT_ALLOWED_FILES,
    is_ignored,
    resolve_config,
)


def find_areas(docs_dir: Path, ignore: list[str]) -> list[Path]:
    """Find all NN-* directories in the docs root."""
    areas = []
    for item in sorted(docs_dir.iterdir()):
        if item.is_dir() and not is_ignored(item.name, ignore):
            if re.match(r"^[0-9]{2}-", item.name):
                areas.append(item)
    return areas


def validate_directory_name(name: str) -> tuple[bool, str | None]:
    """Check if a directory name matches the J.D convention.

    Returns:
        tuple: (is_valid, error_message or None)
    """
    if not AREA_NAME_PATTERN.match(name):
        return False, f"'{name}' does not match NN-kebab-case pattern"
    return True, None


def check_numbering(areas: list[Path]) -> list[str]:
    """Check area prefix numbering conventions.

    Returns list of warning messages.
    """
    warnings = []
    for area in areas:
        prefix = area.name[:2]
        try:
            num = int(prefix)
            if num % 10 != 0 and num < 90:
                warnings.append(
                    f"Area prefix '{prefix}' is not a multiple of 10 "
                    f"(convention: 00, 10, 20, ..., 90)"
                )
        except ValueError:
            pass  # Invalid prefix caught by validate_directory_name
    return warnings


def check_orphan_files(
    docs_dir: Path,
    ignore: list[str],
) -> list[Path]:
    """Find markdown files in docs root that should be in an area."""
    orphans = []
    for item in docs_dir.iterdir():
        if item.is_file() and not is_ignored(item.name, ignore):
            if item.name.lower() not in ROOT_ALLOWED_FILES:
                if item.suffix.lower() == ".md":
                    orphans.append(item)
    return orphans


def check_readme_presence(areas: list[Path]) -> list[Path]:
    """Find area directories missing README.md."""
    missing = []
    for area in areas:
        readme = area / "README.md"
        if not readme.exists():
            missing.append(area)
    return missing


def check_missing_standard_areas(
    areas: list[Path],
    expected_areas: dict[str, str],
) -> list[str]:
    """Report standard areas that are missing."""
    found_prefixes = {a.name[:2] for a in areas}
    missing = []
    for prefix, name in sorted(expected_areas.items()):
        if prefix not in found_prefixes:
            missing.append(f"{prefix}-{name}")
    return missing


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Validate a Johnny.Decimal documentation structure"
    )
    parser.add_argument(
        "--dir",
        "-d",
        required=True,
        help="Docs directory to validate",
    )
    parser.add_argument(
        "--config",
        "-c",
        default=None,
        help="Path to .jd-config.json (auto-detected if not specified)",
    )
    parser.add_argument(
        "--strict",
        action="store_true",
        help="Treat warnings as errors (exit code 1)",
    )

    args = parser.parse_args()

    # Resolve directory
    docs_dir = Path(args.dir)
    if not docs_dir.is_absolute():
        docs_dir = Path.cwd() / docs_dir

    if not docs_dir.exists():
        print(f"Error: Directory does not exist: {docs_dir}")
        return 1

    if not docs_dir.is_dir():
        print(f"Error: Not a directory: {docs_dir}")
        return 1

    # Load config
    config = resolve_config(args.config, Path.cwd())

    expected_areas = config.get("areas", DEFAULT_AREAS)
    ignore = config.get("ignore", ["adr", "*.pdf"])

    # Run checks
    errors: list[str] = []
    warnings: list[str] = []
    info: list[str] = []

    # Find areas
    areas = find_areas(docs_dir, ignore)

    # Check root README
    root_readme = docs_dir / "README.md"
    if not root_readme.exists():
        warnings.append("Missing README.md in docs root")

    # Validate area names
    for area in areas:
        valid, msg = validate_directory_name(area.name)
        if not valid:
            errors.append(f"Invalid area name: {msg}")

    # Check numbering conventions
    numbering_warnings = check_numbering(areas)
    warnings.extend(numbering_warnings)

    # Check orphan files
    orphans = check_orphan_files(docs_dir, ignore)
    for orphan in orphans:
        warnings.append(f"Orphan file: {orphan.name}")

    # Check README presence in areas
    missing_readme = check_readme_presence(areas)
    for area in missing_readme:
        warnings.append(f"Missing README.md in {area.name}/")

    # Check missing standard areas
    missing_areas = check_missing_standard_areas(areas, expected_areas)
    for area_name in missing_areas:
        info.append(f"Standard area not present: {area_name}/")

    # Print report
    print("Johnny.Decimal Validation Report")
    print("=" * 40)
    print(f"Directory: {docs_dir}")
    print()

    # Areas found
    print(f"Areas found: {len(areas)}")
    for area in areas:
        valid, _ = validate_directory_name(area.name)
        mark = "+" if valid else "x"
        print(f"  {mark} {area.name}")
    print()

    # Errors
    if errors:
        print(f"Errors: {len(errors)}")
        for err in errors:
            print(f"  x {err}")
        print()

    # Warnings
    if warnings:
        print(f"Warnings: {len(warnings)}")
        for warn in warnings:
            print(f"  ! {warn}")
        print()

    # Info
    if info:
        print(f"Info: {len(info)}")
        for inf in info:
            print(f"  - {inf}")
        print()

    # Result
    if errors:
        result = "FAIL"
    elif warnings and args.strict:
        result = "FAIL (strict mode)"
    else:
        result = "PASS"

    print(f"Result: {result} ({len(areas)} areas, {len(errors)} errors, {len(warnings)} warnings)")

    if errors or (warnings and args.strict):
        return 1
    return 0


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