# 7. JSON output for LLM prompt injection

**Date:** 2026-07-03

**Status:** Accepted

## Context

The text table output is human-readable but not directly usable by an LLM. To use Dervish conventions in another agent or coding session, the output must be parsed, reformatted, and injected into a prompt — an extra friction step.

An LLM consuming conventions needs:
- Structured data it can read directly (no parsing).
- All metadata per convention (grammar, imports, args, files, packages).
- Compact enough to fit in context without overflow.

## Decision

Add a `--json` flag that outputs a structured JSON array instead of the text table.

JSON structure:
```json
[{
  "language": ".kt",
  "conventions": [{
    "label": "every → assertEquals → verify",
    "method_count": 16,
    "algorithm": "CRX",
    "grammar": "every+.assertEquals.verify+.any?",
    "mdl_score": 8.64,
    "imports": ["import io.mockk.every", "..."],
    "packages": ["eu/corentic/springrag/agent/capability"],
    "arg_patterns": {
      "assertEquals": {
        "occurrences": 42,
        "arg_count": {"min": 2, "max": 3, "common": 2},
        "patterns": [{"count": 30, "args": 2, "types": ["lit", "var"]}]
      }
    }
  }],
  "total_methods": 665
}]
```

Also accepts `--format json` and `--format text` for explicit control.

## Consequences

**Positive:**
- LLM consumes the JSON directly — no parsing step needed.
- All metadata in one object per convention — imports, args, files, packages all together.
- `--json` is a single flag — the default text output remains for human review.

**Negative:**
- JSON is more verbose than text (full import list instead of truncated preview).
- No easy way to limit output size — a large codebase produces JSON that may overflow context.
  - Mitigation: `--include` flag filters files before analysis.

## Alternatives Considered

- **YAML output**: More readable, but less universally parseable by LLMs.
- **CSV output**: Too flat for nested data (arg_patterns, imports list).
- **Custom prompt template**: Would need per-framework templates. JSON is framework-agnostic.
- **No structured output**: User must pipe through `jq` or manual reformatting. Bad UX.