fix: pre-0.3.0 audit remediation#46
Merged
Merged
Conversation
A 9-dimension audit before cutting v0.3.0 surfaced several places where the library silently dropped content or diverged from its own documented behaviour. - Tables now parse as GitHub-Flavored Markdown. Flexmark's permissive defaults (column spans, multiple header rows, trailing `[caption]` lines) were all dropped by the mapper without a trace — a caption vanished, and a header-less table mapped to null, discarding its whole body invisibly even to strict mode. The parser pins GFM options and mapTable now surfaces a header-less table as UnsupportedBlockNode (rejected in strict, shown verbatim otherwise). - List-item continuation blocks (a second paragraph, code block, quote) kept the item's left indent instead of rendering flush against the page margin, left of the marker. Nested lists, which compute their own indent, are unchanged. - The custom-renderer seam the docs advertise for headings/TOC is now reachable: RenderContext.headingSlug(HeadingNode) and tocEntries() are public and TocEntry is a public record, so an external heading/TOC renderer can declare the same planned anchors [TOC] links to instead of allocating a desynced fresh slug. - An undefined [^label] renders as literal text (CommonMark) rather than a numbered, dangling superscript with a gap in the run. - Heading slugs stay document-unique even when a later heading's own text slugifies to an already-generated -N anchor (Foo / Foo / Foo 1). - The built-in dark themes ship a dark-tuned alert palette (AlertColors.defaultDark); the light amber accents fell below a readable contrast on the near-black surface. - Case-folding for custom-block dispatch, callout variants, image-URL schemes and inline-HTML detection uses Locale.ROOT (a Turkish locale broke :::INFO dispatch). Tests: TableGfmParityTest, ListContinuationIndentTest (glyph-x geometry), UndefinedFootnoteTest, HeadingSlugSeamTest added; full suite 188 green.
Housekeeping surfaced by the audit, none of it changing rendered output. - CLI --version was hard-coded "0.2.0-SNAPSHOT" and had already gone stale at the v0.2.0 tag (the lockstep guard does not check it). It now reads the Maven-filtered gcmd-cli.properties via a picocli IVersionProvider, so it tracks the module <version> the guard already enforces and cannot drift again. - README status line (two releases stale) and examples/README install line (claimed 0.1.0-SNAPSHOT while it installs 0.3.0-SNAPSHOT) corrected. - The scratch sandbox project GP-Test/ is gitignored so a stray `git add .` cannot commit it. - cli/ junit-bom pin aligned to 6.1.1 (matched the other synchronized pins). Verified: `mvn -f cli/pom.xml package` green (7 tests, incl. a --version assertion); the built jar prints "graph-compose-markdown CLI 0.3.0-SNAPSHOT".
The manual's Installation section showed a plain Maven dependency with no "not yet on Central" caveat (the README already carries one), so it implied an artifact that cannot be resolved yet. Added the caveat and re-rendered the committed manual.pdf / manual-dark.pdf so they match the source. Also adds ManualTest#regeneratesTheCommittedManualPdfs — an opt-in test (`-Dgcmd.regenerateManual=true`) that rewrites both PDFs from manual.md with the exact composers the other tests assert against, so the checked-in PDFs have a single, drift-free way to be refreshed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A pre-release audit before cutting v0.3.0 (9 dimensions, each factual finding
adversarially verified) surfaced 0 blockers but 45 verified findings — mostly
places where the library silently dropped content or diverged from its own
documented behaviour. This PR lands the correctness fixes, the safe minors, and
the release hygiene. The larger refactors are deferred to a follow-up (below).
What changed
Correctness (
17ac17d)(column spans, extra header rows, trailing
[caption]) were dropped by themapper without a trace, and a header-less table mapped to
null— its wholebody vanished, invisible even to strict mode. The parser pins GFM options, and
mapTablenow surfaces a header-less table asUnsupportedBlockNode.flush against the page margin, left of their own marker.
RenderContext.headingSlug(HeadingNode)and
tocEntries()arepublicandTocEntryis a public record, so an externalheading/TOC renderer declares the same planned anchors
[TOC]links to insteadof a desynced fresh slug.
[^label]renders as literal text, not a dangling numbered superscript.already-generated
-Nanchor.AlertColors.defaultDark); thelight amber accents were below a readable contrast on the dark surface.
Locale.ROOTon the four case-folding sites (a Turkish locale broke:::INFO).Release hygiene (
66eff1b)--versionis drift-proof: it read a hard-coded, already-stale0.2.0-SNAPSHOT; it now reads the Maven-filteredgcmd-cli.propertiesvia apicocli
IVersionProvider, tracking the module version the lockstep guard enforces.GP-Test/gitignored;cli
junit-bomaligned to6.1.1.Docs (
7418041)already had it);
manual.pdf/manual-dark.pdfre-rendered to match, via a newopt-in
ManualTest#regeneratesTheCommittedManualPdfs.Verification
./mvnw test -pl .→ 188 green (1 skipped = the opt-in manual regenerator)../mvnw -f cli/pom.xml package→ 7 green (incl. a--versionassertion); thebuilt jar prints
graph-compose-markdown CLI 0.3.0-SNAPSHOT../mvnw -f examples/pom.xml test-compile→ green../mvnw javadoc:javadoc -pl .→ clean.4 new tests:
TableGfmParityTest,ListContinuationIndentTest(glyph-x geometry),UndefinedFootnoteTest,HeadingSlugSeamTest.Deferred to a follow-up PR
Bigger or riskier items from the audit (report §5): break the
theme↔renderandtheme↔extensionpackage cycles, abstract the 4–5 hand-mirrored tree walks, thedead
SpacingTokens.headingSpaceBelowtoken, the code-blocklineSpacingunitmismatch, missing
with*methods /PageTokens.of/RenderContext.offactories,@since+package-infobackfill, a golden-image regression harness, and exposingthe new 0.3.0 features through CLI flags.