#!/usr/bin/env python3
"""
check.py — Validate _FEATURES.md hierarchy against current codebase state.

Discovers all _FEATURES.md files (root + sub-files linked from parents),
parses symbol references, resolves them via tree-sitting, and reports:
  - Broken refs (symbol renamed, deleted, or moved)
  - Dead features (ALL key symbols gone)
  - Uncovered symbols (new public API not mentioned in any feature)
  - Orphan sub-files (_FEATURES.md files not linked from any parent)
  - Broken sub-file links (links to _FEATURES.md that don't exist)

Usage:
    python check.py /path/to/repo [--features _FEATURES.md] [--skip tests]

Exit codes: 0 = clean, 1 = drift detected
"""

import argparse
import re
import sys
from collections import defaultdict
from pathlib import Path

# Reuse gather's engine discovery
from gather import _find_treesit_engine


def discover_features_files(root_path: Path, repo: Path) -> list:
    """Discover all _FEATURES.md files by following links from the root.

    Returns list of (path, linked_from) tuples.
    """
    # Start with the root
    discovered = [(root_path, None)]
    visited = {root_path.resolve()}

    # Sub-file link pattern: [text](path/to/_FEATURES.md) or (path/_FEATURES.md)
    link_pattern = re.compile(r'\]\(([^)]*_FEATURES\.md)\)')

    queue = [root_path]
    while queue:
        current = queue.pop(0)
        if not current.exists():
            continue

        text = current.read_text()
        parent_dir = current.parent

        for match in link_pattern.finditer(text):
            rel_link = match.group(1)
            linked_path = (parent_dir / rel_link).resolve()

            if linked_path not in visited:
                visited.add(linked_path)
                discovered.append((linked_path, str(current.relative_to(repo))))
                if linked_path.exists():
                    queue.append(linked_path)

    return discovered


def find_all_features_files(repo: Path) -> list:
    """Find ALL _FEATURES.md files in the repo, including unlinked ones."""
    return list(repo.rglob('_FEATURES.md'))


def parse_features_file(path: Path) -> dict:
    """Parse _FEATURES.md and extract structure.

    Returns:
        {
            'path': str,
            'features': [
                {
                    'name': str,
                    'line': int,
                    'refs': [{'file': str, 'symbol': str, 'line': int}, ...],
                },
                ...
            ],
            'all_refs': [{'file': str, 'symbol': str, 'feature': str, 'line': int, 'source_file': str}, ...],
            'sub_links': [{'target': str, 'line': int}, ...]
        }
    """
    text = path.read_text()
    lines = text.split('\n')

    ref_pattern = re.compile(r'`([^`]+?)#([^`]+?)`')
    link_pattern = re.compile(r'\]\(([^)]*_FEATURES\.md)\)')

    features = []
    all_refs = []
    sub_links = []
    current_feature = None

    for i, line in enumerate(lines, 1):
        # Feature headers are ## level
        if line.startswith('## ') and not line.startswith('### '):
            feature_name = line[3:].strip()
            if feature_name.lower() in ('feature inventory', 'status summary'):
                continue
            current_feature = {
                'name': feature_name,
                'line': i,
                'refs': [],
            }
            features.append(current_feature)

        # Extract symbol references
        for match in ref_pattern.finditer(line):
            filepath = match.group(1)
            symbol = match.group(2)
            ref = {
                'file': filepath,
                'symbol': symbol,
                'line': i,
                'feature': current_feature['name'] if current_feature else '(preamble)',
                'source_file': str(path),
            }
            if current_feature:
                current_feature['refs'].append(ref)
            all_refs.append(ref)

        # Extract sub-file links
        for match in link_pattern.finditer(line):
            sub_links.append({'target': match.group(1), 'line': i})

    return {
        'path': str(path),
        'features': features,
        'all_refs': all_refs,
        'sub_links': sub_links,
    }


def resolve_refs(cache, refs: list) -> tuple[list, list]:
    """Check each ref against the codebase.

    Returns (resolved, broken) where each is a list of ref dicts
    with an added 'match' key for resolved refs.
    """
    resolved = []
    broken = []

    for ref in refs:
        filepath = ref['file']
        symbol_parts = ref['symbol'].split('#')
        symbol_name = symbol_parts[-1]

        file_syms = cache.file_symbols(filepath)
        found = False

        if file_syms:
            for sym in file_syms:
                if sym.name == symbol_name:
                    found = True
                    ref['match'] = sym
                    break
                for child in sym.children:
                    if child.name == symbol_name:
                        found = True
                        ref['match'] = child
                        break
                if found:
                    break

        if not found:
            global_matches = cache.find_symbol(symbol_name, limit=3)
            if global_matches:
                ref['moved_to'] = global_matches[0].file
                ref['match'] = global_matches[0]
                found = True

        if found:
            resolved.append(ref)
        else:
            broken.append(ref)

    return resolved, broken


def find_uncovered(cache, all_refs: list, skip_patterns: set = None) -> list:
    """Find public symbols not referenced in any feature."""
    skip_patterns = skip_patterns or set()

    referenced = set()
    for ref in all_refs:
        parts = ref['symbol'].split('#')
        referenced.add(parts[-1])
        if len(parts) > 1:
            referenced.add(parts[0])

    uncovered = []
    for relpath, entry in cache.files.items():
        if entry.lang == 'markdown':
            continue
        if any(p in relpath.lower() for p in ('test', 'spec', '__tests__', 'vendor')):
            continue
        if any(p in relpath for p in skip_patterns):
            continue

        for sym in entry.symbols:
            if sym.name.startswith('_'):
                continue
            if sym.name not in referenced:
                uncovered.append(sym)
            for child in sym.children:
                if child.name.startswith('_'):
                    continue
                if child.name not in referenced:
                    if sym.name in referenced:
                        uncovered.append(child)

    return uncovered


def check(repo_path: str, features_path: str = None,
          skip: set = None, verbose: bool = False) -> dict:
    """Run all checks across the full _FEATURES.md hierarchy."""

    engine_path = _find_treesit_engine()
    if engine_path is None:
        print("ERROR: tree-sitting skill not found.", file=sys.stderr)
        sys.exit(1)
    sys.path.insert(0, str(engine_path))
    from engine import CodeCache

    repo = Path(repo_path).resolve()

    # Find root _FEATURES.md
    if features_path:
        root_fpath = Path(features_path)
    else:
        root_fpath = repo / '_FEATURES.md'
    if not root_fpath.exists():
        return {'error': f'_FEATURES.md not found at {root_fpath}'}

    # Discover linked hierarchy
    linked_files = discover_features_files(root_fpath, repo)

    # Find ALL _FEATURES.md files in repo (for orphan detection)
    all_files_on_disk = find_all_features_files(repo)
    linked_paths = {p.resolve() for p, _ in linked_files}

    # Parse all linked feature files
    all_features = []
    all_refs = []
    all_sub_links = []
    broken_sub_links = []
    file_count = 0

    for fpath, linked_from in linked_files:
        if not fpath.exists():
            broken_sub_links.append({
                'target': str(fpath.relative_to(repo)),
                'linked_from': linked_from or '(root)',
            })
            continue
        file_count += 1
        parsed = parse_features_file(fpath)
        all_features.extend(parsed['features'])
        all_refs.extend(parsed['all_refs'])

        # Check sub-links resolve
        for link in parsed['sub_links']:
            target = (fpath.parent / link['target']).resolve()
            if not target.exists():
                broken_sub_links.append({
                    'target': link['target'],
                    'linked_from': str(fpath.relative_to(repo)),
                    'line': link['line'],
                })

    # Detect orphan _FEATURES.md files
    orphans = [
        str(f.relative_to(repo))
        for f in all_files_on_disk
        if f.resolve() not in linked_paths
    ]

    # Scan codebase
    cache = CodeCache()
    cache.scan(str(repo), skip=skip)

    # Resolve refs
    resolved, broken = resolve_refs(cache, all_refs)

    # Find moved symbols
    moved = [r for r in resolved if 'moved_to' in r]

    # Find dead features
    dead_features = []
    for feat in all_features:
        if feat['refs'] and all(r in broken for r in feat['refs']):
            dead_features.append(feat)

    # Find uncovered symbols
    uncovered = find_uncovered(cache, all_refs)

    return {
        'features_files': file_count,
        'total_features': len(all_features),
        'total_refs': len(all_refs),
        'resolved': len(resolved),
        'broken': broken,
        'moved': moved,
        'dead_features': dead_features,
        'uncovered': uncovered,
        'orphan_files': orphans,
        'broken_sub_links': broken_sub_links,
        'clean': (len(broken) == 0 and len(broken_sub_links) == 0),
    }


def format_report(results: dict) -> str:
    """Format check results as readable report."""
    lines = []

    if 'error' in results:
        return f"ERROR: {results['error']}"

    lines.append("# _FEATURES.md Check")
    lines.append(f"Feature files: {results['features_files']} | "
                 f"Features: {results['total_features']} | "
                 f"Refs: {results['total_refs']} | "
                 f"Resolved: {results['resolved']} | "
                 f"Broken: {len(results['broken'])}")
    lines.append("")

    if results['clean'] and not results['moved'] and not results['orphan_files']:
        lines.append("✓ All symbol references resolve. No drift detected.")
    else:
        if results['broken']:
            lines.append(f"## Broken References ({len(results['broken'])})")
            for ref in results['broken']:
                source = ref.get('source_file', '')
                lines.append(f"  ✗ `{ref['file']}#{ref['symbol']}` "
                             f"(line {ref['line']}, feature: {ref['feature']})")
            lines.append("")

        if results['moved']:
            lines.append(f"## Moved Symbols ({len(results['moved'])})")
            for ref in results['moved']:
                lines.append(f"  → `{ref['file']}#{ref['symbol']}` "
                             f"moved to `{ref['moved_to']}` "
                             f"(line {ref['line']}, feature: {ref['feature']})")
            lines.append("")

        if results['dead_features']:
            lines.append(f"## Dead Features ({len(results['dead_features'])})")
            for feat in results['dead_features']:
                lines.append(f"  ☠ **{feat['name']}** (line {feat['line']}) "
                             f"— all {len(feat['refs'])} refs broken")
            lines.append("")

        if results['broken_sub_links']:
            lines.append(f"## Broken Sub-File Links ({len(results['broken_sub_links'])})")
            for link in results['broken_sub_links']:
                from_str = link.get('linked_from', '?')
                lines.append(f"  ✗ `{link['target']}` linked from {from_str}")
            lines.append("")

    if results['orphan_files']:
        lines.append(f"## Orphan Feature Files ({len(results['orphan_files'])})")
        for orphan in results['orphan_files']:
            lines.append(f"  ? `{orphan}` — not linked from any parent _FEATURES.md")
        lines.append("")

    if results['uncovered']:
        lines.append(f"## Uncovered Public Symbols ({len(results['uncovered'])})")
        by_file = defaultdict(list)
        for sym in results['uncovered']:
            by_file[sym.file].append(sym)
        for filepath in sorted(by_file.keys()):
            syms = by_file[filepath]
            names = ', '.join(s.name for s in syms[:8])
            if len(syms) > 8:
                names += f', ... +{len(syms) - 8}'
            lines.append(f"  {filepath}: {names}")
        lines.append("")
        lines.append("These symbols appear in the public API but aren't referenced "
                     "in any _FEATURES.md file.")

    return '\n'.join(lines)


def main():
    parser = argparse.ArgumentParser(description='Check _FEATURES.md hierarchy against codebase')
    parser.add_argument('repo', help='Path to codebase root')
    parser.add_argument('--features', default=None, help='Path to root _FEATURES.md')
    parser.add_argument('--skip', default='', help='Comma-separated dirs to skip')
    parser.add_argument('-v', '--verbose', action='store_true')
    args = parser.parse_args()

    skip = set(args.skip.split(',')) if args.skip else None
    results = check(args.repo, features_path=args.features, skip=skip, verbose=args.verbose)
    print(format_report(results))
    sys.exit(0 if results.get('clean', False) else 1)


if __name__ == '__main__':
    main()

#!/usr/bin/env python3
"""
gather.py — Collect structural data from a codebase via tree-sitting for feature synthesis.

Scans a codebase with tree-sitting's engine, then outputs a structured summary
optimized for LLM consumption: entry points, public APIs, symbol clusters by
directory, and selective source excerpts for key files.

Supports two modes:
  - Full scan: entire codebase → root _FEATURES.md synthesis
  - Area scan: specific subdirectory or file set → sub-feature file synthesis

Usage:
    # Full repo scan
    python gather.py /path/to/repo [--skip tests,.github] [--source-budget 8000]

    # Area scan (specific capability area)
    python gather.py /path/to/repo --area src/memory --source-budget 4000

Output: structured markdown to stdout, suitable as LLM prompt input.
"""

import argparse
import sys
from pathlib import Path


def _find_treesit_engine():
    """Locate tree-sitting engine across known skill directories."""
    candidates = [
        Path(__file__).resolve().parent.parent.parent / 'tree-sitting' / 'scripts',
        Path('/mnt/skills/user/tree-sitting/scripts'),
        Path('/mnt/skills/public/tree-sitting/scripts'),
    ]
    for p in candidates:
        if (p / 'engine.py').exists():
            return p
    return None


def setup_engine():
    """Import tree-sitting engine."""
    engine_path = _find_treesit_engine()
    if engine_path is None:
        print("ERROR: tree-sitting skill not found. Install it first.", file=sys.stderr)
        sys.exit(1)
    sys.path.insert(0, str(engine_path))
    try:
        from engine import CodeCache
        return CodeCache()
    except ImportError as e:
        print(f"ERROR: tree-sitting engine import failed: {e}\n"
              "Install deps: uv pip install tree-sitter-language-pack", file=sys.stderr)
        sys.exit(1)


def classify_symbols(cache, area_prefix=None) -> dict:
    """Classify symbols into feature-relevant categories.

    If area_prefix is set, only include symbols from files under that path.
    """
    categories = {
        'entry_points': [],
        'public_api': [],
        'types': [],
        'constants': [],
        'tests': [],
        'internal': [],
    }

    entry_patterns = {'main', 'cli', 'run', 'serve', 'start', 'app', 'init', 'setup', 'boot'}
    test_patterns = {'test_', 'test', 'spec_', 'it_'}

    for relpath, entry in cache.files.items():
        # Area filter
        if area_prefix and not relpath.startswith(area_prefix):
            continue
        if entry.lang == 'markdown':
            continue
        is_test_file = any(p in relpath.lower() for p in ('test', 'spec', '__tests__'))
        for sym in entry.symbols:
            name_lower = sym.name.lower()

            if is_test_file or any(name_lower.startswith(p) for p in test_patterns):
                categories['tests'].append(sym)
            elif name_lower in entry_patterns or (name_lower == '__main__'):
                categories['entry_points'].append(sym)
            elif sym.kind in ('class', 'struct', 'enum', 'interface', 'trait', 'type'):
                categories['types'].append(sym)
            elif sym.kind in ('constant', 'define', 'static'):
                categories['constants'].append(sym)
            elif sym.name.startswith('_'):
                categories['internal'].append(sym)
            else:
                categories['public_api'].append(sym)

    return categories


def _source_bytes(repo_path, relpath, entry) -> bytes:
    """Raw bytes of one scanned file.

    ``entry.source`` is populated only on a COLD scan: tree-sitting's on-disk
    cache (/tmp/treesit-cache) persists lang/symbols/imports and deliberately
    drops source, so every cache HIT hands back ``source=None``. Both call sites
    here used it unguarded, which made gather.py crash on its SECOND run against
    the same repo+skip set while the first succeeded -- diagnosed 2026-08-22,
    reproduced A/B/C: cold rc=0 (5697 lines), warm rc=1 (TypeError).
    Re-read from disk on the miss; return b"" if the file is gone.
    """
    if entry is not None and entry.source is not None:
        return entry.source
    try:
        return (Path(repo_path) / relpath).read_bytes()
    except OSError:
        return b""


def identify_key_files(cache, source_budget: int, area_prefix=None, repo_path=None) -> list:
    """Pick files worth reading source from, within a token budget."""
    file_scores = []
    for relpath, entry in cache.files.items():
        if area_prefix and not relpath.startswith(area_prefix):
            continue
        if any(p in relpath.lower() for p in ('test', 'spec', '__tests__', 'vendor', 'node_modules')):
            continue
        if entry.lang in ('json', 'yaml', 'toml', 'css', 'html', 'markdown'):
            continue

        score = 0
        for sym in entry.symbols:
            name_lower = sym.name.lower()
            if name_lower in ('main', 'cli', 'run', 'serve', 'boot', 'app'):
                score += 5
            elif sym.kind in ('class', 'struct', 'trait', 'interface'):
                score += 3 + len(sym.children)
            elif not sym.name.startswith('_'):
                score += 1

        if score > 0:
            source_len = len(_source_bytes(repo_path, relpath, entry))
            file_scores.append((relpath, score, source_len))

    file_scores.sort(key=lambda x: x[1], reverse=True)
    selected = []
    remaining = source_budget
    for relpath, score, size in file_scores:
        char_estimate = size
        if char_estimate <= remaining:
            selected.append(relpath)
            remaining -= char_estimate
        elif remaining > 2000:
            selected.append(relpath)
            break
    return selected


def compute_complexity(cache, area_prefix=None) -> dict:
    """Compute complexity metrics to help decide hierarchy.

    Returns dict with counts and a suggested decomposition.
    """
    public_count = 0
    file_count = 0
    type_count = 0
    dir_symbols = {}  # dir → count of public symbols

    for relpath, entry in cache.files.items():
        if area_prefix and not relpath.startswith(area_prefix):
            continue
        if entry.lang in ('json', 'yaml', 'toml', 'css', 'html', 'markdown'):
            continue
        if any(p in relpath.lower() for p in ('test', 'spec', '__tests__', 'vendor')):
            continue

        file_count += 1
        parent = str(Path(relpath).parent) if '/' in relpath else '.'

        for sym in entry.symbols:
            if sym.name.startswith('_'):
                continue
            public_count += 1
            dir_symbols[parent] = dir_symbols.get(parent, 0) + 1
            if sym.kind in ('class', 'struct', 'enum', 'interface', 'trait', 'type'):
                type_count += 1

    # Suggest decomposition if complex enough
    suggestions = []
    if public_count > 30:
        # Find directory clusters with significant symbol counts
        for d, count in sorted(dir_symbols.items(), key=lambda x: -x[1]):
            if count >= 6:
                suggestions.append((d, count))

    return {
        'public_symbols': public_count,
        'files': file_count,
        'types': type_count,
        'dir_clusters': dir_symbols,
        'decomposition_candidates': suggestions,
        'needs_hierarchy': public_count > 20 or len(suggestions) > 2,
    }


def format_symbol_brief(sym, indent=0) -> str:
    """One-line symbol summary."""
    prefix = '  ' * indent
    parts = [f"{prefix}- **{sym.name}** ({sym.kind})"]
    if sym.signature:
        parts.append(f"`{sym.signature}`")
    parts.append(f"@ {sym.file}:{sym.line}")
    if sym.doc:
        parts.append(f"— {sym.doc}")
    return ' '.join(parts)


def gather(repo_path: str, skip: set = None, source_budget: int = 8000,
           area: str = None, orient: bool = False) -> str:
    """Scan a codebase and produce structured output for feature synthesis.

    Args:
        repo_path: Root of the codebase to scan
        skip: Directory names to skip
        source_budget: Approximate char budget for source excerpts
        area: Optional subdirectory to focus on (for sub-feature generation)
        orient: Stop after the orientation header (complexity assessment,
            decomposition ranking, directory tree, entry points) and omit the
            full symbol inventory. ~115 lines instead of thousands. Use when the
            deliverable is your own understanding; use the full output only when
            you are writing a _FEATURES.md that must cite every symbol.
    """
    cache = setup_engine()

    stats = cache.scan(repo_path, skip=skip)
    if stats['files'] == 0:
        return f"No parseable files found in {repo_path}"

    # Normalize area prefix
    area_prefix = area.rstrip('/') + '/' if area else None
    if area_prefix == './':
        area_prefix = None

    categories = classify_symbols(cache, area_prefix)
    key_files = identify_key_files(cache, source_budget, area_prefix, repo_path)
    complexity = compute_complexity(cache, area_prefix)

    lines = []

    # ── Header
    root_name = Path(repo_path).name
    if area:
        lines.append(f"# Structural Scan: {root_name}/{area}")
    else:
        lines.append(f"# Structural Scan: {root_name}")
    lines.append(f"Files: {stats['files']} | Symbols: {stats['symbols']} | "
                 f"Languages: {', '.join(stats['languages'])}")
    lines.append("")

    # ── Complexity assessment (helps LLM decide hierarchy)
    lines.append("## Complexity Assessment")
    lines.append(f"Public symbols: {complexity['public_symbols']} | "
                 f"Source files: {complexity['files']} | "
                 f"Types: {complexity['types']}")
    if complexity['needs_hierarchy']:
        lines.append("**Hierarchy recommended.** This codebase has enough complexity "
                     "for sub-feature files.")
        if complexity['decomposition_candidates']:
            lines.append("\nCandidate areas for sub-files (by symbol density):")
            for d, count in complexity['decomposition_candidates']:
                lines.append(f"  - `{d}/` — {count} public symbols")
    else:
        lines.append("**Flat structure sufficient.** A single _FEATURES.md should work.")
    lines.append("")

    # ── Directory structure
    lines.append("## Directory Structure")
    lines.append(cache.tree_overview())
    lines.append("")

    # ── Entry points
    if categories['entry_points']:
        lines.append("## Entry Points")
        for sym in categories['entry_points']:
            lines.append(format_symbol_brief(sym))
        lines.append("")

    # Everything above is the orientation header: what this repo is, where it is
    # dense, and where execution starts. Everything below is the full symbol
    # inventory, which exists to be CITED in a _FEATURES.md -- not read end to end.
    if orient:
        lines.append(f"_Orientation only ({len(categories['public_api'])} public symbols and "
                     f"{len(categories['types'])} types withheld). Re-run without --orient "
                     f"to emit the full inventory._")
        return "\n".join(lines)

    # ── Public API (grouped by file)
    if categories['public_api']:
        lines.append("## Public API")
        by_file = {}
        for sym in categories['public_api']:
            by_file.setdefault(sym.file, []).append(sym)
        for filepath in sorted(by_file.keys()):
            lines.append(f"\n### {filepath}")
            for sym in by_file[filepath]:
                lines.append(format_symbol_brief(sym))
                for child in sym.children[:5]:
                    lines.append(format_symbol_brief(child, indent=1))
                if len(sym.children) > 5:
                    lines.append(f"    ... +{len(sym.children) - 5} more methods")
        lines.append("")

    # ── Types
    if categories['types']:
        lines.append("## Types & Data Structures")
        for sym in categories['types']:
            lines.append(format_symbol_brief(sym))
            for child in sym.children[:5]:
                lines.append(format_symbol_brief(child, indent=1))
            if len(sym.children) > 5:
                lines.append(f"    ... +{len(sym.children) - 5} more")
        lines.append("")

    # ── Key file sources
    if key_files:
        lines.append("## Key Source Excerpts")
        lines.append(f"*{len(key_files)} files selected by structural importance*\n")
        for filepath in key_files:
            entry = cache.files.get(filepath)
            if not entry:
                continue
            source_text = _source_bytes(repo_path, filepath, entry).decode('utf-8', errors='replace')
            source_lines = source_text.split('\n')
            if len(source_lines) > 150:
                excerpt = '\n'.join(source_lines[:150])
                lines.append(f"### {filepath} (first 150/{len(source_lines)} lines)")
            else:
                excerpt = source_text
                lines.append(f"### {filepath}")
            lines.append(f"```{entry.lang}")
            lines.append(excerpt)
            lines.append("```\n")

    # ── Import graph summary
    lines.append("## Import Graph (internal dependencies)")
    repo_modules = set()
    for relpath in cache.files:
        stem = Path(relpath).stem
        if stem != '__init__':
            repo_modules.add(stem)
        parts = Path(relpath).parts
        for p in parts[:-1]:
            repo_modules.add(p)

    for relpath, entry in sorted(cache.files.items()):
        if area_prefix and not relpath.startswith(area_prefix):
            continue
        if entry.lang == 'markdown':
            continue
        internal = [imp for imp in entry.imports
                    if imp.startswith('.') or
                    imp.split('.')[0] in repo_modules]
        if internal:
            lines.append(f"- {relpath} ← {', '.join(internal[:10])}")

    return '\n'.join(lines)


def main():
    parser = argparse.ArgumentParser(description='Gather codebase structure for feature synthesis')
    parser.add_argument('repo', help='Path to codebase root')
    parser.add_argument('--skip', default='', help='Comma-separated dirs to skip')
    parser.add_argument('--area', default=None,
                        help='Focus on a specific subdirectory (for sub-feature generation)')
    parser.add_argument('--source-budget', type=int, default=8000,
                        help='Approximate char budget for source excerpts (default: 8000)')
    parser.add_argument('--orient', action='store_true',
                        help='Orientation header only (~115 lines): complexity, decomposition '
                             'ranking, directory tree, entry points. Omits the symbol inventory. '
                             'Use this unless you are writing a _FEATURES.md.')
    args = parser.parse_args()

    skip = set(args.skip.split(',')) if args.skip else None
    out = gather(args.repo, skip=skip, source_budget=args.source_budget,
                 area=args.area, orient=args.orient)
    if not args.orient and out.count("\n") > 400:
        # Diagnosed 2026-08-22 (FreeToken review): a 5,697-line gather was piped
        # through `head -120` and the rest paid for and discarded. Say the size up
        # front so the cost of NOT using --orient is visible before the scroll.
        print(f"<!-- {out.count(chr(10)) + 1} lines. Reading only the top? "
              f"Re-run with --orient. -->")
    print(out)


if __name__ == '__main__':
    main()