spec-up-t-healthcheck 1.0.0

package/lib/index.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Main entry point for spec-up-t-healthcheck
+ * 
+ * This module serves as the primary API for the spec-up-t-healthcheck library,
+ * providing convenient access to all core functionality including health checking,
+ * result formatting, and provider management. It offers both individual component
+ * access and a simplified high-level API.
+ * 
+ * @author spec-up-t-healthcheck
+ 
+ */
+
+// Re-export provider functionality
+export { createProvider, createLocalProvider } from './providers.js';
+
+// Re-export health checking functionality
+export { runHealthChecks, createHealthCheckResult, checkPackageJson, checkSpecFiles, checkSpecsJson, checkExternalSpecsUrls, checkGitignore } from './health-checker.js';
+
+// Re-export formatting functionality
+export { formatResultsAsText, formatResultsAsJson, formatResultsAsHtml } from './formatters.js';
+
+// Re-export file opening utilities
+export { openFile, openHtmlFile, getOpenCommand } from './file-opener.js';
+
+// Import functions for internal use
+import { createProvider } from './providers.js';
+import { runHealthChecks } from './health-checker.js';
+
+/**
+ * Direct API Usage Examples
+ * 
+ * For more control over the health checking process, you can use the core functions directly:
+ * 
+ * @example
+ * ```javascript
+ * // Direct usage with runHealthChecks (more control)
+ * (async () => {
+ *     const { createProvider, runHealthChecks } = await import('spec-up-t-healthcheck');
+ *     const provider = createProvider('.');
+ *     const results = await runHealthChecks(provider, {});
+ *     console.log("🚀 ~ Healthcheck results:", results);
+ * })().catch(console.error);
+ * 
+ * // With specific checks
+ * (async () => {
+ *     const { createProvider, runHealthChecks } = await import('spec-up-t-healthcheck');
+ *     const provider = createProvider('./my-project');
+ *     const results = await runHealthChecks(provider, {
+ *         checks: ['package-json', 'spec-files']
+ *     });
+ *     console.log("Health score:", results.summary.score + "%");
+ *     console.log("Errors:", results.summary.hasErrors);
+ * })().catch(console.error);
+ * 
+ * // Format results in different ways
+ * (async () => {
+ *     const { createProvider, runHealthChecks, formatResultsAsHtml } = await import('spec-up-t-healthcheck');
+ *     const provider = createProvider('.');
+ *     const results = await runHealthChecks(provider, {});
+ *     
+ *     // Generate HTML report
+ *     const htmlReport = formatResultsAsHtml(results, {
+ *         title: 'My Project Health Check',
+ *         repositoryUrl: 'https://github.com/user/repo'
+ *     });
+ *     
+ *     // Save or display the HTML
+ *     console.log("HTML report generated");
+ * })().catch(console.error);
+ * ```
+ */
+
+/**
+ * Simplified high-level API for performing health checks on a specification repository.
+ * 
+ * This convenience function combines provider creation and health checking into a single
+ * call, making it easy to perform health checks without managing providers manually.
+ * It automatically determines the appropriate provider type based on the input.
+ * 
+ * @param {string} input - The path or URL to the specification repository
+ * @param {Object} [options={}] - Configuration options for the health check
+ * @param {string[]} [options.checks] - Specific checks to run (defaults to all registered checks)
+ * @param {string[]} [options.categories] - Legacy alias for checks parameter
+ * @param {Object} [options.providerOptions] - Options to pass to the provider
+ * @returns {Promise<import('./health-checker.js').HealthCheckReport>} Complete health check report
+ * 
+ * @example
+ * ```javascript
+ * // Check a local repository (runs all registered checks)
+ * const report = await healthCheck('/path/to/spec-repo');
+ * 
+ * // Check with specific options
+ * const customReport = await healthCheck('/path/to/spec-repo', {
+ *   checks: ['package-json', 'spec-files']
+ * });
+ * 
+ * // Display results
+ * console.log(`Health score: ${report.summary.score}%`);
+ * if (report.summary.hasErrors) {
+ *   console.error('Some health checks failed');
+ * }
+ * ```
+ * 
+ * @since 1.0.0
+ */
+export async function healthCheck(input, options = {}) {
+  // Handle legacy 'categories' parameter
+  const healthCheckOptions = {
+    ...options,
+    checks: options.checks || options.categories
+    // If neither checks nor categories is provided, orchestrator will run all registered checks
+  };
+  
+  const provider = createProvider(input, options.providerOptions);
+  return await runHealthChecks(provider, healthCheckOptions);
+}
+
+/**
+ * The current version of the spec-up-t-healthcheck library.
+ * @type {string}
+ * @readonly
+ */
+export const version = '1.0.2';

package/lib/providers.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Providers module for spec-up-t-healthcheck
+ * 
+ * This module contains provider implementations for accessing specification files
+ * from different sources (local filesystem, remote repositories, etc.).
+ * Providers offer a unified interface for file operations regardless of the underlying source.
+ * 
+ * @author spec-up-t-healthcheck
+ 
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * @typedef {Object} FileEntry
+ * @property {string} name - The name of the file or directory
+ * @property {string} path - The relative path from the repository root
+ * @property {boolean} isDirectory - Whether this entry is a directory
+ * @property {boolean} isFile - Whether this entry is a file
+ */
+
+/**
+ * @typedef {Object} Provider
+ * @property {string} type - The type of provider ('local', 'remote', etc.)
+ * @property {string} repoPath - The base path or URL for the repository
+ * @property {function(string): Promise<string>} readFile - Read a file and return its content
+ * @property {function(string): Promise<boolean>} fileExists - Check if a file exists
+ * @property {function(string): Promise<FileEntry[]>} listFiles - List files in a directory
+ */
+
+/**
+ * Creates a local filesystem provider for accessing specification files.
+ * 
+ * The local provider enables reading files from a local directory structure,
+ * providing async methods for file operations with proper error handling.
+ * All file paths are resolved relative to the provided repository path.
+ * 
+ * @param {string} repoPath - The absolute or relative path to the local repository root
+ * @returns {Provider} A provider object with methods for file operations
+ * 
+ * @example
+ * ```javascript
+ * const provider = createLocalProvider('/path/to/spec/repo');
+ * const content = await provider.readFile('spec/example.md');
+ * const exists = await provider.fileExists('package.json');
+ * const files = await provider.listFiles('spec');
+ * ```
+ * 
+ * @throws {Error} When file operations fail due to permissions or other filesystem errors
+ */
+export function createLocalProvider(repoPath) {
+  const provider = {
+    type: 'local',
+    repoPath,
+    
+    /**
+     * Returns the base path of the repository.
+     * 
+     * @returns {string} The base path of the repository
+     */
+    getBasePath() {
+      return repoPath;
+    },
+    
+    /**
+     * Reads the content of a file from the local filesystem.
+     * 
+     * @param {string} filePath - The relative path to the file from the repository root
+     * @returns {Promise<string>} The file content as a UTF-8 string
+     * 
+     * @throws {Error} When the file is not found (ENOENT)
+     * @throws {Error} When there's a filesystem error reading the file
+     * 
+     * @example
+     * ```javascript
+     * const content = await provider.readFile('spec/introduction.md');
+     * console.log(content); // File content as string
+     * ```
+     */
+    async readFile(filePath) {
+      const fullPath = path.join(repoPath, filePath);
+      try {
+        const content = await fs.readFile(fullPath, 'utf8');
+        return content;
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          throw new Error(`File not found: ${filePath}`);
+        }
+        throw new Error(`Error reading file ${filePath}: ${error.message}`);
+      }
+    },
+
+    /**
+     * Checks whether a file exists in the local filesystem.
+     * 
+     * @param {string} filePath - The relative path to the file from the repository root
+     * @returns {Promise<boolean>} True if the file exists, false otherwise
+     * 
+     * @example
+     * ```javascript
+     * const exists = await provider.fileExists('package.json');
+     * if (exists) {
+     *   console.log('Package.json found');
+     * }
+     * ```
+     */
+    async fileExists(filePath) {
+      const fullPath = path.join(repoPath, filePath);
+      try {
+        await fs.access(fullPath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    /**
+     * Lists all files and directories in the specified directory.
+     * 
+     * @param {string} [dirPath=''] - The relative path to the directory from the repository root.
+     *                                Defaults to the repository root if not specified.
+     * @returns {Promise<FileEntry[]>} An array of file entries with metadata
+     * 
+     * @throws {Error} When the directory cannot be read or doesn't exist
+     * 
+     * @example
+     * ```javascript
+     * const entries = await provider.listFiles('spec');
+     * entries.forEach(entry => {
+     *   console.log(`${entry.name} - ${entry.isDirectory ? 'DIR' : 'FILE'}`);
+     * });
+     * ```
+     */
+    async listFiles(dirPath = '') {
+      const fullPath = path.join(repoPath, dirPath);
+      try {
+        const entries = await fs.readdir(fullPath, { withFileTypes: true });
+        return entries.map(entry => ({
+          name: entry.name,
+          path: path.join(dirPath, entry.name),
+          isDirectory: entry.isDirectory(),
+          isFile: entry.isFile()
+        }));
+      } catch (error) {
+        throw new Error(`Error listing directory ${dirPath}: ${error.message}`);
+      }
+    }
+  };
+  
+  return provider;
+}
+
+/**
+ * Creates a provider based on the input type (local path or remote URL).
+ * 
+ * This factory function automatically determines the appropriate provider type
+ * based on the input format. Currently supports local filesystem providers,
+ * with remote providers planned for future implementation.
+ * 
+ * @param {string} input - The path or URL to the specification repository.
+ *                        Local paths can be absolute or relative.
+ *                        Remote URLs should start with http:// or https://
+ * @returns {Provider} An appropriate provider instance for the input type
+ * 
+ * @throws {Error} When remote URLs are provided (not yet implemented)
+ * 
+ * @example
+ * ```javascript
+ * // Create a local provider
+ * const localProvider = createProvider('/path/to/spec');
+ * 
+ * // Remote provider (throws error - not implemented)
+ * const remoteProvider = createProvider('https://github.com/user/spec-repo');
+ * ```
+ * 
+ * @since 1.0.0
+ */
+export function createProvider(input) {
+  if (input.startsWith('http://') || input.startsWith('https://')) {
+    throw new Error('Remote providers not yet implemented');
+  }
+  return createLocalProvider(input);
+}

package/lib/web.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Browser-compatible entry point for spec-up-t-healthcheck
+ * 
+ * This module provides a browser-safe API that excludes Node.js-specific modules
+ * like file-opener which depend on child_process. This allows the health check
+ * functionality to work in browser environments like Vite.
+ * 
+ * @author spec-up-t-healthcheck
+ */
+
+// Re-export provider functionality (browser-compatible)
+export { createProvider } from './providers.js';
+
+// Re-export health checking functionality (browser-compatible)
+export { 
+  runHealthChecks, 
+  createHealthCheckResult, 
+  checkPackageJson, 
+  checkSpecFiles, 
+  checkSpecsJson 
+} from './health-checker.js';
+
+// Re-export formatting functionality (browser-compatible)
+export { 
+  formatResultsAsText, 
+  formatResultsAsJson, 
+  formatResultsAsHtml 
+} from './formatters.js';
+
+// Import functions for internal use
+import { createProvider } from './providers.js';
+import { runHealthChecks } from './health-checker.js';
+
+/**
+ * Simplified API for browser environments
+ * 
+ * This function provides the same functionality as the main package
+ * but excludes file opening capabilities that require Node.js
+ * 
+ * @param {Object} provider - File system provider (must be provided)
+ * @param {Object} [options={}] - Health check options
+ * @returns {Promise<Object>} Health check results
+ * 
+ * @example
+ * ```javascript
+ * import { runHealthCheck } from 'spec-up-t-healthcheck/web';
+ * 
+ * const provider = createGitHubProvider(token, owner, repo);
+ * const results = await runHealthCheck(provider);
+ * ```
+ */
+export async function runHealthCheck(provider, options = {}) {
+  if (!provider) {
+    throw new Error('Provider is required for browser environments');
+  }
+  
+  return await runHealthChecks(provider, options);
+}
+
+/**
+ * Browser-compatible health check API
+ * Excludes file opening functionality for browser safety
+ */
+export const browserApi = {
+  runHealthCheck,
+  createProvider,
+  runHealthChecks
+};
+
+export default browserApi;

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "spec-up-t-healthcheck",
+  "version": "1.0.0",
+  "description": "Modular health check tool for spec-up-t repositories - works in Node.js, browsers, and CLI",
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "spec-up-t-healthcheck": "bin/cli.js"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./web": "./lib/web.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint lib test",
+    "lint:fix": "eslint lib test --fix",
+    "cli": "node bin/cli.js",
+    "example": "node examples/node-usage.js",
+    "examples": "node examples/comprehensive-usage.js",
+    "healthcheck": "node bin/cli.js check .",
+    "healthcheck:html": "node bin/cli.js check . --format html",
+    "demo:html": "node bin/demo-html.js"
+  },
+  "keywords": [
+    "spec-up-t",
+    "health-check",
+    "validation",
+    "specification",
+    "markdown",
+    "cli",
+    "npm",
+    "quality-assurance"
+  ],
+  "author": "Blockchain Bird",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blockchainbird/spec-up-t-healthcheck.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blockchainbird/spec-up-t-healthcheck/issues"
+  },
+  "homepage": "https://github.com/blockchainbird/spec-up-t-healthcheck#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "lib/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "axios": "^1.6.7",
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.0.3"
+  },
+  "peerDependencies": {
+    "node-fetch": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "node-fetch": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "@jest/environment": "^29.7.0",
+    "@jest/environment-jsdom-abstract": "^29.7.0",
+    "@jest/fake-timers": "^29.7.0",
+    "@jest/schemas": "^29.7.0",
+    "@jest/types": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jest-message-util": "^29.7.0",
+    "jest-mock": "^29.7.0",
+    "jest-util": "^29.7.0",
+    "pretty-format": "^29.7.0",
+    "@jest/pattern": "^29.7.0",
+    "jest-regex-util": "^29.7.0"
+  }
+}