@loculus/infer 0.0.0-stage → 0.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 toiroakr
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,108 @@
1
- # Temporary Holding Version
1
+ # @loculus/infer
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Extract the `Input` and `Output` types of [Loculus](https://github.com/toiroakr/loculus) schemas as plain TypeScript source, like [zinfer](https://github.com/toiroakr/zinfer) does for Zod.
4
+
5
+ Use it to publish readable types for an API, to check generated types into a repository that does not depend on Loculus, or to see what a schema accepts and returns.
6
+
7
+ ```bash
8
+ npm install --save-dev @loculus/infer
9
+ ```
10
+
11
+ ## CLI
12
+
13
+ ```ts
14
+ // src/query.ts
15
+ import * as l from 'loculus';
16
+
17
+ export const QuerySchema = l.object(
18
+ {
19
+ search: l.string({ trim: true, min: 1, description: 'Words to search for' }),
20
+ page: l.number({ integer: true, gte: 1, default: 1 }),
21
+ tag: l.array(l.enum(['docs', 'code']), { wrapScalar: true, optional: true }),
22
+ },
23
+ { description: 'Search query parameters' },
24
+ );
25
+ ```
26
+
27
+ ```bash
28
+ npx loculus-infer src/query.ts --suffix Schema --with-descriptions
29
+ ```
30
+
31
+ ```ts
32
+ /** Search query parameters */
33
+ export type QueryInput = {
34
+ /** Words to search for */
35
+ search: string;
36
+ page?: string | number | undefined;
37
+ tag?: 'docs' | 'code' | readonly ('docs' | 'code')[] | undefined;
38
+ };
39
+
40
+ /** Search query parameters */
41
+ export type QueryOutput = {
42
+ /** Words to search for */
43
+ search: string;
44
+ page: number;
45
+ tag?: ('docs' | 'code')[] | undefined;
46
+ };
47
+ ```
48
+
49
+ Every exported Loculus schema in the matching files is extracted. Fields keep the order of the `object()` shape.
50
+
51
+ ```
52
+ Usage: loculus-infer [options] <files...>
53
+
54
+ Options:
55
+ -p, --project <path> Path to tsconfig.json
56
+ --exclude <glob> Skip matching files (repeatable)
57
+ --schemas <names> Comma-separated schema names to extract
58
+ --input-only Emit only input types
59
+ --output-only Emit only output types
60
+ --merge-same Emit one type when input and output are identical
61
+ --suffix <suffix> Remove this suffix from schema names (e.g. Schema)
62
+ --input-suffix <suffix> Suffix for input type names (default: Input)
63
+ --output-suffix <suffix> Suffix for output type names (default: Output)
64
+ --map <mappings> Comma-separated renames (e.g. UserSchema:User)
65
+ --with-descriptions Emit description options as TSDoc comments
66
+ --outDir <dir> Write one module per source file into this directory
67
+ --outFile <file> Write all types into one module
68
+ --outPattern <pattern> File name inside outDir (default: [name].types.ts)
69
+ -d, --declaration Use .d.ts file names in outDir
70
+ --dry-run Print the files instead of writing them
71
+ --check Exit with 1 when written files are out of date
72
+ -h, --help Show this help
73
+ ```
74
+
75
+ Without `--outDir` or `--outFile`, types are printed to standard output. Use `--check` in CI to fail when generated files are out of date.
76
+
77
+ ## Library
78
+
79
+ ```ts
80
+ import { LoculusTypeExtractor, generate, renderModule } from '@loculus/infer';
81
+
82
+ const extractor = new LoculusTypeExtractor({ project: './tsconfig.json' });
83
+ const { input, output } = extractor.extract('src/query.ts', 'QuerySchema');
84
+
85
+ const schemas = extractor.extractAll('src/query.ts', { withDescriptions: true });
86
+ const source = renderModule(schemas, { suffix: 'Schema', mergeSame: true });
87
+
88
+ const { files } = await generate({ include: ['src/**/*.ts'], outDir: 'types' });
89
+ ```
90
+
91
+ ## How types are printed
92
+
93
+ - Types come from the TypeScript compiler, so they match `l.Input<typeof schema>` and `l.Output<typeof schema>`. The tests check this with type-level equality.
94
+ - Object types, intersections and Loculus helper types such as `ObjectInput` are written out in full.
95
+ - Named interfaces and classes stay as references, such as `Date`, `URL` or an interface returned by `transform()`. The generated module imports exported types from their own modules. A type that is not exported produces a warning.
96
+ - `--with-descriptions` reads `description` options written as string literals, including fields of nested `object()` shapes and array rows. Descriptions computed at runtime are not read. After `unflatten()`, only the input type gets field comments, because the output keys are restructured.
97
+
98
+ The extractor uses the tsconfig.json given by `--project`, or the nearest one above the working directory. Without one, it uses strict NodeNext settings.
99
+
100
+ ## License
101
+
102
+ MIT
103
+
104
+ ## Type-checking cost
105
+
106
+ `pnpm bench:infer` in the repository compares a consumer that uses `l.Input` / `l.Output` with one that imports the generated types. It uses the twelve benchmark fixtures (each copied 20 times by default, `COPIES` to change) and reports `tsc --extendedDiagnostics`.
107
+
108
+ With TypeScript 7.0.2 and 240 schemas, the generated types needed 64 instantiations instead of 71,359 (schemas + inference), about a sixth of the check time and less memory.
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../dist/cli.js';
3
+
4
+ main().then(
5
+ (code) => {
6
+ process.exitCode = code;
7
+ },
8
+ (error) => {
9
+ process.stderr.write(`loculus-infer: ${error instanceof Error ? error.message : String(error)}\n`);
10
+ process.exitCode = 1;
11
+ },
12
+ );
package/dist/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ //#region src/cli.d.ts
2
+ export declare function main(argv?: readonly string[]): Promise<number>;
3
+ //#endregion
package/dist/cli.js ADDED
@@ -0,0 +1,133 @@
1
+ import { n as findOutdated, r as generate } from "./generate-ncDNvye5.js";
2
+ import { dirname, relative } from "node:path";
3
+ import { mkdir, rm, writeFile } from "node:fs/promises";
4
+ import { parseArgs } from "node:util";
5
+ //#region src/cli.ts
6
+ const help = `Usage: loculus-infer [options] <files...>
7
+
8
+ Extract Input/Output types from exported Loculus schemas.
9
+
10
+ Options:
11
+ -p, --project <path> Path to tsconfig.json
12
+ --exclude <glob> Skip matching files (repeatable)
13
+ --schemas <names> Comma-separated schema names to extract
14
+ --input-only Emit only input types
15
+ --output-only Emit only output types
16
+ --merge-same Emit one type when input and output are identical
17
+ --suffix <suffix> Remove this suffix from schema names (e.g. Schema)
18
+ --input-suffix <suffix> Suffix for input type names (default: Input)
19
+ --output-suffix <suffix> Suffix for output type names (default: Output)
20
+ --map <mappings> Comma-separated renames (e.g. UserSchema:User)
21
+ --with-descriptions Emit description options as TSDoc comments
22
+ --outDir <dir> Write one module per source file into this directory
23
+ --outFile <file> Write all types into one module
24
+ --outPattern <pattern> File name inside outDir (default: [name].types.ts)
25
+ -d, --declaration Use .d.ts file names in outDir
26
+ --dry-run Print the files instead of writing them
27
+ --check Exit with 1 when written files are out of date
28
+ -h, --help Show this help
29
+ `;
30
+ async function main(argv = process.argv.slice(2)) {
31
+ const { values, positionals } = parseArgs({
32
+ args: [...argv],
33
+ allowPositionals: true,
34
+ options: {
35
+ project: {
36
+ type: "string",
37
+ short: "p"
38
+ },
39
+ exclude: {
40
+ type: "string",
41
+ multiple: true
42
+ },
43
+ schemas: { type: "string" },
44
+ "input-only": { type: "boolean" },
45
+ "output-only": { type: "boolean" },
46
+ "merge-same": { type: "boolean" },
47
+ suffix: { type: "string" },
48
+ "input-suffix": { type: "string" },
49
+ "output-suffix": { type: "string" },
50
+ map: { type: "string" },
51
+ "with-descriptions": { type: "boolean" },
52
+ outDir: { type: "string" },
53
+ outFile: { type: "string" },
54
+ outPattern: { type: "string" },
55
+ declaration: {
56
+ type: "boolean",
57
+ short: "d"
58
+ },
59
+ "dry-run": { type: "boolean" },
60
+ check: { type: "boolean" },
61
+ help: {
62
+ type: "boolean",
63
+ short: "h"
64
+ }
65
+ }
66
+ });
67
+ if (values.help) {
68
+ process.stdout.write(help);
69
+ return 0;
70
+ }
71
+ if (positionals.length === 0) {
72
+ process.stderr.write(help);
73
+ return 2;
74
+ }
75
+ const options = {
76
+ include: positionals,
77
+ ...values.exclude && { exclude: values.exclude },
78
+ ...values.project && { project: values.project },
79
+ ...values.schemas && { schemas: list(values.schemas) },
80
+ ...values.map && { map: parseMap(values.map) },
81
+ ...values.suffix && { suffix: values.suffix },
82
+ ...values["input-suffix"] !== void 0 && { inputSuffix: values["input-suffix"] },
83
+ ...values["output-suffix"] !== void 0 && { outputSuffix: values["output-suffix"] },
84
+ ...values.outDir && { outDir: values.outDir },
85
+ ...values.outFile && { outFile: values.outFile },
86
+ ...values.outPattern && { outPattern: values.outPattern },
87
+ inputOnly: values["input-only"] ?? false,
88
+ outputOnly: values["output-only"] ?? false,
89
+ mergeSame: values["merge-same"] ?? false,
90
+ withDescriptions: values["with-descriptions"] ?? false,
91
+ declaration: values.declaration ?? false
92
+ };
93
+ if (values.check && !values.outDir && !values.outFile) throw new Error("--check needs --outDir or --outFile");
94
+ const { files, warnings } = await generate(options);
95
+ for (const warning of warnings) process.stderr.write(`warning: ${warning}\n`);
96
+ if (values.check) {
97
+ const outdated = await findOutdated(files);
98
+ for (const file of outdated) process.stderr.write(`out of date: ${relative(process.cwd(), file.path)}\n`);
99
+ return outdated.length ? 1 : 0;
100
+ }
101
+ const print = values["dry-run"] || files.every((file) => !file.path);
102
+ for (const [index, file] of files.entries()) if (file.obsolete) {
103
+ if (print) process.stdout.write(`${index ? "\n" : ""}// delete ${relative(process.cwd(), file.path)}\n`);
104
+ else {
105
+ await rm(file.path);
106
+ process.stderr.write(`deleted ${relative(process.cwd(), file.path)}\n`);
107
+ }
108
+ } else if (print) {
109
+ const label = file.path ?? file.sources[0];
110
+ if (files.length > 1 || file.path) process.stdout.write(`${index ? "\n" : ""}// ${relative(process.cwd(), label)}\n`);
111
+ process.stdout.write(file.content);
112
+ } else {
113
+ await mkdir(dirname(file.path), { recursive: true });
114
+ await writeFile(file.path, file.content);
115
+ process.stderr.write(`wrote ${relative(process.cwd(), file.path)}\n`);
116
+ }
117
+ if (files.length === 0) process.stderr.write("No exported Loculus schemas found.\n");
118
+ return 0;
119
+ }
120
+ function list(value) {
121
+ return value.split(",").map((item) => item.trim()).filter(Boolean);
122
+ }
123
+ function parseMap(value) {
124
+ const map = {};
125
+ for (const entry of list(value)) {
126
+ const [from, to, extra] = entry.split(":").map((part) => part.trim());
127
+ if (!from || !to || extra !== void 0) throw new Error(`Invalid mapping "${entry}"; expected Schema:Type`);
128
+ map[from] = to;
129
+ }
130
+ return map;
131
+ }
132
+ //#endregion
133
+ export { main };
@@ -0,0 +1,672 @@
1
+ import { existsSync } from "node:fs";
2
+ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
3
+ import { Node, Project, SyntaxKind, ts } from "ts-morph";
4
+ import { readFile } from "node:fs/promises";
5
+ import { glob } from "tinyglobby";
6
+ //#region src/descriptions.ts
7
+ const wrappers = /* @__PURE__ */ new Set([
8
+ "transform",
9
+ "refine",
10
+ "unflatten"
11
+ ]);
12
+ /**
13
+ * Statically reads `description` options from a schema expression such as
14
+ * `l.object({ name: l.string({ description: '...' }) }, { description: '...' })`.
15
+ * Only string literals are read; anything else is ignored.
16
+ */
17
+ function readDescriptions(expression, seen = /* @__PURE__ */ new Set()) {
18
+ const node = expression && unwrap(expression);
19
+ if (!node || seen.has(node)) return {};
20
+ seen.add(node);
21
+ if (Node.isIdentifier(node)) {
22
+ const declaration = (node.getSymbol()?.getAliasedSymbol() ?? node.getSymbol())?.getValueDeclaration();
23
+ return Node.isVariableDeclaration(declaration) ? readDescriptions(declaration.getInitializer(), seen) : {};
24
+ }
25
+ if (!Node.isCallExpression(node)) return {};
26
+ const callee = node.getExpression();
27
+ const name = Node.isPropertyAccessExpression(callee) ? callee.getName() : Node.isIdentifier(callee) ? callee.getText() : "";
28
+ const args = node.getArguments();
29
+ if (wrappers.has(name)) {
30
+ const inner = readDescriptions(args[0], seen);
31
+ const options = name === "unflatten" ? void 0 : readOwnDescription(args.slice(1));
32
+ return {
33
+ ...inner,
34
+ ...options === void 0 ? {} : { description: options },
35
+ ...name === "unflatten" ? { inputOnlyFields: true } : {}
36
+ };
37
+ }
38
+ const tree = {};
39
+ if (name === "object" && args[0] && Node.isObjectLiteralExpression(unwrap(args[0]))) {
40
+ tree.fields = readShape(unwrap(args[0]), seen);
41
+ const description = readOwnDescription(args.slice(1));
42
+ if (description !== void 0) tree.description = description;
43
+ return tree;
44
+ }
45
+ if (name === "array") {
46
+ const element = readDescriptions(args[0], seen);
47
+ if (element.fields) tree.element = element;
48
+ const description = readOwnDescription(args.slice(1));
49
+ if (description !== void 0) tree.description = description;
50
+ return tree;
51
+ }
52
+ const description = readOwnDescription(args);
53
+ if (description !== void 0) tree.description = description;
54
+ return tree;
55
+ }
56
+ function readShape(shape, seen) {
57
+ const fields = /* @__PURE__ */ new Map();
58
+ for (const property of shape.getProperties()) if (Node.isPropertyAssignment(property)) {
59
+ const key = propertyKey(property.getNameNode());
60
+ if (key !== void 0) fields.set(key, readDescriptions(property.getInitializer(), new Set(seen)));
61
+ } else if (Node.isShorthandPropertyAssignment(property)) fields.set(property.getName(), readDescriptions(property.getNameNode(), new Set(seen)));
62
+ return fields;
63
+ }
64
+ function readOwnDescription(args) {
65
+ for (const arg of args) {
66
+ const node = unwrap(arg);
67
+ if (!Node.isObjectLiteralExpression(node)) continue;
68
+ const property = node.getProperty("description");
69
+ if (!Node.isPropertyAssignment(property)) continue;
70
+ const value = property.getInitializer() && unwrap(property.getInitializerOrThrow());
71
+ if (Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value)) return value.getLiteralValue();
72
+ }
73
+ }
74
+ function propertyKey(name) {
75
+ if (Node.isIdentifier(name) || Node.isPrivateIdentifier(name)) return name.getText();
76
+ if (Node.isStringLiteral(name) || Node.isNoSubstitutionTemplateLiteral(name) || Node.isNumericLiteral(name)) return name.getLiteralText();
77
+ if (Node.isComputedPropertyName(name)) {
78
+ const inner = unwrap(name.getExpression());
79
+ if (Node.isStringLiteral(inner) || Node.isNoSubstitutionTemplateLiteral(inner)) return inner.getLiteralValue();
80
+ }
81
+ }
82
+ function unwrap(node) {
83
+ let current = node;
84
+ while (current.isKind(SyntaxKind.ParenthesizedExpression) || current.isKind(SyntaxKind.AsExpression) || current.isKind(SyntaxKind.SatisfiesExpression) || current.isKind(SyntaxKind.NonNullExpression)) current = current.getExpression();
85
+ return current;
86
+ }
87
+ //#endregion
88
+ //#region src/extractor.ts
89
+ const builderFlags = ts.NodeBuilderFlags.NoTruncation | ts.NodeBuilderFlags.InTypeAlias | ts.NodeBuilderFlags.MultilineObjectLiterals;
90
+ const docMarker = /^([ \t]*)\/\*\*__LOCULUS_DOC_(\d+)__\*\/\n/gm;
91
+ /** Reads `Input` and `Output` types of exported Loculus schemas with the TypeScript compiler. */
92
+ var LoculusTypeExtractor = class {
93
+ #project;
94
+ #cwd;
95
+ constructor(options = {}) {
96
+ this.#cwd = resolve(options.cwd ?? process.cwd());
97
+ const tsConfigFilePath = options.project ? resolve(this.#cwd, options.project) : findTsConfig(this.#cwd);
98
+ this.#project = tsConfigFilePath ? new Project({
99
+ tsConfigFilePath,
100
+ skipAddingFilesFromTsConfig: true
101
+ }) : new Project({ compilerOptions: {
102
+ strict: true,
103
+ target: ts.ScriptTarget.ES2022,
104
+ module: ts.ModuleKind.NodeNext,
105
+ moduleResolution: ts.ModuleResolutionKind.NodeNext,
106
+ skipLibCheck: true
107
+ } });
108
+ }
109
+ /** Lists exported Loculus schema names in a file. */
110
+ listSchemas(filePath) {
111
+ return this.#candidates(this.#sourceFile(filePath)).map((candidate) => candidate.exportName);
112
+ }
113
+ /** Extracts every exported Loculus schema in a file, in declaration order. */
114
+ extractAll(filePath, options = {}) {
115
+ const sourceFile = this.#sourceFile(filePath);
116
+ let candidates = this.#candidates(sourceFile);
117
+ if (options.schemas) {
118
+ const wanted = new Set(options.schemas);
119
+ candidates = candidates.filter((candidate) => wanted.has(candidate.exportName));
120
+ }
121
+ if (candidates.length === 0) return [];
122
+ const scope = scopeOf(sourceFile);
123
+ return candidates.map(({ exportName, declaration }) => {
124
+ const tree = options.withDescriptions ? readDescriptions(declaration.getInitializer()) : {};
125
+ const inputReferences = new References(sourceFile, scope);
126
+ const outputReferences = new References(sourceFile, scope);
127
+ const schemaType = declaration.getType().compilerType;
128
+ const order = this.#shapeOrder(schemaType, declaration.compilerNode);
129
+ const input = this.#print(declaration, schemaType, "_input", tree, order, false, inputReferences);
130
+ const output = this.#print(declaration, schemaType, "_output", tree, order, true, outputReferences);
131
+ const description = options.withDescriptions ? tree.description : void 0;
132
+ return {
133
+ schemaName: exportName,
134
+ filePath: sourceFile.getFilePath(),
135
+ input,
136
+ output,
137
+ ...description === void 0 ? {} : { description },
138
+ imports: inputReferences.merge(outputReferences),
139
+ inputImports: inputReferences.imports(),
140
+ outputImports: outputReferences.imports(),
141
+ warnings: [.../* @__PURE__ */ new Set([...inputReferences.warnings, ...outputReferences.warnings])]
142
+ };
143
+ });
144
+ }
145
+ /** Extracts one exported Loculus schema. Throws when it is not found. */
146
+ extract(filePath, schemaName, options = {}) {
147
+ const [result] = this.extractAll(filePath, {
148
+ ...options,
149
+ schemas: [schemaName]
150
+ });
151
+ if (!result) throw new Error(`Loculus schema "${schemaName}" is not exported from ${filePath}`);
152
+ return result;
153
+ }
154
+ /** Loads several files before extraction so their dependencies are resolved once, not per file. */
155
+ addSourceFiles(filePaths) {
156
+ let added = false;
157
+ for (const filePath of filePaths) {
158
+ const absolute = resolve(this.#cwd, filePath);
159
+ if (this.#project.getSourceFile(absolute)) continue;
160
+ this.#project.addSourceFileAtPath(absolute);
161
+ added = true;
162
+ }
163
+ if (added) this.#project.resolveSourceFileDependencies();
164
+ }
165
+ #sourceFile(filePath) {
166
+ this.addSourceFiles([filePath]);
167
+ return this.#project.getSourceFileOrThrow(resolve(this.#cwd, filePath));
168
+ }
169
+ #candidates(sourceFile) {
170
+ const candidates = [];
171
+ for (const [exportName, declarations] of sourceFile.getExportedDeclarations()) {
172
+ if (exportName === "default") continue;
173
+ for (const declaration of declarations) if (Node.isVariableDeclaration(declaration) && declaration.getSourceFile() === sourceFile && isLoculusSchema(declaration.getType(), declaration)) candidates.push({
174
+ exportName,
175
+ declaration
176
+ });
177
+ }
178
+ return candidates.sort((a, b) => a.declaration.getStart() - b.declaration.getStart());
179
+ }
180
+ /** Field order of `object()` shapes, which the printed intersection types do not keep. */
181
+ #shapeOrder(type, location, depth = 0) {
182
+ const checker = this.#project.getTypeChecker().compilerObject;
183
+ const shape = type.getProperty("shape");
184
+ if (!shape || depth > 32) return void 0;
185
+ const fields = /* @__PURE__ */ new Map();
186
+ for (const property of checker.getTypeOfSymbolAtLocation(shape, location).getProperties()) fields.set(property.getName(), this.#shapeOrder(checker.getTypeOfSymbolAtLocation(property, location), location, depth + 1));
187
+ return fields;
188
+ }
189
+ #print(declaration, schemaType, marker, tree, order, output, references) {
190
+ const checker = this.#project.getTypeChecker().compilerObject;
191
+ const location = declaration.compilerNode;
192
+ const property = schemaType.getProperty(marker);
193
+ if (!property) throw new Error(`${declaration.getName()} has no ${marker} type`);
194
+ const node = reorder(new TypeNodeBuilder(checker, location).build(checker.getTypeOfSymbolAtLocation(property, location)), order);
195
+ const docs = [];
196
+ annotate(node, tree, output, docs);
197
+ references.collect(node);
198
+ let text = ts.createPrinter({
199
+ newLine: ts.NewLineKind.LineFeed,
200
+ removeComments: false
201
+ }).printNode(ts.EmitHint.Unspecified, node, declaration.getSourceFile().compilerNode);
202
+ text = text.replace(/^( {4})+/gm, (indent) => " ".repeat(indent.length / 2));
203
+ text = references.replaceImportTypes(text);
204
+ return text.replace(docMarker, (_, indent, index) => formatDoc(docs[Number(index)], indent));
205
+ }
206
+ };
207
+ /**
208
+ * Builds a type node that spells out anonymous object types, intersections and
209
+ * helper aliases such as `ObjectInput`, while keeping named interfaces and
210
+ * classes (`Date`, `URL`, user interfaces) as references.
211
+ */
212
+ var TypeNodeBuilder = class {
213
+ #checker;
214
+ #location;
215
+ #visiting = /* @__PURE__ */ new Set();
216
+ constructor(checker, location) {
217
+ this.#checker = checker;
218
+ this.#location = location;
219
+ }
220
+ build(type) {
221
+ if (!this.#needsExpansion(type, /* @__PURE__ */ new Set())) return this.#reference(type);
222
+ if (this.#visiting.has(type)) return this.#reference(type);
223
+ this.#visiting.add(type);
224
+ try {
225
+ return this.#expand(type);
226
+ } finally {
227
+ this.#visiting.delete(type);
228
+ }
229
+ }
230
+ #expand(type) {
231
+ const checker = this.#checker;
232
+ const { factory } = ts;
233
+ if (type.isUnion()) {
234
+ const members = [];
235
+ const booleans = type.types.filter((member) => member.flags & ts.TypeFlags.BooleanLiteral);
236
+ const nullish = (member) => member.flags & ts.TypeFlags.Undefined ? 2 : member.flags & ts.TypeFlags.Null ? 1 : 0;
237
+ const absorbed = (member) => member.isIntersection() && member.types.some((part) => type.types.includes(part));
238
+ for (const member of [...type.types].filter((member) => !absorbed(member)).sort((a, b) => nullish(a) - nullish(b))) {
239
+ if (member.flags & ts.TypeFlags.BooleanLiteral && booleans.length === 2) {
240
+ if (member === booleans[0]) members.push(factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword));
241
+ continue;
242
+ }
243
+ const node = this.build(member);
244
+ members.push(ts.isFunctionTypeNode(node) || ts.isConstructorTypeNode(node) || ts.isConditionalTypeNode(node) ? factory.createParenthesizedType(node) : node);
245
+ }
246
+ return factory.createUnionTypeNode(members);
247
+ }
248
+ if (type.isIntersection() && type.types.some((part) => !(part.flags & ts.TypeFlags.Object))) return factory.createIntersectionTypeNode(type.types.map((part) => {
249
+ const node = this.build(part);
250
+ return ts.isUnionTypeNode(node) || ts.isFunctionTypeNode(node) ? factory.createParenthesizedType(node) : node;
251
+ }));
252
+ if (checker.isArrayType(type)) {
253
+ const [element] = checker.getTypeArguments(type);
254
+ let node = this.build(element);
255
+ if (ts.isUnionTypeNode(node) || ts.isIntersectionTypeNode(node) || ts.isFunctionTypeNode(node) || ts.isConditionalTypeNode(node)) node = factory.createParenthesizedType(node);
256
+ const array = factory.createArrayTypeNode(node);
257
+ return isReadonlyArray(type) ? factory.createTypeOperatorNode(ts.SyntaxKind.ReadonlyKeyword, array) : array;
258
+ }
259
+ if (checker.isTupleType(type)) {
260
+ const target = type.target;
261
+ const elements = checker.getTypeArguments(type).map((element, index) => {
262
+ const flags = target.elementFlags[index];
263
+ const node = this.build(element);
264
+ if (flags & ts.ElementFlags.Rest) return factory.createRestTypeNode(factory.createArrayTypeNode(node));
265
+ return flags & ts.ElementFlags.Optional ? factory.createOptionalTypeNode(node) : node;
266
+ });
267
+ const tuple = factory.createTupleTypeNode(elements);
268
+ return target.readonly ? factory.createTypeOperatorNode(ts.SyntaxKind.ReadonlyKeyword, tuple) : tuple;
269
+ }
270
+ const properties = checker.getPropertiesOfType(type);
271
+ if (properties.some((property) => String(property.escapedName).startsWith("__@"))) return this.#reference(type);
272
+ const members = properties.map((property) => {
273
+ const propertyType = checker.getTypeOfSymbolAtLocation(property, this.#location);
274
+ return factory.createPropertySignature(isReadonlyProperty(property) ? [factory.createModifier(ts.SyntaxKind.ReadonlyKeyword)] : void 0, propertyName(property.getName()), property.flags & ts.SymbolFlags.Optional ? factory.createToken(ts.SyntaxKind.QuestionToken) : void 0, this.build(propertyType));
275
+ });
276
+ const indexInfos = checker.getIndexInfosOfType(type).map((info) => factory.createIndexSignature(info.isReadonly ? [factory.createModifier(ts.SyntaxKind.ReadonlyKeyword)] : void 0, [factory.createParameterDeclaration(void 0, void 0, "key", void 0, this.#reference(info.keyType))], this.build(info.type)));
277
+ return factory.createTypeLiteralNode([...indexInfos, ...members]);
278
+ }
279
+ /** Whether the type contains an anonymous object or intersection the compiler would print by alias. */
280
+ #needsExpansion(type, seen) {
281
+ if (seen.has(type)) return false;
282
+ seen.add(type);
283
+ if (type.getCallSignatures().length || type.getConstructSignatures().length) return false;
284
+ if (type.aliasSymbol && type.flags & (ts.TypeFlags.Object | ts.TypeFlags.UnionOrIntersection)) return true;
285
+ if (type.isUnion()) return type.types.some((member) => this.#needsExpansion(member, seen));
286
+ if (type.isIntersection()) return true;
287
+ if (this.#checker.isArrayType(type) || this.#checker.isTupleType(type)) return this.#checker.getTypeArguments(type).some((member) => this.#needsExpansion(member, seen));
288
+ if (!(type.flags & ts.TypeFlags.Object)) return false;
289
+ return !isNamed(type);
290
+ }
291
+ #reference(type) {
292
+ const node = this.#checker.typeToTypeNode(type, this.#location, builderFlags);
293
+ if (!node) throw new Error(`Cannot print type ${this.#checker.typeToString(type)}`);
294
+ return node;
295
+ }
296
+ };
297
+ function leftmost(name) {
298
+ while (ts.isQualifiedName(name)) name = name.left;
299
+ return name.text;
300
+ }
301
+ function isNamed(type) {
302
+ const symbol = type.getSymbol();
303
+ return symbol !== void 0 && (symbol.flags & (ts.SymbolFlags.Class | ts.SymbolFlags.Interface | ts.SymbolFlags.Enum)) !== 0;
304
+ }
305
+ const readonlyCheckFlag = 8;
306
+ function isReadonlyProperty(property) {
307
+ if ((property.links?.checkFlags ?? 0) & readonlyCheckFlag) return true;
308
+ const declaration = property.valueDeclaration ?? property.declarations?.[0];
309
+ return declaration !== void 0 && (ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Readonly) !== 0;
310
+ }
311
+ function isReadonlyArray(type) {
312
+ return type.target?.getSymbol()?.getName() === "ReadonlyArray";
313
+ }
314
+ function propertyName(name) {
315
+ return /^[A-Za-z_$][\w$]*$/.test(name) ? ts.factory.createIdentifier(name) : ts.factory.createStringLiteral(name);
316
+ }
317
+ function isLoculusSchema(type, node) {
318
+ const standard = type.getProperty("~standard");
319
+ if (!standard || !type.getProperty("_input") || !type.getProperty("_output")) return false;
320
+ const vendor = standard.getTypeAtLocation(node).getProperty("vendor")?.getTypeAtLocation(node);
321
+ return vendor?.isStringLiteral() === true && vendor.getLiteralValue() === "loculus";
322
+ }
323
+ function findTsConfig(from) {
324
+ for (let directory = from;; directory = dirname(directory)) {
325
+ const candidate = join(directory, "tsconfig.json");
326
+ if (existsSync(candidate)) return candidate;
327
+ if (dirname(directory) === directory) return void 0;
328
+ }
329
+ }
330
+ function memberName(member) {
331
+ const name = member.name;
332
+ return name && (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) ? name.text : void 0;
333
+ }
334
+ function reorder(node, order) {
335
+ if (!order) return node;
336
+ if (ts.isUnionTypeNode(node)) return ts.factory.updateUnionTypeNode(node, ts.factory.createNodeArray(node.types.map((type) => reorder(type, order))));
337
+ if (ts.isParenthesizedTypeNode(node)) return ts.factory.updateParenthesizedType(node, reorder(node.type, order));
338
+ if (!ts.isTypeLiteralNode(node)) return node;
339
+ const keys = [...order.keys()];
340
+ const rank = (member) => {
341
+ const index = keys.indexOf(memberName(member) ?? "");
342
+ return index === -1 ? keys.length : index;
343
+ };
344
+ const members = node.members.map((member, index) => {
345
+ const child = order.get(memberName(member) ?? "");
346
+ return {
347
+ member: child && ts.isPropertySignature(member) && member.type ? ts.factory.updatePropertySignature(member, member.modifiers, member.name, member.questionToken, reorder(member.type, child)) : member,
348
+ rank: rank(member),
349
+ index
350
+ };
351
+ });
352
+ members.sort((a, b) => a.rank - b.rank || a.index - b.index);
353
+ return ts.factory.updateTypeLiteralNode(node, ts.factory.createNodeArray(members.map((entry) => entry.member)));
354
+ }
355
+ function annotate(node, tree, output, docs) {
356
+ if (tree.inputOnlyFields && output) return;
357
+ if (ts.isTypeOperatorNode(node)) return annotate(node.type, tree, output, docs);
358
+ if (ts.isArrayTypeNode(node)) {
359
+ if (tree.element) annotate(node.elementType, tree.element, output, docs);
360
+ return;
361
+ }
362
+ if (ts.isParenthesizedTypeNode(node)) return annotate(node.type, tree, output, docs);
363
+ if (ts.isUnionTypeNode(node)) {
364
+ for (const member of node.types) annotate(member, tree, output, docs);
365
+ return;
366
+ }
367
+ if (!ts.isTypeLiteralNode(node) || !tree.fields) return;
368
+ for (const member of node.members) {
369
+ if (!ts.isPropertySignature(member)) continue;
370
+ const name = memberName(member);
371
+ const field = name === void 0 ? void 0 : tree.fields.get(name);
372
+ if (!field) continue;
373
+ if (field.description !== void 0) {
374
+ ts.addSyntheticLeadingComment(member, ts.SyntaxKind.MultiLineCommentTrivia, `*__LOCULUS_DOC_${docs.length}__`, true);
375
+ docs.push(field.description);
376
+ }
377
+ if (member.type) annotate(member.type, field, output, docs);
378
+ }
379
+ }
380
+ /** Formats a TSDoc comment at the given indentation, ending with a newline. */
381
+ function formatDoc(description, indent = "") {
382
+ const lines = description.replaceAll("*/", "*\\/").split(/\r?\n/);
383
+ if (lines.length === 1) return `${indent}/** ${lines[0]} */\n`;
384
+ return `${indent}/**\n${lines.map((line) => `${indent} *${line ? ` ${line}` : ""}`).join("\n")}\n${indent} */\n`;
385
+ }
386
+ function scopeOf(sourceFile) {
387
+ return new Map(sourceFile.getProject().getTypeChecker().getSymbolsInScope(sourceFile, ts.SymbolFlags.Type | ts.SymbolFlags.Value | ts.SymbolFlags.Namespace | ts.SymbolFlags.Alias).map((symbol) => [symbol.getName(), symbol]));
388
+ }
389
+ /** Tracks named types referenced by printed type nodes. */
390
+ var References = class References {
391
+ warnings = [];
392
+ #sourceFile;
393
+ #scope;
394
+ #imports = /* @__PURE__ */ new Map();
395
+ constructor(sourceFile, scope) {
396
+ this.#sourceFile = sourceFile;
397
+ this.#scope = scope;
398
+ }
399
+ imports() {
400
+ return [...this.#imports.values()];
401
+ }
402
+ /** The imports of both, rejecting one name bound to different types. */
403
+ merge(other) {
404
+ const merged = new References(this.#sourceFile, this.#scope);
405
+ for (const entry of [...this.imports(), ...other.imports()]) merged.#record(entry);
406
+ return merged.imports();
407
+ }
408
+ collect(node) {
409
+ if (ts.isTypeReferenceNode(node)) this.#add(leftmost(node.typeName));
410
+ else if (ts.isTypeQueryNode(node)) this.#add(leftmost(node.exprName));
411
+ else if (ts.isComputedPropertyName(node)) {
412
+ let expression = node.expression;
413
+ while (ts.isPropertyAccessExpression(expression)) expression = expression.expression;
414
+ if (ts.isIdentifier(expression)) this.#add(expression.text);
415
+ }
416
+ ts.forEachChild(node, (child) => this.collect(child));
417
+ }
418
+ /** Replaces `import("./module").Name` with `Name` and records the import. */
419
+ replaceImportTypes(text) {
420
+ return text.replace(/import\("([^"]+)"\)\.([A-Za-z_$][\w$]*)/g, (_, specifier, name) => {
421
+ const from = specifier.startsWith(".") || isAbsolute(specifier) ? this.#resolveModule(specifier) : specifier;
422
+ this.#record({
423
+ name,
424
+ importedName: name,
425
+ from
426
+ });
427
+ return name;
428
+ });
429
+ }
430
+ #resolveModule(specifier) {
431
+ return ts.resolveModuleName(specifier, this.#sourceFile.getFilePath(), this.#sourceFile.getProject().getCompilerOptions(), ts.sys).resolvedModule?.resolvedFileName ?? resolve(this.#sourceFile.getDirectoryPath(), specifier);
432
+ }
433
+ #add(name) {
434
+ if (this.#imports.has(name)) return;
435
+ const symbol = this.#scope.get(name);
436
+ if (!symbol) return;
437
+ const declaration = symbol.getDeclarations()[0];
438
+ if (!declaration) return;
439
+ if (Node.isImportSpecifier(declaration)) {
440
+ const importDeclaration = declaration.getImportDeclaration();
441
+ this.#record({
442
+ name,
443
+ importedName: declaration.getName(),
444
+ from: this.#moduleOf(importDeclaration)
445
+ });
446
+ } else if (Node.isImportClause(declaration)) {
447
+ const importDeclaration = declaration.getParent();
448
+ if (Node.isImportDeclaration(importDeclaration)) this.#record({
449
+ name,
450
+ importedName: "default",
451
+ from: this.#moduleOf(importDeclaration)
452
+ });
453
+ } else if (Node.isNamespaceImport(declaration)) this.#record({
454
+ name,
455
+ importedName: "*",
456
+ from: this.#moduleOf(declaration.getFirstAncestorByKindOrThrow(SyntaxKind.ImportDeclaration))
457
+ });
458
+ else if (declaration.getSourceFile() === this.#sourceFile) {
459
+ const exported = [...this.#sourceFile.getExportedDeclarations()].find(([, nodes]) => nodes.includes(declaration));
460
+ if (exported) this.#record({
461
+ name,
462
+ importedName: exported[0],
463
+ from: this.#sourceFile.getFilePath()
464
+ });
465
+ else this.warnings.push(`"${name}" is used by a schema type but is not exported from ${this.#sourceFile.getFilePath()}`);
466
+ }
467
+ }
468
+ #moduleOf(importDeclaration) {
469
+ const specifier = importDeclaration.getModuleSpecifierValue();
470
+ if (!specifier.startsWith(".") && !isAbsolute(specifier)) return specifier;
471
+ return importDeclaration.getModuleSpecifierSourceFile()?.getFilePath() ?? resolve(this.#sourceFile.getDirectoryPath(), specifier);
472
+ }
473
+ #record(entry) {
474
+ const existing = this.#imports.get(entry.name);
475
+ if (!existing) this.#imports.set(entry.name, entry);
476
+ else if (existing.from !== entry.from || existing.importedName !== entry.importedName) throw new Error(`"${entry.name}" refers to different types from ${existing.from} and ${entry.from}; rename one of them`);
477
+ }
478
+ };
479
+ //#endregion
480
+ //#region src/format.ts
481
+ /** Decides the exported type declarations for extracted schemas. */
482
+ function formatTypes(schemas, options = {}) {
483
+ if (options.inputOnly && options.outputOnly) throw new Error("inputOnly and outputOnly cannot be combined");
484
+ const types = [];
485
+ for (const schema of schemas) {
486
+ const base = baseName(schema.schemaName, options);
487
+ const common = {
488
+ schemaName: schema.schemaName,
489
+ ...schema.description === void 0 ? {} : { description: schema.description }
490
+ };
491
+ if (options.mergeSame && !options.inputOnly && !options.outputOnly && schema.input === schema.output) {
492
+ types.push({
493
+ ...common,
494
+ name: base,
495
+ kind: "merged",
496
+ text: schema.input
497
+ });
498
+ continue;
499
+ }
500
+ if (!options.outputOnly) types.push({
501
+ ...common,
502
+ name: base + (options.inputSuffix ?? "Input"),
503
+ kind: "input",
504
+ text: schema.input
505
+ });
506
+ if (!options.inputOnly) types.push({
507
+ ...common,
508
+ name: base + (options.outputSuffix ?? "Output"),
509
+ kind: "output",
510
+ text: schema.output
511
+ });
512
+ }
513
+ const seen = /* @__PURE__ */ new Map();
514
+ for (const type of types) {
515
+ const previous = seen.get(type.name);
516
+ if (previous !== void 0) throw new Error(`Type name "${type.name}" is generated for both ${previous} and ${type.schemaName}`);
517
+ seen.set(type.name, type.schemaName);
518
+ }
519
+ return types;
520
+ }
521
+ function baseName(schemaName, options) {
522
+ const mapped = options.map?.[schemaName];
523
+ if (mapped !== void 0) return mapped;
524
+ const { suffix } = options;
525
+ return suffix && schemaName.endsWith(suffix) && schemaName.length > suffix.length ? schemaName.slice(0, -suffix.length) : schemaName;
526
+ }
527
+ /** Renders extracted schemas as a TypeScript module. */
528
+ function renderModule(schemas, options = {}) {
529
+ const types = formatTypes(schemas, options);
530
+ const directory = options.outFile ? dirname(options.outFile) : options.cwd ?? process.cwd();
531
+ const imports = /* @__PURE__ */ new Map();
532
+ const namespaces = [];
533
+ const bindings = new Map(types.map((type) => [type.name, `the generated type ${type.name}`]));
534
+ const emitted = schemas.flatMap((schema) => formatTypes([schema], options).map((type) => ({
535
+ type,
536
+ schema
537
+ })));
538
+ for (const { type, schema } of emitted) for (const entry of type.kind === "output" ? schema.outputImports : schema.inputImports) {
539
+ const specifier = importSpecifier(entry, directory);
540
+ const identity = `${entry.importedName} from ${specifier}`;
541
+ const bound = bindings.get(entry.name);
542
+ if (bound !== void 0 && bound !== identity) throw new Error(`"${entry.name}" would refer to both ${bound} and ${identity}; rename one of them`);
543
+ bindings.set(entry.name, identity);
544
+ if (entry.importedName === "*") {
545
+ namespaces.push(`import type * as ${entry.name} from ${JSON.stringify(specifier)};`);
546
+ continue;
547
+ }
548
+ const names = imports.get(specifier) ?? /* @__PURE__ */ new Map();
549
+ names.set(entry.name, entry.importedName === entry.name ? entry.name : `${entry.importedName} as ${entry.name}`);
550
+ imports.set(specifier, names);
551
+ }
552
+ const lines = [];
553
+ if (options.header) lines.push(options.header, "");
554
+ const importLines = [...[...imports].map(([specifier, names]) => `import type { ${[...new Set(names.values())].sort().join(", ")} } from ${JSON.stringify(specifier)};`), ...new Set(namespaces)];
555
+ if (importLines.length) lines.push(...importLines, "");
556
+ for (const type of types) {
557
+ const doc = type.description === void 0 ? "" : formatDoc(type.description);
558
+ lines.push(`${doc}export type ${type.name} = ${type.text};`, "");
559
+ }
560
+ return lines.join("\n").replace(/\n+$/, "\n");
561
+ }
562
+ function importSpecifier(entry, directory) {
563
+ if (!isAbsolute(entry.from)) return entry.from;
564
+ let specifier = relative(directory, entry.from).split(sep).join("/");
565
+ specifier = specifier.replace(/\.d\.([cm]?)ts$/, ".$1js").replace(/\.([cm]?)tsx?$/, ".$1js");
566
+ return specifier.startsWith(".") ? specifier : `./${specifier}`;
567
+ }
568
+ //#endregion
569
+ //#region src/generate.ts
570
+ const GENERATED_HEADER = "// Generated by @loculus/infer. Do not edit by hand.";
571
+ /** Extracts types from the matching files and renders the output modules without writing them. */
572
+ async function generate(options) {
573
+ if (options.outDir && options.outFile) throw new Error("outDir and outFile cannot be combined");
574
+ const cwd = resolve(options.cwd ?? process.cwd());
575
+ const files = await resolveFiles(options.include, options.exclude, cwd);
576
+ if (files.length === 0) throw new Error(`No files matched ${options.include.join(", ")}`);
577
+ const extractor = new LoculusTypeExtractor(options);
578
+ extractor.addSourceFiles(files);
579
+ const extracted = files.map((file) => ({
580
+ file,
581
+ schemas: extractor.extractAll(file, options)
582
+ }));
583
+ const warnings = [...new Set(extracted.flatMap(({ schemas }) => schemas.flatMap((schema) => schema.warnings)))];
584
+ const withSchemas = extracted.filter(({ schemas }) => schemas.length > 0);
585
+ if (options.outFile) {
586
+ const path = resolve(cwd, options.outFile);
587
+ const schemas = withSchemas.flatMap((entry) => entry.schemas);
588
+ return {
589
+ warnings,
590
+ files: [{
591
+ path,
592
+ sources: withSchemas.map((entry) => entry.file),
593
+ schemas,
594
+ content: renderModule(schemas, {
595
+ ...options,
596
+ outFile: path,
597
+ header: GENERATED_HEADER
598
+ })
599
+ }]
600
+ };
601
+ }
602
+ if (options.outDir) {
603
+ const pattern = options.outPattern ?? (options.declaration ? "[name].types.d.ts" : "[name].types.ts");
604
+ const byPath = /* @__PURE__ */ new Map();
605
+ const outputPath = (file) => resolve(cwd, options.outDir, pattern.replaceAll("[name]", basename(file, extname(file))));
606
+ const headerFor = (file, path) => `${GENERATED_HEADER}\n// Source: ${relative(dirname(path), file).split(sep).join("/")}`;
607
+ const generated = withSchemas.map(({ file, schemas }) => {
608
+ const path = outputPath(file);
609
+ const previous = byPath.get(path);
610
+ if (previous) throw new Error(`${previous} and ${file} would both be written to ${path}; use outFile or a different outPattern`);
611
+ byPath.set(path, file);
612
+ return {
613
+ path,
614
+ sources: [file],
615
+ schemas,
616
+ content: renderModule(schemas, {
617
+ ...options,
618
+ outFile: path,
619
+ header: headerFor(file, path)
620
+ })
621
+ };
622
+ });
623
+ for (const { file, schemas } of extracted) {
624
+ if (schemas.length > 0 || extractor.listSchemas(file).length > 0) continue;
625
+ const path = outputPath(file);
626
+ if (byPath.has(path)) continue;
627
+ if ((await readFile(path, "utf8").catch(() => void 0))?.startsWith(`${headerFor(file, path)}\n`)) generated.push({
628
+ path,
629
+ sources: [file],
630
+ schemas,
631
+ content: "",
632
+ obsolete: true
633
+ });
634
+ }
635
+ return {
636
+ warnings,
637
+ files: generated
638
+ };
639
+ }
640
+ return {
641
+ warnings,
642
+ files: withSchemas.map(({ file, schemas }) => ({
643
+ sources: [file],
644
+ schemas,
645
+ content: renderModule(schemas, {
646
+ ...options,
647
+ cwd
648
+ })
649
+ }))
650
+ };
651
+ }
652
+ /** Returns the generated files whose content differs from what is on disk. */
653
+ async function findOutdated(files) {
654
+ const outdated = [];
655
+ for (const file of files) {
656
+ if (!file.path) continue;
657
+ const current = await readFile(file.path, "utf8").catch(() => void 0);
658
+ if (file.obsolete ? current !== void 0 : current !== file.content) outdated.push(file);
659
+ }
660
+ return outdated;
661
+ }
662
+ async function resolveFiles(include, exclude = [], cwd) {
663
+ const matches = await glob([...include], {
664
+ cwd,
665
+ absolute: true,
666
+ ignore: [...exclude, "**/node_modules/**"],
667
+ expandDirectories: false
668
+ });
669
+ return [...new Set(matches.map((file) => resolve(file)))].filter((file) => /\.[cm]?tsx?$/.test(file) && !/\.d\.[cm]?ts$/.test(file)).sort();
670
+ }
671
+ //#endregion
672
+ export { renderModule as a, formatTypes as i, findOutdated as n, LoculusTypeExtractor as o, generate as r, formatDoc as s, GENERATED_HEADER as t };
@@ -0,0 +1,130 @@
1
+ //#region src/extractor.d.ts
2
+ /** A named type the extracted text refers to, and where to import it from. */
3
+ interface TypeImport {
4
+ /** Name used in the extracted type text. */
5
+ readonly name: string;
6
+ /** Name exported by the source module. */
7
+ readonly importedName: string;
8
+ /** Absolute file path, or a package specifier such as `"some-package"`. */
9
+ readonly from: string;
10
+ }
11
+ interface ExtractedSchema {
12
+ /** Exported name of the schema. */
13
+ readonly schemaName: string;
14
+ /** Absolute path of the file declaring the schema. */
15
+ readonly filePath: string;
16
+ /** `Input<typeof schema>` as TypeScript source. */
17
+ readonly input: string;
18
+ /** `Output<typeof schema>` as TypeScript source. */
19
+ readonly output: string;
20
+ /** The schema's own `description`, when written as a string literal. */
21
+ readonly description?: string;
22
+ /** Named types referenced by `input` or `output` that need an import. */
23
+ readonly imports: readonly TypeImport[];
24
+ /** Named types referenced by `input`. */
25
+ readonly inputImports: readonly TypeImport[];
26
+ /** Named types referenced by `output`. */
27
+ readonly outputImports: readonly TypeImport[];
28
+ /** Referenced types that cannot be imported, such as non-exported local types. */
29
+ readonly warnings: readonly string[];
30
+ }
31
+ interface ExtractorOptions {
32
+ /** Path to tsconfig.json. Defaults to the nearest tsconfig.json above `cwd`. */
33
+ readonly project?: string;
34
+ /** Base directory for relative paths. Defaults to `process.cwd()`. */
35
+ readonly cwd?: string;
36
+ }
37
+ interface ExtractOptions {
38
+ /** Only extract these exported names. */
39
+ readonly schemas?: readonly string[];
40
+ /** Emit `description` options as TSDoc comments on fields. */
41
+ readonly withDescriptions?: boolean;
42
+ }
43
+ /** Reads `Input` and `Output` types of exported Loculus schemas with the TypeScript compiler. */
44
+ export declare class LoculusTypeExtractor {
45
+ #private;
46
+ constructor(options?: ExtractorOptions);
47
+ /** Lists exported Loculus schema names in a file. */
48
+ listSchemas(filePath: string): string[];
49
+ /** Extracts every exported Loculus schema in a file, in declaration order. */
50
+ extractAll(filePath: string, options?: ExtractOptions): ExtractedSchema[];
51
+ /** Extracts one exported Loculus schema. Throws when it is not found. */
52
+ extract(filePath: string, schemaName: string, options?: Omit<ExtractOptions, 'schemas'>): ExtractedSchema;
53
+ /** Loads several files before extraction so their dependencies are resolved once, not per file. */
54
+ addSourceFiles(filePaths: readonly string[]): void;
55
+ }
56
+ /** Formats a TSDoc comment at the given indentation, ending with a newline. */
57
+ export declare function formatDoc(description: string, indent?: string): string;
58
+ //#endregion
59
+ //#region src/format.d.ts
60
+ interface FormatOptions {
61
+ /** Emit only input types. */
62
+ readonly inputOnly?: boolean;
63
+ /** Emit only output types. */
64
+ readonly outputOnly?: boolean;
65
+ /** Emit one type when the input and output types are identical. */
66
+ readonly mergeSame?: boolean;
67
+ /** Suffix removed from schema names, such as `"Schema"`. */
68
+ readonly suffix?: string;
69
+ /** Suffix of input type names. Defaults to `"Input"`. */
70
+ readonly inputSuffix?: string;
71
+ /** Suffix of output type names. Defaults to `"Output"`. */
72
+ readonly outputSuffix?: string;
73
+ /** Base type names by schema name, such as `{ UserSchema: "User" }`. */
74
+ readonly map?: Readonly<Record<string, string>>;
75
+ }
76
+ interface FormattedType {
77
+ readonly name: string;
78
+ readonly kind: 'input' | 'output' | 'merged';
79
+ readonly schemaName: string;
80
+ readonly text: string;
81
+ readonly description?: string;
82
+ }
83
+ /** Decides the exported type declarations for extracted schemas. */
84
+ export declare function formatTypes(schemas: readonly ExtractedSchema[], options?: FormatOptions): FormattedType[];
85
+ interface RenderOptions extends FormatOptions {
86
+ /** Absolute path of the generated file, used for relative import specifiers. */
87
+ readonly outFile?: string;
88
+ /** Directory used for relative import specifiers when `outFile` is not set. */
89
+ readonly cwd?: string;
90
+ /** Text placed at the top of the module. */
91
+ readonly header?: string;
92
+ }
93
+ /** Renders extracted schemas as a TypeScript module. */
94
+ export declare function renderModule(schemas: readonly ExtractedSchema[], options?: RenderOptions): string;
95
+ //#endregion
96
+ //#region src/generate.d.ts
97
+ interface GenerateOptions extends ExtractorOptions, ExtractOptions, FormatOptions {
98
+ /** Files or glob patterns to read. */
99
+ readonly include: readonly string[];
100
+ /** Glob patterns to skip. */
101
+ readonly exclude?: readonly string[];
102
+ /** Write one module per source file into this directory. */
103
+ readonly outDir?: string;
104
+ /** Write every type into this module. */
105
+ readonly outFile?: string;
106
+ /** File name pattern inside `outDir`; `[name]` is the source file name without its extension. */
107
+ readonly outPattern?: string;
108
+ /** Use a `.d.ts` file name by default. */
109
+ readonly declaration?: boolean;
110
+ }
111
+ interface GeneratedFile {
112
+ /** Absolute output path, or undefined when no output location was given. */
113
+ readonly path?: string;
114
+ /** A file this tool generated earlier whose source no longer exports schemas; delete it. */
115
+ readonly obsolete?: boolean;
116
+ readonly sources: readonly string[];
117
+ readonly schemas: readonly ExtractedSchema[];
118
+ readonly content: string;
119
+ }
120
+ interface GenerateResult {
121
+ readonly files: GeneratedFile[];
122
+ readonly warnings: string[];
123
+ }
124
+ export declare const GENERATED_HEADER = "// Generated by @loculus/infer. Do not edit by hand.";
125
+ /** Extracts types from the matching files and renders the output modules without writing them. */
126
+ export declare function generate(options: GenerateOptions): Promise<GenerateResult>;
127
+ /** Returns the generated files whose content differs from what is on disk. */
128
+ export declare function findOutdated(files: readonly GeneratedFile[]): Promise<GeneratedFile[]>;
129
+ //#endregion
130
+ export type { ExtractOptions, ExtractedSchema, ExtractorOptions, FormatOptions, FormattedType, GenerateOptions, GenerateResult, GeneratedFile, RenderOptions, TypeImport };
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+ export { t as GENERATED_HEADER, o as LoculusTypeExtractor, n as findOutdated, s as formatDoc, i as formatTypes, r as generate, a as renderModule } from "./generate-ncDNvye5.js";
package/package.json CHANGED
@@ -1,6 +1,60 @@
1
1
  {
2
2
  "name": "@loculus/infer",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.0",
4
+ "description": "Extract input/output types from Loculus schemas as TypeScript source",
5
+ "keywords": [
6
+ "loculus",
7
+ "schema",
8
+ "type-extraction",
9
+ "typescript"
10
+ ],
11
+ "license": "MIT",
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+https://github.com/toiroakr/loculus.git",
15
+ "directory": "packages/infer"
16
+ },
17
+ "bin": {
18
+ "loculus-infer": "./bin/loculus-infer.js"
19
+ },
20
+ "files": [
21
+ "bin",
22
+ "dist",
23
+ "README.md",
24
+ "CHANGELOG.md",
25
+ "LICENSE"
26
+ ],
27
+ "type": "module",
28
+ "exports": {
29
+ ".": {
30
+ "types": "./dist/index.d.ts",
31
+ "import": "./dist/index.js"
32
+ }
33
+ },
34
+ "publishConfig": {
35
+ "access": "public"
36
+ },
37
+ "dependencies": {
38
+ "tinyglobby": "^0.2.15",
39
+ "ts-morph": "^28.0.0"
40
+ },
41
+ "devDependencies": {
42
+ "knip": "6.39.0",
43
+ "oxfmt": "0.71.0",
44
+ "oxlint": "1.86.0",
45
+ "tsdown": "^0.23.1"
46
+ },
47
+ "peerDependencies": {
48
+ "loculus": "^0.4.0"
49
+ },
50
+ "engines": {
51
+ "node": ">=22.18.0"
52
+ },
53
+ "scripts": {
54
+ "build": "tsdown",
55
+ "lint": "oxlint",
56
+ "format": "oxfmt --write .",
57
+ "format:check": "oxfmt --check .",
58
+ "knip": "knip"
59
+ }
6
60
  }