From 51809cf3ddd07885e3fa15983e24b3b269756ea8 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Wed, 17 Dec 2025 17:36:51 +0000 Subject: [PATCH 1/4] Add doc-detective-resolver to dependency list --- docs/contribute/repos/doc-detective.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contribute/repos/doc-detective.md b/docs/contribute/repos/doc-detective.md index 870abf92..0fc9d206 100644 --- a/docs/contribute/repos/doc-detective.md +++ b/docs/contribute/repos/doc-detective.md @@ -8,4 +8,5 @@ The most common entrypoint for most users, [`doc-detective`](https://github.com/ This repo depends on - [`doc-detective-core`](doc-detective-core) for the primary testing logic. -- [`doc-detective-common`](doc-detective-common) for JSON schema definitions, schema validation logic, and path resolution logic. \ No newline at end of file +- [`doc-detective-common`](doc-detective-common) for JSON schema definitions, schema validation logic, and path resolution logic. +- [`doc-detective-resolver`](resolver) for detecting and resolving documentation into Doc Detective tests. \ No newline at end of file From 5680a56242ab0f97c32f3a8a58c8dbca14d670d6 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Wed, 17 Dec 2025 17:42:57 +0000 Subject: [PATCH 2/4] Sync documentation updates --- docs/contribute/repos/doc-detective.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/repos/doc-detective.md b/docs/contribute/repos/doc-detective.md index 0fc9d206..d8751803 100644 --- a/docs/contribute/repos/doc-detective.md +++ b/docs/contribute/repos/doc-detective.md @@ -9,4 +9,4 @@ The most common entrypoint for most users, [`doc-detective`](https://github.com/ This repo depends on - [`doc-detective-core`](doc-detective-core) for the primary testing logic. - [`doc-detective-common`](doc-detective-common) for JSON schema definitions, schema validation logic, and path resolution logic. -- [`doc-detective-resolver`](resolver) for detecting and resolving documentation into Doc Detective tests. \ No newline at end of file +- [`doc-detective-resolver`](https://github.com/doc-detective/resolver) for detecting and resolving documentation into Doc Detective tests. \ No newline at end of file From 2f619715190fa321231a366547501a9452cc7842 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Wed, 17 Dec 2025 17:52:15 +0000 Subject: [PATCH 3/4] Sync documentation updates --- docs/contribute/repos/doc-detective.md | 2 +- docs/contribute/repos/resolver.md | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 docs/contribute/repos/resolver.md diff --git a/docs/contribute/repos/doc-detective.md b/docs/contribute/repos/doc-detective.md index d8751803..0fc9d206 100644 --- a/docs/contribute/repos/doc-detective.md +++ b/docs/contribute/repos/doc-detective.md @@ -9,4 +9,4 @@ The most common entrypoint for most users, [`doc-detective`](https://github.com/ This repo depends on - [`doc-detective-core`](doc-detective-core) for the primary testing logic. - [`doc-detective-common`](doc-detective-common) for JSON schema definitions, schema validation logic, and path resolution logic. -- [`doc-detective-resolver`](https://github.com/doc-detective/resolver) for detecting and resolving documentation into Doc Detective tests. \ No newline at end of file +- [`doc-detective-resolver`](resolver) for detecting and resolving documentation into Doc Detective tests. \ No newline at end of file diff --git a/docs/contribute/repos/resolver.md b/docs/contribute/repos/resolver.md new file mode 100644 index 00000000..de555d22 --- /dev/null +++ b/docs/contribute/repos/resolver.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 4 +--- + +# `doc-detective-resolver` + +[`doc-detective-resolver`](https://github.com/doc-detective/resolver) is an NPM package that detects and resolves documentation into Doc Detective tests. It's installable via NPM (`npm i doc-detective-resolver`). + +This repo depends on [`doc-detective-common`](doc-detective-common) for JSON schema definitions, schema validation logic, and path resolution logic. From dae4fdbcff9000b8a0bd5d80769c6959e8cfca54 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Fri, 9 Jan 2026 01:42:32 +0000 Subject: [PATCH 4/4] Sync documentation updates --- docs/contribute/repos/resolver.md | 86 +++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/docs/contribute/repos/resolver.md b/docs/contribute/repos/resolver.md index de555d22..fea4e46a 100644 --- a/docs/contribute/repos/resolver.md +++ b/docs/contribute/repos/resolver.md @@ -7,3 +7,89 @@ sidebar_position: 4 [`doc-detective-resolver`](https://github.com/doc-detective/resolver) is an NPM package that detects and resolves documentation into Doc Detective tests. It's installable via NPM (`npm i doc-detective-resolver`). This repo depends on [`doc-detective-common`](doc-detective-common) for JSON schema definitions, schema validation logic, and path resolution logic. + +## Contributing code + +Code contributions to `doc-detective-resolver` need tests that maintain code coverage. This keeps the resolver stable across the Doc Detective ecosystem. + +### Test requirements + +Your contribution needs: + +- **Unit tests**: Each source file in `src/` needs a corresponding test file (also in `src/`) +- **Minimum coverage**: All metrics must meet or exceed baseline thresholds +- **Coverage ratchet**: Coverage can't decrease from current baselines + +Test file locations: + +| Source file | Test file | +|-------------|-----------| +| `src/openapi.js` | `src/openapi.test.js` | +| `src/arazzo.js` | `src/arazzo.test.js` | +| `src/resolve.js` | `src/resolve.test.js` | +| `src/sanitize.js` | `src/sanitize.test.js` | +| `src/utils.js` | `src/utils.test.js` | +| `src/config.js` | `src/config.test.js` | +| `src/heretto.js` | `src/heretto.test.js` | +| `src/telem.js` | `src/telem.test.js` | + +### Running tests + +Run the full test suite: + +```bash +npm test +``` + +Run tests with coverage reporting: + +```bash +npm run test:coverage +``` + +Verify coverage hasn't decreased: + +```bash +npm run coverage:ratchet +``` + +Run all tests including integration tests: + +```bash +npm run test:all +``` + +Run all tests with coverage: + +```bash +npm run test:all:coverage +``` + +### How coverage is enforced + +The coverage ratchet check runs automatically in CI. It compares your coverage against baseline thresholds in `coverage-thresholds.json`. If coverage decreases, the build fails. + +Current thresholds: + +| Metric | Threshold | +|--------|-----------| +| Lines | 87% | +| Statements | 87% | +| Functions | 97% | +| Branches | 84% | + +To pass the ratchet check: + +1. Write tests for all new code +2. Run `npm run coverage:ratchet` locally +3. If the check fails, add tests until coverage is restored +4. Commit your tests with your code changes + +### Test-driven development + +TDD works well here. It helps you catch edge cases early and maintain coverage naturally: + +1. Write tests that describe expected behavior (tests should fail) +2. Implement the code to make tests pass +3. Refactor while keeping tests passing +4. Verify coverage with `npm run coverage:ratchet`