@linxiraos/pi-utils 1.0.0

package/dist/types/marked/core.d.ts

@@ -0,0 +1,445 @@
+/** Token shapes emitted by the Markdown lexer. */
+export declare namespace Tokens {
+    /** A block quote. */
+    interface Blockquote {
+        type: "blockquote";
+        raw: string;
+        text: string;
+        tokens: Token[];
+    }
+    /** A hard line break. */
+    interface Br {
+        type: "br";
+        raw: string;
+    }
+    /** A task-list checkbox. */
+    interface Checkbox {
+        type: "checkbox";
+        raw: string;
+        checked: boolean;
+    }
+    /** A code block. */
+    interface Code {
+        type: "code";
+        raw: string;
+        codeBlockStyle?: "indented";
+        lang?: string;
+        text: string;
+        escaped?: boolean;
+    }
+    /** An inline code span. */
+    interface Codespan {
+        type: "codespan";
+        raw: string;
+        text: string;
+    }
+    /** A reference-link definition. */
+    interface Def {
+        type: "def";
+        raw: string;
+        tag: string;
+        href: string;
+        title?: string;
+    }
+    /** Deleted text. */
+    interface Del {
+        type: "del";
+        raw: string;
+        text: string;
+        tokens: Token[];
+    }
+    /** Emphasized text. */
+    interface Em {
+        type: "em";
+        raw: string;
+        text: string;
+        tokens: Token[];
+    }
+    /** An escaped punctuation character. */
+    interface Escape {
+        type: "escape";
+        raw: string;
+        text: string;
+    }
+    /** A custom extension token. */
+    interface Generic {
+        [key: string]: any;
+        type: string;
+        raw: string;
+        tokens?: Token[];
+    }
+    /** A heading. */
+    interface Heading {
+        type: "heading";
+        raw: string;
+        depth: number;
+        text: string;
+        tokens: Token[];
+    }
+    /** A horizontal rule. */
+    interface Hr {
+        type: "hr";
+        raw: string;
+    }
+    /** Raw block or inline HTML. */
+    interface HTML {
+        type: "html";
+        raw: string;
+        pre?: boolean;
+        text: string;
+        block: boolean;
+        inLink?: boolean;
+        inRawBlock?: boolean;
+    }
+    /** An image. */
+    interface Image {
+        type: "image";
+        raw: string;
+        href: string;
+        title: string | null;
+        text: string;
+        tokens: Token[];
+    }
+    /** A hyperlink. */
+    interface Link {
+        type: "link";
+        raw: string;
+        href: string;
+        title?: string | null;
+        text: string;
+        tokens: Token[];
+    }
+    /** A list. */
+    interface List {
+        type: "list";
+        raw: string;
+        ordered: boolean;
+        start: number | "";
+        loose: boolean;
+        items: ListItem[];
+    }
+    /** A list item. */
+    interface ListItem {
+        type: "list_item";
+        raw: string;
+        task: boolean;
+        checked?: boolean;
+        loose: boolean;
+        text: string;
+        tokens: Token[];
+    }
+    /** A paragraph. */
+    interface Paragraph {
+        type: "paragraph";
+        raw: string;
+        pre?: boolean;
+        text: string;
+        tokens: Token[];
+    }
+    /** Blank block space. */
+    interface Space {
+        type: "space";
+        raw: string;
+    }
+    /** Strongly emphasized text. */
+    interface Strong {
+        type: "strong";
+        raw: string;
+        text: string;
+        tokens: Token[];
+    }
+    /** A GFM table cell. */
+    interface TableCell {
+        text: string;
+        tokens: Token[];
+        header: boolean;
+        align: "center" | "left" | "right" | null;
+    }
+    /** A GFM table. */
+    interface Table {
+        type: "table";
+        raw: string;
+        align: Array<"center" | "left" | "right" | null>;
+        header: TableCell[];
+        rows: TableCell[][];
+    }
+    /** Plain text. */
+    interface Text {
+        type: "text";
+        raw: string;
+        text: string;
+        tokens?: Token[];
+        escaped?: boolean;
+    }
+}
+type KnownToken = Tokens.Blockquote | Tokens.Br | Tokens.Checkbox | Tokens.Code | Tokens.Codespan | Tokens.Def | Tokens.Del | Tokens.Em | Tokens.Escape | Tokens.Heading | Tokens.Hr | Tokens.HTML | Tokens.Image | Tokens.Link | Tokens.List | Tokens.ListItem | Tokens.Paragraph | Tokens.Space | Tokens.Strong | Tokens.Table | Tokens.Text;
+/** A built-in or extension Markdown token. */
+export type Token = KnownToken | Tokens.Generic;
+/** Reference definitions collected while lexing. */
+export type Links = Record<string, Pick<Tokens.Link | Tokens.Image, "href" | "title">>;
+/** A token array carrying its reference-definition map. */
+export type TokensList = Token[] & {
+    links: Links;
+};
+/** Context supplied to extension tokenizers. */
+export interface TokenizerThis {
+    lexer: Lexer;
+}
+/** A tokenizer extension callback. */
+export type TokenizerExtensionFunction = (this: TokenizerThis, src: string, tokens: Token[] | TokensList) => Tokens.Generic | undefined;
+/** A tokenizer extension start hint. */
+export type TokenizerStartFunction = (this: TokenizerThis, src: string) => number | void;
+/** An inline or block tokenizer extension. */
+export interface TokenizerExtension {
+    name: string;
+    level: "block" | "inline";
+    start?: TokenizerStartFunction;
+    tokenizer: TokenizerExtensionFunction;
+    childTokens?: string[];
+}
+/** Context supplied to extension renderers. */
+export interface RendererThis {
+    parser: Parser;
+}
+/** A custom renderer extension callback. */
+export type RendererExtensionFunction = (this: RendererThis, token: Tokens.Generic) => string | false | undefined;
+/** A named renderer extension. */
+export interface RendererExtension {
+    name: string;
+    renderer: RendererExtensionFunction;
+}
+/** A combined tokenizer/renderer extension. */
+export type TokenizerAndRendererExtension = TokenizerExtension | RendererExtension | (TokenizerExtension & RendererExtension);
+/** Overrides for built-in tokenizer methods. */
+export interface TokenizerObject {
+    url?(this: Tokenizer, src: string): Tokens.Link | undefined | false;
+    lheading?(this: Tokenizer, src: string): Tokens.Heading | undefined | false;
+    del?(this: Tokenizer, src: string, maskedSrc?: string, prevChar?: string): Tokens.Del | undefined | false;
+}
+interface RendererTokenMap {
+    space: Tokens.Space;
+    html: Tokens.HTML;
+    link: Tokens.Link;
+    image: Tokens.Image;
+    text: Tokens.Text | Tokens.Escape;
+    code: Tokens.Code;
+    blockquote: Tokens.Blockquote;
+    heading: Tokens.Heading;
+    hr: Tokens.Hr;
+    list: Tokens.List;
+    listitem: Tokens.ListItem;
+    paragraph: Tokens.Paragraph;
+    strong: Tokens.Strong;
+    em: Tokens.Em;
+    codespan: Tokens.Codespan;
+    br: Tokens.Br;
+    del: Tokens.Del;
+}
+/** Overrides for built-in HTML renderer methods. */
+export type RendererObject = {
+    [K in keyof RendererTokenMap]?: (this: Renderer, token: RendererTokenMap[K]) => string | false;
+};
+/** Options supported by the in-house Markdown implementation. */
+export interface MarkedOptions {
+    async?: boolean;
+    breaks?: boolean;
+    gfm?: boolean;
+    pedantic?: boolean;
+    silent?: boolean;
+    tokenizer?: Tokenizer | TokenizerObject | null;
+    /** Built-in tokenizer overrides composed by Marked.use(). */
+    tokenizerOverrides?: TokenizerObject;
+    renderer?: Renderer | RendererObject | null;
+    walkTokens?: ((token: Token) => void | Promise<void>) | null;
+    extensions?: ExtensionRegistry | null;
+}
+interface ExtensionRegistry {
+    block: TokenizerExtension[];
+    inline: TokenizerExtension[];
+    renderers: Record<string, RendererExtensionFunction>;
+    childTokens: Record<string, string[]>;
+}
+/** Options accepted by Marked.use(). */
+export interface MarkedExtension extends Omit<MarkedOptions, "extensions"> {
+    extensions?: TokenizerAndRendererExtension[] | null;
+}
+/** Tokenizes the built-in inline Markdown surface. */
+export declare class Tokenizer {
+    options: MarkedOptions;
+    lexer: Lexer;
+    /** Creates a tokenizer with the supplied options. */
+    constructor(options?: MarkedOptions);
+    /** Tokenizes GFM deletion. */
+    del(src: string): Tokens.Del | undefined;
+}
+/** Stateful block and inline Markdown lexer. */
+export declare class Lexer {
+    tokens: TokensList;
+    options: MarkedOptions;
+    state: {
+        inLink: boolean;
+        inRawBlock: boolean;
+        top: boolean;
+    };
+    inlineQueue: Array<{
+        src: string;
+        tokens: Token[];
+    }>;
+    tokenizer: Tokenizer;
+    tokenizerOverrides: TokenizerObject;
+    extensions: ExtensionRegistry;
+    /** Creates a lexer. */
+    constructor(options?: MarkedOptions);
+    /** Exposes rule objects for callers that optimize regular expressions. */
+    static get rules(): {
+        block: {
+            normal: {
+                blockquote: RegExp;
+                code: RegExp;
+                def: RegExp;
+                fences: RegExp;
+                heading: RegExp;
+                hr: RegExp;
+                html: RegExp;
+                lheading: RegExp;
+                list: RegExp;
+                newline: RegExp;
+                paragraph: RegExp;
+                table: RegExp;
+                text: RegExp;
+            };
+            gfm: Record<string, RegExp>;
+            pedantic: Record<string, RegExp>;
+        };
+        inline: {
+            normal: {
+                _backpedal: RegExp;
+                anyPunctuation: RegExp;
+                autolink: RegExp;
+                blockSkip: RegExp;
+                br: RegExp;
+                code: RegExp;
+                del: RegExp;
+                delLDelim: RegExp;
+                delRDelim: RegExp;
+                emStrongLDelim: RegExp;
+                emStrongRDelimAst: RegExp;
+                emStrongRDelimUnd: RegExp;
+                escape: RegExp;
+                link: RegExp;
+                nolink: RegExp;
+                punctuation: RegExp;
+                reflink: RegExp;
+                reflinkSearch: RegExp;
+                tag: RegExp;
+                text: RegExp;
+                url: RegExp;
+            };
+            gfm: Record<string, RegExp>;
+            breaks: Record<string, RegExp>;
+            pedantic: Record<string, RegExp>;
+        };
+    };
+    /** Lexes a complete document. */
+    static lex(src: string, options?: MarkedOptions): TokensList;
+    /** Lexes inline Markdown. */
+    static lexInline(src: string, options?: MarkedOptions): Token[];
+    /** Lexes and resolves a complete document. */
+    lex(src: string): TokensList;
+    /** Appends block tokens to an output array. */
+    blockTokens(src: string, tokens?: Token[] | TokensList): Token[] | TokensList;
+    /** Queues inline tokenization compatibly with marked. */
+    inline(src: string, tokens?: Token[]): Token[];
+    /** Tokenizes inline Markdown immediately. */
+    inlineTokens(src: string, tokens?: Token[]): Token[];
+}
+/** Default HTML renderer. */
+export declare class Renderer {
+    options: MarkedOptions;
+    parser: Parser;
+    overrides: RendererObject;
+    /** Creates an HTML renderer. */
+    constructor(options?: MarkedOptions, overrides?: RendererObject);
+    /** Renders blank space. */ space(_token: Tokens.Space): string;
+    /** Renders a code block. */ code({ text, lang, escaped }: Tokens.Code): string;
+    /** Renders a block quote. */ blockquote({ tokens }: Tokens.Blockquote): string;
+    /** Passes raw HTML through. */ html({ text }: Tokens.HTML): string;
+    /** Renders a definition as no output. */ def(_token: Tokens.Def): string;
+    /** Renders a heading. */ heading({ tokens, depth }: Tokens.Heading): string;
+    /** Renders a horizontal rule. */ hr(_token: Tokens.Hr): string;
+    /** Renders a list. */ list(token: Tokens.List): string;
+    /** Renders a list item. */ listitem(item: Tokens.ListItem): string;
+    /** Renders a checkbox. */ checkbox({ checked }: Tokens.Checkbox): string;
+    /** Renders a paragraph. */ paragraph({ tokens }: Tokens.Paragraph): string;
+    /** Renders a table. */ table(token: Tokens.Table): string;
+    /** Renders a table row. */ tablerow(text: string): string;
+    /** Renders a table cell. */ tablecell(token: Tokens.TableCell): string;
+    /** Renders strong text. */ strong({ tokens }: Tokens.Strong): string;
+    /** Renders emphasized text. */ em({ tokens }: Tokens.Em): string;
+    /** Renders inline code. */ codespan({ text }: Tokens.Codespan): string;
+    /** Renders a line break. */ br(_token: Tokens.Br): string;
+    /** Renders deleted text. */ del({ tokens }: Tokens.Del): string;
+    /** Renders a link. */ link({ href, title, tokens }: Tokens.Link): string;
+    /** Renders an image. */ image({ href, title, text }: Tokens.Image): string;
+    /** Renders plain text. */ text({ text }: Tokens.Text | Tokens.Escape): string;
+}
+/** Converts token streams into HTML. */
+export declare class Parser {
+    options: MarkedOptions;
+    renderer: Renderer;
+    extensions: ExtensionRegistry;
+    /** Creates a parser. */
+    constructor(options?: MarkedOptions);
+    /** Parses block tokens. */ static parse(tokens: Token[], options?: MarkedOptions): string;
+    /** Parses inline tokens. */ static parseInline(tokens: Token[], options?: MarkedOptions): string;
+    /** Parses block tokens with the configured renderer. */
+    parse(tokens: Token[]): string;
+    /** Parses inline tokens with the configured renderer. */
+    parseInline(tokens: Token[]): string;
+    /** Renders a list item, including custom renderer overrides. */
+    renderListItem(item: Tokens.ListItem): string;
+    call<K extends keyof RendererTokenMap>(name: K, token: RendererTokenMap[K], fallback: () => string): string;
+}
+/** Configurable Markdown lexer and HTML parser. */
+export declare class Marked {
+    defaults: MarkedOptions;
+    /** Creates an isolated Marked instance. */
+    constructor(...extensions: MarkedExtension[]);
+    /** Merges default options. */ options(options: MarkedOptions): this;
+    /** Merges default options. */ setOptions(options: MarkedOptions): this;
+    /** Adds tokenizer, renderer, and walk-token extensions. */
+    use(...extensions: MarkedExtension[]): this;
+    /** Lexes Markdown into tokens. */ lexer(src: string, options?: MarkedOptions): TokensList;
+    /** Parses a token stream to HTML. */ parser(tokens: Token[], options?: MarkedOptions): string;
+    /** Walks a token tree depth first. */ walkTokens(tokens: Token[] | TokensList, callback: (token: Token) => void | Promise<void>): Array<void | Promise<void>>;
+    /** Parses Markdown to HTML, synchronously unless async mode is requested. */
+    parse(src: string, options: MarkedOptions & {
+        async: true;
+    }): Promise<string>;
+    parse(src: string, options: MarkedOptions & {
+        async: false;
+    }): string;
+    parse(src: string, options?: MarkedOptions | null): string | Promise<string>;
+    /** Parses inline Markdown to HTML. */ parseInline(src: string, options?: MarkedOptions): string;
+}
+/** Parses Markdown with a shared default instance. */
+export declare function marked(src: string, options: MarkedOptions & {
+    async: true;
+}): Promise<string>;
+export declare function marked(src: string, options: MarkedOptions & {
+    async: false;
+}): string;
+export declare function marked(src: string, options?: MarkedOptions | null): string | Promise<string>;
+/** Parses Markdown with a shared default instance. */
+export declare const parse: typeof marked;
+/** Lexes Markdown with default options. */
+export declare const lexer: typeof Lexer.lex;
+/** Parses inline Markdown with default options. */
+export declare const parseInline: (src: string, options?: MarkedOptions) => string;
+/** Parses a token stream with default options. */
+export declare const parser: typeof Parser.parse;
+/** The default option object. */
+export declare const defaults: MarkedOptions;
+/** Returns a fresh copy of the default options. */
+export declare function getDefaults(): MarkedOptions;
+export {};

package/dist/types/marked.d.ts

@@ -0,0 +1,2 @@
+/** Behavior-compatible reimplementation of marked's used surface. */
+export * from "./marked/core.js";

package/dist/types/mermaid-ascii.d.ts

@@ -0,0 +1,11 @@
+import { type AsciiRenderOptions } from "./vendor/mermaid-ascii/index.js";
+export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+export declare function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string;
+export declare function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null;
+/**
+ * Extract mermaid code blocks from markdown text.
+ */
+export declare function extractMermaidBlocks(markdown: string): {
+    source: string;
+    hash: bigint | number;
+}[];

package/dist/types/mime.d.ts

@@ -0,0 +1,29 @@
+export declare const SUPPORTED_IMAGE_MIME_TYPES: Set<string>;
+export type ImageMetadata = {
+    mimeType: "image/png";
+    width?: number;
+    height?: number;
+    channels?: number;
+    hasAlpha?: boolean;
+} | {
+    mimeType: "image/jpeg";
+    width?: number;
+    height?: number;
+    channels?: number;
+    hasAlpha?: false;
+} | {
+    mimeType: "image/gif";
+    width?: number;
+    height?: number;
+    channels?: 3;
+    hasAlpha?: never;
+} | {
+    mimeType: "image/webp";
+    width?: number;
+    height?: number;
+    channels?: number;
+    hasAlpha?: boolean;
+};
+export declare function parseImageMetadata(header: Uint8Array): ImageMetadata | null;
+export declare function readImageMetadataSync(filePath: string, maxBytes?: number): ImageMetadata | null;
+export declare function readImageMetadata(filePath: string, maxBytes?: number): Promise<ImageMetadata | null>;

package/dist/types/module-timer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/path-tree.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Multi-level path tree shared by grouped file listings (find / grep / ast tools)
+ * and compaction file-operation lists.
+ *
+ * Flat path lists used to group by the *immediate* parent directory and print the
+ * full directory path in every header. For results spread across a deep tree — or
+ * rooted outside cwd, where paths stay absolute — that repeated the shared prefix
+ * on every line. The tree below folds single-child directory chains (so the common
+ * prefix collapses into one header) and nests the rest, charging the model one
+ * token per path segment instead of one per file.
+ */
+/** True for `scheme://…` entries that have no meaningful directory structure. */
+export declare function isUrlLikePath(filePath: string): boolean;
+export interface PathTreeNode {
+    /** Direct file leaves, in first-seen order. */
+    files: Array<{
+        name: string;
+        key: string;
+    }>;
+    /** Dedup set for `files` (a glob can surface the same path twice on retry). */
+    fileNames: Set<string>;
+    /** Child directories, in first-seen order. */
+    subdirs: Array<{
+        name: string;
+        node: PathTreeNode;
+    }>;
+    /** Dedup index for `subdirs`. */
+    dirIndex: Map<string, PathTreeNode>;
+}
+export interface PathTreeInput {
+    /** Path string; absolute, cwd-relative, or url-like. Backslashes are normalized. */
+    path: string;
+    /** Whether the leaf itself is a directory (trailing-slash match from find). */
+    isDir: boolean;
+    /** Opaque key carried onto file events for section lookup. Defaults to `path`. */
+    key?: string;
+}
+/** One node emitted while walking the tree: a folded directory or a file leaf. */
+export interface GroupedTreeEvent {
+    kind: "dir" | "file";
+    /** 0-based nesting depth (root children are depth 0). */
+    depth: number;
+    /** Folded chain for dirs (e.g. `a/b/c`, no trailing slash); basename for files. */
+    name: string;
+    /** File key for `kind === "file"`; empty string for directories. */
+    key: string;
+}
+/**
+ * Build a directory tree from a flat list of paths. URL-like entries are kept
+ * whole as root-level file leaves (they have no meaningful directory structure).
+ * Absolute paths carry a leading empty segment so they share a common `/` root
+ * and fold like any other prefix.
+ */
+export declare function buildPathTree(entries: Iterable<PathTreeInput>): PathTreeNode;
+/**
+ * Depth-first walk yielding directory and file events. Directories collapse their
+ * single-child chains (`a` → `a/b` → `a/b/c`) so a shared prefix becomes one
+ * header. Each node's direct files are emitted before its subdirectories, keeping
+ * a file unambiguously attached to the header above it.
+ */
+export declare function walkPathTree(node: PathTreeNode, depth?: number): Generator<GroupedTreeEvent>;
+/**
+ * Render a flat path list as a grouped, prefix-folded directory tree without
+ * per-file bodies (find-tool output shape, also used by compaction `<files>`
+ * lists). Single-child directory chains fold into one header (`# a/b/c/`),
+ * each level adds one `#`, and files are listed bare under the deepest
+ * directory header that owns them. Trailing-slash entries are directory
+ * leaves and keep their slash in the header.
+ *
+ * `annotate` receives each file's full original path and its return value is
+ * appended verbatim to the file line (e.g. ` (RW)`).
+ *
+ * Order follows the input: a directory appears when its first member is
+ * emitted, and a node's own files precede its subdirectories.
+ */
+export declare function formatGroupedPaths(paths: readonly string[], annotate?: (path: string) => string): string;

package/dist/types/path.d.ts

@@ -0,0 +1,2 @@
+/** Removes Win32 extended-length prefixes before passing paths to Bun APIs. */
+export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, platform?: NodeJS.Platform): string;

package/dist/types/peek-file.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Synchronously reads up to `maxBytes` from the start of `filePath` and returns `op(header)`.
+ * If the file is shorter, `header` is only the bytes actually read.
+ */
+export declare function peekFileSync<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): T;
+/**
+ * Like {@link peekFileSync} but uses async I/O.
+ */
+export declare function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T>;
+/**
+ * Read up to the last `maxBytes` of `filePath` and pass that slice to `op`.
+ *
+ * The tail mirror of {@link peekFile}: same pooled-buffer strategy (no per-call
+ * allocation for small reads), but the read is positioned at `size - len` so the
+ * window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
+ * returned. A multi-byte codepoint straddling the leading cut decodes to a
+ * replacement char — callers that parse line-oriented tails drop the partial
+ * leading line anyway.
+ */
+export declare function peekFileTail<T>(filePath: string, maxBytes: number, op: (tail: Uint8Array) => T): Promise<T>;
+/**
+ * Read up to the first `prefixBytes` and last `suffixBytes` of `filePath`, then
+ * pass both slices to `op`.
+ *
+ * Uses a single open/stat sequence. When the whole file fits in the head window,
+ * the tail is sliced from the already-read head bytes instead of issuing a
+ * second read.
+ */
+export declare function peekFileEnds<T>(filePath: string, prefixBytes: number, suffixBytes: number, op: (head: Uint8Array, tail: Uint8Array) => T): Promise<T>;