com.wallstop-studios.dxmessaging 2.1.5 → 2.1.7

package/.llm/skills/index.md

@@ -1,6 +1,6 @@
 # Skills Index
 
-> **Auto-generated** on 2026-01-28. Do not edit manually.
+> **Auto-generated** on 2026-01-30. Do not edit manually.
 > Run `node scripts/generate-skills-index.js` to regenerate.
 
 ---
@@ -9,19 +9,20 @@
 
 | Metric       | Value |
 | ------------ | ----- |
-| Total Skills | 76    |
-| Categories   | 5     |
-| Unique Tags  | 139   |
+| Total Skills | 86    |
+| Categories   | 6     |
+| Unique Tags  | 162   |
 
 ---
 
 ## Table of Contents
 
-- [Documentation](#documentation) (12)
+- [Documentation](#documentation) (15)
+- [GitHub Actions](#github-actions) (2)
 - [Performance](#performance) (24)
-- [Scripting](#scripting) (3)
+- [Scripting](#scripting) (6)
 - [Solid](#solid) (13)
-- [Testing](#testing) (24)
+- [Testing](#testing) (26)
 - [Tag Cloud](#tag-cloud)
 - [All Skills by Complexity](#all-skills-by-complexity)
 
@@ -29,20 +30,30 @@
 
 ## Documentation
 
-| Skill                                                                                       | Lines  | Complexity | Status    | Performance | Tags                                      |
-| ------------------------------------------------------------------------------------------- | ------ | ---------- | --------- | ----------- | ----------------------------------------- |
-| [Changelog Entry Writing and Anti-Patterns](./documentation/changelog-entry-writing.md)     | ✅ 278 | 🟢 Basic   | ✅ Stable | ○○○○○       | changelog, release-notes, writing         |
-| [Changelog Management](./documentation/changelog-management.md)                             | 📝 191 | 🟢 Basic   | ✅ Stable | ○○○○○       | changelog, documentation, versioning      |
-| [Changelog Release Workflow](./documentation/changelog-release-workflow.md)                 | ✅ 250 | 🟢 Basic   | ✅ Stable | ○○○○○       | changelog, release-workflow, versioning   |
-| [Documentation Code Samples](./documentation/documentation-code-samples.md)                 | ✅ 263 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, code-samples, examples     |
-| [Documentation Style Guide](./documentation/documentation-style-guide.md)                   | 📝 186 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, style, writing             |
-| [Documentation Update Workflow](./documentation/documentation-update-workflow.md)           | 📝 147 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, workflow, checklist        |
-| [Documentation Updates and Maintenance](./documentation/documentation-updates.md)           | 📝 147 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, code-comments, xml-docs    |
-| [External URL Fragment Validation](./documentation/external-url-fragment-validation.md)     | 📝 182 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, links, urls                |
-| [GitHub Actions Version Consistency](./documentation/github-actions-version-consistency.md) | ✅ 204 | 🟢 Basic   | ✅ Stable | ○○○○○       | github-actions, ci-cd, version-management |
-| [Link Quality and External URL Management](./documentation/link-quality-guidelines.md)      | ✅ 268 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, links, urls                |
-| [Skill File Sizing Guidelines](./documentation/skill-file-sizing.md)                        | ✅ 261 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, skills, file-organization  |
-| [XML Documentation Standards](./documentation/documentation-xml-docs.md)                    | 📝 191 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, xml-docs, api-reference    |
+| Skill                                                                                       | Lines  | Complexity      | Status    | Performance | Tags                                      |
+| ------------------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | ----------------------------------------- |
+| [Changelog Entry Writing and Anti-Patterns](./documentation/changelog-entry-writing.md)     | ✅ 278 | 🟢 Basic        | ✅ Stable | ○○○○○       | changelog, release-notes, writing         |
+| [Changelog Management](./documentation/changelog-management.md)                             | ✅ 229 | 🟢 Basic        | ✅ Stable | ○○○○○       | changelog, documentation, versioning      |
+| [Changelog Release Workflow](./documentation/changelog-release-workflow.md)                 | ✅ 250 | 🟢 Basic        | ✅ Stable | ○○○○○       | changelog, release-workflow, versioning   |
+| [Documentation Code Samples](./documentation/documentation-code-samples.md)                 | ✅ 263 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, code-samples, examples     |
+| [Documentation Style Guide](./documentation/documentation-style-guide.md)                   | ✅ 204 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, style, writing             |
+| [Documentation Update Workflow](./documentation/documentation-update-workflow.md)           | 📝 149 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, workflow, checklist        |
+| [Documentation Updates and Maintenance](./documentation/documentation-updates.md)           | 📝 149 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, code-comments, xml-docs    |
+| [External URL Fragment Validation](./documentation/external-url-fragment-validation.md)     | 📝 182 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, links, urls                |
+| [GitHub Actions Version Consistency](./documentation/github-actions-version-consistency.md) | ✅ 204 | 🟢 Basic        | ✅ Stable | ○○○○○       | github-actions, ci-cd, version-management |
+| [Link Quality and External URL Management](./documentation/link-quality-guidelines.md)      | ✅ 268 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, links, urls                |
+| [Markdown Compatibility Guidelines](./documentation/markdown-compatibility.md)              | ⚠️ 477 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, markdown, compatibility    |
+| [Mermaid Diagram Theming](./documentation/mermaid-theming.md)                               | ✅ 327 | 🟡 Intermediate | ✅ Stable | ○○○○○       | documentation, mermaid, theming           |
+| [MkDocs Navigation Management](./documentation/mkdocs-navigation.md)                        | ✅ 291 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, mkdocs, navigation         |
+| [Skill File Sizing Guidelines](./documentation/skill-file-sizing.md)                        | ✅ 261 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, skills, file-organization  |
+| [XML Documentation Standards](./documentation/documentation-xml-docs.md)                    | 📝 191 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, xml-docs, api-reference    |
+
+## GitHub Actions
+
+| Skill                                                                              | Lines  | Complexity      | Status    | Performance | Tags                            |
+| ---------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | ------------------------------- |
+| [Git Renormalize Pattern Validation](./github-actions/git-renormalize-patterns.md) | ✅ 232 | 🟡 Intermediate | ✅ Stable | ●○○○○       | github-actions, git, ci-cd      |
+| [GitHub Actions Workflow Consistency](./github-actions/workflow-consistency.md)    | ✅ 347 | 🟡 Intermediate | ✅ Stable | ●●○○○       | github-actions, ci-cd, workflow |
 
 ## Performance
 
@@ -75,11 +86,14 @@
 
 ## Scripting
 
-| Skill                                                                              | Lines  | Complexity      | Status    | Performance | Tags                                      |
-| ---------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | ----------------------------------------- |
-| [Cross-Platform Script Compatibility](./scripting/cross-platform-compatibility.md) | ✅ 225 | 🟡 Intermediate | ✅ Stable | ○○○○○       | cross-platform, case-sensitivity, testing |
-| [PowerShell Scripting Best Practices](./scripting/powershell-best-practices.md)    | ⚠️ 387 | 🟡 Intermediate | ✅ Stable | ○○○○○       | powershell, scripting, regex              |
-| [Shell Scripting Best Practices](./scripting/shell-best-practices.md)              | ✅ 336 | 🟡 Intermediate | ✅ Stable | ○○○○○       | shell, bash, scripting                    |
+| Skill                                                                                      | Lines  | Complexity      | Status    | Performance | Tags                                      |
+| ------------------------------------------------------------------------------------------ | ------ | --------------- | --------- | ----------- | ----------------------------------------- |
+| [Cross-Platform Script Compatibility](./scripting/cross-platform-compatibility.md)         | ✅ 225 | 🟡 Intermediate | ✅ Stable | ○○○○○       | cross-platform, case-sensitivity, testing |
+| [JavaScript Code Quality Practices](./scripting/javascript-code-quality.md)                | ⚠️ 418 | 🟡 Intermediate | ✅ Stable | ○○○○○       | javascript, code-quality, linting         |
+| [PowerShell Scripting Best Practices](./scripting/powershell-best-practices.md)            | ⚠️ 387 | 🟡 Intermediate | ✅ Stable | ○○○○○       | powershell, scripting, regex              |
+| [Regex Pattern Documentation](./scripting/regex-documentation.md)                          | ⚠️ 462 | 🟡 Intermediate | ✅ Stable | ○○○○○       | regex, documentation, scripting           |
+| [Shell Scripting Best Practices](./scripting/shell-best-practices.md)                      | ⚠️ 387 | 🟡 Intermediate | ✅ Stable | ○○○○○       | shell, bash, scripting                    |
+| [Validation Patterns and Duplicate Warning Prevention](./scripting/validation-patterns.md) | ⚠️ 419 | 🟡 Intermediate | ✅ Stable | ○○○○○       | validation, javascript, error-handling    |
 
 ## Solid
 
@@ -117,6 +131,7 @@
 | [Test Base Class with Automatic Resource Cleanup](./testing/test-base-class-cleanup.md)           | ✅ 324 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, cleanup, lifecycle                 |
 | [Test Categories for Selective Execution](./testing/test-categories.md)                           | ✅ 288 | 🟢 Basic        | ✅ Stable | ●●●○○       | testing, organization, categories           |
 | [Test Category Execution](./testing/test-categories-execution.md)                                 | 📝 143 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, organization, categories           |
+| [Test Code Quality and Accuracy](./testing/test-code-quality.md)                                  | ✅ 244 | 🟡 Intermediate | ✅ Stable | ●●○○○       | testing, documentation, linting             |
 | [Test Coverage Scenario Categories](./testing/test-coverage-scenario-categories.md)               | ✅ 224 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, coverage, edge-cases               |
 | [Test Diagnostics and Investigation Patterns](./testing/test-diagnostics.md)                      | ✅ 248 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, diagnostics, debugging             |
 | [Test Diagnostics Patterns](./testing/test-diagnostics-patterns.md)                               | 📝 190 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, diagnostics, logging               |
@@ -126,13 +141,14 @@
 | [Test Failure Root Causes and Anti-Patterns](./testing/test-failure-investigation-root-causes.md) | 📝 187 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, root-cause-analysis, anti-patterns |
 | [Test Invalid Skill](./testing/test-invalid-skill.md)                                             | 📝 27  | 🔴 Expert       | ✅ Stable | ●●●○○       |                                             |
 | [Test Organization and Assertions](./testing/test-coverage-organization-assertions.md)            | 📝 172 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, assertions, naming                 |
+| [Test Production Code Directly](./testing/test-production-code.md)                                | ✅ 349 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, anti-patterns, code-quality        |
 | [Unity Test Considerations and Anti-Patterns](./testing/test-coverage-unity-anti-patterns.md)     | ✅ 233 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, unity, anti-patterns               |
 
 ---
 
 ## Tag Cloud
 
-`testing`×26 `performance`×15 `unity`×13 `documentation`×10 `solid`×10 `memory`×9 `patterns`×9 `pooling`×9 `allocation`×8 `ci-cd`×8 `nunit`×8 `zero-alloc`×7 `collections`×5 `data-driven`×5 `debugging`×5 `singleton`×5 `struct`×5 `anti-patterns`×4 `builder`×4 `coverage`×4 `dictionary`×4 `fixtures`×4 `versioning`×4 `api-design`×3 `caching`×3 `changelog`×3 `defensive`×3 `diagnostics`×3 `equality`×3 `extensions`×3 `fluent-api`×3 `inspector`×3 `investigation`×3 `keep-a-changelog`×3 `linting`×3 `logging`×3 `markdown`×3 `messaging`×3 `organization`×3 `parameterized`×3 `powershell`×3 `quality`×3 `reference-counting`×3 `serialization`×3 `try-pattern`×3 `api-reference`×2 `arrays`×2 `benchmark`×2 `case-sensitivity`×2 `categories`×2 `ci`×2 `cleanup`×2 `code-comments`×2 `code-samples`×2 `data-structures`×2 `edge-cases`×2 `error-handling`×2 `eviction`×2 `examples`×2 `github-actions`×2 `hashcode`×2 `hot-path`×2 `iequatable`×2 `inlining`×2 `javascript`×2 `lfu`×2 `lifecycle`×2 `links`×2 `linux`×2 `lru`×2 `optimization`×2 `release-notes`×2 `root-cause-analysis`×2 `scripting`×2 `urls`×2 `user-communication`×2 `workflows`×2 `writing`×2 `xml-docs`×2 `accessibility`×1 `accuracy`×1 `architecture`×1 `arraypool`×1 `assertions`×1 `automation`×1 `bash`×1 `best-practices`×1 `boxing`×1 `buffers`×1 `checklist`×1 `clarity`×1 `configuration`×1 `coroutines`×1 `cross-platform`×1 `disposable`×1 `dry`×1 `encoding`×1 `file-organization`×1 `fisher-yates`×1 `flaky-tests`×1 `fragments`×1 `garbage-collection`×1 `generic`×1 `git`×1 `here-strings`×1 `implementation`×1 `jest`×1 `llm-context`×1 `macos`×1 `maintainability`×1 `maintenance`×1 `methodimpl`×1 `naming`×1 `negative-tests`×1 `parsing`×1 `pre-commit`×1 `procedure`×1 `raii`×1 `regex`×1 `release-workflow`×1 `scriptable-object`×1 `scripts`×1 `semantic-versioning`×1 `shared-state`×1 `shell`×1 `shuffle`×1 `skills`×1 `stringbuilder`×1 `strings`×1 `style`×1 `test-cases`×1 `thread-safety`×1 `type-specialization`×1 `validation`×1 `version-management`×1 `windows`×1 `workflow`×1 `yield`×1 `zero-flaky`×1
+`testing`×30 `documentation`×16 `performance`×15 `unity`×13 `ci-cd`×10 `patterns`×10 `solid`×10 `memory`×9 `pooling`×9 `allocation`×8 `nunit`×8 `zero-alloc`×7 `javascript`×6 `anti-patterns`×5 `collections`×5 `data-driven`×5 `debugging`×5 `linting`×5 `singleton`×5 `struct`×5 `builder`×4 `coverage`×4 `dictionary`×4 `fixtures`×4 `github-actions`×4 `markdown`×4 `versioning`×4 `api-design`×3 `caching`×3 `changelog`×3 `code-quality`×3 `defensive`×3 `diagnostics`×3 `equality`×3 `error-handling`×3 `extensions`×3 `fluent-api`×3 `inspector`×3 `investigation`×3 `keep-a-changelog`×3 `logging`×3 `messaging`×3 `mkdocs`×3 `organization`×3 `parameterized`×3 `powershell`×3 `quality`×3 `reference-counting`×3 `scripting`×3 `serialization`×3 `try-pattern`×3 `api-reference`×2 `arrays`×2 `benchmark`×2 `best-practices`×2 `case-sensitivity`×2 `categories`×2 `ci`×2 `cleanup`×2 `code-comments`×2 `code-samples`×2 `data-structures`×2 `edge-cases`×2 `eviction`×2 `examples`×2 `git`×2 `hashcode`×2 `hot-path`×2 `iequatable`×2 `inlining`×2 `jest`×2 `lfu`×2 `lifecycle`×2 `links`×2 `linux`×2 `lru`×2 `maintainability`×2 `maintenance`×2 `optimization`×2 `regex`×2 `release-notes`×2 `root-cause-analysis`×2 `urls`×2 `user-communication`×2 `validation`×2 `workflow`×2 `workflows`×2 `writing`×2 `xml-docs`×2 `yaml`×2 `accessibility`×1 `accuracy`×1 `architecture`×1 `arraypool`×1 `assertions`×1 `automation`×1 `bash`×1 `boxing`×1 `buffers`×1 `checklist`×1 `clarity`×1 `comments`×1 `compatibility`×1 `configuration`×1 `consistency`×1 `coroutines`×1 `cross-platform`×1 `diagrams`×1 `disposable`×1 `dry`×1 `duplicate-warnings`×1 `encoding`×1 `enum-validation`×1 `eslint`×1 `file-organization`×1 `fisher-yates`×1 `flaky-tests`×1 `fragments`×1 `garbage-collection`×1 `generic`×1 `gitattributes`×1 `here-strings`×1 `implementation`×1 `line-endings`×1 `llm-context`×1 `macos`×1 `mermaid`×1 `methodimpl`×1 `naming`×1 `navigation`×1 `negative-tests`×1 `optional-fields`×1 `parsing`×1 `portability`×1 `pre-commit`×1 `procedure`×1 `raii`×1 `release-workflow`×1 `scriptable-object`×1 `scripts`×1 `security`×1 `semantic-versioning`×1 `shared-state`×1 `shell`×1 `shuffle`×1 `site-structure`×1 `skills`×1 `stringbuilder`×1 `strings`×1 `style`×1 `sync-notes`×1 `test-cases`×1 `testability`×1 `theming`×1 `thread-safety`×1 `truthiness`×1 `type-coercion`×1 `type-specialization`×1 `version-management`×1 `windows`×1 `yield`×1 `zero-flaky`×1
 
 ---
 
@@ -151,6 +167,8 @@
 - [External URL Fragment Validation](./documentation/external-url-fragment-validation.md) _(documentation)_
 - [GitHub Actions Version Consistency](./documentation/github-actions-version-consistency.md) _(documentation)_
 - [Link Quality and External URL Management](./documentation/link-quality-guidelines.md) _(documentation)_
+- [Markdown Compatibility Guidelines](./documentation/markdown-compatibility.md) _(documentation)_
+- [MkDocs Navigation Management](./documentation/mkdocs-navigation.md) _(documentation)_
 - [Skill File Sizing Guidelines](./documentation/skill-file-sizing.md) _(documentation)_
 - [StringBuilder Pooling for Zero-Allocation String Building](./performance/stringbuilder-pooling.md) _(performance)_
 - [Test Categories for Selective Execution](./testing/test-categories.md) _(testing)_
@@ -185,9 +203,13 @@
 - [Fluent Builder Templates and Factories](./solid/fluent-builder-pattern-templates.md) _(solid)_
 - [Fluent Builder Usage Examples](./solid/fluent-builder-pattern-usage-examples.md) _(solid)_
 - [Git and Parser Robustness in CI/CD](./testing/git-workflow-robustness.md) _(testing)_
+- [Git Renormalize Pattern Validation](./github-actions/git-renormalize-patterns.md) _(github-actions)_
+- [GitHub Actions Workflow Consistency](./github-actions/workflow-consistency.md) _(github-actions)_
 - [IEquatable Implementation for Value Types](./solid/iequatable-implementation.md) _(solid)_
 - [IEquatable Implementation Variants](./solid/iequatable-implementation-variants.md) _(solid)_
 - [IEquatable Usage Examples](./solid/iequatable-implementation-usage.md) _(solid)_
+- [JavaScript Code Quality Practices](./scripting/javascript-code-quality.md) _(scripting)_
+- [Mermaid Diagram Theming](./documentation/mermaid-theming.md) _(documentation)_
 - [Object Pooling Anti-Patterns](./performance/object-pooling-anti-patterns.md) _(performance)_
 - [Object Pooling for Zero-Allocation Messaging](./performance/object-pooling.md) _(performance)_
 - [Object Pooling Usage Examples](./performance/object-pooling-usage-examples.md) _(performance)_
@@ -195,6 +217,7 @@
 - [PowerShell Scripting Best Practices](./scripting/powershell-best-practices.md) _(scripting)_
 - [Readonly Struct Cached Hash Performance Notes](./performance/readonly-struct-cached-hash-performance-notes.md) _(performance)_
 - [Readonly Struct with Cached Hash for Dictionary Keys](./performance/readonly-struct-cached-hash.md) _(performance)_
+- [Regex Pattern Documentation](./scripting/regex-documentation.md) _(scripting)_
 - [Runtime Singleton Pattern](./performance/singleton-runtime.md) _(performance)_
 - [RuntimeSingleton and ScriptableObject Singleton Patterns](./performance/singleton-patterns.md) _(performance)_
 - [Script Test Coverage Requirements](./testing/script-test-coverage.md) _(testing)_
@@ -206,6 +229,7 @@
 - [Singleton Usage Examples](./performance/singleton-usage-examples.md) _(performance)_
 - [Test Base Class Cleanup Usage](./testing/test-base-class-cleanup-usage.md) _(testing)_
 - [Test Base Class with Automatic Resource Cleanup](./testing/test-base-class-cleanup.md) _(testing)_
+- [Test Code Quality and Accuracy](./testing/test-code-quality.md) _(testing)_
 - [Test Coverage Scenario Categories](./testing/test-coverage-scenario-categories.md) _(testing)_
 - [Test Diagnostics and Investigation Patterns](./testing/test-diagnostics.md) _(testing)_
 - [Test Diagnostics Patterns](./testing/test-diagnostics-patterns.md) _(testing)_
@@ -213,6 +237,8 @@
 - [Test Failure Investigation and Zero-Flaky Policy](./testing/test-failure-investigation.md) _(testing)_
 - [Test Failure Investigation Procedure](./testing/test-failure-investigation-procedure.md) _(testing)_
 - [Test Failure Root Causes and Anti-Patterns](./testing/test-failure-investigation-root-causes.md) _(testing)_
+- [Test Production Code Directly](./testing/test-production-code.md) _(testing)_
+- [Validation Patterns and Duplicate Warning Prevention](./scripting/validation-patterns.md) _(scripting)_
 
 ### 🟠 Advanced
 

package/.llm/skills/scripting/javascript-code-quality.md

@@ -0,0 +1,417 @@
+---
+title: "JavaScript Code Quality Practices"
+id: "javascript-code-quality"
+category: "scripting"
+version: "1.0.0"
+created: "2026-01-30"
+updated: "2026-01-30"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "scripts/"
+    - path: "scripts/__tests__/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "javascript"
+  - "code-quality"
+  - "linting"
+  - "testing"
+  - "jest"
+  - "eslint"
+  - "documentation"
+  - "sync-notes"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of linting tools, test organization, and code documentation"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Code quality patterns only; no runtime performance impact"
+  maintainability:
+    rating: "high"
+    details: "Proper code organization and documentation prevents confusion and bugs"
+  testability:
+    rating: "high"
+    details: "Well-organized tests are easier to maintain and extend"
+
+prerequisites:
+  - "JavaScript fundamentals"
+  - "Jest testing framework familiarity"
+  - "Understanding of linting concepts"
+
+dependencies:
+  packages:
+    - "jest"
+  skills:
+    - "script-test-coverage"
+    - "cross-platform-compatibility"
+
+applies_to:
+  languages:
+    - "JavaScript"
+  frameworks:
+    - "Jest"
+    - "Node.js"
+  versions:
+    node: ">=18.0"
+    jest: ">=29.0"
+
+aliases:
+  - "JS code quality"
+  - "JavaScript best practices"
+  - "Test organization"
+
+related:
+  - "script-test-coverage"
+  - "cross-platform-compatibility"
+  - "comprehensive-test-coverage"
+  - "validation-patterns"
+
+status: "stable"
+---
+
+# JavaScript Code Quality Practices
+
+> **One-line summary**: Ensure JavaScript code has accurate documentation, properly placed
+> directives, correctly categorized tests, and bidirectional synchronization notes.
+
+## Overview
+
+JavaScript code quality extends beyond just "working code." This skill covers common pitfalls in
+documentation accuracy, linter directive placement, test organization, and synchronization between
+related code. Following these practices prevents confusion, reduces bugs, and improves codebase
+maintainability.
+
+## Solution
+
+1. **Keep JSDoc accurate** - function descriptions, parameter types, and return values must match
+   implementation
+1. **Keep module exports documented** - `@exports` tags must list actual exports with correct types
+   and values
+1. **Place linter directives immediately before suppressed code** - `eslint-disable-next-line`
+   only affects the next line
+1. **Only use linter directives if the linter is configured** - don't add ESLint comments to
+   projects that don't use ESLint
+1. **Use accurate `describe` block names** - test categories must reflect actual test content
+1. **Match user-facing messages to actual UI terminology** - column names, labels, and terms must
+   be consistent
+1. **Add bidirectional SYNC notes** - when code A references code B, code B must reference code A
+1. **Test user-facing message content** - verify messages contain correct terminology
+
+## Linter Directive Placement
+
+### Problem
+
+Linter disable directives (ESLint, JSHint, etc.) must be placed immediately before the line they
+suppress. Placing them earlier in the file has no effect and creates confusion.
+
+### Anti-Pattern
+
+```javascript
+// BAD: Directive is too far from the code it's meant to suppress
+// eslint-disable-next-line no-unused-vars
+const SOME_CONSTANT = "value";
+
+// Many lines of other code here...
+
+function unusedFunction() {
+  // This function is NOT suppressed - the directive was consumed by SOME_CONSTANT
+}
+```
+
+### Correct Pattern
+
+```javascript
+// GOOD: Directive immediately precedes the suppressed code
+const SOME_CONSTANT = "value";
+
+// Many lines of other code here...
+
+// eslint-disable-next-line no-unused-vars
+function unusedFunction() {
+  // This function IS suppressed
+}
+```
+
+### When to Avoid Directives Entirely
+
+Before adding a linter directive, verify:
+
+1. **Is the linter actually configured?** Adding ESLint directives to a project that doesn't use
+   ESLint is misleading and creates maintenance burden.
+1. **Can the underlying issue be fixed?** Unused variables should usually be removed, not
+   suppressed.
+1. **Is the suppression documented?** If you must suppress, add a comment explaining why.
+
+```javascript
+// GOOD: If ESLint is not used in the project, don't add ESLint directives
+// Just remove or use the code properly instead of suppressing warnings
+```
+
+## JSDoc Accuracy
+
+### Problem
+
+JSDoc comments that don't match implementation create dangerous misunderstandings. Tests written
+against inaccurate JSDoc verify incorrect behavior.
+
+### Anti-Pattern: Misleading Function Description
+
+```javascript
+// BAD: JSDoc says "excludes arrays" but implementation accepts them
+/**
+ * Validates that value is a non-null object (excludes arrays).
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is a non-null object
+ */
+function isValidObject(value) {
+  // Implementation actually accepts arrays!
+  return value !== null && typeof value === "object";
+}
+```
+
+### Correct Pattern: Documentation Matches Implementation
+
+```javascript
+// GOOD: JSDoc accurately describes behavior
+/**
+ * Validates that value is a non-null object (arrays are objects in JavaScript).
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is non-null and typeof is 'object'
+ */
+function isValidObject(value) {
+  return value !== null && typeof value === "object";
+}
+
+// OR: Update implementation to match documented intent
+/**
+ * Validates that value is a non-null, non-array object.
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is a non-null, non-array object
+ */
+function isValidObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+```
+
+### Module Export Documentation
+
+When using `@exports` tags to document module exports, keep them synchronized with actual exports:
+
+```javascript
+// BAD: @exports lists wrong values or missing exports
+/**
+ * @exports {Array<string>} VALID_LEVELS - Valid values: 'low', 'high'
+ */
+module.exports = {
+  VALID_LEVELS, // Actual values: ['basic', 'intermediate', 'advanced']
+  helperFunction // Not documented!
+};
+
+// GOOD: @exports matches actual export values
+/**
+ * @exports {Array<string>} VALID_LEVELS - Valid values: 'basic', 'intermediate', 'advanced'
+ * @exports {Function} helperFunction - Validates input and returns errors
+ */
+module.exports = {
+  VALID_LEVELS,
+  helperFunction
+};
+```
+
+### Verification Checklist
+
+1. **Read the implementation** - Don't just copy JSDoc from similar functions
+1. **Test edge cases mentioned in JSDoc** - If it says "excludes arrays", test with arrays
+1. **Update JSDoc when changing implementation** - Don't leave stale documentation
+1. **Avoid vague descriptions** - "Validates value" doesn't tell readers what validation occurs
+
+## Test Documentation Accuracy
+
+### Problem
+
+Test file headers, `describe` block names, and comments must accurately describe what the tests
+actually verify. Inaccurate documentation causes confusion and hides the test's true purpose.
+
+### Anti-Pattern: Incorrect Value Categorization
+
+```javascript
+// BAD: Header says "falsy/undefined" but tests actually check "undefined/null"
+/**
+ * @fileoverview Tests for frontmatter validation - falsy and undefined values.
+ */
+
+describe("Falsy/Undefined Value Handling", () => {
+  // But the tests below actually check undefined/null (missing values),
+  // not other falsy values like empty string, 0, or false
+  test("should warn when value is undefined", () => {
+    validate({ field: undefined });
+  });
+  test("should warn when value is null", () => {
+    validate({ field: null });
+  });
+});
+```
+
+### Correct Pattern: Precise Documentation
+
+```javascript
+// GOOD: Documentation accurately describes what is tested
+/**
+ * @fileoverview Tests for frontmatter validation - undefined and null values.
+ */
+
+describe("Undefined/Null Value Handling", () => {
+  test("should warn when value is undefined", () => {
+    validate({ field: undefined });
+  });
+  test("should warn when value is null", () => {
+    validate({ field: null });
+  });
+});
+
+// Separate describe block for falsy wrong-type values
+describe("Wrong Type Value Handling", () => {
+  test("should warn when value is empty string (wrong type)", () => {
+    validate({ field: "" });
+  });
+  test("should warn when value is zero (wrong type)", () => {
+    validate({ field: 0 });
+  });
+  test("should warn when value is false (wrong type)", () => {
+    validate({ field: false });
+  });
+});
+```
+
+### JavaScript Truthiness Reference
+
+When documenting tests, use accurate terminology:
+
+| Value       | Truthy/Falsy | Correct Term for Missing Check |
+| ----------- | ------------ | ------------------------------ |
+| `undefined` | Falsy        | "missing" or "undefined"       |
+| `null`      | Falsy        | "missing" or "null"            |
+| `""`        | Falsy        | "wrong type" (not "missing")   |
+| `0`         | Falsy        | "wrong type" (not "missing")   |
+| `false`     | Falsy        | "wrong type" (not "missing")   |
+| `[]`        | **Truthy**   | "empty array" (not falsy!)     |
+| `{}`        | **Truthy**   | "empty object" (not falsy!)    |
+
+## User-Facing Message Consistency
+
+### Problem
+
+Warning messages, error messages, and other user-facing text must match the actual UI, column
+names, or output they reference. Inconsistent naming causes confusion.
+
+### Anti-Pattern
+
+```javascript
+// BAD: Message says "Difficulty column" but the actual table header is "Complexity"
+console.warn(`Warning: ${file} has missing Difficulty column value`);
+
+// The actual table in the output/UI:
+// | Title | Complexity | Performance |
+// |-------|------------|-------------|
+```
+
+### Correct Pattern
+
+```javascript
+// GOOD: Message matches actual column name
+console.warn(`Warning: ${file} has missing Complexity column value`);
+
+// Matches the actual table:
+// | Title | Complexity | Performance |
+// |-------|------------|-------------|
+```
+
+### Test Coverage for Messages
+
+When code produces user-facing messages, tests should verify the message content:
+
+```javascript
+// GOOD: Test verifies message matches actual column names
+describe("Warning Messages", () => {
+  test("should use correct column name in warning", () => {
+    const result = validate(invalidData);
+
+    // Verify the warning uses the actual column name from the UI
+    expect(result.warnings[0]).toContain("Complexity");
+    expect(result.warnings[0]).not.toContain("Difficulty"); // Old incorrect name
+  });
+});
+```
+
+## Bidirectional SYNC Notes
+
+### Problem
+
+SYNC notes that only exist in one location are easily missed. When code A references code B, code B
+should also reference code A.
+
+### Anti-Pattern: One-Way SYNC
+
+```javascript
+// File: validate-skills.js
+// SYNC: Keep column names in sync with format-table.js formatHeader()
+const COLUMNS = ["Complexity", "Performance"];
+
+// File: format-table.js
+// No SYNC note here - easy to forget to update validate-skills.js
+function formatHeader() {
+  return ["Complexity", "Performance"];
+}
+```
+
+### Correct Pattern: Bidirectional SYNC
+
+```javascript
+// File: validate-skills.js
+// SYNC: Keep column names in sync with format-table.js formatHeader()
+const COLUMNS = ["Complexity", "Performance"];
+
+// File: format-table.js
+// SYNC: Keep column names in sync with validate-skills.js COLUMNS
+function formatHeader() {
+  return ["Complexity", "Performance"];
+}
+```
+
+### SYNC Note Checklist
+
+When adding a SYNC note:
+
+1. **Add notes in BOTH locations** - never just one direction
+1. **Reference by function/variable name** - not line numbers
+1. **Verify the referenced code exists** - don't reference non-existent functions
+1. **Update tests** - if synced values are used in tests, add SYNC notes there too
+1. **Cross-environment code** - browser/Node.js boundaries require SYNC notes since modules cannot
+   be shared; the test file replicates logic and the SYNC notes ensure they stay aligned
+
+## Common Mistakes Checklist
+
+Before committing JavaScript code, verify:
+
+- [ ] JSDoc function descriptions match implementation behavior
+- [ ] JSDoc `@param` and `@returns` types are accurate
+- [ ] Module `@exports` documentation lists actual exports with correct values
+- [ ] Linter directives are immediately before the suppressed line
+- [ ] Linter directives are only used if the linter is actually configured
+- [ ] Test `describe` blocks accurately categorize the tests they contain
+- [ ] File headers accurately describe file contents
+- [ ] Comments about JavaScript behavior are factually correct
+- [ ] User-facing messages match actual UI/output terminology
+- [ ] SYNC notes exist in both directions between related code
+- [ ] Tests verify user-facing message content
+
+## See Also
+
+- [Script Test Coverage](../testing/script-test-coverage.md) - Test file structure and naming
+- [Cross-Platform Compatibility](cross-platform-compatibility.md) - Platform-specific considerations
+- [Comprehensive Test Coverage](../testing/comprehensive-test-coverage.md) - Test coverage requirements