@loozo/angular-router 0.0.0-stage → 0.0.1

package/node/src/generation/emit.js

@@ -0,0 +1,245 @@
+import { dirname, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+import { markers } from "./files.js";
+import { resolveModule } from "./sources.js";
+import { authoredPath } from "./validate.js";
+import { relativeSelections } from "./selectors.js";
+export function specifier(from, file) {
+    let name = relative(dirname(from), file).split(sep).join("/").replace(/\.ts$/, ".js");
+    if (!name.startsWith(".")) {
+        name = `./${name}`;
+    }
+    return name;
+}
+function lazySpecifier(from, file, options) {
+    const emitted = specifier(from, file);
+    const extensionless = emitted.slice(0, -3);
+    const ordinary = resolveModule(extensionless, from, {
+        ...options,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+    });
+    if (ordinary === file) {
+        return extensionless;
+    }
+    const fallback = resolveModule(emitted, from, {
+        ...options,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+    });
+    if (fallback !== file) {
+        throw new Error(`Cannot emit an identity-preserving lazy page import: ${file}`);
+    }
+    return emitted;
+}
+export function emit(sources, selected) {
+    const desired = new Map();
+    const declarations = sources.declarations.filter((declaration) => declaration.retained || declaration.target);
+    if (declarations.length === 0) {
+        return desired;
+    }
+    const routesFile = resolve(sources.output, "routes.generated.ts");
+    const sharedFile = resolve(sources.output, "destinations.generated.ts");
+    const names = new Map();
+    for (let index = 0; index < declarations.length; index += 1) {
+        names.set(declarations[index], `definition${index}`);
+    }
+    const routes = [
+        markers["routes.generated.ts"],
+        "import type { Routes } from '@angular/router';",
+    ];
+    let needsNative = false;
+    let needsCallbacks = false;
+    let needsRedirect = false;
+    for (const declaration of declarations) {
+        if (["providers", "title", "data", "canDeactivate", "runGuardsAndResolvers"].some((key) => declaration.config.has(key))) {
+            needsNative = true;
+        }
+        if (["canActivate", "canActivateChild", "canMatch", "resolve"].some((key) => declaration.config.has(key))) {
+            needsCallbacks = true;
+        }
+        if (declaration.target) {
+            needsRedirect = true;
+        }
+    }
+    const helpers = [];
+    if (needsNative) {
+        helpers.push("nativeOptions");
+    }
+    if (needsCallbacks) {
+        helpers.push("callbacks");
+        routes.push(`import { getRouteSet } from './destinations.generated.js';`);
+    }
+    if (needsRedirect) {
+        helpers.push("redirect");
+    }
+    if (helpers.length > 0) {
+        routes.push(`import { ${helpers.join(", ")} } from '@loozo/angular-router/_generated';`);
+    }
+    for (const declaration of declarations) {
+        if (declaration.config.size > 0 &&
+            [...declaration.config.keys()].some((key) => !["parent", "params", "search", "fragments"].includes(key))) {
+            routes.push(`import ${names.get(declaration)} from ${JSON.stringify(specifier(routesFile, declaration.file))};`);
+        }
+    }
+    function nativePath(declaration, effective) {
+        const parts = [];
+        let segments = declaration.segments;
+        if (effective) {
+            segments = declaration.effective;
+        }
+        for (const segment of segments) {
+            if (segment.kind === "static") {
+                parts.push(segment.text);
+            }
+            else if (segment.kind === "catchall") {
+                parts.push("**");
+            }
+            else {
+                parts.push(`:${segment.name}`);
+            }
+        }
+        return parts.join("/");
+    }
+    function record(declaration) {
+        const parts = [];
+        const name = names.get(declaration);
+        const native = ["providers", "title", "data", "canDeactivate", "runGuardsAndResolvers"].some((key) => declaration.config.has(key));
+        if (native) {
+            parts.push(`...nativeOptions(${name})`);
+        }
+        parts.push(`path: ${JSON.stringify(nativePath(declaration, !!declaration.target))}`);
+        if (declaration.full || declaration.target) {
+            parts.push("pathMatch: 'full'");
+        }
+        let data = "";
+        if (declaration.config.has("data")) {
+            data = `...nativeOptions(${name}).data as object, `;
+        }
+        parts.push(`data: { ${data}__loozoAngularRouterRouteId: ${JSON.stringify(declaration.id)} }`);
+        if (declaration.target) {
+            parts.push(`redirectTo: redirect(() => ${name})`);
+        }
+        else {
+            if (["canActivate", "canActivateChild", "canMatch", "resolve"].some((key) => declaration.config.has(key))) {
+                parts.push(`...callbacks(getRouteSet(), ${JSON.stringify(declaration.id)})`);
+            }
+            if (declaration.page) {
+                parts.push(`loadComponent: () => import(${JSON.stringify(lazySpecifier(routesFile, declaration.page, sources.parsed.options))})`);
+            }
+            const children = declaration.children.filter((child) => child.retained);
+            children.sort(order);
+            if (children.length > 0) {
+                parts.push(`children: [${children.map(record).join(",\n")}]`);
+            }
+        }
+        return `{ ${parts.join(",\n")} }`;
+    }
+    function order(a, b) {
+        const catchA = a.segments.at(-1)?.kind === "catchall";
+        const catchB = b.segments.at(-1)?.kind === "catchall";
+        if (catchA !== catchB) {
+            if (catchA) {
+                return 1;
+            }
+            return -1;
+        }
+        return authoredPath(a).localeCompare(authoredPath(b), "en") || a.id.localeCompare(b.id, "en");
+    }
+    const before = [];
+    const ordinary = [];
+    const after = [];
+    for (const declaration of declarations) {
+        if (declaration.target) {
+            if (declaration.effective.at(-1)?.kind === "catchall") {
+                after.push(declaration);
+            }
+            else {
+                before.push(declaration);
+            }
+        }
+        else if (!declaration.parent) {
+            ordinary.push(declaration);
+        }
+    }
+    for (const group of [before, ordinary, after]) {
+        group.sort(order);
+    }
+    routes.push(`\nexport const routes: Routes = [${[...before, ...ordinary, ...after].map(record).join(",\n")}];\n`);
+    desired.set(routesFile, routes.join("\n"));
+    const retained = declarations.filter((declaration) => declaration.retained);
+    if (retained.length === 0) {
+        return desired;
+    }
+    const shared = [
+        markers["destinations.generated.ts"],
+        "import type { RouteSet, Handle as GeneratedHandle, Destination as GeneratedDestination } from '@loozo/angular-router/_generated';",
+    ];
+    for (const declaration of declarations) {
+        shared.push(`import ${names.get(declaration)} from ${JSON.stringify(specifier(sharedFile, declaration.file))};`);
+    }
+    shared.push("\nexport type Definitions = {");
+    for (const declaration of declarations) {
+        shared.push(`${JSON.stringify(declaration.id)}: typeof ${names.get(declaration)};`);
+    }
+    shared.push("};\ndeclare const setIdentity: unique symbol;");
+    shared.push("export type AbsoluteTargets = {");
+    for (const [path, declaration] of selected) {
+        shared.push(`${JSON.stringify(path)}: ${JSON.stringify(declaration.id)};`);
+    }
+    const relativeTargets = relativeSelections(sources, selected);
+    shared.push("};\nexport type RelativeTargets = {");
+    for (const [id, expressions] of relativeTargets) {
+        shared.push(`${JSON.stringify(id)}: {`);
+        for (const [expression, target] of expressions) {
+            shared.push(`${JSON.stringify(expression)}: ${JSON.stringify(target)};`);
+        }
+        shared.push("};");
+    }
+    shared.push(`};
+export type Selected<Id extends keyof RelativeTargets> = {
+  readonly [Expression in keyof AbsoluteTargets | keyof RelativeTargets[Id]]:
+    Definitions[(Expression extends keyof AbsoluteTargets ? AbsoluteTargets[Expression] :
+      Expression extends keyof RelativeTargets[Id] ? RelativeTargets[Id][Expression] : never) & keyof Definitions];
+};
+export type Handle<Id extends keyof RelativeTargets> = GeneratedHandle<Definitions[Id], Selected<Id>, typeof setIdentity, Pick<Definitions, keyof RelativeTargets>>;
+export type Destination<Id extends keyof RelativeTargets> = GeneratedDestination<Definitions[Id], typeof setIdentity, Id>;
+const routeSet: RouteSet = { records: {`);
+    for (const declaration of retained) {
+        const owners = [];
+        let current = declaration;
+        while (current) {
+            owners.unshift(current.id);
+            current = current.parent;
+        }
+        shared.push(`${JSON.stringify(declaration.id)}: { definition: () => ${names.get(declaration)}, owners: ${JSON.stringify(owners)} },`);
+    }
+    shared.push("}, destinations: {");
+    for (const declaration of declarations) {
+        shared.push(`${JSON.stringify(declaration.id)}: () => ${names.get(declaration)},`);
+    }
+    const absoluteSelectors = Object.create(null);
+    const relativeSelectors = Object.create(null);
+    for (const [path, declaration] of selected) {
+        absoluteSelectors[path] = declaration.id;
+    }
+    for (const [id, expressions] of relativeTargets) {
+        relativeSelectors[id] = Object.fromEntries(expressions);
+    }
+    shared.push(`}, absolute: ${JSON.stringify(absoluteSelectors)}, relative: ${JSON.stringify(relativeSelectors)} };\nexport function getRouteSet(): RouteSet { return routeSet; }\n`);
+    desired.set(sharedFile, shared.join("\n"));
+    for (const declaration of retained) {
+        const facade = resolve(dirname(declaration.file), "route.generated.ts");
+        const body = [
+            markers["route.generated.ts"],
+            "import { createDestination, injectGeneratedRoute } from '@loozo/angular-router/_generated';",
+            `import { getRouteSet, type Destination, type Handle } from ${JSON.stringify(specifier(facade, sharedFile))};`,
+            "export { defineRoute } from '@loozo/angular-router';",
+            `export const destination: Destination<${JSON.stringify(declaration.id)}> = createDestination(() => getRouteSet(), ${JSON.stringify(declaration.id)});`,
+            `export function injectRoute(): Handle<${JSON.stringify(declaration.id)}> { return injectGeneratedRoute(getRouteSet(), ${JSON.stringify(declaration.id)}); }`,
+            "",
+        ];
+        desired.set(facade, body.join("\n"));
+    }
+    return desired;
+}

package/node/src/generation/files.js

@@ -0,0 +1,168 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+export const markers = {
+    "routes.generated.ts": "// @loozo/angular-router routegen: owned routes.generated.ts",
+    "destinations.generated.ts": "// @loozo/angular-router routegen: owned destinations.generated.ts",
+    "route.generated.ts": "// @loozo/angular-router routegen: owned route.generated.ts",
+};
+export function contains(directory, file) {
+    const suffix = relative(directory, file);
+    return (suffix === "" || (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`)));
+}
+export async function metadata(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+// Resolve only aliases for the workspace access prefix, never a source/output suffix.
+export async function workspacePaths(workspace) {
+    const canonical = await realpath(workspace);
+    return {
+        canonical,
+        async resolve(path) {
+            let absolute = resolve(workspace, path);
+            if (contains(workspace, absolute)) {
+                absolute = resolve(canonical, relative(workspace, absolute));
+            }
+            const ancestors = [];
+            let current = dirname(absolute);
+            while (dirname(current) !== current) {
+                ancestors.unshift(current);
+                current = dirname(current);
+            }
+            for (const ancestor of ancestors) {
+                const info = await metadata(ancestor);
+                if (info?.isSymbolicLink()) {
+                    const target = await realpath(ancestor);
+                    if (target === canonical) {
+                        return resolve(canonical, relative(ancestor, absolute));
+                    }
+                    // A source/output link cannot become legitimate by resolving its target.
+                    return absolute;
+                }
+            }
+            return absolute;
+        },
+    };
+}
+export async function auditPath(path) {
+    const parent = dirname(path);
+    if (parent !== path) {
+        await auditPath(parent);
+    }
+    const info = await metadata(path);
+    if (info?.isSymbolicLink()) {
+        throw new Error(`Unsafe source/output symbolic link: ${path}`);
+    }
+    if (info && parent !== path && !info.isDirectory() && !info.isFile()) {
+        throw new Error(`Unsafe filesystem entry: ${path}`);
+    }
+}
+export async function walk(directory) {
+    await auditPath(directory);
+    const info = await metadata(directory);
+    if (!info) {
+        return [];
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`Scan/output directory is not a directory: ${directory}`);
+    }
+    const result = [];
+    async function visit(path) {
+        const entries = await readdir(path, { withFileTypes: true });
+        entries.sort((a, b) => a.name.localeCompare(b.name, "en"));
+        for (const entry of entries) {
+            const child = resolve(path, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`Unsafe source/output symbolic link: ${child}`);
+            }
+            if (entry.isDirectory()) {
+                // Dependency package-manager links are not application sources.
+                if (entry.name !== "node_modules") {
+                    await visit(child);
+                }
+            }
+            else if (entry.isFile()) {
+                result.push(child);
+            }
+            else {
+                throw new Error(`Unsafe filesystem entry: ${child}`);
+            }
+        }
+    }
+    await visit(directory);
+    return result;
+}
+export async function planOutputs(desired, encountered, globals) {
+    const changed = [];
+    const missing = [];
+    const stale = [];
+    const possible = new Set([...desired.keys(), ...globals]);
+    for (const path of encountered) {
+        if (path.endsWith(`${sep}route.generated.ts`)) {
+            possible.add(path);
+        }
+    }
+    for (const path of [...possible].sort()) {
+        await auditPath(path);
+        const info = await metadata(path);
+        const expected = desired.get(path);
+        if (!info) {
+            if (expected !== undefined) {
+                missing.push(path);
+            }
+            continue;
+        }
+        if (!info.isFile()) {
+            throw new Error(`Generated output is not a regular file: ${path}`);
+        }
+        const bytes = await readFile(path, "utf8");
+        const name = path.slice(path.lastIndexOf(sep) + 1);
+        const owned = bytes.split("\n", 1)[0] === markers[name];
+        if (!owned) {
+            if (expected !== undefined) {
+                throw new Error(`Unmarked generated-output collision: ${path}`);
+            }
+            continue;
+        }
+        if (expected === undefined) {
+            stale.push(path);
+        }
+        else if (bytes !== expected) {
+            changed.push(path);
+        }
+    }
+    return { changed, missing, stale, desired };
+}
+export function publish(plan, check, stopped) {
+    if (stopped()) {
+        return;
+    }
+    if (check) {
+        for (const [kind, paths] of [
+            ["changed", plan.changed],
+            ["missing", plan.missing],
+            ["stale", plan.stale],
+        ]) {
+            if (paths.length > 0) {
+                throw new Error(`Generated artifacts ${kind}:\n${paths.join("\n")}`);
+            }
+        }
+        return;
+    }
+    // No awaits from the final stop check through this short publication section.
+    for (const path of [...plan.changed, ...plan.missing]) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, plan.desired.get(path), "utf8");
+    }
+    for (const path of plan.stale) {
+        unlinkSync(path);
+    }
+}

package/node/src/generation/generate.js

@@ -0,0 +1,19 @@
+import { resolve } from "node:path";
+import { discover } from "./sources.js";
+import { selections, validateProgram } from "./validate.js";
+import { emit } from "./emit.js";
+import { planOutputs, publish, walk } from "./files.js";
+export async function generate(workspace, options, stopped) {
+    const sources = await discover(workspace, options.tsconfig, options.scanDirectories, options.outDirectory);
+    const selected = selections(sources);
+    const desired = emit(sources, selected);
+    const globalFiles = [
+        resolve(sources.output, "routes.generated.ts"),
+        resolve(sources.output, "destinations.generated.ts"),
+    ];
+    await walk(sources.output);
+    const plan = await planOutputs(desired, sources.encountered, globalFiles);
+    // Unrelated output contents are audited but never become cleanup candidates.
+    await validateProgram(sources, desired, plan.stale);
+    publish(plan, options.check === true, stopped);
+}

package/node/src/generation/selectors.js

@@ -0,0 +1,60 @@
+import { authoredPath } from "./validate.js";
+// Compile URL-template segment relationships, never authored directory ancestry.
+export function relativeSelections(sources, selected) {
+    const result = new Map();
+    for (const origin of sources.declarations) {
+        if (!origin.retained) {
+            continue;
+        }
+        const expressions = new Map();
+        result.set(origin.id, expressions);
+        if (origin.effective.some((segment) => segment.kind === "catchall")) {
+            continue;
+        }
+        let originParts = [];
+        if (origin.effective.length > 0) {
+            originParts = authoredPath(origin).slice(1).split("/");
+        }
+        for (let climb = 0; climb <= originParts.length; climb += 1) {
+            const prefix = originParts.slice(0, originParts.length - climb);
+            const steps = [];
+            for (let index = 0; index < climb; index += 1) {
+                steps.push("..");
+            }
+            for (const [path, target] of selected) {
+                let targetParts = [];
+                if (target.effective.length > 0) {
+                    targetParts = path.slice(1).split("/");
+                }
+                if (prefix.length > targetParts.length) {
+                    continue;
+                }
+                let matches = true;
+                for (let index = 0; index < prefix.length; index += 1) {
+                    if (prefix[index] !== targetParts[index]) {
+                        matches = false;
+                        break;
+                    }
+                }
+                if (!matches) {
+                    continue;
+                }
+                const suffix = targetParts.slice(prefix.length);
+                if (suffix.some((part) => part.includes("?") || part.includes("#"))) {
+                    continue;
+                }
+                let expression = "./";
+                if (climb > 0) {
+                    expression = steps.join("/");
+                    if (suffix.length === 0) {
+                        expressions.set(expression, target.id);
+                    }
+                    expression += "/";
+                }
+                expression += suffix.join("/");
+                expressions.set(expression, target.id);
+            }
+        }
+    }
+    return result;
+}