validate_spec
Lint a .3tg.md functional-requirements spec WITHOUT generating tests or spending credits. Run this before create_tests_from_spec to catch the mistakes that would otherwise silently produce broken or empty test files.
WHY THIS EXISTS: 3TG's spec parser is deliberately lenient — it never errors on a malformed .3tg.md, it just silently ignores tables it can't parse and emits whatever column names it sees. So a spec can look fine yet compile to nothing useful. This tool runs the same parse 3TG would, then cross-checks the result against the source's real exports (via 3TG's own analysis) and reports problems.
WHAT IT CATCHES:
ERROR: the spec parsed to an empty config (no valid table — usually a wrong return-column header; it must be the literal
=>, or a row/header column-count mismatch).ERROR: a table targets a function the source does not export (the generated test would import a non-existent symbol).
WARNING: a parameter column matches no parameter of any exported function (likely a typo such as
input_afora).INFO: exported functions the spec doesn't cover yet.
WHAT IT CANNOT CHECK: whether the => expected-return values are arithmetically correct — 3TG itself doesn't verify that. Treat a valid: true result as "structurally sound and ready to compile", not "the expected values are right".
This tool is FREE — no clientId, no quota, no test cases consumed. Surface the summary and any diagnostics back to the user; if there are errors, help them fix the spec, then re-validate.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fileName | Yes | Path of the source file relative to the project root (e.g. "src/foo/bar.ts"). Must end in `.ts` or `.tsx` — the extension tells 3TG whether to parse a React component table or a unit table. The spec filename is derived by replacing the extension with `.3tg.md`. | |
| sourceCode | Yes | Full UTF-8 contents of the source file the spec describes. Needed so 3TG can compute the ground-truth list of exported functions and their parameter names to cross-check the spec against. | |
| specContent | Yes | Full UTF-8 contents of the `.3tg.md` spec to validate — exactly as it lives under `.3tg/<sourceDir>/<basename>.3tg.md`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| valid | Yes | True iff there are zero error-severity diagnostics. Warnings and info do NOT flip this to false — they're advisory. `true` means "structurally sound; safe to compile", not "expected values are correct". | |
| parsed | Yes | What 3TG actually parsed — useful for eyeballing coverage. | |
| summary | Yes | One-line human summary — lead with this when reporting back. | |
| diagnostics | Yes | Ordered findings. `error` = will break generation; `warning` = probably a mistake but generation still runs; `info` = advisory (coverage gaps, unverifiable columns). |