spec-up-t-healthcheck 1.0.0

package/lib/checks/spec-files.js

@@ -0,0 +1,263 @@
+/**
+ * @fileoverview Specification files health check module
+ * 
+ * This module validates the presence and accessibility of specification files
+ * in repositories. It searches for markdown files in common specification
+ * directories and ensures that specification content is properly organized.
+ * 
+ * @author spec-up-t-healthcheck
+ */
+
+import { createHealthCheckResult, createErrorResult } from '../health-check-utils.js';
+
+/**
+ * The identifier for this health check, used in reports and registries.
+ * @type {string}
+ */
+export const CHECK_ID = 'spec-files';
+
+/**
+ * Human-readable name for this health check.
+ * @type {string}
+ */
+export const CHECK_NAME = 'Specification Files Discovery';
+
+/**
+ * Description of what this health check validates.
+ * @type {string}
+ */
+export const CHECK_DESCRIPTION = 'Discovers and validates specification files in the repository';
+
+/**
+ * Common directory paths where specification files are typically located.
+ * These paths are searched in order of preference.
+ * @type {readonly string[]}
+ */
+const SPEC_DIRECTORIES = Object.freeze([
+  'spec/',
+  'specs/', 
+  'docs/',
+  'documentation/',
+  'doc/'
+]);
+
+/**
+ * File extensions that are considered specification files.
+ * @type {readonly string[]}
+ */
+const SPEC_EXTENSIONS = Object.freeze(['.md', '.markdown', '.rst', '.txt']);
+
+/**
+ * Common specification file names that indicate primary specification content.
+ * These files are given higher priority in reporting.
+ * @type {readonly string[]}
+ */
+const PRIMARY_SPEC_NAMES = Object.freeze([
+  'spec.md',
+  'specification.md',
+  'README.md',
+  'index.md',
+  'main.md'
+]);
+
+/**
+ * Checks for the presence and accessibility of specification files in the repository.
+ * 
+ * This health check searches for markdown and other documentation files in common
+ * specification directories as well as the repository root. It validates that
+ * specification content is available and properly organized.
+ * 
+ * The check performs the following discovery:
+ * - Searches common spec directories (spec/, docs/, etc.)
+ * - Looks for markdown and text files in root directory
+ * - Identifies primary specification files
+ * - Reports on file organization and accessibility
+ * 
+ * @param {import('../providers.js').Provider} provider - The provider instance for file operations
+ * @returns {Promise<import('../health-check-utils.js').HealthCheckResult>} The health check result with file discovery details
+ * 
+ * @example
+ * ```javascript
+ * const provider = createLocalProvider('/path/to/repo');
+ * const result = await checkSpecFiles(provider);
+ * console.log(result.details.specFiles); // Array of found specification files
+ * ```
+ */
+export async function checkSpecFiles(provider) {
+  try {
+    const discoveryResult = await discoverSpecificationFiles(provider);
+    
+    const {
+      specFiles,
+      specDirectory, 
+      primarySpecs,
+      rootSpecFiles,
+      searchedPaths,
+      totalFiles
+    } = discoveryResult;
+
+    // No specification files found
+    if (totalFiles === 0) {
+      return createHealthCheckResult(
+        CHECK_NAME, 
+        'fail', 
+        'No specification files found in repository',
+        { 
+          searchedPaths,
+          searchedExtensions: SPEC_EXTENSIONS,
+          suggestions: [
+            'Create a spec/ or docs/ directory',
+            'Add a README.md file with specification content',
+            'Ensure specification files use supported extensions (.md, .markdown, .rst, .txt)'
+          ]
+        }
+      );
+    }
+
+    // Determine health status - keep it simple like the original
+    let status = 'pass';
+    let message = `Found ${totalFiles} specification file${totalFiles === 1 ? '' : 's'}`;
+    
+    const details = {
+      specFiles: specFiles.map(f => f.name),
+      specDirectory,
+      primarySpecs: primarySpecs.map(f => f.name),
+      rootSpecFiles: rootSpecFiles.map(f => f.name),
+      totalFiles,
+      hasOrganizedSpecs: !!specDirectory,
+      hasPrimarySpecs: primarySpecs.length > 0,
+      searchedPaths
+    };
+
+    // Only add organization info to message, don't change status
+    if (specDirectory) {
+      message += ` in organized ${specDirectory} directory`;
+    } else if (rootSpecFiles.length > 0) {
+      message += ' in repository root';
+      // Only warn if there are many unorganized files in root (more aggressive threshold)
+      if (rootSpecFiles.length > 5) {
+        details.organizationSuggestion = 'Consider moving specification files to a dedicated directory like spec/ or docs/';
+      }
+    }
+
+    // Don't warn about missing primary specs - this is optional organizational advice only
+    if (primarySpecs.length === 0 && totalFiles > 1) {
+      details.primarySpecSuggestion = 'Consider adding a main specification file (spec.md, README.md, or index.md)';
+    }
+
+    return createHealthCheckResult(CHECK_NAME, status, message, details);
+
+  } catch (error) {
+    return createErrorResult(CHECK_NAME, error, {
+      context: 'discovering specification files',
+      provider: provider.type
+    });
+  }
+}
+
+/**
+ * Discovers all specification files in the repository.
+ * 
+ * This function performs the actual file discovery logic, searching through
+ * common specification directories and the repository root for relevant files.
+ * 
+ * @param {import('../providers.js').Provider} provider - The provider instance for file operations
+ * @returns {Promise<Object>} Discovery result with found files and metadata
+ * @private
+ */
+async function discoverSpecificationFiles(provider) {
+  let specFiles = [];
+  let specDirectory = null;
+  let primarySpecs = [];
+  let rootSpecFiles = [];
+  const searchedPaths = [];
+
+  // Search spec directories first
+  for (const dir of SPEC_DIRECTORIES) {
+    searchedPaths.push(dir);
+    try {
+      const files = await provider.listFiles(dir);
+      if (files.length > 0) {
+        const relevantFiles = filterSpecificationFiles(files);
+        if (relevantFiles.length > 0) {
+          specDirectory = dir;
+          specFiles = relevantFiles;
+          primarySpecs = identifyPrimarySpecs(relevantFiles, dir);
+          break; // Use first directory with spec files
+        }
+      }
+    } catch (dirError) {
+      // Directory doesn't exist or can't be accessed, continue searching
+    }
+  }
+
+  // Also check root directory for specification files
+  try {
+    const rootFiles = await provider.listFiles('');
+    const rootRelevantFiles = filterSpecificationFiles(rootFiles);
+    rootSpecFiles = rootRelevantFiles;
+    
+    // If no organized spec directory found, use root files as primary
+    if (!specDirectory && rootRelevantFiles.length > 0) {
+      specFiles = rootRelevantFiles;
+      primarySpecs = identifyPrimarySpecs(rootRelevantFiles, '');
+    }
+  } catch (rootError) {
+    // Can't access root directory
+  }
+
+  const totalFiles = specFiles.length + (specDirectory ? 0 : rootSpecFiles.length);
+
+  return {
+    specFiles,
+    specDirectory,
+    primarySpecs,
+    rootSpecFiles,
+    searchedPaths,
+    totalFiles
+  };
+}
+
+/**
+ * Filters a list of files to include only specification-relevant files.
+ * 
+ * @param {Array} files - Array of file objects from provider.listFiles()
+ * @returns {Array} Filtered array of specification files
+ * @private
+ */
+function filterSpecificationFiles(files) {
+  return files.filter(file => {
+    if (!file.isFile) return false;
+    
+    return SPEC_EXTENSIONS.some(ext => 
+      file.name.toLowerCase().endsWith(ext.toLowerCase())
+    );
+  });
+}
+
+/**
+ * Identifies primary specification files from a list of files.
+ * 
+ * Primary specification files are those with common names that typically
+ * contain the main specification content.
+ * 
+ * @param {Array} files - Array of specification files
+ * @param {string} directory - The directory containing the files
+ * @returns {Array} Array of primary specification files
+ * @private
+ */
+function identifyPrimarySpecs(files, directory) {
+  const primaryFiles = [];
+  
+  for (const file of files) {
+    const fileName = file.name.toLowerCase();
+    if (PRIMARY_SPEC_NAMES.some(name => fileName === name.toLowerCase())) {
+      primaryFiles.push(file);
+    }
+  }
+  
+  return primaryFiles;
+}
+
+// Export the health check function as default for easy registration
+export default checkSpecFiles;

package/lib/checks/specsjson.js

@@ -0,0 +1,361 @@
+/**
+ * @fileoverview Specs.json health check module
+ *
+ * This module validates the existence and structure of specs.json files in
+ * specification repositories. It ensures that essential spec metadata is
+ * present and properly formatted.
+ *
+ * @author spec-up-t-healthcheck
+ */
+
+import { createHealthCheckResult, createErrorResult } from '../health-check-utils.js';
+
+/**
+ * The identifier for this health check, used in reports and registries.
+ * @type {string}
+ */
+export const CHECK_ID = 'specs-json';
+
+/**
+ * Human-readable name for this health check.
+ * @type {string}
+ */
+export const CHECK_NAME = 'Specs.json Validation';
+
+/**
+ * Description of what this health check validates.
+ * @type {string}
+ */
+export const CHECK_DESCRIPTION = 'Validates the existence and structure of specs.json file';
+
+/**
+ * Required fields that must be present in a valid specs.json file.
+ * These fields are essential for proper spec functionality in Spec-Up-T.
+ * @type {readonly string[]}
+ */
+const REQUIRED_FIELDS = Object.freeze([
+  'title',
+  'description', 
+  'author',
+  'spec_directory',
+  'spec_terms_directory',
+  'output_path',
+  'markdown_paths',
+  'logo',
+  'logo_link',
+  'source'
+]);
+
+/**
+ * Warning fields that should be present but missing values only trigger warnings.
+ * @type {readonly string[]}
+ */
+const WARNING_FIELDS = Object.freeze(['favicon']);
+
+/**
+ * Optional fields that provide info if missing.
+ * @type {readonly string[]}
+ */
+const OPTIONAL_FIELDS = Object.freeze(['anchor_symbol', 'katex']);
+
+/**
+ * Validates the existence and structure of specs.json in a repository.
+ *
+ * This health check ensures that a valid specs.json file exists at the repository root
+ * and contains the required fields for proper Spec-Up-T functionality. It performs
+ * comprehensive validation of the specs.json structure including the specs array.
+ *
+ * The check performs the following validations:
+ * - File exists at repository root
+ * - File contains valid JSON
+ * - Root object contains exactly one 'specs' field
+ * - 'specs' is an array with exactly one object
+ * - Required fields are present and non-empty
+ * - Warning fields are checked (favicon)
+ * - Optional fields are noted if missing
+ * - Source object has required subfields
+ *
+ * @param {import('../providers.js').Provider} provider - The provider instance for file operations
+ * @returns {Promise<import('../health-check-utils.js').HealthCheckResult>} The health check result with validation details
+ *
+ * @example
+ * ```javascript
+ * const provider = createLocalProvider('/path/to/repo');
+ * const result = await checkSpecsJson(provider);
+ * console.log(result.status); // 'pass', 'fail', or 'warn'
+ * ```
+ */
+export async function checkSpecsJson(provider) {
+  try {
+        // Check if specs.json exists
+    const exists = await provider.fileExists('specs.json');
+    if (!exists) {
+      return createHealthCheckResult(
+        CHECK_NAME,
+        'fail',
+        'specs.json not found in repository root',
+        {
+          suggestions: [
+            'Create a specs.json file in your repository root',
+            'Use the Spec-Up-T boilerplate as a template',
+            'Ensure the file is named exactly "specs.json"'
+          ]
+        }
+      );
+    }
+
+    // Read and parse the specs.json file
+    const content = await provider.readFile('specs.json');
+    let specsData;
+
+    try {
+      specsData = JSON.parse(content);
+    } catch (parseError) {
+      return createHealthCheckResult(
+        CHECK_NAME,
+        'fail',
+        'specs.json contains invalid JSON',
+        {
+          parseError: parseError.message,
+          fileContent: content.substring(0, 500) + (content.length > 500 ? '...' : '')
+        }
+      );
+    }
+
+    // Validate basic structure
+    const structureValidation = validateBasicStructure(specsData);
+    if (!structureValidation.isValid) {
+      return createHealthCheckResult(
+        CHECK_NAME,
+        'fail',
+        structureValidation.message,
+        { structureError: structureValidation.details }
+      );
+    }
+
+    const spec = specsData.specs[0];
+    const validationResults = {
+      errors: [],
+      warnings: [],
+      info: [],
+      success: []
+    };
+
+    // Validate required fields
+    validateRequiredFields(spec, validationResults);
+    
+    // Validate warning fields  
+    validateWarningFields(spec, validationResults);
+    
+    // Validate optional fields
+    validateOptionalFields(spec, validationResults);
+    
+    // Validate field types and structure
+    validateFieldTypes(spec, validationResults);
+
+    // Determine overall status
+    let status = 'pass';
+    let message = 'specs.json is valid';
+
+    if (validationResults.errors.length > 0) {
+      status = 'fail';
+      message = `specs.json has ${validationResults.errors.length} error(s)`;
+    } else if (validationResults.warnings.length > 0) {
+      status = 'warn';
+      message = `specs.json is valid but has ${validationResults.warnings.length} warning(s)`;
+    }
+
+    return createHealthCheckResult(
+      CHECK_NAME,
+      status,
+      message,
+      {
+        errors: validationResults.errors,
+        warnings: validationResults.warnings,
+        info: validationResults.info,
+        success: validationResults.success,
+        totalIssues: validationResults.errors.length + validationResults.warnings.length
+      }
+    );
+
+  } catch (error) {
+    return createErrorResult(CHECK_NAME, error);
+  }
+}
+
+/**
+ * Validates the basic structure of specs.json
+ * @param {any} data - Parsed JSON data
+ * @returns {{isValid: boolean, message?: string, details?: any}}
+ */
+function validateBasicStructure(data) {
+  // Check if data is an object
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    return {
+      isValid: false,
+      message: 'specs.json must contain a JSON object at root level',
+      details: { actualType: Array.isArray(data) ? 'array' : typeof data }
+    };
+  }
+
+  // Check if it contains exactly one field called 'specs'
+  const keys = Object.keys(data);
+  if (keys.length !== 1) {
+    return {
+      isValid: false,
+      message: `Root object should contain exactly one field, found ${keys.length}: [${keys.join(', ')}]`,
+      details: { foundKeys: keys }
+    };
+  }
+
+  if (keys[0] !== 'specs') {
+    return {
+      isValid: false,
+      message: `Root object should contain field 'specs', found '${keys[0]}'`,
+      details: { foundKey: keys[0] }
+    };
+  }
+
+  // Check if specs is an array
+  if (!Array.isArray(data.specs)) {
+    return {
+      isValid: false,
+      message: 'Field "specs" should be an array',
+      details: { actualType: typeof data.specs }
+    };
+  }
+
+  // Check if array contains exactly one object
+  if (data.specs.length !== 1) {
+    return {
+      isValid: false,
+      message: `Field "specs" should contain exactly one object, found ${data.specs.length}`,
+      details: { arrayLength: data.specs.length }
+    };
+  }
+
+  // Check if the single item is an object
+  if (typeof data.specs[0] !== 'object' || data.specs[0] === null || Array.isArray(data.specs[0])) {
+    return {
+      isValid: false,
+      message: 'The item in "specs" array should be an object',
+      details: { actualType: Array.isArray(data.specs[0]) ? 'array' : typeof data.specs[0] }
+    };
+  }
+
+  return { isValid: true };
+}
+
+/**
+ * Validates required fields
+ * @param {Object} spec - The spec object to validate
+ * @param {Object} results - Results accumulator
+ */
+function validateRequiredFields(spec, results) {
+  REQUIRED_FIELDS.forEach(field => {
+    if (!(field in spec)) {
+      results.errors.push(`Required field "${field}" is missing`);
+    } else if (spec[field] === null || spec[field] === undefined || spec[field] === '') {
+      results.errors.push(`Required field "${field}" is empty or null`);
+    } else if (Array.isArray(spec[field]) && spec[field].length === 0) {
+      results.errors.push(`Required field "${field}" is an empty array`);
+    } else {
+      results.success.push(`Required field "${field}" is present and valid`);
+    }
+  });
+}
+
+/**
+ * Validates warning fields
+ * @param {Object} spec - The spec object to validate  
+ * @param {Object} results - Results accumulator
+ */
+function validateWarningFields(spec, results) {
+  WARNING_FIELDS.forEach(field => {
+    if (!(field in spec)) {
+      results.warnings.push(`Recommended field "${field}" is missing`);
+    } else if (spec[field] === null || spec[field] === undefined || spec[field] === '') {
+      results.warnings.push(`Recommended field "${field}" is empty or null`);
+    } else {
+      results.success.push(`Recommended field "${field}" is present and valid`);
+    }
+  });
+}
+
+/**
+ * Validates optional fields
+ * @param {Object} spec - The spec object to validate
+ * @param {Object} results - Results accumulator  
+ */
+function validateOptionalFields(spec, results) {
+  OPTIONAL_FIELDS.forEach(field => {
+    if (!(field in spec)) {
+      results.info.push(`Optional field "${field}" is not set (this is acceptable)`);
+    } else {
+      results.success.push(`Optional field "${field}" is present`);
+    }
+  });
+}
+
+/**
+ * Validates specific field types and formats
+ * @param {Object} spec - The spec object to validate
+ * @param {Object} results - Results accumulator
+ */
+function validateFieldTypes(spec, results) {
+  // Validate markdown_paths is array of strings
+  if (spec.markdown_paths && Array.isArray(spec.markdown_paths)) {
+    if (spec.markdown_paths.every(item => typeof item === 'string')) {
+      results.success.push('Field "markdown_paths" contains valid string array');
+    } else {
+      results.errors.push('Field "markdown_paths" should contain only strings');
+    }
+  }
+
+  // Validate source object structure
+  if (spec.source && typeof spec.source === 'object') {
+    const requiredSourceFields = ['host', 'account', 'repo', 'branch'];
+    let sourceValid = true;
+    
+    requiredSourceFields.forEach(field => {
+      if (!(field in spec.source) || !spec.source[field]) {
+        results.errors.push(`Source field "${field}" is missing or empty`);
+        sourceValid = false;
+      }
+    });
+    
+    if (sourceValid) {
+      results.success.push('Source object structure is valid');
+    }
+  }
+
+  // Validate external_specs if present
+  if (spec.external_specs) {
+    if (Array.isArray(spec.external_specs)) {
+      spec.external_specs.forEach((extSpec, index) => {
+        const requiredExtFields = ['external_spec', 'gh_page', 'url', 'terms_dir'];
+        requiredExtFields.forEach(field => {
+          if (!(field in extSpec) || !extSpec[field]) {
+            results.errors.push(`External spec ${index} missing "${field}"`);
+          }
+        });
+      });
+      results.success.push(`External specs array contains ${spec.external_specs.length} entries`);
+    } else {
+      results.errors.push('Field "external_specs" should be an array');
+    }
+  }
+
+  // Validate katex is boolean if present
+  if ('katex' in spec && typeof spec.katex !== 'boolean') {
+    results.errors.push('Field "katex" should be a boolean value');
+  }
+}
+
+// Export as default for backward compatibility
+export default {
+  CHECK_ID,
+  CHECK_NAME,
+  CHECK_DESCRIPTION,
+  checkSpecsJson
+};