index.md
HTML wrapper for HTML-only fetchers; content is shown verbatim.
Raw file
Links (extracted)
Clickable list for reviewers; avoids copy/paste line-wrap issues.
# iftypeset — codepack (curated source + core spec)
**Generated (UTC):** 2026-01-06T02:15:06Z
## Notes
- This is a hosted-static fallback for review when Forgejo UI/auth is blocked.
- Curated: excludes virtualenvs, build outputs, caches, and fixtures.
- iftypeset git HEAD (source subset): `626779d4aa8e6f3aaac2c339c384cb5e6de42847`
## Links (one per line)
https://infrafabric.io/grok/
https://infrafabric.io/grok/iftypeset-task-board.html
https://infrafabric.io/static/hosted/review/iftrace-iftypeset-bundle/2026-01-05/review-pack.html
## Files (inlined)
### `iftypeset/README.md`
- bytes: `5498`
- sha256: `1175a12695a84af05959f5db190c8bd45ee68f25e5258d587100c97e1ee8b78a`
````md
# iftypeset (pubstyle) — publication-quality typesetting pipeline
This project is a **thin, deterministic runtime** for turning Markdown into high‑quality HTML/PDF using:
- **A machine‑readable rule registry** (Chicago / Bringhurst pointers; paraphrased rules only)
- **Typeset profiles** (`spec/profiles/*.yaml`) that map typographic intent → render tokens
- **Post‑render QA gates** (`spec/quality_gates.yaml`) that fail builds when layout degrades
It is designed to be embedded into constrained workers (e.g. Forgejo PDF export with `--network=none`) and also run as a standalone CLI.
**Status:** working spec + seeded rule registry. See `STATUS.md`.
## Constraints (non-negotiable)
- **No bulk OCR/transcription** of Chicago/Bringhurst into this repo (copyright).
- Rule records are **paraphrases only**, backed by **pointers** (e.g. `CMOS18 §X.Y pNNN (scan pMMM)`).
- Chicago OCR (when needed) must be **ephemeral** (extract just enough to locate pointers; do not store page text).
- Optional profile `webtypography_nc` is **CC BY-NC 4.0** (non-commercial only). See `docs/18-webtypography-nc.md`.
## Quickstart (current)
From `ai-workspace/iftypeset/`:
- (Optional) Install deps into a venv: `python3 -m venv .venv && . .venv/bin/activate && python -m pip install -r requirements.txt`
- Install the console entrypoint: `python3 -m pip install -e .`
- Validate spec + rebuild indexes: `iftypeset validate-spec --spec spec --build-indexes`
- One-shot CI pipeline (recommended): `iftypeset run --input fixtures/sample.md --out out --profile web_pdf --degraded-ok`
- Multi-doc run (directory or glob): `iftypeset run --input fixtures --out out --profile web_pdf --degraded-ok`
- Lint Markdown (emits `out/lint-report.json` + `out/manual-checklist.md`): `iftypeset lint --input fixtures/sample.md --out out --profile web_pdf`
- Lint with auto-fix + post-fix diagnostics: `iftypeset lint --input fixtures/sample.md --out out --profile web_pdf --fix --fix-mode rewrite --lint-fixed`
- Render HTML + CSS: `iftypeset render-html --input fixtures/sample.md --out out --profile web_pdf`
- Run QA gates (HTML fallback if no PDF): `iftypeset qa --out out --profile web_pdf`
- Render PDF (if an engine is installed): `iftypeset render-pdf --input fixtures/sample.md --out out --profile web_pdf`
- Coverage + trust contract + HTML index: `iftypeset report --spec spec --out out` (writes `out/report/index.html`)
- Environment/determinism report: `iftypeset doctor --spec spec --out out`
- Portable review bundle: `iftypeset bundle --out out` (writes `out/iftypeset-bundle.tar.gz`)
- Run self-check tests: `python3 -m unittest discover -s tests -p 'test_*.py'`
- Inspect profiles/gates/rules:
- `iftypeset profiles list`
- `iftypeset gates show --profile web_pdf`
- `iftypeset rules list --category links`
- `iftypeset rules show HOUSE.LINKS.URLS.PREFER_HTTPS`
If you do not want to install the console entrypoint, you can still run:
- `PYTHONPATH=src python3 -m iftypeset.cli <command> ...`
## Config file (`iftypeset.yaml`)
You can set repo defaults in `./iftypeset.yaml`. CLI flags always win.
Example:
```yaml
defaults:
spec: spec
out: out
profile: web_pdf
lint:
fail_on: must
degraded_ok: true
run:
skip_pdf: false
require_pdf: false
engine: playwright
```
To use a different config path: `iftypeset --config /path/to/iftypeset.yaml <command> ...`
## Enforcement limits (read this)
- **Not all rules are automated.** Manual rules (tagged `manual_checklist=true`) appear in `out/manual-checklist.md`.
- **PDF QA is heuristic.** It depends on text extraction and will miss some layout failures.
- **Renderer variance exists.** Profiles aim for determinism, but output still depends on the PDF engine + fonts.
- **Trust contract is explicit.** Run `iftypeset report` to generate `out/trust-contract.md` with current limits.
## Lint suppression (explicit, auditable)
You can suppress specific rules in a document when needed:
- Inline directive (applies to the next non-empty line):
- `<!-- iftypeset:ignore CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE -->`
- Front matter allowlist:
- `iftypeset_ignore: [CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE, LINK.WRAP.RISK]`
Suppression works by rule id or diagnostic code and should be used sparingly.
## Session resilience (avoid “lost work”)
If a chat/session resets, trust the repo, not the transcript:
- Quick resume: `./scripts/resume.sh`
- Audit repo state: `./scripts/audit.sh`
- Run CI sanity checks: `./scripts/ci.sh`
- Create a portable restore point: `./scripts/checkpoint.sh "short note"`
Details: `docs/07-session-resilience.md`
Handoff snapshot: `docs/08-handoff.md`
Project status: `docs/09-project-status.md`
Downloadable summary: `docs/11-project-summary.md`
Rendering pipeline: `docs/17-rendering-pipeline.md`
Non-commercial WebTypography profile: `docs/18-webtypography-nc.md`
Agent notes: `AGENTS.md`
External review pack: `docs/14-external-review.md`
Docker runtime: `docs/15-docker.md`
## PDF renderers
`render-pdf` defaults to `playwright`. Use `--engine auto` to pick the first available engine in this order:
- `playwright` (Python module)
- `chromium` / `chromium-browser` / `google-chrome`
- `wkhtmltopdf`
- `weasyprint` (Python module)
If none are installed, the command exits with a clear message but still leaves HTML artifacts for QA.
Note: Chromium CLI does not support header/footer templates, so running heads only appear when using Playwright (or wkhtmltopdf).
````
### `iftypeset/STATUS.md`
- bytes: `6733`
- sha256: `892f3ee0ad7586cf484f8b399590da6e693c1cedca674c547ede260cc80810a1`
````md
# iftypeset status (pubstyle)
**Updated:** 2026-01-04
**Project root:** `/root/ai-workspace/iftypeset/`
## What exists (working today)
- **Spec + schema:** `spec/schema/rule.schema.json`, `spec/manifest.yaml`
- **Profiles:** `spec/profiles/*.yaml` (`web_pdf`, `print_pdf`, `dense_tech`, `memo`, `slide_deck`, `webtypography_nc` non-commercial)
- **Post-render QA gates:** `spec/quality_gates.yaml`
- **PDF-aware QA (heuristic):** Poppler text extraction via `pdftotext` + `pdftohtml -xml` with page-aware incidents (`widow_pdf`, `orphan_pdf`, `stranded_heading_pdf`, `overfull_line_pdf`, `overfull_bbox_pdf`)
- **HTML QA (v0):** catches bare URL/DOI/email wrapping, overfull tokens, code/table overflow (profile-aware thresholds)
- **Deterministic lint coverage:** DOI references, ordinal suffix errors, and note-marker placement (alongside existing punctuation/link safety checks)
- **Rule registry (seeded):** `spec/rules/**.ndjson`
- **House pointers (no quotes):** `spec/house/HOUSE_EDITORIAL_POINTERS.md`
- **Indexes (derived):** `spec/indexes/*.json` (rebuildable)
- **CLI:** `validate-spec`, `report`, `lint`, `render-html`, `render-pdf`, `qa`, `emit-css`, `doctor`, `bundle`, `run`
- `render-pdf --engine <name>` to force a specific renderer.
- `run --require-pdf` to fail the pipeline if PDF rendering fails.
- **Renderer default:** `playwright` is the default engine for PDF typesetting; `chromium` remains a fallback (no running-head support).
- **CLI introspection:** `profiles list`, `gates show`, `rules list/show`
- **Config defaults:** `iftypeset.yaml` (CLI flags override)
- **Run summary artifact:** `out/run-summary.json` (CI-style pipeline output)
- **Multi-doc run mode:** `iftypeset run --input <dir|glob>` writes per-doc outputs under `out/docs/` and a top-level run index at `out/report/index.html`
- **Ephemeral extraction helpers:** `tools/` (Chicago OCR is grep-only, temp files deleted)
- **Forgejo integration note:** `forgejo/README.md`
- **Fixtures + tests:** `fixtures/` and `tests/`
- **CI script:** `scripts/ci.sh` (validate-spec, report, unit tests)
- **Docker runtime:** `Dockerfile` + `docs/15-docker.md` (Chromium + Poppler + fonts)
- **“Don’t lose work” tooling:** `scripts/audit.sh`, `scripts/checkpoint.sh`, `scripts/state.sh`, `scripts/resume.sh` + `docs/07-session-resilience.md`
- **Trust contract artifacts:** `out/trust-contract.md` + `out/trust-contract.json` (generated by `report`)
- **Report index:** `out/report/index.html` (artifact hub from `report`)
- **Doctor report:** `out/doctor.md` + `out/doctor.json` (environment + determinism)
- **Bundle artifact:** `out/iftypeset-bundle.tar.gz` + `out/bundle-manifest.json` (portable review pack)
## Rule corpus snapshot
From `out/coverage-report.json`:
- **Total rules:** 524
- **By category:** editorial 45, abbreviations 27, accessibility 22, backmatter 18, citations 61, code 28, figures 22, frontmatter 20, headings 32, i18n 27, layout 46, links 21, numbers 62, punctuation 55, tables 23, typography 15
- **By enforcement:** manual 379, typeset 62, lint 70, postrender 13
- **By severity:** must 37, should 470, warn 17
## Current rule batches
- `spec/rules/abbreviations/v1_abbreviations_003.ndjson` (27)
- `spec/rules/accessibility/v1_accessibility_001.ndjson` (4)
- `spec/rules/accessibility/v1_accessibility_003.ndjson` (18)
- `spec/rules/backmatter/v1_backmatter_003.ndjson` (18)
- `spec/rules/citations/v1_citations_001.ndjson` (16)
- `spec/rules/citations/v1_citations_002.ndjson` (45)
- `spec/rules/code/v1_code_001.ndjson` (4)
- `spec/rules/code/v1_code_003.ndjson` (24)
- `spec/rules/editorial/v1_editorial_001.ndjson` (45)
- `spec/rules/figures/v1_figures_003.ndjson` (22)
- `spec/rules/frontmatter/v1_frontmatter_003.ndjson` (20)
- `spec/rules/headings/v1_headings_001.ndjson` (12)
- `spec/rules/headings/v1_headings_002.ndjson` (20)
- `spec/rules/i18n/v1_i18n_003.ndjson` (27)
- `spec/rules/layout/v1_layout_001.ndjson` (12)
- `spec/rules/layout/v1_layout_002.ndjson` (30)
- `spec/rules/layout/v1_layout_003.ndjson` (4)
- `spec/rules/links/v1_links_001.ndjson` (5)
- `spec/rules/links/v1_links_003.ndjson` (16)
- `spec/rules/numbers/v1_numbers_001.ndjson` (12)
- `spec/rules/numbers/v1_numbers_002.ndjson` (50)
- `spec/rules/punctuation/v1_punctuation_001.ndjson` (15)
- `spec/rules/punctuation/v1_punctuation_002.ndjson` (40)
- `spec/rules/tables/v1_tables_001.ndjson` (8)
- `spec/rules/tables/v1_tables_002.ndjson` (15)
- `spec/rules/typography/v1_typography_001.ndjson` (8)
- `spec/rules/typography/v1_typography_002.ndjson` (7)
## How to validate and inspect
- Validate spec + rebuild indexes:
- `PYTHONPATH=src python3 -m iftypeset.cli validate-spec --spec spec --build-indexes`
- Lint:
- `PYTHONPATH=src python3 -m iftypeset.cli lint --input fixtures/sample.md --out out --profile web_pdf`
- Run end-to-end pipeline:
- `PYTHONPATH=src python3 -m iftypeset.cli run --input fixtures/sample.md --out out --profile web_pdf --degraded-ok`
- `PYTHONPATH=src python3 -m iftypeset.cli run --input fixtures/sample.md --out out --profile web_pdf --require-pdf`
- Render HTML + CSS:
- `PYTHONPATH=src python3 -m iftypeset.cli render-html --input fixtures/sample.md --out out --profile web_pdf`
- Render PDF (if renderer installed):
- `PYTHONPATH=src python3 -m iftypeset.cli render-pdf --input fixtures/sample.md --out out --profile web_pdf`
- `PYTHONPATH=src python3 -m iftypeset.cli render-pdf --input fixtures/sample.md --out out --profile web_pdf --engine chromium`
- Run QA gates (HTML fallback if no PDF):
- `PYTHONPATH=src python3 -m iftypeset.cli qa --out out --profile web_pdf`
- Coverage report:
- `PYTHONPATH=src python3 -m iftypeset.cli report --spec spec --out out --build-indexes`
- Emit CSS for a profile:
- `PYTHONPATH=src python3 -m iftypeset.cli emit-css --spec spec --profile web_pdf --out out-css`
- Run unit tests:
- `python3 -m unittest discover -s tests -p 'test_*.py'`
## Key constraints (don’t drift)
- **No bulk OCR/transcription** of books into repo. Rules must be paraphrased and pointer-backed.
- `source_refs` must be **pointers**, not quotes; include `(scan pN)` only as a single page hint.
- Chicago extraction may use OCR **ephemerally** only to locate pointers; do not persist OCR output.
## Next work (highest leverage)
- Extend deterministic lint coverage for citations (author-date patterns, bibliography normalization) and locale/i18n rules where feasible.
- Deepen typeset/CSS profile mapping for tables, figures, and code to reduce manual cleanup before PDF export (and to reduce QA incidents).
- Expand editorial automation beyond manual checklists (safe heuristics like headline ALL-CAPS checks and abbreviation definition hints).
````
### `iftypeset/pyproject.toml`
- bytes: `369`
- sha256: `945b26441866ac1978d43d838d5eb3814da5c7908ad150170884373b5a540e33`
````toml
[project]
name = "iftypeset"
version = "0.1.0"
description = "Publication-quality typesetting runtime (Markdown→HTML→PDF) with Chicago/Bringhurst-backed rule registry pointers."
requires-python = ">=3.11"
dependencies = [
"pyyaml>=6.0",
"jsonschema>=4.19",
]
[project.scripts]
iftypeset = "iftypeset.cli:main"
[tool.pytest.ini_options]
testpaths = ["tests"]
````
### `iftypeset/requirements.txt`
- bytes: `33`
- sha256: `0dc50f517e27e51f275f54e33c9dbc54bc153db6e9dbb9d531b39dd7d9bb94e8`
````text
PyYAML==6.0.2
jsonschema==4.19.2
````
### `iftypeset/src/iftypeset/__init__.py`
- bytes: `50`
- sha256: `2515233a0cdac6c5447c9dbd6b0d54c89284f191d8cb41473d89b347ee296ae7`
````py
__all__ = ["__version__"]
__version__ = "0.1.0"
````
### `iftypeset/src/iftypeset/cli.py`
- bytes: `44571`
- sha256: `c8106e39058160ae455fde650270328be86dac2161c3748e3bdffb68daf75761`
````py
import argparse
import glob
import io
import json
import os
import sys
from contextlib import redirect_stdout
from datetime import datetime, timezone
from dataclasses import asdict
from pathlib import Path
from iftypeset import __version__
from iftypeset.config import apply_config
from iftypeset.css_gen import generate_profile_css
from iftypeset.index_builder import build_indexes, write_indexes
from iftypeset.linting import collect_input_paths, lint_paths, manual_checklist
from iftypeset.qa import LayoutReport, analyze_html, analyze_pdf, evaluate_gates, layout_report_dict
from iftypeset.rendering import render_html, render_pdf, renderer_info
from iftypeset.reporting import (
CoverageError,
CoverageReport,
build_coverage_report,
build_doctor_report,
build_bundle,
build_run_index,
build_report_index,
build_trust_contract,
)
from iftypeset.spec_loader import SpecError, load_spec
EXIT_OK = 0
EXIT_GATE_FAIL = 1
EXIT_CONFIG = 2
EXIT_RENDER = 3
EXIT_NONDET = 4
QA_RULE_MAP = {
"link_wrap": "HOUSE.LINKS.WRAP.SAFE_BREAKS",
"code_overflow": "HOUSE.CODE.BLOCKS.NO_CLIPPING",
"table_overflow": "HOUSE.TABLES.OVERFLOW.NO_CLIPPING",
"overfull_token": "HOUSE.LAYOUT.OVERFLOW.OVERFULL_LINES.REPORT",
"overfull_line_pdf": "HOUSE.LAYOUT.OVERFLOW.OVERFULL_LINES.REPORT",
"overfull_bbox_pdf": "HOUSE.LAYOUT.OVERFLOW.OVERFULL_LINES.REPORT",
"stranded_heading": "HOUSE.HEADINGS.KEEPS.AVOID_STRANDED",
"stranded_heading_pdf": "HOUSE.HEADINGS.KEEPS.AVOID_STRANDED",
"widow_pdf": "BRING.LAYOUT.PAGINATION.WIDOWS_AVOID",
"orphan_pdf": "BRING.LAYOUT.PAGINATION.ORPHANS_AVOID",
}
def _cmd_validate_spec(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
_write_json(Path(args.out) / "spec-validation.json", {"ok": False, "error": str(e)})
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
out: dict[str, object] = {
"ok": True,
"spec_root": str(Path(args.spec).resolve()),
"manifest_version": spec.manifest.get("version"),
"profiles": sorted(spec.profiles.keys()),
}
if args.build_indexes:
indexes = build_indexes(spec.rules)
write_indexes(indexes, Path(args.spec) / "indexes")
out["indexes_written"] = True
out_dir = Path(args.out)
out_dir.mkdir(parents=True, exist_ok=True)
_write_json(out_dir / "spec-validation.json", out)
print(json.dumps(out, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_report(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
try:
report: CoverageReport = build_coverage_report(spec, strict=args.strict)
except CoverageError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_GATE_FAIL
out_dir = Path(args.out)
out_dir.mkdir(parents=True, exist_ok=True)
(out_dir / "coverage-report.json").write_text(
json.dumps(asdict(report), indent=2, sort_keys=True) + "\n", encoding="utf-8"
)
(out_dir / "coverage-summary.md").write_text(report.to_markdown(), encoding="utf-8")
trust = build_trust_contract(spec, report)
(out_dir / "trust-contract.json").write_text(
json.dumps(asdict(trust), indent=2, sort_keys=True) + "\n", encoding="utf-8"
)
(out_dir / "trust-contract.md").write_text(trust.to_markdown(), encoding="utf-8")
report_dir = out_dir / "report"
report_dir.mkdir(parents=True, exist_ok=True)
(report_dir / "index.html").write_text(build_report_index(out_dir), encoding="utf-8")
if args.build_indexes:
indexes = build_indexes(spec.rules)
write_indexes(indexes, Path(args.spec) / "indexes")
print(json.dumps({"ok": True, "out_dir": str(out_dir.resolve())}, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_doctor(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
report = build_doctor_report(spec)
out_dir = Path(args.out)
out_dir.mkdir(parents=True, exist_ok=True)
(out_dir / "doctor.json").write_text(json.dumps(asdict(report), indent=2, sort_keys=True) + "\n", encoding="utf-8")
(out_dir / "doctor.md").write_text(report.to_markdown(), encoding="utf-8")
print(json.dumps({"ok": True, "out_dir": str(out_dir.resolve())}, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_bundle(args: argparse.Namespace) -> int:
out_dir = Path(args.out)
bundle_path = Path(args.bundle) if args.bundle else (out_dir / "iftypeset-bundle.tar.gz")
max_bytes = int(args.max_size_mb * 1024 * 1024)
manifest = build_bundle(out_dir, bundle_path, max_bytes=max_bytes)
print(
json.dumps(
{
"ok": True,
"bundle": str(bundle_path.resolve()),
"manifest": str((out_dir / "bundle-manifest.json").resolve()),
"included": len(manifest.get("included", []) if isinstance(manifest, dict) else []),
},
indent=2,
sort_keys=True,
)
)
return EXIT_OK
def _has_glob(value: str) -> bool:
return any(ch in value for ch in ("*", "?", "["))
def _resolve_run_inputs(input_value: str) -> tuple[list[Path], Path]:
if _has_glob(input_value):
matches = [Path(p) for p in glob.glob(input_value, recursive=True)]
paths = sorted([p for p in matches if p.is_file() and p.suffix.lower() == ".md"])
if not paths:
raise ValueError(f"No markdown files matched: {input_value}")
base_dir = Path(os.path.commonpath([str(p.resolve()) for p in paths]))
return paths, base_dir
input_path = Path(input_value)
if input_path.is_dir():
paths = collect_input_paths(input_path)
if not paths:
raise ValueError(f"No markdown files found under {input_path}")
return paths, input_path
if input_path.exists():
return [input_path], input_path.parent
raise ValueError(f"Input path not found: {input_path}")
def _run_pipeline(
args: argparse.Namespace,
*,
input_path: Path,
out_dir: Path,
emit_stdout: bool,
) -> tuple[dict[str, object], int]:
started = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
out_dir.mkdir(parents=True, exist_ok=True)
steps: list[dict[str, object]] = []
warnings: list[str] = []
def run_step(name: str, func, ns: argparse.Namespace) -> int:
buf = io.StringIO()
with redirect_stdout(buf):
rc = func(ns)
entry: dict[str, object] = {"name": name, "rc": rc, "ok": rc == EXIT_OK}
output = buf.getvalue().strip()
if rc != 0 and output:
entry["stdout"] = output
steps.append(entry)
return rc
def record_skip(name: str, reason: str) -> None:
steps.append({"name": name, "rc": None, "ok": False, "skipped": True, "reason": reason})
validate_args = argparse.Namespace(spec=args.spec, out=str(out_dir), build_indexes=True)
rc_validate = run_step("validate-spec", _cmd_validate_spec, validate_args)
if rc_validate == EXIT_CONFIG:
summary = _finalize_run(
args,
steps,
warnings,
started,
EXIT_CONFIG,
input_path=input_path,
out_dir=out_dir,
emit_stdout=emit_stdout,
)
return summary, EXIT_CONFIG
lint_args = argparse.Namespace(
spec=args.spec,
input=str(input_path),
out=str(out_dir),
profile=args.profile,
format=args.format,
fail_on=args.fail_on,
degraded_ok=args.degraded_ok,
fix=args.fix,
fix_mode=args.fix_mode,
lint_fixed=args.lint_fixed,
)
rc_lint = run_step("lint", _cmd_lint, lint_args)
if rc_lint == EXIT_CONFIG:
summary = _finalize_run(
args,
steps,
warnings,
started,
EXIT_CONFIG,
input_path=input_path,
out_dir=out_dir,
emit_stdout=emit_stdout,
)
return summary, EXIT_CONFIG
render_html_args = argparse.Namespace(
spec=args.spec,
input=str(input_path),
out=str(out_dir),
profile=args.profile,
self_contained=args.self_contained,
degraded_ok=args.degraded_ok,
)
rc_html = run_step("render-html", _cmd_render_html, render_html_args)
if rc_html == EXIT_CONFIG:
summary = _finalize_run(
args,
steps,
warnings,
started,
EXIT_CONFIG,
input_path=input_path,
out_dir=out_dir,
emit_stdout=emit_stdout,
)
return summary, EXIT_CONFIG
if args.skip_pdf:
record_skip("render-pdf", "skip_pdf")
rc_pdf = EXIT_OK
else:
render_pdf_args = argparse.Namespace(
spec=args.spec,
input=str(input_path),
out=str(out_dir),
profile=args.profile,
engine=getattr(args, "engine", None),
self_contained=args.self_contained,
)
rc_pdf = run_step("render-pdf", _cmd_render_pdf, render_pdf_args)
if rc_pdf == EXIT_CONFIG:
summary = _finalize_run(
args,
steps,
warnings,
started,
EXIT_CONFIG,
input_path=input_path,
out_dir=out_dir,
emit_stdout=emit_stdout,
)
return summary, EXIT_CONFIG
if rc_pdf == EXIT_RENDER:
if getattr(args, "require_pdf", False):
warnings.append("render-pdf failed and require-pdf is set")
else:
warnings.append("render-pdf failed or renderer missing; continuing with HTML QA")
if (out_dir / "render.html").exists():
qa_args = argparse.Namespace(
spec=args.spec,
out=str(out_dir),
profile=args.profile,
strict=args.strict,
html=None,
pdf=None,
format="json",
)
rc_qa = run_step("qa", _cmd_qa, qa_args)
else:
record_skip("qa", "render-html missing")
rc_qa = EXIT_CONFIG
report_args = argparse.Namespace(spec=args.spec, out=str(out_dir), strict=args.strict, build_indexes=True)
rc_report = run_step("report", _cmd_report, report_args)
exit_code = EXIT_OK
if EXIT_CONFIG in {rc_validate, rc_lint, rc_html, rc_pdf, rc_qa, rc_report}:
exit_code = EXIT_CONFIG
elif EXIT_RENDER in {rc_pdf} and getattr(args, "require_pdf", False):
exit_code = EXIT_RENDER
elif EXIT_GATE_FAIL in {rc_lint, rc_html, rc_qa, rc_report}:
exit_code = EXIT_GATE_FAIL
summary = _finalize_run(
args,
steps,
warnings,
started,
exit_code,
input_path=input_path,
out_dir=out_dir,
emit_stdout=emit_stdout,
)
return summary, exit_code
def _cmd_run(args: argparse.Namespace) -> int:
if getattr(args, "skip_pdf", False) and getattr(args, "require_pdf", False):
print(json.dumps({"ok": False, "error": "--skip-pdf and --require-pdf cannot be used together"}))
return EXIT_CONFIG
try:
input_paths, base_dir = _resolve_run_inputs(args.input)
except ValueError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
out_root = Path(args.out)
if len(input_paths) == 1:
_, exit_code = _run_pipeline(
args,
input_path=input_paths[0],
out_dir=out_root,
emit_stdout=True,
)
return exit_code
started = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
out_root.mkdir(parents=True, exist_ok=True)
documents: list[dict[str, object]] = []
warnings: list[str] = []
for path in input_paths:
try:
rel = path.resolve().relative_to(base_dir.resolve())
except ValueError:
rel = Path(path.name)
rel = rel.with_suffix("")
doc_out = out_root / "docs" / rel
doc_out.mkdir(parents=True, exist_ok=True)
summary, exit_code = _run_pipeline(
args,
input_path=path,
out_dir=doc_out,
emit_stdout=False,
)
report_index = doc_out / "report" / "index.html"
doc_entry = {
"input": str(path.resolve()),
"rel_input": rel.as_posix(),
"out_dir": str(doc_out.resolve()),
"exit_code": exit_code,
"ok": exit_code == EXIT_OK,
"summary": str((doc_out / "run-summary.json").resolve()),
"report_index": str(report_index.resolve()) if report_index.exists() else None,
}
documents.append(doc_entry)
for warning in summary.get("warnings", []) if isinstance(summary, dict) else []:
warnings.append(f"{rel.as_posix()}: {warning}")
finished = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
codes = [int(doc.get("exit_code", EXIT_OK)) for doc in documents]
exit_code = EXIT_OK
if EXIT_CONFIG in codes:
exit_code = EXIT_CONFIG
elif EXIT_RENDER in codes:
exit_code = EXIT_RENDER
elif EXIT_GATE_FAIL in codes:
exit_code = EXIT_GATE_FAIL
summary = {
"ok": exit_code == EXIT_OK,
"exit_code": exit_code,
"mode": "multi",
"started_at_utc": started,
"finished_at_utc": finished,
"spec_root": str(Path(args.spec).resolve()),
"input": str(args.input),
"profile": str(args.profile),
"out_dir": str(out_root.resolve()),
"documents": documents,
"warnings": warnings,
}
_write_json(out_root / "run-summary.json", summary)
report_dir = out_root / "report"
report_dir.mkdir(parents=True, exist_ok=True)
(report_dir / "index.html").write_text(build_run_index(out_root, documents), encoding="utf-8")
print(json.dumps({"ok": summary["ok"], "out_dir": summary["out_dir"], "exit_code": exit_code}, indent=2))
return exit_code
def _finalize_run(
args: argparse.Namespace,
steps: list[dict[str, object]],
warnings: list[str],
started: str,
exit_code: int,
*,
input_path: Path,
out_dir: Path,
emit_stdout: bool,
) -> dict[str, object]:
finished = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
summary = {
"ok": exit_code == 0,
"exit_code": exit_code,
"started_at_utc": started,
"finished_at_utc": finished,
"spec_root": str(Path(args.spec).resolve()),
"input": str(input_path.resolve()),
"profile": str(args.profile),
"out_dir": str(out_dir.resolve()),
"steps": steps,
"warnings": warnings,
}
_write_json(out_dir / "run-summary.json", summary)
if emit_stdout:
print(json.dumps({"ok": summary["ok"], "out_dir": summary["out_dir"], "exit_code": exit_code}, indent=2))
return summary
def _cmd_emit_css(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profile = spec.profiles.get(str(args.profile))
if not profile:
print(json.dumps({"ok": False, "error": f"Unknown profile_id: {args.profile}"}))
return EXIT_CONFIG
out_dir = Path(args.out)
out_dir.mkdir(parents=True, exist_ok=True)
css_out = generate_profile_css(profile)
(out_dir / "render.css").write_text(css_out.css, encoding="utf-8")
(out_dir / "typeset-report.json").write_text(
json.dumps(css_out.report, indent=2, sort_keys=True) + "\n", encoding="utf-8"
)
print(json.dumps({"ok": True, "out_dir": str(out_dir.resolve())}, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_profiles_list(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profiles = sorted(spec.profiles.keys())
print(json.dumps({"ok": True, "profiles": profiles}, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_gates_show(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profile_id = str(args.profile)
gates_all = spec.quality_gates.get("profiles", {}).get(profile_id)
if not gates_all:
print(json.dumps({"ok": False, "error": f"Missing quality gates for profile {profile_id}"}))
return EXIT_CONFIG
mode = "strict" if args.strict else "default"
gates = gates_all.get(mode) or {}
print(json.dumps({"ok": True, "profile": profile_id, "mode": mode, "gates": gates}, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_rules_list(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
categories = set(args.category or [])
enforcements = set(args.enforcement or [])
severities = set(args.severity or [])
tags_filter = set(args.tag or [])
items: list[dict[str, object]] = []
for rule in spec.rules:
raw = rule.raw
if categories and rule.category not in categories:
continue
if enforcements and rule.enforcement not in enforcements:
continue
if severities and rule.severity not in severities:
continue
tags = [str(t) for t in (raw.get("tags") or [])]
if tags_filter and not tags_filter.issubset(set(tags)):
continue
items.append(
{
"id": rule.id,
"title": raw.get("title", ""),
"category": rule.category,
"severity": rule.severity,
"enforcement": rule.enforcement,
"manual_checklist": "manual_checklist=true" in tags,
"tags": tags,
}
)
print(json.dumps({"ok": True, "count": len(items), "rules": items}, indent=2, sort_keys=True))
return EXIT_OK
def _cmd_rules_show(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
target = str(args.rule_id)
for rule in spec.rules:
if rule.id == target:
out = dict(rule.raw)
out["source_path"] = rule.source_path
out["line_no"] = rule.line_no
print(json.dumps({"ok": True, "rule": out}, indent=2, sort_keys=True))
return EXIT_OK
print(json.dumps({"ok": False, "error": f"Rule not found: {target}"}))
return EXIT_CONFIG
def _cmd_lint(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profile = spec.profiles.get(str(args.profile))
if not profile:
print(json.dumps({"ok": False, "error": f"Unknown profile_id: {args.profile}"}))
return EXIT_CONFIG
input_path = Path(args.input)
if not input_path.exists():
print(json.dumps({"ok": False, "error": f"Input path not found: {input_path}"}))
return EXIT_CONFIG
paths = collect_input_paths(input_path)
if not paths:
print(json.dumps({"ok": False, "error": f"No markdown files found under {input_path}"}))
return EXIT_CONFIG
result = lint_paths(
paths,
profile_id=str(args.profile),
fix=args.fix,
fix_mode=args.fix_mode,
lint_fixed=getattr(args, "lint_fixed", False),
degraded_ok=args.degraded_ok,
fail_on=args.fail_on,
)
out_dir = Path(args.out)
out_dir.mkdir(parents=True, exist_ok=True)
_write_json(out_dir / "lint-report.json", result.report)
if result.degraded:
_write_json(out_dir / "degraded-mode-report.json", {"files": result.degraded})
checklist = manual_checklist(spec)
_write_json(out_dir / "manual-checklist.json", {"items": checklist})
(out_dir / "manual-checklist.md").write_text(_manual_checklist_md(checklist), encoding="utf-8")
if args.fix:
if args.fix_mode == "rewrite":
fixed_dir = out_dir / "fixed"
fixed_dir.mkdir(parents=True, exist_ok=True)
for path_str, content in result.fixed_outputs.items():
path = Path(path_str)
rel = path.name if input_path.is_file() else path.relative_to(input_path)
out_path = fixed_dir / rel
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(content, encoding="utf-8")
else:
_write_json(out_dir / "fix-suggestions.json", {"fixes": result.report.get("fixes", [])})
if args.format == "sarif":
_write_json(out_dir / "lint-report.sarif", _to_sarif(result.report))
if args.format == "json":
print(json.dumps(result.report, indent=2, sort_keys=True))
if args.format == "text":
print(_lint_text_summary(result.report))
return EXIT_OK if result.report.get("ok") else EXIT_GATE_FAIL
def _cmd_render_html(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profile = spec.profiles.get(str(args.profile))
if not profile:
print(json.dumps({"ok": False, "error": f"Unknown profile_id: {args.profile}"}))
return EXIT_CONFIG
input_path = Path(args.input)
if not input_path.exists() or input_path.is_dir():
print(json.dumps({"ok": False, "error": f"Input markdown file not found: {input_path}"}))
return EXIT_CONFIG
out_dir = Path(args.out)
out_dir.mkdir(parents=True, exist_ok=True)
result = render_html(input_path, profile, self_contained=args.self_contained)
(out_dir / "render.html").write_text(result.html, encoding="utf-8")
(out_dir / "render.css").write_text(result.css, encoding="utf-8")
_write_json(out_dir / "typeset-report.json", result.typeset_report)
if result.degraded:
_write_json(out_dir / "degraded-mode-report.json", {"files": result.degraded})
summary = {
"ok": True,
"out_dir": str(out_dir.resolve()),
"warnings": result.warnings,
"degraded": result.degraded,
}
print(json.dumps(summary, indent=2, sort_keys=True))
if result.degraded and not args.degraded_ok:
return EXIT_GATE_FAIL
return EXIT_OK
def _cmd_render_pdf(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profile = spec.profiles.get(str(args.profile))
if not profile:
print(json.dumps({"ok": False, "error": f"Unknown profile_id: {args.profile}"}))
return EXIT_CONFIG
input_path = Path(args.input)
if not input_path.exists() or input_path.is_dir():
print(json.dumps({"ok": False, "error": f"Input markdown file not found: {input_path}"}))
return EXIT_CONFIG
out_dir = Path(args.out)
result = render_pdf(
input_path,
profile,
out_dir,
engine_name=getattr(args, "engine", None),
self_contained=args.self_contained,
)
_write_json(out_dir / "render-log.json", result.log)
if result.ok:
print(json.dumps({"ok": True, "engine": result.engine, "pdf": result.pdf_path}, indent=2, sort_keys=True))
return EXIT_OK
print(json.dumps({"ok": False, "engine": result.engine, "error": result.log.get("error")}, indent=2, sort_keys=True))
return EXIT_RENDER
def _cmd_qa(args: argparse.Namespace) -> int:
try:
spec = load_spec(Path(args.spec))
except SpecError as e:
print(json.dumps({"ok": False, "error": str(e)}))
return EXIT_CONFIG
profile = spec.profiles.get(str(args.profile))
if not profile:
print(json.dumps({"ok": False, "error": f"Unknown profile_id: {args.profile}"}))
return EXIT_CONFIG
out_dir = Path(args.out)
html_path = Path(args.html) if getattr(args, "html", None) else (out_dir / "render.html")
pdf_path = Path(args.pdf) if getattr(args, "pdf", None) else (out_dir / "render.pdf")
if not html_path.exists():
print(json.dumps({"ok": False, "error": f"Missing HTML input at {html_path}"}))
return EXIT_CONFIG
html_text = html_path.read_text(encoding="utf-8")
layout = analyze_html(html_text, profile, analysis_mode="html")
metrics = dict(layout.metrics)
incidents = list(layout.incidents)
warnings = list(layout.warnings)
analysis_mode = layout.analysis_mode
if pdf_path.exists():
pdf_result = analyze_pdf(pdf_path, profile, analysis_mode="pdf")
if pdf_result.ok:
metrics["max_widows_per_10_pages"] = pdf_result.metrics.get("max_widows_per_10_pages", 0)
metrics["max_orphans_per_10_pages"] = pdf_result.metrics.get("max_orphans_per_10_pages", 0)
if "max_overfull_lines" in pdf_result.metrics:
metrics["max_overfull_lines"] = max(
metrics.get("max_overfull_lines", 0),
pdf_result.metrics.get("max_overfull_lines", 0),
)
if "max_stranded_headings" in pdf_result.metrics:
metrics["max_stranded_headings"] = max(
metrics.get("max_stranded_headings", 0),
pdf_result.metrics.get("max_stranded_headings", 0),
)
for key in (
"max_caption_separation_incidents",
"max_list_break_incidents",
"max_heading_proximity_incidents",
"max_runt_final_page",
):
if key in pdf_result.metrics:
metrics[key] = max(metrics.get(key, 0), pdf_result.metrics.get(key, 0))
incidents.extend(pdf_result.incidents)
warnings.extend(pdf_result.warnings)
analysis_mode = "html+pdf"
else:
warnings.extend(pdf_result.warnings or ["PDF analysis failed; HTML-only analysis used"])
else:
warnings.append("PDF not available; HTML-only analysis used")
layout = LayoutReport(
metrics=metrics,
incidents=incidents,
warnings=warnings,
profile_id=layout.profile_id,
analysis_mode=analysis_mode,
)
gates_all = spec.quality_gates.get("profiles", {}).get(str(args.profile))
if not gates_all:
print(json.dumps({"ok": False, "error": f"Missing quality gates for profile {args.profile}"}))
return EXIT_CONFIG
gates = gates_all.get("strict" if args.strict else "default") or {}
qa_report = evaluate_gates(layout.metrics, gates, profile_id=str(args.profile), strict=args.strict)
qa_report["metrics"] = layout.metrics
layout_dict = layout_report_dict(layout)
layout_dict.setdefault("inputs", {})["html"] = str(html_path.resolve())
if pdf_path.exists():
layout_dict.setdefault("inputs", {})["pdf"] = str(pdf_path.resolve())
_write_json(out_dir / "layout-report.json", layout_dict)
_write_json(out_dir / "qa-report.json", qa_report)
if args.format == "sarif":
_write_json(out_dir / "qa-report.sarif", _qa_to_sarif(layout_dict, qa_report))
print(json.dumps({"ok": qa_report.get("ok"), "out_dir": str(out_dir.resolve())}, indent=2, sort_keys=True))
return EXIT_OK if qa_report.get("ok") else EXIT_GATE_FAIL
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="iftypeset",
description="Publication-quality typesetting runtime (spec tooling).",
)
parser.add_argument("--config", help="Path to iftypeset.yaml (defaults to ./iftypeset.yaml when present).")
parser.add_argument("--version", action="store_true", help="Print tool version and exit.")
sub = parser.add_subparsers(dest="command")
validate = sub.add_parser("validate-spec", help="Validate spec files and rule records.")
validate.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
validate.add_argument("--out", default="out", help="Output directory (default: ./out).")
validate.add_argument("--build-indexes", action="store_true", help="Build and write indexes into spec/indexes/.")
validate.set_defaults(func=_cmd_validate_spec)
report = sub.add_parser("report", help="Generate coverage report from the current spec and rule set.")
report.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
report.add_argument("--out", default="out", help="Output directory (default: ./out).")
report.add_argument("--strict", action="store_true", help="Fail if coverage floors are not met.")
report.add_argument("--build-indexes", action="store_true", help="Build and write indexes into spec/indexes/.")
report.set_defaults(func=_cmd_report)
doctor = sub.add_parser("doctor", help="Emit environment + determinism report.")
doctor.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
doctor.add_argument("--out", default="out", help="Output directory (default: ./out).")
doctor.set_defaults(func=_cmd_doctor)
bundle = sub.add_parser("bundle", help="Create a portable review bundle from out/ artifacts.")
bundle.add_argument("--out", default="out", help="Output directory (default: ./out).")
bundle.add_argument("--bundle", help="Bundle output path (default: <out>/iftypeset-bundle.tar.gz).")
bundle.add_argument(
"--max-size-mb",
type=float,
default=50.0,
help="Skip artifacts larger than this size (default: 50).",
)
bundle.set_defaults(func=_cmd_bundle)
run = sub.add_parser("run", help="Run a CI-style pipeline: validate → lint → render → qa → report.")
run.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
run.add_argument("--input", required=True, help="Markdown file.")
run.add_argument("--out", default="out", help="Output directory (default: ./out).")
run.add_argument("--profile", help="Profile id (default: web_pdf or config).")
run.add_argument("--strict", action="store_true", help="Use strict QA/report thresholds.")
run.add_argument("--format", default="json", choices=["json", "sarif", "text"], help="Lint output format.")
run.add_argument("--fail-on", default="must", choices=["must", "should", "warn"], help="Lint fail threshold.")
run.add_argument("--degraded-ok", action="store_true", help="Allow degraded mode without failing.")
run.add_argument("--fix", action="store_true", help="Apply safe deterministic fixes.")
run.add_argument("--fix-mode", default="suggest", choices=["suggest", "rewrite"], help="Fix mode.")
run.add_argument(
"--lint-fixed",
action="store_true",
help="When rewriting fixes, lint the fixed output instead of the original.",
)
run.add_argument("--self-contained", action="store_true", help="Embed local images as data URIs.")
run.add_argument(
"--engine",
default="playwright",
help="Preferred PDF engine (default: playwright; use auto to pick first available).",
)
run.add_argument(
"--require-pdf",
action="store_true",
help="Fail the run if PDF rendering fails.",
)
run.add_argument("--skip-pdf", action="store_true", help="Skip PDF rendering.")
run.set_defaults(func=_cmd_run)
emit_css = sub.add_parser("emit-css", help="Emit deterministic CSS for a given typeset profile.")
emit_css.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
emit_css.add_argument("--profile", help="Profile id (default: web_pdf or config).")
emit_css.add_argument("--out", default="out", help="Output directory (default: ./out).")
emit_css.set_defaults(func=_cmd_emit_css)
profiles = sub.add_parser("profiles", help="Inspect available profiles.")
profiles_sub = profiles.add_subparsers(dest="profiles_cmd", required=True)
profiles_list = profiles_sub.add_parser("list", help="List profiles in the current spec.")
profiles_list.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
profiles_list.set_defaults(func=_cmd_profiles_list)
gates = sub.add_parser("gates", help="Inspect QA gates.")
gates_sub = gates.add_subparsers(dest="gates_cmd", required=True)
gates_show = gates_sub.add_parser("show", help="Show QA gates for a profile.")
gates_show.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
gates_show.add_argument("--profile", help="Profile id (default: web_pdf or config).")
gates_show.add_argument("--strict", action="store_true", help="Use strict thresholds.")
gates_show.set_defaults(func=_cmd_gates_show)
rules = sub.add_parser("rules", help="Inspect rule registry.")
rules_sub = rules.add_subparsers(dest="rules_cmd", required=True)
rules_list = rules_sub.add_parser("list", help="List rules (optional filters).")
rules_list.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
rules_list.add_argument("--category", action="append", help="Filter by category.")
rules_list.add_argument("--enforcement", action="append", help="Filter by enforcement.")
rules_list.add_argument("--severity", action="append", help="Filter by severity.")
rules_list.add_argument("--tag", action="append", help="Filter by tag (can be repeated).")
rules_list.set_defaults(func=_cmd_rules_list)
rules_show = rules_sub.add_parser("show", help="Show a rule by id.")
rules_show.add_argument("rule_id", help="Rule identifier.")
rules_show.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
rules_show.set_defaults(func=_cmd_rules_show)
lint = sub.add_parser("lint", help="Run Markdown lint rules and emit diagnostics.")
lint.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
lint.add_argument("--input", required=True, help="Markdown file or directory.")
lint.add_argument("--out", default="out", help="Output directory (default: ./out).")
lint.add_argument("--profile", help="Profile id (default: web_pdf or config).")
lint.add_argument("--format", default="json", choices=["json", "sarif", "text"], help="Output format.")
lint.add_argument("--fail-on", default="must", choices=["must", "should", "warn"], help="Fail threshold.")
lint.add_argument("--degraded-ok", action="store_true", help="Allow degraded mode without failing.")
lint.add_argument("--fix", action="store_true", help="Apply safe deterministic fixes.")
lint.add_argument("--fix-mode", default="suggest", choices=["suggest", "rewrite"], help="Fix mode.")
lint.add_argument(
"--lint-fixed",
action="store_true",
help="When rewriting fixes, lint the fixed output instead of the original.",
)
lint.set_defaults(func=_cmd_lint)
render_html_cmd = sub.add_parser("render-html", help="Render Markdown to deterministic HTML + CSS.")
render_html_cmd.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
render_html_cmd.add_argument("--input", required=True, help="Markdown file.")
render_html_cmd.add_argument("--out", default="out", help="Output directory (default: ./out).")
render_html_cmd.add_argument("--profile", help="Profile id (default: web_pdf or config).")
render_html_cmd.add_argument("--self-contained", action="store_true", help="Embed local images as data URIs.")
render_html_cmd.add_argument("--degraded-ok", action="store_true", help="Allow degraded mode without failing.")
render_html_cmd.set_defaults(func=_cmd_render_html)
render_pdf_cmd = sub.add_parser("render-pdf", help="Render Markdown to PDF using available engines.")
render_pdf_cmd.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
render_pdf_cmd.add_argument("--input", required=True, help="Markdown file.")
render_pdf_cmd.add_argument("--out", default="out", help="Output directory (default: ./out).")
render_pdf_cmd.add_argument("--profile", help="Profile id (default: web_pdf or config).")
render_pdf_cmd.add_argument("--self-contained", action="store_true", help="Embed local images as data URIs.")
render_pdf_cmd.add_argument(
"--engine",
default="playwright",
help="Preferred PDF engine (default: playwright; use auto to pick first available).",
)
render_pdf_cmd.set_defaults(func=_cmd_render_pdf)
qa = sub.add_parser("qa", help="Run post-render QA gates.")
qa.add_argument("--spec", default="spec", help="Spec root directory (default: ./spec).")
qa.add_argument("--out", default="out", help="Output directory (default: ./out).")
qa.add_argument("--html", help="HTML file to analyze (default: <out>/render.html).")
qa.add_argument("--pdf", help="Optional PDF path for reporting (default: <out>/render.pdf).")
qa.add_argument("--profile", help="Profile id (default: web_pdf or config).")
qa.add_argument("--strict", action="store_true", help="Use strict thresholds.")
qa.add_argument("--format", default="json", choices=["json", "sarif"], help="Output format.")
qa.set_defaults(func=_cmd_qa)
return parser
def _write_json(path: Path, data: dict[str, object]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
def _manual_checklist_md(items: list[dict[str, object]]) -> str:
lines = ["# Manual checklist", ""]
if not items:
lines.append("_No manual checklist items._")
lines.append("")
return "\n".join(lines)
for item in items:
lines.append(f"- {item.get('id')}: {item.get('title')}")
if item.get("rule_text"):
lines.append(f" - {item.get('rule_text')}")
if item.get("source_refs"):
refs = ", ".join([str(r) for r in item.get("source_refs") or []])
lines.append(f" - Source: {refs}")
lines.append("")
return "\n".join(lines)
def _lint_text_summary(report: dict[str, object]) -> str:
summary = report.get("summary", {}) if isinstance(report.get("summary"), dict) else {}
counts = summary.get("diagnostic_counts", {}) if isinstance(summary.get("diagnostic_counts"), dict) else {}
degraded = summary.get("degraded_files", 0)
lines = [
f"Diagnostics: must={counts.get('must', 0)}, should={counts.get('should', 0)}, warn={counts.get('warn', 0)}",
f"Degraded files: {degraded}",
]
return "\n".join(lines)
def _to_sarif(report: dict[str, object]) -> dict[str, object]:
results = []
for diag in report.get("diagnostics", []) or []:
if not isinstance(diag, dict):
continue
severity = diag.get("severity")
level = "warning"
if severity == "must":
level = "error"
elif severity == "warn":
level = "note"
results.append(
{
"ruleId": diag.get("code"),
"level": level,
"message": {"text": diag.get("message")},
"locations": [
{
"physicalLocation": {
"artifactLocation": {"uri": diag.get("path")},
"region": {"startLine": diag.get("line") or 1},
}
}
],
}
)
return {
"version": "2.1.0",
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"runs": [
{
"tool": {"driver": {"name": "iftypeset", "version": __version__}},
"results": results,
}
],
}
def _qa_to_sarif(layout: dict[str, object], qa_report: dict[str, object]) -> dict[str, object]:
incidents = layout.get("incidents", []) or []
inputs = layout.get("inputs", {}) if isinstance(layout.get("inputs"), dict) else {}
html_uri = inputs.get("html")
pdf_uri = inputs.get("pdf")
results: list[dict[str, object]] = []
def _artifact_for_kind(kind: str) -> str | None:
if kind.endswith("_pdf"):
return pdf_uri or html_uri
return html_uri
for incident in incidents:
if not isinstance(incident, dict):
continue
kind = str(incident.get("kind") or "qa_incident")
rule_id = QA_RULE_MAP.get(kind, f"QA.{kind}")
detail = str(incident.get("detail") or kind)
context = str(incident.get("context") or "").strip()
message = detail if not context else f"{detail} ({context})"
artifact = _artifact_for_kind(kind)
locations = []
if artifact:
locations.append(
{
"physicalLocation": {
"artifactLocation": {"uri": artifact},
"region": {"startLine": 1},
}
}
)
results.append(
{
"ruleId": rule_id,
"level": "warning",
"message": {"text": message},
"locations": locations,
"properties": {"incident_kind": kind},
}
)
gates = qa_report.get("gates", {}) if isinstance(qa_report.get("gates"), dict) else {}
for metric, gate in gates.items():
if not isinstance(gate, dict):
continue
if gate.get("status") != "fail":
continue
count = gate.get("count")
maximum = gate.get("max")
rule_id = f"QA_GATE.{metric}"
message = f"QA gate failed: {metric} count {count} > max {maximum}"
locations = []
if html_uri:
locations.append(
{
"physicalLocation": {
"artifactLocation": {"uri": html_uri},
"region": {"startLine": 1},
}
}
)
results.append(
{
"ruleId": rule_id,
"level": "error",
"message": {"text": message},
"locations": locations,
"properties": {"metric": metric, "count": count, "max": maximum},
}
)
return {
"version": "2.1.0",
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"runs": [
{
"tool": {"driver": {"name": "iftypeset", "version": __version__}},
"results": results,
}
],
}
def main(argv: list[str] | None = None) -> None:
parser = build_parser()
raw_argv = list(argv) if argv is not None else sys.argv[1:]
args = parser.parse_args(raw_argv)
if args.version:
print(
json.dumps(
{
"tool": "iftypeset",
"version": __version__,
"renderer": renderer_info(),
},
indent=2,
sort_keys=True,
)
)
raise SystemExit(0)
if not getattr(args, "func", None):
parser.error("Command required")
try:
args = apply_config(args, raw_argv)
except Exception as exc:
print(json.dumps({"ok": False, "error": str(exc)}))
raise SystemExit(EXIT_CONFIG)
try:
rc = int(args.func(args))
except BrokenPipeError:
rc = EXIT_CONFIG
raise SystemExit(rc)
if __name__ == "__main__":
main(sys.argv[1:])
````
### `iftypeset/src/iftypeset/config.py`
- bytes: `3310`
- sha256: `b60b4324f7eae0fdfe2aaf7d2d8cbcbb37fc9b277bc868946e325f22795dbf33`
````py
from __future__ import annotations
from pathlib import Path
from typing import Any
import yaml
def _argv_has_flag(argv: list[str], flag: str) -> bool:
prefix = f"{flag}="
return any(arg == flag or arg.startswith(prefix) for arg in argv)
def _get_section(config: dict[str, Any], command: str | None) -> dict[str, Any]:
if not command:
return {}
key = command.replace("-", "_")
section = config.get(key)
if isinstance(section, dict):
return section
if key in {"render_html", "render_pdf"}:
section = config.get("render")
if isinstance(section, dict):
return section
return {}
def find_config_path(spec_root: Path | None, cwd: Path, explicit: Path | None) -> Path | None:
if explicit:
return explicit
candidates: list[Path] = []
candidates.append(cwd / "iftypeset.yaml")
if spec_root is not None:
candidates.append(spec_root.parent / "iftypeset.yaml")
for path in candidates:
if path.exists():
return path
return None
def load_config(path: Path | None) -> dict[str, Any]:
if not path:
return {}
if not path.exists():
raise ValueError(f"Config not found: {path}")
raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
if not isinstance(raw, dict):
raise ValueError("Config must be a mapping at the top level.")
return raw
def apply_config(args: Any, argv: list[str]) -> Any:
spec_root = Path(getattr(args, "spec", "spec"))
explicit = Path(args.config) if getattr(args, "config", None) else None
config_path = find_config_path(spec_root if spec_root else None, Path.cwd(), explicit)
if not config_path:
if hasattr(args, "profile") and not getattr(args, "profile"):
setattr(args, "profile", "web_pdf")
return args
config = load_config(config_path)
defaults = config.get("defaults") if isinstance(config.get("defaults"), dict) else {}
section = _get_section(config, getattr(args, "command", None))
def get_value(key: str) -> Any:
if key in section:
return section.get(key)
return defaults.get(key)
def maybe_set(attr: str, flag: str, key: str) -> None:
if not hasattr(args, attr):
return
if _argv_has_flag(argv, flag):
return
value = get_value(key)
if value is not None:
setattr(args, attr, value)
maybe_set("spec", "--spec", "spec")
maybe_set("out", "--out", "out")
maybe_set("profile", "--profile", "profile")
maybe_set("strict", "--strict", "strict")
maybe_set("format", "--format", "format")
maybe_set("fail_on", "--fail-on", "fail_on")
maybe_set("degraded_ok", "--degraded-ok", "degraded_ok")
maybe_set("fix", "--fix", "fix")
maybe_set("fix_mode", "--fix-mode", "fix_mode")
maybe_set("lint_fixed", "--lint-fixed", "lint_fixed")
maybe_set("self_contained", "--self-contained", "self_contained")
maybe_set("engine", "--engine", "engine")
maybe_set("require_pdf", "--require-pdf", "require_pdf")
maybe_set("skip_pdf", "--skip-pdf", "skip_pdf")
if hasattr(args, "profile") and not getattr(args, "profile"):
setattr(args, "profile", get_value("profile") or "web_pdf")
return args
````
### `iftypeset/src/iftypeset/css_gen.py`
- bytes: `26652`
- sha256: `5188946444af313e90e7d8a6e2fe25240bb16f657c89d2a0cc0a65df78d0c31d`
````py
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
import re
@dataclass(frozen=True)
class CssOutput:
css: str
report: dict[str, Any]
def generate_profile_css(profile: dict[str, Any]) -> CssOutput:
profile_id = str(profile.get("profile_id") or "").strip()
if not profile_id:
raise ValueError("profile_id is required")
page = profile.get("page") or {}
fonts = profile.get("fonts") or {}
colors = profile.get("colors") or {}
paragraphs = profile.get("paragraphs") or {}
hyphenation = profile.get("hyphenation") or {}
widows_orphans = profile.get("widows_orphans") or {}
headings = profile.get("headings") or {}
heading_sizes_cfg = headings.get("sizes") or {}
heading_spacing = headings.get("spacing") or {}
code = profile.get("code") or {}
tables = profile.get("tables") or {}
figures = profile.get("figures") or {}
typography = profile.get("typography") or {}
lists = profile.get("lists") or {}
layout = profile.get("layout") or {}
page_size = str(page.get("size") or "Letter")
orientation = str(page.get("orientation") or "portrait")
two_sided = bool(page.get("two_sided") or False)
margins = page.get("margins") or {}
margin_top = str(margins.get("top") or "1in")
margin_bottom = str(margins.get("bottom") or "1in")
margin_inner = str(margins.get("inner") or "1in")
margin_outer = str(margins.get("outer") or "1in")
body_font = fonts.get("body") or {}
heading_font = fonts.get("heading") or {}
mono_font = fonts.get("mono") or {}
body_family = _font_stack(body_font.get("family") or [])
heading_family = _font_stack(heading_font.get("family") or [])
mono_family = _font_stack(mono_font.get("family") or [])
body_color = str(colors.get("body") or "#111827")
accent_color = str(colors.get("accent") or body_color)
heading_color = str(colors.get("heading") or accent_color)
link_color = str(colors.get("link") or accent_color)
citation_color = str(colors.get("citation") or link_color)
table_rule_color = str(colors.get("table_rule") or "#e5e7eb")
table_stripe_bg = str(colors.get("table_stripe") or "transparent")
body_size = str(body_font.get("size") or "11pt")
body_line_height = body_font.get("line_height") or 1.45
heading_size = str(heading_font.get("size") or body_size)
mono_size = str(mono_font.get("size") or "10pt")
mono_line_height = mono_font.get("line_height") or 1.35
indent = str(paragraphs.get("indent") or "0")
first_paragraph_indent = str(paragraphs.get("first_paragraph_indent") or "0")
block_spacing = str(paragraphs.get("block_paragraph_spacing") or "0")
density_overrides = layout.get("density_overrides") or {}
use_density_vars = bool(density_overrides)
hyphens_enabled = bool(hyphenation.get("enabled") or False)
widows = int(widows_orphans.get("widow_lines") or 2)
orphans = int(widows_orphans.get("orphan_lines") or 2)
keep_with_next_lines = int(headings.get("keep_with_next_lines") or 2)
avoid_stranded = bool(headings.get("avoid_stranded_headings") or False)
heading_rule = headings.get("rule") or {}
heading_rule_enabled = bool(heading_rule.get("enabled") or False)
heading_rule_position = str(heading_rule.get("position") or "under")
heading_rule_thickness = str(heading_rule.get("thickness") or "1px")
heading_rule_color = str(heading_rule.get("color") or heading_color)
heading_rule_spacing = str(heading_rule.get("spacing") or "0.2em")
h1_size = str(heading_sizes_cfg.get("h1") or "1.8em")
h2_size = str(heading_sizes_cfg.get("h2") or "1.5em")
h3_size = str(heading_sizes_cfg.get("h3") or "1.25em")
h4_size = str(heading_sizes_cfg.get("h4") or "1.1em")
heading_margin_top = heading_spacing.get("top")
heading_margin_bottom = heading_spacing.get("bottom")
code_block = (code.get("block") or {}) if isinstance(code, dict) else {}
code_block_size = str(code_block.get("font_size") or mono_size)
code_block_line_height = code_block.get("line_height") or mono_line_height
code_block_wrap = bool(code_block.get("wrap") or False)
code_block_padding = str(code_block.get("padding") or "0.4em 0.6em")
code_block_background = str(code_block.get("background") or "transparent")
code_block_border = str(code_block.get("border") or "none")
code_block_radius = str(code_block.get("radius") or "0")
table_padding = str(tables.get("cell_padding") or "3pt 6pt")
table_header_repeat = bool(tables.get("header_repeat") or False)
table_layout = str(tables.get("layout") or "auto")
table_cell_wrap = bool(tables.get("cell_wrap") or False)
table_keep_together = bool(tables.get("keep_together") or False)
table_row_keep = bool(tables.get("row_keep_together") or False)
table_header_align = str(tables.get("header_align") or "left")
table_cell_align = str(tables.get("cell_align") or "left")
table_numeric_align = str(tables.get("numeric_align") or "right")
table_boolean_align = str(tables.get("boolean_align") or "center")
table_grid_style = str(tables.get("grid_style") or "boxed")
figure_max_width = str(figures.get("max_width") or "100%")
figure_margin = str(figures.get("margin") or "0.6em auto")
small_caps_cfg = typography.get("small_caps_acronyms") or {}
if isinstance(small_caps_cfg, dict):
small_caps_enabled = bool(small_caps_cfg.get("enabled") or False)
small_caps_tracking = str(small_caps_cfg.get("letter_spacing") or "0.04em")
else:
small_caps_enabled = bool(small_caps_cfg)
small_caps_tracking = "0.04em"
drop_caps_cfg = typography.get("drop_caps") or {}
drop_caps_enabled = bool(drop_caps_cfg.get("enabled") or False)
drop_caps_size = str(drop_caps_cfg.get("size") or "2.8em")
drop_caps_padding_right = str(drop_caps_cfg.get("padding_right") or "0.08em")
drop_caps_padding_top = str(drop_caps_cfg.get("padding_top") or "0.02em")
drop_caps_weight = str(drop_caps_cfg.get("weight") or "").strip()
text_wrap_cfg = typography.get("text_wrap") or {}
body_text_wrap = str(text_wrap_cfg.get("body") or "").strip()
heading_text_wrap = str(text_wrap_cfg.get("headings") or "").strip()
hanging_cfg = lists.get("hanging_punctuation") or {}
list_text_wrap = str(lists.get("text_wrap") or "").strip()
if isinstance(hanging_cfg, dict):
hanging_enabled = bool(hanging_cfg.get("enabled") or False)
hanging_indent = str(hanging_cfg.get("indent") or "1.2em")
hanging_hang = str(hanging_cfg.get("hang") or "0.4em")
else:
hanging_enabled = bool(hanging_cfg)
hanging_indent = str(lists.get("indent") or "1.2em")
hanging_hang = str(lists.get("hang") or "0.4em")
# Build CSS deterministically.
css: list[str] = []
css.append("/* iftypeset profile CSS */")
css.append(f"/* profile_id: {profile_id} */")
css.append("")
css.append(":root {")
css.append(f" --if-body-font: {body_family};")
css.append(f" --if-heading-font: {heading_family};")
css.append(f" --if-mono-font: {mono_family};")
css.append(f" --if-body-size: {body_size};")
css.append(f" --if-heading-size: {heading_size};")
css.append(f" --if-mono-size: {mono_size};")
css.append(f" --if-body-color: {body_color};")
css.append(f" --if-accent-color: {accent_color};")
css.append(f" --if-heading-color: {heading_color};")
css.append(f" --if-link-color: {link_color};")
css.append(f" --if-citation-color: {citation_color};")
css.append(f" --if-table-rule-color: {table_rule_color};")
css.append(f" --if-table-stripe-bg: {table_stripe_bg};")
css.append(f" --if-small-caps-tracking: {small_caps_tracking};")
css.append(f" --if-code-block-padding: {code_block_padding};")
css.append(f" --if-code-block-bg: {code_block_background};")
css.append(f" --if-code-block-border: {code_block_border};")
css.append(f" --if-code-block-radius: {code_block_radius};")
css.append(f" --if-figure-max-width: {figure_max_width};")
css.append(f" --if-figure-margin: {figure_margin};")
if use_density_vars:
css.append(f" --if-body-line-height: {body_line_height};")
css.append(f" --if-paragraph-spacing: {block_spacing};")
if heading_margin_top:
css.append(f" --if-heading-margin-top: {heading_margin_top};")
if heading_margin_bottom:
css.append(f" --if-heading-margin-bottom: {heading_margin_bottom};")
css.append("}")
css.append("")
# Paged media
css.append("@page {")
css.append(f" size: {page_size} {orientation};")
css.append(f" margin-top: {margin_top};")
css.append(f" margin-bottom: {margin_bottom};")
if two_sided:
css.append("}")
css.append("@page:left {")
css.append(f" margin-left: {margin_inner};")
css.append(f" margin-right: {margin_outer};")
css.append("}")
css.append("@page:right {")
css.append(f" margin-left: {margin_outer};")
css.append(f" margin-right: {margin_inner};")
else:
css.append(f" margin-left: {margin_inner};")
css.append(f" margin-right: {margin_outer};")
css.append("}")
css.append("")
css.append("html {")
css.append(" font-kerning: normal;")
css.append(" text-rendering: geometricPrecision;")
css.append("}")
css.append("")
css.append("body {")
css.append(" font-family: var(--if-body-font);")
css.append(f" font-size: var(--if-body-size);")
if use_density_vars:
css.append(" line-height: var(--if-body-line-height);")
else:
css.append(f" line-height: {body_line_height};")
if body_text_wrap:
css.append(f" text-wrap: {body_text_wrap};")
css.append(" color: var(--if-body-color);")
css.append("}")
css.append("")
if use_density_vars:
for name, cfg in density_overrides.items():
if not isinstance(cfg, dict):
continue
line_height = cfg.get("body_line_height")
spacing = cfg.get("paragraph_spacing")
heading_top = cfg.get("heading_margin_top")
heading_bottom = cfg.get("heading_margin_bottom")
if not line_height and not spacing and not heading_top and not heading_bottom:
continue
css.append(f"body.if-density-{name} {{")
if line_height:
css.append(f" --if-body-line-height: {line_height};")
if spacing:
css.append(f" --if-paragraph-spacing: {spacing};")
if heading_top:
css.append(f" --if-heading-margin-top: {heading_top};")
if heading_bottom:
css.append(f" --if-heading-margin-bottom: {heading_bottom};")
css.append("}")
css.append("")
css.append("h1, h2, h3, h4, h5, h6 {")
css.append(" font-family: var(--if-heading-font);")
css.append(" font-weight: 650;")
css.append(" color: var(--if-heading-color);")
if heading_text_wrap:
css.append(f" text-wrap: {heading_text_wrap};")
css.append(" break-after: avoid-page;")
css.append(" page-break-after: avoid;")
if avoid_stranded:
css.append(" break-inside: avoid;")
if use_density_vars:
if heading_margin_top:
css.append(" margin-top: var(--if-heading-margin-top);")
if heading_margin_bottom:
css.append(" margin-bottom: var(--if-heading-margin-bottom);")
else:
if heading_margin_top:
css.append(f" margin-top: {heading_margin_top};")
if heading_margin_bottom:
css.append(f" margin-bottom: {heading_margin_bottom};")
css.append("}")
css.append("")
css.append(f"h1 {{ font-size: {h1_size}; }}")
css.append(f"h2 {{ font-size: {h2_size}; }}")
css.append(f"h3 {{ font-size: {h3_size}; }}")
css.append(f"h4 {{ font-size: {h4_size}; }}")
css.append("")
css.append("p {")
if hyphens_enabled:
css.append(" hyphens: auto;")
css.append(f" widows: {widows};")
css.append(f" orphans: {orphans};")
if indent != "0":
css.append(f" text-indent: {indent};")
if use_density_vars:
css.append(" margin-top: var(--if-paragraph-spacing);")
css.append(" margin-bottom: var(--if-paragraph-spacing);")
elif block_spacing != "0":
css.append(f" margin-top: {block_spacing};")
css.append(f" margin-bottom: {block_spacing};")
css.append("}")
css.append("")
css.append("li {")
css.append(" break-inside: avoid;")
css.append(" page-break-inside: avoid;")
if hanging_enabled:
css.append(f" text-indent: -{hanging_hang};")
css.append(f" padding-left: {hanging_hang};")
if list_text_wrap:
css.append(f" text-wrap: {list_text_wrap};")
if hyphens_enabled:
css.append(" hyphens: auto;")
css.append("}")
css.append("")
if hanging_enabled:
css.append("ul {")
css.append(" list-style-position: outside;")
css.append(f" padding-left: {hanging_indent};")
css.append("}")
css.append("")
css.append("a {")
css.append(" color: var(--if-link-color);")
css.append(" text-decoration: underline;")
css.append(" text-underline-offset: 0.12em;")
css.append("}")
css.append("")
css.append(".if-citation {")
css.append(" color: var(--if-citation-color);")
css.append(" font-weight: 600;")
css.append(" white-space: nowrap;")
css.append("}")
css.append("")
if small_caps_enabled:
css.append(".if-sc {")
css.append(" font-variant-caps: all-small-caps;")
css.append(" letter-spacing: var(--if-small-caps-tracking);")
css.append("}")
css.append("")
# First paragraph in a section: no indent when configured.
if first_paragraph_indent == "0" and indent != "0":
css.append("main > p:first-of-type, section > p:first-of-type {")
css.append(" text-indent: 0;")
css.append("}")
css.append("")
css.append("code, pre {")
css.append(" font-family: var(--if-mono-font);")
css.append(f" font-size: {mono_size};")
css.append(f" line-height: {mono_line_height};")
css.append("}")
css.append("")
css.append("pre {")
css.append(f" font-size: {code_block_size};")
css.append(f" line-height: {code_block_line_height};")
css.append(" max-width: 100%;")
css.append(" padding: var(--if-code-block-padding);")
css.append(" background: var(--if-code-block-bg);")
css.append(" border: var(--if-code-block-border);")
css.append(" border-radius: var(--if-code-block-radius);")
css.append(" white-space: pre;")
if code_block_wrap:
css.append(" white-space: pre-wrap;")
css.append(" overflow-wrap: anywhere;")
else:
css.append(" overflow-x: auto;")
css.append("}")
css.append("")
css.append("table {")
css.append(" border-collapse: collapse;")
css.append(" width: 100%;")
css.append(f" table-layout: {table_layout};")
if table_keep_together:
css.append(" break-inside: avoid;")
css.append(" page-break-inside: avoid;")
css.append("}")
css.append("")
css.append("th, td {")
css.append(f" padding: {table_padding};")
if table_grid_style in {"rules", "rules_minimal"}:
css.append(" border: none;")
if table_grid_style == "rules":
css.append(" border-bottom: 1px solid var(--if-table-rule-color);")
else:
css.append(" border: 1px solid var(--if-table-rule-color);")
css.append(" vertical-align: top;")
if table_cell_wrap:
css.append(" overflow-wrap: anywhere;")
css.append(" word-break: break-word;")
css.append("}")
css.append("")
if table_grid_style in {"rules", "rules_minimal"}:
header_top = "1.5px"
header_bottom = "1.5px"
tail_bottom = "1.5px"
if table_grid_style == "rules_minimal":
header_bottom = "0.5px"
css.append("thead th {")
css.append(f" border-top: {header_top} solid var(--if-table-rule-color);")
css.append(f" border-bottom: {header_bottom} solid var(--if-table-rule-color);")
css.append("}")
css.append("")
css.append("tbody tr:last-child td {")
css.append(f" border-bottom: {tail_bottom} solid var(--if-table-rule-color);")
css.append("}")
css.append("")
css.append(f"th {{ text-align: {table_header_align}; }}")
css.append(f"td {{ text-align: {table_cell_align}; }}")
css.append(f".if-num {{ text-align: {table_numeric_align}; font-variant-numeric: tabular-nums; }}")
css.append(f".if-bool {{ text-align: {table_boolean_align}; }}")
css.append("")
css.append("tbody tr:nth-child(even) {")
css.append(" background: var(--if-table-stripe-bg);")
css.append("}")
css.append("")
if table_row_keep:
css.append("tr, th, td {")
css.append(" break-inside: avoid;")
css.append(" page-break-inside: avoid;")
css.append("}")
css.append("")
if table_header_repeat:
css.append("thead { display: table-header-group; }")
css.append("")
css.append("figure.if-figure {")
css.append(" margin: var(--if-figure-margin);")
css.append(" break-inside: avoid;")
css.append(" page-break-inside: avoid;")
css.append("}")
css.append("")
css.append("figure.if-figure img {")
css.append(" display: block;")
css.append(" max-width: var(--if-figure-max-width);")
css.append(" height: auto;")
css.append("}")
css.append("")
css.append("img {")
css.append(" max-width: 100%;")
css.append(" height: auto;")
css.append("}")
css.append("")
# Approximation: keep headings with at least N following lines by avoiding breaks after heading.
# CSS cannot express "keep_with_next_lines" precisely; this is a pragmatic guard.
if keep_with_next_lines > 0:
css.append("h1, h2, h3 {")
css.append(" page-break-after: avoid;")
css.append("}")
css.append("")
if heading_rule_enabled:
selector = "h1, h2" if heading_rule_position == "under" else "h1, h2"
css.append(f"{selector} {{")
if heading_rule_position == "over":
css.append(f" border-top: {heading_rule_thickness} solid {heading_rule_color};")
css.append(f" padding-top: {heading_rule_spacing};")
else:
css.append(f" border-bottom: {heading_rule_thickness} solid {heading_rule_color};")
css.append(f" padding-bottom: {heading_rule_spacing};")
css.append("}")
css.append("")
if drop_caps_enabled:
selector = (
"main > p:first-of-type::first-letter, "
"h1 + p::first-letter, "
"h2 + p::first-letter, "
"h3 + p::first-letter"
)
css.append(f"{selector} {{")
css.append(" float: left;")
css.append(" line-height: 1;")
css.append(f" font-size: {drop_caps_size};")
css.append(f" padding-right: {drop_caps_padding_right};")
css.append(f" padding-top: {drop_caps_padding_top};")
if drop_caps_weight:
css.append(f" font-weight: {drop_caps_weight};")
css.append("}")
css.append("")
section_overrides = layout.get("section_overrides") or {}
for key, cfg in section_overrides.items():
if not isinstance(cfg, dict):
continue
slug = _slugify(str(key))
if not slug:
continue
selector = f".if-section-{slug}"
content_max_width = cfg.get("content_max_width")
content_margin_left = cfg.get("content_margin_left")
content_margin_right = cfg.get("content_margin_right")
content_padding_left = cfg.get("content_padding_left")
content_padding_right = cfg.get("content_padding_right")
list_max_width = cfg.get("list_max_width")
list_padding_right = cfg.get("list_padding_right")
list_padding_left = cfg.get("list_padding_left")
list_margin_left = cfg.get("list_margin_left")
list_margin_right = cfg.get("list_margin_right")
item_width = cfg.get("list_item_width")
item_max_width = cfg.get("list_item_max_width")
item_padding_right = cfg.get("list_item_padding_right")
item_padding_left = cfg.get("list_item_padding_left")
item_margin_left = cfg.get("list_item_margin_left")
item_margin_right = cfg.get("list_item_margin_right")
if (
content_max_width
or content_margin_left
or content_margin_right
or content_padding_left
or content_padding_right
):
targets = f"{selector} > :not(h2)"
css.append(f"{targets} {{")
if content_max_width:
css.append(f" max-width: {content_max_width};")
if content_margin_left:
css.append(f" margin-left: {content_margin_left};")
if content_margin_right:
css.append(f" margin-right: {content_margin_right};")
if content_padding_left:
css.append(f" padding-left: {content_padding_left};")
if content_padding_right:
css.append(f" padding-right: {content_padding_right};")
css.append("}")
css.append("")
if list_max_width or list_padding_right or list_padding_left or list_margin_left or list_margin_right:
targets = f"{selector} ul, {selector} ol"
css.append(f"{targets} {{")
if list_max_width:
css.append(f" max-width: {list_max_width};")
if list_padding_left:
css.append(f" padding-left: {list_padding_left};")
if list_padding_right:
css.append(f" padding-right: {list_padding_right};")
if list_margin_left:
css.append(f" margin-left: {list_margin_left};")
if list_margin_right:
css.append(f" margin-right: {list_margin_right};")
css.append("}")
css.append("")
if (
item_width
or item_max_width
or item_padding_right
or item_padding_left
or item_margin_left
or item_margin_right
):
targets = f"{selector} li"
css.append(f"{targets} {{")
if item_width:
css.append(f" width: {item_width};")
if item_max_width:
css.append(f" max-width: {item_max_width};")
if item_padding_left:
css.append(f" padding-left: {item_padding_left};")
if item_padding_right:
css.append(f" padding-right: {item_padding_right};")
if item_margin_left:
css.append(f" margin-left: {item_margin_left};")
if item_margin_right:
css.append(f" margin-right: {item_margin_right};")
css.append("}")
css.append("")
report = {
"profile_id": profile_id,
"page": {
"size": page_size,
"orientation": orientation,
"two_sided": two_sided,
"margins": {"top": margin_top, "bottom": margin_bottom, "inner": margin_inner, "outer": margin_outer},
},
"fonts": {
"body": {"family": body_family, "size": body_size, "line_height": body_line_height},
"heading": {"family": heading_family, "size": heading_size},
"mono": {"family": mono_family, "size": mono_size, "line_height": mono_line_height},
},
"colors": {
"body": body_color,
"accent": accent_color,
"heading": heading_color,
"link": link_color,
"citation": citation_color,
"table_rule": table_rule_color,
"table_stripe": table_stripe_bg,
},
"hyphenation": {"enabled": hyphens_enabled},
"widows_orphans": {"widows": widows, "orphans": orphans},
"code": {
"block": {
"font_size": code_block_size,
"line_height": code_block_line_height,
"wrap": code_block_wrap,
"padding": code_block_padding,
"background": code_block_background,
"border": code_block_border,
"radius": code_block_radius,
}
},
"tables": {
"cell_padding": table_padding,
"header_repeat": table_header_repeat,
"layout": table_layout,
"grid_style": table_grid_style,
"keep_together": table_keep_together,
"row_keep_together": table_row_keep,
},
"figures": {"max_width": figure_max_width, "margin": figure_margin},
"typography": {
"small_caps_acronyms": {
"enabled": small_caps_enabled,
"letter_spacing": small_caps_tracking,
},
"drop_caps": {
"enabled": drop_caps_enabled,
"size": drop_caps_size,
"weight": drop_caps_weight or "inherit",
},
},
"lists": {
"hanging_punctuation": {
"enabled": hanging_enabled,
"indent": hanging_indent,
"hang": hanging_hang,
}
},
}
return CssOutput(css="\n".join(css).rstrip() + "\n", report=report)
def _font_stack(family: list[Any]) -> str:
parts: list[str] = []
generic = {
"serif",
"sans-serif",
"monospace",
"cursive",
"fantasy",
"system-ui",
"ui-serif",
"ui-sans-serif",
"ui-monospace",
"ui-rounded",
"math",
"emoji",
"fangsong",
}
for f in family:
s = str(f).strip()
if not s:
continue
if s.lower() in generic:
parts.append(s.lower())
elif any(ch in s for ch in [" ", "-"]):
parts.append(f'"{s}"')
else:
parts.append(s)
return ", ".join(parts) if parts else "serif"
def _slugify(value: str) -> str:
slug = re.sub(r"[^a-z0-9\\s-]", "", value.lower())
slug = re.sub(r"\\s+", "-", slug.strip())
return slug
````
### `iftypeset/src/iftypeset/index_builder.py`
- bytes: `2115`
- sha256: `c743e27087da8479528f95672b626e5b8ee497f532309e51b488d0153b7c35af`
````py
from __future__ import annotations
import json
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from iftypeset.rules import RuleRecord
def _norm_keyword(s: str) -> str:
return " ".join(str(s).strip().lower().split())
@dataclass(frozen=True)
class IndexBundle:
keywords_all: dict[str, list[str]]
source_refs_all: dict[str, list[str]]
category: dict[str, list[str]]
enforcement: dict[str, list[str]]
def build_indexes(rules: list[RuleRecord]) -> IndexBundle:
keywords: dict[str, set[str]] = {}
source_refs: dict[str, set[str]] = {}
by_category: dict[str, set[str]] = {}
by_enforcement: dict[str, set[str]] = {}
for r in rules:
rid = r.id
by_category.setdefault(r.category, set()).add(rid)
by_enforcement.setdefault(r.enforcement, set()).add(rid)
for kw in (r.raw.get("keywords") or []):
k = _norm_keyword(kw)
if not k:
continue
keywords.setdefault(k, set()).add(rid)
for ref in (r.raw.get("source_refs") or []):
ref_s = str(ref).strip()
if not ref_s:
continue
source_refs.setdefault(ref_s, set()).add(rid)
def to_sorted(d: dict[str, set[str]]) -> dict[str, list[str]]:
return {k: sorted(v) for k, v in sorted(d.items(), key=lambda kv: kv[0])}
return IndexBundle(
keywords_all=to_sorted(keywords),
source_refs_all=to_sorted(source_refs),
category=to_sorted(by_category),
enforcement=to_sorted(by_enforcement),
)
def write_indexes(indexes: IndexBundle, indexes_dir: Path) -> None:
indexes_dir.mkdir(parents=True, exist_ok=True)
_write(indexes_dir / "keywords_all.json", indexes.keywords_all)
_write(indexes_dir / "source_refs_all.json", indexes.source_refs_all)
_write(indexes_dir / "category.json", indexes.category)
_write(indexes_dir / "enforcement.json", indexes.enforcement)
def _write(path: Path, data: Any) -> None:
path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
````
### `iftypeset/src/iftypeset/linting.py`
- bytes: `91242`
- sha256: `11970f4842bfe9331ff9979e2930f718ff832b659a7579a308058eedb5f7c75e`
````py
from __future__ import annotations
from dataclasses import asdict, dataclass
from datetime import datetime, timezone
from pathlib import Path
import ipaddress
import re
from typing import Any
from urllib.parse import parse_qs, urlparse
import yaml
from iftypeset import __version__
from iftypeset.md_parser import MdDocument, code_fence_lines, parse_markdown, read_markdown
from iftypeset.spec_loader import LoadedSpec
SEVERITY_ORDER = {"warn": 0, "should": 1, "must": 2}
@dataclass(frozen=True)
class LintDiagnostic:
code: str
message: str
severity: str
path: str
line: int | None = None
column: int | None = None
rule_id: str | None = None
@dataclass(frozen=True)
class LintFix:
code: str
description: str
count: int
mode: str
@dataclass(frozen=True)
class LintResult:
report: dict[str, Any]
fixed_outputs: dict[str, str]
degraded: dict[str, list[str]]
def collect_input_paths(input_path: Path) -> list[Path]:
if input_path.is_dir():
return sorted([p for p in input_path.rglob("*.md") if p.is_file()])
return [input_path]
def lint_paths(
input_paths: list[Path],
profile_id: str,
*,
fix: bool = False,
fix_mode: str = "suggest",
lint_fixed: bool = False,
degraded_ok: bool = False,
fail_on: str = "must",
) -> LintResult:
diagnostics: list[LintDiagnostic] = []
fixes: list[LintFix] = []
fixed_outputs: dict[str, str] = {}
degraded: dict[str, list[str]] = {}
for path in input_paths:
raw_text, read_reasons = read_markdown(path)
doc = parse_markdown(path, raw_text)
reasons = read_reasons + doc.degraded_reasons
if reasons:
degraded[str(path)] = reasons
if fix:
fixed_text, applied = apply_fixes(raw_text, fix_mode=fix_mode)
if applied:
fixes.extend(applied)
fixed_outputs[str(path)] = fixed_text
if fix_mode == "rewrite" and lint_fixed:
doc = parse_markdown(path, fixed_text)
diagnostics.extend(_lint_document(doc))
report = _build_report(
diagnostics=diagnostics,
fixes=fixes,
inputs=input_paths,
profile_id=profile_id,
degraded=degraded,
degraded_ok=degraded_ok,
fail_on=fail_on,
)
return LintResult(report=report, fixed_outputs=fixed_outputs, degraded=degraded)
def manual_checklist(spec: LoadedSpec) -> list[dict[str, Any]]:
items: list[dict[str, Any]] = []
for rule in spec.rules:
tags = [str(t) for t in (rule.raw.get("tags") or [])]
if "manual_checklist=true" not in tags:
continue
items.append(
{
"id": rule.id,
"title": rule.raw.get("title"),
"category": rule.raw.get("category"),
"severity": rule.raw.get("severity"),
"rule_text": rule.raw.get("rule_text"),
"source_refs": rule.raw.get("source_refs"),
}
)
return items
def apply_fixes(text: str, *, fix_mode: str) -> tuple[str, list[LintFix]]:
if fix_mode not in {"suggest", "rewrite"}:
raise ValueError("fix_mode must be suggest or rewrite")
lines = text.splitlines()
fenced = code_fence_lines(text)
new_lines, trailing_count = _strip_trailing_whitespace(lines, fenced)
new_lines, link_count = _normalize_link_spacing(new_lines, fenced)
new_lines, sentence_space_count = _normalize_sentence_spacing(new_lines, fenced)
new_lines, colon_space_count = _normalize_colon_spacing(new_lines, fenced)
new_lines, em_dash_count = _normalize_em_dashes(new_lines, fenced)
new_lines, leading_zero_count = _normalize_leading_zero_decimals(new_lines, fenced)
new_lines, decade_plural_count = _normalize_decade_plurals(new_lines, fenced)
new_lines, link_trailing_punct_count = _normalize_markdown_link_trailing_punct(new_lines, fenced)
new_lines, smart_quotes_count = _normalize_smart_quotes(new_lines, fenced)
fixes: list[LintFix] = []
if trailing_count:
fixes.append(
LintFix(
code="WS.TRAILING",
description="Trim trailing whitespace",
count=trailing_count,
mode=fix_mode,
)
)
if link_count:
fixes.append(
LintFix(
code="LINK.SPACING",
description="Normalize Markdown link spacing",
count=link_count,
mode=fix_mode,
)
)
if sentence_space_count:
fixes.append(
LintFix(
code="TYPO.SENTENCE_SPACE",
description="Normalize sentence spacing to single spaces",
count=sentence_space_count,
mode=fix_mode,
)
)
if colon_space_count:
fixes.append(
LintFix(
code="PUNCT.COLON_SPACE",
description="Normalize spaces after colons",
count=colon_space_count,
mode=fix_mode,
)
)
if em_dash_count:
fixes.append(
LintFix(
code="PUNCT.EM_DASH",
description="Normalize em dash formatting (US style)",
count=em_dash_count,
mode=fix_mode,
)
)
if leading_zero_count:
fixes.append(
LintFix(
code="NUM.LEADING_ZERO",
description="Add leading zero to decimals < 1",
count=leading_zero_count,
mode=fix_mode,
)
)
if decade_plural_count:
fixes.append(
LintFix(
code="NUM.DECADE_PLURAL",
description="Normalize decade plurals (no apostrophe)",
count=decade_plural_count,
mode=fix_mode,
)
)
if link_trailing_punct_count:
fixes.append(
LintFix(
code="LINK.TRAILING_PUNCT",
description="Move trailing punctuation outside Markdown link targets",
count=link_trailing_punct_count,
mode=fix_mode,
)
)
if smart_quotes_count:
fixes.append(
LintFix(
code="PUNCT.SMART_QUOTES",
description="Convert straight quotes to typographic quotes",
count=smart_quotes_count,
mode=fix_mode,
)
)
out_text = "\n".join(new_lines)
if text.endswith("\n"):
out_text += "\n"
if fix_mode == "suggest":
return text, fixes
return out_text, fixes
def _strip_trailing_whitespace(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
stripped = line.rstrip()
if stripped != line:
count += 1
out.append(stripped)
return out, count
def _normalize_link_spacing(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern = re.compile(r"\]\s+\(\s*([^)]+?)\s*\)")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
new_line, n = pattern.subn(r"](\1)", line)
count += n
out.append(new_line)
return out, count
def _lint_document(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
masked_lines: list[str] = []
link_keys: set[str] = set()
file_ignores = _parse_front_matter_ignore(doc.normalized_source)
line_ignores = _collect_line_ignores(doc.normalized_source, fenced)
reference_ranges = _reference_section_ranges(doc.blocks, len(lines))
for idx, line in enumerate(lines, start=1):
if idx in fenced:
masked_lines.append(line)
continue
masked = _mask_inline_code(line)
masked_lines.append(masked)
for _label, url, _start, _end in _iter_markdown_link_spans(masked):
link_keys.add(_canonical_link_key(url))
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
clean_no_links = _strip_markdown_links(clean)
masked = masked_lines[idx - 1]
if line.rstrip() != line:
diagnostics.append(
LintDiagnostic(
code="WS.TRAILING",
message="Trailing whitespace",
severity="warn",
path=str(doc.path),
line=idx,
column=len(line),
)
)
if re.match(r"^\s*(?:[-*+]\s*|\d+\.\s*)$", line):
diagnostics.append(
LintDiagnostic(
code="A11Y.LIST_EMPTY_ITEM",
message="Avoid empty list items",
severity="should",
path=str(doc.path),
line=idx,
column=1,
rule_id="HOUSE.ACCESSIBILITY.LISTS.NO_EMPTY_ITEMS",
)
)
if _has_double_sentence_space(clean):
diagnostics.append(
LintDiagnostic(
code="TYPO.SENTENCE_SPACE",
message="Use a single space between sentences",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="BRING.TYPOGRAPHY.SPACING.SENTENCE_SPACE.SINGLE",
)
)
if _colon_spacing_violation(clean):
diagnostics.append(
LintDiagnostic(
code="PUNCT.COLON_SPACE",
message="Use a single space after a colon in prose",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="CMOS.PUNCTUATION.COLONS.SPACE_AFTER",
)
)
if re.search(r"\s—\s|\s--\s", clean):
diagnostics.append(
LintDiagnostic(
code="PUNCT.EM_DASH",
message="Use em dashes without surrounding spaces (US style)",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="CMOS.PUNCTUATION.DASHES.EM_DASH.USE_WITHOUT_SPACES_US",
)
)
if '"' in clean:
diagnostics.append(
LintDiagnostic(
code="PUNCT.SMART_QUOTES",
message="Use typographic quotation marks (avoid straight double quotes)",
severity="must",
path=str(doc.path),
line=idx,
column=clean.find('"') + 1,
rule_id="CMOS.PUNCTUATION.QUOTES.SMART_QUOTES",
)
)
if "file://" in clean:
diagnostics.append(
LintDiagnostic(
code="LINK.FILE_URI",
message="file:// links are not allowed in published outputs",
severity="must",
path=str(doc.path),
line=idx,
column=clean.find("file://") + 1,
rule_id="HOUSE.LINKS.DISALLOW.FILE_URIS",
)
)
js_match = re.search(r"\bjavascript\s*:", clean, flags=re.IGNORECASE)
if js_match:
diagnostics.append(
LintDiagnostic(
code="LINK.JAVASCRIPT_URI",
message="javascript: links are not allowed",
severity="must",
path=str(doc.path),
line=idx,
column=js_match.start() + 1,
rule_id="HOUSE.LINKS.DISALLOW.JAVASCRIPT_URIS",
)
)
if re.search(r"https?://(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?:\b|/)", clean, flags=re.IGNORECASE):
diagnostics.append(
LintDiagnostic(
code="LINK.LOCALHOST",
message="Do not publish localhost/loopback links",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="HOUSE.LINKS.URLS.DISALLOW.LOCALHOST",
)
)
if _contains_zero_width(clean):
diagnostics.append(
LintDiagnostic(
code="LINK.ZERO_WIDTH",
message="Zero-width characters detected (can break or disguise links)",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="HOUSE.LINKS.URLS.NO_ZERO_WIDTH",
)
)
if re.search(r"(?<![0-9A-Za-z])\.(\d+)", clean):
diagnostics.append(
LintDiagnostic(
code="NUM.LEADING_ZERO",
message="Add leading zero for decimals less than one",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="CMOS.NUMBERS.DECIMALS.LEADING_ZERO",
)
)
if re.search(r"\b\d{4}[’']s\b", clean):
diagnostics.append(
LintDiagnostic(
code="NUM.DECADE_PLURAL",
message="Decade plurals should not use apostrophes",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="CMOS.NUMBERS.PLURALS.DECADE.NO_APOSTROPHE",
)
)
if re.search(r"\b[A-Z]{2,8}[’']s\b", clean):
diagnostics.append(
LintDiagnostic(
code="ABBREV.PLURAL_APOSTROPHE",
message="Plural abbreviations should not use apostrophes",
severity="must",
path=str(doc.path),
line=idx,
column=1,
rule_id="CMOS.ABBREVIATIONS.PLURALS.NO_APOSTROPHE",
)
)
for m in re.finditer(r"\b(\d+)(st|nd|rd|th)\b", clean, flags=re.IGNORECASE):
number = int(m.group(1))
suffix = m.group(2).lower()
expected = _expected_ordinal_suffix(number)
if suffix != expected:
diagnostics.append(
LintDiagnostic(
code="NUM.ORDINAL_SUFFIX",
message=f"Use the correct ordinal suffix ({number}{expected})",
severity="should",
path=str(doc.path),
line=idx,
column=m.start(1) + 1,
rule_id="CMOS.NUMBERS.ORDINALS.SUFFIX.CORRECT",
)
)
todo_match = re.search(r"\b(?:TODO|FIXME)\b", clean, flags=re.IGNORECASE)
if todo_match:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.TODO_FIXME",
message="Remove TODO/FIXME markers before publishing",
severity="must",
path=str(doc.path),
line=idx,
column=todo_match.start() + 1,
rule_id="HOUSE.EDITORIAL.PLACEHOLDERS.NO_TODO_FIXME",
)
)
tbd_match = re.search(r"\b(?:TBD|TKTK)\b", clean, flags=re.IGNORECASE)
if tbd_match:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.TBD_TKTK",
message="Remove TBD/TKTK placeholders before publishing",
severity="must",
path=str(doc.path),
line=idx,
column=tbd_match.start() + 1,
rule_id="HOUSE.EDITORIAL.PLACEHOLDERS.NO_TBD_TKTK",
)
)
lorem_match = re.search(r"lorem\s+ipsum", clean, flags=re.IGNORECASE)
if lorem_match:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.LOREM_IPSUM",
message="Avoid lorem ipsum placeholder text",
severity="should",
path=str(doc.path),
line=idx,
column=lorem_match.start() + 1,
rule_id="HOUSE.EDITORIAL.PLACEHOLDERS.NO_LOREM_IPSUM",
)
)
for m in re.finditer(r"\b10\.\d{4,9}/[^\s\])>]+", clean_no_links, flags=re.IGNORECASE):
prefix = clean_no_links[max(0, m.start() - 20) : m.start()].lower()
if prefix.endswith(("doi.org/", "dx.doi.org/")):
continue
diagnostics.append(
LintDiagnostic(
code="CITATION.DOI_PREFERRED",
message="Prefer canonical doi.org links for DOI references",
severity="should",
path=str(doc.path),
line=idx,
column=m.start() + 1,
rule_id="CMOS.CITATIONS.DOI.PREFERRED_OVER_URL",
)
)
for label, url, col in _iter_markdown_links(clean):
if re.search(r"\s", url):
diagnostics.append(
LintDiagnostic(
code="LINK.URL_WHITESPACE",
message="Whitespace in Markdown link target",
severity="must",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.NO_WHITESPACE",
)
)
if re.match(r"https?://", url, flags=re.IGNORECASE) and url.endswith((".", ",", ";", ":")):
diagnostics.append(
LintDiagnostic(
code="LINK.TRAILING_PUNCT",
message="Trailing punctuation should not be inside link URLs",
severity="must",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.PUNCTUATION.NO_TRAILING_PUNCT",
)
)
if re.match(r"http://", url, flags=re.IGNORECASE):
diagnostics.append(
LintDiagnostic(
code="LINK.PREFER_HTTPS",
message="Prefer HTTPS URLs when available",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.PREFER_HTTPS",
)
)
if "\\" in url:
diagnostics.append(
LintDiagnostic(
code="LINK.URL_BACKSLASH",
message="Avoid backslashes in URLs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.NO_BACKSLASH",
)
)
if url.lower().startswith("ftp://"):
diagnostics.append(
LintDiagnostic(
code="LINK.FTP",
message="Avoid ftp: links in published docs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.FTP.AVOID",
)
)
if _url_has_embedded_credentials(url):
diagnostics.append(
LintDiagnostic(
code="LINK.CREDENTIALS",
message="Do not embed credentials in URLs",
severity="must",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.EMBEDDED_CREDENTIALS.AVOID",
)
)
if url.startswith("//"):
diagnostics.append(
LintDiagnostic(
code="LINK.PROTOCOL_RELATIVE",
message="Avoid protocol-relative URLs; use explicit https://",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.NO_PROTOCOL_RELATIVE",
)
)
if re.search(r"dx\.doi\.org/", url, flags=re.IGNORECASE) or url.lower().startswith("http://doi.org/"):
diagnostics.append(
LintDiagnostic(
code="LINK.DOI_CANONICAL",
message="Prefer canonical https://doi.org/ DOI links",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.DOIS.PREFER_DOI_ORG",
)
)
if _has_text_fragment(url):
diagnostics.append(
LintDiagnostic(
code="LINK.TEXT_FRAGMENT",
message="Avoid text-fragment URLs in published links",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.AVOID.TEXT_FRAGMENTS",
)
)
if _url_has_signed_params(url):
diagnostics.append(
LintDiagnostic(
code="LINK.EXPIRING_SIGNED",
message="Avoid expiring signed URLs in published docs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.AVOID.EXPIRING_SIGNED",
)
)
if _url_has_tracking_params(url):
diagnostics.append(
LintDiagnostic(
code="LINK.TRACKING_PARAMS",
message="Avoid tracking parameters in published URLs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.TRACKING_PARAMS.AVOID",
)
)
if _url_has_session_params(url):
diagnostics.append(
LintDiagnostic(
code="LINK.SESSION_PARAMS",
message="Avoid session or token parameters in published URLs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.SESSION_PARAMS.AVOID",
)
)
host = _extract_url_host(url)
if host and host in _SHORTENER_HOSTS:
diagnostics.append(
LintDiagnostic(
code="LINK.SHORTENER",
message="Avoid opaque link shorteners in published docs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.ACCESSIBILITY.LINKS.AVOID_SHORTENERS",
)
)
if host and _host_looks_staging(host):
diagnostics.append(
LintDiagnostic(
code="LINK.STAGING_HOST",
message="Avoid staging or test hostnames in published docs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.STAGING_HOSTNAMES.AVOID",
)
)
if host and _host_looks_internal(host):
diagnostics.append(
LintDiagnostic(
code="LINK.INTERNAL_HOST",
message="Avoid internal-only hostnames in published docs",
severity="must",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.INTERNAL_HOSTNAMES.AVOID",
)
)
if host and _is_ip_literal(host) and host not in {"127.0.0.1", "0.0.0.0", "localhost"}:
diagnostics.append(
LintDiagnostic(
code="LINK.IP_LITERAL",
message="Avoid literal IP addresses in published links",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.URLS.AVOID.IP_LITERALS",
)
)
if host and _is_private_ip_literal(host):
diagnostics.append(
LintDiagnostic(
code="LINK.PRIVATE_IP",
message="Avoid private IP addresses in published links",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.PRIVATE_IPS.AVOID",
)
)
if _url_looks_invite(url):
diagnostics.append(
LintDiagnostic(
code="LINK.INVITE",
message="Avoid one-time or invite-only links in published docs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.INVITE_LINKS.AVOID",
)
)
if _url_looks_password_reset(url):
diagnostics.append(
LintDiagnostic(
code="LINK.PASSWORD_RESET",
message="Do not publish password reset or recovery links",
severity="must",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.PASSWORD_RESET.AVOID",
)
)
if _url_looks_login(url):
diagnostics.append(
LintDiagnostic(
code="LINK.LOGIN",
message="Avoid publishing login links in public docs",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.LINKS.AUTO.LOGIN_LINKS.AVOID",
)
)
if _is_low_information_link_text(label):
diagnostics.append(
LintDiagnostic(
code="LINK.TEXT_DESCRIPTIVE",
message="Link text should be descriptive",
severity="should",
path=str(doc.path),
line=idx,
column=1,
rule_id="HOUSE.LINKS.TEXT.DESCRIPTIVE",
)
)
for label, url, start, end in _iter_markdown_link_spans(masked):
if start > 0 and masked[start - 1] == "!":
continue
if (
(start > 0 and _is_word_char(masked[start - 1]))
or (end < len(masked) and _is_word_char(masked[end]))
):
diagnostics.append(
LintDiagnostic(
code="LINK.PARTIAL_WORD",
message="Avoid linking only part of a word",
severity="should",
path=str(doc.path),
line=idx,
column=start + 1,
rule_id="HOUSE.LINKS.AUTO.PARTIAL_WORD.AVOID",
)
)
ext = _extract_download_extension(url)
if ext and not _label_mentions_filetype(label, ext):
diagnostics.append(
LintDiagnostic(
code="LINK.FILETYPE_LABEL",
message="Label downloadable file types in the link text",
severity="should",
path=str(doc.path),
line=idx,
column=start + 1,
rule_id="HOUSE.LINKS.AUTO.FILETYPE_LABEL.REQUIRED",
)
)
if _label_is_overlong(label):
diagnostics.append(
LintDiagnostic(
code="LINK.LABEL_OVERLONG",
message="Avoid overly long link labels in running text",
severity="should",
path=str(doc.path),
line=idx,
column=start + 1,
rule_id="HOUSE.LINKS.AUTO.LABEL_LENGTH.AVOID_OVERLONG",
)
)
if ext and not _has_html_fallback(url, link_keys):
diagnostics.append(
LintDiagnostic(
code="LINK.HTML_FALLBACK",
message="Provide an HTML view fallback for download links when available",
severity="should",
path=str(doc.path),
line=idx,
column=start + 1,
rule_id="HOUSE.LINKS.AUTO.HTML_FALLBACK.REQUIRED",
)
)
for alt, _url, col in _iter_markdown_images(clean):
if not alt.strip():
diagnostics.append(
LintDiagnostic(
code="A11Y.IMG_ALT",
message="Image alt text is required (or explicit empty alt only for decorative images)",
severity="must",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.A11Y.IMAGES.ALT_REQUIRED",
)
)
elif _alt_text_looks_like_filename(alt):
diagnostics.append(
LintDiagnostic(
code="A11Y.IMG_ALT_QUALITY",
message="Alt text should describe content, not a filename or generic label",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.ACCESSIBILITY.IMAGES.ALT_TEXT.QUALITY.NO_FILENAME",
)
)
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
in_reference_section = _line_in_ranges(idx, reference_ranges)
for match in re.finditer(r"(https?://\S+|www\.\S+)", clean):
token = match.group(1)
if _long_unbroken(token, 80) and not in_reference_section:
diagnostics.append(
LintDiagnostic(
code="LINK.WRAP.RISK",
message="Very long unbroken URL may wrap poorly",
severity="warn",
path=str(doc.path),
line=idx,
column=match.start(1) + 1,
)
)
if _looks_like_bare_url(token) and "](" not in clean and not in_reference_section:
diagnostics.append(
LintDiagnostic(
code="LINK.BARE_URL",
message="Avoid naked URLs in prose when a labeled link will do",
severity="should",
path=str(doc.path),
line=idx,
column=match.start(1) + 1,
rule_id="HOUSE.LINKS.URLS.AVOID.NAKED_URLS_IN_PROSE",
)
)
break
link_spacing = re.compile(r"\]\s+\(\s*([^)]+?)\s*\)")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
if link_spacing.search(line):
diagnostics.append(
LintDiagnostic(
code="LINK.SPACING",
message="Normalize spacing inside Markdown links",
severity="warn",
path=str(doc.path),
line=idx,
column=1,
)
)
break
for block in doc.blocks:
if block.type == "heading" and block.level:
if block.level > 1 and not _prior_heading_level(doc, block.level, block.start_line):
diagnostics.append(
LintDiagnostic(
code="A11Y.HEADINGS.NO_SKIPS",
message="Heading level skips a level",
severity="must",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.A11Y.HEADINGS.NO_SKIPS",
)
)
stripped = block.text.rstrip()
if stripped.endswith((".", ":", ";")):
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.HEADING_TRAILING_PUNCT",
message="Avoid trailing punctuation in headings",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.EDITORIAL.HEADINGS.NO_TRAILING_PUNCTUATION",
)
)
heading_text = _strip_markdown_links(_strip_inline_code(block.text))
if _is_effectively_empty_text(heading_text):
diagnostics.append(
LintDiagnostic(
code="A11Y.HEADING_EMPTY",
message="Avoid empty or decorative headings",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.ACCESSIBILITY.HEADINGS.NO_EMPTY",
)
)
if _is_all_caps_heading(heading_text):
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.HEADING_ALL_CAPS",
message="Avoid all caps headings in prose documents",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.EDITORIAL.HEADINGS.AVOID_ALL_CAPS",
)
)
if block.type == "table":
if not any(h for h in block.headers):
diagnostics.append(
LintDiagnostic(
code="TABLE.HEADER.MISSING",
message="Table header row is empty",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.ACCESSIBILITY.TABLES.HEADER_ROW.REQUIRED",
)
)
if block.type == "blockquote":
if block.text.lstrip().startswith(("\"", "“", "”")):
diagnostics.append(
LintDiagnostic(
code="PUNCT.BLOCKQUOTE.NO_QUOTES",
message="Block quotes should omit surrounding quotation marks",
severity="must",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="CMOS.PUNCTUATION.BLOCK_QUOTES.NO_QUOTE_MARKS",
)
)
if block.type in {"paragraph", "heading", "blockquote"}:
if _unbalanced_delimiters(_strip_markdown_links(_strip_inline_code(block.text))):
diagnostics.append(
LintDiagnostic(
code="PUNCT.BALANCE",
message="Parentheses/brackets appear unbalanced",
severity="must",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE",
)
)
if block.type == "list":
if len(block.items) == 1:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.LIST_SINGLE_ITEM",
message="Avoid single-item lists",
severity="warn",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.EDITORIAL.LISTS.AVOID_SINGLE_ITEM",
)
)
h1s = [b for b in doc.blocks if b.type == "heading" and b.level == 1]
if not h1s:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.TITLE.MISSING",
message="Include an H1 title",
severity="should",
path=str(doc.path),
line=1,
column=1,
rule_id="HOUSE.EDITORIAL.STRUCTURE.H1_TITLE.PRESENT",
)
)
if len(h1s) > 1:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.TITLE.MULTIPLE",
message="Avoid multiple H1 titles",
severity="should",
path=str(doc.path),
line=h1s[1].start_line,
column=1,
rule_id="HOUSE.EDITORIAL.STRUCTURE.H1_TITLE.SINGLE",
)
)
if h1s:
first_idx = next((i for i, b in enumerate(doc.blocks) if b.type == "heading" and b.level == 1), 0)
if first_idx > 2:
diagnostics.append(
LintDiagnostic(
code="EDITORIAL.TITLE.LATE",
message="Place the title near the top",
severity="should",
path=str(doc.path),
line=h1s[0].start_line,
column=1,
rule_id="HOUSE.EDITORIAL.STRUCTURE.H1_TITLE.EARLY",
)
)
diagnostics.extend(_lint_layout_spacing(doc))
diagnostics.extend(_lint_empty_sections(doc))
diagnostics.extend(_lint_emphasis_spans(doc))
diagnostics.extend(_lint_accessibility_links(doc))
diagnostics.extend(_lint_footnote_marker_sequence(doc))
diagnostics.extend(_lint_citations_bracketed_numbers(doc))
diagnostics.extend(_lint_citations_heading_note_markers(doc))
diagnostics.extend(_lint_citations_ibid(doc))
diagnostics.extend(_lint_citations_notes_bibliography_required(doc))
diagnostics.extend(_lint_code_blocks(doc))
diagnostics.extend(_lint_acronyms(doc))
diagnostics.extend(_lint_citations_author_date(doc))
diagnostics.extend(_lint_i18n_consistency(doc))
if file_ignores or line_ignores:
diagnostics = [
d
for d in diagnostics
if not _should_ignore_diagnostic(d, file_ignores, line_ignores)
]
return diagnostics
def _prior_heading_level(doc: MdDocument, level: int, line_no: int) -> bool:
for block in doc.blocks:
if block.type != "heading" or block.level is None:
continue
if block.start_line >= line_no:
break
if block.level == level - 1:
return True
return level == 1
def _is_all_caps_heading(text: str) -> bool:
clean = re.sub(r"[\s\u00a0]+", " ", text.strip())
if not clean:
return False
letters = [ch for ch in clean if ch.isalpha()]
if len(letters) < 4:
return False
if any(ch.islower() for ch in letters):
return False
words = [w for w in re.split(r"\s+", clean) if w]
if len(words) == 1 and len(letters) <= 6:
return False
return True
def _is_effectively_empty_text(text: str) -> bool:
return not bool(re.search(r"[A-Za-z0-9]", text))
def _long_unbroken(text: str, threshold: int) -> bool:
for token in re.findall(r"\S+", text):
if len(token) >= threshold:
return True
return False
def _split_inline_code(text: str) -> list[tuple[bool, str]]:
parts: list[tuple[bool, str]] = []
buf: list[str] = []
in_code = False
delimiter = ""
i = 0
while i < len(text):
if not in_code and text[i] == "`":
j = i
while j < len(text) and text[j] == "`":
j += 1
if buf:
parts.append((False, "".join(buf)))
buf.clear()
delimiter = text[i:j]
buf.append(delimiter)
in_code = True
i = j
continue
if in_code and delimiter and text.startswith(delimiter, i):
buf.append(delimiter)
parts.append((True, "".join(buf)))
buf.clear()
in_code = False
i += len(delimiter)
delimiter = ""
continue
buf.append(text[i])
i += 1
if buf:
parts.append((in_code, "".join(buf)))
return parts
def _strip_inline_code(text: str) -> str:
return "".join(seg for is_code, seg in _split_inline_code(text) if not is_code)
def _strip_markdown_links(text: str) -> str:
return re.sub(r"\[[^\]]*\]\([^)]+\)", " ", text)
def _has_double_sentence_space(text: str) -> bool:
return bool(re.search(r"[.!?][\]\)\"']? {2,}", text))
def _unbalanced_delimiters(text: str) -> bool:
stack: list[str] = []
pairs = {")": "(", "]": "["}
for idx, ch in enumerate(text):
if ch in "([":
stack.append(ch)
elif ch in ")]":
if ch == ")" and not stack and _looks_like_enumeration_close(text, idx):
continue
if not stack or stack[-1] != pairs[ch]:
return True
stack.pop()
return bool(stack)
def _looks_like_enumeration_close(text: str, idx: int) -> bool:
if idx <= 0 or text[idx] != ")":
return False
j = idx - 1
while j >= 0 and text[j].isalnum():
j -= 1
token = text[j + 1 : idx]
if not token:
return False
if not (token.isdigit() or (len(token) == 1 and token.isalpha())):
return False
if j >= 0 and not text[j].isspace():
return False
if idx + 1 < len(text) and not text[idx + 1].isspace():
return False
return True
def _contains_zero_width(text: str) -> bool:
return any(ch in text for ch in ("\u200b", "\u200c", "\u200d", "\ufeff"))
def _expected_ordinal_suffix(number: int) -> str:
if 10 <= (number % 100) <= 20:
return "th"
last = number % 10
if last == 1:
return "st"
if last == 2:
return "nd"
if last == 3:
return "rd"
return "th"
def _colon_spacing_violation(text: str) -> bool:
# Space-after-colon rule (skip URLs, time, ratios).
if "://" in text:
return False
if re.search(r": {2,}", text):
return True
return bool(re.search(r":(?!\s)(?=[A-Za-z])", text))
def _iter_markdown_links(line: str) -> list[tuple[str, str, int]]:
out: list[tuple[str, str, int]] = []
for m in re.finditer(r"\[([^\]]+)\]\(([^)]+)\)", line):
label = m.group(1)
url = m.group(2).strip()
out.append((label, url, m.start(2) + 1))
return out
def _iter_markdown_link_spans(line: str) -> list[tuple[str, str, int, int]]:
out: list[tuple[str, str, int, int]] = []
for m in re.finditer(r"\[([^\]]+)\]\(([^)]+)\)", line):
label = m.group(1)
url = m.group(2).strip()
out.append((label, url, m.start(), m.end()))
return out
def _mask_inline_code(text: str) -> str:
parts = _split_inline_code(text)
masked: list[str] = []
for is_code, seg in parts:
if is_code:
masked.append(" " * len(seg))
else:
masked.append(seg)
return "".join(masked)
def _normalize_ignore_list(value: Any) -> set[str]:
if value is None:
return set()
if isinstance(value, str):
return {v for v in re.split(r"[,\s]+", value) if v}
if isinstance(value, list):
out: set[str] = set()
for item in value:
if isinstance(item, str):
out.update({v for v in re.split(r"[,\s]+", item) if v})
return out
return set()
def _parse_front_matter_ignore(text: str) -> set[str]:
lines = text.splitlines()
if not lines or lines[0].strip() != "---":
return set()
end_idx = None
for i in range(1, min(len(lines), 200)):
if lines[i].strip() in {"---", "..."}:
end_idx = i
break
if end_idx is None:
return set()
raw = "\n".join(lines[1:end_idx])
try:
data = yaml.safe_load(raw) or {}
except yaml.YAMLError:
return set()
if not isinstance(data, dict):
return set()
ignores: set[str] = set()
ignores |= _normalize_ignore_list(data.get("iftypeset_ignore"))
if isinstance(data.get("iftypeset"), dict):
ignores |= _normalize_ignore_list(data["iftypeset"].get("ignore"))
return ignores
def _collect_line_ignores(text: str, fenced: set[int]) -> dict[int, set[str]]:
lines = text.splitlines()
ignores_by_line: dict[int, set[str]] = {}
pending: set[str] = set()
directive = re.compile(r"<!--\s*iftypeset:ignore\s+(.+?)\s*-->")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
match = directive.search(line)
if match:
tokens = _normalize_ignore_list(match.group(1))
if tokens:
ignores_by_line.setdefault(idx, set()).update(tokens)
remainder = directive.sub("", line).strip()
if remainder:
continue
pending |= tokens
continue
if pending and line.strip():
ignores_by_line.setdefault(idx, set()).update(pending)
pending = set()
return ignores_by_line
def _should_ignore_diagnostic(
diag: LintDiagnostic, file_ignores: set[str], line_ignores: dict[int, set[str]]
) -> bool:
candidates: set[str] = set()
if diag.rule_id:
candidates.add(diag.rule_id)
if diag.code:
candidates.add(diag.code)
if not candidates:
return False
if candidates & file_ignores:
return True
if diag.line is None:
return False
if candidates & line_ignores.get(diag.line, set()):
return True
return False
def _reference_section_ranges(blocks: list[MdBlock], total_lines: int) -> list[tuple[int, int]]:
headings = [b for b in blocks if b.type == "heading" and b.start_line]
headings.sort(key=lambda b: b.start_line)
ranges: list[tuple[int, int]] = []
for i, heading in enumerate(headings):
end_line = total_lines
if i + 1 < len(headings):
end_line = headings[i + 1].start_line - 1
if _is_reference_heading(heading.text):
ranges.append((heading.start_line, end_line))
return ranges
def _is_reference_heading(text: str) -> bool:
cleaned = re.sub(r"[^a-z0-9]+", " ", text.lower())
tokens = cleaned.split()
keywords = {
"references",
"reference",
"bibliography",
"sources",
"source",
"links",
"resources",
"appendix",
"appendices",
"data",
"datasets",
"citations",
}
return any(token in keywords for token in tokens)
def _line_in_ranges(line_no: int, ranges: list[tuple[int, int]]) -> bool:
for start, end in ranges:
if start <= line_no <= end:
return True
return False
def _iter_markdown_images(line: str) -> list[tuple[str, str, int]]:
out: list[tuple[str, str, int]] = []
for m in re.finditer(r"!\[([^\]]*)\]\(([^)]+)\)", line):
alt = m.group(1)
url = m.group(2).strip()
out.append((alt, url, m.start(2) + 1))
return out
_SHORTENER_HOSTS = {
"bit.ly",
"buff.ly",
"goo.gl",
"is.gd",
"lnkd.in",
"ow.ly",
"rb.gy",
"rebrand.ly",
"t.co",
"tiny.cc",
"tinyurl.com",
}
_FILETYPE_LABELS: dict[str, set[str]] = {
".tar.gz": {"tar.gz", "tar", "tgz", "archive"},
".tgz": {"tgz", "tar.gz", "archive"},
".tar": {"tar", "archive"},
".zip": {"zip", "archive"},
".gz": {"gz", "gzip", "archive"},
".pdf": {"pdf"},
".csv": {"csv"},
".tsv": {"tsv"},
".xlsx": {"xlsx", "excel"},
".xls": {"xls", "excel"},
".docx": {"docx", "word"},
".doc": {"doc", "word"},
".pptx": {"pptx", "powerpoint"},
".ppt": {"ppt", "powerpoint"},
".md": {"md", "markdown"},
".json": {"json"},
".py": {"py", "python"},
}
_HTML_FALLBACK_EXTS = {".md", ".tar.gz", ".tgz", ".zip", ".gz", ".py"}
_LINK_LABEL_MAX_CHARS = 80
_LINK_LABEL_MAX_WORDS = 12
_STAGING_TOKENS = {"staging", "stage", "dev", "test", "qa", "sandbox", "preview"}
_INTERNAL_TLDS = {".local", ".internal", ".intranet", ".corp", ".lan", ".home", ".private"}
_TRACKING_PARAMS = {
"utm_source",
"utm_medium",
"utm_campaign",
"utm_term",
"utm_content",
"ref",
"referrer",
"source",
"fbclid",
"gclid",
"mc_cid",
"mc_eid",
}
_SESSION_PARAMS = {"session", "sessionid", "sid", "phpsessid", "jsessionid", "token", "auth", "access_token"}
_INVITE_PATH_TOKENS = {"invite", "invitation", "join", "signup", "register"}
_INVITE_PARAMS = {"invite", "invitation", "invite_code", "join", "signup", "register", "code"}
_TOKEN_PARAMS = {"token", "code", "key", "auth", "access_token"}
_PASSWORD_RESET_TOKENS = {"reset", "forgot", "recover", "password"}
_LOGIN_TOKENS = {"login", "signin", "sign-in", "auth", "session"}
def _normalize_url_for_parse(url: str) -> str:
if url.startswith("//"):
return f"https:{url}"
if url.startswith("www."):
return f"https://{url}"
return url
def _parse_url(url: str):
try:
return urlparse(_normalize_url_for_parse(url))
except ValueError:
return None
def _url_has_tracking_params(url: str) -> bool:
parsed = _parse_url(url)
if not parsed or not parsed.query:
return False
keys = {k.lower() for k in parse_qs(parsed.query, keep_blank_values=True)}
return any(k.startswith("utm_") or k in _TRACKING_PARAMS for k in keys)
def _url_has_session_params(url: str) -> bool:
parsed = _parse_url(url)
if not parsed or not parsed.query:
return False
keys = {k.lower() for k in parse_qs(parsed.query, keep_blank_values=True)}
return bool(keys & _SESSION_PARAMS)
def _url_has_embedded_credentials(url: str) -> bool:
parsed = _parse_url(url)
if not parsed:
return False
return bool(parsed.username or parsed.password)
def _host_looks_staging(host: str | None) -> bool:
if not host:
return False
parts = host.split(".")
for part in parts:
if part in _STAGING_TOKENS:
return True
for token in _STAGING_TOKENS:
if part.startswith(token) or part.endswith(token):
return True
return False
def _host_looks_internal(host: str | None) -> bool:
if not host:
return False
if any(host.endswith(tld) for tld in _INTERNAL_TLDS):
return True
parts = host.split(".")
return any(part in {"internal", "intranet", "corp", "lan", "local"} for part in parts)
def _is_private_ip_literal(host: str | None) -> bool:
if not host:
return False
try:
ip = ipaddress.ip_address(host)
except ValueError:
return False
return ip.is_private
def _url_looks_invite(url: str) -> bool:
parsed = _parse_url(url)
if not parsed:
return False
path = (parsed.path or "").lower()
has_invite_path = any(token in path for token in _INVITE_PATH_TOKENS)
keys = {k.lower() for k in parse_qs(parsed.query, keep_blank_values=True)}
has_invite_key = bool(keys & _INVITE_PARAMS)
has_token = bool(keys & _TOKEN_PARAMS)
return (has_invite_path or has_invite_key) and (has_token or has_invite_key)
def _url_looks_password_reset(url: str) -> bool:
parsed = _parse_url(url)
if not parsed:
return False
path = (parsed.path or "").lower()
if any(token in path for token in _PASSWORD_RESET_TOKENS):
return True
keys = {k.lower() for k in parse_qs(parsed.query, keep_blank_values=True)}
return bool(keys & {"reset", "password", "recover", "forgot"})
def _url_looks_login(url: str) -> bool:
parsed = _parse_url(url)
if not parsed:
return False
path = (parsed.path or "").lower()
if any(token in path for token in _LOGIN_TOKENS):
return True
keys = {k.lower() for k in parse_qs(parsed.query, keep_blank_values=True)}
return bool(keys & {"login", "signin", "auth"})
def _extract_url_host(url: str) -> str | None:
try:
parsed = urlparse(_normalize_url_for_parse(url))
except ValueError:
return None
host = parsed.netloc
if not host:
return None
host = host.split("@")[-1]
if host.startswith("["):
host = host.split("]")[0].lstrip("[")
elif ":" in host:
host = host.split(":", 1)[0]
return host.lower()
def _is_ipv4_literal(host: str) -> bool:
if not re.match(r"^(?:\d{1,3}\.){3}\d{1,3}$", host):
return False
return all(0 <= int(part) <= 255 for part in host.split("."))
def _is_ip_literal(host: str) -> bool:
if _is_ipv4_literal(host):
return True
return ":" in host
def _url_has_signed_params(url: str) -> bool:
parsed = urlparse(_normalize_url_for_parse(url))
if not parsed.query:
return False
keys = {k.lower() for k in parse_qs(parsed.query, keep_blank_values=True)}
if {"x-amz-signature", "x-amz-credential", "x-amz-expires"} & keys:
return True
if {"x-goog-signature", "x-goog-credential", "x-goog-expires"} & keys:
return True
if {"x-ms-signature", "x-ms-expires", "x-ms-date"} & keys:
return True
if "signature" in keys and "expires" in keys:
return True
return False
def _has_text_fragment(url: str) -> bool:
return "#:~:text=" in url
def _extract_download_extension(url: str) -> str | None:
parsed = _parse_url(url)
path = parsed.path if parsed else url
lower_path = path.lower()
for ext in sorted(_FILETYPE_LABELS.keys(), key=len, reverse=True):
if lower_path.endswith(ext):
return ext
return None
def _label_mentions_filetype(label: str, ext: str) -> bool:
tokens = _FILETYPE_LABELS.get(ext, set())
if not tokens:
return True
label_lower = label.lower()
if any(token in label_lower for token in tokens):
return True
label_compact = re.sub(r"[^a-z0-9]+", "", label_lower)
for token in tokens:
token_compact = re.sub(r"[^a-z0-9]+", "", token)
if token_compact and token_compact in label_compact:
return True
return False
def _label_is_overlong(label: str) -> bool:
if len(label) >= _LINK_LABEL_MAX_CHARS:
return True
words = re.findall(r"[A-Za-z0-9]+", label)
return len(words) >= _LINK_LABEL_MAX_WORDS
def _canonical_link_key(url: str) -> str:
parsed = _parse_url(url)
if not parsed:
return url.strip().lower()
path = parsed.path or ""
if parsed.scheme and parsed.netloc:
return f"{parsed.scheme.lower()}://{parsed.netloc.lower()}{path}".rstrip("/")
return path.lower().rstrip("/")
def _possible_html_fallback_keys(url: str) -> set[str]:
parsed = _parse_url(url)
path = parsed.path if parsed else url
ext = _extract_download_extension(url)
if not ext or ext not in _HTML_FALLBACK_EXTS:
return set()
base = path[: -len(ext)]
prefix = ""
if parsed and parsed.scheme and parsed.netloc:
prefix = f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
candidates = {
f"{prefix}{base}",
f"{prefix}{base}/",
f"{prefix}{base}.html",
f"{prefix}{base}/index.html",
}
return {_canonical_link_key(c) for c in candidates if c}
def _has_html_fallback(url: str, link_keys: set[str]) -> bool:
candidates = _possible_html_fallback_keys(url)
if not candidates:
return True
return bool(candidates & link_keys)
def _is_word_char(ch: str) -> bool:
return bool(re.match(r"[A-Za-z0-9_]", ch))
def _is_low_information_link_text(label: str) -> bool:
s = " ".join(label.strip().lower().split())
if not s:
return True
if s in {"click here", "here", "this", "link", "more", "read more"}:
return True
if s.startswith("http://") or s.startswith("https://") or s.startswith("www."):
return True
return False
def _is_symbol_only_text(label: str) -> bool:
s = label.strip()
if not s:
return True
return not bool(re.search(r"[A-Za-z0-9]", s))
def _normalize_label(label: str) -> str:
return " ".join(label.strip().lower().split())
def _looks_like_bare_url(token: str) -> bool:
return token.startswith("http://") or token.startswith("https://") or token.startswith("www.")
def _alt_text_looks_like_filename(alt: str) -> bool:
s = alt.strip().lower()
if not s:
return False
if s in {"image", "photo", "screenshot", "figure"}:
return True
return bool(re.search(r"\b[\w.-]+\.(png|jpe?g|gif|svg|webp|pdf)\b", s))
def _lint_footnote_marker_sequence(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
text = doc.normalized_source
fenced = code_fence_lines(text)
refs: list[tuple[int, int]] = []
defs: set[int] = set()
for idx, line in enumerate(text.splitlines(), start=1):
if idx in fenced:
continue
for m in re.finditer(r"\[\^(\d+)\]", line):
refs.append((idx, int(m.group(1))))
mdef = re.match(r"^\[\^(\d+)\]:\s+", line.strip())
if mdef:
defs.add(int(mdef.group(1)))
if not refs:
return diagnostics
seen_numbers: list[int] = [n for _, n in refs]
counts: dict[int, int] = {}
for n in seen_numbers:
counts[n] = counts.get(n, 0) + 1
dupes = sorted(n for n, c in counts.items() if c > 1)
expected = list(range(1, max(seen_numbers) + 1))
if sorted(set(seen_numbers)) != expected or seen_numbers != sorted(seen_numbers):
diagnostics.append(
LintDiagnostic(
code="CITATION.NOTE_SEQUENCE",
message="Footnote markers should be continuous and ordered",
severity="must",
path=str(doc.path),
line=refs[0][0],
column=1,
rule_id="CMOS.CITATIONS.NOTES.NOTE_MARKERS.SEQUENCE_CONTINUOUS",
)
)
if dupes:
diagnostics.append(
LintDiagnostic(
code="CITATION.NOTE_DUPLICATE",
message=f"Duplicate footnote markers found: {', '.join(str(n) for n in dupes)}",
severity="must",
path=str(doc.path),
line=refs[0][0],
column=1,
rule_id="CMOS.CITATIONS.NOTES.NOTE_MARKERS.SEQUENCE_CONTINUOUS",
)
)
missing_defs = [n for n in set(seen_numbers) if n not in defs]
if missing_defs:
diagnostics.append(
LintDiagnostic(
code="CITATION.NOTE_DEFINITION",
message=f"Missing footnote definitions for: {', '.join(str(n) for n in sorted(missing_defs))}",
severity="should",
path=str(doc.path),
line=refs[0][0],
column=1,
rule_id="HOUSE.CITATIONS.NOTES.DEFINITIONS.REQUIRED",
)
)
for idx, line in enumerate(text.splitlines(), start=1):
if idx in fenced:
continue
if re.match(r"^\[\^\d+\]:\s+", line.strip()):
continue
for m in re.finditer(r"\[\^\d+\][,.;:!?]", line):
diagnostics.append(
LintDiagnostic(
code="CITATION.NOTE_PLACEMENT",
message="Place note markers after related punctuation",
severity="should",
path=str(doc.path),
line=idx,
column=m.start() + 1,
rule_id="CMOS.CITATIONS.NOTES.NOTE_MARKERS.PLACEMENT_AFTER_PUNCT",
)
)
break
return diagnostics
def _lint_layout_spacing(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
blank_run = 0
run_start: int | None = None
for idx, line in enumerate(lines, start=1):
if idx in fenced:
blank_run = 0
run_start = None
continue
if not line.strip():
if blank_run == 0:
run_start = idx
blank_run += 1
continue
if blank_run >= 2 and run_start is not None:
diagnostics.append(
LintDiagnostic(
code="LAYOUT.EXTRA_BLANK_LINES",
message="Avoid extra blank lines between paragraphs unless a section break is intended",
severity="warn",
path=str(doc.path),
line=run_start,
column=1,
rule_id="HOUSE.LAYOUT.MD.BLANK_LINES.SPARING",
)
)
blank_run = 0
run_start = None
if blank_run >= 2 and run_start is not None:
diagnostics.append(
LintDiagnostic(
code="LAYOUT.EXTRA_BLANK_LINES",
message="Avoid extra blank lines between paragraphs unless a section break is intended",
severity="warn",
path=str(doc.path),
line=run_start,
column=1,
rule_id="HOUSE.LAYOUT.MD.BLANK_LINES.SPARING",
)
)
return diagnostics
def _lint_empty_sections(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
blocks = doc.blocks
for i, block in enumerate(blocks):
if block.type != "heading":
continue
has_content = False
for nxt in blocks[i + 1 :]:
if nxt.type == "heading":
break
if nxt.type in {"paragraph", "list", "code", "table", "blockquote"}:
if nxt.type == "paragraph" and not nxt.text.strip():
continue
has_content = True
break
if not has_content:
diagnostics.append(
LintDiagnostic(
code="LAYOUT.EMPTY_SECTION",
message="Headings should be followed by content, not another heading or EOF",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.LAYOUT.MD.HEADINGS.NON_EMPTY_SECTIONS",
)
)
return diagnostics
def _span_overlaps(existing: list[tuple[int, int]], start: int, end: int) -> bool:
for s, e in existing:
if start < e and end > s:
return True
return False
def _collect_emphasis_spans(text: str) -> list[tuple[str, str, int]]:
spans: list[tuple[str, str, int]] = []
used: list[tuple[int, int]] = []
patterns = [
("bold_italic", r"\*\*\*([^*]+)\*\*\*"),
("bold_italic", r"___([^_]+)___"),
("bold", r"\*\*([^*]+)\*\*"),
("bold", r"__([^_]+)__"),
("italic", r"(?<!\*)\*([^*]+?)\*(?!\*)"),
("italic", r"(?<!_)_([^_]+?)_(?!_)"),
]
for kind, pattern in patterns:
for m in re.finditer(pattern, text):
start, end = m.span()
if _span_overlaps(used, start, end):
continue
content = m.group(1).strip()
if not content:
continue
spans.append((kind, content, start))
used.append((start, end))
return spans
def _is_all_caps_text(text: str) -> bool:
letters = [ch for ch in text if ch.isalpha()]
if len(letters) < 4:
return False
return all(ch.isupper() for ch in letters)
def _lint_emphasis_spans(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
for kind, content, col in _collect_emphasis_spans(clean):
words = len(re.findall(r"[A-Za-z0-9]+", content))
chars = len(content)
if kind == "italic" and (words >= 20 or chars >= 120):
diagnostics.append(
LintDiagnostic(
code="TYPO.ITALIC_LONG",
message="Avoid long runs of italics in body text",
severity="should",
path=str(doc.path),
line=idx,
column=col + 1,
rule_id="HOUSE.TYPOGRAPHY.EMPHASIS.ITALIC_LONG.AVOID",
)
)
if kind == "bold" and (words >= 12 or chars >= 80):
diagnostics.append(
LintDiagnostic(
code="TYPO.BOLD_LONG",
message="Avoid long runs of bold text in body paragraphs",
severity="should",
path=str(doc.path),
line=idx,
column=col + 1,
rule_id="HOUSE.TYPOGRAPHY.EMPHASIS.BOLD_LONG.AVOID",
)
)
if kind == "bold_italic" and (words >= 8 or chars >= 60):
diagnostics.append(
LintDiagnostic(
code="TYPO.BOLD_ITALIC_LONG",
message="Avoid long runs of bold italics",
severity="warn",
path=str(doc.path),
line=idx,
column=col + 1,
rule_id="HOUSE.TYPOGRAPHY.EMPHASIS.BOLD_ITALIC_LONG.AVOID",
)
)
if kind in {"bold", "bold_italic"} and _is_all_caps_text(content):
diagnostics.append(
LintDiagnostic(
code="TYPO.BOLD_ALL_CAPS",
message="Avoid bold all-caps text in running prose",
severity="should",
path=str(doc.path),
line=idx,
column=col + 1,
rule_id="HOUSE.TYPOGRAPHY.EMPHASIS.BOLD_ALL_CAPS.AVOID",
)
)
return diagnostics
def _lint_accessibility_links(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
label_targets: dict[str, set[str]] = {}
label_first_line: dict[str, int] = {}
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
for label, url, col in _iter_markdown_links(line):
norm_label = _normalize_label(label)
if norm_label:
label_targets.setdefault(norm_label, set()).add(url.strip())
label_first_line.setdefault(norm_label, idx)
if _is_symbol_only_text(label):
diagnostics.append(
LintDiagnostic(
code="A11Y.LINK_TEXT.SYMBOL_ONLY",
message="Avoid symbol-only link text; provide a readable label",
severity="should",
path=str(doc.path),
line=idx,
column=col,
rule_id="HOUSE.ACCESSIBILITY.LINK_TEXT.SYMBOL_ONLY.AVOID",
)
)
for label, targets in sorted(label_targets.items()):
if len(targets) <= 1:
continue
line_no = label_first_line.get(label, 1)
diagnostics.append(
LintDiagnostic(
code="A11Y.LINK_TEXT.DUPLICATE_LABELS",
message="Identical link text should not point to different destinations",
severity="should",
path=str(doc.path),
line=line_no,
column=1,
rule_id="HOUSE.ACCESSIBILITY.LINK_TEXT.UNIQUE_TARGETS",
)
)
return diagnostics
def _lint_citations_bracketed_numbers(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
pattern = re.compile(r"\[(\d{1,3})\]")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
if re.match(r"^\s*\[\d+\]:\s+", line) or re.match(r"^\s*\[\^\d+\]:\s+", line):
continue
clean = _strip_inline_code(line)
for m in pattern.finditer(clean):
if m.start() > 0 and clean[m.start() - 1] == "]":
continue
if m.end() < len(clean) and clean[m.end()] == "(":
continue
diagnostics.append(
LintDiagnostic(
code="CITATION.BRACKETED_NUMERIC",
message="Avoid bracketed numeric citations in prose; use Markdown footnotes",
severity="warn",
path=str(doc.path),
line=idx,
column=m.start() + 1,
rule_id="HOUSE.CITATIONS.NOTES.MARKERS.BRACKETED_NUMBERS.AVOID",
)
)
break
return diagnostics
def _lint_citations_heading_note_markers(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
pattern = re.compile(r"\[\^\d+\]")
for block in doc.blocks:
if block.type != "heading":
continue
matches = list(pattern.finditer(block.text))
if not matches:
continue
last = matches[-1]
trailing = block.text[last.end() :]
if trailing.strip():
diagnostics.append(
LintDiagnostic(
code="CITATION.HEADING_NOTE_PLACEMENT",
message="Place note markers at the end of headings",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="CMOS.CITATIONS.NOTES.NOTE_MARKERS.HEADINGS_END",
)
)
return diagnostics
def _lint_citations_ibid(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
ibid_re = re.compile(r"\bibid\.?\b", flags=re.IGNORECASE)
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
if not re.match(r"^\s*\[\^\d+\]:\s+", line):
continue
if ibid_re.search(line):
diagnostics.append(
LintDiagnostic(
code="CITATION.IBID",
message="Avoid ibid in notes; prefer unambiguous short forms",
severity="warn",
path=str(doc.path),
line=idx,
column=1,
rule_id="HOUSE.CITATIONS.NOTES.IBID.AVOID",
)
)
return diagnostics
def _lint_citations_notes_bibliography_required(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
ref_heading = re.compile(r"^#{1,6}\s*(references|bibliography|works cited)\b", flags=re.IGNORECASE)
notes_present = False
ref_heading_found = False
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
if re.search(r"\[\^\d+\]", line) or re.match(r"^\s*\[\^\d+\]:\s+", line):
notes_present = True
if ref_heading.match(line.strip()):
ref_heading_found = True
if notes_present and not ref_heading_found:
diagnostics.append(
LintDiagnostic(
code="CITATION.BIBLIOGRAPHY_REQUIRED",
message="Include a bibliography or references section when using footnote citations",
severity="should",
path=str(doc.path),
line=1,
column=1,
rule_id="HOUSE.CITATIONS.NOTES.BIBLIOGRAPHY.REQUIRED",
)
)
return diagnostics
def _lint_code_blocks(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
for block in doc.blocks:
if block.type != "code":
continue
if not (block.info or "").strip():
diagnostics.append(
LintDiagnostic(
code="CODE.LANG_INFO",
message="Consider adding a language identifier to fenced code blocks",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.CODE.FENCES.LANGUAGE_INFO.SUGGEST",
)
)
max_len = max((len(ln) for ln in block.text.splitlines()), default=0)
if max_len >= 100:
diagnostics.append(
LintDiagnostic(
code="CODE.LONG_LINES",
message="Code block contains very long lines that may overflow in PDF",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.CODE.BLOCKS.LONG_LINES.AVOID",
)
)
if "\t" in block.text:
diagnostics.append(
LintDiagnostic(
code="CODE.TABS",
message="Code block contains tab characters",
severity="should",
path=str(doc.path),
line=block.start_line,
column=1,
rule_id="HOUSE.CODE.BLOCKS.TABS.AVOID",
)
)
return diagnostics
def _lint_acronyms(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
text = doc.normalized_source
fenced = code_fence_lines(text)
allow = {
"AI",
"API",
"CLI",
"CPU",
"CSS",
"DNS",
"EU",
"GPU",
"HTML",
"HTTP",
"HTTPS",
"ID",
"IP",
"ISO",
"JSON",
"JWT",
"PDF",
"QA",
"RFC",
"SQL",
"SSH",
"SSL",
"TLS",
"UI",
"UK",
"US",
"UTC",
"UUID",
"URI",
"URL",
"VM",
"YAML",
}
defined: set[str] = set()
first_seen: dict[str, int] = {}
for idx, line in enumerate(text.splitlines(), start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
for m in re.finditer(r"\(([A-Z]{2,8})\)", clean):
defined.add(m.group(1))
for m in re.finditer(r"\b([A-Z]{2,8})\b", clean):
ac = m.group(1)
if ac in allow:
continue
first_seen.setdefault(ac, idx)
for ac, line_no in sorted(first_seen.items(), key=lambda kv: kv[1]):
if ac in defined:
continue
diagnostics.append(
LintDiagnostic(
code="ABBREV.DEFINE_FIRST_USE",
message=f"Acronym '{ac}' may need definition on first use",
severity="should",
path=str(doc.path),
line=line_no,
column=1,
rule_id="CMOS.ABBREVIATIONS.ACRONYMS.DEFINE_FIRST_USE",
)
)
return diagnostics
def _lint_citations_author_date(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
author_date_present = False
author_date_inline = re.compile(
r"\b[A-Z][A-Za-z-]+(?:\s+[A-Z][A-Za-z-]+)*\s*\((?:19|20)\d{2}[a-z]?\)"
)
author_date_paren = re.compile(r"\([A-Z][A-Za-z-]+[^)]*(?:19|20)\d{2}[a-z]?\)")
year_only_paren = re.compile(r"\((?:19|20)\d{2}[a-z]?\)")
year_pattern = re.compile(r"\b(1[89]\d{2}|20\d{2})\b")
nd_pattern = re.compile(r"\b(n\.d\.|forthcoming|in press)\b", flags=re.IGNORECASE)
ref_heading = re.compile(r"^#{1,6}\s*(references|bibliography|works cited)\b", flags=re.IGNORECASE)
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
clean = _strip_markdown_links(clean)
if author_date_inline.search(clean) or author_date_paren.search(clean):
author_date_present = True
for m in year_only_paren.finditer(clean):
diagnostics.append(
LintDiagnostic(
code="CITATION.AUTHOR_DATE.PAREN_YEAR_ONLY",
message="Year-only parenthetical citations are ambiguous in author-date style",
severity="warn",
path=str(doc.path),
line=idx,
column=m.start() + 1,
rule_id="HOUSE.CITATIONS.AUTHOR_DATE.PAREN_YEAR_ONLY",
)
)
if not author_date_present:
return diagnostics
in_refs = False
ref_heading_found = False
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
if ref_heading.match(clean):
ref_heading_found = True
in_refs = True
continue
if in_refs and clean.lstrip().startswith("#"):
break
if not in_refs:
continue
entry = clean.strip()
if not entry:
continue
entry = entry.lstrip("-*0123456789. ").strip()
if not entry:
continue
if year_pattern.search(entry) or nd_pattern.search(entry):
continue
diagnostics.append(
LintDiagnostic(
code="CITATION.AUTHOR_DATE.MISSING_YEAR",
message="Author-date references should include a year (or n.d.)",
severity="should",
path=str(doc.path),
line=idx,
column=1,
rule_id="HOUSE.CITATIONS.AUTHOR_DATE.REFLIST.YEAR_REQUIRED",
)
)
if author_date_present and not ref_heading_found:
diagnostics.append(
LintDiagnostic(
code="CITATION.AUTHOR_DATE.REFLIST_REQUIRED",
message="Provide a reference list when using author-date citations",
severity="should",
path=str(doc.path),
line=1,
column=1,
rule_id="HOUSE.CITATIONS.AUTHOR_DATE.REFLIST.REQUIRED",
)
)
return diagnostics
def _lint_i18n_consistency(doc: MdDocument) -> list[LintDiagnostic]:
diagnostics: list[LintDiagnostic] = []
lines = doc.normalized_source.splitlines()
fenced = code_fence_lines(doc.normalized_source)
comma_decimal = re.compile(r"\b\d+,\d{1,2}\b")
dot_decimal = re.compile(r"\b\d+\.\d{1,2}\b")
comma_line = None
dot_line = None
guillemet_line = None
curly_line = None
for idx, line in enumerate(lines, start=1):
if idx in fenced:
continue
clean = _strip_inline_code(line)
if comma_line is None and comma_decimal.search(clean):
comma_line = idx
if dot_line is None and dot_decimal.search(clean):
dot_line = idx
if guillemet_line is None and ("«" in clean or "»" in clean):
guillemet_line = idx
if curly_line is None and ("“" in clean or "”" in clean):
curly_line = idx
if comma_line is not None and dot_line is not None:
diagnostics.append(
LintDiagnostic(
code="I18N.MIXED_DECIMAL_SEPARATORS",
message="Avoid mixing decimal separators within the same document",
severity="should",
path=str(doc.path),
line=comma_line,
column=1,
rule_id="HOUSE.I18N.NUMBERS.MIXED_DECIMAL_SEPARATORS",
)
)
if guillemet_line is not None and curly_line is not None:
diagnostics.append(
LintDiagnostic(
code="I18N.MIXED_QUOTE_STYLES",
message="Avoid mixing quotation styles across locales in the same document",
severity="should",
path=str(doc.path),
line=guillemet_line,
column=1,
rule_id="HOUSE.I18N.QUOTES.MIXED_STYLES",
)
)
return diagnostics
def _normalize_sentence_spacing(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern = re.compile(r"([.!?][\]\)\"']?)( {2,})")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
parts: list[str] = []
for is_code, seg in _split_inline_code(line):
if is_code:
parts.append(seg)
continue
new_seg, n = pattern.subn(r"\1 ", seg)
count += n
parts.append(new_seg)
out.append("".join(parts))
return out, count
def _normalize_colon_spacing(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern_many = re.compile(r": {2,}")
pattern_missing = re.compile(r":(?!\s)(?=[A-Za-z])")
for idx, line in enumerate(lines, start=1):
if idx in fenced or "://" in line:
out.append(line)
continue
parts: list[str] = []
for is_code, seg in _split_inline_code(line):
if is_code:
parts.append(seg)
continue
seg2, n1 = pattern_many.subn(": ", seg)
seg3, n2 = pattern_missing.subn(": ", seg2)
count += n1 + n2
parts.append(seg3)
out.append("".join(parts))
return out, count
def _normalize_em_dashes(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern = re.compile(r"\s--\s")
spaced = re.compile(r"\s—\s")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
parts: list[str] = []
for is_code, seg in _split_inline_code(line):
if is_code:
parts.append(seg)
continue
seg2, n1 = pattern.subn("—", seg)
seg3, n2 = spaced.subn("—", seg2)
count += n1 + n2
parts.append(seg3)
out.append("".join(parts))
return out, count
def _normalize_leading_zero_decimals(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern = re.compile(r"(?<![0-9A-Za-z])\.(\d+)")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
parts: list[str] = []
for is_code, seg in _split_inline_code(line):
if is_code:
parts.append(seg)
continue
seg2, n = pattern.subn(r"0.\1", seg)
count += n
parts.append(seg2)
out.append("".join(parts))
return out, count
def _normalize_decade_plurals(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern = re.compile(r"\b(\d{4})[’']s(?=$|[\s\.,;:!?])")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
parts: list[str] = []
for is_code, seg in _split_inline_code(line):
if is_code:
parts.append(seg)
continue
seg2, n = pattern.subn(r"\1s", seg)
count += n
parts.append(seg2)
out.append("".join(parts))
return out, count
def _normalize_markdown_link_trailing_punct(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
pattern = re.compile(r"\]\((https?://[^)\s]+?)([\.,;:])\)")
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
new_line, n = pattern.subn(r"](\1)\2", line)
count += n
out.append(new_line)
return out, count
def _normalize_smart_quotes(lines: list[str], fenced: set[int]) -> tuple[list[str], int]:
out: list[str] = []
count = 0
for idx, line in enumerate(lines, start=1):
if idx in fenced:
out.append(line)
continue
parts: list[str] = []
for is_code, seg in _split_inline_code(line):
if is_code or seg.count('"') % 2 != 0:
parts.append(seg)
continue
opening = True
new_chars: list[str] = []
local = 0
for ch in seg:
if ch != '"':
new_chars.append(ch)
continue
new_chars.append("“" if opening else "”")
opening = not opening
local += 1
count += local
parts.append("".join(new_chars))
out.append("".join(parts))
return out, count
def _build_report(
*,
diagnostics: list[LintDiagnostic],
fixes: list[LintFix],
inputs: list[Path],
profile_id: str,
degraded: dict[str, list[str]],
degraded_ok: bool,
fail_on: str,
) -> dict[str, Any]:
now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
counts = {"must": 0, "should": 0, "warn": 0}
for diag in diagnostics:
counts[diag.severity] = counts.get(diag.severity, 0) + 1
failed = _fails_threshold(diagnostics, degraded, degraded_ok=degraded_ok, fail_on=fail_on)
return {
"ok": not failed,
"tool": "iftypeset",
"tool_version": __version__,
"generated_at_utc": now,
"profile_id": profile_id,
"inputs": [str(p) for p in inputs],
"fail_on": fail_on,
"degraded_ok": degraded_ok,
"summary": {
"diagnostic_counts": counts,
"fix_counts": {f.code: f.count for f in fixes},
"degraded_files": len(degraded),
},
"degraded": degraded,
"diagnostics": [asdict(d) for d in diagnostics],
"fixes": [asdict(f) for f in fixes],
}
def _fails_threshold(
diagnostics: list[LintDiagnostic],
degraded: dict[str, list[str]],
*,
degraded_ok: bool,
fail_on: str,
) -> bool:
if degraded and not degraded_ok:
return True
if fail_on not in SEVERITY_ORDER:
raise ValueError(f"Unknown fail-on severity: {fail_on}")
threshold = SEVERITY_ORDER[fail_on]
return any(SEVERITY_ORDER.get(d.severity, 0) >= threshold for d in diagnostics)
def evaluate_fail_on(diagnostics: list[LintDiagnostic], fail_on: str) -> bool:
if fail_on not in SEVERITY_ORDER:
raise ValueError(f"Unknown fail-on severity: {fail_on}")
threshold = SEVERITY_ORDER[fail_on]
return any(SEVERITY_ORDER.get(d.severity, 0) >= threshold for d in diagnostics)
````
### `iftypeset/src/iftypeset/md_parser.py`
- bytes: `10737`
- sha256: `f1c8d33c39d0e5c022ddc3fc7fc9a0ead4fd9ad9d2189ad581a7a0c72a6e8962`
````py
from __future__ import annotations
from dataclasses import dataclass, field
from pathlib import Path
import re
from typing import Iterable
@dataclass(frozen=True)
class MdBlock:
type: str
start_line: int
end_line: int
text: str = ""
level: int | None = None
items: list[str] = field(default_factory=list)
ordered: bool | None = None
info: str | None = None
headers: list[str] = field(default_factory=list)
rows: list[list[str]] = field(default_factory=list)
@dataclass(frozen=True)
class MdDocument:
path: Path
source: str
blocks: list[MdBlock]
degraded: bool
degraded_reasons: list[str]
normalized_source: str
def read_markdown(path: Path) -> tuple[str, list[str]]:
reasons: list[str] = []
try:
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
text = path.read_text(encoding="utf-8", errors="replace")
reasons.append("invalid_utf8_replaced")
return text, reasons
def normalize_newlines(text: str) -> str:
return text.replace("\r\n", "\n").replace("\r", "\n")
def detect_degraded(text: str) -> list[str]:
reasons: list[str] = []
lines = [ln for ln in text.splitlines()]
non_empty = [ln for ln in lines if ln.strip()]
fenced = code_fence_lines(text)
content_lines: list[str] = []
for idx, ln in enumerate(lines, start=1):
if idx in fenced:
continue
if not ln.strip():
continue
if re.match(r"^#{1,6}\s+", ln):
continue
if re.match(r"^\s*([-*+]\s+|\d+\.\s+)", ln):
continue
if ln.lstrip().startswith(">"):
continue
if "|" in ln and re.match(r"^\s*\|", ln):
continue
content_lines.append(ln.strip())
if content_lines:
lengths = sorted(len(ln) for ln in content_lines)
short = [l for l in lengths if l < 35]
ratio = len(short) / max(len(lengths), 1)
median = lengths[len(lengths) // 2]
continuations = 0
possible = 0
for prev, nxt in zip(content_lines, content_lines[1:]):
if not prev or not nxt:
continue
possible += 1
prev_last = prev[-1]
next_first = nxt[0]
if prev_last == "-" and next_first.islower():
continuations += 1
elif prev_last.isalpha() and prev_last.islower() and next_first.islower():
continuations += 1
continuation_ratio = continuations / max(possible, 1)
if (
len(lengths) >= 20
and continuation_ratio > 0.3
and ((ratio > 0.8 and median < 40) or (ratio > 0.6 and median < 30))
):
reasons.append("hard_wrap_density")
if len(non_empty) >= 12 and not any(re.match(r"^#{1,6}\s+", ln) for ln in lines):
reasons.append("missing_headings")
return reasons
def unwrap_hard_wrapped_paragraphs(text: str) -> str:
lines = text.splitlines()
out_lines: list[str] = []
buf: list[str] = []
def flush_buf() -> None:
if not buf:
return
joined = ""
for i, ln in enumerate(buf):
ln = ln.strip()
if i == 0:
joined = ln
continue
if joined.endswith("-") and ln and ln[0].islower():
joined = joined[:-1] + ln
else:
joined = joined + " " + ln
out_lines.append(joined)
buf.clear()
for ln in lines:
if not ln.strip():
flush_buf()
out_lines.append("")
continue
if re.match(r"^\s*(```|~~~)", ln) or re.match(r"^\s*([-*+]\s+|\d+\.\s+)", ln):
flush_buf()
out_lines.append(ln.rstrip())
continue
if re.match(r"^#{1,6}\s+", ln) or ln.lstrip().startswith(">"):
flush_buf()
out_lines.append(ln.rstrip())
continue
if "|" in ln and re.match(r"^\s*\|?\s*[-:]{3,}", ln):
flush_buf()
out_lines.append(ln.rstrip())
continue
buf.append(ln)
flush_buf()
return "\n".join(out_lines)
def parse_markdown(path: Path, text: str) -> MdDocument:
original = normalize_newlines(text)
reasons = detect_degraded(original)
normalized = original
if "hard_wrap_density" in reasons:
normalized = unwrap_hard_wrapped_paragraphs(original)
blocks = _parse_blocks(normalized)
return MdDocument(
path=path,
source=original,
blocks=blocks,
degraded=bool(reasons),
degraded_reasons=reasons,
normalized_source=normalized,
)
def _parse_blocks(text: str) -> list[MdBlock]:
lines = text.splitlines()
blocks: list[MdBlock] = []
i = 0
while i < len(lines):
line = lines[i]
if not line.strip():
i += 1
continue
if _is_code_fence(line):
blocks.append(_parse_code_block(lines, i))
i = blocks[-1].end_line
continue
heading = _parse_heading(line, i)
if heading:
blocks.append(heading)
i += 1
continue
table = _parse_table(lines, i)
if table:
blocks.append(table)
i = table.end_line
continue
lst = _parse_list(lines, i)
if lst:
blocks.append(lst)
i = lst.end_line
continue
if line.lstrip().startswith(">"):
blocks.append(_parse_blockquote(lines, i))
i = blocks[-1].end_line
continue
blocks.append(_parse_paragraph(lines, i))
i = blocks[-1].end_line
return blocks
def _is_code_fence(line: str) -> bool:
return bool(re.match(r"^\s*(```|~~~)", line))
def _parse_code_block(lines: list[str], start: int) -> MdBlock:
fence = lines[start]
m = re.match(r"^\s*(```|~~~)(.*)$", fence)
info = m.group(2).strip() if m else ""
i = start + 1
code_lines: list[str] = []
while i < len(lines):
if _is_code_fence(lines[i]):
i += 1
break
code_lines.append(lines[i])
i += 1
text = "\n".join(code_lines)
return MdBlock(type="code", start_line=start + 1, end_line=i, text=text, info=info)
def _parse_heading(line: str, idx: int) -> MdBlock | None:
m = re.match(r"^(#{1,6})\s+(.*)$", line)
if not m:
return None
level = len(m.group(1))
text = m.group(2).strip()
return MdBlock(type="heading", start_line=idx + 1, end_line=idx + 1, text=text, level=level)
def _parse_list(lines: list[str], start: int) -> MdBlock | None:
m = re.match(r"^\s*([-*+])\s+(.+)$", lines[start])
ordered_m = re.match(r"^\s*(\d+)\.\s+(.+)$", lines[start])
if not m and not ordered_m:
return None
items: list[str] = []
ordered = False
i = start
while i < len(lines):
line = lines[i]
m = re.match(r"^\s*([-*+])\s+(.+)$", line)
ordered_m = re.match(r"^\s*(\d+)\.\s+(.+)$", line)
if m:
items.append(m.group(2).strip())
elif ordered_m:
ordered = True
items.append(ordered_m.group(2).strip())
else:
break
i += 1
return MdBlock(
type="list",
start_line=start + 1,
end_line=i,
items=items,
ordered=ordered,
)
def _parse_table(lines: list[str], start: int) -> MdBlock | None:
if start + 1 >= len(lines):
return None
header = lines[start]
sep = lines[start + 1]
if "|" not in header:
return None
if not _is_table_separator(sep):
return None
headers = _split_pipes(header)
rows: list[list[str]] = []
i = start + 2
while i < len(lines):
if "|" not in lines[i] or not lines[i].strip():
break
if _is_code_fence(lines[i]) or re.match(r"^#{1,6}\s+", lines[i]):
break
rows.append(_split_pipes(lines[i]))
i += 1
return MdBlock(
type="table",
start_line=start + 1,
end_line=i,
headers=headers,
rows=rows,
)
def _is_table_separator(line: str) -> bool:
parts = _split_pipes(line)
if len(parts) < 2:
return False
for p in parts:
if not re.match(r"^:?-{3,}:?$", p.strip()):
return False
return True
def _split_pipes(line: str) -> list[str]:
stripped = line.strip()
if stripped.startswith("|"):
stripped = stripped[1:]
if stripped.endswith("|"):
stripped = stripped[:-1]
return [p.strip() for p in stripped.split("|")]
def _parse_blockquote(lines: list[str], start: int) -> MdBlock:
i = start
parts: list[str] = []
while i < len(lines):
line = lines[i]
if not line.lstrip().startswith(">"):
break
parts.append(line.lstrip()[1:].lstrip())
i += 1
text = " ".join([p for p in parts if p])
return MdBlock(type="blockquote", start_line=start + 1, end_line=i, text=text)
def _parse_paragraph(lines: list[str], start: int) -> MdBlock:
i = start
paragraph_lines: list[tuple[str, bool]] = []
while i < len(lines):
line = lines[i]
if not line.strip():
break
if _is_code_fence(line) or re.match(r"^#{1,6}\s+", line) or _parse_list(lines, i) or _parse_table(lines, i):
break
if line.lstrip().startswith(">"):
break
hard_break = line.endswith(" ")
clean = line.rstrip()
if clean.endswith("\\"):
hard_break = True
clean = clean[:-1].rstrip()
text_line = clean.strip()
if text_line:
paragraph_lines.append((text_line, hard_break))
i += 1
text_parts: list[str] = []
prev_break = False
for idx, (text_line, hard_break) in enumerate(paragraph_lines):
if idx > 0:
text_parts.append("\n" if prev_break else " ")
text_parts.append(text_line)
prev_break = hard_break
text = "".join(text_parts)
return MdBlock(type="paragraph", start_line=start + 1, end_line=i, text=text)
def code_fence_lines(text: str) -> set[int]:
lines = text.splitlines()
in_fence = False
fenced_lines: set[int] = set()
for i, line in enumerate(lines, start=1):
if _is_code_fence(line):
in_fence = not in_fence
fenced_lines.add(i)
continue
if in_fence:
fenced_lines.add(i)
return fenced_lines
def iter_blocks(blocks: Iterable[MdBlock], type_name: str) -> Iterable[MdBlock]:
for b in blocks:
if b.type == type_name:
yield b
````
### `iftypeset/src/iftypeset/qa.py`
- bytes: `39188`
- sha256: `fb203f36769418e9b14888b5d01aeac19aa3ed9b5888d185f15dc09b04618d81`
````py
from __future__ import annotations
from dataclasses import asdict, dataclass
from datetime import datetime, timezone
from html.parser import HTMLParser
from pathlib import Path
import re
import subprocess
from typing import Any
import xml.etree.ElementTree as ET
from iftypeset import __version__
@dataclass(frozen=True)
class LayoutIncident:
kind: str
detail: str
context: str | None = None
@dataclass(frozen=True)
class LayoutReport:
metrics: dict[str, int]
incidents: list[LayoutIncident]
warnings: list[str]
profile_id: str
analysis_mode: str
@dataclass(frozen=True)
class PdfAnalysisResult:
ok: bool
metrics: dict[str, int]
incidents: list[LayoutIncident]
warnings: list[str]
page_count: int | None = None
@dataclass
class _Block:
type: str
word_count: int
text: str = ""
level: int | None = None
line_count: int = 0
class HtmlCollector(HTMLParser):
def __init__(self) -> None:
super().__init__()
self.headings: list[tuple[int, str]] = []
self.links: list[tuple[str, str]] = []
self.code_blocks: list[str] = []
self.tables: list[dict[str, object]] = []
self.blocks: list[_Block] = []
self._heading_level: int | None = None
self._heading_text: list[str] = []
self._link_href: str | None = None
self._link_text: list[str] = []
self._in_pre = False
self._code_text: list[str] = []
self._in_paragraph = False
self._paragraph_text: list[str] = []
self._in_list_item = False
self._list_text: list[str] = []
self._in_table = False
self._table_rows: list[int] = []
self._table_cell_lengths: list[int] = []
self._table_max_cell_sample = ""
self._table_word_count = 0
self._current_row_cols = 0
self._cell_text: list[str] | None = None
def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
if tag in {"h1", "h2", "h3", "h4", "h5", "h6"}:
self._heading_level = int(tag[1])
self._heading_text = []
if tag == "a":
href = ""
for k, v in attrs:
if k == "href" and v:
href = v
self._link_href = href
self._link_text = []
if tag == "pre":
self._in_pre = True
self._code_text = []
if tag == "p":
self._in_paragraph = True
self._paragraph_text = []
if tag == "li":
self._in_list_item = True
self._list_text = []
if tag == "table":
self._in_table = True
self._table_rows = []
self._table_cell_lengths = []
self._table_max_cell_sample = ""
self._table_word_count = 0
self._current_row_cols = 0
if tag == "tr" and self._in_table:
self._current_row_cols = 0
if tag in {"td", "th"} and self._in_table:
self._cell_text = []
def handle_endtag(self, tag: str) -> None:
if tag in {"h1", "h2", "h3", "h4", "h5", "h6"} and self._heading_level is not None:
text = " ".join(self._heading_text).strip()
self.headings.append((self._heading_level, text))
self.blocks.append(_Block(type="heading", word_count=0, text=text, level=self._heading_level))
self._heading_level = None
self._heading_text = []
if tag == "a" and self._link_href is not None:
text = " ".join(self._link_text).strip()
self.links.append((self._link_href, text))
self._link_href = None
self._link_text = []
if tag == "pre" and self._in_pre:
text = "".join(self._code_text)
self.code_blocks.append(text)
wc = _word_count(text)
line_count = len([ln for ln in text.splitlines() if ln.strip()]) or 1
self.blocks.append(_Block(type="code", word_count=wc, text=text, line_count=line_count))
self._in_pre = False
self._code_text = []
if tag == "p" and self._in_paragraph:
text = " ".join(self._paragraph_text).strip()
wc = _word_count(text)
self.blocks.append(_Block(type="paragraph", word_count=wc, text=text))
self._in_paragraph = False
self._paragraph_text = []
if tag == "li" and self._in_list_item:
text = " ".join(self._list_text).strip()
wc = _word_count(text)
self.blocks.append(_Block(type="list_item", word_count=wc, text=text))
self._in_list_item = False
self._list_text = []
if tag in {"td", "th"} and self._in_table and self._cell_text is not None:
text = " ".join(self._cell_text).strip()
cell_len = len(text)
self._table_cell_lengths.append(len(text))
if cell_len >= max(self._table_cell_lengths):
self._table_max_cell_sample = text[:120]
self._table_word_count += _word_count(text)
self._current_row_cols += 1
self._cell_text = None
if tag == "tr" and self._in_table:
self._table_rows.append(self._current_row_cols)
self._current_row_cols = 0
if tag == "table" and self._in_table:
max_cols = max(self._table_rows) if self._table_rows else 0
max_cell = max(self._table_cell_lengths) if self._table_cell_lengths else 0
row_count = len(self._table_rows)
self.tables.append(
{
"max_cols": max_cols,
"max_cell_len": max_cell,
"rows": row_count,
"max_cell_sample": self._table_max_cell_sample,
}
)
self.blocks.append(_Block(type="table", word_count=self._table_word_count, line_count=row_count))
self._in_table = False
self._table_rows = []
self._table_cell_lengths = []
self._table_max_cell_sample = ""
self._table_word_count = 0
def handle_data(self, data: str) -> None:
if self._heading_level is not None:
self._heading_text.append(data)
if self._link_href is not None:
self._link_text.append(data)
if self._in_pre:
self._code_text.append(data)
if self._in_paragraph:
self._paragraph_text.append(data)
if self._in_list_item:
self._list_text.append(data)
if self._cell_text is not None:
self._cell_text.append(data)
def analyze_html(html_text: str, profile: dict[str, Any], *, analysis_mode: str = "html") -> LayoutReport:
collector = HtmlCollector()
collector.feed(html_text)
measure = profile.get("measure_targets") or {}
body_chars = (measure.get("body_chars_per_line") or {}).get("max") or 75
body_chars = int(body_chars)
link_threshold = max(80, body_chars)
code_threshold = max(90, body_chars + 15)
table_profile = profile.get("tables") or {}
shrink_limit = table_profile.get("shrink_limit") or 0.9
try:
shrink_limit_f = float(shrink_limit)
except (TypeError, ValueError):
shrink_limit_f = 0.9
if not (0.5 <= shrink_limit_f <= 1.0):
shrink_limit_f = 0.9
effective_chars = int(body_chars * min(1.15, 1.0 / shrink_limit_f))
table_max_cols = max(5, min(12, int(round(effective_chars / 11.0))))
table_max_cell = max(30, min(100, int(round(effective_chars * 0.6))))
incidents: list[LayoutIncident] = []
link_wrap = 0
anchor_tokens: set[str] = set()
for href, text in collector.links:
for token in _extract_link_like_tokens(text):
anchor_tokens.add(token)
for token in _extract_link_like_tokens(href):
anchor_tokens.add(token)
for href, text in collector.links:
candidates = _extract_link_like_tokens(text) + _extract_link_like_tokens(href)
token = max(candidates, key=len) if candidates else (text or href)
if token and _long_unbroken(token, link_threshold):
link_wrap += 1
incidents.append(LayoutIncident(kind="link_wrap", detail=href, context=token[:120]))
for block in collector.blocks:
if block.type not in {"paragraph", "list_item"}:
continue
tokens = {t for t in _extract_link_like_tokens(block.text) if t not in anchor_tokens}
for token in sorted(tokens):
if not _long_unbroken(token, link_threshold):
continue
link_wrap += 1
incidents.append(LayoutIncident(kind="link_wrap", detail=token, context=block.text[:140]))
code_overflow = 0
for code in collector.code_blocks:
max_len = 0
max_line_no = 0
max_line_sample = ""
for idx, line in enumerate(code.splitlines(), start=1):
ln = len(line)
if ln >= max_len:
max_len = ln
max_line_no = idx
max_line_sample = line[:120]
if max_len > code_threshold:
code_overflow += 1
incidents.append(
LayoutIncident(
kind="code_overflow",
detail=f"line_len={max_len} line_no={max_line_no}",
context=max_line_sample or None,
)
)
table_overflow = 0
for table in collector.tables:
if table.get("max_cols", 0) > table_max_cols or table.get("max_cell_len", 0) > table_max_cell:
table_overflow += 1
incidents.append(
LayoutIncident(
kind="table_overflow",
detail=f"cols={table.get('max_cols')} max_cell_len={table.get('max_cell_len')} rows={table.get('rows')} (limits cols={table_max_cols} cell={table_max_cell})",
context=str(table.get("max_cell_sample") or "")[:140] or None,
)
)
heading_errors, heading_incidents = _heading_numbering_errors(collector.headings)
incidents.extend(heading_incidents)
stranded, stranded_incidents = _stranded_headings(collector.blocks, profile)
incidents.extend(stranded_incidents)
overfull_lines, overfull_incidents = _overfull_lines(collector.blocks, body_chars)
incidents.extend(overfull_incidents)
metrics = {
"max_widows_per_10_pages": 0,
"max_orphans_per_10_pages": 0,
"max_stranded_headings": stranded,
"max_overfull_lines": overfull_lines,
"max_table_overflow_incidents": table_overflow,
"max_code_overflow_incidents": code_overflow,
"max_link_wrap_incidents": link_wrap,
"max_heading_numbering_errors": heading_errors,
"max_citation_format_errors": 0,
"max_caption_separation_incidents": 0,
"max_list_break_incidents": 0,
"max_heading_proximity_incidents": 0,
"max_runt_final_page": 0,
}
return LayoutReport(
metrics=metrics,
incidents=incidents,
warnings=[],
profile_id=str(profile.get("profile_id") or ""),
analysis_mode=analysis_mode,
)
def analyze_pdf(pdf_path: Path, profile: dict[str, Any], *, analysis_mode: str = "pdf") -> PdfAnalysisResult:
warnings: list[str] = []
page_count, info_warnings = _run_pdfinfo(pdf_path)
warnings.extend(info_warnings)
pages, text_warnings = _run_pdftotext(pdf_path)
warnings.extend(text_warnings)
xml_pages, xml_warnings = _run_pdftohtml_xml(pdf_path)
warnings.extend(xml_warnings)
if not pages:
if not warnings:
warnings.append("PDF analysis failed; HTML-only analysis used")
return PdfAnalysisResult(ok=False, metrics={}, incidents=[], warnings=warnings, page_count=page_count)
if page_count and page_count != len(pages):
warnings.append(
f"pdfinfo pages ({page_count}) differ from pdftotext pages ({len(pages)}); using pdftotext output"
)
measure = profile.get("measure_targets") or {}
body_chars = (measure.get("body_chars_per_line") or {}).get("max") or 75
body_chars = int(body_chars)
keep_lines = int((profile.get("headings") or {}).get("keep_with_next_lines") or 2)
heading_max_chars = max(24, min(60, int(body_chars * 0.75)))
widows_per_page, orphans_per_page, incidents = _detect_widows_orphans(pages)
pagination_cfg = profile.get("pagination") or {}
runt_ratio = float(pagination_cfg.get("min_last_page_ratio") or 0.33)
runt_min_lines = int(pagination_cfg.get("min_last_page_lines") or 4)
runt_count, runt_incidents = _detect_runt_final_page(
pages,
min_ratio=runt_ratio,
min_lines=runt_min_lines,
)
overfull_counts, overfull_incidents = _detect_pdf_overfull_lines(pages, body_chars)
caption_counts, caption_incidents = _detect_caption_separation_pdf(pages)
list_counts, list_incidents = _detect_list_breaks_pdf(pages)
bbox_counts: list[int] = []
bbox_incidents: list[LayoutIncident] = []
if xml_pages:
bbox_counts, bbox_incidents = _detect_pdf_bbox_overflow(xml_pages, tolerance=2.0)
incidents.extend(bbox_incidents)
stranded_counts, stranded_incidents = _detect_stranded_headings_pdf(pages, keep_lines, heading_max_chars)
proximity_counts, proximity_incidents = _detect_heading_proximity_pdf(pages, heading_max_chars)
incidents.extend(overfull_incidents)
incidents.extend(caption_incidents)
incidents.extend(list_incidents)
incidents.extend(stranded_incidents)
incidents.extend(proximity_incidents)
incidents.extend(runt_incidents)
metrics = {
"max_widows_per_10_pages": _max_count_per_window(widows_per_page, window=10),
"max_orphans_per_10_pages": _max_count_per_window(orphans_per_page, window=10),
"max_overfull_lines": sum(overfull_counts) + sum(bbox_counts),
"max_stranded_headings": sum(stranded_counts),
"max_caption_separation_incidents": sum(caption_counts),
"max_list_break_incidents": sum(list_counts),
"max_heading_proximity_incidents": sum(proximity_counts),
"max_runt_final_page": runt_count,
}
warnings.append("PDF QA is heuristic and based on text extraction; verify layout for release-quality outputs.")
return PdfAnalysisResult(
ok=True,
metrics=metrics,
incidents=incidents,
warnings=warnings,
page_count=page_count or len(pages),
)
def evaluate_gates(
metrics: dict[str, int],
gates: dict[str, int],
*,
profile_id: str,
strict: bool,
) -> dict[str, Any]:
results: dict[str, Any] = {}
failed: list[str] = []
for metric, limit in gates.items():
count = metrics.get(metric, 0)
status = "pass" if count <= limit else "fail"
results[metric] = {"count": count, "max": limit, "status": status}
if status == "fail":
failed.append(metric)
return {
"ok": not failed,
"profile_id": profile_id,
"strict": strict,
"gates": results,
"failed": failed,
}
def layout_report_dict(report: LayoutReport) -> dict[str, Any]:
now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
return {
"ok": True,
"tool": "iftypeset",
"tool_version": __version__,
"generated_at_utc": now,
"profile_id": report.profile_id,
"analysis_mode": report.analysis_mode,
"metrics": report.metrics,
"incidents": [asdict(i) for i in report.incidents],
"warnings": report.warnings,
}
def _heading_numbering_errors(headings: list[tuple[int, str]]) -> tuple[int, list[LayoutIncident]]:
errors = 0
incidents: list[LayoutIncident] = []
last_numbers: list[int] = []
for level, text in headings:
m = re.match(r"^(\d+(?:\.\d+)*)\s+", text)
if not m:
continue
parts = [int(p) for p in m.group(1).split(".")]
if not last_numbers:
last_numbers = parts
continue
if len(parts) == 1:
if parts[0] <= last_numbers[0]:
errors += 1
incidents.append(LayoutIncident(kind="heading_numbering", detail=text))
last_numbers = parts
continue
prefix = parts[:-1]
if prefix != last_numbers[: len(prefix)]:
errors += 1
incidents.append(LayoutIncident(kind="heading_numbering", detail=text))
last_numbers = parts
continue
prev = last_numbers[len(parts) - 1] if len(last_numbers) >= len(parts) else 0
if parts[-1] != prev + 1 and not (prev == 0 and parts[-1] == 1):
errors += 1
incidents.append(LayoutIncident(kind="heading_numbering", detail=text))
last_numbers = parts
return errors, incidents
def _stranded_headings(blocks: list[_Block], profile: dict[str, Any]) -> tuple[int, list[LayoutIncident]]:
keep_lines = int((profile.get("headings") or {}).get("keep_with_next_lines") or 2)
measure = profile.get("measure_targets") or {}
ideal_chars = (measure.get("body_chars_per_line") or {}).get("ideal") or 66
words_per_line = max(8, int(int(ideal_chars) / 6))
stranded = 0
incidents: list[LayoutIncident] = []
for i, block in enumerate(blocks):
if block.type != "heading":
continue
content_lines = 0
for nxt in blocks[i + 1 :]:
if nxt.type == "heading":
break
if nxt.type in {"code", "table"}:
content_lines += max(keep_lines, nxt.line_count or keep_lines)
elif nxt.type == "list_item":
content_lines += 1
else:
wc = max(0, int(nxt.word_count))
content_lines += max(1, (wc + words_per_line - 1) // words_per_line) if wc else 0
if content_lines >= keep_lines:
break
if content_lines < keep_lines:
stranded += 1
incidents.append(LayoutIncident(kind="stranded_heading", detail=block.text))
return stranded, incidents
def _overfull_lines(blocks: list[_Block], max_chars: int) -> tuple[int, list[LayoutIncident]]:
count = 0
incidents: list[LayoutIncident] = []
for block in blocks:
if block.type not in {"paragraph", "list_item"}:
continue
for token in re.findall(r"\S+", block.text):
if len(token) > max_chars:
count += 1
incidents.append(LayoutIncident(kind="overfull_token", detail=token[:120], context=block.text[:140]))
break
return count, incidents
def _long_unbroken(text: str, threshold: int) -> bool:
for token in re.findall(r"\S+", text):
if len(token) >= threshold:
return True
return False
def _word_count(text: str) -> int:
return len([t for t in re.split(r"\s+", text.strip()) if t])
def _run_pdfinfo(pdf_path: Path) -> tuple[int | None, list[str]]:
warnings: list[str] = []
try:
proc = subprocess.run(
["pdfinfo", str(pdf_path)],
check=True,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
except FileNotFoundError:
return None, ["pdfinfo not available; PDF analysis skipped"]
except subprocess.CalledProcessError as exc:
msg = exc.stderr.decode("utf-8", errors="replace").strip() or "pdfinfo failed"
return None, [msg]
text = proc.stdout.decode("utf-8", errors="replace")
match = re.search(r"^Pages:\s+(\d+)\s*$", text, flags=re.MULTILINE)
if not match:
warnings.append("pdfinfo did not report page count")
return None, warnings
return int(match.group(1)), warnings
def _run_pdftotext(pdf_path: Path) -> tuple[list[str], list[str]]:
warnings: list[str] = []
try:
proc = subprocess.run(
["pdftotext", "-layout", str(pdf_path), "-"],
check=True,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
except FileNotFoundError:
return [], ["pdftotext not available; PDF analysis skipped"]
except subprocess.CalledProcessError as exc:
msg = exc.stderr.decode("utf-8", errors="replace").strip() or "pdftotext failed"
return [], [msg]
text = proc.stdout.decode("utf-8", errors="replace")
pages = _split_pdf_pages(text)
if not pages:
warnings.append("pdftotext returned no extractable text")
return pages, warnings
def _safe_float(value: str | None) -> float:
try:
return float(value) if value is not None else 0.0
except (TypeError, ValueError):
return 0.0
def _run_pdftohtml_xml(pdf_path: Path) -> tuple[list[dict[str, Any]], list[str]]:
warnings: list[str] = []
try:
proc = subprocess.run(
["pdftohtml", "-xml", "-stdout", str(pdf_path)],
check=True,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
except FileNotFoundError:
return [], ["pdftohtml not available; PDF bbox analysis skipped"]
except subprocess.CalledProcessError as exc:
msg = exc.stderr.decode("utf-8", errors="replace").strip() or "pdftohtml failed"
return [], [msg]
raw = proc.stdout.decode("utf-8", errors="replace").strip()
if not raw:
return [], ["pdftohtml returned no XML output"]
try:
root = ET.fromstring(raw)
except ET.ParseError as exc:
return [], [f"pdftohtml XML parse error: {exc}"]
pages: list[dict[str, Any]] = []
for page in root.findall(".//page"):
width = _safe_float(page.get("width"))
height = _safe_float(page.get("height"))
number_raw = page.get("number")
try:
number = int(number_raw) if number_raw is not None else len(pages) + 1
except ValueError:
number = len(pages) + 1
texts: list[dict[str, Any]] = []
for node in page.findall("text"):
text = "".join(node.itertext()).strip()
if not text:
continue
texts.append(
{
"left": _safe_float(node.get("left")),
"top": _safe_float(node.get("top")),
"width": _safe_float(node.get("width")),
"height": _safe_float(node.get("height")),
"text": text,
}
)
pages.append({"number": number, "width": width, "height": height, "texts": texts})
if not pages:
warnings.append("pdftohtml XML contained no pages")
return pages, warnings
def _split_pdf_pages(text: str) -> list[str]:
pages = text.split("\f")
if pages and not pages[-1].strip():
pages = pages[:-1]
return pages
def _max_count_per_window(counts: list[int], *, window: int) -> int:
if not counts:
return 0
if len(counts) <= window:
return sum(counts)
max_sum = 0
running = sum(counts[:window])
max_sum = max(max_sum, running)
for i in range(window, len(counts)):
running += counts[i] - counts[i - window]
if running > max_sum:
max_sum = running
return max_sum
_PAGE_NUMBER_RE = re.compile(r"^\s*([ivxlcdmIVXLCDM]+|\d{1,4})\s*$")
_CAPTION_RE = re.compile(r"^(figure|fig\.|table|tbl\.)\s*\d+[A-Za-z0-9.\-]*\b", flags=re.IGNORECASE)
_LIST_ITEM_RE = re.compile(r"^\s*(?:[-*•]|\d+[.)])\s+\S+")
_LIST_INTRO_RE = re.compile(r".+:\s*$")
def _normalize_pdf_lines(page_text: str) -> list[str]:
lines = [ln.rstrip() for ln in page_text.splitlines()]
out: list[str] = []
for ln in lines:
if _PAGE_NUMBER_RE.match(ln):
out.append("")
else:
out.append(ln)
return out
def _median_int(values: list[int]) -> int:
if not values:
return 0
vals = sorted(values)
mid = len(vals) // 2
if len(vals) % 2:
return vals[mid]
return int(round((vals[mid - 1] + vals[mid]) / 2))
def _detect_runt_final_page(
pages: list[str],
*,
min_ratio: float,
min_lines: int,
) -> tuple[int, list[LayoutIncident]]:
if len(pages) < 2:
return 0, []
line_counts = []
for page in pages:
lines = [ln for ln in _normalize_pdf_lines(page) if ln.strip()]
line_counts.append(len(lines))
last_lines = line_counts[-1] if line_counts else 0
sample_counts = [c for c in line_counts[:-1] if c >= max(4, min_lines)]
if not sample_counts:
return 0, []
typical = _median_int(sample_counts)
threshold = max(min_lines, int(round(typical * min_ratio)))
if last_lines >= threshold:
return 0, []
lines = [ln.strip() for ln in _normalize_pdf_lines(pages[-1]) if ln.strip()]
snippet = " | ".join(lines[:3])
incident = LayoutIncident(
kind="runt_final_page_pdf",
detail=f"page={len(pages)} lines={last_lines} threshold={threshold} typical={typical}",
context=snippet or None,
)
return 1, [incident]
def _non_empty_line_indices(lines: list[str]) -> list[int]:
return [i for i, ln in enumerate(lines) if ln.strip()]
def _caption_line_kind(line: str) -> str | None:
s = line.strip()
if not s:
return None
match = _CAPTION_RE.match(s)
if not match:
return None
return match.group(1).lower().rstrip(".")
def _page_edge_info(page_text: str) -> dict[str, object]:
lines = _normalize_pdf_lines(page_text)
if not any(ln.strip() for ln in lines):
return {
"leading_lines": 0,
"trailing_lines": 0,
"leading_blank": True,
"trailing_blank": True,
"leading_snippet": "",
"trailing_snippet": "",
}
first_idx = next(i for i, ln in enumerate(lines) if ln.strip())
last_idx = len(lines) - 1 - next(i for i, ln in enumerate(reversed(lines)) if ln.strip())
leading_blank = first_idx > 0
trailing_blank = last_idx < len(lines) - 1
trimmed = lines[first_idx : last_idx + 1]
leading_lines = 0
leading_snip: list[str] = []
for ln in trimmed:
if not ln.strip():
break
leading_lines += 1
if len(leading_snip) < 3:
leading_snip.append(ln.strip())
trailing_lines = 0
trailing_snip: list[str] = []
for ln in reversed(trimmed):
if not ln.strip():
break
trailing_lines += 1
if len(trailing_snip) < 3:
trailing_snip.append(ln.strip())
trailing_snip = list(reversed(trailing_snip))
return {
"leading_lines": leading_lines,
"trailing_lines": trailing_lines,
"leading_blank": leading_blank,
"trailing_blank": trailing_blank,
"leading_snippet": " ".join(leading_snip).strip(),
"trailing_snippet": " ".join(trailing_snip).strip(),
}
def _detect_widows_orphans(pages: list[str]) -> tuple[list[int], list[int], list[LayoutIncident]]:
widows = [0 for _ in pages]
orphans = [0 for _ in pages]
incidents: list[LayoutIncident] = []
infos = [_page_edge_info(p) for p in pages]
for idx in range(len(pages) - 1):
cur = infos[idx]
nxt = infos[idx + 1]
if (
cur["trailing_lines"] == 0
or nxt["leading_lines"] == 0
or cur["trailing_blank"]
or nxt["leading_blank"]
):
continue
if cur["trailing_lines"] == 1:
orphans[idx] += 1
incidents.append(
LayoutIncident(
kind="orphan_pdf",
detail=f"page={idx + 1}",
context=str(cur.get("trailing_snippet") or "")[:140] or None,
)
)
if nxt["leading_lines"] == 1:
widows[idx + 1] += 1
incidents.append(
LayoutIncident(
kind="widow_pdf",
detail=f"page={idx + 2}",
context=str(nxt.get("leading_snippet") or "")[:140] or None,
)
)
return widows, orphans, incidents
def _is_heading_candidate(text: str, *, max_chars: int, blank_before: bool, blank_after: bool) -> bool:
s = text.strip()
if not s or len(s) > max_chars:
return False
if not re.search(r"[A-Za-z]", s):
return False
if re.match(r"^[-*+•]\s", s):
return False
if re.match(r"^\d+[\.)]\s", s):
return False
if re.search(r"[.!;]$", s):
return False
words = [w for w in re.split(r"\s+", s) if w]
if len(words) > 1:
upper_words = sum(1 for w in words if w[:1].isupper())
if upper_words / len(words) < 0.6 and not s.isupper():
return False
if not (blank_before or blank_after or s.isupper()):
return False
return True
def _detect_stranded_headings_pdf(
pages: list[str], keep_lines: int, heading_max_chars: int
) -> tuple[list[int], list[LayoutIncident]]:
counts = [0 for _ in pages]
incidents: list[LayoutIncident] = []
for idx in range(len(pages) - 1):
lines = _normalize_pdf_lines(pages[idx])
if not any(ln.strip() for ln in lines):
continue
candidate_idx = None
for i in range(len(lines) - 1, -1, -1):
s = lines[i].strip()
if not s:
continue
blank_before = i == 0 or not lines[i - 1].strip()
blank_after = i == len(lines) - 1 or not lines[i + 1].strip()
if _is_heading_candidate(s, max_chars=heading_max_chars, blank_before=blank_before, blank_after=blank_after):
candidate_idx = i
candidate_text = s
break
if len(s) > heading_max_chars:
continue
if candidate_idx is None:
continue
following = sum(1 for ln in lines[candidate_idx + 1 :] if ln.strip())
if following < keep_lines:
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="stranded_heading_pdf",
detail=f"page={idx + 1}",
context=str(candidate_text)[:140] or None,
)
)
return counts, incidents
def _detect_caption_separation_pdf(pages: list[str]) -> tuple[list[int], list[LayoutIncident]]:
counts = [0 for _ in pages]
incidents: list[LayoutIncident] = []
for idx, page in enumerate(pages):
lines = _normalize_pdf_lines(page)
non_empty = _non_empty_line_indices(lines)
if not non_empty:
continue
first_non = non_empty[0]
last_non = non_empty[-1]
edge_window = {non_empty[0], non_empty[1] if len(non_empty) > 1 else non_empty[0], non_empty[-1]}
if len(non_empty) > 1:
edge_window.add(non_empty[-2])
for line_idx in non_empty:
kind = _caption_line_kind(lines[line_idx])
if not kind:
continue
at_top = line_idx in edge_window and line_idx <= first_non + 1
at_bottom = line_idx in edge_window and line_idx >= last_non - 1
sparse_page = len(non_empty) <= 5
if not (at_top or at_bottom or sparse_page):
continue
pos = "top" if at_top else "bottom" if at_bottom else "sparse"
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="caption_separation_pdf",
detail=f"page={idx + 1} pos={pos}",
context=str(lines[line_idx].strip())[:140] or None,
)
)
return counts, incidents
def _detect_list_breaks_pdf(pages: list[str]) -> tuple[list[int], list[LayoutIncident]]:
counts = [0 for _ in pages]
incidents: list[LayoutIncident] = []
for idx, page in enumerate(pages):
lines = _normalize_pdf_lines(page)
non_empty = _non_empty_line_indices(lines)
if not non_empty:
continue
list_lines = [i for i in non_empty if _LIST_ITEM_RE.match(lines[i])]
if len(list_lines) == 1:
lone_idx = list_lines[0]
if lone_idx == non_empty[0] or lone_idx == non_empty[-1]:
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="list_lonely_item_pdf",
detail=f"page={idx + 1}",
context=str(lines[lone_idx].strip())[:140] or None,
)
)
last_idx = non_empty[-1]
if _LIST_INTRO_RE.search(lines[last_idx].strip()) and idx + 1 < len(pages):
next_lines = _normalize_pdf_lines(pages[idx + 1])
next_non_empty = _non_empty_line_indices(next_lines)
if next_non_empty and _LIST_ITEM_RE.match(next_lines[next_non_empty[0]]):
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="list_intro_separated_pdf",
detail=f"page={idx + 1} -> {idx + 2}",
context=str(lines[last_idx].strip())[:140] or None,
)
)
return counts, incidents
def _collect_heading_candidates(lines: list[str], max_chars: int) -> set[int]:
candidates: set[int] = set()
for i, line in enumerate(lines):
s = line.strip()
if not s:
continue
blank_before = i == 0 or not lines[i - 1].strip()
blank_after = i == len(lines) - 1 or not lines[i + 1].strip()
if _is_heading_candidate(s, max_chars=max_chars, blank_before=blank_before, blank_after=blank_after):
candidates.add(i)
return candidates
def _detect_heading_proximity_pdf(pages: list[str], heading_max_chars: int) -> tuple[list[int], list[LayoutIncident]]:
counts = [0 for _ in pages]
incidents: list[LayoutIncident] = []
for idx, page in enumerate(pages):
lines = _normalize_pdf_lines(page)
non_empty = _non_empty_line_indices(lines)
if not non_empty:
continue
candidates = _collect_heading_candidates(lines, heading_max_chars)
for line_idx in non_empty:
if line_idx not in candidates:
continue
next_idx = next((j for j in non_empty if j > line_idx), None)
if next_idx is not None and next_idx in candidates:
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="heading_proximity_pdf",
detail=f"page={idx + 1}",
context=str(lines[line_idx].strip())[:140] or None,
)
)
break
last_idx = non_empty[-1]
if last_idx in candidates and idx + 1 < len(pages):
next_lines = _normalize_pdf_lines(pages[idx + 1])
next_non_empty = _non_empty_line_indices(next_lines)
if next_non_empty:
next_candidates = _collect_heading_candidates(next_lines, heading_max_chars)
if next_non_empty[0] in next_candidates:
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="heading_proximity_pdf",
detail=f"page={idx + 1} -> {idx + 2}",
context=str(lines[last_idx].strip())[:140] or None,
)
)
return counts, incidents
def _detect_pdf_overfull_lines(pages: list[str], max_chars: int) -> tuple[list[int], list[LayoutIncident]]:
counts = [0 for _ in pages]
incidents: list[LayoutIncident] = []
for idx, page in enumerate(pages):
lines = _normalize_pdf_lines(page)
for ln in lines:
if not ln.strip():
continue
if len(ln) > max_chars:
counts[idx] += 1
incidents.append(
LayoutIncident(
kind="overfull_line_pdf",
detail=f"page={idx + 1} line_len={len(ln)}",
context=ln.strip()[:140] or None,
)
)
return counts, incidents
def _detect_pdf_bbox_overflow(
pages: list[dict[str, Any]],
*,
tolerance: float = 2.0,
max_incidents_per_page: int = 5,
) -> tuple[list[int], list[LayoutIncident]]:
counts = [0 for _ in pages]
incidents: list[LayoutIncident] = []
for idx, page in enumerate(pages):
width = float(page.get("width") or 0)
height = float(page.get("height") or 0)
if width <= 0 or height <= 0:
continue
page_number = int(page.get("number") or (idx + 1))
for text in page.get("texts", []) or []:
if counts[idx] >= max_incidents_per_page:
break
left = float(text.get("left") or 0)
top = float(text.get("top") or 0)
box_w = float(text.get("width") or 0)
box_h = float(text.get("height") or 0)
if box_w <= 0 or box_h <= 0:
continue
right = left + box_w
bottom = top + box_h
if right <= width + tolerance and bottom <= height + tolerance and left >= -tolerance and top >= -tolerance:
continue
overflow_x = right - width
overflow_y = bottom - height
snippet = str(text.get("text") or "").strip()[:120] or None
incidents.append(
LayoutIncident(
kind="overfull_bbox_pdf",
detail=f"page={page_number} overflow_x={overflow_x:.1f} overflow_y={overflow_y:.1f}",
context=snippet,
)
)
counts[idx] += 1
return counts, incidents
_URL_RE = re.compile(r"(?i)\bhttps?://[^\s<>\"]+")
_WWW_RE = re.compile(r"(?i)\bwww\.[^\s<>\"]+")
_DOI_RE = re.compile(r"\b10\.\d{4,9}/[^\s<>\"']+")
_EMAIL_RE = re.compile(r"(?i)\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b")
def _normalize_link_token(token: str) -> str:
token = token.strip()
token = token.strip("<>")
token = token.strip("()[]{}")
token = token.rstrip(".,;:!?)]}\"'")
return token
def _extract_link_like_tokens(text: str) -> list[str]:
if not text:
return []
tokens: list[str] = []
for match in _URL_RE.findall(text):
norm = _normalize_link_token(match)
if norm:
tokens.append(norm)
for match in _WWW_RE.findall(text):
norm = _normalize_link_token(match)
if norm:
tokens.append(norm)
for match in _DOI_RE.findall(text):
norm = _normalize_link_token(match)
if norm:
tokens.append(norm)
for match in _EMAIL_RE.findall(text):
norm = _normalize_link_token(match)
if norm:
tokens.append(norm)
return tokens
````
### `iftypeset/src/iftypeset/rendering.py`
- bytes: `44833`
- sha256: `1b2bef12fae692e63c7f279d468fb8ca9f2c6f34bd5a4be94671809a2a4ace1a`
````py
from __future__ import annotations
from dataclasses import dataclass
from datetime import datetime, timezone
import base64
import html
import importlib
import importlib.util
import json
import math
import mimetypes
import os
from pathlib import Path
import re
import shutil
import subprocess
import sys
import tempfile
from typing import Any
from iftypeset import __version__
from iftypeset.css_gen import generate_profile_css
from iftypeset.md_parser import MdDocument, parse_markdown, read_markdown
_NBSP_TOKEN = "{{NBSP}}"
_DEFAULT_WEAK_WORDS = {
"and",
"to",
"with",
"in",
"for",
"of",
"on",
"at",
"by",
"from",
"under",
"into",
"over",
"hit",
}
@dataclass(frozen=True)
class HtmlRenderResult:
html: str
css: str
warnings: list[str]
degraded: dict[str, list[str]]
typeset_report: dict[str, Any]
doc_title: str
@dataclass(frozen=True)
class InlineOptions:
small_caps_acronyms: bool
small_caps_min_letters: int
@dataclass(frozen=True)
class PdfRenderResult:
ok: bool
engine: str | None
pdf_path: str | None
log: dict[str, Any]
def render_html(
input_path: Path,
profile: dict[str, Any],
*,
self_contained: bool = False,
) -> HtmlRenderResult:
raw_text, read_reasons = read_markdown(input_path)
doc = parse_markdown(input_path, raw_text)
degraded: dict[str, list[str]] = {}
reasons = read_reasons + doc.degraded_reasons
if reasons:
degraded[str(input_path)] = reasons
css_out = generate_profile_css(profile)
warnings: list[str] = []
doc_title = _doc_title(doc)
inline_opts = _inline_options_from_profile(profile)
density = _auto_density(doc, profile)
body_class = "if-doc"
if density:
body_class += f" if-density-{density}"
html_out = _render_doc(
doc,
profile=profile,
base_path=input_path.parent,
self_contained=self_contained,
warnings=warnings,
doc_title=doc_title,
inline_opts=inline_opts,
body_class=body_class,
)
html_out = _balance_lists_with_chromium(html_out, profile, warnings)
typeset_report = dict(css_out.report)
doc_stats = _doc_stats(doc)
if density:
typeset_report["auto_density"] = density
typeset_report["doc_stats"] = doc_stats
return HtmlRenderResult(
html=html_out,
css=css_out.css,
warnings=warnings,
degraded=degraded,
typeset_report=typeset_report,
doc_title=doc_title,
)
def _inline_options_from_profile(profile: dict[str, Any]) -> InlineOptions:
typography = profile.get("typography") or {}
small_caps_cfg = typography.get("small_caps_acronyms")
enabled = False
min_letters = 2
if isinstance(small_caps_cfg, dict):
enabled = bool(small_caps_cfg.get("enabled") or False)
min_letters = int(small_caps_cfg.get("min_letters") or 2)
elif isinstance(small_caps_cfg, bool):
enabled = small_caps_cfg
return InlineOptions(small_caps_acronyms=enabled, small_caps_min_letters=min_letters)
def _running_head_config(profile: dict[str, Any], *, doc_title: str) -> dict[str, str] | None:
cfg = profile.get("running_head") or {}
if not isinstance(cfg, dict) or not cfg.get("enabled"):
return None
placement = str(cfg.get("placement") or "footer")
template = str(cfg.get("template") or "{page} | {title}")
font_size = str(cfg.get("font_size") or "9pt")
font_style = str(cfg.get("font_style") or "italic")
color = str(cfg.get("color") or "#6b7280")
date = str(cfg.get("date") or "")
base = template.replace("{title}", doc_title).replace("{date}", date)
return {
"placement": placement,
"template": base,
"font_size": font_size,
"font_style": font_style,
"color": color,
}
def detect_pdf_engines() -> list[dict[str, Any]]:
engines: list[dict[str, Any]] = []
if importlib.util.find_spec("playwright"):
engines.append({"name": "playwright", "detail": "python-module"})
chromium_path = _find_executable(["chromium", "chromium-browser", "google-chrome", "chrome"])
if chromium_path:
engines.append({"name": "chromium", "detail": chromium_path})
wk_path = _find_executable(["wkhtmltopdf"])
if wk_path:
engines.append({"name": "wkhtmltopdf", "detail": wk_path})
if importlib.util.find_spec("weasyprint"):
engines.append({"name": "weasyprint", "detail": "python-module"})
return engines
def renderer_info() -> dict[str, Any]:
engines = detect_pdf_engines()
return {"pdf_engines_detected": engines, "pdf_engine_versions": _engine_versions(engines)}
def render_pdf(
input_path: Path,
profile: dict[str, Any],
out_dir: Path,
*,
engine_name: str | None = None,
self_contained: bool = False,
) -> PdfRenderResult:
out_dir.mkdir(parents=True, exist_ok=True)
html_result = render_html(input_path, profile, self_contained=self_contained)
html_path = out_dir / "render.html"
css_path = out_dir / "render.css"
html_path.write_text(html_result.html, encoding="utf-8")
css_path.write_text(html_result.css, encoding="utf-8")
(out_dir / "typeset-report.json").write_text(
json.dumps(html_result.typeset_report, indent=2, sort_keys=True) + "\n", encoding="utf-8"
)
engines = detect_pdf_engines()
log = _base_render_log(engines, html_result.warnings)
running_head = _running_head_config(profile, doc_title=html_result.doc_title)
if running_head:
log["running_head"] = {k: v for k, v in running_head.items() if k != "template"}
if engine_name:
log["requested_engine"] = engine_name
if not engines:
log["ok"] = False
log["error"] = "No PDF renderer detected. Install playwright, chromium, wkhtmltopdf, or weasyprint."
return PdfRenderResult(ok=False, engine=None, pdf_path=None, log=log)
chosen = engines[0]
if engine_name and engine_name.lower() != "auto":
requested = engine_name.lower()
chosen = next((entry for entry in engines if entry.get("name") == requested), None)
if not chosen:
available = ", ".join(sorted({str(entry.get("name")) for entry in engines if entry.get("name")}))
log["ok"] = False
log["error"] = f"Requested engine '{engine_name}' not available. Available: {available}"
return PdfRenderResult(ok=False, engine=None, pdf_path=None, log=log)
engine = str(chosen.get("name"))
pdf_path = out_dir / "render.pdf"
log["engine"] = engine
log["engine_versions"] = _engine_versions(engines)
log["html_path"] = str(html_path)
log["pdf_path"] = str(pdf_path)
try:
if engine == "playwright":
_render_pdf_playwright(html_path, pdf_path, running_head=running_head)
elif engine == "chromium":
detail = chosen.get("detail")
if not isinstance(detail, str):
raise RuntimeError("Chromium engine selected but executable path is missing.")
if running_head:
log["warnings"].append(
"Running head requested but chromium CLI does not support header/footer templates."
)
_render_pdf_chromium(html_path, pdf_path, detail)
elif engine == "wkhtmltopdf":
detail = chosen.get("detail")
if not isinstance(detail, str):
raise RuntimeError("wkhtmltopdf engine selected but executable path is missing.")
_render_pdf_wkhtmltopdf(html_path, pdf_path, detail, running_head=running_head)
elif engine == "weasyprint":
if running_head:
log["warnings"].append(
"Running head requested but weasyprint adapter does not inject headers yet."
)
_render_pdf_weasyprint(html_path, pdf_path)
else:
raise RuntimeError(f"Unknown engine: {engine}")
except Exception as e: # noqa: BLE001
log["ok"] = False
log["error"] = str(e)
return PdfRenderResult(ok=False, engine=engine, pdf_path=None, log=log)
log["ok"] = True
return PdfRenderResult(ok=True, engine=engine, pdf_path=str(pdf_path), log=log)
def _render_doc(
doc: MdDocument,
*,
profile: dict[str, Any],
base_path: Path,
self_contained: bool,
warnings: list[str],
doc_title: str,
inline_opts: InlineOptions,
body_class: str,
) -> str:
title = doc_title
heading_ids: dict[str, int] = {}
body_lines: list[str] = []
section_open = False
current_section_slug: str | None = None
body_lines.append("<main>")
for block in doc.blocks:
if block.type == "heading":
level = block.level or 1
slug = _unique_slug(block.text, heading_ids)
if level == 2:
if section_open:
body_lines.append("</section>")
body_lines.append(f"<section class=\"if-section if-section-{slug}\">")
section_open = True
current_section_slug = slug
body_lines.append(
f"<h{level} id=\"{slug}\">{_render_inline(block.text, base_path, self_contained, warnings, inline_opts)}</h{level}>"
)
continue
if block.type == "paragraph":
img_only = _image_only_paragraph(block.text)
if img_only:
alt, url = img_only
src = _resolve_image_src(url, base_path, self_contained, warnings)
body_lines.append("<figure class=\"if-figure\">")
body_lines.append(f" <img src=\"{html.escape(src)}\" alt=\"{html.escape(alt)}\">")
body_lines.append("</figure>")
else:
body_lines.append(
f"<p>{_render_inline(block.text, base_path, self_contained, warnings, inline_opts)}</p>"
)
continue
if block.type == "list":
tag = "ol" if block.ordered else "ul"
body_lines.append(f"<{tag}>")
for item in block.items:
groomed = _groom_list_item_text(item, profile, current_section_slug)
rendered = _render_inline(groomed, base_path, self_contained, warnings, inline_opts)
rendered = rendered.replace(_NBSP_TOKEN, " ")
body_lines.append(
f" <li>{rendered}</li>"
)
body_lines.append(f"</{tag}>")
continue
if block.type == "code":
lang = block.info.strip()
class_attr = f" class=\"language-{html.escape(lang)}\"" if lang else ""
body_lines.append(f"<pre><code{class_attr}>{html.escape(block.text)}</code></pre>")
continue
if block.type == "blockquote":
body_lines.append(
f"<blockquote><p>{_render_inline(block.text, base_path, self_contained, warnings, inline_opts)}</p></blockquote>"
)
continue
if block.type == "table":
numeric_cols, bool_cols = _table_column_classes(block.headers, block.rows)
body_lines.append("<table>")
body_lines.append(" <thead>")
body_lines.append(" <tr>")
for idx, h in enumerate(block.headers):
class_attr = _table_class_attr(idx, numeric_cols, bool_cols)
body_lines.append(
f" <th{class_attr}>{_render_inline(h, base_path, self_contained, warnings, inline_opts)}</th>"
)
body_lines.append(" </tr>")
body_lines.append(" </thead>")
body_lines.append(" <tbody>")
for row in block.rows:
body_lines.append(" <tr>")
for idx, cell in enumerate(row):
class_attr = _table_class_attr(idx, numeric_cols, bool_cols)
body_lines.append(
f" <td{class_attr}>{_render_inline(cell, base_path, self_contained, warnings, inline_opts)}</td>"
)
body_lines.append(" </tr>")
body_lines.append(" </tbody>")
body_lines.append("</table>")
continue
if section_open:
body_lines.append("</section>")
body_lines.append("</main>")
html_lines: list[str] = []
html_lines.append("<!doctype html>")
html_lines.append("<html lang=\"en\">")
html_lines.append("<head>")
html_lines.append(" <meta charset=\"utf-8\">")
html_lines.append(" <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">")
html_lines.append(f" <title>{html.escape(title)}</title>")
html_lines.append(" <link rel=\"stylesheet\" href=\"render.css\">")
html_lines.append("</head>")
html_lines.append(f"<body class=\"{html.escape(body_class)}\">")
html_lines.extend([" " + line for line in body_lines])
html_lines.append("</body>")
html_lines.append("</html>")
return "\n".join(html_lines).rstrip() + "\n"
def _doc_title(doc: MdDocument) -> str:
for block in doc.blocks:
if block.type == "heading" and block.level == 1:
return block.text.strip() or doc.path.stem
return doc.path.stem
def _doc_stats(doc: MdDocument) -> dict[str, Any]:
counts = {"heading": 0, "paragraph": 0, "list": 0, "code": 0, "table": 0, "blockquote": 0}
char_count = 0
for block in doc.blocks:
counts[block.type] = counts.get(block.type, 0) + 1
if block.type == "list":
for item in block.items:
char_count += len(item)
else:
char_count += len(block.text)
return {"blocks": counts, "char_count": char_count}
def _groom_list_item_text(text: str, profile: dict[str, Any], section_slug: str | None) -> str:
heur = _list_wrap_heuristics(profile)
if not heur.get("enabled"):
return text
if _has_inline_markup(text):
return text
normalized = " ".join(text.split())
words = normalized.split()
if len(words) < 8:
return text
width = _list_item_measure(profile, section_slug, heur)
if not width or width < 30:
return text
min_tail_ratio = float(heur.get("min_tail_ratio") or 0.25)
min_tail_chars = int(heur.get("min_tail_chars") or 12)
weak_words = {w.lower() for w in (heur.get("weak_words") or _DEFAULT_WEAK_WORDS)}
max_shift = int(heur.get("max_shift_words") or 3)
min_tail = max(min_tail_chars, int(width * min_tail_ratio))
tokens = _build_tokens(words, set())
lines = _wrap_tokens(tokens, width)
if len(lines) <= 1:
return text
if _lines_ok(lines, tokens, min_tail, weak_words):
return text
locks = _group_tail_words(words, width, min_tail, weak_words)
if locks:
return _join_words_with_locks(words, locks)
boundary = _find_shift_boundary(words, width, min_tail, weak_words, max_shift)
if boundary is None:
return _join_weak_pairs(text, weak_words, max_pairs=1)
initial = _join_words_with_locks(words, {boundary})
if _has_nbsp_token(initial):
return initial
return _join_weak_pairs(initial, weak_words, max_pairs=1)
def _list_wrap_heuristics(profile: dict[str, Any]) -> dict[str, Any]:
lists_cfg = profile.get("lists") or {}
heur = lists_cfg.get("wrap_heuristics")
if isinstance(heur, dict):
enabled = heur.get("enabled")
if enabled is None:
heur = dict(heur)
heur["enabled"] = True
return heur
if isinstance(heur, bool):
return {"enabled": heur}
return {"enabled": True}
def _has_inline_markup(text: str) -> bool:
return bool(re.search(r"[`*_<>\\[]", text))
def _list_item_measure(
profile: dict[str, Any],
section_slug: str | None,
heuristics: dict[str, Any] | None = None,
) -> int | None:
measure = profile.get("measure_targets") or {}
body_chars = measure.get("body_chars_per_line") or {}
ideal = int(body_chars.get("ideal") or 66)
layout = profile.get("layout") or {}
overrides = layout.get("section_overrides") or {}
factor = 1.0
indent_chars = 0
if isinstance(heuristics, dict):
factor = float(heuristics.get("width_factor") or 1.0)
indent_chars = int(heuristics.get("indent_chars") or 0)
if section_slug:
for key, cfg in overrides.items():
if not isinstance(cfg, dict):
continue
if _slugify(str(key)) != section_slug:
continue
width = _parse_width_to_chars(cfg.get("list_item_width") or cfg.get("list_item_max_width"), ideal)
if width:
return max(20, int(round(width * factor)) - indent_chars)
return max(20, int(round(ideal * factor)) - indent_chars)
def _parse_width_to_chars(value: Any, ideal: int) -> int | None:
if value is None:
return None
if isinstance(value, int):
return value
if isinstance(value, float):
return int(round(value))
if not isinstance(value, str):
return None
text = value.strip().lower()
if text.endswith("ch"):
num = text[:-2].strip()
try:
return int(round(float(num)))
except ValueError:
return None
if text.endswith("%"):
num = text[:-1].strip()
try:
pct = float(num) / 100.0
except ValueError:
return None
return max(1, int(round(ideal * pct)))
return None
def _build_tokens(words: list[str], locks: set[int]) -> list[dict[str, Any]]:
tokens: list[dict[str, Any]] = []
i = 0
while i < len(words):
start = i
token = words[i]
while i < len(words) - 1 and i in locks:
token = f"{token}{_NBSP_TOKEN}{words[i + 1]}"
i += 1
end = i
tokens.append({"text": token, "start": start, "end": end})
i += 1
return tokens
def _wrap_tokens(tokens: list[dict[str, Any]], width: int) -> list[list[int]]:
lines: list[list[int]] = []
line: list[int] = []
line_len = 0
for idx, token in enumerate(tokens):
token_len = _token_display_len(token["text"])
add = token_len if not line else token_len + 1
if line and line_len + add > width:
lines.append(line)
line = [idx]
line_len = token_len
else:
line.append(idx)
line_len += add
if line:
lines.append(line)
return lines
def _token_display_len(text: str) -> int:
return len(text.replace(_NBSP_TOKEN, " "))
def _line_len(line: list[int], tokens: list[dict[str, Any]]) -> int:
total = 0
for i, idx in enumerate(line):
if i:
total += 1
total += _token_display_len(tokens[idx]["text"])
return total
def _lines_ok(
lines: list[list[int]],
tokens: list[dict[str, Any]],
min_tail: int,
weak_words: set[str],
) -> bool:
if len(lines) < 2:
return True
last_len = _line_len(lines[-1], tokens)
prev_last_word = _last_word(tokens[lines[-2][-1]]["text"])
return last_len >= min_tail and prev_last_word not in weak_words
def _group_tail_words(
words: list[str],
width: int,
min_tail: int,
weak_words: set[str],
) -> set[int]:
tokens = _build_tokens(words, set())
lines = _wrap_tokens(tokens, width)
if len(lines) < 2:
return set()
last_len = _line_len(lines[-1], tokens)
prev_last = _last_word(tokens[lines[-2][-1]]["text"])
if last_len >= min_tail and prev_last not in weak_words:
return set()
tail_len = 0
idx = len(words) - 1
while idx >= 0:
word = words[idx]
tail_len += len(word) + (1 if tail_len else 0)
if tail_len >= min_tail:
break
idx -= 1
if idx <= 0 or tail_len > width:
return set()
start = idx
end = len(words) - 1
if prev_last in weak_words:
boundary = _boundary_between_lines(lines[-2], lines[-1], tokens)
if boundary is None:
return set()
start = max(start, boundary)
return set(range(start, end))
def _last_word(text: str) -> str:
cleaned = text.replace(_NBSP_TOKEN, " ").strip()
parts = cleaned.split()
return parts[-1].lower() if parts else ""
def _boundary_between_lines(
prev_line: list[int],
next_line: list[int],
tokens: list[dict[str, Any]],
) -> int | None:
if not prev_line or not next_line:
return None
prev_last = tokens[prev_line[-1]]
return int(prev_last["end"])
def _find_shift_boundary(
words: list[str],
width: int,
min_tail: int,
weak_words: set[str],
max_shift: int,
) -> int | None:
base_tokens = _build_tokens(words, set())
base_lines = _wrap_tokens(base_tokens, width)
if len(base_lines) < 2:
return None
base_last_len = _line_len(base_lines[-1], base_tokens)
base_prev_last = _last_word(base_tokens[base_lines[-2][-1]]["text"])
boundary = _boundary_between_lines(base_lines[-2], base_lines[-1], base_tokens)
if boundary is None:
return None
if base_prev_last in weak_words:
return boundary
tokens = _build_tokens(words, {boundary})
lines = _wrap_tokens(tokens, width)
if len(lines) >= 2:
last_len = _line_len(lines[-1], tokens)
prev_last = _last_word(tokens[lines[-2][-1]]["text"])
if last_len >= min_tail and prev_last not in weak_words:
return boundary
best: int | None = None
best_last_len = base_last_len
best_no_weak = base_prev_last not in weak_words
for shift in range(1, max_shift + 1):
cand = boundary - shift
if cand < 0:
break
tokens = _build_tokens(words, {cand})
lines = _wrap_tokens(tokens, width)
if len(lines) < 2:
continue
last_len = _line_len(lines[-1], tokens)
prev_last = _last_word(tokens[lines[-2][-1]]["text"])
no_weak = prev_last not in weak_words
if last_len >= min_tail and no_weak:
return cand
if last_len > best_last_len or (last_len == best_last_len and no_weak and not best_no_weak):
best = cand
best_last_len = last_len
best_no_weak = no_weak
if best is None:
return None
if best_last_len > base_last_len:
return best
if best_no_weak and not (base_prev_last not in weak_words):
return best
return None
def _join_words_with_locks(words: list[str], locks: set[int]) -> str:
out: list[str] = []
for idx, word in enumerate(words):
out.append(word)
if idx < len(words) - 1:
sep = _NBSP_TOKEN if idx in locks else " "
out.append(sep)
return "".join(out)
def _join_weak_pairs(text: str, weak_words: set[str], max_pairs: int) -> str:
if max_pairs <= 0:
return text
words = text.split(" ")
changed = 0
for i in range(len(words) - 1):
clean = words[i].replace(_NBSP_TOKEN, "").strip(" ,.;:()[]")
if clean.lower() in weak_words:
if _NBSP_TOKEN not in words[i]:
words[i] = f"{words[i]}{_NBSP_TOKEN}{words[i + 1]}"
words.pop(i + 1)
changed += 1
if changed >= max_pairs:
break
return " ".join(words)
def _has_nbsp_token(text: str) -> bool:
return _NBSP_TOKEN in text
def _balance_lists_with_chromium(html_doc: str, profile: dict[str, Any], warnings: list[str]) -> str:
heur = _list_wrap_heuristics(profile)
if not heur.get("balance_with_chromium"):
return html_doc
css = generate_profile_css(profile).css
chromium_path = _find_executable(["chromium", "chromium-browser", "google-chrome", "chrome"])
if not chromium_path:
warnings.append("List balancing skipped: chromium not available for layout-aware pass.")
return html_doc
script = _balance_script(heur, css)
if not script:
return html_doc
injected = _inject_script(html_doc, script)
with tempfile.TemporaryDirectory(prefix="iftypeset-balance-") as tmpdir:
html_path = Path(tmpdir) / "balance.html"
html_path.write_text(injected, encoding="utf-8")
cmd = [
chromium_path,
"--headless",
"--disable-gpu",
"--virtual-time-budget=2000",
"--allow-file-access-from-files",
"--dump-dom",
html_path.resolve().as_uri(),
]
if os.geteuid() == 0:
cmd.insert(1, "--no-sandbox")
result = subprocess.run(cmd, capture_output=True, text=True, check=False)
if result.returncode != 0:
warnings.append(f"List balancing failed: chromium exited {result.returncode}.")
return html_doc
output = result.stdout.strip()
if "<!doctype html>" not in output.lower():
warnings.append("List balancing failed: chromium did not return HTML.")
return html_doc
return output
def _inject_script(html_doc: str, script: str) -> str:
marker = "</body>"
if marker in html_doc:
return html_doc.replace(marker, script + marker)
return html_doc + script
def _balance_script(heuristics: dict[str, Any], css: str) -> str:
min_tail_ratio = float(heuristics.get("min_tail_ratio") or 0.25)
min_tail_chars = int(heuristics.get("min_tail_chars") or 12)
max_passes = int(heuristics.get("max_passes") or 2)
weak_words = heuristics.get("weak_words") or sorted(_DEFAULT_WEAK_WORDS)
if not weak_words:
weak_words = sorted(_DEFAULT_WEAK_WORDS)
config = {
"minTailRatio": min_tail_ratio,
"minTailChars": min_tail_chars,
"maxPasses": max_passes,
"weakWords": weak_words,
}
payload = json.dumps(config)
return (
f"<style id=\"iftypeset-balance-css\">{css}</style>\n"
"<script>\n"
f"const IF_BALANCE_CFG = {payload};\n"
"(function(){\n"
" const cfg = IF_BALANCE_CFG;\n"
" const weak = new Set((cfg.weakWords || []).map(w => String(w).toLowerCase()));\n"
" function isPlain(li){\n"
" return !Array.from(li.childNodes).some(n => n.nodeType === 1);\n"
" }\n"
" function wrapWords(li, words){\n"
" li.textContent = '';\n"
" words.forEach((w,i)=>{\n"
" const span = document.createElement('span');\n"
" span.textContent = w;\n"
" span.dataset.idx = String(i);\n"
" li.appendChild(span);\n"
" if(i < words.length-1){ li.appendChild(document.createTextNode(' ')); }\n"
" });\n"
" }\n"
" function measureLines(li){\n"
" const spans = Array.from(li.querySelectorAll('span[data-idx]'));\n"
" const lines = [];\n"
" spans.forEach(span => {\n"
" const rect = span.getBoundingClientRect();\n"
" const top = Math.round(rect.top);\n"
" let line = lines.find(l => Math.abs(l.top - top) <= 1);\n"
" if(!line){ line = {top: top, spans: []}; lines.push(line); }\n"
" line.spans.push(span);\n"
" });\n"
" lines.sort((a,b)=>a.top-b.top);\n"
" return lines;\n"
" }\n"
" function lineText(line){\n"
" return line.spans.map(s=>s.textContent).join(' ');\n"
" }\n"
" function balanceLi(li){\n"
" if(!isPlain(li)) return;\n"
" const raw = li.textContent.trim();\n"
" if(!raw) return;\n"
" const words = raw.split(/\\s+/);\n"
" if(words.length < 6) return;\n"
" for(let pass=0; pass<cfg.maxPasses; pass++){\n"
" wrapWords(li, words);\n"
" const lines = measureLines(li);\n"
" if(lines.length <= 1){ li.textContent = words.join(' '); return; }\n"
" const last = lines[lines.length-1];\n"
" const prev = lines[lines.length-2];\n"
" const lastText = lineText(last);\n"
" const prevText = lineText(prev);\n"
" const minTail = Math.max(cfg.minTailChars, Math.round(prevText.length * cfg.minTailRatio));\n"
" const prevLast = prev.spans[prev.spans.length-1].textContent.toLowerCase();\n"
" if(lastText.length >= minTail && !weak.has(prevLast)){\n"
" li.textContent = words.join(' ');\n"
" return;\n"
" }\n"
" const boundary = parseInt(prev.spans[prev.spans.length-1].dataset.idx || '-1', 10);\n"
" if(boundary < 0 || boundary >= words.length-1){\n"
" li.textContent = words.join(' ');\n"
" return;\n"
" }\n"
" words[boundary] = words[boundary] + '\\u00A0' + words[boundary+1];\n"
" words.splice(boundary+1, 1);\n"
" }\n"
" li.textContent = words.join(' ');\n"
" }\n"
" window.addEventListener('load', () => {\n"
" document.querySelectorAll('li').forEach(balanceLi);\n"
" const style = document.getElementById('iftypeset-balance-css');\n"
" if(style){ style.remove(); }\n"
" if(document.currentScript){ document.currentScript.remove(); }\n"
" });\n"
"})();\n"
"</script>\n"
)
def _auto_density(doc: MdDocument, profile: dict[str, Any]) -> str | None:
layout = profile.get("layout") or {}
if not layout.get("auto_density"):
return None
thresholds = layout.get("density_thresholds") or {}
tight_over = int(thresholds.get("tight_over") or 46)
loose_under = int(thresholds.get("loose_under") or 34)
estimated_lines = _estimate_line_count(doc, profile)
if estimated_lines >= tight_over:
return "tight"
if estimated_lines <= loose_under:
return "loose"
return "normal"
def _estimate_line_count(doc: MdDocument, profile: dict[str, Any]) -> int:
measure = profile.get("measure_targets") or {}
body_chars = measure.get("body_chars_per_line") or {}
ideal = int(body_chars.get("ideal") or 66)
total = 0
for block in doc.blocks:
if block.type == "heading":
total += max(1, math.ceil(len(block.text) / ideal))
elif block.type == "paragraph":
parts = block.text.split("\n")
for part in parts:
total += max(1, math.ceil(len(part) / ideal))
elif block.type == "list":
for item in block.items:
total += max(1, math.ceil(len(item) / ideal))
elif block.type == "code":
lines = block.text.splitlines() or [""]
total += len(lines)
elif block.type == "table":
total += max(1, len(block.rows) + 1)
elif block.type == "blockquote":
total += max(1, math.ceil(len(block.text) / ideal))
return total
def _unique_slug(text: str, used: dict[str, int]) -> str:
slug = _slugify(text)
if slug not in used:
used[slug] = 1
return slug
used[slug] += 1
return f"{slug}-{used[slug]}"
def _slugify(text: str) -> str:
slug = re.sub(r"[^a-z0-9\\s-]", "", text.lower())
slug = re.sub(r"\\s+", "-", slug.strip())
return slug or "section"
def _table_column_classes(headers: list[str], rows: list[list[str]]) -> tuple[set[int], set[int]]:
col_count = len(headers)
for row in rows:
col_count = max(col_count, len(row))
numeric_cols: set[int] = set()
bool_cols: set[int] = set()
for col in range(col_count):
values = []
for row in rows:
if col < len(row):
values.append(row[col])
if not values:
continue
if _is_boolean_column(values):
bool_cols.add(col)
continue
if _is_numeric_column(values):
numeric_cols.add(col)
return numeric_cols, bool_cols
def _table_class_attr(col_idx: int, numeric_cols: set[int], bool_cols: set[int]) -> str:
if col_idx in bool_cols:
return " class=\"if-bool\""
if col_idx in numeric_cols:
return " class=\"if-num\""
return ""
def _is_numeric_cell(text: str) -> bool:
clean = _strip_inline_markup(text).strip()
if not clean:
return False
if re.search(r"[A-Za-z]", clean):
return False
if clean.lower() in {"n/a", "na"}:
return True
return bool(re.fullmatch(r"[\\s\\(\\)\\[\\]\\+\\-−–—$€£¥%.,/0-9]+", clean))
def _is_numeric_column(values: list[str]) -> bool:
candidates = [v for v in values if _strip_inline_markup(v).strip()]
if not candidates:
return False
numeric_hits = sum(1 for value in candidates if _is_numeric_cell(value))
return numeric_hits / max(len(candidates), 1) >= 0.6
def _is_boolean_column(values: list[str]) -> bool:
tokens = []
for value in values:
clean = _strip_inline_markup(value).strip().lower()
if not clean:
continue
tokens.append(clean)
if not tokens:
return False
bool_tokens = {"yes", "no", "y", "n", "true", "false", "✓", "✔", "✗", "x"}
neutral_tokens = {"n/a", "na", "—", "-", "—-", "–", "—"}
significant = [t for t in tokens if t not in neutral_tokens]
if not significant:
return True
if all(t in bool_tokens for t in significant):
return True
hits = sum(1 for t in significant if t in bool_tokens)
return hits / max(len(significant), 1) >= 0.8
def _strip_inline_markup(text: str) -> str:
without_links = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
return re.sub(r"[`*_]", "", without_links)
def _render_inline(
text: str,
base_path: Path,
self_contained: bool,
warnings: list[str],
inline_opts: InlineOptions,
) -> str:
out: list[str] = []
buffer: list[str] = []
def flush_buffer() -> None:
if not buffer:
return
segment = "".join(buffer)
out.append(_render_text_segment(segment, inline_opts))
buffer.clear()
i = 0
while i < len(text):
if text[i] == "`":
j = text.find("`", i + 1)
if j == -1:
buffer.append(text[i:])
break
flush_buffer()
code_text = text[i + 1 : j]
out.append(f"<code>{html.escape(code_text)}</code>")
i = j + 1
continue
if text[i] == "\n":
flush_buffer()
out.append("<br>")
i += 1
continue
if text[i] == "!" and i + 1 < len(text) and text[i + 1] == "[":
img = _parse_bracket_link(text, i + 1)
if img:
flush_buffer()
alt, url, end_idx = img
src = _resolve_image_src(url, base_path, self_contained, warnings)
out.append(f"<img src=\"{html.escape(src)}\" alt=\"{html.escape(alt)}\">")
i = end_idx
continue
if text[i] == "[":
link = _parse_bracket_link(text, i)
if link:
flush_buffer()
label, url, end_idx = link
out.append(f"<a href=\"{html.escape(url)}\">{html.escape(label)}</a>")
i = end_idx
continue
cite = _parse_citation_token(text, i)
if cite:
flush_buffer()
token, end_idx = cite
out.append(f"<span class=\"if-citation\">{html.escape(token)}</span>")
i = end_idx
continue
buffer.append(text[i])
i += 1
flush_buffer()
return "".join(out)
def _render_text_segment(text: str, inline_opts: InlineOptions) -> str:
tokens = _split_emphasis_tokens(text)
rendered: list[str] = []
for kind, segment in tokens:
if not segment:
continue
if inline_opts.small_caps_acronyms:
content = _wrap_small_caps_tokens(segment, min_letters=inline_opts.small_caps_min_letters)
else:
content = html.escape(segment)
if kind == "strong":
rendered.append(f"<strong>{content}</strong>")
elif kind == "em":
rendered.append(f"<em>{content}</em>")
else:
rendered.append(content)
return "".join(rendered)
def _split_emphasis_tokens(text: str) -> list[tuple[str, str]]:
tokens: list[tuple[str, str]] = []
buffer: list[str] = []
i = 0
while i < len(text):
if text.startswith("**", i):
end = text.find("**", i + 2)
if end != -1:
if buffer:
tokens.append(("plain", "".join(buffer)))
buffer.clear()
tokens.append(("strong", text[i + 2 : end]))
i = end + 2
continue
if text[i] == "*":
end = text.find("*", i + 1)
if end != -1:
if buffer:
tokens.append(("plain", "".join(buffer)))
buffer.clear()
tokens.append(("em", text[i + 1 : end]))
i = end + 1
continue
buffer.append(text[i])
i += 1
if buffer:
tokens.append(("plain", "".join(buffer)))
return tokens
def _wrap_small_caps_tokens(text: str, *, min_letters: int) -> str:
pattern = re.compile(r"\b[0-9A-Z][0-9A-Z&/.\-]*\b")
out: list[str] = []
last = 0
for match in pattern.finditer(text):
token = match.group(0)
letters = [ch for ch in token if ch.isalpha()]
if len(letters) < min_letters or any(ch.islower() for ch in letters):
continue
out.append(html.escape(text[last : match.start()]))
out.append(f"<span class=\"if-sc\">{html.escape(token)}</span>")
last = match.end()
out.append(html.escape(text[last:]))
return "".join(out)
def _image_only_paragraph(text: str) -> tuple[str, str] | None:
stripped = text.strip()
if not (stripped.startswith("![") and len(stripped) > 3):
return None
img = _parse_bracket_link(stripped, 1)
if not img:
return None
alt, url, end_idx = img
if end_idx != len(stripped):
return None
return alt, url
def _parse_bracket_link(text: str, idx: int) -> tuple[str, str, int] | None:
if text[idx] != "[":
return None
close = text.find("]", idx + 1)
if close == -1 or close + 1 >= len(text) or text[close + 1] != "(":
return None
end = text.find(")", close + 2)
if end == -1:
return None
label = text[idx + 1 : close]
url = text[close + 2 : end].strip()
return label, url, end + 1
def _parse_citation_token(text: str, idx: int) -> tuple[str, int] | None:
if text[idx] != "[":
return None
match = re.match(r"\\[S\\d{2,4}\\]", text[idx:])
if not match:
return None
token = match.group(0)
return token, idx + len(token)
def _resolve_image_src(url: str, base_path: Path, self_contained: bool, warnings: list[str]) -> str:
if not self_contained:
return url
if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:", url):
return url
img_path = (base_path / url).resolve()
if not img_path.exists() or not img_path.is_file():
warnings.append(f"Image not found for embedding: {url}")
return url
mime = mimetypes.guess_type(str(img_path))[0] or "application/octet-stream"
data = base64.b64encode(img_path.read_bytes()).decode("ascii")
return f"data:{mime};base64,{data}"
def _find_executable(candidates: list[str]) -> str | None:
for name in candidates:
path = shutil.which(name)
if path:
return path
return None
def _render_pdf_playwright(html_path: Path, pdf_path: Path, *, running_head: dict[str, str] | None) -> None:
from playwright.sync_api import sync_playwright # type: ignore
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page()
page.goto(html_path.resolve().as_uri())
pdf_kwargs: dict[str, Any] = {"path": str(pdf_path), "print_background": True}
if running_head:
placement = running_head.get("placement")
template = html.escape(running_head.get("template") or "")
template = template.replace("{page}", '<span class="pageNumber"></span>')
template = template.replace("{total}", '<span class="totalPages"></span>')
style = (
f"font-size:{running_head.get('font_size')};"
f"font-style:{running_head.get('font_style')};"
f"color:{running_head.get('color')};"
"width:100%;"
"text-align:center;"
)
box = f"<div style=\"{style}\">{template}</div>"
pdf_kwargs["display_header_footer"] = True
if placement == "header":
pdf_kwargs["header_template"] = box
pdf_kwargs["footer_template"] = "<div></div>"
else:
pdf_kwargs["footer_template"] = box
pdf_kwargs["header_template"] = "<div></div>"
page.pdf(**pdf_kwargs)
browser.close()
def _render_pdf_chromium(html_path: Path, pdf_path: Path, chromium_path: str) -> None:
uri = html_path.resolve().as_uri()
cmd = [
chromium_path,
"--headless",
"--disable-gpu",
"--print-to-pdf=" + str(pdf_path),
"--print-to-pdf-no-header",
"--allow-file-access-from-files",
uri,
]
if os.geteuid() == 0:
cmd.insert(1, "--no-sandbox")
subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
def _render_pdf_wkhtmltopdf(
html_path: Path,
pdf_path: Path,
wk_path: str,
*,
running_head: dict[str, str] | None,
) -> None:
cmd = [wk_path, "--quiet"]
if running_head:
template = running_head.get("template") or ""
template = template.replace("{page}", "[page]").replace("{total}", "[topage]")
font_size = running_head.get("font_size") or "9"
cmd.extend(["--footer-font-size", str(font_size).replace("pt", "")])
cmd.extend(["--footer-font-name", "Times-Roman"])
if running_head.get("placement") == "header":
cmd.extend(["--header-font-size", str(font_size).replace("pt", "")])
cmd.extend(["--header-font-name", "Times-Roman"])
cmd.extend(["--header-line"])
cmd.extend(["--header-center", template])
else:
cmd.extend(["--footer-line"])
cmd.extend(["--footer-center", template])
cmd.extend([str(html_path.resolve()), str(pdf_path)])
subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
def _render_pdf_weasyprint(html_path: Path, pdf_path: Path) -> None:
from weasyprint import HTML # type: ignore
HTML(filename=str(html_path.resolve())).write_pdf(str(pdf_path))
def _base_render_log(engines: list[dict[str, Any]], warnings: list[str]) -> dict[str, Any]:
now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
return {
"ok": False,
"tool": "iftypeset",
"tool_version": __version__,
"generated_at_utc": now,
"engine": None,
"engines_detected": engines,
"warnings": warnings,
"python": sys.version.split()[0],
}
def _engine_versions(engines: list[dict[str, Any]]) -> dict[str, str]:
versions: dict[str, str] = {}
for entry in engines:
name = entry.get("name")
detail = entry.get("detail")
if name == "chromium" and isinstance(detail, str):
versions[name] = _run_version_cmd([detail, "--version"])
elif name == "wkhtmltopdf" and isinstance(detail, str):
versions[name] = _run_version_cmd([detail, "--version"])
elif name == "playwright":
versions[name] = _module_version("playwright")
elif name == "weasyprint":
versions[name] = _module_version("weasyprint")
return versions
def _run_version_cmd(cmd: list[str]) -> str:
try:
out = subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
return out.stdout.strip() or out.stderr.strip()
except Exception: # noqa: BLE001
return "unknown"
def _module_version(module_name: str) -> str:
try:
mod = importlib.import_module(module_name)
return getattr(mod, "__version__", "unknown")
except Exception: # noqa: BLE001
return "unknown"
````
### `iftypeset/src/iftypeset/reporting.py`
- bytes: `24916`
- sha256: `4a53a2d52bc4ed62b8bb36e9ddc11330d56a3998fb86a49a822683f9873bb917`
````py
from __future__ import annotations
import hashlib
import json
import locale
import os
import shutil
import subprocess
import tarfile
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from iftypeset.spec_loader import LoadedSpec
class CoverageError(RuntimeError):
pass
@dataclass(frozen=True)
class CoverageCounts:
total_rules: int
by_category: dict[str, int]
by_enforcement: dict[str, int]
by_severity: dict[str, int]
@dataclass(frozen=True)
class CoverageReport:
tool: str
tool_version: str
generated_at_utc: str
spec_root: str
manifest_version: str | None
profiles: list[str]
counts: CoverageCounts
notes: list[str] = field(default_factory=list)
def to_markdown(self) -> str:
lines: list[str] = []
lines.append("# iftypeset coverage report\n")
lines.append(f"- Generated (UTC): `{self.generated_at_utc}`")
lines.append(f"- Spec root: `{self.spec_root}`")
if self.manifest_version:
lines.append(f"- Manifest version: `{self.manifest_version}`")
lines.append(f"- Profiles: {', '.join(f'`{p}`' for p in self.profiles)}\n")
lines.append("## Counts\n")
lines.append(f"- Total rules: `{self.counts.total_rules}`")
def section(title: str, d: dict[str, int]) -> None:
lines.append(f"\n### {title}\n")
if not d:
lines.append("_None_\n")
return
for k, v in sorted(d.items(), key=lambda kv: kv[0]):
lines.append(f"- `{k}`: `{v}`")
lines.append("")
section("By Category", self.counts.by_category)
section("By Enforcement", self.counts.by_enforcement)
section("By Severity", self.counts.by_severity)
if self.notes:
lines.append("## Notes\n")
for n in self.notes:
lines.append(f"- {n}")
lines.append("")
return "\n".join(lines).rstrip() + "\n"
@dataclass(frozen=True)
class TrustContract:
tool: str
tool_version: str
generated_at_utc: str
spec_root: str
manifest_version: str | None
profiles: list[str]
counts: CoverageCounts
enforcement_summary: dict[str, Any]
qa_limitations: list[str]
determinism_assumptions: list[str]
manual_checklist: dict[str, Any]
notes: list[str] = field(default_factory=list)
def to_markdown(self) -> str:
lines: list[str] = []
lines.append("# iftypeset trust contract\n")
lines.append(f"- Generated (UTC): `{self.generated_at_utc}`")
lines.append(f"- Spec root: `{self.spec_root}`")
if self.manifest_version:
lines.append(f"- Manifest version: `{self.manifest_version}`")
lines.append(f"- Profiles: {', '.join(f'`{p}`' for p in self.profiles)}\n")
lines.append("## Enforcement coverage\n")
lines.append(f"- Total rules: `{self.counts.total_rules}`")
lines.append(
f"- Enforced rules (lint/typeset/postrender): `{self.enforcement_summary.get('enforced_total', 0)}` "
f"({self.enforcement_summary.get('enforced_percent', 0)}%)"
)
lines.append(
f"- Manual rules: `{self.enforcement_summary.get('manual_total', 0)}` "
f"({self.enforcement_summary.get('manual_percent', 0)}%)"
)
enforced_by = self.enforcement_summary.get("enforced_by_type", {})
if enforced_by:
lines.append("")
for k, v in sorted(enforced_by.items(), key=lambda kv: kv[0]):
lines.append(f"- `{k}`: `{v}`")
lines.append("")
lines.append("## Coverage counts\n")
lines.append(f"- By category: {', '.join(f'{k}={v}' for k, v in sorted(self.counts.by_category.items()))}")
lines.append(f"- By enforcement: {', '.join(f'{k}={v}' for k, v in sorted(self.counts.by_enforcement.items()))}")
lines.append(f"- By severity: {', '.join(f'{k}={v}' for k, v in sorted(self.counts.by_severity.items()))}\n")
lines.append("## Manual checklist\n")
lines.append(f"- Tag: `{self.manual_checklist.get('tag')}`")
artifacts = self.manual_checklist.get("artifacts") or []
if artifacts:
lines.append(f"- Artifacts: {', '.join(f'`{a}`' for a in artifacts)}")
lines.append("")
lines.append("## QA limitations (v0)\n")
for item in self.qa_limitations:
lines.append(f"- {item}")
lines.append("")
lines.append("## Determinism assumptions\n")
for item in self.determinism_assumptions:
lines.append(f"- {item}")
lines.append("")
if self.notes:
lines.append("## Notes\n")
for n in self.notes:
lines.append(f"- {n}")
lines.append("")
return "\n".join(lines).rstrip() + "\n"
@dataclass(frozen=True)
class DoctorReport:
tool: str
tool_version: str
generated_at_utc: str
spec_root: str
renderer: dict[str, Any]
poppler: dict[str, Any]
fonts: dict[str, Any]
locale: dict[str, Any]
hyphenation: dict[str, Any]
determinism_caveats: list[str]
notes: list[str] = field(default_factory=list)
def to_markdown(self) -> str:
lines: list[str] = []
lines.append("# iftypeset doctor report\n")
lines.append(f"- Generated (UTC): `{self.generated_at_utc}`")
lines.append(f"- Spec root: `{self.spec_root}`\n")
lines.append("## Renderer\n")
lines.append(f"- PDF engines detected: `{self.renderer.get('pdf_engines_detected')}`")
lines.append(f"- PDF engine versions: `{self.renderer.get('pdf_engine_versions')}`\n")
lines.append("## Poppler tools\n")
tools = self.poppler.get("tools") if isinstance(self.poppler.get("tools"), dict) else {}
if tools:
for name, info in tools.items():
path = info.get("path") if isinstance(info, dict) else None
version = info.get("version") if isinstance(info, dict) else None
lines.append(f"- `{name}`: path={path or 'missing'} version={version or 'unknown'}")
else:
lines.append("- _No Poppler tools detected._")
lines.append("")
lines.append("## Fonts (primary match per profile)\n")
profiles = self.fonts.get("profiles") if isinstance(self.fonts.get("profiles"), dict) else {}
if profiles:
for profile_id, info in profiles.items():
lines.append(f"- `{profile_id}`: {info}")
else:
lines.append("- _No font data available._")
lines.append("")
lines.append("## Locale\n")
for key, value in self.locale.items():
lines.append(f"- `{key}`: {value}")
lines.append("")
lines.append("## Hyphenation (profile settings)\n")
for profile_id, info in self.hyphenation.items():
lines.append(f"- `{profile_id}`: {info}")
lines.append("")
lines.append("## Determinism caveats\n")
for item in self.determinism_caveats:
lines.append(f"- {item}")
lines.append("")
if self.notes:
lines.append("## Notes\n")
for note in self.notes:
lines.append(f"- {note}")
lines.append("")
return "\n".join(lines).rstrip() + "\n"
def build_coverage_report(spec: LoadedSpec, *, strict: bool) -> CoverageReport:
by_category: dict[str, int] = {}
by_enforcement: dict[str, int] = {}
by_severity: dict[str, int] = {}
for r in spec.rules:
by_category[r.category] = by_category.get(r.category, 0) + 1
by_enforcement[r.enforcement] = by_enforcement.get(r.enforcement, 0) + 1
by_severity[r.severity] = by_severity.get(r.severity, 0) + 1
notes: list[str] = []
if not spec.rules:
notes.append("No rule batches found under spec/rules/. Phase 2 extraction has not been applied yet.")
# This is intentionally conservative: without rule implementation handlers, we cannot compute implemented coverage.
if strict and not spec.rules:
raise CoverageError("Strict coverage requested, but no rules are present.")
counts = CoverageCounts(
total_rules=len(spec.rules),
by_category=by_category,
by_enforcement=by_enforcement,
by_severity=by_severity,
)
now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
from iftypeset import __version__
return CoverageReport(
tool="iftypeset",
tool_version=__version__,
generated_at_utc=now,
spec_root=str(spec.spec_root),
manifest_version=spec.manifest.get("version"),
profiles=sorted(spec.profiles.keys()),
counts=counts,
notes=notes,
)
def build_trust_contract(spec: LoadedSpec, report: CoverageReport) -> TrustContract:
by_enforcement = report.counts.by_enforcement
enforced_total = sum(v for k, v in by_enforcement.items() if k != "manual")
manual_total = by_enforcement.get("manual", 0)
total = report.counts.total_rules or 0
enforced_percent = round((enforced_total / total) * 100, 1) if total else 0.0
manual_percent = round((manual_total / total) * 100, 1) if total else 0.0
manifest_contract = spec.manifest.get("coverage_contract", {}) if isinstance(spec.manifest, dict) else {}
manual_tag = (
(manifest_contract.get("must_rules") or {}).get("manual_checklist_tag")
if isinstance(manifest_contract, dict)
else None
)
manual_checklist = {
"tag": manual_tag or "manual_checklist=true",
"artifacts": ["manual-checklist.md", "manual-checklist.json"],
"generated_by": "lint",
}
qa_limitations = [
"QA combines HTML heuristics with Poppler-based PDF text extraction; it is not a full layout engine.",
"Widows/orphans and true overflow measurement remain heuristic until geometry-aware PDF analysis exists.",
"QA does not validate factual correctness or citation accuracy; manual checklist remains required.",
"Outbound links are not fetched; availability and trustworthiness are not verified.",
]
determinism_assumptions = [
"Same input content, spec files, and profile settings produce the same outputs.",
"Same renderer engine/version and the same font set are available when rendering PDF.",
"No external network fetches are required for assets; local files are stable.",
"Rendering occurs in a consistent environment (locale, time zone, line endings).",
]
enforcement_summary = {
"enforced_total": enforced_total,
"manual_total": manual_total,
"enforced_percent": enforced_percent,
"manual_percent": manual_percent,
"enforced_by_type": {k: v for k, v in by_enforcement.items() if k != "manual"},
}
return TrustContract(
tool=report.tool,
tool_version=report.tool_version,
generated_at_utc=report.generated_at_utc,
spec_root=report.spec_root,
manifest_version=report.manifest_version,
profiles=report.profiles,
counts=report.counts,
enforcement_summary=enforcement_summary,
qa_limitations=qa_limitations,
determinism_assumptions=determinism_assumptions,
manual_checklist=manual_checklist,
notes=report.notes,
)
def build_doctor_report(spec: LoadedSpec) -> DoctorReport:
from iftypeset import __version__
from iftypeset.rendering import renderer_info
now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
renderer = renderer_info()
poppler = _detect_poppler_tools()
fonts = _font_availability(spec)
locale_info = _locale_info()
hyphenation = {pid: (spec.profiles[pid].get("hyphenation") or {}) for pid in sorted(spec.profiles.keys())}
determinism_caveats = [
"PDF output depends on renderer engine version and font availability.",
"Poppler-based QA relies on text extraction and is not geometry-accurate.",
"Locale and line-ending differences can affect hyphenation and wrapping.",
"External assets should be local; network fetches are not assumed.",
]
return DoctorReport(
tool="iftypeset",
tool_version=__version__,
generated_at_utc=now,
spec_root=str(spec.spec_root),
renderer=renderer,
poppler=poppler,
fonts=fonts,
locale=locale_info,
hyphenation=hyphenation,
determinism_caveats=determinism_caveats,
notes=[],
)
def _command_version(cmd: str, flags: list[str]) -> str | None:
for flag in flags:
try:
proc = subprocess.run(
[cmd, flag],
check=True,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
except (FileNotFoundError, subprocess.CalledProcessError):
continue
output = (proc.stdout.decode("utf-8", errors="replace") + proc.stderr.decode("utf-8", errors="replace")).strip()
if not output:
continue
return output.splitlines()[0].strip()
return None
def _detect_poppler_tools() -> dict[str, Any]:
tools = {}
for name in ("pdfinfo", "pdftotext", "pdftohtml"):
path = shutil.which(name)
version = None
if path:
version = _command_version(name, ["-v", "--version"])
tools[name] = {"path": path, "version": version}
return {"tools": tools}
def _font_availability(spec: LoadedSpec) -> dict[str, Any]:
fc_match = shutil.which("fc-match")
profiles: dict[str, Any] = {}
for profile_id, profile in sorted(spec.profiles.items()):
fonts = profile.get("fonts") or {}
entry: dict[str, Any] = {}
for role in ("body", "heading", "mono"):
role_info = fonts.get(role) or {}
families = role_info.get("family") or []
if not families:
continue
primary = str(families[0])
match = None
if fc_match:
match = _run_fc_match(primary)
entry[role] = {"primary": primary, "fallbacks": families[1:], "match": match}
profiles[str(profile_id)] = entry
return {"tools": {"fc_match": fc_match}, "profiles": profiles}
def _run_fc_match(family: str) -> str | None:
try:
proc = subprocess.run(
["fc-match", "-f", "%{family}\n", family],
check=True,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
except (FileNotFoundError, subprocess.CalledProcessError):
return None
output = proc.stdout.decode("utf-8", errors="replace").strip()
if not output:
return None
return output.splitlines()[0].strip()
def _locale_info() -> dict[str, Any]:
return {
"lang": os.environ.get("LANG"),
"lc_all": os.environ.get("LC_ALL"),
"lc_ctype": os.environ.get("LC_CTYPE"),
"python_locale": locale.getlocale(),
"preferred_encoding": locale.getpreferredencoding(False),
}
def build_report_index(out_dir: Path) -> str:
generated_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
def load_ok(path: Path) -> str:
if not path.exists():
return "missing"
try:
data = json.loads(path.read_text(encoding="utf-8"))
except Exception:
return "present"
if data.get("ok") is True:
return "ok"
if data.get("ok") is False:
return "fail"
return "present"
def link_item(label: str, filename: str, status: str | None = None) -> str:
rel = Path("..") / filename
status_html = f'<span class="status {status}">{status}</span>' if status else ""
return f'<li><a href="{rel.as_posix()}">{label}</a> {status_html}</li>'
lint_status = load_ok(out_dir / "lint-report.json")
qa_status = load_ok(out_dir / "qa-report.json")
run_status = load_ok(out_dir / "run-summary.json")
spec_status = load_ok(out_dir / "spec-validation.json")
pdf_present = "present" if (out_dir / "render.pdf").exists() else "missing"
lines: list[str] = []
lines.append("<!doctype html>")
lines.append("<html><head><meta charset=\"utf-8\" />")
lines.append("<title>iftypeset report index</title>")
lines.append(
"<style>"
"body{font-family:Arial,Helvetica,sans-serif;margin:24px;color:#111;}"
"h1{font-size:20px;margin:0 0 12px 0;}"
"h2{font-size:16px;margin:20px 0 8px 0;}"
"ul{padding-left:18px;}"
".status{font-size:12px;padding:2px 6px;border-radius:10px;margin-left:6px;}"
".status.ok{background:#e6f6ea;color:#126b2d;}"
".status.fail{background:#fdecea;color:#9b1c1c;}"
".status.missing{background:#f2f2f2;color:#666;}"
".status.present{background:#eef2f7;color:#35507a;}"
"</style></head><body>"
)
lines.append("<h1>iftypeset report index</h1>")
lines.append(f"<div>Generated (UTC): {generated_at}</div>")
lines.append("<h2>Summary</h2>")
lines.append("<ul>")
lines.append(f"<li>spec validation: <span class=\"status {spec_status}\">{spec_status}</span></li>")
lines.append(f"<li>lint: <span class=\"status {lint_status}\">{lint_status}</span></li>")
lines.append(f"<li>qa: <span class=\"status {qa_status}\">{qa_status}</span></li>")
lines.append(f"<li>run: <span class=\"status {run_status}\">{run_status}</span></li>")
lines.append(f"<li>pdf: <span class=\"status {pdf_present}\">{pdf_present}</span></li>")
lines.append("</ul>")
lines.append("<h2>Artifacts</h2>")
lines.append("<ul>")
lines.append(link_item("render.html", "render.html"))
lines.append(link_item("render.css", "render.css"))
lines.append(link_item("render.pdf", "render.pdf", pdf_present))
lines.append(link_item("typeset-report.json", "typeset-report.json"))
lines.append(link_item("render-log.json", "render-log.json"))
lines.append(link_item("lint-report.json", "lint-report.json", lint_status))
lines.append(link_item("manual-checklist.md", "manual-checklist.md"))
lines.append(link_item("manual-checklist.json", "manual-checklist.json"))
lines.append(link_item("layout-report.json", "layout-report.json"))
lines.append(link_item("qa-report.json", "qa-report.json", qa_status))
lines.append(link_item("coverage-summary.md", "coverage-summary.md"))
lines.append(link_item("coverage-report.json", "coverage-report.json"))
lines.append(link_item("trust-contract.md", "trust-contract.md"))
lines.append(link_item("trust-contract.json", "trust-contract.json"))
lines.append(link_item("run-summary.json", "run-summary.json", run_status))
lines.append(link_item("spec-validation.json", "spec-validation.json", spec_status))
lines.append("</ul>")
lines.append("</body></html>")
return "\n".join(lines) + "\n"
def build_run_index(out_dir: Path, documents: list[dict[str, Any]]) -> str:
generated_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
def status_for_code(code: int) -> str:
if code == 0:
return "ok"
if code == 1:
return "gate_fail"
if code == 2:
return "config"
if code == 3:
return "render"
return "unknown"
counts = {"ok": 0, "gate_fail": 0, "config": 0, "render": 0, "unknown": 0}
for doc in documents:
status = status_for_code(int(doc.get("exit_code", 0)))
counts[status] = counts.get(status, 0) + 1
lines: list[str] = []
lines.append("<!doctype html>")
lines.append("<html><head><meta charset=\"utf-8\" />")
lines.append("<title>iftypeset run index</title>")
lines.append(
"<style>"
"body{font-family:Arial,Helvetica,sans-serif;margin:24px;color:#111;}"
"h1{font-size:20px;margin:0 0 12px 0;}"
"h2{font-size:16px;margin:20px 0 8px 0;}"
"ul{padding-left:18px;}"
".status{font-size:12px;padding:2px 6px;border-radius:10px;margin-left:6px;}"
".status.ok{background:#e6f6ea;color:#126b2d;}"
".status.gate_fail{background:#fdecea;color:#9b1c1c;}"
".status.config{background:#f7e9c0;color:#7a4e00;}"
".status.render{background:#eef2f7;color:#35507a;}"
".status.unknown{background:#f2f2f2;color:#666;}"
"</style></head><body>"
)
lines.append("<h1>iftypeset run index</h1>")
lines.append(f"<div>Generated (UTC): {generated_at}</div>")
lines.append("<h2>Summary</h2>")
lines.append("<ul>")
lines.append(f"<li>documents: {len(documents)}</li>")
lines.append(f"<li>ok: {counts['ok']}</li>")
lines.append(f"<li>gate_fail: {counts['gate_fail']}</li>")
lines.append(f"<li>config: {counts['config']}</li>")
lines.append(f"<li>render: {counts['render']}</li>")
lines.append("</ul>")
lines.append("<h2>Documents</h2>")
lines.append("<ul>")
for doc in documents:
status = status_for_code(int(doc.get("exit_code", 0)))
label = doc.get("rel_input") or doc.get("input") or "unknown"
report_path = Path(str(doc.get("out_dir", ""))) / "report" / "index.html"
href = None
if report_path.exists():
try:
rel = report_path.resolve().relative_to(out_dir.resolve())
href = rel.as_posix()
except ValueError:
href = report_path.as_posix()
if href:
lines.append(f'<li><a href="{href}">{label}</a> <span class="status {status}">{status}</span></li>')
else:
lines.append(f'<li>{label} <span class="status {status}">{status}</span></li>')
lines.append("</ul>")
lines.append("</body></html>")
return "\n".join(lines) + "\n"
def build_bundle(out_dir: Path, bundle_path: Path, *, max_bytes: int = 50 * 1024 * 1024) -> dict[str, Any]:
candidates = [
"render.html",
"render.css",
"render.pdf",
"render-log.json",
"typeset-report.json",
"lint-report.json",
"lint-report.sarif",
"manual-checklist.md",
"manual-checklist.json",
"layout-report.json",
"qa-report.json",
"qa-report.sarif",
"coverage-report.json",
"coverage-summary.md",
"trust-contract.json",
"trust-contract.md",
"run-summary.json",
"spec-validation.json",
"doctor.json",
"doctor.md",
"report/index.html",
]
included: list[dict[str, Any]] = []
skipped: list[dict[str, Any]] = []
for rel in candidates:
path = out_dir / rel
if not path.exists() or not path.is_file():
continue
size = path.stat().st_size
if size > max_bytes:
skipped.append({"path": rel, "reason": "size_limit", "size": size})
continue
included.append(
{
"path": rel,
"sha256": _sha256_path(path),
"size": size,
}
)
manifest = {
"tool": "iftypeset",
"generated_at_utc": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
"out_dir": str(out_dir.resolve()),
"bundle_path": str(bundle_path.resolve()),
"max_size_bytes": max_bytes,
"included": sorted(included, key=lambda item: item["path"]),
"skipped": skipped,
}
manifest_path = out_dir / "bundle-manifest.json"
manifest_path.parent.mkdir(parents=True, exist_ok=True)
manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
entries = [(out_dir / item["path"], item["path"]) for item in manifest["included"]]
entries.append((manifest_path, "bundle-manifest.json"))
_write_bundle_tar(bundle_path, entries)
return manifest
def _sha256_path(path: Path) -> str:
h = hashlib.sha256()
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
h.update(chunk)
return h.hexdigest()
def _write_bundle_tar(bundle_path: Path, entries: list[tuple[Path, str]]) -> None:
bundle_path.parent.mkdir(parents=True, exist_ok=True)
with tarfile.open(bundle_path, "w:gz") as tar:
for path, arcname in sorted(entries, key=lambda item: item[1]):
if not path.exists() or not path.is_file():
continue
info = tar.gettarinfo(str(path), arcname=arcname)
info.uid = 0
info.gid = 0
info.uname = ""
info.gname = ""
info.mtime = 0
with path.open("rb") as handle:
tar.addfile(info, handle)
````
### `iftypeset/src/iftypeset/rules.py`
- bytes: `2409`
- sha256: `2346a2eef2a1e55b46724c39a4473a3702fb93f24ae55ff7fec1145c9f3d351b`
````py
from __future__ import annotations
import json
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable
from jsonschema import Draft202012Validator
class RulesError(RuntimeError):
pass
@dataclass(frozen=True)
class RuleRecord:
raw: dict[str, Any]
source_path: str
line_no: int
@property
def id(self) -> str:
return str(self.raw.get("id", ""))
@property
def category(self) -> str:
return str(self.raw.get("category", ""))
@property
def enforcement(self) -> str:
return str(self.raw.get("enforcement", ""))
@property
def severity(self) -> str:
return str(self.raw.get("severity", ""))
def _iter_ndjson_files(rules_root: Path) -> Iterable[Path]:
if not rules_root.exists():
return []
return sorted([p for p in rules_root.rglob("*.ndjson") if p.is_file()])
def load_rules(rules_root: Path, *, validator: Draft202012Validator) -> list[RuleRecord]:
rules: list[RuleRecord] = []
if not rules_root.exists():
return rules
seen_ids: dict[str, str] = {}
for path in _iter_ndjson_files(rules_root):
rel = str(path)
for i, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
if not line.strip():
continue
try:
obj = json.loads(line)
except json.JSONDecodeError as e:
raise RulesError(f"Invalid NDJSON ({rel}:{i}): {e}")
if not isinstance(obj, dict):
raise RulesError(f"Rule record must be a JSON object ({rel}:{i})")
errors = sorted(validator.iter_errors(obj), key=lambda err: list(err.absolute_path))
if errors:
first = errors[0]
path_bits = ".".join([str(p) for p in first.absolute_path]) if first.absolute_path else "<root>"
raise RulesError(f"Rule schema violation ({rel}:{i}) at {path_bits}: {first.message}")
rec = RuleRecord(raw=obj, source_path=rel, line_no=i)
rid = rec.id
if not rid:
raise RulesError(f"Rule missing id ({rel}:{i})")
if rid in seen_ids:
raise RulesError(f"Duplicate rule id '{rid}' in {rel}:{i} (already seen in {seen_ids[rid]})")
seen_ids[rid] = f"{rel}:{i}"
rules.append(rec)
return rules
````
### `iftypeset/src/iftypeset/spec_loader.py`
- bytes: `3314`
- sha256: `213ae2428e03541c2e907bee92593f2303a7fb2b83599c55a9e191967250d159`
````py
from __future__ import annotations
import json
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import yaml
from jsonschema import Draft202012Validator
from iftypeset.rules import RuleRecord, load_rules
class SpecError(RuntimeError):
pass
def _read_yaml(path: Path) -> Any:
try:
return yaml.safe_load(path.read_text(encoding="utf-8"))
except FileNotFoundError:
raise SpecError(f"Missing required file: {path}")
except Exception as e: # noqa: BLE001 - surface friendly error
raise SpecError(f"Invalid YAML: {path}: {e}")
def _read_json(path: Path) -> Any:
try:
return json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError:
raise SpecError(f"Missing required file: {path}")
except json.JSONDecodeError as e:
raise SpecError(f"Invalid JSON: {path}: {e}")
@dataclass(frozen=True)
class LoadedSpec:
spec_root: Path
manifest: dict[str, Any]
rule_schema: dict[str, Any]
profiles: dict[str, dict[str, Any]]
quality_gates: dict[str, Any]
rules: list[RuleRecord]
rule_validator: Draft202012Validator
def load_spec(spec_root: Path) -> LoadedSpec:
spec_root = spec_root.resolve()
if not spec_root.exists():
raise SpecError(f"Spec root does not exist: {spec_root}")
if not spec_root.is_dir():
raise SpecError(f"Spec root is not a directory: {spec_root}")
manifest_path = spec_root / "manifest.yaml"
schema_path = spec_root / "schema" / "rule.schema.json"
gates_path = spec_root / "quality_gates.yaml"
profiles_dir = spec_root / "profiles"
manifest = _read_yaml(manifest_path) or {}
if not isinstance(manifest, dict):
raise SpecError("manifest.yaml must be a mapping/object.")
rule_schema = _read_json(schema_path) or {}
if not isinstance(rule_schema, dict):
raise SpecError("rule.schema.json must be a JSON object.")
try:
rule_validator = Draft202012Validator(rule_schema)
except Exception as e: # noqa: BLE001
raise SpecError(f"Invalid JSON Schema: {schema_path}: {e}")
gates = _read_yaml(gates_path) or {}
if not isinstance(gates, dict):
raise SpecError("quality_gates.yaml must be a mapping/object.")
profiles: dict[str, dict[str, Any]] = {}
if not profiles_dir.exists():
raise SpecError(f"Missing required directory: {profiles_dir}")
for path in sorted(profiles_dir.glob("*.yaml")):
data = _read_yaml(path) or {}
if not isinstance(data, dict):
raise SpecError(f"Profile must be a mapping/object: {path}")
pid = data.get("profile_id")
if not isinstance(pid, str) or not pid:
raise SpecError(f"Profile missing profile_id: {path}")
if pid in profiles:
raise SpecError(f"Duplicate profile_id '{pid}' in {path}")
profiles[pid] = data
# Rules are optional until Phase 2 extraction delivers NDJSON batches.
rules: list[RuleRecord] = load_rules(spec_root / "rules", validator=rule_validator)
return LoadedSpec(
spec_root=spec_root,
manifest=manifest,
rule_schema=rule_schema,
profiles=profiles,
quality_gates=gates,
rules=rules,
rule_validator=rule_validator,
)
````
### `iftypeset/spec/manifest.yaml`
- bytes: `4862`
- sha256: `66c9edc039594c4b9ca36e13926fab495f06a79cb2b7e8a54f36ebcf6aeca06f`
````yaml
version: "0.1.0"
registry_id: "pubstyle"
description: >
Machine-readable style+typesetting rules for a Markdown→HTML→PDF pipeline,
backed by primary references (Chicago / Bringhurst) and optional house rules.
Rules are paraphrases only; sources are referenced by pointer strings.
id_naming:
prefixes:
CMOS: "Editorial/style usage rules derived primarily from Chicago."
BRING: "Typographic/layout rules derived primarily from Bringhurst."
HOUSE: "Project-specific rules not directly sourced to Chicago/Bringhurst."
pattern: "PREFIX.DOMAIN.TOPIC[.SUBTOPIC[.DETAIL...]]"
delimiter: "."
casing: "UPPER_SNAKE for segments"
stability:
rule_ids_are_immutable: true
rename_policy: "Deprecate old id; introduce new id; keep mapping in report diffs."
examples:
- "CMOS.PUNCTUATION.DASHES.EM_DASH"
- "BRING.LAYOUT.WIDOWS_ORPHANS.AVOID"
- "HOUSE.CITATIONS.DOI.PREFER_HTTPS"
source_pointer_scheme:
goal: "Provide auditable traceability without reproducing sources."
pointer_format_primary: "CMOS18 §<section> p<book_page>"
pointer_format_secondary: "BRING §<section> p<book_page>"
pointer_format_house: "HOUSE §<section> p<doc_page>"
optional_scan_hint: "(scan p<pdf_page_index>)"
allowed_page_numbering:
- arabic
- roman
notes:
- "Pointers must be sufficient for a reader with the book to locate the guidance."
- "Never store verbatim passages; paraphrase only."
- "If a rule depends on exact wording, rule_text must say: Exact wording required—refer to pointer."
category_taxonomy:
- editorial
- typography
- layout
- headings
- citations
- numbers
- punctuation
- abbreviations
- links
- tables
- figures
- code
- frontmatter
- backmatter
- accessibility
- i18n
profiles:
- web_pdf
- print_pdf
- dense_tech
- memo
- slide_deck
- webtypography_nc
- cv_onepage
planned_rule_counts:
target_total_range: [800, 1500]
target_by_category:
editorial: 120
typography: 170
layout: 140
headings: 70
citations: 140
numbers: 90
punctuation: 120
abbreviations: 60
links: 50
tables: 60
figures: 50
code: 70
frontmatter: 40
backmatter: 40
accessibility: 90
i18n: 60
coverage_contract:
must_rules:
enforceability_requirement: >
Every MUST rule must be enforceable by at least one of: lint, typeset, postrender;
otherwise it must be explicitly labeled as a manual checklist item and emitted in
a checklist output artifact.
manual_checklist_tag: "manual_checklist=true"
checklist_artifact: "manual-checklist.md (and JSON mirror)"
should_rules:
policy: "Should rules should be enforceable when practical; otherwise allowed as manual with explicit rationale."
warn_rules:
policy: "Warnings may be non-blocking and advisory; still require source pointers."
enforcement_definitions:
lint: "Static analysis over normalized Markdown/HTML AST. Deterministic."
typeset: "CSS/tokens shaping decisions prior to rendering (pagination, keeps, hyphenation parameters)."
postrender: "PDF/HTML layout inspection (widows/orphans, overflow, keep failures, numbering mismatches)."
manual: "Human review; system must still produce checklist items and traceability pointers."
ci_guardrails:
coverage_floor:
must_implemented_min_percent: 95
overall_implemented_min_percent: 80
regression_rule: "CI fails if implemented coverage decreases from main branch."
degraded_mode_contract:
purpose: "Handle badly-structured inputs safely without crashing; still provide useful output."
triggers:
- "Markdown parse errors / invalid UTF-8"
- "Missing heading hierarchy (no H1/H2 etc.)"
- "Garbage extraction (e.g., line breaks every word, excessive hard wraps)"
- "Mixed language with no lang metadata"
behavior:
normalize:
attempt_repairs:
- "Normalize whitespace and line endings"
- "Detect and unwrap hard-wrapped paragraphs heuristically"
- "Infer heading levels from patterns (e.g., 1., 1.1, ALL CAPS lines) with low confidence"
if_unrecoverable:
- "Fall back to minimal AST: paragraphs + code blocks + raw spans"
- "Mark document structure confidence = low"
enforcement_in_degraded_mode:
lint:
run_subset:
- "safety"
- "sanity"
- "catastrophic typography (double spaces, broken links)"
downgrade_some_must_to_warn: true
typeset:
use_fallback_tokens: true
disable_aggressive_hyphenation: true
postrender:
run_core_gates_only:
- "overfull_lines"
- "table_overflow_incidents"
- "code_overflow_incidents"
reporting:
always_emit:
- "layout-report.json"
- "coverage-report.json"
- "degraded-mode-report.json (what was inferred and why)"
````
### `iftypeset/spec/quality_gates.yaml`
- bytes: `6299`
- sha256: `901aa1b97c81426e69745f807796b6aa5972591a176024c4a5ff9d14c5dd601e`
````yaml
version: "0.1.0"
description: >
Post-render QA gates. All thresholds are hard numeric limits used to fail builds
(unless a gate is explicitly marked as warn-only by the invoking CLI flags).
metrics:
max_widows_per_10_pages: "Count of widow lines across any 10 consecutive pages."
max_orphans_per_10_pages: "Count of orphan lines across any 10 consecutive pages."
max_stranded_headings: "Count of headings at page bottom with insufficient following content per keep rule."
max_overfull_lines: "Count of lines exceeding measure by overflow threshold (render-time measured)."
max_table_overflow_incidents: "Count of tables that overflow page/column bounds or are clipped."
max_code_overflow_incidents: "Count of code blocks with horizontal overflow or clipping."
max_link_wrap_incidents: "Count of wrapped URLs/DOIs/emails violating link wrap policy."
max_heading_numbering_errors: "Count of numbering sequence/format violations."
max_citation_format_errors: "Count of citations not matching configured style format."
max_caption_separation_incidents: "Count of captions likely separated from their figures/tables."
max_list_break_incidents: "Count of list pagination issues (intro separated, lonely items)."
max_heading_proximity_incidents: "Count of adjacent/stacked headings with insufficient body text."
max_runt_final_page: "Count of final pages judged too short (runt pages) by PDF analysis."
overflow_detection:
overfull_line_threshold_css_px: 1.0
consider_clipping_as_overflow: true
ignore_decorative_elements: true
profiles:
web_pdf:
default:
max_widows_per_10_pages: 1
max_orphans_per_10_pages: 1
max_stranded_headings: 0
max_overfull_lines: 1
max_table_overflow_incidents: 0
max_code_overflow_incidents: 1
max_link_wrap_incidents: 1
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 1
max_list_break_incidents: 1
max_heading_proximity_incidents: 1
max_runt_final_page: 0
strict:
max_widows_per_10_pages: 0
max_orphans_per_10_pages: 0
max_stranded_headings: 0
max_overfull_lines: 0
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 0
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 0
max_list_break_incidents: 0
max_heading_proximity_incidents: 0
max_runt_final_page: 0
print_pdf:
default:
max_widows_per_10_pages: 0
max_orphans_per_10_pages: 0
max_stranded_headings: 0
max_overfull_lines: 0
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 0
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 0
max_list_break_incidents: 0
max_heading_proximity_incidents: 0
max_runt_final_page: 0
strict:
max_widows_per_10_pages: 0
max_orphans_per_10_pages: 0
max_stranded_headings: 0
max_overfull_lines: 0
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 0
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 0
max_list_break_incidents: 0
max_heading_proximity_incidents: 0
max_runt_final_page: 0
dense_tech:
default:
max_widows_per_10_pages: 1
max_orphans_per_10_pages: 1
max_stranded_headings: 0
max_overfull_lines: 2
max_table_overflow_incidents: 0
max_code_overflow_incidents: 2
max_link_wrap_incidents: 2
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 1
max_list_break_incidents: 1
max_heading_proximity_incidents: 1
max_runt_final_page: 0
strict:
max_widows_per_10_pages: 0
max_orphans_per_10_pages: 0
max_stranded_headings: 0
max_overfull_lines: 1
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 1
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 0
max_list_break_incidents: 0
max_heading_proximity_incidents: 0
max_runt_final_page: 0
memo:
default:
max_widows_per_10_pages: 3
max_orphans_per_10_pages: 3
max_stranded_headings: 0
max_overfull_lines: 1
max_table_overflow_incidents: 0
max_code_overflow_incidents: 1
max_link_wrap_incidents: 3
max_heading_numbering_errors: 1
max_citation_format_errors: 1
max_caption_separation_incidents: 2
max_list_break_incidents: 2
max_heading_proximity_incidents: 2
max_runt_final_page: 0
strict:
max_widows_per_10_pages: 1
max_orphans_per_10_pages: 1
max_stranded_headings: 0
max_overfull_lines: 0
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 2
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 1
max_list_break_incidents: 1
max_heading_proximity_incidents: 1
max_runt_final_page: 0
slide_deck:
default:
max_widows_per_10_pages: 5
max_orphans_per_10_pages: 5
max_stranded_headings: 0
max_overfull_lines: 0
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 0
max_heading_numbering_errors: 0
max_citation_format_errors: 1
max_caption_separation_incidents: 2
max_list_break_incidents: 2
max_heading_proximity_incidents: 2
max_runt_final_page: 0
strict:
max_widows_per_10_pages: 2
max_orphans_per_10_pages: 2
max_stranded_headings: 0
max_overfull_lines: 0
max_table_overflow_incidents: 0
max_code_overflow_incidents: 0
max_link_wrap_incidents: 0
max_heading_numbering_errors: 0
max_citation_format_errors: 0
max_caption_separation_incidents: 1
max_list_break_incidents: 1
max_heading_proximity_incidents: 1
max_runt_final_page: 0
````
### `iftypeset/spec/indexes/enforcement.json`
- bytes: `51840`
- sha256: `f1f06fbb798677cceba73cc6fb7bbdabb27a59b4dce9f8d319e6fc1c6084c187`
````json
{
"lint": [
"BRING.HEADINGS.CAPITALIZATION.CONSISTENT",
"BRING.HEADINGS.DEGRADED.INFER_STRUCTURE",
"BRING.HEADINGS.HIERARCHY.NO_SKIPPED_LEVELS",
"BRING.HEADINGS.SUBHEADS.LEVELS.AS_MANY_AS_NEEDED",
"BRING.LAYOUT.DEGRADED.HARD_WRAP_REFLOW",
"BRING.TABLES.DEGRADED.REBUILD_COLUMNS",
"BRING.TYPOGRAPHY.ALIGNMENT.DONT_STRETCH_SPACE",
"BRING.TYPOGRAPHY.HYPHENATION.HARD_SPACES.SHORT_EXPRESSIONS",
"BRING.TYPOGRAPHY.SPACING.SENTENCE_SPACE.SINGLE",
"CMOS.ABBREVIATIONS.ACRONYMS.DEFINE_FIRST_USE",
"CMOS.ABBREVIATIONS.PLURALS.NO_APOSTROPHE",
"CMOS.CITATIONS.DEGRADED.NOTE_MARKERS.REPAIR",
"CMOS.CITATIONS.DEGRADED.URL_LINEBREAKS.NORMALIZE",
"CMOS.CITATIONS.DOI.PREFERRED_OVER_URL",
"CMOS.CITATIONS.NOTES.NOTE_MARKERS.HEADINGS_END",
"CMOS.CITATIONS.NOTES.NOTE_MARKERS.PLACEMENT_AFTER_PUNCT",
"CMOS.CITATIONS.NOTES.NOTE_MARKERS.SEQUENCE_CONTINUOUS",
"CMOS.CITATIONS.NOTES.NOTE_MARKERS.SUPERSCRIPT_TEXT",
"CMOS.NUMBERS.DECIMALS.LEADING_ZERO",
"CMOS.NUMBERS.DECIMALS.NUMERALS",
"CMOS.NUMBERS.DECIMAL_MARKER.LOCALE",
"CMOS.NUMBERS.DEGRADED.HARD_WRAP_UNITS",
"CMOS.NUMBERS.DEGRADED.NUMERAL_NORMALIZATION",
"CMOS.NUMBERS.GROUPING.THOUSANDS_SEPARATOR",
"CMOS.NUMBERS.ORDINALS.SUFFIX.CORRECT",
"CMOS.NUMBERS.PERCENTAGES.NUMERALS",
"CMOS.NUMBERS.PLURALS.DECADE.NO_APOSTROPHE",
"CMOS.NUMBERS.RANGES.EN_DASH.USE",
"CMOS.NUMBERS.SI_PREFIXES.NO_HYPHEN",
"CMOS.PUNCTUATION.BLOCK_QUOTES.NO_QUOTE_MARKS",
"CMOS.PUNCTUATION.COLONS.SPACE_AFTER",
"CMOS.PUNCTUATION.COMMAS.SERIAL_COMMA.DEFAULT",
"CMOS.PUNCTUATION.DASHES.EM_DASH.USE_WITHOUT_SPACES_US",
"CMOS.PUNCTUATION.DASHES.EN_DASH.RANGES",
"CMOS.PUNCTUATION.DEGRADED.EXTRA_SPACES.AFTER_PUNCT",
"CMOS.PUNCTUATION.ELLIPSIS.FORMAT.CONSISTENT",
"CMOS.PUNCTUATION.MULTIPLE_MARKS.AVOID_STACKING",
"CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE",
"CMOS.PUNCTUATION.QUOTES.SMART_QUOTES",
"HOUSE.A11Y.HEADINGS.NO_SKIPS",
"HOUSE.A11Y.IMAGES.ALT_REQUIRED",
"HOUSE.A11Y.LINK_TEXT.DESCRIPTIVE",
"HOUSE.ACCESSIBILITY.HEADINGS.NO_EMPTY",
"HOUSE.ACCESSIBILITY.IMAGES.ALT_TEXT.QUALITY.NO_FILENAME",
"HOUSE.ACCESSIBILITY.LINK_TEXT.SYMBOL_ONLY.AVOID",
"HOUSE.ACCESSIBILITY.LINK_TEXT.UNIQUE_TARGETS",
"HOUSE.ACCESSIBILITY.LISTS.NO_EMPTY_ITEMS",
"HOUSE.ACCESSIBILITY.TABLES.HEADER_ROW.REQUIRED",
"HOUSE.CITATIONS.AUTHOR_DATE.PAREN_YEAR_ONLY",
"HOUSE.CITATIONS.AUTHOR_DATE.REFLIST.REQUIRED",
"HOUSE.CITATIONS.AUTHOR_DATE.REFLIST.YEAR_REQUIRED",
"HOUSE.CITATIONS.NOTES.BIBLIOGRAPHY.REQUIRED",
"HOUSE.CITATIONS.NOTES.DEFINITIONS.REQUIRED",
"HOUSE.CITATIONS.NOTES.IBID.AVOID",
"HOUSE.CITATIONS.NOTES.MARKERS.BRACKETED_NUMBERS.AVOID",
"HOUSE.CODE.BLOCKS.LANGUAGE_TAGS.PREFERRED",
"HOUSE.CODE.BLOCKS.LONG_LINES.AVOID",
"HOUSE.CODE.BLOCKS.TABS.AVOID",
"HOUSE.CODE.FENCES.LANGUAGE_INFO.SUGGEST",
"HOUSE.CODE.INLINE.MONO_BACKTICKS",
"HOUSE.EDITORIAL.HEADINGS.AVOID_ALL_CAPS",
"HOUSE.EDITORIAL.HEADINGS.NO_TRAILING_PUNCTUATION",
"HOUSE.EDITORIAL.LISTS.AVOID_SINGLE_ITEM",
"HOUSE.EDITORIAL.PLACEHOLDERS.NO_LOREM_IPSUM",
"HOUSE.EDITORIAL.PLACEHOLDERS.NO_TBD_TKTK",
"HOUSE.EDITORIAL.PLACEHOLDERS.NO_TODO_FIXME",
"HOUSE.EDITORIAL.STRUCTURE.H1_TITLE.EARLY",
"HOUSE.EDITORIAL.STRUCTURE.H1_TITLE.PRESENT",
"HOUSE.EDITORIAL.STRUCTURE.H1_TITLE.SINGLE",
"HOUSE.I18N.NUMBERS.MIXED_DECIMAL_SEPARATORS",
"HOUSE.I18N.QUOTES.MIXED_STYLES",
"HOUSE.LAYOUT.MD.BLANK_LINES.SPARING",
"HOUSE.LAYOUT.MD.HEADINGS.NON_EMPTY_SECTIONS",
"HOUSE.LINKS.AUTO.EMBEDDED_CREDENTIALS.AVOID",
"HOUSE.LINKS.AUTO.FILETYPE_LABEL.REQUIRED",
"HOUSE.LINKS.AUTO.FTP.AVOID",
"HOUSE.LINKS.AUTO.HTML_FALLBACK.REQUIRED",
"HOUSE.LINKS.AUTO.INTERNAL_HOSTNAMES.AVOID",
"HOUSE.LINKS.AUTO.INVITE_LINKS.AVOID",
"HOUSE.LINKS.AUTO.LABEL_LENGTH.AVOID_OVERLONG",
"HOUSE.LINKS.AUTO.LOGIN_LINKS.AVOID",
"HOUSE.LINKS.AUTO.PARTIAL_WORD.AVOID",
"HOUSE.LINKS.AUTO.PASSWORD_RESET.AVOID",
"HOUSE.LINKS.AUTO.PRIVATE_IPS.AVOID",
"HOUSE.LINKS.AUTO.SESSION_PARAMS.AVOID",
"HOUSE.LINKS.AUTO.STAGING_HOSTNAMES.AVOID",
"HOUSE.LINKS.AUTO.TRACKING_PARAMS.AVOID",
"HOUSE.LINKS.DISALLOW.FILE_URIS",
"HOUSE.LINKS.DISALLOW.JAVASCRIPT_URIS",
"HOUSE.LINKS.PUNCTUATION.NO_TRAILING_PUNCT",
"HOUSE.LINKS.TEXT.DESCRIPTIVE",
"HOUSE.LINKS.TEXT.NO_CLICK_HERE",
"HOUSE.LINKS.URLS.AVOID.NAKED_URLS_IN_PROSE",
"HOUSE.LINKS.URLS.DISALLOW.LOCALHOST",
"HOUSE.LINKS.URLS.DOIS.PREFER_DOI_ORG",
"HOUSE.LINKS.URLS.NO_BACKSLASH",
"HOUSE.LINKS.URLS.NO_TRAILING_PARENS",
"HOUSE.LINKS.URLS.NO_WHITESPACE",
"HOUSE.LINKS.URLS.NO_ZERO_WIDTH",
"HOUSE.LINKS.URLS.PREFER_HTTPS",
"HOUSE.TYPOGRAPHY.EMPHASIS.BOLD_ALL_CAPS.AVOID",
"HOUSE.TYPOGRAPHY.EMPHASIS.BOLD_ITALIC_LONG.AVOID",
"HOUSE.TYPOGRAPHY.EMPHASIS.BOLD_LONG.AVOID",
"HOUSE.TYPOGRAPHY.EMPHASIS.ITALIC_LONG.AVOID"
],
"manual": [
"BRING.HEADINGS.AVOID_ABBREVIATIONS",
"BRING.HEADINGS.AVOID_STACKED_LEVELS",
"BRING.HEADINGS.BREAKS.AT_PHRASE_BOUNDARIES",
"BRING.HEADINGS.CASE.PROPER_NOUNS_PRESERVE",
"BRING.HEADINGS.CONTRAST.CLEAR_HIERARCHY",
"BRING.HEADINGS.HIERARCHY.MAX_DEPTH",
"BRING.HEADINGS.LEADIN_TEXT.BEFORE_LIST",
"BRING.HEADINGS.LENGTH.CONCISE",
"BRING.HEADINGS.NO_HYPHENATION",
"BRING.HEADINGS.NO_SINGLE_WORD_LINE",
"BRING.HEADINGS.NO_TERMINAL_COLON",
"BRING.HEADINGS.NO_TERMINAL_PERIOD",
"BRING.HEADINGS.NUMBERING.APPENDIX_LABELS",
"BRING.HEADINGS.NUMBERING.CONSISTENT_STYLE",
"BRING.HEADINGS.NUMBERING.NO_GAPS",
"BRING.HEADINGS.NUMBERING.PREFIXES.CONSISTENT",
"BRING.HEADINGS.NUMBERING.PUNCTUATION.CONSISTENT",
"BRING.HEADINGS.NUMBERING.SUBLEVELS.DECIMAL_STYLE",
"BRING.HEADINGS.QUESTION_MARK_ONLY_IF_QUESTION",
"BRING.HEADINGS.RELATED_ELEMENTS.COHERENT",
"BRING.HEADINGS.RUN_IN.END_PUNCTUATION",
"BRING.HEADINGS.RUN_IN.SEPARATION.CONSISTENT",
"BRING.HEADINGS.RUN_IN.STANDALONE.CONSISTENT",
"BRING.HEADINGS.SECTION_OPENING.PARAGRAPH_REQUIRED",
"BRING.HEADINGS.STRUCTURE.MATCH_TEXT_LOGIC",
"BRING.HEADINGS.STYLE.PALETTE_LIMIT",
"BRING.HEADINGS.SUBHEADS.MIXING.HIERARCHY_PLACEMENT",
"BRING.HEADINGS.SUBHEADS.PARALLEL_GRAMMAR",
"BRING.HEADINGS.TOC.MATCH",
"BRING.HEADINGS.WIDTH.BALANCED",
"BRING.LAYOUT.COLUMNS.RAGGED_BOTTOM.AVOID",
"BRING.LAYOUT.COLUMNS.SPAN_POLICY.FIGURES",
"BRING.LAYOUT.COLUMNS.SPAN_POLICY.TABLES",
"BRING.LAYOUT.COLUMNS.USE_FOR_LONG_LISTS",
"BRING.LAYOUT.ELEMENT_RELATIONSHIPS.VISIBLE",
"BRING.LAYOUT.FLOATS.PLACEMENT.NEAR_REFERENCE",
"BRING.LAYOUT.MARGINS.BLEED.ONLY_WHEN_ENABLED",
"BRING.LAYOUT.MARGINS.NOTES.OUTSIDE_TEXTBLOCK",
"BRING.LAYOUT.MEASURE.CODE_BLOCKS.WRAP_POLICY",
"BRING.LAYOUT.PAGE.BLANKS.INTENTIONAL",
"BRING.LAYOUT.PAGE.DENSITY.DONT_SUFFOCATE",
"BRING.LAYOUT.PAGE.FACING_ELEMENTS.ALIGN",
"BRING.LAYOUT.PAGE.ODD_EVEN.CONSISTENT",
"BRING.LAYOUT.PAGE.OPENING_SPREAD.RULE",
"BRING.LAYOUT.PAGE.SPREADS.BALANCE_CONTENT",
"BRING.LAYOUT.PAGE.WHITE_SPACE.DISTRIBUTION",
"BRING.LAYOUT.PAGINATION.AVOID_BREAK_AFTER_HEADING",
"BRING.LAYOUT.PAGINATION.AVOID_BREAK_BEFORE_LAST_LINE",
"BRING.LAYOUT.PAGINATION.AVOID_BREAK_IN_BLOCK_QUOTES",
"BRING.LAYOUT.PAGINATION.AVOID_BREAK_IN_EQUATIONS",
"BRING.LAYOUT.PAGINATION.AVOID_EXCESS_WHITE_SPACE",
"BRING.LAYOUT.PAGINATION.AVOID_LONELY_LINE_IN_LISTS",
"BRING.LAYOUT.PAGINATION.AVOID_STRANDED_CAPTIONS",
"BRING.LAYOUT.PAGINATION.BALANCE_FINAL_PAGE",
"BRING.LAYOUT.PAGINATION.CLEAR_SECTION_BREAKS",
"BRING.LAYOUT.PAGINATION.KEEP_FIGURE_WITH_CAPTION",
"BRING.LAYOUT.PAGINATION.KEEP_LIST_WITH_INTRO",
"BRING.LAYOUT.PAGINATION.KEEP_TABLE_WITH_HEADER",
"BRING.LAYOUT.PARAGRAPH.AFTER_QUOTE.FLUSH",
"BRING.LAYOUT.PARAGRAPH.AVOID_WIDOW_END",
"BRING.LAYOUT.PARAGRAPH.AVOID_WIDOW_START",
"BRING.LAYOUT.PARAGRAPH.BLANK_LINES.SPARING",
"BRING.LAYOUT.PARAGRAPH.BLOCK_STYLE.CONSISTENT",
"BRING.LAYOUT.PARAGRAPH.RUN_IN_HEADS.CONSISTENT",
"BRING.LAYOUT.PARAGRAPH.SECTION_BREAKS.CLEAR",
"BRING.LAYOUT.RHYTHM.RULES_SERVE_TEXT",
"BRING.TABLES.CAPTIONS.CLEAR",
"BRING.TABLES.DATA_TYPES.NOT_MIXED",
"BRING.TABLES.EDIT_AS_TEXT.READABILITY",
"BRING.TABLES.GUIDES.READING_DIRECTION",
"BRING.TABLES.HEADERS.CONCISE",
"BRING.TABLES.MULTI_LINE_HEADERS.AVOID",
"BRING.TABLES.NUMERIC_PRECISION.CONSISTENT",
"BRING.TABLES.ORDER.LOGICAL",
"BRING.TABLES.SOURCES.NOTES.DISTINCT",
"BRING.TABLES.STUB_COLUMN.USE",
"BRING.TABLES.TEXT_ORIENTATION.HORIZONTAL",
"BRING.TABLES.TITLES.CONSISTENT_PLACEMENT",
"BRING.TABLES.UNITS.IN_HEADERS",
"BRING.TYPOGRAPHY.BOLD.AVOID_LONG_PASSAGES",
"BRING.TYPOGRAPHY.BOLD.HEADING_HIERARCHY_BALANCE",
"BRING.TYPOGRAPHY.BOLD.LABELS_SHORT",
"BRING.TYPOGRAPHY.BOLD.NOT_WITH_ALL_CAPS",
"BRING.TYPOGRAPHY.BOLD.NOT_WITH_ITALICS_LONG",
"BRING.TYPOGRAPHY.BOLD.SPARING_USE",
"BRING.TYPOGRAPHY.CAPS.ALL_CAPS_AVOID_LONG_RUNS",
"BRING.TYPOGRAPHY.CAPS.ALL_CAPS_SHORT_LABELS_ONLY",
"BRING.TYPOGRAPHY.CAPS.AVOID_FOR_EMPHASIS",
"BRING.TYPOGRAPHY.CAPS.MIXED_CAPS_CONSISTENT",
"BRING.TYPOGRAPHY.CAPS.ROMAN_NUMERALS_SPACING",
"BRING.TYPOGRAPHY.CAPS.SMALL_CAPS_FOR_ACRONYMS",
"BRING.TYPOGRAPHY.CAPS.SMALL_CAPS_NOT_FOR_LONG_PASSAGES",
"BRING.TYPOGRAPHY.CONTRAST.AVOID_EXTREME_MIX",
"BRING.TYPOGRAPHY.CONTRAST.FONT_PAIRING_MATCH",
"BRING.TYPOGRAPHY.FAMILY.BOLD_FOR_STRONG_EMPHASIS",
"BRING.TYPOGRAPHY.FAMILY.ITALIC_FOR_SUBTLE_EMPHASIS",
"BRING.TYPOGRAPHY.FAMILY.ITALIC_PUNCTUATION_MATCH",
"BRING.TYPOGRAPHY.FAMILY.LIMIT_STYLE_VARIANTS",
"BRING.TYPOGRAPHY.FAMILY.METRICS_MATCH_WHEN_MIXING",
"BRING.TYPOGRAPHY.FAMILY.SINGLE_FAMILY_BODY",
"BRING.TYPOGRAPHY.FAMILY.SMALL_CAPS_SPARE",
"BRING.TYPOGRAPHY.HYPHENATION.AVOID_PROPER_NAMES",
"BRING.TYPOGRAPHY.ITALICS.AVOID_IN_ALL_CAPS_HEADINGS",
"BRING.TYPOGRAPHY.ITALICS.AVOID_NUMERAL_ITALICS",
"BRING.TYPOGRAPHY.ITALICS.AVOID_STACKED_EMPHASIS",
"BRING.TYPOGRAPHY.ITALICS.CONSISTENT_TITLE_TREATMENT",
"BRING.TYPOGRAPHY.ITALICS.EMPHASIS_NOT_UNDERLINE",
"BRING.TYPOGRAPHY.ITALICS.HEADINGS_AVOID",
"BRING.TYPOGRAPHY.ITALICS.LONG_SPANS_AVOID",
"BRING.TYPOGRAPHY.ITALICS.PUNCTUATION_FOLLOWS_STYLE",
"BRING.TYPOGRAPHY.ITALICS.RUNNING_HEADS_AVOID",
"BRING.TYPOGRAPHY.ITALICS.SPARING",
"BRING.TYPOGRAPHY.ITALICS.TERMS_INTRODUCED_SPARE",
"BRING.TYPOGRAPHY.ITALICS.TITLES_STANDALONE_WORKS",
"BRING.TYPOGRAPHY.KERNING.CONSISTENT_OR_NONE",
"BRING.TYPOGRAPHY.LIGATURES.AVOID_IN_ACRONYMS",
"BRING.TYPOGRAPHY.LIGATURES.AVOID_IN_ALL_CAPS",
"BRING.TYPOGRAPHY.LIGATURES.DISCRETIONARY_IN_DISPLAY",
"BRING.TYPOGRAPHY.LIGATURES.DISCRETIONARY_SPARING",
"BRING.TYPOGRAPHY.LIGATURES.DO_NOT_USE_IF_AMBIGUOUS",
"BRING.TYPOGRAPHY.LIGATURES.KEEP_CONSISTENT",
"BRING.TYPOGRAPHY.LIGATURES.REVIEW_FOR_LANGUAGE",
"BRING.TYPOGRAPHY.NUMBER_STRINGS.SPACE_FOR_READABILITY",
"BRING.TYPOGRAPHY.NUMERALS.AVOID_LINING_IN_LOWERCASE",
"BRING.TYPOGRAPHY.NUMERALS.CONSISTENT_STYLE_WITHIN_SECTION",
"BRING.TYPOGRAPHY.NUMERALS.FIGURE_STYLE_FOR_CAPTIONS",
"BRING.TYPOGRAPHY.NUMERALS.MIXED_STYLE_AVOID",
"BRING.TYPOGRAPHY.NUMERALS.SLASHED_ZERO_IF_CONFUSION",
"BRING.TYPOGRAPHY.NUMERALS.SMALL_CAPS_AND_FIGURES",
"BRING.TYPOGRAPHY.SERIF.AVOID_MIX_SAME_ROLE",
"BRING.TYPOGRAPHY.SERIF.BODY_TEXT_DEFAULT",
"BRING.TYPOGRAPHY.SERIF.PAIR_WITH_COMPATIBLE_XHEIGHT",
"BRING.TYPOGRAPHY.SERIF.SANS_FOR_DISPLAY",
"BRING.TYPOGRAPHY.SERIF.SERIF_SANS_BALANCE",
"BRING.TYPOGRAPHY.SERIF.STROKE_CONTRAST_COMPATIBLE",
"BRING.TYPOGRAPHY.SIZE.AVOID_TOO_MANY_SIZES",
"BRING.TYPOGRAPHY.SIZE.BODY_SIZE_MATCH_MEASURE",
"BRING.TYPOGRAPHY.SIZE.DISPLAY_SIZE_BALANCE",
"BRING.TYPOGRAPHY.SIZE.SCALE_CONSISTENT",
"BRING.TYPOGRAPHY.SIZE.SMALL_TEXT_MINIMUM",
"BRING.TYPOGRAPHY.SPACING.INITIALS.THIN_SPACE",
"BRING.TYPOGRAPHY.TYPEFACE.CONTRAST_INTENTIONAL",
"BRING.TYPOGRAPHY.TYPEFACE.DISPLAY_FACES_FOR_DISPLAY",
"BRING.TYPOGRAPHY.TYPEFACE.FAMILY_WITH_VARIANTS",
"BRING.TYPOGRAPHY.TYPEFACE.GLYPH_COVERAGE_REQUIRED",
"BRING.TYPOGRAPHY.TYPEFACE.LEGIBILITY_AT_SIZE",
"BRING.TYPOGRAPHY.TYPEFACE.LIMIT_NUMBER",
"BRING.TYPOGRAPHY.TYPEFACE.MIXING_BY_ROLE_ONLY",
"BRING.TYPOGRAPHY.TYPEFACE.PURPOSE_MATCH_CONTENT",
"BRING.TYPOGRAPHY.TYPEFACE.SIMILAR_FACES_AVOID",
"BRING.TYPOGRAPHY.TYPEFACE.TEXT_FACES_FOR_BODY",
"BRING.TYPOGRAPHY.WEIGHT.AVOID_TOO_MANY_WEIGHTS",
"BRING.TYPOGRAPHY.WEIGHT.BOLD_IN_LONG_PASSAGES_AVOID",
"BRING.TYPOGRAPHY.WEIGHT.HEAVY_WEIGHTS_SHORT_LABELS",
"BRING.TYPOGRAPHY.WEIGHT.HIERARCHY_CLEAR",
"CMOS.ABBREVIATIONS.ACADEMIC.DEGREES.STYLE",
"CMOS.ABBREVIATIONS.ACRONYMS.AVOID_IN_HEADINGS",
"CMOS.ABBREVIATIONS.ACRONYMS.AVOID_SENTENCE_START",
"CMOS.ABBREVIATIONS.ACRONYMS.AVOID_STACKING",
"CMOS.ABBREVIATIONS.ACRONYMS.REINTRODUCE_AFTER_GAP",
"CMOS.ABBREVIATIONS.AVOID_ONE_OFFS",
"CMOS.ABBREVIATIONS.BIBLIOGRAPHY.STANDARDS.FOLLOW",
"CMOS.ABBREVIATIONS.CAPS.AVOID_ALL_CAPS_WORDS",
"CMOS.ABBREVIATIONS.CAPTIONS.DEFINE_ON_FIRST_USE",
"CMOS.ABBREVIATIONS.COMPANIES.INC_LTD.CONSISTENT",
"CMOS.ABBREVIATIONS.COUNTRIES.ABBREV_IN_TABLES_ONLY",
"CMOS.ABBREVIATIONS.DAYS.ABBREV_IN_TABLES",
"CMOS.ABBREVIATIONS.DAYS.SPELL_OUT_IN_TEXT",
"CMOS.ABBREVIATIONS.FOOTNOTES.ABBREV_ON_FIRST_USE",
"CMOS.ABBREVIATIONS.GENERAL.AVOID_OVERUSE",
"CMOS.ABBREVIATIONS.GENERAL.CONSISTENCY",
"CMOS.ABBREVIATIONS.GENERAL.GLOSSARY.WHEN_NEEDED",
"CMOS.ABBREVIATIONS.GEOGRAPHY.STATE_ABBREVS.CONSISTENT",
"CMOS.ABBREVIATIONS.INITIALISMS.NO_PERIODS.DEFAULT",
"CMOS.ABBREVIATIONS.LATIN.EG_IE.PUNCTUATION",
"CMOS.ABBREVIATIONS.LATIN.ET_AL.USE",
"CMOS.ABBREVIATIONS.LATIN.VERSUS_ENGLISH",
"CMOS.ABBREVIATIONS.MEASURES.SI.SPACE",
"CMOS.ABBREVIATIONS.MONTHS.ABBREV_IN_TABLES",
"CMOS.ABBREVIATIONS.MONTHS.SPELL_OUT_IN_TEXT",
"CMOS.ABBREVIATIONS.NAMES.INITIALS.SPACING",
"CMOS.ABBREVIATIONS.ORGANIZATIONS.SPELL_OUT_FIRST",
"CMOS.ABBREVIATIONS.PARENTHETICALS.AVOID_STACKING",
"CMOS.ABBREVIATIONS.POSSESSIVE.FORM",
"CMOS.ABBREVIATIONS.PUNCTUATION.ABBREV_WITH_PERIODS.AVOID_DOUBLE",
"CMOS.ABBREVIATIONS.READER_FAMILIARITY",
"CMOS.ABBREVIATIONS.STATES.POSTAL_ONLY",
"CMOS.ABBREVIATIONS.STATES.SPELL_OUT_IN_TEXT",
"CMOS.ABBREVIATIONS.TABLES.ABBREV_KEY",
"CMOS.ABBREVIATIONS.TABLES.KEYS.WHEN_DENSE",
"CMOS.ABBREVIATIONS.TECH.TERMS.CASE_SENSITIVE",
"CMOS.ABBREVIATIONS.TIME.AM_PM.FORM",
"CMOS.ABBREVIATIONS.TITLES.COURTESY_PERIODS",
"CMOS.ABBREVIATIONS.TITLES.HONORIFICS.CONSISTENT",
"CMOS.ABBREVIATIONS.TITLES.JR_SR.CONSISTENT",
"CMOS.ABBREVIATIONS.UNITS.ABBREV_WITH_NUMERALS_ONLY",
"CMOS.ABBREVIATIONS.UNITS.NO_PERIODS",
"CMOS.ABBREVIATIONS.UNITS.NO_PLURAL_SYMBOLS",
"CMOS.ABBREVIATIONS.UNITS.SPELL_OUT_WITHOUT_NUMERALS",
"CMOS.ABBREVIATIONS.US_USA.CONSISTENT",
"CMOS.BACKMATTER.ABBREVIATIONS.LIST.WHEN_NEEDED",
"CMOS.BACKMATTER.ACKNOWLEDGMENTS.PLACEMENT",
"CMOS.BACKMATTER.APPENDICES.CROSS_REFERENCES",
"CMOS.BACKMATTER.APPENDICES.FORMAT_MATCH",
"CMOS.BACKMATTER.APPENDICES.LABELED",
"CMOS.BACKMATTER.APPENDICES.SOURCES",
"CMOS.BACKMATTER.APPENDIX.NUMBERING.SEQUENTIAL",
"CMOS.BACKMATTER.APPENDIX.START_ON_NEW_PAGE",
"CMOS.BACKMATTER.APPENDIX.TOC.ENTRIES",
"CMOS.BACKMATTER.BIBLIOGRAPHY.CONSISTENT_STYLE",
"CMOS.BACKMATTER.BIBLIOGRAPHY.SORTING",
"CMOS.BACKMATTER.CONTACT.SUPPORT",
"CMOS.BACKMATTER.DATA.AVAILABILITY",
"CMOS.BACKMATTER.ENDNOTES.VERSUS_FOOTNOTES.CONSISTENT",
"CMOS.BACKMATTER.ERRATA.WHEN_NEEDED",
"CMOS.BACKMATTER.GLOSSARY.DEFINITIONS.CONCISE",
"CMOS.BACKMATTER.GLOSSARY.SORTING",
"CMOS.BACKMATTER.GLOSSARY.TERMS.CONSISTENT_STYLE",
"CMOS.BACKMATTER.GLOSSARY.WHEN_TERMS",
"CMOS.BACKMATTER.INDEX.ABBREVIATIONS.CONSISTENT",
"CMOS.BACKMATTER.INDEX.CROSS_REFERENCES.CONSISTENT",
"CMOS.BACKMATTER.INDEX.ENTRIES.CONSISTENT_CASE",
"CMOS.BACKMATTER.INDEX.LOCATORS.ACCURATE",
"CMOS.BACKMATTER.INDEX.NAMES.SORTING",
"CMOS.BACKMATTER.INDEX.PAGE_RANGES.STANDARD",
"CMOS.BACKMATTER.INDEX.SEE_ALSO.USE_WHEN_NEEDED",
"CMOS.BACKMATTER.INDEX.SUBENTRIES.NESTED",
"CMOS.BACKMATTER.INDEX.SUBENTRY.ORDER.LOGICAL",
"CMOS.BACKMATTER.INDEX.WHEN_REQUIRED",
"CMOS.BACKMATTER.LICENSES.THIRD_PARTY",
"CMOS.BACKMATTER.NOTES.BLOCKS.CONSISTENT",
"CMOS.BACKMATTER.NOTES.CITATIONS.COMPLETE",
"CMOS.BACKMATTER.NOTES.NUMBERING.SEQUENTIAL",
"CMOS.BACKMATTER.NOTES.ORDER.FOLLOW_TEXT",
"CMOS.BACKMATTER.NOTES.REFERENCE.MATCH",
"CMOS.BACKMATTER.REFERENCES.ACCESS_DATES.WHEN_NEEDED",
"CMOS.BACKMATTER.REFERENCES.AUTHOR_NAMES.CONSISTENT",
"CMOS.BACKMATTER.REFERENCES.DOI.OR_URL",
"CMOS.BACKMATTER.REFERENCES.SECTION_PRESENT",
"CMOS.BACKMATTER.REFERENCES.URLS.STABLE",
"CMOS.CITATIONS.AUTHOR_DATE.IN_TEXT.DIRECT_QUOTES",
"CMOS.CITATIONS.AUTHOR_DATE.IN_TEXT.EXTRA_INFO",
"CMOS.CITATIONS.AUTHOR_DATE.IN_TEXT.LOCATORS",
"CMOS.CITATIONS.AUTHOR_DATE.IN_TEXT.MULTI_SOURCES",
"CMOS.CITATIONS.AUTHOR_DATE.IN_TEXT.PARENTHETICAL",
"CMOS.CITATIONS.AUTHOR_DATE.IN_TEXT.PLACEMENT",
"CMOS.CITATIONS.AUTHOR_DATE.REFERENCE_LIST.ALPHABETICAL",
"CMOS.CITATIONS.AUTHOR_DATE.REFERENCE_LIST.ORDER_AND_YEAR",
"CMOS.CITATIONS.AUTHOR_DATE.REFERENCE_LIST.REPEATED_NAMES",
"CMOS.CITATIONS.AUTHOR_DATE.REFERENCE_LIST.REQUIRED",
"CMOS.CITATIONS.BIBLIOGRAPHY.ALT_NAMES.CROSSREF",
"CMOS.CITATIONS.BIBLIOGRAPHY.AUTHOR_NAME.CONSISTENT_FORM",
"CMOS.CITATIONS.BIBLIOGRAPHY.AUTHOR_NAME.INITIALS_PREFERRED",
"CMOS.CITATIONS.BIBLIOGRAPHY.AUTHOR_NAME.PUBLISHED_FORM",
"CMOS.CITATIONS.BIBLIOGRAPHY.MULTI_AUTHORS.ORDER",
"CMOS.CITATIONS.BIBLIOGRAPHY.NO_AUTHOR.TITLE_LEAD",
"CMOS.CITATIONS.BIBLIOGRAPHY.PSEUDONYMS.CONSISTENT",
"CMOS.CITATIONS.BIBLIOGRAPHY.REPEATED_NAMES.THREE_EM_DASH",
"CMOS.CITATIONS.BIBLIOGRAPHY.SAME_AUTHOR.ORDER",
"CMOS.CITATIONS.BIBLIOGRAPHY.SAME_SURNAME.DISAMBIGUATE",
"CMOS.CITATIONS.IBID.MINIMIZE_OR_AVOID",
"CMOS.CITATIONS.LEGAL_PUBLIC_DOCS.USE_JURISDICTIONAL_FORMAT",
"CMOS.CITATIONS.MATCHING.BIBLIO_ENTRY_REQUIRED",
"CMOS.CITATIONS.NOTES.AUTHOR_DATE_PLUS_NOTES",
"CMOS.CITATIONS.NOTES.AVOID_OVERLONG",
"CMOS.CITATIONS.NOTES.CHAPTER_IN_EDITED_BOOK",
"CMOS.CITATIONS.NOTES.ENDNOTES.AVOID_IBID",
"CMOS.CITATIONS.NOTES.ENDNOTES.PLACEMENT",
"CMOS.CITATIONS.NOTES.ENDNOTES.RUNNING_HEADS",
"CMOS.CITATIONS.NOTES.FOOTNOTES_VS_ENDNOTES.CHOOSE",
"CMOS.CITATIONS.NOTES.JOURNAL.ARTICLE_ELEMENTS",
"CMOS.CITATIONS.NOTES.LONG_NOTES.PARAGRAPHING",
"CMOS.CITATIONS.NOTES.MULTIPLE_CITATIONS.SINGLE_NOTE",
"CMOS.CITATIONS.NOTES.QUOTE_IN_NOTE.LOCATOR",
"CMOS.CITATIONS.NOTES.SHORT_FORM.BASIC_ELEMENTS",
"CMOS.CITATIONS.NOTES.SHORT_FORM.CROSS_REFERENCE",
"CMOS.CITATIONS.NOTES.SOURCE_NOTES.REPRINTS",
"CMOS.CITATIONS.NOTES.SUBSTANTIVE.SEPARATE_FROM_SOURCE",
"CMOS.CITATIONS.NOTES.UNNUMBERED.NOT_FOR_SOURCES",
"CMOS.CITATIONS.NOTES_BIBLIO.BIBLIOGRAPHY.INCLUDE_WHEN_USED",
"CMOS.CITATIONS.NOTES_BIBLIO.BIBLIOGRAPHY.SORT_BY_AUTHOR",
"CMOS.CITATIONS.NOTES_BIBLIO.FIRST_NOTE.FULL_REFERENCE",
"CMOS.CITATIONS.NOTES_BIBLIO.NAME_ORDER.NOTES_VS_BIBLIO",
"CMOS.CITATIONS.NOTES_BIBLIO.SUBSEQUENT_NOTES.SHORT_FORM",
"CMOS.CITATIONS.ONLINE.ACCESS_DATE.WHEN_NEEDED",
"CMOS.CITATIONS.ONLINE.PERMALINKS.PREFERRED",
"CMOS.CITATIONS.ONLINE.REVISION_DATE.DISTINCT",
"CMOS.CITATIONS.ONLINE.URLS.STABLE",
"CMOS.CITATIONS.ONLINE.VERSION.CITE_RIGHT_VERSION",
"CMOS.CITATIONS.QUOTATIONS.LOCATORS.PAGE_REQUIRED",
"CMOS.CITATIONS.RESEARCH.METADATA.CAPTURE_EARLY",
"CMOS.CITATIONS.SYSTEM.CONSISTENT_CHOICE",
"CMOS.CITATIONS.TITLES.CAPITALIZATION.CONSISTENT",
"CMOS.FIGURES.ACCESSIBILITY.ALT_TEXT",
"CMOS.FIGURES.ANNOTATIONS.CONSISTENT_STYLE",
"CMOS.FIGURES.ASPECT_RATIO.PRESERVE",
"CMOS.FIGURES.AXES.UNITS.CONSISTENT",
"CMOS.FIGURES.BLEED.ONLY_WHEN_ENABLED",
"CMOS.FIGURES.CALL_OUTS.AVOID_OVERLAP",
"CMOS.FIGURES.CAPTION.ALIGNMENT.CONSISTENT",
"CMOS.FIGURES.CAPTION.CREDITS.INLINE_OR_NOTE",
"CMOS.FIGURES.CAPTION.FONT.CONSISTENT",
"CMOS.FIGURES.CAPTION.LENGTH.REASONABLE",
"CMOS.FIGURES.CAPTION.NUMBER.MATCH_LABEL",
"CMOS.FIGURES.CAPTION.PLACEMENT.CONSISTENT",
"CMOS.FIGURES.CAPTION.PREFIX.CONSISTENT",
"CMOS.FIGURES.CAPTION.PUNCTUATION.CONSISTENT",
"CMOS.FIGURES.CAPTIONS.PRESENT",
"CMOS.FIGURES.COLOR.NOT_SOLE_SIGNAL",
"CMOS.FIGURES.COLOR.PALETTE.CONSISTENT",
"CMOS.FIGURES.CONTRAST.SUFFICIENT",
"CMOS.FIGURES.CREDIT.SOURCE_WHEN_REQUIRED",
"CMOS.FIGURES.CROP.AVOID_LOSS",
"CMOS.FIGURES.EMBEDDED_TEXT.MINIMAL",
"CMOS.FIGURES.FILENAME.STABLE",
"CMOS.FIGURES.FORMAT.VECTOR_WHEN_POSSIBLE",
"CMOS.FIGURES.KEY.READABLE",
"CMOS.FIGURES.LABELS.AVOID_OVERLAP",
"CMOS.FIGURES.LABELS.FONT.CONSISTENT",
"CMOS.FIGURES.LEGENDS.EXPLAIN_SYMBOLS",
"CMOS.FIGURES.LINE_WEIGHTS.CONSISTENT",
"CMOS.FIGURES.LIST_ENTRIES.MATCH_CAPTIONS",
"CMOS.FIGURES.LIST_OF_FIGURES.WHEN_NEEDED",
"CMOS.FIGURES.MARGINS.AVOID_CLIPPING",
"CMOS.FIGURES.MULTIPART.PANEL_LABELS",
"CMOS.FIGURES.NUMBERING.SEQUENTIAL",
"CMOS.FIGURES.NUMBERING.WITHIN_CHAPTERS",
"CMOS.FIGURES.ORIENTATION.CONSISTENT",
"CMOS.FIGURES.PANEL_ORDER.LOGICAL",
"CMOS.FIGURES.PERMISSIONS.DOCUMENTED",
"CMOS.FIGURES.PLACEMENT.AVOID_SPLIT",
"CMOS.FIGURES.PLACEMENT.NEAR_MENTION",
"CMOS.FIGURES.PLACEMENT.TOP_OR_BOTTOM.CONSISTENT",
"CMOS.FIGURES.REFERENCES.IN_TEXT",
"CMOS.FIGURES.RESOLUTION.RASTER_SUFFICIENT",
"CMOS.FIGURES.SCALE.LEGIBLE",
"CMOS.FIGURES.SCALING.UNIFORM",
"CMOS.FIGURES.SENSITIVE.DATA.REDACT",
"CMOS.FIGURES.SIZE.MATCH_READABILITY",
"CMOS.FIGURES.SOURCE.DATA.CITED",
"CMOS.FIGURES.SYMBOLS.CONSISTENT",
"CMOS.FIGURES.TABLE_VS_FIGURE.CHOOSE",
"CMOS.FIGURES.UNITS.LABEL_AXES",
"CMOS.FRONTMATTER.ABSTRACT.WHEN_APPROPRIATE",
"CMOS.FRONTMATTER.ACCESSIBILITY.NOTES",
"CMOS.FRONTMATTER.ACKNOWLEDGMENTS.NAMES.CONSISTENT",
"CMOS.FRONTMATTER.ACKNOWLEDGMENTS.PLACEMENT",
"CMOS.FRONTMATTER.ACKNOWLEDGMENTS.SCOPE",
"CMOS.FRONTMATTER.AUDIENCE.SCOPE.STATED",
"CMOS.FRONTMATTER.CHANGELOG.LINKS",
"CMOS.FRONTMATTER.CITATION_STYLE.DECLARED",
"CMOS.FRONTMATTER.CONTACT.OWNERSHIP",
"CMOS.FRONTMATTER.COPYRIGHT.NOTICES.PRESENT",
"CMOS.FRONTMATTER.COPYRIGHT.RIGHTS.CONTACT",
"CMOS.FRONTMATTER.DISCLAIMERS.WHEN_REQUIRED",
"CMOS.FRONTMATTER.EDITION.VERSION_VISIBLE",
"CMOS.FRONTMATTER.EPIGRAPH.ATTRIBUTION",
"CMOS.FRONTMATTER.EPIGRAPH.PLACEMENT.CONSISTENT",
"CMOS.FRONTMATTER.FOREWORD.AUTHOR.ATTRIBUTED",
"CMOS.FRONTMATTER.FOREWORD.DATE_IF_PRESENT",
"CMOS.FRONTMATTER.INTRODUCTION.SCOPE",
"CMOS.FRONTMATTER.LANGUAGE.NOTICE",
"CMOS.FRONTMATTER.LICENSE.ATTRIBUTION",
"CMOS.FRONTMATTER.LISTS.OF_FIGURES_TABLES.WHEN_NEEDED",
"CMOS.FRONTMATTER.LIST_OF_FIGURES.SECTION_TITLE",
"CMOS.FRONTMATTER.LIST_OF_TABLES.SECTION_TITLE",
"CMOS.FRONTMATTER.NAVIGATION.METADATA",
"CMOS.FRONTMATTER.PREFACE.DATE_IF_PRESENT",
"CMOS.FRONTMATTER.PREFACE.PURPOSE",
"CMOS.FRONTMATTER.READING_TIME.WHEN_HELPFUL",
"CMOS.FRONTMATTER.REVISION_HISTORY.WHEN_REQUIRED",
"CMOS.FRONTMATTER.SECURITY.CLASSIFICATION",
"CMOS.FRONTMATTER.TERMS.DEFINITIONS.EARLY",
"CMOS.FRONTMATTER.TITLEPAGE.PRESENT",
"CMOS.FRONTMATTER.TOC.ENTRIES.MATCH_HEADINGS",
"CMOS.FRONTMATTER.TOC.FRONT_BACK_MATTER.INCLUDED",
"CMOS.FRONTMATTER.TOC.INDENTATION.BY_LEVEL",
"CMOS.FRONTMATTER.TOC.LEADERS.CONSISTENT",
"CMOS.FRONTMATTER.TOC.LEVELS.CONSISTENT",
"CMOS.FRONTMATTER.TOC.ORDER.MATCH_BODY",
"CMOS.FRONTMATTER.TOC.PAGE_NUMBERS.MATCH",
"CMOS.FRONTMATTER.TOC.SHORT_TITLES.CONSISTENT",
"CMOS.FRONTMATTER.TOC.WHEN_NEEDED",
"CMOS.HEADINGS.DIVISIONS.CHAPTERS.MULTIAUTHOR",
"CMOS.HEADINGS.DIVISIONS.LETTERS_DIARIES.HEADINGS",
"CMOS.HEADINGS.LETTERS_DIARIES.DATELINE_FORMAT",
"CMOS.HEADINGS.LETTERS_DIARIES.SIGNATURE_FORMAT",
"CMOS.HEADINGS.MULTIAUTHOR.AUTHOR_ATTRIBUTION_PLACEMENT",
"CMOS.HEADINGS.MULTIAUTHOR.CHAPTER_NUMBERING",
"CMOS.HEADINGS.RUNNING_HEADS.DEFINITION",
"CMOS.HEADINGS.RUNNING_HEADS.DIVISION_MATCH",
"CMOS.HEADINGS.RUNNING_HEADS.LENGTH_SHORT",
"CMOS.HEADINGS.RUNNING_HEADS.NAVIGATION_SCOPE",
"CMOS.I18N.ACRONYMS.LANGUAGE_SPECIFIC",
"CMOS.I18N.CAPITALIZATION.TITLES.LANGUAGE_RULES",
"CMOS.I18N.CITATIONS.TITLES.ORIGINAL_OR_TRANSLATED",
"CMOS.I18N.CURRENCY.CODES.LABEL",
"CMOS.I18N.DATES.FORMAT.CONSISTENT",
"CMOS.I18N.DIACRITICS.PRESERVE",
"CMOS.I18N.GLOSSARY.MULTILINGUAL",
"CMOS.I18N.HYPHENATION.LANGUAGE_TAGS",
"CMOS.I18N.ITALICS.FOREIGN_WORDS.SPARE",
"CMOS.I18N.LANGUAGE.CONSISTENT_SPELLING",
"CMOS.I18N.MEANINGFUL_TRANSLATIONS.NOT_LITERAL",
"CMOS.I18N.NAMES.SORTING.COLLATION",
"CMOS.I18N.NUMBERS.DECIMAL_SEPARATOR.LOCALE",
"CMOS.I18N.PARENS.BRACKETS.TRANSLATOR_NOTES",
"CMOS.I18N.PUNCTUATION.DASHES.MINUS_SIGN",
"CMOS.I18N.PUNCTUATION.ELLIPSIS.STYLE",
"CMOS.I18N.PUNCTUATION.SPACING.LANGUAGE_RULES",
"CMOS.I18N.QUOTES.NESTING.CONSISTENT",
"CMOS.I18N.QUOTES.STYLE.MATCH_LOCALE",
"CMOS.I18N.RIGHT_TO_LEFT.MARKUP",
"CMOS.I18N.ROMANIZATION.DIACRITICS.KEEP",
"CMOS.I18N.SCRIPT_MIXING.AVOID",
"CMOS.I18N.SECURITY.HOMOGLYPHS.AWARE",
"CMOS.I18N.TRANSLATION.INDICATE",
"CMOS.I18N.TRANSLITERATION.SYSTEM.CONSISTENT",
"CMOS.I18N.TYPOGRAPHY.FONT_COVERAGE",
"CMOS.I18N.UNITS.SYMBOLS.STANDARD",
"CMOS.LAYOUT.FOOTNOTES.PLACEMENT",
"CMOS.LAYOUT.FOOTNOTES.SEQUENCE",
"CMOS.LAYOUT.ILLUSTRATIONS.PLACEMENT_NEAR_REF",
"CMOS.LAYOUT.PAGINATION.FACING_PAGES.BALANCE",
"CMOS.LAYOUT.PAGINATION.FACING_PAGES.BLANKS",
"CMOS.LAYOUT.PAGINATION.PAGE_BREAKS.BEFORE_PARTS",
"CMOS.LAYOUT.PAGINATION.PAGE_NUMBERS.POSITION",
"CMOS.LAYOUT.PAGINATION.PAGE_NUMBERS.STYLE",
"CMOS.LAYOUT.PAGINATION.PAGE_SEQUENCE.CONTINUITY",
"CMOS.LAYOUT.PAGINATION.RUNNING_HEADS.CONSISTENCY",
"CMOS.LAYOUT.PAGINATION.RUNNING_HEADS.PLACEMENT",
"CMOS.LAYOUT.RUNNING_HEADS.CHAPTER_TITLES",
"CMOS.LAYOUT.RUNNING_HEADS.SECTION_TITLES",
"CMOS.LAYOUT.TABLES.PLACEMENT_NEAR_REF",
"CMOS.NUMBERS.BASES.NON_DECIMAL.NO_GROUPING",
"CMOS.NUMBERS.CENTURIES.SPELLED_OUT",
"CMOS.NUMBERS.CONSISTENCY.MIXED_FORMS.AVOID",
"CMOS.NUMBERS.CONTEXTS.ALWAYS_NUMERALS",
"CMOS.NUMBERS.CURRENCY.CODE_POSITION.CONSISTENT",
"CMOS.NUMBERS.CURRENCY.FORMAT.SYMBOL_PLACEMENT",
"CMOS.NUMBERS.CURRENCY.HISTORICAL.YEAR_CONTEXT",
"CMOS.NUMBERS.CURRENCY.ISO_CODES",
"CMOS.NUMBERS.CURRENCY.LARGE_AMOUNTS",
"CMOS.NUMBERS.CURRENCY.NON_US.DISAMBIGUATE",
"CMOS.NUMBERS.CURRENCY.RANGES.REPEAT_SYMBOL",
"CMOS.NUMBERS.CURRENCY.SYMBOL_ADJACENT",
"CMOS.NUMBERS.CURRENCY.WORDS_VS_SYMBOLS",
"CMOS.NUMBERS.DATES.ABBREVIATED_YEAR",
"CMOS.NUMBERS.DATES.ALL_NUMERAL",
"CMOS.NUMBERS.DATES.CONSISTENT_FORMAT",
"CMOS.NUMBERS.DATES.DAY_MONTH_ORDER.CONSISTENT",
"CMOS.NUMBERS.DATES.ISO_8601",
"CMOS.NUMBERS.DATES.MONTH_DAY_STYLE",
"CMOS.NUMBERS.DATES.ORDINALS.AVOID",
"CMOS.NUMBERS.DATES.YEAR_NUMERALS",
"CMOS.NUMBERS.DECADES.CONSISTENT_FORM",
"CMOS.NUMBERS.DECIMALS.TRAILING_ZEROS.AVOID",
"CMOS.NUMBERS.DENSE_CONTEXT.USE_NUMERALS",
"CMOS.NUMBERS.ERAS.BCE_CE",
"CMOS.NUMBERS.FRACTIONS.ADJECTIVAL.HYPHENATE",
"CMOS.NUMBERS.FRACTIONS.MATH.NUMERALS",
"CMOS.NUMBERS.FRACTIONS.MIXED.WHOLE_PLUS_FRACTION",
"CMOS.NUMBERS.FRACTIONS.SIMPLE.SPELL_OUT",
"CMOS.NUMBERS.FRACTIONS.SLASH_INLINE",
"CMOS.NUMBERS.INCLUSIVE.COMMAS",
"CMOS.NUMBERS.INCLUSIVE.SHORTEN_SECOND_NUMBER",
"CMOS.NUMBERS.INCLUSIVE.YEARS",
"CMOS.NUMBERS.INCLUSIVE.YEARS.CENTURY_CROSSING",
"CMOS.NUMBERS.INCLUSIVE_RANGES.PAGE_NUMBERS.SHORTEN",
"CMOS.NUMBERS.LARGE_VALUES.MILLIONS_BILLIONS",
"CMOS.NUMBERS.LISTS.OUTLINE.NUMERAL_STYLE",
"CMOS.NUMBERS.NAMES.MONARCHS_POPES",
"CMOS.NUMBERS.NUMERALS.MEASUREMENTS.UNITS",
"CMOS.NUMBERS.ORDINALS.CONSISTENT_FORM",
"CMOS.NUMBERS.PERCENTAGES.SYMBOL_NO_SPACE",
"CMOS.NUMBERS.PERCENTAGES.SYMBOL_OR_WORD.CONSISTENT",
"CMOS.NUMBERS.PERIODICALS.VOLUME_ISSUE",
"CMOS.NUMBERS.PLACES.BUILDINGS_APTS",
"CMOS.NUMBERS.PLACES.HIGHWAYS",
"CMOS.NUMBERS.PLACES.STREETS",
"CMOS.NUMBERS.PLURALS.SPELLED_OUT",
"CMOS.NUMBERS.RANGES.NO_MIXED_FROM_BETWEEN",
"CMOS.NUMBERS.RANGES.REPEAT_UNIT_IF_AMBIG",
"CMOS.NUMBERS.RANGES.UNITS.PLACEMENT_CONSISTENT",
"CMOS.NUMBERS.RATIOS.COLON_SPACING",
"CMOS.NUMBERS.RATIOS.FORMAT",
"CMOS.NUMBERS.REFERENCES.PAGE_CHAPTER_FIGURE",
"CMOS.NUMBERS.ROMAN_NUMERALS.CASE_CONSISTENT",
"CMOS.NUMBERS.ROMAN_NUMERALS.USE",
"CMOS.NUMBERS.ROUND_NUMBERS.SPELL_OUT",
"CMOS.NUMBERS.RULE_SELECTION.ALTERNATIVE_ZERO_TO_NINE",
"CMOS.NUMBERS.RULE_SELECTION.GENERAL_OR_ALTERNATIVE",
"CMOS.NUMBERS.SCIENTIFIC.NOTATION.MANTISSA_RANGE",
"CMOS.NUMBERS.SCIENTIFIC.NOTATION.TIMES_SYMBOL",
"CMOS.NUMBERS.SCIENTIFIC.POWERS_OF_TEN",
"CMOS.NUMBERS.SENTENCE_START.AVOID_NUMERAL",
"CMOS.NUMBERS.SPELLING.ONE_TO_ONE_HUNDRED.DEFAULT",
"CMOS.NUMBERS.TELEPHONE.COUNTRY_CODE.WHEN_INTERNATIONAL",
"CMOS.NUMBERS.TELEPHONE.FORMAT",
"CMOS.NUMBERS.TELEPHONE.SEPARATORS.CONSISTENT",
"CMOS.NUMBERS.TIME.AM_PM.CONSISTENT_SPACING",
"CMOS.NUMBERS.TIME.GENERAL_NUMERALS",
"CMOS.NUMBERS.TIME.ISO_STYLE",
"CMOS.NUMBERS.TIME.LEADING_ZERO_MINUTES",
"CMOS.NUMBERS.TIME.NOON_MIDNIGHT",
"CMOS.NUMBERS.TIME.RANGES.CONSISTENT_FORMAT",
"CMOS.NUMBERS.TIME.SECONDS.INCLUDE_FOR_PRECISION",
"CMOS.NUMBERS.TIME.SECONDS.OMIT_IF_NOT_NEEDED",
"CMOS.NUMBERS.TIME.TWENTY_FOUR_HOUR",
"CMOS.NUMBERS.TIME.ZONE.INCLUDE_WHEN_AMBIGUOUS",
"CMOS.NUMBERS.UNITS.REPEATED.OMIT_REPEAT",
"CMOS.NUMBERS.UNITS.SPACE_BETWEEN_NUMBER_UNIT",
"CMOS.NUMBERS.VEHICLES.VESSELS_NUMBERS",
"CMOS.PUNCTUATION.BRACKETS.EDITORIAL_INSERTIONS",
"CMOS.PUNCTUATION.BRACKETS.NESTED_PARENS",
"CMOS.PUNCTUATION.BRACKETS.TRANSLATED_TEXT",
"CMOS.PUNCTUATION.COLONS.AS_FOLLOWS",
"CMOS.PUNCTUATION.COLONS.AVOID_AFTER_PREPOSITION",
"CMOS.PUNCTUATION.COLONS.CAPITALIZATION",
"CMOS.PUNCTUATION.COLONS.COMPLETE_CLAUSE_REQUIRED",
"CMOS.PUNCTUATION.COLONS.INTRODUCE_FORMAL_LISTS",
"CMOS.PUNCTUATION.COLONS.INTRO_QUOTE_QUESTION",
"CMOS.PUNCTUATION.COMMAS.ADDRESSES",
"CMOS.PUNCTUATION.COMMAS.APPOSITIVES",
"CMOS.PUNCTUATION.COMMAS.COMPOUND_PREDICATES",
"CMOS.PUNCTUATION.COMMAS.DATES",
"CMOS.PUNCTUATION.COMMAS.DEPENDENT_CLAUSE_AFTER",
"CMOS.PUNCTUATION.COMMAS.DESCRIPTIVE_PHRASES",
"CMOS.PUNCTUATION.COMMAS.INTRODUCTORY_ELEMENTS.CLARITY",
"CMOS.PUNCTUATION.COMMAS.INTRODUCTORY_PHRASES",
"CMOS.PUNCTUATION.COMMAS.NONRESTRICTIVE.SET_OFF",
"CMOS.PUNCTUATION.COMMAS.PARTICIPIAL_PHRASES",
"CMOS.PUNCTUATION.COMMAS.QUESTIONS",
"CMOS.PUNCTUATION.COMMAS.QUOTED_TITLES",
"CMOS.PUNCTUATION.COMMAS.REPEATED_ADJECTIVES",
"CMOS.PUNCTUATION.COMMAS.RESTRICTIVE.NO_SET_OFF",
"CMOS.PUNCTUATION.DASHES.EM_DASH.SPARE_USE",
"CMOS.PUNCTUATION.DASHES.EM_INSTEAD_OF_QUOTES",
"CMOS.PUNCTUATION.DASHES.EN_DASH.WORD_RANGES",
"CMOS.PUNCTUATION.EXCLAMATION.USE_SPARINGLY",
"CMOS.PUNCTUATION.EXCLAMATION.VS_QUESTION",
"CMOS.PUNCTUATION.HYPHENATION.COMPOUND_DEFINITION",
"CMOS.PUNCTUATION.HYPHENATION.GENERAL_CHOICE",
"CMOS.PUNCTUATION.HYPHENATION.READABILITY",
"CMOS.PUNCTUATION.HYPHENATION.SUSPENDED",
"CMOS.PUNCTUATION.HYPHENATION.TREND_CLOSED",
"CMOS.PUNCTUATION.HYPHENS.ADVERB_LY.NO_HYPHEN",
"CMOS.PUNCTUATION.HYPHENS.COMPOUND_MODIFIERS.BEFORE_NOUN",
"CMOS.PUNCTUATION.HYPHENS.NUMERIC_COMPOUNDS",
"CMOS.PUNCTUATION.PARENS.GLOSSES_TRANSLATIONS",
"CMOS.PUNCTUATION.PARENS.NESTING",
"CMOS.PUNCTUATION.PARENS.PUNCTUATION_PLACEMENT",
"CMOS.PUNCTUATION.PARENS.USE",
"CMOS.PUNCTUATION.PERIODS.USE",
"CMOS.PUNCTUATION.PERIODS.WITH_PARENS",
"CMOS.PUNCTUATION.QUESTION_MARK.DIRECT_VS_INDIRECT",
"CMOS.PUNCTUATION.QUESTION_MARK.USE",
"CMOS.PUNCTUATION.QUESTION_MARK.WITH_PUNCT",
"CMOS.PUNCTUATION.QUESTION_MARKS.QUOTE_PLACEMENT",
"CMOS.PUNCTUATION.QUOTATION_MARKS.DOUBLE_PRIMARY_US",
"CMOS.PUNCTUATION.QUOTATION_MARKS.PUNCTUATION_PLACEMENT_US",
"CMOS.PUNCTUATION.SEMICOLONS.AVOID_COMMA_SPLICE",
"CMOS.PUNCTUATION.SEMICOLONS.BEFORE_CONJUNCTION",
"CMOS.PUNCTUATION.SEMICOLONS.COMPLEX_SERIES.SEPARATE",
"CMOS.PUNCTUATION.SEMICOLONS.CONJUNCTIVE_PHRASES",
"CMOS.PUNCTUATION.SEMICOLONS.INDEPENDENT_CLAUSES",
"CMOS.PUNCTUATION.SLASHES.ALTERNATIVES",
"CMOS.PUNCTUATION.SLASHES.NO_SPACES",
"CMOS.PUNCTUATION.SLASHES.TWO_YEAR_SPANS",
"CMOS.TABLES.ABBREVIATIONS.EXPLAIN",
"CMOS.TABLES.ALIGNMENT.NUMERIC_DECIMAL",
"CMOS.TABLES.ALIGNMENT.TEXT_LEFT",
"CMOS.TABLES.CAPTIONS.BREVITY",
"CMOS.TABLES.CAPTIONS.CLARITY",
"CMOS.TABLES.CAPTIONS.PRESENT",
"CMOS.TABLES.COLUMN_ORDER.LOGICAL",
"CMOS.TABLES.COLUMN_SPACING.READABLE",
"CMOS.TABLES.DATA_TYPES.NOT_MIXED",
"CMOS.TABLES.FOOTNOTES.PLACEMENT",
"CMOS.TABLES.GRIDLINES.LIGHT",
"CMOS.TABLES.GROUPING.WHITESPACE",
"CMOS.TABLES.HEADERS.ALIGNMENT.CONSISTENT",
"CMOS.TABLES.HEADERS.CAPITALIZATION.CONSISTENT",
"CMOS.TABLES.HEADERS.REQUIRED",
"CMOS.TABLES.MISSING_VALUES.EXPLAIN",
"CMOS.TABLES.NOTES.ORDERED_MARKERS",
"CMOS.TABLES.PRECISION.CONSISTENT",
"CMOS.TABLES.REFERENCES.IN_TEXT",
"CMOS.TABLES.ROTATION.LANDSCAPE.WHEN_NEEDED",
"CMOS.TABLES.ROUNDING.CONSISTENT",
"CMOS.TABLES.ROW_ORDER.LOGICAL",
"CMOS.TABLES.ROW_SPACING.READABLE",
"CMOS.TABLES.RULES.MINIMAL",
"CMOS.TABLES.SHADING.SPARING",
"CMOS.TABLES.SORTING.LOGICAL",
"CMOS.TABLES.SOURCE.NOTES.DISTINCT",
"CMOS.TABLES.SPLITS.AVOID_ROW_BREAKS",
"CMOS.TABLES.SPLITS.REPEAT_HEADERS",
"CMOS.TABLES.STUB_COLUMN.USE",
"CMOS.TABLES.SUBTOTALS.CLEAR",
"CMOS.TABLES.TITLES.NUMBERING.SEQUENTIAL",
"CMOS.TABLES.TITLES.PLACEMENT.CONSISTENT",
"CMOS.TABLES.TITLES.SCOPE.CONSISTENT",
"CMOS.TABLES.UNITS.CONSISTENT",
"CMOS.TABLES.UNITS.IN_HEADERS",
"CMOS.TABLES.WIDTH.FIT_PAGE",
"HOUSE.ACCESSIBILITY.CODE.FENCES.LANGUAGE",
"HOUSE.ACCESSIBILITY.COLOR.NOT_SOLE_CONVEYOR",
"HOUSE.ACCESSIBILITY.CONTRAST.NON_TEXT",
"HOUSE.ACCESSIBILITY.CONTRAST.TEXT_READABLE",
"HOUSE.ACCESSIBILITY.EMPHASIS.USE_SPARELY",
"HOUSE.ACCESSIBILITY.FIGURES.REFERENCED_IN_TEXT",
"HOUSE.ACCESSIBILITY.HEADINGS.HIERARCHY.NO_SKIPS",
"HOUSE.ACCESSIBILITY.HEADINGS.NO_DECORATIVE",
"HOUSE.ACCESSIBILITY.HEADINGS.SINGLE_H1",
"HOUSE.ACCESSIBILITY.IMAGES.ALT_AVOID_DUPLICATE_CAPTION",
"HOUSE.ACCESSIBILITY.IMAGES.ALT_SUMMARY_FOR_CHARTS",
"HOUSE.ACCESSIBILITY.IMAGES.CAPTION_FOR_COMPLEX",
"HOUSE.ACCESSIBILITY.IMAGES.DECORATIVE.EMPTY_ALT",
"HOUSE.ACCESSIBILITY.IMAGES.LINKED.ALT_TARGET",
"HOUSE.ACCESSIBILITY.IMAGES.TEXT_IN_IMAGES.AVOID",
"HOUSE.ACCESSIBILITY.LANGUAGE.METADATA",
"HOUSE.ACCESSIBILITY.LINKS.AVOID_SHORTENERS",
"HOUSE.ACCESSIBILITY.LINKS.FOCUS_ORDER",
"HOUSE.ACCESSIBILITY.LINKS.FOCUS_VISIBLE",
"HOUSE.ACCESSIBILITY.LINKS.ICON_ONLY.TEXT",
"HOUSE.ACCESSIBILITY.LINKS.SKIP_TO_CONTENT",
"HOUSE.ACCESSIBILITY.LINKS.TARGETS.PUBLIC",
"HOUSE.ACCESSIBILITY.LINKS.VISUALLY_DISTINCT",
"HOUSE.ACCESSIBILITY.LINK_TEXT.NO_BARE_URLS",
"HOUSE.ACCESSIBILITY.LISTS.MARKER_CONSISTENT",
"HOUSE.ACCESSIBILITY.LISTS.USE_LIST_MARKUP",
"HOUSE.ACCESSIBILITY.MEDIA.TRANSCRIPTS",
"HOUSE.ACCESSIBILITY.NAVIGATION.FOOTNOTE_BACKLINKS",
"HOUSE.ACCESSIBILITY.NAVIGATION.PDF_BOOKMARKS",
"HOUSE.ACCESSIBILITY.PDF.TAGS.WHEN_AVAILABLE",
"HOUSE.ACCESSIBILITY.TABLES.AVOID_SCREENSHOT",
"HOUSE.ACCESSIBILITY.TABLES.CAPTION_SUMMARY",
"HOUSE.ACCESSIBILITY.TABLES.HEADERS.SCOPE",
"HOUSE.ACCESSIBILITY.TABLES.HEADER_SCOPE",
"HOUSE.ACCESSIBILITY.TABLES.NO_LAYOUT",
"HOUSE.ACCESSIBILITY.TABLES.ROW_HEADERS_FOR_STUB",
"HOUSE.ACCESSIBILITY.TABLES.SIMPLE_STRUCTURE",
"HOUSE.ACCESSIBILITY.TOC.LINKED_ENTRIES",
"HOUSE.BACKMATTER.APPENDICES.LABELS.MATCH",
"HOUSE.BACKMATTER.GLOSSARY.ALPHABETICAL",
"HOUSE.BACKMATTER.GLOSSARY.CROSS_REFERENCES",
"HOUSE.BACKMATTER.INDEX.CROSS_REFERENCES.CONSISTENT",
"HOUSE.BACKMATTER.REFERENCES.DEDUPLICATE",
"HOUSE.BACKMATTER.REFERENCES.SORTING.CONSISTENT",
"HOUSE.CODE.BLOCKS.COMMANDS.PROMPT_FREE_COPY",
"HOUSE.CODE.BLOCKS.CONFIG.VALID",
"HOUSE.CODE.BLOCKS.DATA.SYNTHETIC_FOR_SENSITIVE",
"HOUSE.CODE.BLOCKS.DETERMINISTIC_OUTPUT",
"HOUSE.CODE.BLOCKS.ELISION.MARKED",
"HOUSE.CODE.BLOCKS.ERROR_OUTPUT.LABELED",
"HOUSE.CODE.BLOCKS.INDENTATION.CONSISTENT",
"HOUSE.CODE.BLOCKS.LINE_BREAKS.SEMANTIC_SAFE",
"HOUSE.CODE.BLOCKS.NO_LINE_NUMBERS",
"HOUSE.CODE.BLOCKS.NO_PERSONAL_PATHS",
"HOUSE.CODE.BLOCKS.NO_SMART_QUOTES",
"HOUSE.CODE.BLOCKS.PLATFORM.NOTED",
"HOUSE.CODE.BLOCKS.PRECONDITIONS.STATED",
"HOUSE.CODE.BLOCKS.SPLIT_BY_LANGUAGE",
"HOUSE.CODE.BLOCKS.TESTED_OR_MARKED",
"HOUSE.CODE.BLOCKS.TRAILING_WHITESPACE.AVOID",
"HOUSE.CODE.BLOCKS.USE_FOR_MULTILINE",
"HOUSE.CODE.CAPTIONS.EXPLAIN_SNIPPET",
"HOUSE.CODE.COMMENTS.MINIMIZE_NOISE",
"HOUSE.CODE.DIFFS.CONTEXT_LINES.PRESENT",
"HOUSE.CODE.DIFFS.FILE_HEADERS.PRESENT",
"HOUSE.CODE.DIFFS.UNIFIED_FORMAT",
"HOUSE.CODE.ERRORS.SHOW_FAILURES",
"HOUSE.CODE.EXAMPLES.ENV_VARS.DOCUMENT",
"HOUSE.CODE.EXAMPLES.FILE_PATH.LABEL",
"HOUSE.CODE.EXAMPLES.MULTI_FILE.SEPARATE",
"HOUSE.CODE.EXAMPLES.ORDERED_STEPS",
"HOUSE.CODE.FENCES.CLOSE_PROPERLY",
"HOUSE.CODE.INLINE.USE_FOR_IDENTIFIERS",
"HOUSE.CODE.LANGUAGE.CONSISTENT_FENCES",
"HOUSE.CODE.LANGUAGE.NOTATION.CONSISTENT",
"HOUSE.CODE.LINE_ENDINGS.NORMALIZE",
"HOUSE.CODE.MONO.FONT.PREFERRED",
"HOUSE.CODE.OUTPUT.DISTINGUISH_FROM_INPUT",
"HOUSE.CODE.OUTPUT.TRUNCATION.LABELED",
"HOUSE.CODE.PLACEHOLDERS.CLEAR",
"HOUSE.CODE.REFERENCES.VERSION_PIN",
"HOUSE.CODE.SECURITY.REDACT_SECRETS",
"HOUSE.CODE.SHELL.DESTRUCTIVE.WARN",
"HOUSE.CODE.SHELL.PROMPTS.CONSISTENT",
"HOUSE.CODE.TABLES.AVOID_FOR_CODE",
"HOUSE.CODE.TYPED_VALUES.DISTINGUISH",
"HOUSE.CODE.TYPOGRAPHY.UNICODE.MINIMIZE",
"HOUSE.CODE.URLS.IN_CODE.AVOID_WRAPPING",
"HOUSE.CODE.WRAPPING.NO_SOFT_HYPHENS",
"HOUSE.EDITORIAL.CLAIMS.AVOID_ABSOLUTES",
"HOUSE.EDITORIAL.CLAIMS.BASELINE_FOR_COMPARISONS",
"HOUSE.EDITORIAL.CLAIMS.DISTINGUISH_FACT_OPINION",
"HOUSE.EDITORIAL.CLAIMS.QUANTIFY_WHEN_POSSIBLE",
"HOUSE.EDITORIAL.CLAIMS.SCOPE_TIMEBOUND",
"HOUSE.EDITORIAL.CLAIMS.SUPPORT_WITH_SOURCES",
"HOUSE.EDITORIAL.CLARITY.ACTIVE_VOICE_INSTRUCTIONS",
"HOUSE.EDITORIAL.CLARITY.AVOID_AMBIGUOUS_PRONOUNS",
"HOUSE.EDITORIAL.CLARITY.AVOID_DOUBLE_NEGATIVES",
"HOUSE.EDITORIAL.CLARITY.AVOID_METACOMMENTARY",
"HOUSE.EDITORIAL.CLARITY.AVOID_WEASEL_WORDS",
"HOUSE.EDITORIAL.CLARITY.DEFINE_JARGON_ON_FIRST_USE",
"HOUSE.EDITORIAL.CLARITY.DEFINE_METRICS",
"HOUSE.EDITORIAL.CLARITY.EDIT_FOR_BREVITY",
"HOUSE.EDITORIAL.CLARITY.EXAMPLES_WHEN_COMPLEX",
"HOUSE.EDITORIAL.CLARITY.ONE_IDEA_PER_PARAGRAPH",
"HOUSE.EDITORIAL.CONSISTENCY.CAPITALIZATION.STABLE",
"HOUSE.EDITORIAL.CONSISTENCY.DATE_FORMAT.SINGLE",
"HOUSE.EDITORIAL.CONSISTENCY.NAMES.SAME_FORM",
"HOUSE.EDITORIAL.CONSISTENCY.SPELLING_VARIANT.CHOOSE_ONE",
"HOUSE.EDITORIAL.CONSISTENCY.TERMINOLOGY.STABLE",
"HOUSE.EDITORIAL.CONSISTENCY.TIMEZONE.EXPLICIT",
"HOUSE.EDITORIAL.HEADINGS.AVOID_GENERIC",
"HOUSE.EDITORIAL.HEADINGS.CASE.CONSISTENT",
"HOUSE.EDITORIAL.HEADINGS.LENGTH.CONCISE",
"HOUSE.EDITORIAL.HEADINGS.NO_DUPLICATE",
"HOUSE.EDITORIAL.LISTS.AVOID_DEEP_NESTING",
"HOUSE.EDITORIAL.LISTS.ITEMS.ACTIONABLE",
"HOUSE.EDITORIAL.LISTS.ORDERED_ONLY_WHEN_ORDERED",
"HOUSE.EDITORIAL.LISTS.PARALLEL_STRUCTURE",
"HOUSE.EDITORIAL.LISTS.PUNCTUATION.CONSISTENT",
"HOUSE.EDITORIAL.LISTS.TASKS.CHECKLIST",
"HOUSE.EDITORIAL.OPSEC.REMOVE_PII",
"HOUSE.EDITORIAL.PLACEHOLDERS.NO_REVIEW_NOTES_INLINE",
"HOUSE.EDITORIAL.REVIEW.CROSS_REFERENCES.VERIFY",
"HOUSE.EDITORIAL.REVIEW.FACT_CHECK",
"HOUSE.EDITORIAL.REVIEW.LINKS.VERIFY",
"HOUSE.EDITORIAL.REVIEW.SENSITIVE_INFO.NO_SECRETS",
"HOUSE.EDITORIAL.REVIEW.SPELLCHECK_AND_READTHROUGH",
"HOUSE.EDITORIAL.STRUCTURE.ACTION_ITEMS.EXPLICIT",
"HOUSE.EDITORIAL.STRUCTURE.ASSUMPTIONS.EXPLICIT",
"HOUSE.EDITORIAL.STRUCTURE.AUDIENCE.STATED",
"HOUSE.EDITORIAL.STRUCTURE.CHANGELOG.LIVING_DOCS",
"HOUSE.EDITORIAL.STRUCTURE.DECISIONS.EXPLICIT",
"HOUSE.EDITORIAL.STRUCTURE.GLOSSARY.WHEN_DENSE",
"HOUSE.EDITORIAL.STRUCTURE.METADATA.OWNER_DATE",
"HOUSE.EDITORIAL.STRUCTURE.REFERENCES.WHEN_CITED",
"HOUSE.EDITORIAL.STRUCTURE.RISKS.MITIGATIONS",
"HOUSE.EDITORIAL.STRUCTURE.SCOPE.STATED",
"HOUSE.EDITORIAL.STRUCTURE.SUMMARY.EARLY",
"HOUSE.EDITORIAL.TONE.AVOID_EXCESSIVE_EMPHASIS",
"HOUSE.EDITORIAL.TONE.CALIBRATE_CERTAINTY",
"HOUSE.EDITORIAL.TONE.INCLUSIVE_LANGUAGE",
"HOUSE.EDITORIAL.TONE.PROFESSIONAL_AND_RESPECTFUL",
"HOUSE.FIGURES.AXES.UNITS.LABELED",
"HOUSE.FIGURES.CAPTIONS.TAKEAWAY",
"HOUSE.FIGURES.COLOR.CONTRAST_SAFE",
"HOUSE.FIGURES.COLOR.LEGEND.REQUIRED",
"HOUSE.FIGURES.FORMAT.VECTOR_FOR_LINE_ART",
"HOUSE.FIGURES.RESOLUTION.MINIMUM",
"HOUSE.FIGURES.TEXT.NOT_RASTERIZED",
"HOUSE.FRONTMATTER.ABSTRACT.REQUIRED_FOR_LONG_DOCS",
"HOUSE.FRONTMATTER.DISTRIBUTION.CONTACT",
"HOUSE.FRONTMATTER.METADATA.CONFIDENTIALITY",
"HOUSE.FRONTMATTER.METADATA.DOC_STATUS",
"HOUSE.FRONTMATTER.METADATA.LAST_REVIEWED",
"HOUSE.FRONTMATTER.METADATA.VERSION",
"HOUSE.FRONTMATTER.TOC.AUTO_GENERATED",
"HOUSE.I18N.CURRENCY.DISAMBIGUATE",
"HOUSE.I18N.LANGUAGE.SWITCHES.MARK",
"HOUSE.I18N.NUMBERS.DIGIT_SYSTEM.CONSISTENT",
"HOUSE.I18N.NUMBERS.GROUPING.CONSISTENT",
"HOUSE.I18N.TRANSLATION.LABELS",
"HOUSE.I18N.UNITS.SPACING.CONSISTENT",
"HOUSE.LINKS.EMAILS.MAILTO_POLICY",
"HOUSE.LINKS.TEXT.ACCESS_RESTRICTIONS.NOTE",
"HOUSE.LINKS.TEXT.ARCHIVE_AND_HTML.BOTH",
"HOUSE.LINKS.TEXT.AVOID_OVERLONG_LABELS",
"HOUSE.LINKS.TEXT.DIFFERENTIATE_REPEATED_LINKS",
"HOUSE.LINKS.TEXT.FILESIZE.LABEL",
"HOUSE.LINKS.TEXT.FILETYPE.LABEL",
"HOUSE.LINKS.TEXT.LANGUAGE.LABEL",
"HOUSE.LINKS.TEXT.LINK_TARGET_MISMATCH",
"HOUSE.LINKS.TEXT.MATCHES_TARGET",
"HOUSE.LINKS.TEXT.MIRROR.LABEL",
"HOUSE.LINKS.TEXT.NO_EMOJIS",
"HOUSE.LINKS.TEXT.PARTIAL_WORD.AVOID",
"HOUSE.LINKS.TEXT.STABILITY.NOTE",
"HOUSE.LINKS.URLS.ANCHORS.STABLE",
"HOUSE.LINKS.URLS.AVOID.EXPIRING_SIGNED",
"HOUSE.LINKS.URLS.AVOID.INTERNAL_HOSTNAMES",
"HOUSE.LINKS.URLS.AVOID.IP_LITERALS",
"HOUSE.LINKS.URLS.AVOID.ONE_TIME_INVITES",
"HOUSE.LINKS.URLS.AVOID.PASSWORD_RESET",
"HOUSE.LINKS.URLS.AVOID.STAGING_DOMAINS",
"HOUSE.LINKS.URLS.AVOID.TEMP_FILESHARES",
"HOUSE.LINKS.URLS.AVOID.TEXT_FRAGMENTS",
"HOUSE.LINKS.URLS.AVOID_PRIVATE_IPS",
"HOUSE.LINKS.URLS.BARE_DOMAIN.TRAILING_SLASH",
"HOUSE.LINKS.URLS.CANONICAL.NO_TRACKING_PARAMS",
"HOUSE.LINKS.URLS.CANONICAL_HOST",
"HOUSE.LINKS.URLS.DISALLOW.FTP",
"HOUSE.LINKS.URLS.MAILTO.INTENT",
"HOUSE.LINKS.URLS.NO_EMBEDDED_CREDENTIALS",
"HOUSE.LINKS.URLS.NO_PROTOCOL_RELATIVE",
"HOUSE.LINKS.URLS.NO_QUERY_WHEN_NOT_NEEDED",
"HOUSE.LINKS.URLS.NO_SESSION_PARAMS",
"HOUSE.LINKS.URLS.RELATIVE.REPO_LOCAL",
"HOUSE.LINKS.URLS.SHORTENERS.AVOID",
"HOUSE.LINKS.URLS.STABLE_ANCHORS",
"HOUSE.TABLES.COLUMN_WIDTHS.BALANCED",
"HOUSE.TABLES.MISSING_DATA.CONSISTENT_MARK",
"HOUSE.TABLES.NUMERIC.ALIGN_DECIMALS",
"HOUSE.TABLES.NUMERIC.PRECISION.CONSISTENT",
"HOUSE.TABLES.SOURCE.NOTES",
"HOUSE.TABLES.UNITS.IN_HEADERS"
],
"postrender": [
"BRING.LAYOUT.COLUMNS.BALANCE_LENGTHS",
"BRING.LAYOUT.HYPHENATION.AVOID_NEAR_INTERRUPTION",
"BRING.LAYOUT.LINEBREAKS.AVOID_SAME_WORD_START",
"BRING.LAYOUT.PAGINATION.BALANCE_FACING_PAGES",
"BRING.LAYOUT.PAGINATION.ORPHANS_AVOID",
"BRING.LAYOUT.PAGINATION.WIDOWS_AVOID",
"BRING.TYPOGRAPHY.HYPHENATION.AVOID_AFTER_SHORT_LINE",
"CMOS.CITATIONS.NOTES.FOOTNOTES.PAGE_BREAKS",
"CMOS.LAYOUT.PAGINATION.AVOID_SHORT_LAST_LINE",
"CMOS.LAYOUT.PAGINATION.AVOID_SINGLE_LINE_ENDING",
"CMOS.LAYOUT.PAGINATION.HEADINGS.AVOID_BOTTOM_OF_PAGE",
"CMOS.LAYOUT.PAGINATION.HEADINGS.AVOID_TOP_OF_PAGE",
"CMOS.LAYOUT.PAGINATION.HEADINGS.KEEP_WITH_TEXT",
"CMOS.LAYOUT.PAGINATION.ORPHANS.AVOID",
"CMOS.LAYOUT.PAGINATION.WIDOWS.AVOID",
"HOUSE.CODE.BLOCKS.NO_CLIPPING",
"HOUSE.HEADINGS.KEEPS.AVOID_STRANDED",
"HOUSE.LAYOUT.OVERFLOW.OVERFULL_LINES.REPORT",
"HOUSE.LAYOUT.PAGINATION.CAPTIONS.KEEP_WITH_CONTENT",
"HOUSE.LAYOUT.PAGINATION.HEADINGS.NO_ADJACENT",
"HOUSE.LAYOUT.PAGINATION.KEEP_WITH_NEXT.HEADINGS",
"HOUSE.LAYOUT.PAGINATION.LISTS.AVOID_LONELY_ITEM",
"HOUSE.LAYOUT.PAGINATION.LISTS.KEEP_INTRO",
"HOUSE.LAYOUT.PAGINATION.RUNT_FINAL_PAGE",
"HOUSE.TABLES.OVERFLOW.NO_CLIPPING"
],
"typeset": [
"BRING.HEADINGS.ALIGNMENT.CONSISTENT_LEVEL",
"BRING.HEADINGS.BLOCK_QUOTE.SPACING_AROUND",
"BRING.HEADINGS.MARGIN_HEADS.CLEAR_GUTTER",
"BRING.HEADINGS.PARAGRAPH_INDENT.AFTER_HEAD_NONE",
"BRING.HEADINGS.SPACING.VERTICAL_RHYTHM",
"BRING.HEADINGS.SUBHEADS.CROSSHEADS_SIDEHEADS.CHOOSE_DELIBERATELY",
"BRING.HEADINGS.SUBHEADS.MARGIN_HEADS.RUNNING_SHOULDERHEADS",
"BRING.HEADINGS.SUBHEADS.MIXING_SYMM_ASYMM.AVOID_HAPHAZARD",
"BRING.HEADINGS.SUBHEADS.RIGHT_SIDEHEADS.VISIBILITY",
"BRING.HEADINGS.SUBHEADS.STYLE_CONTRIBUTES_TO_WHOLE",
"BRING.HEADINGS.WEIGHT_SIZE.HIERARCHY_SCALE",
"BRING.LAYOUT.BASELINE_GRID.APPLY_TO_BLOCK_QUOTES",
"BRING.LAYOUT.BASELINE_GRID.APPLY_TO_CAPTIONS",
"BRING.LAYOUT.BASELINE_GRID.APPLY_TO_HEADINGS",
"BRING.LAYOUT.BASELINE_GRID.APPLY_TO_TABLES",
"BRING.LAYOUT.BLOCK_QUOTES.AVOID_CROWDING",
"BRING.LAYOUT.BLOCK_QUOTES.BEFORE_AFTER_SPACING",
"BRING.LAYOUT.BLOCK_QUOTES.EXTRA_LEAD",
"BRING.LAYOUT.BLOCK_QUOTES.INDENT_OR_NARROW",
"BRING.LAYOUT.COLUMNS.ALIGN_BASELINES",
"BRING.LAYOUT.COLUMNS.COUNT.MODERATE",
"BRING.LAYOUT.COLUMNS.GUTTER.CONSISTENT",
"BRING.LAYOUT.COLUMNS.GUTTER.SUFFICIENT",
"BRING.LAYOUT.COLUMNS.SIDEBARS.DISTINCT_MEASURE",
"BRING.LAYOUT.COLUMNS.WIDTH.CONSISTENT",
"BRING.LAYOUT.GRID.ALIGN_ELEMENTS",
"BRING.LAYOUT.HYPHENATION.STUB_END_AVOID",
"BRING.LAYOUT.JUSTIFICATION.RAGGED_RIGHT_IF_NEEDED",
"BRING.LAYOUT.LEADING.ADJUST_FOR_SIZE_CHANGES",
"BRING.LAYOUT.LEADING.ALIGN_BASELINE_GRID",
"BRING.LAYOUT.LEADING.AVOID_TOO_LOOSE",
"BRING.LAYOUT.LEADING.AVOID_TOO_TIGHT",
"BRING.LAYOUT.LEADING.CHOOSE_BASE",
"BRING.LAYOUT.LEADING.CONSISTENT_BODY",
"BRING.LAYOUT.LEADING.NEGATIVE.AVOID_CONTINUOUS_TEXT",
"BRING.LAYOUT.MARGINS.AVOID_CROWDING",
"BRING.LAYOUT.MARGINS.CONSISTENT.ACROSS_SECTIONS",
"BRING.LAYOUT.MARGINS.FACING_PAGES.INNER_OUTER",
"BRING.LAYOUT.MARGINS.FOOTNOTE.CLEARANCE",
"BRING.LAYOUT.MARGINS.GUTTER.ALLOW_BINDING",
"BRING.LAYOUT.MARGINS.OUTER_LARGER_THAN_INNER",
"BRING.LAYOUT.MARGINS.PROPORTION.BALANCED",
"BRING.LAYOUT.MARGINS.RUNNING_HEAD.CLEARANCE",
"BRING.LAYOUT.MARGINS.TOP_BOTTOM.BALANCE",
"BRING.LAYOUT.MEASURE.ADJUST_FOR_TYPE_SIZE",
"BRING.LAYOUT.MEASURE.AVOID_TOO_LONG",
"BRING.LAYOUT.MEASURE.AVOID_TOO_SHORT",
"BRING.LAYOUT.MEASURE.CHANGE_FOR_LISTS",
"BRING.LAYOUT.MEASURE.COMFORTABLE_RANGE",
"BRING.LAYOUT.MEASURE.CONSISTENT_WITHIN_SECTION",
"BRING.LAYOUT.MEASURE.MULTICOLUMN_TARGETS",
"BRING.LAYOUT.MEASURE.TARGET_RANGE_CHARS",
"BRING.LAYOUT.PAGE.FRAME.TEXTBLOCK_BALANCE",
"BRING.LAYOUT.PAGE.HEAD_FOOT_BANDS.CONSISTENT",
"BRING.LAYOUT.PAGE.SHAPE.PROPORTIONATE",
"BRING.LAYOUT.PAGE.SPREADS.ALIGN_BASELINES",
"BRING.LAYOUT.PAGE.TEXTBLOCK.POSITION",
"BRING.LAYOUT.PARAGRAPH.DROP_CAPS.ALIGN_BASELINE",
"BRING.LAYOUT.PARAGRAPH.INDENT.NOT_TOO_DEEP",
"BRING.LAYOUT.PARAGRAPH.INDENT.PROPORTIONAL",
"BRING.LAYOUT.PARAGRAPH.INDENT.WITHIN_MEASURE",
"BRING.LAYOUT.PARAGRAPH.INDENT_AFTER_FIRST",
"BRING.LAYOUT.PARAGRAPH.INDENT_OR_SPACE_NOT_BOTH",
"BRING.LAYOUT.PARAGRAPH.INDENT_SIZE.CONSISTENT",
"BRING.LAYOUT.PARAGRAPH.LISTS.ALIGN_WITH_BODY",
"BRING.LAYOUT.PARAGRAPH.LISTS.HANGING_INDENT",
"BRING.LAYOUT.PARAGRAPH.NO_INDENT_AFTER_BLOCKS",
"BRING.LAYOUT.PARAGRAPH.OPENING_FLUSH_LEFT",
"BRING.LAYOUT.TEXTBLOCK.CONSISTENT_WIDTH",
"BRING.LAYOUT.VERTICAL_RHYTHM.CAPTIONS.SPACING",
"BRING.LAYOUT.VERTICAL_RHYTHM.FIGURES.SPACING",
"BRING.LAYOUT.VERTICAL_RHYTHM.FOOTNOTES.SPACING",
"BRING.LAYOUT.VERTICAL_RHYTHM.HEADINGS.BEFORE_AFTER",
"BRING.LAYOUT.VERTICAL_RHYTHM.LISTS.SPACING",
"BRING.LAYOUT.VERTICAL_RHYTHM.MEASURED_INTERVALS.MULTIPLES",
"BRING.LAYOUT.VERTICAL_RHYTHM.TABLES.SPACING",
"BRING.TABLES.COLUMN_ALIGNMENT.CONSISTENT",
"BRING.TABLES.FURNITURE.MINIMIZE",
"BRING.TABLES.GROUPING.WHITESPACE",
"BRING.TABLES.HEADERS.ALIGN_WITH_COLUMNS",
"BRING.TABLES.ROW_SPACING.READABLE",
"BRING.TABLES.TYPE_SIZE.READABLE",
"BRING.TYPOGRAPHY.CAPS.TRACKING_REVIEW",
"BRING.TYPOGRAPHY.FAMILY.AVOID_FAUX_BOLD",
"BRING.TYPOGRAPHY.FAMILY.TRUE_ITALICS",
"BRING.TYPOGRAPHY.FAMILY.TRUE_SMALL_CAPS",
"BRING.TYPOGRAPHY.FAMILY.USE_DESIGNED_WEIGHTS",
"BRING.TYPOGRAPHY.FAMILY.WEIGHT_CONTRAST_CLEAR",
"BRING.TYPOGRAPHY.HYPHENATION.LANGUAGE_DICTIONARY.MATCH",
"BRING.TYPOGRAPHY.HYPHENATION.MAX_CONSECUTIVE_LINES",
"BRING.TYPOGRAPHY.HYPHENATION.MIN_LEFT_RIGHT",
"BRING.TYPOGRAPHY.LETTERFORMS.AVOID_DISTORTION",
"BRING.TYPOGRAPHY.LIGATURES.AVOID_IN_CODE_URLS",
"BRING.TYPOGRAPHY.LIGATURES.FI_FL_COLLISIONS",
"BRING.TYPOGRAPHY.LIGATURES.STANDARD_ON_BODY",
"BRING.TYPOGRAPHY.NUMERALS.FRACTIONS_TRUE_GLYPHS",
"BRING.TYPOGRAPHY.NUMERALS.LINING_FOR_CAPS_AND_DISPLAY",
"BRING.TYPOGRAPHY.NUMERALS.OLDSTYLE_FOR_TEXT",
"BRING.TYPOGRAPHY.NUMERALS.PROPORTIONAL_FOR_PROSE",
"BRING.TYPOGRAPHY.NUMERALS.SUPERIOR_INFERIOR_FOR_NOTES",
"BRING.TYPOGRAPHY.NUMERALS.TABULAR_FOR_TABLES",
"BRING.TYPOGRAPHY.SIZE.LEADING_RELATION",
"BRING.TYPOGRAPHY.SPACING.WORD_SPACE.DEFINE",
"BRING.TYPOGRAPHY.TRACKING.CAPS_SMALLCAPS_AND_LONG_DIGITS",
"BRING.TYPOGRAPHY.TRACKING.LOWERCASE.AVOID",
"BRING.TYPOGRAPHY.TYPEFACE.FALLBACKS_COMPATIBLE_METRICS",
"BRING.TYPOGRAPHY.TYPEFACE.OPTICAL_SIZES_USE",
"CMOS.LAYOUT.MEASURE.LINE_LENGTH.TARGET_RANGE",
"CMOS.LAYOUT.MEASURE.MAX_LINE_LENGTH",
"CMOS.LAYOUT.MEASURE.MIN_LINE_LENGTH",
"CMOS.LAYOUT.PARAGRAPHS.BLOCK_QUOTE_STYLE",
"CMOS.LAYOUT.PARAGRAPHS.INDENT_POLICY",
"CMOS.LAYOUT.PARAGRAPHS.SPACING_POLICY",
"CMOS.LAYOUT.SPACING.LEADING.CHOOSE",
"CMOS.LAYOUT.SPACING.LINE_SPACING.CONSISTENT",
"CMOS.LAYOUT.SPACING.VERTICAL_RHYTHM",
"CMOS.NUMBERS.DIGIT_GROUPING.SI_SPACE",
"CMOS.PUNCTUATION.DASHES.EM_LINE_BREAKS",
"HOUSE.A11Y.DOCUMENT_LANGUAGE.DECLARE",
"HOUSE.CODE.BLOCKS.WRAP_POLICY",
"HOUSE.HEADINGS.KEEP_WITH_NEXT",
"HOUSE.LAYOUT.HTML.GUTTERS.MIN_PADDING",
"HOUSE.LAYOUT.HTML.MEASURE.MAX_WIDTH",
"HOUSE.LAYOUT.HTML.SECTION_SPACING.CONSISTENT",
"HOUSE.LINKS.WRAP.SAFE_BREAKS",
"HOUSE.TABLES.ALIGNMENT.DECIMALS",
"HOUSE.TABLES.HEADERS.REPEAT_ON_PAGEBREAK",
"HOUSE.TYPOGRAPHY.HTML.JUSTIFICATION.RAGGED_RIGHT",
"HOUSE.TYPOGRAPHY.HTML.LINE_HEIGHT.MINIMUM",
"HOUSE.TYPOGRAPHY.HTML.LINK_DECORATION.CONSISTENT"
]
}
````
### `iftypeset/spec/indexes/README.md`
- bytes: `2142`
- sha256: `7d6301d8503a3776f74073a7a25064e1a18e652d46fa1189c1b5f57b2873c76f`
````md
# Indexes
This project builds small, fast indexes so the runtime can answer questions like:
* “Which rules mention *en dash*?”
* “Which rules cite *CMOS18 §6.88 p412*?”
* “Which rules apply to `postrender` QA?”
* “What rules are overridden by the `print_pdf` profile?”
Indexes are derived artifacts (rebuildable) and should not be hand-edited.
## Indexes the app will build
### 1) keyword → rule IDs
**Purpose:** fast search/autocomplete and lint explanations.
* **Path:** `spec/indexes/keywords_all.json` and per-category deltas:
* `spec/indexes/keywords_<category>.json`
* **Format (JSON):**
* keys: normalized keyword (lowercased)
* values: array of rule IDs sorted stable (lexicographic)
Normalization (default):
* Unicode NFKC
* lowercase
* collapse whitespace
* strip surrounding punctuation
### 2) source_ref → rule IDs
**Purpose:** audit trail back to references without embedding book text.
* **Path:** `spec/indexes/source_refs_all.json` and per-category deltas:
* `spec/indexes/source_refs_<category>.json`
* **Format (JSON):**
* keys: exact `source_ref` pointer strings
* values: array of rule IDs
### 3) category → rule IDs
**Purpose:** batch reporting, extraction coverage, profile scoping.
* **Path:** `spec/indexes/category.json`
* **Format (JSON):**
* keys: category name
* values: array of rule IDs
### 4) enforcement → rule IDs
**Purpose:** quickly decide which engine (lint/typeset/postrender/manual) handles which rules.
* **Path:** `spec/indexes/enforcement.json`
### 5) profile overrides
**Purpose:** allow profiles to override severity or token parameters without editing rules.
* **Path:** `spec/indexes/profile_overrides.json`
* **Format (JSON):**
* per profile: list of override objects (selector + action)
* selectors may match category, tags, applies_to, or explicit rule IDs
## Build guarantees
* Index builds are deterministic from:
* `spec/rules/**.ndjson`
* `spec/profiles/*.yaml`
* `spec/manifest.yaml`
* The runtime must treat indexes as **cacheable**:
* if index missing/outdated → rebuild or fallback to scanning rule files.
````
### `iftypeset/spec/profiles/web_pdf.yaml`
- bytes: `3080`
- sha256: `bc2895a879888e643e43e4f87ae5e210fca0244edfa0899a96ebe40aeedda3c7`
````yaml
profile_id: "web_pdf"
description: "Screen-first PDF for sharing and reading; conservative pagination and strong accessibility defaults."
page:
size: "Letter"
orientation: "portrait"
two_sided: false
margins:
top: "1in"
bottom: "1in"
inner: "1.5in"
outer: "1.5in"
fonts:
body:
family: ["Noto Serif", "STIX Two Text", "Times New Roman", "serif"]
size: "12pt"
line_height: 1.50
heading:
family: ["Noto Sans", "Source Sans 3", "Arial", "sans-serif"]
mono:
family: ["Noto Sans Mono", "Source Code Pro", "Consolas", "monospace"]
size: "10.5pt"
line_height: 1.35
colors:
body: "#111827"
accent: "#1f3a5f"
heading: "#1f3a5f"
link: "#1f3a5f"
citation: "#3b4b63"
table_rule: "#cbd5e1"
table_stripe: "#f1f5f9"
measure_targets:
columns: 1
body_chars_per_line:
min: 55
ideal: 66
max: 75
footnote_chars_per_line:
min: 50
ideal: 60
max: 70
hyphenation:
enabled: true
strategy: "balanced"
language_driven: true
min_left: 2
min_right: 3
max_consecutive_hyphenated_lines: 2
avoid_proper_names_when_possible: true
avoid_after_short_lines: true
paragraphs:
first_paragraph_indent: "0"
indent: "1em"
block_paragraph_spacing: "0.6em"
headings:
keep_with_next_lines: 2
avoid_stranded_headings: true
numbering:
enabled: true
style: "decimal"
require_monotonic_increase: true
rule:
enabled: true
position: "under"
thickness: "1px"
color: "#1f3a5f"
spacing: "0.2em"
widows_orphans:
widow_lines: 3
orphan_lines: 3
balance_facing_pages: false
code:
inline:
use_mono: true
block:
font_size: "10pt"
line_height: 1.35
wrap: true
max_wrap_penalty: "medium"
overflow_policy: "wrap_then_shrink_minor"
shrink_limit: 0.92
padding: "0.4em 0.6em"
background: "#f8fafc"
border: "1px solid #e5e7eb"
radius: "4px"
tables:
cell_padding: "3pt 6pt"
header_repeat: true
overflow_policy: "shrink_then_wrap"
shrink_limit: 0.9
layout: "auto"
cell_wrap: true
keep_together: true
row_keep_together: true
grid_style: "rules_minimal"
header_align: "left"
cell_align: "left"
numeric_align: "right"
boolean_align: "center"
figures:
max_width: "100%"
margin: "0.6em auto"
typography:
small_caps_acronyms:
enabled: true
min_letters: 2
letter_spacing: "0.04em"
drop_caps:
enabled: true
size: "2.8em"
padding_right: "0.08em"
padding_top: "0.02em"
lists:
hanging_punctuation:
enabled: true
indent: "1.2em"
hang: "0.4em"
running_head:
enabled: true
placement: "footer"
template: "{page} | {title}"
font_size: "9pt"
font_style: "normal"
color: "#6b7280"
severity_overrides:
- selector: { category: "layout", tag: "widows_orphans" }
severity: "should"
- selector: { category: "accessibility" }
severity: "must"
locale_defaults:
primary_language: "en"
fallback_languages: ["fr"]
quotation_style: "us"
date_format: "YYYY-MM-DD"
number_format:
decimal_separator: "."
thousands_separator: ","
````
### `iftypeset/spec/profiles/print_pdf.yaml`
- bytes: `2884`
- sha256: `6afc13c6b2a013cdb0ea5b286843705fddd7b64c78812e5a56afc250fde2cc79`
````yaml
profile_id: "print_pdf"
description: "Print-oriented PDF with stricter pagination, book-like rhythm, and stronger keep constraints."
page:
size: "6in×9in"
orientation: "portrait"
two_sided: true
margins:
top: "18mm"
bottom: "20mm"
inner: "22mm"
outer: "18mm"
fonts:
body:
family: ["STIX Two Text", "Noto Serif", "Georgia", "serif"]
size: "10.5pt"
line_height: 1.50
heading:
family: ["STIX Two Text", "Noto Serif", "serif"]
mono:
family: ["Noto Sans Mono", "Source Code Pro", "Consolas", "monospace"]
size: "9.5pt"
line_height: 1.30
colors:
body: "#111827"
accent: "#111827"
heading: "#111827"
link: "#111827"
citation: "#111827"
table_rule: "#cbd5e1"
table_stripe: "#f8fafc"
measure_targets:
columns: 1
body_chars_per_line:
min: 55
ideal: 66
max: 72
hyphenation:
enabled: true
strategy: "print_quality"
min_left: 2
min_right: 3
max_consecutive_hyphenated_lines: 2
avoid_proper_names_when_possible: true
paragraphs:
first_paragraph_indent: "0"
indent: "1em"
headings:
keep_with_next_lines: 3
avoid_stranded_headings: true
numbering:
enabled: true
style: "decimal"
require_monotonic_increase: true
rule:
enabled: false
widows_orphans:
widow_lines: 2
orphan_lines: 2
balance_facing_pages: true
code:
block:
font_size: "9pt"
line_height: 1.25
wrap: true
overflow_policy: "wrap_then_shrink_minor"
shrink_limit: 0.90
padding: "0.4em 0.6em"
background: "#f8fafc"
border: "1px solid #e5e7eb"
radius: "4px"
tables:
cell_padding: "2.5pt 5pt"
header_repeat: true
overflow_policy: "shrink_then_rotate_if_allowed"
shrink_limit: 0.88
layout: "auto"
cell_wrap: true
keep_together: true
row_keep_together: true
grid_style: "rules_minimal"
header_align: "left"
cell_align: "left"
numeric_align: "right"
boolean_align: "center"
figures:
max_width: "100%"
margin: "0.6em auto"
typography:
small_caps_acronyms:
enabled: true
min_letters: 2
letter_spacing: "0.04em"
drop_caps:
enabled: true
size: "3em"
padding_right: "0.08em"
padding_top: "0.02em"
lists:
hanging_punctuation:
enabled: true
indent: "1.1em"
hang: "0.4em"
running_head:
enabled: true
placement: "footer"
template: "{page} | {title}"
font_size: "8.5pt"
font_style: "normal"
color: "#6b7280"
severity_overrides:
- selector: { category: "layout", tag: "widows_orphans" }
severity: "must"
- selector: { category: "layout", tag: "keep_constraints" }
severity: "must"
- selector: { category: "typography", tag: "spacing_consistency" }
severity: "must"
locale_defaults:
primary_language: "en"
fallback_languages: ["fr"]
quotation_style: "us"
date_format: "Month D, YYYY"
number_format:
decimal_separator: "."
thousands_separator: ","
````
### `iftypeset/spec/profiles/memo.yaml`
- bytes: `1696`
- sha256: `7eced12fb3da07d0220e0b1bd9fcf61cc337b771cc18357ff53f7e5f3adad4b6`
````yaml
profile_id: "memo"
description: "Short internal documents: lenient pagination, strong clarity, minimal typographic complexity."
page:
size: "Letter"
orientation: "portrait"
two_sided: false
margins:
top: "1in"
bottom: "1in"
inner: "1in"
outer: "1in"
fonts:
body:
family: ["Noto Sans", "Source Sans 3", "Arial", "sans-serif"]
size: "11pt"
line_height: 1.40
heading:
family: ["Noto Sans", "Source Sans 3", "Arial", "sans-serif"]
mono:
family: ["Noto Sans Mono", "Consolas", "monospace"]
size: "10pt"
line_height: 1.30
measure_targets:
columns: 1
body_chars_per_line:
min: 55
ideal: 70
max: 85
hyphenation:
enabled: false
strategy: "off_for_memos"
headings:
keep_with_next_lines: 2
avoid_stranded_headings: true
numbering:
enabled: false
widows_orphans:
widow_lines: 1
orphan_lines: 1
balance_facing_pages: false
code:
block:
font_size: "9.5pt"
line_height: 1.25
wrap: true
overflow_policy: "wrap"
shrink_limit: 1.0
padding: "0.35em 0.5em"
background: "#f8fafc"
border: "1px solid #e5e7eb"
radius: "4px"
tables:
cell_padding: "3pt 6pt"
header_repeat: false
overflow_policy: "wrap"
shrink_limit: 1.0
layout: "auto"
cell_wrap: true
figures:
max_width: "100%"
margin: "0.5em auto"
severity_overrides:
- selector: { category: "layout", tag: "widows_orphans" }
severity: "warn"
- selector: { category: "accessibility" }
severity: "must"
locale_defaults:
primary_language: "en"
fallback_languages: ["fr"]
quotation_style: "us"
date_format: "YYYY-MM-DD"
number_format:
decimal_separator: "."
thousands_separator: ","
````