Jira progress: loading…

README — Framework Tag Validation Script

This script validates that all frameworkTags defined in the frontmatter of template MDX files are correctly registered in the system-level taxonomy located at:

/config/system/framework-tags.json

It ensures taxonomic consistency across ZAYAZ and prevents templates from referencing undefined or misspelled framework identifiers.

⸻

📌 What It Does

• Loads the official framework registry (framework-tags.json)
• Scans all policy templates:

/templates/policies/**/**/*.mdx

• Extracts frameworkTags from frontmatter
• Verifies that:
• Every tag exists in the registry
• No undefined tags are present
• Exits with:
• 0 if everything is valid
• 1 if unknown or missing tags are found

This script integrates naturally into CI (GitHub Actions), pre-commit hooks, or manual checks.

⸻

📁 File Structure

/config/system/framework-tags.json
/scripts/validate-framework-tags.ts
/templates/policies/.../*.mdx

⸻

▶️ Running the Script

Using ts-node (recommended for development)

npx ts-node scripts/validate-framework-tags.ts

If compiled to JavaScript

node scripts/validate-framework-tags.js

⸻

🔍 Output Examples

✔️ All good

✅ All frameworkTags in templates are defined in framework-tags.json

❌ Unknown tags found

❌ Unknown frameworkTags found in templates:

- ESRS_E99 in templates/policies/env/policy-env-climate-change-v1.mdx (templateId=tpl_policy_env_climate_change_v1)
- GRI_999 in templates/policies/social/policy-social-human-capital-labor-practices-v1.mdx (templateId=tpl_policy_social_human_capital_labor_practices_v1)

Add missing tags to config/system/framework-tags.json or fix typos in template frontmatter.

⸻

🧩 Typical Use Cases

• CI validation (GitHub Actions) Prevents merging templates with invalid framework references.
• Template migration Detects missing framework definitions when onboarding new templates.
• Taxonomy management Ensures global consistency across ZAYAZ, EcoWorld Academy, and the computation engines.

⸻

🚀 Next Steps (Optional Enhancements)

This script has been extended to additionally validate:

• templateId vs file name consistency
• slug consistency
• Cross-reference with template-registry.json
• Tag grouping compliance (framework-groups.json)

⸻

We maintain frontmatter in the MDX templates as the single source of truth.

npx ts-node scripts/generate-template-registry.ts
npx ts-node scripts/validate-templates.ts

• The first script generates:

  • config/system/template-registry.json
  • config/system/slug-map.json (policy_template entries)

• The second script validates:

  • Tags
  • Template/file/slug consistency
  • Registry ↔ MDX coherence
  • Slug-map ↔ registry coherence
  • Framework groups’ members vs framework-tags.json