markdown-patch 0.1.1 → 0.1.3

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.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

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/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const TARGETABLE_BY_ISOLATED_BLOCK_REFERENCE: string[];
+export declare const CAN_INCLUDE_BLOCK_REFERENCE: string[];
+export declare enum ContentType {
+    text = "text/plain",
+    tableRows = "application/vnd.markdown-patch.table-rows+json"
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sCAAsC,UAQlD,CAAC;AAEF,eAAO,MAAM,2BAA2B,UAA6B,CAAC;AAEtE,oBAAY,WAAW;IACrB,IAAI,eAAe;IACnB,SAAS,mDAAmD;CAC7D"}

package/dist/constants.js

@@ -0,0 +1,15 @@
+export const TARGETABLE_BY_ISOLATED_BLOCK_REFERENCE = [
+    "code",
+    "heading",
+    "table",
+    "blockquote",
+    "list",
+    "paragraph",
+    "image",
+];
+export const CAN_INCLUDE_BLOCK_REFERENCE = ["paragraph", "list_item"];
+export var ContentType;
+(function (ContentType) {
+    ContentType["text"] = "text/plain";
+    ContentType["tableRows"] = "application/vnd.markdown-patch.table-rows+json";
+})(ContentType || (ContentType = {}));

package/dist/debug.d.ts

@@ -0,0 +1,3 @@
+import { DocumentMap } from "./types.js";
+export declare const printMap: (content: string, documentMap: DocumentMap, regex: RegExp | undefined) => void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,eAAO,MAAM,QAAQ,YACV,MAAM,eACF,WAAW,SACjB,MAAM,GAAG,SAAS,KACxB,IAmEF,CAAC"}

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.d.ts

@@ -0,0 +1,3 @@
+export { PatchFailureReason, PatchFailed, PatchError, TablePartsNotFound, applyPatch, } from "./patch.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { PatchFailureReason, PatchFailed, PatchError, TablePartsNotFound, applyPatch, } from "./patch.js";
+export * from "./types.js";

package/dist/map.d.ts

@@ -0,0 +1,3 @@
+import { DocumentMap } from "./types.js";
+export declare const getDocumentMap: (document: string) => DocumentMap;
+//# sourceMappingURL=map.d.ts.map

package/dist/map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../src/map.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAGZ,MAAM,YAAY,CAAC;AAyLpB,eAAO,MAAM,cAAc,aAAc,MAAM,KAAG,WAQjD,CAAC"}

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.d.ts

@@ -0,0 +1,19 @@
+import { DocumentMapMarkerContentPair, PatchInstruction } from "./types.js";
+export declare enum PatchFailureReason {
+    InvalidTarget = "invalid-target",
+    ContentAlreadyPreexistsInTarget = "content-already-preexists-in-target",
+    TableContentIncorrectColumnCount = "table-content-incorrect-column-count",
+    RequestedBlockTypeBehaviorUnavailable = "requested-block-type-behavior-unavailable"
+}
+export declare class PatchFailed extends Error {
+    reason: PatchFailureReason;
+    instruction: PatchInstruction;
+    targetMap: DocumentMapMarkerContentPair | null;
+    constructor(reason: PatchFailureReason, instruction: PatchInstruction, targetMap: DocumentMapMarkerContentPair | null);
+}
+export declare class PatchError extends Error {
+}
+export declare class TablePartsNotFound extends Error {
+}
+export declare const applyPatch: (document: string, instruction: PatchInstruction) => string;
+//# sourceMappingURL=patch.d.ts.map

package/dist/patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["../src/patch.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,4BAA4B,EAE5B,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAGpB,oBAAY,kBAAkB;IAC5B,aAAa,mBAAmB;IAChC,+BAA+B,wCAAwC;IACvE,gCAAgC,yCAAyC;IACzE,qCAAqC,8CAA8C;CACpF;AAED,qBAAa,WAAY,SAAQ,KAAK;IAC7B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,EAAE,4BAA4B,GAAG,IAAI,CAAC;gBAGpD,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,gBAAgB,EAC7B,SAAS,EAAE,4BAA4B,GAAG,IAAI;CAUjD;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AA0CxC,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAmNhD,eAAO,MAAM,UAAU,aACX,MAAM,eACH,gBAAgB,KAC5B,MA8BF,CAAC"}