Add the Zensical documentation of the Python package (docs/package, built by the docs workflow), merge the standard publish workflow with the setuptools-scm tag check, add the SPDX header rule to ruff, restructure the README, and point every repository and registry address at the Gitea organization papers. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
44 lines
2.5 KiB
Markdown
44 lines
2.5 KiB
Markdown
# Validate a package
|
|
|
|
A package is a folder, or a zipped package (`.sct.zip`), that holds one document.
|
|
`paperspec validate` checks it against every rule of the specification's conformance chapter and works anywhere the package is installed with its `tools` extra.
|
|
|
|
## Check one or several packages
|
|
|
|
```sh
|
|
paperspec validate fixtures/packages/hale2026harmonic-damb
|
|
paperspec validate fixtures/packages/tiny2026tiny-j4qm.sct.zip fixtures/packages/tiny2026tiny-j4qm
|
|
```
|
|
|
|
Each valid package prints `PACKAGE: valid` and the exit status is 0.
|
|
A failure goes to standard error as `package: where: rule: message`, the exit status is 1, and nothing else prints.
|
|
A usage error, such as no package at all, exits with status 2.
|
|
|
|
A zipped package is unpacked under the specification's path rules before anything else happens: a path that leaves the folder, a symbolic link and an oversize archive are refused.
|
|
`--max-size BYTES` sets the largest size an archive may expand to; the default is 1 GiB.
|
|
|
|
## Read a refusal
|
|
|
|
The rule ID names the rule that failed.
|
|
`https://paperspec.scient.ing/registry/rules.json` lists every ID with the chapter of the specification that states it, which is where to read why.
|
|
The folder `fixtures/invalid/` holds one package for each of many rules; its `expect.json` says which rules the package must trigger.
|
|
|
|
## Try a correction before making it
|
|
|
|
A correction changes one node of a document and records why.
|
|
Before a tool writes one, it can run the proposal through the gate, which needs only the package's current state:
|
|
|
|
```sh
|
|
paperspec validate --correction fix.json fixtures/packages/tiny2026tiny-j4qm
|
|
```
|
|
|
|
`fix.json` holds one proposal as a JSON object, or several as JSON Lines, applied in order:
|
|
|
|
```json
|
|
{"format":"scienting-correction/1","op":"emend","target":"j663d4h","find":"second","replace":"next","kind":"wording","status":"proposed","evidence":[{"kind":"person","by":"ana","note":"The editor prefers a plainer word."}],"author":{"key":"ana"},"reason":"The authors misuse the ordinal; the paragraph follows the first.","at":"2026-10-03T10:00:00Z"}
|
|
```
|
|
|
|
The command prints the record the correction would append to `corrections.jsonl`, with its computed `index`, `id`, `path`, `before` and `after`, and writes nothing.
|
|
A refused proposal prints `file:N node: rule: message` on standard error and stops: with this proposal, changing `second` to `2nd` is refused with `correction.digits`, because an emendation changes no digit.
|
|
`--correction` takes exactly one package, and it refuses a package that withholds its text.
|