---
name: docxology/infrastructure-validation
source: https://app.decimal.ai/s/docxology-infrastructure-validation@1/SKILL.md
source_sha256: 9dc24ec063e4
---

# Validation Module

Quality assurance and content validation tools for research outputs. Covers PDFs, markdown, links, output integrity, and comprehensive audits.

## PDF Validation (`content/pdf_validator.py`)

```python
from infrastructure.validation import validate_pdf_rendering, extract_text_from_pdf, scan_for_issues

# Validate a rendered PDF
results = validate_pdf_rendering(pdf_path)

# Extract text for analysis
text = extract_text_from_pdf(pdf_path)

# Scan for rendering issues
issues = scan_for_issues(text)
```

**CLI:**

```bash
uv run python -m infrastructure.validation.cli.main pdf output/{project}/pdf/
uv run python -m infrastructure.validation.cli.pdf output/{project}/pdf/
```

## Markdown Validation (`markdown_validator.py`)

```python
from pathlib import Path

from infrastructure.validation.content.discovery import discover_markdown_files
from infrastructure.validation.content.markdown_validator import (
    collect_symbols,
    validate_images,
    validate_markdown,
    validate_math,
    validate_refs,
)

repo_root = Path(".")
manuscript_dir = repo_root / "projects" / "project" / "manuscript"
md_files = [str(path) for path in discover_markdown_files(manuscript_dir, scope="tree")]
labels, anchors = collect_symbols(md_files)

# Validate all markdown in a directory
problems, exit_code = validate_markdown(manuscript_dir, repo_root)

# Individual checks
image_issues = validate_images(md_files, repo_root)
ref_issues = validate_refs(md_files, repo_root, labels, anchors)
math_issues = validate_math(md_files, repo_root)
```

**CLI:**

```bash
uv run python -m infrastructure.validation.cli.main markdown projects/{name}/manuscript/
uv run python -m infrastructure.validation.cli markdown projects/{name}/manuscript/
```

## Output Integrity (`integrity/checks.py`)

```python
from infrastructure.validation import (
    verify_output_integrity, verify_file_integrity,
    verify_cross_references, verify_data_consistency,
    verify_academic_standards, generate_integrity_report,
)

# Full integrity check
report = verify_output_integrity(output_dir)

# Individual checks
verify_file_integrity(file_path)
verify_cross_references(manuscript_dir)
verify_data_consistency(data_dir)
verify_academic_standards(manuscript_dir)
```

## Output Structure Validation (`output/validator.py`)

```python
from infrastructure.validation import validate_output_structure, validate_copied_outputs

validate_output_structure(output_dir)
validate_copied_outputs(source_dir, dest_dir)
```

## Link Verification (`integrity/check_links.py`, `integrity/link_validator.py`)

```python
from pathlib import Path
from infrastructure.validation import LinkValidator

validator = LinkValidator(Path("."))
results = validator.validate_all_markdown_files()
```

## Figure Validation (`figure_validator.py`)

```python
from pathlib import Path
from infrastructure.validation import validate_figure_registry

success, issues = validate_figure_registry(
    Path("projects/<name>/output/figures/figure_registry.json"),
    Path("projects/<name>/manuscript"),
)
```

Pass ``require_accessibility=True`` during an explicit migration or release
review to require non-empty ``alt`` or ``metadata.alt_text`` for every
referenced registered figure. The publication CLI exposes the same contract as
``--require-figure-accessibility``. A manuscript that references figures but
has no registry fails closed; a manuscript with no figure references does not
need an empty registry.

Both registry shapes are accepted: ``{"fig:label": {...}, ...}`` (dict, emitted
by ``FigureManager``) and ``[{"label": "fig:label", ...}, ...]`` (list, emitted
by project-side scripts that produce a flat manifest).

Evidence registries may name project-relative sources or repository-relative
shared contracts (for example, a reusable infrastructure module). The
publication and output validators resolve both forms, require the path to
exist, and reject paths that escape the repository boundary.

## Audit Orchestration (`repo/audit_orchestrator.py`)

```python
from infrastructure.validation import run_comprehensive_audit, generate_audit_report

# Run all validation checks in one pass
audit_results = run_comprehensive_audit(project_path)
report = generate_audit_report(audit_results)
```

## Issue Categorization (`repo/issue_categorizer.py`)

```python
from infrastructure.validation import (
    categorize_by_type, assign_severity, filter_false_positives,
    prioritize_issues, group_related_issues, generate_issue_summary,
)

categorized = categorize_by_type(raw_issues)
filtered = filter_false_positives(categorized)
prioritized = prioritize_issues(filtered)
summary = generate_issue_summary(prioritized)
```

## Documentation Scanning (`docs/scanner.py`, `docs/accuracy.py`, `docs/completeness.py`)

Comprehensive scanning of documentation for accuracy, completeness, and quality:

```python
from infrastructure.validation.docs.scanner import DocumentationScanner
from infrastructure.validation.docs.accuracy import verify_documentation_accuracy
from infrastructure.validation.docs.completeness import analyze_documentation_completeness

scanner = DocumentationScanner(repo_root)
inventory = scanner.discover_inventory()
accuracy_report, link_issues, accuracy_issues, headings = verify_documentation_accuracy(
    md_files, repo_root, config_files
)
completeness_report, gaps = analyze_documentation_completeness(repo_root, documentation_files, config_files)
```

## Repository Scanning (`repo/scanner.py`)

```python
from infrastructure.validation.repo.scanner import RepositoryScanner
scanner = RepositoryScanner(repo_root)
results = scanner.scan_all()
```

## Additional CLI Subcommands

```bash
# Strict source-markdown gate: pitfalls + undefined citations
uv run python -m infrastructure.validation.cli prerender projects/{name}/manuscript/

# Validate manuscript claims against registered project evidence
uv run python -m infrastructure.validation.cli evidence projects/{name} --fail-on-issues

# Scan manuscript prose for AI-writing fingerprints
uv run python -m infrastructure.validation.cli prose-quality projects/{name}/manuscript/
```

## Mock Validation (`output/no_mock_enforcer.py`)

The enforced lexical API reports prohibited mock-framework imports/calls. It
does not prove that monkeypatch dependency replacements are absent:

```python
from infrastructure.validation.output.no_mock_enforcer import validate_no_mocks
violations = validate_no_mocks(tests_dir, repo_root)
```

Repository-level commands:

```bash
uv run python scripts/audit/verify_no_mocks.py
uv run python scripts/audit/verify_no_mocks.py --inventory
```