comment-block-replacer 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# comment-block-replacer
+
+Process files with comment block replacements using markdown-magic transforms.
+
+## Installation
+
+```bash
+npm install comment-block-replacer
+```
+
+## Usage
+
+The comment block replacer allows you to process files (both from file paths and content strings) with comment block transforms, applying configured transforms to update content within delimited blocks.
+
+### Basic Usage
+
+```javascript
+const { processFile } = require('comment-block-replacer')
+
+// Process file content directly
+const result = await processFile({
+  content: `
+<!-- DOCS:START example -->
+Some content to transform
+<!-- DOCS:END -->
+  `,
+  dryRun: true,
+  transforms: {
+    example: (api) => {
+      return api.content.toUpperCase()
+    }
+  }
+})
+
+console.log(result.updatedContents)
+// Output: Content will be transformed to uppercase
+```
+
+### Processing Files from Path
+
+```javascript
+const { processFile } = require('comment-block-replacer')
+
+const result = await processFile({
+  srcPath: './docs/README.md',
+  outputPath: './output/README.md',
+  transforms: {
+    wordcount: (api) => {
+      const words = api.content.trim().split(/\s+/).length
+      return `Word count: ${words}`
+    }
+  }
+})
+```
+
+### File Processing Options
+
+```javascript
+const { processFile } = require('comment-block-replacer')
+
+const result = await processFile({
+  srcPath: './src/example.md',
+  outputPath: './dist/example.md',
+  dryRun: false,                    // Set to true to preview changes without writing
+  applyTransformsToSource: true,    // Also update the source file
+  syntax: 'md',                     // Override detected syntax
+  transforms: {
+    uppercase: (api) => api.content.toUpperCase(),
+    file: (api) => `Content from ${api.options.src}`
+  }
+})
+```
+
+### Output Directory Configuration
+
+```javascript
+const result = await processFile({
+  content: 'File content...',
+  outputPath: './dist/processed.md',
+  output: {
+    directory: './dist'    // Output directory
+  },
+  outputDir: './dist',     // Legacy option (same as output.directory)
+  transforms: { /* ... */ }
+})
+```
+
+### Comment Pattern Stripping
+
+```javascript
+const result = await processFile({
+  srcPath: './docs/source.md',
+  outputPath: './dist/clean.md',
+  removeComments: true,
+  patterns: {
+    openPattern: /<!-- DOCS:START .* -->/g,
+    closePattern: /<!-- DOCS:END -->/g
+  },
+  transforms: { /* ... */ }
+})
+```
+
+## API Reference
+
+### processFile(options)
+
+Process a file with comment block replacements using configured transforms.
+
+#### Parameters
+
+- `options` (ProcessFileOptions): Processing configuration options
+
+#### Returns
+
+Promise<ProcessFileResult> - Result object with processed content and metadata
+
+### ProcessFileOptions
+
+Configuration object for processing files.
+
+```typescript
+interface ProcessFileOptions {
+  content?: string                    // File content as string (mutually exclusive with srcPath)
+  srcPath?: string                   // Source file path (mutually exclusive with content)  
+  syntax?: string                    // File syntax type (e.g., 'md', 'js', 'html')
+  outputPath?: string                // Output file path for processed content
+  dryRun?: boolean                   // If true, process but don't write files (default: false)
+  patterns?: {                       // Comment patterns for stripping
+    openPattern?: RegExp             // Opening comment pattern regex
+    closePattern?: RegExp            // Closing comment pattern regex
+  }
+  output?: {                         // Output configuration
+    directory?: string               // Output directory path
+  }
+  outputDir?: string                 // Legacy output directory option
+  applyTransformsToSource?: boolean  // Apply transforms to source file (default: false)
+  transforms?: object                // Transform functions to apply to blocks
+  beforeMiddleware?: Array           // Middleware to run before transforms
+  afterMiddleware?: Array            // Middleware to run after transforms
+  removeComments?: boolean           // Remove comment blocks from output (default: false)
+  open?: string                      // Opening delimiter for comment blocks
+  close?: string                     // Closing delimiter for comment blocks
+}
+```
+
+### ProcessFileResult
+
+Result object returned by processFile:
+
+```typescript
+interface ProcessFileResult {
+  isChanged: boolean           // Whether the content was modified
+  isNewPath: boolean          // Whether srcPath differs from outputPath
+  stripComments: boolean      // Whether comments should be stripped from output
+  srcPath?: string            // Source file path used
+  outputPath?: string         // Output file path used
+  transforms: Array           // Array of transforms that were applied
+  missingTransforms: Array    // Array of transforms that were not found
+  originalContents: string    // Original input content
+  updatedContents: string     // Processed output content
+}
+```
+
+## Transform Function API
+
+Transform functions receive an API object with the following properties:
+
+```typescript
+interface TransformApi {
+  transform: string              // Name of the transform
+  content: string               // Content to transform
+  options: object               // Transform options
+  srcPath?: string              // Source file path
+  outputPath?: string           // Output file path
+  settings: object              // Additional settings including regex patterns
+  currentContent: string        // Current file contents
+  originalContent: string       // Original file contents
+  getCurrentContent(): string   // Function to get current file contents
+  getOriginalContent(): string  // Function to get original file contents
+  getOriginalBlock(): object    // Function to get the original block data
+  getBlockDetails(content?: string): object // Function to get detailed block information
+}
+```
+
+## Examples
+
+### Multiple Transform Types
+
+```javascript
+const { processFile } = require('comment-block-replacer')
+
+const result = await processFile({
+  srcPath: './docs/api.md',
+  transforms: {
+    toc: (api) => generateTableOfContents(api.currentContent),
+    wordcount: (api) => `Words: ${api.content.trim().split(/\s+/).length}`,
+    file: (api) => fs.readFileSync(api.options.src, 'utf8'),
+    code: (api) => {
+      const code = fs.readFileSync(api.options.src, 'utf8')
+      return `\`\`\`${api.options.lang || 'javascript'}\n${code}\n\`\`\``
+    }
+  }
+})
+```
+
+### Syntax Detection
+
+The processor automatically detects file syntax from the file extension:
+
+```javascript
+// JavaScript files (.js)
+await processFile({
+  srcPath: './src/example.js',  // Syntax: 'js'
+  // Uses // comment blocks by default
+})
+
+// Markdown files (.md)
+await processFile({
+  srcPath: './docs/readme.md',  // Syntax: 'md' 
+  // Uses <!-- --> comment blocks by default
+})
+
+// Override syntax detection
+await processFile({
+  srcPath: './config.json',
+  syntax: 'js',  // Force JavaScript syntax
+})
+```
+
+## Error Handling
+
+```javascript
+try {
+  const result = await processFile({
+    srcPath: './docs/file.md',
+    content: 'content string', // Error: can't use both
+    transforms: {}
+  })
+} catch (error) {
+  console.error('Processing failed:', error.message)
+  // "Can't set both "srcPath" & "content""
+}
+```
+
+## Testing
+
+The package uses [uvu](https://github.com/lukeed/uvu) for testing:
+
+```bash
+npm test
+```
+
+## TypeScript Support
+
+This package includes TypeScript declarations. The types are automatically generated from JSDoc comments.
+
+```bash
+npm run build
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "comment-block-replacer",
+  "version": "0.1.0",
+  "description": "Process files with comment block replacements",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "dependencies": {
+    "is-valid-path": "^0.1.1",
+    "comment-block-transformer": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "uvu": "^0.5.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "uvu test",
+    "build": "pnpm run types",
+    "types": "tsc --emitDeclarationOnly --outDir types",
+    "clean": "rimraf types",
+    "release:patch": "pnpm run build && pnpm version patch && pnpm publish",
+    "release:minor": "pnpm run build && pnpm version minor && pnpm publish",
+    "release:major": "pnpm run build && pnpm version major && pnpm publish"
+  }
+}

package/src/index.js

@@ -0,0 +1,137 @@
+const path = require('path')
+const fs = require('fs').promises
+const isValidFile = require('is-valid-path')
+const { blockTransformer } = require('comment-block-transformer')
+
+/**
+ * @typedef {import('comment-block-transformer').ProcessContentConfig} ProcessContentConfig
+ */
+
+/**
+ * @typedef {import('comment-block-transformer').ProcessContentResult} ProcessContentResult
+ */
+
+/**
+ * Extended configuration for processing files with additional file-specific options
+ * @typedef {ProcessContentConfig & {
+ *   content?: string
+ *   srcPath?: string
+ *   outputPath?: string
+ *   dryRun?: boolean
+ *   patterns?: {
+ *     openPattern?: RegExp
+ *     closePattern?: RegExp
+ *   }
+ *   output?: {
+ *     directory?: string
+ *   }
+ *   outputDir?: string
+ *   applyTransformsToSource?: boolean
+ *   open?: string
+ *   close?: string
+ * }} ProcessFileOptions
+ */
+
+/**
+ * Result of processing a file with comment block replacements
+ * @typedef {Object} ProcessFileResult
+ * @property {boolean} isChanged - Whether the content was modified
+ * @property {boolean} isNewPath - Whether srcPath differs from outputPath
+ * @property {boolean} stripComments - Whether comments should be stripped from output
+ * @property {string} [srcPath] - Source file path used
+ * @property {string} [outputPath] - Output file path used
+ * @property {Array} transforms - Array of transforms that were applied
+ * @property {Array} missingTransforms - Array of transforms that were not found
+ * @property {string} originalContents - Original input content
+ * @property {string} updatedContents - Processed output content
+ */
+
+/**
+ * Write file with directory creation if needed
+ * @param {string} filePath - File path to write to
+ * @param {string} content - Content to write
+ * @returns {Promise<void>}
+ */
+async function writeFile(filePath, content) {
+  try {
+    await fs.writeFile(filePath, content)
+  } catch(e) {
+    const dirName = path.dirname(filePath)
+    await fs.mkdir(dirName, { recursive: true })
+    await fs.writeFile(filePath, content)
+  }
+}
+
+/**
+ * Read file content
+ * @param {string} filePath - File path to read from
+ * @param {string} [encoding='utf8'] - File encoding
+ * @returns {Promise<string>} File content
+ */
+async function readFile(filePath, encoding = 'utf8') {
+  return fs.readFile(filePath, encoding)
+}
+
+/**
+ * Process a file with comment block replacements using configured transforms
+ * @param {ProcessFileOptions} [opts={}] - Processing options
+ * @returns {Promise<ProcessContentResult>} Result object with processed content and metadata
+ */
+async function processFile(opts = {}) {
+  const { content, syntax, outputPath, dryRun, patterns, output = {}, applyTransformsToSource } = opts
+  const outputDir = output.directory || opts.outputDir
+
+  let srcPath = opts.srcPath
+  if (srcPath && content) {
+    throw new Error(`Can't set both "srcPath" & "content"`)
+  }
+  let fileContents
+  if (content) {
+    const isFile = isValidFile(content) && content.indexOf('\n') === -1
+    srcPath = (isFile) ? content : undefined
+    fileContents = (!isFile) ? content : undefined
+  }
+
+  if (!fileContents) {
+    fileContents = await readFile(srcPath || content, 'utf8')
+  }
+  
+  let syntaxType = syntax
+  if (srcPath && !syntaxType) {
+    const ext = path.extname(srcPath).replace(/^\./, '')
+    if (ext === 'js') syntaxType = 'js'
+    else if (ext === 'md') syntaxType = 'md'
+    else syntaxType = ext || 'md'
+  }
+
+  const result = await blockTransformer(fileContents, {
+    ...opts,
+    outputPath,
+    srcPath,
+    syntax: syntaxType,
+  })
+
+  // console.log('resultFromBlockTransformer', result)
+
+  if (dryRun) {
+    return result
+  }
+
+  if (outputPath && (result.isChanged || result.isNewPath)) {
+    let cleanContents = result.updatedContents
+    if (result.stripComments && result.patterns.openPattern && result.patterns.closePattern) {
+      cleanContents = result.updatedContents.replace(result.patterns.openPattern, '').replace(result.patterns.closePattern, '')
+    }
+    await writeFile(outputPath, cleanContents)
+  }
+
+  if (applyTransformsToSource && srcPath && result.isChanged) {
+    await writeFile(srcPath, result.updatedContents)
+  }
+
+  return result
+}
+
+module.exports = {
+  processFile
+}

package/test/index.test.js

@@ -0,0 +1,271 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const path = require('path')
+const fs = require('fs').promises
+const { processFile } = require('../src')
+
+/**
+ * @typedef {import('../src').ProcessFileOptions} ProcessFileOptions
+ */
+
+// Create temporary test files for testing
+const testDir = path.join(__dirname, 'temp')
+const testFile = path.join(testDir, 'test.md')
+const outputFile = path.join(testDir, 'output.md')
+
+// Setup and cleanup
+async function setup() {
+  try {
+    await fs.mkdir(testDir, { recursive: true })
+  } catch (e) {
+    // Directory might already exist
+  }
+}
+
+async function cleanup() {
+  try {
+    // @ts-ignore
+    await fs.rm(testDir, { recursive: true })
+  } catch (e) {
+    // Directory might not exist or not be empty
+  }
+}
+
+// Mock transforms for testing
+const mockTransforms = {
+  uppercase: (api) => {
+    return api.content.toUpperCase()
+  },
+  wordcount: (api) => {
+    const words = api.content.trim().split(/\s+/).length
+    return `Word count: ${words}`
+  },
+  file: (api) => {
+    return `Content from ${api.options.src || 'unknown file'}`
+  }
+}
+
+test.before(setup)
+test.after(cleanup)
+
+test('should process file content with transforms', async () => {
+  const content = `
+# Test Document
+
+<!-- DOCS:START uppercase -->
+hello world
+<!-- DOCS:END -->
+
+Some other content.
+  `
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    content,
+    dryRun: true,
+    transforms: mockTransforms
+  }
+
+  const result = await processFile(options)
+  
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('HELLO WORLD'))
+  assert.is(result.transforms.length, 1)
+})
+
+test('should process file from path', async () => {
+  const content = `
+# Test File
+
+<!-- DOCS:START wordcount -->
+This is a test document with multiple words to count.
+<!-- DOCS:END -->
+  `
+  
+  await fs.writeFile(testFile, content)
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    srcPath: testFile,
+    dryRun: true,
+    transforms: mockTransforms
+  }
+
+  const result = await processFile(options)
+  
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('Word count: 10'))
+})
+
+test('should write to output file when not dry run', async () => {
+  const content = `
+<!-- DOCS:START uppercase -->
+test content
+<!-- DOCS:END -->
+  `
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    content,
+    outputPath: outputFile,
+    transforms: mockTransforms
+  }
+
+  const result = await processFile(options)
+
+  console.log('result', result)
+  assert.is(result.isChanged, true, 'isChanged')
+  assert.is(result.isNewPath, true, 'isNewPath')
+  
+  // Check output file was created
+  const outputContent = await fs.readFile(outputFile, 'utf8')
+  assert.ok(outputContent.includes('TEST CONTENT'))
+})
+
+test('should apply transforms to source file when applyTransformsToSource is true', async () => {
+  const content = `
+<!-- DOCS:START uppercase -->
+source content
+<!-- DOCS:END -->
+  `
+  
+  await fs.writeFile(testFile, content)
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    srcPath: testFile,
+    applyTransformsToSource: true,
+    transforms: mockTransforms
+  }
+
+  const result = await processFile(options)
+  
+  assert.is(result.isChanged, true)
+  
+  // Check source file was updated
+  const updatedContent = await fs.readFile(testFile, 'utf8')
+  assert.ok(updatedContent.includes('SOURCE CONTENT'))
+})
+
+test('should detect syntax from file extension', async () => {
+  const jsFile = path.join(testDir, 'test.js')
+  const content = `
+/* DOCS:START uppercase */
+const test = 'hello world'
+/* DOCS:END */
+  `
+  
+  await fs.writeFile(jsFile, content)
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    srcPath: jsFile,
+    dryRun: true,
+    open: 'DOCS:START',
+    close: 'DOCS:END',
+    transforms: mockTransforms
+  }
+
+  const result = await processFile(options)
+  
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes(`CONST TEST = 'HELLO WORLD'`))
+})
+
+test('should handle missing transforms', async () => {
+  const content = `
+<!-- DOCS:START nonexistent -->
+test content
+<!-- DOCS:END -->
+  `
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    content,
+    dryRun: true,
+    transforms: {}
+  }
+
+  const result = await processFile(options)
+  
+  assert.is(result.missingTransforms.length, 1)
+  assert.is(result.isChanged, false)
+})
+
+test('should handle both srcPath and content error', async () => {
+  /** @type {ProcessFileOptions} */
+  const options = {
+    srcPath: '/some/path',
+    content: 'some content',
+    dryRun: true
+  }
+
+  try {
+    await processFile(options)
+    assert.unreachable('Should have thrown an error')
+  } catch (error) {
+    assert.ok(error.message.includes('Can\'t set both "srcPath" & "content"'))
+  }
+})
+
+test('should handle file with output directory', async () => {
+  const content = `
+<!-- DOCS:START uppercase -->
+directory test
+<!-- DOCS:END -->
+  `
+  
+  const outputDir = path.join(testDir, 'output')
+  const expectedOutput = path.join(outputDir, 'result.md')
+
+  /** @type {ProcessFileOptions} */
+  const options = {
+    content,
+    outputPath: expectedOutput,
+    output: {
+      directory: outputDir
+    },
+    transforms: mockTransforms
+  }
+
+  const result = await processFile(options)
+  
+  assert.is(result.isChanged, true)
+  
+  // Check output file exists in output directory
+  const outputContent = await fs.readFile(expectedOutput, 'utf8')
+  assert.ok(outputContent.includes('DIRECTORY TEST'))
+})
+
+test('Custom patterns', async () => {
+  const content = `
+TotallyCustom uppercase
+content with comments
+BlockHere
+  `
+  
+  /** @type {ProcessFileOptions} */
+  const options = {
+    content,
+    outputPath: outputFile,
+    removeComments: true,
+    customPatterns: {
+      openPattern: /TotallyCustom (.*)/g,
+      closePattern: /BlockHere/g,
+    },
+    transforms: Object.assign({}, mockTransforms, {
+      custom: (api) => {
+        return api.content.toUpperCase()
+      }
+    })
+  }
+
+  const result = await processFile(options)
+
+  console.log('result', result)
+  
+  assert.is(result.stripComments, true)
+  assert.is(result.isNewPath, true)
+})
+
+test.run()

package/test-manual.js

@@ -0,0 +1,38 @@
+const { processFile } = require('./src')
+
+async function testBasic() {
+  console.log('Testing basic functionality...')
+  
+  const content = `
+# Test Document
+
+<!-- DOCS:START uppercase -->
+hello world
+<!-- DOCS:END -->
+
+Some other content.
+  `
+
+  const options = {
+    content,
+    dryRun: true,
+    transforms: {
+      uppercase: (api) => {
+        return api.content.toUpperCase()
+      }
+    }
+  }
+
+  try {
+    const result = await processFile(options)
+    console.log('✅ Test passed!')
+    console.log('isChanged:', result.isChanged)
+    console.log('transforms applied:', result.transforms.length)
+    console.log('Updated content contains HELLO WORLD:', result.updatedContents.includes('HELLO WORLD'))
+  } catch (error) {
+    console.error('❌ Test failed:', error.message)
+    console.error(error.stack)
+  }
+}
+
+testBasic()

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "strict": false,
+    "noImplicitAny": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "test", "types"]
+}

package/types/index.d.ts

@@ -0,0 +1,69 @@
+export type ProcessContentConfig = import("comment-block-transformer").ProcessContentConfig;
+export type ProcessContentResult = import("comment-block-transformer").ProcessContentResult;
+/**
+ * Extended configuration for processing files with additional file-specific options
+ */
+export type ProcessFileOptions = ProcessContentConfig & {
+    content?: string;
+    srcPath?: string;
+    outputPath?: string;
+    dryRun?: boolean;
+    patterns?: {
+        openPattern?: RegExp;
+        closePattern?: RegExp;
+    };
+    output?: {
+        directory?: string;
+    };
+    outputDir?: string;
+    applyTransformsToSource?: boolean;
+    open?: string;
+    close?: string;
+};
+/**
+ * Result of processing a file with comment block replacements
+ */
+export type ProcessFileResult = {
+    /**
+     * - Whether the content was modified
+     */
+    isChanged: boolean;
+    /**
+     * - Whether srcPath differs from outputPath
+     */
+    isNewPath: boolean;
+    /**
+     * - Whether comments should be stripped from output
+     */
+    stripComments: boolean;
+    /**
+     * - Source file path used
+     */
+    srcPath?: string;
+    /**
+     * - Output file path used
+     */
+    outputPath?: string;
+    /**
+     * - Array of transforms that were applied
+     */
+    transforms: any[];
+    /**
+     * - Array of transforms that were not found
+     */
+    missingTransforms: any[];
+    /**
+     * - Original input content
+     */
+    originalContents: string;
+    /**
+     * - Processed output content
+     */
+    updatedContents: string;
+};
+/**
+ * Process a file with comment block replacements using configured transforms
+ * @param {ProcessFileOptions} [opts={}] - Processing options
+ * @returns {Promise<ProcessContentResult>} Result object with processed content and metadata
+ */
+export function processFile(opts?: ProcessFileOptions): Promise<ProcessContentResult>;