@jay-framework/plugin-validator 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { PluginManifest } from '@jay-framework/editor-protocol';
+
+interface ValidatePluginOptions {
+    pluginPath?: string;
+    local?: boolean;
+    verbose?: boolean;
+    strict?: boolean;
+    generateTypes?: boolean;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    pluginName?: string;
+    contractsChecked?: number;
+    componentsChecked?: number;
+    packageJsonChecked?: boolean;
+    typesGenerated?: number;
+}
+interface ValidationError {
+    type: 'schema' | 'file-missing' | 'export-mismatch' | 'contract-invalid' | 'type-generation-failed';
+    message: string;
+    location?: string;
+    suggestion?: string;
+}
+interface ValidationWarning {
+    type: string;
+    message: string;
+    location?: string;
+    suggestion?: string;
+}
+interface PluginContext {
+    manifest: PluginManifest;
+    pluginPath: string;
+    isNpmPackage: boolean;
+}
+
+/**
+ * Validates a Jay Stack plugin package or local plugin directory.
+ *
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ */
+declare function validatePlugin(options?: ValidatePluginOptions): Promise<ValidationResult>;
+
+export { type PluginContext, type ValidatePluginOptions, type ValidationError, type ValidationResult, type ValidationWarning, validatePlugin };

package/dist/index.js

@@ -0,0 +1,413 @@
+import fs from "fs";
+import path from "path";
+import YAML from "yaml";
+import { loadPluginManifest } from "@jay-framework/compiler-shared";
+async function validatePlugin(options = {}) {
+  const pluginPath = options.pluginPath || process.cwd();
+  if (options.local) {
+    return validateLocalPlugins(pluginPath, options);
+  } else {
+    return validatePluginPackage(pluginPath, options);
+  }
+}
+async function validatePluginPackage(pluginPath, options) {
+  const result = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    contractsChecked: 0,
+    componentsChecked: 0
+  };
+  const pluginYamlPath = path.join(pluginPath, "plugin.yaml");
+  const pluginManifest = loadPluginManifest(pluginPath);
+  if (!pluginManifest) {
+    if (!fs.existsSync(pluginYamlPath)) {
+      result.errors.push({
+        type: "file-missing",
+        message: "plugin.yaml not found",
+        location: pluginPath,
+        suggestion: "Create a plugin.yaml file in the plugin root directory"
+      });
+    } else {
+      result.errors.push({
+        type: "schema",
+        message: "Invalid YAML syntax or format",
+        location: pluginYamlPath
+      });
+    }
+    result.valid = false;
+    return result;
+  }
+  result.pluginName = pluginManifest.name;
+  const context = {
+    manifest: pluginManifest,
+    pluginPath,
+    isNpmPackage: fs.existsSync(path.join(pluginPath, "package.json"))
+  };
+  await validateSchema(context, result);
+  if (pluginManifest.contracts) {
+    for (let i = 0; i < pluginManifest.contracts.length; i++) {
+      await validateContract(
+        pluginManifest.contracts[i],
+        i,
+        context,
+        options.generateTypes || false,
+        result
+      );
+    }
+  }
+  if (pluginManifest.contracts) {
+    for (let i = 0; i < pluginManifest.contracts.length; i++) {
+      await validateComponent(pluginManifest.contracts[i], i, context, result);
+    }
+  }
+  if (context.isNpmPackage) {
+    await validatePackageJson(context, result);
+    result.packageJsonChecked = true;
+  }
+  if (pluginManifest.dynamic_contracts) {
+    await validateDynamicContracts(context, result);
+  }
+  result.valid = result.errors.length === 0;
+  return result;
+}
+async function validateLocalPlugins(projectPath, options) {
+  const pluginsPath = path.join(projectPath, "src/plugins");
+  if (!fs.existsSync(pluginsPath)) {
+    return {
+      valid: false,
+      errors: [
+        {
+          type: "file-missing",
+          message: "src/plugins/ directory not found",
+          location: projectPath,
+          suggestion: "Create src/plugins/ directory for local plugins"
+        }
+      ],
+      warnings: []
+    };
+  }
+  const pluginDirs = fs.readdirSync(pluginsPath, { withFileTypes: true }).filter((d) => d.isDirectory());
+  const allResults = [];
+  for (const pluginDir of pluginDirs) {
+    const pluginPath = path.join(pluginsPath, pluginDir.name);
+    const result = await validatePluginPackage(pluginPath, options);
+    allResults.push(result);
+  }
+  return {
+    valid: allResults.every((r) => r.valid),
+    errors: allResults.flatMap((r) => r.errors),
+    warnings: allResults.flatMap((r) => r.warnings),
+    contractsChecked: allResults.reduce((sum, r) => sum + (r.contractsChecked || 0), 0),
+    componentsChecked: allResults.reduce((sum, r) => sum + (r.componentsChecked || 0), 0),
+    typesGenerated: allResults.reduce((sum, r) => sum + (r.typesGenerated || 0), 0)
+  };
+}
+async function validateSchema(context, result) {
+  const { manifest } = context;
+  if (!manifest.name) {
+    result.errors.push({
+      type: "schema",
+      message: "Missing required field: name",
+      location: "plugin.yaml",
+      suggestion: 'Add a "name" field with a kebab-case plugin name'
+    });
+  } else if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(manifest.name)) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid plugin name: "${manifest.name}". Must be kebab-case.`,
+      location: "plugin.yaml",
+      suggestion: 'Use lowercase letters, numbers, and hyphens only (e.g., "my-plugin")'
+    });
+  }
+  if (manifest.contracts) {
+    if (!Array.isArray(manifest.contracts)) {
+      result.errors.push({
+        type: "schema",
+        message: 'Field "contracts" must be an array',
+        location: "plugin.yaml"
+      });
+    } else {
+      manifest.contracts.forEach((contract, index) => {
+        if (!contract.name) {
+          result.errors.push({
+            type: "schema",
+            message: `Contract at index ${index} is missing "name" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!contract.contract) {
+          result.errors.push({
+            type: "schema",
+            message: `Contract "${contract.name || index}" is missing "contract" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify path to .jay-contract file"
+          });
+        }
+        if (!contract.component) {
+          result.errors.push({
+            type: "schema",
+            message: `Contract "${contract.name || index}" is missing "component" field`,
+            location: "plugin.yaml",
+            suggestion: 'Specify the exported member name from the module (e.g., "moodTracker")'
+          });
+        }
+      });
+    }
+  }
+  if (manifest.dynamic_contracts) {
+    if (!manifest.dynamic_contracts.component) {
+      result.errors.push({
+        type: "schema",
+        message: 'dynamic_contracts is missing "component" field',
+        location: "plugin.yaml",
+        suggestion: "Specify path to shared component for dynamic contracts"
+      });
+    }
+    if (!manifest.dynamic_contracts.generator) {
+      result.errors.push({
+        type: "schema",
+        message: 'dynamic_contracts is missing "generator" field',
+        location: "plugin.yaml",
+        suggestion: "Specify path to generator file"
+      });
+    }
+    if (!manifest.dynamic_contracts.prefix) {
+      result.errors.push({
+        type: "schema",
+        message: 'dynamic_contracts is missing "prefix" field',
+        location: "plugin.yaml",
+        suggestion: 'Specify prefix for dynamic contract names (e.g., "cms")'
+      });
+    }
+  }
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
+    result.warnings.push({
+      type: "schema",
+      message: "Plugin has no contracts or dynamic_contracts defined",
+      location: "plugin.yaml",
+      suggestion: 'Add either "contracts" or "dynamic_contracts" to expose functionality'
+    });
+  }
+}
+async function validateContract(contract, index, context, generateTypes, result) {
+  result.contractsChecked = (result.contractsChecked || 0) + 1;
+  let contractPath;
+  if (context.isNpmPackage) {
+    const contractSpec = contract.contract;
+    const possiblePaths = [
+      path.join(context.pluginPath, "dist", contractSpec),
+      path.join(context.pluginPath, "lib", contractSpec),
+      path.join(context.pluginPath, contractSpec)
+    ];
+    let found = false;
+    for (const possiblePath of possiblePaths) {
+      if (fs.existsSync(possiblePath)) {
+        contractPath = possiblePath;
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      result.errors.push({
+        type: "file-missing",
+        message: `Contract file not found: ${contractSpec}`,
+        location: `plugin.yaml contracts[${index}]`,
+        suggestion: `Ensure the contract file exists (looked in dist/, lib/, and root)`
+      });
+      return;
+    }
+  } else {
+    contractPath = path.join(context.pluginPath, contract.contract);
+    if (!fs.existsSync(contractPath)) {
+      result.errors.push({
+        type: "file-missing",
+        message: `Contract file not found: ${contract.contract}`,
+        location: `plugin.yaml contracts[${index}]`,
+        suggestion: `Create the contract file at ${contractPath}`
+      });
+      return;
+    }
+  }
+  try {
+    const contractContent = await fs.promises.readFile(contractPath, "utf-8");
+    const parsedContract = YAML.parse(contractContent);
+    if (!parsedContract.name) {
+      result.errors.push({
+        type: "contract-invalid",
+        message: `Contract file ${contract.contract} is missing "name" field`,
+        location: contractPath
+      });
+    }
+    if (!parsedContract.tags || !Array.isArray(parsedContract.tags)) {
+      result.errors.push({
+        type: "contract-invalid",
+        message: `Contract file ${contract.contract} is missing "tags" array`,
+        location: contractPath
+      });
+    }
+  } catch (error) {
+    result.errors.push({
+      type: "contract-invalid",
+      message: `Invalid contract YAML: ${error.message}`,
+      location: contractPath,
+      suggestion: "Check YAML syntax and ensure it follows Jay contract format"
+    });
+    return;
+  }
+  if (generateTypes) {
+    try {
+      const { compileContractFile } = await import("@jay-framework/compiler-jay-html");
+      const dtsPath = contractPath + ".d.ts";
+      await compileContractFile(contractPath, dtsPath);
+      result.typesGenerated = (result.typesGenerated || 0) + 1;
+    } catch (error) {
+      result.errors.push({
+        type: "type-generation-failed",
+        message: `Failed to generate types for ${contract.contract}: ${error.message}`,
+        location: contractPath
+      });
+    }
+  }
+}
+async function validateComponent(contract, index, context, result) {
+  result.componentsChecked = (result.componentsChecked || 0) + 1;
+  if (typeof contract.component !== "string" || contract.component.length === 0) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid component name: ${contract.component}`,
+      location: `plugin.yaml contracts[${index}]`,
+      suggestion: 'Component should be the exported member name (e.g., "moodTracker")'
+    });
+  }
+  if (contract.component.includes("/") || contract.component.includes(".")) {
+    result.warnings.push({
+      type: "schema",
+      message: `Component "${contract.component}" looks like a path. Should it be an export name?`,
+      location: `plugin.yaml contracts[${index}]`,
+      suggestion: 'Component should be the exported member name (e.g., "moodTracker"), not a file path'
+    });
+  }
+}
+async function validatePackageJson(context, result) {
+  const packageJsonPath = path.join(context.pluginPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    result.warnings.push({
+      type: "file-missing",
+      message: "package.json not found",
+      location: context.pluginPath,
+      suggestion: "Create a package.json file for NPM package distribution"
+    });
+    return;
+  }
+  try {
+    const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf-8"));
+    if (!packageJson.exports) {
+      result.warnings.push({
+        type: "export-mismatch",
+        message: 'package.json missing "exports" field',
+        location: packageJsonPath,
+        suggestion: "Add exports field to define entry points for server/client builds"
+      });
+    } else {
+      if (!packageJson.exports["."]) {
+        result.warnings.push({
+          type: "export-mismatch",
+          message: 'package.json exports missing "." entry point',
+          location: packageJsonPath,
+          suggestion: 'Add "." export for the main module entry'
+        });
+      }
+      if (context.manifest.contracts) {
+        for (const contract of context.manifest.contracts) {
+          const contractExport = "./" + contract.contract;
+          if (!packageJson.exports[contractExport]) {
+            result.errors.push({
+              type: "export-mismatch",
+              message: `Contract "${contract.name}" not exported in package.json`,
+              location: packageJsonPath,
+              suggestion: `Add "${contractExport}": "./dist/${contract.contract}" to exports field`
+            });
+          }
+        }
+      }
+      if (!packageJson.exports["."]) {
+        result.errors.push({
+          type: "export-mismatch",
+          message: 'NPM package missing "." export in package.json',
+          location: packageJsonPath,
+          suggestion: 'Add ".": "./dist/index.js" (or your main file) to exports field'
+        });
+      }
+      if (context.manifest.module) {
+        const moduleName = context.manifest.module;
+        result.warnings.push({
+          type: "schema",
+          message: 'NPM packages should omit the "module" field - the package main export will be used',
+          location: "plugin.yaml",
+          suggestion: 'Remove the "module" field from plugin.yaml'
+        });
+      }
+    }
+    if (!packageJson.exports || !packageJson.exports["./plugin.yaml"]) {
+      result.errors.push({
+        type: "export-mismatch",
+        message: "plugin.yaml not exported in package.json (required for plugin resolution)",
+        location: packageJsonPath,
+        suggestion: 'Add "./plugin.yaml": "./plugin.yaml" to exports field'
+      });
+    }
+  } catch (error) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid package.json: ${error.message}`,
+      location: packageJsonPath
+    });
+  }
+}
+async function validateDynamicContracts(context, result) {
+  const { dynamic_contracts } = context.manifest;
+  if (!dynamic_contracts)
+    return;
+  if (dynamic_contracts.generator) {
+    const generatorPath = path.join(context.pluginPath, dynamic_contracts.generator);
+    const possibleExtensions = [".ts", ".js", "/index.ts", "/index.js"];
+    let found = false;
+    for (const ext of possibleExtensions) {
+      if (fs.existsSync(generatorPath + ext)) {
+        found = true;
+        break;
+      }
+    }
+    if (!found && !context.isNpmPackage) {
+      result.errors.push({
+        type: "file-missing",
+        message: `Generator file not found: ${dynamic_contracts.generator}`,
+        location: "plugin.yaml dynamic_contracts",
+        suggestion: `Create generator file at ${generatorPath}.ts`
+      });
+    }
+  }
+  if (dynamic_contracts.component) {
+    const componentPath = path.join(context.pluginPath, dynamic_contracts.component);
+    const possibleExtensions = [".ts", ".js", "/index.ts", "/index.js"];
+    let found = false;
+    for (const ext of possibleExtensions) {
+      if (fs.existsSync(componentPath + ext)) {
+        found = true;
+        break;
+      }
+    }
+    if (!found && !context.isNpmPackage) {
+      result.errors.push({
+        type: "file-missing",
+        message: `Dynamic contracts component not found: ${dynamic_contracts.component}`,
+        location: "plugin.yaml dynamic_contracts",
+        suggestion: `Create component file at ${componentPath}.ts`
+      });
+    }
+  }
+}
+export {
+  validatePlugin
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jay-framework/plugin-validator",
+  "version": "0.10.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Validation tool for Jay Stack plugins",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": ":",
+    "test:watch": ":"
+  },
+  "dependencies": {
+    "@jay-framework/compiler-jay-html": "^0.10.0",
+    "@jay-framework/editor-protocol": "^0.10.0",
+    "chalk": "^4.1.2",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.10.0",
+    "@types/node": "^22.15.21",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}