Widgets XML Verification Script

[Lightning11wins]

This python3 script detects discrepancies between the widgets.xml docs and the widget implementations in wgtr_*.c, htr_*.c, and htr_*.js files to generate a report. The report summarizes the issues detected and provides links to make it easy for developers to quickly correct them. This branch also includes a documentation file explaining how to read the reports, how to use the script, and a high-level overview of how the script works.

Note: Many of the issues detected by running this script are fixed in #100.

Example 1

Example 2

Note 1: As usual, these changes were made on a completely different dev branch, then the commits were cherry-picked to this branch. This prevents the PR being blocked behind 8+ other PRs, however, it was a difficult and technical process. If you notice any bizarre changes on this branch, please let me know.

[Lightning11wins]

@greptileai Please review of this PR.

[Lightning11wins]

Greptile finally started. I think I pinged it at least 8 times (most deleted), and it's supposed to trigger automatically.

[Lightning11wins]

I suppose this qualifies as testing since we're testing the docs. I'll document it in #94 once that PR is unblocked.

[greptile-apps]

Greptile Summary

This PR adds a Python 3.11+ script (generate.py) that cross-references widgets.xml documentation against wgtr_*.c, htdrv_*.c, and htdrv_*.js implementations to produce report.json and report.md doc-drift reports, along with a usage guide and a make doc-report target.

• generate.py: Parses XML docs and C/JS driver files via regex and ElementTree, computes per-widget missing/stale event, action, and parameter findings, and writes both a machine-readable JSON report and a human-readable Markdown report with clickable source links.
• doc-reports-guide.md: Documents how to generate and read reports, covering confidence levels, child-widget assumptions, and the four report sections.
• .gitignore / makefile: Adds ignore entries for generated report files and a doc-report phony target; a previously path-specific __pycache__ entry is replaced with a global one.

Confidence Score: 5/5

Safe to merge; the script is a standalone reporting tool with no impact on the Centrallix build or runtime.

The changes add a self-contained developer tooling script and its documentation. The core parse → diff → write pipeline is logically sound, the generated filenames and .gitignore entries are consistent, and the Python version floor is correctly stated. The one finding is a dead-code comparison in parse_js that can never fire and has no effect on report correctness.

No files require special attention; the dead comparison in parse_js is cosmetic and does not affect output.

Important Files Changed

Filename	Overview
centrallix-doc/Widgets/doc-report/generate.py	New 1179-line Python script that parses widgets.xml, wgtr/htdrv C files, and htdrv JS files to generate doc-drift reports. Logic is generally sound after previous fix rounds; one dead-code comparison in parse_js (widget_name vs eager_widget_name) will never fire.
centrallix-doc/Widgets/doc-report/doc-reports-guide.md	New guide file documenting usage, output format, and design of generate.py. Filenames (report.json/report.md), Python version floor (3.11), and TOC anchors are all consistent with the script after previous fixes.
.gitignore	Replaces path-specific pycache entry with a global pycache/ pattern and adds ignore entries for the two generated report files; consistent with script output paths.
centrallix-doc/Widgets/makefile	Adds a doc-report phony target that invokes generate.py with the correct --repo-root path; straightforward addition.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[widgets.xml] -->|ElementTree + regex| B[parse_docs\ndocs, doc_types]
    C[wgtr/wgtdrv_*.c] -->|c_register_re| D[parse_widgets_in_wgtr\nwidget_types, families, refs]
    E[htmlgen/htdrv_*.c] -->|c_name_re\nhtrAddEvent\nhtrAddAction| F[parse_c\nc_widgets]
    G[sys/js/htdrv_*.js] -->|ifcProbeAdd\nifEvent/ifAction\n.Add calls| H[parse_js\njs_widgets]
    D -->|expand_any_child_coverage| B
    F --> I[merge_widget_lists\nwidgets]
    H --> I
    B --> J[compute_report]
    D --> J
    I --> J
    J -->|WRITE_REPORT_JSON| K[report.json]
    J -->|WRITE_REPORT_MD| L[report.md]

Loading

_{Reviews (6): Last reviewed commit: "Fix mistake caught by Greptile." | Re-trigger Greptile}

[Lightning11wins]

@greptileai Your comments should be resolved. Please re-review this code.

[Lightning11wins]

@greptileai I think I've resolved all of your feedback. Please conduct a thorough re-review of the entire PR and tell me if there are any other issues.

[Lightning11wins]

This PR is cleared for human review.