@dunkinfrunkin/mdcat 0.1.15 → 0.1.17

package/README.md

@@ -6,7 +6,7 @@
 [![CI](https://github.com/dunkinfrunkin/mdcat/actions/workflows/ci.yml/badge.svg)](https://github.com/dunkinfrunkin/mdcat/actions/workflows/ci.yml)
 [![site](https://img.shields.io/badge/site-mdcat.frankchan.dev-61afef)](https://mdcat.frankchan.dev)
 
-**Terminal pager for Markdown.** Full colour, syntax highlighting, incremental search, mouse support — zero config.
+**Terminal pager for Markdown.** Full colour, syntax highlighting, git diff gutter, incremental search, mouse support — zero config.
 
 ```sh
 npm install -g @dunkinfrunkin/mdcat
@@ -33,6 +33,7 @@ npx @dunkinfrunkin/mdcat README.md
 
 ```sh
 mdcat README.md                  # open a file
+mdcat file1.md file2.md file3.md # view multiple files
 mdcat --web README.md            # render and open in browser
 mdcat -p README.md               # plain text output (no TUI, no ANSI)
 mdcat -n README.md               # show line numbers
@@ -97,6 +98,7 @@ MDCAT_THEME=light mdcat file.md  # env var override
 | Images | `[alt text]` badge in dim |
 | Horizontal rules | Full-width dim `─` line |
 | HTML entities | Decoded (`&`, `<`, …) |
+| Git diff gutter | Green `+` added, yellow `~` modified, red `-` deleted |
 
 ## Contributing
 
@@ -109,7 +111,7 @@ npm install
 npm test
 ```
 
-All PRs must pass `npm test` (90 tests).
+All PRs must pass `npm test` (107 tests).
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunkinfrunkin/mdcat",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "View markdown files beautifully in your terminal",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -8,6 +8,8 @@ import { renderTokens, setTheme } from "./render.js";
 import { launch } from "./tui.js";
 import { toDocx } from "./docx.js";
 import { detectTheme, themeFromArgs, stripThemeArgs } from "./theme.js";
+import { concatFiles } from "./concat.js";
+import { getDiffMap, mapDiffToRendered } from "./git.js";
 
 marked.use({ gfm: true });
 
@@ -27,7 +29,7 @@ if (args[0] === "--help" || args[0] === "-h") {
   console.log(`\n${CAT}  ${bold("mdcat")} ${dim(`v${pkg.version}`)}`);
   console.log(`${dim("         markdown pager for your terminal")}\n`);
   console.log(`${bold("Usage:")}`);
-  console.log(`  mdcat ${dim("<file.md>")}`);
+  console.log(`  mdcat ${dim("<file.md> [file2.md ...]")}`);
   console.log(`  mdcat ${dim("--web <file.md>")}   ${dim("# open in browser")}`);
   console.log(`  mdcat ${dim("--doc <file.md>")}   ${dim("# export to .docx")}`);
   console.log(`  mdcat ${dim("-p, --plain")}       ${dim("# plain output (no TUI, no ANSI)")}`);
@@ -149,12 +151,20 @@ function openInBrowser(title, content) {
   catch { console.error(`mdcat: could not open browser`); process.exit(1); }
 }
 
-function runTUI(title, content) {
+function runTUI(title, content, filePath) {
   const termCols = process.stdout.columns || 80;
   const cols = Math.min(termCols, MAX_COLS);
   const tokens = marked.lexer(content);
   const lines = renderTokens(tokens, cols, termCols > MAX_COLS ? termCols : undefined);
-  launch(title, lines, activeTheme, { lineNumbers: showLineNumbers });
+
+  let diffMap = new Map();
+  if (filePath) {
+    const sourceLineCount = content.split("\n").length;
+    const sourceDiffMap = getDiffMap(filePath, sourceLineCount);
+    diffMap = mapDiffToRendered(sourceDiffMap, sourceLineCount, lines.length);
+  }
+
+  launch(title, lines, activeTheme, { lineNumbers: showLineNumbers, diffMap });
 }
 
 // --web / --doc flags
@@ -183,20 +193,26 @@ if (!process.stdin.isTTY && fileArgs.length === 0) {
     else runTUI("stdin", input);
   });
 } else if (fileArgs.length === 0) {
-  console.error("Usage: mdcat <file.md>");
+  console.error("Usage: mdcat <file.md> [file2.md ...]");
   process.exit(1);
 } else {
-  const filePath = resolve(fileArgs[0]);
-  let content;
-  try {
-    content = readFileSync(filePath, "utf8");
-  } catch (err) {
-    console.error(`mdcat: ${fileArgs[0]}: ${err.code === "ENOENT" ? "No such file" : err.message}`);
-    process.exit(1);
+  const parts = [];
+  for (const arg of fileArgs) {
+    const filePath = resolve(arg);
+    let text;
+    try {
+      text = readFileSync(filePath, "utf8");
+    } catch (err) {
+      console.error(`mdcat: ${arg}: ${err.code === "ENOENT" ? "No such file" : err.message}`);
+      process.exit(1);
+    }
+    parts.push({ name: basename(filePath), content: text });
   }
-  const title = basename(filePath);
+
+  const { title, content } = concatFiles(parts);
+
   if (docMode) exportDocx(title, content);
   else if (webMode) openInBrowser(title, content);
   else if (plainMode) runPlain(content);
-  else runTUI(title, content);
+  else runTUI(title, content, filePath);
 }

package/src/concat.js

@@ -0,0 +1,16 @@
+/**
+ * Concatenate multiple file entries into a single markdown document.
+ * Each entry is { name, content }. When there is more than one file,
+ * a `## filename` heading and `---` separator are inserted between files.
+ * Returns { title, content }.
+ */
+export function concatFiles(parts) {
+  if (parts.length === 0) return { title: "", content: "" };
+  if (parts.length === 1) return { title: parts[0].name, content: parts[0].content };
+  return {
+    title: `${parts.length} files`,
+    content: parts
+      .map(p => `## ${p.name}\n\n${p.content}`)
+      .join("\n\n---\n\n"),
+  };
+}

package/src/git.js

@@ -0,0 +1,207 @@
+import { execFileSync } from "child_process";
+import { dirname } from "path";
+
+/**
+ * Parse unified diff output into a Map of source line numbers to change types.
+ *
+ * Change types:
+ *   "added"    — line exists only in the working copy
+ *   "modified" — line was changed (deletion + addition at the same position)
+ *   "deleted"  — a deletion occurred at or just before this line
+ *
+ * @param {string} diffOutput - raw unified diff text (from `git diff`)
+ * @returns {Map<number, string>} lineNumber (1-based) → "added" | "modified" | "deleted"
+ */
+export function parseDiff(diffOutput) {
+  const map = new Map();
+  if (!diffOutput) return map;
+
+  const lines = diffOutput.split("\n");
+  let newLine = 0; // current line number in the new (working) file
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Parse hunk header: @@ -oldstart,oldcount +newstart,newcount @@
+    const hunkMatch = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (hunkMatch) {
+      const oldStart = parseInt(hunkMatch[1], 10);
+      const oldCount = hunkMatch[2] !== undefined ? parseInt(hunkMatch[2], 10) : 1;
+      const newStart = parseInt(hunkMatch[3], 10);
+      const newCount = hunkMatch[4] !== undefined ? parseInt(hunkMatch[4], 10) : 1;
+
+      newLine = newStart;
+
+      // Walk through hunk body lines
+      let j = i + 1;
+      let curNew = newStart;
+      let curOld = oldStart;
+
+      while (j < lines.length && !lines[j].startsWith("@@") && !lines[j].startsWith("diff ")) {
+        const hLine = lines[j];
+
+        if (hLine.startsWith("---") || hLine.startsWith("+++")) {
+          j++;
+          continue;
+        }
+
+        if (hLine.startsWith("-")) {
+          // Deletion — look ahead to see if the next line is an addition (modification)
+          let k = j + 1;
+          // Peek ahead: if the next non-delete line is a +, this is a modification
+          if (k < lines.length && lines[k].startsWith("+")) {
+            // This is a modification: the + line replaces the - line
+            map.set(curNew, "modified");
+            curOld++;
+            curNew++;
+            j = k + 1; // skip both - and + lines
+            continue;
+          }
+          // Pure deletion — mark the current new-file line
+          // If curNew hasn't gone past the file, mark it as a deletion point
+          if (!map.has(curNew)) {
+            map.set(curNew, "deleted");
+          }
+          curOld++;
+          j++;
+          continue;
+        }
+
+        if (hLine.startsWith("+")) {
+          // Pure addition
+          map.set(curNew, "added");
+          curNew++;
+          j++;
+          continue;
+        }
+
+        // Context line (starts with space or is empty after diff markers)
+        curNew++;
+        curOld++;
+        j++;
+      }
+
+      // Advance outer loop past the hunk body we just consumed
+      i = j - 1;
+      continue;
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Check whether a file is tracked by git.
+ *
+ * @param {string} filePath - absolute path to the file
+ * @returns {boolean}
+ */
+function isTracked(filePath) {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", filePath], {
+      cwd: dirname(filePath),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check whether a path is inside a git repository.
+ *
+ * @param {string} filePath - absolute path to the file
+ * @returns {boolean}
+ */
+function isGitRepo(filePath) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd: dirname(filePath),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get a diff map for a file, mapping source line numbers to change types.
+ *
+ * Handles:
+ * - Not a git repo: returns empty map
+ * - Untracked file: returns map with every line marked "added"
+ * - Tracked file with changes: parses `git diff HEAD -- <file>`
+ * - Tracked file with no changes: returns empty map
+ *
+ * @param {string} filePath - absolute path to the file
+ * @param {number} totalLines - total number of lines in the file
+ * @returns {Map<number, string>} lineNumber (1-based) → "added" | "modified" | "deleted"
+ */
+export function getDiffMap(filePath, totalLines) {
+  if (!isGitRepo(filePath)) {
+    return new Map();
+  }
+
+  if (!isTracked(filePath)) {
+    // Untracked file — everything is "added"
+    const map = new Map();
+    for (let i = 1; i <= totalLines; i++) {
+      map.set(i, "added");
+    }
+    return map;
+  }
+
+  try {
+    const diff = execFileSync("git", ["diff", "HEAD", "--", filePath], {
+      cwd: dirname(filePath),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return parseDiff(diff);
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Map source-file diff markers to rendered output lines using proportional mapping.
+ *
+ * Since markdown rendering changes the line count (headings become boxes, code blocks
+ * get borders, etc.), we use a proportional mapping from source lines to rendered lines.
+ *
+ * @param {Map<number, string>} sourceDiffMap - from getDiffMap (1-based source lines)
+ * @param {number} sourceLineCount - total lines in the source file
+ * @param {number} renderedLineCount - total lines in the rendered output
+ * @returns {Map<number, string>} renderedLineIndex (0-based) → "added" | "modified" | "deleted"
+ */
+export function mapDiffToRendered(sourceDiffMap, sourceLineCount, renderedLineCount) {
+  const rendered = new Map();
+  if (sourceDiffMap.size === 0 || sourceLineCount === 0 || renderedLineCount === 0) {
+    return rendered;
+  }
+
+  for (const [srcLine, type] of sourceDiffMap) {
+    // Proportional mapping: source line 1..N → rendered line 0..(M-1)
+    const ratio = (srcLine - 1) / Math.max(sourceLineCount - 1, 1);
+    const renderedLine = Math.round(ratio * (renderedLineCount - 1));
+    const clamped = Math.max(0, Math.min(renderedLine, renderedLineCount - 1));
+
+    // If a line already has a stronger marker, keep it
+    // Priority: modified > added > deleted
+    const existing = rendered.get(clamped);
+    if (!existing || priority(type) > priority(existing)) {
+      rendered.set(clamped, type);
+    }
+  }
+
+  return rendered;
+}
+
+function priority(type) {
+  if (type === "modified") return 3;
+  if (type === "added") return 2;
+  if (type === "deleted") return 1;
+  return 0;
+}

package/src/tui.js

@@ -143,6 +143,9 @@ export function launch(title, lines, theme, opts = {}) {
   const totalDigits = String(lines.length).length;
   const gutterW = totalDigits + 2; // "  N " width
 
+  // Git diff map (rendered line index → "added" | "modified" | "deleted")
+  const diffMap = opts.diffMap ?? new Map();
+
   // Viewport state
   let offset = 0;
 
@@ -230,6 +233,15 @@ export function launch(title, lines, theme, opts = {}) {
     return `${C.chromeBg}${left}${C.dimFg}${" ".repeat(gap)}${cat}${RESET}`;
   }
 
+  function diffMarkerFor(absLine) {
+    const type = diffMap.get(absLine);
+    if (!type) return "";
+    if (type === "added")    return `${C.greenFg}+${RESET}`;
+    if (type === "modified") return `${C.matchFg}~${RESET}`;
+    if (type === "deleted")  return `${C.redFg}-${RESET}`;
+    return "";
+  }
+
   function gutterFor(absLine) {
     let prefix = "";
     if (lineNumbers) {
@@ -237,10 +249,13 @@ export function launch(title, lines, theme, opts = {}) {
       prefix = `${C.dimFg}${num}${RESET} `;
     }
 
-    if (mode === "normal" || !searchQuery) return prefix || "  ";
-    if (matchLines[matchIdx] === absLine)   return `${prefix}${C.matchFg}▶${RESET} `;
-    if (matchSet.has(absLine))              return `${prefix}${C.otherMatchFg}›${RESET} `;
-    return prefix || "  ";
+    // Diff gutter marker (single char column before content)
+    const diff = diffMap.size > 0 ? (diffMarkerFor(absLine) || " ") : "";
+
+    if (mode === "normal" || !searchQuery) return `${prefix}${diff}${diff ? " " : prefix ? "" : "  "}`;
+    if (matchLines[matchIdx] === absLine)   return `${prefix}${diff ? diff + " " : ""}${C.matchFg}▶${RESET} `;
+    if (matchSet.has(absLine))              return `${prefix}${diff ? diff + " " : ""}${C.otherMatchFg}›${RESET} `;
+    return `${prefix}${diff}${diff ? " " : prefix ? "" : "  "}`;
   }
 
   function statusBar(w) {