eslint-plugin-use-agnostic 0.9.3 → 0.9.5

package/library/_commons/constants/bases.js

@@ -17,7 +17,6 @@ export const enforceEffectiveDirectivesRuleName =
 // directive21
 export const enforceCommentedDirectivesRuleName =
   "enforce-commented-directives-import-rules";
-
 // crossingStrategies (canceled)
 export const verifySpecifierImportRuleName =
   "verify-specifier-import-export-same-strategy";
@@ -69,8 +68,7 @@ export const CLIENT_CONTEXTS_MODULE = "Client Contexts Module";
 export const AGNOSTIC_CONDITIONS_MODULE = "Agnostic Conditions Module";
 export const AGNOSTIC_STRATEGIES_MODULE = "Agnostic Strategies Module";
 
-/* from the resolveImportPath utility */
-
+// JavaScript/TypeScript extensions
 export const TSX = ".tsx";
 export const TS = ".ts";
 export const JSX = ".jsx";
@@ -78,8 +76,9 @@ export const JS = ".js";
 export const MJS = ".mjs";
 export const CJS = ".cjs";
 
+// JavaScript/TypeScript extensions array
+/** @type {readonly [TSX, TS, JSX, JS, MJS, CJS]} */
 export const EXTENSIONS = [TSX, TS, JSX, JS, MJS, CJS]; // In priority order
 
-/* from the isImportBlocked utility */
-
+// message strings
 export const ARE_NOT_ALLOWED_TO_IMPORT = "are not allowed to import";

package/library/_commons/utilities/helpers.js

@@ -30,15 +30,28 @@ import {
 
 /* resolveImportPath */
 
+/**
+ * Finds the existing path of an import that does not have an extension specified.
+ * @param {string} basePath The absolute import path with extension yet resolved.
+ * @returns The absolute path with its extension or `null` if no path is found.
+ */
+const findExistingPath = (basePath) => {
+  for (const ext of EXTENSIONS) {
+    const fullPath = `${basePath}${ext}`;
+    if (fs.existsSync(fullPath)) return fullPath;
+  }
+  return null;
+};
+
 /**
  * Resolves an import path to a filesystem path, handling:
  * - Aliases (via tsconfig.json `paths`)
  * - Missing extensions (appends .ts, .tsx, etc.)
  * - Directory imports (e.g., `./components` → `./components/index.ts`)
- * @param {string} currentDir Directory of the file containing the import (from `path.dirname(context.filename)`).
+ * @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 Project root (from `context.cwd`). Caveat: only as an assumption currently.
- * @returns {string | null} Absolute resolved path or `null` if not found.
+ * @param {string} cwd The project root (from `context.cwd`). Caveat: only as an assumption currently.
+ * @returns The absolute resolved path or `null` if no path is found.
  */
 export const resolveImportPath = (currentDir, importPath, cwd) => {
   // --- Step 1: Resolve aliases (if tsconfig.json `paths` exists) ---
@@ -63,19 +76,15 @@ export const resolveImportPath = (currentDir, importPath, cwd) => {
   if (path.extname(importPath) && fs.existsSync(basePath)) return basePath;
 
   // Case 2: Try appending extensions
-  for (const ext of EXTENSIONS) {
-    const fullPath = `${basePath}${ext}`;
-    if (fs.existsSync(fullPath)) return fullPath;
-  }
+  const extensionlessImportPath = findExistingPath(basePath);
+  if (extensionlessImportPath) return extensionlessImportPath;
 
   // Case 3: Directory import (e.g., `./components` → `./components/index.ts`)
   const indexPath = path.join(basePath, "index");
-  for (const ext of EXTENSIONS) {
-    const fullPath = `${indexPath}${ext}`;
-    if (fs.existsSync(fullPath)) return fullPath;
-  }
+  const directoryImportPath = findExistingPath(indexPath);
+  if (directoryImportPath) return extensionlessImportPath;
 
-  return null; // Not found
+  return null; // not found
 };
 
 /* getImportedFileFirstLine */
@@ -83,7 +92,7 @@ export const resolveImportPath = (currentDir, importPath, cwd) => {
 /**
  * Gets the first line of code of the imported module.
  * @param {string} resolvedImportPath The resolved path of the imported module.
- * @returns {string} Returns the first line of the imported module.
+ * @returns The first line of the imported module.
  */
 export const getImportedFileFirstLine = (resolvedImportPath) => {
   // gets the code of the import
@@ -116,7 +125,7 @@ export const highlightFirstLineOfCode = (context) => ({
  * @param {Readonly<{"use server logics": {blockedImport: string; message: string;}[]; "use client logics": {blockedImport: string; message: string;}[]; "use agnostic logics": {blockedImport: string; message: string;}[]; "use server components": {blockedImport: string; message: string;}[]; "use client components": {blockedImport: string; message: string;}[]; "use agnostic components": {blockedImport: string; message: string;}[]; "use server functions": {blockedImport: string; message: string;}[]; "use client contexts"?: {blockedImport: string; message: string;}[]; "use agnostic conditions"?: {blockedImport: string; message: string;}[]; "use agnostic strategies"?: {blockedImport: string; message: string;}[];}>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileResolvedDirective The current file's "resolved" directive.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS} importedFileResolvedDirective The imported file's "resolved" directive.
- * @returns {boolean} Returns `true` if the import is blocked, as established in respective `resolvedDirectives_blockedImports`.
+ * @returns Returns `true` if the import is blocked, as established in respective `resolvedDirectives_blockedImports`.
  */
 export const isImportBlocked = (
   // Note: "Blocked" here is preferred over "not allowed" because a specific message will be shared for each of the blocked situations, explaining their reasons and the solutions needed.
@@ -135,7 +144,7 @@ export const isImportBlocked = (
  * @param {Readonly<{"use server logics": SERVER_LOGICS_MODULE; "use client logics": CLIENT_LOGICS_MODULE; "use agnostic logics": AGNOSTIC_LOGICS_MODULE; "use server components": SERVER_COMPONENTS_MODULE; "use client components": CLIENT_COMPONENTS_MODULE; "use agnostic components": AGNOSTIC_COMPONENTS_MODULE; "use server functions": SERVER_FUNCTIONS_MODULE; "use client contexts": CLIENT_CONTEXTS_MODULE; "use agnostic conditions": AGNOSTIC_CONDITIONS_MODULE; "use agnostic strategies": AGNOSTIC_STRATEGIES_MODULE;}>} resolvedDirectives_ResolvedModules The resolved modules object, either for agnostic20 or for directive21.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileResolvedDirective The current file's "resolved" directive.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS} importedFileResolvedDirective The imported file's "resolved" directive.
- * @returns {string} Returns "[Current file 'resolved' modules] are not allowed to import [imported file 'resolved' modules]."
+ * @returns Returns "[Current file 'resolved' modules] are not allowed to import [imported file 'resolved' modules]."
  */
 export const makeIntroForSpecificViolationMessage = (
   resolvedDirectives_ResolvedModules,
@@ -151,7 +160,7 @@ export const makeIntroForSpecificViolationMessage = (
  * @param {Readonly<{"use server logics": SERVER_LOGICS_MODULE; "use client logics": CLIENT_LOGICS_MODULE; "use agnostic logics": AGNOSTIC_LOGICS_MODULE; "use server components": SERVER_COMPONENTS_MODULE; "use client components": CLIENT_COMPONENTS_MODULE; "use agnostic components": AGNOSTIC_COMPONENTS_MODULE; "use server functions": SERVER_FUNCTIONS_MODULE; "use client contexts": CLIENT_CONTEXTS_MODULE; "use agnostic conditions": AGNOSTIC_CONDITIONS_MODULE; "use agnostic strategies": AGNOSTIC_STRATEGIES_MODULE;}>} resolvedDirectives_ResolvedModules The resolved modules object, either for agnostic20 or for directive21.
  * @param {Readonly<{"use server logics": {blockedImport: string; message: string;}[]; "use client logics": {blockedImport: string; message: string;}[]; "use agnostic logics": {blockedImport: string; message: string;}[]; "use server components": {blockedImport: string; message: string;}[]; "use client components": {blockedImport: string; message: string;}[]; "use agnostic components": {blockedImport: string; message: string;}[]; "use server functions": {blockedImport: string; message: string;}[]; "use client contexts"?: {blockedImport: string; message: string;}[]; "use agnostic conditions"?: {blockedImport: string; message: string;}[]; "use agnostic strategies"?: {blockedImport: string; message: string;}[];}>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} resolvedDirective The "resolved" directive of the "resolved" module.
- * @returns {string} The message listing the incompatible "resolved" modules.
+ * @returns The message listing the incompatible "resolved" modules.
  */
 export const makeMessageFromResolvedDirective = (
   resolvedDirectives_ResolvedModules,
@@ -191,7 +200,7 @@ export const makeMessageFromResolvedDirective = (
  * @param {Readonly<{"use server logics": {blockedImport: string; message: string;}[]; "use client logics": {blockedImport: string; message: string;}[]; "use agnostic logics": {blockedImport: string; message: string;}[]; "use server components": {blockedImport: string; message: string;}[]; "use client components": {blockedImport: string; message: string;}[]; "use agnostic components": {blockedImport: string; message: string;}[]; "use server functions": {blockedImport: string; message: string;}[]; "use client contexts"?: {blockedImport: string; message: string;}[]; "use agnostic conditions"?: {blockedImport: string; message: string;}[]; "use agnostic strategies"?: {blockedImport: string; message: string;}[];}>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileResolvedDirective The current file's "resolved" directive.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS} importedFileResolvedDirective The imported file's "resolved" directive.
- * @returns {string} The corresponding `message`.
+ * @returns The corresponding `message`.
  */
 export const findSpecificViolationMessage = (
   resolvedDirectives_blockedImports,

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

@@ -23,6 +23,14 @@ export const USE_SERVER = "use server";
 export const USE_CLIENT = "use client";
 export const USE_AGNOSTIC = "use agnostic";
 
+// directives array
+/** @type {readonly [USE_SERVER, USE_CLIENT, USE_AGNOSTIC]} */
+export const directivesArray = [USE_SERVER, USE_CLIENT, USE_AGNOSTIC];
+
+// directives set
+/** @type {ReadonlySet<USE_SERVER | USE_CLIENT | USE_AGNOSTIC>} */
+export const directivesSet = new Set(directivesArray); // no longer used exported to satisfy static type inference
+
 // effective directives
 export const USE_SERVER_LOGICS = COMMONS_USE_SERVER_LOGICS;
 export const USE_SERVER_COMPONENTS = COMMONS_USE_SERVER_COMPONENTS;
@@ -53,30 +61,18 @@ export const effectiveDirectives_EffectiveModules = Object.freeze({
 });
 
 // message placeholders
-
 export const currentFileEffectiveDirective = "currentFileEffectiveDirective";
 export const importedFileEffectiveDirective = "importedFileEffectiveDirective";
 export const effectiveDirectiveMessage = "effectiveDirectiveMessage";
 export const specificViolationMessage = "specificViolationMessage";
 
-/* from the getDirectiveFromCurrentModule utility */
-
-export const directivesSet = new Set([USE_SERVER, USE_CLIENT, USE_AGNOSTIC]);
-
-/* from the getDirectiveFromImportedModule utility */
-
-/** @type {readonly [USE_SERVER, USE_CLIENT, USE_AGNOSTIC]} */
-export const directivesArray = Array.from(directivesSet);
-
-/* from the isImportBlocked utility */
-
 /* effectiveDirectives_BlockedImports */
 
 /**
  * Makes the intro for each specific import rule violation messages.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} importedFileEffectiveDirective The imported file's effective directive.
- * @returns {string} Returns "[Current file effective modules] are not allowed to import [imported file effective modules]."
+ * @returns "[Current file effective modules] are not allowed to import [imported file effective modules]."
  */
 const makeIntroForSpecificViolationMessage = (
   currentFileEffectiveDirective,

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

@@ -7,6 +7,7 @@ import {
   reExportNotSameMessageId,
 } from "../../../_commons/constants/bases.js";
 import {
+  USE_SERVER,
   USE_SERVER_LOGICS,
   USE_SERVER_COMPONENTS,
   USE_SERVER_FUNCTIONS,
@@ -38,7 +39,7 @@ import {
 /**
  * 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.
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
- * @returns {{skip: true; currentFileEffectiveDirective: undefined;} | {skip: undefined; currentFileEffectiveDirective: USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS;}} Returns either an object with `skip: true` to disregard or one with the non-null `currentFileEffectiveDirective`.
+ * @returns {{skip: true; currentFileEffectiveDirective: undefined;} | {skip: undefined; currentFileEffectiveDirective: USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS;}} Either an object with `skip: true` to disregard or one with the non-null `currentFileEffectiveDirective`.
  */
 export const currentFileFlow = (context) => {
   // GETTING THE EXTENSION OF THE CURRENT FILE
@@ -60,7 +61,7 @@ export const currentFileFlow = (context) => {
 
   // reports if a file marked "use server" has a JSX extension
   if (
-    currentFileDirective === "use server" &&
+    currentFileDirective === USE_SERVER &&
     currentFileExtension.endsWith("x")
   ) {
     context.report({
@@ -82,9 +83,7 @@ export const currentFileFlow = (context) => {
     return { skip: true };
   }
 
-  return {
-    currentFileEffectiveDirective,
-  };
+  return { currentFileEffectiveDirective };
 };
 
 /* importedFileFlow */
@@ -93,7 +92,7 @@ export const currentFileFlow = (context) => {
  * The flow that is shared between import and re-export traversals to obtain the import file's effective directive.
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
- * @returns {{skip: true; importedFileEffectiveDirective: undefined; resolvedImportPath: undefined;} | {skip: undefined; importedFileEffectiveDirective: USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS; resolvedImportPath: string;}} Returns either an object with `skip: true` to disregard or one with the non-null `importedFileEffectiveDirective`.
+ * @returns {{skip: true; importedFileEffectiveDirective: undefined;} | {skip: undefined; importedFileEffectiveDirective: USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS;}} Either an object with `skip: true` to disregard or one with the non-null `importedFileEffectiveDirective`.
  */
 const importedFileFlow = (context, node) => {
   // finds the full path of the import
@@ -130,9 +129,7 @@ const importedFileFlow = (context, node) => {
 
   // For now skipping on both "does not operate" (which should ignore) and "fails" albeit with console.error (which should crash).
 
-  return {
-    importedFileEffectiveDirective,
-  };
+  return { importedFileEffectiveDirective };
 };
 
 /* importsFlow */
@@ -141,7 +138,7 @@ const importedFileFlow = (context, node) => {
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
- * @returns Returns early if the flow needs to be interrupted.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const importsFlow = (context, node, currentFileEffectiveDirective) => {
   // does not operate on `import type`
@@ -180,7 +177,7 @@ export const importsFlow = (context, node, currentFileEffectiveDirective) => {
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration | import('@typescript-eslint/types').TSESTree.ExportAllDeclaration} node The ESLint `node` of the rule's current traversal.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
- * @returns Returns early if the flow needs to be interrupted.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const reExportsFlow = (context, node, currentFileEffectiveDirective) => {
   // does not operate on `export type`

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

@@ -1,13 +1,13 @@
 import {
-  useServerJSXMessageId,
-  importBreaksEffectiveImportRulesMessageId,
-  reExportNotSameMessageId,
   TSX,
   TS,
   JSX,
   JS,
   MJS,
   CJS,
+  useServerJSXMessageId,
+  importBreaksEffectiveImportRulesMessageId,
+  reExportNotSameMessageId,
 } from "../../../_commons/constants/bases.js";
 import {
   NO_DIRECTIVE,
@@ -22,7 +22,6 @@ import {
   USE_AGNOSTIC_LOGICS,
   USE_AGNOSTIC_COMPONENTS,
   effectiveDirectives_EffectiveModules,
-  directivesSet,
   directivesArray,
   effectiveDirectives_BlockedImports,
 } from "../constants/bases.js";
@@ -43,7 +42,7 @@ import {
  * - `'use server'` denotes a Server Functions Module.
  * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
- * @returns {NO_DIRECTIVE | USE_SERVER | USE_CLIENT | USE_AGNOSTIC} The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
  */
 export const getDirectiveFromCurrentModule = (context) => {
   // the AST body to check for the top-of-the-file directive
@@ -63,7 +62,8 @@ 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 = directivesSet.has(value) ? value : null;
+  const currentFileDirective =
+    directivesArray.find((directive) => directive === value) ?? null;
 
   return currentFileDirective;
 };
@@ -81,7 +81,7 @@ export const getDirectiveFromCurrentModule = (context) => {
  * - `'use agnostic components'` denotes an Agnostic Components Module.
  * @param {NO_DIRECTIVE | USE_SERVER | USE_CLIENT | USE_AGNOSTIC} directive The directive as written on top of the file (`null` if no valid directive).
  * @param {TSX | TS | JSX | JS | MJS | CJS} extension The JavaScript (TypeScript) extension of the file.
- * @returns {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS | null} The effective directive, from which imports rules are applied.
+ * @returns The effective directive, from which imports rules are applied.
  */
 export const getEffectiveDirective = (directive, extension) => {
   // I could use a map, but because this is in JS with JSDoc, a manual solution is peculiarly more typesafe.
@@ -112,7 +112,7 @@ export const getEffectiveDirective = (directive, extension) => {
  * - `'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 {USE_SERVER | USE_CLIENT | USE_AGNOSTIC | NO_DIRECTIVE} The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ * @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
@@ -141,7 +141,7 @@ export const getDirectiveFromImportedModule = (resolvedImportPath) => {
  * Returns a boolean deciding if an imported file's effective directive is incompatible with the current file's effective directive.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} importedFileEffectiveDirective The imported file's effective directive.
- * @returns {boolean} Returns `true` if the import is blocked, as established in `effectiveDirectives_BlockedImports`.
+ * @returns `true` if the import is blocked, as established in `effectiveDirectives_BlockedImports`.
  */
 export const isImportBlocked = (
   currentFileEffectiveDirective,
@@ -158,7 +158,7 @@ export const isImportBlocked = (
 /**
  * Lists in an message the effective modules incompatible with an effective module based on its effective directive.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} effectiveDirective The effective directive of the effective module.
- * @returns {string} The message listing the incompatible effective modules.
+ * @returns The message listing the incompatible effective modules.
  */
 export const makeMessageFromEffectiveDirective = (effectiveDirective) =>
   makeMessageFromResolvedDirective(
@@ -173,7 +173,7 @@ export const makeMessageFromEffectiveDirective = (effectiveDirective) =>
  * Finds the `message` for the specific violation of effective directives import rules based on `effectiveDirectives_BlockedImports`.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
  * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} importedFileEffectiveDirective The imported file's effective directive.
- * @returns {string} The corresponding `message`.
+ * @returns The corresponding `message`.
  */
 export const findSpecificViolationMessage = (
   currentFileEffectiveDirective,

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

@@ -35,6 +35,25 @@ export const USE_CLIENT_CONTEXTS = COMMONS_USE_CLIENT_CONTEXTS;
 export const USE_AGNOSTIC_CONDITIONS = COMMONS_USE_AGNOSTIC_CONDITIONS;
 export const USE_AGNOSTIC_STRATEGIES = COMMONS_USE_AGNOSTIC_STRATEGIES;
 
+// commented directives array
+/** @type {readonly [USE_SERVER_LOGICS, USE_CLIENT_LOGICS, USE_AGNOSTIC_LOGICS, USE_SERVER_COMPONENTS, USE_CLIENT_COMPONENTS, USE_AGNOSTIC_COMPONENTS, USE_SERVER_FUNCTIONS, USE_CLIENT_CONTEXTS, USE_AGNOSTIC_CONDITIONS, USE_AGNOSTIC_STRATEGIES]} */
+export const directivesArray = [
+  USE_SERVER_LOGICS,
+  USE_CLIENT_LOGICS,
+  USE_AGNOSTIC_LOGICS,
+  USE_SERVER_COMPONENTS,
+  USE_CLIENT_COMPONENTS,
+  USE_AGNOSTIC_COMPONENTS,
+  USE_SERVER_FUNCTIONS,
+  USE_CLIENT_CONTEXTS,
+  USE_AGNOSTIC_CONDITIONS,
+  USE_AGNOSTIC_STRATEGIES,
+];
+
+// commented directives set
+/** @type {ReadonlySet<USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES>} */
+export const directivesSet = new Set(directivesArray); // no longer used exported to satisfy static type inference
+
 // commented modules
 const SERVER_LOGICS_MODULE = COMMONS_SERVER_LOGICS_MODULE;
 const CLIENT_LOGICS_MODULE = COMMONS_CLIENT_LOGICS_MODULE;
@@ -61,34 +80,55 @@ export const commentedDirectives_CommentedModules = Object.freeze({
   [USE_AGNOSTIC_STRATEGIES]: AGNOSTIC_STRATEGIES_MODULE,
 });
 
-// message placeholders
+// commented strategies
+const AT_SERVER_LOGICS = "@serverLogics";
+const AT_CLIENT_LOGICS = "@clientLogics";
+const AT_AGNOSTIC_LOGICS = "@agnosticLogics";
+const AT_SERVER_COMPONENTS = "@serverComponents";
+const AT_CLIENT_COMPONENTS = "@clientComponents";
+const AT_AGNOSTIC_COMPONENTS = "@agnosticComponents";
+const AT_SERVER_FUNCTIONS = "@serverFunctions";
+const AT_CLIENT_CONTEXTS = "@clientContexts";
+const AT_AGNOSTIC_CONDITIONS = "@agnosticConditions";
 
+// commented strategies array
+/** @type {readonly [AT_SERVER_LOGICS, AT_CLIENT_LOGICS, AT_AGNOSTIC_LOGICS, AT_SERVER_COMPONENTS, AT_CLIENT_COMPONENTS, AT_AGNOSTIC_COMPONENTS, AT_SERVER_FUNCTIONS, AT_CLIENT_CONTEXTS, AT_AGNOSTIC_CONDITIONS]} */
+export const strategiesArray = [
+  AT_SERVER_LOGICS,
+  AT_CLIENT_LOGICS,
+  AT_AGNOSTIC_LOGICS,
+  AT_SERVER_COMPONENTS,
+  AT_CLIENT_COMPONENTS,
+  AT_AGNOSTIC_COMPONENTS,
+  AT_SERVER_FUNCTIONS,
+  AT_CLIENT_CONTEXTS,
+  AT_AGNOSTIC_CONDITIONS,
+];
+
+// commented strategies set
+/** @type {ReadonlySet<AT_SERVER_LOGICS | AT_CLIENT_LOGICS | AT_AGNOSTIC_LOGICS | AT_SERVER_COMPONENTS | AT_CLIENT_COMPONENTS | AT_AGNOSTIC_COMPONENTS | AT_SERVER_FUNCTIONS | AT_CLIENT_CONTEXTS | AT_AGNOSTIC_CONDITIONS>} */
+export const strategiesSet = new Set(strategiesArray); // no longer used exported to satisfy static type inference
+
+// mapped commented strategies to their commented directives
+export const commentedStrategies_CommentedDirectives = Object.freeze({
+  [AT_SERVER_LOGICS]: USE_SERVER_LOGICS,
+  [AT_CLIENT_LOGICS]: USE_CLIENT_LOGICS,
+  [AT_AGNOSTIC_LOGICS]: USE_AGNOSTIC_LOGICS,
+  [AT_SERVER_COMPONENTS]: USE_SERVER_COMPONENTS,
+  [AT_CLIENT_COMPONENTS]: USE_CLIENT_COMPONENTS,
+  [AT_AGNOSTIC_COMPONENTS]: USE_AGNOSTIC_COMPONENTS,
+  [AT_SERVER_FUNCTIONS]: USE_SERVER_FUNCTIONS,
+  [AT_CLIENT_CONTEXTS]: USE_CLIENT_CONTEXTS,
+  [AT_AGNOSTIC_CONDITIONS]: USE_AGNOSTIC_CONDITIONS,
+});
+
+// message placeholders
 export const currentFileCommentedDirective = "currentFileCommentedDirective";
 export const importedFileCommentedDirective = "importedFileCommentedDirective";
 export const commentedDirectiveMessage = "commentedDirectiveMessage";
 export const specificViolationMessage = "specificViolationMessage";
 export const specificFailure = "specificFailure";
 
-/* from the getCommentedDirectiveFromCurrentModule utility */
-
-export const directivesSet = new Set([
-  USE_SERVER_LOGICS,
-  USE_CLIENT_LOGICS,
-  USE_AGNOSTIC_LOGICS,
-  USE_SERVER_COMPONENTS,
-  USE_CLIENT_COMPONENTS,
-  USE_AGNOSTIC_COMPONENTS,
-  USE_SERVER_FUNCTIONS,
-  USE_CLIENT_CONTEXTS,
-  USE_AGNOSTIC_CONDITIONS,
-  USE_AGNOSTIC_STRATEGIES,
-]);
-
-/* from the getCommentedDirectiveFromImportedModule utility */
-
-/** @type {readonly [USE_SERVER_LOGICS, USE_CLIENT_LOGICS, USE_AGNOSTIC_LOGICS, USE_SERVER_COMPONENTS, USE_CLIENT_COMPONENTS, USE_AGNOSTIC_COMPONENTS, USE_SERVER_FUNCTIONS, USE_CLIENT_CONTEXTS, USE_AGNOSTIC_CONDITIONS, USE_AGNOSTIC_STRATEGIES]} */
-export const directivesArray = Array.from(directivesSet);
-
 /* commentedDirectives_4RawImplementations */
 
 // all formatting styles as an array of [prefix, quote, suffix]
@@ -97,20 +137,19 @@ const commentStyles = [
   [`// `, `"`, ``], // V2: `// "directive"`
   [`/* `, `'`, ` */`], // V3: `/* 'directive' */`
   [`/* `, `"`, ` */`], // V4: `/* "directive" */`
-];
+]; // further inference optimation can be made but is overkill...
 
 /**
  * Makes the array of all four accepted commented directive implementations on a directive basis.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} directive The commented directive.
- * @returns {string[]} The array of formatted commented directives.
+ * @returns The array of formatted commented directives.
  */
 const make4RawImplementations = (directive) =>
   commentStyles.map(
     ([prefix, quote, suffix]) =>
       `${prefix}${quote}${directive}${quote}${suffix}`
-  );
+  ); // ...further inference optimation could be an extra challenge but would probably require TypeScript for comfort
 
-// mapped commented directives to their 4 raw implementations
 export const commentedDirectives_4RawImplementations = Object.freeze({
   [USE_SERVER_LOGICS]: make4RawImplementations(USE_SERVER_LOGICS),
   [USE_CLIENT_LOGICS]: make4RawImplementations(USE_CLIENT_LOGICS),
@@ -124,37 +163,35 @@ export const commentedDirectives_4RawImplementations = Object.freeze({
   [USE_AGNOSTIC_STRATEGIES]: make4RawImplementations(USE_AGNOSTIC_STRATEGIES),
 });
 
-// commented strategies
-export const AT_SERVER_LOGICS = "@serverLogics";
-export const AT_CLIENT_LOGICS = "@clientLogics";
-export const AT_AGNOSTIC_LOGICS = "@agnosticLogics";
-export const AT_SERVER_COMPONENTS = "@serverComponents";
-export const AT_CLIENT_COMPONENTS = "@clientComponents";
-export const AT_AGNOSTIC_COMPONENTS = "@agnosticComponents";
-export const AT_SERVER_FUNCTIONS = "@serverFunctions";
-export const AT_CLIENT_CONTEXTS = "@clientContexts";
-export const AT_AGNOSTIC_CONDITIONS = "@agnosticConditions";
+/* commentedDirectives_VerificationReports */
 
-// mapped commented strategies to their commented directives
-export const commentedStrategies_CommentedDirectives = Object.freeze({
-  [AT_SERVER_LOGICS]: USE_SERVER_LOGICS,
-  [AT_CLIENT_LOGICS]: USE_CLIENT_LOGICS,
-  [AT_AGNOSTIC_LOGICS]: USE_AGNOSTIC_LOGICS,
-  [AT_SERVER_COMPONENTS]: USE_SERVER_COMPONENTS,
-  [AT_CLIENT_COMPONENTS]: USE_CLIENT_COMPONENTS,
-  [AT_AGNOSTIC_COMPONENTS]: USE_AGNOSTIC_COMPONENTS,
-  [AT_SERVER_FUNCTIONS]: USE_SERVER_FUNCTIONS,
-  [AT_CLIENT_CONTEXTS]: USE_CLIENT_CONTEXTS,
-  [AT_AGNOSTIC_CONDITIONS]: USE_AGNOSTIC_CONDITIONS,
+const MODULES_MARKED_WITH_THE_ = "modules marked with the";
+const _DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION =
+  "directive must have a non-JSX file extension";
+const _DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION =
+  "directive must have a JSX file extension";
+
+export const commentedDirectives_VerificationReports = Object.freeze({
+  // somehow doing it by hand is better for type inference in raw JS
+  [USE_SERVER_LOGICS]: `${MODULES_MARKED_WITH_THE_} "${USE_SERVER_LOGICS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
+  [USE_CLIENT_LOGICS]: `${MODULES_MARKED_WITH_THE_} "${USE_CLIENT_LOGICS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
+  [USE_AGNOSTIC_LOGICS]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_LOGICS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
+  [USE_SERVER_COMPONENTS]: `${MODULES_MARKED_WITH_THE_} "${USE_SERVER_COMPONENTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
+  [USE_CLIENT_COMPONENTS]: `${MODULES_MARKED_WITH_THE_} "${USE_CLIENT_COMPONENTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
+  [USE_AGNOSTIC_COMPONENTS]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_COMPONENTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
+  [USE_SERVER_FUNCTIONS]: `${MODULES_MARKED_WITH_THE_} "${USE_SERVER_FUNCTIONS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
+  [USE_CLIENT_CONTEXTS]: `${MODULES_MARKED_WITH_THE_} "${USE_CLIENT_CONTEXTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
+  [USE_AGNOSTIC_CONDITIONS]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_CONDITIONS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
+  [USE_AGNOSTIC_STRATEGIES]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_STRATEGIES}" directive are free to have the file extension of their choosing. (This is not a problem and should never surface.)`,
 });
 
-/* from the isImportBlocked utility */
+/* commentedDirectives_BlockedImports */
 
 /**
  * Makes the intro for each specific import rule violation messages.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileCommentedDirective The current file's commented directive.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS} importedFileCommentedDirective The imported file's commented directive.
- * @returns {string} Returns "[Current file commented modules] are not allowed to import [imported file commented modules]."
+ * @returns "[Current file commented modules] are not allowed to import [imported file commented modules]."
  */
 const makeIntroForSpecificViolationMessage = (
   currentFileCommentedDirective,
@@ -379,7 +416,7 @@ export const commentedDirectives_BlockedImports = Object.freeze({
       message: `${makeIntroForSpecificViolationMessage(
         USE_SERVER_FUNCTIONS,
         USE_AGNOSTIC_CONDITIONS
-      )} (Special) Agnostic Conditions Components aren't allowed (Special)because Server Functions have no business working with React Components.`,
+      )} (Special) Agnostic Conditions Components aren't allowed because (Special) Server Functions have no business working with React Components.`,
     },
   ],
   [USE_CLIENT_CONTEXTS]: [
@@ -397,13 +434,13 @@ export const commentedDirectives_BlockedImports = Object.freeze({
       message: `${makeIntroForSpecificViolationMessage(
         USE_CLIENT_CONTEXTS,
         USE_SERVER_COMPONENTS
-      )} Lineal Server Components may only pass through Client Contexts Components via the children prop within Server Components Modules.`,
+      )} Lineal Server Components may only pass through (Special) Client Contexts Components via the children prop within Server Components Modules.`,
     },
     // USE_CLIENT_COMPONENTS allowed, because Lineal Client Components can create client boundaries within (Special) Client Contexts Components.
     // USE_AGNOSTIC_COMPONENTS allowed, because Lineal Agnostic Components can render safely on the client just like they can on the server.
     // USE_SERVER_FUNCTIONS allowed, because (Special) Server Functions are specifically triggered by Client Components.
     // USE_CLIENT_CONTEXTS allowed, because (Special) Client Contexts Components can compose with one another.
-    // USE_AGNOSTIC_CONDITIONS allowed, because (Special) Agnostic Conditions Components, as if they were Lineal Agnostic Components themselves, can render safely on the client just like they can on the server, in a mechanism that allows Client Contexts Components to safely and indirectly compose with child Server Components within Client Contexts Modules.
+    // USE_AGNOSTIC_CONDITIONS allowed, because (Special) Agnostic Conditions Components, as if they were Lineal Agnostic Components themselves, can render safely on the client just like they can on the server, in a mechanism that allows (Special) Client Contexts Components to safely and indirectly compose with child Server Components within Client Contexts Modules.
   ],
   [USE_AGNOSTIC_CONDITIONS]: [
     {
@@ -444,25 +481,3 @@ export const commentedDirectives_BlockedImports = Object.freeze({
     // (Special) Agnostic Strategies Modules can import all known modules, except themselves since they cannot be imported as they are, only as and via Strategies. (Since Agnostic Strategies Modules cannot be imported as they are, there is no such things as a 'use agnostic strategies' importFileCommentedDirective.)
   ],
 });
-
-/* from the currentFileFlow flow */
-
-const MODULES_MARKED_WITH_THE_ = "modules marked with the";
-const _DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION =
-  "directive must have a non-JSX file extension";
-const _DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION =
-  "directive must have a JSX file extension";
-
-export const commentedDirectives_VerificationReports = Object.freeze({
-  // somehow doing it by hand is better for type inference in raw JS
-  [USE_SERVER_LOGICS]: `${MODULES_MARKED_WITH_THE_} "${USE_SERVER_LOGICS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
-  [USE_CLIENT_LOGICS]: `${MODULES_MARKED_WITH_THE_} "${USE_CLIENT_LOGICS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
-  [USE_AGNOSTIC_LOGICS]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_LOGICS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
-  [USE_SERVER_COMPONENTS]: `${MODULES_MARKED_WITH_THE_} "${USE_SERVER_COMPONENTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
-  [USE_CLIENT_COMPONENTS]: `${MODULES_MARKED_WITH_THE_} "${USE_CLIENT_COMPONENTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
-  [USE_AGNOSTIC_COMPONENTS]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_COMPONENTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
-  [USE_SERVER_FUNCTIONS]: `${MODULES_MARKED_WITH_THE_} "${USE_SERVER_FUNCTIONS}" ${_DIRECTIVE_MUST_HAVE_A_NON_JSX_FILE_EXTENSION}.`,
-  [USE_CLIENT_CONTEXTS]: `${MODULES_MARKED_WITH_THE_} "${USE_CLIENT_CONTEXTS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
-  [USE_AGNOSTIC_CONDITIONS]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_CONDITIONS}" ${_DIRECTIVE_MUST_HAVE_A_JSX_FILE_EXTENSION}.`,
-  [USE_AGNOSTIC_STRATEGIES]: `${MODULES_MARKED_WITH_THE_} "${USE_AGNOSTIC_STRATEGIES}" directive are free to have the file extension of their choosing. (This is not a problem and should never surface.)`,
-});

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

@@ -48,7 +48,7 @@ import {
 /**
  * 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.
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
- * @returns {{skip: true; verifiedCommentedDirective: undefined;} | {skip: undefined; verifiedCommentedDirective: USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES;}} Returns either an object with `skip: true` to disregard or one with the non-null `verifiedCommentedDirective`.
+ * @returns {{skip: true; verifiedCommentedDirective: undefined;} | {skip: undefined; verifiedCommentedDirective: USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES;}} Either an object with `skip: true` to disregard or one with the non-null `verifiedCommentedDirective`.
  */
 export const currentFileFlow = (context) => {
   // GETTING THE EXTENSION OF THE CURRENT FILE
@@ -95,9 +95,7 @@ export const currentFileFlow = (context) => {
     return { skip: true };
   }
 
-  return {
-    verifiedCommentedDirective,
-  };
+  return { verifiedCommentedDirective };
 };
 
 /* importedFileFlow */
@@ -106,7 +104,7 @@ export const currentFileFlow = (context) => {
  * The flow that is shared between import and re-export traversals to obtain the import file's commented directive.
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
- * @returns {{skip: true; importedFileCommentedDirective: undefined;} | {skip: undefined; importedFileCommentedDirective: USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS;}} Returns either an object with `skip: true` to disregard or one with the non-null `importedFileCommentedDirective`.
+ * @returns {{skip: true; importedFileCommentedDirective: undefined;} | {skip: undefined; importedFileCommentedDirective: USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS;}} Either an object with `skip: true` to disregard or one with the non-null `importedFileCommentedDirective`.
  */
 const importedFileFlow = (context, node) => {
   // finds the full path of the import
@@ -131,18 +129,18 @@ const importedFileFlow = (context, node) => {
   // returns early if there is no directive or no valid directive (same, but eventually no directive could have defaults)
   if (!importedFileCommentedDirective) {
     console.warn(
-      "The imported file, whose path has been resolved, has no directive. It is thus ignored since the report on that circumstance is available on the imported file itself."
+      "WARNING. The imported file, whose path has been resolved, has no directive. It is thus ignored since the report on that circumstance is available on the imported file itself."
     );
     return { skip: true };
   }
 
   /* GETTING THE CORRECT DIRECTIVE INTERPRETATION OF STRATEGY FOR AGNOSTIC STRATEGIES MODULES IMPORTS. 
-  (The Directive-First Architecture does not check whether the export and import Strategies are the same at this time, meaning an @clientLogics strategy could be wrongly imported and interpreted as an @serverLogics strategy.
+  The Directive-First Architecture does not check whether the export and import Strategies are the same at this time, meaning an @clientLogics strategy could be wrongly imported and interpreted as an @serverLogics strategy.
   
   After a short attempt, this feature is currently canceled, mainly since the amount of work it will require will not be able to be transferred in a future where commented strategies will actually be real syntax.
   
-  // (Consequently, details below are currently at the stage of wishful thinking.)
-  However, Strategy exports are planned to be linting in the future within their own Agnostic Strategies Modules to ensure they respect import rules within their own scopes. It may also become possible to check whether the export and import Strategies are the same in the future when identifiers are defined and the same, especially for components modules where a convention could be to for all non-type export to be named and PascalCase.) */
+  (Consequently, details below are currently at the stage of wishful thinking.)
+  Strategy exports are planned to be linting in the future within their own Agnostic Strategies Modules to ensure they respect import rules within their own scopes. It may also become possible to check whether the export and import Strategies are the same in the future when identifiers are defined and the same, especially for components modules where a convention could be for all non-type exports to be named and PascalCase. */
   if (importedFileCommentedDirective === USE_AGNOSTIC_STRATEGIES) {
     const importingFileCommentedDirective = getStrategizedDirective(
       context,
@@ -171,7 +169,7 @@ const importedFileFlow = (context, node) => {
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileCommentedDirective The current file's commented directive.
- * @returns Returns early if the flow needs to be interrupted.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const importsFlow = (context, node, currentFileCommentedDirective) => {
   // does not operate on `import type`
@@ -211,7 +209,7 @@ export const importsFlow = (context, node, currentFileCommentedDirective) => {
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration | import('@typescript-eslint/types').TSESTree.ExportAllDeclaration | import('@typescript-eslint/types').TSESTree.ExportDefaultDeclaration} node The ESLint `node` of the rule's current traversal.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileCommentedDirective The current file's commented directive.
- * @returns Returns early if the flow needs to be interrupted.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const allExportsFlow = (
   context,
@@ -250,9 +248,9 @@ export const allExportsFlow = (
         node,
         messageId: reExportNotSameMessageId,
         data: {
-          // currentFileCommentedDirective
+          // currentFileCommentedDirective:
           currentFileCommentedDirective,
-          // importedFileCommentedDirective
+          // importedFileCommentedDirective:
           importedFileCommentedDirective,
         },
       });

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

@@ -17,8 +17,8 @@ import {
   USE_CLIENT_CONTEXTS,
   USE_AGNOSTIC_CONDITIONS,
   USE_AGNOSTIC_STRATEGIES,
-  directivesSet,
   directivesArray,
+  strategiesArray,
   commentedDirectives_4RawImplementations,
   commentedStrategies_CommentedDirectives,
   commentedDirectives_BlockedImports,
@@ -34,6 +34,45 @@ import {
 
 /* getCommentedDirectiveFromCurrentModule */
 
+/**
+ * Detects whether a string is single- or double-quoted.
+ * @param {string} string
+ * @returns
+ */
+const detectQuoteType = (string) => {
+  if (string.startsWith("'") && string.endsWith("'")) {
+    return true; // single quotes
+  } else if (string.startsWith('"') && string.endsWith('"')) {
+    return false; // double quotes
+  } else {
+    return null; // neither
+  }
+};
+
+/**
+ * Removes single quotes from a string known to be single-quoted.
+ * @param {string} string
+ * @returns
+ */
+const stripSingleQuotes = (string) => {
+  if (string.startsWith("'") && string.endsWith("'")) {
+    return string.slice(1, -1);
+  }
+  return string;
+};
+
+/**
+ * Removes double quotes from a string known to be double-quoted.
+ * @param {string} string
+ * @returns
+ */
+const stripDoubleQuotes = (string) => {
+  if (string.startsWith('"') && string.endsWith('"')) {
+    return string.slice(1, -1);
+  }
+  return string;
+};
+
 /**
  * Gets the commented directive of the current module.
  *
@@ -50,7 +89,7 @@ import {
  * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
  * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
- * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} 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 be provided.)
+ * @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) => {
   // gets the first comment from the source code
@@ -78,50 +117,12 @@ export const getCommentedDirectiveFromCurrentModule = (context) => {
     : stripDoubleQuotes(rawValue);
 
   // certifies the directive or lack thereof from the obtained value
-  const commentedDirective = directivesSet.has(value) ? value : null;
+  const commentedDirective =
+    directivesArray.find((directive) => directive === value) ?? null;
 
   return commentedDirective;
 };
 
-/**
- * Detects whether a string is single- or double-quoted.
- * @param {string} string
- * @returns
- */
-const detectQuoteType = (string) => {
-  if (string.startsWith("'") && string.endsWith("'")) {
-    return true; // single quotes
-  } else if (string.startsWith('"') && string.endsWith('"')) {
-    return false; // double quotes
-  } else {
-    return null; // neither
-  }
-};
-
-/**
- * Removes single quotes from a string known to be single-quoted.
- * @param {string} string
- * @returns
- */
-const stripSingleQuotes = (string) => {
-  if (string.startsWith("'") && string.endsWith("'")) {
-    return string.slice(1, -1);
-  }
-  return string;
-};
-
-/**
- * Removes double quotes from a string known to be double-quoted.
- * @param {string} string
- * @returns
- */
-const stripDoubleQuotes = (string) => {
-  if (string.startsWith('"') && string.endsWith('"')) {
-    return string.slice(1, -1);
-  }
-  return string;
-};
-
 /* getVerifiedCommentedDirective */
 
 /**
@@ -138,7 +139,7 @@ const stripDoubleQuotes = (string) => {
  * - `'use agnostic strategies'`: Agnostic Strategies Modules may export JSX.
  * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} directive The commented directive as written on top of the file (cannot be `null` at that stage).
  * @param {TSX | TS | JSX | JS | MJS | CJS} extension The JavaScript (TypeScript) extension of the file.
- * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} The verified commented directive, from which imports rules are applied. Returns `null` if the verification failed, upon which an error will be reported depending on the commented directive, since the error logic here is strictly binary.
+ * @returns The verified commented directive, from which imports rules are applied. Returns `null` if the verification failed, upon which an error will be reported depending on the commented directive, since the error logic here is strictly binary.
  */
 export const getVerifiedCommentedDirective = (directive, extension) => {
   // I could use a map, but because this is in JS with JSDoc, a manual solution is peculiarly more typesafe.
@@ -183,7 +184,7 @@ export const getVerifiedCommentedDirective = (directive, extension) => {
  * - `'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 {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} 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 be provided.)
+ * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} 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
@@ -231,7 +232,7 @@ export const getCommentedDirectiveFromImportedModule = (resolvedImportPath) => {
  * Gets the interpreted directive from a specified commented Strategy (such as `@serverLogics`) nested inside the import declaration for an import from an Agnostic Strategies Module.
  * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
  * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
- * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | null} Returns the interpreted directive, a.k.a. strategized directive, or lack thereof via `null`.
+ * @returns The interpreted directive, a.k.a. strategized directive, or lack thereof via `null`.
  */
 export const getStrategizedDirective = (context, node) => {
   const firstNestedComment = context.sourceCode.getCommentsInside(node)[0];
@@ -239,9 +240,17 @@ export const getStrategizedDirective = (context, node) => {
   // returns null early if there is no nested comments
   if (!firstNestedComment) return null;
 
-  const strategy = firstNestedComment.value.trim() || null;
+  const rawStrategy = firstNestedComment.value.trim() || "";
+
+  const strategy =
+    strategiesArray.find((strategy) => strategy === rawStrategy) ?? null;
+
+  // returns null early if no strategy was identified
+  if (!strategy) return null;
 
-  return commentedStrategies_CommentedDirectives[strategy] || null;
+  const commentedDirective = commentedStrategies_CommentedDirectives[strategy];
+
+  return commentedDirective;
 };
 
 /* isImportBlocked */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-use-agnostic",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Highlights problematic server-client imports in projects made with the Fullstack React Architecture.",
   "keywords": [
     "eslint",
@@ -20,7 +20,8 @@
   "license": "MIT",
   "author": "Luther Tchofo Safo <luther@tchofo-safo-portfolio.me>",
   "files": [
-    "library"
+    "library",
+    "types/index.d.ts"
   ],
   "exports": {
     ".": "./library/index.js"
@@ -48,5 +49,6 @@
   "engines": {
     "node": ">=18.18.0 <18.99 || >=20.9.0 <21.0.0 || >=21.1.0"
   },
-  "type": "module"
+  "type": "module",
+  "types": "types/index.d.ts"
 }

package/types/index.d.ts

@@ -0,0 +1,12 @@
+import type { ESLint } from "eslint";
+
+declare const plugin: ESLint.Plugin;
+
+export default plugin;
+
+// must be manually maintained
+export const useAgnosticPluginName: "use-agnostic";
+export const agnostic20ConfigName: "agnostic20";
+export const directive21ConfigName: "directive21";
+export const enforceEffectiveDirectivesRuleName: "enforce-effective-directives-import-rules";
+export const enforceCommentedDirectivesRuleName: "enforce-commented-directives-import-rules";