@noego/trust 0.4.0 → 0.5.0-dev.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/README.md +926 -13
- package/dist/baseline-B0AplCuF.d.ts +362 -0
- package/dist/chunk-NG4KYWVW.js +6154 -0
- package/dist/chunk-NG4KYWVW.js.map +1 -0
- package/dist/chunk-OSSITT3R.js +156 -0
- package/dist/chunk-OSSITT3R.js.map +1 -0
- package/dist/chunk-V72KWVWP.js +2820 -0
- package/dist/chunk-V72KWVWP.js.map +1 -0
- package/dist/cli/index.js +1140 -63
- package/dist/cli/index.js.map +1 -1
- package/dist/core/index.d.ts +127 -0
- package/dist/core/index.js +115 -0
- package/dist/core/index.js.map +1 -0
- package/dist/eslint/index.d.ts +73 -167
- package/dist/eslint/index.js +320 -32
- package/dist/eslint/index.js.map +1 -1
- package/package.json +7 -4
- package/dist/chunk-YJYGTNJD.js +0 -2168
- package/dist/chunk-YJYGTNJD.js.map +0 -1
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
import * as TS from 'typescript';
|
|
2
|
+
|
|
3
|
+
type TypeScript = typeof TS;
|
|
4
|
+
declare function loadTypeScript(cwd: string): TypeScript;
|
|
5
|
+
|
|
6
|
+
type Zone = 'checked' | 'passthrough' | 'ignore' | 'external';
|
|
7
|
+
interface ZoneGroup {
|
|
8
|
+
/** Config file that declared the patterns (for error messages). */
|
|
9
|
+
readonly source: string;
|
|
10
|
+
/** Realpath of the directory the patterns are relative to. */
|
|
11
|
+
readonly baseDir: string;
|
|
12
|
+
readonly patterns: readonly string[];
|
|
13
|
+
}
|
|
14
|
+
declare function toPosix(path: string): string;
|
|
15
|
+
declare function realpathOrSelf(path: string): string;
|
|
16
|
+
/** Normalizes one configured pattern; returns an error message for an invalid one. */
|
|
17
|
+
declare function normalizePattern(raw: string): {
|
|
18
|
+
pattern: string;
|
|
19
|
+
} | {
|
|
20
|
+
error: string;
|
|
21
|
+
};
|
|
22
|
+
/** Posix path of `absolutePath` relative to `baseDir`, or null when it lies outside. */
|
|
23
|
+
declare function relativeInside(baseDir: string, absolutePath: string): string | null;
|
|
24
|
+
/** ESLint `ignores` semantics: patterns apply in order, a `!pattern` match un-includes. */
|
|
25
|
+
declare function matchesPatterns(patterns: readonly string[], rel: string): boolean;
|
|
26
|
+
declare function groupMatches(group: ZoneGroup, absoluteRealPath: string): boolean;
|
|
27
|
+
declare class Zones {
|
|
28
|
+
/** Realpath of the project root (directory of the leaf trust config). */
|
|
29
|
+
readonly rootDir: string;
|
|
30
|
+
private readonly passthrough;
|
|
31
|
+
private readonly ignore;
|
|
32
|
+
private readonly cache;
|
|
33
|
+
constructor(
|
|
34
|
+
/** Realpath of the project root (directory of the leaf trust config). */
|
|
35
|
+
rootDir: string, passthrough: readonly ZoneGroup[], ignore: readonly ZoneGroup[]);
|
|
36
|
+
/** Zone of a file. Ignore wins over passthrough; files outside the root or in node_modules are external. */
|
|
37
|
+
zoneOf(fileName: string): Zone;
|
|
38
|
+
/** Project-relative posix path (for `local:` origins and baselines), or the absolute path when outside. */
|
|
39
|
+
relativePath(fileName: string): string;
|
|
40
|
+
private compute;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
type TrustEntry = string | {
|
|
44
|
+
readonly origin: string;
|
|
45
|
+
readonly reason?: string;
|
|
46
|
+
};
|
|
47
|
+
interface TrustLevel {
|
|
48
|
+
/** Config file path or `preset:<name>`. */
|
|
49
|
+
readonly source: string;
|
|
50
|
+
readonly trust: readonly string[];
|
|
51
|
+
readonly distrust: readonly string[];
|
|
52
|
+
/** Origins whose declared types are trusted (`trust_type`). */
|
|
53
|
+
readonly typeTrust: readonly string[];
|
|
54
|
+
/** Origins removed from the inherited type-trust list (`distrust_type`). */
|
|
55
|
+
readonly typeDistrust: readonly string[];
|
|
56
|
+
}
|
|
57
|
+
interface TrustConfig {
|
|
58
|
+
/** Absolute path of the leaf config file. */
|
|
59
|
+
readonly file: string;
|
|
60
|
+
/** Realpath of the leaf config file's directory: the project root for zones and `local:` origins. */
|
|
61
|
+
readonly rootDir: string;
|
|
62
|
+
/** Leaf first, root preset last. */
|
|
63
|
+
readonly levels: readonly TrustLevel[];
|
|
64
|
+
readonly passthrough: readonly ZoneGroup[];
|
|
65
|
+
readonly ignore: readonly ZoneGroup[];
|
|
66
|
+
/** `strict` globs of the chain: `trust check` also runs the strict rules on files matching them. */
|
|
67
|
+
readonly strict: readonly ZoneGroup[];
|
|
68
|
+
/** `tsconfig` entries of the chain, leaf first, in declaration order. */
|
|
69
|
+
readonly tsconfig: readonly TsconfigMapping[];
|
|
70
|
+
/** Per-rule settings (`rules`), each resolved along the chain; unset keys take DEFAULT_RULE_SETTINGS. */
|
|
71
|
+
readonly rules: TrustRuleSettings;
|
|
72
|
+
}
|
|
73
|
+
/** An opt-in rule's switch. */
|
|
74
|
+
type RuleSwitch = 'on' | 'off';
|
|
75
|
+
/** Which callback parameters are untrusted-value sources (see the file comment). */
|
|
76
|
+
type UntrustedCallbacks = 'off' | 'inline' | 'all';
|
|
77
|
+
/** The rules that are off unless a config turns them on. */
|
|
78
|
+
type OptInRule = 'type-claim' | 'untrusted-value' | 'dropped-result' | 'redundant-guard';
|
|
79
|
+
interface TrustRuleSettings {
|
|
80
|
+
readonly 'type-claim': RuleSwitch;
|
|
81
|
+
readonly 'untrusted-value': RuleSwitch;
|
|
82
|
+
readonly 'dropped-result': RuleSwitch;
|
|
83
|
+
readonly 'redundant-guard': RuleSwitch;
|
|
84
|
+
readonly untrustedCallbacks: UntrustedCallbacks;
|
|
85
|
+
}
|
|
86
|
+
/** What a config that sets nothing gets: the opt-in rules off, callbacks as today. */
|
|
87
|
+
declare const DEFAULT_RULE_SETTINGS: TrustRuleSettings;
|
|
88
|
+
/** Whether the config turns an opt-in rule on. */
|
|
89
|
+
declare function isRuleEnabled(config: Pick<TrustConfig, 'rules'>, rule: OptInRule): boolean;
|
|
90
|
+
/** One `tsconfig` entry: files matching `patterns` (zone glob semantics) compile under `tsconfig`. */
|
|
91
|
+
interface TsconfigMapping extends ZoneGroup {
|
|
92
|
+
/** Position in the declaring file's `tsconfig` array (for error messages). */
|
|
93
|
+
readonly index: number;
|
|
94
|
+
/** Absolute tsconfig path. Its existence is checked when a file maps to it, not at load. */
|
|
95
|
+
readonly tsconfig: string;
|
|
96
|
+
}
|
|
97
|
+
interface LoadTrustConfigOptions {
|
|
98
|
+
/** Check that every glob matches at least one file (default true). */
|
|
99
|
+
readonly validateGlobs?: boolean;
|
|
100
|
+
/**
|
|
101
|
+
* Directory the leaf config's globs, `tsconfig` paths, baseline keys and `local:` origins resolve
|
|
102
|
+
* against, instead of the config file's own directory (a config kept outside the project).
|
|
103
|
+
*/
|
|
104
|
+
readonly rootDir?: string;
|
|
105
|
+
}
|
|
106
|
+
declare class TrustConfigError extends Error {
|
|
107
|
+
readonly name = "TrustConfigError";
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Trust entries are matched exactly as written. Origin namespaces:
|
|
111
|
+
* js:JSON.parse JavaScript built-ins (TypeScript lib)
|
|
112
|
+
* node:fs.existsSync Node built-in modules (the `node:` import specifier)
|
|
113
|
+
* node:global.process.cwd Node globals
|
|
114
|
+
* zod.object, @scope/pkg.fn npm packages (bare package name)
|
|
115
|
+
*/
|
|
116
|
+
declare function normalizeOrigin(origin: string): string;
|
|
117
|
+
/** Loads and validates a trust config file and its `extend` chain. Throws TrustConfigError. */
|
|
118
|
+
declare function loadTrustConfig(configFile: string, options?: LoadTrustConfigOptions): TrustConfig;
|
|
119
|
+
/** Union of every trust entry in the chain (for tooling and tests). */
|
|
120
|
+
declare function effectiveTrustList(config: TrustConfig): string[];
|
|
121
|
+
/** Union of every type-trust entry in the chain (for tooling and tests). */
|
|
122
|
+
declare function effectiveTypeTrustList(config: TrustConfig): string[];
|
|
123
|
+
|
|
124
|
+
type OriginInfo = {
|
|
125
|
+
readonly kind: 'external';
|
|
126
|
+
readonly origin: string;
|
|
127
|
+
readonly base: string;
|
|
128
|
+
readonly fileName: string;
|
|
129
|
+
} | {
|
|
130
|
+
readonly kind: 'local';
|
|
131
|
+
readonly zone: Exclude<Zone, 'external'>;
|
|
132
|
+
readonly origin: string;
|
|
133
|
+
readonly fileName: string;
|
|
134
|
+
};
|
|
135
|
+
/** Name in the nearest package.json that has one, walking up from the file. */
|
|
136
|
+
declare function nearestPackageName(fileName: string): string | null;
|
|
137
|
+
declare class OriginResolver {
|
|
138
|
+
private readonly ts;
|
|
139
|
+
private readonly zones;
|
|
140
|
+
constructor(ts: TypeScript, zones: Zones);
|
|
141
|
+
originOf(declaration: TS.Node): OriginInfo;
|
|
142
|
+
/** Named containers from the module down to (and including) the declaration. */
|
|
143
|
+
memberPath(declaration: TS.Node): string[];
|
|
144
|
+
private containerName;
|
|
145
|
+
private ambientModuleName;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** The directive, as written after the comment marker. */
|
|
149
|
+
declare const VALIDATOR_DIRECTIVE = "trust:validator_function";
|
|
150
|
+
/** The accept directive, as written after the comment marker; its reason follows it (accept.ts). */
|
|
151
|
+
declare const ACCEPT_DIRECTIVE = "trust:accept";
|
|
152
|
+
/** A `//trust:…` comment: the validator or accept directive, or a typo of one. */
|
|
153
|
+
interface TrustDirective {
|
|
154
|
+
readonly pos: number;
|
|
155
|
+
readonly end: number;
|
|
156
|
+
/** The comment as written (`//trust:validator_function`). */
|
|
157
|
+
readonly text: string;
|
|
158
|
+
readonly kind: 'line' | 'block';
|
|
159
|
+
/** The comment's content after its marker, trimmed (`trust:validator_function`). */
|
|
160
|
+
readonly body: string;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* True when `directive` is the directive `name` (`trust:accept`): its body is `name` alone or `name`
|
|
164
|
+
* followed by whitespace and a reason, so `trust:accepted` is a typo of it, not it.
|
|
165
|
+
*/
|
|
166
|
+
declare function isNamedDirective(directive: TrustDirective, name: string): boolean;
|
|
167
|
+
/** The text after the directive name `name`, trimmed: empty when there is no reason. */
|
|
168
|
+
declare function directiveReason(directive: TrustDirective, name: string): string;
|
|
169
|
+
/**
|
|
170
|
+
* Every directive of `prefix` (`ioc` for `//ioc:…`) in the file, in source order, found exactly as
|
|
171
|
+
* trustDirectivesIn finds trust's own: line and block comments alike, so a caller can report the
|
|
172
|
+
* block ones.
|
|
173
|
+
*/
|
|
174
|
+
declare function lineDirectivesIn(ts: TypeScript, sourceFile: TS.SourceFile, prefix: string): TrustDirective[];
|
|
175
|
+
/**
|
|
176
|
+
* The directive directly above `node`: the last comment before it is a trust directive, on the line
|
|
177
|
+
* directly above its first token (after any JSDoc, never with a blank line between). Else null.
|
|
178
|
+
*/
|
|
179
|
+
declare function directiveDirectlyAbove(ts: TypeScript, node: TS.Node, prefix?: string): TrustDirective | null;
|
|
180
|
+
/**
|
|
181
|
+
* True when the function `fn` (a function declaration, a method, or an arrow / function expression
|
|
182
|
+
* assigned to a `const`) is marked `//trust:validator_function`. A call into such a function is the
|
|
183
|
+
* sanctioned way out of `unknown`: its return type is trusted.
|
|
184
|
+
*/
|
|
185
|
+
declare function isMarkedValidator(ts: TypeScript, fn: TS.Node): boolean;
|
|
186
|
+
/**
|
|
187
|
+
* The validator recogniser the rules use: `node` (a claim: a cast, `x!`, an `any`, a type predicate, a
|
|
188
|
+
* generic call) is inside a validator when it, or any function enclosing it, is a marked validator.
|
|
189
|
+
*/
|
|
190
|
+
declare function isInsideValidator(ts: TypeScript, node: TS.Node): boolean;
|
|
191
|
+
/** The outermost node whose first token is the first one after `directive` (the node it sits above), else undefined. */
|
|
192
|
+
declare function nodeBelow(ts: TypeScript, sourceFile: TS.SourceFile, directive: TrustDirective): TS.Node | undefined;
|
|
193
|
+
|
|
194
|
+
declare const UNTRUSTED_CALL_RULE = "untrusted-call-must-return-result";
|
|
195
|
+
declare const THROW_RULE = "throw-must-return-result";
|
|
196
|
+
type CatchProblem = 'rethrow' | 'notResultErr' | 'rawCatchValue' | 'notAllPaths';
|
|
197
|
+
declare const THROW_MESSAGES: {
|
|
198
|
+
readonly escapes: "`throw` must be inside a `try` (same function) whose `catch` returns Result.err(...), or inside Trust.try/tryAsync.";
|
|
199
|
+
readonly rethrow: string;
|
|
200
|
+
readonly notResultErr: string;
|
|
201
|
+
readonly rawCatchValue: string;
|
|
202
|
+
readonly notAllPaths: string;
|
|
203
|
+
};
|
|
204
|
+
declare const UNTRUSTED_CALL_MESSAGES: {
|
|
205
|
+
readonly unguarded: "Call into untrusted \"{{origin}}\" must be inside a `try` (same function) whose `catch` returns Result.err(...), or inside Trust.try/tryAsync. If \"{{origin}}\" cannot fail, trust it in trust.config.json.";
|
|
206
|
+
readonly notAwaited: "Async call into untrusted \"{{origin}}\" must be awaited inside the guard, or its rejection escapes the catch.";
|
|
207
|
+
readonly callsIgnored: "Call into \"{{origin}}\" is trusted only because its file is ignored. List that file under \"passthrough\" instead of \"ignore\" so calls into it must be handled.";
|
|
208
|
+
readonly rethrow: string;
|
|
209
|
+
readonly notResultErr: string;
|
|
210
|
+
readonly rawCatchValue: string;
|
|
211
|
+
readonly notAllPaths: string;
|
|
212
|
+
};
|
|
213
|
+
declare const TYPE_CLAIM_RULE = "type-claim";
|
|
214
|
+
/**
|
|
215
|
+
* Keyed by origin: the baseline key, and the ESLint messageId of `trust/type-claim`. The five `claim:*`
|
|
216
|
+
* origins name the kind of claim; `unanalyzable` is a node the analyzer could not type (reported, never
|
|
217
|
+
* passed); `directive` is a `//trust:` comment that marks nothing (a misspelled or misplaced
|
|
218
|
+
* `//trust:validator_function`, see core/validator.ts; a misplaced `//trust:accept` is reported by the
|
|
219
|
+
* throw rule, see ACCEPT_DIRECTIVE_MESSAGES).
|
|
220
|
+
*/
|
|
221
|
+
declare const TYPE_CLAIM_MESSAGES: {
|
|
222
|
+
readonly 'claim:as': "Type assertion claims \"{{from}}\" is \"{{to}}\", but \"{{from}}\" is not assignable to \"{{to}}\": nothing proves it. Narrow or validate the value instead.";
|
|
223
|
+
readonly 'claim:non-null': "Non-null assertion `!` claims \"{{from}}\" is never null or undefined: nothing proves it. Check for the missing value instead.";
|
|
224
|
+
readonly 'claim:any': "{{detail}}: `any` turns type checking off. Use `unknown` and narrow or validate it.";
|
|
225
|
+
readonly 'claim:predicate': "Type predicate \"{{predicate}}\" is a claim: the compiler does not check that the function body proves it.";
|
|
226
|
+
readonly 'claim:generic-return': "Call picks its own return type: type parameter \"{{parameter}}\" of \"{{callee}}\" appears only in the return type, so \"{{chosen}}\" is claimed, not proven. Validate the returned value.";
|
|
227
|
+
readonly unanalyzable: "Cannot analyze {{what}}: {{reason}}. What cannot be analyzed is reported, never passed.";
|
|
228
|
+
readonly directive: "Trust directive \"{{text}}\" {{problem}}: it marks nothing. A validator is marked by `//trust:validator_function` on the line directly above its function declaration, method, or `const` arrow/function expression; an accepted failure path by `//trust:accept <reason>` on the line directly above its statement.";
|
|
229
|
+
};
|
|
230
|
+
/**
|
|
231
|
+
* The `directive` finding of throw-must-return-result (core/accept.ts), keyed by ESLint messageId (origin
|
|
232
|
+
* `directive`): a `//trust:accept` that accepts nothing.
|
|
233
|
+
*/
|
|
234
|
+
declare const ACCEPT_DIRECTIVE_MESSAGES: {
|
|
235
|
+
readonly directive: "Trust directive \"{{text}}\" {{problem}}: it accepts nothing. A failure path is accepted by `//trust:accept <reason>` on the line directly above the statement that throws, calls or holds the promise (not above its function), and only that statement's findings are accepted.";
|
|
236
|
+
};
|
|
237
|
+
type TypeClaimOrigin = keyof typeof TYPE_CLAIM_MESSAGES;
|
|
238
|
+
/** The origins that name a claim kind (every type-claim origin except `unanalyzable` and `directive`). */
|
|
239
|
+
declare const TYPE_CLAIM_KINDS: readonly ["claim:as", "claim:non-null", "claim:any", "claim:predicate", "claim:generic-return"];
|
|
240
|
+
/** Origin of a node the type-claim analyzer could not type. */
|
|
241
|
+
declare const UNANALYZABLE_ORIGIN = "unanalyzable";
|
|
242
|
+
/** Origin of a `//trust:` comment that marks nothing. */
|
|
243
|
+
declare const DIRECTIVE_ORIGIN = "directive";
|
|
244
|
+
declare const UNTRUSTED_VALUE_RULE = "untrusted-value";
|
|
245
|
+
/**
|
|
246
|
+
* How an untrusted value entered the checked code (core/untrusted-values.ts):
|
|
247
|
+
* return returned by a call / `new` into an origin that is not type-trusted
|
|
248
|
+
* generic-return returned by a call that picked its own return type (a type parameter found only
|
|
249
|
+
* in the return position), whatever the origin
|
|
250
|
+
* parameter a parameter of a callback whose signature is declared by an origin that is not
|
|
251
|
+
* type-trusted: the outside calls it, with whatever it has
|
|
252
|
+
* read a property or a global declared by an origin that is not type-trusted
|
|
253
|
+
* catch a `catch` variable: anything can be thrown
|
|
254
|
+
* guard a value narrowed by a type guard or assertion function (`x is T`, `asserts x is T`,
|
|
255
|
+
* `asserts x`) whose signature is declared by an origin that is not type-trusted: the
|
|
256
|
+
* narrowed type is that origin's claim (AJV's `ValidateFunction<T>`)
|
|
257
|
+
*/
|
|
258
|
+
type UntrustedEntry = 'return' | 'generic-return' | 'parameter' | 'read' | 'catch' | 'guard';
|
|
259
|
+
/** Origin of a `catch` variable: no declaration says what is thrown. */
|
|
260
|
+
declare const CATCH_ORIGIN = "catch";
|
|
261
|
+
/**
|
|
262
|
+
* The messages of `untrusted-value`, keyed by ESLint messageId. `{{origin}}` is the baseline key;
|
|
263
|
+
* `{{entry}}` is the entry's label, `{{use}}` what the code does with the value and `{{type}}` the type
|
|
264
|
+
* it is declared to have. `callerChosen` is the message of a `generic-return` value: no type-trust entry
|
|
265
|
+
* proves a type the caller picked, so it does not suggest one. `handoff` is a function checked code hands
|
|
266
|
+
* to an origin that is not type-trusted (`untrustedCallbacks: "all"`): `{{callback}}` names the function,
|
|
267
|
+
* `{{parameter}}` the parameter that claims a type and `{{type}}` that type.
|
|
268
|
+
*/
|
|
269
|
+
declare const UNTRUSTED_VALUE_MESSAGES: {
|
|
270
|
+
readonly untrusted: "Untrusted value {{entry}} \"{{origin}}\" is {{use}}: its type \"{{type}}\" is declared, not proven. Pass it to a validator, or keep it as `unknown` and narrow it (typeof, in, Array.isArray). If \"{{origin}}\" declares true types, add it to \"trust_type\" in trust.config.json.";
|
|
271
|
+
readonly callerChosen: "Untrusted value {{entry}} \"{{origin}}\" is {{use}}: its type \"{{type}}\" was picked by the call, not proven, and no type trust proves it. Pass it to a validator, or keep it as `unknown` and narrow it (typeof, in, Array.isArray).";
|
|
272
|
+
readonly handoff: "\"{{callback}}\" receives data from \"{{origin}}\" but declares its parameter \"{{parameter}}\" as \"{{type}}\", which nothing proves. Declare the parameter `unknown` and validate it, or, if \"{{origin}}\" declares true types, add it to \"trust_type\" in trust.config.json.";
|
|
273
|
+
};
|
|
274
|
+
declare const DROPPED_RESULT_RULE = "dropped-result";
|
|
275
|
+
/**
|
|
276
|
+
* The messages of `dropped-result` (core/dropped-results.ts), keyed by origin: the baseline key, and the
|
|
277
|
+
* ESLint messageId of `trust/dropped-result`. `{{subject}}` is the variable or expression whose failure is
|
|
278
|
+
* dropped (for `callback`, the callee the function is handed to); `{{kinds}}` lists the failure kinds still
|
|
279
|
+
* possible there.
|
|
280
|
+
*/
|
|
281
|
+
declare const DROPPED_RESULT_MESSAGES: {
|
|
282
|
+
readonly discarded: "`{{subject}}` can fail with {{kinds}}, but its Result is not kept, so the failure is dropped. Return it, or handle it with Trust.decide.";
|
|
283
|
+
readonly argument: "`{{subject}}` can fail with {{kinds}}, but it is passed where no Result is expected, so the failure is dropped. Keep it in a variable, then return it or handle it with Trust.decide.";
|
|
284
|
+
readonly stored: "`{{subject}}` can fail with {{kinds}}, but it is stored where failures are not followed, so the failure is dropped. Return it or handle it with Trust.decide first, and store the value.";
|
|
285
|
+
readonly callback: "The function passed to `{{subject}}` returns a Result that can fail with {{kinds}}, but `{{subject}}` takes no Result back, so the failure is dropped. Handle it with Trust.decide inside the function.";
|
|
286
|
+
readonly return: "This return drops `{{subject}}`, which can still fail with {{kinds}}. Return the failure (`if (!{{subject}}.ok) return {{subject}};`), or handle it with Trust.decide.";
|
|
287
|
+
readonly end: "`{{subject}}` can still fail with {{kinds}} when it goes out of scope here, so the failure is dropped. Return it, or handle it with Trust.decide.";
|
|
288
|
+
readonly overwritten: "`{{subject}}` is assigned again while it can still fail with {{kinds}}, so the failure is dropped. Return it, or handle it with Trust.decide first.";
|
|
289
|
+
};
|
|
290
|
+
type DroppedResultOrigin = keyof typeof DROPPED_RESULT_MESSAGES;
|
|
291
|
+
declare const REDUNDANT_GUARD_RULE = "redundant-guard";
|
|
292
|
+
/** Origin label of every redundant-guard finding (baseline key). */
|
|
293
|
+
declare const REDUNDANT_GUARD_ORIGIN = "redundant";
|
|
294
|
+
/**
|
|
295
|
+
* The message of `redundant-guard` (core/redundant-guards.ts). `{{guard}}` is `Trust.try`, `Trust.tryAsync` or
|
|
296
|
+
* `try`; `{{calls}}` says what is called inside.
|
|
297
|
+
*/
|
|
298
|
+
declare const REDUNDANT_GUARD_MESSAGES: {
|
|
299
|
+
readonly redundant: "`{{guard}}` guards nothing that can fail: {{calls}}. It invents a failure path callers must unwrap for nothing. Call it directly and return its value; a trusted origin's failure is a programmer error, not a failure path. If the call can fail, remove its origin from \"trust\" in trust.config.json instead.";
|
|
300
|
+
};
|
|
301
|
+
/** One trust-rule violation. `line`/`column` are 1-based; `file` is relative to the trust root when inside it. */
|
|
302
|
+
interface Finding {
|
|
303
|
+
readonly file: string;
|
|
304
|
+
readonly rule: string;
|
|
305
|
+
readonly origin: string;
|
|
306
|
+
readonly line: number;
|
|
307
|
+
readonly column: number;
|
|
308
|
+
readonly message: string;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/** What a baseline counts a finding by. */
|
|
312
|
+
type BaselineFinding = Pick<Finding, 'file' | 'rule' | 'origin'>;
|
|
313
|
+
/** file → rule → origin → count */
|
|
314
|
+
type BaselineCounts = Record<string, Record<string, Record<string, number>>>;
|
|
315
|
+
interface BaselineDelta<F extends BaselineFinding = Finding> {
|
|
316
|
+
readonly file: string;
|
|
317
|
+
readonly rule: string;
|
|
318
|
+
readonly origin: string;
|
|
319
|
+
readonly allowed: number;
|
|
320
|
+
readonly found: number;
|
|
321
|
+
readonly findings: readonly F[];
|
|
322
|
+
}
|
|
323
|
+
declare function countFindings(findings: readonly BaselineFinding[]): BaselineCounts;
|
|
324
|
+
/**
|
|
325
|
+
* Which baseline entries a run speaks for: `all` (a run over the whole tree: an entry with no
|
|
326
|
+
* findings now is stale, and --update drops it), or only the entries of the files it checked
|
|
327
|
+
* (baseline keys); entries of other files are neither stale nor rewritten.
|
|
328
|
+
*/
|
|
329
|
+
type BaselineScope = {
|
|
330
|
+
readonly kind: 'all';
|
|
331
|
+
} | {
|
|
332
|
+
readonly kind: 'files';
|
|
333
|
+
readonly files: ReadonlySet<string>;
|
|
334
|
+
};
|
|
335
|
+
declare const WHOLE_BASELINE: BaselineScope;
|
|
336
|
+
/** The baseline after `--update`: in-scope files get their current counts, out-of-scope entries are kept as they are. */
|
|
337
|
+
declare function updateBaseline(baseline: BaselineCounts, findings: readonly BaselineFinding[], scope: BaselineScope): {
|
|
338
|
+
counts: BaselineCounts;
|
|
339
|
+
kept: number;
|
|
340
|
+
};
|
|
341
|
+
declare function compareToBaseline<F extends BaselineFinding = Finding>(findings: readonly F[], baseline: BaselineCounts, scope?: BaselineScope): {
|
|
342
|
+
readonly added: BaselineDelta<F>[];
|
|
343
|
+
readonly stale: BaselineDelta<F>[];
|
|
344
|
+
};
|
|
345
|
+
/** The baseline file's text; `comment` (another tool's own) replaces trust's `$comment`. */
|
|
346
|
+
declare function serializeBaseline(counts: BaselineCounts, comment?: string): string;
|
|
347
|
+
/** Throws (with `source` in the message) on invalid JSON or an unexpected shape. */
|
|
348
|
+
declare function parseBaseline(text: string, source: string): BaselineCounts;
|
|
349
|
+
/** The baseline's counts (none when the file does not exist), or why it could not be read. */
|
|
350
|
+
declare function readBaseline(baselineFile: string): {
|
|
351
|
+
counts: BaselineCounts;
|
|
352
|
+
} | {
|
|
353
|
+
error: string;
|
|
354
|
+
};
|
|
355
|
+
/** A delta as `trust baseline` prints it: a header line, then one indented line per finding. */
|
|
356
|
+
declare function describeBaselineDelta(delta: BaselineDelta<BaselineFinding & {
|
|
357
|
+
readonly line: number;
|
|
358
|
+
readonly column: number;
|
|
359
|
+
readonly message: string;
|
|
360
|
+
}>): string[];
|
|
361
|
+
|
|
362
|
+
export { TYPE_CLAIM_KINDS as $, updateBaseline as A, type BaselineCounts as B, type TrustRuleSettings as C, type TrustConfig as D, type OriginInfo as E, type Finding as F, type CatchProblem as G, ACCEPT_DIRECTIVE as H, ACCEPT_DIRECTIVE_MESSAGES as I, CATCH_ORIGIN as J, DEFAULT_RULE_SETTINGS as K, DIRECTIVE_ORIGIN as L, DROPPED_RESULT_MESSAGES as M, DROPPED_RESULT_RULE as N, OriginResolver as O, type DroppedResultOrigin as P, type LoadTrustConfigOptions as Q, type OptInRule as R, REDUNDANT_GUARD_MESSAGES as S, type TypeScript as T, REDUNDANT_GUARD_ORIGIN as U, REDUNDANT_GUARD_RULE as V, WHOLE_BASELINE as W, type RuleSwitch as X, THROW_MESSAGES as Y, type ZoneGroup as Z, THROW_RULE as _, type TsconfigMapping as a, TYPE_CLAIM_MESSAGES as a0, TYPE_CLAIM_RULE as a1, TrustConfigError as a2, type TrustEntry as a3, type TrustLevel as a4, type TypeClaimOrigin as a5, UNANALYZABLE_ORIGIN as a6, UNTRUSTED_CALL_MESSAGES as a7, UNTRUSTED_CALL_RULE as a8, UNTRUSTED_VALUE_MESSAGES as a9, UNTRUSTED_VALUE_RULE as aa, type UntrustedCallbacks as ab, type UntrustedEntry as ac, VALIDATOR_DIRECTIVE as ad, effectiveTrustList as ae, effectiveTypeTrustList as af, isInsideValidator as ag, isMarkedValidator as ah, isRuleEnabled as ai, loadTrustConfig as aj, normalizeOrigin as ak, type BaselineDelta as b, type BaselineFinding as c, type BaselineScope as d, type TrustDirective as e, type Zone as f, Zones as g, compareToBaseline as h, countFindings as i, describeBaselineDelta as j, directiveDirectlyAbove as k, directiveReason as l, groupMatches as m, isNamedDirective as n, lineDirectivesIn as o, loadTypeScript as p, matchesPatterns as q, nearestPackageName as r, nodeBelow as s, normalizePattern as t, parseBaseline as u, readBaseline as v, realpathOrSelf as w, relativeInside as x, serializeBaseline as y, toPosix as z };
|