batless 0.2.2

A non-blocking, LLM-friendly code viewer inspired by bat
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

# CLAUDE.md

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

## Project Overview

batless is a Rust-based CLI tool designed as a non-blocking, AI-friendly code viewer. It's inspired by `bat` but optimized for AI code assistants, CI/CD pipelines, and non-interactive workflows. The tool never hangs or blocks, making it ideal for automation.

## Development Commands

### Build and Test

```bash
cargo build                          # Debug build
cargo build --release               # Release build
cargo test                          # Run all tests
cargo test --test integration_tests # Run integration tests only
cargo test test_name                # Run specific test
```

### Code Quality

```bash
cargo clippy -- -D warnings         # Linting with warnings as errors
cargo fmt --all -- --check          # Check formatting
cargo fmt                           # Format code
cargo audit                         # Security vulnerability audit
```

### Running the Tool

```bash
cargo run -- file.rs                # Run in debug mode
cargo run --release -- file.rs      # Run in release mode
./target/debug/batless file.rs      # Run debug binary directly
./demo.sh                           # Run demo script
```

## 🚀 Release Process

### Automated Release (Recommended)

```bash
# Install required tools
cargo install cargo-release

# Set crates.io token (one-time setup)
export CARGO_REGISTRY_TOKEN="your-token-here"

# Full automated release
./scripts/release.sh 0.2.1

# Or use cargo-release directly
cargo release 0.2.1 --execute
```

### Manual/Emergency Release

If the automated process fails:

```bash
# 1. Publish to crates.io
cargo release publish --execute

# 2. Create GitHub release
git tag v0.2.1 -m "Release message"
git push origin v0.2.1
gh release create v0.2.1 --title "Release Title" --notes "Release notes"

# 3. Verify publication
curl -s "https://crates.io/api/v1/crates/batless" | jq -r '.crate.max_version'
curl -s "https://api.github.com/repos/docdyhr/batless/releases/latest" | jq -r '.tag_name'
```

### Release Checklist

- [ ] All tests passing (201 tests: 162 unit + 33 integration + 6 property)
- [ ] Version updated in Cargo.toml
- [ ] CHANGELOG.md updated with release notes
- [ ] Published to crates.io
- [ ] GitHub release created with proper tag
- [ ] Homebrew formula updated (automatic via workflow)

### CI/CD Workflows

```bash
# Manual workflow triggers available:
gh workflow run workflow-dispatch.yml -f workflow_type=full-test-suite
gh workflow run workflow-dispatch.yml -f workflow_type=security-audit
gh workflow run workflow-dispatch.yml -f workflow_type=performance-benchmark
gh workflow run workflow-dispatch.yml -f workflow_type=quality-check
gh workflow run workflow-dispatch.yml -f workflow_type=quick-validation

# Release workflow (triggered by tags):
gh workflow run release.yml --ref v0.2.1
```

## Architecture

### Core Components

- **main.rs**: CLI entry point using clap for argument parsing
- **lib.rs**: Core library with streaming file processing, syntax highlighting, and summary extraction
- **integration_tests.rs**: Comprehensive CLI behavior tests

### Key Design Principles

1. **Streaming Architecture**: Never loads entire files into memory - processes line by line
2. **Cached Resources**: Uses lazy_static for syntax/theme sets to optimize performance
3. **Result-Based Error Handling**: All operations return Result types for proper error propagation
4. **Modular Output Modes**: Cleanly separated plain, highlight, JSON, and summary modes

### Output Modes

- **plain**: Raw text without highlighting
- **highlight**: Syntax-highlighted output (default)
- **json**: Structured JSON with metadata, optionally includes tokens and summary
- **summary**: Extracts important code structures (functions, classes, imports)

### Important Implementation Details

- Language detection uses file extensions via syntect's syntax set
- Smart truncation supports both `--max-lines` and `--max-bytes` limits
- Summary extraction identifies functions, classes, imports, and type definitions
- Token extraction uses basic word boundary splitting for AI processing
- ANSI stripping is automatic in non-terminal environments

## Testing Guidelines

When modifying the codebase:

1. Run the full test suite with `cargo test`
2. Add integration tests for new CLI features in `tests/integration_tests.rs`
3. Add unit tests for new library functions in `src/lib.rs`
4. Ensure all tests pass on CI before considering changes complete

## Development Workflow

### Feature Development

- Use feature branches for changes
- Implement new features with comprehensive test coverage
- Ensure clean, modular code following Rust best practices

## Common Tasks

### Adding a New Output Mode

1. Add the variant to `OutputMode` enum in `src/lib.rs`
2. Update the clap `ValueEnum` implementation
3. Implement the logic in `process_file()` function
4. Add integration tests for the new mode

### Updating Dependencies

1. Update version in `Cargo.toml`
2. Run `cargo update` to update lock file
3. Run `cargo test` to ensure compatibility
4. Run `cargo audit` to check for vulnerabilities

```