pd-vibe: CLI tooling for semantic diff, documentation, and structured workflows in Pure Data

Hello Pure Data community,

I would like to share a project I've been working on called **pd-vibe**, an open-source CLI toolkit designed to make Pure Data patches easier to analyze, maintain, and integrate into modern development workflows.

Repository: https://github.com/BorisMolch/pd-vibe

pd-vibe builds on top of the pd file format and pdpy, providing higher-level tooling for semantic understanding, safe editing, documentation generation, and automation.

The goal is to make Pure Data patches more maintainable, reviewable, and automation-friendly, especially for larger or long-term projects.

---

## Feature Highlights

### pd2ir — IR/DSL conversion and analysis

Convert `.pd` patches into an intermediate representation (IR) or DSL for structured analysis and tooling.

Features:

- `pd2ir`: IR/DSL conversion for fast patch understanding
- `--indices`: include stable node indices for referencing objects
- `--annotate`: add structural annotations
- `--state`: extract state and structure information
- `--doc`: generate documentation artifacts from IR
- `--doc-json`: export documentation in machine-readable JSON format
- `--watch`: automatically convert modified `.pd` files during development
- `--screenshot`: generate Pd-rendered PNG screenshots of patches (macOS)

---

### pdpatch — safe CLI editing

Provides structural editing of `.pd` files while preserving file integrity and format consistency.

Examples:

- add objects
- inspect patch structure
- modify connections safely

Designed to avoid corruption risks associated with manual text editing.

---

### pddiff — semantic diff for Pure Data patches

Provides meaningful diffs based on patch structure rather than raw text differences.

Features:

- semantic patch comparison
- easier code review and change tracking
- Git difftool integration support

---

### pd-docs — living documentation pipeline

A complete documentation workflow for Pure Data projects.

Commands:

- `pd-docs init` — initialize documentation structure
- `pd-docs check` — verify documentation consistency
- `pd-docs drift` — detect stale documentation
- `pd-docs report` — generate coverage reports
- `pd-docs update` — refresh documentation artifacts
- `pd-docs html` — generate browsable documentation

---

### Documentation drift detection

`pd-docs drift` supports:

- hash-based stale documentation detection
- timestamp mode (`-t`) for lightweight checking
- CI integration
- local workflow validation

This helps ensure documentation remains synchronized with patch changes.

---

## Use cases

pd-vibe is intended to support workflows such as:

- maintaining large or complex Pure Data projects
- enabling meaningful version control diffs
- automated documentation generation
- CI validation
- structured patch analysis
- tooling and ecosystem development

---

## Project status

The project is currently in early development and evolving.

Feedback, ideas, and contributions are welcome.

If you have suggestions, workflow ideas, or use cases, I would be very interested to hear them.

Repository:  
https://github.com/BorisMolch/pd-vibe

---

Thank you,  
Boris
---
[email protected] - the Pure Data mailinglist
https://lists.iem.at/hyperkitty/list/[email protected]/message/35DGUASWHSJGWL3NFUAFKFE7UM7HBWIO/

To unsubscribe send an email to [email protected] mailing list
UNSUBSCRIBE and account-management -> https://lists.iem.at/