batless 0.2.4

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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

# Development Guide for batless

## Quick Start

1. **Clone and setup**

   ```bash
   git clone https://github.com/docdyhr/batless
   cd batless
   cargo build
   ```

2. **Run tests**

   ```bash
   cargo test
   cargo clippy -- -D warnings
   cargo fmt --check
   ```

3. **Make changes**
   - Create a feature branch: `git checkout -b feature/your-feature`
   - Make your changes
   - Run tests and linting
   - Commit with clear messages

## Release Process

### Automated Release (Recommended)

We now use a PR-based release workflow that respects branch protection:

```bash
# Trigger a release PR
gh workflow run manual-release-pr.yml -f version=0.1.4 -f create_tag=true -f dry_run=false

# This will:
# 1. Create a release branch (release/0.1.4)
# 2. Update version in Cargo.toml and Cargo.lock
# 3. Update CHANGELOG.md
# 4. Create a PR to main
# 5. After PR merge, automatically create tag v0.1.4
# 6. Trigger the release workflow
```

### Manual Release (if needed)

1. Create a release branch

   ```bash
   git checkout -b release/0.1.4
   ```

2. Update version

   ```bash
   # Update version in Cargo.toml
   sed -i 's/^version = ".*"/version = "0.1.4"/' Cargo.toml
   cargo update --workspace
   ```

3. Update CHANGELOG.md with release notes

4. Create PR and merge

5. After merge, create tag

   ```bash
   git checkout main
   git pull
   git tag -a v0.1.4 -m "Release 0.1.4"
   git push origin v0.1.4
   ```

## CI/CD Workflows

### Available Workflows

1. **Quality & Coverage** (`.github/workflows/quality.yml`)
   - Aggregated gates: markdown lint, coverage (cargo-llvm-cov), code quality (fmt, clippy, unused deps/features, dead code heuristic), documentation quality, complexity analysis, performance regression (non-blocking initially)
   - Posts summary comment on PRs

2. **Release** (`.github/workflows/release.yml`)
   - Triggered by version tags (v*)
   - Builds and publishes binaries
   - Publishes to crates.io

3. **Manual Release PR** (`.github/workflows/manual-release-pr.yml`)
   - Creates release PRs, bumps version, regenerates CHANGELOG via `scripts/prep-release-changelog.sh`
   - Use this for all releases (preferred path)

4. **Security Review** (`.github/workflows/security.yml`)
   - Audit (cargo audit / deny), dependency review, CodeQL, Semgrep, SBOM, license scan, Scorecard

5. **Fuzz Testing** (`.github/workflows/fuzz.yml`)
   - Nightly + PR short fuzz run on tokenizer target (non-blocking)
   - Adds PR comment with summary & artifact list

6. **Changelog Generation** (`.github/workflows/changelog.yml`)
   - Manual generation of unreleased changelog artifact

7. **Performance Baseline Update** (`.github/workflows/performance-baseline.yml`)
   - Refreshes & commits `benchmark_baseline.txt` after intentional perf improvements

### Manual Workflow Triggers

```bash
# Full test suite
gh workflow run workflow-dispatch.yml -f workflow_type=full-test-suite

# Security audit
gh workflow run workflow-dispatch.yml -f workflow_type=security-audit

# Performance benchmark
gh workflow run workflow-dispatch.yml -f workflow_type=performance-benchmark

# Quality check
gh workflow run workflow-dispatch.yml -f workflow_type=quality-check

# Quick validation
gh workflow run workflow-dispatch.yml -f workflow_type=quick-validation
```

## Branch Protection

The `main` branch is protected and requires:

- 5 status checks to pass:
  - Test (ubuntu-latest, stable)
  - Test (windows-latest, stable)
  - Test (macos-latest, stable)
  - Security Audit
  - Code Coverage
- PR reviews before merging
- Conversation resolution

## Development Tips

### Running Locally

```bash
# Debug mode
cargo run -- src/main.rs

# Release mode (optimized)
cargo run --release -- src/main.rs

# With specific options
cargo run -- --mode=summary --max-lines=50 src/lib.rs
```

### Testing

```bash
# All tests
cargo test

# Specific test
cargo test test_name

# Integration tests only
cargo test --test integration_tests

# With output
cargo test -- --nocapture
```

### Performance

```bash
# Run benchmarks
cargo bench

# Update performance baseline (after validating improvement)
gh workflow run performance-baseline.yml

# Profile with flamegraph (requires cargo-flamegraph)
cargo flamegraph -- benchmark_files/large.rs

# Check binary size
cargo build --release
ls -lh target/release/batless
```

### Common Issues

1. **Release workflow fails**: Use the PR-based release workflow instead of direct push
2. **Tests fail on Windows**: Check line ending handling (CRLF vs LF)
3. **Performance regression**: Run benchmarks before merging