@ng-doc/builder 22.0.0 → 22.1.0

package/generator/compiler/plan.d.ts

@@ -1,5 +1,6 @@
 import { JsonArtifactCache } from '../artifacts/index.js';
 import { GeneratorContentCompiler } from '../content/content-compiler.js';
+import { type FormatSession } from '../content/format-cache.js';
 import { type HighlightSession } from '../content/highlight-cache.js';
 import { type RenderBack } from '../content/html-pool.js';
 import type { CompilationRequest, Dependency, Diagnostic, DiscoverySnapshot, PageArtifact, RebuildReason } from '../contracts.js';
@@ -58,12 +59,24 @@ export interface GenerationPlan extends CompilationServices {
     compiler: GeneratorContentCompiler;
     /** The cache of highlighted code blocks, when this generation uses one (`content/highlight-cache`). */
     highlight?: HighlightSession;
+    /** The cache of formatted signatures and snippets, when this generation uses one (`content/format-cache`). */
+    format?: FormatSession;
     /** Where the content's HTML pipeline runs, when it may run on threads (`content/html-pool`). */
     back?: RenderBack;
 }
 /**
  * Setup phase: previous artifacts (session snapshot or cache index), reuse switches and the output
  * templates. Its diagnostics are recorded as the `setup` phase.
+ * @param services
+ * @param input
+ * @param input.request
+ * @param input.signal
+ * @param input.records
+ * @param input.refresher
+ * @param input.found
+ * @param input.programDependencies
+ * @param input.scopedSemantic
+ * @param input.scratch
  */
 export declare function planGeneration(services: CompilationServices, input: {
     request: CompilationRequest;
@@ -82,11 +95,22 @@ export declare function planGeneration(services: CompilationServices, input: {
 /**
  * Plan phase, after describe: the current descriptor plan, in which a duplicate descriptor fails
  * the generation. Every descriptor of the plan is rendered.
+ * @param plan
+ * @param units
  */
 export declare function planContent(plan: GenerationPlan, units: Unit[]): void;
 /**
  * The artifacts the cache index names, in its order. An entry that cannot be read is left out
  * with its diagnostics; an index of another schema version restores nothing.
+ * @param root
+ * @param projectId
+ * @param diagnostics
  */
 export declare function restoreIndex(root: string, projectId: string, diagnostics: Diagnostic[]): Promise<PageArtifact[]>;
+/**
+ *
+ * @param root
+ * @param projectId
+ * @param artifacts
+ */
 export declare function saveIndex(root: string, projectId: string, artifacts: PageArtifact[]): Promise<void>;

package/generator/content/code-snippet.d.ts

@@ -0,0 +1,20 @@
+/** The code of a named snippet, or why a file has none. */
+export type SnippetRegion = {
+    status: 'found';
+    code: string;
+} | {
+    status: 'unknown';
+} | {
+    status: 'unclosed';
+};
+/**
+ * The region of `text` between the first `snippet#<id>` marker and the next marker with the same
+ * id, as a code block's `file="./x.ts"#<id>` shows it: every marker line inside it is removed
+ * (nested snippets included, as in demos) and so are `ng-doc-ignore-line` lines, blank lines
+ * around it are dropped, and the common indentation is taken off, so a region inside a class
+ * reads like top-level code. Lines end with LF whatever the file uses, so the output never
+ * depends on the platform that saved the file.
+ * @param text - The whole file.
+ * @param id - The snippet id.
+ */
+export declare function snippetRegion(text: string, id: string): SnippetRegion;

package/generator/content/content-compiler.d.ts

@@ -30,13 +30,17 @@ export declare class GeneratorContentCompiler implements ContentCompiler {
     private readonly services;
     private readonly highlight?;
     private readonly back?;
+    /** The Shiki grammars highlighting loads (`grammarsSwitch`). */
+    private readonly grammars;
     /**
      * @param services - What the compiler reads.
      * @param highlight - The generation's cache of highlighted code blocks; without it, every block
      *   is highlighted (`./highlight-cache`).
      * @param back - Where the HTML pipeline runs; without it, in this thread, at once.
      */
-    constructor(services: ContentCompilerServices, highlight?: HighlightSession | undefined, back?: ContentBack | undefined);
+    constructor(services: ContentCompilerServices, highlight?: HighlightSession | undefined, back?: ContentBack | undefined, 
+    /** The Shiki grammars highlighting loads (`grammarsSwitch`). */
+    grammars?: 'used' | 'all');
     /**
      * Whether this call records its footprint. The semantic service's effective recorder state
      * decides when it reports one: a service that records nothing, or whose probe or install failed,

package/generator/content/format-cache.d.ts

@@ -0,0 +1,108 @@
+import type { Options } from 'prettier';
+import type { CompilationRequest, GeneratorConfiguration } from '../contracts.js';
+/**
+ * The cache of formatted code: API signatures and demo snippets that `formatCode` formats with
+ * Prettier (`helpers/format-code.ts`), the main thread's largest cost after highlighting at a
+ * cold start. Each call resolved the Prettier configuration again and formatted through
+ * `@prettier/sync`'s worker.
+ *
+ * - **Configuration.** One generation resolves the configuration of a directory once. The files
+ *   it reads (`.prettierrc*`, `prettier.config.*`, `.editorconfig`, `package.json` in the workspace
+ *   root and every directory above it) are already program inputs of every page that formats
+ *   (`trackFormatterConfiguration`), so an edit of one runs a new generation, which resolves
+ *   again.
+ * - **Formatted code.** Formatting is a pure function of the code, the parser, the resolved
+ *   configuration and the Prettier release, so its result is cached under
+ *   `digestOf({ context, parser, config, code })`: the context is this cache's format and the
+ *   resolved versions of `prettier` and `@prettier/sync`, and `config` the resolved configuration
+ *   with the versions of the plugins it names. A configuration that cannot be identified exactly
+ *   (a value JSON cannot hold, a plugin given as a path or that does not resolve to a package) is
+ *   never cached: such code is formatted every time. Code Prettier rejects with a syntax error
+ *   (signatures such as a bare `constructor(…): T;` always are) is cached as such and throws
+ *   again, so `formatCode` returns it unformatted as before; any other error stores nothing.
+ * - **Storage.** One map per runtime, kept across generations by a long-lived runtime and
+ *   cleared when it outgrows {@link FORMAT_CACHE_LIMIT}. Development generations with the artifact
+ *   cache read `<hash(projectId)>.format.json` beside it once per runtime and context, and write it
+ *   after the cache (best effort, atomic, skipped when unchanged), like the highlight cache.
+ *   Production, `cache: false` and the reference path never read or write the pack.
+ *
+ * No dependency or watch input is added: the result depends only on the key, and the
+ * configuration's own files are recorded where the program is built.
+ *
+ * `NGDOC_FORMAT_CACHE=0` (`CompilationOptions.formatCache: false`) formats every call as before;
+ * `verify` resolves the configuration and formats every hit again, uses the fresh result and
+ * reports `CONTENT_FORMAT_CACHE_MISMATCH` when one differs. The semantic service formats through
+ * the session the compiler installs for the generation (`semantic/formatting.ts`).
+ */
+/** The warning of a `verify` hit (or configuration) that differs from the cached one. */
+export declare const FORMAT_CACHE_MISMATCH = "CONTENT_FORMAT_CACHE_MISMATCH";
+/**
+ * Above this size (keys and values, in UTF-16 code units) the pack and the map keep only the
+ * entries of the current generation.
+ */
+export declare const FORMAT_CACHE_LIMIT: number;
+/**
+ * The cache's switch: `off`, `on` or `verify`.
+ * @param options
+ * @param options.formatCache
+ */
+export declare function formatCacheSwitch(options: {
+    formatCache?: boolean | 'verify';
+}): 'off' | 'on' | 'verify';
+/**
+ * The cache of one generation, or undefined when code is formatted without it: with the switch
+ * off, and on the reference path (`incrementalReuse: false`), which recomputes everything. Only
+ * a development generation with the artifact cache on keeps a pack.
+ * @param options
+ * @param options.projectId
+ * @param options.incrementalReuse
+ * @param options.formatCache
+ * @param request
+ * @param configuration
+ */
+export declare function createFormatSession(options: {
+    projectId: string;
+    incrementalReuse?: boolean;
+    formatCache?: boolean | 'verify';
+}, request: Pick<CompilationRequest, 'mode'>, configuration: Pick<GeneratorConfiguration, 'cacheEnabled' | 'cacheRoot'>): FormatSession | undefined;
+/**
+ * One generation's use of the cache: its resolved configurations, the keys it used, its pack. It
+ * is a `FormatCodeCache` (`helpers/format-cache.ts`), structurally: the published declarations
+ * reach this class, and they cannot import from outside the generator.
+ */
+export declare class FormatSession {
+    readonly verify: boolean;
+    readonly pack: string | undefined;
+    readonly context: string;
+    /** The keys this generation hit or formatted. */
+    private readonly used;
+    /** The resolved configuration per directory (`''` for the process's working directory). */
+    private readonly configs;
+    /** Each resolved configuration's identity in the keys; undefined: not cacheable. */
+    private readonly identities;
+    private loaded;
+    /** An entry was replaced (a `verify` repair): the pack must be written. */
+    private replaced;
+    private mismatchCount;
+    constructor(verify: boolean, pack: string | undefined);
+    /** How many `verify` hits and configurations differed from the cached ones. */
+    get mismatches(): number;
+    config(configDirectory: string | undefined, resolve: () => Options | null): Options | null;
+    format(input: {
+        code: string;
+        parser: string;
+        config: Options | null;
+    }, format: () => string): string;
+    /**
+     * Writes the pack after the artifact cache: the entries this generation hit or formatted, plus
+     * those the pack held before unless the generation rendered every content (`complete`), or the
+     * result would exceed {@link FORMAT_CACHE_LIMIT}. Best effort.
+     * @param complete
+     */
+    save(complete: boolean): Promise<void>;
+    private remember;
+    /** Reads the pack once per runtime and context; an unusable pack is not read. */
+    private load;
+}
+/** Forgets every entry and pack of this runtime (tests). */
+export declare function resetFormatCache(): void;

package/generator/content/highlight-cache.d.ts

@@ -1,37 +1,4 @@
-import type { CompilationRequest, GeneratorConfiguration } from '../contracts.js';
-/**
- * The cache of highlighted code blocks (`processHtml`'s `highlight` option, `@ng-doc/utils`).
- *
- * Highlighting a block is a pure function of its text, language and meta string, the themes, the
- * fixed options of the highlighting plugin and the Shiki release, so its result is cached under a
- * key that covers all of them: `digestOf({ context, block })`, where the context is the format of
- * this cache, the resolved versions of `shiki`, `@shikijs/core` and `@shikijs/rehype`
- * (`runtimePackages`) and the identity of each theme (a bundled theme's name; NgDoc's own theme by
- * the digest of its definition), and the block names the plugin's format and options, the theme
- * names, the language before its fallback, the raw meta string and the text. A Shiki upgrade or a
- * plugin change therefore changes every key, and a stale entry is never hit.
- *
- * Every runtime (each thread) keeps one map of entries, which a long-lived runtime keeps across
- * generations. A development generation with the artifact cache on also reads a pack of entries
- * beside the cache (`<hash(projectId)>.highlight.json`) the first time it highlights, and writes
- * it after the cache (best effort, atomically replaced, skipped when unchanged). Production, the
- * reference path and `cache: false` never read or write the pack: they use the map only.
- *
- * A cached entry can never change output: the plugin uses an entry only when it is a JSON array of
- * HAST elements and highlights the block otherwise, it stores only blocks that were highlighted
- * without an error, and a pack of another version or context, or one that cannot be read or
- * parsed, is not read. No dependency or watch input is added: the result depends only on the key.
- *
- * `NGDOC_HIGHLIGHT_CACHE=0` (`CompilationOptions.highlightCache: false`) highlights every block
- * with the plain `@shikijs/rehype` plugin, which sets its highlighter up again for every document;
- * `verify` highlights every hit again, uses the fresh result and reports
- * `CONTENT_HIGHLIGHT_CACHE_MISMATCH` when it differs.
- *
- * The entries are plain strings, so a render thread (`./html-pool`) is handed them (the journal of
- * this runtime's writes, `highlightJournal`) and returns what it hit and highlighted, which the
- * main thread merges (`HighlightSession.merge`); the key is a function of the block alone. Only the
- * main thread reads and writes the pack.
- */
+import type { CompilationRequest, GeneratorConfiguration, ShikiLanguage } from '../contracts.js';
 /** The warning of a `verify` hit whose highlighting differs from the cached one. */
 export declare const HIGHLIGHT_CACHE_MISMATCH = "CONTENT_HIGHLIGHT_CACHE_MISMATCH";
 /**
@@ -46,6 +13,7 @@ export interface HighlightBlock {
         readonly light: string;
         readonly dark: string;
     };
+    readonly languages?: string;
     readonly lang: string;
     readonly meta: string;
     readonly code: string;
@@ -70,6 +38,14 @@ export declare function highlightJournal(): {
 export declare function highlightCacheSwitch(options: {
     highlightCache?: boolean | 'verify';
 }): 'off' | 'on' | 'verify';
+/**
+ * Which Shiki grammars highlighting loads: only those code blocks reach (`used`, the default), or
+ * every bundled grammar (`all`: `usedGrammars: false` or `NGDOC_USED_GRAMMARS=0`). The HTML is the
+ * same, so neither the cache keys nor any digest depend on it.
+ */
+export declare function grammarsSwitch(options: {
+    usedGrammars?: boolean;
+}): 'used' | 'all';
 /**
  * The cache of one generation, or undefined when blocks are highlighted without it: with the
  * switch off, and on the reference path (`incrementalReuse: false`), which recomputes everything.
@@ -79,7 +55,7 @@ export declare function createHighlightSession(options: {
     projectId: string;
     incrementalReuse?: boolean;
     highlightCache?: boolean | 'verify';
-}, request: Pick<CompilationRequest, 'mode'>, configuration: Pick<GeneratorConfiguration, 'cacheEnabled' | 'cacheRoot' | 'themes'>): HighlightSession | undefined;
+}, request: Pick<CompilationRequest, 'mode'>, configuration: Pick<GeneratorConfiguration, 'cacheEnabled' | 'cacheRoot' | 'themes' | 'shikiLangs'>): HighlightSession | undefined;
 /** One generation's use of the cache: what it hit or highlighted, and its pack. */
 export declare class HighlightSession {
     readonly themes: {
@@ -97,7 +73,7 @@ export declare class HighlightSession {
     constructor(themes: {
         readonly light: string;
         readonly dark: string;
-    }, verify: boolean, pack: string | undefined);
+    }, verify: boolean, pack: string | undefined, langs?: readonly ShikiLanguage[]);
     /** The cache of one `processHtml` call. */
     call(): HighlightCall;
     /**

package/generator/content/html-pipeline.d.ts

@@ -1,4 +1,4 @@
-import type { ContentAnchor, KeywordExport, SearchRecord } from '../contracts.js';
+import type { ContentAnchor, KeywordExport, SearchRecord, ShikiLanguage } from '../contracts.js';
 import type { HighlightBlock } from './highlight-cache.js';
 /**
  * The back half of content compilation: the HTML pipeline of `@ng-doc/utils` (process, post-process,
@@ -19,6 +19,8 @@ interface HtmlUtilities {
         route?: string;
         lightTheme?: string;
         darkTheme?: string;
+        langs?: readonly ShikiLanguage[];
+        grammars?: 'all' | 'used';
         highlight?: PipelineHighlight;
     }): Promise<{
         content: string;
@@ -60,6 +62,13 @@ export interface RenderTask {
         readonly light: string;
         readonly dark: string;
     };
+    /** The configured Shiki languages (`shiki.langs`); absent without any. */
+    readonly langs?: readonly ShikiLanguage[];
+    /**
+     * `all` when highlighting loads every bundled Shiki grammar (the switch is off); absent when it
+     * loads only the grammars code blocks reach. The HTML is the same.
+     */
+    readonly grammars?: 'all';
 }
 /**
  * What processing one document gave. `mismatches` counts the cached code blocks that `verify`

package/generator/content/html-pool.d.ts

@@ -1,5 +1,5 @@
 import { Worker } from 'node:worker_threads';
-import type { CompilationRequest, KeywordExport } from '../contracts.js';
+import type { CompilationRequest, KeywordExport, ShikiLanguage } from '../contracts.js';
 import type { ContentBack } from './content-compiler.js';
 export { PARALLEL_RENDER_MISMATCH } from './content-compiler.js';
 import { type HighlightSession } from './highlight-cache.js';
@@ -103,12 +103,18 @@ declare class HtmlThread {
     fail(error: Error): void;
     terminate(): Promise<void>;
 }
-/** A warm-up: the themes to set the highlighter up for, and whether the cached plugin is used. */
+/**
+ * A warm-up: the themes and languages to set the highlighter up for, and whether the cached
+ * plugin is used.
+ */
 export interface RenderWarmUp {
     themes: {
         light: string;
         dark: string;
     };
+    langs?: readonly ShikiLanguage[];
+    /** `all` when highlighting loads every bundled grammar. */
+    grammars?: 'all';
     cache: boolean;
 }
 /** Up to `size` render threads, started on demand. */