@loozo/angular-router 0.0.2 → 0.0.4

package/node/src/generation/filesystem.js

@@ -7,29 +7,104 @@ import { specifier } from "./emit.js";
 export function transparent(root, directory) {
     return directory !== root && basename(directory).startsWith("-");
 }
-function localPath(root, directory) {
-    if (directory === root || basename(directory).startsWith("+")) {
+// Directive comments bind to a following line or the module start, so edits must not move them.
+const directive = /@ts-(?:expect-error|ignore|check|nocheck)\b|@jsx(?:frag|importsource|runtime)?\b|\/\/\/\s*<(?:reference|amd-dependency|amd-module)\b|(?:eslint|oxlint)-disable-next-line\b/i;
+function contribution(root, directory) {
+    if (directory === root || transparent(root, directory) || basename(directory).startsWith("+")) {
         return "";
     }
     return basename(directory);
 }
-function unusedBinding(source, preferred) {
-    const identifiers = new Set();
+// Names that bindings, declarations and references use; property names are not bindings.
+function identifiers(source) {
+    const names = new Set();
     function visit(node) {
-        if (ts.isIdentifier(node)) {
-            identifiers.add(node.text);
+        const propertyName = (ts.isPropertyAssignment(node.parent) || ts.isPropertyAccessExpression(node.parent)) &&
+            node.parent.name === node;
+        if (ts.isIdentifier(node) && !propertyName) {
+            names.add(node.text);
         }
         ts.forEachChild(node, visit);
     }
-    visit(source);
+    ts.forEachChild(source, visit);
+    return names;
+}
+function unusedBinding(source, preferred) {
+    const used = identifiers(source);
     let name = preferred;
     let index = 0;
-    while (identifiers.has(name)) {
+    while (used.has(name)) {
         index += 1;
         name = `${preferred}${index}`;
     }
     return name;
 }
+function parentBinding(source) {
+    if (identifiers(source).has("parent")) {
+        return unusedBinding(source, "filesystemParent");
+    }
+    return "parent";
+}
+// Reuse a stringParam import from the router, else import it as `stringParam` when that
+// identifier is free.
+function stringParamBinding(source, imports) {
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) ||
+            statement.importClause?.isTypeOnly ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== "@loozo/angular-router") {
+            continue;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings)) {
+            continue;
+        }
+        for (const binding of bindings.elements) {
+            if (!binding.isTypeOnly && (binding.propertyName ?? binding.name).text === "stringParam") {
+                return binding.name.text;
+            }
+        }
+    }
+    if (identifiers(source).has("stringParam")) {
+        const name = unusedBinding(source, "filesystemStringParam");
+        imports.push(`import { stringParam as ${name} } from "@loozo/angular-router";`);
+        return name;
+    }
+    imports.push('import { stringParam } from "@loozo/angular-router";');
+    return "stringParam";
+}
+// After the last import, keeping ordinary same-line comments with the import they annotate. A
+// directive or multiline comment there can bind to the next line, so insert before it instead.
+function importPosition(source) {
+    let last;
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            last = statement;
+        }
+    }
+    // Every admitted declaration imports defineRoute.
+    let position = last.end;
+    for (const range of ts.getTrailingCommentRanges(source.text, last.end) ?? []) {
+        const comment = source.text.slice(range.pos, range.end);
+        if (directive.test(comment) || /[\r\n]/.test(comment)) {
+            return last.end;
+        }
+        position = range.end;
+    }
+    return position;
+}
+// Point the parent property at a binding, as shorthand when it is named `parent` and nothing
+// but whitespace separates the key from its value.
+function parentValue(property, value, name, source) {
+    if (ts.isShorthandPropertyAssignment(property)) {
+        return { start: value.getStart(source), end: value.end, text: `parent: ${name}` };
+    }
+    const separator = source.text.slice(property.name.end, value.getStart(source));
+    if (name === "parent" && /^\s*:\s*$/.test(separator)) {
+        return { start: property.getStart(source), end: property.end, text: name };
+    }
+    return { start: value.getStart(source), end: value.end, text: name };
+}
 function removeSyntax(node, source) {
     const start = node.getStart(source);
     const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, source.text);
@@ -46,8 +121,7 @@ function removeSyntax(node, source) {
         }
         // Include adjacent retained trivia: it too can become module-leading after
         // deletion. Stop at the next actual token, without copying trailing bytes.
-        if (comment &&
-            /@ts-(?:expect-error|ignore|check|nocheck)\b|@jsx(?:frag|importsource|runtime)?\b|\/\/\/\s*<(?:reference|amd-dependency|amd-module)\b|(?:eslint|oxlint)-disable-next-line\b/i.test(scanner.getTokenText())) {
+        if (comment && directive.test(scanner.getTokenText())) {
             fail(node, "Cannot remove directive-bound filesystem parent syntax; repair it explicitly");
         }
         if (scanner.getTokenPos() >= start && scanner.getTokenPos() < node.end && trivia) {
@@ -123,6 +197,47 @@ function otherUses(source, imported, parent, checker) {
     visit(source);
     return used;
 }
+// The builder owns the path, so the fix is in the params or the directories, never the path.
+// `opaque` says why the builder can't read the params' keys.
+function ambiguousParams(node, path, removed, added, opaque) {
+    const changes = [];
+    if (removed.length > 0) {
+        changes.push(`removed params: ${removed.join(", ")}`);
+    }
+    if (added.length > 0) {
+        changes.push(`added params: ${added.join(", ")}`);
+    }
+    let repair = "Edit this file's params to match";
+    if (!parsePath(path).some((segment) => segment.kind !== "static")) {
+        repair = "Remove this file's params";
+    }
+    else if (opaque) {
+        repair = `This file's params ${opaque}; write each one as a plain \`name: codec\` property to match`;
+    }
+    fail(node, `Ambiguous filesystem params: the directories give path "${path}" (${changes.join("; ")}). ` +
+        `${repair}, or move or rename the directory`);
+}
+// The keys of a direct inline params object, or why the builder can't read them.
+function paramKeys(params) {
+    if (!ts.isObjectLiteralExpression(params)) {
+        return "are not an inline object";
+    }
+    const keys = new Set();
+    for (const property of params.properties) {
+        if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) {
+            return "use a spread or accessor";
+        }
+        const name = property.name;
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name)) {
+            return "use a computed or numeric key";
+        }
+        if (keys.has(name.text)) {
+            return `repeat the key ${name.text}`;
+        }
+        keys.add(name.text);
+    }
+    return keys;
+}
 function patchDeclaration(declaration, path, parentFile, options, host, checker) {
     const source = declaration.source;
     const assignment = source.statements.find(ts.isExportAssignment);
@@ -149,34 +264,85 @@ function patchDeclaration(declaration, path, parentFile, options, host, checker)
                 desiredNames.add(segment.name);
             }
         }
-        const sameNames = names.size === desiredNames.size && [...names].every((name) => desiredNames.has(name));
-        if (!sameNames) {
+        const removed = [];
+        const added = [];
+        for (const name of names) {
+            if (!desiredNames.has(name)) {
+                removed.push(name);
+            }
+        }
+        for (const name of desiredNames) {
+            if (!names.has(name)) {
+                added.push(name);
+            }
+        }
+        if (removed.length > 0 || added.length > 0) {
             const params = declaration.config.get("params");
-            if (names.size === 1 && desiredNames.size === 1 && params) {
-                const entries = properties(params, "Filesystem local params");
-                const oldName = [...names][0];
-                const newName = [...desiredNames][0];
-                if (entries.size !== 1 || !entries.has(oldName)) {
-                    fail(params, "Ambiguous filesystem codec change; update local params explicitly");
-                }
-                const inline = params;
-                const property = inline.properties[0];
-                if (!ts.isPropertyAssignment(property)) {
-                    fail(property, "Filesystem param rename requires a direct property with its codec expression");
+            let keys = new Set();
+            if (params) {
+                const readable = paramKeys(params);
+                if (typeof readable === "string") {
+                    ambiguousParams(params, path, removed, added, readable);
                 }
-                patches.push({
-                    start: property.name.getStart(source),
-                    end: property.name.end,
-                    text: JSON.stringify(newName),
-                });
+                keys = readable;
             }
-            else if (names.size === 0 && desiredNames.size === 1 && !params) {
-                const name = unusedBinding(source, "filesystemStringParam");
-                imports.push(`import { stringParam as ${name} } from "@loozo/angular-router";${newline}`);
-                additions.push(`params: { ${JSON.stringify([...desiredNames][0])}: ${name} }`);
+            // Params the author already made match the directories need only the path rewritten. A
+            // path without params matches only a declaration without `params`, as at runtime.
+            let reconciled = keys.size === desiredNames.size;
+            if (desiredNames.size === 0 && params) {
+                reconciled = false;
             }
-            else {
-                fail(literal, "Ambiguous filesystem codec change; update path and local params explicitly before synchronization");
+            for (const name of desiredNames) {
+                if (!keys.has(name)) {
+                    reconciled = false;
+                }
+            }
+            if (!reconciled) {
+                if (removed.length === 1 && added.length === 1 && params) {
+                    const entries = properties(params, "Filesystem local params");
+                    const [oldName] = removed;
+                    const [newName] = added;
+                    if (entries.size !== names.size || !entries.has(oldName)) {
+                        ambiguousParams(params, path, removed, added);
+                    }
+                    const property = entries.get(oldName).parent;
+                    if (!ts.isPropertyAssignment(property)) {
+                        ambiguousParams(property, path, removed, added, "use a shorthand property");
+                    }
+                    patches.push({
+                        start: property.name.getStart(source),
+                        end: property.name.end,
+                        text: JSON.stringify(newName),
+                    });
+                }
+                else if (removed.length === 0 && params) {
+                    // Pure additions keep every authored codec and give each new param the seed's codec.
+                    for (const name of names) {
+                        if (!keys.has(name)) {
+                            ambiguousParams(params, path, removed, added);
+                        }
+                    }
+                    if (keys.size !== names.size) {
+                        ambiguousParams(params, path, removed, added);
+                    }
+                    const name = stringParamBinding(source, imports);
+                    const appended = [];
+                    for (const param of added) {
+                        appended.push(`${JSON.stringify(param)}: ${name}`);
+                    }
+                    patches.push(addProperty(params, appended.join(", ")));
+                }
+                else if (names.size === 0 && !params) {
+                    const name = stringParamBinding(source, imports);
+                    const entries = [];
+                    for (const param of added) {
+                        entries.push(`${JSON.stringify(param)}: ${name}`);
+                    }
+                    additions.push(`params: { ${entries.join(", ")} }`);
+                }
+                else {
+                    ambiguousParams(literal, path, removed, added);
+                }
             }
         }
         patches.push({ start: literal.getStart(source), end: literal.end, text: JSON.stringify(path) });
@@ -195,6 +361,13 @@ function patchDeclaration(declaration, path, parentFile, options, host, checker)
                     end: module.end,
                     text: JSON.stringify(specifier(declaration.file, parentFile)),
                 });
+                // A specifier that still resolves names a different parent, and so does its binding. An
+                // unresolvable one went stale because a file moved or was deleted; its name may still fit.
+                const binding = imported.importClause.name;
+                if (resolved && binding.text !== "parent" && !identifiers(source).has("parent")) {
+                    patches.push({ start: binding.getStart(source), end: binding.end, text: "parent" });
+                    patches.push(parentValue(parent.parent, parent, "parent", source));
+                }
             }
             else {
                 if (!resolved && (usedElsewhere || imported.importClause?.namedBindings)) {
@@ -210,35 +383,35 @@ function patchDeclaration(declaration, path, parentFile, options, host, checker)
                     patches.push(...removeProperty(property, source));
                 }
                 else {
-                    parentName = unusedBinding(source, "filesystemParent");
-                    let text = parentName;
-                    if (ts.isShorthandPropertyAssignment(property)) {
-                        text = `parent: ${parentName}`;
-                    }
-                    patches.push({ start: parent.getStart(source), end: parent.end, text });
+                    parentName = parentBinding(source);
+                    patches.push(parentValue(property, parent, parentName, source));
                 }
             }
         }
     }
     else if (parentFile) {
-        parentName = unusedBinding(source, "filesystemParent");
-        additions.push(`parent: ${parentName}`);
+        parentName = parentBinding(source);
+        if (parentName === "parent") {
+            additions.push("parent");
+        }
+        else {
+            additions.push(`parent: ${parentName}`);
+        }
     }
     if (parentFile && parentName) {
         // A new binding leaves a still-valid old import and its unrelated uses alone.
-        imports.push(`import ${parentName} from ${JSON.stringify(specifier(declaration.file, parentFile))};${newline}`);
+        imports.push(`import ${parentName} from ${JSON.stringify(specifier(declaration.file, parentFile))};`);
     }
     if (additions.length > 0) {
         patches.push(addProperty(object, additions.join(", ")));
     }
     if (imports.length > 0) {
-        // Static imports are hoisted. Appending at the complete module boundary
-        // preserves every existing statement/comment attachment without parsing it.
-        patches.push({
-            start: source.text.length,
-            end: source.text.length,
-            text: newline + imports.join(""),
-        });
+        const position = importPosition(source);
+        let text = "";
+        for (const statement of imports) {
+            text += newline + statement;
+        }
+        patches.push({ start: position, end: position, text });
     }
     patches.sort((a, b) => b.start - a.start);
     let bytes = source.text;
@@ -254,6 +427,8 @@ function patchDeclaration(declaration, path, parentFile, options, host, checker)
 }
 export async function synchronize(root, declarations, pages, options, { filename = "route.ts" }, checker) {
     const byDirectory = new Map();
+    // Only directories with a page or a declaration become records. Others contribute their
+    // path segment to the records below them.
     const participating = new Set();
     for (const declaration of declarations) {
         const directory = dirname(declaration.file);
@@ -277,15 +452,6 @@ export async function synchronize(root, declarations, pages, options, { filename
         }
         participating.add(directory);
     }
-    for (const directory of participating) {
-        let ancestor = directory;
-        while (ancestor !== root) {
-            ancestor = dirname(ancestor);
-            if (!transparent(root, ancestor)) {
-                participating.add(ancestor);
-            }
-        }
-    }
     const files = new Map();
     for (const directory of [...participating].sort()) {
         let file = byDirectory.get(directory)?.file;
@@ -305,16 +471,30 @@ export async function synchronize(root, declarations, pages, options, { filename
     };
     const authored = new Map();
     for (const [directory, file] of files) {
+        const contributions = [contribution(root, directory)];
+        let ancestor = directory;
         let parentFile;
-        if (directory !== root) {
-            let parent = dirname(directory);
-            while (transparent(root, parent)) {
-                parent = dirname(parent);
+        while (ancestor !== root && !parentFile) {
+            ancestor = dirname(ancestor);
+            parentFile = files.get(ancestor);
+            if (!parentFile) {
+                contributions.unshift(contribution(root, ancestor));
             }
-            parentFile = files.get(parent);
         }
-        const path = localPath(root, directory);
-        const segments = parsePath(path);
+        const parts = [];
+        for (const part of contributions) {
+            if (part !== "") {
+                parts.push(part);
+            }
+        }
+        const path = parts.join("/");
+        let segments;
+        try {
+            segments = parsePath(path);
+        }
+        catch (error) {
+            throw new Error(`Invalid filesystem path "${path}" for ${file}: ${error.message}`);
+        }
         const declaration = byDirectory.get(directory);
         if (declaration) {
             const bytes = patchDeclaration(declaration, path, parentFile, options, host, checker);
@@ -330,14 +510,26 @@ export async function synchronize(root, declarations, pages, options, { filename
             imports.push(`import parent from ${JSON.stringify(specifier(file, parentFile))};`);
             config.push("parent");
         }
+        const params = new Set();
         for (const segment of segments) {
             if (segment.kind !== "static") {
-                imported.push("stringParam");
-                config.push(`params: { ${JSON.stringify(segment.name)}: stringParam }`);
+                params.add(segment.name);
+            }
+        }
+        if (params.size > 0) {
+            const entries = [];
+            for (const name of params) {
+                entries.push(`${JSON.stringify(name)}: stringParam`);
             }
+            imported.push("stringParam");
+            config.push(`params: { ${entries.join(", ")} }`);
+        }
+        let object = "{}";
+        if (config.length > 0) {
+            object = `{ ${config.join(", ")} }`;
         }
         imports.unshift(`import { ${imported.join(", ")} } from "@loozo/angular-router";`);
-        authored.set(file, `${imports.join("\n")}\n\nexport default defineRoute(${JSON.stringify(path)}, { ${config.join(", ")} });\n`);
+        authored.set(file, `${imports.join("\n")}\n\nexport default defineRoute(${JSON.stringify(path)}, ${object});\n`);
     }
     return authored;
 }

package/node/src/generation/generate.d.ts

@@ -0,0 +1,16 @@
+import type { AutoDefineRoutes } from "./filesystem.js";
+import type { CompilerState } from "./compiler.js";
+import type { AnchorState } from "./anchor.js";
+export interface GenerationOptions {
+    tsconfig: string;
+    scanDirectories: string[];
+    outDirectory: string;
+    check?: boolean;
+    autoDefineRoutes?: AutoDefineRoutes | false;
+}
+export interface GenerationState {
+    discovery: CompilerState;
+    overlay: CompilerState;
+    anchor: AnchorState;
+}
+export declare function generate(workspace: string, options: GenerationOptions, stopped: () => boolean, state?: GenerationState): Promise<void>;

package/node/src/generation/generate.js

@@ -1,10 +1,15 @@
 import { resolve } from "node:path";
 import { discover } from "./sources.js";
-import { selections, validateProgram } from "./validate.js";
+import { createValidationProgram, selections, validateRoutes } from "./validate.js";
 import { emit } from "./emit.js";
 import { auditPath, metadata, planOutputs, publish, walk } from "./files.js";
-export async function generate(workspace, options, stopped) {
-    const sources = await discover(workspace, options.tsconfig, options.scanDirectories, options.outDirectory, options.autoDefineRoutes);
+export async function generate(workspace, options, stopped, state) {
+    const { autoDefineRoutes = {} } = options;
+    let auto;
+    if (autoDefineRoutes !== false) {
+        auto = autoDefineRoutes;
+    }
+    const sources = await discover(workspace, options.tsconfig, options.scanDirectories, options.outDirectory, auto, undefined, undefined, undefined, state?.discovery);
     const selected = selections(sources);
     const desired = emit(sources, selected);
     const globalFiles = [
@@ -25,6 +30,7 @@ export async function generate(workspace, options, stopped) {
             throw new Error(`Filesystem definition is not a regular file: ${file}`);
         }
     }
-    await validateProgram(sources, desired, plan.stale);
+    const validation = createValidationProgram(sources, desired, plan.stale, state?.overlay);
+    await validateRoutes(sources, desired, validation, state?.anchor);
     publish(plan, options.check === true, stopped, sources.authored, seeds);
 }

package/node/src/generation/index.d.ts

@@ -0,0 +1,16 @@
+import type { CompilerState } from "./compiler.js";
+export declare function prepareLaunchRoutes(workspace: string, options: {
+    tsconfig: string;
+    scanDirectories: string[];
+    outDirectory: string;
+}, typeEntry: string, compiler?: CompilerState): Promise<{
+    sources: import("./sources.js").Sources;
+    desired: Map<string, string>;
+}>;
+export { CompilerState } from "./compiler.js";
+export { AnchorState } from "./anchor.js";
+export { createValidationProgram, validateRoutes } from "./validate.js";
+export { planOutputs, publish, walk, auditPath, launchMarkers } from "./files.js";
+export { fail, properties, namedImport, genuineImport } from "./sources.js";
+export { specifier } from "./emit.js";
+export type { Sources, Declaration, LaunchDeclaration } from "./sources.js";

package/node/src/generation/index.js

@@ -0,0 +1,15 @@
+// Closed integration seam for @loozo/angular-launch. Node-only, not a plugin API.
+import { discover } from "./sources.js";
+import { selections } from "./validate.js";
+import { emit } from "./emit.js";
+export async function prepareLaunchRoutes(workspace, options, typeEntry, compiler) {
+    const sources = await discover(workspace, options.tsconfig, options.scanDirectories, options.outDirectory, undefined, new Map(), false, { typeEntry }, compiler);
+    const desired = emit(sources, selections(sources));
+    return { sources, desired };
+}
+export { CompilerState } from "./compiler.js";
+export { AnchorState } from "./anchor.js";
+export { createValidationProgram, validateRoutes } from "./validate.js";
+export { planOutputs, publish, walk, auditPath, launchMarkers } from "./files.js";
+export { fail, properties, namedImport, genuineImport } from "./sources.js";
+export { specifier } from "./emit.js";

package/node/src/generation/overlay.d.ts

@@ -0,0 +1,3 @@
+import ts from "typescript";
+export declare function overlayHost(options: ts.CompilerOptions, authored: ReadonlyMap<string, string>): ts.CompilerHost;
+export declare function overlayDirectory(authored: ReadonlyMap<string, string>, resolveDirectory: (directory: string) => string): ts.ParseConfigHost["readDirectory"];

package/node/src/generation/selectors.d.ts

@@ -0,0 +1,2 @@
+import type { Declaration, Sources } from "./sources.js";
+export declare function relativeSelections(sources: Sources, selected: ReadonlyMap<string, Declaration>): Map<string, Map<string, string>>;

package/node/src/generation/sources.d.ts

@@ -0,0 +1,50 @@
+import ts from "typescript";
+import { type Segment } from "../../_core/src/path.js";
+import type { CompilerState } from "./compiler.js";
+import { type AutoDefineRoutes } from "./filesystem.js";
+export interface Declaration {
+    file: string;
+    id: string;
+    source: ts.SourceFile;
+    rawText: string;
+    config: Map<string, ts.Expression>;
+    path: string;
+    segments: readonly Segment[];
+    effective: readonly Segment[];
+    parent?: Declaration;
+    target?: Declaration;
+    children: Declaration[];
+    page?: string;
+    retained: boolean;
+    full: boolean;
+}
+export interface LaunchDeclaration {
+    file: string;
+    kind: "defineContext" | "defineRpc";
+    call: ts.CallExpression;
+}
+export interface LaunchMode {
+    typeEntry: string;
+}
+export interface Sources {
+    configFile: string;
+    parsed: ts.ParsedCommandLine;
+    roots: string[];
+    output: string;
+    encountered: string[];
+    declarations: Declaration[];
+    factoryEntry: string;
+    deferredFactories: Declaration[];
+    authored: ReadonlyMap<string, string>;
+    filesystem: boolean;
+    launch?: {
+        typeEntry: string;
+        declarations: LaunchDeclaration[];
+    };
+}
+export declare function fail(node: ts.Node, message: string): never;
+export declare function properties(node: ts.Expression, label: string): Map<string, ts.Expression>;
+export declare function resolveModule(name: string, source: string, options: ts.CompilerOptions, host?: ts.ModuleResolutionHost): string | undefined;
+export declare function namedImport(source: ts.SourceFile, name: ts.Expression, imported: string): ts.ImportDeclaration | undefined;
+export declare function genuineImport(statement: ts.ImportDeclaration, expected: string, options: ts.CompilerOptions, host?: ts.ModuleResolutionHost): Promise<boolean>;
+export declare function discover(workspace: string, config: string, scans: readonly string[], out: string, auto?: AutoDefineRoutes, authored?: ReadonlyMap<string, string>, filesystem?: boolean, launch?: LaunchMode, compiler?: CompilerState): Promise<Sources>;