Implement Comprehensive Markdown Documentation Generation

[unclesp1d3r]

Implement Comprehensive Markdown Documentation Generation

Overview

Replace placeholder Markdown generation with comprehensive, production-ready documentation. Generate detailed schema documentation with tables, columns, constraints, indexes, foreign keys, and metadata.

Scope

What's Included:

• Implement full Markdown generation in generate_markdown() in file:dbsurveyor/src/main.rs:
  • Header section: Database name, version, collection date, collector version
  • Summary section: Object counts (tables, views, indexes, constraints, procedures, functions, triggers)
  • Table of Contents: Clickable links to all sections
  • Tables section: For each table:
    • Table name, comment, row count
    • Columns table with: name, type, nullable, default, primary key, auto-increment, comment
    • Primary key details
    • Foreign keys table with: name, columns, referenced table, referenced columns, on delete, on update
    • Indexes table with: name, columns, unique, type
    • Constraints table with: name, type, columns, check clause
  • Views section: View name, definition (if available), comment
  • Procedures section: Procedure name, parameters, definition (if available)
  • Functions section: Function name, parameters, return type, definition (if available)
  • Triggers section: Trigger name, table, timing, event, definition (if available)
  • Custom Types section: Type name, definition
  • Collection Metadata section: Warnings, collection duration, object failures (if any)
• Add data redaction support:
  • Respect --redact-mode flag from CLI
  • Redact sample data based on redaction mode (None, Minimal, Balanced, Conservative)
  • Redact column names that match PII patterns (email, ssn, password, etc.)
• Add Markdown formatting utilities:
  • Table generation helper
  • Code block formatting
  • Link generation for internal references
• Handle multi-database bundles:
  • Combined mode: Generate sections for each database
  • Split mode: Generate separate files per database
• Add unit tests for Markdown generation
• Add integration tests with real schema files

What's Explicitly Out:

• Mermaid ERD diagram generation (separate ticket)
• HTML conversion (separate ticket)
• Advanced formatting (syntax highlighting, collapsible sections) (deferred)

Markdown Structure Example

# Database Schema: production_db

Generated by DBSurveyor v1.0.0
Collection Date: 2026-02-07 14:30:00 UTC

## Summary

- **Tables**: 25
- **Views**: 5
- **Indexes**: 47
- **Constraints**: 38
- **Procedures**: 3
- **Functions**: 7
- **Triggers**: 2

## Table of Contents

- [Tables](#tables)
  - [users](#table-users)
  - [orders](#table-orders)
- [Views](#views)
- [Procedures](#procedures)
...

## Tables

### Table: users

**Comment**: User account information
**Estimated Rows**: 10,523

#### Columns

| Name | Type | Nullable | Default | Primary Key | Auto Increment | Comment |
|------|------|----------|---------|-------------|----------------|---------|
| id | INTEGER | No | - | Yes | Yes | User ID |
| email | VARCHAR(255) | No | - | No | No | Email address |
| created_at | TIMESTAMP | No | CURRENT_TIMESTAMP | No | No | Account creation time |

#### Primary Key

- **Name**: users_pkey
- **Columns**: id

#### Foreign Keys

| Name | Columns | Referenced Table | Referenced Columns | On Delete | On Update |
|------|---------|------------------|--------------------|-----------|-----------|
| fk_user_role | role_id | roles | id | CASCADE | CASCADE |

...

Acceptance Criteria

• Markdown generation produces comprehensive documentation with all schema objects
• Tables section includes columns, primary keys, foreign keys, indexes, constraints
• Views, procedures, functions, triggers sections include relevant metadata
• Collection metadata section shows warnings and object failures
• Data redaction works correctly based on --redact-mode flag
• Multi-database bundles generate combined or split Markdown based on CLI flags
• Generated Markdown is valid and renders correctly in standard viewers
• Unit tests verify Markdown formatting and structure
• Integration tests verify documentation generation with real schema files
• Documentation is readable and useful for DBAs and developers

References

• Spec: spec:de2eeeb8-bfeb-4a11-98aa-84efc70568b2/820ca524-8c7d-4939-8097-f1158e7d67ea (Tech Plan - Postprocessor)
• Core Flows: spec:de2eeeb8-bfeb-4a11-98aa-84efc70568b2/661dbe3d-b679-4287-991e-26f4a0dd98b9 (Flow 3 - documentation generation)
• Epic Brief: spec:de2eeeb8-bfeb-4a11-98aa-84efc70568b2/64fc1d47-e1e3-40db-a5dc-8dc9c248814c (v1.0 Must Have - Markdown documentation)

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#42 - feat: implement dual-binary architecture with CI fixes for test race conditions and security audit [merged]
#52 - feat: implement database engine adapters and CI/CD pipeline enhancements [merged]

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[dosubot]

Created page: https://app.dosu.dev/documents/99fc823a-bdec-4539-8363-7171923a1dc3

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}