eslint-plugin-use-agnostic 0.10.7 → 0.11.1

package/README.md

@@ -74,9 +74,7 @@ With this list established, it thus becomes possible to recognize static import
 
 ## Caveats
 
-Only the first line of code in a file is observed for the presence of a directive. If no top-of-the-file directive is present or recognized, the file is considered to not have a directive, defaulting to being understood as a Server Logics Module if it doesn't use a JSX file extension (`.js`, `.ts`) or as a Server Components Module if it does (`.jsx`, `.tsx`).
-
-Aliased import paths are resolved only if your ESLint config file and your `tsconfig.json` file are in the same directory. At least to my knowledge, since the resolution depends on the `cwd` property from ESLint rules' `context` objects.
+Base url and aliased import paths are currently resolved under the assumption that `process.cwd()` and `context.cwd` have the same value.
 
 It is up to you to confirm that your Agnostic Modules are indeed agnostic, meaning that they have neither server- nor client-side code. `eslint-plugin-use-agnostic`, at least at this time, does not do this verification for you.
 
@@ -102,4 +100,4 @@ But not having a directive to distinguish between 1. non-special Server Modules
 
 This is what the `'use agnostic'` directive solves. It clearly marks a module to be an Agnostic Module. And if a module that used to lack a directive can now be marked as an Agnostic Module, this allows modules without a directive to finally, truly be Server Modules by default. And `eslint-plugin-use-agnostic` can work from there.
 
-A lot more needs to be done, and a lot of it unfortunately can only be optimized deeper into React's innerworkings. But if the introduction of `'use agnostic'` can already create such powerful static analysis, imagine what it could produce if only it were incorporated into React as an official directive of the Fullstack React Architecture.
+A lot more needs to be done, and I suspect a lot of it unfortunately can only be optimized deeperly into React's innerworkings. But if the introduction of `'use agnostic'` can already create such powerful static analysis, imagine what it could produce if only it were incorporated into React as an official directive of the Fullstack React Architecture.

package/library/_commons/constants/bases.js

@@ -1,3 +1,6 @@
+import { Linter } from "eslint";
+import tseslint from "typescript-eslint";
+
 /**
  * @typedef {import('../../../types/_commons/typedefs').Extensions} Extensions
  */
@@ -117,3 +120,12 @@ export const ARE_NOT_ALLOWED_TO_IMPORT = "are not allowed to import";
 export const skip = Object.freeze({
   skip: true,
 });
+
+// common linter for AST retrieval
+export const linter = new Linter();
+
+// ESLint configs language options
+export const typeScriptCompatible = Object.freeze({
+  // for compatibility with .ts and .tsx
+  parser: tseslint.parser,
+});

package/library/_commons/utilities/helpers.js

@@ -1,17 +1,20 @@
 import fs from "fs";
 import path from "path";
 
+import { Linter } from "eslint";
 import { loadConfig, createMatchPath } from "tsconfig-paths";
 
 import {
   EXTENSIONS,
   ARE_NOT_ALLOWED_TO_IMPORT,
   resolvedDirectives_resolvedModules,
+  // linter,
+  typeScriptCompatible,
 } from "../constants/bases.js";
 
 /**
- * @typedef {import('../../../types/_commons/typedefs').ResolvedDirectiveWithoutUseAgnosticStrategies} ResolvedDirectiveWithoutUseAgnosticStrategies
  * @typedef {import('../../../types/_commons/typedefs').Context<string, readonly unknown[]>} Context
+ * @typedef {import('../../../types/_commons/typedefs').ResolvedDirectiveWithoutUseAgnosticStrategies} ResolvedDirectiveWithoutUseAgnosticStrategies
  */
 
 /**
@@ -36,16 +39,16 @@ const findExistingPath = (basePath) => {
 
 /**
  * Resolves an import path to a filesystem path, handling:
- * - Aliases (via tsconfig.json `paths`)
- * - Missing extensions (appends .ts, .tsx, etc.)
+ * - Base url and aliases (via tsconfig.json `baseUrl` and `paths` compiler options)
+ * - Missing extensions (appends `.ts`, `.tsx`, etc.)
  * - Directory imports (e.g., `./components` → `./components/index.ts`)
  * @param {string} currentDir The directory of the file containing the import (from `path.dirname(context.filename)`).
  * @param {string} importPath The import specifier (e.g., `@/components/Button` or `./utils`), from the current node.
- * @param {string} cwd The project root (from `context.cwd`). Caveat: only as an assumption currently.
+ * @param {string} cwd The project root (from `context.cwd`).
  * @returns The absolute resolved path or `null` if no path is found.
  */
 export const resolveImportPath = (currentDir, importPath, cwd) => {
-  // Step 1: Resolve baseUrl and aliases (if tsconfig.json `paths` exists)
+  // Step 1: Resolves baseUrl and aliases
   const config = loadConfig(cwd);
 
   const resolveTSConfig =
@@ -53,12 +56,12 @@ export const resolveImportPath = (currentDir, importPath, cwd) => {
       ? createMatchPath(config.absoluteBaseUrl, config.paths)
       : null;
 
-  const aliasedPath = resolveTSConfig
+  const baseUrlOrAliasedPath = resolveTSConfig
     ? resolveTSConfig(importPath, undefined, undefined, EXTENSIONS)
     : null;
 
-  // Step 2: Resolve relative/absolute paths
-  const basePath = aliasedPath || path.resolve(currentDir, importPath);
+  // Step 2: Resolves relative/absolute paths
+  const basePath = baseUrlOrAliasedPath || path.resolve(currentDir, importPath);
 
   // does not resolve on node_modules
   if (basePath.includes("node_modules")) return null;
@@ -66,7 +69,7 @@ export const resolveImportPath = (currentDir, importPath, cwd) => {
   // Case 1: File with extension exists
   if (path.extname(importPath) && fs.existsSync(basePath)) return basePath;
 
-  // Case 2: Try appending extensions
+  // Case 2: Tries appending extensions
   const extensionlessImportPath = findExistingPath(basePath);
   if (extensionlessImportPath) return extensionlessImportPath;
 
@@ -78,7 +81,30 @@ export const resolveImportPath = (currentDir, importPath, cwd) => {
   return null; // not found
 };
 
-/* getImportedFileFirstLine */
+/* getASTFromResolvedPath */ // for agnostic20
+// Note: For agnostic20, I need the AST so that the directive can be picked up on any line as long as it is the first statement of the file.
+
+/**
+ * Gets the ESLint-generated Abstract Syntax Tree of a file from its resolved path.
+ * @param {string} resolvedPath The resolved path of the file.
+ * @returns The ESLint-generated AST (Abstract Syntax Tree) of the file.
+ */
+export const getASTFromFilePath = (resolvedPath) => {
+  const linter = new Linter();
+  // the raw code of the file at the end of the resolved path
+  const text = fs.readFileSync(resolvedPath, "utf8");
+  // utilizes linter.verify ...
+  linter.verify(text, { languageOptions: typeScriptCompatible });
+  // ... to retrieve the raw code as a SourceCode object ...
+  const code = linter.getSourceCode();
+  // ... from which to extra the ESLint-generated AST
+  const ast = code.ast;
+
+  return ast;
+};
+
+/* getImportedFileFirstLine */ // for directive21
+// Note: For directive21, I prioritize reading from the file system for performance, forgoing the retrieval of the source code comments for imported modules, since the Directive-First Architecture imposes that the first line of the file is reserved for its commented directive.
 
 /**
  * Gets the first line of code of the imported module.
@@ -114,9 +140,10 @@ export const highlightFirstLineOfCode = (context) => ({
 /**
  * Returns a boolean deciding if an imported file's "resolved" directive is incompatible with the current file's "resolved" directive.
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
+ * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
  * @param {ResolvedDirectives_BlockedImports<T>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
  * @param {T} currentFileResolvedDirective The current file's "resolved" directive.
- * @param {T} importedFileResolvedDirective The imported file's "resolved" directive.
+ * @param {U} importedFileResolvedDirective The imported file's "resolved" directive.
  * @returns `true` if the import is blocked, as established in respective `resolvedDirectives_blockedImports`.
  */
 export const isImportBlocked = (
@@ -135,8 +162,8 @@ export const isImportBlocked = (
  * Makes the intro for each specific import rule violation messages.
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
- * @param {T} currentFileResolvedDirective The current file's "resolved" directive, excluding `"use agnostic strategies"`.
- * @param {U} importedFileResolvedDirective The imported file's "resolved" directive, excluding `"use agnostic strategies"`.
+ * @param {T} currentFileResolvedDirective The current file's "resolved" directive.
+ * @param {U} importedFileResolvedDirective The imported file's "resolved" directive.
  * @returns "[Current file 'resolved' modules] are not allowed to import [imported file 'resolved' modules]."
  */
 export const makeIntroForSpecificViolationMessage = (
@@ -194,9 +221,10 @@ export const makeMessageFromCurrentFileResolvedDirective = (
 /**
  * Finds the `message` for the specific violation of "resolved" directives import rules based on `resolvedDirectives_blockedImports`.
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
+ * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
  * @param {ResolvedDirectives_BlockedImports<T>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
- * @param {T} currentFileResolvedDirective The current file's "resolved" directive, excluding `"use agnostic strategies"`.
- * @param {T} importedFileResolvedDirective The imported file's "resolved" directive.
+ * @param {T} currentFileResolvedDirective The current file's "resolved" directive.
+ * @param {U} importedFileResolvedDirective The imported file's "resolved" directive.
  * @returns The corresponding `message`.
  */
 export const findSpecificViolationMessage = (

package/library/agnostic20/_commons/constants/bases.js

@@ -54,28 +54,28 @@ export const FUNCTIONS = "functions";
 
 // mapping directives with effective directives
 /** @type {Directives_EffectiveDirectives} */
-export const directives_effectiveDirectives = {
-  [NO_DIRECTIVE]: {
+export const directives_effectiveDirectives = Object.freeze({
+  [NO_DIRECTIVE]: Object.freeze({
     [LOGICS]: USE_SERVER_LOGICS,
     [COMPONENTS]: USE_SERVER_COMPONENTS,
     [FUNCTIONS]: null,
-  },
-  [USE_SERVER]: {
+  }),
+  [USE_SERVER]: Object.freeze({
     [LOGICS]: null,
     [COMPONENTS]: null,
     [FUNCTIONS]: USE_SERVER_FUNCTIONS,
-  },
-  [USE_CLIENT]: {
+  }),
+  [USE_CLIENT]: Object.freeze({
     [LOGICS]: USE_CLIENT_LOGICS,
     [COMPONENTS]: USE_CLIENT_COMPONENTS,
     [FUNCTIONS]: null,
-  },
-  [USE_AGNOSTIC]: {
+  }),
+  [USE_AGNOSTIC]: Object.freeze({
     [LOGICS]: USE_AGNOSTIC_LOGICS,
     [COMPONENTS]: USE_AGNOSTIC_COMPONENTS,
     [FUNCTIONS]: null,
-  },
-};
+  }),
+});
 
 // message placeholders
 export const currentFileEffectiveDirective = "currentFileEffectiveDirective";

package/library/agnostic20/_commons/utilities/flows.js

@@ -40,7 +40,7 @@ import {
 /* currentFileFlow */
 
 /**
- * The flow that begins the import rules enforcement rule, retrieving the valid directive of the current file before comparing it to upcoming valid directives of the files it imports.
+ * The flow that begins the import rules enforcement rule, retrieving the effective directive of the current file before comparing it to upcoming effective directives of the files it imports.
  * @param {Context} context The ESLint rule's `context` object.
  * @returns Either an object with `skip: true` to disregard or one with the non-null `currentFileEffectiveDirective`.
  */

package/library/agnostic20/_commons/utilities/helpers.js

@@ -9,13 +9,14 @@ import {
 } from "../constants/bases.js";
 
 import {
-  getImportedFileFirstLine,
   isImportBlocked as commonsIsImportBlocked,
   makeMessageFromCurrentFileResolvedDirective,
   findSpecificViolationMessage as commonsFindSpecificViolationMessage,
+  getASTFromFilePath,
 } from "../../../_commons/utilities/helpers.js";
 
 /**
+ * @typedef {import('../../../../types/agnostic20/_commons/typedefs.js').AST} AST
  * @typedef {import('../../../../types/agnostic20/_commons/typedefs.js').Context} Context
  * @typedef {import('../../../../types/agnostic20/_commons/typedefs.js').Directive} Directive
  * @typedef {import('../../../../types/agnostic20/_commons/typedefs.js').NoDirective} NoDirective
@@ -23,20 +24,20 @@ import {
  * @typedef {import('../../../../types/agnostic20/_commons/typedefs.js').EffectiveDirective} EffectiveDirective
  */
 
-/* getDirectiveFromCurrentModule */
+/* getDirectiveFromModule */
 
 /**
- * Gets the directive of the current module.
+ * Gets the directive of a module from its Abstract Syntax Tree.
  * - `null` denotes a server-by-default module, ideally a Server Module.
  * - `'use client'` denotes a Client Module.
  * - `'use server'` denotes a Server Functions Module.
  * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
- * @param {Context} context The ESLint rule's `context` object.
+ * @param {AST} ast The module's AST (Abstract Syntax Tree).
  * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
  */
-export const getDirectiveFromCurrentModule = (context) => {
+export const getDirectiveFromModule = (ast) => {
   // the AST body to check for the top-of-the-file directive
-  const { body } = context.sourceCode.ast;
+  const { body } = ast;
 
   // the first statement from the source code's Abstract Syntax Tree
   const firstStatement = body[0];
@@ -52,10 +53,46 @@ export const getDirectiveFromCurrentModule = (context) => {
   if (value === null) return value;
 
   // the value to be exactly 'use client', 'use server' or 'use agnostic' in order not to be considered null by default, or server-by-default
-  const currentFileDirective =
+  const moduleDirective =
     directivesArray.find((directive) => directive === value) ?? null;
 
-  return currentFileDirective;
+  return moduleDirective;
+};
+
+/* getDirectiveFromCurrentModule */
+
+/**
+ * Gets the directive of the current module.
+ * - `null` denotes a server-by-default module, ideally a Server Module.
+ * - `'use client'` denotes a Client Module.
+ * - `'use server'` denotes a Server Functions Module.
+ * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
+ * @param {Context} context The ESLint rule's `context` object.
+ * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ */
+export const getDirectiveFromCurrentModule = (context) => {
+  // the AST of the current module
+  const ast = context.sourceCode.ast;
+
+  return getDirectiveFromModule(ast);
+};
+
+/* getDirectiveFromImportedModule */
+
+/**
+ * Gets the directive of the imported module.
+ * - `'use client'` denotes a Client Module.
+ * - `'use server'` denotes a Server Functions Module.
+ * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
+ * - `null` denotes a server-by-default module, ideally a Server Module.
+ * @param {string} resolvedImportPath The resolved path of the import.
+ * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ */
+export const getDirectiveFromImportedModule = (resolvedImportPath) => {
+  // the AST of the imported module
+  const ast = getASTFromFilePath(resolvedImportPath);
+
+  return getDirectiveFromModule(ast);
 };
 
 /* getEffectiveDirective */
@@ -83,38 +120,6 @@ export const getEffectiveDirective = (directive, extension) => {
   return directives_effectiveDirectives[directive][moduleKind];
 };
 
-/* getDirectiveFromImportedModule */
-
-/**
- * Gets the directive of the imported module.
- * - `'use client'` denotes a Client Module.
- * - `'use server'` denotes a Server Functions Module.
- * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
- * - `null` denotes a server-by-default module, ideally a Server Module.
- * @param {string} resolvedImportPath The resolved path of the import.
- * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
- */
-export const getDirectiveFromImportedModule = (resolvedImportPath) => {
-  // gets the first line of the code of the import
-  const importedFileFirstLine = getImportedFileFirstLine(resolvedImportPath);
-
-  // verifies that this first line starts with a valid directive, thus excluding comments
-  const hasAcceptedDirective = directivesArray.some(
-    (directive) =>
-      importedFileFirstLine.startsWith(`'${directive}'`) ||
-      importedFileFirstLine.startsWith(`"${directive}"`)
-  );
-
-  // applies the correct directive or the lack thereof with null
-  const importedFileDirective = hasAcceptedDirective
-    ? directivesArray.find((directive) =>
-        importedFileFirstLine.includes(directive)
-      ) ?? null
-    : null;
-
-  return importedFileDirective;
-};
-
 /* isImportBlocked */
 
 /**

package/library/agnostic20/config.js

@@ -1,10 +1,10 @@
 import { defineConfig } from "eslint/config";
-import tseslint from "typescript-eslint";
 
 import {
   agnostic20ConfigName,
   useAgnosticPluginName,
   enforceEffectiveDirectivesRuleName,
+  typeScriptCompatible,
 } from "../_commons/constants/bases.js";
 
 /**
@@ -26,10 +26,7 @@ export const makeAgnostic20Config = (plugin) => ({
         [`${useAgnosticPluginName}/${enforceEffectiveDirectivesRuleName}`]:
           "warn",
       },
-      languageOptions: {
-        // for compatibility with .ts and .tsx
-        parser: tseslint.parser,
-      },
+      languageOptions: typeScriptCompatible,
     },
   ]),
 });

package/library/directive21/_commons/utilities/helpers.js

@@ -11,10 +11,10 @@ import {
 } from "../constants/bases.js";
 
 import {
-  getImportedFileFirstLine,
   isImportBlocked as commonsIsImportBlocked,
   makeMessageFromCurrentFileResolvedDirective,
   findSpecificViolationMessage as commonsFindSpecificViolationMessage,
+  getImportedFileFirstLine,
 } from "../../../_commons/utilities/helpers.js";
 
 /**

package/library/directive21/config.js

@@ -1,10 +1,10 @@
 import { defineConfig } from "eslint/config";
-import tseslint from "typescript-eslint";
 
 import {
   directive21ConfigName,
   useAgnosticPluginName,
   enforceCommentedDirectivesRuleName,
+  typeScriptCompatible,
 } from "../_commons/constants/bases.js";
 
 /**
@@ -26,10 +26,7 @@ export const makeDirective21Config = (plugin) => ({
         [`${useAgnosticPluginName}/${enforceCommentedDirectivesRuleName}`]:
           "warn",
       },
-      languageOptions: {
-        // for compatibility with .ts and .tsx
-        parser: tseslint.parser,
-      },
+      languageOptions: typeScriptCompatible,
     },
   ]),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-use-agnostic",
-  "version": "0.10.7",
+  "version": "0.11.1",
   "description": "Highlights problematic server-client imports in projects made with the Fullstack React Architecture.",
   "keywords": [
     "eslint",