peisar 0.0.1 → 0.1.2

package/index.d.ts

@@ -0,0 +1,499 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+/**
+ * Parses one Markdown document and exposes its AST, HTML, and front matter
+ * to JavaScript.
+ *
+ * Construct this class with the Markdown source and an optional
+ * [`PeisarOptions`] object. Properties are computed from the source document;
+ * accessing `ast`, `html`, or `astJson` also applies registered visitors.
+ */
+export declare class Peisar {
+  /**
+   * Creates a parser for `rawMd`.
+   *
+   * When `options` is omitted, GFM and Kramdown parsing are enabled and
+   * `html` returns a complete HTML document.
+   */
+  constructor(rawMd: string, options?: PeisarOptions | undefined | null)
+  /**
+   * Gets the parsed Markdown document as a JavaScript AST object.
+   *
+   * Registered visitors run before the AST is returned. The returned value
+   * is a clone, so reading this property does not consume the parser state.
+   */
+  get ast(): Document
+  /**
+   * Registers a JavaScript AST visitor.
+   *
+   * The visitor can provide `visitBlock` and/or `visitInline` callbacks.
+   * Each callback receives a one-item node tuple and may return a control object that
+   * changes the node or determines whether its children are visited.
+   */
+  useVisitor(visitor: Visitor): void
+  /**
+   * Renders the parsed Markdown as HTML using the configured render options.
+   *
+   * Registered visitors run before rendering.
+   */
+  get html(): string
+  /** Gets the deserialized YAML front matter, or `null` when none exists. */
+  get frontmatter(): any | null
+  /**
+   * Gets the parsed Markdown AST serialized as JSON.
+   *
+   * Registered visitors run before serialization.
+   */
+  get astJson(): string
+}
+
+/**
+ * Options that control how Markdown is parsed.
+ *
+ * # Defaults
+ *
+ * Both GFM and Kramdown extensions are enabled by default.  To parse
+ * strict CommonMark only:
+ *
+ * ```ignore
+ * use peisar_ast::AstOptions;
+ *
+ * let opts = AstOptions {
+ *     gfm: false,
+ *     kramdown: false,
+ *     file_name: None,
+ * };
+ * ```
+ */
+export interface AstOptions {
+  /**
+   * Enable GitHub Flavored Markdown (tables, strikethrough, task lists,
+   * autolinks).  Default: `true`.
+   */
+  gfm: boolean
+  /**
+   * Enable Kramdown-style block attributes (`{:#id .class key="val"}`).
+   * Default: `true`.
+   */
+  kramdown: boolean
+  /** Optional file name to attach to the parsed [`Document`](crate::Document). */
+  fileName?: string
+}
+
+/**
+ * Parsed Kramdown block attributes (`{:#id .class key="val"}`).
+ *
+ * # Example
+ *
+ * ```ignore
+ * use peisar_ast::tokens::Attributes;
+ *
+ * let attrs = Attributes {
+ *     id: Some("intro".into()),
+ *     classes: Some(vec!["banner".into(), "wide".into()]),
+ *     attributes: Some(vec![("data-index".into(), "42".into())]),
+ * };
+ * assert_eq!(
+ *     attrs.to_html_attr_string(),
+ *     "id=\"intro\" class=\"banner wide\" data-index=\"42\""
+ * );
+ * ```
+ */
+export interface Attributes {
+  /** HTML `id` attribute. */
+  id?: string
+  /** CSS class list. */
+  classes?: Array<string>
+  /** Arbitrary key/value attributes. */
+  attributes?: Array<[string, string]>
+}
+
+/** Block-level nodes. */
+export type Block =
+  | { type: 'Heading'; /** Heading level (1–6). */
+    level: number; /** Inline content of the heading. */
+    children: Array<Inline>; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'Paragraph'; /** Inline content of the paragraph. */
+    children: Array<Inline>; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'CodeBlock'; /** Language hint from the info string (e.g. `rust` from ` ```rust `). */
+    lang?: string; /** The raw code content. */
+    code: string; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'BlockQuote'; /** Nested block content inside the quote. */
+    children: Array<Block>; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'List'; /** `true` for ordered lists, `false` for unordered. */
+    ordered: boolean; /** The list items. */
+    items: Array<ListItem>; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'ThematicBreak'; /** Source span. */
+  pos: Span }
+  | { type: 'HtmlBlock'; /** The raw HTML content. */
+    html: string; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'Table'; /** The table structure (header, rows, alignments). */
+    table: Table; /** Source span. */
+    pos: Span; /** Optional Kramdown attributes. */
+  attrs?: Attributes }
+  | { type: 'LinkReferenceDefinition'; /** Normalised label (lowercased, trimmed). */
+    label: string; /** The destination URL. */
+    url: string; /** Optional link title. */
+    title?: string; /** Source span. */
+  pos: Span }
+  | { type: 'Comment'; /** The comment text (markers stripped). */
+    value: string; /** Source span. */
+  pos: Span }
+
+/**
+ * Synchronous block-visitor callback. Receives a `Block`, returns
+ * `VisitControlJs`.
+ */
+export type BlockCallback = (arg: [Block]) => VisitControlJs
+
+/**
+ * A Markdown document — the root of the AST.
+ *
+ * Contains the top-level block children and all link reference definitions
+ * collected from the source text.
+ *
+ * # Example
+ *
+ * ```ignore
+ * use peisar_ast::Document;
+ * use peisar_ast::AstOptions;
+ *
+ * let doc = Document::parse("# Hello
+", &AstOptions::default(), None);
+ * assert_eq!(doc.node_type, "root");
+ * assert_eq!(doc.children.len(), 1);
+ * ```
+ */
+export interface Document {
+  /** Always `"root"`. */
+  nodeType: string
+  /** Optional source file name. */
+  fileName?: string
+  /** Span of the whole document in the source text. */
+  pos: Span
+  /** Top-level block children. */
+  children: Array<Block>
+  /** All link reference definitions collected from the document. */
+  linkReferences: Array<LinkReferenceDefinition>
+}
+
+/** Emphasis strength. */
+export declare const enum EmphasisLevel {
+  /** `*italic*` / `_italic_` */
+  Italic = 0,
+  /** `**bold**` / `__bold__` */
+  Bold = 1,
+}
+
+/** Inline-level nodes. */
+export type Inline =
+  | { type: 'Text'; /** The text value. */
+    value: string; /** Source span. */
+  pos: Span }
+  | { type: 'Emphasis'; /** Emphasis level (italic or bold). */
+    level: EmphasisLevel; /** Nested inline content. */
+    children: Array<Inline>; /** Source span. */
+  pos: Span }
+  | { type: 'Code'; /** The code text. */
+    code: string; /** Source span. */
+  pos: Span }
+  | { type: 'HtmlInline'; /** The raw HTML string. */
+    html: string; /** Source span. */
+  pos: Span }
+  | { type: 'Strikethrough'; /** Nested inline content. */
+    children: Array<Inline>; /** Source span. */
+  pos: Span }
+  | { type: 'HardBreak'; /** Source span. */
+  pos: Span }
+  | { type: 'SoftBreak'; /** Source span. */
+  pos: Span }
+  | { type: 'Image'; /** Alternative text. */
+    alt: string; /** Image URL. */
+    url: string; /** Optional title. */
+    title?: string; /** Source span. */
+  pos: Span }
+  | { type: 'Link'; /** Link text (inline children). */
+    text: Array<Inline>; /** Destination URL. */
+    url: string; /** Optional link title. */
+    title?: string; /** `true` if this is a GFM autolink (bare URL). */
+    autolink: boolean; /** Source span. */
+  pos: Span }
+  | { type: 'LinkReference'; /** Link text (inline children). */
+    text: Array<Inline>; /** Normalised label used to look up the reference. */
+    label: string; /** Resolved destination URL. */
+    url: string; /** Optional resolved title. */
+    title?: string; /** Source span. */
+  pos: Span }
+
+/**
+ * Synchronous inline-visitor callback. Receives an `Inline`, returns
+ * `InlineVisitControlJs`.
+ */
+export type InlineCallback = (arg: [Inline]) => InlineVisitControlJs
+
+/**
+ * JS-facing mirror of [`InlineVisitControl`].
+ *
+ * Returned from the JS `visitInline` callback.  All fields are optional;
+ * omitting a field means "no change" for that operation.
+ */
+export interface InlineVisitControlJs {
+  /** Nodes to insert before the current node. */
+  insertBefore?: Array<Inline>
+  /** Nodes to insert after the current node. */
+  insertAfter?: Array<Inline>
+  /** Replace the current node with these nodes. */
+  replaceWith?: Array<Inline>
+  /** Remove the current node entirely. */
+  remove?: boolean
+  /** Whether to recurse into this node's children. */
+  recurse?: boolean
+}
+
+/** A link reference definition collected at the document level. */
+export interface LinkReferenceDefinition {
+  /** Normalised label (lowercased, trimmed). */
+  label: string
+  /** The destination URL. */
+  url: string
+  /** Optional link title. */
+  title?: string
+  /** Source span. */
+  pos: Span
+}
+
+/** A single list item (an `<li>`). Contains nested block content. */
+export interface ListItem {
+  /** Nested block content of the item. */
+  children: Array<Block>
+  /** GFM task-list state: `None` = not a task, `Some` = checked / unchecked. */
+  task?: TaskState
+  /** Span of the item in the *sub-document* of its enclosing list. */
+  pos: Span
+}
+
+/** The Markdown body and YAML metadata parsed from a front-matter document. */
+export interface ParseResult {
+  /** Markdown source after the leading YAML front matter is removed. */
+  pureMarkdownContent: string
+  /** Deserialized YAML front matter, or `null` when no front matter exists. */
+  yamlData?: Record<string, any>
+}
+
+/**
+ * JavaScript options for Markdown parsing and HTML rendering.
+ *
+ * Every property is optional. Omitted parsing options enable GFM and
+ * Kramdown; omitted rendering options produce a complete HTML document with
+ * charset and viewport metadata.
+ */
+export interface PeisarOptions {
+  /**
+   * Enable GitHub Flavored Markdown (tables, strikethrough, task lists,
+   * autolinks).  Default: `true`.
+   */
+  gfm?: boolean
+  /**
+   * Enable Kramdown-style block attributes (`{:#id .class key="val"}`).
+   * Default: `true`.
+   */
+  kramdown?: boolean
+  /** Optional file name to attach to the parsed [`Document`](crate::Document). */
+  fileName?: string
+  /**
+   * If `true`, emit only the body content (no `<!DOCTYPE>`, `<html>`,
+   * `<head>`, or `<body>` wrapper).  If `false`, emit a full HTML
+   * document.  Default: `true` (fragment).
+   */
+  fragment?: boolean
+  /**
+   * Include a `<meta charset="utf-8">` in the head (only relevant when
+   * `fragment` is `false`).  Default: `true`.
+   */
+  charset?: boolean
+  /**
+   * Include a `<meta name="viewport" content="width=device-width,
+   * initial-scale=1.0">` in the head (only relevant when `fragment` is
+   * `false`).  Default: `true`.
+   */
+  viewport?: boolean
+  /**
+   * Optional `<title>` for the HTML head (only relevant when
+   * `fragment` is `false`).  Default: `None`.
+   */
+  title?: string
+  /**
+   * Optional additional CSS classes to add to `<body>` (only relevant
+   * when `fragment` is `false`).  Default: `None`.
+   */
+  bodyClass?: string
+  /**
+   * Optional inline CSS to inject in a `<style>` tag in the head.
+   * Default: `None`.
+   */
+  style?: string
+}
+
+/** A zero-based point in the source text. */
+export interface Position {
+  /** Line number, 0-based. */
+  line: number
+  /** Column number, 0-based (in characters). */
+  column: number
+  /** Byte offset from the start of the input. */
+  offset: number
+}
+
+/** Options that control how the AST is rendered to HTML. */
+export interface RenderOptions {
+  /**
+   * If `true`, emit only the body content (no `<!DOCTYPE>`, `<html>`,
+   * `<head>`, or `<body>` wrapper).  If `false`, emit a full HTML
+   * document.  Default: `true` (fragment).
+   */
+  fragment: boolean
+  /**
+   * Include a `<meta charset="utf-8">` in the head (only relevant when
+   * `fragment` is `false`).  Default: `true`.
+   */
+  charset: boolean
+  /**
+   * Include a `<meta name="viewport" content="width=device-width,
+   * initial-scale=1.0">` in the head (only relevant when `fragment` is
+   * `false`).  Default: `true`.
+   */
+  viewport: boolean
+  /**
+   * Optional `<title>` for the HTML head (only relevant when
+   * `fragment` is `false`).  Default: `None`.
+   */
+  title?: string
+  /**
+   * Optional additional CSS classes to add to `<body>` (only relevant
+   * when `fragment` is `false`).  Default: `None`.
+   */
+  bodyClass?: string
+  /**
+   * Optional inline CSS to inject in a `<style>` tag in the head.
+   * Default: `None`.
+   */
+  style?: string
+}
+
+/**
+ * A half-open span `[start, end)` covering a node's source text.
+ *
+ * `start` is inclusive and `end` is exclusive; both positions point into the
+ * original source string.
+ */
+export interface Span {
+  /** The start position (inclusive). */
+  start: Position
+  /** The end position (exclusive). */
+  end: Position
+}
+
+/** A GFM table. */
+export interface Table {
+  /** The header row. */
+  header: TableRow
+  /** Body rows. */
+  rows: Array<TableRow>
+  /** Column alignment specifications (one per column). */
+  alignments: Array<TableCellAlignment>
+}
+
+/** A single table cell. */
+export interface TableCell {
+  /** Inline content of the cell. */
+  children: Array<Inline>
+}
+
+/** Column alignment for table cells. */
+export declare const enum TableCellAlignment {
+  /** `:---` or `---` — default (left) */
+  Default = 0,
+  /** `:---` */
+  Left = 1,
+  /** `:---:` */
+  Center = 2,
+  /** `---:` */
+  Right = 3,
+}
+
+/** A single table row (header or body). */
+export interface TableRow {
+  /** The cells in this row. */
+  cells: Array<TableCell>
+}
+
+/** GFM task-list checkbox state. */
+export declare const enum TaskState {
+  /** `[ ]` — unchecked */
+  Unchecked = 0,
+  /** `[x]` / `[X]` — checked */
+  Checked = 1,
+}
+
+/**
+ * JS-facing mirror of [`VisitControl`].
+ *
+ * Returned from the JS `visitBlock` callback.  All fields are optional;
+ * omitting a field means "no change" for that operation.
+ */
+export interface VisitControlJs {
+  /** Nodes to insert before the current node. */
+  insertBefore?: Array<Block>
+  /** Nodes to insert after the current node. */
+  insertAfter?: Array<Block>
+  /** Replace the current node with these nodes. */
+  replaceWith?: Array<Block>
+  /** Remove the current node entirely. */
+  remove?: boolean
+  /** Whether to recurse into this node's children. */
+  recurse?: boolean
+}
+
+/**
+ * JavaScript object shape for a visitor callback pair.
+ *
+ * On the JS side it is a plain object with two optional
+ * function properties:
+ *
+ * ```js
+ * const myPlugin = {
+ *   visitBlock(block)  { return { recurse: true }; },
+ *   visitInline(inline) { return {}; },
+ * };
+ * ast.addVisitor(myPlugin);
+ * ```
+ *
+ * Either property may be omitted / `null` to skip that node kind.
+ */
+export interface Visitor {
+  /** Optional JS callback for block nodes (JS: `visitBlock`). */
+  visitBlock?: BlockCallback
+  /** Optional JS callback for inline nodes (JS: `visitInline`). */
+  visitInline?: InlineCallback
+}