Add useful tool to git repository

claude.md

@@ -0,0 +1,134 @@
+# Claude Code Guide for GenesisGraph
+
+This document provides guidance for working with the GenesisGraph codebase using Claude Code.
+
+## Available Tools
+
+### Progressive Reveal CLI
+
+Located in `tools/progressive-reveal-cli/`, this is a powerful command-line tool for exploring files at different levels of detail. It's particularly useful when analyzing large configuration files, data files, or complex code files in the GenesisGraph repository.
+
+#### Installation
+
+```bash
+cd tools/progressive-reveal-cli
+pip install -e .
+```
+
+#### Usage
+
+The tool provides 4 progressive levels of file exploration:
+
+**Level 0: Metadata** - Quick overview of file characteristics
+```bash
+reveal path/to/file.yaml
+```
+Shows: filename, type, size, modification date, line count, SHA256 hash
+
+**Level 1: Structure** - Structural synopsis without content
+```bash
+reveal path/to/file.yaml --level 1
+```
+For different file types, shows:
+- YAML/JSON: Top-level keys, nesting depth, object/array counts
+- Python: Imports, classes, functions, top-level assignments
+- Markdown: Headings hierarchy, paragraph/code block/list counts
+- Text: Line count, word count, estimated type
+
+**Level 2: Preview** - Content preview with key sections
+```bash
+reveal path/to/file.py --level 2
+```
+Shows a condensed view of important content (e.g., class/function signatures, docstrings)
+
+**Level 3: Full Content** - Complete file content with pagination
+```bash
+reveal path/to/file.md --level 3 --page-size 50
+```
+Full file content with configurable page size
+
+#### Filtering with Grep
+
+All levels support regex-based filtering:
+
+```bash
+# Find specific patterns in structure
+reveal config.yaml --level 1 --grep "database"
+
+# Preview with context around matches
+reveal app.py --level 2 --grep "class" --context 2
+
+# Full content filtered by pattern
+reveal README.md --level 3 --grep "installation" --context 5
+```
+
+#### Common Workflows
+
+**Exploring configuration files:**
+```bash
+# Start with metadata to understand size/type
+reveal pyproject.toml
+
+# Check structure to see all configuration sections
+reveal pyproject.toml --level 1
+
+# Preview specific sections
+reveal pyproject.toml --level 2 --grep "dependencies"
+
+# View full content when needed
+reveal pyproject.toml --level 3
+```
+
+**Understanding Python modules:**
+```bash
+# See module structure (imports, classes, functions)
+reveal genesisgraph/core.py --level 1
+
+# Preview class/function signatures with docstrings
+reveal genesisgraph/core.py --level 2
+
+# Find specific implementations
+reveal genesisgraph/core.py --level 3 --grep "def process" --context 10
+```
+
+**Analyzing documentation:**
+```bash
+# See document structure (headings, sections)
+reveal README.md --level 1
+
+# Preview introduction and key sections
+reveal README.md --level 2
+
+# Find specific topics
+reveal README.md --level 3 --grep "API" --context 3
+```
+
+## Tips for Working with GenesisGraph
+
+1. **Start Small**: Use `reveal` with level 0 or 1 to understand file structure before diving into full content
+2. **Use Grep**: Filter large files with `--grep` to focus on relevant sections
+3. **Progressive Exploration**: Follow the natural progression (metadata → structure → preview → full content)
+4. **Context Lines**: Use `--context` to see code around matches for better understanding
+
+## Repository Structure
+
+```
+genesisgraph/
+├── genesisgraph/      # Main package source code
+├── tests/            # Test suite
+├── docs/             # Documentation
+├── tools/            # Development tools (including progressive-reveal-cli)
+├── examples/         # Usage examples
+├── scripts/          # Build and utility scripts
+└── pyproject.toml    # Project configuration
+```
+
+## Working with Claude Code
+
+When Claude Code is exploring the GenesisGraph codebase, it can use the Progressive Reveal CLI to:
+- Quickly understand file structure without reading entire files
+- Filter large configuration or data files for specific sections
+- Get file metadata to make informed decisions about what to analyze
+- Preview code structure before making modifications
+
+This is especially useful for large files where full content might be overwhelming or unnecessary for the task at hand.

tools/progressive-reveal-cli/README.md

@@ -0,0 +1,101 @@
+# Progressive Reveal CLI
+
+A powerful command-line tool for exploring files at different levels of detail. Progressive Reveal CLI allows you to understand file contents incrementally, from high-level metadata to detailed content, with smart type-aware analysis for YAML, JSON, Markdown, and Python files.
+
+## Features
+
+- **4 Progressive Levels**: Metadata → Structure → Preview → Full Content
+- **Smart File Type Detection**: Automatic detection and specialized handling for YAML, JSON, Markdown, Python
+- **Grep Filtering**: Regex-based filtering with context support across all levels
+- **Type-Aware Analysis**:
+  - YAML: Top-level keys, nesting depth, anchors/aliases
+  - JSON: Object/array counts, max depth, value types
+  - Markdown: Headings, paragraphs, code blocks
+  - Python: Imports, classes, functions, docstrings
+- **Paged Output**: Configurable page size for large files
+- **Binary Detection**: Safe handling of binary files
+- **UTF-8 Support**: Proper Unicode handling throughout
+
+## Installation
+
+```bash
+# Install from the tools directory
+cd tools/progressive-reveal-cli
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# View metadata
+reveal myfile.yaml
+
+# View structure
+reveal myfile.json --level 1
+
+# View preview with filtering
+reveal myfile.py --level 2 --grep "class"
+
+# View full content with paging
+reveal myfile.md --level 3 --page-size 50
+```
+
+## Usage with Claude Code
+
+This tool is particularly useful when working with Claude Code to explore large codebases or configuration files incrementally:
+
+```bash
+# Start with metadata to understand file size and type
+reveal config.yaml
+
+# Then view structure to see top-level keys
+reveal config.yaml --level 1
+
+# Preview specific sections with grep
+reveal config.yaml --level 2 --grep "database"
+
+# Finally view full content when needed
+reveal config.yaml --level 3
+```
+
+## Command Line Options
+
+```
+reveal <file> [options]
+
+Options:
+  --level <0-3>           Revelation level (default: 0)
+                          0 = metadata
+                          1 = structural synopsis
+                          2 = content preview
+                          3 = full content (paged)
+
+  --grep, -m <pattern>    Filter pattern (regex)
+  --context, -C <n>       Context lines around matches (default: 0)
+  --grep-case-sensitive   Use case-sensitive grep matching
+  --page-size <n>         Page size for level 3 (default: 120)
+  --force                 Force read of large or binary files
+```
+
+## Examples
+
+```bash
+# View file metadata
+reveal config.yaml
+
+# View YAML structure
+reveal config.yaml --level 1
+
+# Preview Python file
+reveal app.py --level 2
+
+# View full content with grep
+reveal app.py --level 3 --grep "class" --context 2
+
+# Force read large file
+reveal large.log --level 3 --force
+```
+
+## License
+
+MIT License

tools/progressive-reveal-cli/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "progressive-reveal-cli"
+version = "0.1.0"
+description = "A CLI tool for exploring files at different levels of detail"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Progressive Reveal Team"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+reveal = "reveal.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.coverage.run]
+source = ["reveal"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]

tools/progressive-reveal-cli/reveal/__init__.py

@@ -0,0 +1,4 @@
+"""Progressive Reveal CLI - A tool for exploring files at different levels of detail."""
+
+__version__ = "0.1.0"
+__author__ = "Progressive Reveal Team"

tools/progressive-reveal-cli/reveal/analyzers/__init__.py

@@ -0,0 +1,17 @@
+"""Analyzers for different file types."""
+
+from .base import BaseAnalyzer
+from .yaml_analyzer import YAMLAnalyzer
+from .json_analyzer import JSONAnalyzer
+from .markdown_analyzer import MarkdownAnalyzer
+from .python_analyzer import PythonAnalyzer
+from .text_analyzer import TextAnalyzer
+
+__all__ = [
+    'BaseAnalyzer',
+    'YAMLAnalyzer',
+    'JSONAnalyzer',
+    'MarkdownAnalyzer',
+    'PythonAnalyzer',
+    'TextAnalyzer',
+]

tools/progressive-reveal-cli/reveal/analyzers/base.py

@@ -0,0 +1,37 @@
+"""Base analyzer interface."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List
+
+
+class BaseAnalyzer(ABC):
+    """Base class for file type analyzers."""
+
+    def __init__(self, lines: List[str]):
+        """
+        Initialize analyzer with file lines.
+
+        Args:
+            lines: List of file lines
+        """
+        self.lines = lines
+
+    @abstractmethod
+    def analyze_structure(self) -> Dict[str, Any]:
+        """
+        Analyze file structure for Level 1.
+
+        Returns:
+            Dictionary with structural information
+        """
+        pass
+
+    @abstractmethod
+    def generate_preview(self) -> List[tuple[int, str]]:
+        """
+        Generate preview for Level 2.
+
+        Returns:
+            List of (line_number, content) tuples
+        """
+        pass