markdown-patch 0.1.0

package/.tool-versions

@@ -0,0 +1 @@
+nodejs 20.8.0

package/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Jest All",
+            //"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/jest",
+            "args": [
+                "--runInBand"
+            ],
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen",
+            "program": "${workspaceFolder}/node_modules/.bin/jest",
+            "cwd": "${workspaceFolder}"
+        }
+    ]
+}

package/dist/index.js

@@ -0,0 +1,75 @@
+#!/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";
+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("mdpatch")
+    .description("Change markdown documents by inserting or changing content relative to headings or other parst of a document's structure.")
+    .version("0.1.0");
+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("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/document.md

@@ -0,0 +1,11 @@
+# Main
+
+Some content
+
+## Secondary
+
+Some more content
+
+## Tertiary
+
+Even more content

package/document.mdpatch.json

@@ -0,0 +1,8 @@
+[
+	{
+		"operation": "append",
+		"targetType": "heading",
+		"target": ["Main", "Secondary"],
+		"content": "This is a test\n"
+	}
+]

package/jest.config.ts

@@ -0,0 +1,9 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  // Include other configurations if needed
+  testPathIgnorePatterns: [
+	  "/node_modules/",
+	  "/dist/"
+  ]
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "dependencies": {
+    "@tsconfig/node16": "^16.1.3",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "marked": "^14.1.0"
+  },
+  "devDependencies": {
+    "@types/commander": "^2.12.2",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.4.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4"
+  },
+  "name": "markdown-patch",
+  "version": "0.1.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "node node_modules/.bin/jest"
+  },
+  "bin": {
+    "mdpatch": "./dist/index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "Change markdown documents by inserting or changing content relative to headings or other parts of a document's structure.",
+  "type": "module"
+}

package/src/constants.ts

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

package/src/debug.ts

@@ -0,0 +1,75 @@
+import chalk from "chalk";
+import { DocumentMap } from "./types.js";
+
+export const printMap = (
+  content: string,
+  documentMap: DocumentMap,
+  regex: RegExp | undefined
+): void => {
+  for (const type in documentMap) {
+    for (const positionName in documentMap[type as keyof typeof documentMap]) {
+      const position =
+        documentMap[type as keyof typeof documentMap][positionName];
+
+      const blockName = `${type} :: ${positionName.replaceAll(
+        "\u001f",
+        " :: "
+      )}`;
+      if (regex && !blockName.match(regex)) {
+        continue;
+      }
+      console.log("\n" + chalk.blue(blockName));
+      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/src/index.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs/promises";
+import { getDocumentMap } from "./map.js";
+import { printMap } from "./debug.js";
+import { PatchInstruction } from "./types.js";
+import { applyPatch } from "./patch.js";
+import packageJson from "../package.json" assert { type: "json" };
+
+async function readStdin(): Promise<string> {
+  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: string, regex: string | undefined) => {
+    const document = await fs.readFile(path, "utf-8");
+    const documentMap = getDocumentMap(document);
+
+    printMap(document, documentMap, regex ? new RegExp(regex) : undefined);
+  });
+
+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: string, patch: string, options) => {
+    let patchParsed: PatchInstruction[];
+    let patchData: string;
+    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/map.ts

@@ -0,0 +1,200 @@
+import * as marked from "marked";
+
+import {
+  DocumentMap,
+  DocumentMapMarkerContentPair,
+  HeadingMarkerContentPair,
+} from "./types.js";
+
+import {
+  CAN_INCLUDE_BLOCK_REFERENCE,
+  TARGETABLE_BY_ISOLATED_BLOCK_REFERENCE,
+} from "./constants.js";
+
+function getHeadingPositions(
+  document: string,
+  tokens: marked.TokensList
+): Record<string, HeadingMarkerContentPair> {
+  // 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: Record<string, HeadingMarkerContentPair> = {
+    "": {
+      content: {
+        start: documentStart,
+        end: document.length,
+      },
+      marker: {
+        start: 0,
+        end: 0,
+      },
+      level: 0,
+    },
+  };
+  const stack: Array<{ heading: string; position: HeadingMarkerContentPair }> =
+    [];
+
+  let currentPosition = 0;
+
+  tokens.forEach((token, index) => {
+    if (token.type === "heading") {
+      const headingToken = token as marked.Tokens.Heading;
+
+      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: number | undefined = undefined;
+      for (let i = index + 1; i < tokens.length; i++) {
+        if (
+          tokens[i].type === "heading" &&
+          (tokens[i] as marked.Tokens.Heading).depth <= headingLevel
+        ) {
+          endContent = document.indexOf(tokens[i].raw.trim(), startContent);
+          break;
+        }
+      }
+      if (endContent === undefined) {
+        endContent = document.length;
+      }
+
+      const currentHeading: HeadingMarkerContentPair = {
+        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: string,
+  tokens: marked.TokensList
+): Record<string, DocumentMapMarkerContentPair> {
+  const positions: Record<string, DocumentMapMarkerContentPair> = {};
+
+  let lastBlockDetails:
+    | {
+        token: marked.Token;
+        start: number;
+        end: number;
+      }
+    | undefined = 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: string): DocumentMap => {
+  const lexer = new marked.Lexer();
+  const tokens = lexer.lex(document);
+
+  return {
+    heading: getHeadingPositions(document, tokens),
+    block: getBlockPositions(document, tokens),
+  };
+};