YAML Property Assurance Script Enhancements

YAML Property Assurance Script Enhancements

Core Improvements

1. UUID Integration

• Added automatic site_uuid generation for markdown files
• Implemented UUID v4 for unique site identification
• Preserves existing UUIDs, only generates for missing entries

const required = {
  properties: ['site_uuid'],
  generateIfMissing: {
    site_uuid: () => uuidv4()
  }
}

2. Configuration Centralization

• Introduced USER_OPTIONS configuration object
• Separated concerns into logical groupings:
  • Directory paths and exclusions
  • YAML property requirements
  • File generation settings
  • Formatting preferences

const USER_OPTIONS = {
  directories: { /* ... */ },
  frontmatter: { /* ... */ },
  reporting: { /* ... */ }
};

3. Property Management

• Enhanced YAML property handling:
  • Configurable required properties list
  • Automatic value generation for missing properties
  • Property name formatting standardization

frontmatter: {
  required: {
    properties: ['site_uuid'],
    generateIfMissing: {
      site_uuid: () => uuidv4()
    }
  },
  propertyFormatting: {
    convertHyphensToUnderscores: true,
    ensureArrayForTags: true
  }
}

Technical Improvements

1. Directory Structure

• Moved script to build-scripts/ directory
• Implemented configurable directory paths
• Added exclusion patterns for URL checks

directories: {
  content: path.join(process.cwd(), 'src/content/tooling'),
  fixes: path.join(process.cwd(), 'scripts/fixes-needed'),
  excludeUrlCheck: ['Explainers']
}

2. Error Reporting

• Consolidated issue reporting
• Dynamic file generation based on issue type
• Improved error tracking and statistics

reporting: {
  issueFiles: {
    lowercaseTags: 'Lowercase-Tags.md',
    missingUrls: 'Missing-URLs.md'
  }
}

3. Code Organization

• Modularized functionality into logical sections
• Improved code readability with clear section markers
• Enhanced maintainability through configuration centralization

Impact

• Consistency: Ensures uniform YAML frontmatter across all markdown files
• Identification: Automatic UUID generation for content tracking
• Maintenance: Reduced code duplication and improved configurability
• Reliability: Better error handling and reporting
• Flexibility: Easy configuration updates through USER_OPTIONS

Usage Notes

1. Automatic UUID generation for new content
2. Standardized property naming (hyphens to underscores)
3. Tag formatting and validation
4. URL presence verification (with configurable exclusions)
5. Comprehensive issue reporting

Technical Details

Dependencies

const { v4: uuidv4 } = require('uuid');

Key Functions

• Property Generation:

if (!parsedFile.data[prop] && USER_OPTIONS.frontmatter.required.generateIfMissing[prop]) {
  const generatedValue = USER_OPTIONS.frontmatter.required.generateIfMissing[prop]();
  modifiedFrontmatter = `${prop}: "${generatedValue}"\n${modifiedFrontmatter}`;
}

Configuration

• Directory paths
• Required properties
• Formatting rules
• Issue reporting paths

Migration Notes

• Existing UUIDs are preserved
• Current formatting is maintained unless explicitly configured
• Issue reporting continues to work as before

• Required properties
• Directory paths
• Formatting rules
• Issue reporting configuration