@memberjunction/react-test-harness 2.96.0 → 2.97.0

package/dist/lib/component-linter.js

@@ -222,14 +222,16 @@ class ComponentLinter {
             }
             // If we have critical syntax errors, return immediately with those
             if (syntaxViolations.length > 0) {
+                // Add suggestions directly to syntax violations
+                this.generateSyntaxErrorSuggestions(syntaxViolations);
                 return {
                     success: false,
                     violations: syntaxViolations,
-                    suggestions: this.generateSyntaxErrorSuggestions(syntaxViolations),
                     criticalCount: syntaxViolations.length,
                     highCount: 0,
                     mediumCount: 0,
-                    lowCount: 0
+                    lowCount: 0,
+                    hasErrors: true
                 };
             }
             // Continue with existing linting logic
@@ -299,16 +301,16 @@ class ComponentLinter {
                 }
                 console.log('');
             }
-            // Generate fix suggestions
-            const suggestions = this.generateFixSuggestions(uniqueViolations);
+            // Add suggestions directly to violations
+            this.addSuggestionsToViolations(uniqueViolations);
             return {
                 success: criticalCount === 0 && highCount === 0, // Only fail on critical/high
                 violations: uniqueViolations,
-                suggestions,
                 criticalCount,
                 highCount,
                 mediumCount,
-                lowCount
+                lowCount,
+                hasErrors: criticalCount > 0 || highCount > 0
             };
         }
         catch (error) {
@@ -322,7 +324,7 @@ class ComponentLinter {
                         column: 0,
                         message: `Failed to parse component: ${error instanceof Error ? error.message : 'Unknown error'}`
                     }],
-                suggestions: []
+                hasErrors: true
             };
         }
     }
@@ -690,14 +692,17 @@ class ComponentLinter {
         });
         return unique;
     }
-    static generateFixSuggestions(violations) {
-        const suggestions = [];
+    /**
+     * Adds suggestions directly to violations based on their rule type
+     * @param violations Array of violations to enhance with suggestions
+     * @returns The same violations array with suggestions embedded
+     */
+    static addSuggestionsToViolations(violations) {
         for (const violation of violations) {
             switch (violation.rule) {
                 case 'no-import-statements':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Remove all import statements. Interactive components receive everything through props.',
+                    violation.suggestion = {
+                        text: 'Remove all import statements. Interactive components receive everything through props.',
                         example: `// ❌ WRONG - Using import statements:
 import React from 'react';
 import { useState } from 'react';
@@ -725,12 +730,11 @@ function MyComponent({ utilities, styles, components }) {
 // 2. Passed through the 'components' prop (child components)
 // 3. Passed through the 'styles' prop (styling)
 // 4. Available globally (React hooks)`
-                    });
+                    };
                     break;
                 case 'no-export-statements':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Remove all export statements. The component function should be the only code, not exported.',
+                    violation.suggestion = {
+                        text: 'Remove all export statements. The component function should be the only code, not exported.',
                         example: `// ❌ WRONG - Using export:
 export function MyComponent({ utilities }) {
   return <div>Hello</div>;
@@ -752,12 +756,11 @@ function MyComponent({ utilities, styles, components }) {
 // The component is self-contained.
 // No exports needed - the host environment
 // will execute the function directly.`
-                    });
+                    };
                     break;
                 case 'no-require-statements':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Remove all require() and dynamic import() statements. Use props instead.',
+                    violation.suggestion = {
+                        text: 'Remove all require() and dynamic import() statements. Use props instead.',
                         example: `// ❌ WRONG - Using require or dynamic import:
 function MyComponent({ utilities }) {
   const lodash = require('lodash');
@@ -788,12 +791,11 @@ function MyComponent({ utilities, styles, components }) {
 // - Passed via props (utilities, components, styles)
 // - Available globally (React hooks)
 // No module loading allowed!`
-                    });
+                    };
                     break;
                 case 'use-function-declaration':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use function declaration syntax for TOP-LEVEL component definitions. Arrow functions are fine inside components.',
+                    violation.suggestion = {
+                        text: 'Use function declaration syntax for TOP-LEVEL component definitions. Arrow functions are fine inside components.',
                         example: `// ❌ WRONG - Top-level arrow function component:
 const MyComponent = ({ utilities, styles, components }) => {
   const [state, setState] = useState('');
@@ -826,12 +828,11 @@ function ChildComponent() {
 // 3. Hoisting allows flexible code organization
 // 4. Consistent with React documentation patterns
 // 5. Easier to distinguish from regular variables`
-                    });
+                    };
                     break;
                 case 'no-return-component':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Remove the return statement at the end of the file. The component function should stand alone.',
+                    violation.suggestion = {
+                        text: 'Remove the return statement at the end of the file. The component function should stand alone.',
                         example: `// ❌ WRONG - Returning the component:
 function MyComponent({ utilities, styles, components }) {
   const [state, setState] = useState('');
@@ -858,12 +859,11 @@ function MyComponent({ utilities, styles, components }) {
 
 // The runtime will find and execute your component
 // by its function name. No need to return or reference it!`
-                    });
+                    };
                     break;
                 case 'no-iife-wrapper':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Remove the IIFE wrapper. Component code should be plain functions, not wrapped in immediately invoked functions.',
+                    violation.suggestion = {
+                        text: 'Remove the IIFE wrapper. Component code should be plain functions, not wrapped in immediately invoked functions.',
                         example: `// ❌ WRONG - IIFE wrapper patterns:
 (function() {
   function MyComponent({ utilities, styles, components }) {
@@ -897,12 +897,11 @@ function MyComponent({ utilities, styles, components }) {
 // 3. IIFEs prevent proper component discovery
 // 4. Makes debugging harder
 // 5. Unnecessary complexity`
-                    });
+                    };
                     break;
                 case 'full-state-ownership':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Components must manage ALL their own state internally. Use proper naming conventions for initialization.',
+                    violation.suggestion = {
+                        text: 'Components must manage ALL their own state internally. Use proper naming conventions for initialization.',
                         example: `// ❌ WRONG - Controlled state props:
 function PaginationControls({ currentPage, filters, sortBy, onPageChange }) {
   // These props suggest parent controls the state - WRONG!
@@ -962,12 +961,11 @@ function DataTable({
 // - Direct state names (currentPage, selectedId, activeTab)
 // - State without 'initial'/'default' prefix (sortBy, filters, searchTerm)
 // - Controlled patterns (value + onChange, checked + onChange)`
-                    });
+                    };
                     break;
                 case 'no-use-reducer':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use useState for state management, not useReducer',
+                    violation.suggestion = {
+                        text: 'Use useState for state management, not useReducer',
                         example: `// Instead of:
 const [state, dispatch] = useReducer(reducer, initialState);
 
@@ -990,12 +988,11 @@ function Component({ savedUserSettings, onSaveUserSettings }) {
     }
   };
 }`
-                    });
+                    };
                     break;
                 case 'no-data-prop':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Replace generic data prop with specific named props',
+                    violation.suggestion = {
+                        text: 'Replace generic data prop with specific named props',
                         example: `// Instead of:
 function Component({ data, savedUserSettings, onSaveUserSettings }) {
   return <div>{data.items.map(...)}</div>;
@@ -1013,12 +1010,11 @@ function Component({ items, customers, savedUserSettings, onSaveUserSettings })
 
 // Load data using utilities:
 const result = await utilities.rv.RunView({ entityName: 'Items' });`
-                    });
+                    };
                     break;
                 case 'saved-user-settings-pattern':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Only save important user preferences, not ephemeral UI state',
+                    violation.suggestion = {
+                        text: 'Only save important user preferences, not ephemeral UI state',
                         example: `// ✅ SAVE these (important preferences):
 - Selected items/tabs: selectedCustomerId, activeTab
 - Sort preferences: sortBy, sortDirection  
@@ -1043,12 +1039,11 @@ const handleSelect = (id) => {
     selectedId: id
   });
 };`
-                    });
+                    };
                     break;
                 case 'pass-standard-props':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Always pass standard props to all components',
+                    violation.suggestion = {
+                        text: 'Always pass standard props to all components',
                         example: `// Always include these props when calling components:
 <ChildComponent
   items={items}  // Data props
@@ -1063,19 +1058,17 @@ const handleSelect = (id) => {
   components={components}
   callbacks={callbacks}
 />`
-                    });
+                    };
                     break;
                 case 'no-child-implementation':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Remove child component implementations. Only the root component function should be in this file',
+                    violation.suggestion = {
+                        text: 'Remove child component implementations. Only the root component function should be in this file',
                         example: 'Move child component functions to separate generation requests'
-                    });
+                    };
                     break;
                 case 'undefined-component-usage':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Ensure all components destructured from the components prop are defined in the component spec dependencies',
+                    violation.suggestion = {
+                        text: 'Ensure all components destructured from the components prop are defined in the component spec dependencies',
                         example: `// Component spec should include all referenced components:
 {
   "name": "MyComponent",
@@ -1100,12 +1093,11 @@ const handleSelect = (id) => {
 // Then in your component:
 const { ModelTreeView, PromptTable, FilterPanel } = components;
 // All these will be available`
-                    });
+                    };
                     break;
                 case 'component-usage-without-destructuring':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Components must be properly accessed - either destructure from components prop or use dot notation',
+                    violation.suggestion = {
+                        text: 'Components must be properly accessed - either destructure from components prop or use dot notation',
                         example: `// ❌ WRONG - Using component without destructuring:
 function MyComponent({ components }) {
   return <AccountList />; // Error: AccountList not destructured
@@ -1126,12 +1118,11 @@ function MyComponent({ components }) {
 function MyComponent({ components: { AccountList } }) {
   return <AccountList />;
 }`
-                    });
+                    };
                     break;
                 case 'unsafe-array-access':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Always check array bounds before accessing elements',
+                    violation.suggestion = {
+                        text: 'Always check array bounds before accessing elements',
                         example: `// ❌ UNSAFE:
 const firstItem = items[0].name;
 const total = data[0].reduce((sum, item) => sum + item.value, 0);
@@ -1145,12 +1136,11 @@ const total = data.length > 0
 // ✅ BETTER - Use optional chaining:
 const firstItem = items[0]?.name || 'No items';
 const total = data[0]?.reduce((sum, item) => sum + item.value, 0) || 0;`
-                    });
+                    };
                     break;
                 case 'array-reduce-safety':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Always provide an initial value for reduce() or check array length',
+                    violation.suggestion = {
+                        text: 'Always provide an initial value for reduce() or check array length',
                         example: `// ❌ UNSAFE:
 const sum = numbers.reduce((a, b) => a + b); // Fails on empty array
 const total = data[0].reduce((sum, item) => sum + item.value); // Multiple issues
@@ -1165,12 +1155,11 @@ const total = data.length > 0 && data[0]
 const sum = numbers.length > 0 
   ? numbers.reduce((a, b) => a + b)
   : 0;`
-                    });
+                    };
                     break;
                 case 'entity-name-mismatch':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use the exact entity name from dataRequirements in RunView calls',
+                    violation.suggestion = {
+                        text: 'Use the exact entity name from dataRequirements in RunView calls',
                         example: `// The component spec defines the entities to use:
 // dataRequirements: {
 //   entities: [
@@ -1198,12 +1187,11 @@ await utilities.rv.RunViews([
 
 // The linter validates that all entity names in RunView/RunViews calls
 // match those declared in the component spec's dataRequirements`
-                    });
+                    };
                     break;
                 case 'missing-query-parameter':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Provide all required parameters defined in dataRequirements for the query',
+                    violation.suggestion = {
+                        text: 'Provide all required parameters defined in dataRequirements for the query',
                         example: `// The component spec defines required parameters:
 // dataRequirements: {
 //   queries: [
@@ -1234,12 +1222,11 @@ await utilities.rq.RunQuery({
     StartDate: startDate  // All parameters included
   }
 });`
-                    });
+                    };
                     break;
                 case 'unknown-query-parameter':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Only use parameters that are defined in dataRequirements for the query',
+                    violation.suggestion = {
+                        text: 'Only use parameters that are defined in dataRequirements for the query',
                         example: `// ❌ WRONG - Using undefined parameter:
 await utilities.rq.RunQuery({
   QueryName: "User Activity Summary",
@@ -1258,12 +1245,11 @@ await utilities.rq.RunQuery({
     StartDate: startDate  // Only parameters from dataRequirements
   }
 });`
-                    });
+                    };
                     break;
                 case 'missing-parameters-object':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Queries with parameters must include a Parameters object in RunQuery',
+                    violation.suggestion = {
+                        text: 'Queries with parameters must include a Parameters object in RunQuery',
                         example: `// ❌ WRONG - Query requires parameters but none provided:
 await utilities.rq.RunQuery({
   QueryName: "User Activity Summary"
@@ -1278,12 +1264,11 @@ await utilities.rq.RunQuery({
     StartDate: startDate
   }
 });`
-                    });
+                    };
                     break;
                 case 'query-name-mismatch':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use the exact query name from dataRequirements in RunQuery calls',
+                    violation.suggestion = {
+                        text: 'Use the exact query name from dataRequirements in RunQuery calls',
                         example: `// The component spec defines the queries to use:
 // dataRequirements: {
 //   queries: [
@@ -1305,12 +1290,11 @@ await utilities.rv.RunQuery({
 
 // The linter validates that all query names in RunQuery calls
 // match those declared in the component spec's dataRequirements.queries`
-                    });
+                    };
                     break;
                 case 'runview-sql-function':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'RunView does not support SQL aggregations. Use RunQuery or aggregate in JavaScript.',
+                    violation.suggestion = {
+                        text: 'RunView does not support SQL aggregations. Use RunQuery or aggregate in JavaScript.',
                         example: `// ❌ WRONG - SQL functions in RunView:
 await utilities.rv.RunView({
   EntityName: 'Accounts',
@@ -1332,12 +1316,11 @@ if (result?.Success) {
   const total = result.Results.length;
   const totalRevenue = result.Results.reduce((sum, acc) => sum + (acc.Revenue || 0), 0);
 }`
-                    });
+                    };
                     break;
                 case 'field-not-in-requirements':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Only use fields that are defined in dataRequirements for the entity',
+                    violation.suggestion = {
+                        text: 'Only use fields that are defined in dataRequirements for the entity',
                         example: `// Check your dataRequirements to see allowed fields:
 // dataRequirements: {
 //   entities: [{
@@ -1359,12 +1342,11 @@ await utilities.rv.RunView({
   EntityName: 'Accounts',
   Fields: ['ID', 'AccountName', 'Industry'] // All from displayFields
 });`
-                    });
+                    };
                     break;
                 case 'orderby-field-not-sortable':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'OrderBy fields must be in the sortFields array for the entity',
+                    violation.suggestion = {
+                        text: 'OrderBy fields must be in the sortFields array for the entity',
                         example: `// ❌ WRONG - Sorting by non-sortable field:
 await utilities.rv.RunView({
   EntityName: 'Accounts',
@@ -1376,12 +1358,11 @@ await utilities.rv.RunView({
   EntityName: 'Accounts',
   OrderBy: 'AccountName ASC' // AccountName is in sortFields
 });`
-                    });
+                    };
                     break;
                 case 'parent-event-callback-usage':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Components must invoke parent event callbacks when state changes',
+                    violation.suggestion = {
+                        text: 'Components must invoke parent event callbacks when state changes',
                         example: `// ❌ WRONG - Only updating internal state:
 function ChildComponent({ onSelectAccount, savedUserSettings, onSaveUserSettings }) {
   const [selectedAccountId, setSelectedAccountId] = useState(savedUserSettings?.selectedAccountId);
@@ -1410,12 +1391,11 @@ function ChildComponent({ onSelectAccount, savedUserSettings, onSaveUserSettings
     onSaveUserSettings?.({ ...savedUserSettings, selectedAccountId: accountId });
   };
 }`
-                    });
+                    };
                     break;
                 case 'property-name-consistency':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Maintain consistent property names when transforming data',
+                    violation.suggestion = {
+                        text: 'Maintain consistent property names when transforming data',
                         example: `// ❌ WRONG - Transform to camelCase but access as PascalCase:
 setAccountData(results.map(item => ({
   accountName: item.AccountName,      // camelCase
@@ -1442,12 +1422,11 @@ setAccountData(results.map(item => ({
 // Later in render...
 <td>{account.accountName}</td>        // Use camelCase consistently
 <td>{formatCurrency(account.annualRevenue)}</td> // Works!`
-                    });
+                    };
                     break;
                 case 'noisy-settings-updates':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Save settings sparingly - only on meaningful user actions',
+                    violation.suggestion = {
+                        text: 'Save settings sparingly - only on meaningful user actions',
                         example: `// ❌ WRONG - Saving on every keystroke:
 const handleSearchChange = (e) => {
   setSearchTerm(e.target.value);
@@ -1468,12 +1447,11 @@ const saveSearchTerm = useMemo(() =>
   }, 500),
   [savedUserSettings]
 );`
-                    });
+                    };
                     break;
                 case 'prop-state-sync':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Initialize state once, don\'t sync from props',
+                    violation.suggestion = {
+                        text: 'Initialize state once, don\'t sync from props',
                         example: `// ❌ WRONG - Syncing prop to state:
 const [value, setValue] = useState(propValue);
 useEffect(() => {
@@ -1487,12 +1465,11 @@ const [value, setValue] = useState(
 
 // ✅ CORRECT - If you need prop changes, use derived state:
 const displayValue = propOverride || value;`
-                    });
+                    };
                     break;
                 case 'performance-memoization':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use useMemo for expensive operations and static data',
+                    violation.suggestion = {
+                        text: 'Use useMemo for expensive operations and static data',
                         example: `// ❌ WRONG - Expensive operation on every render:
 const filteredItems = items.filter(item => 
   item.name.toLowerCase().includes(searchTerm.toLowerCase())
@@ -1517,12 +1494,11 @@ const columns = useMemo(() => [
   { field: 'name', header: 'Name' },
   { field: 'value', header: 'Value' }
 ], []); // Empty deps = never changes`
-                    });
+                    };
                     break;
                 case 'child-state-management':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Never manage state for child components',
+                    violation.suggestion = {
+                        text: 'Never manage state for child components',
                         example: `// ❌ WRONG - Managing child state:
 const [childTableSort, setChildTableSort] = useState('name');
 const [modalOpen, setModalOpen] = useState(false);
@@ -1539,12 +1515,11 @@ const [modalOpen, setModalOpen] = useState(false);
   onSaveUserSettings={handleChildSettings}
   // Child manages its own sort state!
 />`
-                    });
+                    };
                     break;
                 case 'server-reload-on-client-operation':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use client-side operations for sorting and filtering',
+                    violation.suggestion = {
+                        text: 'Use client-side operations for sorting and filtering',
                         example: `// ❌ WRONG - Reload from server:
 const handleSort = (field) => {
   setSortBy(field);
@@ -1568,12 +1543,11 @@ const sortedData = useMemo(() => {
   });
   return sorted;
 }, [data, sortBy, sortDirection]);`
-                    });
+                    };
                     break;
                 case 'runview-runquery-valid-properties':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use only valid properties for RunView/RunViews and RunQuery',
+                    violation.suggestion = {
+                        text: 'Use only valid properties for RunView/RunViews and RunQuery',
                         example: `// ❌ WRONG - Invalid properties on RunView:
 await utilities.rv.RunView({
   EntityName: 'MJ: AI Prompt Runs',
@@ -1602,23 +1576,34 @@ await utilities.rq.RunQuery({
 // Valid RunQuery properties:
 // - QueryName (required)
 // - CategoryName, CategoryID, Parameters (optional)`
-                    });
+                    };
                     break;
                 case 'component-props-validation':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Components can only accept standard props or props defined in spec. Load data internally.',
-                        example: `// ❌ WRONG - Root component with additional props:
-function RootComponent({ utilities, styles, components, customers, orders, selectedId }) {
-  // Additional props will break hosting environment
+                    violation.suggestion = {
+                        text: 'Components can only accept standard props and props explicitly defined in the component spec. Additional props must be declared in the spec\'s properties array.',
+                        example: `// ❌ WRONG - Component with undeclared props:
+function MyComponent({ utilities, styles, components, customers, orders, selectedId }) {
+  // customers, orders, selectedId are NOT allowed unless defined in spec
 }
 
-// ✅ CORRECT - Root component with only standard props:
-function RootComponent({ utilities, styles, components, callbacks, savedUserSettings, onSaveUserSettings }) {
-  // Load ALL data internally using utilities
+// ✅ CORRECT Option 1 - Use only standard props and load data internally:
+function MyComponent({ utilities, styles, components, callbacks, savedUserSettings, onSaveUserSettings }) {
+  // Load data internally using utilities
   const [customers, setCustomers] = useState([]);
   const [orders, setOrders] = useState([]);
   const [selectedId, setSelectedId] = useState(savedUserSettings?.selectedId);
+}
+
+// ✅ CORRECT Option 2 - Define props in component spec:
+// In spec.properties array:
+// [
+//   { name: "customers", type: "array", required: false, description: "Customer list" },
+//   { name: "orders", type: "array", required: false, description: "Order list" },
+//   { name: "selectedId", type: "string", required: false, description: "Selected item ID" }
+// ]
+// Then the component can accept them:
+function MyComponent({ utilities, styles, components, customers, orders, selectedId }) {
+  // These props are now allowed because they're defined in the spec
   
   useEffect(() => {
     const loadData = async () => {
@@ -1639,12 +1624,11 @@ function RootComponent({ utilities, styles, components, callbacks, savedUserSett
   
   return <div>{/* Use state, not props */}</div>;
 }`
-                    });
+                    };
                     break;
                 case 'runview-runquery-result-direct-usage':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'RunView and RunQuery return result objects, not arrays. Access the data with .Results property.',
+                    violation.suggestion = {
+                        text: 'RunView and RunQuery return result objects, not arrays. Access the data with .Results property.',
                         example: `// ❌ WRONG - Using result directly as array:
 const result = await utilities.rv.RunView({
   EntityName: 'Users',
@@ -1690,12 +1674,11 @@ setData(queryResult.Results || []);  // NOT queryResult directly!
 //   TotalRowCount?: number,
 //   ExecutionTime?: number
 // }`
-                    });
+                    };
                     break;
                 case 'styles-invalid-path':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Fix invalid styles property paths. Use the correct ComponentStyles interface structure.',
+                    violation.suggestion = {
+                        text: 'Fix invalid styles property paths. Use the correct ComponentStyles interface structure.',
                         example: `// ❌ WRONG - Invalid property paths:
 styles.fontSize.small           // fontSize is not at root level
 styles.colors.background        // colors.background exists
@@ -1710,12 +1693,11 @@ styles.spacing.sm               // correct size name
 styles?.typography?.fontSize?.sm || '14px'
 styles?.colors?.background || '#FFFFFF'
 styles?.spacing?.sm || '8px'`
-                    });
+                    };
                     break;
                 case 'styles-unsafe-access':
-                    suggestions.push({
-                        violation: violation.rule,
-                        suggestion: 'Use optional chaining for nested styles access to prevent runtime errors.',
+                    violation.suggestion = {
+                        text: 'Use optional chaining for nested styles access to prevent runtime errors.',
                         example: `// ❌ UNSAFE - Direct nested access:
 const fontSize = styles.typography.fontSize.md;
 const borderRadius = styles.borders.radius.sm;
@@ -1730,45 +1712,39 @@ const {
     fontSize: { md: fontSize = '14px' } = {}
   } = {}
 } = styles || {};`
-                    });
+                    };
                     break;
             }
         }
-        return suggestions;
+        return violations;
     }
     static generateSyntaxErrorSuggestions(violations) {
-        const suggestions = [];
         for (const violation of violations) {
             if (violation.message.includes('Unterminated string')) {
-                suggestions.push({
-                    violation: violation.rule,
-                    suggestion: 'Check that all string literals are properly closed with matching quotes',
+                violation.suggestion = {
+                    text: 'Check that all string literals are properly closed with matching quotes',
                     example: 'Template literals with interpolation must use backticks: `text ${variable} text`'
-                });
+                };
             }
             else if (violation.message.includes('Unexpected token') || violation.message.includes('export')) {
-                suggestions.push({
-                    violation: violation.rule,
-                    suggestion: 'Ensure all code is within the component function body',
+                violation.suggestion = {
+                    text: 'Ensure all code is within the component function body',
                     example: 'Remove any export statements or code outside the function definition'
-                });
+                };
             }
             else if (violation.message.includes('import') && violation.message.includes('top level')) {
-                suggestions.push({
-                    violation: violation.rule,
-                    suggestion: 'Import statements are not allowed in components - use props instead',
+                violation.suggestion = {
+                    text: 'Import statements are not allowed in components - use props instead',
                     example: 'Access libraries through props: const { React, MaterialUI } = props.components'
-                });
+                };
             }
             else {
-                suggestions.push({
-                    violation: violation.rule,
-                    suggestion: 'Fix the syntax error before the component can be compiled',
+                violation.suggestion = {
+                    text: 'Fix the syntax error before the component can be compiled',
                     example: 'Review the code at the specified line and column for syntax issues'
-                });
+                };
             }
         }
-        return suggestions;
     }
     /**
      * Apply library-specific lint rules based on ComponentLibrary LintRules field
@@ -2513,7 +2489,7 @@ ComponentLinter.universalComponentRules = [
                                     severity: 'critical',
                                     line: path.node.loc?.start.line || 0,
                                     column: path.node.loc?.start.column || 0,
-                                    message: `Component '${varName}' shadows a dependency component. The component '${varName}' is already available from dependencies (auto-destructured), but this code is creating a new definition which overrides it.`,
+                                    message: `Component '${varName}' shadows a dependency component. The component '${varName}' should be accessed via destructuring from components prop or as components.${varName}, but this code is creating a new definition which overrides it.`,
                                     code: `const ${varName} = ...`
                                 });
                             }
@@ -2531,15 +2507,15 @@ ComponentLinter.universalComponentRules = [
                                 severity: 'critical',
                                 line: path.node.loc?.start.line || 0,
                                 column: path.node.loc?.start.column || 0,
-                                message: `Component '${funcName}' shadows a dependency component. The component '${funcName}' is already available from dependencies (auto-destructured), but this code is creating a new function which overrides it.`,
+                                message: `Component '${funcName}' shadows a dependency component. The component '${funcName}' should be accessed via destructuring from components prop or as components.${funcName}, but this code is creating a new function which overrides it.`,
                                 code: `function ${funcName}(...)`
                             });
                         }
                     }
                 }
             });
-            // Components are now auto-destructured in the wrapper, so we don't need to check for manual destructuring
-            // We just need to check if they're being used directly
+            // Components must be destructured from the components prop or accessed via components.ComponentName
+            // Check if they're being used correctly
             let hasComponentsUsage = false;
             const usedDependencies = new Set();
             mainComponentPath.traverse({
@@ -2580,7 +2556,7 @@ ComponentLinter.universalComponentRules = [
                     }
                 }
             });
-            // Components are now auto-destructured, so just check for unused dependencies
+            // Check for unused dependencies - components must be destructured or accessed via components prop
             if (dependencyNames.size > 0 && usedDependencies.size === 0) {
                 const depList = Array.from(dependencyNames).join(', ');
                 violations.push({
@@ -2588,7 +2564,7 @@ ComponentLinter.universalComponentRules = [
                     severity: 'low',
                     line: mainComponentPath.node.loc?.start.line || 0,
                     column: mainComponentPath.node.loc?.start.column || 0,
-                    message: `Component has dependencies [${depList}] defined in spec but they're not being used. These components are available for use.`,
+                    message: `Component has dependencies [${depList}] defined in spec but they're not being used. These components must be destructured from the components prop or accessed as components.ComponentName to use them.`,
                     code: `// Available: ${depList}`
                 });
             }
@@ -4954,10 +4930,13 @@ Valid properties: QueryID, QueryName, CategoryID, CategoryPath, Parameters, MaxR
             // Build set of allowed props: standard props + React special props + componentSpec properties
             const allowedProps = new Set([...standardProps, ...reactSpecialProps]);
             // Add props from componentSpec.properties if they exist
+            // These are the architect-defined props that this component is allowed to accept
+            const specDefinedProps = [];
             if (componentSpec?.properties) {
                 for (const prop of componentSpec.properties) {
                     if (prop.name) {
                         allowedProps.add(prop.name);
+                        specDefinedProps.push(prop.name);
                     }
                 }
             }
@@ -4979,15 +4958,28 @@ Valid properties: QueryID, QueryName, CategoryID, CategoryPath, Parameters, MaxR
                             }
                             // Only report if there are non-allowed props
                             if (invalidProps.length > 0) {
-                                const customPropsMessage = componentSpec?.properties?.length
-                                    ? ` and custom props defined in spec: ${componentSpec.properties.map(p => p.name).join(', ')}`
-                                    : '';
+                                let message;
+                                if (specDefinedProps.length > 0) {
+                                    message = `Component "${componentName}" accepts undeclared props: ${invalidProps.join(', ')}. ` +
+                                        `This component can only accept: ` +
+                                        `(1) Standard props: ${Array.from(standardProps).join(', ')}, ` +
+                                        `(2) Spec-defined props: ${specDefinedProps.join(', ')}, ` +
+                                        `(3) React props: ${Array.from(reactSpecialProps).join(', ')}. ` +
+                                        `Any additional props must be defined in the component spec's properties array.`;
+                                }
+                                else {
+                                    message = `Component "${componentName}" accepts undeclared props: ${invalidProps.join(', ')}. ` +
+                                        `This component can only accept: ` +
+                                        `(1) Standard props: ${Array.from(standardProps).join(', ')}, ` +
+                                        `(2) React props: ${Array.from(reactSpecialProps).join(', ')}. ` +
+                                        `To accept additional props, they must be defined in the component spec's properties array.`;
+                                }
                                 violations.push({
                                     rule: 'component-props-validation',
                                     severity: 'critical',
                                     line: path.node.loc?.start.line || 0,
                                     column: path.node.loc?.start.column || 0,
-                                    message: `Component "${componentName}" accepts undeclared props: ${invalidProps.join(', ')}. Components can only accept standard props: ${Array.from(standardProps).join(', ')}, React special props: ${Array.from(reactSpecialProps).join(', ')}${customPropsMessage}. All custom props must be defined in the component spec properties array.`
+                                    message
                                 });
                             }
                         }
@@ -5012,15 +5004,28 @@ Valid properties: QueryID, QueryName, CategoryID, CategoryPath, Parameters, MaxR
                                     }
                                 }
                                 if (invalidProps.length > 0) {
-                                    const customPropsMessage = componentSpec?.properties?.length
-                                        ? ` and custom props defined in spec: ${componentSpec.properties.map(p => p.name).join(', ')}`
-                                        : '';
+                                    let message;
+                                    if (specDefinedProps.length > 0) {
+                                        message = `Component "${componentName}" accepts undeclared props: ${invalidProps.join(', ')}. ` +
+                                            `This component can only accept: ` +
+                                            `(1) Standard props: ${Array.from(standardProps).join(', ')}, ` +
+                                            `(2) Spec-defined props: ${specDefinedProps.join(', ')}, ` +
+                                            `(3) React props: ${Array.from(reactSpecialProps).join(', ')}. ` +
+                                            `Any additional props must be defined in the component spec's properties array.`;
+                                    }
+                                    else {
+                                        message = `Component "${componentName}" accepts undeclared props: ${invalidProps.join(', ')}. ` +
+                                            `This component can only accept: ` +
+                                            `(1) Standard props: ${Array.from(standardProps).join(', ')}, ` +
+                                            `(2) React props: ${Array.from(reactSpecialProps).join(', ')}. ` +
+                                            `To accept additional props, they must be defined in the component spec's properties array.`;
+                                    }
                                     violations.push({
                                         rule: 'component-props-validation',
                                         severity: 'critical',
                                         line: path.node.loc?.start.line || 0,
                                         column: path.node.loc?.start.column || 0,
-                                        message: `Component "${componentName}" accepts undeclared props: ${invalidProps.join(', ')}. Components can only accept standard props: ${Array.from(standardProps).join(', ')}, React special props: ${Array.from(reactSpecialProps).join(', ')}${customPropsMessage}. All custom props must be defined in the component spec properties array.`
+                                        message
                                     });
                                 }
                             }
@@ -5253,87 +5258,6 @@ Valid properties: QueryID, QueryName, CategoryID, CategoryPath, Parameters, MaxR
             return violations;
         }
     },
-    {
-        name: 'invalid-components-destructuring',
-        appliesTo: 'all',
-        test: (ast, componentName, componentSpec) => {
-            const violations = [];
-            // Build sets of valid component names and library names
-            const validComponentNames = new Set();
-            const libraryNames = new Set();
-            const libraryGlobalVars = new Set();
-            // Add dependency components
-            if (componentSpec?.dependencies) {
-                for (const dep of componentSpec.dependencies) {
-                    if (dep.name) {
-                        validComponentNames.add(dep.name);
-                    }
-                }
-            }
-            // Add libraries
-            if (componentSpec?.libraries) {
-                for (const lib of componentSpec.libraries) {
-                    if (lib.name) {
-                        libraryNames.add(lib.name);
-                    }
-                    if (lib.globalVariable) {
-                        libraryGlobalVars.add(lib.globalVariable);
-                    }
-                }
-            }
-            // Check for manual destructuring from components (now optional since auto-destructuring is in place)
-            (0, traverse_1.default)(ast, {
-                VariableDeclarator(path) {
-                    // Look for: const { Something } = components;
-                    if (t.isObjectPattern(path.node.id) &&
-                        t.isIdentifier(path.node.init) &&
-                        path.node.init.name === 'components') {
-                        for (const prop of path.node.id.properties) {
-                            if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
-                                const destructuredName = prop.key.name;
-                                // Check if this is NOT a valid component from dependencies
-                                if (!validComponentNames.has(destructuredName)) {
-                                    // Check if it might be a library being incorrectly destructured
-                                    if (libraryNames.has(destructuredName) || libraryGlobalVars.has(destructuredName)) {
-                                        violations.push({
-                                            rule: 'invalid-components-destructuring',
-                                            severity: 'critical',
-                                            line: prop.loc?.start.line || 0,
-                                            column: prop.loc?.start.column || 0,
-                                            message: `Attempting to destructure library "${destructuredName}" from components prop. Libraries should be accessed directly via their globalVariable, not from components.`,
-                                            code: `const { ${destructuredName} } = components;`
-                                        });
-                                    }
-                                    else {
-                                        violations.push({
-                                            rule: 'invalid-components-destructuring',
-                                            severity: 'high',
-                                            line: prop.loc?.start.line || 0,
-                                            column: prop.loc?.start.column || 0,
-                                            message: `Destructuring "${destructuredName}" from components prop, but it's not in the component's dependencies array. Either add it to dependencies or it might be a missing library.`,
-                                            code: `const { ${destructuredName} } = components;`
-                                        });
-                                    }
-                                }
-                                else {
-                                    // Valid component, but manual destructuring is now redundant
-                                    violations.push({
-                                        rule: 'invalid-components-destructuring',
-                                        severity: 'low',
-                                        line: prop.loc?.start.line || 0,
-                                        column: prop.loc?.start.column || 0,
-                                        message: `Manual destructuring of "${destructuredName}" from components prop is redundant. Components are now auto-destructured and available directly.`,
-                                        code: `const { ${destructuredName} } = components; // Can be removed`
-                                    });
-                                }
-                            }
-                        }
-                    }
-                }
-            });
-            return violations;
-        }
-    },
     {
         name: 'unsafe-array-operations',
         appliesTo: 'all',
@@ -5727,14 +5651,14 @@ Valid properties: QueryID, QueryName, CategoryID, CategoryPath, Parameters, MaxR
                     });
                   }
                   } else if (componentsFromProp.has(tagName)) {
-                    // This shouldn't happen since dependency components are auto-destructured
-                    // But keep as a fallback check
+                    // Component is in dependencies but not destructured/accessible
+                    // This indicates the component wasn't properly destructured from components prop
                     violations.push({
                       rule: 'undefined-jsx-component',
                       severity: 'high',
                       line: openingElement.loc?.start.line || 0,
                       column: openingElement.loc?.start.column || 0,
-                      message: `JSX component "${tagName}" is in dependencies but appears to be undefined. There may be an issue with component registration.`,
+                      message: `JSX component "${tagName}" is in dependencies but appears to be undefined. Make sure to destructure it from the components prop: const { ${tagName} } = components;`,
                       code: `<${tagName} ... />`
                     });
                   } else {
@@ -7543,87 +7467,117 @@ Correct pattern:
         appliesTo: 'all',
         test: (ast, componentName) => {
             const violations = [];
-            // Count all function declarations and expressions at the top level
-            const functionDeclarations = [];
-            const functionExpressions = [];
-            (0, traverse_1.default)(ast, {
-                FunctionDeclaration(path) {
-                    // Only check top-level functions (not nested inside other functions)
-                    const parent = path.getFunctionParent();
-                    if (!parent) {
-                        const funcName = path.node.id?.name || 'anonymous';
-                        functionDeclarations.push({
-                            name: funcName,
-                            line: path.node.loc?.start.line || 0,
-                            column: path.node.loc?.start.column || 0
-                        });
-                    }
-                },
-                VariableDeclaration(path) {
-                    // Check for const/let/var func = function() or arrow functions at top level
-                    const parent = path.getFunctionParent();
-                    if (!parent) {
-                        for (const declarator of path.node.declarations) {
-                            if (t.isVariableDeclarator(declarator) &&
-                                (t.isFunctionExpression(declarator.init) ||
-                                    t.isArrowFunctionExpression(declarator.init))) {
-                                const funcName = t.isIdentifier(declarator.id) ? declarator.id.name : 'anonymous';
-                                functionExpressions.push({
-                                    name: funcName,
-                                    line: declarator.loc?.start.line || 0,
-                                    column: declarator.loc?.start.column || 0
-                                });
-                            }
-                        }
-                    }
-                }
-            });
-            const allFunctions = [...functionDeclarations, ...functionExpressions];
-            // Check if we have more than one function
-            if (allFunctions.length > 1) {
-                // Find which one is the main component
-                const mainComponentIndex = allFunctions.findIndex(f => f.name === componentName);
-                const otherFunctions = allFunctions.filter((_, index) => index !== mainComponentIndex);
+            // Check that the AST body contains exactly one statement and it's a function declaration
+            const programBody = ast.program.body;
+            // First, check if there's anything other than a single function declaration
+            if (programBody.length === 0) {
+                violations.push({
+                    rule: 'single-function-only',
+                    severity: 'critical',
+                    line: 1,
+                    column: 0,
+                    message: `Component code must contain exactly one function declaration named "${componentName}". No code found.`,
+                    code: `Add: function ${componentName}({ utilities, styles, components, callbacks, savedUserSettings, onSaveUserSettings }) { ... }`
+                });
+                return violations;
+            }
+            if (programBody.length > 1) {
+                // Multiple top-level statements - not allowed
                 violations.push({
                     rule: 'single-function-only',
                     severity: 'critical',
-                    line: otherFunctions[0].line,
-                    column: otherFunctions[0].column,
-                    message: `Component code must contain ONLY the main component function "${componentName}". Found ${allFunctions.length} functions: ${allFunctions.map(f => f.name).join(', ')}. Move other functions to separate component dependencies.`,
-                    code: `Remove functions: ${otherFunctions.map(f => f.name).join(', ')}`
+                    line: programBody[1].loc?.start.line || 0,
+                    column: programBody[1].loc?.start.column || 0,
+                    message: `Component code must contain ONLY a single function declaration. Found ${programBody.length} top-level statements. No code should exist before or after the function.`,
+                    code: `Remove all code except: function ${componentName}(...) { ... }`
                 });
-                // Add a violation for each extra function
-                for (const func of otherFunctions) {
+                // Report each extra statement
+                for (let i = 1; i < programBody.length; i++) {
+                    const stmt = programBody[i];
+                    let stmtType = 'statement';
+                    if (t.isVariableDeclaration(stmt)) {
+                        stmtType = 'variable declaration';
+                    }
+                    else if (t.isFunctionDeclaration(stmt)) {
+                        stmtType = 'function declaration';
+                    }
+                    else if (t.isExpressionStatement(stmt)) {
+                        stmtType = 'expression';
+                    }
                     violations.push({
                         rule: 'single-function-only',
                         severity: 'critical',
-                        line: func.line,
-                        column: func.column,
-                        message: `Extra function "${func.name}" not allowed. Each component must be a single function. Move this to a separate component dependency.`,
-                        code: `function ${func.name} should be a separate component`
+                        line: stmt.loc?.start.line || 0,
+                        column: stmt.loc?.start.column || 0,
+                        message: `Extra ${stmtType} not allowed. Only the component function should exist.`,
+                        code: ''
                     });
                 }
             }
-            // Also check that the single function matches the component name
-            if (allFunctions.length === 1 && allFunctions[0].name !== componentName) {
+            // Check that the single statement is a function declaration (not arrow function or other)
+            const firstStatement = programBody[0];
+            if (!t.isFunctionDeclaration(firstStatement)) {
+                let actualType = 'unknown statement';
+                let suggestion = '';
+                if (t.isVariableDeclaration(firstStatement)) {
+                    // Check if it's an arrow function or other variable
+                    const declarator = firstStatement.declarations[0];
+                    if (t.isVariableDeclarator(declarator)) {
+                        if (t.isArrowFunctionExpression(declarator.init) || t.isFunctionExpression(declarator.init)) {
+                            actualType = 'arrow function or function expression';
+                            suggestion = `Use function declaration syntax: function ${componentName}(...) { ... }`;
+                        }
+                        else {
+                            actualType = 'variable declaration';
+                            suggestion = 'Remove this variable and ensure only the component function exists';
+                        }
+                    }
+                }
+                else if (t.isExpressionStatement(firstStatement)) {
+                    actualType = 'expression statement';
+                    suggestion = 'Remove this expression and add the component function';
+                }
                 violations.push({
                     rule: 'single-function-only',
                     severity: 'critical',
-                    line: allFunctions[0].line,
-                    column: allFunctions[0].column,
-                    message: `Component function name "${allFunctions[0].name}" does not match component name "${componentName}". The function must be named exactly as specified.`,
-                    code: `Rename function to: function ${componentName}(...)`
+                    line: firstStatement.loc?.start.line || 0,
+                    column: firstStatement.loc?.start.column || 0,
+                    message: `Component must be a function declaration, not ${actualType}. ${suggestion}`,
+                    code: ''
                 });
+                // Don't check name if it's not a function declaration
+                return violations;
             }
-            // Check for no function at all
-            if (allFunctions.length === 0) {
+            // Check that the function name matches the component name
+            const functionName = firstStatement.id?.name;
+            if (functionName !== componentName) {
                 violations.push({
                     rule: 'single-function-only',
                     severity: 'critical',
-                    line: 1,
-                    column: 0,
-                    message: `Component code must contain exactly one function named "${componentName}". No functions found.`,
-                    code: `Add: function ${componentName}({ utilities, styles, components, callbacks, savedUserSettings, onSaveUserSettings }) { ... }`
+                    line: firstStatement.loc?.start.line || 0,
+                    column: firstStatement.loc?.start.column || 0,
+                    message: `Component function name "${functionName}" does not match component name "${componentName}". The function must be named exactly as specified.`,
+                    code: `Rename to: function ${componentName}(...)`
+                });
+            }
+            // Additional check: look for any code before the function that might have been missed
+            // (e.g., leading variable declarations that destructure from React)
+            if (programBody.length === 1 && t.isFunctionDeclaration(firstStatement)) {
+                // Use traverse to find any problematic patterns inside
+                (0, traverse_1.default)(ast, {
+                    Program(path) {
+                        // Check if there are any directives or other non-obvious code
+                        if (path.node.directives && path.node.directives.length > 0) {
+                            violations.push({
+                                rule: 'single-function-only',
+                                severity: 'high',
+                                line: 1,
+                                column: 0,
+                                message: 'Component should not have directives like "use strict". These are added automatically.',
+                                code: ''
+                            });
+                        }
+                    }
                 });
             }
             return violations;
@@ -8061,6 +8015,44 @@ Correct pattern:
             });
             return violations;
         }
+    },
+    {
+        name: 'no-react-destructuring',
+        appliesTo: 'all',
+        test: (ast, componentName, componentSpec) => {
+            const violations = [];
+            (0, traverse_1.default)(ast, {
+                VariableDeclarator(path) {
+                    // Check for destructuring from React
+                    if (t.isObjectPattern(path.node.id) &&
+                        t.isIdentifier(path.node.init) &&
+                        path.node.init.name === 'React') {
+                        // Get the destructured properties
+                        const destructuredProps = path.node.id.properties
+                            .filter(prop => t.isObjectProperty(prop) && t.isIdentifier(prop.key))
+                            .map(prop => prop.key)
+                            .map(key => key.name);
+                        violations.push({
+                            rule: 'no-react-destructuring',
+                            severity: 'critical',
+                            line: path.node.loc?.start.line || 0,
+                            column: path.node.loc?.start.column || 0,
+                            message: `Cannot destructure from React. The hooks (${destructuredProps.join(', ')}) are already available as global functions in the React runtime.`,
+                            code: path.toString().substring(0, 100),
+                            suggestion: {
+                                text: `Remove the destructuring statement. React hooks like ${destructuredProps.join(', ')} are already available globally and don't need to be imported or destructured.`,
+                                example: `// Remove this line entirely:
+// const { ${destructuredProps.join(', ')} } = React;
+
+// Just use the hooks directly:
+const [state, setState] = useState(initialValue);`
+                            }
+                        });
+                    }
+                }
+            });
+            return violations;
+        }
     }
 ];
 //# sourceMappingURL=component-linter.js.map