@ng-doc/builder 22.0.0-beta.2 → 22.1.0

package/generator/vite/configuration.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactSnapshot, PublishedGeneratorConfiguration } from '../contracts.js';
+export declare function requirePublishedConfiguration(snapshot: ArtifactSnapshot): PublishedGeneratorConfiguration;
+export declare function sameRuntimeConfiguration(left: PublishedGeneratorConfiguration, right: PublishedGeneratorConfiguration): boolean;

package/generator/vite/demo-application.d.ts

@@ -0,0 +1,34 @@
+/** The generated module of the demo application, in the output root (`demo-app.ts.nunj`). */
+export declare const DEMO_APPLICATION_MODULE = "demo-app.ts";
+/**
+ * The demo application of a generation: its generated module and the URL path of its pages.
+ * The NgDoc plugin publishes it to the application plugin (`NgDocDemoApplicationApi`).
+ */
+export interface NgDocDemoApplication {
+    /** The generated module (absolute), which exports the routes and the providers import. */
+    readonly module: string;
+    /** The URL path of the demo pages, relative to the base href, without slashes around it. */
+    readonly path: string;
+    /** Every demo page, relative to the base href (`<path>/<page route>/<demo name>`). */
+    readonly pages: readonly string[];
+}
+/**
+ * What the NgDoc plugin offers the application plugin through `api.ngDocDemoApplication`.
+ * @internal
+ */
+export interface NgDocDemoApplicationApi {
+    readonly schemaVersion: 1;
+    /**
+     * The demo application of the build's generation, generating first if the build has not yet: a
+     * build adds the demo page's input before it starts, when there is one.
+     */
+    resolve(): Promise<NgDocDemoApplication | undefined>;
+    /** The demo application of the current generation of the development server, if any. */
+    current(): Promise<NgDocDemoApplication | undefined>;
+}
+/**
+ * Reads the demo application from a committed output root: a generation writes `demo-app.ts`
+ * only when a guide has demo pages, and that module names the URL path of the pages.
+ * @param outputRoot - The output root of the published generation.
+ */
+export declare function readDemoApplication(outputRoot: string): Promise<NgDocDemoApplication | undefined>;

package/generator/vite/dev-server-builder.js

@@ -0,0 +1,339 @@
+// libs/builder/generator/vite/dev-server-builder.ts
+import { createBuilder } from "@angular-devkit/architect";
+
+// libs/builder/generator/vite/builders.ts
+import path2 from "node:path";
+import { Observable } from "rxjs";
+import { createServer as viteCreateServer } from "vite";
+
+// libs/builder/generator/vite/production.ts
+import { existsSync } from "node:fs";
+import { rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { build as viteBuild } from "vite";
+
+// libs/builder/generator/vite/angular-version.ts
+import { createRequire } from "node:module";
+var TRANSFORM_OPTIONS_ANGULAR = "22.2.0";
+var VERSION = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.+-]*)?$/;
+function parse(version) {
+  const match = VERSION.exec(version);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : void 0;
+}
+function usesTransformOptions([major, minor, patch]) {
+  const [lowMajor, lowMinor, lowPatch] = parse(TRANSFORM_OPTIONS_ANGULAR);
+  if (major !== lowMajor) return major > lowMajor;
+  if (minor !== lowMinor) return minor > lowMinor;
+  return patch >= lowPatch;
+}
+function isConsistentAngularBuild(compiler, build) {
+  const left = parse(compiler);
+  const right = parse(build);
+  if (!left || !right || left[0] !== right[0]) return false;
+  return usesTransformOptions(left) === usesTransformOptions(right);
+}
+function resolveVersion(name) {
+  try {
+    const manifest = createRequire(import.meta.url)(`${name}/package.json`);
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveAngularCompilerVersion() {
+  return resolveVersion("@angular/compiler-cli");
+}
+function resolveAngularBuildVersion() {
+  return resolveVersion("@angular/build");
+}
+function assertConsistentAngularBuild(compiler = resolveAngularCompilerVersion(), build = resolveAngularBuildVersion()) {
+  if (compiler && build && isConsistentAngularBuild(compiler, build)) return;
+  if (!compiler || !build) {
+    const missing = !compiler ? "@angular/compiler-cli" : "@angular/build";
+    throw new Error(
+      `[NGDOC_VITE_ANGULAR_VERSION] The NgDoc Vite engine needs @angular/compiler-cli and @angular/build of the application's Angular 22, but ${missing} is not installed. Install it in the application's devDependencies: npm i -D ${missing}@22.`
+    );
+  }
+  throw new Error(
+    `[NGDOC_VITE_ANGULAR_VERSION] NgDoc resolves @angular/compiler-cli ${compiler} and @angular/build ${build}, which belong to different Angular releases: the Vite engine drives @angular/build through the compiler's version, so both must be from before ${TRANSFORM_OPTIONS_ANGULAR} or both from ${TRANSFORM_OPTIONS_ANGULAR} or later. This usually means a second @angular/build was installed for NgDoc: check with \`npm ls @angular/build\`, then install the same Angular version for every @angular/* package (ng update @angular/core@22 @angular/cli@22) and reinstall, or deduplicate @angular/build (npm dedupe, an override or a resolution).`
+  );
+}
+
+// libs/builder/generator/vite/prerender.ts
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+function prerenderError(code, message2) {
+  return new Error(`[${code}] ${message2}`);
+}
+function heapArguments(execArgv) {
+  return execArgv.filter(
+    (item) => /^--(?:max-old-space-size|max-semi-space-size|stack-size)=/.test(item)
+  );
+}
+function prerenderNgDoc(options) {
+  const request = {
+    browserDir: options.browserDir,
+    serverEntry: options.serverEntry,
+    routes: [...options.routes ?? []],
+    discoverRoutes: options.discoverRoutes ?? true,
+    ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
+    ...options.demoServerEntry ? { demoServerEntry: options.demoServerEntry } : {}
+  };
+  if (request.routeTimeoutMs !== void 0 && (!Number.isSafeInteger(request.routeTimeoutMs) || request.routeTimeoutMs < 1)) {
+    return Promise.reject(
+      prerenderError("NGDOC_PRERENDER_OPTION", "routeTimeoutMs must be a positive integer.")
+    );
+  }
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+      reject(prerenderError("NGDOC_PRERENDER_ABORTED", "Prerendering was aborted."));
+      return;
+    }
+    const child = fork(
+      fileURLToPath(options.entryUrl ?? new URL("./prerender-entry.js", import.meta.url)),
+      [],
+      // Keep the host's heap limits (a large site renders many routes in one process), nothing else.
+      { execArgv: heapArguments(process.execArgv), stdio: ["ignore", "inherit", "inherit", "ipc"] }
+    );
+    let reply;
+    const abort = () => child.kill("SIGKILL");
+    options.signal?.addEventListener("abort", abort, { once: true });
+    child.on("message", (message2) => {
+      reply ??= message2;
+    });
+    child.once("error", (error) => {
+      options.signal?.removeEventListener("abort", abort);
+      reject(error);
+    });
+    child.once("exit", (code, signal) => {
+      options.signal?.removeEventListener("abort", abort);
+      if (options.signal?.aborted) {
+        reject(prerenderError("NGDOC_PRERENDER_ABORTED", "Prerendering was aborted."));
+      } else if (reply?.type === "result" && code === 0) {
+        resolve(reply.report);
+      } else if (reply?.type === "error") {
+        reject(new Error(reply.message));
+      } else {
+        reject(
+          prerenderError(
+            "NGDOC_PRERENDER_EXIT",
+            `The prerender process exited without a result (code=${String(code)}, signal=${String(signal)}).`
+          )
+        );
+      }
+    });
+    child.send(request, () => {
+    });
+  });
+}
+
+// libs/builder/generator/vite/vite-version.ts
+import { version as resolvedViteVersion } from "vite";
+var SUPPORTED_VITE_RANGE = "^8.3.0";
+var SUPPORTED_MAJOR = 8;
+var MINIMUM_MINOR = 3;
+function isSupportedViteVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+  if (!match) return false;
+  const [major, minor, patch] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  if (major !== SUPPORTED_MAJOR || minor < MINIMUM_MINOR) return false;
+  return !(match[4] && minor === MINIMUM_MINOR && patch === 0);
+}
+function assertSupportedViteVersion(found = resolvedViteVersion) {
+  if (found && isSupportedViteVersion(found)) return;
+  throw new Error(
+    `[NGDOC_VITE_VERSION] The NgDoc Vite engine requires vite ${SUPPORTED_VITE_RANGE}, but vite ${found || "(unknown version)"} is running. Install a supported release in the application's devDependencies: npm i -D vite@${SUPPORTED_VITE_RANGE}. The legacy builders (@ng-doc/builder:application and dev-server) do not use Vite.`
+  );
+}
+
+// libs/builder/generator/vite/production.ts
+var defaultDependencies = {
+  build: viteBuild,
+  prerender: prerenderNgDoc
+};
+function generationHandoff() {
+  const handoff = { schemaVersion: 1 };
+  return { name: "@ng-doc/vite:generation-handoff", api: { ngDocGeneration: handoff } };
+}
+function buildError(code, message2) {
+  return new Error(`[${code}] ${message2}`);
+}
+function applicationProbe() {
+  let found;
+  return {
+    plugin: {
+      name: "@ng-doc/vite:build-probe",
+      configResolved(config) {
+        const matches = config.plugins.filter(
+          (plugin) => plugin.api?.ngDocApplication?.schemaVersion === 1
+        );
+        if (matches.length > 1) {
+          throw buildError(
+            "NGDOC_VITE_APPLICATION",
+            "Expected at most one createNgDocApplicationPlugin in the Vite configuration."
+          );
+        }
+        found = matches[0]?.api.ngDocApplication;
+      }
+    },
+    api: () => found
+  };
+}
+async function buildNgDocViteApplication(options, dependencies = defaultDependencies) {
+  assertSupportedViteVersion();
+  assertConsistentAngularBuild();
+  const configFile = path.resolve(options.configFile);
+  const outputPath = path.resolve(options.outputPath);
+  const browser = path.join(outputPath, "browser");
+  const serverDirectory = path.join(outputPath, "server");
+  const serverEntry = path.join(serverDirectory, "server.mjs");
+  const mode = options.mode ?? "production";
+  const log = options.log ?? (() => {
+  });
+  const aborted = () => {
+    if (options.signal?.aborted)
+      throw buildError("NGDOC_VITE_BUILD_ABORTED", "The build was aborted.");
+  };
+  const timed = async (label, step) => {
+    const started = Date.now();
+    const value = await step();
+    log(`${label} in ${((Date.now() - started) / 1e3).toFixed(1)} s`);
+    return value;
+  };
+  let ssr = options.ssr;
+  const noServer = () => buildError(
+    "NGDOC_VITE_SERVER_ENTRY",
+    "Prerendering needs the server bundle: build it (ssr) from createNgDocApplicationPlugin with a server entry."
+  );
+  if (!options.skipBuild && options.prerender === true && options.ssr === false) throw noServer();
+  if (!options.skipBuild) {
+    const probe = applicationProbe();
+    const generation = generationHandoff();
+    await timed(
+      `Built the browser bundle into ${browser}`,
+      () => dependencies.build({
+        configFile,
+        mode,
+        plugins: [probe.plugin, generation],
+        build: { outDir: browser, emptyOutDir: true }
+      })
+    );
+    aborted();
+    const entry = probe.api()?.serverEntry;
+    ssr ??= entry !== void 0;
+    if (!ssr) {
+      await rm(serverDirectory, { recursive: true, force: true });
+      await rm(path.join(outputPath, "prerendered-routes.json"), { force: true });
+      if (options.prerender === true) throw noServer();
+    } else {
+      if (!entry) {
+        throw buildError(
+          "NGDOC_VITE_SERVER_ENTRY",
+          "The server build needs createNgDocApplicationPlugin with a server entry in the Vite configuration."
+        );
+      }
+      await timed(
+        `Built the server bundle into ${serverDirectory}`,
+        () => dependencies.build({
+          configFile,
+          mode,
+          plugins: [generation],
+          build: {
+            ssr: true,
+            outDir: serverDirectory,
+            emptyOutDir: true,
+            rolldownOptions: {
+              input: { server: entry },
+              output: {
+                format: "es",
+                entryFileNames: "[name].mjs",
+                chunkFileNames: "chunks/[name]-[hash].mjs"
+              }
+            }
+          }
+        })
+      );
+      aborted();
+    }
+  }
+  const prerender = options.prerender ?? (options.skipBuild ? true : ssr === true);
+  if (!prerender) return { browser, ...ssr ? { server: serverEntry } : {} };
+  const demoServerEntry = path.join(serverDirectory, "demo-server.mjs");
+  const report = await timed(
+    "Prerendered the routes",
+    () => dependencies.prerender({
+      browserDir: browser,
+      serverEntry,
+      ...existsSync(demoServerEntry) && existsSync(path.join(browser, "ng-doc-demo.html")) ? { demoServerEntry } : {},
+      routes: options.routes ?? [],
+      discoverRoutes: options.discoverRoutes ?? true,
+      ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
+      ...options.signal ? { signal: options.signal } : {}
+    })
+  );
+  await writeFile(
+    path.join(outputPath, "prerendered-routes.json"),
+    `${JSON.stringify({ routes: report.routes, excluded: report.excluded }, null, 2)}
+`
+  );
+  log(`Prerendered ${report.routes.length} route(s) into ${browser}`);
+  for (const { route, message: message2 } of report.warnings ?? []) log(`Warning: ${route}: ${message2}`);
+  if (report.errors.length) {
+    log(`The application logged ${report.errors.length} error(s) while prerendering:`);
+    for (const { route, message: message2 } of report.errors.slice(0, 10)) log(`  ${route}: ${message2}`);
+  }
+  return { browser, server: serverEntry, prerendered: report };
+}
+
+// libs/builder/generator/vite/builders.ts
+var defaultDependencies2 = {
+  build: (options) => buildNgDocViteApplication(options),
+  createServer: viteCreateServer
+};
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function runViteDevServerBuilder(options, context, dependencies = defaultDependencies2) {
+  return new Observable((subscriber) => {
+    let server;
+    let stopped = false;
+    const close = () => server?.close().catch((error) => context.logger.error(message(error)));
+    void (async () => {
+      try {
+        server = await dependencies.createServer({
+          configFile: path2.resolve(context.workspaceRoot, options.configFile),
+          mode: options.mode ?? "development",
+          server: {
+            ...options.host === void 0 ? {} : { host: options.host },
+            ...options.port === void 0 ? {} : { port: options.port }
+          }
+        });
+        if (stopped) {
+          await close();
+          return;
+        }
+        await server.listen();
+        server.printUrls();
+        const baseUrl = server.resolvedUrls?.local[0];
+        subscriber.next({ success: true, ...baseUrl ? { baseUrl } : {} });
+      } catch (error) {
+        context.logger.error(message(error));
+        await close();
+        subscriber.next({ success: false, error: message(error) });
+        subscriber.complete();
+      }
+    })();
+    return () => {
+      stopped = true;
+      void close();
+    };
+  });
+}
+
+// libs/builder/generator/vite/dev-server-builder.ts
+var dev_server_builder_default = createBuilder(
+  (options, context) => runViteDevServerBuilder(options, context)
+);
+export {
+  dev_server_builder_default as default
+};

package/generator/vite/dev-server-builder.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "NgDoc Vite development server",
+  "description": "Serves an Angular application with the Vite development server and the NgDoc Vite engine.",
+  "type": "object",
+  "properties": {
+    "configFile": {
+      "type": "string",
+      "description": "The Vite configuration file, relative to the workspace root."
+    },
+    "mode": {
+      "type": "string",
+      "description": "The Vite mode.",
+      "default": "development"
+    },
+    "host": {
+      "type": "string",
+      "description": "The host to listen on. Defaults to the Vite configuration's server.host."
+    },
+    "port": {
+      "type": "number",
+      "description": "The port to listen on. Defaults to the Vite configuration's server.port."
+    }
+  },
+  "required": ["configFile"],
+  "additionalProperties": false
+}

package/generator/vite/dev-styles.d.ts

@@ -0,0 +1,65 @@
+import type { HtmlTagDescriptor, ViteDevServer } from 'vite';
+/** Timings of the development style gate, in milliseconds. */
+export interface NgDocDevStyleGateTimings {
+    /** How long one style sheet may hide content before the gate stops waiting for it. */
+    readonly sheet: number;
+    /** How long the page must add no component style sheet before the initial load is over. */
+    readonly quiet: number;
+    /** How long after the script starts the initial load is over, whatever happens. */
+    readonly limit: number;
+}
+/**
+ * Returns the inline script that keeps the first paint of a development page from showing
+ * components without their styles.
+ *
+ * With live reload, Analog compiles component styles to external style sheets: Angular adds a
+ * `<link rel="stylesheet">` for a component when it first creates it, in the same task as the
+ * component's elements. A link added by a script does not block rendering, so the component
+ * paints unstyled until its sheet arrives. Production inlines the styles, and server rendering
+ * puts them in the page, so neither has the problem.
+ *
+ * Only the initial load is gated: from the start of the page until it has added no component
+ * sheet for `quiet` ms with none pending, until the reader's first input, or until `limit` ms,
+ * whichever comes first. During it, the gate hides the body until every component sheet the page
+ * adds has loaded (or failed, or waited `sheet` ms), so the first paint is styled, the way the
+ * render-blocking styles of a production page are. Angular names a component in its sheet's URL
+ * (`?ngcomp`); other sheets are ignored. After the initial load the gate hides nothing: a
+ * component created later (a dialog, the search palette) may paint unstyled for a moment in
+ * development, but the page never blanks and focus is never moved off a hidden element.
+ *
+ * It is a string, not a function's source, so no build or coverage tool can rewrite it with
+ * helpers the page does not have. The mutation observer runs before the next paint, because
+ * Angular adds the link and the elements in one task.
+ * @param timings - The timings, in milliseconds.
+ * @returns The script.
+ */
+export declare function ngDocDevStyleGate(timings?: NgDocDevStyleGateTimings): string;
+/** The development style gate with its default timings. */
+export declare const NG_DOC_DEV_STYLE_GATE: string;
+/**
+ * The index page tags that let the first paint of a development page look like production:
+ * the global style sheets inlined in `<head>`, and the component style gate.
+ *
+ * Vite adds a global style sheet with a script, after the application's modules have loaded, so
+ * the first paint has no global styles: no font, layout or theme background (a dark theme paints
+ * white first). Each inlined sheet is a `<style data-vite-dev-id>` with the id Vite's client
+ * uses for it: the client adopts the element, so the module's own copy replaces its text in
+ * place, and hot updates keep working, with no duplicate and no change of order. A sheet that
+ * fails to compile is left to the module, which reports the error.
+ * @param server - The development server.
+ * @param styles - The global style sheets, as absolute paths.
+ * @returns The tags to add to `<head>`.
+ */
+export declare function ngDocDevStyleTags(server: ViteDevServer, styles: readonly string[]): Promise<HtmlTagDescriptor[]>;
+/**
+ * Reads the id and the CSS out of a style sheet module as Vite serves it in development. The
+ * page imports that same module, so transforming it here costs nothing extra; a `?direct`
+ * request would add a second module that every edit of the sheet then hot-updates, which makes
+ * the client reload the page.
+ * @param code - The module's code.
+ * @returns The sheet, or `undefined` for code in another shape.
+ */
+export declare function cssModuleSheet(code: string): {
+    id: string;
+    css: string;
+} | undefined;

package/generator/vite/diagnostics.d.ts

@@ -0,0 +1,4 @@
+import type { BuildResult, Diagnostic } from '../contracts.js';
+export declare function diagnosticText(diagnostic: Diagnostic): string;
+export declare function resultError(result: BuildResult, fallback: string): Error;
+export declare function hostDiagnostic(code: string, message: string): Diagnostic;

package/generator/vite/external-probes.d.ts

@@ -0,0 +1,40 @@
+import type { FileChange } from '../contracts.js';
+/**
+ * How often a recorded file outside the workspace is re-checked. These are configuration lookups
+ * (`.editorconfig`, `.prettierrc*`, `package.json` in the directories above the workspace) and
+ * rarely edited, so a change there is noticed within about a second.
+ */
+export declare const EXTERNAL_PROBE_INTERVAL_MS = 1000;
+/**
+ * At most this many files outside the workspace are polled. More are handed to the native watcher
+ * as before, so a workspace whose inputs mostly live elsewhere never turns into a stat storm.
+ */
+export declare const MAX_EXTERNAL_PROBES = 512;
+/** A file's probe state: its metadata signature, `missing`, or the code of a failed lookup. */
+export declare function probeState(file: string): string;
+/**
+ * Watches individual files outside the workspace by polling their metadata instead of attaching
+ * the shared native watcher to them. chokidar's FSEvents backend watches a missing or extension
+ * file through its directory and consolidates nearby streams upwards, so a probe such as
+ * `/.editorconfig` or `/package.json` made the Vite process subscribe to every file event on the
+ * disk (`/`, `/Users`). A poll costs one `stat` per probe per interval and sees exactly the probed
+ * path: its creation, change and removal.
+ *
+ * The baseline is taken synchronously when a path is added, before the generation that recorded
+ * it is published, so a change after that point is reported on the next poll.
+ */
+export declare class ExternalProbeWatcher {
+    private readonly emit;
+    private readonly intervalMs;
+    private readonly states;
+    private timer?;
+    private polling;
+    private disposed;
+    constructor(emit: (change: FileChange) => void, intervalMs?: number);
+    get size(): number;
+    has(file: string): boolean;
+    add(files: readonly string[]): void;
+    /** One pass over every probe; exported for deterministic tests. */
+    poll(): Promise<void>;
+    dispose(): void;
+}