com.wallstop-studios.dxmessaging 2.1.5 → 2.1.7

package/scripts/__tests__/validate-workflows.test.js

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Tests for validate-workflows.js logic.
+ *
+ * These tests validate the core detection logic for problematic
+ * git add --renormalize patterns in GitHub Actions workflows.
+ */
+
+"use strict";
+
+const {
+    isForbiddenRenormalizePattern,
+    hasExistenceCheck,
+} = require('../validate-workflows.js');
+
+describe("isForbiddenRenormalizePattern", () => {
+    describe("should detect FORBIDDEN patterns", () => {
+        test("single line with multiple distinct extensions", () => {
+            const line =
+                "git add --renormalize -- '*.md' '**/*.md' '*.json' '**/*.json'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(true);
+        });
+
+        test("single line with three extensions", () => {
+            const line =
+                "git add --renormalize -- '*.md' '*.json' '*.yml'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(true);
+        });
+
+        test("double-quoted patterns", () => {
+            const line =
+                'git add --renormalize -- "*.md" "**/*.md" "*.json" "**/*.json"';
+            expect(isForbiddenRenormalizePattern(line)).toBe(true);
+        });
+
+        test("mixed quote styles", () => {
+            const line =
+                "git add --renormalize -- '*.cs' \"*.md\"";
+            expect(isForbiddenRenormalizePattern(line)).toBe(true);
+        });
+
+        test("indented in workflow file", () => {
+            const line =
+                "          git add --renormalize -- '*.md' '*.json' '*.yml'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(true);
+        });
+    });
+
+    describe("should ALLOW safe patterns", () => {
+        test("single extension with recursive pattern", () => {
+            const line = "git add --renormalize -- '*.md' '**/*.md'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("variable-based pattern in loop", () => {
+            const line = 'git add --renormalize -- "*.$ext" "**/*.$ext"';
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("variable-based pattern with braces", () => {
+            const line = 'git add --renormalize -- "*.${ext}" "**/*.${ext}"';
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("single specific file", () => {
+            const line =
+                "git add --renormalize -- '.config/dotnet-tools.json'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("line without git add", () => {
+            const line = "echo 'renormalize'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("line without renormalize", () => {
+            const line = "git add -- '*.md' '*.json'";
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("add_options: --renormalize (YAML key)", () => {
+            const line = "add_options: --renormalize";
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+
+        test("comment describing renormalize", () => {
+            const line =
+                "# Use --renormalize to ensure line endings";
+            expect(isForbiddenRenormalizePattern(line)).toBe(false);
+        });
+    });
+});
+
+describe("hasExistenceCheck", () => {
+    describe("should detect proper guards", () => {
+        test("if statement with git ls-files and grep", () => {
+            const lines = [
+                "for ext in cs md json; do",
+                '  if git ls-files "*.$ext" "**/*.$ext" | grep -q .; then',
+                '    git add --renormalize -- "*.$ext" "**/*.$ext"',
+                "  fi",
+                "done",
+            ];
+            expect(hasExistenceCheck(lines, 2)).toBe(true);
+        });
+
+        test("for loop with existence check", () => {
+            const lines = [
+                "for ext in cs md json asmdef yml yaml; do",
+                '  if git ls-files "*.$ext" "**/*.$ext" | grep -q .; then',
+                '    git add --renormalize -- "*.$ext" "**/*.$ext"',
+                "  fi",
+                "done",
+            ];
+            expect(hasExistenceCheck(lines, 2)).toBe(true);
+        });
+    });
+
+    describe("should detect missing guards", () => {
+        test("direct command without check", () => {
+            const lines = [
+                "- name: Renormalize line endings",
+                "  run: |",
+                "    git add --renormalize -- '*.md' '**/*.md'",
+            ];
+            expect(hasExistenceCheck(lines, 2)).toBe(false);
+        });
+
+        test("guard too far away", () => {
+            const lines = [
+                'if git ls-files "*.md" | grep -q .; then',
+                "  echo 'files exist'",
+                "fi",
+                "",
+                "",
+                "",
+                "",
+                "git add --renormalize -- '*.md' '**/*.md'",
+            ];
+            // Index 7, lookback 5 won't reach index 0
+            expect(hasExistenceCheck(lines, 7)).toBe(false);
+        });
+    });
+});
+
+describe("Real workflow patterns", () => {
+    describe("should correctly handle actual workflow content", () => {
+        test("correct per-extension loop pattern", () => {
+            const workflowContent = `
+      - name: Renormalize line endings
+        shell: bash
+        run: |
+          # Renormalize each extension separately to avoid "pathspec did not match" failures
+          for ext in cs md json asmdef yml yaml; do
+            if git ls-files "*.$ext" "**/*.$ext" | grep -q .; then
+              git add --renormalize -- "*.$ext" "**/*.$ext"
+            fi
+          done
+`;
+            const lines = workflowContent.split("\n");
+            const renormalizeLine = lines.findIndex((l) =>
+                l.includes("git add --renormalize")
+            );
+
+            // Should NOT be forbidden (uses variable)
+            expect(isForbiddenRenormalizePattern(lines[renormalizeLine])).toBe(
+                false
+            );
+            // Should have existence check
+            expect(hasExistenceCheck(lines, renormalizeLine)).toBe(true);
+        });
+
+        test("problematic single-line pattern", () => {
+            const workflowContent = `
+      - name: Renormalize line endings
+        run: git add --renormalize -- '*.md' '*.markdown' '*.json'
+`;
+            const lines = workflowContent.split("\n");
+            const renormalizeLine = lines.findIndex((l) =>
+                l.includes("git add --renormalize")
+            );
+
+            // Should BE forbidden (multiple extensions on single line)
+            expect(isForbiddenRenormalizePattern(lines[renormalizeLine])).toBe(
+                true
+            );
+        });
+    });
+});

package/scripts/__tests__/validate-workflows.test.js.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: cfde2601b3671e813b015ff9eddfb824
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/scripts/generate-skills-index.js

@@ -33,6 +33,79 @@ const EXCLUDED_DIRS = ["templates"];
 const REPO_ROOT = path.join(__dirname, "..");
 const PRETTIER_VERSION = "3.8.1";
 
+/**
+ * Brand name capitalization mapping.
+ * Maps lowercase words to their properly capitalized forms.
+ */
+const BRAND_NAMES = {
+    github: "GitHub",
+    javascript: "JavaScript",
+    typescript: "TypeScript",
+    nodejs: "Node.js",
+    csharp: "C#",
+    dotnet: ".NET",
+    nuget: "NuGet",
+    npm: "npm",
+    api: "API",
+    apis: "APIs",
+    cli: "CLI",
+    json: "JSON",
+    yaml: "YAML",
+    xml: "XML",
+    html: "HTML",
+    css: "CSS",
+    sql: "SQL",
+    url: "URL",
+    urls: "URLs",
+    uri: "URI",
+    uris: "URIs",
+    http: "HTTP",
+    https: "HTTPS",
+    rest: "REST",
+    graphql: "GraphQL",
+    oauth: "OAuth",
+    jwt: "JWT",
+    sdk: "SDK",
+    ide: "IDE",
+    vscode: "VS Code",
+    visualstudio: "Visual Studio",
+    macos: "macOS",
+    ios: "iOS",
+    webgl: "WebGL",
+    opengl: "OpenGL",
+    directx: "DirectX",
+    llm: "LLM",
+    ai: "AI",
+    ml: "ML",
+    ci: "CI",
+    cd: "CD",
+};
+
+/**
+ * Apply proper brand name capitalization to a word.
+ * Returns the properly capitalized form if it's a known brand,
+ * otherwise returns the word with standard title case.
+ */
+function applyBrandCapitalization(word) {
+    const lowerWord = word.toLowerCase();
+    if (BRAND_NAMES[lowerWord]) {
+        return BRAND_NAMES[lowerWord];
+    }
+    // Standard title case: capitalize first letter
+    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+
+/**
+ * Convert a category slug (e.g., "github-actions") to a properly
+ * capitalized title (e.g., "GitHub Actions").
+ */
+function categoryToTitle(category) {
+    return category
+        .split("-")
+        .map((word) => applyBrandCapitalization(word))
+        .join(" ");
+}
+
 function normalizeToCrlf(text) {
     let normalized = text.replace(/\r\n/g, "\n");
     normalized = normalized.replace(/\r/g, "\n");
@@ -369,7 +442,7 @@ function generateIndex(skills) {
 `;
 
     for (const cat of sortedCategories) {
-        const catTitle = cat.charAt(0).toUpperCase() + cat.slice(1).replace(/-/g, " ");
+        const catTitle = categoryToTitle(cat);
         content += `- [${catTitle}](#${cat}) (${byCategory[cat].length})\n`;
     }
 
@@ -380,7 +453,7 @@ function generateIndex(skills) {
 
     // Category sections
     for (const cat of sortedCategories) {
-        const catTitle = cat.charAt(0).toUpperCase() + cat.slice(1).replace(/-/g, " ");
+        const catTitle = categoryToTitle(cat);
         content += `## ${catTitle}\n\n`;
 
         content += `| Skill | Lines | Complexity | Status | Performance | Tags |\n`;
@@ -509,4 +582,16 @@ function main() {
     return 0;
 }
 
-process.exit(main());
+// Export for testing when required as a module
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        applyBrandCapitalization,
+        categoryToTitle,
+        BRAND_NAMES,
+    };
+}
+
+// Only run main when executed directly (not when required as a module)
+if (require.main === module) {
+    process.exit(main());
+}

package/scripts/validate-skills.js

@@ -35,6 +35,7 @@ const EXCLUDED_DIRS = ['templates'];
 // Files excluded from "short file" informational messages
 const SHORT_FILE_EXCLUDES = ['context.md'];
 
+// Required fields that must be present in all skill files
 const REQUIRED_FIELDS = ['title', 'id', 'category', 'version', 'created', 'updated', 'status'];
 
 // File size limits (in lines)
@@ -54,6 +55,7 @@ const VALID_CATEGORIES = [
     'code-generation',
     'documentation',
     'scripting',
+    'github-actions',
 ];
 
 const VALID_COMPLEXITY_LEVELS = ['basic', 'intermediate', 'advanced', 'expert'];
@@ -73,6 +75,127 @@ class ValidationError {
     }
 }
 
+/**
+ * Validates a single required field of a frontmatter object.
+ *
+ * @param {Object} frontmatter - The parsed frontmatter object
+ * @param {string} field - The field name to validate
+ * @param {string} relativePath - The relative path for error reporting
+ * @returns {ValidationError[]} Array of validation errors
+ */
+function validateRequiredField(frontmatter, field, relativePath) {
+    const errors = [];
+
+    if (frontmatter[field] === undefined || frontmatter[field] === null) {
+        errors.push(new ValidationError(relativePath, field, `Required field '${field}' is missing`));
+    } else if (frontmatter[field] === '') {
+        errors.push(new ValidationError(relativePath, field, `Required field '${field}' is empty`));
+    }
+
+    return errors;
+}
+
+/**
+ * Validates the tags field of a frontmatter object.
+ *
+ * @param {Object} frontmatter - The parsed frontmatter object
+ * @param {string} relativePath - The relative path for error reporting
+ * @returns {ValidationError[]} Array of validation warnings
+ */
+function validateTags(frontmatter, relativePath) {
+    const warnings = [];
+
+    if (frontmatter.tags === undefined || frontmatter.tags === null) {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'tags',
+                `Missing 'tags' array - will show empty Tags column in skills index`
+            )
+        );
+    } else if (!Array.isArray(frontmatter.tags)) {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'tags',
+                `'tags' must be an array, got ${typeof frontmatter.tags} - will show empty Tags column in skills index`
+            )
+        );
+    } else if (frontmatter.tags.length === 0) {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'tags',
+                `Empty 'tags' array - will show empty Tags column in skills index`
+            )
+        );
+    }
+
+    return warnings;
+}
+
+/**
+ * Validates the complexity.level field of a frontmatter object.
+ *
+ * @param {Object} frontmatter - The parsed frontmatter object
+ * @param {string} relativePath - The relative path for error reporting
+ * @returns {ValidationError[]} Array of validation warnings
+ */
+function validateComplexityLevel(frontmatter, relativePath) {
+    const warnings = [];
+
+    if (frontmatter.complexity == null || frontmatter.complexity.level == null) {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'complexity.level',
+                `Missing 'complexity.level' - will show '?' in Complexity column of skills index`
+            )
+        );
+    } else if (frontmatter.complexity.level === '') {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'complexity.level',
+                `Empty 'complexity.level' - will show '?' in Complexity column of skills index`
+            )
+        );
+    }
+
+    return warnings;
+}
+
+/**
+ * Validates the impact.performance.rating field of a frontmatter object.
+ *
+ * @param {Object} frontmatter - The parsed frontmatter object
+ * @param {string} relativePath - The relative path for error reporting
+ * @returns {ValidationError[]} Array of validation warnings
+ */
+function validatePerformanceRating(frontmatter, relativePath) {
+    const warnings = [];
+
+    if (frontmatter.impact == null || frontmatter.impact.performance == null || frontmatter.impact.performance.rating == null) {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'impact.performance.rating',
+                `Missing 'impact.performance.rating' - will show '?' in Performance column of skills index`
+            )
+        );
+    } else if (frontmatter.impact.performance.rating === '') {
+        warnings.push(
+            new ValidationError(
+                relativePath,
+                'impact.performance.rating',
+                `Empty 'impact.performance.rating' - will show '?' in Performance column of skills index`
+            )
+        );
+    }
+
+    return warnings;
+}
+
 /**
  * Parse YAML frontmatter from markdown file content.
  * Uses a stack-based approach to handle arbitrary nesting depth.
@@ -216,6 +339,33 @@ function findSkillFiles(dir) {
     return skills;
 }
 
+/**
+ * Validates that impact is present and is an object (not a primitive or array).
+ *
+ * @param {Object} frontmatter - The parsed frontmatter object
+ * @returns {boolean} True if impact is a valid object to iterate over
+ */
+function isValidImpactObject(frontmatter) {
+    return frontmatter.impact != null && typeof frontmatter.impact === 'object' && !Array.isArray(frontmatter.impact);
+}
+
+/**
+ * Validates all required fields of a frontmatter object.
+ *
+ * @param {Object} frontmatter - The parsed frontmatter object
+ * @param {string} relativePath - The relative path for error reporting
+ * @returns {ValidationError[]} Array of validation errors
+ */
+function validateRequiredFields(frontmatter, relativePath) {
+    const errors = [];
+
+    for (const field of REQUIRED_FIELDS) {
+        errors.push(...validateRequiredField(frontmatter, field, relativePath));
+    }
+
+    return errors;
+}
+
 /**
  * Validate a single skill file.
  * Returns validation results with errors, warnings, and line count.
@@ -269,14 +419,10 @@ function validateSkill(skillFile) {
     }
 
     // Check required fields
-    for (const field of REQUIRED_FIELDS) {
-        if (!frontmatter[field]) {
-            errors.push(new ValidationError(skillFile.relativePath, field, `Required field '${field}' is missing`));
-        }
-    }
+    errors.push(...validateRequiredFields(frontmatter, skillFile.relativePath));
 
     // Validate id matches filename
-    if (frontmatter.id && frontmatter.id !== skillFile.expectedId) {
+    if (frontmatter.id != null && frontmatter.id !== '' && frontmatter.id !== skillFile.expectedId) {
         errors.push(
             new ValidationError(
                 skillFile.relativePath,
@@ -287,7 +433,7 @@ function validateSkill(skillFile) {
     }
 
     // Validate category matches folder
-    if (frontmatter.category && frontmatter.category !== skillFile.category) {
+    if (frontmatter.category != null && frontmatter.category !== '' && frontmatter.category !== skillFile.category) {
         errors.push(
             new ValidationError(
                 skillFile.relativePath,
@@ -298,7 +444,7 @@ function validateSkill(skillFile) {
     }
 
     // Validate category is known
-    if (frontmatter.category && !VALID_CATEGORIES.includes(frontmatter.category)) {
+    if (frontmatter.category != null && frontmatter.category !== '' && !VALID_CATEGORIES.includes(frontmatter.category)) {
         warnings.push(
             new ValidationError(
                 skillFile.relativePath,
@@ -309,7 +455,7 @@ function validateSkill(skillFile) {
     }
 
     // Validate status
-    if (frontmatter.status && !VALID_STATUSES.includes(frontmatter.status)) {
+    if (frontmatter.status != null && frontmatter.status !== '' && !VALID_STATUSES.includes(frontmatter.status)) {
         errors.push(
             new ValidationError(
                 skillFile.relativePath,
@@ -321,8 +467,9 @@ function validateSkill(skillFile) {
 
     // Validate complexity level
     if (
-        frontmatter.complexity &&
-        frontmatter.complexity.level &&
+        frontmatter.complexity != null &&
+        frontmatter.complexity.level != null &&
+        frontmatter.complexity.level !== '' &&
         !VALID_COMPLEXITY_LEVELS.includes(frontmatter.complexity.level)
     ) {
         warnings.push(
@@ -335,7 +482,7 @@ function validateSkill(skillFile) {
     }
 
     // Validate impact ratings
-    if (frontmatter.impact) {
+    if (isValidImpactObject(frontmatter)) {
         // Warn about unknown impact types
         for (const impactType of Object.keys(frontmatter.impact)) {
             if (!VALID_IMPACT_TYPES.includes(impactType)) {
@@ -351,8 +498,9 @@ function validateSkill(skillFile) {
         // Validate ratings for known impact types
         for (const impactType of VALID_IMPACT_TYPES) {
             if (
-                frontmatter.impact[impactType] &&
-                frontmatter.impact[impactType].rating &&
+                frontmatter.impact[impactType] != null &&
+                frontmatter.impact[impactType].rating != null &&
+                frontmatter.impact[impactType].rating !== '' &&
                 !VALID_IMPACT_RATINGS.includes(frontmatter.impact[impactType].rating)
             ) {
                 warnings.push(
@@ -367,29 +515,43 @@ function validateSkill(skillFile) {
     }
 
     // Validate version format (semver-like)
-    if (frontmatter.version && !frontmatter.version.match(/^\d+\.\d+\.\d+$/)) {
-        warnings.push(
-            new ValidationError(
-                skillFile.relativePath,
-                'version',
-                `Version '${frontmatter.version}' should be in semver format (e.g., 1.0.0)`
-            )
-        );
-    }
-
-    // Validate date format
-    for (const dateField of ['created', 'updated']) {
-        if (frontmatter[dateField] && !frontmatter[dateField].match(/^\d{4}-\d{2}-\d{2}$/)) {
+    if (frontmatter.version != null && frontmatter.version !== '') {
+        // Coerce to string to handle numeric or other non-string types
+        const versionStr = String(frontmatter.version);
+        if (!versionStr.match(/^\d+\.\d+\.\d+$/)) {
             warnings.push(
                 new ValidationError(
                     skillFile.relativePath,
-                    dateField,
-                    `Date '${frontmatter[dateField]}' should be in ISO format (YYYY-MM-DD)`
+                    'version',
+                    `Version '${versionStr}' should be in semver format (e.g., 1.0.0)`
                 )
             );
         }
     }
 
+    // Warn about missing optional fields that affect skills index display
+    // These are not required but cause '?' placeholders in the generated index
+    warnings.push(...validateComplexityLevel(frontmatter, skillFile.relativePath));
+    warnings.push(...validatePerformanceRating(frontmatter, skillFile.relativePath));
+    warnings.push(...validateTags(frontmatter, skillFile.relativePath));
+
+    // Validate date format
+    for (const dateField of ['created', 'updated']) {
+        if (frontmatter[dateField] != null && frontmatter[dateField] !== '') {
+            // Coerce to string to handle numeric or other non-string types
+            const dateStr = String(frontmatter[dateField]);
+            if (!dateStr.match(/^\d{4}-\d{2}-\d{2}$/)) {
+                warnings.push(
+                    new ValidationError(
+                        skillFile.relativePath,
+                        dateField,
+                        `Date '${dateStr}' should be in ISO format (YYYY-MM-DD)`
+                    )
+                );
+            }
+        }
+    }
+
     // Check for required sections in body
     const requiredSections = ['## Overview', '## Solution'];
     for (const section of requiredSections) {
@@ -554,4 +716,42 @@ function main() {
     return 0;
 }
 
-process.exit(main());
+/**
+ * @module validate-skills
+ * @description Validates skill files in .llm/skills/ for frontmatter correctness, naming conventions,
+ * size limits, and cross-references. Used by pre-commit hooks and CI pipelines.
+ *
+ * @exports {Function} validateSkill - Validates a single skill file, returning errors and warnings
+ * @exports {Function} parseFrontmatter - Extracts YAML frontmatter from markdown content
+ * @exports {Function} validateRequiredField - Validates a single required frontmatter field
+ * @exports {Function} validateRequiredFields - Validates all required frontmatter fields
+ * @exports {Function} validateTags - Validates the tags array in frontmatter
+ * @exports {Function} validateComplexityLevel - Validates the complexity.level field
+ * @exports {Function} validatePerformanceRating - Validates presence of impact.performance.rating field
+ * @exports {Function} isValidImpactObject - Checks if impact field is a non-null object (excludes arrays)
+ * @exports {Class} ValidationError - Error class with file, field, and message properties
+ * @exports {Array<string>} REQUIRED_FIELDS - List of required frontmatter field names
+ * @exports {Array<string>} VALID_COMPLEXITY_LEVELS - Valid values: 'basic', 'intermediate', 'advanced', 'expert'
+ * @exports {Array<string>} VALID_IMPACT_RATINGS - Valid rating values: 'none', 'low', 'medium', 'high', 'critical'
+ */
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        validateSkill,
+        parseFrontmatter,
+        ValidationError,
+        REQUIRED_FIELDS,
+        VALID_COMPLEXITY_LEVELS,
+        VALID_IMPACT_RATINGS,
+        validateRequiredField,
+        validateRequiredFields,
+        validateTags,
+        validateComplexityLevel,
+        validatePerformanceRating,
+        isValidImpactObject,
+    };
+}
+
+// Only run main when executed directly (not when required as a module)
+if (require.main === module) {
+    process.exit(main());
+}