docs: Rewrite the plugin documentation for the current plugin framework - #1385
Open
TimothyJones wants to merge 1 commit into
Open
docs: Rewrite the plugin documentation for the current plugin framework#1385TimothyJones wants to merge 1 commit into
TimothyJones wants to merge 1 commit into
Conversation
The plugin framework page predated the current plugin API (it still described the JSii approach, and carried a banner saying it was inaccurate). Replace it with a new top-level Plugins section that documents the framework as it is today, written so that a plugin can be implemented without prior knowledge of ContractCase internals: - The anatomy of a plugin: the ContractCasePlugin object, the description fields and why each name exists, package structure and the -dsl split, and type namespacing rules - Writing matchers: descriptors, the four executor functions and their invariants, context modification, descending into children, and the match context - Writing mock types: descriptors, the write/read setup block, the mock executor lifecycle, mockConfig, and a worked example from the core function plugin - Declaring your DSL: the PluginDslDeclaration data model (noting the generator itself is still work in progress) - Loading and distributing plugins: loadPlugins, module name restrictions, load-time checks, and a pre-publishing checklist The old /docs/reference/plugin-framework URL is kept alive as the contract file format reference, since published API documentation links to it for the matcher format. Also adds maintainer todo notes for the gaps found while writing these docs: plugin resolution from the Java connector's temp directory, loadPlugins missing from the TS DSL, default-export unwrapping in BoundaryPluginLoader, and completing the DSL generator CLI. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014mD6p9EEmftbpBQHZZBWB1
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.
Replaces the outdated
reference/plugin-frameworkpage (which predated the real plugin framework and still described the JSii approach) with a new root-level Plugins documentation section, written so that a user with no prior context can implement their own plugin.What's here
A new
docs/plugins/section with six pages:ContractCasePluginobject, whyhumanReadableName/shortName/uniqueMachineNameare three separate names, the-dslpackage split and its rationale, and namespacing rulesyourorg:AnyUlid) covering descriptor design, the special_case:matcher:*keys, context modifiers, all four executor functions, thecheck(strip(x))invariant, errors-as-values, and child descent withaddLocationsetupblock explained via the function plugin's mirrored caller/execution pair, the mock lifecycle as a sequence diagram, a walkthrough of the realMockFunctionExecutionexecutor, andmockConfig/getPluginConfigPluginDslDeclarationmodel includingPassToMatcherloadPlugins, the package-name-only security restriction and why, load-time checks, "both sides need the plugin", and a pre-publishing checklistAlso:
reference/plugin-frameworkis kept alive (retitled "Contract file format") because published TSDoc incase-definition-dsllinks to that URL for the matcher format; it now points readers to the new sectiondocs/maintainers/todo.mdfor gaps found while writing (addressed by the follow-up PRs stacked on this one)Verification
onBrokenLinks: 'throw', so all internal links and anchors are checkedcase-plugin-base/case-plugin-dsl-typessource withtsc --strict🤖 Generated with Claude Code
https://claude.ai/code/session_014mD6p9EEmftbpBQHZZBWB1
Generated by Claude Code