docs(cli): document tool-install smoke test and worker bundling#109
Merged
Conversation
`fce generate` spawns FirstClassErrors.GenDoc.Worker in a child process and resolves it next to the installed executable (AppContext.BaseDirectory), so the tool only works if the worker and its closure travel inside the .nupkg under tools/<tfm>/any. That bundling already happens -- PackAsTool packs the CLI's publish output and _PublishDocumentationWorker drops the worker there -- but nothing enforced it: neither `dotnet build` nor `dotnet publish` exercises the .nupkg content, so a regression would pass every local check and only surface as "documentation worker could not be located" on a user's first run. Add a pack-time assertion in tools/packaging/pack.sh (cli scope) that fails the pack when FirstClassErrors.GenDoc.Worker.dll is absent from tools/<tfm>/any, in the same spirit as the existing SBOM check. Verified it bites by temporarily disabling the packaging target: the pack then exits non-zero. Replace the misleading "validate with dotnet build and dotnet publish" comment in the CLI .csproj with a pointer to that guard and to a new manual tool-install smoke test, documented in maintainers/ReleaseDryRun (EN + FR): install the packed tool and run `fce generate`, the only oracle that proves the packaged closure actually runs. Checked once here against FirstClassErrors.Usage -- a non-empty catalog, no worker-not-located error. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0132ctxy3scPRq5mjAS8Xjeu
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
2 participants
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.
Summary
This PR documents the manual smoke test required to validate that the
fce.NET tool correctly bundles and executes its GenDoc worker process. It also adds an automated assertion inpack.shto catch silent failures where the worker file is missing from the packaged tool, and clarifies the packaging mechanism in code comments.Type of change
Changes
maintainers/ReleaseDryRun.en.md and maintainers/ReleaseDryRun.fr.md: Added comprehensive section "The tool-install smoke test (the
fceworker)" documenting:FirstClassErrors.Usageas a convenient test targetFirstClassErrors.Cli/FirstClassErrors.Cli.csproj: Expanded comments to explain:
ReferenceOutputAssembly=false)_PublishDocumentationWorkertarget ensures the worker reaches the packagedotnet buildanddotnet publishalone cannot validate worker bundlingtools/packaging/pack.sh: Added automated assertion that:
FirstClassErrors.GenDoc.Worker.dllin the packaged toolcliscopeTesting
dotnet build FirstClassErrors.sln— verified no build errorsdotnet test FirstClassErrors.sln— 609 passed, 0 failed, 0 skippedfcetool globally and ranfce generateagainstFirstClassErrors.Usage(both--assembliesand--solutionmodes): non-empty catalog (465 lines, 10 documented errors), zero "documentation worker could not be located" errorspack.sh … cliworker-bundling guard verified in both directions — passes when the worker ships, and fails (exit 1) when the packaging target is temporarily disabledDocumentation
.csprojandpack.shRelated issues
None
https://claude.ai/code/session_0132ctxy3scPRq5mjAS8Xjeu