@carlonicora/nextjs-jsonapi 1.2.0 → 1.3.0

package/scripts/generate-web-module/utils/bootstrapper-updater.ts

@@ -0,0 +1,145 @@
+/**
+ * Bootstrapper Updater
+ *
+ * Updates the Bootstrapper.ts file to register new modules.
+ */
+
+import * as fs from "fs";
+import { FrontendTemplateData } from "../types/template-data.interface";
+
+const BOOTSTRAPPER_PATH = "apps/web/src/config/Bootstrapper.ts";
+
+export interface BootstrapperUpdateResult {
+  success: boolean;
+  message: string;
+  alreadyRegistered?: boolean;
+}
+
+/**
+ * Update Bootstrapper.ts to add a new module
+ *
+ * @param data - Frontend template data
+ * @param webBasePath - Base path to web app
+ * @param dryRun - Whether to perform a dry run
+ * @returns Update result
+ */
+export function updateBootstrapper(
+  data: FrontendTemplateData,
+  webBasePath: string,
+  dryRun: boolean = false
+): BootstrapperUpdateResult {
+  const { names, targetDir } = data;
+  const bootstrapperPath = `${webBasePath}/${BOOTSTRAPPER_PATH}`;
+
+  // Check if file exists
+  if (!fs.existsSync(bootstrapperPath)) {
+    return {
+      success: false,
+      message: `Bootstrapper.ts not found at ${bootstrapperPath}`,
+    };
+  }
+
+  let content = fs.readFileSync(bootstrapperPath, "utf-8");
+
+  // Check if module is already registered
+  const modulePattern = new RegExp(`${names.pascalCase}Module`, "g");
+  if (modulePattern.test(content)) {
+    return {
+      success: true,
+      message: `Module ${names.pascalCase} already registered in Bootstrapper.ts`,
+      alreadyRegistered: true,
+    };
+  }
+
+  // Add import statement
+  const importStatement = `import { ${names.pascalCase}Module } from "@/features/${targetDir}/${names.kebabCase}/${names.pascalCase}Module";`;
+
+  // Find the right place to insert import (after "// Feature module imports" or at end of imports)
+  const featureImportsMarker = "// Feature module imports";
+  const lastImportMatch = content.match(/^import .* from ".*";$/gm);
+
+  if (content.includes(featureImportsMarker)) {
+    // Find the last import after the marker
+    const markerIndex = content.indexOf(featureImportsMarker);
+    const afterMarker = content.substring(markerIndex);
+    const nextNewlineIndex = afterMarker.indexOf("\n");
+    const insertPosition = markerIndex + nextNewlineIndex;
+
+    // Find next empty line or start of const
+    const afterMarkerContent = content.substring(insertPosition);
+    const constIndex = afterMarkerContent.indexOf("\nconst ");
+
+    if (constIndex > 0) {
+      const insertAt = insertPosition + constIndex;
+      content = content.slice(0, insertAt) + `\n${importStatement}` + content.slice(insertAt);
+    }
+  } else if (lastImportMatch) {
+    // Insert after last import
+    const lastImport = lastImportMatch[lastImportMatch.length - 1];
+    const lastImportIndex = content.lastIndexOf(lastImport);
+    const insertAt = lastImportIndex + lastImport.length;
+    content = content.slice(0, insertAt) + `\n${importStatement}` + content.slice(insertAt);
+  }
+
+  // Add module to allModules object
+  const allModulesPattern = /const allModules = \{[^}]+\}/s;
+  const allModulesMatch = content.match(allModulesPattern);
+
+  if (allModulesMatch) {
+    const allModulesBlock = allModulesMatch[0];
+    // Find the last line before closing brace
+    const lines = allModulesBlock.split("\n");
+    const lastEntryIndex = lines.length - 1;
+
+    // Add new module entry before the closing brace
+    const newEntry = `  ${names.pascalCase}: ${names.pascalCase}Module(moduleFactory),`;
+
+    // Find if there's a trailing comma on the last entry
+    for (let i = lastEntryIndex - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (line && !line.startsWith("//")) {
+        // Add comma if needed
+        if (!line.endsWith(",")) {
+          lines[i] = lines[i].replace(/(\s*)$/, ",$1");
+        }
+        break;
+      }
+    }
+
+    // Insert new entry
+    lines.splice(lastEntryIndex, 0, newEntry);
+    const updatedBlock = lines.join("\n");
+    content = content.replace(allModulesBlock, updatedBlock);
+  }
+
+  if (dryRun) {
+    return {
+      success: true,
+      message: `[DRY RUN] Would update Bootstrapper.ts with ${names.pascalCase}Module`,
+    };
+  }
+
+  // Write updated content
+  fs.writeFileSync(bootstrapperPath, content, "utf-8");
+
+  return {
+    success: true,
+    message: `Updated Bootstrapper.ts with ${names.pascalCase}Module`,
+  };
+}
+
+/**
+ * Generate the import statement for a module
+ */
+export function generateImportStatement(data: FrontendTemplateData): string {
+  const { names, targetDir } = data;
+  return `import { ${names.pascalCase}Module } from "@/features/${targetDir}/${names.kebabCase}/${names.pascalCase}Module";`;
+}
+
+/**
+ * Generate the module registration entry
+ */
+export function generateModuleEntry(data: FrontendTemplateData): string {
+  const { names } = data;
+  return `  ${names.pascalCase}: ${names.pascalCase}Module(moduleFactory),`;
+}

package/scripts/generate-web-module/utils/file-writer.ts

@@ -0,0 +1,115 @@
+/**
+ * File Writer Utility
+ *
+ * Handles file writing with conflict detection and directory creation.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { GeneratedFile } from "../types/template-data.interface";
+
+export interface WriteOptions {
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export interface WriteResult {
+  path: string;
+  status: "created" | "updated" | "skipped" | "dry-run";
+  existed: boolean;
+}
+
+/**
+ * Write a single file to disk
+ *
+ * @param file - Generated file data
+ * @param options - Write options
+ * @returns Write result
+ */
+export function writeFile(file: GeneratedFile, options: WriteOptions = {}): WriteResult {
+  const { dryRun = false, force = false } = options;
+  const existed = fs.existsSync(file.path);
+
+  if (dryRun) {
+    return {
+      path: file.path,
+      status: "dry-run",
+      existed,
+    };
+  }
+
+  // Check if file exists and we're not forcing
+  if (existed && !force) {
+    return {
+      path: file.path,
+      status: "skipped",
+      existed: true,
+    };
+  }
+
+  // Create directory if needed
+  const dir = path.dirname(file.path);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write the file
+  fs.writeFileSync(file.path, file.content, "utf-8");
+
+  return {
+    path: file.path,
+    status: existed ? "updated" : "created",
+    existed,
+  };
+}
+
+/**
+ * Write multiple files to disk
+ *
+ * @param files - Array of generated files
+ * @param options - Write options
+ * @returns Array of write results
+ */
+export function writeFiles(files: GeneratedFile[], options: WriteOptions = {}): WriteResult[] {
+  return files.map((file) => writeFile(file, options));
+}
+
+/**
+ * Print write results to console
+ *
+ * @param results - Array of write results
+ */
+export function printResults(results: WriteResult[]): void {
+  const grouped = {
+    created: results.filter((r) => r.status === "created"),
+    updated: results.filter((r) => r.status === "updated"),
+    skipped: results.filter((r) => r.status === "skipped"),
+    dryRun: results.filter((r) => r.status === "dry-run"),
+  };
+
+  if (grouped.dryRun.length > 0) {
+    console.log("\n📋 DRY RUN - Files that would be created:");
+    grouped.dryRun.forEach((r) => {
+      console.log(`   ${r.existed ? "🔄" : "✨"} ${r.path}`);
+    });
+  }
+
+  if (grouped.created.length > 0) {
+    console.log("\n✨ Created files:");
+    grouped.created.forEach((r) => console.log(`   ${r.path}`));
+  }
+
+  if (grouped.updated.length > 0) {
+    console.log("\n🔄 Updated files:");
+    grouped.updated.forEach((r) => console.log(`   ${r.path}`));
+  }
+
+  if (grouped.skipped.length > 0) {
+    console.log("\n⏭️  Skipped (already exist, use --force to overwrite):");
+    grouped.skipped.forEach((r) => console.log(`   ${r.path}`));
+  }
+
+  console.log(
+    `\nTotal: ${results.length} files (${grouped.created.length} created, ${grouped.updated.length} updated, ${grouped.skipped.length} skipped)`
+  );
+}

package/scripts/generate-web-module/utils/i18n-updater.ts

@@ -0,0 +1,108 @@
+/**
+ * i18n Updater
+ *
+ * Updates the messages/en.json file with new module translations.
+ */
+
+import * as fs from "fs";
+import { FrontendTemplateData } from "../types/template-data.interface";
+import { buildI18nMessages } from "../transformers/i18n-generator";
+
+const MESSAGES_PATH = "apps/web/messages/en.json";
+
+export interface I18nUpdateResult {
+  success: boolean;
+  message: string;
+  alreadyExists?: boolean;
+}
+
+/**
+ * Update messages/en.json with new module translations
+ *
+ * @param data - Frontend template data
+ * @param webBasePath - Base path to web app
+ * @param dryRun - Whether to perform a dry run
+ * @returns Update result
+ */
+export function updateI18n(
+  data: FrontendTemplateData,
+  webBasePath: string,
+  dryRun: boolean = false
+): I18nUpdateResult {
+  const { names, i18nKeys } = data;
+  const messagesPath = `${webBasePath}/${MESSAGES_PATH}`;
+
+  // Check if file exists
+  if (!fs.existsSync(messagesPath)) {
+    return {
+      success: false,
+      message: `Messages file not found at ${messagesPath}`,
+    };
+  }
+
+  const content = fs.readFileSync(messagesPath, "utf-8");
+  let messages: Record<string, any>;
+
+  try {
+    messages = JSON.parse(content);
+  } catch (e) {
+    return {
+      success: false,
+      message: `Failed to parse messages/en.json: ${e}`,
+    };
+  }
+
+  // Check if module already exists in features
+  if (messages.features && messages.features[names.camelCase]) {
+    return {
+      success: true,
+      message: `Module ${names.camelCase} already exists in messages/en.json`,
+      alreadyExists: true,
+    };
+  }
+
+  // Build the i18n messages for this module
+  const moduleMessages = buildI18nMessages(i18nKeys);
+
+  // Add to features section
+  if (!messages.features) {
+    messages.features = {};
+  }
+  messages.features[names.camelCase] = moduleMessages.features[i18nKeys.moduleName];
+
+  // Add to types section (if not exists)
+  if (!messages.types) {
+    messages.types = {};
+  }
+  const typesKey = Object.keys(moduleMessages.types)[0];
+  if (typesKey && !messages.types[names.pluralCamel]) {
+    messages.types[names.pluralCamel] = moduleMessages.types[typesKey];
+  }
+
+  if (dryRun) {
+    return {
+      success: true,
+      message: `[DRY RUN] Would update messages/en.json with ${names.camelCase} translations`,
+    };
+  }
+
+  // Write updated content with proper formatting
+  const updatedContent = JSON.stringify(messages, null, 2);
+  fs.writeFileSync(messagesPath, updatedContent, "utf-8");
+
+  return {
+    success: true,
+    message: `Updated messages/en.json with ${names.camelCase} translations`,
+  };
+}
+
+/**
+ * Preview the i18n messages that would be added
+ *
+ * @param data - Frontend template data
+ * @returns Preview of messages
+ */
+export function previewI18nMessages(data: FrontendTemplateData): string {
+  const moduleMessages = buildI18nMessages(data.i18nKeys);
+  return JSON.stringify(moduleMessages, null, 2);
+}

package/scripts/generate-web-module/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Utils Index
+ *
+ * Exports all utility functions.
+ */
+
+export { writeFile, writeFiles, printResults, type WriteOptions, type WriteResult } from "./file-writer";
+export { updateBootstrapper, generateImportStatement, generateModuleEntry, type BootstrapperUpdateResult } from "./bootstrapper-updater";
+export { updateI18n, previewI18nMessages, type I18nUpdateResult } from "./i18n-updater";

package/scripts/generate-web-module/validators/json-schema-validator.ts

@@ -0,0 +1,306 @@
+/**
+ * JSON Schema Validator
+ *
+ * Validates JSON module definition files for the frontend generator.
+ * Note: Backend-specific fields (toNode, relationshipName) are warnings, not errors.
+ */
+
+import { JsonModuleDefinition } from "../types/json-schema.interface";
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  severity: "error" | "warning";
+}
+
+/**
+ * Validate JSON module definition for frontend generation
+ *
+ * @param schema - JSON module definition
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateJsonSchema(schema: any): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Required fields
+  const required = ["moduleName", "endpointName", "targetDir"];
+  for (const field of required) {
+    if (!schema[field]) {
+      errors.push({
+        field,
+        message: `${field} is required`,
+        severity: "error",
+      });
+    }
+  }
+
+  // Module name format (PascalCase)
+  if (schema.moduleName && !/^[A-Z][a-zA-Z0-9]*$/.test(schema.moduleName)) {
+    errors.push({
+      field: "moduleName",
+      message: 'Must be PascalCase (e.g., "Comment", "Discussion")',
+      severity: "error",
+    });
+  }
+
+  // Endpoint format (kebab-case plural)
+  if (schema.endpointName && !/^[a-z][a-z0-9-]*$/.test(schema.endpointName)) {
+    errors.push({
+      field: "endpointName",
+      message: 'Must be kebab-case (e.g., "comments", "discussions")',
+      severity: "error",
+    });
+  }
+
+  // Target directory validation
+  if (schema.targetDir && !["features", "foundations"].includes(schema.targetDir)) {
+    errors.push({
+      field: "targetDir",
+      message: 'Must be either "features" or "foundations"',
+      severity: "error",
+    });
+  }
+
+  // Module ID validation (required for frontend)
+  if (!schema.moduleId) {
+    errors.push({
+      field: "moduleId",
+      message: "moduleId is required for frontend module registration",
+      severity: "error",
+    });
+  } else if (!/^[a-f0-9-]{36}$/i.test(schema.moduleId)) {
+    errors.push({
+      field: "moduleId",
+      message: "moduleId must be a valid UUID",
+      severity: "warning",
+    });
+  }
+
+  // Fields validation
+  if (schema.fields && Array.isArray(schema.fields)) {
+    schema.fields.forEach((field: any, index: number) => {
+      if (!field.name) {
+        errors.push({
+          field: `fields[${index}].name`,
+          message: "Field name is required",
+          severity: "error",
+        });
+      }
+
+      if (!field.type) {
+        errors.push({
+          field: `fields[${index}].type`,
+          message: "Field type is required",
+          severity: "error",
+        });
+      }
+
+      if (field.nullable === undefined) {
+        errors.push({
+          field: `fields[${index}].nullable`,
+          message: "Field nullable flag is required",
+          severity: "error",
+        });
+      }
+
+      // Validate known types
+      const validTypes = ["string", "number", "boolean", "date", "any"];
+      if (field.type && !validTypes.includes(field.type)) {
+        errors.push({
+          field: `fields[${index}].type`,
+          message: `Unknown type "${field.type}". Valid types: ${validTypes.join(", ")}`,
+          severity: "warning",
+        });
+      }
+    });
+  }
+
+  // Relationships validation
+  if (schema.relationships && Array.isArray(schema.relationships)) {
+    schema.relationships.forEach((rel: any, index: number) => {
+      if (!rel.name) {
+        errors.push({
+          field: `relationships[${index}].name`,
+          message: "Relationship name is required",
+          severity: "error",
+        });
+      }
+
+      if (!rel.directory) {
+        errors.push({
+          field: `relationships[${index}].directory`,
+          message: "Relationship directory is required",
+          severity: "error",
+        });
+      }
+
+      // Directory should be features or foundations
+      if (rel.directory && !["features", "foundations"].includes(rel.directory)) {
+        errors.push({
+          field: `relationships[${index}].directory`,
+          message: 'Relationship directory should be "features" or "foundations"',
+          severity: "warning",
+        });
+      }
+
+      if (rel.single === undefined) {
+        errors.push({
+          field: `relationships[${index}].single`,
+          message: "Relationship single flag is required",
+          severity: "error",
+        });
+      }
+
+      if (rel.nullable === undefined) {
+        errors.push({
+          field: `relationships[${index}].nullable`,
+          message: "Relationship nullable flag is required",
+          severity: "error",
+        });
+      }
+
+      // Backend-specific fields are warnings only (not used in frontend)
+      if (!rel.relationshipName) {
+        errors.push({
+          field: `relationships[${index}].relationshipName`,
+          message: "relationshipName missing (backend-specific, not used in frontend)",
+          severity: "warning",
+        });
+      }
+
+      if (rel.toNode === undefined) {
+        errors.push({
+          field: `relationships[${index}].toNode`,
+          message: "toNode missing (backend-specific, not used in frontend)",
+          severity: "warning",
+        });
+      }
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Format validation errors for display
+ *
+ * @param errors - Validation errors
+ * @returns Formatted error message
+ */
+export function formatValidationErrors(errors: ValidationError[]): string {
+  if (errors.length === 0) {
+    return "No validation errors";
+  }
+
+  const errorCount = errors.filter((e) => e.severity === "error").length;
+  const warningCount = errors.filter((e) => e.severity === "warning").length;
+
+  const lines: string[] = [];
+
+  if (errorCount > 0) {
+    lines.push(`\n❌ ${errorCount} error(s):`);
+    errors
+      .filter((e) => e.severity === "error")
+      .forEach((error) => {
+        lines.push(`   • ${error.field}: ${error.message}`);
+      });
+  }
+
+  if (warningCount > 0) {
+    lines.push(`\n⚠️  ${warningCount} warning(s):`);
+    errors
+      .filter((e) => e.severity === "warning")
+      .forEach((error) => {
+        lines.push(`   • ${error.field}: ${error.message}`);
+      });
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Validation result interface
+ */
+export interface ValidationResult {
+  data: JsonModuleDefinition | null;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Validate and parse JSON file from path
+ *
+ * @param filePath - Path to JSON file
+ * @returns Validation result with data, errors, and warnings
+ */
+export function parseAndValidate(filePath: string): ValidationResult {
+  const result: ValidationResult = {
+    data: null,
+    errors: [],
+    warnings: [],
+  };
+
+  // Read file
+  let content: string;
+  try {
+    const fs = require("fs");
+    if (!fs.existsSync(filePath)) {
+      result.errors.push(`File not found: ${filePath}`);
+      return result;
+    }
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (e) {
+    result.errors.push(`Failed to read file: ${(e as Error).message}`);
+    return result;
+  }
+
+  // Parse JSON
+  let schema: any;
+  try {
+    schema = JSON.parse(content);
+  } catch (e) {
+    result.errors.push(`Invalid JSON: ${(e as Error).message}`);
+    return result;
+  }
+
+  // Handle array format (for bulk import compatibility)
+  if (Array.isArray(schema)) {
+    if (schema.length === 0) {
+      result.errors.push("JSON array is empty");
+      return result;
+    }
+    if (schema.length > 1) {
+      result.warnings.push(
+        `JSON file contains ${schema.length} definitions. Only processing the first one.`
+      );
+    }
+    schema = schema[0];
+  }
+
+  // Validate
+  const validationErrors = validateJsonSchema(schema);
+
+  // Separate errors and warnings
+  validationErrors.forEach((ve) => {
+    const msg = `${ve.field}: ${ve.message}`;
+    if (ve.severity === "error") {
+      result.errors.push(msg);
+    } else {
+      result.warnings.push(msg);
+    }
+  });
+
+  // Only set data if validation passed
+  if (result.errors.length === 0) {
+    result.data = schema as JsonModuleDefinition;
+  }
+
+  return result;
+}
+
+/**
+ * Check if validation result passed (no errors)
+ */
+export function validationPassed(result: ValidationResult): boolean {
+  return result.errors.length === 0 && result.data !== null;
+}