@intentius/chant 0.0.5 → 0.0.9

package/src/lint/engine.test.ts

@@ -29,7 +29,7 @@ describe("runLint", () => {
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].ruleId).toBe("test-rule");
@@ -64,7 +64,7 @@ const x = 1;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
 
       expect(diagnostics).toHaveLength(0);
     });
@@ -115,7 +115,7 @@ const x = 1;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule1, mockRule2]);
+      const { diagnostics } = await runLint([testFile], [mockRule1, mockRule2]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].ruleId).toBe("test-rule-2");
@@ -157,7 +157,7 @@ const y = 2;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].line).toBe(2);
@@ -200,7 +200,7 @@ const y = 2;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].line).toBe(3);
@@ -248,7 +248,7 @@ const y = 2;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule1, mockRule2]);
+      const { diagnostics } = await runLint([testFile], [mockRule1, mockRule2]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].ruleId).toBe("test-rule-2");
@@ -282,7 +282,7 @@ const x = 1;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].ruleId).toBe("test-rule");
@@ -335,7 +335,7 @@ const z = 3;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].line).toBe(5);
@@ -367,7 +367,7 @@ const z = 3;`
         },
       };
 
-      const diagnostics = await runLint([testFile1, testFile2], [mockRule]);
+      const { diagnostics } = await runLint([testFile1, testFile2], [mockRule]);
 
       expect(diagnostics).toHaveLength(2);
       expect(diagnostics.map((d) => d.file).sort()).toEqual([testFile1, testFile2].sort());
@@ -388,7 +388,7 @@ const z = 3;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule]);
+      const { diagnostics } = await runLint([testFile], [mockRule]);
       expect(diagnostics).toHaveLength(0);
     });
   });
@@ -456,10 +456,286 @@ const x = 1;`
         },
       };
 
-      const diagnostics = await runLint([testFile], [mockRule1, mockRule2, mockRule3]);
+      const { diagnostics } = await runLint([testFile], [mockRule1, mockRule2, mockRule3]);
 
       expect(diagnostics).toHaveLength(1);
       expect(diagnostics[0].ruleId).toBe("test-rule-3");
     });
   });
+
+  test("parses reason from disable comment with -- separator", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule -- intentional for backwards compat
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { diagnostics, suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(0);
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].ruleId).toBe("test-rule");
+      expect(suppressed[0].reason).toBe("intentional for backwards compat");
+    });
+  });
+
+  test("parses reason from disable-all comment with -- separator", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable -- entire file suppressed for migration
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { diagnostics, suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(0);
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].reason).toBe("entire file suppressed for migration");
+    });
+  });
+
+  test("backwards compat: no reason when -- is absent", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { diagnostics, suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(0);
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].reason).toBeUndefined();
+    });
+  });
+
+  test("handles reason with multiple -- in text", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule -- reason with -- dashes in it
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].reason).toBe("reason with -- dashes in it");
+    });
+  });
+
+  test("trailing -- with no text treats reason as undefined", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule --
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].reason).toBeUndefined();
+    });
+  });
+
+  test("disable-line with reason", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(testFile, `const x = 1; // chant-disable-line test-rule -- CDN must use us-east-1`);
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 1,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].reason).toBe("CDN must use us-east-1");
+    });
+  });
+
+  test("disable-next-line with reason", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable-next-line -- legacy code, will refactor
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(suppressed).toHaveLength(1);
+      expect(suppressed[0].reason).toBe("legacy code, will refactor");
+    });
+  });
+
+  test("suppressed diagnostics contain the original diagnostic data", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule -- reason
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const { suppressed } = await runLint([testFile], [mockRule]);
+
+      expect(suppressed[0].file).toBe(testFile);
+      expect(suppressed[0].line).toBe(2);
+      expect(suppressed[0].column).toBe(1);
+      expect(suppressed[0].ruleId).toBe("test-rule");
+      expect(suppressed[0].severity).toBe("error");
+      expect(suppressed[0].message).toBe("Test error");
+    });
+  });
 });

package/src/lint/engine.ts

@@ -2,6 +2,16 @@ import type { LintRule, LintDiagnostic, LintContext } from "./rule";
 import { parseFile } from "./parser";
 import { readFileSync } from "fs";
 
+/**
+ * Result of a lint run, separating active diagnostics from suppressed ones.
+ */
+export interface LintRunResult {
+  /** Diagnostics that were not suppressed by disable directives */
+  diagnostics: LintDiagnostic[];
+  /** Diagnostics that were suppressed by disable directives, with optional reason */
+  suppressed: Array<LintDiagnostic & { reason?: string }>;
+}
+
 /**
  * Represents a disable directive found in source code comments
  */
@@ -12,6 +22,8 @@ interface DisableDirective {
   type: "file" | "line" | "next-line";
   /** Specific rule IDs to disable, or undefined for all rules */
   ruleIds?: string[];
+  /** Optional reason for the suppression (text after ` -- `) */
+  reason?: string;
 }
 
 /**
@@ -24,6 +36,60 @@ interface DisableDirective {
  * - // chant-disable-line rule-id1 - disable specific rules for line
  * - // chant-disable-next-line rule-id1 - disable specific rules for next line
  */
+/**
+ * Parse the text after a directive keyword, splitting rule IDs from an optional reason.
+ * Reason is separated by ` -- ` (first occurrence only).
+ * Trailing `--` with no text is treated as no reason.
+ */
+function parseDirectiveText(afterDirective: string | undefined): {
+  ruleIds?: string[];
+  reason?: string;
+} {
+  if (!afterDirective) return {};
+
+  const trimmed = afterDirective.trim();
+  if (!trimmed) return {};
+
+  // Handle `-- reason` at the start (no rule IDs, just reason)
+  if (trimmed.startsWith("-- ")) {
+    const reasonPart = trimmed.slice(3).trim();
+    return { reason: reasonPart || undefined };
+  }
+
+  // Handle bare `--` (no rule IDs, no reason)
+  if (trimmed === "--") {
+    return {};
+  }
+
+  // Handle `RULE_ID -- reason` (rule IDs + reason separated by ` -- `)
+  const dashIdx = trimmed.indexOf(" -- ");
+  if (dashIdx >= 0) {
+    const idsPart = trimmed.slice(0, dashIdx).trim();
+    const reasonPart = trimmed.slice(dashIdx + 4).trim();
+    const ruleIds = idsPart ? idsPart.split(/\s+/).filter(Boolean) : undefined;
+    const reason = reasonPart || undefined;
+    return {
+      ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+      reason,
+    };
+  }
+
+  // Handle trailing ` --` with no reason text
+  if (trimmed.endsWith(" --")) {
+    const idsPart = trimmed.slice(0, -3).trim();
+    const ruleIds = idsPart ? idsPart.split(/\s+/).filter(Boolean) : undefined;
+    return {
+      ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+    };
+  }
+
+  // No `--` at all — just rule IDs
+  const ruleIds = trimmed.split(/\s+/).filter(Boolean);
+  return {
+    ruleIds: ruleIds.length > 0 ? ruleIds : undefined,
+  };
+}
+
 function parseDisableComments(content: string): DisableDirective[] {
   const directives: DisableDirective[] = [];
   const lines = content.split("\n");
@@ -38,25 +104,28 @@ function parseDisableComments(content: string): DisableDirective[] {
     const disableNextLineMatch = line.match(/\/\/\s*chant-disable-next-line(?:\s+(.+))?$/);
 
     if (disableNextLineMatch) {
-      const ruleIds = disableNextLineMatch[1]?.trim().split(/\s+/).filter(Boolean);
+      const { ruleIds, reason } = parseDirectiveText(disableNextLineMatch[1]);
       directives.push({
         line: lineNumber + 1, // Next line
         type: "next-line",
-        ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+        ruleIds,
+        reason,
       });
     } else if (disableLineMatch) {
-      const ruleIds = disableLineMatch[1]?.trim().split(/\s+/).filter(Boolean);
+      const { ruleIds, reason } = parseDirectiveText(disableLineMatch[1]);
       directives.push({
         line: lineNumber,
         type: "line",
-        ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+        ruleIds,
+        reason,
       });
     } else if (disableFileMatch) {
-      const ruleIds = disableFileMatch[1]?.trim().split(/\s+/).filter(Boolean);
+      const { ruleIds, reason } = parseDirectiveText(disableFileMatch[1]);
       directives.push({
         line: lineNumber,
         type: "file",
-        ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+        ruleIds,
+        reason,
       });
     }
   }
@@ -65,24 +134,25 @@ function parseDisableComments(content: string): DisableDirective[] {
 }
 
 /**
- * Check if a diagnostic should be suppressed based on disable directives
+ * Check if a diagnostic should be suppressed based on disable directives.
+ * Returns suppression info if suppressed, or null if not suppressed.
  */
 function isDiagnosticDisabled(
   diagnostic: LintDiagnostic,
   directives: DisableDirective[],
   allRuleIds: Set<string>
-): boolean {
+): { suppressed: boolean; reason?: string } {
   // Check for file-level disables
   const fileDisables = directives.filter((d) => d.type === "file");
   for (const directive of fileDisables) {
     if (!directive.ruleIds) {
       // Disable all rules
-      return true;
+      return { suppressed: true, reason: directive.reason };
     }
     // Check if rule ID exists before checking if it's disabled
     if (directive.ruleIds.some((id) => allRuleIds.has(id))) {
       if (directive.ruleIds.includes(diagnostic.ruleId)) {
-        return true;
+        return { suppressed: true, reason: directive.reason };
       }
     }
     // Silently ignore non-existent rule IDs
@@ -95,18 +165,18 @@ function isDiagnosticDisabled(
   for (const directive of lineDisables) {
     if (!directive.ruleIds) {
       // Disable all rules
-      return true;
+      return { suppressed: true, reason: directive.reason };
     }
     // Check if rule ID exists before checking if it's disabled
     if (directive.ruleIds.some((id) => allRuleIds.has(id))) {
       if (directive.ruleIds.includes(diagnostic.ruleId)) {
-        return true;
+        return { suppressed: true, reason: directive.reason };
       }
     }
     // Silently ignore non-existent rule IDs
   }
 
-  return false;
+  return { suppressed: false };
 }
 
 /**
@@ -114,14 +184,15 @@ function isDiagnosticDisabled(
  * @param files - Array of file paths to lint
  * @param rules - Array of lint rules to execute
  * @param ruleOptions - Optional map of rule ID to options object
- * @returns Array of diagnostics from all rules and files, with disable comments applied
+ * @returns LintRunResult with diagnostics and suppressed items
  */
 export async function runLint(
   files: string[],
   rules: LintRule[],
   ruleOptions?: Map<string, Record<string, unknown>>,
-): Promise<LintDiagnostic[]> {
+): Promise<LintRunResult> {
   const allDiagnostics: LintDiagnostic[] = [];
+  const allSuppressed: Array<LintDiagnostic & { reason?: string }> = [];
   const allRuleIds = new Set(rules.map((r) => r.id));
 
   for (const filePath of files) {
@@ -148,21 +219,28 @@ export async function runLint(
         allDiagnostics.push(...diagnostics);
       }
 
-      // Filter out disabled diagnostics for this file
-      const filteredDiagnostics = allDiagnostics.filter(
-        (diagnostic) => diagnostic.file === filePath && !isDiagnosticDisabled(diagnostic, directives, allRuleIds)
-      );
+      // Partition file diagnostics into active and suppressed
+      const fileDiags = allDiagnostics.filter((d) => d.file === filePath);
+      const otherFileDiags = allDiagnostics.filter((d) => d.file !== filePath);
+
+      const keptDiags: LintDiagnostic[] = [];
+      for (const diagnostic of fileDiags) {
+        const result = isDiagnosticDisabled(diagnostic, directives, allRuleIds);
+        if (result.suppressed) {
+          allSuppressed.push({ ...diagnostic, reason: result.reason });
+        } else {
+          keptDiags.push(diagnostic);
+        }
+      }
 
       // Replace file diagnostics with filtered ones
-      const otherFileDiagnostics = allDiagnostics.filter((d) => d.file !== filePath);
       allDiagnostics.length = 0;
-      allDiagnostics.push(...otherFileDiagnostics, ...filteredDiagnostics);
+      allDiagnostics.push(...otherFileDiags, ...keptDiags);
     } catch (error) {
       // If parsing fails, skip this file and continue with others
-      // In a real implementation, you might want to collect these errors
       continue;
     }
   }
 
-  return allDiagnostics;
+  return { diagnostics: allDiagnostics, suppressed: allSuppressed };
 }