Repository navigation
Full error UX: structured errors, --explain flag, recovery hints #148
Description
Problem
v0.1 delivers baseline file+line errors. v1.0 requires production-grade error UX: structured machine-readable output, extended explanations, and recovery suggestions.
Acceptance Criteria
-
--jsonflag on all commands outputs structured error objects (code, file, line, col, message) -
nlsc explain E001(or--explainflag) gives extended documentation for each error code - Every error class has a documented error code
- Recovery hints are context-aware (e.g. suggests correct @use path, correct type name)
- Editor/LSP integration can consume structured errors
Why This Blocks v1.0
Production tools have production error handling. This is a trust signal for engineering teams.
Activity
fix(cli): add structured JSON diagnostics (#148)
Mnehmos commentedon Apr 2, 2026
Delivered the first structured-error slice in / PR #168.
This slice adds:
Still remaining for #148:
Mnehmos commentedon Apr 2, 2026
Delivered the first structured-error slice in
1ba3324/ PR #168.This slice adds:
code,file,line,col,message, optionalhint--jsonsupport fornlsc verify, plus matchingcompileandrunsupport while the implementation stayed compactEFILE001), parse errors (EPARSE001), stdlib@useresolution errors (EUSE001), and dependency resolution errors (E_RESOLUTION)Still remaining for #148:
--explain/nlsc explain)Merge pull request #168 from Mnehmos/fix/148-structured-error-json
fix(cli): add error code explanations
Mnehmos commentedon Apr 2, 2026
Delivered the next Gitflow slice in PR #169.\n\nThis slice adds a centralized catalog for the currently emitted compile/verify/run CLI error codes, adds , and updates for the active codes.\n\nStill remaining on #148 after this slice: any broader error taxonomy expansion beyond the currently emitted compile/verify/run codes, any additional UX/formatting work around explanations, and any other acceptance points not covered by the explain/catalog/docs slice.
Mnehmos commentedon Apr 2, 2026
Delivered the next Gitflow slice in PR #169.
This slice adds a centralized catalog for the currently emitted compile/verify/run CLI error codes, adds
nlsc explain <ERROR_CODE>, and updatesdocs/error-reference.mdfor the active codes.Still remaining on #148 after this slice: any broader error taxonomy expansion beyond the currently emitted compile/verify/run codes, any additional UX or formatting work around explanations, and any other acceptance points not covered by the explain/catalog/docs slice.
fix(cli): add graph and diff JSON diagnostics
Mnehmos commentedon Apr 2, 2026
Delivered this slice in via PR #170.
This slice adds structured error output to and , reusing the shared diagnostic contract already used by compile/verify/run. It reuses and , and adds the minimum new graph-only codes for lookup and unsupported ANLU graph formats (, ). Tests and were updated for the new behavior.
Still remaining on #148 after this slice:
Mnehmos commentedon Apr 2, 2026
Delivered this slice in fd46815 via PR #170.
This slice adds --json structured error output to nlsc graph and nlsc diff, reusing the shared diagnostic contract already used by compile/verify/run. It reuses EFILE001 and EPARSE001, and adds the minimum new graph-only codes for --anlu lookup and unsupported ANLU graph formats (EGRAPH001, EGRAPH002). Tests and docs/error-reference.md were updated for the new behavior.
Still remaining on #148 after this slice:
fix(cli): add json diagnostics for nlsc test
37 remaining items
Mnehmos commentedon Apr 3, 2026
Follow-up from PR #170 is fixed in #184. {
"ok": false,
"command": "graph",
"diagnostics": [
{
"code": "ECLI001",
"file": "",
"line": null,
"col": null,
"message": "the following arguments are required: file",
"hint": "Rerun the command with --help to inspect the required arguments and valid options."
}
],
"usage": "usage: nlsc graph [-h] [-f {mermaid,dot,ascii}] [-a ANLU] [--dataflow]\n [-o OUTPUT] [--json]\n file",
"error_type": "ECLI001"
} and {
"ok": false,
"command": "diff",
"diagnostics": [
{
"code": "ECLI001",
"file": "",
"line": null,
"col": null,
"message": "the following arguments are required: file",
"hint": "Rerun the command with --help to inspect the required arguments and valid options."
}
],
"usage": "usage: nlsc diff [-h] [--stat] [--full] [--json] file",
"error_type": "ECLI001"
} now return structured JSON payloads on successful runs, including graph metadata/rendered output and diff summaries/serialized changes so the JSON contract is coherent on both success and failure paths.
Mnehmos commentedon Apr 3, 2026
Follow-up from PR #173 is in PR #185. This fixes {
"ok": false,
"command": "atomize",
"diagnostics": [
{
"code": "EATOM002",
"file": ".",
"line": null,
"col": null,
"message": "Atomize failed for .: WindowsPath('.') has an empty name",
"hint": "Check the output path and local filesystem permissions, then rerun
nlsc atomize."}
],
"file": "."
} so default output-path derivation no longer raises an uncaught before diagnostics are emitted. The command now keeps that failure inside the handled atomize flow and returns a structured payload instead of a traceback, with focused regression coverage for both JSON and direct command error handling.
Mnehmos commentedon Apr 3, 2026
Superseding the previous shell-mangled comment.
Follow-up from PR #173 is in PR #185. This fixes
nlsc atomize . --jsonso default output-path derivation no longer raises an uncaughtValueErrorbefore diagnostics are emitted. The command now keeps that failure inside the handled atomize flow and returns a structuredEATOM002payload instead of a traceback, with focused regression coverage for both JSON and direct command error handling.fix(cli): route init and assoc parser bootstrap to JSON
Mnehmos commentedon Apr 3, 2026
Implemented the parser-bootstrap JSON follow-up in 6def1e9 via #186. Added failing coverage for treesitter and , updated the bootstrap allowlist, and extended EPARSE002 explain coverage.
Mnehmos commentedon Apr 3, 2026
Follow-up note: this is specifically the parser-bootstrap JSON gap for treesitter init --json and assoc --json.
fix(cli): cover atomize parser bootstrap JSON
Mnehmos commentedon Apr 3, 2026
Implemented the remaining atomize parser-bootstrap JSON gap in commit ec49b36 and opened PR #187.\n\nCovered by CLI JSON/explain tests for plus emitted_by metadata alignment.
Mnehmos commentedon Apr 3, 2026
Implemented the remaining atomize parser-bootstrap JSON gap in commit ec49b36 and opened PR #187.
Covered by CLI JSON/explain tests for --parser treesitter atomize --json plus EPARSE002 emitted_by metadata alignment.
fix(cli): harden compile and lock update JSON I/O
Mnehmos commentedon Apr 3, 2026
Completed the compile/lock:update JSON and file-I/O slice in #188.
Commit: 97aabf7
fix(cli): harden graph JSON artifact writes
Mnehmos commentedon Apr 3, 2026
Implemented the graph JSON artifact-write slice in commit adf9996.
PR: #189
Validation:
Mnehmos commentedon Sep 10, 2026
Audited against current master — all acceptance criteria are delivered:
--jsonon all commands emits structured diagnostics (code, file, line, col, message, hint) — including the newnlsc ircommand and warnings-vs-failure separation (ok,diagnostics,warnings,scaffoldfields from bug(semantics): reject executable prose and implicit placeholder returns #190/feat(semantics): resolve operation signatures and type-check calls, bindings, and returns #195).nlsc explain <code>prints extended documentation (title, summary, emitted-by, common causes, next steps) and--jsonreturns it structured; unknown codes getEEXPLAIN001.nlsc/error_catalog.py— ECLI/EFILE/EPARSE/EUSE/E_RESOLUTION/ETEST/ECONTRACT/ETARGET/EVALIDATE/E_RUN/EEXEC/EGRAPH/ELOCK/ELSP/EASSOC/EWATCH plus the EIR001–004 and ESEM001–012 families, each with causes and next steps.--stdlib-path, strict-mode hints show the ELSE migration pattern.nlsc lsppublishes structured LSP diagnostics (line, severity, source) on open/change.Closing as delivered.