@aoelite/refpact-ts 0.0.0-stage → 0.2.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.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +38 -2
  3. package/dist/baseline.d.ts +26 -0
  4. package/dist/baseline.js +65 -0
  5. package/dist/core/index.d.ts +88 -0
  6. package/dist/core/index.js +105 -0
  7. package/dist/core/model.d.ts +340 -0
  8. package/dist/core/model.js +1 -0
  9. package/dist/core/results.d.ts +268 -0
  10. package/dist/core/results.js +1 -0
  11. package/dist/core/wasm.d.ts +7 -0
  12. package/dist/core/wasm.js +67 -0
  13. package/dist/custom.d.ts +166 -0
  14. package/dist/custom.js +239 -0
  15. package/dist/filters.d.ts +73 -0
  16. package/dist/filters.js +39 -0
  17. package/dist/frontend/checks.d.ts +15 -0
  18. package/dist/frontend/checks.js +12 -0
  19. package/dist/frontend/classic.d.ts +3 -0
  20. package/dist/frontend/classic.js +105 -0
  21. package/dist/frontend/compiler.d.ts +93 -0
  22. package/dist/frontend/compiler.js +116 -0
  23. package/dist/frontend/components.d.ts +29 -0
  24. package/dist/frontend/components.js +111 -0
  25. package/dist/frontend/declarations.d.ts +45 -0
  26. package/dist/frontend/declarations.js +158 -0
  27. package/dist/frontend/dependencies.d.ts +53 -0
  28. package/dist/frontend/dependencies.js +337 -0
  29. package/dist/frontend/imports.d.ts +149 -0
  30. package/dist/frontend/imports.js +765 -0
  31. package/dist/frontend/native.d.ts +3 -0
  32. package/dist/frontend/native.js +165 -0
  33. package/dist/frontend/paths.d.ts +10 -0
  34. package/dist/frontend/paths.js +18 -0
  35. package/dist/frontend/project.d.ts +118 -0
  36. package/dist/frontend/project.js +775 -0
  37. package/dist/group.d.ts +74 -0
  38. package/dist/group.js +106 -0
  39. package/dist/index.d.ts +35 -0
  40. package/dist/index.js +27 -0
  41. package/dist/items.d.ts +133 -0
  42. package/dist/items.js +179 -0
  43. package/dist/layers.d.ts +112 -0
  44. package/dist/layers.js +215 -0
  45. package/dist/onion.d.ts +78 -0
  46. package/dist/onion.js +96 -0
  47. package/dist/patterns.d.ts +14 -0
  48. package/dist/patterns.js +15 -0
  49. package/dist/rules.d.ts +408 -0
  50. package/dist/rules.js +665 -0
  51. package/package.json +52 -4
  52. package/wasm/refpact_core.wasm +0 -0
@@ -0,0 +1,340 @@
1
+ /** A path: a non-empty list of non-empty segments (SPEC section 1). */
2
+ export type Path = readonly string[];
3
+ /** A raw pattern: segments that the core validates (SPEC section 2). */
4
+ export type RawPattern = readonly string[];
5
+ /** What a front end found in one project (SPEC section 3). */
6
+ export interface FactSet {
7
+ /** Text that separates segments when a path is printed. */
8
+ readonly separator: string;
9
+ /** Paths of all units. Rust: modules. TypeScript: files. */
10
+ readonly units: readonly Path[];
11
+ /** Paths of all known named things inside units. */
12
+ readonly items: readonly Path[];
13
+ /** The number of lines of each unit, in the order of `units`. Absent or empty for front ends that do not count them. */
14
+ readonly unitLines?: readonly number[];
15
+ /** All reference kinds the front end can produce. */
16
+ readonly kinds: readonly string[];
17
+ /** All markers the front end can produce. */
18
+ readonly markers: readonly string[];
19
+ /** All tags the front end can produce. */
20
+ readonly tags: readonly string[];
21
+ /** The facts, in a stable order. */
22
+ readonly facts: readonly Fact[];
23
+ /** The named items that the units declare, in a stable order. Default: none. */
24
+ readonly declarations?: readonly Declaration[];
25
+ /** All item kinds the front end can produce. Default: none. */
26
+ readonly itemKinds?: readonly string[];
27
+ /** All visibilities the front end can produce. Default: none. */
28
+ readonly visibilities?: readonly string[];
29
+ /** All relations the front end can produce. Default: none. */
30
+ readonly relations?: readonly string[];
31
+ /** All modifiers of declarations the front end can produce. Default: none. */
32
+ readonly modifiers?: readonly string[];
33
+ /** The names of all properties of references the front end can produce. Default: none. */
34
+ readonly properties?: readonly string[];
35
+ /** Segments that reports print without a separator before them, by prefix. Default: none. */
36
+ readonly attachedPrefixes?: readonly string[];
37
+ /** Prefixes that reports leave out of the first segment of a path. Default: none. */
38
+ readonly hiddenPrefixes?: readonly string[];
39
+ }
40
+ /** One observation at one place in the source. */
41
+ export interface Fact {
42
+ /** The unit that contains the fact. */
43
+ readonly unit: Path;
44
+ /** The file, as the front end names it. */
45
+ readonly file: string;
46
+ /** The line in the file. */
47
+ readonly line: number;
48
+ /** The column in the line. */
49
+ readonly column: number;
50
+ /** The tags of the fact. */
51
+ readonly tags: readonly string[];
52
+ /** Text that is copied to the violation. */
53
+ readonly note?: string;
54
+ /**
55
+ * The path of the innermost declaration that contains the fact. Absent outside every
56
+ * declaration, and for front ends that do not record it.
57
+ */
58
+ readonly item?: Path;
59
+ /** What was observed. */
60
+ readonly what: Reference | Marker;
61
+ }
62
+ /** A named item that a unit declares, such as a type or a function (SPEC section 3). */
63
+ export interface Declaration {
64
+ /** The path of the item. */
65
+ readonly path: Path;
66
+ /** The name of the item as the code writes it. */
67
+ readonly name: string;
68
+ /** The unit that declares the item. */
69
+ readonly unit: Path;
70
+ /** The file, as the front end names it. */
71
+ readonly file: string;
72
+ /** The line of the name. */
73
+ readonly line: number;
74
+ /** The column of the name. */
75
+ readonly column: number;
76
+ /** The line on which the item ends. Absent for front ends that do not record it. */
77
+ readonly endLine?: number;
78
+ /** The tags of the declaration. */
79
+ readonly tags: readonly string[];
80
+ /** The kind of item, one of the item kinds of the fact set. */
81
+ readonly kind: string;
82
+ /** The visibility, one of the visibilities of the fact set. */
83
+ readonly visibility: string;
84
+ /** The paths that the item is tied to, such as the classes that it extends. */
85
+ readonly relations: readonly Relation[];
86
+ /**
87
+ * What the declaration says of the item besides its kind and its visibility, such as
88
+ * `async` or `documented`. Each is one of the modifiers of the fact set.
89
+ */
90
+ readonly modifiers: readonly string[];
91
+ }
92
+ /** A tie between a declared item and a path. */
93
+ export interface Relation {
94
+ /** The kind of tie, one of the relations of the fact set. */
95
+ readonly relation: string;
96
+ /** The path. */
97
+ readonly target: Path;
98
+ }
99
+ /** The unit refers to a path. */
100
+ export interface Reference {
101
+ /** Tells a reference from a marker. */
102
+ readonly type: "reference";
103
+ /** The path the code refers to, resolved as far as the front end can. */
104
+ readonly target: Path;
105
+ /** Further paths the same reference denotes, such as the definition behind a re-export. */
106
+ readonly aliases: readonly Path[];
107
+ /** The kind of the reference, one of the kinds of the fact set. */
108
+ readonly kind: string;
109
+ /** Whether the front end proved the path. */
110
+ readonly certainty: Certainty;
111
+ /**
112
+ * What the front end knows of the target besides its path, by name, such as the version
113
+ * of a package. No built-in rule reads them; a check of your own does.
114
+ */
115
+ readonly properties?: Readonly<Record<string, string>>;
116
+ }
117
+ /** The unit contains something that has a name but no path, such as an unsafe block. */
118
+ export interface Marker {
119
+ /** Tells a marker from a reference. */
120
+ readonly type: "marker";
121
+ /** The marker, one of the markers of the fact set. */
122
+ readonly marker: string;
123
+ }
124
+ /** `candidate`: the front end could not prove this path, for example a name behind a glob import. */
125
+ export type Certainty = "exact" | "candidate";
126
+ /** One architecture rule (SPEC section 4). */
127
+ export interface Rule {
128
+ /** The name, printed with every violation. An empty name is an error. */
129
+ readonly name: string;
130
+ /** Why the rule exists, printed with its violations. Default: no reason. */
131
+ readonly reason?: string;
132
+ /**
133
+ * `error`: a violation fails the check. `warning`: a violation is reported, and the check
134
+ * passes. It does not change the evaluation. Default: `error`.
135
+ */
136
+ readonly severity?: Severity;
137
+ /** The units the rule applies to. */
138
+ readonly subjects: Subjects;
139
+ /** What the units must do or must not do. */
140
+ readonly constraint: Constraint;
141
+ /** The reference kinds the rule looks at. Default: all kinds. */
142
+ readonly kinds?: KindFilter;
143
+ /** Facts with one of these tags are not checked. Default: none. */
144
+ readonly ignoreTags?: readonly string[];
145
+ /** Whether candidate references count. Default: `include`. */
146
+ readonly candidates?: Candidates;
147
+ /** References that the rule does not see. Default: none. */
148
+ readonly exemptions?: readonly Exemption[];
149
+ /**
150
+ * The names of the properties of references that the check of the rule reads. One that the
151
+ * front end does not produce is an error. Default: none.
152
+ */
153
+ readonly properties?: readonly string[];
154
+ }
155
+ /**
156
+ * References that a rule does not see (SPEC 4.13): those of the units that a `from` pattern
157
+ * matches exactly, with a path that a `to` pattern matches within.
158
+ */
159
+ export interface Exemption {
160
+ /** The units. An empty list is an error. */
161
+ readonly from: readonly RawPattern[];
162
+ /** The paths. An empty list is an error. */
163
+ readonly to: readonly RawPattern[];
164
+ }
165
+ /** Which units a rule applies to. */
166
+ export interface Subjects {
167
+ /** The units that are selected before the exceptions. */
168
+ readonly include: Include;
169
+ /** Absent: no exceptions. An empty list is an error. */
170
+ readonly except?: readonly RawPattern[];
171
+ }
172
+ /** The units a rule selects before its exceptions: all units, or those that a pattern matches exactly. */
173
+ export type Include = {
174
+ readonly type: "all";
175
+ } | {
176
+ readonly type: "any-of";
177
+ /** The patterns. An empty list is an error. */
178
+ readonly patterns: readonly RawPattern[];
179
+ };
180
+ /**
181
+ * What a rule demands of its subjects (SPEC section 4).
182
+ *
183
+ * - `must-not-use`: no reference may lead to one of the targets.
184
+ * - `must-only-use`: every reference must lead to one of the targets, or stay inside its own unit.
185
+ * - `must-not-contain`: the units must not contain one of the markers.
186
+ * - `must-be-acyclic`: the references between the units, or between the slices, must not form a cycle.
187
+ * - `must-be-independent`: no reference may lead from one slice to another slice.
188
+ * - `must-be-used`: each unit must be referred to from outside itself and the units below it.
189
+ * - `must-not-reach`: no chain of references may lead from the units to one of the targets.
190
+ * - `must-be-reachable-from`: a chain of references must lead from one of the roots to each unit.
191
+ * - `must-be-in`: each unit must be matched exactly by one of the places.
192
+ * - `must-only-be-used-by`: only the users, and the selected units, may refer to the selected units.
193
+ * - `items`: the declarations of the units that the filters select must meet a demand.
194
+ * - `custom`: a check of the binding, which finds the violations itself (SPEC 4.15). Only
195
+ * `select` takes it.
196
+ */
197
+ export type Constraint = {
198
+ readonly type: "must-not-use";
199
+ /** The paths that the units must not refer to. */
200
+ readonly targets: Targets;
201
+ } | {
202
+ readonly type: "must-only-use";
203
+ /** The only paths that the units may refer to outside themselves. */
204
+ readonly targets: Targets;
205
+ } | {
206
+ readonly type: "must-not-contain";
207
+ /** The markers. An empty list is an error. */
208
+ readonly markers: readonly string[];
209
+ } | {
210
+ readonly type: "must-be-acyclic";
211
+ /** Without `slices`, each unit is a node. An empty list is an error. */
212
+ readonly slices?: readonly RawPattern[];
213
+ } | {
214
+ readonly type: "must-be-independent";
215
+ /** The patterns of the slices. An empty list is an error. */
216
+ readonly slices: readonly RawPattern[];
217
+ } | {
218
+ readonly type: "must-be-used";
219
+ } | {
220
+ readonly type: "must-not-reach";
221
+ /** The paths that no chain from the units may end at. */
222
+ readonly targets: Targets;
223
+ } | {
224
+ readonly type: "must-be-reachable-from";
225
+ /** The patterns of the root units. An empty list is an error. */
226
+ readonly roots: readonly RawPattern[];
227
+ } | {
228
+ readonly type: "must-be-in";
229
+ /** The places, which match units exactly. An empty list is an error. */
230
+ readonly places: readonly RawPattern[];
231
+ } | {
232
+ readonly type: "must-only-be-used-by";
233
+ /** The units that may refer to the selected units, which match units exactly. An empty list is an error. */
234
+ readonly users: readonly RawPattern[];
235
+ } | {
236
+ /** Each unit must have at most a number of lines (SPEC 4.16). */
237
+ readonly type: "must-not-exceed-lines";
238
+ /** The number of lines that a unit may have. */
239
+ readonly lines: number;
240
+ } | ({
241
+ readonly type: "items";
242
+ } & Items) | CustomConstraint;
243
+ /**
244
+ * A check of the binding (SPEC 4.15), as a constraint or as the demand of a rule about
245
+ * items. The core applies the rest of the rule, and `select` answers what the rule sees.
246
+ */
247
+ export interface CustomConstraint {
248
+ /** Tells a custom check from the built-in ones. */
249
+ readonly type: "custom";
250
+ /** Lists of paths that the check looks for. For each list, `select` marks the first path of each reference that it matches. */
251
+ readonly targets?: readonly Targets[];
252
+ /** Lists of unit patterns. For each list, `select` answers the units that it matches exactly. */
253
+ readonly units?: readonly (readonly RawPattern[])[];
254
+ }
255
+ /** A rule about declarations (SPEC 4.12): filters, which all must hold, and a demand. */
256
+ export interface Items {
257
+ /** Absent: any name. Otherwise a glob must match the name. An empty list is an error. */
258
+ readonly named?: readonly string[];
259
+ /** Absent: any kind. An empty list is an error. */
260
+ readonly kinds?: readonly string[];
261
+ /** Absent: any visibility. An empty list is an error. */
262
+ readonly visibilities?: readonly string[];
263
+ /** The relations that the item must have, each to one of its paths. Absent or empty: any. */
264
+ readonly related?: readonly Related[];
265
+ /** Absent: any modifiers. Otherwise the item must have one of these. An empty list is an error. */
266
+ readonly modifiers?: readonly string[];
267
+ /** What each selected declaration must meet. */
268
+ readonly must: Demand;
269
+ }
270
+ /** A relation to one of some paths. */
271
+ export interface Related {
272
+ /** The kind of tie, such as `extends`. */
273
+ readonly relation: string;
274
+ /** The paths, which match the target within. An empty list is an error. */
275
+ readonly anyOf: readonly RawPattern[];
276
+ }
277
+ /**
278
+ * What each declaration of a rule about items must meet: not to exist, to reside in one of
279
+ * some units, to have a name that a glob matches, to have a relation or a modifier.
280
+ */
281
+ export type Demand = {
282
+ /** No declaration may be selected. */
283
+ readonly type: "not-exist";
284
+ } | {
285
+ /** The unit of the declaration must be one of the places. */
286
+ readonly type: "reside-in";
287
+ /** The places, which match units exactly. An empty list is an error. */
288
+ readonly places: readonly RawPattern[];
289
+ } | {
290
+ /** A glob must match the name. */
291
+ readonly type: "be-named";
292
+ /** The globs. An empty list is an error. */
293
+ readonly names: readonly string[];
294
+ } | ({
295
+ /** The item must have the relation to one of the paths. */
296
+ readonly type: "have";
297
+ } & Related) | {
298
+ /** The item must have one of the modifiers. */
299
+ readonly type: "have-modifier";
300
+ /** The modifiers. An empty list is an error. */
301
+ readonly modifiers: readonly string[];
302
+ } | {
303
+ /** No reference inside the item may lead to one of the targets (SPEC 4.12). */
304
+ readonly type: "not-use";
305
+ /** The paths that the code of the item must not refer to. */
306
+ readonly targets: Targets;
307
+ } | {
308
+ /** Every reference inside the item must lead to one of the targets, or stay in its unit (SPEC 4.12). */
309
+ readonly type: "only-use";
310
+ /** The only paths that the code of the item may refer to outside its unit. */
311
+ readonly targets: Targets;
312
+ } | {
313
+ /** The item must have at most a number of lines (SPEC 4.16). */
314
+ readonly type: "not-exceed-lines";
315
+ /** The number of lines that an item may have. */
316
+ readonly lines: number;
317
+ } | CustomConstraint;
318
+ /** Targets of a rule about uses: the union of both lists. */
319
+ export interface Targets {
320
+ /** Checked for existence when they are inside the analysed project. */
321
+ readonly anyOf: readonly RawPattern[];
322
+ /** Never checked for existence. */
323
+ readonly unverified: readonly RawPattern[];
324
+ }
325
+ /** How much a violation of a rule weighs (SPEC section 4). */
326
+ export type Severity = "error" | "warning";
327
+ /** Which reference kinds a rule looks at: all kinds, some kinds only, or all kinds except some. */
328
+ export type KindFilter = {
329
+ readonly type: "all";
330
+ } | {
331
+ readonly type: "only";
332
+ /** The kinds the rule looks at. */
333
+ readonly kinds: readonly string[];
334
+ } | {
335
+ readonly type: "except";
336
+ /** The kinds the rule does not look at. */
337
+ readonly kinds: readonly string[];
338
+ };
339
+ /** Whether a rule looks at candidate references. `include`: they count like exact references. */
340
+ export type Candidates = "include" | "ignore";
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,268 @@
1
+ /** What the core gives back: violations, errors, and baselines (SPEC sections 4, 5 and 7). */
2
+ import type { Certainty, FactSet, Path } from "./model.ts";
3
+ /** The violations in fact order, or the reasons why the rule cannot be evaluated. */
4
+ export type EvaluateResult = {
5
+ readonly ok: true;
6
+ /** The violations in fact order. May be empty. */
7
+ readonly violations: readonly Violation[];
8
+ } | {
9
+ readonly ok: false;
10
+ /** The reasons, in the order of the specification. */
11
+ readonly errors: readonly RuleError[];
12
+ };
13
+ /** One place where the code breaks a rule. */
14
+ export interface Violation {
15
+ /** The name of the rule. */
16
+ readonly rule: string;
17
+ /** The unit that breaks the rule. */
18
+ readonly unit: Path;
19
+ /**
20
+ * The file of the place. For a violation about a unit as a whole, the file of the first
21
+ * fact of the unit, or empty.
22
+ */
23
+ readonly file: string;
24
+ /** The line, or 0 for a violation about a unit as a whole. */
25
+ readonly line: number;
26
+ /** The column, or 0 for a violation about a unit as a whole. */
27
+ readonly column: number;
28
+ /** The note of the fact, when it has one. */
29
+ readonly note?: string;
30
+ /** What the unit does. */
31
+ readonly detail: Detail;
32
+ }
33
+ /**
34
+ * What a violation is about.
35
+ *
36
+ * - `uses`: the unit refers to a path that the rule does not allow.
37
+ * - `contains`: the unit contains a marker that the rule forbids.
38
+ * - `cycle`: one cycle of a tangle, which is a group of nodes that all reach each other.
39
+ * - `unused`: nothing outside the unit and the units below it refers to it.
40
+ * - `reaches`: a chain of references leads from the unit to a forbidden target.
41
+ * - `unreachable`: no chain of references leads from a root to the unit.
42
+ * - `outside`: the unit is in none of the places of the rule.
43
+ * - `item`: a declaration that does not meet a rule about items.
44
+ * - `custom`: what a check of the user found.
45
+ */
46
+ export type Detail = {
47
+ readonly type: "uses";
48
+ /** For a rule about items: the item whose code has the reference. */
49
+ readonly item?: Path;
50
+ /** The forbidden path. */
51
+ readonly target: Path;
52
+ /** The path as the code names it, when it differs from `target`. */
53
+ readonly written?: Path;
54
+ /** The kind of the reference. */
55
+ readonly kind: string;
56
+ /** Whether the front end proved the path. */
57
+ readonly certainty: Certainty;
58
+ } | {
59
+ readonly type: "contains";
60
+ /** The marker. */
61
+ readonly marker: string;
62
+ } | {
63
+ readonly type: "cycle";
64
+ /** The edges of the cycle, in order. The last step leads back to the first node. */
65
+ readonly steps: readonly Step[];
66
+ /** The number of nodes in the tangle. */
67
+ readonly size: number;
68
+ } | {
69
+ readonly type: "unused";
70
+ } | {
71
+ readonly type: "reaches";
72
+ /** The edges from the unit to the unit that uses the target. Empty when the unit uses the target itself. */
73
+ readonly steps: readonly Step[];
74
+ /** The use of the target at the end of the chain. */
75
+ readonly end: End;
76
+ } | {
77
+ readonly type: "unreachable";
78
+ } | {
79
+ readonly type: "outside";
80
+ } | {
81
+ readonly type: "item";
82
+ /** The path of the item. */
83
+ readonly item: Path;
84
+ /** The kind of the item. */
85
+ readonly kind: string;
86
+ } | {
87
+ /** The unit, or one declaration of it, has more lines than the rule allows (SPEC 4.16). */
88
+ readonly type: "too-long";
89
+ /** For a rule about items: the path of the item. */
90
+ readonly item?: Path;
91
+ /** For a rule about items: the kind of the item. */
92
+ readonly kind?: string;
93
+ /** The number of lines. */
94
+ readonly lines: number;
95
+ /** The number of lines that the rule allows. */
96
+ readonly limit: number;
97
+ } | {
98
+ readonly type: "custom";
99
+ /** What the unit does, printed after the unit. */
100
+ readonly message: string;
101
+ /** What a baseline counts the violation as. Absent: the message. */
102
+ readonly key?: string;
103
+ };
104
+ /** What a rule sees (SPEC section 8), or the reasons why the rule cannot be evaluated. Units, facts and declarations are given by their position in the fact set. */
105
+ export type SelectResult = {
106
+ /** The rule can be evaluated. */
107
+ readonly ok: true;
108
+ /** The units that the rule selects. */
109
+ readonly subjects: readonly number[];
110
+ /** For each list of unit patterns of the check: the units that it matches. */
111
+ readonly units: readonly (readonly number[])[];
112
+ /** The references that the rule sees, of all units, in the order of the facts. */
113
+ readonly references: readonly SelectedReference[];
114
+ /** The markers of the subjects that the rule sees. */
115
+ readonly markers: readonly number[];
116
+ /** The declarations of the subjects that the rule sees. */
117
+ readonly declarations: readonly number[];
118
+ /** For a rule about items: the declarations that its filters select. */
119
+ readonly items?: readonly number[];
120
+ } | {
121
+ /** The rule cannot be evaluated. */
122
+ readonly ok: false;
123
+ /** The reasons, in the order of the specification. */
124
+ readonly errors: readonly RuleError[];
125
+ };
126
+ /** The tangles of a graph of what a rule sees (SPEC section 8), or the reasons why the rule cannot be evaluated. */
127
+ export type TanglesResult = {
128
+ /** The rule can be evaluated. */
129
+ readonly ok: true;
130
+ /** The tangles. A step of `cycle` is `[node, edge]`, with the place of the edge in the edges of the node. */
131
+ readonly tangles: readonly {
132
+ /** The nodes of the tangle, in ascending order. */
133
+ readonly members: readonly number[];
134
+ /** A shortest cycle through the first member. */
135
+ readonly cycle: readonly (readonly [number, number])[];
136
+ }[];
137
+ } | {
138
+ /** The rule cannot be evaluated. */
139
+ readonly ok: false;
140
+ /** The reasons, in the order of the specification. */
141
+ readonly errors: readonly RuleError[];
142
+ };
143
+ /** The edges of a graph of what a rule sees (SPEC section 8), or the reasons why the rule cannot be evaluated. */
144
+ export type GraphResult = {
145
+ /** The rule can be evaluated. */
146
+ readonly ok: true;
147
+ /** The unit of each node, by position in the fact set. Absent for the unit graph, where a node is its unit. */
148
+ readonly nodes?: readonly number[];
149
+ /** For each node: its edges, each as `[to, fact, path]`, with the place of the path in `[target, ...aliases]`. */
150
+ readonly edges: readonly (readonly (readonly [number, number, number])[])[];
151
+ } | {
152
+ /** The rule cannot be evaluated. */
153
+ readonly ok: false;
154
+ /** The reasons, in the order of the specification. */
155
+ readonly errors: readonly RuleError[];
156
+ };
157
+ /** A reference that a rule sees. */
158
+ export interface SelectedReference {
159
+ /** The position of the fact. */
160
+ readonly fact: number;
161
+ /** The unit of the fact. */
162
+ readonly unit: number;
163
+ /** For each path of the reference, `[target, ...aliases]`: the unit that owns it, or `null`. */
164
+ readonly owners: readonly (number | null)[];
165
+ /**
166
+ * For each list of targets of the check: the first path that it matches, by its place in
167
+ * `[target, ...aliases]`, or `null`. Absent when no list matches a path.
168
+ */
169
+ readonly hits?: readonly (number | null)[];
170
+ /** For a rule about items: the reference is inside an item that the filters select. */
171
+ readonly inside?: true;
172
+ }
173
+ /** The reference at the end of a chain: the use of the forbidden target. */
174
+ export interface End {
175
+ /** The unit that uses the target. */
176
+ readonly unit: Path;
177
+ /** The file of the use. */
178
+ readonly file: string;
179
+ /** The line of the use. */
180
+ readonly line: number;
181
+ /** The column of the use. */
182
+ readonly column: number;
183
+ /** The forbidden path. */
184
+ readonly target: Path;
185
+ /** The kind of the reference. */
186
+ readonly kind: string;
187
+ }
188
+ /** One edge of a cycle or of a chain, with the reference that makes it. */
189
+ export interface Step {
190
+ /** The node the edge leaves. */
191
+ readonly from: Path;
192
+ /** The node the edge leads to. */
193
+ readonly to: Path;
194
+ /** The file of the reference. */
195
+ readonly file: string;
196
+ /** The line of the reference. */
197
+ readonly line: number;
198
+ /** The column of the reference. */
199
+ readonly column: number;
200
+ /** The path the reference names. */
201
+ readonly target: Path;
202
+ /** The kind of the reference. */
203
+ readonly kind: string;
204
+ }
205
+ /** Why a rule cannot be evaluated (SPEC section 5). */
206
+ export interface RuleError {
207
+ /** The check that failed. */
208
+ readonly code: ErrorCode;
209
+ /** The part of the rule or of the fact set that the error is about, when there is one. */
210
+ readonly role?: Role;
211
+ /** The offending value, such as a pattern, when there is one. */
212
+ readonly value?: string;
213
+ }
214
+ /** The check that failed (SPEC section 5). */
215
+ export type ErrorCode = "invalid-facts" | "empty-name" | "empty-list" | "invalid-pattern" | "pattern-matches-nothing" | "no-subjects" | "too-few-nodes" | "unknown-marker" | "unknown-kind" | "unknown-tag" | "unused-exemption" | "unknown-item-kind" | "unknown-visibility" | "unknown-relation" | "unknown-modifier" | "unknown-property";
216
+ /** The part of a rule or of a fact set that an error is about. */
217
+ export type Role = "unit" | "subject" | "subject-exception" | "target" | "unverified-target" | "marker" | "slice" | "root" | "kind" | "tag" | "place" | "user" | "exemption-from" | "exemption-to" | "exemption" | "name" | "item-kind" | "visibility" | "relation" | "related" | "required-name" | "required" | "modifier" | "required-modifier" | "layer" | "property";
218
+ /**
219
+ * How reports and baselines print paths (SPEC section 3). A fact set is a path format, so a
220
+ * report can take the fact set itself.
221
+ */
222
+ export type PathFormat = Pick<FactSet, "separator" | "attachedPrefixes" | "hiddenPrefixes">;
223
+ /** One line of a baseline: `count` accepted violations with one key. */
224
+ export interface BaselineEntry {
225
+ /** The name of the rule. */
226
+ readonly rule: string;
227
+ /** The unit, printed as in reports. */
228
+ readonly unit: string;
229
+ /** What the violations are, as SPEC section 7 writes it for each kind of violation. */
230
+ readonly what: string;
231
+ /** The number of accepted violations with this key. */
232
+ readonly count: number;
233
+ }
234
+ /** An entry that accepts more violations than the code has. */
235
+ export interface StaleEntry {
236
+ /** The unit of the entry. */
237
+ readonly unit: string;
238
+ /** What the entry accepts, as in {@link BaselineEntry.what}. */
239
+ readonly what: string;
240
+ /** The number of violations that the baseline accepts for this key. */
241
+ readonly count: number;
242
+ /** The number of violations that the code has. */
243
+ readonly found: number;
244
+ }
245
+ /** The entries, or the number of the first invalid line, from 1. */
246
+ export type ParsedBaseline = {
247
+ readonly ok: true;
248
+ /** The entries, in the order of the text. */
249
+ readonly entries: readonly BaselineEntry[];
250
+ } | {
251
+ readonly ok: false;
252
+ /** The number of the first invalid line, from 1. */
253
+ readonly line: number;
254
+ };
255
+ /** The result of `applyBaseline`. */
256
+ export interface Applied {
257
+ /** The violations that the baseline does not accept. */
258
+ readonly remaining: readonly Violation[];
259
+ /** The entries that accept more violations than the code has. */
260
+ readonly stale: readonly StaleEntry[];
261
+ }
262
+ /** The key of a violation in a baseline. */
263
+ export interface BaselineKey {
264
+ /** The unit, printed as in reports. */
265
+ readonly unit: string;
266
+ /** What the violation is, as SPEC section 7 writes it. */
267
+ readonly what: string;
268
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,7 @@
1
+ /** The instance that the handles of fact sets belong to. */
2
+ export declare function currentGeneration(): number;
3
+ /**
4
+ * Sends one request and returns the answer as JSON text. Throws when the core finds the
5
+ * request not valid, which is a bug of this package and not of the rule.
6
+ */
7
+ export declare function call(request: string): string;