@wdprlib/ast 1.1.1 → 1.2.0

package/dist/index.d.cts

@@ -1042,6 +1042,86 @@ declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
 */
 declare function isParagraphSafe(element: Element): boolean;
 /**
+* Severity level of a diagnostic.
+*
+* - `"error"` — the markup is structurally broken (e.g. inline `[[div]]`
+*   without a newline after `]]`).
+* - `"warning"` — the markup is likely unintentional but the parser can
+*   recover (e.g. a missing `[[/div]]` close tag).
+* - `"info"` — informational hints (e.g. deprecated syntax).
+*
+* @since 2.0.0
+* @group Diagnostics
+*/
+type DiagnosticSeverity = "error" | "warning" | "info";
+/**
+* A single diagnostic emitted during parsing.
+*
+* Each diagnostic pinpoints a source location via {@link Position} and
+* carries a machine-readable {@link Diagnostic.code | code} string for
+* programmatic filtering (e.g. `"unclosed-block"`, `"inline-block-element"`).
+*
+* @example
+* ```ts
+* import { parse } from "@wdprlib/parser";
+*
+* const { ast, diagnostics } = parse("[[div]]\nHello");
+* for (const d of diagnostics) {
+*   console.log(`[${d.severity}] ${d.message} (line ${d.position.start.line})`);
+* }
+* ```
+*
+* @since 2.0.0
+* @group Diagnostics
+*/
+interface Diagnostic {
+	/** How severe the issue is. */
+	severity: DiagnosticSeverity;
+	/**
+	* Machine-readable identifier for the diagnostic kind.
+	*
+	* Current codes:
+	* - `"unclosed-block"` — a block element has no matching close tag.
+	* - `"inline-block-element"` — a block element (e.g. `[[div]]`) is used
+	*   inline without the required trailing newline.
+	*/
+	code: string;
+	/** Human-readable description of the issue. */
+	message: string;
+	/** Source range where the issue was detected. */
+	position: Position;
+	/**
+	* An optional related source range that provides additional context
+	* (e.g. the opening tag position when reporting a missing close tag).
+	*/
+	relatedPosition?: Position;
+}
+/**
+* The result of parsing a Wikidot markup string.
+*
+* Contains both the parsed AST and any diagnostics emitted during parsing.
+* The AST is always produced, even when diagnostics are present — the parser
+* is lenient and recovers from errors.
+*
+* @example
+* ```ts
+* import { parse } from "@wdprlib/parser";
+*
+* const result = parse("**bold** and //italic//");
+* console.log(result.ast.elements); // AST nodes
+* console.log(result.diagnostics);  // [] (no issues)
+* ```
+*
+* @since 2.0.0
+* @group Diagnostics
+*/
+interface ParseResult {
+	/** The parsed syntax tree. */
+	ast: SyntaxTree;
+	/** Diagnostics emitted during parsing (empty when the input is clean). */
+	diagnostics: Diagnostic[];
+}
+/**
 * Sentinel prefix for style slot placeholders in {@link SyntaxTree.styles}.
 *
 * When the resolver encounters an unresolved `[[iftags]]` block containing
@@ -1160,4 +1240,4 @@ declare const DEFAULT_SETTINGS: WikitextSettings;
 * @group Core
 */
 type Version = "wikidot";
-export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, createSettings, createPosition, createPoint, container, bold, WikitextSettings, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, Position, Point, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, FootnoteBlockData, FloatAlignment, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
+export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, createSettings, createPosition, createPoint, container, bold, WikitextSettings, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, Position, Point, ParseResult, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, FootnoteBlockData, FloatAlignment, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DiagnosticSeverity, Diagnostic, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };

package/dist/index.d.ts

@@ -1042,6 +1042,86 @@ declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
 */
 declare function isParagraphSafe(element: Element): boolean;
 /**
+* Severity level of a diagnostic.
+*
+* - `"error"` — the markup is structurally broken (e.g. inline `[[div]]`
+*   without a newline after `]]`).
+* - `"warning"` — the markup is likely unintentional but the parser can
+*   recover (e.g. a missing `[[/div]]` close tag).
+* - `"info"` — informational hints (e.g. deprecated syntax).
+*
+* @since 2.0.0
+* @group Diagnostics
+*/
+type DiagnosticSeverity = "error" | "warning" | "info";
+/**
+* A single diagnostic emitted during parsing.
+*
+* Each diagnostic pinpoints a source location via {@link Position} and
+* carries a machine-readable {@link Diagnostic.code | code} string for
+* programmatic filtering (e.g. `"unclosed-block"`, `"inline-block-element"`).
+*
+* @example
+* ```ts
+* import { parse } from "@wdprlib/parser";
+*
+* const { ast, diagnostics } = parse("[[div]]\nHello");
+* for (const d of diagnostics) {
+*   console.log(`[${d.severity}] ${d.message} (line ${d.position.start.line})`);
+* }
+* ```
+*
+* @since 2.0.0
+* @group Diagnostics
+*/
+interface Diagnostic {
+	/** How severe the issue is. */
+	severity: DiagnosticSeverity;
+	/**
+	* Machine-readable identifier for the diagnostic kind.
+	*
+	* Current codes:
+	* - `"unclosed-block"` — a block element has no matching close tag.
+	* - `"inline-block-element"` — a block element (e.g. `[[div]]`) is used
+	*   inline without the required trailing newline.
+	*/
+	code: string;
+	/** Human-readable description of the issue. */
+	message: string;
+	/** Source range where the issue was detected. */
+	position: Position;
+	/**
+	* An optional related source range that provides additional context
+	* (e.g. the opening tag position when reporting a missing close tag).
+	*/
+	relatedPosition?: Position;
+}
+/**
+* The result of parsing a Wikidot markup string.
+*
+* Contains both the parsed AST and any diagnostics emitted during parsing.
+* The AST is always produced, even when diagnostics are present — the parser
+* is lenient and recovers from errors.
+*
+* @example
+* ```ts
+* import { parse } from "@wdprlib/parser";
+*
+* const result = parse("**bold** and //italic//");
+* console.log(result.ast.elements); // AST nodes
+* console.log(result.diagnostics);  // [] (no issues)
+* ```
+*
+* @since 2.0.0
+* @group Diagnostics
+*/
+interface ParseResult {
+	/** The parsed syntax tree. */
+	ast: SyntaxTree;
+	/** Diagnostics emitted during parsing (empty when the input is clean). */
+	diagnostics: Diagnostic[];
+}
+/**
 * Sentinel prefix for style slot placeholders in {@link SyntaxTree.styles}.
 *
 * When the resolver encounters an unresolved `[[iftags]]` block containing
@@ -1160,4 +1240,4 @@ declare const DEFAULT_SETTINGS: WikitextSettings;
 * @group Core
 */
 type Version = "wikidot";
-export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, createSettings, createPosition, createPoint, container, bold, WikitextSettings, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, Position, Point, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, FootnoteBlockData, FloatAlignment, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
+export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, createSettings, createPosition, createPoint, container, bold, WikitextSettings, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, Position, Point, ParseResult, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, FootnoteBlockData, FloatAlignment, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DiagnosticSeverity, Diagnostic, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdprlib/ast",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "AST types for Wikidot markup",
   "keywords": [
     "ast",