@starci/eslint-canon-be 3.11.19 → 3.13.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/CHANGELOG.md +11 -0
- package/README.md +10 -0
- package/dist/auth-passport.d.ts +2 -4
- package/dist/auth-passport.js +21 -33
- package/dist/explicit-surface.d.ts +7 -0
- package/dist/explicit-surface.js +19 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +3 -1
- package/dist/lib/unit-spec.js +2 -2
- package/dist/project-graph.d.ts +14 -0
- package/dist/project-graph.js +16 -1
- package/package.json +1 -1
- package/runtime/bundle.json +2 -0
- package/runtime/knowledge/hfs/canon-pins.yaml +31 -10
- package/runtime/knowledge/hfs/fe-stack.yaml +7 -7
- package/runtime/knowledge/hfs/rules.yaml +107 -8
- package/runtime/knowledge/hfs/slots.yaml +71 -22
- package/runtime/scripts/hfs/architecture/identity.mjs +18 -83
- package/runtime/scripts/hfs/architecture/test-world-files.mjs +26 -7
- package/runtime/scripts/hfs/architecture/transport-owner.mjs +3 -6
- package/runtime/scripts/hfs/explicit-surface-rule.mjs +59 -0
- package/runtime/scripts/hfs/manifest-shape.mjs +1 -1
- package/runtime/scripts/hfs/slots.mjs +1 -1
- package/runtime/scripts/lib/declaration-surface.mjs +112 -0
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { declarationSurface, isEmittableSource } from '../lib/declaration-surface.mjs';
|
|
2
|
+
/** What to write, by what the classifier says to annotate. */
|
|
3
|
+
const HINTS = {
|
|
4
|
+
'return type': 'Write the return type after the parameter list: `(): Result =>` or `function name(): Result`.',
|
|
5
|
+
'variable type': 'Give the variable a type: `export const name: Result = ...`.',
|
|
6
|
+
'parameter type': 'Give the parameter a type: `(value: Input)`.',
|
|
7
|
+
'property type': 'Give the property a type: `name: Result = ...`.',
|
|
8
|
+
'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
|
|
9
|
+
'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`.',
|
|
10
|
+
'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
|
|
11
|
+
};
|
|
12
|
+
/** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */
|
|
13
|
+
const plain = (reason) => reason.replace(/ with --isolatedDeclarations\.?/, '').replace(/\.$/, '');
|
|
14
|
+
/**
|
|
15
|
+
* The rule. `ts` is the canon's own TypeScript (its peer dependency); the side's `module` option comes from the typed program when the file is linted with one.
|
|
16
|
+
*
|
|
17
|
+
* @param input - `ts` is the compiler.
|
|
18
|
+
* @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
|
|
19
|
+
*/
|
|
20
|
+
export const explicitSurfaceRule = ({ ts }) => ({
|
|
21
|
+
meta: {
|
|
22
|
+
type: 'problem',
|
|
23
|
+
docs: { description: 'An exported declaration states its type: the return type, variable type or parameter type is written, not inferred from a body or from other files.' },
|
|
24
|
+
schema: [],
|
|
25
|
+
messages: {
|
|
26
|
+
inferred: 'HFS_EXPLICIT_EXPORT_SURFACE: `{{name}}` is exported with an inferred type ({{reason}}), so importers cannot read it from this file and every one of them is linted again whenever the file changes. Annotate the {{annotate}}. {{hint}}',
|
|
27
|
+
},
|
|
28
|
+
},
|
|
29
|
+
create(context) {
|
|
30
|
+
return {
|
|
31
|
+
Program() {
|
|
32
|
+
const file = context.filename;
|
|
33
|
+
if (!isEmittableSource(file))
|
|
34
|
+
return;
|
|
35
|
+
const { sourceCode } = context;
|
|
36
|
+
const module = sourceCode.parserServices?.program?.getCompilerOptions().module;
|
|
37
|
+
const whole = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
|
|
38
|
+
let surface;
|
|
39
|
+
try {
|
|
40
|
+
surface = declarationSurface(ts, file, sourceCode.text, module);
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
surface = null;
|
|
44
|
+
}
|
|
45
|
+
if (surface === null) {
|
|
46
|
+
context.report({ loc: whole, messageId: 'inferred', data: { name: 'this file', reason: 'the declaration emit could not read it', annotate: 'exported value', hint: HINTS['exported value'] } });
|
|
47
|
+
return;
|
|
48
|
+
}
|
|
49
|
+
for (const problem of surface.problems) {
|
|
50
|
+
context.report({
|
|
51
|
+
loc: { start: sourceCode.getLocFromIndex(problem.start), end: sourceCode.getLocFromIndex(problem.start + problem.length) },
|
|
52
|
+
messageId: 'inferred',
|
|
53
|
+
data: { name: problem.name, reason: plain(problem.reason), annotate: problem.annotate, hint: HINTS[problem.annotate] },
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
},
|
|
59
|
+
});
|
|
@@ -121,7 +121,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
|
|
|
121
121
|
export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
|
|
122
122
|
const strList = (v) => stringList(v);
|
|
123
123
|
|
|
124
|
-
const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'logic'];
|
|
124
|
+
const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'logic', 'managedOnly'];
|
|
125
125
|
/** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
|
|
126
126
|
const SLOT_ROLES = ['entity-registry'];
|
|
127
127
|
/** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
|
|
@@ -232,7 +232,7 @@ export function readRepoDeclaration(manifest, repoRoot) {
|
|
|
232
232
|
function createScopeResolver(manifest, repo) {
|
|
233
233
|
const profile = repo.profile;
|
|
234
234
|
const edition = repo.edition ?? 'full';
|
|
235
|
-
const slots = manifest.slots.filter((s) => s.profiles.includes(profile) && slotInEdition(manifest, s, edition)).map((s) => effectiveSlot(s, profile, edition));
|
|
235
|
+
const slots = manifest.slots.filter((s) => s.managedOnly !== true && s.profiles.includes(profile) && slotInEdition(manifest, s, edition)).map((s) => effectiveSlot(s, profile, edition));
|
|
236
236
|
const scope = { manifest, repo, profile, slots, byId: new Map(slots.map((s) => [s.id, s])), variants: slots.flatMap(variantsOf), appKind: new Map(repo.apps.map((a) => [a.name, a.kind])) };
|
|
237
237
|
const classifyPath = (input) => classifyIn(scope, input);
|
|
238
238
|
/** tracked | ignored | external for the slot owning `p`, or null when no slot owns it. */
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
|
|
2
|
+
export const SCRIPT = /\.(?:[cm]?jsx?)$/;
|
|
3
|
+
/** A declaration file: it is its own surface. */
|
|
4
|
+
export const DECLARATION = /\.d\.[cm]?ts$/;
|
|
5
|
+
/** A TypeScript source file whose surface the declaration emit writes. */
|
|
6
|
+
export const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
|
|
7
|
+
/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
|
|
8
|
+
export const isEmittableSource = (file) => TYPESCRIPT.test(file) && !DECLARATION.test(file);
|
|
9
|
+
/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
|
|
10
|
+
function isJsxValue(ts, expression) {
|
|
11
|
+
if (expression === undefined)
|
|
12
|
+
return false;
|
|
13
|
+
let node = expression;
|
|
14
|
+
while (ts.isParenthesizedExpression(node))
|
|
15
|
+
node = node.expression;
|
|
16
|
+
if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
|
|
17
|
+
return true;
|
|
18
|
+
if (ts.isIdentifier(node))
|
|
19
|
+
return node.text === 'undefined';
|
|
20
|
+
return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
|
|
24
|
+
* reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
|
|
25
|
+
* type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
|
|
26
|
+
*/
|
|
27
|
+
function returnsOnlyJsx(ts, source, start) {
|
|
28
|
+
let found;
|
|
29
|
+
const find = (node) => {
|
|
30
|
+
if (found !== undefined || start < node.getFullStart() || start >= node.end)
|
|
31
|
+
return;
|
|
32
|
+
const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
|
|
33
|
+
if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
|
|
34
|
+
found = node;
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
37
|
+
ts.forEachChild(node, find);
|
|
38
|
+
};
|
|
39
|
+
find(source);
|
|
40
|
+
const fn = found;
|
|
41
|
+
if (fn === undefined || fn.type !== undefined || fn.body === undefined)
|
|
42
|
+
return false;
|
|
43
|
+
if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
|
|
44
|
+
return false;
|
|
45
|
+
if (!ts.isBlock(fn.body))
|
|
46
|
+
return isJsxValue(ts, fn.body);
|
|
47
|
+
let only = true;
|
|
48
|
+
const visit = (node) => {
|
|
49
|
+
if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
|
|
50
|
+
return;
|
|
51
|
+
if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
|
|
52
|
+
only = false;
|
|
53
|
+
ts.forEachChild(node, visit);
|
|
54
|
+
};
|
|
55
|
+
ts.forEachChild(fn.body, visit);
|
|
56
|
+
return only;
|
|
57
|
+
}
|
|
58
|
+
/** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
|
|
59
|
+
const ANNOTATE = new Map([
|
|
60
|
+
[9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
|
|
61
|
+
[9019, 'destructured export'], [9025, 'parameter type'],
|
|
62
|
+
]);
|
|
63
|
+
/** The declaration kinds whose name labels the export a diagnostic sits in, innermost first. */
|
|
64
|
+
function nameOf(ts, source, start) {
|
|
65
|
+
let innermost = source;
|
|
66
|
+
const descend = (node) => {
|
|
67
|
+
if (start < node.getFullStart() || start >= node.end)
|
|
68
|
+
return;
|
|
69
|
+
innermost = node;
|
|
70
|
+
ts.forEachChild(node, descend);
|
|
71
|
+
};
|
|
72
|
+
ts.forEachChild(source, descend);
|
|
73
|
+
for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
|
|
74
|
+
if (ts.isExportAssignment(node))
|
|
75
|
+
return 'default export';
|
|
76
|
+
if (ts.isBindingElement(node) && ts.isIdentifier(node.name))
|
|
77
|
+
return node.name.text;
|
|
78
|
+
if ((ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node) || ts.isGetAccessorDeclaration(node)) && node.name !== undefined && ts.isIdentifier(node.name))
|
|
79
|
+
return node.name.text;
|
|
80
|
+
if (ts.isFunctionDeclaration(node) && (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0)
|
|
81
|
+
return 'default export';
|
|
82
|
+
}
|
|
83
|
+
return 'default export';
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
|
|
87
|
+
* when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
|
|
88
|
+
* surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
|
|
89
|
+
* decides what an unreadable file means.
|
|
90
|
+
*/
|
|
91
|
+
export function declarationSurface(ts, file, text, module) {
|
|
92
|
+
const emit = ts.transpileDeclaration;
|
|
93
|
+
if (emit === undefined)
|
|
94
|
+
return null;
|
|
95
|
+
const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(module === undefined ? {} : { module }) }, fileName: file, reportDiagnostics: true });
|
|
96
|
+
const diagnostics = (declared.diagnostics ?? []);
|
|
97
|
+
if (diagnostics.length === 0)
|
|
98
|
+
return { outputText: declared.outputText, problems: [] };
|
|
99
|
+
const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
|
|
100
|
+
const problems = [];
|
|
101
|
+
for (const diagnostic of diagnostics) {
|
|
102
|
+
const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
|
|
103
|
+
if (exempt)
|
|
104
|
+
continue;
|
|
105
|
+
const start = diagnostic.start ?? 0;
|
|
106
|
+
problems.push({
|
|
107
|
+
code: diagnostic.code, start, length: diagnostic.length ?? 0, name: nameOf(ts, source, start), annotate: ANNOTATE.get(diagnostic.code) ?? 'exported value',
|
|
108
|
+
reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
return { outputText: declared.outputText, problems };
|
|
112
|
+
}
|