fedstylevalidator 0.1.1

Federal writing-style validator for Word docs — CLI, FastAPI, and React UI.

Federal Style Validator (FSV)

Federal Style Validator checks Word documents against federal writing, formatting, accessibility, and terminology rules.

Use FSV to scan Advisory Circulars, Orders, and other federal documents before review or publication. It reports issues by category and severity, includes document metadata, and can produce machine-readable output for automation.

FSV includes:

• A command-line tool for local and batch document checks.
• Built-in rule packs for federal, FAA, DOT OGC, plain language, accessibility, and external prose checks.
• A FastAPI backend and React UI for source-checkout deployments.
• JSON, text, HTML, SARIF, JUnit, DOCX, and PDF report options.

The PyPI package installs the fedstylevalidator Python modules, CLI entry point, and built-in rule packs. The repository-local backend and frontend apps are source-checkout workflows.

Disclaimer: This is an independent open source project. It is not an official product of, affiliated with, endorsed by, or sponsored by the U.S. Government, the FAA, or any agency.

Requirements

• Python 3.11 through 3.13.
• .docx input files for the core validator.
• Node 18+ only if you run the React UI from source.

DOCX is the primary supported document format. Adapter workflows can normalize findings from other tools into FSV's canonical schema, but the CLI and API document checker expect .docx files.

Install

Install from PyPI:

pip install fedstylevalidator

For an isolated command-line install:

pipx install fedstylevalidator

Install from a source checkout:

git clone https://github.com/eputnam77/FedStyleValidator.git
cd FedStyleValidator
python -m venv .venv
.venv\Scripts\activate
pip install -e .

On macOS or Linux, activate the environment with:

source .venv/bin/activate

Check A Document

Run the default checks:

fedstylevalidator --file mydoc.docx --type "Advisory Circular"

The CLI prints canonical JSON by default. It exits with code 0 when no findings are reported and code 1 when findings are reported or processing fails.

Use the check alias if you prefer a verb in the command:

fedstylevalidator check --file mydoc.docx --type "Order"

You can also run the module directly:

python -m fedstylevalidator.core.cli --file mydoc.docx --type "Order"

What FSV Checks

The core engine can:

• Read .docx structure and document metadata.
• Validate headings, document structure, formatting, accessibility, and terminology.
• Group results by category or severity.
• Run the same rules through the CLI, API, and web UI.
• Add optional style packs without changing the base install.

FSV reports metadata such as title, author, last modified by, created date, and modified date when that information is available in the document.

Style Packs

All built-in style packs ship with the main distribution. No separate license key or install step is required.

Available built-in packs include:

• faa
• agency-style
• dot-ogc
• plain-language
• accessibility
• prose-sources
• references
• link-validation

Enable a pack with --pack:

fedstylevalidator --file mydoc.docx --type "Advisory Circular" --pack faa

Combine packs by repeating --pack or using comma-separated names:

fedstylevalidator --file mydoc.docx --type "Order" --pack plain-language --pack accessibility
fedstylevalidator --file mydoc.docx --type "Order" --pack plain-language,accessibility

Output Options

Print text instead of JSON:

fedstylevalidator --file mydoc.docx --type "Order" --format text

Print SARIF for code-scanning workflows:

fedstylevalidator --file mydoc.docx --type "Order" --format sarif

Write report files:

fedstylevalidator --file mydoc.docx --type "Order" --out json,html,junit --output-dir ./reports

Supported stdout formats are json, text, html, sarif, and junit.

Supported file outputs are json, text, html, sarif, junit, docx, and pdf.

Group findings by severity:

fedstylevalidator --file mydoc.docx --type "Order" --group-by severity

Show only selected categories:

fedstylevalidator --file mydoc.docx --type "Order" --show-only headings terminology accessibility

Hide selected categories:

fedstylevalidator --file mydoc.docx --type "Order" --hide readability prose

Suppressions And Baselines

Use suppressions for accepted findings that should not appear in normal reports:

fedstylevalidator --file mydoc.docx --type "Order" --suppressions suppressions.yml

Create a baseline for existing findings:

fedstylevalidator --file mydoc.docx --type "Order" --baseline-out baseline.json

Fail only when new findings appear:

fedstylevalidator --file mydoc.docx --type "Order" --baseline baseline.json --fail-on-new

Compare a document with a previous version and report only findings in changed sections:

fedstylevalidator --file mydoc.docx --type "Order" --diff-from mydoc.previous.docx --new-issues-only

See docs/suppressions.md for suppression file syntax.

Configuration

FSV accepts YAML, TOML, and JSON configuration files:

fedstylevalidator --file mydoc.docx --type "Order" --config ./fedstylevalidator.yaml

Show the effective configuration without checking a document:

fedstylevalidator --file mydoc.docx --type "Order" --config ./fedstylevalidator.yaml --show-config

See docs/configuration.md for configuration fields.

Run The API From Source

Clone the repository and install it in a virtual environment first. Then start the backend from the repository root:

python run.py --mode ui --port 8000

Open the interactive API docs at:

http://127.0.0.1:8000/docs

For secure or remote deployments, set a signing key and run secure mode:

export FEDSTYLEVALIDATOR_SECRET_KEY="your-long-random-secret"
python run.py --mode secure --host 0.0.0.0 --port 8000

On Windows PowerShell:

$env:FEDSTYLEVALIDATOR_SECRET_KEY = "your-long-random-secret"
python run.py --mode secure --host 0.0.0.0 --port 8000

API Example

Upload a document:

curl -X POST http://localhost:8000/process \
  -F "doc_file=@mydoc.docx" \
  -F "doc_type=Advisory Circular" \
  -F "pack=faa" \
  -F "group_by=category"

The response includes:

• has_errors: Whether the run produced findings.
• severity: Highest severity reported.
• rendered: HTML report content.
• metadata: Issue counts and document metadata.
• by_category: Findings grouped by category.
• result_id: ID for downloading saved results.

Download a saved result:

curl -L "http://localhost:8000/results/<RESULT_ID>.json" -o result.json
curl -L "http://localhost:8000/results/<RESULT_ID>.html" -o report.html

See docs/api-reference.md for the full API reference.

Run The Web UI From Source

Start the backend first. Then run the frontend:

cd frontend/fedstylevalidator
npm install
npm run dev -- --host 127.0.0.1 --port 3000

Open:

http://127.0.0.1:3000/

Use the UI to upload a .docx file, select a document type, run checks, and review the summary and detailed findings.

Useful Environment Variables

Variable	Purpose
FEDSTYLE_MODE	Runtime profile: ui or secure.
FEDSTYLEVALIDATOR_SECRET_KEY	JWT signing key for secure API mode.
REQUIRE_AUTH	Explicit API authentication override.
ALLOW_ORIGINS	Comma-separated CORS origins for deployed APIs.
RESULT_PERSISTENCE	Result storage mode: sqlite, memory, or disabled.
RESULT_TTL	Result retention window in seconds.
RESULT_DB_PATH	SQLite database path when persistence is enabled.
VITE_API_BASE	API URL override for the React frontend.

More Documentation

• Getting started
• Concepts
• Configuration
• API reference
• Checks reference
• Suppressions
• Contributing

License

This project is distributed under the Apache License 2.0.