@openuji/speculator 0.2.0 → 0.3.1

package/dist/browser.d.ts

@@ -1,33 +1,78 @@
 import MarkdownIt from 'markdown-it';
 
 /**
- * Service responsible for processing data-format attributes and markdown content.
+ * Strategy interface for converting content based on its format.
  */
-declare class FormatProcessor {
-    private readonly markdownOptions;
-    constructor(markdownOptions?: MarkdownOptions);
+interface FormatStrategy {
+    convert(content: string): string;
+}
+/**
+ * Registry responsible for mapping formats to strategies and processing content.
+ */
+declare class FormatRegistry {
+    private readonly strategies;
+    constructor(markdownOptions?: MarkdownOptions, customStrategies?: Record<string, FormatStrategy>);
     /**
-     * Convert content based on the specified format.
+     * Register a new strategy for a given format.
      */
-    processContent(content: string, format: DataFormat): string;
+    register(format: DataFormat, strategy: FormatStrategy): void;
     /**
-     * Process an element with a data-format attribute.
+     * Convert content based on the specified format.
      */
-    process(element: Element, stats: ProcessingStats, warnings: string[]): void;
+    processContent(content: string, format: DataFormat): string;
+}
+
+declare class StatsTracker {
+    private _stats;
+    private startTime;
+    start(): void;
+    stop(): void;
+    incrementElements(count?: number): void;
+    incrementFiles(count?: number): void;
+    incrementMarkdownBlocks(count?: number): void;
+    toJSON(): ProcessingStats;
+}
+
+interface ProcessorResult {
+    content?: string | null;
+    error?: string;
+}
+interface ElementProcessor {
+    matches(element: Element): boolean;
+    process(element: Element, tracker: StatsTracker, warnings: string[]): Promise<ProcessorResult> | ProcessorResult;
 }
 
 /**
  * Service responsible for handling data-include attributes.
  */
-declare class IncludeProcessor {
+declare class IncludeProcessor implements ElementProcessor {
     private readonly baseUrl;
     private readonly fileLoader;
-    private readonly formatProcessor;
-    constructor(baseUrl: string | undefined, fileLoader: FileLoader, formatProcessor: FormatProcessor);
-    process(element: Element, stats: ProcessingStats, warnings: string[]): Promise<void>;
+    private readonly formatRegistry;
+    constructor(baseUrl: string | undefined, fileLoader: FileLoader, formatRegistry: FormatRegistry);
+    matches(element: Element): boolean;
+    process(element: Element, tracker: StatsTracker, warnings: string[]): Promise<ProcessorResult>;
     private resolveFilePath;
 }
 
+/**
+ * Result returned from {@link FormatProcessor.process}.
+ * When `error` is present, `content` will be undefined.
+ */
+interface FormatResult extends ProcessorResult {
+    content?: string;
+}
+/**
+ * Processor responsible for handling elements with a `data-format` attribute.
+ * Delegates content conversion to {@link FormatRegistry}.
+ */
+declare class FormatProcessor implements ElementProcessor {
+    private readonly registry;
+    constructor(registry?: FormatRegistry);
+    matches(element: Element): boolean;
+    process(element: Element, tracker: StatsTracker, _warnings: string[]): FormatResult;
+}
+
 /**
  * Abstraction over DOM parsing and serialization, allowing custom implementations.
  */
@@ -56,7 +101,9 @@ interface SpeculatorOptions {
     postprocess?: PostprocessOptions;
     includeProcessor?: IncludeProcessor;
     formatProcessor?: FormatProcessor;
+    formatRegistry?: FormatRegistry;
     htmlRenderer?: HtmlRenderer;
+    passes?: PipelinePass[] | ((container: Element) => PipelinePass[]);
 }
 /**
  * File loader function type
@@ -74,9 +121,20 @@ interface MarkdownOptions {
     smartypants?: boolean;
     /** Generate header IDs */
     headerIds?: boolean;
+    /** Enable Mermaid diagrams */
+    mermaid?: boolean | MermaidConfig;
     /** Custom renderer extensions */
     extensions?: Array<MarkdownIt.PluginSimple | [MarkdownIt.PluginWithOptions<any>, any]>;
 }
+/**
+ * Configuration options for the Mermaid markdown plugin
+ */
+interface MermaidConfig {
+    /** Theme to use when rendering diagrams */
+    theme?: string;
+    /** Additional Mermaid settings */
+    [key: string]: unknown;
+}
 /**
  * Processing result for a single element
  */
@@ -102,9 +160,10 @@ interface ProcessingStats {
     processingTime: number;
 }
 /**
- * Supported data formats
+ * Supported data formats. Additional formats can be provided by registering
+ * custom {@link FormatStrategy} implementations with {@link FormatRegistry}.
  */
-type DataFormat = 'markdown' | 'text' | 'html';
+type DataFormat = 'markdown' | 'text' | 'html' | (string & {});
 /**
  * Error thrown during rendering
  */
@@ -113,8 +172,84 @@ declare class SpeculatorError extends Error {
     readonly path?: string | undefined;
     constructor(message: string, element?: Element | undefined, path?: string | undefined);
 }
+/**
+ * Hook invoked after all pipeline passes have run.
+ */
+type PostProcessHook = (container: Element, outputs: Partial<Record<OutputArea, unknown>>) => void | Promise<void>;
+/**
+ * Result returned after rendering a {@link SpeculatorConfig}.
+ */
+interface RenderResult {
+    sections: Element[];
+    header?: Element;
+    sotd?: Element;
+    metadata?: Record<string, unknown>;
+    pubrules?: Element;
+    legal?: Element;
+    warnings: string[];
+    stats: ProcessingStats;
+    toc?: string;
+    boilerplate?: string[];
+    references?: string;
+}
+/**
+ * Full configuration for Speculator combining document areas and processing
+ * options.
+ */
+interface SpeculatorConfig extends SpeculatorOptions {
+    /** Document sections to process */
+    sections?: Element[];
+    /** Optional document header */
+    header?: Element;
+    /** Status of This Document section */
+    sotd?: Element;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+    /** Pubrules-specific content */
+    pubrules?: Element;
+    /** Legal boilerplate content */
+    legal?: Element;
+    /** Hook invoked before any processing begins. */
+    preHook?: (container: Element) => void | Promise<void>;
+    /** Hook invoked after rendering completes. */
+    postHook?: (result: RenderResult) => void | Promise<void>;
+    /** Hooks executed after pipeline passes complete. */
+    postProcess?: PostProcessHook | PostProcessHook[];
+    /** Additional, implementation-specific fields. */
+    [key: string]: unknown;
+}
+/**
+ * Respec's configuration shape. Used for migrating existing specs to the new
+ * {@link SpeculatorConfig}.
+ */
+interface RespecConfig extends SpeculatorConfig {
+    [key: string]: unknown;
+}
+/**
+ * Convert a {@link RespecConfig} object to a {@link SpeculatorConfig}.
+ */
+declare function fromRespecConfig(respec: RespecConfig): SpeculatorConfig;
+interface RenderHtmlResult {
+    sections: string;
+    toc: string;
+    header?: string;
+    sotd?: string;
+    metadata?: Record<string, unknown>;
+    pubrules?: string;
+    legal?: string;
+    warnings: string[];
+    stats: ProcessingStats;
+    boilerplate?: string[];
+    references?: string;
+}
 type XrefQuery = {
+    /** Unique identifier returned with results (internal use). */
+    id?: string;
+    /** The term to resolve. */
     term: string;
+    /** Optional list of spec shortnames to constrain the search. */
+    specs?: string[];
+    /** Additional context for the lookup (unused for now). */
     context?: string;
 };
 type XrefResult = {
@@ -123,11 +258,15 @@ type XrefResult = {
     cite?: string;
 };
 interface XrefResolver {
-    resolveBatch(queries: XrefQuery[], specs?: string[]): Promise<Map<string, XrefResult>>;
+    /**
+     * Resolve a batch of xref queries. The returned map is keyed by the query's
+     * `id` if provided, otherwise by the query term.
+     */
+    resolveBatch(queries: XrefQuery[]): Promise<Map<string, XrefResult[]>>;
 }
 interface XrefOptions {
     specs?: string[];
-    resolver?: XrefResolver;
+    resolver: XrefResolver;
 }
 interface BiblioEntry {
     id: string;
@@ -149,6 +288,12 @@ interface TocOptions {
     selector?: string;
     enabled?: boolean;
 }
+interface DiagnosticsOptions {
+    /** Suppress link warnings within elements having this class. */
+    suppressClass?: string;
+    /** Enable duplicate-id and missing-href checks (default true). */
+    idsAndLinks?: boolean;
+}
 interface BoilerplateOptions {
     conformance?: boolean | {
         title?: string;
@@ -167,29 +312,36 @@ interface BoilerplateOptions {
     };
     mount?: 'end' | 'before-references' | 'after-toc';
 }
-interface DiagnosticsOptions {
-    /** Suppress link warnings within elements having this class. */
-    suppressClass?: string;
-}
-interface DiagnosticsOptions {
-    suppressClass?: string;
-    /** Enable duplicate-id and missing-href checks (default true). */
-    idsAndLinks?: boolean;
+interface AssertionsOptions {
+    /** Override spec short name (e.g., 'ujse'). Defaults from baseUrl path. */
+    spec?: string;
+    /** Override version string (e.g., '1.0'). Defaults from baseUrl path. */
+    version?: string | number;
 }
 interface PostprocessOptions {
-    xref?: XrefOptions;
-    biblio?: BiblioOptions;
-    idl?: IdlOptions;
-    toc?: TocOptions;
-    diagnostics?: DiagnosticsOptions;
-}
-interface PostprocessOptions {
-    xref?: XrefOptions;
+    xref?: XrefOptions | XrefOptions[];
     biblio?: BiblioOptions;
     idl?: IdlOptions;
     toc?: TocOptions;
     diagnostics?: DiagnosticsOptions;
     boilerplate?: BoilerplateOptions;
+    assertions?: AssertionsOptions;
+}
+type OutputArea = 'idl' | 'xref' | 'references' | 'boilerplate' | 'toc' | 'diagnostics' | 'assertions' | 'metadata' | 'pubrules' | 'legal';
+interface PipelineContext {
+    /** Accumulated outputs from earlier passes. */
+    outputs: Partial<Record<OutputArea, unknown>>;
+    /** Accumulated warnings from executed passes. */
+    warnings: string[];
+    /** Full configuration for the current render. */
+    config: SpeculatorConfig;
+}
+type PipelineNext = () => Promise<void>;
+interface PipelinePass {
+    /** Which output area this pass is responsible for. */
+    area: OutputArea;
+    /** Execute the pass. */
+    run(context: PipelineContext, next: PipelineNext): Promise<void>;
 }
 
 /**
@@ -198,21 +350,29 @@ interface PostprocessOptions {
 declare class Speculator {
     private readonly includeProcessor;
     private readonly formatProcessor;
+    private readonly formatRegistry;
+    private readonly processors;
     private readonly htmlRenderer;
-    private readonly postprocessOptions;
+    private readonly baseConfig;
+    private readonly passFactory;
+    private readonly documentBuilder;
+    private readonly pipelineRunner;
+    private prevConfig;
     constructor(options?: SpeculatorOptions);
     /**
      * Process a single DOM element
      */
-    processElement(element: Element): Promise<ProcessingResult>;
+    processElement(element: Element, tracker?: StatsTracker): Promise<ProcessingResult>;
+    private processNode;
     /**
-     * Process an entire document
+     * Process an entire document described by a SpeculatorConfig
      */
-    renderDocument(container: Element): Promise<ProcessingResult>;
+    renderDocument(spec: SpeculatorConfig, configOrOutputs?: SpeculatorConfig | OutputArea[]): Promise<RenderResult>;
+    renderSections(inputHtml: string): Promise<RenderResult>;
     /**
      * Process HTML string and return processed HTML
      */
-    renderHTML(html: string): Promise<string>;
+    renderHTML(inputHtml: string): Promise<RenderHtmlResult>;
 }
 
 declare function createMarkdownRenderer(options?: MarkdownOptions): MarkdownIt;
@@ -222,10 +382,12 @@ declare function parseMarkdown(markdown: string, options?: MarkdownOptions, env?
  * Default file loader for Node.js environments
  */
 declare const nodeFileLoader: FileLoader;
+
 /**
  * Default file loader for browser environments
  */
 declare const browserFileLoader: FileLoader;
+
 /**
  * Creates a file loader that tries multiple loaders in sequence
  */
@@ -235,4 +397,22 @@ declare function createFallbackFileLoader(loaders: FileLoader[]): FileLoader;
  */
 declare function getDefaultFileLoader(): FileLoader;
 
-export { DOMHtmlRenderer, type DataFormat, type FileLoader, FormatProcessor, type HtmlRenderer, IncludeProcessor, type MarkdownOptions, type ProcessingResult, type ProcessingStats, Speculator, SpeculatorError, type SpeculatorOptions, browserFileLoader, createFallbackFileLoader, createMarkdownRenderer, getDefaultFileLoader, nodeFileLoader, parseMarkdown };
+/**
+ * Xref resolver that queries the public ReSpec xref database.
+ *
+ * The fetch implementation is injectable to allow easy testing.
+ */
+declare class RespecXrefResolver implements XrefResolver {
+    private readonly fetchFn;
+    private readonly endpoint;
+    constructor(fetchFn?: typeof fetch, endpoint?: string);
+    resolveBatch(queries: XrefQuery[]): Promise<Map<string, XrefResult[]>>;
+}
+
+interface FieldMapping<T> {
+    fields: (keyof T)[];
+    outputs: OutputArea[];
+}
+declare function getChangedOutputAreas(oldConfig: SpeculatorConfig | undefined, newConfig: SpeculatorConfig): OutputArea[];
+
+export { DOMHtmlRenderer, type DataFormat, type ElementProcessor, type FieldMapping, type FileLoader, FormatProcessor, FormatRegistry, type FormatResult, type FormatStrategy, type HtmlRenderer, IncludeProcessor, type MarkdownOptions, type MermaidConfig, type PostProcessHook, type ProcessingResult, type ProcessingStats, type ProcessorResult, type RenderHtmlResult, type RenderResult, type RespecConfig, RespecXrefResolver, Speculator, type SpeculatorConfig, SpeculatorError, type SpeculatorOptions, StatsTracker, browserFileLoader, createFallbackFileLoader, createMarkdownRenderer, fromRespecConfig, getChangedOutputAreas, getDefaultFileLoader, nodeFileLoader, parseMarkdown };

package/dist/browser.js

@@ -1,25 +1,35 @@
 import {
   DOMHtmlRenderer,
   FormatProcessor,
+  FormatRegistry,
   IncludeProcessor,
+  RespecXrefResolver,
   Speculator,
   SpeculatorError,
+  StatsTracker,
   browserFileLoader,
   createFallbackFileLoader,
   createMarkdownRenderer,
+  fromRespecConfig,
+  getChangedOutputAreas,
   getDefaultFileLoader,
   nodeFileLoader,
   parseMarkdown
-} from "./chunk-JAR5PGCK.js";
+} from "./chunk-V4GSFQE7.js";
 export {
   DOMHtmlRenderer,
   FormatProcessor,
+  FormatRegistry,
   IncludeProcessor,
+  RespecXrefResolver,
   Speculator,
   SpeculatorError,
+  StatsTracker,
   browserFileLoader,
   createFallbackFileLoader,
   createMarkdownRenderer,
+  fromRespecConfig,
+  getChangedOutputAreas,
   getDefaultFileLoader,
   nodeFileLoader,
   parseMarkdown

package/dist/chunk-H7C7MOU6.js

@@ -0,0 +1,28 @@
+import {
+  Speculator
+} from "./chunk-V4GSFQE7.js";
+
+// src/linkedom-html-renderer.ts
+import { DOMParser } from "linkedom";
+var LinkedomHtmlRenderer = class {
+  parse(html) {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(`<div>${html}</div>`, "text/html");
+    return doc.querySelector("div");
+  }
+  serialize(element) {
+    return element.innerHTML;
+  }
+};
+
+// src/node.ts
+var Speculator2 = class extends Speculator {
+  constructor(options = {}) {
+    super({ ...options, htmlRenderer: options.htmlRenderer || new LinkedomHtmlRenderer() });
+  }
+};
+
+export {
+  LinkedomHtmlRenderer,
+  Speculator2 as Speculator
+};