From 94445ba4aeb899c1c86e4b12ccda3db1a69dfb5e Mon Sep 17 00:00:00 2001 From: Timothy Jones Date: Sun, 31 May 2026 20:26:30 +1000 Subject: [PATCH 1/2] docs: Sync maintainer docs with current code Reviewed docs/maintainers against the codebase and fixed drift: - DslGenerators: correct package name to @contract-case/definition-generator - CodingStandards: replace stale .eslintrc-style example with the flat eslint.config.mjs form and correct package name (@contract-case/eslint-config-case-maintainer) - PackageStructure: document the case-definition-generator package, and replace the truncated case-definition-dsl note - it is being deprecated in favour of the definition generator - AddingDsl: clarify the standalone @contract-case/case-boundary package was removed; boundary types now live inside case-connector Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/maintainers/AddingDsl.md | 2 +- docs/maintainers/CodingStandards.md | 10 +++++----- docs/maintainers/DslGenerators.md | 2 +- docs/maintainers/PackageStructure.md | 6 +++++- 4 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/maintainers/AddingDsl.md b/docs/maintainers/AddingDsl.md index 4b54e4dcd..5773b35b8 100644 --- a/docs/maintainers/AddingDsl.md +++ b/docs/maintainers/AddingDsl.md @@ -30,7 +30,7 @@ break these rules won't be accepted. - **No hand-written JSON matcher/mock example definitions go in your DSL.** The pure-json interaction and matcher definitions are already exposed by other packages. You should not be creating JSON for Interactions or Matchers in your DSL, unless you are depending on those other translated boundary packages to do so. Long term, if a non-JSii language were to be supported, it would need its own JSON definitions (ideally, parsed from `@contract-case/case-entities-internal`). -- **No types from `@contract-case/case-boundary` are to be exposed to users.** These types are internal implementation details. +- **No boundary types (from the `case-boundary` module inside `@contract-case/case-connector`) are to be exposed to users.** These types are internal implementation details. (The standalone `@contract-case/case-boundary` package has been removed - see [the case boundary API reference](./reference/case-boundary-API.md).) - **Your user-facing package may depend on other user-facing packages.** For example, a Gradle DSL can depend on the Java DSL. Or a Jest DSL can depend on the TypeScript DSL. diff --git a/docs/maintainers/CodingStandards.md b/docs/maintainers/CodingStandards.md index e4d237469..35cffafeb 100644 --- a/docs/maintainers/CodingStandards.md +++ b/docs/maintainers/CodingStandards.md @@ -482,12 +482,12 @@ Extend the shared config: ### ESLint Configuration -Extend the shared maintainer config: +Use the shared maintainer config via a flat config in `eslint.config.mjs`: -```json -{ - "extends": ["@contract-case/case-maintainer"] -} +```js +import lintConfig from '@contract-case/eslint-config-case-maintainer'; + +export default [...lintConfig]; ``` ### Package Scripts diff --git a/docs/maintainers/DslGenerators.md b/docs/maintainers/DslGenerators.md index 63824eac9..4776c7c83 100644 --- a/docs/maintainers/DslGenerators.md +++ b/docs/maintainers/DslGenerators.md @@ -1,7 +1,7 @@ ## DSL Generators ContractCase has a new DSL system, which allows matcher generation -from a json definition, consumed by the `@contract-case/case-definition-generator` package. +from a json definition, consumed by the `@contract-case/definition-generator` package. Properties that the generated matchers must support in order for the generator's type system to make sense: diff --git a/docs/maintainers/PackageStructure.md b/docs/maintainers/PackageStructure.md index c3ddc961a..7cc36c3f6 100644 --- a/docs/maintainers/PackageStructure.md +++ b/docs/maintainers/PackageStructure.md @@ -44,12 +44,16 @@ These are the packages that users will actually import and use in their tests. T Additionally, there are two cross-platform packages: - `contract-case-cli`: The cross-platform CLI used for contract manipulation and contacting a broker. -- `case-definition-dsl`: The JSii layer that just describes the definition language for defining interactions to be run. This should be renamed `contract-case-definition-dsl` for consistency. It currently re-exports the http-plugin-dsl types - long term, we should separate this into a separate +- `case-definition-dsl`: The JSii layer that just describes the definition language for defining interactions to be run. It currently re-exports the http-plugin-dsl types (and the function-plugin-dsl types). This package is being deprecated in favour of the definition generator (`@contract-case/definition-generator`), which generates the DSL source files instead - see [DSL Generators](./DslGenerators.md). #### Documentation The main documentation is built in the `documentation` package. Any custom code that's specific to `contract-case` is in a package prefixed with documentation - eg `documentation-matchers-generator` generates the matcher documentation. None of the documentation packages are published to any package managers. +#### Code generation + +- `case-definition-generator` (published as `@contract-case/definition-generator`): Generates DSL source files for the matcher DSLs from a JSON definition. See [DSL Generators](./DslGenerators.md). + #### Maintainer packages - `case-maintainer-config`: Common settings for maintaining packages (doesn't include the eslint config, as it needs specific naming conventions). From e4b2d6a816f0387c93ad099c4f66856c0488b0e0 Mon Sep 17 00:00:00 2001 From: Timothy Jones Date: Sun, 31 May 2026 20:30:09 +1000 Subject: [PATCH 2/2] docs: Drop reference to removed case-boundary package Keep AddingDsl referencing only current/future states. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/maintainers/AddingDsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maintainers/AddingDsl.md b/docs/maintainers/AddingDsl.md index 5773b35b8..487ad3191 100644 --- a/docs/maintainers/AddingDsl.md +++ b/docs/maintainers/AddingDsl.md @@ -30,7 +30,7 @@ break these rules won't be accepted. - **No hand-written JSON matcher/mock example definitions go in your DSL.** The pure-json interaction and matcher definitions are already exposed by other packages. You should not be creating JSON for Interactions or Matchers in your DSL, unless you are depending on those other translated boundary packages to do so. Long term, if a non-JSii language were to be supported, it would need its own JSON definitions (ideally, parsed from `@contract-case/case-entities-internal`). -- **No boundary types (from the `case-boundary` module inside `@contract-case/case-connector`) are to be exposed to users.** These types are internal implementation details. (The standalone `@contract-case/case-boundary` package has been removed - see [the case boundary API reference](./reference/case-boundary-API.md).) +- **No boundary types (from the `case-boundary` module inside `@contract-case/case-connector`) are to be exposed to users.** These types are internal implementation details. - **Your user-facing package may depend on other user-facing packages.** For example, a Gradle DSL can depend on the Java DSL. Or a Jest DSL can depend on the TypeScript DSL.