"SchemaLinter-OneShot" was designed as a lightweight, one-shot linter built entirely on the Python standard library, purposely eliminating excessive dependencies like heavy external validation libraries.
_extract_json) json ...
fenced code blocks.{ to the last }._validate_types) jsonschema, it recursively scans the payload to ensure the presence of required keys and performs minimal, strict type checking.
The implementation appeared beautifully cohesive. However, during the QA phase, when implementing the requirement to "format error handling into JSON when arguments are missing," I fell into a deep quagmire caused by the internal specifications of the standard framework.
When executing the script without arguments, instead of the intended JSON-formatted error, the default plain-text usage error from argparse leaked into the standard error stream.
$ python3 V2_PROD_20261007_030033_test.py
usage: V2_PROD_20261007_030033_test.py [-h] -s SCHEMA [-i INPUT]
[--mode {strict,prompt}]
V2_PROD_20261007_030033_test.py: error: the following arguments are required: -s/--schema
💡 For immediate deployment: The complete source code suite (ZIP) for this architecture is available on Gumroad for $0+ (Pay What You Want).
On the development side, I took the approach of catching the error using a try...except SystemExit: block to intercept the termination and convert it into a JSON payload before exiting, as shown below:
try:
args = parser.parse_args()
except SystemExit:
print(json.dumps({
"status": "error",
"message": "Argument parsing failed. Required argument '-s/--schema' is missing."
}, ensure_ascii=False))
sys.exit(2)
However, this approach contained two fatal oversights regarding the lifecycle of the Python argparse module:
argparse detects missing required arguments or invalid options, it outputs a usage message directly to sys.stderr via its internal error() method SystemExit). except block to output the JSON payload, the plain-text error message had already been flushed to the standard error stream.--help (-h) with Validation Errors SystemExit(0) after successfully displaying the help message.except SystemExit: implementation above, Following the feedback from QA, I had to acknowledge the architectural limitations of relying on exception hooking within argparse. To build a truly robust JSON-only CLI, extensive refactoring would be required:
argparse.ArgumentParser class.sys.argv prior to parsing to insert an explicit, decoupled validation layer upfront.
However, the initial requirement for this tool was to be a "lightweight, one-shot tool that operates reliably within one second to ensure CI/CD pipeline health." Continuously expending engineering effort on hacking standard frameworks at the primitive layer of CLI argument parsing would severely degrade the project's Return on Investment (ROI).
Making a comprehensive architectural judgment, I decided to avoid complicating the codebase with brittle patches in this version (V2). Consequently, I chose to temporarily close the project as [Development Incomplete], extracting the technical debt and passing the accumulated knowledge on to future designs.
The architectural insights gained from this challenge will serve as valuable anti-patterns for future CLI tool development.
If this engineering log saved your production server (and your sanity), consider supporting our architecture on GitHub Sponsors.