Add custom ESLint rule to enforce block style guide

Co-authored-by: rita-gorokhod <60586879+rita-gorokhod@users.noreply.github.com>

Author: Copilot

.eslintrc.json

@@ -1,7 +1,7 @@
 {
   "root": true,
   "ignorePatterns": ["**/*", "deploy/**/*"],
-  "plugins": ["@nx"],
+  "plugins": ["@nx", "@openops/block-style"],
   "overrides": [
     {
       "files": ["*.ts", "*.tsx", "*.js", "*.jsx", "*.json"],
@@ -51,6 +51,12 @@
         "jest": true
       },
       "rules": {}
+    },
+    {
+      "files": ["packages/blocks/**/*.ts"],
+      "rules": {
+        "@openops/block-style/block-style-guide": "error"
+      }
     }
   ],
   "settings": {
@@ -65,5 +71,8 @@
         "project": ["tsconfig.json", "package/tsconfig.json"]
       }
     }
+  },
+  "plugins": {
+    "@openops/block-style": "./tools/eslint-rules"
   }
 }

tools/eslint-rules/README.md

@@ -0,0 +1,165 @@
+# OpenOps Block Style Guide ESLint Plugin
+
+Custom ESLint plugin to enforce style guide rules for `displayName` and `description` fields in OpenOps blocks.
+
+## Rules
+
+### `block-style-guide`
+
+Enforces the following style guide rules for block definitions:
+
+#### 1. displayName - Title Case
+- Must be in Title Case (first letter of each word capitalized)
+- Exception: small words like "a", "and", "the", "of" can be lowercase (unless first word)
+- Acronyms (API, SQL, UUID, HTTP, etc.) should remain uppercase
+
+**Examples:**
+```typescript
+// ✓ Good
+displayName: 'Get Recommendations'
+displayName: 'Execute SQL Statement'
+displayName: 'Send HTTP Request'
+displayName: 'Order By'
+
+// ✗ Bad
+displayName: 'get recommendations'
+displayName: 'Execute sql statement'
+displayName: 'send Http request'
+```
+
+#### 2. description - Sentence Case
+- Must start with a capital letter
+- Should NOT end with a period (unless multiple sentences)
+- Use imperative form for actions (Get, Create, Send) not third-person (Gets, Creates, Sends)
+
+**Examples:**
+```typescript
+// ✓ Good
+description: 'Get cost recommendations from the provider'
+description: 'Send an email using SMTP. Supports attachments and HTML content.'
+
+// ✗ Bad
+description: 'get cost recommendations'
+description: 'Get cost recommendations from the provider.'  // No period for single sentence
+description: 'Gets cost recommendations'  // Use imperative, not third-person
+```
+
+#### 3. displayName and description Must Be Distinct
+- displayName and description should not be the same or too similar (>80% similarity)
+
+**Examples:**
+```typescript
+// ✓ Good
+displayName: 'Get Recommendations'
+description: 'Fetch cost optimization suggestions from the provider'
+
+// ✗ Bad
+displayName: 'Get Recommendations'
+description: 'Get recommendations'  // Too similar
+```
+
+#### 4. description Must Not Be Empty
+- Every description field must have meaningful content
+
+**Examples:**
+```typescript
+// ✓ Good
+description: 'Create a new item in the database'
+
+// ✗ Bad
+description: ''
+description: '  '
+```
+
+#### 5. Action displayNames Should Use Verbs
+- For actions, displayName should start with an action verb
+- Common verbs: Get, Create, Update, Delete, Send, Execute, Run, Add, Remove, etc.
+
+**Examples:**
+```typescript
+// ✓ Good (in createAction context)
+displayName: 'Get User Profile'
+displayName: 'Create Database Entry'
+displayName: 'Send Notification'
+
+// ✗ Bad (in createAction context)
+displayName: 'User Profile'  // Missing verb
+displayName: 'Database Entry Creation'  // Not verb-first
+```
+
+## Installation
+
+The plugin is already integrated into the OpenOps monorepo. To enable it:
+
+1. The plugin is located in `tools/eslint-rules/`
+2. It's configured in `.eslintrc.json` for the blocks package
+
+## Usage
+
+The rule runs automatically when you run ESLint:
+
+```bash
+# Lint all files
+npm run lint
+
+# Lint blocks specifically
+npx nx lint blocks
+
+# Auto-fix issues where possible
+npx nx lint blocks --fix
+```
+
+## Configuration
+
+The rule is enabled by default for the blocks package. You can configure it in `.eslintrc.json`:
+
+```json
+{
+  "rules": {
+    "@openops/block-style/block-style-guide": "error"
+  }
+}
+```
+
+## Development
+
+To test the rule:
+
+```bash
+# From the tools/eslint-rules directory
+npm test
+
+# Or test against actual block files
+npx eslint packages/blocks/*/src/**/*.ts
+```
+
+## Error Messages
+
+The rule provides specific error messages for each violation:
+
+- `displayNameNotTitleCase`: displayName should be in Title Case
+- `descriptionNotSentenceCase`: description should start with a capital letter
+- `descriptionTrailingPeriod`: description should not end with a period (unless multiple sentences)
+- `descriptionEmpty`: description must not be empty
+- `displayNameDescriptionSimilar`: displayName and description are too similar
+- `actionDisplayNameNotVerb`: Action displayName should start with a verb
+
+## Examples
+
+### Before (Violations)
+```typescript
+createAction({
+  displayName: 'get recommendations',  // Not Title Case
+  description: 'Gets recommendations.',  // Third-person verb + trailing period
+  // ...
+});
+```
+
+### After (Compliant)
+```typescript
+createAction({
+  displayName: 'Get Recommendations',  // Title Case
+  description: 'Get cost optimization recommendations from the provider',  // Imperative, no period
+  // ...
+});
+```

tools/eslint-rules/examples.ts

@@ -0,0 +1,108 @@
+/**
+ * Test examples for the block-style-guide ESLint rule
+ * 
+ * These examples demonstrate violations and correct usage
+ */
+
+// ❌ VIOLATIONS - These will trigger ESLint errors
+
+// Violation: displayName not in Title Case
+const badAction1 = {
+  displayName: 'get recommendations',  // Should be "Get Recommendations"
+  description: 'Get cost optimization recommendations',
+};
+
+// Violation: description with trailing period (single sentence)
+const badAction2 = {
+  displayName: 'Get Recommendations',
+  description: 'Get cost optimization recommendations.',  // Remove period
+};
+
+// Violation: description not starting with capital
+const badAction3 = {
+  displayName: 'Send Email',
+  description: 'send an email using SMTP',  // Should start with capital
+};
+
+// Violation: empty description
+const badAction4 = {
+  displayName: 'Create User',
+  description: '',  // Must not be empty
+};
+
+// Violation: displayName and description too similar
+const badAction5 = {
+  displayName: 'Delete Record',
+  description: 'Delete record',  // Too similar to displayName
+};
+
+// Violation: Action displayName not starting with verb
+const badAction6 = {
+  displayName: 'User Profile',  // Should be "Get User Profile" or similar
+  description: 'Get the user profile information',
+};
+
+// Violation: Using third-person verb
+const badAction7 = {
+  displayName: 'Update Settings',
+  description: 'Updates the application settings',  // Should be "Update" not "Updates"
+};
+
+// ✅ CORRECT USAGE - These pass the linter
+
+const goodAction1 = {
+  displayName: 'Get Recommendations',
+  description: 'Get cost optimization recommendations from the provider',
+};
+
+const goodAction2 = {
+  displayName: 'Send HTTP Request',
+  description: 'Send an HTTP request to a specified URL',
+};
+
+const goodAction3 = {
+  displayName: 'Execute SQL Statement',
+  description: 'Run an SQL query in a Databricks workspace and retrieve results',
+};
+
+const goodAction4 = {
+  displayName: 'Create Database Entry',
+  description: 'Create a new entry in the database with the provided data',
+};
+
+const goodAction5 = {
+  displayName: 'Update User Profile',
+  description: 'Update the user profile with new information. Validates all fields before saving.',  // Multiple sentences OK with period
+};
+
+const goodTrigger1 = {
+  displayName: 'New Email',
+  description: 'Trigger when a new email arrives in the inbox',
+};
+
+const goodProperty1 = {
+  displayName: 'API Token',
+  description: 'Authentication token for API access',
+};
+
+const goodProperty2 = {
+  displayName: 'Order By',
+  description: 'Sort the results by the specified field',
+};
+
+// Edge cases that should pass
+
+const edgeCaseAcronyms = {
+  displayName: 'Send HTTP Request via API',  // Acronyms OK
+  description: 'Send an HTTP request using the REST API endpoint',
+};
+
+const edgeCaseParentheses = {
+  displayName: 'Get Volume IOPS (GB)',  // Parentheses OK
+  description: 'Get the IOPS value for the volume in gigabytes',
+};
+
+const edgeCaseSpecialChars = {
+  displayName: 'Execute SQL Query',
+  description: 'Execute an SQL query (not a SQL) in the database',  // "an SQL" is correct
+};

tools/eslint-rules/index.js

@@ -0,0 +1,9 @@
+/**
+ * Custom ESLint plugin for OpenOps block style guide enforcement
+ */
+
+module.exports = {
+  rules: {
+    'block-style-guide': require('./rules/block-style-guide'),
+  },
+};

tools/eslint-rules/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@openops/eslint-plugin-block-style",
+  "version": "1.0.0",
+  "description": "ESLint plugin to enforce OpenOps block style guide",
+  "main": "index.js",
+  "keywords": ["eslint", "eslintplugin", "openops", "blocks"],
+  "author": "OpenOps",
+  "license": "MIT"
+}