doc-detective-common 4.0.0 → 4.0.1-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-detective-common",
-  "version": "4.0.0",
+  "version": "4.0.1-dev.2",
   "description": "Shared components for Doc Detective projects.",
   "type": "module",
   "main": "dist/index.cjs",

package/scripts/check-coverage-ratchet.cjs

@@ -0,0 +1,123 @@
+#!/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.cjs
+ */
+
+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 currentMetric = current?.[metric];
+    if (typeof baseline !== 'number' || typeof currentMetric?.pct !== 'number') {
+      console.error(`Invalid or missing coverage metric: "${metric}"`);
+      process.exit(1);
+    }
+    const currentValue = currentMetric.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/scripts/createCjsWrapper.js

@@ -0,0 +1,25 @@
+import { build } from "esbuild";
+import { copyFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const distDir = path.join(__dirname, "..", "dist");
+
+await build({
+  entryPoints: [path.join(distDir, "index.js")],
+  outfile: path.join(distDir, "index.cjs"),
+  bundle: true,
+  format: "cjs",
+  platform: "node",
+  packages: "external",
+});
+
+await copyFile(
+  path.join(distDir, "index.d.ts"),
+  path.join(distDir, "index.d.cts")
+);
+
+console.log("Created CJS bundle at dist/index.cjs");
+console.log("Copied type definitions to dist/index.d.cts");

package/scripts/generateTypes.cjs

@@ -0,0 +1,54 @@
+const { compile } = require("json-schema-to-typescript");
+const fs = require("fs").promises;
+const path = require("path");
+
+async function generateTypes() {
+  const schemasDir = path.join(__dirname, "..", "src", "schemas", "output_schemas");
+  const outputDir = path.join(__dirname, "..", "src", "types", "generated");
+
+  // Create output directory
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Get all v3 schema files (current version)
+  const files = await fs.readdir(schemasDir);
+  const v3Schemas = files.filter((f) => f.endsWith("_v3.schema.json"));
+
+  console.log(`Generating TypeScript types for ${v3Schemas.length} schemas...`);
+
+  let hadErrors = false;
+  const failedFiles = [];
+
+  for (const file of v3Schemas) {
+    const schemaPath = path.join(schemasDir, file);
+
+    try {
+      const schema = JSON.parse(await fs.readFile(schemaPath, "utf-8"));
+      const ts = await compile(schema, schema.title || file.replace(".schema.json", ""), {
+        bannerComment: `/* eslint-disable */\n/**\n * Auto-generated from ${file}\n * Do not edit manually\n */`,
+        style: {
+          semi: true,
+          trailingComma: "es5",
+        },
+      });
+
+      const outputPath = path.join(outputDir, file.replace(".schema.json", ".ts"));
+      await fs.writeFile(outputPath, ts);
+      console.log(`  ✓ ${file} → ${path.basename(outputPath)}`);
+    } catch (error) {
+      hadErrors = true;
+      failedFiles.push(file);
+      console.error(`  ✗ Failed to generate ${file}:`, error.message);
+    }
+  }
+
+  if (hadErrors) {
+    throw new Error(`One or more schemas failed to generate TypeScript types: ${failedFiles.join(", ")}`);
+  }
+
+  console.log("Type generation complete!");
+}
+
+generateTypes().catch((error) => {
+  console.error("Type generation failed:", error);
+  process.exit(1);
+});