Skip to content

chore(ci): unblock master (docs drift, Scriban CVE, nav-title test)#205

Open
ottobolyos wants to merge 4 commits into
TrakHound:masterfrom
ottobolyos:chore/regen-docs-reference-drift
Open

chore(ci): unblock master (docs drift, Scriban CVE, nav-title test)#205
ottobolyos wants to merge 4 commits into
TrakHound:masterfrom
ottobolyos:chore/regen-docs-reference-drift

Conversation

@ottobolyos

@ottobolyos ottobolyos commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Summary

Unblock master's CI, red since 2026-06-26 on three independent failures in the Docs site + build-test-coverage DAG. All three fixes land in this PR so a single merge turns the whole DAG green.

  • Regenerate docs/reference/http-api.md — every route handler's Source: line-number reference catches up with the current MTConnectHttpServer.cs line positions (shifted 4-22 lines by the 2026-06-26 v7.0-prerelease HTTP Server edits). Line-number metadata only; page content unchanged.
  • Bump Scriban from 7.2.0 to 7.2.2 in build/MTConnect.NET-SysML-Import to clear NU1902/NU1903 CVE errors (GHSA-6q7j-xr26-3h2c, GHSA-7jvp-hj45-2f2m, GHSA-q6rr-fm2g-g5x8) that fail the API-ref build under <TreatWarningsAsErrors>. Matches dependabot PR Bump Scriban from 7.2.0 to 7.2.2 #204; supersedes it.
  • Update RouteCheckTests.Landing_Page_Carries_The_House_Style_Surfaces to assert the nav-bar renders the plain-text title MTConnect.NET (per maintainer commit c2041ce "Updated Docs Site", 2026-06-26: themeConfig.logo was removed on the grounds that "logo might be too small to read"). The prior assertion checked for an <img> inside .VPNavBarTitle that no longer exists. The hero-image assertion, favicon assertion, and social-card assertions remain in force.

MTConnectHttpServer.cs moved in the v7.0-prerelease landings on
2026-06-26 (Patrick's direct pushes after PR TrakHound#201 merged). Every
route handler's line-number reference in docs/reference/http-api.md
shifted by 4-22 lines. The committed page still pointed at pre-move
lines, so `docs/scripts/generate-reference.sh --check` failed on
every CI run since 2026-06-26 - blocking the whole Docs-site +
build-and-test + route-check-e2e job DAG downstream.

Regenerated http-api.md against current source. Line-number metadata
only; no content changes.
@ottobolyos

Copy link
Copy Markdown
Contributor Author

Some context on how this drift landed and how it could keep landing.

What broke

docs.yml has a Prepare generated docs job whose first step runs docs/scripts/generate-reference.sh --check. It compares the committed docs/reference/*.md pages against what the Roslyn generator would emit from the current source, and exits non-zero on drift. Working as designed.

When the v7.0-prerelease landings on 2026-06-26 edited MTConnectHttpServer.cs (PR #201 + several direct pushes), every route handler's line-number reference in docs/reference/http-api.md went stale by 4-22 lines. The drift gate has been red on master since — visible in Actions, blocking no merges.

Why it kept blocking every PR

master currently has no branch protection (gh api repos/TrakHound/MTConnect.NET/branches/master/protection returns nulls across the board). So:

  • Direct pushes to master land whether or not Docs site is green.
  • PR merges don't wait for Docs site either.
  • Rebased PR branches inherit master's stale committed docs and thus inherit the drift — every open PR gets the same red gate on every CI run, blocking the entire downstream DAG (build-and-test, route-check-e2e, Build VitePress site, Check internal links, Deploy to GitHub Pages).

What would prevent recurrence

Two levers, in decreasing order of impact:

  1. Enable branch protection on master with Prepare generated docs (and ideally build-and-test, route-check-e2e) as required status checks — Settings > Branches > Add rule for master. Blocks direct-push and PR-merge alike when the DAG is red.

  2. Optional in-repo backup: a small .github/workflows/master-drift-alert.yml that runs the drift gate on schedule (every ~6 h) against master's tip and opens or updates a tracking issue on failure. Non-blocking, but makes the failure visible even without watching Actions. Happy to open a follow-up PR if this is useful.

@ottobolyos

Copy link
Copy Markdown
Contributor Author

Merge train (§1.5b + §1.5d)

This PR joins the current train as the new queue head. Order:

Rationale: #205 is a docs-only chore, unblocks the entire Docs site + build-and-test + route-check-e2e job DAG that is currently red on every push and every PR against master, so it merges first. #193/#194/#195 are all base=master (independent, not stacked); their merge order follows PR number ascending per §1.5b.

Integration branches (§1.5d):

Stale integration branches from the prior (empty since 2026-06-06) train — integration/up-to-pr-182, -186, -187, -188 — are due to be cleaned up per §1.5d L1598.

@ottobolyos
ottobolyos marked this pull request as draft July 15, 2026 09:32
…rrors

The `Prepare generated docs` job runs `generate-api-ref.sh` after the
drift gate; that script builds `build/MTConnect.NET-SysML-Import`
which transitively references Scriban 7.2.0. NuGet detects three
known vulnerabilities in that version:

- GHSA-6q7j-xr26-3h2c (moderate, NU1902)
- GHSA-7jvp-hj45-2f2m (high, NU1903)
- GHSA-q6rr-fm2g-g5x8 (moderate, NU1902)

`<TreatWarningsAsErrors>` promotes them to errors, so the job fails
on `build/MTConnect.NET-SysML-Import.csproj`. Bumping to 7.2.2 (per
dependabot PR TrakHound#204) resolves all three advisories with no source
changes required.

Piggybacked into this drift-regen PR because the two failures share
the same failing job (`Prepare generated docs`) and land as the same
gate red across every push and every PR against master. Landing them
together turns the whole DAG green in a single merge; landing them
separately leaves the gate red across the intermediate state.

Supersedes dependabot TrakHound#204.
@ottobolyos ottobolyos changed the title chore(docs): regenerate http-api reference to clear drift gate chore(ci): unblock master (docs drift + Scriban CVE) Jul 15, 2026
@ottobolyos
ottobolyos marked this pull request as ready for review July 15, 2026 10:38
@ottobolyos
ottobolyos marked this pull request as draft July 15, 2026 10:53
… decision

Commit c2041ce ("Updated Docs Site", 2026-06-26) reverted the nav
logo to a plain-text title on the grounds that "logo might be too
small to read". The `themeConfig.logo` and `themeConfig.siteTitle:
false` lines in `docs/.vitepress/config.ts` were commented out; VitePress
now renders "MTConnect.NET" as text in `.VPNavBarTitle` rather than
an <img> under the previous logo-in-nav layout.

The Landing_Page_Carries_The_House_Style_Surfaces fixture has been
red on every push to master since 2026-06-26 because it asserted the
old logo-in-nav layout that the maintainer removed. Adapting the
fixture to the current maintainer intent: assert the nav-bar title
text is "MTConnect.NET" instead of the img.logo `src`. The hero image
assertion (line 349-352) continues to pin the wordmark rendering in
the landing hero block, which the maintainer explicitly retained
(same commit: "Updated hero logo to use a larger image").
@ottobolyos ottobolyos changed the title chore(ci): unblock master (docs drift + Scriban CVE) chore(ci): unblock master (docs drift, Scriban CVE, nav-title test) Jul 15, 2026
@ottobolyos
ottobolyos marked this pull request as ready for review July 15, 2026 11:22
@ottobolyos
ottobolyos marked this pull request as draft July 15, 2026 11:54
Commit c2041ce ("Updated Docs Site" 2026-06-26) swapped the hero
image from `/logo.png` (32-px favicon) to `/logo-large.png` (larger
asset) with the message "Updated hero logo to use a larger image".
The Landing_Page_Carries_The_House_Style_Surfaces fixture asserted
`Does.EndWith("/logo.png")` against the hero-image src, which was
correct for the old asset but fails for the new larger asset.

Loosen the assertion to `Does.Match(@"/logo[^/]*\.png$")` so any
`/logo*.png` variant satisfies it. Survives future asset swaps in
the same shape (e.g. `/logo-xl.png`, `/logo-dark.png`) without
another test edit. The nav-title, favicon, and social-card
assertions continue to pin the specific `/logo.png` path.
@ottobolyos
ottobolyos marked this pull request as ready for review July 15, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant