@noego/trust 0.5.0-dev.2 → 0.5.0-dev.4
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 +87 -3
- package/dist/{baseline-Bkav9mS0.d.ts → baseline-DQGyHwig.d.ts} +35 -2
- package/dist/{chunk-UG6D3V4M.js → chunk-6YBPW4NP.js} +4680 -4604
- package/dist/chunk-6YBPW4NP.js.map +1 -0
- package/dist/{chunk-7PY2Q6OX.js → chunk-LJJDRFO7.js} +233 -3
- package/dist/chunk-LJJDRFO7.js.map +1 -0
- package/dist/{chunk-XXLWC5DB.js → chunk-TQWRH47T.js} +2 -2
- package/dist/cli/index.js +54 -11
- package/dist/cli/index.js.map +1 -1
- package/dist/core/index.d.ts +2 -2
- package/dist/core/index.js +2 -2
- package/dist/eslint/index.d.ts +3 -2
- package/dist/eslint/index.js +58 -17
- package/dist/eslint/index.js.map +1 -1
- package/dist/native/trust_native_wasm.wasm +0 -0
- package/package.json +4 -6
- package/dist/chunk-7PY2Q6OX.js.map +0 -1
- package/dist/chunk-UG6D3V4M.js.map +0 -1
- /package/dist/{chunk-XXLWC5DB.js.map → chunk-TQWRH47T.js.map} +0 -0
package/README.md
CHANGED
|
@@ -231,6 +231,12 @@ For both forms:
|
|
|
231
231
|
- Throwing at the edge is the exception, not the rule: when an API's contract is exceptions, the edge
|
|
232
232
|
turns the decided failure into one, under `//trust:accept <reason>`.
|
|
233
233
|
|
|
234
|
+
The lint holds the edge to this. Name the edge files in trust.config.json (`boundaries`: controllers, a
|
|
235
|
+
job's `main`, the public entry of a library), and `boundary-result` reports every exported function and
|
|
236
|
+
public member there whose return value can still fail, including `Promise<Result<…>>` and `Result[]`
|
|
237
|
+
(see [`boundary-result`](#boundary-result-a-result-does-not-cross-the-edge)). A boundary that is allowed
|
|
238
|
+
to hand a `Result` on (an internal API of the application) is left out by name in the item's `exclude`.
|
|
239
|
+
|
|
234
240
|
### Only real failure points return `Result`
|
|
235
241
|
|
|
236
242
|
A `Result` is a promise to the caller that something can go wrong at runtime. Code that cannot fail
|
|
@@ -411,6 +417,10 @@ export default [
|
|
|
411
417
|
"passthrough": ["server/repositories/**"],
|
|
412
418
|
"ignore": ["**/*.test.ts", "server/testing/**"],
|
|
413
419
|
"strict": ["server/services/workspace/**", "server/controller/workspace.controller.ts"],
|
|
420
|
+
"boundaries": [
|
|
421
|
+
{ "files": ["server/admin/**/*.controller.ts"], "exclude": ["UserController.get_user"] },
|
|
422
|
+
{ "files": ["server/public/**/*.controller.ts"], "exclude": [".health"] }
|
|
423
|
+
],
|
|
414
424
|
"tsconfig": [{ "files": "ui/**", "tsconfig": "tsconfig.web.json" }]
|
|
415
425
|
}
|
|
416
426
|
```
|
|
@@ -440,7 +450,20 @@ export default [
|
|
|
440
450
|
(`callsIgnored`) because ignoring alone silently trusts.
|
|
441
451
|
- `strict` (`trust check` only): globs of files that are always checked under the strict rules, with or without
|
|
442
452
|
the `--strict` flag. Use it to hold finished parts of the tree to the strict standard. `!negation` carves files
|
|
443
|
-
back out; `ignore` still wins. `trust baseline` and ESLint ignore this key
|
|
453
|
+
back out; `ignore` still wins. `trust baseline` and ESLint ignore this key (except that `boundary-result` reports
|
|
454
|
+
an unproven boundary return as an error, not a warning, in a file the globs match).
|
|
455
|
+
- `boundaries`: the files at the edge of the program, as a list of items `{ "files": <glob or globs>, "exclude":
|
|
456
|
+
[names] }` (`exclude` optional). Having the key turns the [`boundary-result`](#boundary-result-a-result-does-not-cross-the-edge)
|
|
457
|
+
rule on: every exported function and public member of a matched file is a boundary, and one whose return
|
|
458
|
+
value can fail is reported. An `exclude` name applies to that item's files only: `"UserController.get_user"`
|
|
459
|
+
(that member of every exported class with that name in the item's files), `"UserController.*"` (every public
|
|
460
|
+
member of every exported class or object with that name there, members added later included; never a
|
|
461
|
+
function), `".get_user"` (that member of any exported class or object there), `"get_user"` (an exported
|
|
462
|
+
function). `*` stands only for the whole member part after a class name: `".*"`, `"User*.get"`, `"X.get*"`
|
|
463
|
+
and a bare `"*"` are config errors. A file two items match is an error, and so is an `exclude` name that
|
|
464
|
+
matches nothing in its item's files; split the items (or the configs) to tell same-named classes apart.
|
|
465
|
+
Items of every file in the `extend` chain are kept, each relative to its own directory; there is no `rules`
|
|
466
|
+
switch for this rule.
|
|
444
467
|
- `tsconfig` (CLI only): an ordered list of `{ "files": <glob or globs>, "tsconfig": <path> }`. The first entry
|
|
445
468
|
whose globs match a file picks the tsconfig its program is built from; the path is relative to the config
|
|
446
469
|
file's directory. `--tsconfig` overrides it, and files no entry matches use the nearest `tsconfig.json`. A file
|
|
@@ -536,8 +559,8 @@ It needs neither ESLint nor an installed TypeScript package. TypeScript 5.9.3 st
|
|
|
536
559
|
are copied and embedded when the engine is built; they are not chosen from the checked project at runtime.
|
|
537
560
|
The experimental `--rs` and `--go` flags have been removed.
|
|
538
561
|
|
|
539
|
-
Every rule, including the opt-in `type-claim`, `untrusted-value`, `dropped-result` and `redundant-guard`,
|
|
540
|
-
runs in the engine. The TypeScript implementation in `src/core` stays the reference: differential tests
|
|
562
|
+
Every rule, including the opt-in `type-claim`, `untrusted-value`, `dropped-result` and `redundant-guard`, and
|
|
563
|
+
`boundary-result` (on when the config names `boundaries`), runs in the engine. The TypeScript implementation in `src/core` stays the reference: differential tests
|
|
541
564
|
(`test/native-check.test.ts`, `test/native-opt-in.test.ts`) run the fixtures and the shared rule-case corpus
|
|
542
565
|
through both and compare whole findings (file, position, rule, message, severity). Two things keep the
|
|
543
566
|
output independent of the compiler: type text in messages is printed in a canonical member order
|
|
@@ -1002,6 +1025,67 @@ async instance<T>(token: new () => T) {
|
|
|
1002
1025
|
Fix it by calling directly and returning the value. If the call really can fail, the trust entry is wrong: remove the
|
|
1003
1026
|
origin from `trust`, and the guard becomes required again.
|
|
1004
1027
|
|
|
1028
|
+
### `boundary-result`: a Result does not cross the edge
|
|
1029
|
+
|
|
1030
|
+
`Result` is an internal contract; the edge of the program decides every kind that is left and returns plain data
|
|
1031
|
+
(see [The edge decides everything that is left](#the-edge-decides-everything-that-is-left)). `boundary-result`
|
|
1032
|
+
holds the edge to that. It is on as soon as trust.config.json names the edge files under `boundaries`
|
|
1033
|
+
(`trust check`, `trust baseline` and the ESLint rule `trust/boundary-result` read the same key):
|
|
1034
|
+
|
|
1035
|
+
```json
|
|
1036
|
+
"boundaries": [
|
|
1037
|
+
{ "files": ["server/admin/**/*.controller.ts"], "exclude": ["UserController.get_user"] },
|
|
1038
|
+
{ "files": ["server/public/**/*.controller.ts"], "exclude": [".health"] },
|
|
1039
|
+
{ "files": ["src/index.ts"] }
|
|
1040
|
+
]
|
|
1041
|
+
```
|
|
1042
|
+
|
|
1043
|
+
Every exported function and public member of a matched file is a **boundary**: an `export function`, an exported
|
|
1044
|
+
`const` function, every public instance or static method, getter and function-valued property of an exported
|
|
1045
|
+
class (also `export default class`, as controllers are written), the function-valued properties and getters of an
|
|
1046
|
+
exported object, and what a barrel re-exports (`export { a } from './a'`, `export *`), reported at the export
|
|
1047
|
+
statement. Not boundaries: `private`, `protected` and `#private` members, inherited members, type-only exports,
|
|
1048
|
+
and exported values that are not functions. A boundary **can fail** when its awaited return type has an `Err`
|
|
1049
|
+
member from `@noego/trust`, one level into an array or tuple (the `dropped-result` definition), so a
|
|
1050
|
+
`Promise<Result<…>>` method and a `Result[]` return are reported. The origin is the baseline key:
|
|
1051
|
+
|
|
1052
|
+
| Origin | What is reported | Severity |
|
|
1053
|
+
|---|---|---|
|
|
1054
|
+
| `returns-result` | a boundary whose return value can fail, with the kinds it can carry | error |
|
|
1055
|
+
| `unproven-return` | a boundary whose return type is `any` or `unknown`: nothing shows it is free of a `Result` | warning; an error under `--strict` or in a file the `strict` globs match |
|
|
1056
|
+
| `stale-exclude` | an `exclude` name that matches no boundary in its item's files, like a stale `//trust:accept` (reported against the config file, once per run) | error |
|
|
1057
|
+
| `overlapping-items` | a file two items match; its boundaries are not checked until the globs are split | error |
|
|
1058
|
+
|
|
1059
|
+
```ts
|
|
1060
|
+
// server/admin/user.controller.ts, a boundary file
|
|
1061
|
+
export default class UserController {
|
|
1062
|
+
async get(id: number) {
|
|
1063
|
+
return this.users.find(id);
|
|
1064
|
+
// boundary-result (returns-result): Boundary "UserController.get" returns a Result that can fail with "NotFound"…
|
|
1065
|
+
}
|
|
1066
|
+
}
|
|
1067
|
+
```
|
|
1068
|
+
|
|
1069
|
+
Fix it by deciding every kind in the boundary (an exhaustive `switch` with a `never` default) and returning plain
|
|
1070
|
+
data. A boundary that is meant to hand its `Result` on, say an internal API another service consumes, is left out by
|
|
1071
|
+
name in the item's `exclude`: `"UserController.get_user"` names that member of every exported class with that
|
|
1072
|
+
declared name in the item's files (a shared class name applies to all of them, on purpose), `"UserController.*"`
|
|
1073
|
+
every public member of every exported class or object with that declared name there (a whole internal API: a
|
|
1074
|
+
method added to the class later is covered too, so the list need not grow with the class), `".get_user"` names
|
|
1075
|
+
that member of any exported class or object there, and `"get_user"` an exported function. A plain name never means
|
|
1076
|
+
a class and `"UserController.*"` never means a function: one entry says one thing. `*` stands only for the whole
|
|
1077
|
+
member part after a class name: `".*"` (every member of everything in the item) is refused when the config loads,
|
|
1078
|
+
as are `"User*.get"`, `"X.get*"` and a bare `"*"`. Names use `.`, as origins and call graphs do (`Store.load`); there
|
|
1079
|
+
is no file-qualified form. To tell two same-named classes apart, put their files in separate items. An `exclude`
|
|
1080
|
+
name applies to its own item only, and `"UserController.*"` is stale, like any other entry, when no exported class
|
|
1081
|
+
or object of that name is in the item's files.
|
|
1082
|
+
|
|
1083
|
+
The stale check needs the whole item: it is decided while checking the first of the item's files, and only when
|
|
1084
|
+
every file the item's globs match on disk is in the program, so `trust check server/admin/one.controller.ts` never
|
|
1085
|
+
calls an entry stale for a file it did not load. `trust explain <file>:<line>` lists every boundary starting on the
|
|
1086
|
+
line, the item it belongs to, the `exclude` name that leaves it out, and what its return value says. `//trust:accept`
|
|
1087
|
+
does not accept a boundary-result finding; `exclude` is the way out.
|
|
1088
|
+
|
|
1005
1089
|
### `trust refactor`: the order to refactor in
|
|
1006
1090
|
|
|
1007
1091
|
```sh
|
|
@@ -66,6 +66,8 @@ interface TrustConfig {
|
|
|
66
66
|
readonly ignore: readonly ZoneGroup[];
|
|
67
67
|
/** `strict` globs of the chain: `trust check` also runs the strict rules on files matching them. */
|
|
68
68
|
readonly strict: readonly ZoneGroup[];
|
|
69
|
+
/** `boundaries` items of the chain, leaf first, in declaration order; empty when no level sets the key (rule off). */
|
|
70
|
+
readonly boundaries: readonly BoundaryGroup[];
|
|
69
71
|
/** `tsconfig` entries of the chain, leaf first, in declaration order. */
|
|
70
72
|
readonly tsconfig: readonly TsconfigMapping[];
|
|
71
73
|
/** Per-rule settings (`rules`), each resolved along the chain; unset keys take DEFAULT_RULE_SETTINGS. */
|
|
@@ -100,6 +102,15 @@ interface TsconfigMapping extends ZoneGroup {
|
|
|
100
102
|
/** Absolute tsconfig path. Its existence is checked when a file maps to it, not at load. */
|
|
101
103
|
readonly tsconfig: string;
|
|
102
104
|
}
|
|
105
|
+
/**
|
|
106
|
+
* One `boundaries` item: files matching `patterns` (zone glob semantics) are boundary files, and the
|
|
107
|
+
* `exclude` names leave members of those files out (`Class.member`, `Class.*`, `.member`, `function`).
|
|
108
|
+
*/
|
|
109
|
+
interface BoundaryGroup extends ZoneGroup {
|
|
110
|
+
/** Position in the declaring file's `boundaries` array (for messages). */
|
|
111
|
+
readonly index: number;
|
|
112
|
+
readonly exclude: readonly string[];
|
|
113
|
+
}
|
|
103
114
|
/**
|
|
104
115
|
* What to do with a glob that matches no file: `'report'` lists it in `TrustConfig.unmatchedGlobs`
|
|
105
116
|
* and loads anyway, `true` makes it a load error (TrustConfigError), `false` does not check.
|
|
@@ -316,7 +327,28 @@ declare const REDUNDANT_GUARD_ORIGIN = "redundant";
|
|
|
316
327
|
declare const REDUNDANT_GUARD_MESSAGES: {
|
|
317
328
|
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.";
|
|
318
329
|
};
|
|
319
|
-
|
|
330
|
+
declare const BOUNDARY_RULE = "boundary-result";
|
|
331
|
+
/**
|
|
332
|
+
* The messages of `boundary-result` (core/boundaries.ts), keyed by origin: the baseline key, and the ESLint
|
|
333
|
+
* messageId of `trust/boundary-result`. `{{member}}` is the boundary (`Class.member`, `api.get`, `fn`), `{{item}}`
|
|
334
|
+
* the `boundaries` item it belongs to (`boundaries[0] in trust.config.json`), `{{kinds}}` the failure kinds its
|
|
335
|
+
* Result can carry, `{{type}}` `any` or `unknown`, `{{entry}}` an `exclude` name and `{{other}}` a second item.
|
|
336
|
+
* returns-result an error: the boundary's return value can fail
|
|
337
|
+
* unproven-return a warning (an error under strict): the return type is `any` / `unknown`, so nothing shows it is free of a Result
|
|
338
|
+
* stale-exclude an error, reported against the config file: an `exclude` entry that names no boundary of its item's files
|
|
339
|
+
* overlapping-items an error at the file's start: two items match the same file, so its boundaries are not checked
|
|
340
|
+
*/
|
|
341
|
+
declare const BOUNDARY_MESSAGES: {
|
|
342
|
+
readonly 'returns-result': "Boundary \"{{member}}\" returns a Result that can fail with {{kinds}}: a Result must not cross the edge. Decide every kind here (an exhaustive `switch` with a `never` default) and return plain data, or leave it out by adding \"{{member}}\" to \"exclude\" of {{item}}.";
|
|
343
|
+
readonly 'unproven-return': "Boundary \"{{member}}\" returns `{{type}}`, which may hold a Result: nothing shows a failure does not cross the edge here. Return a type that is not `any` or `unknown`, or leave it out by adding \"{{member}}\" to \"exclude\" of {{item}}.";
|
|
344
|
+
readonly 'stale-exclude': "Boundary exclude \"{{entry}}\" of {{item}} matches no exported function, class member or object member in its files: it excludes nothing. Remove it, or fix the name (\"Class.member\", \"Class.*\", \".member\" or \"function\").";
|
|
345
|
+
readonly 'overlapping-items': "File \"{{file}}\" is a boundary of both {{item}} and {{other}}: a file belongs to one item. Split the globs (or the configs) so each file matches one item; its boundaries are not checked until then.";
|
|
346
|
+
};
|
|
347
|
+
type BoundaryOrigin = keyof typeof BOUNDARY_MESSAGES;
|
|
348
|
+
/**
|
|
349
|
+
* One trust-rule violation. `line`/`column` are 1-based; `file` is relative to the trust root when inside it.
|
|
350
|
+
* `severity` is set only by a rule that can warn (`boundary-result`'s `unproven-return`); absent means an error.
|
|
351
|
+
*/
|
|
320
352
|
interface Finding {
|
|
321
353
|
readonly file: string;
|
|
322
354
|
readonly rule: string;
|
|
@@ -324,6 +356,7 @@ interface Finding {
|
|
|
324
356
|
readonly line: number;
|
|
325
357
|
readonly column: number;
|
|
326
358
|
readonly message: string;
|
|
359
|
+
readonly severity?: 'error' | 'warning';
|
|
327
360
|
}
|
|
328
361
|
|
|
329
362
|
/** What a baseline counts a finding by. */
|
|
@@ -377,4 +410,4 @@ declare function describeBaselineDelta(delta: BaselineDelta<BaselineFinding & {
|
|
|
377
410
|
readonly message: string;
|
|
378
411
|
}>): string[];
|
|
379
412
|
|
|
380
|
-
export {
|
|
413
|
+
export { REDUNDANT_GUARD_RULE 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, BOUNDARY_MESSAGES as J, BOUNDARY_RULE as K, type BoundaryGroup as L, type BoundaryOrigin as M, CATCH_ORIGIN as N, OriginResolver as O, DEFAULT_RULE_SETTINGS as P, DIRECTIVE_ORIGIN as Q, DROPPED_RESULT_MESSAGES as R, DROPPED_RESULT_RULE as S, type TypeScript as T, type DroppedResultOrigin as U, type LoadTrustConfigOptions as V, WHOLE_BASELINE as W, type OptInRule as X, REDUNDANT_GUARD_MESSAGES as Y, type ZoneGroup as Z, REDUNDANT_GUARD_ORIGIN as _, type TsconfigMapping as a, type RuleSwitch as a0, THROW_MESSAGES as a1, THROW_RULE as a2, TYPE_CLAIM_KINDS as a3, TYPE_CLAIM_MESSAGES as a4, TYPE_CLAIM_RULE as a5, TrustConfigError as a6, type TrustEntry as a7, type TrustLevel as a8, type TypeClaimOrigin as a9, UNANALYZABLE_ORIGIN as aa, UNTRUSTED_CALL_MESSAGES as ab, UNTRUSTED_CALL_RULE as ac, UNTRUSTED_VALUE_MESSAGES as ad, UNTRUSTED_VALUE_RULE as ae, type UntrustedCallbacks as af, type UntrustedEntry as ag, VALIDATOR_DIRECTIVE as ah, effectiveTrustList as ai, effectiveTypeTrustList as aj, isInsideValidator as ak, isMarkedValidator as al, isRuleEnabled as am, loadTrustConfig as an, normalizeOrigin as ao, 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 };
|