tessl/npm-compodoc--compodoc

The missing documentation tool for your Angular application

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

File Engine

Name: tessl/npm-compodoc--compodoc
Author: tessl

The File Engine provides file system operations and utilities for reading and writing documentation files.

Capabilities

FileEngine Class

Singleton class providing file system operations for documentation generation.

/**
 * File system operations engine
 * Uses singleton pattern - access via FileEngine.getInstance() or default export
 */
class FileEngine {
  /**
   * Get singleton instance of FileEngine
   * @returns FileEngine instance
   */
  static getInstance(): FileEngine;
  
  /**
   * Read file asynchronously
   * @param filepath - Path to file to read
   * @returns Promise resolving to file contents as string
   */
  get(filepath: string): Promise<string>;
  
  /**
   * Read file synchronously
   * @param filepath - Path to file to read
   * @returns File contents as string
   */
  getSync(filepath: string): string;
  
  /**
   * Write file asynchronously
   * @param filepath - Path to file to write
   * @param contents - Content to write to file
   * @returns Promise resolving when write is complete
   */
  write(filepath: string, contents: string): Promise<void>;
  
  /**
   * Write file synchronously
   * @param filepath - Path to file to write
   * @param contents - Content to write to file
   */
  writeSync(filepath: string, contents: string): void;
  
  /**
   * Check if file exists synchronously  
   * @param filepath - Path to file to check
   * @returns True if file exists
   */
  existsSync(filepath: string): boolean;
}

Usage Examples:

import FileEngine from "@compodoc/compodoc";

// Read file asynchronously
const content = await FileEngine.get("./README.md");
console.log(content);

// Read file synchronously
const packageJson = FileEngine.getSync("./package.json");
const package = JSON.parse(packageJson);

// Write file asynchronously
await FileEngine.write("./output/index.html", "<html>...</html>");

// Write file synchronously
FileEngine.writeSync("./output/data.json", JSON.stringify(data));

// Check if file exists
if (FileEngine.existsSync("./tsconfig.json")) {
  console.log("TypeScript config found");
}

File Operations

Core file system operations provided by the File Engine.

/**
 * Read operations for accessing file content
 */
interface ReadOperations {
  /**
   * Asynchronous file reading
   * @param filepath - Absolute or relative path to file
   * @returns Promise<string> with file contents
   * @throws Error if file cannot be read
   */
  get(filepath: string): Promise<string>;
  
  /**
   * Synchronous file reading
   * @param filepath - Absolute or relative path to file  
   * @returns string with file contents
   * @throws Error if file cannot be read
   */
  getSync(filepath: string): string;
}

/**
 * Write operations for creating/updating files
 */
interface WriteOperations {
  /**
   * Asynchronous file writing
   * @param filepath - Absolute or relative path for output file
   * @param contents - String content to write
   * @returns Promise<void> resolving when write completes
   * @throws Error if file cannot be written
   */
  write(filepath: string, contents: string): Promise<void>;
  
  /**
   * Synchronous file writing
   * @param filepath - Absolute or relative path for output file
   * @param contents - String content to write
   * @throws Error if file cannot be written
   */
  writeSync(filepath: string, contents: string): void;
}

/**
 * File system utilities
 */
interface FileSystemUtilities {
  /**
   * Synchronous file existence check
   * @param filepath - Path to check
   * @returns boolean indicating if file exists
   */
  existsSync(filepath: string): boolean;
}

Error Handling

Error handling patterns for file operations.

/**
 * File operation error types
 */
interface FileEngineErrors {
  /**
   * File not found error
   */
  ENOENT: "File or directory not found";
  
  /**
   * Permission denied error
   */
  EACCES: "Permission denied";
  
  /**
   * Invalid file path error
   */
  EINVAL: "Invalid file path";
  
  /**
   * Disk full error
   */
  ENOSPC: "No space left on device";
}

Usage Examples:

// Error handling with async operations
try {
  const content = await FileEngine.get("./missing-file.txt");
} catch (error) {
  if (error.code === 'ENOENT') {
    console.log("File not found");
  } else {
    console.error("Unexpected error:", error);
  }
}

// Error handling with sync operations
try {
  const content = FileEngine.getSync("./config.json");
  return JSON.parse(content);
} catch (error) {
  console.error("Failed to read config:", error.message);
  return {};
}

// Safe file existence check before operations
if (FileEngine.existsSync("./optional-config.json")) {
  const config = await FileEngine.get("./optional-config.json");
  // Process config
}

Common File Patterns

Common patterns used by Compodoc for file operations.

/**
 * Common file reading patterns used in Compodoc
 */
interface CommonFilePatterns {
  /**
   * Read and parse JSON file
   * @param filepath - Path to JSON file
   * @returns Parsed JSON object
   */
  readJson(filepath: string): Promise<any>;
  
  /**
   * Read and parse JSON file synchronously
   * @param filepath - Path to JSON file
   * @returns Parsed JSON object
   */
  readJsonSync(filepath: string): any;
  
  /**
   * Write JSON data to file
   * @param filepath - Output file path
   * @param data - Data to stringify and write
   * @returns Promise resolving when complete
   */
  writeJson(filepath: string, data: any): Promise<void>;
  
  /**
   * Read markdown file
   * @param filepath - Path to markdown file
   * @returns Markdown content string
   */
  readMarkdown(filepath: string): Promise<string>;
  
  /**
   * Write HTML file with proper structure
   * @param filepath - Output HTML file path
   * @param content - HTML content
   * @returns Promise resolving when complete
   */
  writeHtml(filepath: string, content: string): Promise<void>;
}

Implementation Examples:

// JSON file operations
const readJson = async (filepath: string) => {
  const content = await FileEngine.get(filepath);
  return JSON.parse(content);
};

const writeJson = async (filepath: string, data: any) => {
  const content = JSON.stringify(data, null, 2);
  await FileEngine.write(filepath, content);
};

// Markdown operations
const readMarkdown = async (filepath: string) => {
  return await FileEngine.get(filepath);
};

// HTML operations with proper structure
const writeHtml = async (filepath: string, content: string) => {
  await FileEngine.write(filepath, content);
};

// Usage in Compodoc context
const packageData = await readJson("./package.json");
const readme = await readMarkdown("./README.md");
await writeHtml("./docs/index.html", renderedHtml);

Directory Operations

Extended functionality for directory operations (though not directly in FileEngine, commonly used patterns).

/**
 * Directory operation patterns commonly used with FileEngine
 */
interface DirectoryPatterns {
  /**
   * Ensure directory exists before writing files
   * @param dirpath - Directory path to create if needed
   */
  ensureDir(dirpath: string): Promise<void>;
  
  /**
   * Copy directory recursively
   * @param source - Source directory
   * @param destination - Destination directory
   */
  copyDir(source: string, destination: string): Promise<void>;
  
  /**
   * List files in directory with pattern matching
   * @param dirpath - Directory to list
   * @param pattern - Optional glob pattern
   */
  listFiles(dirpath: string, pattern?: string): Promise<string[]>;
}