fix: stabilise the export harness and publish what was assembled - #352
Open
jackye1995 wants to merge 2 commits into
Open
fix: stabilise the export harness and publish what was assembled#352jackye1995 wants to merge 2 commits into
jackye1995 wants to merge 2 commits into
Conversation
The first published build dropped docs/.cursor/ silently: actions/upload-artifact skips hidden files by default, so the assembled tree had 268 files and the `assembled` branch had 267. Editor configuration is not site content and should not be published, but it should not vanish by accident either. The assembler now excludes dot-prefixed paths deliberately and names what it dropped, so the assembled tree and the published tree are the same thing — which is the guarantee the whole pipeline rests on.
Two problems found while verifying the first publish to `assembled`. The published branch had 267 files where the assembler produced 268: actions/upload-artifact skips hidden files by default and silently dropped docs/.cursor/. The first attempt excluded dotfiles from the assembly instead, which was wrong — mint export carries that file today, so removing it would have quietly deleted a published file at cutover. The harness caught that, which is the strongest evidence so far that it works. The upload now includes hidden files, and the assembler publishes what it assembled. The harness itself was intermittently failing on identical trees. Mintlify renders the OpenAPI reference non-deterministically: response code blocks come out syntax-highlighted on one run and plain on the next, ~2 KB across ~78 fragments. One comparison passed, the next failed, on byte-identical input. A gate that fails at random is one people learn to route around. That subtree is now compared for presence but not for bytes, and only that subtree. It gives up nothing about the assembler, which passes openapi.yml through byte-identically and cannot influence one render differently from the other; a page appearing or disappearing is still caught. Verified: five consecutive comparisons pass, an authored-page change is caught, a reference page being removed is caught, and a reference page's contents are knowingly not.
jackye1995
changed the title
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.
Both problems here were found by verifying the first publish to
assembledrather than trusting green CI.The published tree was not the assembled tree
The assembler produced 268 files; the published branch had 267.
actions/upload-artifactskips hidden files by default and silently droppeddocs/.cursor/.My first fix excluded dotfiles from the assembly instead. That was wrong —
mint exportcarries that file today, so excluding it would have quietly deleted a published file at cutover. The harness caught it immediately, which is the best evidence yet that the harness earns its keep. The upload now setsinclude-hidden-files: true, and the assembler publishes exactly what it assembled.Deciding a file is "not really content" is how a byte-comparability guarantee turns into a list of exceptions.
The harness was intermittently failing on identical trees
Worse, and the reason this PR matters. Mintlify renders the OpenAPI reference non-deterministically: response code blocks come out syntax-highlighted on one run and plain on the next — ~2 KB across ~78 fragments, on top of the per-build React keys already normalised.
It is intermittent. Byte-identical trees, run 1
EQUIVALENT, run 2DIFFERENT. In CI that is a gate failing at random, which is precisely the failure mode this project's design warns about: "false positives train engineers to route around the gate."api-reference/rest/**is now compared for presence but not for bytes, and only that subtree. This gives up nothing about the assembler:openapi.ymlthrough byte-identically, so both sides feed Mintlify the same specmake assemble, and covers the spec fileVerified