Skip to content

CLAUDE.md

Latest commit

 

History

History
111 lines (84 loc) · 3.88 KB

CLAUDE.md

File metadata and controls

111 lines (84 loc) · 3.88 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

IMPORTANT: When making significant changes to the project structure, testing infrastructure, development workflow, or adding new tools/utilities, update this CLAUDE.md file to reflect those changes so future instances of Claude Code have accurate information.

Project Overview

This is a collection of quick utility tools from the CON (Center for Open Neuroscience) team. The repository contains standalone command-line utilities written primarily in Python, with minimal package infrastructure.

Key Utilities

show-paths

Located in bin/show-paths. This is the primary tool in the repository - a Python script that visualizes paths to lines in structured files using indentation-based navigation. It's useful for:

  • Navigating complex XML/JSON files (e.g., datacite schemas)
  • Finding elements in DICOM dumps (medical imaging data)
  • Tracing structure in Python code and other indented formats

Key features:

  • Two output formats: inline (default) and full-lines
  • Regex-based search (-e flag)
  • Line number filtering (-n flag)
  • Optional color output with termcolor (requires termcolor package)
  • Reads from stdin or file

run-and-xclip

Located in bin/run-and-xclip. A bash helper that runs a command and copies its output to X clipboard formatted as a GitHub issue <details> block.

Development Commands

Testing

The project uses pytest with tox for testing across multiple Python versions (3.8-3.13):

# Run tests on all Python versions
tox

# Run tests on specific Python version
tox -e py313

# Run tests with verbose output
tox -e py313 -- -v

# Run a specific test
tox -e py313 -- tests/test_show_paths.py::test_show_paths_color_on

# Run tests on multiple versions
tox -e py38,py310,py312

# Run tests directly with pytest (without tox)
pytest -v

Test Coverage (22 tests):

  • Basic functionality: regex search, line numbers, stdin input
  • Format testing: inline vs full-lines format differences
  • Color output: verification of ANSI codes with --color=on, --color=off, --color=auto
  • Structure parsing: Python nested functions, XML hierarchy, JSON nesting
  • Edge cases: missing files, empty files, out-of-range line numbers, case sensitivity
  • Help output formatting

Test Conventions:

  • All tests should be marked with @pytest.mark.ai_generated when generated by AI assistants
  • Test fixtures are located in tests/data/ (sample Python, XML, JSON files)
  • The ai_generated marker is registered in pyproject.toml for filtering/identification
  • Color tests use FORCE_COLOR=1 environment variable to test ANSI codes in non-TTY environments

Code Quality

The project uses pre-commit hooks with the following checks:

  • black - Code formatting (max line length 100)
  • isort - Import sorting
  • flake8 - Linting (max line length 100)
  • codespell - Spell checking
  • Standard pre-commit hooks (trailing whitespace, EOF fixer, etc.)

Run pre-commit manually:

pre-commit run --all-files

Install pre-commit hooks:

pre-commit install

Run linting via tox:

tox -e lint

CI/CD

GitHub Actions runs codespell on pushes and PRs to main branch.

Project Structure

  • bin/ - Executable utilities (the actual tools)
  • tests/ - Test directory
    • tests/data/ - Test fixtures (sample Python, XML, JSON files)
    • tests/test_show_paths.py - Tests for show-paths utility
  • Configuration files:
    • pyproject.toml - black, isort, and pytest configuration
    • setup.cfg - flake8 configuration (max line length 100)
    • tox.ini - tox configuration for testing and linting
    • .pre-commit-config.yaml - pre-commit hooks configuration

Code Style

  • Black formatting with excludes for certain patterns
  • isort with black profile
  • Line length: 100 characters (enforced by flake8 and black)
  • Force sort within sections for imports