Project-wide rules

CHANGELOG.md

@@ -1,8 +1,51 @@
 # Changelog
 
-## Unreleased
-
-- Deprecate `context.rawChecker`. Types overrides from `context.checker` have been updated so it can be passed to other libraries. Thanks @JoshuaKGoldberg for challenging this!
+## 1.1.0
+
+### Project-wide rules (experimental)
+
+Rules can now implement an `aggregate` function that will be called once for all files that have been linted. This allows to implement rules that require cross-file analysis, like detecting circular dependencies.
+
+```ts
+import { type AST, core, defineConfig } from "tsl";
+
+type ImportsData = {
+  imports: { path: string; node: AST.ImportDeclaration }[];
+};
+
+export default defineConfig({
+  rules: [
+    ...core.all(),
+    {
+      name: "org/noCircularDependencies",
+      createData: (): ImportsData => ({ imports: [] }),
+      visitor: {
+        ImportDeclaration(context, node) {
+          context.data.imports.push({ path: toAbsolutePath(node), node });
+        },
+      },
+      aggregate(context, files) {
+        //                ^ { sourceFile: AST.SourceFile; data: ImportsData }[]
+        for (const circularEntry of getCircularDependencies(files)) {
+          context.report({
+            message: "Circular dependency detected",
+            sourceFile: circularEntry.sourceFile,
+            node: circularEntry.data.imports[circularEntry.importIndex].node,
+          });
+        }
+      },
+    },
+  ],
+});
+```
+
+`enableProjectWideRulesInIDE` is an experimental new option to enable project-wide reports in the IDE (default to false). The IDE implementation is still a work in progress, and memory leaks or performance issues may occur.
+
+`core/unusedExport` is a new project-wide rule available with this release.
+
+### Deprecate `context.rawChecker`
+
+Types overrides of `context.checker` have been updated so it can be passed to other libraries. `context.rawChecker` is therefore not needed anymore and has been deprecated. Thanks @JoshuaKGoldberg for challenging this!
 
 ## 1.0.28
 

README.md

@@ -6,6 +6,7 @@ tsl is an extension of tsc for type-aware linting. It's designed to be used in c
 
 - Run type-aware rules [faster](https://github.com/ArnaudBarre/tsl/issues/3) than [typescript-eslint](https://typescript-eslint.io/)
 - Type safe config with custom rules in TypeScript
+- Project-wide rules (experimental)
 - No [IDE caching issue](https://typescript-eslint.io/troubleshooting/faqs/general/#changes-to-one-file-are-not-reflected-when-linting-other-files-in-my-ide)
 - Something missing? Look at the [roadmap](https://github.com/ArnaudBarre/tsl/issues/4) or [open an issue](https://github.com/ArnaudBarre/tsl/issues/new)
 
@@ -200,6 +201,10 @@ Like the ignore option, the `files` option test for inclusion against the file p
 
 Redeclared rules (identical name) completely replace the "base" rule, there is no merging of options.
 
+### enableProjectWideRulesInIDE (experimental)
+
+Enable project-wide rules in IDE. The IDE implementation is still a work in progress, and memory leaks or performance issues may occur. Enable and report issues if you encounter any.
+
 ## Ignore comments
 
 Rules reports can be ignored with line comments (ignore next line) or one line block comments (ignore for the whole file).
@@ -271,9 +276,58 @@ export default defineConfig({
 });
 ```
 
+### Project-wide rules (added in 1.1.0, experimental)
+
+Rules can optionally implement an `aggregate` function that will be called once for all files that have been linted. This allows to implement rules that require cross-file analysis, like detecting circular dependencies.
+
+```ts
+import { type AST, core, defineConfig } from "tsl";
+
+type ImportsData = {
+  imports: { path: string; node: AST.ImportDeclaration }[];
+};
+
+export default defineConfig({
+  rules: [
+    ...core.all(),
+    {
+      name: "org/noCircularDependencies",
+      createData: (): ImportsData => ({ imports: [] }),
+      visitor: {
+        ImportDeclaration(context, node) {
+          context.data.imports.push({ path: toAbsolutePath(node), node });
+        },
+      },
+      aggregate(context, files) {
+        //                ^ { sourceFile: AST.SourceFile; data: ImportsData }[]
+        for (const circularEntry of getCircularDependencies(files)) {
+          context.report({
+            message: "Circular dependency detected",
+            sourceFile: circularEntry.sourceFile,
+            node: circularEntry.data.imports[circularEntry.importIndex].node,
+          });
+        }
+      },
+    },
+  ],
+});
+```
+
+> [!CAUTION]
+> Project-wide rules are currently not supported inside overrides
+
+> [!IMPORTANT]
+> The list of files is only files that were linted. If you need a generated file to be in that list, but you still want to ignore all lint rules inside it, use a top level ignore comment instead of using the ignore option.
+
 ## Core rules
 
-Currently, the list of core rules are the type-aware lint rules I use from typescript-eslint. If you think more rules should be added, please open an issue, but to reduce the surface, only non-styling type-aware rules will be accepted. Here is the list of [typescript-eslint type aware rules](https://typescript-eslint.io/rules/?=typeInformation) with their status:
+### Exclusive rules
+
+- unusedExport: Detect unused exports (Using experimental project-wide linting)
+
+### From typescript-eslint
+
+Currently, the ported rules are the type-aware lint rules I use from typescript-eslint. If you think more rules should be added, please open an issue, but to reduce the surface, only non-styling type-aware rules will be accepted. Here is the list of [typescript-eslint type aware rules](https://typescript-eslint.io/rules/?=typeInformation) with their status:
 
 - await-thenable: ✅ Implemented
 - consistent-return: 🛑 Implementation not planned, you can use `noImplicitReturns` compilerOption

src/cli.ts

@@ -8,7 +8,7 @@ import {
   type TSLDiagnostic,
 } from "./formatDiagnostic.ts";
 import { core } from "./index.ts";
-import { initRules } from "./initRules.ts";
+import { initRules, type Report } from "./initRules.ts";
 import { loadConfig } from "./loadConfig.ts";
 
 const { values } = parseArgs({
@@ -75,11 +75,12 @@ if (values.timing) {
 
 const configStart = performance.now();
 const { config } = await loadConfig(program);
-const { lint, allRules, timingMaps } = await initRules(
-  () => program,
-  config ?? { rules: core.all() },
-  values.timing,
-);
+const { lint, allRules, aggregate, getUnusedIgnoreComments, timingMaps } =
+  await initRules(
+    () => program,
+    config ?? { rules: core.all() },
+    values.timing,
+  );
 if (values.timing) {
   console.log(
     `Config with ${allRules.size} ${
@@ -118,39 +119,65 @@ const lintStart = performance.now();
 
 const files = program.getSourceFiles();
 
+function onReport(
+  sourceFile: ts.SourceFile,
+  r: Report,
+  currentIdx: number | undefined,
+) {
+  if (currentIdx === undefined) {
+    const lastTsDiagnostic = diagnostics.findLastIndex(
+      (d) => d.file === sourceFile,
+    );
+    if (lastTsDiagnostic !== -1) {
+      currentIdx = lastTsDiagnostic + 1;
+    } else {
+      const sortIdx = diagnostics.findIndex((d, i) => {
+        const previousFile = i === 0 ? undefined : diagnostics[i - 1].file;
+        return (
+          d.file !== undefined
+          && sourceFile.fileName < d.file.fileName
+          && (previousFile === undefined
+            || sourceFile.fileName > previousFile.fileName)
+        );
+      });
+      currentIdx = sortIdx === -1 ? diagnostics.length : sortIdx;
+    }
+  } else {
+    currentIdx++;
+  }
+  diagnostics.splice(currentIdx, 0, {
+    file: sourceFile,
+    name: r.type === "rule" ? r.rule.name : "tsl-unused-ignore",
+    message: r.message,
+    start: "node" in r ? r.node.getStart() : r.start,
+    length: "node" in r ? r.node.getEnd() - r.node.getStart() : r.end - r.start,
+  });
+  return currentIdx;
+}
+
 for (const it of files) {
   let currentIdx: number | undefined = undefined;
   lint(it as unknown as SourceFile, (r) => {
-    if (currentIdx === undefined) {
-      const lastTsDiagnostic = diagnostics.findLastIndex((d) => d.file === it);
-      if (lastTsDiagnostic !== -1) {
-        currentIdx = lastTsDiagnostic + 1;
-      } else {
-        const sortIdx = diagnostics.findIndex((d, i) => {
-          const previousFile = i === 0 ? undefined : diagnostics[i - 1].file;
-          return (
-            d.file !== undefined
-            && it.fileName < d.file.fileName
-            && (previousFile === undefined
-              || it.fileName > previousFile.fileName)
-          );
-        });
-        currentIdx = sortIdx === -1 ? diagnostics.length : sortIdx;
-      }
-    } else {
-      currentIdx++;
-    }
-    diagnostics.splice(currentIdx, 0, {
-      file: it,
-      name: r.type === "rule" ? r.rule.name : "tsl-unused-ignore",
-      message: r.message,
-      start: "node" in r ? r.node.getStart() : r.start,
-      length:
-        "node" in r ? r.node.getEnd() - r.node.getStart() : r.end - r.start,
-    });
+    currentIdx = onReport(it, r, currentIdx);
   });
 }
 
+const aggregateReports = aggregate();
+for (const [sourceFile, reports] of aggregateReports) {
+  for (const report of reports) {
+    onReport(sourceFile, report, undefined);
+  }
+}
+
+const unusedIgnoreComments = getUnusedIgnoreComments({
+  includeProjectWideRules: true,
+});
+for (const [sourceFile, reports] of unusedIgnoreComments) {
+  for (const report of reports) {
+    onReport(sourceFile, report, undefined);
+  }
+}
+
 if (values.timing) {
   console.log(`Lint ran in ${displayTiming(lintStart)}`);
 }

src/formatDiagnostic.ts

@@ -179,7 +179,7 @@ function formatCodeSpan(
   return context;
 }
 
-export function formatLocation(file: SourceFile, start: number): string {
+function formatLocation(file: SourceFile, start: number): string {
   const { line, character } = getLineAndCharacterOfPosition(file, start);
   const relativeFileName = displayFilename(file.fileName);
   let output = "";