markdown-patch 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,111 @@
+# Markdown Patch
+
+Have you ever needed to set up a script for modifying a markdown document and found yourself using arcane tools like `sed` before giving up entirely?
+
+Markdown Patch (`mdpatch`) is aware of the structure of your markdown document and makes it possible for you to easily inserting content relative to parts of that structure like headings and block references.
+
+## Quickstart
+
+You can install the package via `npm`:
+
+```bash
+npm install markdown-patch
+```
+
+And if you were to create a document named `document.md` with the following content:
+
+```markdown
+# Noise Floor
+
+- Some content
+
+# Discoveries
+
+# Events
+
+- Checked out of my hotel
+- Caught the flight home
+
+```
+
+Then you can use the `patch` or `apply` subcommands to alter the document.  For example, the following will add a new heading below the heading "Discoveries":
+
+```bash
+mdpatch patch append heading Discoveries ./document.md
+
+## My discovery
+I discovered a thing
+
+<Ctrl+D>
+```
+
+Your final document will then look like:
+
+```markdown
+# Noise Floor
+
+- Some content
+
+# Discoveries
+
+## My discovery
+I discovered a thing
+
+# Events
+
+- Checked out of my hotel
+- Caught the flight home
+
+```
+
+See `--help` for more insight into what commands are available.
+
+## Use as a library
+
+```ts
+import {PatchInstruction, applyPatch} from "markdown-patch"
+
+const myDocument = `
+# Noise Floor
+
+- Some content
+
+# Discoveries
+
+# Events
+
+- Checked out of my hotel
+- Caught the flight home
+
+`
+
+const instruction: PatchInstruction {
+    operation: "append",
+    targetType: "heading",
+    target: "Discoveries",
+    content: "\n## My discovery\nI discovered a thing\n",
+}
+
+console.log(
+    applyPatch(myDocument, instruction)
+)
+```
+
+and you'll see the output:
+
+```markdown
+# Noise Floor
+
+- Some content
+
+# Discoveries
+
+## My discovery
+I discovered a thing
+
+# Events
+
+- Checked out of my hotel
+- Caught the flight home
+
+```

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs/promises";
+import { getDocumentMap } from "./map.js";
+import { printMap } from "./debug.js";
+import { applyPatch } from "./patch.js";
+import packageJson from "../package.json" assert { type: "json" };
+async function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+const program = new Command();
+// Configure the CLI
+program
+    .name(Object.keys(packageJson.bin)[0])
+    .description(packageJson.description)
+    .version(packageJson.version);
+program
+    .command("print-map")
+    .argument("<path>", "filepath to show identified patchable paths for")
+    .argument("[regex]", "limit displayed matches to those matching the supplied regular expression")
+    .action(async (path, regex) => {
+    const document = await fs.readFile(path, "utf-8");
+    const documentMap = getDocumentMap(document);
+    printMap(document, documentMap, regex ? new RegExp(regex) : undefined);
+});
+program
+    .command("patch")
+    .option("-i, --input <input>", "Path to content to insert; by default reads from stdin.")
+    .option("-o, --output <output>", "Path to write output to; use '-' for stdout.  Defaults to patching in-place.")
+    .option("-d, --delimiter <delimiter>", "Heading delimiter to use in place of '::'.", "::")
+    .argument("<operation>", "Operation to perform ('replace', 'append', etc.)")
+    .argument("<targetType>", "Target type ('heading', 'block', etc.)")
+    .argument("<target>", "Target ('::'-delimited by default for Headings); see `mdpatch print-map <path to document>` for options)")
+    .argument("<documentPath>", "Path to document to apply patch to.")
+    .action(async (operation, targetType, target, documentPath, options) => {
+    let content;
+    if (options.input) {
+        content = await fs.readFile(options.input, "utf-8");
+    }
+    else {
+        content = await readStdin();
+    }
+    const document = await fs.readFile(documentPath, "utf-8");
+    const instruction = {
+        operation,
+        targetType,
+        content,
+        target: targetType !== "heading" ? target : target.split(options.delimiter),
+    };
+    const patchedDocument = applyPatch(document, instruction);
+    if (options.output === "-") {
+        process.stdout.write(patchedDocument);
+    }
+    else {
+        await fs.writeFile(options.output ? options.output : documentPath, patchedDocument);
+    }
+});
+program
+    .command("apply")
+    .argument("<path>", "file to patch")
+    .argument("<patch>", "patch file to apply")
+    .option("-o, --output <output>", "write output to the specified path instead of applying in-place; use '-' for stdout")
+    .action(async (path, patch, options) => {
+    let patchParsed;
+    let patchData;
+    try {
+        if (patch === "-") {
+            patchData = await readStdin();
+        }
+        else {
+            patchData = await fs.readFile(patch, "utf-8");
+        }
+    }
+    catch (e) {
+        console.error("Failed to read patch: ", e);
+        process.exit(1);
+    }
+    try {
+        const parsedData = JSON.parse(patchData);
+        if (!Array.isArray(parsedData)) {
+            patchParsed = [parsedData];
+        }
+        else {
+            patchParsed = parsedData;
+        }
+    }
+    catch (e) {
+        console.error("Could not parse patch file as JSON");
+        process.exit(1);
+    }
+    let document = await fs.readFile(path, "utf-8");
+    console.log("Document", document);
+    for (const instruction of patchParsed) {
+        document = applyPatch(document, instruction);
+    }
+    if (options.output === "-") {
+        process.stdout.write(document);
+    }
+    else {
+        await fs.writeFile(options.output ? options.output : path, document);
+    }
+});
+program.parse(process.argv);

package/{src/constants.ts → dist/constants.js}

@@ -1,11 +1,10 @@
 export const TARGETABLE_BY_ISOLATED_BLOCK_REFERENCE = [
-  "code",
-  "heading",
-  "table",
-  "blockquote",
-  "list",
-  "paragraph",
-  "image",
+    "code",
+    "heading",
+    "table",
+    "blockquote",
+    "list",
+    "paragraph",
+    "image",
 ];
-
 export const CAN_INCLUDE_BLOCK_REFERENCE = ["paragraph", "list_item"];

package/dist/debug.js

@@ -0,0 +1,50 @@
+import chalk from "chalk";
+export const printMap = (content, documentMap, regex) => {
+    for (const type in documentMap) {
+        for (const positionName in documentMap[type]) {
+            const position = documentMap[type][positionName];
+            const blockName = `[${chalk.magenta(type)}] ${positionName
+                .split("\u001f")
+                .map((pos) => chalk.blueBright(pos))
+                .join(",")}`;
+            if (regex && !blockName.match(regex)) {
+                continue;
+            }
+            console.log("\n" + blockName + "\n");
+            if (position.content.start < position.marker.start) {
+                console.log(content
+                    .slice(position.content.start - 100, position.content.start)
+                    .replaceAll("\n", "\\n\n") +
+                    chalk.black.bgGreen(content
+                        .slice(position.content.start, position.content.end)
+                        .replaceAll("\n", "\\n\n")) +
+                    content
+                        .slice(position.content.end, Math.min(position.content.end + 100, position.marker.start))
+                        .replaceAll("\n", "\\n\n") +
+                    chalk.black.bgRed(content
+                        .slice(position.marker.start, position.marker.end)
+                        .replaceAll("\n", "\\n\n")) +
+                    content
+                        .slice(position.marker.end, position.marker.end + 100)
+                        .replaceAll("\n", "\\n\n"));
+            }
+            else {
+                console.log(content
+                    .slice(position.marker.start - 100, position.marker.start)
+                    .replaceAll("\n", "\\n\n") +
+                    chalk.black.bgRed(content
+                        .slice(position.marker.start, position.marker.end)
+                        .replaceAll("\n", "\\n\n")) +
+                    content
+                        .slice(position.marker.end, Math.min(position.marker.end + 100, position.content.start))
+                        .replaceAll("\n", "\\n\n") +
+                    chalk.black.bgGreen(content
+                        .slice(position.content.start, position.content.end)
+                        .replaceAll("\n", "\\n\n")) +
+                    content
+                        .slice(position.content.end, position.content.end + 100)
+                        .replaceAll("\n", "\\n\n"));
+            }
+        }
+    }
+};

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/map.js

@@ -0,0 +1,144 @@
+import * as marked from "marked";
+import { CAN_INCLUDE_BLOCK_REFERENCE, TARGETABLE_BY_ISOLATED_BLOCK_REFERENCE, } from "./constants.js";
+function getHeadingPositions(document, tokens) {
+    // If the document starts with frontmatter, figure out where
+    // the frontmatter ends so we can know where the text of the
+    // document begins
+    let documentStart = 0;
+    if (tokens[0].type === "hr") {
+        documentStart = tokens[0].raw.length + 1;
+        for (const token of tokens.slice(1)) {
+            documentStart += token.raw.length;
+            if (token.type === "hr") {
+                break;
+            }
+        }
+    }
+    const positions = {
+        "": {
+            content: {
+                start: documentStart,
+                end: document.length,
+            },
+            marker: {
+                start: 0,
+                end: 0,
+            },
+            level: 0,
+        },
+    };
+    const stack = [];
+    let currentPosition = 0;
+    tokens.forEach((token, index) => {
+        if (token.type === "heading") {
+            const headingToken = token;
+            const startHeading = document.indexOf(headingToken.raw.trim(), currentPosition);
+            const endHeading = startHeading + headingToken.raw.trim().length + 1;
+            const headingLevel = headingToken.depth;
+            // Determine the start of the content after this heading
+            const startContent = endHeading;
+            // Determine the end of the content before the next heading of the same or higher level, or end of document
+            let endContent = undefined;
+            for (let i = index + 1; i < tokens.length; i++) {
+                if (tokens[i].type === "heading" &&
+                    tokens[i].depth <= headingLevel) {
+                    endContent = document.indexOf(tokens[i].raw.trim(), startContent);
+                    break;
+                }
+            }
+            if (endContent === undefined) {
+                endContent = document.length;
+            }
+            const currentHeading = {
+                content: {
+                    start: startContent,
+                    end: endContent,
+                },
+                marker: {
+                    start: startHeading,
+                    end: endHeading,
+                },
+                level: headingLevel,
+            };
+            // Build the full heading path with parent headings separated by '\t'
+            let fullHeadingPath = headingToken.text.trim();
+            while (stack.length &&
+                stack[stack.length - 1].position.level >= headingLevel) {
+                stack.pop();
+            }
+            if (stack.length) {
+                const parent = stack[stack.length - 1];
+                parent.position.content.end = endContent;
+                fullHeadingPath = `${parent.heading}\u001f${fullHeadingPath}`;
+            }
+            positions[fullHeadingPath] = currentHeading;
+            stack.push({ heading: fullHeadingPath, position: currentHeading });
+            currentPosition = endHeading;
+        }
+    });
+    return positions;
+}
+function getBlockPositions(document, tokens) {
+    const positions = {};
+    let lastBlockDetails = undefined;
+    let startContent = 0;
+    let endContent = 0;
+    let endMarker = 0;
+    marked.walkTokens(tokens, (token) => {
+        const blockReferenceRegex = /(?:\s+|^)\^([a-zA-Z0-9_-]+)\s*$/;
+        startContent = document.indexOf(token.raw, startContent);
+        const match = blockReferenceRegex.exec(token.raw);
+        endContent = startContent + (match ? match.index : token.raw.length);
+        const startMarker = match ? startContent + match.index : -1;
+        endMarker = startContent + token.raw.length;
+        // The end of a list item token sometimes doesn't include the trailing
+        // newline -- i'm honestly not sure why, but treating it as
+        // included here would simplify my implementation
+        if (document.slice(endMarker - 1, endMarker) !== "\n" &&
+            document.slice(endMarker, endMarker + 1) === "\n") {
+            endMarker += 1;
+        }
+        else if (document.slice(endMarker - 2, endMarker) !== "\r\n" &&
+            document.slice(endMarker, endMarker + 2) === "\r\n") {
+            endMarker += 2;
+        }
+        if (CAN_INCLUDE_BLOCK_REFERENCE.includes(token.type) && match) {
+            const name = match[1];
+            if (!name || match.index === undefined) {
+                return;
+            }
+            const finalStartContent = {
+                start: startContent,
+                end: endContent,
+            };
+            if (finalStartContent.start === finalStartContent.end &&
+                lastBlockDetails) {
+                finalStartContent.start = lastBlockDetails.start;
+                finalStartContent.end = lastBlockDetails.end;
+            }
+            positions[name] = {
+                content: finalStartContent,
+                marker: {
+                    start: startMarker,
+                    end: endMarker,
+                },
+            };
+        }
+        if (TARGETABLE_BY_ISOLATED_BLOCK_REFERENCE.includes(token.type)) {
+            lastBlockDetails = {
+                token: token,
+                start: startContent,
+                end: endContent - 1,
+            };
+        }
+    });
+    return positions;
+}
+export const getDocumentMap = (document) => {
+    const lexer = new marked.Lexer();
+    const tokens = lexer.lex(document);
+    return {
+        heading: getHeadingPositions(document, tokens),
+        block: getBlockPositions(document, tokens),
+    };
+};

package/dist/patch.js

@@ -0,0 +1,191 @@
+import { getDocumentMap } from "./map.js";
+import * as marked from "marked";
+export var PatchFailureReason;
+(function (PatchFailureReason) {
+    PatchFailureReason["InvalidTarget"] = "invalid-target";
+    PatchFailureReason["ContentAlreadyPreexistsInTarget"] = "content-already-preexists-in-target";
+    PatchFailureReason["TableContentIncorrectColumnCount"] = "table-content-incorrect-column-count";
+    PatchFailureReason["RequestedBlockTypeBehaviorUnavailable"] = "requested-block-type-behavior-unavailable";
+})(PatchFailureReason || (PatchFailureReason = {}));
+export class PatchFailed extends Error {
+    constructor(reason, instruction, targetMap) {
+        super();
+        this.reason = reason;
+        this.instruction = instruction;
+        this.targetMap = targetMap;
+        this.name = "PatchFailed";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class PatchError extends Error {
+}
+const replaceText = (document, instruction, target) => {
+    return [
+        document.slice(0, target.content.start),
+        instruction.content,
+        document.slice(target.content.end),
+    ].join("");
+};
+const prependText = (document, instruction, target) => {
+    return [
+        document.slice(0, target.content.start),
+        instruction.content,
+        instruction.trimTargetWhitespace
+            ? document.slice(target.content.start).trimStart()
+            : document.slice(target.content.start),
+    ].join("");
+};
+const appendText = (document, instruction, target) => {
+    return [
+        instruction.trimTargetWhitespace
+            ? document.slice(0, target.content.end).trimEnd()
+            : document.slice(0, target.content.end),
+        instruction.content,
+        document.slice(target.content.end),
+    ].join("");
+};
+export class TablePartsNotFound extends Error {
+}
+const _getTableData = (document, target) => {
+    const targetTable = document.slice(target.content.start, target.content.end);
+    const tableToken = marked.lexer(targetTable)[0];
+    const match = /^(.*?)(?:\r?\n)(.*?)(\r?\n)/.exec(targetTable);
+    if (!(tableToken.type === "table") || !match) {
+        throw new TablePartsNotFound();
+    }
+    const lineEnding = match[3];
+    return {
+        token: tableToken,
+        lineEnding: match[3],
+        headerParts: match[1] + lineEnding + match[2] + lineEnding,
+        contentParts: targetTable.slice(match[0].length),
+    };
+};
+const replaceTable = (document, instruction, target) => {
+    try {
+        const table = _getTableData(document, target);
+        const tableRows = [table.headerParts];
+        for (const row of instruction.content) {
+            if (row.length !== table.token.header.length || typeof row === "string") {
+                throw new PatchFailed(PatchFailureReason.TableContentIncorrectColumnCount, instruction, target);
+            }
+            tableRows.push("| " + row.join(" | ") + " |" + table.lineEnding);
+        }
+        return [
+            document.slice(0, target.content.start),
+            tableRows.join(""),
+            document.slice(target.content.end),
+        ].join("");
+    }
+    catch (TablePartsNotFound) {
+        throw new PatchFailed(PatchFailureReason.RequestedBlockTypeBehaviorUnavailable, instruction, target);
+    }
+};
+const prependTable = (document, instruction, target) => {
+    try {
+        const table = _getTableData(document, target);
+        const tableRows = [table.headerParts];
+        for (const row of instruction.content) {
+            if (row.length !== table.token.header.length || typeof row === "string") {
+                throw new PatchFailed(PatchFailureReason.TableContentIncorrectColumnCount, instruction, target);
+            }
+            tableRows.push("| " + row.join(" | ") + " |" + table.lineEnding);
+        }
+        tableRows.push(table.contentParts);
+        return [
+            document.slice(0, target.content.start),
+            tableRows.join(""),
+            document.slice(target.content.end),
+        ].join("");
+    }
+    catch (TablePartsNotFound) {
+        throw new PatchFailed(PatchFailureReason.RequestedBlockTypeBehaviorUnavailable, instruction, target);
+    }
+};
+const appendTable = (document, instruction, target) => {
+    try {
+        const table = _getTableData(document, target);
+        const tableRows = [table.headerParts, table.contentParts];
+        for (const row of instruction.content) {
+            if (row.length !== table.token.header.length || typeof row === "string") {
+                throw new PatchFailed(PatchFailureReason.TableContentIncorrectColumnCount, instruction, target);
+            }
+            tableRows.push("| " + row.join(" | ") + " |" + table.lineEnding);
+        }
+        return [
+            document.slice(0, target.content.start),
+            tableRows.join(""),
+            document.slice(target.content.end),
+        ].join("");
+    }
+    catch (TablePartsNotFound) {
+        throw new PatchFailed(PatchFailureReason.RequestedBlockTypeBehaviorUnavailable, instruction, target);
+    }
+};
+const replace = (document, instruction, target) => {
+    const targetBlockTypeBehavior = "targetBlockTypeBehavior" in instruction &&
+        instruction.targetBlockTypeBehavior
+        ? instruction.targetBlockTypeBehavior
+        : "text";
+    switch (targetBlockTypeBehavior) {
+        case "text":
+            return replaceText(document, instruction, target);
+        case "table":
+            return replaceTable(document, instruction, target);
+    }
+};
+const prepend = (document, instruction, target) => {
+    const targetBlockTypeBehavior = "targetBlockTypeBehavior" in instruction &&
+        instruction.targetBlockTypeBehavior
+        ? instruction.targetBlockTypeBehavior
+        : "text";
+    switch (targetBlockTypeBehavior) {
+        case "text":
+            return prependText(document, instruction, target);
+        case "table":
+            return prependTable(document, instruction, target);
+    }
+};
+const append = (document, instruction, target) => {
+    const targetBlockTypeBehavior = "targetBlockTypeBehavior" in instruction &&
+        instruction.targetBlockTypeBehavior
+        ? instruction.targetBlockTypeBehavior
+        : "text";
+    switch (targetBlockTypeBehavior) {
+        case "text":
+            return appendText(document, instruction, target);
+        case "table":
+            return appendTable(document, instruction, target);
+    }
+};
+const getTarget = (map, instruction) => {
+    switch (instruction.targetType) {
+        case "heading":
+            return map.heading[instruction.target ? instruction.target.join("\u001f") : ""];
+        case "block":
+            return map.block[instruction.target];
+    }
+};
+export const applyPatch = (document, instruction) => {
+    const map = getDocumentMap(document);
+    const target = getTarget(map, instruction);
+    if (!target) {
+        throw new PatchFailed(PatchFailureReason.InvalidTarget, instruction, null);
+    }
+    if ((!("applyIfContentPreexists" in instruction) ||
+        !instruction.applyIfContentPreexists) &&
+        typeof instruction.content === "string" &&
+        document
+            .slice(target.content.start, target.content.end)
+            .includes(instruction.content.trim())) {
+        throw new PatchFailed(PatchFailureReason.ContentAlreadyPreexistsInTarget, instruction, target);
+    }
+    switch (instruction.operation) {
+        case "append":
+            return append(document, instruction, target);
+        case "prepend":
+            return prepend(document, instruction, target);
+        case "replace":
+            return replace(document, instruction, target);
+    }
+};