check-rule-mate 0.5.4 → 0.5.5

package/README.md

@@ -70,6 +70,7 @@ This separation makes the system flexible, scalable, and easy to maintain.
   - [Basic Usage](#Basic-Usage)
   - [Lifecycle Hooks](#Lifecycle-Hooks)
   - [Auto documentation](#Auto-Documentation)
+  - [[Experimental] - Documentation Playground](#experimental-documentation-playground)
   - [Auto Checker for Templates](#Auto-Checker-for-Templates)
 - [Defining Validation](#Defining-Validation)
   - [1. Schema](#Defining-a-Schema-What-to-validate)
@@ -293,11 +294,71 @@ await validator.validate();
 To use that it is simple, you only need to run this command:
 
 ```bash
-npx check-rule-mate-auto-docs --rules {rules path} --schemas {schemas path} --errors {errors path} --out file.html
+npx check-rule-mate-auto-docs --rules {rules path} --schemas {schemas path} --errors {errors path} --out {file.html}
 ```
 
 This will generate a HTML file containing the rules, schemas and errors.
 
+### [Experimental] Documentation Playground
+
+> ⚠️ The playground executes bundled client-side JavaScript.
+> Do not use untrusted validation code.
+
+The **Docs Playground** allows you to generate an interactive HTML page where you can **test your schemas, rules, and validators directly in the browser**.
+
+This feature is **experimental** and intended mainly for development and exploration purposes. It bundles your validation logic into a client-side format, enabling real-time validation without any backend setup.
+
+> ⚠️ Since this feature is experimental, APIs and behavior may change.
+
+---
+
+#### Requirements
+
+The playground generator depends on **optional dependencies** that are **not installed by default**.
+
+Before using it, make sure you have the required optional dependencies installed:
+
+```bash
+npm install esbuild
+```
+
+#### Usage
+
+Run the playground generator using the CLI:
+```bash
+npx check-rule-mate-auto-docs-playground-experimental \
+  --rules {rules-path} \
+  --schemas {schemas-path} \
+  --errors {errors-path} \
+  --options {options-path} \
+  --out {output-file.html}
+```
+
+This command will generate a self-contained HTML file with:
+- Documentation for your rules and schemas
+- A playground to test validation behavior in real time
+
+#### Options File
+
+The playground requires an **options file** to map validator names to their source files.
+
+Example:
+```json
+{
+  "validators": {
+    "myValidator": "./examples/vanilla/src/check-rule-mate-rules/validators/validators.js",
+    "nameValidator": "./examples/vanilla/src/check-rule-mate-rules/validators/validators.js",
+    "myValidator2": "./examples/vanilla/src/check-rule-mate-rules/validators/validator2.js"
+  }
+}
+```
+**How it works**:
+- **Keys** represent the **exported object/function/class** name of your **validator**
+- **Values** are paths to the **files** where those validators are defined
+- These validators are bundled and made available inside the playground
+
+This explicit mapping ensures predictable builds and avoids magic imports.
+
 ### Auto Checker for Templates
 You can **auto check** if your template it is working properly with all necessary properties or have something missing.
 

package/bin/generate-docs-playground-experimental.js

@@ -0,0 +1,617 @@
+#!/usr/bin/env node
+/**
+ * check-rule-mate — Auto Documentation Generator
+ */
+
+// import fs from "fs";
+// import path from "path";
+// import process from "process";
+
+const fs = require('fs');
+const path = require('path');
+const process = require('process');
+let esbuild;
+try {
+  esbuild = require('esbuild');
+} catch {
+  console.warn(
+    '[check-rule-mate] esbuild not found. ' +
+    'Install it to enable playground generation.'
+  );
+  process.exit(1);
+}
+
+/* ---------------------------------------
+ * CLI ARGS
+ * -------------------------------------*/
+const args = process.argv.slice(2);
+const getArg = (flag) => {
+  const index = args.indexOf(flag);
+  return index !== -1 ? args[index + 1] : null;
+};
+
+const RULES_DIR = getArg('--rules');
+const SCHEMAS_DIR = getArg('--schemas');
+const ERRORS_DIR = getArg('--errors')
+const OPTIONS_DIR = getArg('--options');
+const OUTPUT = getArg('--out') || "check-rule-mate-docs.html";
+const OUTPUT_DIR = path.dirname(OUTPUT);
+
+const OPTIONS = OPTIONS_DIR ? JSON.parse(fs.readFileSync(OPTIONS_DIR, "utf-8")) : null;
+
+
+if (OPTIONS) {
+  let entryPointFile = Object.keys(OPTIONS.validators).map((key) => `var ${key} = require('${OPTIONS.validators[key]}')`).join('\n');
+  entryPointFile += `\n window.validatorHelpers = {${Object.keys(OPTIONS.validators).map((key) => `${key}: ${key}`)}}`
+
+  fs.writeFileSync(`./check-rule-mate.validators.docs.js`, entryPointFile);
+
+  esbuild.build({
+    entryPoints: ['./node_modules/check-rule-mate/src/main.js'],
+    bundle: true,
+    outfile: `${OUTPUT_DIR}/check-rule-mate.js`,
+    platform: 'browser',
+    target: 'node16',
+    format: 'iife',
+    minify: false
+  }).then(() => {
+      console.log('Build completed successfully: check-rule-mate.js');
+
+      const checkRuleMateFIle = fs.readFileSync(`${OUTPUT_DIR}/check-rule-mate.js`, 'utf-8');
+      const lines = checkRuleMateFIle.split('\n')
+      lines.shift();
+      lines.splice(lines.length - 2, 1)
+      fs.writeFileSync(`${OUTPUT_DIR}/check-rule-mate.js`, lines.join('\n'))
+  }).catch(() => process.exit(1));
+
+  esbuild.build({
+    entryPoints: [`./check-rule-mate.validators.docs.js`],
+    bundle: true,
+    outfile: `${OUTPUT_DIR}/index.js`,
+    platform: 'browser',
+    target: 'node16',
+    format: 'iife',
+    minify: false
+  }).then(() => {
+      console.log('Build completed successfully: index.js');
+      fs.rmSync('./check-rule-mate.validators.docs.js')
+  }).catch(() => process.exit(1));
+}
+
+
+if (!RULES_DIR || !SCHEMAS_DIR) {
+  console.error(`
+Usage:
+npx check-rule-mate-auto-docs --rules ./rules --schemas ./schemas --errors ./errors --out docs.html
+`);
+  process.exit(1);
+}
+
+/* ---------------------------------------
+ * HELPERS
+ * -------------------------------------*/
+const readJSONFiles = (dir) => {
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith(".json"))
+    .map(file => ({
+      name: file.replace(".json", ""),
+      content: JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"))
+    }));
+};
+
+const rulesFiles = readJSONFiles(RULES_DIR);
+const schemasFiles = readJSONFiles(SCHEMAS_DIR);
+const errorsFiles = readJSONFiles(ERRORS_DIR);
+
+
+/* ---------------------------------------
+ * INDEX RELATIONSHIPS
+ * -------------------------------------*/
+const ruleUsageMap = {};
+const errorUsageMap = {}
+
+schemasFiles.forEach(schemaFile => {
+  Object.entries(schemaFile.content).forEach(([field, config]) => {
+    const ruleName = config.rule.split("--")[0];
+    if (!ruleUsageMap[ruleName]) ruleUsageMap[ruleName] = [];
+    ruleUsageMap[ruleName].push({
+      schema: schemaFile.name,
+      field,
+      rule: config.rule
+    });
+  });
+});
+
+rulesFiles.forEach(rulesFile => {
+  Object.entries(rulesFile.content).forEach(([field, config]) => {
+    Object.entries(config.error).forEach(([key, value]) => {
+      const errorName = value;
+      if (!errorUsageMap[errorName]) errorUsageMap[errorName] = [];
+      errorUsageMap[errorName].push({
+        file: rulesFile.name,
+        field,
+        error: value
+      });
+    });
+    if (config?.modifier) {
+      Object.entries(config.modifier).forEach(([modifierKey, modifier]) => {
+        if (modifier?.error) {
+          Object.entries(modifier.error).forEach(([key, value]) => {
+            const errorName = value;
+            if (!errorUsageMap[errorName]) errorUsageMap[errorName] = [];
+            errorUsageMap[errorName].push({
+              file: rulesFile.name,
+              field,
+              error: value
+            });
+          });
+        }
+      });
+    }
+  });
+});
+
+
+/* ---------------------------------------
+ * HTML GENERATION
+ * -------------------------------------*/
+const html = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>check-rule-mate — Documentation</title>
+<style>
+${generateCSS()}
+</style>
+${OPTIONS ? `
+  <script src="./check-rule-mate.js" defer></script>
+  <script src="./index.js" defer></script>`
+: ''}
+</head>
+<body>
+
+<aside class="sidebar">
+  <input id="search" placeholder="Search..." />
+
+  <h3>Schemas</h3>
+  ${schemasFiles.map(s => `
+    <a href="#schema-${s.name}">${s.name}</a>
+  `).join("")}
+
+  <h3>Rules</h3>
+  ${rulesFiles.map(rf =>
+    Object.keys(rf.content).map(rule => `
+      <a href="#rule-${rule}">${rf.name} - ${rule}</a>
+    `).join("")
+  ).join("")}
+
+  <h3>Errors</h3>
+  ${errorsFiles.map(errorFile =>
+    Object.keys(errorFile.content).map(error => `
+      <a href="#error-${error}">${errorFile.name} - ${error}</a>
+    `).join("")
+  ).join("")}
+</aside>
+
+<main>
+  <section>
+    <h1>check-rule-mate</h1>
+    <p class="muted">
+      Visual documentation of validation rules and schemas.
+    </p>
+  </section>
+
+  ${renderSchemas(schemasFiles)}
+  ${renderRules(rulesFiles, ruleUsageMap)}
+  ${renderErrors(errorsFiles, errorUsageMap)}
+</main>
+
+<script>
+${generateClientJS()}
+</script>
+
+</body>
+</html>
+`;
+
+fs.writeFileSync(OUTPUT, html);
+console.log(`✔ Documentation generated at ${OUTPUT}`);
+
+/* ---------------------------------------
+ * RENDERERS
+ * -------------------------------------*/
+function renderSchemas(schemas) {
+  return schemas.map(schema => `
+  <section id="schema-${schema.name}" class="card">
+    <h2>Schema: ${schema.name}</h2>
+
+    <table>
+      <thead>
+        <tr>
+          <th>Field</th>
+          <th>Rule</th>
+          <th class="text-center">Required</th>
+          <th class="text-center">Cache</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${Object.entries(schema.content).map(([field, cfg]) => `
+          <tr>
+            <td>${field}</td>
+            <td>
+              <a href="#rule-${cfg.rule.split("--")[0]}">
+                ${cfg.rule}
+              </a>
+            </td>
+            <td class="text-center">${cfg.required ? "✔" : "optional"}</td>
+            <td class="text-center">${cfg.cache === false ? "off" : "✔"}</td>
+          </tr>
+        `).join("")}
+      </tbody>
+    </table>
+    ${OPTIONS ? `
+      <details class="schema-test">
+        <summary>Schema Test (Experimental)</summary>
+        <div class="schema-test-container">
+          <form id="schema:${schema.name}" data-form="schema--${schema.name}">
+            ${Object.entries(schema.content).map(([field, cfg]) => {
+              const attributesHTML = cfg.attributesHTML ? Object.keys(cfg.attributesHTML).map((key) => `${key}="${cfg?.attributesHTML[key]}"`).join(' ') : null
+              return `
+              <div style="display: flex; flex-direction: column;">
+                <label for="${field}">${field} (${cfg.rule})</label>
+                <input name="${field}" ${cfg.required ? 'required': ''} ${attributesHTML}/>
+              </div>
+            `}).join("")}
+            <div style="display: flex; flex-direction: column;">
+              <label for="check-rule-mate-validators">VALIDATORS</label>
+              <input name="check-rule-mate-validators" placeholder="Add the validator object/function/class name - example: myValidator" required/>
+            </div>
+            <div style="display: flex; flex-direction: column;">
+              <label for="check-rule-mate-rules">RULES</label>
+              <input name="check-rule-mate-rules" placeholder="Add the rule file name - example: myRules" required/>
+            </div>
+            <button type="submit">Validate Schema</button>
+          </form>
+          <div class="schema-test-result">
+            <span>Result:</span>
+            <textarea id="textarea-schema-${schema.name}"></textarea>
+          </div>
+        </div>
+      </details>
+    ` : ''}
+    </section>
+  `).join("");
+}
+
+function renderRules(rulesFiles, usageMap) {
+  return rulesFiles.map(file =>
+    Object.entries(file.content).map(([ruleName, rule]) => `
+    <section id="rule-${ruleName}" class="card">
+      <h2>Rule: ${ruleName} (${file.name})</h2>
+      ${rule?.docs?.description ?
+        `<p>${rule.docs.description}</p>`
+      : ''}
+
+      <h3>Validation Flow</h3>
+      <div class="flow">
+        ${rule.validate.map(v => `
+          <div class="flow-step">${v}</div>
+          <div class="flow-arrow">→</div>
+        `).join("")}
+        <div class="flow-step success">valid</div>
+      </div>
+
+      <h3>Error Codes</h3>
+      ${renderRulesErrors(rule.error)}
+
+      ${rule.modifier ? `
+        <h3>Modifiers</h3>
+        ${Object.entries(rule.modifier).map(([mod, modRule]) => `
+          <div class="modifier">
+            <span class="tag modifier">${mod}</span>
+            ${modRule?.docs?.description ? `<p>${modRule.docs.description}</p>` : ''}
+
+            <div class="flow">
+              ${modRule.validate.map(v => `
+                <div class="flow-step">${v}</div>
+                <div class="flow-arrow">→</div>
+              `).join("")}
+              <div class="flow-step success">valid</div>
+            </div>
+
+            <h4>Error Codes</h4>
+            ${renderRulesErrors(modRule.error)}
+          </div>
+        `).join("")}
+      ` : ""}
+
+      <h3>Used by Schemas</h3>
+      <ul>
+        ${(usageMap[ruleName] || []).map(u =>
+          `<li>${u.schema} → <strong>${u.field}</strong> (${u.rule})</li>`
+        ).join("") || "<li>Not used</li>"}
+      </ul>
+
+      ${rule?.docs?.notes ?
+      `
+        <h3>Notes</h3>
+        <div class="rule-notes">${rule?.docs?.notes}</div>
+      `
+      : ''}
+    </section>
+    `).join("")
+  ).join("");
+}
+
+function renderRulesErrors(errors = {}) {
+  return `
+    <ul>
+      ${Object.entries(errors).map(([k, v]) =>
+        `<li><a href="#error-${v.split('.')[0]}" class="tag error">${k}</a> ${v}</li>`
+      ).join("")}
+    </ul>
+  `;
+}
+
+function renderErrors(errorFiles, usageMap) {
+  return errorFiles.map(file =>
+    Object.entries(file.content).map(([errorName, errors]) => `
+    <section id="error-${errorName}" class="card">
+      <h2>Error: ${errorName} (${file.name})</h2>
+      <ul>
+      ${Object.entries(errors).map(([key, value]) => `
+        <li><span class="tag error">${key}</span> ${value} </li>
+      `).join('')}
+      </ul>
+
+      <h3>Used by Rules</h3>
+      <ul>
+        ${Object.entries(errors).map(([key, value]) => `
+          ${(usageMap[`${errorName}.${key}`] || []).map(u =>
+            `<li>${u.file} → <strong>${u.field}</strong> (${u.error})</li>`
+          ).join("") || "<li>Not used</li>"}
+        `).join('')}
+      </ul>
+    </section>
+  `).join('')).join('');
+}
+
+/* ---------------------------------------
+ * CSS
+ * -------------------------------------*/
+function generateCSS() {
+  return `
+  body {
+    margin: 0;
+    font-family: Inter, system-ui, sans-serif;
+    display: grid;
+    grid-template-columns: 280px 1fr;
+    background: #0f172a;
+    color: #e5e7eb;
+  }
+
+  .sidebar {
+    padding: 16px;
+    background: #020617;
+    overflow-y: auto;
+  }
+
+  .sidebar input {
+    width: 100%;
+    padding: 8px;
+    border-radius: 6px;
+    border: none;
+    margin-bottom: 16px;
+  }
+
+  .sidebar a {
+    display: block;
+    padding: 6px 10px;
+    color: #e5e7eb;
+    text-decoration: none;
+    border-radius: 6px;
+  }
+
+  .sidebar a:hover {
+    background: rgba(56,189,248,0.2);
+  }
+
+  a {
+    color: #e5e7eb;
+  }
+
+  main {
+    padding: 32px;
+    overflow-y: auto;
+  }
+
+  .card {
+    background: #020617;
+    border-radius: 12px;
+    padding: 24px;
+    margin-bottom: 32px;
+    border: 1px solid rgba(255,255,255,0.05);
+  }
+
+  .flow {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    flex-wrap: wrap;
+  }
+
+  .flow-step {
+    padding: 10px 14px;
+    border-radius: 8px;
+    background: rgba(56,189,248,0.15);
+  }
+
+  .flow-arrow {
+    opacity: 0.5;
+  }
+
+  .success {
+    background: rgba(34,197,94,0.2);
+  }
+
+  .tag {
+    padding: 4px 8px;
+    border-radius: 999px;
+    font-size: 14px;
+  }
+
+  .tag.error {
+    display: inline-block;
+    margin-bottom: 8px;
+    background: rgba(239,68,68,0.2);
+    text-decoration: none;
+  }
+
+  .tag.modifier {
+    display: inline-block;
+    font-size: 16px;
+    margin-bottom: 8px;
+    font-weight: 600;
+    background: rgba(167,139,250,0.2);
+  }
+
+  table {
+    width: 100%;
+    border-collapse: collapse;
+  }
+
+  td, th {
+    padding: 8px;
+    border-bottom: 1px solid rgba(255,255,255,0.05);
+  }
+
+  th {
+    text-align: left;
+    border-bottom: 1px solid #f4f4f4;
+  }
+
+  .rule-notes {
+    padding: 16px;
+    color: black;
+    background: #f4f4f4;
+    border-radius: 12px;
+  }
+
+  .text-center {
+    text-align: center;
+  }
+
+  .schema-test {
+    margin-top: 32px;
+  }
+
+  .schema-test-container {
+    display: flex;
+    width: 100%;
+    margin: 32px 0 24px 0;
+    gap: 40px;
+  }
+
+  .schema-test-container > * {
+    width: 100%;
+  }
+
+  .schema-test-result span {
+    display: block;
+    font-size: 20px;
+    font-weight: 600;
+    margin-bottom: 16px;
+  }
+
+  .schema-test-result textarea {
+    width: 100%;
+    height: 80%;
+    color: #f4f4f4;
+    background-color: #111111;
+    border: none;
+  }
+
+  button {
+    cursor: pointer;
+  }
+
+  form button[type="submit"] {
+    width: 100%;
+    padding: 16px 24px;
+    min-width: 120px;
+    min-height: 48px;
+    margin-top: 16px;
+    font-size: 16px;
+    font-weight: 600;
+    color: #444444;
+    background-color: #eede91;
+  }
+
+  label {
+    margin-bottom: 4px;
+    font-size: 16px;
+    color: #e5e7eb;
+  }
+
+  .schema-test input {
+    min-height: 28px;
+    padding: 4px 8px 4px 8px;
+    margin-bottom: 16px;
+    font-size: 16px;
+    color: #e5e7eb;
+    background-color: transparent;
+    border: none;
+    border-bottom: 1px solid white;
+  }
+  `;
+}
+
+/* ---------------------------------------
+ * CLIENT JS
+ * -------------------------------------*/
+function generateClientJS() {
+  return `
+  const search = document.getElementById("search");
+  search.addEventListener("input", e => {
+    const value = e.target.value.toLowerCase();
+    document.querySelectorAll("section.card").forEach(card => {
+      card.style.display = card.innerText.toLowerCase().includes(value)
+        ? ""
+        : "none";
+    });
+  });
+
+  ${OPTIONS ? `
+    setTimeout(() => {
+      const rulesFiles = ${JSON.stringify(rulesFiles)}
+      const schemasFiles = ${JSON.stringify(schemasFiles)}
+
+      const formElements = document.querySelectorAll('form[data-form]');
+      formElements.forEach((formElement) => {
+        formElement.addEventListener('submit', async (e) => {
+          e.preventDefault();
+          const inputElements = formElement.querySelectorAll('input');
+          const formName = formElement.dataset.form.split('--')[1];
+          const formData = {};
+          inputElements.forEach((inputElement) => {
+            formData[inputElement.name] = inputElement.value;
+          })
+
+          const validatorHelper = window.validatorHelpers[formData["check-rule-mate-validators"]][formData["check-rule-mate-validators"]];
+
+          const rules = rulesFiles.filter((rulesFile) => rulesFile.name === formData["check-rule-mate-rules"])[0].content;
+          const schema = schemasFiles.filter((schemaFile) => schemaFile.name === formName)[0].content;
+
+          const validator = createValidator(formData, {validationHelpers: validatorHelper, rules: rules, schema: schema, options: { propertiesMustMatch: false, abortEarly: false, cache: true}});
+          const result = await validator.validate();
+          console.log(formName, result);
+
+          const textAreaElement = document.querySelector('#textarea-schema-'+formName);
+          textAreaElement.value = JSON.stringify(result);
+        });
+      });
+    }, 1000);
+  `: ''}
+  `;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "check-rule-mate",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "",
   "main": "./dist/main.cjs.js",
   "type": "commonjs",
@@ -19,6 +19,7 @@
   ],
   "bin": {
     "check-rule-mate-auto-docs": "./bin/generate-docs.js",
+    "check-rule-mate-auto-docs-playground-experimental": "./bin/generate-docs-playground-experimental.js",
     "check-rule-mate-verify-templates": "./bin/verify-templates.js"
   },
   "scripts": {
@@ -30,6 +31,9 @@
   },
   "author": "João Rocha",
   "license": "ISC",
+  "optionalDependencies": {
+    "esbuild": "^0.27.2"
+  },
   "devDependencies": {
     "esbuild": "^0.27.2",
     "express": "^4.21.2",