Knowledge Base Scripts Tutorial & Maintenance Guide

This tutorial provides a complete guide for using the maintenance scripts in knowledge-base/. These tools maintain relationships between terms, validate markdown links, enforce DAG (acyclic) prerequisites, ensure bidirectional related-term symmetry, and generate Zero-to-Hero learning paths.

---

🛠️ Maintained Scripts Overview

---

🚀 1. Validation & Integrity (validate_relationships.js)

validate_relationships.js is the core quality assurance tool for the knowledge base. It is also executed automatically by the git pre-commit hook when staging relationship files.

Common Usage Commands

# Validate all 14 technology modules across the entire repository
node knowledge-base/validate_relationships.js

# Validate a single specific module (e.g., 15-rust or 03-javascript)
node knowledge-base/validate_relationships.js --module 15-rust

What It Validates

1. File Consistency: Every term in _meta/relationships.json has a corresponding .md file on disk, and vice versa.
2. Prerequisite & Related Link Sync: Edges declared in .md files match relationships.json.
3. DAG Non-Cyclicity: Prerequisite relationships form a strict Directed Acyclic Graph (no cyclic dependencies).
4. Bidirectional Symmetry: Intra-module related links must be reciprocal (if A relates to B, B must relate to A).
5. Cross-Module Edges: External references target valid existing modules and terms.

---

🔄 2. Bi-directional Synchronization (sync_relationships.js)

When creating new terms or updating prerequisite/related links, use sync_relationships.js to synchronize between relationships.json and markdown term files.

Workflow Modes

Mode A: Update Markdown files from relationships.json (--from-json)

Use this mode when you edit _meta/relationships.json directly and want to update ## Prerequisites and ## Related Terms sections in all .md files.

# Preview changes across all modules (dry run)
node knowledge-base/sync_relationships.js --from-json

# Apply changes to a specific module
node knowledge-base/sync_relationships.js --from-json --module 03-javascript --apply

Mode B: Update relationships.json from Markdown files (--from-files)

Use this mode when you add or edit prerequisite/related links directly inside markdown term files.

# Update relationships.json from markdown files for a specific module
node knowledge-base/sync_relationships.js --from-files --module 13-mongodb --apply

Mode C: View Differences (--diff)

# Show discrepancies between JSON metadata and markdown files
node knowledge-base/sync_relationships.js --diff

---

🌐 3. Global Index Generation (build_cross_module_index.js)

Cross-module edges (e.g., Rust referencing C++ or Next.js referencing React) are aggregated into a global index at knowledge-base/_meta/cross_module_edges.json.

# Rebuild the global cross-module edge index
node knowledge-base/build_cross_module_index.js

---

🛠️ 4. Relationship Auto-Repair (fix_relationships.js)

fix_relationships.js automatically repairs common relationship metadata issues in relationships.json, such as adding missing reciprocal related links and registering untracked term files.

# Auto-repair relationship symmetry and missing entries
node knowledge-base/fix_relationships.js

---

🔗 5. Link Checking & Auto-Fixing (check_links.js & fix_markdown_links.js)

Keep markdown relative links clean and working with link validation tools.

# Scan for broken markdown file links
node knowledge-base/check_links.js

# Automatically repair malformed relative links across all modules
node knowledge-base/fix_markdown_links.js --all

# Automatically repair links for a single module
node knowledge-base/fix_markdown_links.js 14-surrealdb

---

🎓 6. Zero-to-Hero Roadmap Generation (sync_zero_hero.js)

Each module includes a *_terms_zero_to_hero.md file (e.g., rust_terms_zero_to_hero.md) providing a level-by-level structured learning pathway.

# Preview Zero-to-Hero roadmap changes
node knowledge-base/sync_zero_hero.js

# Regenerate and apply Zero-to-Hero roadmap files for all modules
node knowledge-base/sync_zero_hero.js --apply

---

📋 Recommended Workflow for Adding / Editing Terms

1. Create or Edit Term Markdown Files: Add or update terms under knowledge-base/<module>/terms/level_XX/.
2. Synchronize Metadata:

   node knowledge-base/sync_relationships.js --from-files --module <module> --apply
   

3. Repair Relationship Symmetry:

   node knowledge-base/fix_relationships.js
   

4. Validate Everything:

   node knowledge-base/validate_relationships.js
   

5. Rebuild Cross-Module & Roadmap Files:

   node knowledge-base/build_cross_module_index.js
   node knowledge-base/sync_zero_hero.js --apply