doc-detective-common 3.6.0-dev.2 → 3.6.1-dev.1

package/.c8rc.json

@@ -0,0 +1,8 @@
+{
+  "all": true,
+  "include": ["src/**/*.js"],
+  "exclude": ["src/schemas/dereferenceSchemas.js"],
+  "reporter": ["text", "lcov", "json", "json-summary"],
+  "report-dir": "coverage",
+  "check-coverage": false
+}

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

@@ -0,0 +1,161 @@
+# 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 test: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 | Threshold |
+|--------|-----------|
+| Lines | 100% |
+| Statements | 100% |
+| Functions | 100% |
+| Branches | 100% |
+
+### 4. Test Location
+
+| Code | Test File |
+|------|-----------|
+| `src/validate.js` | `test/validate.test.js` |
+| `src/resolvePaths.js` | `test/resolvePaths.test.js` |
+| `src/files.js` | `test/files.test.js` |
+| Schema validation | `test/schema.test.js` |
+
+### 5. Test Structure Pattern
+
+```javascript
+const sinon = require("sinon");
+
+(async () => {
+  const { expect } = await import("chai");
+  const { functionUnderTest } = require("../src/module");
+
+  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 test: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
+npm run test:coverage:ratchet
+
+# Generate HTML coverage report
+npm run test:coverage:html
+```
+
+## 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();
+}
+```
+
+### Testing error handling
+
+```javascript
+it("should throw on invalid input", function () {
+  expect(() => functionUnderTest(null)).to.throw(/error message/);
+});
+```
+
+### Testing transformations
+
+```javascript
+it("should transform v2 object to v3", function () {
+  const result = transformToSchemaKey({
+    currentSchema: "schema_v2",
+    targetSchema: "schema_v3",
+    object: v2Object,
+  });
+  expect(result.newProperty).to.equal(expectedValue);
+});
+```

package/AGENTS.md

@@ -106,6 +106,8 @@ When creating new schema version (e.g., v4):
 **Test structure (Mocha + Chai):**
 - `test/schema.test.js`: Validates all schema examples (auto-generated from schemas)
 - `test/files.test.js`: Unit tests for `readFile()` with Sinon stubs
+- `test/validate.test.js`: Tests for `validate()` and `transformToSchemaKey()`
+- `test/resolvePaths.test.js`: Tests for path resolution
 
 **Run tests:** `npm test` (or `mocha`)
 
@@ -115,6 +117,51 @@ const result = validate({ schemaKey: "step_v3", object: example });
 assert.ok(result.valid, `Validation failed: ${result.errors}`);
 ```
 
+### Testing Requirements (CRITICAL)
+
+**TDD is mandatory for this project.** All code changes must follow test-driven development:
+
+1. **Write tests first** - before any implementation
+2. **Run tests** - verify they fail (red)
+3. **Write implementation** - make tests pass
+4. **Run tests** - verify they pass (green)
+5. **Check coverage** - must not decrease
+
+**Coverage enforcement:**
+
+```bash
+# Run tests with coverage
+npm run test:coverage
+
+# Verify coverage baseline (CI enforces this)
+npm run test:coverage:ratchet
+
+# Generate HTML report for detailed analysis
+npm run test:coverage:html
+```
+
+**Current coverage thresholds (enforced by CI):**
+
+| Metric | Threshold |
+|--------|-----------|
+| Lines | 100% |
+| Statements | 100% |
+| Functions | 100% |
+| Branches | 100% |
+
+**Coverage ratchet:** Thresholds in `coverage-thresholds.json` can only increase. CI fails if coverage decreases.
+
+**Test file mapping:**
+
+| Source | Test File |
+|--------|-----------|
+| `src/validate.js` | `test/validate.test.js` |
+| `src/resolvePaths.js` | `test/resolvePaths.test.js` |
+| `src/files.js` | `test/files.test.js` |
+| Schema examples | `test/schema.test.js` |
+
+**AI Tooling:** See `.claude/skills/tdd-coverage/SKILL.md` for detailed TDD workflow.
+
 ### Version Management & CI/CD Workflows
 
 #### Auto Dev Release (`.github/workflows/auto-dev-release.yml`)

package/CLAUDE.md

@@ -0,0 +1,38 @@
+# Claude Code Configuration
+
+This file is a pointer for Claude Code and similar AI assistants.
+
+## Primary Documentation
+
+See **[AGENTS.md](./AGENTS.md)** for complete project guidelines, architecture, and development workflows.
+
+## Quick Reference
+
+### Testing (CRITICAL)
+
+**All code changes require TDD:**
+1. Write tests first
+2. Verify tests fail
+3. Write implementation
+4. Verify tests pass
+5. Check coverage: `npm run test:coverage:ratchet`
+
+**Coverage must never decrease.**
+
+### Available Commands
+
+```bash
+npm test                     # Run tests
+npm run test:coverage        # Tests + coverage report
+npm run test:coverage:ratchet # Verify coverage baseline
+npm run build               # Build schemas
+```
+
+### Key Files
+
+| Purpose | Location |
+|---------|----------|
+| Project guidelines | `AGENTS.md` |
+| TDD/Coverage skill | `.claude/skills/tdd-coverage/SKILL.md` |
+| Coverage config | `.c8rc.json` |
+| Coverage baseline | `coverage-thresholds.json` |

package/coverage-thresholds.json

@@ -0,0 +1,8 @@
+{
+  "description": "Coverage baseline thresholds. These values should only increase, never decrease.",
+  "lastUpdated": "2026-01-07",
+  "lines": 100,
+  "statements": 100,
+  "functions": 100,
+  "branches": 100
+}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "doc-detective-common",
-  "version": "3.6.0-dev.2",
+  "version": "3.6.1-dev.1",
   "description": "Shared components for Doc Detective projects.",
   "main": "src/index.js",
   "scripts": {
     "dereferenceSchemas": "node ./src/schemas/dereferenceSchemas.js",
     "build": "npm run dereferenceSchemas",
     "postbuild": "npm run test",
-    "test": "mocha"
+    "test": "mocha",
+    "test:coverage": "c8 mocha",
+    "test:coverage:html": "c8 --reporter=html mocha",
+    "test:coverage:check": "c8 check-coverage",
+    "test:coverage:ratchet": "node scripts/check-coverage-ratchet.js"
   },
   "repository": {
     "type": "git",
@@ -20,6 +24,7 @@
   },
   "homepage": "https://github.com/doc-detective/doc-detective-common#readme",
   "devDependencies": {
+    "c8": "^10.1.3",
     "chai": "^6.2.2",
     "mocha": "^11.7.5",
     "sinon": "^21.0.1"

package/scripts/check-coverage-ratchet.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Coverage Ratchet Script
+ * 
+ * Compares current coverage against baseline thresholds.
+ * Fails if any metric has decreased.
+ * 
+ * Usage: node scripts/check-coverage-ratchet.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const THRESHOLDS_FILE = path.join(__dirname, '..', 'coverage-thresholds.json');
+const COVERAGE_SUMMARY_FILE = path.join(__dirname, '..', 'coverage', 'coverage-summary.json');
+
+/**
+ * Load and parse JSON from the given path, exiting the process with code 1 if the file is missing or cannot be parsed.
+ * @param {string} filePath - Filesystem path to the JSON file.
+ * @param {string} description - Human-readable name for the file used in error messages.
+ * @returns {Object} The parsed JSON object.
+ */
+function loadJSON(filePath, description) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`Error: ${description} not found at ${filePath}`);
+    console.error(`Run 'npm run test:coverage' first to generate coverage data.`);
+    process.exit(1);
+  }
+  
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    console.error(`Error parsing ${description}: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Compares current test coverage against the stored baseline thresholds and enforces the coverage ratchet.
+ *
+ * Loads baseline thresholds and the current coverage summary, prints a per-metric table of baseline vs current values and statuses, and enforces policy:
+ * - Exits with code 1 if any metric has decreased relative to the baseline.
+ * - If one or more metrics have improved, prints suggested threshold updates.
+ * - Exits with code 0 when all metrics meet or exceed their baselines.
+ */
+function main() {
+  // Load baseline thresholds
+  const thresholds = loadJSON(THRESHOLDS_FILE, 'Coverage thresholds file');
+  
+  // Load current coverage
+  const coverageSummary = loadJSON(COVERAGE_SUMMARY_FILE, 'Coverage summary');
+  
+  const current = coverageSummary.total;
+  const metrics = ['lines', 'statements', 'functions', 'branches'];
+  
+  let failed = false;
+  const results = [];
+  
+  console.log('\n=== Coverage Ratchet Check ===\n');
+  console.log('Metric      | Baseline | Current  | Status');
+  console.log('------------|----------|----------|--------');
+  
+  for (const metric of metrics) {
+    const baseline = thresholds[metric];
+    const currentValue = current[metric].pct;
+    const diff = (currentValue - baseline).toFixed(2);
+    
+    let status;
+    if (currentValue < baseline) {
+      status = `FAIL (${diff}%)`;
+      failed = true;
+    } else if (currentValue > baseline) {
+      status = `PASS (+${diff}%)`;
+    } else {
+      status = 'PASS';
+    }
+    
+    const baselineStr = `${baseline.toFixed(2)}%`.padEnd(8);
+    const currentStr = `${currentValue.toFixed(2)}%`.padEnd(8);
+    const metricStr = metric.padEnd(11);
+    
+    console.log(`${metricStr} | ${baselineStr} | ${currentStr} | ${status}`);
+    
+    results.push({
+      metric,
+      baseline,
+      current: currentValue,
+      passed: currentValue >= baseline
+    });
+  }
+  
+  console.log('');
+  
+  if (failed) {
+    console.error('Coverage ratchet check FAILED!');
+    console.error('Coverage has decreased from the baseline.');
+    console.error('Please add tests to restore coverage before committing.');
+    process.exit(1);
+  }
+  
+  // Check if we can bump thresholds
+  const canBump = results.filter(r => r.current > r.baseline);
+  if (canBump.length > 0) {
+    console.log('Coverage has improved! Consider updating thresholds:');
+    console.log('');
+    for (const r of canBump) {
+      console.log(`  "${r.metric}": ${r.current.toFixed(2)}`);
+    }
+    console.log('');
+    console.log(`Update ${THRESHOLDS_FILE} to lock in the new baseline.`);
+  }
+  
+  console.log('Coverage ratchet check PASSED!');
+  process.exit(0);
+}
+
+main();

package/src/resolvePaths.js

@@ -5,19 +5,18 @@ const { validate } = require("./validate");
 exports.resolvePaths = resolvePaths;
 
 /**
- * Recursively resolves all relative path properties in a configuration or specification object to absolute paths.
+ * Convert recognized relative path properties in a config or spec object to absolute paths.
  *
- * Traverses the provided object, converting all recognized path-related properties to absolute paths using the given configuration and reference file path. Supports nested objects and distinguishes between config and spec objects based on schema validation. Throws an error if the object is not a valid config or spec, or if the object type is missing for nested objects.
+ * Traverses the provided object (recursing into nested objects and arrays), resolving fields that represent filesystem paths according to the provided config.relativePathBase and reference filePath. On top-level calls the function infers whether the object is a config or spec via schema validation; for nested calls objectType must be provided.
  *
- * @async
  * @param {Object} options - Options for path resolution.
- * @param {Object} options.config - Configuration object containing settings such as `relativePathBase`.
+ * @param {Object} options.config - Configuration containing settings such as `relativePathBase`.
  * @param {Object} options.object - The config or spec object whose path properties will be resolved.
- * @param {string} options.filePath - Reference file path used for resolving relative paths.
- * @param {boolean} [options.nested=false] - Indicates if this is a recursive call for a nested object.
- * @param {string} [options.objectType] - Specifies the object type ('config' or 'spec'); required for nested objects.
- * @returns {Promise<Object>} The object with all applicable path properties resolved to absolute paths.
- * @throws {Error} If the object is neither a valid config nor spec, or if `objectType` is missing for nested objects.
+ * @param {string} options.filePath - Reference file or directory used to resolve relative paths.
+ * @param {boolean} [options.nested=false] - True when invoked recursively for nested objects.
+ * @param {string} [options.objectType] - 'config' or 'spec'; required for nested invocations to select which properties to resolve.
+ * @returns {Object} The same object with applicable path properties converted to absolute paths.
+ * @throws {Error} If the top-level object matches neither config nor spec schema, or if `objectType` is missing for nested calls.
  */
 async function resolvePaths({
   config,
@@ -223,6 +222,7 @@ async function resolvePaths({
 }
 
 // If called directly, resolve paths in the provided object
+/* c8 ignore start */
 if (require.main === module) {
   (async () => {
     // Example usage
@@ -250,3 +250,4 @@ if (require.main === module) {
     console.log(JSON.stringify(object, null, 2));
   })();
 }
+/* c8 ignore stop */

package/src/validate.js

@@ -148,6 +148,7 @@ function validate({ schemaKey, object, addDefaults = true }) {
       if (result.valid) {
         validationObject = transformedObject;
         object = transformedObject;
+        /* c8 ignore start - Defensive: transformToSchemaKey validates internally, so this is unreachable */
       } else if (check.errors) {
         const errors = check.errors.map(
           (error) =>
@@ -158,6 +159,7 @@ function validate({ schemaKey, object, addDefaults = true }) {
         result.errors = errors.join(", ");
         return result;
       }
+      /* c8 ignore stop */
     }
   }
   if (addDefaults) {
@@ -170,18 +172,14 @@ function validate({ schemaKey, object, addDefaults = true }) {
 }
 
 /**
- * Transforms an object from one JSON schema version to another, supporting multiple schema types and nested conversions.
+ * Transform an object from one schema key to another and return a validated instance of the target schema.
  *
- * @param {Object} params
- * @param {string} params.currentSchema - The schema key of the object's current version.
- * @param {string} params.targetSchema - The schema key to which the object should be transformed.
- * @param {Object} params.object - The object to transform.
- * @returns {Object} The transformed object, validated against the target schema.
- *
- * @throws {Error} If transformation between the specified schemas is not supported, or if the transformed object fails validation.
- *
- * @remark
- * Supports deep and recursive transformations for complex schema types, including steps, configs, contexts, OpenAPI integrations, specs, and tests. Throws if the schemas are incompatible or if the resulting object does not conform to the target schema.
+ * @param {Object} params - Function parameters.
+ * @param {string} params.currentSchema - Schema key representing the object's current version.
+ * @param {string} params.targetSchema - Schema key to transform the object into.
+ * @param {Object} params.object - The source object to transform.
+ * @returns {Object} The transformed object conforming to the target schema.
+ * @throws {Error} If transformation between the specified schemas is not supported or if the transformed object fails validation.
  */
 function transformToSchemaKey({
   currentSchema = "",
@@ -445,6 +443,8 @@ function transformToSchemaKey({
       schemaKey: "config_v3",
       object: transformedObject,
     });
+    // Defensive: transformation always produces valid config_v3, unreachable
+    /* c8 ignore next 3 */
     if (!result.valid) {
       throw new Error(`Invalid object: ${result.errors}`);
     }
@@ -528,6 +528,8 @@ function transformToSchemaKey({
       schemaKey: "spec_v3",
       object: transformedObject,
     });
+    // Defensive: nested transforms validate; this is unreachable
+    /* c8 ignore next 3 */
     if (!result.valid) {
       throw new Error(`Invalid object: ${result.errors}`);
     }
@@ -570,18 +572,25 @@ function transformToSchemaKey({
       schemaKey: "test_v3",
       object: transformedObject,
     });
+    // Defensive: nested transforms validate; this is unreachable
+    /* c8 ignore next 3 */
     if (!result.valid) {
       throw new Error(`Invalid object: ${result.errors}`);
     }
     return result.object;
   }
+  /* c8 ignore next - Dead code: incompatible schemas throw at line 197-200 */
   return null;
 }
 
 // If called directly, validate an example object
+/* c8 ignore start */
 if (require.main === module) {
-  const example =  {path: "/User/manny/projects/doc-detective/static/images/image.png"};
+  const example = {
+    path: "/User/manny/projects/doc-detective/static/images/image.png",
+  };
 
   const result = validate({ schemaKey: "screenshot_v3", object: example });
   console.log(JSON.stringify(result, null, 2));
 }
+/* c8 ignore stop */