@colyseus/schema 5.0.13 → 5.0.19

package/README.md

@@ -102,7 +102,7 @@ The `@type()` decorator uses legacy decorators — enable them in your `tsconfig
 
 ### Declaration:
 
-Each primitive type is declared through its `t.*` factory (`t.string()`, `t.uint8()`, …). The string names above remain valid as collection child types (`t.array("string")`).
+Each primitive type is declared through its `t.*` factory (`t.string()`, `t.uint8()`, …). Collection elements take the type **name**, not a builder: `t.array("string")`, never `t.array(t.string())`.
 
 #### Primitive types (`string`, `number`, `boolean`, etc)
 
@@ -293,7 +293,7 @@ up-to-date version of the schema definitions.
 ## Limitations and best practices
 
 - Each `Schema` structure can hold up to `64` fields. If you need more fields, use nested structures.
-- Fields tagged with `.view()`, `.unreliable()`, or `.static()` at field indexes `≥ 32` use a slower per-mutation classification path (linear scan over the tagged-field list instead of a single bitwise op). For schemas with more than 32 fields, declare frequently-mutated tagged fields earlier so they fall in the bitmask fast path.
+- Fields tagged with `.view()`, `.unreliable()`, or `.fullStateOnly()` at field indexes `≥ 32` use a slower per-mutation classification path (linear scan over the tagged-field list instead of a single bitwise op). For schemas with more than 32 fields, declare frequently-mutated tagged fields earlier so they fall in the bitmask fast path.
 - Schemas with `≤ 8` fields store per-field operation bytes inline in two numbers (no allocation per instance). Schemas with `> 8` fields allocate a small `Uint8Array` per instance for op storage. The difference is only material when allocating thousands of instances per tick — prefer narrower nested structures in that regime.
 - `NaN` or `null` numbers are encoded as `0`
 - `null` strings are encoded as `""`
@@ -333,6 +333,11 @@ schema-codegen ./schemas/State.ts --output ./haxe-project/ --haxe
 | `--bundle` | Bundle all generated files into a single file |
 | `--namespace` | Generate namespace/package on output code |
 | `--decorator` | Custom name for `@type` decorator to scan for |
+| `--tsconfig` | `tsconfig.json` to resolve import path aliases with (default: the nearest `tsconfig.json`/`jsconfig.json` above each source file) |
+
+Imports are followed to discover related schemas, including bare specifiers
+mapped by `compilerOptions.paths`/`baseUrl` and barrel files that re-export
+them. Imports of installed packages are not followed.
 
 ### Bundle Mode
 

package/build/Metadata.d.ts

@@ -1,6 +1,6 @@
 import { DefinitionType } from "./annotations.js";
 import { TypeDefinition } from "./types/registry.js";
-import { $descriptors, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $fullStateOnlyFieldIndexes, $streamFieldIndexes, $streamPriorities, $patchOnlyFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+import { $descriptors, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $fullStateOnlyFieldIndexes, $fullSyncSkipIndexes, $streamFieldIndexes, $streamPriorities, $patchOnlyFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
 /**
  * Field indexes ride in the low 6 bits of the operation byte
  * (`(index | operation) & 255`), which leaves room for 0..63. Index 63 is
@@ -42,6 +42,9 @@ export type Metadata = {
 {
     [$patchOnlyFieldIndexes]: number[];
 } & // all field indexes tagged with @patchOnly (not persisted to snapshots)
+{
+    [$fullSyncSkipIndexes]: number[];
+} & // @patchOnly ∪ @deprecated() — never read during full sync
 {
     [$fullStateOnlyFieldIndexes]: number[];
 } & // all field indexes tagged @fullStateOnly / .fullStateOnly() (not tracked after assignment)
@@ -84,6 +87,12 @@ export declare const Metadata: {
     setTag(metadata: Metadata, fieldName: string, tag: number): void;
     setUnreliable(metadata: Metadata, fieldName: string): void;
     setPatchOnly(metadata: Metadata, fieldName: string): void;
+    /**
+     * `@deprecated()` bookkeeping: the field keeps its wire index (so peers
+     * that still carry it stay compatible) but is excluded from full sync —
+     * its accessor may throw — and hidden from `for..in` consumers.
+     */
+    setDeprecated(metadata: Metadata, fieldName: string): void;
     setFullStateOnly(metadata: Metadata, fieldName: string): void;
     setStream(metadata: Metadata, fieldName: string): void;
     /**

package/build/Reflection.d.ts

@@ -71,12 +71,12 @@ export declare const ReflectionField: import("./annotations.js").SchemaWithExten
     childPrimitive: FieldBuilder<string, false, false>;
     /** Set only on `t.quantized()` fields (`.optional()` — no auto-instantiated
      *  default; its absence is the "not quantized" signal on decode). */
-    quantized: FieldBuilder<{} & {
-        min?: number;
-        max?: number;
-        bits?: number;
-        mode?: number;
-    } & Schema<any> & Schema<unknown>, false, true>;
+    quantized: FieldBuilder<{
+        min: number;
+        max: number;
+        bits: number;
+        mode: number;
+    } & {} & Schema<any> & Schema<unknown>, false, true>;
 }, import("./index.js").BuilderInitProps<{
     name: FieldBuilder<string, false, false>;
     type: FieldBuilder<string, false, false>;
@@ -86,43 +86,45 @@ export declare const ReflectionField: import("./annotations.js").SchemaWithExten
     childPrimitive: FieldBuilder<string, false, false>;
     /** Set only on `t.quantized()` fields (`.optional()` — no auto-instantiated
      *  default; its absence is the "not quantized" signal on decode). */
-    quantized: FieldBuilder<{} & {
-        min?: number;
-        max?: number;
-        bits?: number;
-        mode?: number;
-    } & Schema<any> & Schema<unknown>, false, true>;
+    quantized: FieldBuilder<{
+        min: number;
+        max: number;
+        bits: number;
+        mode: number;
+    } & {} & Schema<any> & Schema<unknown>, false, true>;
 }>, typeof Schema>;
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 export declare const ReflectionType: import("./annotations.js").SchemaWithExtendsConstructor<{
     id: FieldBuilder<number, false, false>;
     extendsId: FieldBuilder<number, false, false>;
-    fields: FieldBuilder<ArraySchema<{} & {
-        name?: string;
-        type?: string;
-        quantized?: {} & {
-            min?: number;
-            max?: number;
-            bits?: number;
-            mode?: number;
-        } & Schema<any> & Schema<unknown>;
-        referencedType?: number;
-        childPrimitive?: string;
+    fields: FieldBuilder<ArraySchema<{
+        name: string;
+        type: string;
+        referencedType: number;
+        childPrimitive: string;
+    } & {
+        quantized?: {
+            min: number;
+            max: number;
+            bits: number;
+            mode: number;
+        } & {} & Schema<any> & Schema<unknown>;
     } & Schema<any> & Schema<unknown>>, true, false>;
 }, import("./index.js").BuilderInitProps<{
     id: FieldBuilder<number, false, false>;
     extendsId: FieldBuilder<number, false, false>;
-    fields: FieldBuilder<ArraySchema<{} & {
-        name?: string;
-        type?: string;
-        quantized?: {} & {
-            min?: number;
-            max?: number;
-            bits?: number;
-            mode?: number;
-        } & Schema<any> & Schema<unknown>;
-        referencedType?: number;
-        childPrimitive?: string;
+    fields: FieldBuilder<ArraySchema<{
+        name: string;
+        type: string;
+        referencedType: number;
+        childPrimitive: string;
+    } & {
+        quantized?: {
+            min: number;
+            max: number;
+            bits: number;
+            mode: number;
+        } & {} & Schema<any> & Schema<unknown>;
     } & Schema<any> & Schema<unknown>>, true, false>;
 }>, typeof Schema>;
 export type ReflectionType = SchemaType<typeof ReflectionType>;

package/build/codegen/api.d.ts

@@ -5,5 +5,7 @@ export interface GenerateOptions {
     decorator?: string;
     namespace?: string;
     bundle?: boolean;
+    /** Overrides the nearest-tsconfig lookup used to resolve import path aliases. */
+    tsconfig?: string;
 }
 export declare function generate(targetId: string, options: GenerateOptions): void;

package/build/codegen/cli.cjs

@@ -69,7 +69,9 @@ var argv = (sargs) => {
 if (typeof (__dirname) === "undefined") {
     global.__dirname = path__namespace.dirname(new URL((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href))).pathname);
 }
-const VERSION = JSON.parse(fs__namespace.readFileSync(__dirname + "/../../package.json").toString()).version;
+/** Root of the @colyseus/schema package — `src/codegen/` in dev, `build/codegen/` once bundled. */
+const PACKAGE_ROOT = path__namespace.resolve(__dirname, "..", "..");
+const VERSION = JSON.parse(fs__namespace.readFileSync(path__namespace.resolve(PACKAGE_ROOT, "package.json")).toString()).version;
 const COMMENT_HEADER = `
 THIS FILE HAS BEEN GENERATED AUTOMATICALLY
 DO NOT CHANGE IT MANUALLY UNLESS YOU KNOW WHAT YOU'RE DOING
@@ -217,6 +219,262 @@ function getInheritanceTree(klass, allClasses, includeSelf = true) {
     ];
 }
 
+const CONFIG_NAMES = ["tsconfig.json", "jsconfig.json"];
+/** `No inputs were found in config file` — expected, since readDirectory is stubbed. */
+const NO_INPUTS_FOUND = 18003;
+let configByDir;
+let override;
+let resolveOptions;
+let warned;
+reset();
+function reset() {
+    configByDir = new Map();
+    override = undefined;
+    resolveOptions = {};
+    warned = new Set();
+}
+/**
+ * Drop every cached tsconfig lookup. Called once per top-level `parseFiles()`
+ * run so a long-lived process can generate for two different projects.
+ */
+function resetResolver(options = {}) {
+    reset();
+    resolveOptions = options;
+    if (options.tsconfig && !fs__namespace.existsSync(options.tsconfig)) {
+        throw new Error(`--tsconfig: file not found: ${options.tsconfig}`);
+    }
+}
+function warnOnce(key, message) {
+    if (warned.has(key)) {
+        return;
+    }
+    warned.add(key);
+    console.warn(message);
+}
+/**
+ * `readDirectory` is stubbed on purpose: only `compilerOptions` is wanted here,
+ * and letting TypeScript glob the config's `include` set would stat the user's
+ * whole project on every config discovered.
+ */
+const parseConfigHost = {
+    useCaseSensitiveFileNames: ts__namespace.sys?.useCaseSensitiveFileNames ?? true,
+    readDirectory: () => [],
+    fileExists: (fileName) => fs__namespace.existsSync(fileName),
+    readFile: (fileName) => {
+        try {
+            return fs__namespace.readFileSync(fileName, "utf8");
+        }
+        catch (e) {
+            if (!e?.code) {
+                throw e;
+            }
+            return undefined;
+        }
+    },
+};
+function loadConfig(configFilePath) {
+    const { config, error } = ts__namespace.readConfigFile(configFilePath, parseConfigHost.readFile);
+    if (error) {
+        warnOnce(configFilePath, `schema-codegen: could not read "${configFilePath}" ` +
+            `(${ts__namespace.flattenDiagnosticMessageText(error.messageText, " ")}) — ` +
+            `its import path aliases will be ignored.`);
+        return null;
+    }
+    // parseJsonConfigFileContent (not convertCompilerOptionsFromJson) is what
+    // applies `extends` chains, `${configDir}` templates, and `pathsBasePath` —
+    // the directory of the config that DECLARED `paths`, which in a monorepo is
+    // not the directory of the config being loaded.
+    const parsed = ts__namespace.parseJsonConfigFileContent(config, parseConfigHost, path__namespace.dirname(configFilePath), undefined, configFilePath);
+    const errors = parsed.errors.filter((d) => d.code !== NO_INPUTS_FOUND && d.category === ts__namespace.DiagnosticCategory.Error);
+    if (errors.length > 0) {
+        warnOnce(configFilePath, `schema-codegen: "${configFilePath}" has errors — ` +
+            errors.map((d) => ts__namespace.flattenDiagnosticMessageText(d.messageText, " ")).join("; "));
+    }
+    const options = parsed.options;
+    if (!options.paths && !options.baseUrl) {
+        return null;
+    }
+    const getCanonicalFileName = parseConfigHost.useCaseSensitiveFileNames
+        ? (f) => f
+        : (f) => f.toLowerCase();
+    return {
+        configFilePath,
+        options,
+        cache: ts__namespace.createModuleResolutionCache(path__namespace.dirname(configFilePath), getCanonicalFileName, options),
+    };
+}
+function getOverrideConfig() {
+    if (override === undefined) {
+        override = loadConfig(path__namespace.resolve(resolveOptions.tsconfig));
+        if (override === null) {
+            warnOnce(`no-aliases:${resolveOptions.tsconfig}`, `schema-codegen: "${resolveOptions.tsconfig}" declares no "paths" or ` +
+                `"baseUrl" — there are no import aliases to resolve.`);
+        }
+    }
+    return override;
+}
+/**
+ * Nearest `tsconfig.json`/`jsconfig.json` above `containingFile`. Both names are
+ * checked at every level: a distant tsconfig.json must not win over an adjacent
+ * jsconfig.json. Stops at the first config found even when it declares no
+ * aliases — matching `tsc`, a parent project's `paths` do not leak into a child
+ * that does not `extends` it.
+ */
+function getConfigFor(containingFile) {
+    if (resolveOptions.tsconfig) {
+        return getOverrideConfig();
+    }
+    const dir = path__namespace.dirname(containingFile);
+    if (configByDir.has(dir)) {
+        return configByDir.get(dir);
+    }
+    let config = null;
+    const visited = [];
+    for (let current = dir, parent;; current = parent) {
+        visited.push(current);
+        const found = CONFIG_NAMES
+            .map((name) => path__namespace.join(current, name))
+            .find((candidate) => fs__namespace.existsSync(candidate));
+        if (found) {
+            config = loadConfig(found);
+            break;
+        }
+        parent = path__namespace.dirname(current);
+        if (parent === current) {
+            break;
+        }
+    }
+    // memoize the whole walk, negatives included
+    visited.forEach((visitedDir) => configByDir.set(visitedDir, config));
+    return config;
+}
+/** Exact patterns win outright; among wildcards the longest prefix wins. */
+function findBestPathPattern(specifier, paths) {
+    let best;
+    let bestPrefixLength = -1;
+    for (const pattern in paths) {
+        const star = pattern.indexOf("*");
+        if (star === -1) {
+            if (pattern === specifier) {
+                return { substitutions: paths[pattern], matchedStar: "" };
+            }
+            continue;
+        }
+        const prefix = pattern.slice(0, star);
+        const suffix = pattern.slice(star + 1);
+        if (specifier.length >= prefix.length + suffix.length &&
+            specifier.startsWith(prefix) &&
+            specifier.endsWith(suffix) &&
+            prefix.length > bestPrefixLength) {
+            bestPrefixLength = prefix.length;
+            best = {
+                substitutions: paths[pattern],
+                matchedStar: specifier.slice(prefix.length, specifier.length - suffix.length),
+            };
+        }
+    }
+    return best;
+}
+function resolveViaPathsSubstitution(matched, options) {
+    // mirrors ts.getPathsBasePath(): `paths` may be declared without a baseUrl,
+    // in which case it anchors on the config that declared it
+    const base = options.baseUrl ?? options.pathsBasePath ?? process.cwd();
+    for (const substitution of matched.substitutions) {
+        const resolved = resolveSourceFile(path__namespace.resolve(base, substitution.replace("*", matched.matchedStar)));
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return undefined;
+}
+const isDeclaration = (fileName) => /\.d\.[cm]?ts$/.test(fileName);
+const isInNodeModules = (fileName) => fileName.replace(/\\/g, "/").includes("/node_modules/");
+/**
+ * Resolve a non-relative import (`@schemas/Player`, `shared/Player`) to a
+ * first-party source file through the tsconfig governing `containingFile`.
+ * Returns undefined for npm packages, declaration files, and specifiers no
+ * alias covers.
+ */
+function resolveNonRelativeImport(specifier, containingFile) {
+    const config = getConfigFor(containingFile);
+    if (!config) {
+        return undefined;
+    }
+    const { options } = config;
+    const matched = options.paths && findBestPathPattern(specifier, options.paths);
+    // no alias hit and no baseUrl: TypeScript could only find this under
+    // node_modules, which costs ~130 failed lookups to prove
+    if (!matched && !options.baseUrl) {
+        return undefined;
+    }
+    const resolved = ts__namespace.resolveModuleName(specifier, containingFile, options, ts__namespace.sys, config.cache).resolvedModule;
+    if (resolved) {
+        // a deliberate package/typings hit — not ours to parse, and the
+        // substitution fallback must not second-guess it
+        return (resolved.isExternalLibraryImport ||
+            isDeclaration(resolved.resolvedFileName) ||
+            isInNodeModules(resolved.resolvedFileName)) ? undefined
+            : path__namespace.resolve(resolved.resolvedFileName);
+    }
+    // `.mjs` targets are unresolvable by ts.resolveModuleName in every
+    // moduleResolution mode, but schema-codegen parses them
+    const viaSubstitution = matched && resolveViaPathsSubstitution(matched, options);
+    if (viaSubstitution) {
+        return viaSubstitution;
+    }
+    if (matched) {
+        warnOnce(`unresolved:${specifier}`, `schema-codegen: '${specifier}' matches a "paths" alias in ` +
+            `${config.configFilePath}, but no source file was found for it — ` +
+            `schemas it exports will be missing from the generated output.`);
+    }
+    return undefined;
+}
+/** The extension alternatives parseFiles() probes, in order. Pure — no fs. */
+function sourceFileCandidates(fileName) {
+    if (!fileName.endsWith(".ts") &&
+        !fileName.endsWith(".js") &&
+        !fileName.endsWith(".mjs")) {
+        return [`${fileName}.ts`, `${fileName}/index.ts`];
+    }
+    else if (fileName.endsWith(".js")) {
+        // ESM imports often spell a .ts source with a .js extension
+        return [fileName, fileName.replace(/\.js$/, ".ts")];
+    }
+    else {
+        return [fileName];
+    }
+}
+/** Same probing as parseFiles(), answering "which candidate exists?". */
+function resolveSourceFile(fileName) {
+    const candidates = sourceFileCandidates(fileName);
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = path__namespace.resolve(candidates[i]);
+        try {
+            // statSync, not existsSync: a directory must fall through to the
+            // next candidate, the way readFileSync's EISDIR does
+            if (fs__namespace.statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        catch (e) {
+            if (!e?.code) {
+                throw e;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * The serializer's own source declares wire-internal schemas (`Reflection`,
+ * `ReflectionField`, …) that must never reach generated client code.
+ */
+function isOwnPackageSource(fileName) {
+    const relative = path__namespace.relative(PACKAGE_ROOT, fileName);
+    return (!relative.startsWith("..") &&
+        !path__namespace.isAbsolute(relative) &&
+        (relative.startsWith(`src${path__namespace.sep}`) || relative.startsWith(`build${path__namespace.sep}`)));
+}
+
 let currentStructure;
 let currentProperty;
 let globalContext;
@@ -224,10 +482,12 @@ let defineTypesWarned = false;
 const BUILDER_COLLECTION_KINDS = new Set(["array", "map", "set", "collection"]);
 /**
  * For a t.*().chain().calls() expression, walk down to the base `t.X(...)`
- * call and return its method name and first argument. Returns null if the
+ * call and return its method name, first argument, and the names of the
+ * chained modifiers (`.view()`, `.deprecated()`, …). Returns null if the
  * node does not look like a builder chain.
  */
 function extractBuilderBase(node) {
+    const modifiers = new Set();
     let current = node;
     while (true) {
         const expr = current.expression;
@@ -235,13 +495,14 @@ function extractBuilderBase(node) {
             return null;
         }
         if (ts__namespace.isCallExpression(expr.expression)) {
-            // Chained modifier, e.g. .default() / .view() — walk deeper.
+            modifiers.add(expr.name.text);
             current = expr.expression;
             continue;
         }
         return {
             methodName: expr.name.text,
             firstArg: current.arguments[0],
+            modifiers,
         };
     }
 }
@@ -340,10 +601,27 @@ function defineProperty(property, initializer) {
     if (ts__namespace.isCallExpression(initializer)) {
         const base = extractBuilderBase(initializer);
         if (base) {
+            // same as `@deprecated()`: `.deprecated(false)` still marks the field
+            if (base.modifiers.has("deprecated")) {
+                property.deprecated = true;
+            }
             if (BUILDER_COLLECTION_KINDS.has(base.methodName)) {
                 property.type = base.methodName;
                 if (base.firstArg) {
-                    property.childType = base.firstArg.text ?? base.firstArg.getText();
+                    // see through `(x)`, `x as any`, `x satisfies T`
+                    let childArg = base.firstArg;
+                    while (ts__namespace.isParenthesizedExpression(childArg) || ts__namespace.isAsExpression(childArg) || ts__namespace.isSatisfiesExpression(childArg)) {
+                        childArg = childArg.expression;
+                    }
+                    if (ts__namespace.isCallExpression(childArg)) {
+                        // mirrors the runtime guard in builder.ts resolveChild()
+                        const inner = extractBuilderBase(childArg);
+                        const hint = (inner && !BUILDER_COLLECTION_KINDS.has(inner.methodName) && inner.methodName !== "ref" && inner.methodName !== "quantized")
+                            ? `use the type name instead: t.${base.methodName}("${inner.methodName}")`
+                            : `collections accept a Schema class or a primitive type name ("string", "number", …)`;
+                        throw new Error(`schema-codegen: field '${property.name}': a t.* builder is not a valid element type — ${hint}.`);
+                    }
+                    property.childType = childArg.text ?? childArg.getText();
                 }
             }
             else if (base.methodName === "ref") {
@@ -385,15 +663,27 @@ function defineProperty(property, initializer) {
         property.type = initializer.text;
     }
 }
+function followModuleSpecifier(specifier, currentFile, decoratorName) {
+    const moduleName = specifier?.text;
+    if (!moduleName) {
+        return;
+    } // `export { x }` — no module to follow
+    const resolved = (moduleName.startsWith("."))
+        ? resolveSourceFile(path__namespace.resolve(path__namespace.dirname(currentFile), moduleName))
+        // may be a tsconfig `paths`/`baseUrl` alias onto first-party source;
+        // npm packages are filtered out by the resolver
+        : resolveNonRelativeImport(moduleName, currentFile);
+    if (resolved && !isOwnPackageSource(resolved)) {
+        parseFiles([resolved], decoratorName, globalContext);
+    }
+}
 function inspectNode(node, context, decoratorName) {
     switch (node.kind) {
-        case ts__namespace.SyntaxKind.ImportClause:
-            const specifier = node.parent.moduleSpecifier;
-            if (specifier && specifier.text.startsWith('.')) {
-                const currentDir = path__namespace.dirname(node.getSourceFile().fileName);
-                const pathToImport = path__namespace.resolve(currentDir, specifier.text);
-                parseFiles([pathToImport], decoratorName, globalContext);
-            }
+        case ts__namespace.SyntaxKind.ImportDeclaration:
+        case ts__namespace.SyntaxKind.ExportDeclaration:
+            // ExportDeclaration too: path aliases usually point at a barrel
+            // (`@schemas` -> `schemas/index.ts` -> `export * from "./Player"`).
+            followModuleSpecifier(node.moduleSpecifier, node.getSourceFile().fileName, decoratorName);
             break;
         case ts__namespace.SyntaxKind.ClassDeclaration:
             currentStructure = new Class();
@@ -638,7 +928,10 @@ function inspectNode(node, context, decoratorName) {
                         continue;
                     if (!prop.initializer)
                         continue;
-                    const property = currentProperty || new Property();
+                    // never inherit `currentProperty`: it's the decorator path's
+                    // carry-over from a visited `deprecated` identifier, and a
+                    // trailing `.deprecated()` chain can leave it set
+                    const property = new Property();
                     property.name = prop.name.escapedText;
                     currentStructure.addProperty(property);
                     defineProperty(property, prop.initializer);
@@ -662,7 +955,11 @@ function inspectNode(node, context, decoratorName) {
     ts__namespace.forEachChild(node, (n) => inspectNode(n, context, decoratorName));
 }
 let parsedFiles;
-function parseFiles(fileNames, decoratorName = "type", context = new Context()) {
+/**
+ * `options` is only honored for a top-level call (one passing a fresh
+ * `Context`) — the recursive import walk reuses the run's resolver state.
+ */
+function parseFiles(fileNames, decoratorName = "type", context = new Context(), options) {
     if (typeof ts__namespace.createSourceFile !== "function") {
         // typescript@7+ (native) no longer ships the JS compiler API
         throw new Error(`schema-codegen requires the TypeScript compiler API, which the installed "typescript@${ts__namespace.version}" package does not provide.\n` +
@@ -674,25 +971,16 @@ function parseFiles(fileNames, decoratorName = "type", context = new Context())
     if (globalContext !== context) {
         parsedFiles = {};
         globalContext = context;
+        // a structure left over from a previous run would make the
+        // `currentStructure?.name !== className` guard skip re-registering it
+        currentStructure = undefined;
+        currentProperty = undefined;
+        resetResolver(options);
     }
     fileNames.forEach((fileName) => {
         let sourceFile;
         let sourceFileName;
-        const fileNameAlternatives = [];
-        if (!fileName.endsWith(".ts") &&
-            !fileName.endsWith(".js") &&
-            !fileName.endsWith(".mjs")) {
-            fileNameAlternatives.push(`${fileName}.ts`);
-            fileNameAlternatives.push(`${fileName}/index.ts`);
-        }
-        else if (fileName.endsWith(".js")) {
-            // Handle .js extensions by also trying .ts (ESM imports often use .js extension)
-            fileNameAlternatives.push(fileName);
-            fileNameAlternatives.push(fileName.replace(/\.js$/, ".ts"));
-        }
-        else {
-            fileNameAlternatives.push(fileName);
-        }
+        const fileNameAlternatives = sourceFileCandidates(fileName);
         for (let i = 0; i < fileNameAlternatives.length; i++) {
             try {
                 sourceFileName = path__namespace.resolve(fileNameAlternatives[i]);
@@ -2754,7 +3042,7 @@ function generate(targetId, options) {
         }
         return acc;
     }, []);
-    const structures = parseFiles(options.files, options.decorator);
+    const structures = parseFiles(options.files, options.decorator, undefined, { tsconfig: options.tsconfig });
     // Post-process classes before generating
     structures.classes.forEach(klass => klass.postProcessing());
     if (options.bundle && generator.renderBundle) {
@@ -2802,7 +3090,9 @@ ${Object.
 
 Optional:
     --namespace: generate namespace on output code
-    --decorator: custom name for @type decorator to scan for`);
+    --decorator: custom name for @type decorator to scan for
+    --tsconfig: tsconfig.json to resolve import path aliases with
+                (default: nearest tsconfig.json/jsconfig.json above each source file)`);
     process.exit(exitCode);
 }
 const args = argv(process.argv.slice(2));
@@ -2826,7 +3116,8 @@ try {
         decorator: args.decorator,
         output: args.output,
         namespace: args.namespace,
-        bundle: args.bundle
+        bundle: args.bundle,
+        tsconfig: args.tsconfig,
     });
 }
 catch (e) {