@typfolio/dev-tools 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/README.md +7 -6
- package/dist/index.d.ts +18 -15
- package/dist/index.js +21 -15
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -17,23 +17,24 @@ try {
|
|
|
17
17
|
}
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
`
|
|
20
|
+
`template` is a template made with `defineTemplate`. The check compiles only the files it declares, with each piece of data's JSON Schema at its `schemaPath`, made from its schema, so a file the template imports without declaring it fails, with what to do.
|
|
21
21
|
|
|
22
|
-
`
|
|
22
|
+
`check` also takes `assets`, the files a template reads besides its data (a logo), exactly as `compile`'s `assets`. A JSON Schema file given there at a data path is used as it is instead of one made from the schema: this is how data without a schema, or a schema without Standard JSON Schema, is checked.
|
|
23
23
|
|
|
24
|
-
`
|
|
24
|
+
`checkTemplate(template, { wasm, fonts, modes?, pdf?, assets? })` is the one-shot form that creates and disposes a checker.
|
|
25
25
|
|
|
26
|
-
`inputSchemaFiles(definitions, { toJSONSchema? })` returns the JSON Schema file of every
|
|
26
|
+
`inputSchemaFiles(definitions, { toJSONSchema? })` returns the JSON Schema file of every piece of data these templates and partials read (nested partials included), or of `{ schema, schemaPath }` pairs, by path, as JSON text. It writes nothing: a script writes the files where the editor reads them, and a test compares them, so a schema that changed without its file fails CI. Schemas that implement Standard JSON Schema (`~standard.jsonSchema`, as Zod's do) need no option; for Zod Mini, pass `toJSONSchema: schema => z.toJSONSchema(schema, { io: 'input' })`.
|
|
27
27
|
|
|
28
28
|
```ts
|
|
29
29
|
import { inputSchemaFiles } from '@typfolio/dev-tools';
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
// Every template's own schema file and each of its partials', once per path.
|
|
32
|
+
for (const [path, text] of Object.entries(inputSchemaFiles([outcomes, results]))) {
|
|
32
33
|
assert.deepEqual(JSON.parse(await readFile(new URL(path, templatesRoot), 'utf8')), JSON.parse(text), `${path} is out of date`);
|
|
33
34
|
}
|
|
34
35
|
```
|
|
35
36
|
|
|
36
|
-
A check compiles the template once per sample mode (`minimal`, then `full`) the way an editor does, so `input()` builds a sample from the JSON Schema
|
|
37
|
+
A check compiles the template once per sample mode (`minimal`, then `full`) the way an editor does, so `input()` builds a sample from the JSON Schema at each data path. A compile error is reported in that mode's result; a malformed template or option is thrown. Nothing is written to disk. See "Build-time checks" in [docs/template-authoring.md](../../docs/template-authoring.md) for the rules and a test recipe.
|
|
37
38
|
|
|
38
39
|
## `inspectPdf`
|
|
39
40
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { TypstPdfError, type
|
|
1
|
+
import { TypstPdfError, type AnyTemplate, type Assets, type CompilerOptions, type Diagnostic, type PartialDefinition, type PdfOptions, type StandardSchemaV1 } from '@typfolio/core';
|
|
2
2
|
/** Which sample `@local/typfolio`'s `input()` builds: every property, or only what the schema requires. */
|
|
3
3
|
export type SampleMode = 'minimal' | 'full';
|
|
4
4
|
export interface JSONSchemaOptions {
|
|
@@ -8,10 +8,15 @@ export interface JSONSchemaOptions {
|
|
|
8
8
|
*/
|
|
9
9
|
toJSONSchema?(schema: StandardSchemaV1): unknown;
|
|
10
10
|
}
|
|
11
|
-
|
|
11
|
+
/** A schema and the path its Typst file reads the data from, for a script that cannot import the definitions. */
|
|
12
|
+
export interface SchemaFile {
|
|
13
|
+
readonly schema: StandardSchemaV1;
|
|
14
|
+
readonly schemaPath: string;
|
|
15
|
+
}
|
|
16
|
+
type Definition = AnyTemplate | PartialDefinition | SchemaFile;
|
|
12
17
|
/**
|
|
13
18
|
* The JSON Schema file of each input of these templates, partials (nested ones included) or
|
|
14
|
-
* `
|
|
19
|
+
* `{ schema, schemaPath }` pairs, by its path, such as `common/header.schema.json`, as JSON text. Write
|
|
15
20
|
* each next to the Typst files, where its `input(json.with("./header.schema.json"))` reads it in an
|
|
16
21
|
* editor for a sample, and in a test compare the parsed files with these to catch a schema that
|
|
17
22
|
* changed without its file. An input without a schema is left out. Nothing is written here.
|
|
@@ -20,14 +25,13 @@ export declare function inputSchemaFiles(definitions: Definition | readonly Defi
|
|
|
20
25
|
export interface TemplateCheckOptions extends JSONSchemaOptions {
|
|
21
26
|
/** Defaults to `['minimal', 'full']`. Each mode is a separate compile. */
|
|
22
27
|
modes?: readonly SampleMode[];
|
|
23
|
-
/** Same options as
|
|
28
|
+
/** Same options as `compile`'s `pdf`. */
|
|
24
29
|
pdf?: PdfOptions;
|
|
25
30
|
/**
|
|
26
|
-
* Files the template reads besides its
|
|
27
|
-
*
|
|
28
|
-
* as it is instead of one made from the input's schema.
|
|
31
|
+
* Files the template reads besides its data, such as a logo: as `compile`'s `assets`. A JSON Schema
|
|
32
|
+
* file given here at a data path is used as it is, instead of one made from the schema.
|
|
29
33
|
*/
|
|
30
|
-
assets?:
|
|
34
|
+
assets?: Assets;
|
|
31
35
|
}
|
|
32
36
|
export interface TemplateCheckResult {
|
|
33
37
|
mode: SampleMode;
|
|
@@ -46,19 +50,18 @@ export interface TemplateCheckReport {
|
|
|
46
50
|
}
|
|
47
51
|
export interface TemplateChecker {
|
|
48
52
|
/**
|
|
49
|
-
* Compiles `template` once per mode in editor mode: no runtime marker, so `input()` reads the
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
* imports without declaring it fails, with what to do. A failed compile is reported in its result;
|
|
53
|
+
* Compiles `template` once per mode in editor mode: no runtime marker, so `input()` reads the JSON
|
|
54
|
+
* Schema at each data path (made from the schema, see `inputSchemaFiles`, or given in `assets`) and
|
|
55
|
+
* builds the sample. The template is compiled from the files it declares only: a file it imports
|
|
56
|
+
* without declaring it fails, with what to do. A failed compile is reported in its result;
|
|
54
57
|
* a malformed template or option rejects with `INVALID_REQUEST` or `UNSUPPORTED_OPTION`.
|
|
55
58
|
*/
|
|
56
|
-
check(template:
|
|
59
|
+
check(template: AnyTemplate, options?: TemplateCheckOptions): Promise<TemplateCheckReport>;
|
|
57
60
|
/** Stops accepting checks; waits for an accepted one and frees the compiler. */
|
|
58
61
|
dispose(): Promise<void>;
|
|
59
62
|
}
|
|
60
63
|
/** Same options as `createCompiler`. One active check per checker. */
|
|
61
64
|
export declare function createTemplateChecker(options: CompilerOptions): Promise<TemplateChecker>;
|
|
62
65
|
/** One-shot form of `createTemplateChecker`: creates a checker, runs one check, disposes it. */
|
|
63
|
-
export declare function checkTemplate(template:
|
|
66
|
+
export declare function checkTemplate(template: AnyTemplate, options: CompilerOptions & TemplateCheckOptions): Promise<TemplateCheckReport>;
|
|
64
67
|
export {};
|
package/dist/index.js
CHANGED
|
@@ -4,7 +4,7 @@ import { TypstPdfError, } from '@typfolio/core';
|
|
|
4
4
|
import { bundledPackageDirectory, createEngine, explainCompileError, initialize, isTemplateDefinition, packageFileMounts, prepareRequest, resolveFonts, } from '@typfolio/core/internal';
|
|
5
5
|
import { sampleFile, sampleSource } from './sample-source.generated.js';
|
|
6
6
|
const sampleModes = ['minimal', 'full'];
|
|
7
|
-
// Each input of these templates, partials and
|
|
7
|
+
// Each input of these templates, partials and schema files, nested partials included, once per path.
|
|
8
8
|
function inputsOf(definitions) {
|
|
9
9
|
const found = new Map();
|
|
10
10
|
const add = (path, schema) => {
|
|
@@ -20,16 +20,16 @@ function inputsOf(definitions) {
|
|
|
20
20
|
}
|
|
21
21
|
else if (definition?.kind === 'typfolio-partial') {
|
|
22
22
|
const partial = definition;
|
|
23
|
-
|
|
23
|
+
add(partial.schemaPath, partial.schema);
|
|
24
24
|
for (const nested of Object.values(partial.partials))
|
|
25
25
|
visit(nested);
|
|
26
26
|
}
|
|
27
|
-
else if (typeof definition?.
|
|
28
|
-
const
|
|
29
|
-
add(
|
|
27
|
+
else if (typeof definition?.schemaPath === 'string') {
|
|
28
|
+
const file = definition;
|
|
29
|
+
add(file.schemaPath.replace(/^\/+/, ''), file.schema);
|
|
30
30
|
}
|
|
31
31
|
else {
|
|
32
|
-
throw new TypstPdfError('INVALID_REQUEST', 'Expected a defineTemplate(...), a definePartial(...) or
|
|
32
|
+
throw new TypstPdfError('INVALID_REQUEST', 'Expected a defineTemplate(...), a definePartial(...) or { schema, schemaPath }');
|
|
33
33
|
}
|
|
34
34
|
};
|
|
35
35
|
for (const definition of definitions)
|
|
@@ -46,7 +46,7 @@ function jsonSchemaOf(schema, path, options) {
|
|
|
46
46
|
}
|
|
47
47
|
/**
|
|
48
48
|
* The JSON Schema file of each input of these templates, partials (nested ones included) or
|
|
49
|
-
* `
|
|
49
|
+
* `{ schema, schemaPath }` pairs, by its path, such as `common/header.schema.json`, as JSON text. Write
|
|
50
50
|
* each next to the Typst files, where its `input(json.with("./header.schema.json"))` reads it in an
|
|
51
51
|
* editor for a sample, and in a test compare the parsed files with these to catch a schema that
|
|
52
52
|
* changed without its file. An input without a schema is left out. Nothing is written here.
|
|
@@ -78,22 +78,29 @@ function parseOptions(options) {
|
|
|
78
78
|
throw new TypstPdfError('INVALID_REQUEST', 'toJSONSchema must be a function');
|
|
79
79
|
return { modes, pdf, assets, ...(toJSONSchema === undefined ? {} : { toJSONSchema }) };
|
|
80
80
|
}
|
|
81
|
-
// A
|
|
81
|
+
// A template as the editor sees it: its declared files, and each input's JSON Schema at the path its data is read.
|
|
82
82
|
function editorRequest(template, options) {
|
|
83
83
|
const { pdf, assets } = options;
|
|
84
84
|
if (!isTemplateDefinition(template))
|
|
85
|
-
|
|
86
|
-
|
|
85
|
+
throw new TypstPdfError('INVALID_REQUEST', 'check takes a template made with defineTemplate');
|
|
86
|
+
// A JSON Schema is JSON: mounted like data, where `input(json.with(...))` reads it in the editor branch.
|
|
87
87
|
const schemas = {};
|
|
88
|
+
const given = new Set(Object.keys(assets ?? {}).map(path => path.replace(/^\/+/, '')));
|
|
88
89
|
for (const [path, schema] of inputsOf([template])) {
|
|
89
|
-
if (
|
|
90
|
+
if (given.has(path))
|
|
90
91
|
continue;
|
|
91
92
|
if (schema === undefined) {
|
|
92
|
-
throw new TypstPdfError('INVALID_REQUEST', `The
|
|
93
|
+
throw new TypstPdfError('INVALID_REQUEST', `The data at ${path} has no schema: give its JSON Schema file in assets`);
|
|
93
94
|
}
|
|
94
|
-
schemas[path] =
|
|
95
|
+
schemas[path] = jsonSchemaOf(schema, path, options);
|
|
95
96
|
}
|
|
96
|
-
return {
|
|
97
|
+
return {
|
|
98
|
+
entrypoint: template.entrypoint,
|
|
99
|
+
files: template.files,
|
|
100
|
+
documents: schemas,
|
|
101
|
+
...(assets === undefined ? {} : { assets }),
|
|
102
|
+
...(pdf === undefined ? {} : { pdf }),
|
|
103
|
+
};
|
|
97
104
|
}
|
|
98
105
|
/** Same options as `createCompiler`. One active check per checker. */
|
|
99
106
|
export async function createTemplateChecker(options) {
|
|
@@ -114,7 +121,6 @@ export async function createTemplateChecker(options) {
|
|
|
114
121
|
if (busy)
|
|
115
122
|
throw new TypstPdfError('BUSY', 'The template checker already has an active check');
|
|
116
123
|
const { modes, ...rest } = parseOptions(checkOptions);
|
|
117
|
-
// `input: null` only fills the reserved /input.json; the editor branch never reads it.
|
|
118
124
|
const prepared = prepareRequest(editorRequest(template, rest));
|
|
119
125
|
busy = true;
|
|
120
126
|
let release;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@typfolio/dev-tools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Dev-time tools for Typfolio templates: schema-based template checks and PDF inspection (install as a devDependency)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
}
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@typfolio/core": "^0.
|
|
27
|
+
"@typfolio/core": "^0.3.0"
|
|
28
28
|
},
|
|
29
29
|
"peerDependencies": {
|
|
30
30
|
"pdfjs-dist": "^6.3.0"
|