eslint-plugin-use-agnostic 1.0.0 → 1.1.0

package/README.md

@@ -78,7 +78,7 @@ Base url and aliased import paths are currently resolved under the assumption th
 
 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.
 
-It is also up to you to ensure, as outlined above, that **you avoid** exporting React components along with other logics within the same module, which may derail the linting in some cases. Separating exporting React components within their own modules ending with a JSX file extension, from exporting other logics within modules that don't end with a JSX file extension, is crucial for distinguishing between Components Modules and Logics Modules respectively.
+It is also up to you to ensure, as outlined above, that **you avoid** exporting React components along with other logics within the same modules (unless you have to per the design of your current framework), which may derail the linting in some cases. Separating exporting React components within their own modules ending with a JSX file extension, from exporting other logics within modules that don't end with a JSX file extension, is crucial for distinguishing between Components Modules and Logics Modules respectively.
 
 The import rules are designed to be as permissive as possible, allowing for more obscure use cases as long as they are non-breaking. However, it is still your responsibility as a developer to, within a file, not mix in incompatible ways code that cannot compose.
 

package/library/_commons/utilities/helpers.js

@@ -81,15 +81,14 @@ export const resolveImportPath = (currentDir, importPath, cwd) => {
   return null; // not found
 };
 
-/* 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.
+/* getSourceCodeFromFilePath */
 
 /**
- * Gets the ESLint-generated Abstract Syntax Tree of a file from its resolved path.
+ * Gets the ESLint-generated SourceCode object 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.
+ * @returns The ESLint-generated SourceCode object of the file.
  */
-export const getASTFromFilePath = (resolvedPath) => {
+export const getSourceCodeFromFilePath = (resolvedPath) => {
   // ensures each instance of the function is based on its own linter
   // (just in case somehow some linters were running concurrently)
   const linter = new Linter();
@@ -97,32 +96,10 @@ export const getASTFromFilePath = (resolvedPath) => {
   const text = fs.readFileSync(resolvedPath, "utf8");
   // utilizes linter.verify ...
   linter.verify(text, { languageOptions: typeScriptAndJSXCompatible });
-  // ... to retrieve the raw code as a SourceCode object ...
+  // ... to retrieve the raw code as a SourceCode object
   const code = linter.getSourceCode();
-  // ... from which to extract 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, foregoing 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.
- * @param {string} resolvedImportPath The resolved path of the imported module.
- * @returns The first line of the imported module.
- */
-export const getImportedFileFirstLine = (resolvedImportPath) => {
-  // gets the code of the import
-  const importedFileContent = fs.readFileSync(resolvedImportPath, "utf8");
-  // gets the first line of the code of the import
-  const importedFileFirstLine = importedFileContent
-    .trim()
-    .split("\n")[0]
-    .trim(); // the line itself needs to be trimmed too
-
-  return importedFileFirstLine;
+  return code;
 };
 
 /* highlightFirstLineOfCode */

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

@@ -12,7 +12,7 @@ import {
   isImportBlocked as commonsIsImportBlocked,
   makeMessageFromCurrentFileResolvedDirective,
   findSpecificViolationMessage as commonsFindSpecificViolationMessage,
-  getASTFromFilePath,
+  getSourceCodeFromFilePath,
 } from "../../../_commons/utilities/helpers.js";
 
 /**
@@ -85,12 +85,12 @@ export const getDirectiveFromCurrentModule = (context) => {
  * - `'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.
+ * @param {string} resolvedPath The resolved path of the imported module.
  * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
  */
-export const getDirectiveFromImportedModule = (resolvedImportPath) => {
+export const getDirectiveFromImportedModule = (resolvedPath) => {
   // the AST of the imported module
-  const ast = getASTFromFilePath(resolvedImportPath);
+  const ast = getSourceCodeFromFilePath(resolvedPath).ast;
 
   return getDirectiveFromModule(ast);
 };

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

@@ -119,48 +119,6 @@ export const commentedDirectiveMessage = "commentedDirectiveMessage";
 export const specificViolationMessage = "specificViolationMessage";
 export const specificFailure = "specificFailure";
 
-/* commentedDirectives_4RawImplementations */
-
-// all formatting styles as an array of [prefix, quote, suffix]
-/** @type {CommentStyles} */
-const commentStyles = Object.freeze([
-  Object.freeze([`// `, `'`, ``]), // V1: `// 'directive'`
-  Object.freeze([`// `, `"`, ``]), // V2: `// "directive"`
-  Object.freeze([`\/\* `, `'`, ` \*\/`]), // V3: `/* 'directive' */`
-  Object.freeze([`\/\* `, `"`, ` \*\/`]), // V4: `/* "directive" */`
-]);
-
-/**
- * Makes the array of all four accepted commented directive implementations on a directive basis.
- * @template {CommentedDirective} T
- * @param {T} directive The commented directive.
- * @returns The array of formatted commented directives.
- */
-const make4RawImplementations = (directive) => {
-  /** @type {readonly [`// '${T}'`, `// "${T}""`, `\/\* '${T}' \*\/`, `\/\* "${T}"" \*\/`]} */
-  const rawImplementations = Object.freeze(
-    commentStyles.map(
-      ([prefix, quote, suffix]) =>
-        `${prefix}${quote}${directive}${quote}${suffix}`
-    )
-  );
-
-  return rawImplementations;
-};
-
-export const commentedDirectives_4RawImplementations = Object.freeze({
-  [USE_SERVER_LOGICS]: make4RawImplementations(USE_SERVER_LOGICS),
-  [USE_CLIENT_LOGICS]: make4RawImplementations(USE_CLIENT_LOGICS),
-  [USE_AGNOSTIC_LOGICS]: make4RawImplementations(USE_AGNOSTIC_LOGICS),
-  [USE_SERVER_COMPONENTS]: make4RawImplementations(USE_SERVER_COMPONENTS),
-  [USE_CLIENT_COMPONENTS]: make4RawImplementations(USE_CLIENT_COMPONENTS),
-  [USE_AGNOSTIC_COMPONENTS]: make4RawImplementations(USE_AGNOSTIC_COMPONENTS),
-  [USE_SERVER_FUNCTIONS]: make4RawImplementations(USE_SERVER_FUNCTIONS),
-  [USE_CLIENT_CONTEXTS]: make4RawImplementations(USE_CLIENT_CONTEXTS),
-  [USE_AGNOSTIC_CONDITIONS]: make4RawImplementations(USE_AGNOSTIC_CONDITIONS),
-  [USE_AGNOSTIC_STRATEGIES]: make4RawImplementations(USE_AGNOSTIC_STRATEGIES),
-});
-
 /* commentedDirectives_verificationReports */
 
 const MODULES_MARKED_WITH_THE_ = "modules marked with the";

package/library/directive21/_commons/rules/import-rules.js

@@ -39,7 +39,7 @@ Here, "{{ ${currentFileCommentedDirective} }}" and "{{ ${importedFileCommentedDi
       [importBreaksCommentedImportRulesMessageId]: `{{ ${commentedDirectiveMessage} }} 
 In this case, {{ ${specificViolationMessage} }} `,
       [noCommentedDirective]: `No commented directive detected.
-All targeted modules need to be marked with their respective directives (\`// "use server logics"\`, etc.) for the purpose of this linting rule. `,
+All targeted modules need to be marked with their respective directives (\`// "use server logics"\`, etc.) for the purpose of this linting rule, evaluated from the first JavaScript comment starting on the first column within the first three lines of a module. `,
       [commentedDirectiveVerificationFailed]: `The commented directive could not pass verification due to an incompatible combination with its file extension.
 In this context, {{ ${specificFailure} }} `,
       [importNotStrategized]: `Imports from Agnostic Strategies Modules must be strategized (\`/* @serverLogics */\`, etc.).  

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

@@ -1,11 +1,9 @@
 import { exportNotStrategized } from "../../../_commons/constants/bases.js";
 import {
-  USE_AGNOSTIC_LOGICS,
   USE_AGNOSTIC_STRATEGIES,
   commentedDirectivesArray,
   strategiesArray,
   commentedDirectives_extensionRules,
-  commentedDirectives_4RawImplementations,
   commentedStrategies_commentedDirectives,
   commentedDirectives_blockedImports,
 } from "../constants/bases.js";
@@ -14,10 +12,11 @@ import {
   isImportBlocked as commonsIsImportBlocked,
   makeMessageFromCurrentFileResolvedDirective,
   findSpecificViolationMessage as commonsFindSpecificViolationMessage,
-  getImportedFileFirstLine,
+  getSourceCodeFromFilePath,
 } from "../../../_commons/utilities/helpers.js";
 
 /**
+ * @typedef {import('../../../../types/directive21/_commons/typedefs.js').SourceCode} SourceCode
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').Context} Context
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').CommentedDirective} CommentedDirective
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').CommentedDirectiveWithoutUseAgnosticStrategies} CommentedDirectiveWithoutUseAgnosticStrategies
@@ -28,7 +27,7 @@ import {
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').ExportDefaultDeclaration} ExportDefaultDeclaration
  */
 
-/* getCommentedDirectiveFromCurrentModule */
+/* getCommentedDirectiveFromSourceCode */
 
 /**
  * Detects whether a string is single- or double-quoted.
@@ -70,7 +69,7 @@ const stripDoubleQuotes = (string) => {
 };
 
 /**
- * Gets the commented directive of the current module.
+ * Gets the commented directive of a module from its ESLint SourceCode object.
  *
  * Accepted directives for the default Directive-First Architecture are (single or double quotes included):
  * - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
@@ -84,19 +83,26 @@ const stripDoubleQuotes = (string) => {
  * - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
  * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
  * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
- * @param {Context} context The ESLint rule's `context` object.
+ * @param {SourceCode} sourceCode The ESLint SourceCode object.
  * @returns The commented directive, or lack thereof via `null`. Given the strictness of this architecture, the lack of a directive is considered a mistake. (Though rules may provide the opportunity to declare a default, and configs with preset defaults may become provided.)
  */
-export const getCommentedDirectiveFromCurrentModule = (context) => {
+export const getCommentedDirectiveFromSourceCode = (sourceCode) => {
   // gets the first comment from the source code
-  const firstComment = context.sourceCode.getAllComments()[0];
+  const rawFirstComment = sourceCode.getAllComments()[0];
+
+  const firstComment =
+    rawFirstComment.type === "Shebang"
+      ? sourceCode.getAllComments()[1]
+      : rawFirstComment;
 
   // returns null early if there is no first comment
   if (!firstComment) return null;
 
-  // returns null early if the first comment is not on the first line and the first column
-  if (firstComment.loc.start.line !== 1 || firstComment.loc.start.column !== 0)
-    return null;
+  // returns null early if the first comment is not on one of the first three lines
+  if (firstComment.loc.start.line > 3) return null;
+
+  // returns null early if the first comment is not on the first column
+  if (firstComment.loc.start.column !== 0) return null;
 
   // gets the trimmed raw value of the first comment
   const rawValue = firstComment.value.trim();
@@ -119,6 +125,60 @@ export const getCommentedDirectiveFromCurrentModule = (context) => {
   return commentedDirective;
 };
 
+/* getCommentedDirectiveFromCurrentModule */
+
+/**
+ * Gets the commented directive of the current module.
+ *
+ * Accepted directives for the default Directive-First Architecture are (single or double quotes included):
+ * - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
+ * - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server components'`, `"use server components"` denoting a Server Components Module.
+ * - `'use client components'`, `"use client components"` denoting a Client Components Module.
+ * - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
+ * - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
+ * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
+ * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
+ * @param {Context} context The ESLint rule's `context` object.
+ * @returns The commented directive, or lack thereof via `null`. Given the strictness of this architecture, the lack of a directive is considered a mistake. (Though rules may provide the opportunity to declare a default, and configs with preset defaults may become provided.)
+ */
+export const getCommentedDirectiveFromCurrentModule = (context) => {
+  const sourceCode = context.sourceCode;
+  const commentedDirective = getCommentedDirectiveFromSourceCode(sourceCode);
+
+  return commentedDirective;
+};
+
+/* getCommentedDirectiveFromImportedModule */
+
+/**
+ * Gets the commented directive of the imported module.
+ *
+ * Accepted directives for the default Directive-First Architecture are (single or double quotes included):
+ * - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
+ * - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server components'`, `"use server components"` denoting a Server Components Module.
+ * - `'use client components'`, `"use client components"` denoting a Client Components Module.
+ * - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
+ * - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
+ * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
+ * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
+ * @param {string} resolvedPath The resolved path of the imported module.
+ * @returns The commented directive, or lack thereof via `null`. Given the strictness of this architecture, the lack of a directive is considered a mistake. (Though rules may provide the opportunity to declare a default, and configs with preset defaults may become provided.)
+ */
+export const getCommentedDirectiveFromImportedModule = (resolvedPath) => {
+  const sourceCode = getSourceCodeFromFilePath(resolvedPath);
+  const commentedDirective = getCommentedDirectiveFromSourceCode(sourceCode);
+
+  return commentedDirective;
+};
+
 /* getVerifiedCommentedDirective */
 
 /**
@@ -148,46 +208,6 @@ export const getVerifiedCommentedDirective = (directive, extension) => {
   return null; // verification failed
 };
 
-/* getCommentedDirectiveFromImportedModule */
-
-/**
- * Gets the commented directive of the imported module.
- *
- * Accepted directives for the default Directive-First Architecture are (single or double quotes included):
- * - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
- * - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
- * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
- * - `'use server components'`, `"use server components"` denoting a Server Components Module.
- * - `'use client components'`, `"use client components"` denoting a Client Components Module.
- * - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
- * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
- * - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
- * - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
- * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
- * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
- * @param {string} resolvedImportPath The resolved path of the import.
- * @returns The commented directive, or lack thereof via `null`. Given the strictness of this architecture, the lack of a directive is considered a mistake. (Though rules may provide the opportunity to declare a default, and configs with preset defaults may become provided.)
- */
-export const getCommentedDirectiveFromImportedModule = (resolvedImportPath) => {
-  // gets the first line of the code of the import
-  const importedFileFirstLine = getImportedFileFirstLine(resolvedImportPath);
-
-  // sees if the first line includes any of the directives and finds the directive that it includes, with USE_AGNOSTIC_LOGICS as a default
-  const includedDirective = commentedDirectivesArray.reduce((acc, curr) => {
-    if (importedFileFirstLine.includes(curr)) return curr;
-    else return acc;
-  }, USE_AGNOSTIC_LOGICS);
-
-  // sees if the first line is strictly equal to one of the four raw implementations of the commented directive and returns that directive if true or null if false
-  if (
-    commentedDirectives_4RawImplementations[includedDirective].some(
-      (raw) => raw === importedFileFirstLine
-    )
-  )
-    return includedDirective;
-  else return null;
-};
-
 /* getStrategizedDirective */
 
 /**

package/package.json

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