📝 Add docstrings to coverage

scripts/check-coverage-ratchet.js

@@ -15,6 +15,12 @@ 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}`);
@@ -30,6 +36,14 @@ function loadJSON(filePath, description) {
   }
 }
 
+/**
+ * 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');
@@ -101,4 +115,4 @@ function main() {
   process.exit(0);
 }
 
-main();
+main();

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,
@@ -251,4 +250,4 @@ if (require.main === module) {
     console.log(JSON.stringify(object, null, 2));
   })();
 }
-/* c8 ignore stop */
+/* c8 ignore stop */

src/validate.js

@@ -172,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 = "",
@@ -597,4 +593,4 @@ if (require.main === module) {
   const result = validate({ schemaKey: "screenshot_v3", object: example });
   console.log(JSON.stringify(result, null, 2));
 }
-/* c8 ignore stop */
+/* c8 ignore stop */