0
# CI Integration
1

2
Rome's CI command provides combined formatting and linting checks optimized for continuous integration environments. It performs both format checking and linting in a single command, making it ideal for build pipelines and automated quality gates.
3

4
## Capabilities
5

6
### CI Command
7

8
The comprehensive CI command that runs both formatter and linter checks.
9

10
```bash { .api }
11
/**
12
 * Run the linter and formatter check on a set of files
13
 * 
14
 * Usage: rome ci [OPTIONS] <INPUTS...>
15
 *
16
 * INPUTS can be one or more filesystem paths, each pointing to a single file
17
 * or an entire directory to be searched recursively for supported files
18
 */
19
rome ci <INPUTS...>
20
```
21

22
**Core Options:**
23

24
```bash { .api }
25
--formatter-enabled       # Allow to enable or disable the formatter check (default: true)
26
--linter-enabled         # Allow to enable or disable the linter check (default: true)  
27
--max-diagnostics <number> # Cap the amount of diagnostics displayed (default: 50)
28
--verbose                # Print additional verbose advice on diagnostics
29
```
30

31
**All formatting options are also available** (see [Formatting](./formatting.md) for complete list):
32

33
```bash { .api }
34
--indent-style <tabs|space>              # Change indentation character (default: tabs)
35
--indent-size <number>                   # Spaces for indentation when using space style (default: 2)
36
--line-width <number>                    # Maximum characters per line (default: 80)
37
--quote-style <single|double>            # Quotation character for strings (default: double)
38
--quote-properties <as-needed|preserve>  # When properties should be quoted (default: as-needed)
39
--trailing-comma <all|es5|none>          # Trailing commas in multi-line structures (default: all)
40
--semicolons <always|as-needed>          # When to print semicolons (default: always)
41
```
42

43
### Feature Control
44

45
Selectively enable or disable parts of the CI check:
46

47
```bash { .api }
48
# Run only formatter check
49
rome ci src/ --linter-enabled=false
50

51
# Run only linter check  
52
rome ci src/ --formatter-enabled=false
53

54
# Run both (default behavior)
55
rome ci src/
56
```
57

58
## Usage Examples
59

60
### Basic CI Usage
61

62
```bash
63
# Standard CI check with both formatter and linter
64
rome ci src/
65

66
# Check specific files
67
rome ci src/index.js src/utils.ts
68

69
# Check with custom formatting rules
70
rome ci src/ --indent-style=space --line-width=120
71

72
# Verbose output for debugging
73
rome ci src/ --verbose
74
```
75

76
### Selective Checks
77

78
```bash
79
# Only check formatting (skip linting)
80
rome ci src/ --linter-enabled=false
81

82
# Only check linting (skip formatting)
83
rome ci src/ --formatter-enabled=false
84

85
# Custom diagnostic limits for CI logs
86
rome ci src/ --max-diagnostics=20
87
```
88

89
### CI Pipeline Integration
90

91
```bash
92
# GitHub Actions example
93
- name: Run Rome CI
94
  run: rome ci src/
95

96
# With custom settings
97
- name: Run Rome CI with custom rules
98
  run: rome ci src/ --line-width=100 --max-diagnostics=30
99
```
100

101
## Configuration File Usage
102

103
CI behavior can be configured in `rome.json`:
104

105
```json { .api }
106
{
107
  "formatter": {
108
    "enabled": true,
109
    "indentStyle": "space",
110
    "indentSize": 2,
111
    "lineWidth": 100
112
  },
113
  "linter": {
114
    "enabled": true,
115
    "rules": {
116
      "recommended": true
117
    }
118
  },
119
  "files": {
120
    "ignore": [
121
      "dist/**",
122
      "build/**",
123
      "node_modules/**"
124
    ]
125
  }
126
}
127
```
128

129
## CI-Specific Features
130

131
### Performance Optimizations
132

133
The CI command is optimized for build environments:
134

135
- **Parallel processing**: Processes multiple files concurrently
136
- **Memory efficient**: Optimized memory usage for large codebases
137
- **Fast exit**: Stops on first error when appropriate
138
- **Reduced output**: Less verbose by default than interactive commands
139

140
### Diagnostic Management
141

142
```bash { .api }
143
--max-diagnostics <number>  # Cap diagnostics to prevent log overflow (default: 50)
144
--verbose                  # Enable detailed diagnostic output when needed
145
```
146

147
### Exit Codes
148

149
The CI command uses standard exit codes for integration:
150

151
- `0`: All checks passed
152
- `1`: Formatting or linting issues found
153
- `2`: Configuration or runtime error
154

155
## Common CI Patterns
156

157
### GitHub Actions
158

159
```yaml
160
name: Code Quality
161
on: [push, pull_request]
162

163
jobs:
164
  check:
165
    runs-on: ubuntu-latest
166
    steps:
167
      - uses: actions/checkout@v3
168
      - uses: actions/setup-node@v3
169
        with:
170
          node-version: '18'
171
      - run: npm ci
172
      - run: rome ci src/
173
```
174

175
### GitLab CI
176

177
```yaml
178
code_quality:
179
  stage: test
180
  script:
181
    - npm ci
182
    - rome ci src/
183
  only:
184
    - merge_requests
185
    - main
186
```
187

188
### Jenkins
189

190
```groovy
191
pipeline {
192
    agent any
193
    stages {
194
        stage('Code Quality') {
195
            steps {
196
                sh 'npm ci'
197
                sh 'rome ci src/'
198
            }
199
        }
200
    }
201
}
202
```
203

204
### Azure DevOps
205

206
```yaml
207
steps:
208
- task: NodeTool@0
209
  inputs:
210
    versionSpec: '18'
211
- script: npm ci
212
- script: rome ci src/
213
  displayName: 'Run Rome CI'
214
```
215

216
## Output Formats
217

218
### Human-Readable (Default)
219

220
Standard terminal output with colors and formatting:
221

222
```bash
223
rome ci src/
224
```
225

226
### JSON Output
227

228
Structured output for tooling integration:
229

230
```bash
231
rome ci src/ --json
232
```
233

234
JSON output includes:
235
- File-level results
236
- Rule violations with locations
237
- Formatting differences
238
- Summary statistics
239
- Error details
240

241
## Error Handling
242

243
### Formatter Errors
244

245
- **Syntax errors**: Reports files that cannot be parsed
246
- **Write permissions**: Handles read-only files gracefully
247
- **Binary files**: Automatically skips non-text files
248

249
### Linter Errors
250

251
- **Rule violations**: Reports all configured rule violations
252
- **Configuration errors**: Clear messages for config issues
253
- **File processing**: Continues with other files on individual failures
254

255
### Build Integration
256

257
```bash
258
# Fail build on any issues
259
rome ci src/ || exit 1
260

261
# Allow warnings but fail on errors (requires configuration)
262
rome ci src/
263

264
# Generate reports for analysis
265
rome ci src/ --json > rome-report.json
266
```
267

268
## Performance Considerations
269

270
### Large Codebases
271

272
```bash
273
# Limit file size to avoid processing large generated files
274
rome ci src/ --files-max-size=1048576
275

276
# Use file ignoring for performance
277
# Configure in rome.json:
278
{
279
  "files": {
280
    "ignore": ["**/*.min.js", "dist/**", "coverage/**"]
281
  }
282
}
283
```
284

285
### Parallel Processing
286

287
Rome automatically uses multiple CPU cores for processing, but you can influence performance:
288

289
- **File organization**: Group related files in directories
290
- **Ignore patterns**: Exclude unnecessary files early
291
- **Daemon mode**: Use `--use-server` for repeated runs
292

293
### Memory Usage
294

295
For memory-constrained environments:
296

297
```bash
298
# Process smaller batches
299
rome ci src/components/
300
rome ci src/utils/
301
rome ci src/pages/
302

303
# Use daemon mode to amortize startup costs
304
rome start
305
rome ci src/ --use-server
306
rome stop
307
```