antigravity-skills-reference/scripts/validate-skills.js

const fs = require('fs');
const path = require('path');
const { listSkillIds, parseFrontmatter } = require('../lib/skill-utils');

const ROOT = path.resolve(__dirname, '..');
const SKILLS_DIR = path.join(ROOT, 'skills');
const BASELINE_PATH = path.join(ROOT, 'validation-baseline.json');

const errors = [];
const warnings = [];
const missingUseSection = [];
const missingDoNotUseSection = [];
const missingInstructionsSection = [];
const longFiles = [];
const unknownFieldSkills = [];
const isStrict = process.argv.includes('--strict')
  || process.env.STRICT === '1'
  || process.env.STRICT === 'true';
const writeBaseline = process.argv.includes('--write-baseline')
  || process.env.WRITE_BASELINE === '1'
  || process.env.WRITE_BASELINE === 'true';

const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
const MAX_NAME_LENGTH = 64;
const MAX_DESCRIPTION_LENGTH = 1024;
const MAX_COMPATIBILITY_LENGTH = 500;
const MAX_SKILL_LINES = 500;
const ALLOWED_FIELDS = new Set([
  'name',
  'description',
  'license',
  'compatibility',
  'metadata',
  'allowed-tools',
]);

function isPlainObject(value) {
  return value && typeof value === 'object' && !Array.isArray(value);
}

function validateStringField(fieldName, value, { min = 1, max = Infinity } = {}) {
  if (typeof value !== 'string') {
    return `${fieldName} must be a string.`;
  }
  const trimmed = value.trim();
  if (!trimmed) {
    return `${fieldName} cannot be empty.`;
  }
  if (trimmed.length < min) {
    return `${fieldName} must be at least ${min} characters.`;
  }
  if (trimmed.length > max) {
    return `${fieldName} must be <= ${max} characters.`;
  }
  return null;
}

function addError(message) {
  errors.push(message);
}

function addWarning(message) {
  warnings.push(message);
}

function loadBaseline() {
  if (!fs.existsSync(BASELINE_PATH)) {
    return {
      useSection: [],
      doNotUseSection: [],
      instructionsSection: [],
      longFile: [],
    };
  }

  try {
    const parsed = JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8'));
    return {
      useSection: Array.isArray(parsed.useSection) ? parsed.useSection : [],
      doNotUseSection: Array.isArray(parsed.doNotUseSection) ? parsed.doNotUseSection : [],
      instructionsSection: Array.isArray(parsed.instructionsSection) ? parsed.instructionsSection : [],
      longFile: Array.isArray(parsed.longFile) ? parsed.longFile : [],
    };
  } catch (err) {
    addWarning('Failed to parse validation-baseline.json; strict mode may fail.');
    return { useSection: [], doNotUseSection: [], instructionsSection: [], longFile: [] };
  }
}

function addStrictSectionErrors(label, missing, baselineSet) {
  if (!isStrict) return;
  const strictMissing = missing.filter(skillId => !baselineSet.has(skillId));
  if (strictMissing.length) {
    addError(`Missing "${label}" section (strict): ${strictMissing.length} skills (examples: ${strictMissing.slice(0, 5).join(', ')})`);
  }
}

const skillIds = listSkillIds(SKILLS_DIR);
const baseline = loadBaseline();
const baselineUse = new Set(baseline.useSection || []);
const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
const baselineInstructions = new Set(baseline.instructionsSection || []);
const baselineLongFile = new Set(baseline.longFile || []);

for (const skillId of skillIds) {
  const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');

  if (!fs.existsSync(skillPath)) {
    addError(`Missing SKILL.md: ${skillId}`);
    continue;
  }

  const content = fs.readFileSync(skillPath, 'utf8');
  const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
  const lineCount = content.split(/\r?\n/).length;

  if (!hasFrontmatter) {
    addError(`Missing frontmatter: ${skillId}`);
  }

  if (fmErrors && fmErrors.length) {
    fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
  }

  if (!NAME_PATTERN.test(skillId)) {
    addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
  }

  if (data.name !== undefined) {
    const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
    if (nameError) {
      addError(`${nameError} (${skillId})`);
    } else {
      const nameValue = String(data.name).trim();
      if (!NAME_PATTERN.test(nameValue)) {
        addError(`name must match ${NAME_PATTERN}: ${skillId}`);
      }
      if (nameValue !== skillId) {
        addError(`name must match folder name: ${skillId} -> ${nameValue}`);
      }
    }
  }

  const descError = data.description === undefined
    ? 'description is required.'
    : validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
  if (descError) {
    addError(`${descError} (${skillId})`);
  }

  if (data.license !== undefined) {
    const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
    if (licenseError) {
      addError(`${licenseError} (${skillId})`);
    }
  }

  if (data.compatibility !== undefined) {
    const compatibilityError = validateStringField(
      'compatibility',
      data.compatibility,
      { min: 1, max: MAX_COMPATIBILITY_LENGTH },
    );
    if (compatibilityError) {
      addError(`${compatibilityError} (${skillId})`);
    }
  }

  if (data['allowed-tools'] !== undefined) {
    if (typeof data['allowed-tools'] !== 'string') {
      addError(`allowed-tools must be a space-delimited string. (${skillId})`);
    } else if (!data['allowed-tools'].trim()) {
      addError(`allowed-tools cannot be empty. (${skillId})`);
    }
  }

  if (data.metadata !== undefined) {
    if (!isPlainObject(data.metadata)) {
      addError(`metadata must be a string map/object. (${skillId})`);
    } else {
      for (const [key, value] of Object.entries(data.metadata)) {
        if (typeof value !== 'string') {
          addError(`metadata.${key} must be a string. (${skillId})`);
        }
      }
    }
  }

  if (data && Object.keys(data).length) {
    const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
    if (unknownFields.length) {
      unknownFieldSkills.push(skillId);
      addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
    }
  }

  if (lineCount > MAX_SKILL_LINES) {
    longFiles.push(skillId);
  }

  if (!content.includes('## Use this skill when')) {
    missingUseSection.push(skillId);
  }

  if (!content.includes('## Do not use')) {
    missingDoNotUseSection.push(skillId);
  }

  if (!content.includes('## Instructions')) {
    missingInstructionsSection.push(skillId);
  }
}

if (missingUseSection.length) {
  addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
}

if (missingDoNotUseSection.length) {
  addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
}

if (missingInstructionsSection.length) {
  addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
}

if (longFiles.length) {
  addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
}

if (unknownFieldSkills.length) {
  addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
}

addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);

if (writeBaseline) {
  const baselineData = {
    generatedAt: new Date().toISOString(),
    useSection: [...missingUseSection].sort(),
    doNotUseSection: [...missingDoNotUseSection].sort(),
    instructionsSection: [...missingInstructionsSection].sort(),
    longFile: [...longFiles].sort(),
  };
  fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
  console.log(`Baseline written to ${BASELINE_PATH}`);
}

if (warnings.length) {
  console.warn('Warnings:');
  for (const warning of warnings) {
    console.warn(`- ${warning}`);
  }
}

if (errors.length) {
  console.error('\nErrors:');
  for (const error of errors) {
    console.error(`- ${error}`);
  }
  process.exit(1);
}

console.log(`Validation passed for ${skillIds.length} skills.`);