Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 82 additions & 75 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,58 +1,79 @@
# quality-docs-validator
# Quality Docs Validator

### Catch potential inconsistencies between PFMEA and Control Plan — before technical review

![Workflow diagram: PFMEA and Control Plan XLSX files are checked against six explicit rules, then reviewed by a human engineer](docs/assets/validation-flow.svg)

A **local-first Python CLI** for quality, process and manufacturing engineers. Compare two `.xlsx` workbooks, surface severity-classified **potential findings**, and produce Markdown or JSON reports without sending your files to a cloud service.

[![CI](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)

> Detect **potential inconsistencies between PFMEA and Control Plan** before audits, customer
> submissions or production issues — locally, with simple files, explicit rules and clear reports.
**[Quick start](#quick-start)** · **[See a real example](#see-it-in-action)** · **[What it checks](#what-it-validates)** · **[Limitations](#what-it-does-not-validate-by-design)** · **[Architecture](docs/ARCHITECTURE.md)**

`quality-docs-validator` (CLI: `qdv`) is a **local-first, forkable** tool for quality engineers.
---

## The problem
## See it in action

Run the **bundled synthetic example** containing deliberately seeded gaps:

```bash
git clone https://github.com/migmcc/quality-docs-validator.git
cd quality-docs-validator
pip install -e .
qdv pfmea-control-plan \
--pfmea examples/pfmea.xlsx \
--control-plan examples/control-plan.xlsx \
--out report.md
```

![Illustrated terminal output from bundled synthetic example: 43/100, FAIL, three critical and three warnings](docs/assets/example-output.svg)

**Documented sample terminal output (abridged):**

```text
Potential findings
UNMATCHED_PROCESS_STEP warning Op 40
SPECIAL_CHARACTERISTIC_NOT_CONTROLLED critical Op 20
MISSING_REACTION_PLAN critical Op 20
WEAK_DETECTION_METHOD warning Op 20
HIGH_SEVERITY_WEAK_CONTROL warning Op 20
MISSING_CONTROL critical Op 30

Score: 43/100 Verdict: FAIL
Critical: 3 Warnings: 3
```

[Read the full committed sample report →](examples/report.md)

Quality documents are reviewed one at a time, but the real risk lives **between** them: a
high-severity PFMEA failure mode with no matching Control Plan control, a special characteristic
missing from the inspection plan, a missing reaction plan exactly where risk is highest. These gaps
surface late — at audits, customer submissions or as field complaints. This tool cross-checks the
two documents and surfaces those gaps as **severity-classified potential findings**.
> **Important:** Findings are *potential inconsistencies* for an engineer to judge. This is **not** a regulatory or standards compliance certification and **does not replace human technical review**.

> ⚠️ It **supports, and does not replace, human technical review.** Findings are *potential*
> inconsistencies for an engineer to judge; the tool makes no regulatory or normative conformance
> claim.
## The problem

A PFMEA and its Control Plan can look complete when reviewed separately while disagreeing **between** documents: an unmatched process step, a special characteristic not reflected in controls, or no reaction plan where severity is high. Those gaps deserve attention before an audit or submission.

## Who it's for

Quality / Process / Manufacturing Engineers, SQEs, internal auditors and APQP/PPAP teams — and
anyone using coding agents to automate quality workflows. Runs entirely on your machine, so
confidential supplier/customer data never leaves it.
Quality / Process / Manufacturing Engineers, supplier-quality teams, internal auditors and APQP/PPAP teams working with Excel-based documents.

## What it validates

A single module: **PFMEA ↔ Control Plan consistency checker**.

- Reads a PFMEA `.xlsx` and a Control Plan `.xlsx` (recommended template + common header aliases —
e.g. `Operation No`, `Op #`, `Severity Rating`, `Special Characteristic`, `Reaction Plan`).
- Matches rows by `operation_id` / process step.
- Applies six explicit, documented checks (see [docs/FINDINGS.md](docs/FINDINGS.md)):
`UNMATCHED_PROCESS_STEP`, `MISSING_CONTROL`, `SPECIAL_CHARACTERISTIC_NOT_CONTROLLED`,
`MISSING_REACTION_PLAN`, `WEAK_DETECTION_METHOD` (warning), `HIGH_SEVERITY_WEAK_CONTROL` (warning).
- Computes a **severity-weighted score (0–100)** with verdict bands
(PASS / PASS-WITH-WARNINGS / NEEDS-REVIEW / FAIL).
- Generates a **Markdown report** plus a **rich terminal summary**.
The current module is a **PFMEA ↔ Control Plan consistency checker**.

## What it does *not* validate (by design)
| Capability | How it works |
| --- | --- |
| Excel input | Reads PFMEA and Control Plan `.xlsx` workbooks, with a recommended template and common header aliases. |
| Matching | Matches normalised operation IDs and process steps. |
| Six checks | Flags unmatched steps, missing controls, uncontrolled special characteristics, missing reaction plans and two warning-level weak-method heuristics. |
| Scoring | Severity-weighted 0–100 score with PASS / PASS-WITH-WARNINGS / NEEDS-REVIEW / FAIL verdicts. |
| Reports | Rich terminal summary plus Markdown or JSON, suitable for review and automation. |

- ❌ CSV / other input formats — `.xlsx` only (CSV planned for v0.2).
- ❌ Configurable column mapping — recommended template + fixed aliases only (v0.2).
- ❌ Other document pairs (Process Flow ↔ PFMEA, Work Instructions, PPAP, 8D, SPC, MSA).
- ❌ Web UI, ERP/MES/QMS integration, PDF/OCR, or any AI dependency.
- ❌ Regulatory/standard conformance certification, or replacing human judgement.
**[Read the exact finding triggers and scoring rules →](docs/FINDINGS.md)**

Scope is deliberately narrow — see [docs/MVP_SCOPE.md](docs/MVP_SCOPE.md),
[docs/DECISIONS.md](docs/DECISIONS.md) and the [roadmap](docs/ROADMAP.md).
## Quick start

## Quickstart
**Requirements:** Python 3.12+ and a local checkout of this repository.

```bash
pip install -e .
Expand All @@ -62,35 +83,9 @@ qdv pfmea-control-plan \
--out report.md
```

This runs against the bundled synthetic examples (which contain a deliberately seeded gap) and
writes `report.md` plus a terminal summary. Regenerate the examples with
`python examples/generate_examples.py`.

Expected terminal summary (abridged):

```text
Potential findings
Type Level Op Detail
─────────────────────────────────────────────────────────────────
UNMATCHED_PROCESS_STEP warning 40 no Control Plan row
SPECIAL_CHARACTERISTIC_NOT_CONTROLLED critical 20 not marked special in CP
MISSING_REACTION_PLAN critical 20 S=9, no reaction plan
WEAK_DETECTION_METHOD warning 20 visual inspection
HIGH_SEVERITY_WEAK_CONTROL warning 20 S=9 + weak control
MISSING_CONTROL critical 30 no control method

╭───────────────── quality-docs-validator ─────────────────╮
│ Score: 43/100 Verdict: FAIL Critical: 3 Warnings: 3 │
╰───────────────────────────────────────────────────────────╯
```
The bundled examples are synthetic and intentionally contain a gap. To regenerate them, run `python examples/generate_examples.py`.

The full Markdown report is written to `report.md`; a committed sample lives at
[examples/report.md](examples/report.md). Finding types and scoring are documented in
[docs/FINDINGS.md](docs/FINDINGS.md).

### JSON output

For automation, emit a machine-readable report with `--format json`:
### JSON output for automation

```bash
qdv pfmea-control-plan \
Expand All @@ -99,13 +94,9 @@ qdv pfmea-control-plan \
--format json --out report.json
```

Markdown remains the default. The JSON contains `metadata` (tool, version, UTC timestamp),
`verdict`, `score`, a `summary` (counts by severity and by finding type) and the full `findings`
list.
The JSON report includes metadata, verdict, score, summary and findings.

### Multi-sheet workbooks

If a workbook has several sheets, pick the right one by name (otherwise the active sheet is used):
### Select sheets in multi-sheet workbooks

```bash
qdv pfmea-control-plan \
Expand All @@ -114,12 +105,28 @@ qdv pfmea-control-plan \
--out report.md
```

If the named sheet does not exist, the error lists the available sheet names.
If a specified sheet does not exist, the error lists available sheet names.

## What it does not validate (by design)

- Formats other than `.xlsx`; CSV is not currently supported.
- Arbitrary column mapping beyond the recommended template and supported aliases.
- Other document pairs (Process Flow, Work Instructions, PPAP, 8D, SPC, MSA).
- Web interface, ERP / MES / QMS integration, PDF / OCR or AI-based interpretation.
- Regulatory conformity, audit certification or replacements for engineering judgement.

See [scope](docs/MVP_SCOPE.md), [decisions](docs/DECISIONS.md) and [roadmap](docs/ROADMAP.md).

## How it works

`PFMEA.xlsx + Control Plan.xlsx → operation matching → six checks → scoring → terminal / Markdown / JSON`

## Architecture
The rules and scoring are explicitly documented and testable rather than based on an LLM. For implementation details, see [architecture](docs/ARCHITECTURE.md) and [finding reference](docs/FINDINGS.md).

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the module layout and data flow.
## Get involved

## License
- [Explore the repository](https://github.com/migmcc/quality-docs-validator)
- [Open an issue](https://github.com/migmcc/quality-docs-validator/issues)
- [Contribute](CONTRIBUTING.md)

[MIT](LICENSE). Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
Licensed under [MIT](LICENSE).
1 change: 1 addition & 0 deletions docs/assets/example-output.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/assets/validation-flow.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,7 @@ addopts = "-q"
line-length = 100
target-version = "py312"
src = ["src", "tests"]

[tool.ruff.lint.per-file-ignores]
# Typer declares CLI arguments with Option(...) defaults by design.
"src/quality_docs_validator/cli.py" = ["B008"]
6 changes: 3 additions & 3 deletions src/quality_docs_validator/core/report.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

import json
from collections import Counter
from datetime import datetime, timezone
from datetime import UTC, datetime
from pathlib import Path

from rich.console import Console
Expand All @@ -36,7 +36,7 @@


def render_markdown(result: ValidationResult, pfmea_name: str, control_plan_name: str) -> str:
generated = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
generated = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
lines: list[str] = []
lines.append("# PFMEA ↔ Control Plan Validation Report")
lines.append("")
Expand Down Expand Up @@ -93,7 +93,7 @@ def build_report_data(
"metadata": {
"tool": TOOL_NAME,
"version": __version__,
"generated_at": datetime.now(timezone.utc).isoformat(),
"generated_at": datetime.now(UTC).isoformat(),
"format": "json",
},
"inputs": {
Expand Down
2 changes: 1 addition & 1 deletion tests/test_json_output.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ def test_json_generated_with_flag(example_files, tmp_path: Path) -> None:
assert out.exists()
# Parseable JSON.
data = json.loads(out.read_text(encoding="utf-8"))
assert set(["metadata", "verdict", "score", "summary", "findings"]) <= set(data)
assert {"metadata", "verdict", "score", "summary", "findings"} <= set(data)


def test_json_metadata_shape(example_files, tmp_path: Path) -> None:
Expand Down
Loading