review-dita-guide

Validates an entire DITA guide by walking the full publication hierarchy from a root bookmap or ditamap down through all referenced child maps and leaf topics.

When to use

• Before a DITA-OT build to catch issues across the whole publication
• After restructuring a guide (moving topics, nesting new child maps)
• During CI/CD to gate publishing on guide-wide validity
• When auditing a large guide for quality and best-practice compliance

What is checked

Per-file (each map and topic)

• DTD structural validity (via validate_bookmap, validate_ditamap, validate_dita_topic)
• Best practices (shortdesc, step count, nesting depth, duplicate paragraphs) when --best-practices is supplied

Cross-guide (spanning multiple files)

Output schema

{
  "root":    "<path>",
  "summary": {
    "total_files": 12,
    "maps": 2, "topics": 10, "missing": 0,
    "valid_files": 12, "invalid_files": 0,
    "errors": 0, "warnings": 3,
    "cross_guide_issues": 0
  },
  "files": [
    {
      "path": "relative/path.dita",
      "type": "topic|map|bookmap|missing",
      "depth": 1,
      "is_valid": true,
      "errors": [],
      "warnings": [],
      "best_practices": []
    }
  ],
  "cross_guide": [
    { "rule": "duplicate-guide-id", "message": "...", "paths": ["a.dita","b.dita"] }
  ]
}

Exit codes

• 0 — all files valid, no cross-guide errors
• 1 — one or more errors found
• 2 — usage or IO error