@objectstack/cli 2.0.7 → 3.0.1

package/src/commands/lint.ts

@@ -0,0 +1,303 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadConfig } from '../utils/config.js';
+import {
+  printHeader,
+  printSuccess,
+  printWarning,
+  printError,
+  printInfo,
+  printStep,
+  createTimer,
+} from '../utils/format.js';
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+type Severity = 'error' | 'warning' | 'suggestion';
+
+interface LintIssue {
+  severity: Severity;
+  rule: string;
+  message: string;
+  path: string;
+  fix?: string;
+}
+
+// ─── Rules ──────────────────────────────────────────────────────────
+
+const SNAKE_CASE_RE = /^[a-z][a-z0-9_]*$/;
+
+function checkSnakeCase(value: string, path: string, label: string): LintIssue | null {
+  if (!SNAKE_CASE_RE.test(value)) {
+    return {
+      severity: 'error',
+      rule: 'naming/snake-case',
+      message: `${label} "${value}" must be snake_case`,
+      path,
+      fix: value.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').replace(/([a-z\d])([A-Z])/g, '$1_$2').toLowerCase().replace(/^_/, '').replace(/-/g, '_'),
+    };
+  }
+  return null;
+}
+
+function checkLabelExists(item: any, path: string, kind: string): LintIssue | null {
+  if (!item.label) {
+    return {
+      severity: 'error',
+      rule: 'required/label',
+      message: `${kind} "${item.name || '?'}" is missing a label`,
+      path,
+    };
+  }
+  return null;
+}
+
+function checkLabelCase(label: string, path: string): LintIssue | null {
+  if (label && label[0] !== label[0].toUpperCase()) {
+    return {
+      severity: 'warning',
+      rule: 'convention/label-case',
+      message: `Label "${label}" should start with an uppercase letter`,
+      path,
+      fix: label.charAt(0).toUpperCase() + label.slice(1),
+    };
+  }
+  return null;
+}
+
+// ─── Lint Engine ────────────────────────────────────────────────────
+
+function lintConfig(config: any): LintIssue[] {
+  const issues: LintIssue[] = [];
+
+  const push = (issue: LintIssue | null) => {
+    if (issue) issues.push(issue);
+  };
+
+  // ── Objects ──
+  const objects: any[] = Array.isArray(config.objects) ? config.objects : [];
+
+  for (let i = 0; i < objects.length; i++) {
+    const obj = objects[i];
+    const objPath = `objects[${i}]`;
+
+    // Object name must be snake_case
+    if (obj.name) {
+      push(checkSnakeCase(obj.name, `${objPath}.name`, 'Object name'));
+    }
+
+    // Object must have label
+    push(checkLabelExists(obj, `${objPath}.label`, 'Object'));
+
+    // Object label conventions
+    if (obj.label) {
+      push(checkLabelCase(obj.label, `${objPath}.label`));
+    }
+
+    // Fields
+    if (obj.fields && typeof obj.fields === 'object') {
+      const fieldNames = Object.keys(obj.fields);
+
+      if (fieldNames.length === 0) {
+        issues.push({
+          severity: 'warning',
+          rule: 'structure/empty-fields',
+          message: `Object "${obj.name || '?'}" has an empty fields map`,
+          path: `${objPath}.fields`,
+        });
+      }
+
+      for (const fieldName of fieldNames) {
+        const field = obj.fields[fieldName];
+        const fieldPath = `${objPath}.fields.${fieldName}`;
+
+        // Field key must be snake_case
+        push(checkSnakeCase(fieldName, fieldPath, 'Field name'));
+
+        // Field must have label
+        if (field && typeof field === 'object') {
+          push(checkLabelExists({ ...field, name: fieldName }, `${fieldPath}.label`, 'Field'));
+          if (field.label) {
+            push(checkLabelCase(field.label, `${fieldPath}.label`));
+          }
+        }
+      }
+    } else if (!obj.fields) {
+      issues.push({
+        severity: 'error',
+        rule: 'structure/no-fields',
+        message: `Object "${obj.name || '?'}" has no fields defined`,
+        path: `${objPath}.fields`,
+      });
+    }
+  }
+
+  // ── Views ──
+  const views: any[] = Array.isArray(config.views) ? config.views : [];
+  for (let i = 0; i < views.length; i++) {
+    const view = views[i];
+    const viewPath = `views[${i}]`;
+    if (view.name) {
+      push(checkSnakeCase(view.name, `${viewPath}.name`, 'View name'));
+    }
+    push(checkLabelExists(view, `${viewPath}.label`, 'View'));
+    if (view.label) {
+      push(checkLabelCase(view.label, `${viewPath}.label`));
+    }
+  }
+
+  // ── Apps ──
+  const apps: any[] = Array.isArray(config.apps) ? config.apps : [];
+  for (let i = 0; i < apps.length; i++) {
+    const app = apps[i];
+    const appPath = `apps[${i}]`;
+    if (app.name) {
+      push(checkSnakeCase(app.name, `${appPath}.name`, 'App name'));
+    }
+    push(checkLabelExists(app, `${appPath}.label`, 'App'));
+    if (app.label) {
+      push(checkLabelCase(app.label, `${appPath}.label`));
+    }
+  }
+
+  // ── Flows ──
+  const flows: any[] = Array.isArray(config.flows) ? config.flows : [];
+  for (let i = 0; i < flows.length; i++) {
+    const flow = flows[i];
+    const flowPath = `flows[${i}]`;
+    if (flow.name) {
+      push(checkSnakeCase(flow.name, `${flowPath}.name`, 'Flow name'));
+    }
+  }
+
+  // ── Agents ──
+  const agents: any[] = Array.isArray(config.agents) ? config.agents : [];
+  for (let i = 0; i < agents.length; i++) {
+    const agent = agents[i];
+    const agentPath = `agents[${i}]`;
+    if (agent.name) {
+      push(checkSnakeCase(agent.name, `${agentPath}.name`, 'Agent name'));
+    }
+  }
+
+  return issues;
+}
+
+// ─── Command ────────────────────────────────────────────────────────
+
+export const lintCommand = new Command('lint')
+  .description('Check ObjectStack configuration for style and convention issues')
+  .argument('[config]', 'Configuration file path')
+  .option('--json', 'Output as JSON')
+  .option('--fix', 'Show what would be fixed (dry-run)')
+  .action(async (configPath, options) => {
+    const timer = createTimer();
+
+    if (!options.json) {
+      printHeader('Lint');
+      printStep('Loading configuration...');
+    }
+
+    try {
+      const { config, absolutePath } = await loadConfig(configPath);
+
+      if (!options.json) {
+        printInfo(`Config: ${chalk.white(absolutePath)}`);
+      }
+
+      const issues = lintConfig(config);
+
+      // ── JSON output ──
+      if (options.json) {
+        const errors = issues.filter((i) => i.severity === 'error');
+        const warnings = issues.filter((i) => i.severity === 'warning');
+        const suggestions = issues.filter((i) => i.severity === 'suggestion');
+        console.log(JSON.stringify({
+          passed: errors.length === 0,
+          total: issues.length,
+          errors: errors.length,
+          warnings: warnings.length,
+          suggestions: suggestions.length,
+          issues,
+          duration: timer.elapsed(),
+        }, null, 2));
+        if (errors.length > 0) process.exit(1);
+        return;
+      }
+
+      console.log('');
+
+      if (issues.length === 0) {
+        printSuccess(`All checks passed ${chalk.dim(`(${timer.display()})`)}`);
+        console.log('');
+        return;
+      }
+
+      // Group by severity
+      const errors = issues.filter((i) => i.severity === 'error');
+      const warnings = issues.filter((i) => i.severity === 'warning');
+      const suggestions = issues.filter((i) => i.severity === 'suggestion');
+
+      const printIssue = (issue: LintIssue) => {
+        const color =
+          issue.severity === 'error' ? chalk.red :
+          issue.severity === 'warning' ? chalk.yellow :
+          chalk.blue;
+        const icon =
+          issue.severity === 'error' ? '✗' :
+          issue.severity === 'warning' ? '⚠' :
+          'ℹ';
+
+        console.log(`  ${color(icon)} ${color(issue.message)}`);
+        console.log(chalk.dim(`    ${issue.rule}  at ${issue.path}`));
+        if (options.fix && issue.fix) {
+          console.log(chalk.green(`    → fix: ${issue.fix}`));
+        }
+      };
+
+      if (errors.length > 0) {
+        console.log(chalk.bold.red(`  Errors (${errors.length})`));
+        errors.forEach(printIssue);
+        console.log('');
+      }
+
+      if (warnings.length > 0) {
+        console.log(chalk.bold.yellow(`  Warnings (${warnings.length})`));
+        warnings.forEach(printIssue);
+        console.log('');
+      }
+
+      if (suggestions.length > 0) {
+        console.log(chalk.bold.blue(`  Suggestions (${suggestions.length})`));
+        suggestions.forEach(printIssue);
+        console.log('');
+      }
+
+      // Summary
+      const parts: string[] = [];
+      if (errors.length > 0) parts.push(chalk.red(`${errors.length} error(s)`));
+      if (warnings.length > 0) parts.push(chalk.yellow(`${warnings.length} warning(s)`));
+      if (suggestions.length > 0) parts.push(chalk.blue(`${suggestions.length} suggestion(s)`));
+      console.log(`  ${parts.join(', ')} ${chalk.dim(`(${timer.display()})`)}`);
+
+      if (options.fix) {
+        console.log('');
+        printInfo('Dry-run mode: no files were modified.');
+      }
+
+      console.log('');
+
+      if (errors.length > 0) process.exit(1);
+
+    } catch (error: any) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error.message }));
+        process.exit(1);
+      }
+      console.log('');
+      printError(error.message || String(error));
+      process.exit(1);
+    }
+  });