@principal-ade/markdown-utils 0.1.3

package/README.md

@@ -0,0 +1,148 @@
+# @a24z/markdown-utils
+
+Core markdown parsing and presentation utilities without React dependencies. Extract slides, parse chunks, and handle markdown transformations.
+
+## Installation
+
+```bash
+npm install @a24z/markdown-utils
+# or
+bun add @a24z/markdown-utils
+```
+
+## Features
+
+- 📝 **Markdown parsing** - Parse markdown into typed chunks
+- 🎯 **Slide extraction** - Split markdown into presentation slides
+- 🔀 **Presentation diffing** - Compare two presentations slide-by-slide
+- 🔌 **Extensible** - Plugin system for custom chunk types
+- 🚀 **Zero React dependencies** - Pure TypeScript utilities
+- 📦 **Lightweight** - ~22KB bundled
+
+## Usage
+
+### Parse Markdown into Chunks
+
+```typescript
+import { parseMarkdownChunks, CHUNK_TYPES } from '@a24z/markdown-utils';
+
+const chunks = parseMarkdownChunks(markdownContent, 'my-prefix');
+
+chunks.forEach(chunk => {
+  if (chunk.type === CHUNK_TYPES.MERMAID) {
+    // Handle mermaid diagram
+    console.log('Mermaid:', chunk.content);
+  }
+});
+```
+
+### Create Presentation from Markdown
+
+```typescript
+import { parseMarkdownIntoPresentation, MarkdownPresentationFormat } from '@a24z/markdown-utils';
+
+// Split by horizontal rules (---)
+const presentation = parseMarkdownIntoPresentation(
+  markdownContent,
+  MarkdownPresentationFormat.HORIZONTAL_RULE
+);
+
+console.log(`${presentation.slides.length} slides found`);
+```
+
+### Compare Two Presentations
+
+```typescript
+import { diffPresentations, parseMarkdownIntoPresentation } from '@a24z/markdown-utils';
+
+const beforePresentation = parseMarkdownIntoPresentation(beforeMarkdown);
+const afterPresentation = parseMarkdownIntoPresentation(afterMarkdown);
+
+const diff = diffPresentations(beforePresentation, afterPresentation);
+
+console.log(`${diff.summary.modified} slides modified`);
+console.log(`${diff.summary.added} slides added`);
+console.log(`${diff.summary.removed} slides removed`);
+
+// Iterate through slide-by-slide diffs
+diff.slideDiffs.forEach(slideDiff => {
+  console.log(`Slide status: ${slideDiff.status}`);
+
+  if (slideDiff.status === 'modified') {
+    // Access line-by-line content changes
+    slideDiff.contentChanges?.forEach(change => {
+      if (change.type === 'add') {
+        console.log(`+ ${change.value}`);
+      } else if (change.type === 'remove') {
+        console.log(`- ${change.value}`);
+      }
+    });
+  }
+});
+```
+
+### Extend with Custom Chunks
+
+```typescript
+import { BaseChunk, parseMarkdownChunks } from '@a24z/markdown-utils';
+
+// Define custom chunk type
+interface MathChunk extends BaseChunk<'math_chunk'> {
+  formula: string;
+}
+
+// Custom parser
+const mathParser = (content: string, idPrefix: string): MathChunk[] => {
+  // Parse LaTeX math blocks...
+  return [];
+};
+
+// Use with parser
+const chunks = parseMarkdownChunks<MathChunk | ContentChunk>(
+  content,
+  'prefix',
+  [mathParser]
+);
+```
+
+## API
+
+### Types
+
+**Chunks:**
+- `BaseChunk<T>` - Base interface for extensible chunks
+- `MarkdownChunk`, `MermaidChunk`, `CodeChunk` - Built-in chunk types
+
+**Presentations:**
+- `MarkdownPresentation`, `MarkdownSlide` - Presentation types
+
+**Diffs:**
+- `PresentationDiff` - Complete diff analysis between two presentations
+- `SlideDiff` - Diff between two versions of a slide
+- `DiffSummary` - Summary statistics for a presentation diff
+- `DiffStatus` - Status of a slide: `'added' | 'removed' | 'modified' | 'unchanged' | 'moved'`
+- `TextDiff` - Line-level text change
+
+### Functions
+
+**Parsing:**
+- `parseMarkdownChunks()` - Parse markdown into typed chunks
+- `parseMarkdownIntoPresentation()` - Create presentation from markdown
+- `extractSlideTitle()` - Extract title from slide content
+
+**Diffing:**
+- `diffPresentations()` - Compare two presentations and generate diff
+- `calculateDiffSummary()` - Generate summary statistics from a diff
+- `diffText()` - Low-level line-by-line text comparison
+- `hasChanges()` - Check if a diff has any changes
+- `formatDiffSummary()` - Format summary as human-readable string
+
+**Utilities:**
+- `parseBashCommands()` - Parse bash code blocks
+- `transformImageUrl()` - Transform relative URLs to absolute
+- `slidesAreEqual()` - Check if two slides are identical
+- `normalizeText()` - Normalize text for comparison
+
+## License
+
+MIT - a24z Team

package/dist/cjs/diff/diffPresentations.d.ts

@@ -0,0 +1,17 @@
+import { MarkdownPresentation } from '../types/presentation';
+import { PresentationDiff } from '../types/diff';
+/**
+ * Compares two markdown presentations and generates a complete diff analysis.
+ *
+ * The algorithm:
+ * 1. Matches slides between presentations (by title, then position)
+ * 2. Determines the status of each slide (added, removed, modified, unchanged, moved)
+ * 3. For modified slides, computes line-by-line content changes
+ * 4. Generates summary statistics
+ *
+ * @param before - The original presentation
+ * @param after - The modified presentation
+ * @returns Complete diff analysis including slide-by-slide comparison and summary
+ */
+export declare function diffPresentations(before: MarkdownPresentation, after: MarkdownPresentation): PresentationDiff;
+//# sourceMappingURL=diffPresentations.d.ts.map

package/dist/cjs/diff/diffPresentations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffPresentations.d.ts","sourceRoot":"","sources":["../../../src/diff/diffPresentations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAKxE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,oBAAoB,GAC1B,gBAAgB,CA6BlB"}

package/dist/cjs/diff/diffSummary.d.ts

@@ -0,0 +1,31 @@
+import { PresentationDiff, DiffSummary } from '../types/diff';
+/**
+ * Calculates summary statistics for a presentation diff.
+ * Counts the number of slides in each status category.
+ *
+ * @param diff - The presentation diff to summarize
+ * @returns Summary statistics with counts for each diff status
+ */
+export declare function calculateDiffSummary(diff: PresentationDiff): DiffSummary;
+/**
+ * Checks if a presentation diff has any changes.
+ *
+ * @param diff - The presentation diff to check
+ * @returns true if there are any changes (added, removed, modified, or moved slides)
+ */
+export declare function hasChanges(diff: PresentationDiff): boolean;
+/**
+ * Gets the total number of changed slides (excluding unchanged).
+ *
+ * @param summary - The diff summary
+ * @returns Total number of changed slides
+ */
+export declare function getTotalChangedSlides(summary: DiffSummary): number;
+/**
+ * Formats a diff summary as a human-readable string.
+ *
+ * @param summary - The diff summary to format
+ * @returns Formatted string describing the changes
+ */
+export declare function formatDiffSummary(summary: DiffSummary): string;
+//# sourceMappingURL=diffSummary.d.ts.map

package/dist/cjs/diff/diffSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffSummary.d.ts","sourceRoot":"","sources":["../../../src/diff/diffSummary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAiCxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAQ1D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAqB9D"}

package/dist/cjs/diff/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Diff utilities for comparing markdown presentations
+ * @module diff
+ */
+export { diffPresentations } from './diffPresentations';
+export { calculateDiffSummary, hasChanges, getTotalChangedSlides, formatDiffSummary, } from './diffSummary';
+export { diffText, normalizedTextEquals, normalizeText } from './textDiff';
+export { matchSlides, slidesAreEqual, normalizeSlideContent, } from './matchSlides';
+export type { SlideMatch } from './matchSlides';
+export type { DiffStatus, TextDiffType, TextDiff, SlideDiff, DiffSummary, PresentationDiff, } from '../types/diff';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/diff/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/diff/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3E,OAAO,EACL,WAAW,EACX,cAAc,EACd,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC"}

package/dist/cjs/diff/matchSlides.d.ts

@@ -0,0 +1,44 @@
+import { MarkdownSlide } from '../types/presentation';
+/**
+ * Represents a matched pair of slides from before and after presentations
+ */
+export interface SlideMatch {
+    /** Slide from before presentation (undefined if added) */
+    beforeSlide?: MarkdownSlide;
+    /** Slide from after presentation (undefined if removed) */
+    afterSlide?: MarkdownSlide;
+    /** Index in before presentation (undefined if added) */
+    beforeIndex?: number;
+    /** Index in after presentation (undefined if removed) */
+    afterIndex?: number;
+    /** Whether the slide was matched by title or position */
+    matchedBy: 'title' | 'position' | 'none';
+}
+/**
+ * Matches slides between two presentations using a two-phase approach:
+ * 1. First, match slides by title
+ * 2. Then, match remaining slides by position
+ *
+ * @param beforeSlides - Slides from the before presentation
+ * @param afterSlides - Slides from the after presentation
+ * @returns Array of matched slide pairs
+ */
+export declare function matchSlides(beforeSlides: MarkdownSlide[], afterSlides: MarkdownSlide[]): SlideMatch[];
+/**
+ * Checks if two slides are equal (identical content).
+ * Compares normalized content to avoid false positives from whitespace differences.
+ *
+ * @param slide1 - First slide to compare
+ * @param slide2 - Second slide to compare
+ * @returns true if slides have identical content
+ */
+export declare function slidesAreEqual(slide1: MarkdownSlide, slide2: MarkdownSlide): boolean;
+/**
+ * Normalizes slide content for comparison.
+ * Extracts and normalizes the text content from the slide's location.
+ *
+ * @param slide - Slide to normalize
+ * @returns Normalized content string
+ */
+export declare function normalizeSlideContent(slide: MarkdownSlide): string;
+//# sourceMappingURL=matchSlides.d.ts.map

package/dist/cjs/diff/matchSlides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchSlides.d.ts","sourceRoot":"","sources":["../../../src/diff/matchSlides.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,SAAS,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,aAAa,EAAE,EAC7B,WAAW,EAAE,aAAa,EAAE,GAC3B,UAAU,EAAE,CAyFd;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa,GACpB,OAAO,CAGT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAElE"}

package/dist/cjs/diff/textDiff.d.ts

@@ -0,0 +1,30 @@
+import { TextDiff } from '../types/diff';
+/**
+ * Performs a line-by-line diff between two text strings.
+ * Uses a simple longest common subsequence (LCS) based algorithm.
+ *
+ * @param beforeContent - The original text
+ * @param afterContent - The modified text
+ * @returns Array of TextDiff objects representing the changes
+ */
+export declare function diffText(beforeContent: string, afterContent: string): TextDiff[];
+/**
+ * Checks if two text strings are equal after normalization.
+ * Normalization includes trimming whitespace and normalizing line endings.
+ *
+ * @param text1 - First text to compare
+ * @param text2 - Second text to compare
+ * @returns true if texts are equal after normalization
+ */
+export declare function normalizedTextEquals(text1: string, text2: string): boolean;
+/**
+ * Normalizes text by:
+ * - Trimming leading/trailing whitespace
+ * - Normalizing line endings to \n
+ * - Removing trailing whitespace from each line
+ *
+ * @param text - Text to normalize
+ * @returns Normalized text
+ */
+export declare function normalizeText(text: string): string;
+//# sourceMappingURL=textDiff.d.ts.map

package/dist/cjs/diff/textDiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textDiff.d.ts","sourceRoot":"","sources":["../../../src/diff/textDiff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,QAAQ,EAAE,CAeZ;AA+ED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlD"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,12 @@
+export { CHUNK_TYPES, type ChunkType, type BaseChunk, type MarkdownChunk, type MermaidChunk, type SlideChunk, type CodeChunk, type ContentChunk, isMarkdownChunk, isMermaidChunk, isCodeChunk, } from './types/chunks';
+export { MarkdownSourceType, type MarkdownSource, type MarkdownSlideLocation, type MarkdownSlide, type RepositoryInfo, type MarkdownPresentation, } from './types/presentation';
+export { type BashCommand, type BashCommandOptions, type BashCommandResult, } from './types/bash';
+export { parseMarkdownChunks, } from './utils/markdown-parser';
+export { extractSlideTitle, parseMarkdownIntoPresentationFromSource, parseMarkdownIntoPresentation, serializePresentationToMarkdown, updatePresentationSlide, } from './utils/presentation';
+export { parseBashCommands, getCommandDisplayName, } from './utils/bash-parser';
+export { isRelativeUrl, transformImageUrl, transformMarkdownImageUrls, } from './utils/image-urls';
+export { extractAllSlideTitles, getAllSlideTitles, findSlideByTitle, findSlideIndexByTitle, } from './utils/slide-titles';
+export type { DiffStatus, TextDiffType, TextDiff, SlideDiff, DiffSummary, PresentationDiff, } from './types/diff';
+export { diffPresentations, calculateDiffSummary, hasChanges, getTotalChangedSlides, formatDiffSummary, diffText, normalizedTextEquals, normalizeText, matchSlides, slidesAreEqual, normalizeSlideContent, } from './diff';
+export type { SlideMatch } from './diff';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,iBAAiB,EACjB,uCAAuC,EACvC,6BAA6B,EAC7B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,qBAAqB,EACrB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,cAAc,EACd,qBAAqB,GACtB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC"}