eslint-plugin-use-agnostic 2.0.8 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/comments.config.json +4 -0
- package/comments.config.mjs +5 -1
- package/jscomments/jsdoc/comments.js +2 -0
- package/library/_commons/utilities/helpers.js +24 -24
- package/library/_commons/utilities/walk-ast.js +8 -8
- package/library/agnostic20/_commons/constants/bases.js +57 -57
- package/library/agnostic20/_commons/utilities/flows.js +26 -26
- package/library/agnostic20/_commons/utilities/helpers.js +43 -43
- package/library/agnostic20/config.js +3 -3
- package/library/directive21/_commons/constants/bases.js +105 -105
- package/library/directive21/_commons/rules/import-rules.js +18 -7
- package/library/directive21/_commons/utilities/analyze-exports-re.js +3 -3
- package/library/directive21/_commons/utilities/flows.js +61 -83
- package/library/directive21/_commons/utilities/helpers.js +85 -85
- package/library/directive21/config.js +3 -3
- package/library/index.js +8 -8
- package/package.json +1 -1
- package/types/index.d.ts +114 -114
package/types/index.d.ts
CHANGED
|
@@ -46,9 +46,9 @@ export const commentedDirectives_commentedModules: Readonly<{
|
|
|
46
46
|
}>;
|
|
47
47
|
|
|
48
48
|
/**
|
|
49
|
-
*
|
|
50
|
-
* @param context
|
|
51
|
-
* @returns
|
|
49
|
+
* Gets the coordinates for the first line of code of a file.
|
|
50
|
+
* @param context An ESLint rule's `context` object.
|
|
51
|
+
* @returns The `context.report` `loc`-compatible coordinates for the first line of code of a file.
|
|
52
52
|
*/
|
|
53
53
|
export const highlightFirstLineOfCode: (
|
|
54
54
|
context: RuleContext<string, readonly unknown[]>,
|
|
@@ -64,9 +64,9 @@ export const highlightFirstLineOfCode: (
|
|
|
64
64
|
};
|
|
65
65
|
|
|
66
66
|
/**
|
|
67
|
-
*
|
|
68
|
-
* @param {ResolvedDirective} resolvedDirective
|
|
69
|
-
* @returns
|
|
67
|
+
* Gets the environment from a resolved directive (like `"use server logics"` -> `"server"`). This can either be one of the Concrete Environments (the Server Environment or the Client Environment), or the Abstract Environment (the Agnostic Environment).
|
|
68
|
+
* @param {ResolvedDirective} resolvedDirective The resolved directive at hand.
|
|
69
|
+
* @returns Either `"server"`, `"client"`, or `"agnostic"`.
|
|
70
70
|
*/
|
|
71
71
|
export const getEnvironmentFromResolvedDirective: (
|
|
72
72
|
resolvedDirective:
|
|
@@ -127,56 +127,56 @@ export const directives_effectiveDirectives: Readonly<{
|
|
|
127
127
|
}>;
|
|
128
128
|
|
|
129
129
|
/**
|
|
130
|
-
*
|
|
131
|
-
* -
|
|
132
|
-
* -
|
|
133
|
-
* -
|
|
134
|
-
* -
|
|
135
|
-
* @param ast
|
|
136
|
-
* @returns
|
|
130
|
+
* Gets the directive of a module from its Abstract Syntax Tree.
|
|
131
|
+
* - `null` denotes a server-by-default module, ideally a Server Module.
|
|
132
|
+
* - `'use server'` denotes a Server Functions Module.
|
|
133
|
+
* - `'use client'` denotes a Client Module.
|
|
134
|
+
* - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
|
|
135
|
+
* @param ast The module's AST (Abstract Syntax Tree).
|
|
136
|
+
* @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
|
|
137
137
|
*/
|
|
138
138
|
export const getDirectiveFromModule: (
|
|
139
139
|
ast: TSESLintSourceCode.Program,
|
|
140
140
|
) => "use server" | "use client" | "use agnostic" | null;
|
|
141
141
|
|
|
142
142
|
/**
|
|
143
|
-
*
|
|
144
|
-
* -
|
|
145
|
-
* -
|
|
146
|
-
* -
|
|
147
|
-
* -
|
|
148
|
-
* @param context
|
|
149
|
-
* @returns
|
|
143
|
+
* Gets the directive of the current module.
|
|
144
|
+
* - `null` denotes a server-by-default module, ideally a Server Module.
|
|
145
|
+
* - `'use server'` denotes a Server Functions Module.
|
|
146
|
+
* - `'use client'` denotes a Client Module.
|
|
147
|
+
* - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
|
|
148
|
+
* @param context The ESLint rule's `context` object.
|
|
149
|
+
* @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
|
|
150
150
|
*/
|
|
151
151
|
export const getDirectiveFromCurrentModule: (
|
|
152
152
|
context: RuleContext<string, readonly unknown[]>,
|
|
153
153
|
) => "use server" | "use client" | "use agnostic" | null;
|
|
154
154
|
|
|
155
155
|
/**
|
|
156
|
-
*
|
|
157
|
-
* -
|
|
158
|
-
* -
|
|
159
|
-
* -
|
|
160
|
-
* -
|
|
161
|
-
* @param resolvedPath
|
|
162
|
-
* @returns
|
|
156
|
+
* Gets the directive of the imported module.
|
|
157
|
+
* - `null` denotes a server-by-default module, ideally a Server Module.
|
|
158
|
+
* - `'use server'` denotes a Server Functions Module.
|
|
159
|
+
* - `'use client'` denotes a Client Module.
|
|
160
|
+
* - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
|
|
161
|
+
* @param resolvedPath The resolved path of the imported module.
|
|
162
|
+
* @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
|
|
163
163
|
*/
|
|
164
164
|
export const getDirectiveFromImportedModule: (
|
|
165
165
|
resolvedPath: string,
|
|
166
166
|
) => "use server" | "use client" | "use agnostic" | null;
|
|
167
167
|
|
|
168
168
|
/**
|
|
169
|
-
*
|
|
170
|
-
* -
|
|
171
|
-
* -
|
|
172
|
-
* -
|
|
173
|
-
* -
|
|
174
|
-
* -
|
|
175
|
-
* -
|
|
176
|
-
* -
|
|
177
|
-
* @param directive
|
|
178
|
-
* @param extension
|
|
179
|
-
* @returns
|
|
169
|
+
* Gets the effective directive of a module, based on the combination of its directive (or lack thereof) and its extension (depending on whether it ends with 'x' for JSX).
|
|
170
|
+
* - `'use server logics'` denotes a Server Logics Module.
|
|
171
|
+
* - `'use server components'` denotes a Server Components Module.
|
|
172
|
+
* - `'use server functions'` denotes a Server Functions Module.
|
|
173
|
+
* - `'use client logics'` denotes a Client Logics Module.
|
|
174
|
+
* - `'use client components'` denotes a Client Components Module.
|
|
175
|
+
* - `'use agnostic logics'` denotes an Agnostic Logics Module.
|
|
176
|
+
* - `'use agnostic components'` denotes an Agnostic Components Module.
|
|
177
|
+
* @param directive The directive as written on top of the file (`"no directive"` if no valid directive).
|
|
178
|
+
* @param extension The JavaScript (TypeScript) extension of the file.
|
|
179
|
+
* @returns The effective directive, from which imports rules are applied.
|
|
180
180
|
*/
|
|
181
181
|
export const getEffectiveDirective: (
|
|
182
182
|
directive: "use server" | "use client" | "use agnostic" | "no directive",
|
|
@@ -204,10 +204,10 @@ export const getEffectiveDirective: (
|
|
|
204
204
|
| null;
|
|
205
205
|
|
|
206
206
|
/**
|
|
207
|
-
*
|
|
208
|
-
* @param currentFileEffectiveDirective
|
|
209
|
-
* @param importedFileEffectiveDirective
|
|
210
|
-
* @returns
|
|
207
|
+
* Returns a boolean deciding if an imported file's effective directive is incompatible with the current file's effective directive.
|
|
208
|
+
* @param currentFileEffectiveDirective The current file's effective directive.
|
|
209
|
+
* @param importedFileEffectiveDirective The imported file's effective directive.
|
|
210
|
+
* @returns `true` if the import is blocked, as established in `effectiveDirectives_BlockedImports`.
|
|
211
211
|
*/
|
|
212
212
|
export const isImportBlockedAgnostic20: (
|
|
213
213
|
currentFileEffectiveDirective:
|
|
@@ -430,21 +430,21 @@ export const environments_conditionedExtensions: Readonly<{
|
|
|
430
430
|
export const directive21Data: object;
|
|
431
431
|
|
|
432
432
|
/**
|
|
433
|
-
*
|
|
433
|
+
* Gets the commented directive of a module from its ESLint `SourceCode` object.
|
|
434
434
|
*
|
|
435
|
-
*
|
|
436
|
-
* -
|
|
437
|
-
* -
|
|
438
|
-
* -
|
|
439
|
-
* -
|
|
440
|
-
* -
|
|
441
|
-
* -
|
|
442
|
-
* -
|
|
443
|
-
* -
|
|
444
|
-
* -
|
|
445
|
-
* -
|
|
446
|
-
* @param sourceCode
|
|
447
|
-
* @returns
|
|
435
|
+
* Accepted directives for the default Directive-First Architecture are (single or double quotes included):
|
|
436
|
+
* - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
|
|
437
|
+
* - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
|
|
438
|
+
* - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
|
|
439
|
+
* - `'use server components'`, `"use server components"` denoting a Server Components Module.
|
|
440
|
+
* - `'use client components'`, `"use client components"` denoting a Client Components Module.
|
|
441
|
+
* - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
|
|
442
|
+
* - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
|
|
443
|
+
* - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
|
|
444
|
+
* - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
|
|
445
|
+
* - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
|
|
446
|
+
* @param sourceCode The ESLint SourceCode object.
|
|
447
|
+
* @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.)
|
|
448
448
|
*/
|
|
449
449
|
export const getCommentedDirectiveFromSourceCode: (
|
|
450
450
|
sourceCode: ESLintSourceCode,
|
|
@@ -462,21 +462,21 @@ export const getCommentedDirectiveFromSourceCode: (
|
|
|
462
462
|
| null;
|
|
463
463
|
|
|
464
464
|
/**
|
|
465
|
-
*
|
|
465
|
+
* Gets the commented directive of the current module.
|
|
466
466
|
*
|
|
467
|
-
*
|
|
468
|
-
* -
|
|
469
|
-
* -
|
|
470
|
-
* -
|
|
471
|
-
* -
|
|
472
|
-
* -
|
|
473
|
-
* -
|
|
474
|
-
* -
|
|
475
|
-
* -
|
|
476
|
-
* -
|
|
477
|
-
* -
|
|
478
|
-
* @param context
|
|
479
|
-
* @returns
|
|
467
|
+
* Accepted directives for the default Directive-First Architecture are (single or double quotes included):
|
|
468
|
+
* - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
|
|
469
|
+
* - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
|
|
470
|
+
* - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
|
|
471
|
+
* - `'use server components'`, `"use server components"` denoting a Server Components Module.
|
|
472
|
+
* - `'use client components'`, `"use client components"` denoting a Client Components Module.
|
|
473
|
+
* - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
|
|
474
|
+
* - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
|
|
475
|
+
* - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
|
|
476
|
+
* - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
|
|
477
|
+
* - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
|
|
478
|
+
* @param context The ESLint rule's `context` object.
|
|
479
|
+
* @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.)
|
|
480
480
|
*/
|
|
481
481
|
export const getCommentedDirectiveFromCurrentModule: (
|
|
482
482
|
context: RuleContext<string, readonly unknown[]>,
|
|
@@ -494,21 +494,21 @@ export const getCommentedDirectiveFromCurrentModule: (
|
|
|
494
494
|
| null;
|
|
495
495
|
|
|
496
496
|
/**
|
|
497
|
-
*
|
|
497
|
+
* Gets the commented directive of the imported module.
|
|
498
498
|
*
|
|
499
|
-
*
|
|
500
|
-
* -
|
|
501
|
-
* -
|
|
502
|
-
* -
|
|
503
|
-
* -
|
|
504
|
-
* -
|
|
505
|
-
* -
|
|
506
|
-
* -
|
|
507
|
-
* -
|
|
508
|
-
* -
|
|
509
|
-
* -
|
|
510
|
-
* @param resolvedPath
|
|
511
|
-
* @returns
|
|
499
|
+
* Accepted directives for the default Directive-First Architecture are (single or double quotes included):
|
|
500
|
+
* - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
|
|
501
|
+
* - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
|
|
502
|
+
* - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
|
|
503
|
+
* - `'use server components'`, `"use server components"` denoting a Server Components Module.
|
|
504
|
+
* - `'use client components'`, `"use client components"` denoting a Client Components Module.
|
|
505
|
+
* - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
|
|
506
|
+
* - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
|
|
507
|
+
* - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
|
|
508
|
+
* - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
|
|
509
|
+
* - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
|
|
510
|
+
* @param resolvedPath The resolved path of the imported module.
|
|
511
|
+
* @returns The commented directive, or lack thereof via `null`. Now also provides the obtained `SourceCode` object. 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.)
|
|
512
512
|
*/
|
|
513
513
|
export const getCommentedDirectiveFromImportedModule: (
|
|
514
514
|
resolvedPath: string,
|
|
@@ -529,20 +529,20 @@ export const getCommentedDirectiveFromImportedModule: (
|
|
|
529
529
|
};
|
|
530
530
|
|
|
531
531
|
/**
|
|
532
|
-
*
|
|
533
|
-
* -
|
|
534
|
-
* -
|
|
535
|
-
* -
|
|
536
|
-
* -
|
|
537
|
-
* -
|
|
538
|
-
* -
|
|
539
|
-
* -
|
|
540
|
-
* -
|
|
541
|
-
* -
|
|
542
|
-
* -
|
|
543
|
-
* @param directive
|
|
544
|
-
* @param extension
|
|
545
|
-
* @returns
|
|
532
|
+
* Ensures that a module's commented directive is consistent with its file extension (depending on whether it ends with 'x' for JSX).
|
|
533
|
+
* - `'use server logics'`: Server Logics Modules do NOT export JSX.
|
|
534
|
+
* - `'use client logics'`: Client Logics Modules do NOT export JSX.
|
|
535
|
+
* - `'use agnostic logics'`: Agnostic Logics Modules do NOT export JSX.
|
|
536
|
+
* - `'use server components'`: Server Components Modules ONLY export JSX.
|
|
537
|
+
* - `'use client components'`: Client Components Modules ONLY export JSX.
|
|
538
|
+
* - `'use agnostic components'`: Agnostic Components Modules ONLY export JSX.
|
|
539
|
+
* - `'use server functions'`: Server Functions Modules do NOT export JSX.
|
|
540
|
+
* - `'use client contexts'`: Client Contexts Modules ONLY export JSX.
|
|
541
|
+
* - `'use agnostic conditions'`: Agnostic Conditions Modules ONLY export JSX.
|
|
542
|
+
* - `'use agnostic strategies'`: Agnostic Strategies Modules may export JSX.
|
|
543
|
+
* @param directive The commented directive as written on top of the file (cannot be `null` at that stage).
|
|
544
|
+
* @param extension The JavaScript (TypeScript) extension of the file.
|
|
545
|
+
* @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.
|
|
546
546
|
*/
|
|
547
547
|
export const getVerifiedCommentedDirective: (
|
|
548
548
|
directive:
|
|
@@ -583,10 +583,10 @@ export const getVerifiedCommentedDirective: (
|
|
|
583
583
|
| null;
|
|
584
584
|
|
|
585
585
|
/**
|
|
586
|
-
*
|
|
587
|
-
* @param context
|
|
588
|
-
* @param node
|
|
589
|
-
* @returns
|
|
586
|
+
* Gets the interpreted directive from a specified commented Strategy (such as `@serverLogics`) nested inside the import (or export) declaration for an import (or export) from an Agnostic Strategies Module.
|
|
587
|
+
* @param context The ESLint rule's `context` object.
|
|
588
|
+
* @param node The ESLint `node` of the rule's current traversal.
|
|
589
|
+
* @returns The interpreted directive, a.k.a. strategized directive, or lack thereof via `null`.
|
|
590
590
|
*/
|
|
591
591
|
export const getStrategizedDirective: (
|
|
592
592
|
context: RuleContext<string, readonly unknown[]>,
|
|
@@ -608,10 +608,10 @@ export const getStrategizedDirective: (
|
|
|
608
608
|
| null;
|
|
609
609
|
|
|
610
610
|
/**
|
|
611
|
-
*
|
|
612
|
-
* @param currentFileCommentedDirective
|
|
613
|
-
* @param importedFileCommentedDirective
|
|
614
|
-
* @returns
|
|
611
|
+
* Returns a boolean deciding if an imported file's commented directive is incompatible with the current file's commented directive.
|
|
612
|
+
* @param currentFileCommentedDirective The current file's commented directive.
|
|
613
|
+
* @param importedFileCommentedDirective The imported file's commented directive.
|
|
614
|
+
* @returns `true` if the import is blocked, as established in `commentedDirectives_BlockedImports`.
|
|
615
615
|
*/
|
|
616
616
|
export const isImportBlockedDirective21: (
|
|
617
617
|
currentFileCommentedDirective:
|
|
@@ -639,9 +639,9 @@ export const isImportBlockedDirective21: (
|
|
|
639
639
|
) => boolean;
|
|
640
640
|
|
|
641
641
|
/**
|
|
642
|
-
*
|
|
643
|
-
* @param reactFolder
|
|
644
|
-
* @returns
|
|
642
|
+
* Creates the ESLint config object required as the basis for the Directive-First Architecture, linting server-client-agnostic imports based on their commented directives. (Defaults to `"warn"`. You can import and use ```[`${useAgnosticPluginName}/${directive21ConfigName}`]``` later in a further ESLint config object to modify that value.)
|
|
643
|
+
* @param reactFolder The path of the project's React folder where everything React lives, relative to the root of the project. This is, for example, the app directory when using the Next.js App Router, as `"app"`.
|
|
644
|
+
* @returns An ESLint config object that applies `eslint-plugin-use-agnostic`'s `directive21` config by using the provided `reactFolder` as the basis for JavaScript/TypeScript glob patterns.
|
|
645
645
|
*/
|
|
646
646
|
export const defineDirective21: <T extends string>(
|
|
647
647
|
reactFolder: T,
|
|
@@ -661,11 +661,11 @@ export const defineDirective21: <T extends string>(
|
|
|
661
661
|
};
|
|
662
662
|
|
|
663
663
|
/**
|
|
664
|
-
*
|
|
665
|
-
* @param settings
|
|
666
|
-
* @param settings.reactFolder
|
|
667
|
-
* @param settings.rootPath
|
|
668
|
-
* @returns
|
|
664
|
+
* Defines the config settings for the eXtra JSX VS Code extension as a means to configure `eXtra JSX` directly from ESLint, given the fact that `eslint-plugin-use-agnostic` and `eXtra JSX` have to work together in making the Directive-First Architecture.
|
|
665
|
+
* @param settings The settings as follows:
|
|
666
|
+
* @param settings.reactFolder The path of the project's React folder where everything React lives, relative to the root of the project. This is, for example, the app directory when using the Next.js App Router, as `"app"`.
|
|
667
|
+
* @param settings.rootPath The absolute path of the root of the project, from which the absolute path of the React folder can be easily obtained.
|
|
668
|
+
* @returns The config object responsible for the settings retrieved by the eXtra JSX VS Code extension.
|
|
669
669
|
*/
|
|
670
670
|
export const defineConfigSettings: <T extends string, U extends string>({
|
|
671
671
|
reactFolder,
|