feat: implement comprehensive programmatic API with TypeDoc documentation #3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add src/index.ts with full library exports and convenience functions
- Export all core classes: FileOperations, LinkParser, LinkRefactorer, etc.
- Export all strategy classes and utility functions
- Export comprehensive TypeScript types for all operations
- Add createMarkMv() factory function for easy instantiation
- Add moveFile() and moveFiles() convenience functions
- Add validateOperation() helper for result validation
- Fix empty moves array handling in FileOperations.moveFiles()
- Add proper package.json exports configuration with types
- Create comprehensive test suite for programmatic API (14 tests)
- Add JavaScript and TypeScript usage examples
- Update package.json keywords for better discoverability
- Include examples in published package files
This enables developers to use markmv as a library:
import { createMarkMv, moveFile, FileOperations } from 'markmv';
Breaking changes: None - maintains full backward compatibility
- Add PathUtils.resolveDestination() to handle directory destinations
- Add PathUtils.isDirectory() and PathUtils.looksLikeDirectory() helpers
- Update FileOperations.moveFile() to resolve directory destinations
- Update FileOperations.moveFiles() to handle batch directory moves
- Fix empty moves array handling in moveFiles() method
- Add comprehensive test suite (16 tests) for directory move support
- Support CLI patterns: 'markmv move file.md dir/' and 'markmv move file.md dir'
- Support programmatic API: moveFile('file.md', './target/')
Examples now supported:
- markmv move foo.md ../ (preserves filename: ../foo.md)
- markmv move doc.md ./docs/ (creates: ./docs/doc.md)
- moveFile('test.md', targetDir) (API support)
All 234 tests passing, maintains full backward compatibility
- Support multiple source files: markmv move file1.md file2.md ./target/ - Support glob patterns: markmv move '*.md' ./target/ - Support recursive globs: markmv move '**/*.md' ./archive/ - Support mixed patterns: markmv move file.md 'docs/*.md' ./target/ - Add intelligent destination validation for batch moves - Add comprehensive glob expansion with markdown file filtering - Add proper error handling for invalid destination types - Add verbose output showing pattern expansion and file discovery - Add 11 comprehensive tests for glob functionality - Maintain full backward compatibility with single file moves Examples now supported: - markmv move '*.md' ./archive/ # Simple glob - markmv move '**/*.md' ./archive/ # Recursive glob - markmv move docs/*.md guides/*.md ./archive/ # Multiple patterns - markmv move file1.md 'src/**/*.md' ./backup/ # Mixed patterns All 245 tests passing, zero regressions
- Add TypeDoc v0.28.5 and missing exports plugin v4.0.0 as dev dependencies - Add npm scripts for documentation: docs, docs:serve, docs:watch - Prepare foundation for comprehensive API documentation
- Add typedoc.json with GitHub integration and categorized output - Configure source linking to GitHub repository with line numbers - Add custom CSS theme for enhanced documentation styling - Enable missing exports plugin for complete API coverage - Set up validation and search capabilities
- Add detailed class-level documentation with usage examples - Document FileOperations with move operation examples and dry run patterns - Document LinkParser with parsing and validation examples - Document PathUtils with path resolution and relative path update examples - Include category annotations for TypeDoc organization - Provide practical code examples for each major method
- Create automated docs.yml workflow for TypeDoc generation - Configure build job with Node.js 18 and npm ci installation - Set up GitHub Pages deployment with proper permissions - Deploy documentation to GitHub Pages on main branch pushes - Include build artifact upload for GitHub Pages integration
- Exclude TypeDoc generated documentation from version control - Prevent committing build artifacts that are deployed via GitHub Actions - Keep repository clean by ignoring generated HTML documentation files
- Add Library Usage section with programmatic API examples - Include TypeScript code examples for FileOperations, moveFile, and glob patterns - Update Getting Help section with link to hosted API documentation - Replace generic documentation links with specific TypeDoc documentation URL - Provide practical examples for dry runs, directory moves, and validation
- Replace forEach with for...of loop for better performance - Add explicit type annotation to result variable to prevent implicit any - Maintain code quality standards with Biome linter
- Import OperationResult type from operations module - Resolve TypeScript compilation error - Ensure proper type checking for result variable
There was a problem hiding this comment.
Pull Request Overview
Implements a full programmatic API for markmv with TypeDoc docs and enhances the CLI to support directories and glob patterns.
- Adds
typedoc.jsonand a custom CSS theme for automated API documentation. - Introduces
PathUtilshelpers and exports acreateMarkMv,moveFile,moveFiles, andvalidateOperationAPI insrc/index.ts. - Updates
FileOperationsand themovecommand to handle directory targets and glob expansions.
Reviewed Changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| typedoc.json | Configures TypeDoc entry points, categories, and validation rules |
| typedoc-theme.css | Defines custom CSS variables and styling for the docs |
| src/utils/path-utils.ts | Adds path resolution and directory-detection utilities |
| src/core/file-operations.ts | Integrates directory support by resolving destinations |
| src/commands/move.ts | Implements glob expansion and batch-move logic for the CLI |
| src/index.ts | Exposes the new programmatic API entry points |
Comments suppressed due to low confidence (2)
src/commands/move.ts:26
- PathUtils.isMarkdownFile is used here but not implemented in PathUtils; either add a static isMarkdownFile method (e.g. checking extname against known markdown extensions) or use the existing FileUtils.isMarkdownFile.
if (PathUtils.isMarkdownFile(pattern)) {
src/core/file-operations.ts:95
- PathUtils is referenced here but not imported; add
import { PathUtils } from '../utils/path-utils.js';at the top of the file.
const resolvedDestination = PathUtils.resolveDestination(sourcePath, destinationPath);
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR implements a comprehensive programmatic API for markmv, adding TypeDoc documentation and enhancing CLI functionality with directory and glob support.
🚀 New Features
Programmatic API:
src/index.tswith TypeScript supportcreateMarkMv(),moveFile(),moveFiles(),validateOperation()Enhanced CLI:
markmv move file.md ../target/markmv move '**/*.md' ./archive/TypeDoc Documentation:
🔧 Technical Improvements
✅ Test Coverage
📚 Documentation
🔄 Migration
No breaking changes - this is a purely additive release that enhances existing functionality while maintaining full CLI compatibility.
Test Plan
Related Issues
Closes programmatic API implementation requirements and completes TypeDoc documentation phase.