Add comprehensive test coverage and edge case tests

.c8rc.json

@@ -0,0 +1,12 @@
+{
+  "all": true,
+  "include": ["src/**/*.js"],
+  "exclude": ["src/**/*.test.js", "src/**/*.integration.test.js"],
+  "reporter": ["text", "lcov", "json", "json-summary"],
+  "report-dir": "coverage",
+  "check-coverage": true,
+  "lines": 50,
+  "branches": 45,
+  "functions": 50,
+  "statements": 50
+}

.claude/skills/tdd-coverage/SKILL.md

@@ -0,0 +1,231 @@
+# TDD and Coverage Skill
+
+**Type:** Rigid (follow exactly)
+
+## When to Use
+
+Use this skill when:
+- Creating new functionality
+- Modifying existing code
+- Fixing bugs
+- Refactoring
+
+## Mandatory Process
+
+### 1. Test First (TDD)
+
+Before writing or modifying any implementation code:
+
+1. **Write the test(s)** that describe the expected behavior
+2. **Run the test** - it should FAIL (red)
+3. **Write the implementation** to make the test pass
+4. **Run the test** - it should PASS (green)
+5. **Refactor** if needed, keeping tests passing
+
+### 2. Coverage Verification
+
+After any code change:
+
+```bash
+# Run tests with coverage
+npm run test:coverage
+
+# Verify coverage hasn't decreased
+npm run coverage:ratchet
+```
+
+**Coverage must not decrease.** If ratchet check fails:
+1. Add tests for uncovered code
+2. Re-run coverage until ratchet passes
+
+### 3. Coverage Thresholds
+
+Current thresholds are in `coverage-thresholds.json`. These values must only increase:
+
+| Metric | Current Threshold |
+|--------|-------------------|
+| Lines | 87% |
+| Statements | 87% |
+| Functions | 97% |
+| Branches | 84% |
+
+### 4. Test Location
+
+Tests are co-located with source files in `src/`:
+
+| Code | Test File |
+|------|-----------|
+| `src/openapi.js` | `src/openapi.test.js` |
+| `src/arazzo.js` | `src/arazzo.test.js` |
+| `src/utils.js` | `src/utils.test.js` |
+| `src/resolve.js` | `src/resolve.test.js` |
+| `src/sanitize.js` | `src/sanitize.test.js` |
+| `src/telem.js` | `src/telem.test.js` |
+| `src/config.js` | `src/config.test.js` |
+| `src/heretto.js` | `src/heretto.test.js` |
+| `src/index.js` | `src/index.test.js` |
+
+### 5. Test Structure Pattern
+
+```javascript
+const { expect } = require("chai");
+const sinon = require("sinon");
+const { functionUnderTest } = require("./module");
+
+describe("Module Name", function () {
+  let consoleLogStub;
+
+  beforeEach(function () {
+    consoleLogStub = sinon.stub(console, "log");
+  });
+
+  afterEach(function () {
+    consoleLogStub.restore();
+  });
+
+  describe("functionUnderTest", function () {
+    describe("input validation", function () {
+      it("should throw error when required param missing", function () {
+        expect(() => functionUnderTest()).to.throw();
+      });
+    });
+
+    describe("happy path", function () {
+      it("should return expected result for valid input", function () {
+        const result = functionUnderTest({ validInput: true });
+        expect(result).to.deep.equal(expectedOutput);
+      });
+    });
+
+    describe("edge cases", function () {
+      it("should handle boundary condition", function () {
+        // test edge case
+      });
+    });
+  });
+});
+```
+
+### 6. Checklist
+
+Before completing any code change:
+
+- [ ] Tests written BEFORE implementation (or for existing code: tests added)
+- [ ] All tests pass (`npm test`)
+- [ ] Coverage hasn't decreased (`npm run coverage:ratchet`)
+- [ ] New code has corresponding test coverage
+- [ ] Error paths are tested (not just happy paths)
+
+## Commands Reference
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run coverage ratchet check (prevents coverage decrease)
+npm run coverage:ratchet
+
+# Check coverage thresholds
+npm run coverage:check
+
+# Run integration tests with coverage
+npm run test:integration:coverage
+
+# Run all tests with coverage
+npm run test:all:coverage
+```
+
+## Common Patterns
+
+### Testing async functions
+
+```javascript
+it("should handle async operation", async function () {
+  const result = await asyncFunction();
+  expect(result).to.exist;
+});
+```
+
+### Mocking with Sinon
+
+```javascript
+const stub = sinon.stub(fs, "readFileSync").returns("mock content");
+try {
+  const result = functionUnderTest();
+  expect(result).to.equal("expected");
+} finally {
+  stub.restore();
+}
+```
+
+### Stubbing console.log (for log() function tests)
+
+```javascript
+let consoleLogStub;
+
+beforeEach(function () {
+  consoleLogStub = sinon.stub(console, "log");
+});
+
+afterEach(function () {
+  consoleLogStub.restore();
+});
+```
+
+### Testing error handling
+
+```javascript
+it("should throw on invalid input", function () {
+  expect(() => functionUnderTest(null)).to.throw(/error message/);
+});
+```
+
+### Testing with temporary files
+
+```javascript
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+
+let tempDir;
+let tempFile;
+
+beforeEach(function () {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "test-"));
+  tempFile = path.join(tempDir, "test-file.txt");
+  fs.writeFileSync(tempFile, "test content");
+});
+
+afterEach(function () {
+  if (fs.existsSync(tempFile)) fs.unlinkSync(tempFile);
+  if (fs.existsSync(tempDir)) fs.rmdirSync(tempDir);
+});
+```
+
+### Testing OpenAPI operations
+
+```javascript
+it("should parse OpenAPI spec", async function () {
+  const spec = {
+    openapi: "3.0.0",
+    info: { title: "Test API", version: "1.0.0" },
+    paths: {
+      "/test": {
+        get: { operationId: "testOp", responses: { 200: { description: "OK" } } }
+      }
+    }
+  };
+  const result = await loadDescription(JSON.stringify(spec));
+  expect(result.info.title).to.equal("Test API");
+});
+```
+
+## Project-Specific Notes
+
+- Use `config.logLevel = "error"` in tests to suppress log output
+- The `log()` function from `utils.js` checks config.logLevel before logging
+- OpenAPI specs can be loaded from files or URLs using `loadDescription()`
+- The Arazzo workflow format is supported via `workflowToTest()`

.devcontainer/devcontainer.json

@@ -1,36 +1,36 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the
-// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
-{
-  "name": "Doc Detective Core",
-  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-  "image": "mcr.microsoft.com/devcontainers/base:jammy",
-  "features": {
-    "ghcr.io/devcontainers/features/node:1": {},
-    "ghcr.io/devcontainers-contrib/features/apt-get-packages:1": {}
-  },
-  "containerEnv": {
-    "IN_CONTAINER": "true"
-  },
-  // Use 'forwardPorts' to make a list of ports inside the container available locally.
-  // "forwardPorts": [],
-
-  // Use 'postCreateCommand' to run commands after the container is created.
-  // "postCreateCommand": ".devcontainer/post-create.sh",
-  // Configure tool-specific properties.
-  "customizations": {
-    // Configure properties specific to VS Code.
-    "vscode": {
-      // Add the IDs of extensions you want installed when the container is created.
-      "extensions": [
-        "github.copilot",
-        "aaron-bond.better-comments",
-        "esbenp.prettier-vscode",
-        "GitHub.vscode-pull-request-github",
-        "streetsidesoftware.code-spell-checker"
-      ]
-    }
-  }
-
-  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-  // "remoteUser": "root"
-}
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
+{
+  "name": "Doc Detective Core",
+  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+  "image": "mcr.microsoft.com/devcontainers/base:jammy",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers-contrib/features/apt-get-packages:1": {}
+  },
+  "containerEnv": {
+    "IN_CONTAINER": "true"
+  },
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  // "forwardPorts": [],
+
+  // Use 'postCreateCommand' to run commands after the container is created.
+  // "postCreateCommand": ".devcontainer/post-create.sh",
+  // Configure tool-specific properties.
+  "customizations": {
+    // Configure properties specific to VS Code.
+    "vscode": {
+      // Add the IDs of extensions you want installed when the container is created.
+      "extensions": [
+        "github.copilot",
+        "aaron-bond.better-comments",
+        "esbenp.prettier-vscode",
+        "GitHub.vscode-pull-request-github",
+        "streetsidesoftware.code-spell-checker"
+      ]
+    }
+  }
+
+  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+  // "remoteUser": "root"
+}

.gitattributes

@@ -0,0 +1,3 @@
+# Enforce LF line endings for YAML files
+*.yml text eol=lf
+*.yaml text eol=lf

.github/workflows/auto-dev-release.yml

@@ -51,8 +51,9 @@ jobs:
           echo "Changed files:"
           echo "$CHANGED_FILES"
 
-          # Check if only documentation files changed
-          if echo "$CHANGED_FILES" | grep -v -E '\.(md|txt|yml|yaml)$|^\.github/' | grep -q .; then
+          # Check if only documentation files changed (md, txt, or docs/ directory)
+          # YAML and .github/ files are NOT considered documentation
+          if echo "$CHANGED_FILES" | grep -v -E '\.(md|txt)$|^docs/' | grep -q .; then
             echo "skip_release=false" >> $GITHUB_OUTPUT
             echo "Code changes detected, proceeding with release"
           else
@@ -92,9 +93,14 @@ jobs:
         if: steps.check_changes.outputs.skip_release == 'false'
         run: npm ci
 
-      - name: Run tests
+      - name: Run tests with coverage
+        id: run_tests
         if: steps.check_changes.outputs.skip_release == 'false'
-        run: npm test
+        run: npm run test:coverage
+
+      - name: Check coverage ratchet
+        if: steps.check_changes.outputs.skip_release == 'false' && steps.run_tests.outcome == 'success'
+        run: npm run coverage:ratchet
 
       - name: Configure Git
         run: |
@@ -171,4 +177,4 @@ jobs:
         if: steps.check_changes.outputs.skip_release == 'true'
         run: |
           echo "⏭️ Auto dev release skipped"
-          echo "📝 Only documentation changes detected"
+          echo "📝 Only documentation changes detected"

.github/workflows/integration-tests.yml

@@ -41,15 +41,23 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run integration tests
+      - name: Run integration tests with coverage
         env:
           CI: 'true'
           HERETTO_ORGANIZATION_ID: ${{ secrets.HERETTO_ORGANIZATION_ID }}
           HERETTO_USERNAME: ${{ secrets.HERETTO_USERNAME }}
           HERETTO_API_TOKEN: ${{ secrets.HERETTO_API_TOKEN }}
           # HERETTO_SCENARIO_NAME is optional - defaults to 'Doc Detective' in the application
           HERETTO_SCENARIO_NAME: ${{ secrets.HERETTO_SCENARIO_NAME }}
-        run: npm run test:integration
+        run: npm run test:integration:coverage
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 7
 
       - name: Upload test results
         if: always()