# CLI — Context

The CLI workspace provides headless validation — running the core validators without a
VS Code host. This is the component that enables CI/CD pipeline integration.

---

## What Lives Here

```
cli/
├── index.js          ← Entry point: parses args, runs validators, emits report, exits with code
└── configLoader.js   ← Loads and validates .acurity.json; exports parseConfig, matchesGlob, resolveFailOn
```

---

## CLI Flags

| Flag | Description |
|---|---|
| `--folder <path>` | Path to the folder of `.TXT` Architect files to validate |
| `--fail-on <error\|warning\|none>` | Exit code threshold (default: `error`) |
| `--surface <ide\|cicd\|all>` | Filter diagnostics by surface tag (default: `cicd`) |
| `--config <path>` | Path to a `.acurity.json` project config file (optional) |
| `--diff-only` | Only report diagnostics on lines changed vs `--base-branch` |
| `--base-branch <ref>` | Git ref to diff against for `--diff-only` (default: `main`) |
| `--format <text\|json>` | Output format (default: `text`) *(planned)* |

## Project Config (`.acurity.json`)

An optional JSON file committed to the Architect codebase repo (not this tooling repo).
Pass it with `--config .acurity.json`.

```json
{
  "naming": {
    "charToTypeMap":  { "z": "STRING", "s": "SHORT", "l": "LONG", "f": "DOUBLE", "b": "BOOLEAN", "d": "DATE", "t": "TIME" },
    "scopeToCharMap": { "global": "g", "parameter": "p", "function-scoped": "f" }
  },
  "overrides": [
    { "paths": ["src/legacy/**"], "failOn": "none" },
    { "paths": ["src/new/**"],    "failOn": "warning" }
  ]
}
```

Both sections are optional. When present:

- **`naming`** — overrides the default variable naming prefix conventions used by the naming
  validator. Partial maps are merged with defaults; only the keys you specify are overridden.
- **`overrides`** — per-path `failOn` thresholds. Paths are glob patterns matched against the
  file path relative to `--folder`. First match wins. Files that match no override use the
  global `--fail-on` value.

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | Validation passed (no violations at or above `--fail-on` threshold) |
| `1` | Validation failed (one or more violations at or above threshold) |
| `2` | Runtime error (bad args, folder not found, unexpected exception) |

## JSON Report Schema

```json
{
  "summary": {
    "filesScanned": 12,
    "totalDiagnostics": 4,
    "errors": 1,
    "warnings": 3
  },
  "files": [
    {
      "path": "src/reports/MY_REPORT.TXT",
      "diagnostics": [
        {
          "ruleId": "ACU-FNC-003",
          "severity": "error",
          "message": "...",
          "line": 42
        }
      ]
    }
  ]
}
```

---

## Adding Flags

1. Parse the new flag in `index.js` (plain `process.argv` parsing — no arg-parser library).
2. Pass it through to the relevant `core/` function.
3. Document it in the table above and in `dev-docs/CICD_ARCHITECTURE.md`.

---

## Integration Test Checklist

These scenarios must pass whenever the CLI entry point is modified:

| Scenario | Expected exit |
|---|---|
| Folder with no violations | `0` |
| Folder containing an error | `1` |
| `--fail-on warning` with only warnings present | `1` |
| `--fail-on none` regardless of violations | `0` |
| Non-existent folder path | `2` |
| `--format json` output contains `summary.filesScanned` | `0` or `1` |
