Model GenDoc's own failures as documented first-class errors#163
Merged
Conversation
Add a protected DiagnosableException(Error, Exception) constructor so a subclass can preserve the technical cause of a failure (an I/O error, a serialization error...) on Exception.InnerException, with its stack trace, while the modeled diagnostic tree stays on Error.InnerErrors. Refs: #142 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa
Dogfood the library in its own tooling: every failure of the solution documentation generator is now a first-class error with a stable GENDOC_-prefixed code, structured context, transience, direction, and generated documentation. - add DocumentationRequestError (invalid generation requests, as primary-port errors) and DocumentationToolchainError (SDK and worker failures, as secondary-port errors), 16 documented codes in total; - rebase SolutionDocumentationGenerationException on DiagnosableException so the raised failure exposes the full error; - route every throw and HandleFailure site through the factories, including the previously bare FileNotFoundException/ArgumentException guards and the SDK-query timeout that used to skip a project silently; timeouts get their own transient code and keep the output captured before the kill; - wire the FCE analyzers onto the project and opt it into catalog generation, so the tool documents itself; - cover every factory, the exception contract, and the self-extraction of the 16 codes in unit tests. BREAKING CHANGE: SolutionDocumentationGenerationException is now constructed from an Error instead of a message string, and the generator raises it (with codes GENDOC_SOLUTION_NOT_FOUND and GENDOC_SOLUTION_PATH_UNSUPPORTED) where it previously threw FileNotFoundException or ArgumentException. Refs: #142 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa
Catch DiagnosableException ahead of the generic handler in the generate and catalog commands and render the failure through a single shared helper, so every command emits the same grep-able "CODE: message" line that can be looked up in the tool's own catalog. Refs: #142 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa
Feed FirstClassErrors.GenDoc.dll to the existing fce generate step and require GENDOC_ codes in the produced catalog: the .NET 8 floor job now proves the pipeline end to end against the tool's own error surface. Refs: #142 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa
Refs: #142 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa
The extraction reference now names the GENDOC_ codes and the single code-led warning a timeout produces, and the logging guide notes the runtime-cause channel on DiagnosableException.InnerException. French translations updated in step. Refs: #142 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa
…asserror-f331kj # Conflicts: # maintainers/adr/README.md
Reefact
enabled auto-merge
July 16, 2026 11:28
17 tasks
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
GenDoc now models and documents its own failure surface with the FirstClassErrors model it implements: every generator failure carries a stable
GENDOC_-prefixed code, structured context, transience and direction, and lands in the catalog generated by the tool itself — dogfooding the library, providing a real (non-sample) reference consumer, and letting CI assert the documentation pipeline end to end.Type of change
Changes
DocumentationRequestError(invalid generation requests,PrimaryPortError) andDocumentationToolchainError(SDK/worker failures,SecondaryPortError): 16 documentedGENDOC_*codes with typed context keys (ErrCtxKey), diagnostics and executable examples.SolutionDocumentationGenerationExceptiononDiagnosableException; its constructors now take anError(plus an optional runtime cause). Core gains a protectedDiagnosableException(Error, Exception)constructor preserving the technical cause onException.InnerException.HandleFailuresite ofSolutionErrorDocumentationGeneratorthrough the factories. Timeouts get their own transient code (GENDOC_PROCESS_TIMED_OUT) carrying command, target, timeout and the output captured before the kill; the SDK-query (-getProperty:TargetPath) timeout no longer degrades into a silent project skip; the target-path resolution catch no longer swallowsOperationCanceledExceptionnor re-wraps already-coded failures; exit codes render culture-invariantly.FirstClassErrors.GenDoc(same dogfooding pattern asFirstClassErrors.Usage) and opt the project into catalog generation.generate,catalog diffandcatalog updatecatchDiagnosableExceptionahead of the generic handler and reportCODE: messagethrough a single shared helper (FailureReporting)..NET 8 floorjob also documentsFirstClassErrors.GenDoc.dlland requiresGENDOC_codes in the produced catalog.CODE: messageline.Breaking changes (recorded in the
feat(gendoc)!commit):SolutionDocumentationGenerationException(string[, Exception])constructors are replaced by(Error[, Exception]).GetErrorDocumentationFromraisesSolutionDocumentationGenerationException(codesGENDOC_SOLUTION_NOT_FOUND/GENDOC_SOLUTION_PATH_UNSUPPORTED) where it previously threwFileNotFoundException/ArgumentException.Testing
dotnet build FirstClassErrors.slndotnet test FirstClassErrors.slnFirstClassErrors.Analyzers.UnitTests)Also run:
dotnet build -warnaserror(0 warnings); end-to-endfce generate --assemblies FirstClassErrors.GenDoc.dllthrough the real worker (16GENDOC_*codes extracted), combined with the Usage sample (26 codes, no collision), andfce generate --solution <missing>verifying theerror: GENDOC_SOLUTION_NOT_FOUND: …line and exit code 1. Both were re-verified after mergingmainback into the branch.Documentation
doc/updateddoc/DocumentationExtractionReference.fr.md,doc/LoggingIntegration.fr.md,maintainers/adr/0009-….fr.md)Architecture decisions
Proposed: ADR-0009 (report the tooling's failures as first-class errors; renumbered from 0008 after ADR-0008 landed onmainfor the binder)Checked against the ADR base: ADR-0002 respected (no TFM change to the tooling); ADR-0005 noted — the generator keeps its throwing entry point unrenamed for now, an
Outcome-returning variant is listed as a follow-up in ADR-0009.Related issues
Closes #142
Refs #140
🤖 Generated with Claude Code
https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa