mrmd-project 0.1.0

package/src/assets.js

@@ -0,0 +1,142 @@
+/**
+ * Assets module - Asset path computation and refactoring
+ *
+ * Handles relative paths between documents and assets in _assets/.
+ *
+ * @module Assets
+ */
+
+/**
+ * Compute the relative path from a document to an asset
+ *
+ * @param {string} documentPath - Path of the document (relative to project root)
+ * @param {string} assetPath - Path of the asset (relative to project root)
+ * @returns {string} Relative path from document to asset
+ *
+ * @example
+ * Assets.computeRelativePath('01-intro.md', '_assets/img.png')
+ * // Returns '_assets/img.png'
+ *
+ * Assets.computeRelativePath('02-section/01-doc.md', '_assets/img.png')
+ * // Returns '../_assets/img.png'
+ */
+export function computeRelativePath(documentPath, assetPath) {
+  if (!documentPath || !assetPath) return assetPath || '';
+
+  // Get document directory (remove filename)
+  const docDir = documentPath.includes('/')
+    ? documentPath.split('/').slice(0, -1).join('/')
+    : '';
+
+  // If document is at root, return asset path as-is
+  if (!docDir) {
+    return assetPath;
+  }
+
+  // Count how many levels up we need to go
+  const docDepth = docDir.split('/').length;
+
+  // Build the relative path
+  const upPath = '../'.repeat(docDepth);
+  return upPath + assetPath;
+}
+
+/**
+ * Update asset paths in content when a document moves
+ *
+ * @param {string} content - Document content
+ * @param {string} oldDocPath - Old document path
+ * @param {string} newDocPath - New document path
+ * @param {string} assetsDir - Assets directory name (default '_assets')
+ * @returns {string} Content with updated asset paths
+ *
+ * @example
+ * Assets.refactorPaths(
+ *   '![Img](_assets/img.png)',
+ *   '01-intro.md',
+ *   '02-section/01-intro.md',
+ *   '_assets'
+ * )
+ * // Returns '![Img](../_assets/img.png)'
+ */
+export function refactorPaths(content, oldDocPath, newDocPath, assetsDir = '_assets') {
+  if (!content) return content;
+
+  // Calculate old and new depths
+  const oldDir = oldDocPath.includes('/') ? oldDocPath.split('/').slice(0, -1).join('/') : '';
+  const newDir = newDocPath.includes('/') ? newDocPath.split('/').slice(0, -1).join('/') : '';
+
+  const oldDepth = oldDir ? oldDir.split('/').length : 0;
+  const newDepth = newDir ? newDir.split('/').length : 0;
+
+  // Find all asset references and update them
+  const regex = /(!?)\[([^\]]*)\]\(([^)]+)\)/g;
+
+  return content.replace(regex, (match, bang, alt, path) => {
+    // Check if this path references assets
+    if (!path.includes(assetsDir)) {
+      return match;
+    }
+
+    // Extract the asset path relative to project root
+    // Old path might be: _assets/img.png or ../_assets/img.png or ../../_assets/img.png
+    let assetRelativePath;
+
+    if (path.startsWith(assetsDir)) {
+      // Direct path from root: _assets/img.png
+      assetRelativePath = path;
+    } else if (path.includes('/' + assetsDir)) {
+      // Relative path: ../_assets/img.png
+      const idx = path.indexOf(assetsDir);
+      assetRelativePath = path.slice(idx);
+    } else {
+      // Can't parse, leave as-is
+      return match;
+    }
+
+    // Compute new relative path
+    const newRelativePath = computeRelativePath(newDocPath, assetRelativePath);
+
+    return `${bang}[${alt}](${newRelativePath})`;
+  });
+}
+
+/**
+ * Extract all asset references from content
+ *
+ * Finds both image syntax ![](path) and link syntax [](path) that reference assets.
+ *
+ * @param {string} content - Document content
+ * @returns {object[]} Array of asset references
+ *
+ * @example
+ * Assets.extractPaths('![Alt](../_assets/img.png)')
+ * // Returns [{ path: '../_assets/img.png', start: 6, end: 26, type: 'image' }]
+ */
+export function extractPaths(content) {
+  if (!content) return [];
+
+  const refs = [];
+
+  // Match both images ![alt](path) and links [text](path)
+  // that reference _assets
+  const regex = /(!?)\[([^\]]*)\]\(([^)]+)\)/g;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    const isImage = match[1] === '!';
+    const path = match[3];
+
+    // Only include paths that look like assets (contain _assets or relative paths to _assets)
+    if (path.includes('_assets') || path.includes('assets')) {
+      refs.push({
+        path,
+        start: match.index + match[1].length + match[2].length + 3, // Position of path start
+        end: match.index + match[0].length - 1, // Position before closing )
+        type: isImage ? 'image' : 'link',
+      });
+    }
+  }
+
+  return refs;
+}

package/src/fsml.js

@@ -0,0 +1,371 @@
+/**
+ * FSML module - Filesystem Markup Language utilities
+ *
+ * Handles path parsing, sorting, and navigation tree building
+ * according to FSML conventions.
+ *
+ * @module FSML
+ */
+
+/**
+ * Parse a relative path into FSML components
+ *
+ * @param {string} relativePath - Path relative to project root
+ * @returns {object} Parsed path information
+ *
+ * @example
+ * FSML.parsePath('02-getting-started/01-installation.md')
+ * // Returns {
+ * //   path: '02-getting-started/01-installation.md',
+ * //   order: 1,
+ * //   name: 'installation',
+ * //   title: 'Installation',
+ * //   extension: '.md',
+ * //   isFolder: false,
+ * //   isHidden: false,
+ * //   isSystem: false,
+ * //   depth: 1,
+ * //   parent: '02-getting-started'
+ * // }
+ */
+export function parsePath(relativePath) {
+  if (!relativePath) {
+    return {
+      path: '',
+      order: null,
+      name: '',
+      title: '',
+      extension: '',
+      isFolder: false,
+      isHidden: false,
+      isSystem: false,
+      depth: 0,
+      parent: '',
+    };
+  }
+
+  // Normalize path (remove trailing slash)
+  const path = relativePath.replace(/\/+$/, '');
+
+  // Get segments
+  const segments = path.split('/').filter(Boolean);
+  const depth = segments.length - 1;
+  const parent = segments.slice(0, -1).join('/');
+
+  // Get filename (last segment)
+  const filename = segments[segments.length - 1] || '';
+
+  // Check if it's a folder (no extension or explicitly ends with /)
+  const hasExtension = /\.[^./]+$/.test(filename);
+  const isFolder = !hasExtension;
+
+  // Get extension
+  const extMatch = filename.match(/(\.[^.]+)$/);
+  const extension = extMatch ? extMatch[1] : '';
+
+  // Get name without extension
+  const nameWithoutExt = filename.replace(/\.[^.]+$/, '');
+
+  // Parse numeric prefix (e.g., "01-" or "02_")
+  const prefixMatch = nameWithoutExt.match(/^(\d+)[-_]/);
+  const order = prefixMatch ? parseInt(prefixMatch[1], 10) : null;
+
+  // Get name without prefix
+  const name = prefixMatch ? nameWithoutExt.replace(/^\d+[-_]/, '') : nameWithoutExt;
+
+  // Derive title
+  const title = titleFromFilename(filename);
+
+  // Check hidden/system status based on first segment
+  const firstSegment = segments[0] || filename;
+  const isHidden = firstSegment.startsWith('_');
+  const isSystem = firstSegment.startsWith('.');
+
+  return {
+    path,
+    order,
+    name,
+    title,
+    extension,
+    isFolder,
+    isHidden,
+    isSystem,
+    depth,
+    parent,
+  };
+}
+
+/**
+ * Sort paths according to FSML rules
+ *
+ * Rules:
+ * 1. Numbered items first, in numeric order
+ * 2. Unnumbered items after, alphabetically
+ * 3. Folders and files interleaved by their order
+ *
+ * @param {string[]} paths - Array of relative paths
+ * @returns {string[]} Sorted paths
+ */
+export function sortPaths(paths) {
+  if (!paths || paths.length === 0) return [];
+
+  // Parse all paths
+  const parsed = paths.map(p => ({
+    path: p,
+    ...parsePath(p),
+  }));
+
+  // Sort function
+  return parsed
+    .sort((a, b) => {
+      // First, compare by parent path to keep hierarchy
+      const aParts = a.path.split('/');
+      const bParts = b.path.split('/');
+
+      // Compare common ancestor parts
+      const minLen = Math.min(aParts.length, bParts.length);
+
+      for (let i = 0; i < minLen; i++) {
+        const aPart = aParts[i];
+        const bPart = bParts[i];
+
+        if (aPart === bPart) continue;
+
+        // Parse parts for comparison
+        const aPartParsed = parsePath(aPart);
+        const bPartParsed = parsePath(bPart);
+
+        // Numbered items first
+        if (aPartParsed.order !== null && bPartParsed.order !== null) {
+          return aPartParsed.order - bPartParsed.order;
+        }
+        if (aPartParsed.order !== null) return -1;
+        if (bPartParsed.order !== null) return 1;
+
+        // Alphabetical for unnumbered
+        return aPart.localeCompare(bPart);
+      }
+
+      // Shorter paths (parents) come before longer paths (children) -- actually not, children should come after parent
+      return aParts.length - bParts.length;
+    })
+    .map(p => p.path);
+}
+
+/**
+ * Build a navigation tree from sorted paths
+ *
+ * @param {string[]} paths - Array of relative paths
+ * @returns {object[]} Navigation tree nodes
+ *
+ * @example
+ * FSML.buildNavTree(['01-intro.md', '02-methods/01-setup.md', '02-methods/02-analysis.md'])
+ * // Returns [
+ * //   { path: '01-intro.md', title: 'Intro', isFolder: false, children: [] },
+ * //   { path: '02-methods', title: 'Methods', isFolder: true, hasIndex: false, children: [...] }
+ * // ]
+ */
+export function buildNavTree(paths) {
+  if (!paths || paths.length === 0) return [];
+
+  // Filter out mrmd.md, hidden (_), and system (.) paths
+  const filtered = paths.filter(p => {
+    const parsed = parsePath(p);
+    if (parsed.isHidden || parsed.isSystem) return false;
+    // Exclude mrmd.md at root
+    if (p === 'mrmd.md') return false;
+    return true;
+  });
+
+  // Sort the paths
+  const sorted = sortPaths(filtered);
+
+  // Build folder structure first - collect all unique folders
+  const folders = new Map(); // folder path -> { hasIndex, children: [] }
+  const rootChildren = [];
+
+  // First pass: identify folders and track index.md
+  for (const path of sorted) {
+    const segments = path.split('/');
+
+    // Track folder hierarchy
+    for (let i = 0; i < segments.length - 1; i++) {
+      const folderPath = segments.slice(0, i + 1).join('/');
+      if (!folders.has(folderPath)) {
+        const parsed = parsePath(folderPath);
+        folders.set(folderPath, {
+          path: folderPath,
+          title: titleFromFilename(segments[i]),
+          order: parsed.order,
+          isFolder: true,
+          hasIndex: false,
+          children: [],
+        });
+      }
+    }
+
+    // Check if this is an index.md
+    const filename = segments[segments.length - 1];
+    if (filename === 'index.md' && segments.length > 1) {
+      const parentPath = segments.slice(0, -1).join('/');
+      if (folders.has(parentPath)) {
+        folders.get(parentPath).hasIndex = true;
+      }
+    }
+  }
+
+  // Second pass: build tree
+  for (const path of sorted) {
+    const segments = path.split('/');
+    const filename = segments[segments.length - 1];
+
+    // Skip index.md files (they're represented by the folder itself)
+    if (filename === 'index.md') continue;
+
+    const parsed = parsePath(path);
+
+    const node = {
+      path,
+      title: parsed.title,
+      order: parsed.order,
+      isFolder: false,
+      hasIndex: false,
+      children: [],
+    };
+
+    if (segments.length === 1) {
+      // Top-level file
+      rootChildren.push(node);
+    } else {
+      // File in a folder
+      const parentPath = segments.slice(0, -1).join('/');
+      if (folders.has(parentPath)) {
+        folders.get(parentPath).children.push(node);
+      }
+    }
+  }
+
+  // Third pass: add folders to tree
+  // Sort folders by depth (shallow first) to build hierarchy
+  const folderList = Array.from(folders.values());
+  folderList.sort((a, b) => a.path.split('/').length - b.path.split('/').length);
+
+  for (const folder of folderList) {
+    const segments = folder.path.split('/');
+
+    if (segments.length === 1) {
+      // Top-level folder
+      rootChildren.push(folder);
+    } else {
+      // Nested folder
+      const parentPath = segments.slice(0, -1).join('/');
+      if (folders.has(parentPath)) {
+        folders.get(parentPath).children.push(folder);
+      }
+    }
+  }
+
+  // Sort root children
+  rootChildren.sort((a, b) => {
+    if (a.order !== null && b.order !== null) return a.order - b.order;
+    if (a.order !== null) return -1;
+    if (b.order !== null) return 1;
+    return a.title.localeCompare(b.title);
+  });
+
+  // Sort children of each folder
+  for (const folder of folders.values()) {
+    folder.children.sort((a, b) => {
+      if (a.order !== null && b.order !== null) return a.order - b.order;
+      if (a.order !== null) return -1;
+      if (b.order !== null) return 1;
+      return a.title.localeCompare(b.title);
+    });
+  }
+
+  return rootChildren;
+}
+
+/**
+ * Derive a human-readable title from a filename
+ *
+ * @param {string} filename - Filename (with or without extension)
+ * @returns {string} Human-readable title
+ *
+ * @example
+ * FSML.titleFromFilename('01-getting-started.md') // 'Getting Started'
+ * FSML.titleFromFilename('my_cool_doc.md')        // 'My Cool Doc'
+ */
+export function titleFromFilename(filename) {
+  if (!filename) return '';
+
+  // Remove extension
+  let name = filename.replace(/\.[^.]+$/, '');
+
+  // Remove numeric prefix (e.g., "01-" or "02_")
+  name = name.replace(/^\d+-/, '');
+
+  // Replace hyphens and underscores with spaces
+  name = name.replace(/[-_]/g, ' ');
+
+  // Title case: capitalize first letter of each word
+  name = name
+    .split(' ')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+
+  return name;
+}
+
+/**
+ * Compute new paths when reordering files
+ *
+ * @param {string} sourcePath - Path being moved
+ * @param {string} targetPath - Path to move relative to
+ * @param {'before' | 'after' | 'inside'} position - Where to place
+ * @returns {object} New path and required renames
+ */
+export function computeNewPath(sourcePath, targetPath, position) {
+  const source = parsePath(sourcePath);
+  const target = parsePath(targetPath);
+
+  // Get target directory
+  let targetDir = '';
+  if (position === 'inside') {
+    // Moving inside a folder
+    targetDir = targetPath;
+  } else {
+    // Moving before/after a file or folder
+    targetDir = target.parent;
+  }
+
+  // Determine the new order number
+  let newOrder;
+  if (position === 'before') {
+    // Take the target's order
+    newOrder = target.order || 1;
+  } else if (position === 'after') {
+    newOrder = (target.order || 0) + 1;
+  } else {
+    // Inside: use order 1
+    newOrder = 1;
+  }
+
+  // Build new filename
+  const paddedOrder = String(newOrder).padStart(2, '0');
+  const newFilename = `${paddedOrder}-${source.name}${source.extension}`;
+  const newPath = targetDir ? `${targetDir}/${newFilename}` : newFilename;
+
+  // Calculate renames needed (simplified - just returns the main rename)
+  const renames = [];
+
+  // The source file rename
+  if (sourcePath !== newPath) {
+    renames.push({ from: sourcePath, to: newPath });
+  }
+
+  return {
+    newPath,
+    renames,
+  };
+}

package/src/index.js

@@ -0,0 +1,65 @@
+/**
+ * mrmd-project
+ *
+ * Pure logic for understanding mrmd project structure and conventions.
+ *
+ * This package has NO side effects - no file I/O, no process spawning.
+ * All functions are pure: same input → same output.
+ *
+ * @example
+ * import { Project, FSML, Links, Assets, Scaffold, Search } from 'mrmd-project';
+ *
+ * // Find and parse project
+ * const root = Project.findRoot('/path/to/file.md', hasFile);
+ * const config = Project.parseConfig(mrmdMdContent);
+ *
+ * // Build navigation tree
+ * const tree = FSML.buildNavTree(files);
+ *
+ * // Resolve internal links
+ * const resolved = Links.resolve('installation', 'index.md', projectFiles);
+ *
+ * // Compute asset paths
+ * const relativePath = Assets.computeRelativePath('chapter/doc.md', '_assets/img.png');
+ *
+ * // Generate scaffolding
+ * const scaffold = Scaffold.project('my-project');
+ *
+ * // Fuzzy search
+ * const results = Search.files('thesis readme', allFiles);
+ */
+
+// Project configuration
+export * as Project from './project.js';
+
+// Filesystem Markup Language
+export * as FSML from './fsml.js';
+
+// Internal links
+export * as Links from './links.js';
+
+// Asset management
+export * as Assets from './assets.js';
+
+// Scaffolding templates
+export * as Scaffold from './scaffold.js';
+
+// Search utilities
+export * as Search from './search.js';
+
+// Re-export everything as default for convenience
+import * as Project from './project.js';
+import * as FSML from './fsml.js';
+import * as Links from './links.js';
+import * as Assets from './assets.js';
+import * as Scaffold from './scaffold.js';
+import * as Search from './search.js';
+
+export default {
+  Project,
+  FSML,
+  Links,
+  Assets,
+  Scaffold,
+  Search,
+};