@utoo/lint 0.2.7 → 0.2.8

package/README.md

@@ -67,6 +67,24 @@ when a rule or a particular code shape cannot be fixed safely. The current
 [rule status](https://github.com/fireairforce/utoo-lint/blob/main/docs/rule-status.md)
 lists autofix coverage by rule.
 
+## Suppression comments
+
+Suppress a rule for the next line of code with `utlint-ignore`:
+
+```js
+// utlint-ignore no-debugger: generated breakpoint
+debugger;
+```
+
+Omit the rule ID to suppress all lint rules for the next line of code. Use
+`utlint-ignore-all` before any code for a file-level suppression, or matching
+`utlint-ignore-start` and `utlint-ignore-end` comments for a range. Line and
+block comments are supported. Parse errors remain visible, and fixes from
+suppressed diagnostics are not applied.
+
+Native reports expose suppressed items in `suppressedDiagnostics`; the ESLint
+compatibility API exposes them in `suppressedMessages`.
+
 ## Configuration
 
 `utoo-lint` supports two canonical project config formats:

package/index.cjs

@@ -514,7 +514,7 @@ class UtooLint {
     const results = reportToESLintResults(report, {
       source: code,
       filePath,
-      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0,
+      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0 || (report.suppressedDiagnostics?.length ?? 0) > 0,
       ruleSeverityForFile: (filePath) => ruleSeverityMapForOptions(nativeOptions, filePath)
     });
     if (report.files !== 0) {
@@ -641,7 +641,7 @@ class CLIEngine {
     const results = maybeFilterQuietResults(reportToESLintResults(report, {
       source: code,
       filePath: normalizeESLintFilePath(filePath, mergedOptions.cwd),
-      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0,
+      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0 || (report.suppressedDiagnostics?.length ?? 0) > 0,
       ruleSeverityForFile: (filePath) => ruleSeverityMapForOptions(mergedOptions, filePath)
     }), mergedOptions);
     return resultsToCLIEngineReport(results);
@@ -842,6 +842,7 @@ function publicCliReport(report) {
     files: report.files ?? 0,
     filePaths: report.filePaths ?? [],
     diagnostics: report.diagnostics ?? [],
+    suppressedDiagnostics: report.suppressedDiagnostics ?? [],
     outputs: report.outputs ?? []
   };
 }
@@ -1140,7 +1141,7 @@ function lintFiles(paths, options = {}) {
   const ignoredDiagnostics = ignoredLintPathDiagnostics(targets, options);
   const lintPaths = filteredLintPaths(targets, options);
   if (lintPaths.length === 0) {
-    return { files: 0, filePaths: [], diagnostics: ignoredDiagnostics, exitCode: exitCodeForDiagnostics(ignoredDiagnostics) };
+    return { files: 0, filePaths: [], diagnostics: ignoredDiagnostics, suppressedDiagnostics: [], exitCode: exitCodeForDiagnostics(ignoredDiagnostics) };
   }
 
   const configRuns = nativeConfigRunsForFiles(expandNativeConfigRunPaths(lintPaths, options), options);
@@ -1205,8 +1206,10 @@ function finalizeLintReport(report, ignoredDiagnostics, options) {
   if (!options.deferDiagnosticConfigFiltering) {
     report.filePaths = normalizeReportFilePaths(report.filePaths, options);
     report.diagnostics = normalizeDiagnosticFilePaths(report.diagnostics, options);
+    report.suppressedDiagnostics = normalizeDiagnosticFilePaths(report.suppressedDiagnostics, options);
     report.outputs = normalizeReportOutputs(report.outputs, options);
     report.diagnostics = normalizeReportDiagnostics(report.diagnostics, options);
+    report.suppressedDiagnostics = normalizeReportDiagnostics(report.suppressedDiagnostics, options);
     report.exitCode = exitCodeForDiagnostics(report.diagnostics);
   }
   return report;
@@ -1303,6 +1306,7 @@ function mergeNativeReports(reports) {
     files: reports.reduce((count, item) => count + (item.files ?? 0), 0),
     filePaths: reports.flatMap((item) => item.filePaths ?? []),
     diagnostics: reports.flatMap((item) => item.diagnostics ?? []),
+    suppressedDiagnostics: reports.flatMap((item) => item.suppressedDiagnostics ?? []),
     outputs: reports.flatMap((item) => item.outputs ?? []),
     exitCode: reports.some((item) => item.exitCode) ? 1 : 0
   };
@@ -1335,6 +1339,7 @@ function lintText(code, options = {}) {
         files: 0,
         filePaths: [],
         diagnostics,
+        suppressedDiagnostics: [],
         exitCode: exitCodeForDiagnostics(diagnostics)
       };
     }
@@ -1356,7 +1361,12 @@ function lintText(code, options = {}) {
       ...diagnostic,
       filePath: requestedPath
     }));
+    report.suppressedDiagnostics = (report.suppressedDiagnostics ?? []).map((diagnostic) => ({
+      ...diagnostic,
+      filePath: requestedPath
+    }));
     report.diagnostics = normalizeReportDiagnostics(report.diagnostics, options);
+    report.suppressedDiagnostics = normalizeReportDiagnostics(report.suppressedDiagnostics, options);
     report.exitCode = exitCodeForDiagnostics(report.diagnostics);
     return report;
   } finally {
@@ -1888,7 +1898,10 @@ class Linter {
       config: calculatedConfig({ cwd: verifyOptions.cwd, noConfig: true, overrideConfig: config }, normalizedFilePath)
     });
     const customRuleFilter = applyDisableDirectives(customRuleMessages, sourceCode);
-    this.suppressedMessages = customRuleFilter.suppressedMessages;
+    this.suppressedMessages = [
+      ...(report.suppressedDiagnostics ?? []).map((diagnostic) => suppressedDiagnosticToESLintMessage(diagnostic, ruleSeverities)),
+      ...customRuleFilter.suppressedMessages
+    ];
     this.times = { passes: [] };
     this.fixPassCount = 0;
     return [
@@ -2197,14 +2210,18 @@ function applyDisableDirectives(messages, sourceCode) {
   const directives = sourceCode.getDisableDirectives()
     .filter((directive) => directive.node?.loc?.start?.line)
     .sort((left, right) => left.node.loc.start.line - right.node.loc.start.line);
-  if (directives.length === 0) {
+  const utlintDirectives = sourceCode.getAllComments()
+    .map((comment) => utlintDirectiveFromComment(comment, sourceCode))
+    .filter(Boolean)
+    .sort((left, right) => left.node.range[0] - right.node.range[0]);
+  if (directives.length === 0 && utlintDirectives.length === 0) {
     return { messages, suppressedMessages: [] };
   }
 
   const kept = [];
   const suppressed = [];
   for (const message of messages) {
-    const directive = disableDirectiveForMessage(message, directives);
+    const directive = utlintDirectiveForMessage(message, utlintDirectives) ?? disableDirectiveForMessage(message, directives);
     if (directive) {
       suppressed.push({
         ...message,
@@ -2220,6 +2237,68 @@ function applyDisableDirectives(messages, sourceCode) {
   return { messages: kept, suppressedMessages: suppressed };
 }
 
+function utlintDirectiveFromComment(comment, sourceCode) {
+  const match = String(comment?.value ?? "").trim().match(/^(utlint-ignore(?:-all|-start|-end)?)\b\s*(.*)$/u);
+  if (!match) {
+    return null;
+  }
+
+  const [, type, tail] = match;
+  const colon = tail.indexOf(":");
+  const rawRuleId = (colon === -1 ? tail : tail.slice(0, colon)).trim();
+  const justification = colon === -1 ? "" : tail.slice(colon + 1).trim();
+  const nextToken = sourceCode.getAllTokens().find((token) => token.range?.[0] >= comment.range?.[1]);
+  return {
+    type,
+    node: comment,
+    ruleId: rawRuleId || null,
+    justification,
+    nextCodeLine: nextToken?.loc?.start?.line ?? null,
+    topLevel: sourceCode.getAllTokens().every((token) => token.range?.[0] >= comment.range?.[0])
+  };
+}
+
+function utlintDirectiveForMessage(message, directives) {
+  let allRulesRangeDepth = 0;
+  let namedRuleRangeDepth = 0;
+  let allRulesRangeDirective = null;
+  let namedRuleRangeDirective = null;
+
+  for (const directive of directives) {
+    if (directive.node.loc.start.line > message.line) {
+      break;
+    }
+    if (directive.type === "utlint-ignore-start") {
+      if (directive.ruleId == null) {
+        allRulesRangeDirective ??= directive;
+        allRulesRangeDepth += 1;
+      } else if (directive.ruleId === message.ruleId) {
+        namedRuleRangeDirective ??= directive;
+        namedRuleRangeDepth += 1;
+      }
+      continue;
+    }
+    if (directive.type === "utlint-ignore-end") {
+      if (directive.ruleId == null && allRulesRangeDepth > 0) {
+        allRulesRangeDepth -= 1;
+        if (allRulesRangeDepth === 0) allRulesRangeDirective = null;
+      } else if (directive.ruleId === message.ruleId && namedRuleRangeDepth > 0) {
+        namedRuleRangeDepth -= 1;
+        if (namedRuleRangeDepth === 0) namedRuleRangeDirective = null;
+      }
+      continue;
+    }
+    if (directive.type === "utlint-ignore-all" && directive.topLevel && disableDirectiveMatchesRule(directive, message.ruleId)) {
+      return directive;
+    }
+    if (directive.type === "utlint-ignore" && directive.nextCodeLine === message.line && disableDirectiveMatchesRule(directive, message.ruleId)) {
+      return directive;
+    }
+  }
+
+  return namedRuleRangeDirective ?? allRulesRangeDirective;
+}
+
 function disableDirectiveForMessage(message, directives) {
   const active = {
     all: null,
@@ -3695,6 +3774,18 @@ function reportToESLintResults(report, textOptions = {}) {
     byFile.get(filePath).messages.push(diagnosticToESLintMessage(diagnostic, ruleSeverities));
   }
 
+  for (const diagnostic of report.suppressedDiagnostics ?? []) {
+    const filePath = textOptions.filePath ?? normalizeESLintFilePath(diagnostic.filePath, textOptions.cwd);
+    if (!byFile.has(filePath)) {
+      byFile.set(filePath, emptyESLintResult(filePath, textOptions.source));
+    }
+    const ruleSeverities = textOptions.ruleSeverityForFile?.(filePath) ?? textOptions.ruleSeverities;
+    if (diagnostic.ruleId && ruleSeverities?.get(diagnostic.ruleId) === 0) {
+      continue;
+    }
+    byFile.get(filePath).suppressedMessages.push(suppressedDiagnosticToESLintMessage(diagnostic, ruleSeverities));
+  }
+
   for (const fixed of report.outputs ?? []) {
     const filePath = textOptions.filePath ?? normalizeESLintFilePath(fixed.filePath, textOptions.cwd);
     if (!byFile.has(filePath)) {
@@ -4398,6 +4489,16 @@ function diagnosticToESLintMessage(diagnostic, ruleSeverities) {
   return message;
 }
 
+function suppressedDiagnosticToESLintMessage(diagnostic, ruleSeverities) {
+  return {
+    ...diagnosticToESLintMessage(diagnostic, ruleSeverities),
+    suppressions: [{
+      kind: diagnostic.suppression?.kind ?? "directive",
+      justification: diagnostic.suppression?.justification ?? ""
+    }]
+  };
+}
+
 function finalizeESLintResult(result) {
   result.errorCount = 0;
   result.warningCount = 0;

package/index.d.ts

@@ -9,10 +9,17 @@ export interface LintMessage {
   nodeType?: string | null;
   fix?: LintFix | LintFix[];
   suggestions?: LintSuggestion[];
+  suppressions?: LintSuppression[];
 }
 
-export interface LintDiagnostic extends Omit<LintMessage, "severity"> {
+export interface LintSuppression {
+  kind: "directive";
+  justification: string;
+}
+
+export interface LintDiagnostic extends Omit<LintMessage, "severity" | "suppressions"> {
   severity: "warning" | "error";
+  suppression?: LintSuppression;
 }
 
 export interface LintFix {
@@ -42,6 +49,7 @@ export interface LintReport {
   files: number;
   filePaths: string[];
   diagnostics: LintDiagnostic[];
+  suppressedDiagnostics: LintDiagnostic[];
   outputs?: Array<{ filePath: string; output: string }>;
   exitCode: number;
   stderr?: string;

package/index.js

@@ -517,7 +517,7 @@ export class UtooLint {
     const results = reportToESLintResults(report, {
       source: code,
       filePath,
-      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0,
+      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0 || (report.suppressedDiagnostics?.length ?? 0) > 0,
       ruleSeverityForFile: (filePath) => ruleSeverityMapForOptions(nativeOptions, filePath)
     });
     if (report.files !== 0) {
@@ -635,7 +635,10 @@ export class Linter {
       config: calculatedConfig({ cwd: verifyOptions.cwd, noConfig: true, overrideConfig: config }, normalizedFilePath)
     });
     const customRuleFilter = applyDisableDirectives(customRuleMessages, sourceCode);
-    this.suppressedMessages = customRuleFilter.suppressedMessages;
+    this.suppressedMessages = [
+      ...(report.suppressedDiagnostics ?? []).map((diagnostic) => suppressedDiagnosticToESLintMessage(diagnostic, ruleSeverities)),
+      ...customRuleFilter.suppressedMessages
+    ];
     this.times = { passes: [] };
     this.fixPassCount = 0;
     return [
@@ -944,14 +947,18 @@ function applyDisableDirectives(messages, sourceCode) {
   const directives = sourceCode.getDisableDirectives()
     .filter((directive) => directive.node?.loc?.start?.line)
     .sort((left, right) => left.node.loc.start.line - right.node.loc.start.line);
-  if (directives.length === 0) {
+  const utlintDirectives = sourceCode.getAllComments()
+    .map((comment) => utlintDirectiveFromComment(comment, sourceCode))
+    .filter(Boolean)
+    .sort((left, right) => left.node.range[0] - right.node.range[0]);
+  if (directives.length === 0 && utlintDirectives.length === 0) {
     return { messages, suppressedMessages: [] };
   }
 
   const kept = [];
   const suppressed = [];
   for (const message of messages) {
-    const directive = disableDirectiveForMessage(message, directives);
+    const directive = utlintDirectiveForMessage(message, utlintDirectives) ?? disableDirectiveForMessage(message, directives);
     if (directive) {
       suppressed.push({
         ...message,
@@ -967,6 +974,68 @@ function applyDisableDirectives(messages, sourceCode) {
   return { messages: kept, suppressedMessages: suppressed };
 }
 
+function utlintDirectiveFromComment(comment, sourceCode) {
+  const match = String(comment?.value ?? "").trim().match(/^(utlint-ignore(?:-all|-start|-end)?)\b\s*(.*)$/u);
+  if (!match) {
+    return null;
+  }
+
+  const [, type, tail] = match;
+  const colon = tail.indexOf(":");
+  const rawRuleId = (colon === -1 ? tail : tail.slice(0, colon)).trim();
+  const justification = colon === -1 ? "" : tail.slice(colon + 1).trim();
+  const nextToken = sourceCode.getAllTokens().find((token) => token.range?.[0] >= comment.range?.[1]);
+  return {
+    type,
+    node: comment,
+    ruleId: rawRuleId || null,
+    justification,
+    nextCodeLine: nextToken?.loc?.start?.line ?? null,
+    topLevel: sourceCode.getAllTokens().every((token) => token.range?.[0] >= comment.range?.[0])
+  };
+}
+
+function utlintDirectiveForMessage(message, directives) {
+  let allRulesRangeDepth = 0;
+  let namedRuleRangeDepth = 0;
+  let allRulesRangeDirective = null;
+  let namedRuleRangeDirective = null;
+
+  for (const directive of directives) {
+    if (directive.node.loc.start.line > message.line) {
+      break;
+    }
+    if (directive.type === "utlint-ignore-start") {
+      if (directive.ruleId == null) {
+        allRulesRangeDirective ??= directive;
+        allRulesRangeDepth += 1;
+      } else if (directive.ruleId === message.ruleId) {
+        namedRuleRangeDirective ??= directive;
+        namedRuleRangeDepth += 1;
+      }
+      continue;
+    }
+    if (directive.type === "utlint-ignore-end") {
+      if (directive.ruleId == null && allRulesRangeDepth > 0) {
+        allRulesRangeDepth -= 1;
+        if (allRulesRangeDepth === 0) allRulesRangeDirective = null;
+      } else if (directive.ruleId === message.ruleId && namedRuleRangeDepth > 0) {
+        namedRuleRangeDepth -= 1;
+        if (namedRuleRangeDepth === 0) namedRuleRangeDirective = null;
+      }
+      continue;
+    }
+    if (directive.type === "utlint-ignore-all" && directive.topLevel && disableDirectiveMatchesRule(directive, message.ruleId)) {
+      return directive;
+    }
+    if (directive.type === "utlint-ignore" && directive.nextCodeLine === message.line && disableDirectiveMatchesRule(directive, message.ruleId)) {
+      return directive;
+    }
+  }
+
+  return namedRuleRangeDirective ?? allRulesRangeDirective;
+}
+
 function disableDirectiveForMessage(message, directives) {
   const active = {
     all: null,
@@ -2477,7 +2546,7 @@ export class CLIEngine {
     const results = maybeFilterQuietResults(reportToESLintResults(report, {
       source: code,
       filePath: normalizeESLintFilePath(filePath, mergedOptions.cwd),
-      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0,
+      includeEmptyTextResult: report.files !== 0 || (report.diagnostics?.length ?? 0) > 0 || (report.suppressedDiagnostics?.length ?? 0) > 0,
       ruleSeverityForFile: (filePath) => ruleSeverityMapForOptions(mergedOptions, filePath)
     }), mergedOptions);
     return resultsToCLIEngineReport(results);
@@ -2678,6 +2747,7 @@ function publicCliReport(report) {
     files: report.files ?? 0,
     filePaths: report.filePaths ?? [],
     diagnostics: report.diagnostics ?? [],
+    suppressedDiagnostics: report.suppressedDiagnostics ?? [],
     outputs: report.outputs ?? []
   };
 }
@@ -2976,7 +3046,7 @@ export function lintFiles(paths, options = {}) {
   const ignoredDiagnostics = ignoredLintPathDiagnostics(targets, options);
   const lintPaths = filteredLintPaths(targets, options);
   if (lintPaths.length === 0) {
-    return { files: 0, filePaths: [], diagnostics: ignoredDiagnostics, exitCode: exitCodeForDiagnostics(ignoredDiagnostics) };
+    return { files: 0, filePaths: [], diagnostics: ignoredDiagnostics, suppressedDiagnostics: [], exitCode: exitCodeForDiagnostics(ignoredDiagnostics) };
   }
 
   const configRuns = nativeConfigRunsForFiles(expandNativeConfigRunPaths(lintPaths, options), options);
@@ -3041,8 +3111,10 @@ function finalizeLintReport(report, ignoredDiagnostics, options) {
   if (!options.deferDiagnosticConfigFiltering) {
     report.filePaths = normalizeReportFilePaths(report.filePaths, options);
     report.diagnostics = normalizeDiagnosticFilePaths(report.diagnostics, options);
+    report.suppressedDiagnostics = normalizeDiagnosticFilePaths(report.suppressedDiagnostics, options);
     report.outputs = normalizeReportOutputs(report.outputs, options);
     report.diagnostics = normalizeReportDiagnostics(report.diagnostics, options);
+    report.suppressedDiagnostics = normalizeReportDiagnostics(report.suppressedDiagnostics, options);
     report.exitCode = exitCodeForDiagnostics(report.diagnostics);
   }
   return report;
@@ -3139,6 +3211,7 @@ function mergeNativeReports(reports) {
     files: reports.reduce((count, item) => count + (item.files ?? 0), 0),
     filePaths: reports.flatMap((item) => item.filePaths ?? []),
     diagnostics: reports.flatMap((item) => item.diagnostics ?? []),
+    suppressedDiagnostics: reports.flatMap((item) => item.suppressedDiagnostics ?? []),
     outputs: reports.flatMap((item) => item.outputs ?? []),
     exitCode: reports.some((item) => item.exitCode) ? 1 : 0
   };
@@ -3171,6 +3244,7 @@ export function lintText(code, options = {}) {
         files: 0,
         filePaths: [],
         diagnostics,
+        suppressedDiagnostics: [],
         exitCode: exitCodeForDiagnostics(diagnostics)
       };
     }
@@ -3192,7 +3266,12 @@ export function lintText(code, options = {}) {
       ...diagnostic,
       filePath: requestedPath
     }));
+    report.suppressedDiagnostics = (report.suppressedDiagnostics ?? []).map((diagnostic) => ({
+      ...diagnostic,
+      filePath: requestedPath
+    }));
     report.diagnostics = normalizeReportDiagnostics(report.diagnostics, options);
+    report.suppressedDiagnostics = normalizeReportDiagnostics(report.suppressedDiagnostics, options);
     report.exitCode = exitCodeForDiagnostics(report.diagnostics);
     return report;
   } finally {
@@ -3698,6 +3777,18 @@ function reportToESLintResults(report, textOptions = {}) {
     byFile.get(filePath).messages.push(diagnosticToESLintMessage(diagnostic, ruleSeverities));
   }
 
+  for (const diagnostic of report.suppressedDiagnostics ?? []) {
+    const filePath = textOptions.filePath ?? normalizeESLintFilePath(diagnostic.filePath, textOptions.cwd);
+    if (!byFile.has(filePath)) {
+      byFile.set(filePath, emptyESLintResult(filePath, textOptions.source));
+    }
+    const ruleSeverities = textOptions.ruleSeverityForFile?.(filePath) ?? textOptions.ruleSeverities;
+    if (diagnostic.ruleId && ruleSeverities?.get(diagnostic.ruleId) === 0) {
+      continue;
+    }
+    byFile.get(filePath).suppressedMessages.push(suppressedDiagnosticToESLintMessage(diagnostic, ruleSeverities));
+  }
+
   for (const fixed of report.outputs ?? []) {
     const filePath = textOptions.filePath ?? normalizeESLintFilePath(fixed.filePath, textOptions.cwd);
     if (!byFile.has(filePath)) {
@@ -4401,6 +4492,16 @@ function diagnosticToESLintMessage(diagnostic, ruleSeverities) {
   return message;
 }
 
+function suppressedDiagnosticToESLintMessage(diagnostic, ruleSeverities) {
+  return {
+    ...diagnosticToESLintMessage(diagnostic, ruleSeverities),
+    suppressions: [{
+      kind: diagnostic.suppression?.kind ?? "directive",
+      justification: diagnostic.suppression?.justification ?? ""
+    }]
+  };
+}
+
 function finalizeESLintResult(result) {
   result.errorCount = 0;
   result.warningCount = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utoo/lint",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Experimental JavaScript and TypeScript linter powered by Yuku",
   "license": "MIT",
   "repository": {
@@ -76,11 +76,11 @@
     "use-at-your-own-risk.js"
   ],
   "optionalDependencies": {
-    "@utoo/lint-darwin-arm64": "0.2.7",
-    "@utoo/lint-darwin-x64": "0.2.7",
-    "@utoo/lint-linux-arm64": "0.2.7",
-    "@utoo/lint-linux-x64": "0.2.7",
-    "@utoo/lint-win32-x64": "0.2.7"
+    "@utoo/lint-darwin-arm64": "0.2.8",
+    "@utoo/lint-darwin-x64": "0.2.8",
+    "@utoo/lint-linux-arm64": "0.2.8",
+    "@utoo/lint-linux-x64": "0.2.8",
+    "@utoo/lint-win32-x64": "0.2.8"
   },
   "dependencies": {
     "jiti": "2.7.0"