Metadata-Version: 2.4
Name: fedstylevalidator
Version: 0.1.1
Summary: Federal writing-style validator for Word docs — CLI, FastAPI, and React UI.
Author-email: Eric Putnam <fsv@putnamgroup.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/eputnam77/FedStyleValidator
Project-URL: Repository, https://github.com/eputnam77/FedStyleValidator
Project-URL: Documentation, https://github.com/eputnam77/FedStyleValidator/tree/main/docs
Project-URL: Bug Tracker, https://github.com/eputnam77/FedStyleValidator/issues
Keywords: government,writing,style,validator,accessibility,plain-language
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Other Audience
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Office/Business
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.109.1
Requires-Dist: starlette>=0.49.1
Requires-Dist: python-docx>=0.8.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pdfkit>=1.0.0
Requires-Dist: nltk>=3.9.3
Requires-Dist: pandas>=2.2.1
Requires-Dist: numpy>=1.24.3
Requires-Dist: pydantic>=2.11.4
Requires-Dist: colorama>=0.4.6
Requires-Dist: typing-extensions>=4.9.0
Requires-Dist: filetype>=1.2.0
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: zipp==3.19.1
Requires-Dist: anyio>=4.4.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: tenacity<9.0,>=8.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: PyJWT>=2.8.0
Dynamic: license-file

# 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:

```bash
pip install fedstylevalidator
```

For an isolated command-line install:

```bash
pipx install fedstylevalidator
```

Install from a source checkout:

```bash
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:

```bash
source .venv/bin/activate
```

## Check A Document

Run the default checks:

```bash
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:

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

You can also run the module directly:

```bash
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`:

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

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

```bash
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:

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

Print SARIF for code-scanning workflows:

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

Write report files:

```bash
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:

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

Show only selected categories:

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

Hide selected categories:

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

## Suppressions And Baselines

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

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

Create a baseline for existing findings:

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

Fail only when new findings appear:

```bash
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:

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

See [docs/suppressions.md](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/suppressions.md) for suppression file syntax.

## Configuration

FSV accepts YAML, TOML, and JSON configuration files:

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

Show the effective configuration without checking a document:

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

See [docs/configuration.md](https://github.com/eputnam77/FedStyleValidator/blob/main/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:

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

Open the interactive API docs at:

```text
http://127.0.0.1:8000/docs
```

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

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

On Windows PowerShell:

```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:

```bash
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:

```bash
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](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/api-reference.md) for the full API reference.

## Run The Web UI From Source

Start the backend first. Then run the frontend:

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

Open:

```text
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](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/getting-started.md)
- [Concepts](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/concepts.md)
- [Configuration](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/configuration.md)
- [API reference](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/api-reference.md)
- [Checks reference](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/checks-reference.md)
- [Suppressions](https://github.com/eputnam77/FedStyleValidator/blob/main/docs/suppressions.md)
- [Contributing](https://github.com/eputnam77/FedStyleValidator/blob/main/CONTRIBUTING.md)

## License

This project is distributed under the [Apache License 2.0](https://github.com/eputnam77/FedStyleValidator/blob/main/LICENSE).
