Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
75 changes: 75 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Static analysis of the C# this repository ships, by CodeQL.
#
# ci.yml answers "does the change lower coverage, and what does SonarCloud say about it"; this answers
# "does a second, independent engine find a security defect in the bytes we parse". The two are not
# duplicates: the query packs are written by different people, and a library whose whole job is to read
# untrusted bytes is worth scanning twice. docs/foundation-readiness.md names this pair as the evidence for
# the "high priority on producing secure software" criterion -- Dependabot covers the dependencies, CodeQL
# covers the code.
#
# The results land in the repository's Security tab (Code scanning alerts). That tab, and the SARIF upload
# it stores, are a repository setting no file here can switch on; the workflow runs regardless and starts
# reporting there once the setting exists. Dependabot's *security* updates are the sibling switch, in
# Settings -> Code security.
#
# The build is the one the release ships: both target frameworks, Release configuration, no incremental
# reuse. `build-mode: manual` is deliberate -- autobuild would pick a single project and could miss the
# net10.0 leg, and the extractor reads the compiler, so the build has to be the real one.

name: CodeQL

on:
push:
branches: [main]
pull_request:
branches: [main]
schedule:
# Once a week, so a query-pack update reaches the tree even when nothing is pushed.
- cron: '0 4 * * 1'
workflow_dispatch:

permissions:
security-events: write # upload the SARIF results to the Security tab
packages: read # pull the CodeQL query packs
actions: read
contents: read

concurrency:
group: codeql-${{ github.ref }}
cancel-in-progress: true

jobs:
analyze:
name: Analyze C#
runs-on: ubuntu-latest
timeout-minutes: 30

steps:
- name: Check out
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

# The same two SDKs ci.yml installs: the 11.0 SDK alone cannot produce the net10.0 app host the
# test project and the smoke app need (MSB3030).
- name: Install the .NET SDKs
uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6
with:
dotnet-version: |
11.0.x
10.0.x

- name: Initialize CodeQL
uses: github/codeql-action/init@9418214df1f2c4b8128c770156c409013b07d6b9 # v3
with:
languages: csharp
build-mode: manual
# The default pack is the security suite; extended adds the queries a byte parser benefits
# from without turning the run into a style review.
queries: security-extended

- name: Build
run: dotnet build ./SharpCorePDF.slnx -c Release --no-incremental

- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@9418214df1f2c4b8128c770156c409013b07d6b9 # v3
with:
category: "/language:csharp"
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ feed ever served.
contents of the layers, and the entry below is written against the published `preview.1` rather than
against an empty feed.

## [Unreleased]
## [1.8.0] - 2026-11-14

### Added

Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@
question from a host that is. Read them as:

nuget.org version the vpre endpoint for the entry-point id, which read "unknown" until 1.0.0 was
pushed on 2026-10-17, and reads 1.7.0 now; the four layer ids resolve too, at
1.7.0 and 1.0.0-preview.1
pushed on 2026-10-17, and reads 1.8.0 now; the four layer ids resolve too, at
1.8.0 and 1.0.0-preview.1
tests the ci.yml runs: the build, both test legs and the SonarCloud analysis
PDF/A the compliance.yml runs: veraPDF 1.30.4, PDFBox preflight and Ghostscript
over the archival documents the archive-pdfa example writes
Expand Down Expand Up @@ -61,7 +61,7 @@ independent implementations (`qpdf` via `pikepdf`, and `pypdf`).
The product boundary is recorded in [ADR-001](https://github.com/MPCoreDeveloper/SharpCorePDF/blob/main/docs/adr/0001-pdf-platform-boundary.md).
The capability target is PDFsharp 6.5 for creation and processing and PdfPig 0.1.x for reading and layout
analysis; rendering, conversion, OCR, conformance validation, services and CLIs stay outside the product.
`1.7.0` ships that target for creation, editing and reading — authoring, page editing, over/under layers
`1.8.0` ships that target for creation, editing and reading — authoring, page editing, over/under layers
and stationery, reading with layout analysis, signatures and PDF/A — with the exceptions [`docs/parity.md`](https://github.com/MPCoreDeveloper/SharpCorePDF/blob/main/docs/parity.md)
still records; that file names the release of every row and the test and external command behind it.
Current capability is described below, not the target.
Expand Down Expand Up @@ -333,8 +333,8 @@ guide to the API: twenty-seven chapters, from the first merge to encryption, ins
injection, the architecture, authoring a page, a cookbook of complete recipes, editing an existing document
(including over/under layers and the stationery plan), extraction, layout analysis, the object graph, digital
signatures, archival output, the fonts a document uses, and how the manual itself is built. Read it as
[a PDF](https://github.com/MPCoreDeveloper/SharpCorePDF/blob/main/docs/SharpCorePDF-Manual-1.7.0.pdf)
(the 1.7.0 edition) or chapter by chapter as Markdown, starting with
[a PDF](https://github.com/MPCoreDeveloper/SharpCorePDF/blob/main/docs/SharpCorePDF-Manual-1.8.0.pdf)
(the 1.8.0 edition) or chapter by chapter as Markdown, starting with
[Installation and First Merge](https://github.com/MPCoreDeveloper/SharpCorePDF/blob/main/docs/manual/src/03-installation.md).
The [documentation index](https://github.com/MPCoreDeveloper/SharpCorePDF/blob/main/docs/README.md)
links every chapter and the supporting measurement, release and governance documents.
Expand Down
17 changes: 9 additions & 8 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,20 @@ long-form reference for the API.

## The manual

- **[Read or download the manual as a PDF](SharpCorePDF-Manual-1.7.0.pdf)** — 125 pages, A4, with a
- **[Read or download the manual as a PDF](SharpCorePDF-Manual-1.8.0.pdf)** — 125 pages, A4, with a
linked contents page and PDF bookmarks.
- **Read the chapters as Markdown** in [`manual/src`](manual/src). Each file is one chapter, and the
file-name order is the chapter order. This edition describes `1.7.0`. Chapters 16 to 19 were written
file-name order is the chapter order. This edition describes `1.8.0`. Chapters 16 to 19 were written
while `1.1.0` was the package on the feed, and their heads used to say which part of their surface it
already carried — the annotation writer and the form model shipped there, while the form writer, the
text layouter and the JPEG, BMP and GIF readers are what `1.2.0` added. They now describe the surface as
it stands. The [`1.5.0`](SharpCorePDF-Manual-1.5.0.pdf), [`1.4.0`](SharpCorePDF-Manual-1.4.0.pdf),
[`1.3.0`](SharpCorePDF-Manual-1.3.0.pdf), [`1.2.0`](SharpCorePDF-Manual-1.2.0.pdf) and
[`1.1.0`](SharpCorePDF-Manual-1.1.0.pdf) editions stay beside this one as the record of what those
releases shipped, and the chapter numbers are kept so that a cross-reference survives both. The PDF and
the Markdown are in step: this edition includes Chapter 26 (fonts) and the stationery section in Chapter
14, and it is rebuilt before a release with
it stands. The [`1.7.0`](SharpCorePDF-Manual-1.7.0.pdf), [`1.5.0`](SharpCorePDF-Manual-1.5.0.pdf),
[`1.4.0`](SharpCorePDF-Manual-1.4.0.pdf), [`1.3.0`](SharpCorePDF-Manual-1.3.0.pdf),
[`1.2.0`](SharpCorePDF-Manual-1.2.0.pdf) and [`1.1.0`](SharpCorePDF-Manual-1.1.0.pdf) editions stay
beside this one as the record of what those releases shipped, and the chapter numbers are kept so that a
cross-reference survives both. The PDF and the Markdown are in step: this edition includes the
diagnostics report in Chapter 8, the stationery section in Chapter 14 and Chapter 26 (fonts), and it is
rebuilt before a release with
(`dotnet run --project .\tools\SharpCorePDF.Manual`).

| Chapter | What it covers |
Expand Down
Binary file added docs/SharpCorePDF-Manual-1.8.0.pdf
Binary file not shown.
39 changes: 31 additions & 8 deletions docs/foundation-readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,26 @@ first — because stars, forks and outside issues are what the committee reads a
None of this is a defect in the code; it is the arithmetic of a project that started two days ago. It
is also the reason an application now would be judged on intent rather than on evidence.

### Where it stands on 2026-11-14

The verdict above is the 2026-10-17 snapshot and stays as it was written. Four weeks later the second half
of it — activity — has moved, and the gap is no longer "never published a package":

| Metric | Value on 2026-11-14 | Read |
| --- | --- | --- |
| Age | repository created **2026-10-15** | thirty days |
| Commits | 107 on `main` | still a small project, but no longer a single line of history |
| Issues open / closed | 0 / 5 | the tracker is in use: an outside report (#6) became a shipped feature (#9) |
| Pull requests open / closed | 0 / 13 | every merge goes through the pull-request workflow |
| Releases | 9 tags (`v1.0.0-preview.1`, `v1.0.0`, `v1.1.0` … `v1.7.0`) | a release every few days, each with notes and a gate record |
| Packages | 5 ids on nuget.org, at `1.7.0` | the entry point and the four layers move together |
| Stars / watches / forks | 0 / 0 / 0 | unchanged, and the honest read of "activity" for a Foundation application |

The three documents still exist, and now so does `docs/release-checklist.md`'s per-version record through
`1.7.0`. What is still missing is two settings and one outside commit: **GitHub Discussions**, **private
vulnerability reporting**, and a commit from someone other than the owner. A stable release has not aged
ninety days yet either — `1.0.0` landed 2026-10-17, so it reaches that mark on 2027-01-15.

## Eligibility criteria, one row each

### Open
Expand Down Expand Up @@ -145,12 +165,12 @@ The owner's decision, taken 2026-10-17: **the application is filed as soon as th
That document holds the checklist, the state of each condition, and the answers to the form, so that filing
costs an hour rather than a week of reconstruction.

As of this date three conditions are true (the three documents exist) and five are not: nothing is
published on nuget.org, so no stable release has aged 90 days either; no outside contribution exists;
Discussions is off; and three of the five decisions below are unanswered — the package id and the account
shape were decided on 2026-10-17. Two of the false conditions cost nothing but a settings toggle, and
neither needs anybody else's time: **GitHub Discussions**, and **private vulnerability reporting**, without
which the first channel in `SECURITY.md` does not resolve.
As of 2026-11-14 the picture is: the three documents exist; the five ids are published at `1.7.0`, but no
stable release has aged 90 days yet (`1.0.0` reaches that mark on 2027-01-15); no outside *commit* exists,
though issue #6 was a real outside report; Discussions is still off; and the package id and account shape
were decided on 2026-10-17. Two of the false conditions cost nothing but a settings toggle, and neither
needs anybody else's time: **GitHub Discussions**, and **private vulnerability reporting**, without which
the first channel in `SECURITY.md` does not resolve.

## What to do now, in the order that also serves the release

Expand All @@ -177,8 +197,11 @@ needs whether or not an application is ever filed:
document cannot supply. A policy describes the process; a scanner watches the dependencies.
**Partly done, 2026-10-17:** `.github/dependabot.yml` schedules version updates for the NuGet packages
and the workflow actions, with the project folders listed one by one because the updater does not read
a `.slnx`. Alerts and *security* updates are still a repository setting (Settings → Code security), and
no file in this repository can switch them on.
a `.slnx`. **CodeQL added, 2026-11-14:** `.github/workflows/codeql.yml` runs the C# extractor over the
real Release build (both target frameworks) on every push to `main`, on pull requests, and once a week,
and uploads SARIF to the Security tab; the `security-extended` query pack is the reason a byte parser is
worth a second engine. Dependabot's *security* updates and Code scanning alerts are still repository
settings (Settings → Code security), and no file in this repository can switch them on.

## What not to do

Expand Down
13 changes: 7 additions & 6 deletions docs/manual/src/00-preface.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ pages from nothing, and changes the assembly of an existing document — which p
order and with what rotation. It does all of that without calling a native library, a command line
tool or a third-party PDF engine.

This manual describes version **1.7.0** of the library. It is written for the developer who has to ship a
This manual describes version **1.8.0** of the library. It is written for the developer who has to ship a
feature, not only for the developer who wants to read source code: every chapter explains the behaviour you
can rely on, the behaviour you should not rely on, and the code that exercises it.

Expand Down Expand Up @@ -45,13 +45,14 @@ converter that reads these chapters, the browser that lays the pages out, and th
library writes. Chapter 26 is the font inspector: the fonts a document uses and whether each program
travels with it.

**This edition describes `1.7.0`, and every chapter describes what the package ships.** Since `1.4.0` the
**This edition describes `1.8.0`, and every chapter describes what the package ships.** Since `1.4.0` the
changes a caller can see in the API are additive: a page can paint in a colour space the caller names
(Chapter 15), the layout reader can read a page as horizontal row bands for a document known to be a table
(Chapter 21), and a session keeps one parse open across several questions about the same document
(Chapter 20). `1.6.0` added the level-U PDF/A profiles, a caller-supplied output intent and the font
inspector (Chapter 26); `1.7.0` adds the stationery plan — a background template per page range, with a
default — and the overlay and underlay layers it builds on (Chapter 14). Chapters 16 to 19 were written
inspector (Chapter 26); `1.7.0` added the stationery plan — a background template per page range, with a
default — and the overlay and underlay layers it builds on (Chapter 14); `1.8.0` adds the one-call
diagnostics report (Chapter 8) and PDF/A-4 (Chapter 24). Chapters 16 to 19 were written
while `1.1.0` was the package on the feed, and each of their heads used to say which part of its surface
`1.1.0` already carried; they now describe the surface as it stands. The numbers are kept rather than
reassigned so that a cross-reference in one edition keeps pointing at the same chapter in the next.
Expand Down Expand Up @@ -79,9 +80,9 @@ GitHub documentation and the PDF. If you find a discrepancy between this text an
is the source of truth; please open an issue so the text can be corrected. Chapter 25 describes how those
files become the PDF you are reading.

> **Version note.** This manual is written against 1.7.0. The public API is covered by an approved snapshot
> **Version note.** This manual is written against 1.8.0. The public API is covered by an approved snapshot
> in each project, so a change to a public member is a deliberate, reviewed event rather than an accident of
> a refactoring. Code that compiles against 1.6.0 keeps compiling across this minor release — every addition
> a refactoring. Code that compiles against 1.7.0 keeps compiling across this minor release — every addition
> is additive — and the changelog records every addition and every change of behaviour.

## What you need
Expand Down
39 changes: 39 additions & 0 deletions docs/mutation-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -796,3 +796,42 @@ names — the redundant null guard, the exception message string, the four `Conf
the two warning-merge statements — and the single kill that moved is a mutant 5.1.0's Safe Mode rejects
at compile time rather than executes. No test changed, and no new survivor appeared.

## PdfPageCanvas — the drawing surface (2026-11-14)

The canvas carried the largest survivor set in the tree. The 1.6.0 increment measured it at **42.04%** and
left it there because that increment had not written the drawing code; this pass read the survivors and
closed them with tests that assert the operation the canvas records, not the content stream it becomes —
the same distinction the font record draws between a font's fields and its bytes.

| File | Score | Killed | Survived | No coverage | Mutants |
| --- | --- | --- | --- | --- | --- |
| `PdfPageCanvas.cs` (1.6.0) | 42.04% | 66 | 67 | 24 | 201 |
| `PdfPageCanvas.cs` (this pass) | **85.99%** | 135 | 13 | 0 | 201 |

`PdfPageCanvasTests` adds thirty-three cases (the suite moves from 1196 to 1229). They divide into three
groups. **The guards** — every public method that takes a reference, and every one that takes a raw
coordinate or size — are called with the null, NaN, zero and negative a caller can actually supply, so a
removed `ThrowIfNull`/`ValidatePosition`/`ValidateSize` is a test that fails. **The geometry** — the ellipse
test rebuilds the four cubic curves from the same bounds with the same `0.5522847498307936` constant and
compares the segments point by point, so a sign flip or a doubled radius fails even though the rendered page
would still look round. **The state counter** — one `SaveState` allows one `RestoreState`, and the second
restore throws, which is what makes `stateDepth` a contract rather than a pair of tokens.

The thirteen that remain, read one by one:

- **The eight exception-message strings** (`L41`, `L84`, `L285`, `L540`, `L552`, `L557`, `L584`, `L589`):
no test asserts a refusal's wording, which is not a contract — the reason the merge, font and diagnoser
records already state.
- **The three constructor guards** (`L36`): `PdfPageSize` refuses a non-positive dimension in its own
constructor, so the only invalid value a caller can still pass is `default(PdfPageSize)`, which is
`0 x 0`; at `0 x 0` the `||`, `&&`, `<=` and `<` variants all throw the same way, so no reachable input
distinguishes them. The guard stays for that `default` case.
- **`ValidatePosition` in `DrawTextLayout`** (`L124`): a `PdfPoint` refuses a non-finite coordinate in its
constructor, so this call can never throw. It is the one guard this file keeps although no input reaches
it, because the alternative is a documented exception that cannot occur; the existing test in
`PdfDocumentBuilderTests.Drawing` passes `new PdfPoint(double.NaN, 0)`, which throws in `PdfPoint` before
`DrawTextLayout` is entered.
- **`origin.X + run.Start.X`** (`L139`): the first run of a left-aligned line starts at x = 0, and the
layout fixtures in the suite are left-aligned, so `+` and `-` record the same operation. A centred or
indented layout is the fixture that would close it.

Loading
Loading