@carecard/validate 3.18.0 → 3.19.0

package/lib/validateWhitelistProperties.js

@@ -1,8 +1,8 @@
 'use strict';
 
 const {
-    error: { throwBadInputError },
-    caseConverter: { keysToSnakeCase },
+  error: { throwBadInputError },
+  caseConverter: { keysToSnakeCase },
 } = require('@carecard/common-util');
 
 const { validateProperties } = require('./validateProperties');
@@ -27,7 +27,7 @@ const VALID_FLATTEN_KEY_STYLES = new Set(['path', 'leaf']);
  * @returns {boolean}
  */
 function isMixedCaseSegment(segment) {
-    return /_/.test(segment) && /[A-Z]/.test(segment);
+  return /_/.test(segment) && /[A-Z]/.test(segment);
 }
 
 /**
@@ -37,7 +37,7 @@ function isMixedCaseSegment(segment) {
  * @returns {string}
  */
 function snakeToCamel(s) {
-    return s.replace(/_([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+  return s.replace(/_([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
 }
 
 /**
@@ -47,7 +47,7 @@ function snakeToCamel(s) {
  * @returns {string}
  */
 function camelToSnake(s) {
-    return s.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+  return s.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
 }
 
 /**
@@ -59,9 +59,13 @@ function camelToSnake(s) {
  * @returns {string}
  */
 function alternateCase(segment) {
-    if (segment.indexOf('_') !== -1) return snakeToCamel(segment);
-    if (/[A-Z]/.test(segment)) return camelToSnake(segment);
-    return segment;
+  if (segment.indexOf('_') !== -1) {
+    return snakeToCamel(segment);
+  }
+  if (/[A-Z]/.test(segment)) {
+    return camelToSnake(segment);
+  }
+  return segment;
 }
 
 /**
@@ -71,20 +75,20 @@ function alternateCase(segment) {
  * @returns {string[]}
  */
 function splitPath(path) {
-    const segments = String(path).split('.');
-    if (segments.length > MAX_NESTING_DEPTH) {
-        throwBadInputError({
-            userMessage: `Property path "${path}" exceeds maximum nesting depth of ${MAX_NESTING_DEPTH}`,
-        });
-    }
-    for (const seg of segments) {
-        if (isMixedCaseSegment(seg)) {
-            throwBadInputError({
-                userMessage: `Property path "${path}" has a segment "${seg}" mixing snake_case and camelCase`,
-            });
-        }
+  const segments = String(path).split('.');
+  if (segments.length > MAX_NESTING_DEPTH) {
+    throwBadInputError({
+      userMessage: `Property path "${path}" exceeds maximum nesting depth of ${MAX_NESTING_DEPTH}`,
+    });
+  }
+  for (const seg of segments) {
+    if (isMixedCaseSegment(seg)) {
+      throwBadInputError({
+        userMessage: `Property path "${path}" has a segment "${seg}" mixing snake_case and camelCase`,
+      });
     }
-    return segments;
+  }
+  return segments;
 }
 
 /**
@@ -97,27 +101,39 @@ function splitPath(path) {
  * @returns {{ found: boolean, value: any }}
  */
 function readLeaf(obj, segments) {
-    // Resolve a segment against the current node, trying its as-written form
-    // first and then its alternate snake/camel form. Returns the actual key
-    // present in the node, or undefined if neither form exists.
-    function resolveKey(node, seg) {
-        if (Object.prototype.hasOwnProperty.call(node, seg)) return seg;
-        const alt = alternateCase(seg);
-        if (alt !== seg && Object.prototype.hasOwnProperty.call(node, alt)) return alt;
-        return undefined;
+  // Resolve a segment against the current node, trying its as-written form
+  // first and then its alternate snake/camel form. Returns the actual key
+  // present in the node, or undefined if neither form exists.
+  function resolveKey(node, seg) {
+    if (Object.prototype.hasOwnProperty.call(node, seg)) {
+      return seg;
+    }
+    const alt = alternateCase(seg);
+    if (alt !== seg && Object.prototype.hasOwnProperty.call(node, alt)) {
+      return alt;
     }
+    return undefined;
+  }
 
-    let current = obj;
-    for (let i = 0; i < segments.length - 1; i++) {
-        if (current === null || typeof current !== 'object') return { found: false, value: undefined };
-        const key = resolveKey(current, segments[i]);
-        if (key === undefined) return { found: false, value: undefined };
-        current = current[key];
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    if (current === null || typeof current !== 'object') {
+      return { found: false, value: undefined };
     }
-    if (current === null || typeof current !== 'object') return { found: false, value: undefined };
-    const leafKey = resolveKey(current, segments[segments.length - 1]);
-    if (leafKey === undefined) return { found: false, value: undefined };
-    return { found: true, value: current[leafKey] };
+    const key = resolveKey(current, segments[i]);
+    if (key === undefined) {
+      return { found: false, value: undefined };
+    }
+    current = current[key];
+  }
+  if (current === null || typeof current !== 'object') {
+    return { found: false, value: undefined };
+  }
+  const leafKey = resolveKey(current, segments[segments.length - 1]);
+  if (leafKey === undefined) {
+    return { found: false, value: undefined };
+  }
+  return { found: true, value: current[leafKey] };
 }
 
 /**
@@ -129,15 +145,15 @@ function readLeaf(obj, segments) {
  * @param {*} value
  */
 function writeLeaf(target, segments, value) {
-    let current = target;
-    for (let i = 0; i < segments.length - 1; i++) {
-        const key = segments[i];
-        if (current[key] === null || typeof current[key] !== 'object') {
-            current[key] = {};
-        }
-        current = current[key];
+  let current = target;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const key = segments[i];
+    if (current[key] === null || typeof current[key] !== 'object') {
+      current[key] = {};
     }
-    current[segments[segments.length - 1]] = value;
+    current = current[key];
+  }
+  current[segments[segments.length - 1]] = value;
 }
 
 /**
@@ -152,15 +168,20 @@ function writeLeaf(target, segments, value) {
  * @returns {Object}
  */
 function flattenObject(obj, prefix = '', out = {}) {
-    for (const [key, value] of Object.entries(obj)) {
-        const path = prefix ? `${prefix}.${key}` : key;
-        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
-            flattenObject(value, path, out);
-        } else {
-            out[path] = value;
-        }
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      !(value instanceof Date)
+    ) {
+      flattenObject(value, path, out);
+    } else {
+      out[path] = value;
     }
-    return out;
+  }
+  return out;
 }
 
 /**
@@ -179,17 +200,22 @@ function flattenObject(obj, prefix = '', out = {}) {
  * @returns {Object}
  */
 function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
-    for (const [key, value] of Object.entries(obj)) {
-        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
-            flattenObjectByLeafKey(value, out, depthByKey, depth + 1);
-        } else {
-            if (!Object.prototype.hasOwnProperty.call(out, key) || depth < depthByKey[key]) {
-                out[key] = value;
-                depthByKey[key] = depth;
-            }
-        }
+  for (const [key, value] of Object.entries(obj)) {
+    if (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      !(value instanceof Date)
+    ) {
+      flattenObjectByLeafKey(value, out, depthByKey, depth + 1);
+    } else {
+      if (!Object.prototype.hasOwnProperty.call(out, key) || depth < depthByKey[key]) {
+        out[key] = value;
+        depthByKey[key] = depth;
+      }
     }
-    return out;
+  }
+  return out;
 }
 
 /**
@@ -230,96 +256,110 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
  * @returns {Promise<Object>} Resolves with the validated (and possibly transformed) object.
  */
 function validateWhitelistProperties(
-    inputObject,
-    requiredProperties = [],
-    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false, flattenKeyStyle: DEFAULT_FLATTEN_KEY_STYLE },
+  inputObject,
+  requiredProperties = [],
+  options = {
+    optionalProperties: [],
+    convertToSnakeCase: false,
+    flattenOutput: false,
+    flattenKeyStyle: DEFAULT_FLATTEN_KEY_STYLE,
+  },
 ) {
-    const optionalProperties = (options && options.optionalProperties) || [];
-    const convertToSnakeCase = !!(options && options.convertToSnakeCase);
-    const flattenOutput = !!(options && options.flattenOutput);
-    const flattenKeyStyle = options && options.flattenKeyStyle !== undefined ? options.flattenKeyStyle : DEFAULT_FLATTEN_KEY_STYLE;
+  const optionalProperties = (options && options.optionalProperties) || [];
+  const convertToSnakeCase = !!(options && options.convertToSnakeCase);
+  const flattenOutput = !!(options && options.flattenOutput);
+  const flattenKeyStyle =
+    options && options.flattenKeyStyle !== undefined
+      ? options.flattenKeyStyle
+      : DEFAULT_FLATTEN_KEY_STYLE;
 
-    if (!VALID_FLATTEN_KEY_STYLES.has(flattenKeyStyle)) {
-        throwBadInputError({
-            userMessage: `Invalid flattenKeyStyle: ${String(flattenKeyStyle)}. Expected "path" or "leaf"`,
-        });
-    }
+  if (!VALID_FLATTEN_KEY_STYLES.has(flattenKeyStyle)) {
+    throwBadInputError({
+      userMessage: `Invalid flattenKeyStyle: ${String(flattenKeyStyle)}. Expected "path" or "leaf"`,
+    });
+  }
 
-    // Cap the total number of paths to validate per call.
-    const totalKeys = (requiredProperties ? requiredProperties.length : 0) + optionalProperties.length;
-    if (totalKeys > MAX_KEYS_PER_CALL) {
-        throwBadInputError({
-            userMessage: `Too many properties to validate: ${totalKeys} (maximum ${MAX_KEYS_PER_CALL})`,
-        });
-    }
+  // Cap the total number of paths to validate per call.
+  const totalKeys =
+    (requiredProperties ? requiredProperties.length : 0) + optionalProperties.length;
+  if (totalKeys > MAX_KEYS_PER_CALL) {
+    throwBadInputError({
+      userMessage: `Too many properties to validate: ${totalKeys} (maximum ${MAX_KEYS_PER_CALL})`,
+    });
+  }
 
-    const requiredPaths = (requiredProperties || []).map(p => ({ raw: p, segments: splitPath(p) }));
-    const optionalPaths = optionalProperties.map(p => ({ raw: p, segments: splitPath(p) }));
+  const requiredPaths = (requiredProperties || []).map(p => ({ raw: p, segments: splitPath(p) }));
+  const optionalPaths = optionalProperties.map(p => ({ raw: p, segments: splitPath(p) }));
 
-    let validatedObject = {};
+  let validatedObject = {};
 
-    // Helper: validate a single leaf value by feeding `{ [leafKey]: value }` to
-    // `validateProperties` and checking whether the leaf key survived.
-    //
-    // If `value` is an array, the same per-element validation is applied to
-    // every element; the result is an array of validated element values. The
-    // leaf is considered valid only when every element passes validation.
-    function validateLeafValue(leafKey, value) {
-        if (Array.isArray(value)) {
-            const validatedArray = [];
-            for (const element of value) {
-                const out = validateProperties({ [leafKey]: element });
-                if (!Object.prototype.hasOwnProperty.call(out, leafKey)) {
-                    return { valid: false, value: undefined };
-                }
-                validatedArray.push(out[leafKey]);
-            }
-            return { valid: true, value: validatedArray };
-        }
-        const out = validateProperties({ [leafKey]: value });
-        if (Object.prototype.hasOwnProperty.call(out, leafKey)) {
-            return { valid: true, value: out[leafKey] };
+  // Helper: validate a single leaf value by feeding `{ [leafKey]: value }` to
+  // `validateProperties` and checking whether the leaf key survived.
+  //
+  // If `value` is an array, the same per-element validation is applied to
+  // every element; the result is an array of validated element values. The
+  // leaf is considered valid only when every element passes validation.
+  function validateLeafValue(leafKey, value) {
+    if (Array.isArray(value)) {
+      const validatedArray = [];
+      for (const element of value) {
+        const out = validateProperties({ [leafKey]: element });
+        if (!Object.prototype.hasOwnProperty.call(out, leafKey)) {
+          return { valid: false, value: undefined };
         }
-        return { valid: false, value: undefined };
+        validatedArray.push(out[leafKey]);
+      }
+      return { valid: true, value: validatedArray };
     }
+    const out = validateProperties({ [leafKey]: value });
+    if (Object.prototype.hasOwnProperty.call(out, leafKey)) {
+      return { valid: true, value: out[leafKey] };
+    }
+    return { valid: false, value: undefined };
+  }
 
-    // 1 + 3. Required paths must exist and be valid.
-    requiredPaths.forEach(({ raw, segments }) => {
-        const { found, value } = readLeaf(inputObject, segments);
-        if (!found) {
-            throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
-        }
-        const leafKey = segments[segments.length - 1];
-        const { valid, value: validatedValue } = validateLeafValue(leafKey, value);
-        if (!valid) {
-            throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
-        }
-        writeLeaf(validatedObject, segments, validatedValue);
-    });
-
-    // 1 + 4. Optional paths: if provided, must be valid.
-    optionalPaths.forEach(({ raw, segments }) => {
-        const { found, value } = readLeaf(inputObject, segments);
-        if (!found) return;
-        const leafKey = segments[segments.length - 1];
-        const { valid, value: validatedValue } = validateLeafValue(leafKey, value);
-        if (!valid) {
-            throwBadInputError({ userMessage: `Invalid property value: ${raw}` });
-        }
-        writeLeaf(validatedObject, segments, validatedValue);
-    });
-
-    // 5. Optional case transformation (recursive, handles nested keys).
-    if (convertToSnakeCase) {
-        validatedObject = keysToSnakeCase(validatedObject);
+  // 1 + 3. Required paths must exist and be valid.
+  requiredPaths.forEach(({ raw, segments }) => {
+    const { found, value } = readLeaf(inputObject, segments);
+    if (!found) {
+      throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
+    }
+    const leafKey = segments[segments.length - 1];
+    const { valid, value: validatedValue } = validateLeafValue(leafKey, value);
+    if (!valid) {
+      throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
     }
+    writeLeaf(validatedObject, segments, validatedValue);
+  });
 
-    // 6. Optional flattening.
-    if (flattenOutput) {
-        validatedObject = flattenKeyStyle === 'leaf' ? flattenObjectByLeafKey(validatedObject) : flattenObject(validatedObject);
+  // 1 + 4. Optional paths: if provided, must be valid.
+  optionalPaths.forEach(({ raw, segments }) => {
+    const { found, value } = readLeaf(inputObject, segments);
+    if (!found) {
+      return;
     }
+    const leafKey = segments[segments.length - 1];
+    const { valid, value: validatedValue } = validateLeafValue(leafKey, value);
+    if (!valid) {
+      throwBadInputError({ userMessage: `Invalid property value: ${raw}` });
+    }
+    writeLeaf(validatedObject, segments, validatedValue);
+  });
+
+  // 5. Optional case transformation (recursive, handles nested keys).
+  if (convertToSnakeCase) {
+    validatedObject = keysToSnakeCase(validatedObject);
+  }
+
+  // 6. Optional flattening.
+  if (flattenOutput) {
+    validatedObject =
+      flattenKeyStyle === 'leaf'
+        ? flattenObjectByLeafKey(validatedObject)
+        : flattenObject(validatedObject);
+  }
 
-    return Promise.resolve(validatedObject);
+  return Promise.resolve(validatedObject);
 }
 
 module.exports = validateWhitelistProperties;

package/lint-staged.config.mjs

@@ -0,0 +1,36 @@
+import { ESLint } from 'eslint';
+
+const eslint = new ESLint();
+
+// Pattern: Pure Function - builds one deterministic command without shell interpolation.
+const createCommand = (command, filePaths) =>
+  `${command} ${filePaths.map(filePath => JSON.stringify(filePath)).join(' ')}`;
+
+// Pattern: Adapter - derives lint-staged input from ESLint's authoritative ignore rules.
+const removeEslintIgnoredFiles = async filePaths => {
+  const ignoredFileStates = await Promise.all(
+    filePaths.map(filePath => eslint.isPathIgnored(filePath)),
+  );
+
+  return filePaths.flatMap((filePath, index) => (ignoredFileStates[index] ? [] : [filePath]));
+};
+
+// Pattern: Pipeline - preserves ESLint-before-Prettier ordering for staged code.
+const createJavaScriptTasks = async filePaths => {
+  const lintableFilePaths = await removeEslintIgnoredFiles(filePaths);
+  const tasks = [];
+
+  if (lintableFilePaths.length > 0) {
+    tasks.push(createCommand('eslint --fix --max-warnings 0', lintableFilePaths));
+  }
+
+  tasks.push(createCommand('prettier --write', filePaths));
+  return tasks;
+};
+
+const lintStagedConfig = {
+  '*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}': createJavaScriptTasks,
+  '*.{json,jsonc,md,mdx,css,scss,yaml,yml}': ['prettier --write'],
+};
+
+export default lintStagedConfig;

package/package.json

@@ -1,63 +1,69 @@
 {
-    "name": "@carecard/validate",
-    "version": "3.18.0",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
-    },
-    "description": "Validate data",
-    "main": "index.js",
-    "types": "index.d.ts",
-    "scripts": {
-        "test": "node scripts/runPackageTask.mjs test",
-        "test:order": "node --test scripts/testOrder/randomizeTestOrder.test.mjs scripts/testOrder/testOrderPolicy.test.mjs scripts/testParallel/runIndexedMochaTests.test.mjs scripts/testParallel/parallelTestPolicy.test.mjs scripts/packageTaskRunner.test.mjs",
-        "test:types": "node scripts/runPackageTask.mjs test:types",
-        "test:coverage": "node scripts/runPackageTask.mjs test:coverage",
-        "test:All": "node scripts/runPackageTask.mjs test:All",
-        "format": "prettier --write .",
-        "format:check": "prettier --check .",
-        "prepare": "husky",
-        "lint:fix": "eslint --fix",
-        "lint": "eslint"
-    },
-    "keywords": [
-        "validate",
-        "data"
+  "name": "@carecard/validate",
+  "version": "3.19.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
+  },
+  "description": "Validate data",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node scripts/runPackageTask.mjs test",
+    "test:order": "node --test scripts/testOrder/randomizeTestOrder.test.mjs scripts/testParallel/runIndexedMochaTests.test.mjs scripts/packageTaskRunner.test.mjs scripts/canonicalTestCommand.test.mjs",
+    "validate:audits": "node scripts/runPackageTask.mjs validate:audits",
+    "test:types": "node scripts/runPackageTask.mjs test:types",
+    "test:coverage": "node scripts/runPackageTask.mjs test:coverage",
+    "test:All": "node scripts/runPackageTask.mjs test:All",
+    "format": "prettier --write \"**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}\"",
+    "format:check": "prettier --check \"**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}\"",
+    "lint-staged": "lint-staged",
+    "prepare": "husky",
+    "lint:fix": "eslint . --fix --max-warnings 0",
+    "lint": "eslint . --max-warnings 0"
+  },
+  "keywords": [
+    "validate",
+    "data"
+  ],
+  "author": "CareCard team",
+  "license": "ISC",
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "@types/mocha": "10.0.10",
+    "@types/node": "25.9.3",
+    "@typescript-eslint/parser": "8.67.0",
+    "eslint": "9.39.5",
+    "globals": "17.7.0",
+    "husky": "9.1.7",
+    "lint-staged": "17.2.0",
+    "mocha": "11.7.6",
+    "nyc": "18.0.0",
+    "prettier": "3.9.6",
+    "ts-node": "10.9.2",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "@carecard/common-util": "3.18.0"
+  },
+  "nyc": {
+    "all": true,
+    "include": [
+      "index.js",
+      "lib/**/*.js"
     ],
-    "author": "CareCard team",
-    "license": "ISC",
-    "devDependencies": {
-        "@types/mocha": "10.0.10",
-        "@types/node": "25.9.3",
-        "eslint": "9.39.4",
-        "husky": "9.1.7",
-        "lint-staged": "17.0.7",
-        "mocha": "11.7.6",
-        "nyc": "18.0.0",
-        "prettier": "3.8.4",
-        "ts-node": "10.9.2",
-        "typescript": "6.0.3"
-    },
-    "dependencies": {
-        "@carecard/common-util": "3.18.0"
-    },
-    "nyc": {
-        "all": true,
-        "include": [
-            "index.js",
-            "lib/**/*.js"
-        ],
-        "check-coverage": true,
-        "branches": 100,
-        "functions": 100,
-        "lines": 100,
-        "statements": 100
-    },
-    "overrides": {
-        "diff": "8.0.4",
-        "glob": "13.0.6",
-        "minimatch": "10.2.5",
-        "serialize-javascript": "7.0.5",
-        "js-yaml": "4.3.0"
-    }
+    "check-coverage": true,
+    "branches": 100,
+    "functions": 100,
+    "lines": 100,
+    "statements": 100
+  },
+  "overrides": {
+    "brace-expansion": "5.0.9",
+    "diff": "8.0.4",
+    "glob": "13.0.6",
+    "minimatch": "10.2.6",
+    "serialize-javascript": "7.0.5",
+    "js-yaml": "4.3.1"
+  }
 }

package/readme.md

@@ -15,7 +15,9 @@ not pass validation.
 
 ## Development Rule
 
-Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
+Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, run the relevant focused non-test
+validation before changing the prose; do not add automated tests that inspect
+prose, files, or repository structure.
 
 Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
 
@@ -416,3 +418,22 @@ immediately when no helper remains, allow only a bounded 250 ms settlement
 window for already-stopping helpers, fail persistent descendants, preserve
 failures and output, use exit code `124` only for a real outer deadline, and
 remain a final guard rather than a substitute for explicit cleanup.
+
+## TDD And Validation
+
+Test Driven Development is a non-negotiable requirement.
+
+The sole purpose of automated tests is to verify observable functionality and externally visible behavior.
+Tests must validate what the system does through its public interfaces and expected outcomes.
+
+Tests must not assert, inspect, or depend on implementation details, including but not limited to:
+
+- The existence of specific lines of code, statements, functions, classes, files, or modules.
+- Specific algorithms, control flow, variable names, method calls, code snippets, or internal implementation choices.
+- Any internal structure that can change without changing externally observable behavior.
+
+A correct implementation may be completely rewritten or refactored without requiring changes to functional tests, provided its externally observable behavior remains unchanged.
+
+Any test that fails solely because the implementation changed while the externally observable behavior remained correct is incorrectly designed and must be rewritten or removed.
+
+This requirement is mandatory for all new tests and must be applied whenever existing tests are modified.

package/scripts/canonicalTestCommand.test.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { runPackageTask } from './runPackageTask.mjs';
+
+test('the complete test command runs each validation category exactly once', () => {
+  const executedSteps = [];
+
+  const exitCode = runPackageTask('test', taskStep => {
+    executedSteps.push([taskStep.command, ...(taskStep.arguments ?? [])].join(' '));
+    return 0;
+  });
+
+  assert.equal(exitCode, 0);
+  assert.deepEqual(executedSteps, [
+    'npm run validate:audits',
+    'npm run test:order',
+    'tsc --noEmit',
+    'nyc node test/index.test.js',
+  ]);
+});
+
+test('the legacy aggregate command delegates to the complete test command once', () => {
+  const executedSteps = [];
+
+  runPackageTask('test:All', taskStep => {
+    executedSteps.push([taskStep.command, ...(taskStep.arguments ?? [])].join(' '));
+    return 0;
+  });
+
+  assert.deepEqual(executedSteps, ['npm test']);
+});