@yoo-digital/eslint-plugin-angular 1.0.0 → 1.1.0

package/README.md

@@ -8,28 +8,106 @@ Here should live all custom Angular lint rules that eslint does not already prov
 
 Wrong code is yellow underlined in VScode, it can also be raises running : `npm run lint`
 
-## Rule 1 : boolean input conversion
+## Rule 1 : boolean input conversion (prefer-boolean-attribute-shorthand)
 
 `booleanAttribute @angular/core`
 
 `BooleanInput @angular/cdk/coercion`
 
+### ⚠️ Important Limitations
+
+**Current Implementation:** This rule enforces shorthand syntax (`<x a />` instead of `<x [a]="true" />`) but **cannot automatically verify**:
+- Whether an input has `transform: booleanAttribute` 
+- What the default value of an input is
+
+This is a technical limitation of Angular ESLint - template rules cannot access the component's TypeScript code.
+
+### Recommended Usage
+
+This rule works best when:
+1. **All boolean inputs** in your project use `booleanAttribute` transform
+2. **Most boolean inputs** have `default = false` or no default
+3. You treat this as a **style guide enforcer** rather than a safety checker
+
+### Configuration
+
+By default, the rule only flags `[attr]="true"` bindings (safe default):
+
+```json
+{
+  "rules": {
+    "@yoo-digital/eslint-plugin-angular/prefer-boolean-attribute-shorthand": "error"
+  }
+}
+```
+
+To also enforce removal of `[attr]="false"` bindings:
+
+```json
+{
+  "rules": {
+    "@yoo-digital/eslint-plugin-angular/prefer-boolean-attribute-shorthand": [
+      "error",
+      { "allowFalseLiteral": false }
+    ]
+  }
+}
+```
+
 ### Examples
 
-`<myComp [myBoolInput]="true" ` must be `<myComp myBoolInput`
+#### ✅ Recommended Pattern (Default false or no default)
+
+```typescript
+// Component
+@Input({ transform: booleanAttribute }) disabled: boolean = false;
+// OR
+disabled = input<boolean, BooleanInput>(false, { transform: booleanAttribute });
+```
+
+**Template:**
+- ❌ `<button [disabled]="true">` → Should be `<button disabled>`
+- ✅ `<button disabled>` (shorthand for true)
+- ✅ `<button>` (omit for false)
+- ✅ `<button [disabled]="isLoading">` (expressions are allowed)
+
+#### ⚠️ Special Case: Default true (Disable rule if needed)
+
+```typescript
+// Component
+@Input({ transform: booleanAttribute }) enabled: boolean = true;
+```
+
+**Template:**
+```html
+<!-- eslint-disable-next-line @yoo-digital/eslint-plugin-angular/prefer-boolean-attribute-shorthand -->
+<button [enabled]="false">Explicitly disabled</button>
+```
+
+When default is `true`, you may need explicit `[attr]="true"` or `[attr]="false"` bindings.
+
+#### ❌ Without booleanAttribute (Won't work!)
 
-`<myComp [myBoolInput]="false"` must be `<myComp `
+```typescript
+// Component - Missing transform!
+@Input() checked: boolean = false;
+```
 
-`<myComp [myBoolInput]="2+2===4"` is accepted
+**Template:**
+- ❌ `<input checked>` → Will pass `""` (empty string), NOT boolean!
+- ✅ `<input [checked]="true">` (must use property binding)
 
-### Decorator
+### Decorator Syntax
 
-`@Input({ transform: booleanAttribute }) myInput: boolean = true;`
+`@Input({ transform: booleanAttribute }) myInput: boolean = false;`
 
-### Signal
+### Signal Input Syntax
 
-`myInput = input<boolean, BooleanInput>(true, {transform: booleanAttribute,});`
+`myInput = input<boolean, BooleanInput>(false, { transform: booleanAttribute });`
 
-### Exception
+### Summary
 
-If a **required** boolean input needs to be false, no choice, `[myRequiredInput]="false"` must be written. Therefore boolean input should never be required.
+- **Rule enforces**: `[attr]="true"` → `attr` shorthand
+- **Rule assumes**: Inputs have `booleanAttribute` and `default ≠ true`
+- **Manual override**: Use eslint-disable comments for special cases
+- **Best practice**: Ensure all boolean inputs use `booleanAttribute`

package/dist/rules/prefer-boolean-attribute-shorthand.d.ts

@@ -4,5 +4,34 @@ interface Options {
 }
 type MessageIds = 'preferTrue' | 'preferFalse' | 'suggestTrue' | 'suggestRemove';
 export declare const RULE_NAME = "prefer-boolean-attribute-shorthand";
+/**
+ * IMPORTANT LIMITATIONS:
+ *
+ * Angular ESLint template rules cannot directly access the TypeScript component class
+ * to check for booleanAttribute transforms or default values. This would require:
+ * 1. Access to the TypeScript program (not available in template parser services)
+ * 2. Cross-file analysis (template -> component.ts)
+ * 3. Complex AST traversal and decorator/signal input analysis
+ *
+ * The current implementation enforces shorthand syntax for [attr]="true" bindings
+ * but cannot verify:
+ * - Whether the input has `transform: booleanAttribute`
+ * - What the default value of the input is
+ *
+ * RECOMMENDATIONS FOR USERS:
+ * 1. Only use this rule in projects where ALL boolean inputs have booleanAttribute
+ * 2. If an input has default=true, manually disable the rule for that binding
+ * 3. Consider the rule as a style guide enforcer, not a safety checker
+ *
+ * FUTURE ENHANCEMENTS:
+ * To implement the full feature set requested would require creating a SEPARATE
+ * TypeScript ESLint rule that:
+ * - Runs on .ts component files (not templates)
+ * - Analyzes @Component decorators to find template  references
+ * - Parses templates and cross-references with component inputs
+ * - Reports errors in both .ts and template files
+ *
+ * This would be a significantly more complex multi-file analysis rule.
+ */
 export declare const preferBooleanAttributeShorthandRule: TSESLint.RuleModule<MessageIds, Options[]>;
 export {};

package/dist/rules/prefer-boolean-attribute-shorthand.js

@@ -3,11 +3,40 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferBooleanAttributeShorthandRule = exports.RULE_NAME = void 0;
 const utils_1 = require("@angular-eslint/utils");
 exports.RULE_NAME = 'prefer-boolean-attribute-shorthand';
+/**
+ * IMPORTANT LIMITATIONS:
+ *
+ * Angular ESLint template rules cannot directly access the TypeScript component class
+ * to check for booleanAttribute transforms or default values. This would require:
+ * 1. Access to the TypeScript program (not available in template parser services)
+ * 2. Cross-file analysis (template -> component.ts)
+ * 3. Complex AST traversal and decorator/signal input analysis
+ *
+ * The current implementation enforces shorthand syntax for [attr]="true" bindings
+ * but cannot verify:
+ * - Whether the input has `transform: booleanAttribute`
+ * - What the default value of the input is
+ *
+ * RECOMMENDATIONS FOR USERS:
+ * 1. Only use this rule in projects where ALL boolean inputs have booleanAttribute
+ * 2. If an input has default=true, manually disable the rule for that binding
+ * 3. Consider the rule as a style guide enforcer, not a safety checker
+ *
+ * FUTURE ENHANCEMENTS:
+ * To implement the full feature set requested would require creating a SEPARATE
+ * TypeScript ESLint rule that:
+ * - Runs on .ts component files (not templates)
+ * - Analyzes @Component decorators to find template  references
+ * - Parses templates and cross-references with component inputs
+ * - Reports errors in both .ts and template files
+ *
+ * This would be a significantly more complex multi-file analysis rule.
+ */
 exports.preferBooleanAttributeShorthandRule = {
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Prefer boolean input attribute shorthand instead of binding to literal true/false.',
+            description: 'Prefer boolean input attribute shorthand instead of binding to literal true/false. NOTE: This rule assumes inputs have booleanAttribute transform and does not have default=true.',
         },
         hasSuggestions: true,
         schema: [
@@ -20,22 +49,22 @@ exports.preferBooleanAttributeShorthandRule = {
             },
         ],
         messages: {
-            preferTrue: 'Use attribute shorthand "{{attr}}" instead of [{{attr}}]="true".',
-            preferFalse: 'Avoid binding [{{attr}}]="false"; remove the binding or ensure default is false.',
+            preferTrue: 'Use attribute shorthand "{{attr}}" instead of [{{attr}}]="true". WARNING: Only works if input has booleanAttribute transform.',
+            preferFalse: 'Avoid binding [{{attr}}]="false"; remove the binding if default is false.',
             suggestTrue: 'Replace with attribute shorthand {{attr}}',
             suggestRemove: 'Remove the false binding',
         },
     },
     defaultOptions: [
         {
-            allowFalseLiteral: false,
+            allowFalseLiteral: true, // Changed default to true for safety
         },
     ],
     create(context) {
         // Robust to missing options: default to [{}] if undefined
         const optionsArr = context.options ?? [{}];
         const options = optionsArr[0] ?? {};
-        const allowFalseLiteral = options.allowFalseLiteral ?? false;
+        const allowFalseLiteral = options.allowFalseLiteral ?? true; // Default to true for safety
         const parserServices = (0, utils_1.getTemplateParserServices)(context);
         return {
             BoundAttribute(node) {
@@ -49,6 +78,8 @@ exports.preferBooleanAttributeShorthandRule = {
                     const start = node.sourceSpan.start.offset;
                     const end = node.sourceSpan.end.offset;
                     if (ast.value === true) {
+                        // Enforce shorthand for true bindings
+                        // NOTE: This assumes the input has booleanAttribute and default != true
                         context.report({
                             loc,
                             messageId: 'preferTrue',
@@ -63,6 +94,7 @@ exports.preferBooleanAttributeShorthandRule = {
                         });
                     }
                     else if (ast.value === false && !allowFalseLiteral) {
+                        // Only flag false bindings if explicitly configured
                         context.report({
                             loc,
                             messageId: 'preferFalse',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoo-digital/eslint-plugin-angular",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Yoo Digital custom Angular ESLint plugin providing prefer-boolean-attribute-shorthand rule.",
   "type": "commonjs",
   "main": "dist/index.js",