spec-up-t 1.1.54 → 1.2.0

package/src/health-check/specs-configuration-checker.js

@@ -0,0 +1,274 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Check if specs.json has been configured from default
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Promise<Array>} - Array of check results
+ */
+async function checkSpecsJsonConfiguration(projectRoot) {
+    const results = [];
+
+    try {
+        // Path to the project's specs.json
+        const projectSpecsPath = path.join(projectRoot, 'specs.json');
+
+        // Path to the default boilerplate specs.json
+        const defaultSpecsPath = path.join(
+            __dirname,
+            '..',
+            'install-from-boilerplate',
+            'boilerplate',
+            'specs.json'
+        );
+
+        // Check if project specs.json exists
+        if (!fs.existsSync(projectSpecsPath)) {
+            return [{
+                name: 'Find specs.json file',
+                success: false,
+                details: 'specs.json file not found in project root'
+            }];
+        }
+
+        // Check if default specs.json exists
+        if (!fs.existsSync(defaultSpecsPath)) {
+            return [{
+                name: 'Find default specs.json template',
+                success: false,
+                details: 'Default specs.json template not found'
+            }];
+        }
+
+        // Read both files
+        const projectSpecs = JSON.parse(fs.readFileSync(projectSpecsPath, 'utf8'));
+        const defaultSpecs = JSON.parse(fs.readFileSync(defaultSpecsPath, 'utf8'));
+
+        // Compare key parts to see if the file has been configured
+        results.push({
+            name: 'specs.json exists',
+            success: true,
+            details: 'Project specs.json file found'
+        });
+
+        // Dynamically extract field definitions from the default specs.json
+        const fieldDescriptions = {
+            'title': 'Specification title',
+            'description': 'Specification description',
+            'author': 'Specification author',
+            'source': 'Source repository information',
+            'spec_directory': 'Directory containing specification content',
+            'spec_terms_directory': 'Directory containing term definitions',
+            'output_path': 'Output directory for generated files',
+            'markdown_paths': 'List of markdown files to include in the specification',
+            'logo': 'Logo URL',
+            'logo_link': 'Link to the logo',
+            'favicon': 'Favicon URL',
+            'external_specs': 'External specifications',
+            'katex': 'KaTeX math rendering configuration'
+            // Add more descriptions as needed, or create a more sophisticated lookup
+        };
+
+        // Define required and optional fields based on the default specs.json
+        const defaultSpecKeys = Object.keys(defaultSpecs.specs?.[0] || {});
+
+        // Known optional fields - this could be pulled from documentation if available
+        const knownOptionalFields = ['logo', 'external_specs', 'logo_link', 'favicon', 'katex'];
+
+        // Fields that can remain at their default values without being flagged
+        const allowDefaultValueFields = [
+            'spec_directory',
+            'spec_terms_directory',
+            'output_path',
+            'katex',
+            'logo',
+            'logo_link',
+            'favicon'
+            // Add any other fields that should be allowed to have default values
+            // Add any new field here that should be allowed to have default values
+        ];
+
+        // Fields that should fail if they're not modified from default values
+        const mustChangeFields = [
+            'title',
+            'description',
+            'author',
+            'source'
+        ];
+
+        // Consider all keys in the template as required unless explicitly marked as optional
+        const requiredFields = defaultSpecKeys
+            .filter(key => !knownOptionalFields.includes(key))
+            .map(key => ({
+                key,
+                description: fieldDescriptions[key] || `${key.replace(/_/g, ' ')} field`,
+                allowDefaultValue: allowDefaultValueFields.includes(key),
+                mustChange: mustChangeFields.includes(key)
+            }));
+
+        const optionalFields = defaultSpecKeys
+            .filter(key => knownOptionalFields.includes(key))
+            .map(key => ({
+                key,
+                description: fieldDescriptions[key] || `${key.replace(/_/g, ' ')} field`,
+                allowDefaultValue: allowDefaultValueFields.includes(key)
+            }));
+
+        // Check each required field exists
+        const missingRequiredKeys = [];
+
+        for (const field of requiredFields) {
+            const hasField = projectSpecs.specs?.[0]?.hasOwnProperty(field.key);
+
+            if (!hasField) {
+                missingRequiredKeys.push(field.key);
+
+                results.push({
+                    name: `${field.description} configuration`,
+                    success: false,
+                    details: `Required "${field.key}" key is missing in specs.json`
+                });
+            } else {
+                // Field exists, check if it's configured
+                const projectValue = projectSpecs.specs[0][field.key];
+                const defaultValue = defaultSpecs.specs?.[0]?.[field.key];
+                let isConfigured = false;
+
+                if (typeof projectValue === 'object') {
+                    isConfigured = JSON.stringify(projectValue) !== JSON.stringify(defaultValue);
+                } else {
+                    isConfigured = projectValue !== defaultValue;
+                }
+
+                // For fields that can keep their default values, we'll mark them as configured
+                if (field.allowDefaultValue) {
+                    isConfigured = true;
+                }
+
+                // Determine if we should show warning or fail for unconfigured fields
+                let status = undefined;
+                let success = true;
+                
+                if (!isConfigured) {
+                    if (field.mustChange) {
+                        // Must-change fields should fail if not configured
+                        status = undefined; // No status means it shows as failure
+                        success = false;
+                    } else {
+                        // Other fields should show a warning
+                        status = 'warning';
+                        success = true; // Still technically passes with a warning
+                    }
+                }
+
+                results.push({
+                    name: `${field.description} configuration`,
+                    status: status,
+                    success: success,
+                    details: isConfigured
+                        ? (projectValue === defaultValue && field.allowDefaultValue
+                            ? `Default value for ${field.description} is acceptable`
+                            : `${field.description} has been changed from default`)
+                        : `${field.description} is still set to default value${field.key === 'title' || field.key === 'author' ? `: "${defaultValue}"` : ''}`
+                });
+            }
+        }
+
+        // Check optional fields
+        for (const field of optionalFields) {
+            const hasField = projectSpecs.specs?.[0]?.hasOwnProperty(field.key);
+
+            if (hasField) {
+                const projectValue = projectSpecs.specs[0][field.key];
+                const defaultValue = defaultSpecs.specs?.[0]?.[field.key];
+                let isConfigured = false;
+
+                if (typeof projectValue === 'object') {
+                    isConfigured = JSON.stringify(projectValue) !== JSON.stringify(defaultValue);
+                } else {
+                    isConfigured = projectValue !== defaultValue;
+                }
+
+                // For optional fields that can keep their default values, we'll mark them as configured
+                if (field.allowDefaultValue) {
+                    isConfigured = true;
+                }
+
+                results.push({
+                    name: `${field.description} configuration`,
+                    status: isConfigured ? undefined : 'warning',
+                    success: isConfigured || !isConfigured, // Always true for backward compatibility when using warning
+                    details: isConfigured
+                        ? (projectValue === defaultValue && field.allowDefaultValue
+                            ? `Default value for ${field.description} is acceptable`
+                            : `${field.description} has been changed from default`)
+                        : `${field.description} is still set to default value`
+                });
+            } else {
+                results.push({
+                    name: `${field.description} configuration`,
+                    success: true,
+                    details: `Optional "${field.key}" key is not present (this is not required)`
+                });
+            }
+        }
+
+        // Add a summary of missing required fields
+        if (missingRequiredKeys.length > 0) {
+            results.push({
+                name: 'Required fields check',
+                success: false,
+                details: `Missing required fields: ${missingRequiredKeys.join(', ')}`
+            });
+        } else {
+            results.push({
+                name: 'Required fields check',
+                success: true,
+                details: 'All required fields are present'
+            });
+        }
+
+        // Check if any fields exist that aren't in the standard template (could be typos)
+        const allStandardKeys = [...requiredFields, ...optionalFields].map(f => f.key);
+        const unexpectedKeys = Object.keys(projectSpecs.specs?.[0] || {})
+            .filter(key => !allStandardKeys.includes(key));
+
+        if (unexpectedKeys.length > 0) {
+            results.push({
+                name: 'Unexpected fields check',
+                success: false,
+                details: `Found unexpected fields that might be typos: ${unexpectedKeys.join(', ')}`
+            });
+        }
+
+        // Overall configuration status
+        // Count all fields that are present and configured
+        const fieldResults = results.filter(r =>
+            r.name.includes('configuration') &&
+            !r.name.includes('Overall')
+        );
+
+        const configuredItemsCount = fieldResults.filter(r => r.success).length;
+        const totalItems = fieldResults.length;
+        const configurationPercentage = Math.round((configuredItemsCount / totalItems) * 100);
+
+        results.push({
+            name: 'Overall configuration status',
+            success: configurationPercentage > 50 && missingRequiredKeys.length === 0,
+            details: `${configurationPercentage}% of specs.json has been configured (${configuredItemsCount}/${totalItems} items)`
+        });
+
+        return results;
+    } catch (error) {
+        console.error('Error checking specs.json configuration:', error);
+        return [{
+            name: 'specs.json configuration check',
+            success: false,
+            details: `Error: ${error.message}`
+        }];
+    }
+}
+
+module.exports = {
+    checkSpecsJsonConfiguration
+};

package/src/health-check/term-references-checker.js

@@ -0,0 +1,191 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extracts the spec name from a tref tag at the beginning of a markdown file
+ * @param {string} firstLine - The first line of a markdown file
+ * @returns {string|null} - The extracted spec name or null if not found
+ */
+function extractSpecNameFromTref(firstLine) {
+  if (!firstLine.includes('[[tref:')) {
+    return null;
+  }
+  
+  try {
+    // Extract content between [[tref: and the next comma
+    const match = firstLine.match(/\[\[tref:([^,]+)/);
+    if (match && match[1]) {
+      // Trim whitespace
+      return match[1].trim();
+    }
+  } catch (error) {
+    console.error('Error extracting spec name from tref:', error);
+  }
+  
+  return null;
+}
+
+/**
+ * Check if all markdown files in spec terms directories have valid tref references
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Promise<Array>} - Array of check results
+ */
+async function checkTermReferences(projectRoot) {
+  const results = [];
+  
+  try {
+    const specsPath = path.join(projectRoot, 'specs.json');
+    
+    // Check if specs.json exists
+    if (!fs.existsSync(specsPath)) {
+      return [{
+        name: 'Find specs.json file',
+        success: false,
+        details: 'specs.json file not found in project root'
+      }];
+    }
+    
+    // Read specs.json
+    const specsContent = fs.readFileSync(specsPath, 'utf8');
+    const specs = JSON.parse(specsContent);
+    
+    // Find all external specs
+    const externalSpecs = [];
+    let allSpecDirectories = [];
+    
+    if (specs.specs && Array.isArray(specs.specs)) {
+      // Collect all external specs
+      specs.specs.forEach(spec => {
+        if (spec.external_specs && Array.isArray(spec.external_specs)) {
+          spec.external_specs.forEach(extSpec => {
+            if (extSpec.external_spec) {
+              externalSpecs.push(extSpec.external_spec);
+            }
+          });
+        }
+        
+        // Collect term directories
+        if (spec.spec_directory && spec.spec_terms_directory) {
+          const termsDir = path.join(
+            projectRoot, 
+            spec.spec_directory, 
+            spec.spec_terms_directory
+          );
+          allSpecDirectories.push(termsDir);
+        }
+      });
+    }
+    
+    if (externalSpecs.length === 0) {
+      results.push({
+        name: 'Find external specs',
+        success: false,
+        details: 'No external_spec entries found in specs.json'
+      });
+    } else {
+      results.push({
+        name: 'Find external specs',
+        success: true,
+        details: `Found ${externalSpecs.length} external specs: ${externalSpecs.join(', ')}`
+      });
+    }
+    
+    if (allSpecDirectories.length === 0) {
+      results.push({
+        name: 'Find spec terms directories',
+        success: false,
+        details: 'No spec_directory/spec_terms_directory entries found in specs.json'
+      });
+      return results;
+    }
+    
+    results.push({
+      name: 'Find spec terms directories',
+      success: true,
+      details: `Found ${allSpecDirectories.length} spec terms directories`
+    });
+    
+    // Process all markdown files in all terms directories
+    for (const termsDir of allSpecDirectories) {
+      if (!fs.existsSync(termsDir)) {
+        results.push({
+          name: `Check terms directory: ${termsDir}`,
+          success: false,
+          details: `Terms directory does not exist: ${termsDir}`
+        });
+        continue;
+      }
+      
+      // Find all markdown files in the terms directory
+      const markdownFiles = fs.readdirSync(termsDir)
+        .filter(file => path.extname(file) === '.md')
+        .map(file => path.join(termsDir, file));
+      
+      if (markdownFiles.length === 0) {
+        results.push({
+          name: `Find markdown files in <code>${termsDir}</code>`,
+          success: false,
+          details: `No markdown files found in terms directory: ${termsDir}`
+        });
+        continue;
+      }
+      
+      results.push({
+        name: `Find markdown files in <code>${termsDir}</code>`,
+        success: true,
+        details: `Found ${markdownFiles.length} markdown files`
+      });
+      
+      // Check each markdown file
+      for (const mdFile of markdownFiles) {
+        try {
+          const content = fs.readFileSync(mdFile, 'utf8');
+          const firstLine = content.split('\n')[0];
+          
+          if (!firstLine.includes('[[tref:')) {
+            // Skip this file as it doesn't contain a tref tag in the first line
+            continue;
+          }
+          
+          const specName = extractSpecNameFromTref(firstLine);
+          if (!specName) {
+            results.push({
+              name: `Check tref in ${path.basename(mdFile)}`,
+              success: false,
+              details: `Could not extract spec name from tref tag in first line: "${firstLine}"`
+            });
+            continue;
+          }
+          
+          const isValid = externalSpecs.includes(specName);
+          results.push({
+            name: `Check tref spec "${specName}" in <code>${path.basename(mdFile)}</code>`,
+            success: isValid,
+            details: isValid
+              ? `Valid external spec reference: ${specName}`
+              : `Invalid external spec reference: "${specName}" is not defined in external_specs`
+          });
+        } catch (error) {
+          results.push({
+            name: `Check file ${path.basename(mdFile)}`,
+            success: false,
+            details: `Error reading or processing file: ${error.message}`
+          });
+        }
+      }
+    }
+    
+    return results;
+  } catch (error) {
+    console.error('Error checking term references:', error);
+    return [{
+      name: 'Term references check',
+      success: false,
+      details: `Error: ${error.message}`
+    }];
+  }
+}
+
+module.exports = {
+  checkTermReferences
+};

package/src/health-check/terms-intro-checker.js

@@ -0,0 +1,81 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Check if the terms-and-definitions-intro.md file exists in the spec directory
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Promise<Array>} - Array of check results
+ */
+async function checkTermsIntroFile(projectRoot) {
+  const results = [];
+  
+  try {
+    // Path to the project's specs.json
+    const specsPath = path.join(projectRoot, 'specs.json');
+    
+    // Check if specs.json exists
+    if (!fs.existsSync(specsPath)) {
+      return [{
+        name: 'Find specs.json file',
+        success: false,
+        details: 'specs.json file not found in project root'
+      }];
+    }
+    
+    results.push({
+      name: 'Find specs.json file',
+      success: true,
+      details: 'specs.json file found'
+    });
+    
+    // Read specs.json to get the spec directory
+    const specsContent = fs.readFileSync(specsPath, 'utf8');
+    const specs = JSON.parse(specsContent);
+    
+    // Get the spec_directory value
+    const specDir = specs.specs?.[0]?.spec_directory;
+    
+    if (!specDir) {
+      results.push({
+        name: 'Find spec_directory field',
+        success: false,
+        details: 'spec_directory field not found in specs.json'
+      });
+      return results;
+    }
+    
+    results.push({
+      name: 'Find spec_directory field',
+      success: true,
+      details: `spec_directory field found: "${specDir}"`
+    });
+    
+    // Build the path to the terms-and-definitions-intro.md file
+    const specDirPath = path.resolve(projectRoot, specDir);
+    const termsIntroPath = path.join(specDirPath, 'terms-and-definitions-intro.md');
+    
+    // Check if the terms-and-definitions-intro.md file exists
+    const termsIntroExists = fs.existsSync(termsIntroPath);
+    
+    results.push({
+      name: 'Find terms-and-definitions-intro.md file',
+      success: termsIntroExists,
+      details: termsIntroExists 
+        ? 'terms-and-definitions-intro.md file found in spec directory'
+        : `terms-and-definitions-intro.md file not found in ${specDirPath}`
+    });
+    
+    return results;
+  } catch (error) {
+    console.error('Error checking terms-and-definitions-intro.md file:', error);
+    return [{
+      name: 'Terms intro file check',
+      success: false,
+      details: `Error: ${error.message}`
+    }];
+  }
+}
+
+module.exports = {
+  checkTermsIntroFile
+};