Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
a6c2db5
ci: expand CodeQL coverage and tighten repo guardrails
seonghobae Apr 10, 2026
7945aec
fix: unblock fuzz CI and harden governance tests
seonghobae Apr 10, 2026
bb1cb40
fix: forward libFuzzer flags so ClusterFuzzLite fuzz jobs run
seonghobae Apr 10, 2026
551b374
docs: align repository truth sources with current workflow state
seonghobae Apr 10, 2026
a9d0ebb
Merge pull request #37 from Seongho-Bae/chore/truth-source-alignment
seonghobae Apr 10, 2026
1d263a8
docs: add canonical engineering truth sources
seonghobae Apr 10, 2026
3e7ae79
fix: harden workflow attestation and fuzz builder paths
seonghobae Apr 10, 2026
70383e4
Merge pull request #38 from Seongho-Bae/chore/canonical-engineering-docs
seonghobae Apr 10, 2026
737696b
Merge pull request #39 from Seongho-Bae/chore/workflow-robustness-har…
seonghobae Apr 10, 2026
7fa1b7f
docs: scope markdownlint around active repository docs
seonghobae Apr 10, 2026
1af74b0
Merge pull request #42 from Seongho-Bae/chore/markdownlint-scope-policy
seonghobae Apr 10, 2026
a0e3ac9
docs: pin the supported MkDocs toolchain stance
seonghobae Apr 10, 2026
83c84a1
Merge pull request #43 from Seongho-Bae/chore/docs-toolchain-hold
seonghobae Apr 10, 2026
b3d84ae
docs: align public setup guidance with uv defaults
seonghobae Apr 10, 2026
ae12473
Merge pull request #44 from Seongho-Bae/chore/uv-first-public-setup
seonghobae Apr 10, 2026
06ba722
fix: lock pypdf to patched release
seonghobae Apr 11, 2026
fbb13ef
Merge pull request #46 from Seongho-Bae/fix/pypdf-6-10-lock
seonghobae Apr 11, 2026
bbf0dbc
docs: record reviewer-capacity ruleset alignment plan
seonghobae Apr 11, 2026
c042621
docs: align governance truth with single-maintainer exception
seonghobae Apr 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .clusterfuzzlite/build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ cd "$SRC/newsdom-api"
uv sync --frozen --extra fuzz
export PATH="$SRC/newsdom-api/.venv/bin:$PATH"

for fuzzer in $(find fuzzers -name '*_fuzzer.py'); do
fuzzer_basename=$(basename -s .py "$fuzzer")
while IFS= read -r -d '' fuzzer; do
fuzzer_basename=$(basename "$fuzzer" .py)
fuzzer_package="${fuzzer_basename}.pkg"

pyinstaller --distpath "$OUT" --onefile --name "$fuzzer_package" "$fuzzer"
Expand All @@ -18,4 +18,4 @@ this_dir=\$(dirname "\$0")
exec "\$this_dir/$fuzzer_package" "\$@"
EOF
chmod +x "$OUT/$fuzzer_basename"
done
done < <(find fuzzers -type f -name '*_fuzzer.py' -print0)
6 changes: 6 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
* @Seongho-Bae

# Security and workflow ownership
.github/ @Seongho-Bae
docs/ @Seongho-Bae
manual/ @Seongho-Bae
1 change: 1 addition & 0 deletions .github/workflows/clusterfuzzlite.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ jobs:
language: python
sanitizer: address
github-token: ${{ github.token }}
bad-build-check: false

- name: Run fuzzers
uses: google/clusterfuzzlite/actions/run_fuzzers@52ecc61cb587ee99c26825a112a21abf19c7448c
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ permissions:

jobs:
analyze:
name: codeql (python)
name: codeql (python, actions)
runs-on: ubuntu-latest
permissions:
contents: read
Expand All @@ -27,7 +27,7 @@ jobs:
- name: Initialize CodeQL
uses: github/codeql-action/init@c10b8064de6f491fea524254123dbe5e09572f13
with:
languages: python
languages: python, actions

- name: Autobuild
uses: github/codeql-action/autobuild@c10b8064de6f491fea524254123dbe5e09572f13
Expand Down
1 change: 0 additions & 1 deletion .github/workflows/gh-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ on:
push:
branches:
- main
- master
- develop
paths:
- 'manual/**'
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,8 @@ build/
*.pyc
private/
tmp/
site/
registered_agents.json
task_agent_mapping.json
content_file_3982.pdf
page1_300dpi-1.png
57 changes: 57 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# AGENTS.md

## Project overview

- Repository: `newsdom-api`
- Product: FastAPI service that converts MinerU OCR output into
canonical NewsDOM JSON.
- Primary branch model: manual Git Flow (`develop` integration,
`main` stable).

## Authoritative docs

Read these first when making repository changes:

- `docs/engineering/canonical-docs.md`
- `docs/engineering/execution-policy.md`
- `docs/engineering/acceptance-criteria.md`
- `docs/engineering/harness-engineering.md`
- `docs/engineering/review-policy.md`
- `docs/engineering/runtime-data-policy.md`
- `docs/engineering/skills-subagents-mcp.md`
- `docs/workflow/git-flow.md`
- `docs/workflow/pr-continuity.md`
- `docs/workflow/one-day-delivery-plan.md`
- `docs/operations/deploy-runbook.md`
- `docs/security/api-security-checklist.md`
- `docs/coderabbit/review-commands.md`
- `ARCHITECTURE.md`

## Setup and verification defaults

- Install: `uv sync --frozen --all-extras`
- Test: `uv run pytest`
- Coverage gate:
`uv run pytest --cov=src/newsdom_api --cov-branch --cov-report=term-missing --cov-fail-under=100`
- Docs build: `uv run mkdocs build --strict`
- Local API: `uv run uvicorn --app-dir src newsdom_api.main:app --reload`

## Delivery defaults

- Branch normal work from `develop` unless the task is a `main`-only
release or hotfix path.
- Keep PR continuity explicit with `gh pr view` / `gh pr list` /
`pr_continuity` before opening duplicates.
- Treat CodeRabbit as advisory automation; required human approvals
still follow the repository ruleset.
- When PRs are blocked externally, continue local adjacent tasks
instead of stopping.

## Safety rules

- Keep synthetic fixtures public and private reference inputs
local-only.
- Do not commit secrets, credentials, or copyrighted source
newspaper material.
- Prefer durable evidence in tracked docs, tests, workflow runs,
PR comments, and release assets over scratch notes.
49 changes: 49 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Architecture

## Runtime shape

`newsdom-api` is a small service-oriented Python application with a
thin FastAPI entrypoint and explicit separation between request
orchestration, MinerU process execution, and DOM normalization.

## Primary modules

- `src/newsdom_api/main.py` exposes `/health` and `/parse`
through FastAPI.
- `src/newsdom_api/service.py` orchestrates PDF parsing,
temporary files, and response construction.
- `src/newsdom_api/mineru_runner.py` shells out to the MinerU CLI,
collects JSON outputs, and surfaces process errors.
- `src/newsdom_api/dom_builder.py` converts MinerU `content_list`
blocks into the canonical NewsDOM response model.
- `src/newsdom_api/schemas.py` defines the public response schema.
- `src/newsdom_api/synthetic.py` and
`src/newsdom_api/equivalence.py` support synthetic fixture
generation and structural comparisons.

## Request flow

1. `src/newsdom_api/main.py` receives an uploaded PDF.
2. `src/newsdom_api/service.py` writes the upload to a temporary
workspace and calls MinerU.
3. `src/newsdom_api/mineru_runner.py` resolves the executable, runs
the OCR pipeline, and loads generated JSON artifacts.
4. `src/newsdom_api/dom_builder.py` normalizes OCR blocks into the canonical response.
5. FastAPI returns typed JSON from `src/newsdom_api/schemas.py`.

## Supporting systems

- `tests/fixtures` holds synthetic PDFs, JSON baselines, and
provenance notes; private reference inputs stay out of git.
- `manual/` is the published user manual rendered by MkDocs.
- `.github/workflows/` encodes CI, security scanning, Pages,
release, and image-delivery policy.
- `scripts/release/` builds release manifests and exports GitHub attestation bundles.

## Delivery boundaries

- `develop` is the integration line for normal feature, fix,
and chore work.
- `main` is the stable release line that receives tagged releases.
- The service is production-grade only when code, docs, workflows,
and release evidence agree.
44 changes: 37 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,26 +22,41 @@ PYTHONWARNINGS=error pytest
pytest --cov=src/newsdom_api --cov-branch --cov-report=term-missing --cov-fail-under=100
```

CI installs dependencies from `uv.lock`, and workflow actions are pinned by immutable commit SHA. Keep both policies intact when editing `.github/` automation.
CI installs dependencies from `uv.lock`, and workflow actions are
pinned by immutable commit SHA. Keep both policies intact when editing
`.github/` automation.

CircleCI parity is defined in `.circleci/config.yml` and mirrors the same uv-locked warnings-as-errors and 100% coverage quality gate.
CircleCI parity is defined in `.circleci/config.yml` and mirrors the
same uv-locked warnings-as-errors and 100% coverage quality gate.

## Documentation build

The GitHub Pages workflow installs documentation tooling from `uv.lock` via the optional `docs` extra. For local maintainer work, sync all extras so the docs build does not drop the test toolchain from the active environment.
The GitHub Pages workflow installs documentation tooling from
`uv.lock` via the optional `docs` extra. For local maintainer work,
sync all extras so the docs build does not drop the test toolchain
from the active environment.

```bash
uv sync --frozen --all-extras
uv run mkdocs build --strict
```

Tagged releases use `.github/workflows/release.yml` to build artifacts, generate SHA256 checksums, emit a JSON manifest, export `*.intoto.jsonl` provenance bundles, and publish a GitHub Release with provenance attestation.
Tagged releases use `.github/workflows/release.yml` to build
artifacts, generate SHA256 checksums, emit a JSON manifest, export
`*.intoto.jsonl` provenance bundles, and publish a GitHub Release with
provenance attestation.

For full OpenSSF Scorecard branch-protection visibility against classic GitHub branch protection rules, set a repository secret named `SCORECARD_TOKEN` with the fine-grained administration-read scope recommended by the Scorecard Action documentation. Without that secret, Scorecard still runs but may report the Branch-Protection check as inconclusive.
For full OpenSSF Scorecard branch-protection visibility against
classic GitHub branch protection rules, set a repository secret named
`SCORECARD_TOKEN` with the fine-grained administration-read scope
recommended by the Scorecard Action documentation. Without that
secret, Scorecard still runs but may report the Branch-Protection
check as inconclusive.

## Fixture policy

This project intentionally separates public test artifacts from private validation material.
This project intentionally separates public test artifacts from
private validation material.

Allowed in the repository:

Expand All @@ -57,7 +72,8 @@ Not allowed in the repository:

## Private baseline refresh

If you maintain a private reference page locally, refresh only the derived structural baseline:
If you maintain a private reference page locally, refresh only the
derived structural baseline:

```bash
python tools/derive_private_baseline.py tests/fixtures/private_page_baseline.json
Expand All @@ -67,10 +83,24 @@ The source page must remain local.

## Documentation split

- `AGENTS.md`: repository-local execution bootstrap for autonomous
maintenance
- `ARCHITECTURE.md`: runtime structure and module boundaries
- `README.md`: user-facing overview and quickstart
- `CONTRIBUTING.md`: maintainer workflow and safety rules
- `SECURITY.md`: vulnerability reporting and supported-branch policy
- `manual/`: published end-user manual rendered by MkDocs
- `docs/agents/README.md`: agent-specific read order and
repository-local behavior notes
- `docs/coderabbit/review-commands.md`: supported CodeRabbit review
commands used in PRs
- `docs/engineering/`: canonical maintainer policies and acceptance criteria
- `docs/operations/`: delivery and verification runbooks
- `docs/security/api-security-checklist.md`: API hardening checklist
for FastAPI surface changes
- `docs/workflow/git-flow.md`: canonical branch workflow
- `docs/workflow/pr-continuity.md`: canonical PR-selection and
stacked-PR guidance
- `tests/fixtures/README.md`: fixture provenance and regeneration notes
- `docs/plans/`: design and implementation planning notes

Expand Down
39 changes: 28 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ NewsDOM API parses scanned Japanese newspaper PDFs into DOM-like article trees.

- Primary engine: `MinerU` pipeline backend
- Service wrapper: FastAPI
- Output: canonical JSON with pages, articles, headlines, body blocks, images, captions, and quality metadata
- Output: canonical JSON with pages, articles, headlines, body
blocks, images, captions, and quality metadata

## Quickstart

Expand All @@ -20,7 +21,8 @@ source .venv/bin/activate
pip install -e ".[dev]"
```

To enable real parsing with MinerU, install the MinerU CLI separately in the environment that will execute parsing:
To enable real parsing with MinerU, install the MinerU CLI separately in the
environment that will execute parsing:

```bash
pip install "mineru[pipeline]==3.0.9"
Expand All @@ -29,7 +31,7 @@ pip install "mineru[pipeline]==3.0.9"
### Run

```bash
uvicorn newsdom_api.main:app --reload
uvicorn --app-dir src newsdom_api.main:app --reload
```

### Docker
Expand All @@ -39,9 +41,14 @@ docker build -t newsdom-api .
docker run -p 8000:8000 newsdom-api
```

The default image exposes the REST API on port `8000` as a lean multi-arch service image. It is suitable for `linux/amd64` and `linux/arm64`, including Apple Silicon hosts running the API service inside Docker.
The default image exposes the REST API on port `8000` as a lean multi-arch
service image. It is suitable for `linux/amd64` and `linux/arm64`, including
Apple Silicon hosts running the API service inside Docker.

The lean image is intentionally a REST API shell: `/health`, `/docs`, and OpenAPI endpoints are available immediately, while real `/parse` execution still requires a compatible MinerU runtime to be available inside the container image.
The lean image is intentionally a REST API shell: `/health`, `/docs`, and
OpenAPI endpoints are available immediately, while real `/parse` execution
still requires a compatible MinerU runtime to be available inside the
container image.

For heavier parsing deployments, build the optional NVIDIA-oriented variant:

Expand All @@ -50,9 +57,14 @@ docker build -f Dockerfile.nvidia -t newsdom-api:nvidia .
docker run --gpus all -p 8000:8000 newsdom-api:nvidia
```

`Dockerfile.nvidia` is intended for Linux/NVIDIA environments and is `linux/amd64`-only. Apple Silicon can run the lean API image, but Docker Desktop does not expose Apple GPU acceleration to Linux containers, so real GPU-accelerated parsing should stay on a native Apple Silicon path instead of the containerized runtime.
`Dockerfile.nvidia` is intended for Linux/NVIDIA environments and is
`linux/amd64`-only. Apple Silicon can run the lean API image, but Docker
Desktop does not expose Apple GPU acceleration to Linux containers, so real
GPU-accelerated parsing should stay on a native Apple Silicon path instead of
the containerized runtime.

The NVIDIA variant is `linux/amd64`-only and is meant for hosts that can provide the CUDA user-space/runtime stack required by MinerU.
The NVIDIA variant is `linux/amd64`-only and is meant for hosts that can
provide the CUDA user-space/runtime stack required by MinerU.

### Parse a PDF

Expand All @@ -72,18 +84,23 @@ pytest
python fuzzers/dom_builder_fuzzer.py --smoke tests/fixtures/mineru_sample.json
```

The repository also enforces a `quality-gate` workflow with 100% source coverage and docstring audit coverage.
The repository also enforces a `quality-gate` workflow with 100% source
coverage and docstring audit coverage.

## Fixtures and provenance

This repository ships only synthetic test fixtures and derived structural baselines. For fixture provenance and regeneration notes, see `tests/fixtures/README.md`.
This repository ships only synthetic test fixtures and derived structural
baselines. For fixture provenance and regeneration notes, see
`tests/fixtures/README.md`.

## Development

Development setup, fixture handling rules, and local-only baseline maintenance are documented in `CONTRIBUTING.md`.
Development setup, fixture handling rules, and local-only baseline
maintenance are documented in `CONTRIBUTING.md`.

Security reporting guidance is documented in `SECURITY.md`.
Version tags trigger a GitHub-native release workflow that builds distribution artifacts, checksums, and provenance attestations.
Version tags trigger a GitHub-native release workflow that builds
distribution artifacts, checksums, and provenance attestations.

Project history is tracked in `CHANGELOG.md`.

Expand Down
Loading
Loading