rai-himanshu07/cadence-diff

Purpose and entry points

cadence-diff is a local, read-only quality-control system for recurring Excel and PowerPoint reporting deliverables. It supports single-file preflight, baseline-versus-current cycle comparison, and Excel↔PPT final-package reconciliation. Primary entry points are CLI/server startup in main.py, qc_tool/__main__.py, and qc_tool/cli.py; the local NiceGUI application is qc_tool/ui/app.py.

Run orchestration and modes

qc_tool/engine.py coordinates mode inference, staged analysis, coverage accounting, finding production, cancellation, and report generation. qc_tool/run_service.py and qc_tool/worker.py provide run lifecycle execution, while qc_tool/runqueue.py manages queued UI/background work. The engine is the central boundary between loaded document models and QC-domain analyzers.

Input loading and safety boundary

Read-only document ingestion is centered on qc_tool/io/loader.py and normalized models in qc_tool/io/model.py. OOXML worksheet/chart/interaction parsing is separated into qc_tool/io/ooxml_worksheet.py, qc_tool/io/ooxml_chart.py, and qc_tool/io/ooxml_interaction.py. Decryption is isolated in qc_tool/io/decrypt.py. XLSB formula enrichment has platform-specific adapters (qc_tool/io/xlsb_formula.py, qc_tool/io/libreoffice_formula.py) and intentionally degrades coverage rather than asserting unsupported formula semantics.

Excel analysis pipeline

The Excel domain under qc_tool/excel/ evaluates workbook integrity and cycle changes from normalized snapshots. Core stages include preflight (qc_tool/excel/preflight.py), region/cadence identification (qc_tool/excel/regions.py, qc_tool/excel/periods.py), shift-aware alignment (qc_tool/excel/align.py), formula and value comparison (qc_tool/excel/formulas.py, qc_tool/excel/diff_values.py), dependency/reference analysis (qc_tool/excel/dependency.py, qc_tool/excel/references.py), and workbook/chart/interaction risk checks (qc_tool/excel/workbook_risks.py, qc_tool/excel/charts.py, qc_tool/excel/interaction.py).

PowerPoint and package reconciliation

PowerPoint extraction, preflight, and semantic comparison are distinct from Excel logic: qc_tool/ppt/extract.py, qc_tool/ppt/preflight.py, and qc_tool/ppt/diff.py. Shape and chart matching use dedicated matching/model layers in qc_tool/ppt/match.py, qc_tool/ppt/element_match.py, and qc_tool/ppt/model.py. Final-package QC crosses this boundary through qc_tool/crosscheck/package.py, with numeric and source tracing in qc_tool/crosscheck/numbers.py and qc_tool/crosscheck/trace.py.

Findings, review state, and outputs

Atomic findings and coverage are represented in qc_tool/findings.py; severity classification and analyst overrides flow through qc_tool/triage/rules.py and qc_tool/review.py. Change-story synthesis is isolated in qc_tool/story.py. Reports are generated from reviewed state as JSON, HTML, and annotated Excel via qc_tool/report/json_report.py, qc_tool/report/html_report.py, and qc_tool/report/excel_report.py.

Persistence, security, and runtime

Per-user run history, annotations, mappings, and re-QC lineage are persisted through qc_tool/history/store.py and qc_tool/history/run_state.py (SQLite per README). The UI server defaults to loopback; temporary LAN exposure policy is managed by qc_tool/server_config.py. Privacy and evidence features are local-only: qc_tool/privacy.py, qc_tool/fingerprint.py, qc_tool/attestation.py, and qc_tool/package_sanitize.py. No LLMs or external services are part of the execution architecture.