@loozo/angular-router 0.0.1 → 0.0.3

package/node/src/generation/anchor.js

@@ -0,0 +1,92 @@
+import ts from "typescript";
+import { statSync } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+async function stamp(file) {
+    try {
+        const info = await stat(file);
+        return `${info.mtimeMs}:${info.size}`;
+    }
+    catch {
+        return "missing";
+    }
+}
+// Immutable canonical factory descriptors for one generation session. Inputs are
+// the effective options, entry, factory names and every file the anchor program
+// read (sources and package metadata). A new higher-priority resolution candidate
+// appearing mid-session is not detected; dependency changes need a new session.
+// Recomputation builds a throwaway program, so no SourceFile or Symbol outlives it.
+export class AnchorState {
+    #key;
+    #anchor;
+    #inputs = new Map();
+    clear() {
+        this.#key = undefined;
+        this.#anchor = undefined;
+        this.#inputs.clear();
+    }
+    async anchor(entry, names, options) {
+        const { configFile: _configFile, ...settings } = options;
+        const key = JSON.stringify({ entry, names, settings });
+        if (this.#anchor && key === this.#key) {
+            const files = [...this.#inputs.keys()];
+            const current = await Promise.all(files.map(stamp));
+            let unchanged = true;
+            for (let index = 0; index < files.length; index += 1) {
+                if (current[index] !== this.#inputs.get(files[index])) {
+                    unchanged = false;
+                }
+            }
+            if (unchanged) {
+                return this.#anchor;
+            }
+        }
+        this.#key = undefined;
+        this.#anchor = undefined;
+        this.#inputs.clear();
+        const inputs = new Map();
+        const host = ts.createCompilerHost(options, true);
+        const read = host.readFile.bind(host);
+        // Stamp before reading, so an edit racing this pass invalidates the next one.
+        host.readFile = (file) => {
+            const path = resolve(file);
+            try {
+                const info = statSync(path);
+                inputs.set(path, `${info.mtimeMs}:${info.size}`);
+            }
+            catch {
+                inputs.set(path, "missing");
+            }
+            return read(file);
+        };
+        const program = ts.createProgram({ rootNames: [entry], options, host });
+        const checker = program.getTypeChecker();
+        const module = checker.getSymbolAtLocation(program.getSourceFile(entry));
+        const exports = checker.getExportsOfModule(module);
+        const anchor = new Map();
+        for (const name of names) {
+            let symbol = exports.find((value) => value.name === name);
+            if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+                symbol = checker.getAliasedSymbol(symbol);
+            }
+            if (!symbol?.declarations?.length) {
+                anchor.set(name, undefined);
+                continue;
+            }
+            const declarations = [];
+            for (const declaration of symbol.declarations) {
+                declarations.push({
+                    file: await realpath(declaration.getSourceFile().fileName),
+                    kind: declaration.kind,
+                    pos: declaration.pos,
+                    end: declaration.end,
+                });
+            }
+            anchor.set(name, declarations);
+        }
+        this.#key = key;
+        this.#anchor = anchor;
+        this.#inputs = inputs;
+        return anchor;
+    }
+}

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

@@ -0,0 +1,6 @@
+import ts from "typescript";
+export declare class CompilerState {
+    #private;
+    clear(): void;
+    createProgram(rootNames: readonly string[], options: ts.CompilerOptions, host: ts.CompilerHost): ts.Program;
+}

package/node/src/generation/compiler.js

@@ -0,0 +1,68 @@
+import ts from "typescript";
+import { resolve } from "node:path";
+// One graph's content-aware SourceFiles, including native binding data.
+// Hosts, Programs, checkers and native resolution caches are fresh on every pass.
+export class CompilerState {
+    #files = new Map();
+    #optionsKey;
+    clear() {
+        this.#files.clear();
+        this.#optionsKey = undefined;
+    }
+    createProgram(rootNames, options, host) {
+        // configFile is an AST, not an effective compiler setting. Configs and their
+        // diagnostics are parsed afresh by discovery; never serialize/retain that AST.
+        const { configFile: _configFile, ...settings } = options;
+        const optionsKey = JSON.stringify(settings);
+        if (optionsKey !== this.#optionsKey) {
+            this.clear();
+            this.#optionsKey = optionsKey;
+        }
+        host.getSourceFile = (file, language, _onError, shouldCreateNewSourceFile) => {
+            const key = host.getCanonicalFileName(resolve(file));
+            const text = host.readFile(file);
+            if (text === undefined) {
+                this.#files.delete(key);
+                return undefined;
+            }
+            let languageVersion;
+            let impliedNodeFormat;
+            let jsDocParsingMode = host.jsDocParsingMode;
+            if (typeof language === "object") {
+                languageVersion = language.languageVersion;
+                impliedNodeFormat = language.impliedNodeFormat;
+                jsDocParsingMode = language.jsDocParsingMode;
+            }
+            else {
+                languageVersion = language;
+            }
+            const cached = this.#files.get(key);
+            // The external-module indicator supplied in `language` derives from the
+            // effective settings above; implied format/JSDoc mode are per-file inputs.
+            if (!shouldCreateNewSourceFile &&
+                cached &&
+                cached.source.text === text &&
+                cached.languageVersion === languageVersion &&
+                cached.impliedNodeFormat === impliedNodeFormat &&
+                cached.jsDocParsingMode === jsDocParsingMode) {
+                return cached.source;
+            }
+            const source = ts.createSourceFile(file, text, language, true);
+            this.#files.set(key, { source, languageVersion, impliedNodeFormat, jsDocParsingMode });
+            return source;
+        };
+        // Deliberately do not supply oldProgram: package metadata, missing lookups,
+        // module/type/lib resolutions and directory existence must be current.
+        const program = ts.createProgram({ rootNames, options, host });
+        const retained = new Set();
+        for (const source of program.getSourceFiles()) {
+            retained.add(host.getCanonicalFileName(resolve(source.fileName)));
+        }
+        for (const file of this.#files.keys()) {
+            if (!retained.has(file)) {
+                this.#files.delete(file);
+            }
+        }
+        return program;
+    }
+}

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

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

package/node/src/generation/emit.js

@@ -165,7 +165,12 @@ export function emit(sources, selected) {
     for (const group of [before, ordinary, after]) {
         group.sort(order);
     }
-    routes.push(`\nexport const routes: Routes = [${[...before, ...ordinary, ...after].map(record).join(",\n")}];\n`);
+    routes.push(`
+/**
+ * Generated native Angular route configuration; install with provideRouter(routes).
+ * Regenerate through the router's Architect companions instead of editing this file.
+ */
+export 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) {
@@ -202,7 +207,9 @@ export type Selected<Id extends keyof RelativeTargets> = {
     Definitions[(Expression extends keyof AbsoluteTargets ? AbsoluteTargets[Expression] :
       Expression extends keyof RelativeTargets[Id] ? RelativeTargets[Id][Expression] : never) & keyof Definitions];
 };
+/** A declaration-bound handle; obtain it through its colocated injectRoute facade. */
 export type Handle<Id extends keyof RelativeTargets> = GeneratedHandle<Definitions[Id], Selected<Id>, typeof setIdentity, Pick<Definitions, keyof RelativeTargets>>;
+/** A same-set nominal reference; use the destination exported by a colocated facade. */
 export type Destination<Id extends keyof RelativeTargets> = GeneratedDestination<Definitions[Id], typeof setIdentity, Id>;
 const routeSet: RouteSet = { records: {`);
     for (const declaration of retained) {
@@ -235,7 +242,25 @@ const routeSet: RouteSet = { records: {`);
             "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';",
+            `/**
+ * Inert reference to this exact declaration for same-set handle link/navigate calls.
+ * No injection context is required; copies and foreign-set references are invalid.
+ * This is not an authored route and cannot be passed to the root createUrl function.
+ */`,
             `export const destination: Destination<${JSON.stringify(declaration.id)}> = createDestination(() => getRouteSet(), ${JSON.stringify(declaration.id)});`,
+            `/**
+ * Injects a typed handle bound to this exact generated activated route record.
+ *
+ * @remarks
+ * Call in an Angular injection context. The handle exposes readonly native
+ * params/search/data Resources and destination-typed link/navigate methods.
+ * Data includes local resolver results only, not static or inherited data.
+ * All navigation values are explicit; current inputs are never reused implicitly.
+ *
+ * @returns A noncallable handle for this declaration.
+ * @throws A synchronous wiring error outside an injection context or when the
+ * activated record does not carry this declaration's own generated identity.
+ */`,
             `export function injectRoute(): Handle<${JSON.stringify(declaration.id)}> { return injectGeneratedRoute(getRouteSet(), ${JSON.stringify(declaration.id)}); }`,
             "",
         ];

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

@@ -0,0 +1,26 @@
+export declare const markers: {
+    readonly "routes.generated.ts": "// @loozo/angular-router routegen: owned routes.generated.ts";
+    readonly "destinations.generated.ts": "// @loozo/angular-router routegen: owned destinations.generated.ts";
+    readonly "route.generated.ts": "// @loozo/angular-router routegen: owned route.generated.ts";
+};
+export declare const launchMarkers: {
+    readonly "rpc.generated.ts": "// @loozo/angular-launch: owned rpc.generated.ts";
+    readonly "context.generated.d.ts": "// @loozo/angular-launch: owned context.generated.d.ts";
+    readonly "server.generated.ts": "// @loozo/angular-launch: owned server.generated.ts";
+};
+export declare function contains(directory: string, file: string): boolean;
+export declare function metadata(path: string): Promise<import("fs").Stats | undefined>;
+export declare function workspacePaths(workspace: string): Promise<{
+    canonical: string;
+    resolve(path: string, directory?: boolean): string;
+}>;
+export declare function auditPath(path: string): Promise<void>;
+export declare function walk(directory: string): Promise<string[]>;
+export interface OutputPlan {
+    changed: string[];
+    missing: string[];
+    stale: string[];
+    desired: ReadonlyMap<string, string>;
+}
+export declare function planOutputs(desired: ReadonlyMap<string, string>, encountered: readonly string[], globals: readonly string[], mode?: "router-and-launch"): Promise<OutputPlan>;
+export declare function publish(plan: OutputPlan, check: boolean, stopped: () => boolean, authored: ReadonlyMap<string, string>, seeds: ReadonlySet<string>): void;

package/node/src/generation/files.js

@@ -1,11 +1,16 @@
 import { lstat, readdir, readFile, realpath } from "node:fs/promises";
-import { mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { lstatSync, realpathSync, 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 const launchMarkers = {
+    "rpc.generated.ts": "// @loozo/angular-launch: owned rpc.generated.ts",
+    "context.generated.d.ts": "// @loozo/angular-launch: owned context.generated.d.ts",
+    "server.generated.ts": "// @loozo/angular-launch: owned server.generated.ts",
+};
 export function contains(directory, file) {
     const suffix = relative(directory, file);
     return (suffix === "" || (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`)));
@@ -26,21 +31,31 @@ export async function workspacePaths(workspace) {
     const canonical = await realpath(workspace);
     return {
         canonical,
-        async resolve(path) {
-            let absolute = resolve(workspace, path);
+        // Config matching needs synchronous directory-entry lookup. The optional
+        // directory leaf uses the same restricted prefix policy as file ancestors.
+        resolve(path, directory = false) {
+            const absolute = resolve(workspace, path);
+            // Inside the workspace every link is a suffix, even a link back to its root.
+            // Preserve that spelling for audit; only external access aliases may map.
+            if (contains(canonical, absolute)) {
+                return absolute;
+            }
             if (contains(workspace, absolute)) {
-                absolute = resolve(canonical, relative(workspace, absolute));
+                return resolve(canonical, relative(workspace, absolute));
             }
             const ancestors = [];
             let current = dirname(absolute);
+            if (directory) {
+                current = absolute;
+            }
             while (dirname(current) !== current) {
                 ancestors.unshift(current);
                 current = dirname(current);
             }
             for (const ancestor of ancestors) {
-                const info = await metadata(ancestor);
+                const info = lstatSync(ancestor, { throwIfNoEntry: false });
                 if (info?.isSymbolicLink()) {
-                    const target = await realpath(ancestor);
+                    const target = realpathSync(ancestor);
                     if (target === canonical) {
                         return resolve(canonical, relative(ancestor, absolute));
                     }
@@ -100,13 +115,15 @@ export async function walk(directory) {
     await visit(directory);
     return result;
 }
-export async function planOutputs(desired, encountered, globals) {
+export async function planOutputs(desired, encountered, globals, mode) {
     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`)) {
+        if (path.endsWith(`${sep}route.generated.ts`) ||
+            (mode === "router-and-launch" &&
+                Object.keys(launchMarkers).some((name) => path.endsWith(`${sep}${name}`)))) {
             possible.add(path);
         }
     }
@@ -124,8 +141,12 @@ export async function planOutputs(desired, encountered, globals) {
             throw new Error(`Generated output is not a regular file: ${path}`);
         }
         const bytes = await readFile(path, "utf8");
+        const ownership = { ...markers };
+        if (mode === "router-and-launch") {
+            Object.assign(ownership, launchMarkers);
+        }
         const name = path.slice(path.lastIndexOf(sep) + 1);
-        const owned = bytes.split("\n", 1)[0] === markers[name];
+        const owned = bytes.split("\n", 1)[0] === ownership[name];
         if (!owned) {
             if (expected !== undefined) {
                 throw new Error(`Unmarked generated-output collision: ${path}`);
@@ -141,11 +162,14 @@ export async function planOutputs(desired, encountered, globals) {
     }
     return { changed, missing, stale, desired };
 }
-export function publish(plan, check, stopped) {
+export function publish(plan, check, stopped, authored, seeds) {
     if (stopped()) {
         return;
     }
     if (check) {
+        if (authored.size > 0) {
+            throw new Error(`Filesystem definitions missing/changed:\n${[...authored.keys()].join("\n")}`);
+        }
         for (const [kind, paths] of [
             ["changed", plan.changed],
             ["missing", plan.missing],
@@ -158,6 +182,14 @@ export function publish(plan, check, stopped) {
         return;
     }
     // No awaits from the final stop check through this short publication section.
+    for (const [file, bytes] of authored) {
+        if (seeds.has(file)) {
+            writeFileSync(file, bytes, { encoding: "utf8", flag: "wx" });
+        }
+        else {
+            writeFileSync(file, bytes, "utf8");
+        }
+    }
     for (const path of [...plan.changed, ...plan.missing]) {
         mkdirSync(dirname(path), { recursive: true });
         writeFileSync(path, plan.desired.get(path), "utf8");

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

@@ -0,0 +1,7 @@
+import ts from "typescript";
+import { type Declaration } from "./sources.js";
+export interface AutoDefineRoutes {
+    filename?: string;
+}
+export declare function transparent(root: string, directory: string): boolean;
+export declare function synchronize(root: string, declarations: readonly Declaration[], pages: ReadonlyMap<string, string>, options: ts.CompilerOptions, { filename }: AutoDefineRoutes, checker: ts.TypeChecker): Promise<Map<string, string>>;