Instruction on check_json_files.py script

Owner: Vadim Rudakov, rudakow.wadim@gmail.com
Version: 0.1.0
Birth: 2026-01-21
Last Modified: 2026-01-21

1. Architectural Overview: The SVA Principle¶

This script validates JSON files for syntax errors using Python’s standard library json module.

This tool is designed to serve as a quality gate in CI/CD, preventing commits with malformed JSON files that could break configuration, data pipelines, or application behavior.

It adheres to the Smallest Viable Architecture (SVA) principle.

2. Key Capabilities & Logic¶

A. JSON Syntax Validation¶

The script validates:

B. Directory Exclusions¶

When scanning directories, the script automatically excludes:

3. Technical Architecture¶

The script is organized into specialized classes to maintain clarity:

4. Operational Guide¶

Configuration Reference¶

• Primary Script: tools/scripts/check_json_files.py

• Pre-commit Config: .pre-commit-config.yaml

• CI Config: .github/workflows/quality.yml

Command Line Interface¶

check_json_files.py [files...] [--verbose]

Exit Codes:

• 0 = All JSON files valid

• 1 = Validation errors found

Manual Execution Commands¶

Run these from the repository root using uv for consistent environment resolution:

Examples¶

1. Check specific files:

2. Check with verbose output:

5. Validation Layers¶

Layer 1: Local Pre-commit Hook¶

The first line of defense runs automatically during the git commit process to prevent malformed JSON from entering version control.

Pre-commit Configuration:

- id: check-json-files
  name: Check JSON Files
  entry: uv run --active tools/scripts/check_json_files.py
  language: system
  files: \.json$
  pass_filenames: true
  exclude: ^(tools/tests/|\.vscode/)

• Scope: Validates all staged .json files

• pass_filenames: true: Receives file list from git, enabling targeted checking

• Exclusion: Test fixtures and VS Code settings are excluded

Layer 2: GitHub Action (Continuous Integration)¶

The CI pipeline in quality.yml runs the test suite when relevant files change:

- name: Get changed json-validation files
  id: changed-json-validation
  uses: tj-actions/changed-files@v45
  with:
    files: |
      tools/scripts/check_json_files.py
      tools/tests/test_check_json_files.py

- name: Run JSON Validation Tests
  if: steps.changed-json-validation.outputs.any_changed == 'true' || steps.changed-paths.outputs.any_changed == 'true'
  run: uv run pytest tools/tests/test_check_json_files.py

Note: paths.py is detected separately because it’s a shared dependency across multiple test suites.

Layer 3: Logic Tests Pre-commit Hook¶

A meta-check ensures the validation logic remains sound:

- id: test-check-json-files
  name: Test JSON validation script
  entry: uv run --active pytest tools/tests/test_check_json_files.py
  language: system
  pass_filenames: false
  files: ^tools/(scripts/check_json_files\.py|scripts/paths\.py|tests/test_check_json_files\.py)$

This triggers whenever the script, its tests, or shared configuration change.

6. Test Suite Documentation¶

The script is accompanied by a comprehensive test suite (test_check_json_files.py) that ensures reliability across different patterns and edge cases.

Test Classes and Coverage¶

Key Test Scenarios¶

• Valid JSON: Objects, arrays, nested structures, Unicode content

• Invalid JSON: Missing brackets, trailing commas, single quotes, unquoted keys

• Line Numbers: Correct line reporting for multi-line files

• Binary Files: Gracefully handled with error message

• Missing Files: Warning issued, non-blocking

• Empty Files: Treated as valid (skipped)

• Directory Exclusions: .git, node_modules, __pycache__, etc.

Running the Tests¶

To run the full suite, execute from the repository root:

$ uv run pytest tools/tests/test_check_json_files.py