@pptx-studio/validate 0.2.0 → 0.3.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 +31 -0
- package/NOTICE +13 -3
- package/README.md +20 -16
- package/dist/index.d.ts +51 -122
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +200 -53
- package/dist/index.js.map +1 -1
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,36 @@
|
|
|
1
1
|
# @pptx-studio/validate
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- ae2e566: A table's style is the one PowerPoint draws. `BUILTIN_TABLE_STYLES` is PowerPoint's own Table
|
|
8
|
+
Styles gallery: 74 styles, each with its GUID, its name and the `a:tblStyle` PowerPoint writes for
|
|
9
|
+
it. `tableStyleOf(table)` returns the built-in a table's GUID names, in any case, or `null` for
|
|
10
|
+
PowerPoint's default 1-pt black grid; nothing in `ppt/tableStyles.xml` changes which. `builtinTableStyle`
|
|
11
|
+
and `parseTableStyle` read a `CT_TableStyle` into its thirteen parts. An inline `TableStyleRef` now
|
|
12
|
+
carries its `id`, a style GUID without braces or with padding throws `MODEL_TABLE_ATTR`, and
|
|
13
|
+
`MODEL_ERROR_CODES` lists every code, including the new `MODEL_TABLE_STYLE`.
|
|
14
|
+
|
|
15
|
+
validate adds `V032`, a warning on a table that names no built-in style, and `V033`, refusing the
|
|
16
|
+
table-style forms PowerPoint repairs.
|
|
17
|
+
|
|
18
|
+
## 0.2.1
|
|
19
|
+
|
|
20
|
+
### Patch Changes
|
|
21
|
+
|
|
22
|
+
- b58dd19: Built with tsdown 0.23. The declarations take a new shape, and the API is unchanged.
|
|
23
|
+
|
|
24
|
+
- Every value is exported where it is declared (`export declare function …`), not in a trailing
|
|
25
|
+
`export { … }`.
|
|
26
|
+
- The types are exported in one `export type { … }`.
|
|
27
|
+
- The JavaScript is byte-for-byte what 0.22 emitted.
|
|
28
|
+
- In geometry, opc, validate and xml, the source maps name fewer symbols.
|
|
29
|
+
|
|
30
|
+
- Updated dependencies [b58dd19]
|
|
31
|
+
- @pptx-studio/opc@0.1.3
|
|
32
|
+
- @pptx-studio/xml@0.1.2
|
|
33
|
+
|
|
3
34
|
## 0.2.0
|
|
4
35
|
|
|
5
36
|
### Minor Changes
|
package/NOTICE
CHANGED
|
@@ -27,14 +27,24 @@ Entries are added here at the moment the material lands, not at release time.
|
|
|
27
27
|
presetShapeDefinitions.xml, 538970 bytes
|
|
28
28
|
sha256 4a762444d8d85876881c02a5b1dedf6f73006fcd8acb7b4e393435615b37c780
|
|
29
29
|
|
|
30
|
+
* Microsoft PowerPoint output
|
|
31
|
+
Written by Microsoft PowerPoint, driven by this project's own scripts.
|
|
32
|
+
|
|
33
|
+
@pptx-studio/model contains PowerPoint's 74 built-in table styles: each is
|
|
34
|
+
the a:tblStyle element PowerPoint writes into ppt/tableStyles.xml, byte for
|
|
35
|
+
byte, enumerated through PowerPoint's Table Styles gallery and saved by
|
|
36
|
+
PowerPoint (LEGAL.md, ADR 0063). corpus/ground-truth/table-styles.json holds
|
|
37
|
+
the same 74.
|
|
38
|
+
|
|
39
|
+
The decks in corpus/authored are PowerPoint Blank Presentations, so each
|
|
40
|
+
carries the Microsoft-generated ppt/theme/theme1.xml and default layouts
|
|
41
|
+
PowerPoint writes into a new deck (ADR 0009).
|
|
42
|
+
|
|
30
43
|
--------------------------------------------------------------------------------
|
|
31
44
|
Attributions the plan commits us to, listed so the obligation is visible before
|
|
32
45
|
the code arrives
|
|
33
46
|
--------------------------------------------------------------------------------
|
|
34
47
|
|
|
35
|
-
* Pattern fill tiles (sub-phase 2.7) are generated from Mono libgdiplus.
|
|
36
|
-
libgdiplus - Copyright Novell, Inc. and contributors - MIT
|
|
37
|
-
|
|
38
48
|
* Metric-compatible substitute fonts ship in a separate package,
|
|
39
49
|
@pptx-studio/fonts-metric-compat, under SIL OFL 1.1 with its own
|
|
40
50
|
OFL.txt and reserved-font-name handling. They are deliberately kept out
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @pptx-studio/validate
|
|
2
2
|
|
|
3
|
-
**The repair firewall.** Thirty-
|
|
3
|
+
**The repair firewall.** Thirty-three rules a `.pptx` must not break, checked
|
|
4
4
|
before any bytes are handed over, each finding carrying the part and the XPath.
|
|
5
5
|
|
|
6
6
|
Apache-2.0 · browser and Web Worker only, no Node · part of
|
|
@@ -28,7 +28,7 @@ quietly lost something.
|
|
|
28
28
|
So this is not a schema validator with a nice report. It is the only feedback
|
|
29
29
|
loop that exists, and it runs on every export in development and in production.
|
|
30
30
|
|
|
31
|
-
## Thirty-
|
|
31
|
+
## Thirty-three rules, in two halves
|
|
32
32
|
|
|
33
33
|
Roughly half come from ECMA-376: content-type coverage, `xsd:sequence` child
|
|
34
34
|
order, `minOccurs`, the four identifier ranges. Those are derivable, and one of
|
|
@@ -38,19 +38,23 @@ schemas and checked against 194 148 elements PowerPoint wrote.
|
|
|
38
38
|
The other half cannot be derived from anything. Each is the record of a package
|
|
39
39
|
built with **one** change in it, opened in PowerPoint 16.0.20326, and declined:
|
|
40
40
|
|
|
41
|
-
| |
|
|
42
|
-
| ------ |
|
|
43
|
-
| `V022` | a `p:ph type="hdr"` on a slide. The other seven content types all open.
|
|
44
|
-
| `V023` | a geometry guide referenced but never defined. `ST_GeomGuideName` is an unconstrained token.
|
|
45
|
-
| `V024` | a `c:strLit` inside a series `c:tx`, two elements away from where the literal forms are legal.
|
|
46
|
-
| `V025` | a `p:control`, in all eight forms tried. An empty `p:controls` is accepted.
|
|
47
|
-
| `V026` | a `cs:chartStyle` with thirty of its thirty-one entries. No chart style at all is fine.
|
|
48
|
-
| `V019` | a master id colliding with a layout id. They are one number space and no schema says so.
|
|
49
|
-
| `V020` | a `p:cNvPr/@id` between 2147483648 and 4294967294. 4294967295 opens; it is minus one.
|
|
50
|
-
| `V009` | a slide without exactly one layout relationship; a `cx:chartSpace` with no `.rels`.
|
|
51
|
-
| `V004` | a percent-escape of an _unreserved_ character in a part name. `0x808D1005`.
|
|
52
|
-
| `V012` | an `a:ahXY` directly under `a:custGeom`, without its `a:ahLst` wrapper.
|
|
53
|
-
| `V031` | an `a:gridCol` without `@w`, an `a:tr` without `@h`, `gridSpan="2.0"`, `hMerge="on"`: a repair each.
|
|
41
|
+
| | |
|
|
42
|
+
| ------ | ------------------------------------------------------------------------------------------------------- |
|
|
43
|
+
| `V022` | a `p:ph type="hdr"` on a slide. The other seven content types all open. |
|
|
44
|
+
| `V023` | a geometry guide referenced but never defined. `ST_GeomGuideName` is an unconstrained token. |
|
|
45
|
+
| `V024` | a `c:strLit` inside a series `c:tx`, two elements away from where the literal forms are legal. |
|
|
46
|
+
| `V025` | a `p:control`, in all eight forms tried. An empty `p:controls` is accepted. |
|
|
47
|
+
| `V026` | a `cs:chartStyle` with thirty of its thirty-one entries. No chart style at all is fine. |
|
|
48
|
+
| `V019` | a master id colliding with a layout id. They are one number space and no schema says so. |
|
|
49
|
+
| `V020` | a `p:cNvPr/@id` between 2147483648 and 4294967294. 4294967295 opens; it is minus one. |
|
|
50
|
+
| `V009` | a slide without exactly one layout relationship; a `cx:chartSpace` with no `.rels`. |
|
|
51
|
+
| `V004` | a percent-escape of an _unreserved_ character in a part name. `0x808D1005`. |
|
|
52
|
+
| `V012` | an `a:ahXY` directly under `a:custGeom`, without its `a:ahLst` wrapper. |
|
|
53
|
+
| `V031` | an `a:gridCol` without `@w`, an `a:tr` without `@h`, `gridSpan="2.0"`, `hMerge="on"`: a repair each. |
|
|
54
|
+
| `V033` | a table style id without braces or padded, a table-style part without `@def`, `b="yes"`: a repair each. |
|
|
55
|
+
|
|
56
|
+
And one warning measured the same way: `V032`, a table naming none of PowerPoint's 74 built-in
|
|
57
|
+
table styles, which PowerPoint draws as a 1-pt black grid whatever the package defines.
|
|
54
58
|
|
|
55
59
|
Every rule carries a `why` recording what was tried and what opened, so whoever
|
|
56
60
|
eventually contradicts one knows what they are contradicting.
|
|
@@ -86,7 +90,7 @@ the same reason.
|
|
|
86
90
|
|
|
87
91
|
Two suites that check opposite things, and neither substitutes for the other.
|
|
88
92
|
|
|
89
|
-
**It fires.** `validate.test.ts` breaks a minimal deck
|
|
93
|
+
**It fires.** `validate.test.ts` breaks a minimal deck once per
|
|
90
94
|
rule, and asserts each rule reports the right part and the right XPath.
|
|
91
95
|
|
|
92
96
|
**It is quiet.** `tools/corpus/suites/validate.test.ts` runs all fifty-two committed
|
package/dist/index.d.ts
CHANGED
|
@@ -24,7 +24,7 @@ import { PartName, PartStore, ReadZipOptions, ZipArchive } from "@pptx-studio/op
|
|
|
24
24
|
*
|
|
25
25
|
* Deliberately few. Almost everything this package has to say is a finding.
|
|
26
26
|
*/
|
|
27
|
-
declare const VALIDATE_ERROR_CODES: readonly ["ERR_VALIDATION_FAILED", "ERR_UNVALIDATABLE", "ERR_UNKNOWN_RULE"];
|
|
27
|
+
export declare const VALIDATE_ERROR_CODES: readonly ["ERR_VALIDATION_FAILED", "ERR_UNVALIDATABLE", "ERR_UNKNOWN_RULE"];
|
|
28
28
|
type ValidateErrorCode = (typeof VALIDATE_ERROR_CODES)[number];
|
|
29
29
|
interface ValidateErrorDetail {
|
|
30
30
|
/** The part the failure is about, if it is about one. */
|
|
@@ -40,55 +40,18 @@ interface ValidateErrorDetail {
|
|
|
40
40
|
*/
|
|
41
41
|
readonly report?: unknown;
|
|
42
42
|
}
|
|
43
|
-
declare class ValidateError extends Error {
|
|
43
|
+
export declare class ValidateError extends Error {
|
|
44
44
|
readonly code: ValidateErrorCode;
|
|
45
45
|
readonly detail: ValidateErrorDetail;
|
|
46
46
|
constructor(code: ValidateErrorCode, message: string, detail?: ValidateErrorDetail);
|
|
47
47
|
}
|
|
48
|
-
declare function isValidateError(value: unknown): value is ValidateError;
|
|
48
|
+
export declare function isValidateError(value: unknown): value is ValidateError;
|
|
49
49
|
//#endregion
|
|
50
50
|
//#region src/rules/rules.d.ts
|
|
51
51
|
/**
|
|
52
|
-
* The
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
* The functions are in the files beside this one. What lives here is the part a
|
|
57
|
-
* person reads: what each rule claims, how sure we are, and *how we know*. A
|
|
58
|
-
* validator whose rules exist only as code is a validator nobody can audit, and
|
|
59
|
-
* this one has to be audited, because roughly half of it enforces things no
|
|
60
|
-
* schema says.
|
|
61
|
-
*
|
|
62
|
-
* That is the fact that shapes the whole package. ECMA-376 is a description of
|
|
63
|
-
* a file format; PowerPoint is an implementation that refuses files the
|
|
64
|
-
* description permits. Sub-phase 0.7 and the corpus bisections in
|
|
65
|
-
* `tools/corpus/ROSTER.md` found nineteen such refusals by building a package
|
|
66
|
-
* with one change in it and watching PowerPoint decline to open it - no
|
|
67
|
-
* diagnostic, no log, no part named, just "PowerPoint could not open the file"
|
|
68
|
-
* or `0x80070570`. Every rule below whose `evidence` says `measured` came from
|
|
69
|
-
* that loop and from nowhere else.
|
|
70
|
-
*
|
|
71
|
-
* So each rule carries three things beyond its check:
|
|
72
|
-
*
|
|
73
|
-
* - `evidence` - `schema` (ECMA-376 says so), `measured` (we watched PowerPoint
|
|
74
|
-
* refuse it), or `both`.
|
|
75
|
-
* - `why` - the sentence that justifies the rule to somebody who is about to
|
|
76
|
-
* delete it because it fired on their file.
|
|
77
|
-
* - `severity` - `fatal` refuses an export; `warning` is reported and does not.
|
|
78
|
-
*
|
|
79
|
-
* ## On being wrong in the safe direction
|
|
80
|
-
*
|
|
81
|
-
* A false positive here blocks an export a user wanted. A false negative hands
|
|
82
|
-
* them a file PowerPoint will not open, with no way to find out why. Those are
|
|
83
|
-
* not symmetric, but the first is not free either - a validator that fires on
|
|
84
|
-
* good files gets turned off, and then it catches nothing.
|
|
85
|
-
*
|
|
86
|
-
* The resolution is `origin`, which lives on the finding rather than here: a
|
|
87
|
-
* fatal a caller *introduced* refuses the export, and the identical fatal that
|
|
88
|
-
* was already in the file when it was opened is reported and does not. That is
|
|
89
|
-
* the same split `PartStore.write` already makes for dangling relationships,
|
|
90
|
-
* and for the same reason - refusing to re-export a file we did not break makes
|
|
91
|
-
* the file unopenable in this editor and does not fix anything.
|
|
52
|
+
* The rules, and the evidence for each: `schema`, `measured` (PowerPoint refused or repaired it),
|
|
53
|
+
* or `both`. A fatal a caller introduced refuses an export; the same fatal inherited from the
|
|
54
|
+
* opened file is reported and does not. The README lists every rule.
|
|
92
55
|
*/
|
|
93
56
|
type RuleCategory = 'package' | 'relationships' | 'order' | 'required' | 'ids' | 'refused' | 'preservation';
|
|
94
57
|
type Severity = 'fatal' | 'warning';
|
|
@@ -104,17 +67,12 @@ interface Rule {
|
|
|
104
67
|
/** Why the rule exists, for whoever is about to argue with it. */
|
|
105
68
|
readonly why: string;
|
|
106
69
|
/**
|
|
107
|
-
* True when the rule needs the package as it was opened
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
* Six rules do. They are skipped rather than passed when no baseline is
|
|
111
|
-
* given, and the report says so - a preservation rule that silently reports
|
|
112
|
-
* nothing because it had nothing to compare against is worse than one that
|
|
113
|
-
* did not run, because it looks like a pass.
|
|
70
|
+
* True when the rule needs the package as it was opened; without a baseline it is reported as
|
|
71
|
+
* skipped, never as passed.
|
|
114
72
|
*/
|
|
115
73
|
readonly needsBaseline?: true;
|
|
116
74
|
}
|
|
117
|
-
declare const RULES: readonly [{
|
|
75
|
+
export declare const RULES: readonly [{
|
|
118
76
|
readonly id: "V001";
|
|
119
77
|
readonly category: "package";
|
|
120
78
|
readonly severity: "fatal";
|
|
@@ -334,12 +292,26 @@ declare const RULES: readonly [{
|
|
|
334
292
|
readonly evidence: "both";
|
|
335
293
|
readonly title: "`a:gridCol/@w`, `a:tr/@h`, and typed `gridSpan`, `rowSpan`, `hMerge`, `vMerge`";
|
|
336
294
|
readonly why: string;
|
|
295
|
+
}, {
|
|
296
|
+
readonly id: "V032";
|
|
297
|
+
readonly category: "ids";
|
|
298
|
+
readonly severity: "warning";
|
|
299
|
+
readonly evidence: "measured";
|
|
300
|
+
readonly title: "a table names one of PowerPoint's 74 built-in table styles, or none";
|
|
301
|
+
readonly why: string;
|
|
302
|
+
}, {
|
|
303
|
+
readonly id: "V033";
|
|
304
|
+
readonly category: "required";
|
|
305
|
+
readonly severity: "fatal";
|
|
306
|
+
readonly evidence: "both";
|
|
307
|
+
readonly title: "a table style id is a braced GUID, and the table-style part is one PowerPoint keeps";
|
|
308
|
+
readonly why: string;
|
|
337
309
|
}];
|
|
338
310
|
type RuleId = (typeof RULES)[number]['id'];
|
|
339
|
-
declare function ruleById(id: string): Rule | undefined;
|
|
340
|
-
declare const RULE_IDS: readonly RuleId[];
|
|
311
|
+
export declare function ruleById(id: string): Rule | undefined;
|
|
312
|
+
export declare const RULE_IDS: readonly RuleId[];
|
|
341
313
|
/** Rules that need the package as it was opened. See `Rule.needsBaseline`. */
|
|
342
|
-
declare const BASELINE_RULES: readonly RuleId[];
|
|
314
|
+
export declare const BASELINE_RULES: readonly RuleId[];
|
|
343
315
|
//#endregion
|
|
344
316
|
//#region src/report/location.d.ts
|
|
345
317
|
/**
|
|
@@ -397,9 +369,9 @@ interface Location {
|
|
|
397
369
|
readonly offset: number | null;
|
|
398
370
|
}
|
|
399
371
|
/** A location that names a part and nothing inside it. */
|
|
400
|
-
declare function partLocation(part: string): Location;
|
|
372
|
+
export declare function partLocation(part: string): Location;
|
|
401
373
|
/** The location of the package itself: the archive, the content types, the graph. */
|
|
402
|
-
declare const PACKAGE_LOCATION: Location;
|
|
374
|
+
export declare const PACKAGE_LOCATION: Location;
|
|
403
375
|
/**
|
|
404
376
|
* The XPath of an element, from the document root.
|
|
405
377
|
*
|
|
@@ -408,11 +380,11 @@ declare const PACKAGE_LOCATION: Location;
|
|
|
408
380
|
* finding built from a node the caller synthesised is degraded rather than
|
|
409
381
|
* lost.
|
|
410
382
|
*/
|
|
411
|
-
declare function xpathOf(element: XElement): string;
|
|
383
|
+
export declare function xpathOf(element: XElement): string;
|
|
412
384
|
/** The XPath of an attribute: its owner's path, then `/@qname`. */
|
|
413
|
-
declare function xpathOfAttribute(owner: XElement, attr: XAttribute | string): string;
|
|
385
|
+
export declare function xpathOfAttribute(owner: XElement, attr: XAttribute | string): string;
|
|
414
386
|
/** A location for an element inside a named part. */
|
|
415
|
-
declare function elementLocation(part: string, element: XElement): Location;
|
|
387
|
+
export declare function elementLocation(part: string, element: XElement): Location;
|
|
416
388
|
/**
|
|
417
389
|
* A location for one attribute of an element.
|
|
418
390
|
*
|
|
@@ -420,7 +392,7 @@ declare function elementLocation(part: string, element: XElement): Location;
|
|
|
420
392
|
* element's start when it does not - which is the case that matters, because a
|
|
421
393
|
* *missing* required attribute is a finding and it has to point somewhere.
|
|
422
394
|
*/
|
|
423
|
-
declare function attributeLocation(part: string, element: XElement, qname: string): Location;
|
|
395
|
+
export declare function attributeLocation(part: string, element: XElement, qname: string): Location;
|
|
424
396
|
/**
|
|
425
397
|
* `line:column` for an offset, 1-based, or `null`.
|
|
426
398
|
*
|
|
@@ -429,44 +401,20 @@ declare function attributeLocation(part: string, element: XElement, qname: strin
|
|
|
429
401
|
* hundred times. Callers that render a report for a human ask for it once, at
|
|
430
402
|
* the point of rendering, for the findings they are about to show.
|
|
431
403
|
*/
|
|
432
|
-
declare function lineColumn(source: string, offset: number): {
|
|
404
|
+
export declare function lineColumn(source: string, offset: number): {
|
|
433
405
|
line: number;
|
|
434
406
|
column: number;
|
|
435
407
|
};
|
|
436
408
|
/** Document order, for sorting findings within a part. */
|
|
437
|
-
declare function inDocumentOrder(a: XNode, b: XNode): number;
|
|
409
|
+
export declare function inDocumentOrder(a: XNode, b: XNode): number;
|
|
438
410
|
/** The root element's qname, for the handful of rules that dispatch on it. */
|
|
439
|
-
declare function rootName(document: XDocument): string;
|
|
411
|
+
export declare function rootName(document: XDocument): string;
|
|
440
412
|
//#endregion
|
|
441
413
|
//#region src/report/report.d.ts
|
|
442
414
|
/**
|
|
443
|
-
*
|
|
444
|
-
*
|
|
445
|
-
*
|
|
446
|
-
*
|
|
447
|
-
* The hardest question this package has to answer is not "is this file valid".
|
|
448
|
-
* It is **"did we break it"**, and those are different questions with different
|
|
449
|
-
* consequences. A fatal finding in a deck the user imported ten seconds ago is
|
|
450
|
-
* information; the same finding in a deck they just edited is a bug in us, and
|
|
451
|
-
* handing over the bytes would give them a repair prompt with no explanation.
|
|
452
|
-
*
|
|
453
|
-
* Refusing both would be the strict-looking choice and it is the wrong one. It
|
|
454
|
-
* would mean that a deck with one pre-existing defect - a dangling image
|
|
455
|
-
* relationship, say, which PowerPoint tolerates and which is common in files
|
|
456
|
-
* that have been through three other tools - could be opened in this editor and
|
|
457
|
-
* never saved again. The editor would be refusing to give the user back their
|
|
458
|
-
* own file over a problem it did not cause and cannot fix. `PartStore.write`
|
|
459
|
-
* already made exactly this call for dangling relationships, and this is the
|
|
460
|
-
* same call generalised to all thirty-one rules.
|
|
461
|
-
*
|
|
462
|
-
* So `origin` is not a per-rule judgement call. It is computed by running the
|
|
463
|
-
* rules a second time against the package **as it was opened** and differencing
|
|
464
|
-
* the two reports: a finding that is in both is `inherited`, one that is only in
|
|
465
|
-
* the new report is `introduced`. That is exact, it needs no rule to reason
|
|
466
|
-
* about history, and it cannot drift from what the rules actually do.
|
|
467
|
-
*
|
|
468
|
-
* The second pass only happens when the first found something fatal, so a clean
|
|
469
|
-
* export - the overwhelmingly common case - pays nothing for it.
|
|
415
|
+
* A finding is `inherited` when the package as it was opened already had it, `introduced` when it
|
|
416
|
+
* did not, computed by running the rules on both and differencing. Only an introduced fatal refuses
|
|
417
|
+
* an export, so a deck with a defect it arrived with can still be saved.
|
|
470
418
|
*/
|
|
471
419
|
type Origin =
|
|
472
420
|
/** The finding is in the package we are about to write and was not in the original. */
|
|
@@ -528,14 +476,14 @@ interface Report {
|
|
|
528
476
|
* the same place with different values are different findings, and treating
|
|
529
477
|
* them as one would let an introduced defect hide behind an inherited one.
|
|
530
478
|
*/
|
|
531
|
-
declare function findingKey(finding: Finding): string;
|
|
532
|
-
declare function buildReport(input: {
|
|
479
|
+
export declare function findingKey(finding: Finding): string;
|
|
480
|
+
export declare function buildReport(input: {
|
|
533
481
|
readonly findings: readonly Finding[];
|
|
534
482
|
readonly checked: readonly RuleId[];
|
|
535
483
|
readonly skipped: readonly SkippedRule[];
|
|
536
484
|
readonly problems: readonly ReadProblem[];
|
|
537
485
|
}): Report;
|
|
538
|
-
declare function isReport(value: unknown): value is Report;
|
|
486
|
+
export declare function isReport(value: unknown): value is Report;
|
|
539
487
|
interface FormatOptions {
|
|
540
488
|
/** Include `inherited` findings. Default true. */
|
|
541
489
|
readonly inherited?: boolean;
|
|
@@ -551,32 +499,13 @@ interface FormatOptions {
|
|
|
551
499
|
* "what is wrong with this file", and a file is a set of parts. Grouping by
|
|
552
500
|
* rule is the right shape for the corpus gate and the wrong one here.
|
|
553
501
|
*/
|
|
554
|
-
declare function formatReport(report: Report, options?: FormatOptions): string;
|
|
502
|
+
export declare function formatReport(report: Report, options?: FormatOptions): string;
|
|
555
503
|
//#endregion
|
|
556
504
|
//#region src/context.d.ts
|
|
557
505
|
/**
|
|
558
|
-
* The state a rule reads, and the one method it writes.
|
|
559
|
-
*
|
|
560
|
-
*
|
|
561
|
-
* interface, and it is the same shape `checkLayering({manifests, catalog})` and
|
|
562
|
-
* `checkCorpus({manifests, files, ...})` already have in this repository, for
|
|
563
|
-
* the same reason: a rule that takes a context and returns nothing is a rule
|
|
564
|
-
* that can be run against a package assembled in a test, with no temporary
|
|
565
|
-
* directory, no archive on disk and no other twenty-eight rules running beside
|
|
566
|
-
* it obscuring which one fired.
|
|
567
|
-
*
|
|
568
|
-
* ## Everything is lazy, and everything is cached
|
|
569
|
-
*
|
|
570
|
-
* Twelve of the rules want the parsed tree of every XML part. Parsing each part
|
|
571
|
-
* once per rule would be twelve passes over a deck that can be two hundred
|
|
572
|
-
* megabytes. Parsing all of them up front would be one pass too many for the
|
|
573
|
-
* package-level rules, which need no trees at all.
|
|
574
|
-
*
|
|
575
|
-
* So `document()` parses on first ask and remembers. A part that is not XML
|
|
576
|
-
* returns `null` and is not asked again. A part that will not *parse* also
|
|
577
|
-
* returns `null` - and records a `ReadProblem`, because a rule that silently
|
|
578
|
-
* saw nothing is indistinguishable from a rule that found nothing, and those
|
|
579
|
-
* are opposite answers.
|
|
506
|
+
* The state a rule reads, and the one method it writes. Every rule is `(ctx: Context) => void`,
|
|
507
|
+
* so one runs alone against a package built in a test. Trees parse on first ask and are cached;
|
|
508
|
+
* a part that will not parse returns `null` and records a `ReadProblem`.
|
|
580
509
|
*/
|
|
581
510
|
interface Context {
|
|
582
511
|
/** The package about to be handed over, or the one being inspected. */
|
|
@@ -665,7 +594,7 @@ declare class RuntimeContext implements Context {
|
|
|
665
594
|
add(rule: RuleId, where: Location, message: string): void;
|
|
666
595
|
problem(part: string, message: string): void;
|
|
667
596
|
}
|
|
668
|
-
declare function createContext(input: ContextInput): RuntimeContext;
|
|
597
|
+
export declare function createContext(input: ContextInput): RuntimeContext;
|
|
669
598
|
//#endregion
|
|
670
599
|
//#region src/validate.d.ts
|
|
671
600
|
interface ValidateOptions {
|
|
@@ -688,11 +617,11 @@ interface ValidateOptions {
|
|
|
688
617
|
* those are skipped and the report says so.
|
|
689
618
|
*/
|
|
690
619
|
readonly bytes?: Uint8Array;
|
|
691
|
-
/** The package as it was opened. The
|
|
620
|
+
/** The package as it was opened. The preservation rules need it. */
|
|
692
621
|
readonly baseline?: PartStore;
|
|
693
622
|
/** The baseline's archive, so an inherited `V003` can be recognised as inherited. */
|
|
694
623
|
readonly baselineBytes?: Uint8Array;
|
|
695
|
-
/** A subset to run. Defaults to
|
|
624
|
+
/** A subset to run. Defaults to every rule. */
|
|
696
625
|
readonly rules?: readonly RuleId[];
|
|
697
626
|
/** Passed to `readZip` when `bytes` are given. */
|
|
698
627
|
readonly zip?: ReadZipOptions;
|
|
@@ -704,7 +633,7 @@ interface ValidateOptions {
|
|
|
704
633
|
* findings in it, which is the shape a caller can render. It throws only when
|
|
705
634
|
* it was handed something it cannot open at all.
|
|
706
635
|
*/
|
|
707
|
-
declare function validatePackage(options: ValidateOptions): Report;
|
|
636
|
+
export declare function validatePackage(options: ValidateOptions): Report;
|
|
708
637
|
/**
|
|
709
638
|
* Validate, and refuse to go on if we broke something.
|
|
710
639
|
*
|
|
@@ -715,7 +644,7 @@ declare function validatePackage(options: ValidateOptions): Report;
|
|
|
715
644
|
* feedback loop that exists, and a caller who forgot to check a return value
|
|
716
645
|
* would have removed it.
|
|
717
646
|
*/
|
|
718
|
-
declare function assertValid(options: ValidateOptions): Report;
|
|
647
|
+
export declare function assertValid(options: ValidateOptions): Report;
|
|
719
648
|
//#endregion
|
|
720
|
-
export {
|
|
649
|
+
export type { Context, ContextInput, Evidence, Finding, FormatOptions, Location, Origin, ReadProblem, Report, Rule, RuleCategory, RuleId, Severity, SkippedRule, ValidateErrorCode, ValidateErrorDetail, ValidateOptions };
|
|
721
650
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/rules/rules.ts","../src/report/location.ts","../src/report/report.ts","../src/context.ts","../src/validate.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/rules/rules.ts","../src/report/location.ts","../src/report/report.ts","../src/context.ts","../src/validate.ts"],"mappings":"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"}
|