explorbot 0.4.9 → 0.5.0

package/dist/src/utils/mdq/cli.js

@@ -0,0 +1,122 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { MdqError, mdq } from "./query.js";
+const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend', 'append', 'addRow', 'addItem', 'set'];
+export async function runMdq(argv, readStdin) {
+    const program = new Command();
+    program
+        .name('mdq')
+        .description('query and edit markdown')
+        .argument('[selector]', 'markdown selector')
+        .argument('[file]', 'file to read; stdin when omitted')
+        .option('-j, --json', 'output rows as JSON')
+        .option('-c, --count', 'print the number of matches')
+        .option('-t, --text', 'print unwrapped text')
+        .option('--frontmatter', 'print frontmatter as JSON')
+        .option('-i, --in-place', 'write the result back to the file')
+        .option('--remove', 'delete matched blocks')
+        .option('--replace <markdown>', 'replace matched blocks')
+        .option('--insert-before <markdown>', 'insert before each match')
+        .option('--insert-after <markdown>', 'insert after each match')
+        .option('--prepend <markdown>', 'insert at the start of each match')
+        .option('--append <markdown>', 'insert at the end of each match')
+        .option('--add-row <json>', 'append a table row')
+        .option('--add-item <text>', 'append a list item')
+        .option('--set <key=value>', 'set an entry; omit the value to delete it')
+        .exitOverride()
+        .configureOutput({ writeOut: () => { }, writeErr: () => { } });
+    try {
+        program.parse(argv, { from: 'user' });
+    }
+    catch (error) {
+        return { output: String(error.message), code: 2 };
+    }
+    const options = program.opts();
+    let [selector, file] = program.args;
+    if (options.frontmatter && selector && !file) {
+        file = selector;
+        selector = '';
+    }
+    let source = '';
+    if (!file)
+        source = await readStdin();
+    if (file) {
+        try {
+            source = readFileSync(file, 'utf8');
+        }
+        catch {
+            return { output: `Cannot read ${file}`, code: 2 };
+        }
+    }
+    try {
+        return await apply(mdq(source), selector, options, file);
+    }
+    catch (error) {
+        if (error instanceof MdqError)
+            return { output: error.message, code: 2 };
+        throw error;
+    }
+}
+async function apply(doc, selector, options, file) {
+    if (options.frontmatter)
+        return { output: `${JSON.stringify(doc.frontmatter(), null, 2)}\n`, code: 0 };
+    if (!selector)
+        return { output: 'A selector is required', code: 2 };
+    const chosen = EDIT_FLAGS.filter((flag) => options[flag] !== undefined);
+    if (chosen.length > 1)
+        return { output: 'Only one edit at a time', code: 2 };
+    const selection = doc.query(selector);
+    if (chosen.length === 0)
+        return read(selection, options);
+    if (!selection.exists())
+        return finish(String(doc), 1, options, file);
+    return finish(String(edit(selection, chosen[0], options)), 0, options, file);
+}
+function read(selection, options) {
+    let code = 1;
+    if (selection.exists())
+        code = 0;
+    if (options.count)
+        return { output: `${selection.count()}\n`, code: 0 };
+    if (options.json)
+        return { output: `${JSON.stringify(selection.rows(), null, 2)}\n`, code };
+    if (options.text)
+        return {
+            output: selection
+                .nodes()
+                .map((node) => node.text)
+                .join('\n\n'),
+            code,
+        };
+    return { output: selection.text(), code };
+}
+function edit(selection, flag, options) {
+    if (flag === 'remove')
+        return selection.remove();
+    if (flag === 'replace')
+        return selection.replace(options.replace);
+    if (flag === 'insertBefore')
+        return selection.insertBefore(options.insertBefore);
+    if (flag === 'insertAfter')
+        return selection.insertAfter(options.insertAfter);
+    if (flag === 'prepend')
+        return selection.prepend(options.prepend);
+    if (flag === 'append')
+        return selection.append(options.append);
+    if (flag === 'addItem')
+        return selection.addItem(options.addItem);
+    if (flag === 'addRow')
+        return selection.addRow(JSON.parse(options.addRow));
+    const separator = options.set.indexOf('=');
+    if (separator < 0)
+        return selection.setEntry(options.set, null);
+    return selection.setEntry(options.set.slice(0, separator), options.set.slice(separator + 1) || null);
+}
+function finish(output, code, options, file) {
+    if (!options.inPlace)
+        return { output, code };
+    if (!file)
+        return { output: '--in-place needs a file', code: 2 };
+    writeFileSync(file, output);
+    return { output: '', code };
+}

package/dist/src/utils/mdq/edit.d.ts

@@ -0,0 +1,24 @@
+import type { MatchedRange } from './query.js';
+export declare class MarkdownEditor {
+    source: string;
+    constructor(source: string);
+    static splitFrontmatter(source: string): FrontmatterSplit;
+    static blockEnd(range: MatchedRange): number;
+    static table(headers: string[], rows: string[][], align: (string | null)[]): string;
+    static item(listRaw: string, text: string): string;
+    static entries(text: string, key: string, value: string | null, isBlockquote: boolean): string;
+    remove(ranges: MatchedRange[]): string;
+    replace(ranges: MatchedRange[], render: (range: MatchedRange, index: number) => string): string;
+    insert(offsets: number[], markdown: string): string;
+    frontmatter(): Record<string, unknown>;
+    setFrontmatter(key: string, value: unknown): string;
+    static spliceIn(source: string, offset: number, markdown: string): string;
+    static dashes(alignment: string | null, width: number): string;
+    static entryKey(line: string): string | null;
+    dedupe(ranges: MatchedRange[]): MatchedRange[];
+}
+export interface FrontmatterSplit {
+    raw: string;
+    body: string;
+    offset: number;
+}

package/dist/src/utils/mdq/edit.js

@@ -0,0 +1,147 @@
+import YAML from 'yaml';
+export class MarkdownEditor {
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    static splitFrontmatter(source) {
+        if (!source.startsWith('---'))
+            return { raw: '', body: source, offset: 0 };
+        const match = source.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+        if (!match)
+            return { raw: '', body: source, offset: 0 };
+        return { raw: match[1], body: source.slice(match[0].length), offset: match[0].length };
+    }
+    static blockEnd(range) {
+        if (range.trailing)
+            return range.trailing.start + range.trailing.length;
+        return range.start + range.length;
+    }
+    static table(headers, rows, align) {
+        const widths = headers.map((header, index) => Math.max(header.length, 3, ...rows.map((row) => (row[index] || '').length)));
+        const line = (cells) => `| ${cells.map((cell, index) => (cell || '').padEnd(widths[index])).join(' | ')} |`;
+        const divider = `| ${widths.map((width, index) => MarkdownEditor.dashes(align[index], width)).join(' | ')} |`;
+        return `${[line(headers), divider, ...rows.map(line)].join('\n')}\n`;
+    }
+    static item(listRaw, text) {
+        const lines = listRaw.split('\n').filter((line) => line.trim());
+        const last = lines[lines.length - 1] || '- x';
+        const ordered = last.match(/^(\s*)(\d+)([.)])\s/);
+        if (ordered)
+            return `${ordered[1]}${Number.parseInt(ordered[2], 10) + 1}${ordered[3]} ${text}`;
+        const bullet = last.match(/^(\s*)([-*+])\s/);
+        if (!bullet)
+            return `- ${text}`;
+        return `${bullet[1]}${bullet[2]} ${text}`;
+    }
+    static entries(text, key, value, isBlockquote) {
+        const lines = text
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+        const index = lines.findIndex((line) => MarkdownEditor.entryKey(line) === key.toLowerCase());
+        if (index < 0 && value)
+            lines.push(`${key}: ${value}`);
+        if (index >= 0 && value)
+            lines[index] = `${key}: ${value}`;
+        if (index >= 0 && !value)
+            lines.splice(index, 1);
+        if (!isBlockquote)
+            return lines.join('\n');
+        return lines.map((line) => `> ${line}`).join('\n');
+    }
+    remove(ranges) {
+        const ordered = this.dedupe(ranges);
+        let result = this.source;
+        for (let i = ordered.length - 1; i >= 0; i--) {
+            const range = ordered[i];
+            const head = result.slice(0, range.start);
+            const tail = result.slice(MarkdownEditor.blockEnd(range));
+            if (tail) {
+                result = head + tail;
+                continue;
+            }
+            if (!head) {
+                result = '';
+                continue;
+            }
+            result = `${head.trimEnd()}\n`;
+        }
+        return result;
+    }
+    replace(ranges, render) {
+        const ordered = this.dedupe(ranges);
+        const rendered = ordered.map(render);
+        let result = this.source;
+        for (let i = ordered.length - 1; i >= 0; i--) {
+            const range = ordered[i];
+            result = result.slice(0, range.start) + rendered[i] + result.slice(range.start + range.length);
+        }
+        return result;
+    }
+    insert(offsets, markdown) {
+        const ordered = [...offsets].sort((a, b) => a - b);
+        let result = this.source;
+        for (let i = ordered.length - 1; i >= 0; i--) {
+            result = MarkdownEditor.spliceIn(result, ordered[i], markdown);
+        }
+        return result;
+    }
+    frontmatter() {
+        const { raw } = MarkdownEditor.splitFrontmatter(this.source);
+        if (!raw)
+            return {};
+        return YAML.parseDocument(raw).toJS() || {};
+    }
+    setFrontmatter(key, value) {
+        const { raw, body, offset } = MarkdownEditor.splitFrontmatter(this.source);
+        let document = new YAML.Document({});
+        if (raw)
+            document = YAML.parseDocument(raw);
+        if (value === null)
+            document.delete(key);
+        if (value !== null)
+            document.set(key, value);
+        const rendered = document.toString().trimEnd();
+        if (!offset)
+            return `---\n${rendered}\n---\n\n${this.source}`;
+        return `---\n${rendered}\n---\n${body}`;
+    }
+    static spliceIn(source, offset, markdown) {
+        const block = `${markdown.trimEnd()}\n`;
+        const before = source.slice(0, offset).replace(/\n+$/, '');
+        const after = source.slice(offset).replace(/^\n+/, '');
+        if (!before)
+            return `${block}\n${after}`;
+        if (!after)
+            return `${before}\n\n${block}`;
+        return `${before}\n\n${block}\n${after}`;
+    }
+    static dashes(alignment, width) {
+        if (alignment === 'center')
+            return `:${'-'.repeat(Math.max(width - 2, 1))}:`;
+        if (alignment === 'left')
+            return `:${'-'.repeat(Math.max(width - 1, 1))}`;
+        if (alignment === 'right')
+            return `${'-'.repeat(Math.max(width - 1, 1))}:`;
+        return '-'.repeat(width);
+    }
+    static entryKey(line) {
+        const separator = line.indexOf(':');
+        if (separator < 1)
+            return null;
+        return line.slice(0, separator).trim().toLowerCase();
+    }
+    dedupe(ranges) {
+        const sorted = [...ranges].sort((a, b) => a.start - b.start);
+        const kept = [];
+        let lastEnd = -1;
+        for (const range of sorted) {
+            if (range.start < lastEnd)
+                continue;
+            kept.push(range);
+            lastEnd = range.start + range.length;
+        }
+        return kept;
+    }
+}

package/dist/src/utils/mdq/query.d.ts

@@ -0,0 +1,118 @@
+import { type Token } from 'marked';
+import { MarkdownEditor } from './edit.js';
+export { MarkdownEditor };
+export declare class MarkdownQuery {
+    source: string;
+    matches: MatchedRange[];
+    constructor(source: string, matches?: MatchedRange[]);
+    query(selector: string, matcher?: Matcher): MarkdownQuery;
+    section(matcher?: Matcher, options?: SelectorOptions): MarkdownQuery;
+    heading(matcher?: Matcher, options?: SelectorOptions): MarkdownQuery;
+    paragraph(matcher?: Matcher): MarkdownQuery;
+    table(matcher?: Matcher): MarkdownQuery;
+    list(matcher?: Matcher): MarkdownQuery;
+    item(matcher?: Matcher): MarkdownQuery;
+    code(matcher?: Matcher): MarkdownQuery;
+    blockquote(matcher?: Matcher): MarkdownQuery;
+    comment(matcher?: Matcher): MarkdownQuery;
+    html(matcher?: Matcher): MarkdownQuery;
+    hr(): MarkdownQuery;
+    text(): string;
+    nodes(): NodeInfo[];
+    rows(): Record<string, string>[];
+    entries(): Record<string, string>;
+    frontmatter(): Record<string, unknown>;
+    count(): number;
+    exists(): boolean;
+    at(index: number): MarkdownQuery;
+    slice(from?: number, to?: number): MarkdownQuery;
+    first(): MarkdownQuery;
+    last(): MarkdownQuery;
+    each(): MarkdownQuery[];
+    preceding(): MarkdownQuery;
+    following(): MarkdownQuery;
+    replace(content: Markdown): MarkdownQuery;
+    replaceEach(replacer: (match: MarkdownQuery, index: number) => Markdown): MarkdownQuery;
+    remove(): MarkdownQuery;
+    insertBefore(markdown: Markdown): MarkdownQuery;
+    insertAfter(markdown: Markdown): MarkdownQuery;
+    prepend(markdown: Markdown): MarkdownQuery;
+    append(markdown: Markdown): MarkdownQuery;
+    addRow(row: Record<string, string>): MarkdownQuery;
+    addItem(text: string): MarkdownQuery;
+    setEntry(key: string, value: string | null): MarkdownQuery;
+    setFrontmatter(key: string, value: unknown): MarkdownQuery;
+    toString(): string;
+    valueOf(): string;
+    /** Compatibility aliases. Each delegates to the canonical name above; prefer those. */
+    get(): string;
+    meta(): NodeInfo[];
+    toJson(): Record<string, string>[];
+    keyValue(): Record<string, string>;
+    setKeyValue(key: string, value: string | null): MarkdownQuery;
+    before(): MarkdownQuery;
+    after(): MarkdownQuery;
+    editor(): MarkdownEditor;
+    run(candidates: MatchedRange[], segments: QuerySegment[]): MatchedRange[];
+    sectionsOf(candidates: MatchedRange[], segment: QuerySegment): MatchedRange[];
+    itemsOf(candidates: MatchedRange[]): MatchedRange[];
+    expandSections(matches: MatchedRange[]): MatchedRange[];
+    narrow(matches: MatchedRange[], segment: QuerySegment): MatchedRange[];
+    filterByText(matches: MatchedRange[], segment: QuerySegment): MatchedRange[];
+    matchText(text: string, matcher: TextMatcher): boolean;
+    valueMatcher(matcher: Matcher): TextMatcher;
+    tokenText(token: Token): string;
+    isComment(token: Token): boolean;
+    insertAll(offsetOf: (range: MatchedRange) => number, markdown: Markdown): MarkdownQuery;
+    containerStart(range: MatchedRange): number;
+    containerEnd(range: MatchedRange): number;
+}
+export declare class MdqError extends Error {
+}
+export declare class MdqSelectorError extends MdqError {
+    index: number;
+    constructor(message: string, index: number);
+}
+export declare class MdqOperationError extends MdqError {
+    constructor(message: string);
+}
+export declare function mdq(source: Markdown): MarkdownQuery;
+export declare function parseQuery(input: string): QuerySegment[];
+export declare function buildTokenIndex(source: string): MatchedRange[];
+export type Markdown = string | MarkdownQuery;
+export type Matcher = string | RegExp | ((text: string) => boolean);
+export type SelectorType = 'comment' | 'html' | 'section' | 'section1' | 'section2' | 'section3' | 'section4' | 'section5' | 'section6' | 'table' | 'heading' | 'paragraph' | 'list' | 'item' | 'code' | 'blockquote' | 'hr' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+export interface SelectorOptions {
+    depth?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+export interface TextMatcher {
+    mode: 'exact' | 'contains' | 'regex' | 'predicate';
+    value: string;
+    negated: boolean;
+    flags?: string;
+    predicate?: (text: string) => boolean;
+}
+export interface QuerySegment {
+    selector: SelectorType;
+    textMatch?: TextMatcher;
+    index: number | null;
+    slice: {
+        from?: number;
+        to?: number;
+    } | null;
+}
+export interface MatchedRange {
+    token: Token;
+    start: number;
+    length: number;
+    trailing?: {
+        start: number;
+        length: number;
+    };
+    innerTokens?: MatchedRange[];
+}
+export interface NodeInfo {
+    type: string;
+    depth: number | null;
+    text: string;
+}