ipm-tools

module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: Apache-2.0

README

ipm-tools

Tooling for infinite.pm — Infinite Process Modeling (ipm / IPM), an experiment in applying Mark Burgess's Semantic Spacetime γ(3,4) to everyday modeling and software engineering.

This repository holds the command-line tools and Go libraries that parse, validate, lay out, and render ipmt — the infinite.pm text format for Semantic-Spacetime graphs — including the renderer that compiles the ipmt fenced blocks in ipm-intro into the SVG diagrams you see there, and the language server behind the VS Code extension.

For a gentle, example-driven introduction to the modeling language itself (events, things, concepts, and the four edge kinds), read ipm-intro. For the formal grammar, see docs/ipmt-spec.md.

Status

Prototype, spec-driven / vibe-coded by mj41, open-sourced as it stabilizes. APIs and the ipmt grammar may still change. Sponsors welcome.

Prerequisites

  • Go 1.25.4 or newer (see go.mod).

The pipeline

.ipmt ──ipmt-parse──▶ graph JSON ──layout-gen──▶ layout JSON ──ipmsvg-gen──▶ .ipm.svg
                              │
                              └────────ipm-validate (semantic checks)

md-embed drives that whole pipeline over Markdown files that contain fenced ```ipmt blocks; md-html then publishes those Markdown files as HTML, inlining the SVGs md-embed produced; ipm-rpc exposes the pipeline as a language server.

Commands

Command Purpose
ipmt-parse Parse .ipmt text into canonical graph JSON (nodes, edges, spans).
ipm-validate Run semantic graph validations against .ipmt, .md (with ipmt blocks), or graph JSON.
layout-gen Generate deterministic layout JSON from parsed graph JSON.
ipmsvg-gen Render the static SVG from .ipmt, graph JSON or layout JSON — the same renderer md-embed embeds.
md-embed In place, render ```ipmt blocks in a tree of Markdown files to SVG and insert image markers. Idempotent; suitable for pre-commit / CI.
md-html Render Markdown (with ipmt blocks + inline token highlighting) to standalone HTML.
ipm-rpc JSON-RPC / LSP server that renders and tokenizes ipmt for the VS Code extension.

Each command lives under cmd/<name> and accepts --help for its flags.

Quick start
# Parse ipmt to graph JSON
go run ./cmd/ipmt-parse --in examples/murder-simple.ipmt

# Full pipeline: ipmt -> layout -> SVG
go run ./cmd/layout-gen  --in examples/murder-simple.ipmt --out temp/murder.layout.json
go run ./cmd/ipmsvg-gen  --in temp/murder.layout.json     --out temp/murder.ipm.svg

# Render every ipmt block in a Markdown tree to SVG, in place
go run ./cmd/md-embed --root path/to/docs
Getting the binaries

Tagged releases carry the whole toolset — every shipping command, one archive per platform — on the releases page, with SHA256SUMS and build provenance. Unpack and put the binaries on your PATH.

With a Go toolchain, go install works per command:

go install github.com/infinite-pm/ipm-tools/cmd/ipm-rpc@latest

or build the whole set from a checkout:

make build-all   # all shipping commands into ./bin/
make build-rpc   # just the ipm-rpc LSP server (for the VS Code extension)

The VS Code extension is configured to find the language server through the ipm.serverPath setting (or ./bin on PATH). See docs/ipm-rpc.md.

Development

make test            # go test ./...
make layout-test     # layout regression suite (verbose)
make layout-fitness  # layout fitness score only
make layout-check    # universal-invariant ratchet (node overlaps, edges through boxes)

The layout regression corpora live under tests/layout-gen/ and tests/layout-gen-ext/; fixtures are autogenerated — see docs/dev/testing.md and agents.md. Developer tooling lives under cmd-dev/.

Documentation

All infinite.pm repositories live under the infinite-pm GitHub org.

Authors & credits

Created and maintained by mj41, spec-driven / "vibe-coded" with help from Claude (Opus) and other AI coding agents. See AUTHORS.md.

License

Apache License 2.0.

Directories

Path Synopsis
cmd
ipm-rpc command
Command ipm-rpc is the infinite.pm language server.
 Command ipm-rpc is the infinite.pm language server.
ipm-validate command
ipmsvg-gen command
ipmt-parse command
layout-gen command
md-embed command
Command md-embed renders ```ipmt``` blocks in Markdown files to SVG and inserts a marker comment + image link after each block referencing the rendered file.
 Command md-embed renders ```ipmt``` blocks in Markdown files to SVG and inserts a marker comment + image link after each block referencing the rendered file.
md-html command
md-html — exports `.md` files with ipmt embeds to static HTML.
 md-html — exports `.md` files with ipmt embeds to static HTML.
cmd-dev
gen-invalid-sidecars command
Command gen-invalid-sidecars (re)generates the rejection sidecars for the ipmt-invalid corpus (tests/ipmt/invalid/*.ipmt-invalid).
 Command gen-invalid-sidecars (re)generates the rejection sidecars for the ipmt-invalid corpus (tests/ipmt/invalid/*.ipmt-invalid).
gen-test-doc command
gen-test-md command
layout-debug command
Command layout-debug is the DEV triage view over the layout engine: fast, targeted, one fact per line, greppable and diffable — for an AI session or a human hunting one wrong edge — the debug half of the debug↔explain split (docs/dev/layout-gen/layout-debug.md).
 Command layout-debug is the DEV triage view over the layout engine: fast, targeted, one fact per line, greppable and diffable — for an AI session or a human hunting one wrong edge — the debug half of the debug↔explain split (docs/dev/layout-gen/layout-debug.md).
layout-explain command
Command layout-explain writes the NARRATED end-to-end report for ONE ipmt block — a single .ipmt file, or one block picked out of a markdown document — as a .md report.
 Command layout-explain writes the NARRATED end-to-end report for ONE ipmt block — a single .ipmt file, or one block picked out of a markdown document — as a .md report.
layout-test-runner command
refs-rehash command
slides-copy command
slides-copy — copies selected ipmt-embedded SVGs to flat, sequentially named slide files (e.g.
 slides-copy — copies selected ipmt-embedded SVGs to flat, sequentially named slide files (e.g.
solver-example command
Command solver-example runs the node-kind solver on ipmt and shows or verifies the result — a way to demonstrate, for different edge/type combinations, what the solver resolves undecided (::?etc) nodes to.
 Command solver-example runs the node-kind solver on ipmt and shows or verifies the result — a way to demonstrate, for different edge/type combinations, what the solver resolves undecided (::?etc) nodes to.
svg-edges command
sync-test-cases command
pkg
cli
dsltorules
filterutil
ipm/config
Package config reads the per-repo `.ipm.conf` file shared between cmd/md-embed, cmd/ipm-rpc, and any other infinite.pm Go toolchain entry point.
 Package config reads the per-repo `.ipm.conf` file shared between cmd/md-embed, cmd/ipm-rpc, and any other infinite.pm Go toolchain entry point.
ipm/log
Package log provides a thin convention layer on top of log/slog for the infinite.pm Go toolchain (cmd/md-embed, cmd/ipm-rpc, and the shared pkg/ipm/* packages).
 Package log provides a thin convention layer on top of log/slog for the infinite.pm Go toolchain (cmd/md-embed, cmd/ipm-rpc, and the shared pkg/ipm/* packages).
ipm/lspos
Package lspos translates between three coordinate systems used in language-server work:
 Package lspos translates between three coordinate systems used in language-server work:
ipm/model
ipm/parser
ipm/validate
Package validate runs semantic checks on a parsed IpmGraph, surfacing modelling problems the parser does not enforce.
 Package validate runs semantic checks on a parsed IpmGraph, surfacing modelling problems the parser does not enforce.
ipmsvg
ipmtext
Package ipmtext serializes a model.IpmGraph back to canonical ipmt text — the inverse of ipm-tools' ipmt parser.
 Package ipmtext serializes a model.IpmGraph back to canonical ipmt text — the inverse of ipm-tools' ipmt parser.
ipmtmeta
Package ipmtmeta defines the ipmt processing-pipeline flag vocabulary and the `# ipmt:` first-line pragma, and reconciles the two carriers of that metadata:
 Package ipmtmeta defines the ipmt processing-pipeline flag vocabulary and the `# ipmt:` first-line pragma, and reconciles the two carriers of that metadata:
ipmtokens
Package ipmtokens runs the ipmt semantic tokenizer used by both the LSP server (cmd/ipm-rpc) and the md-html exporter (pkg/mdhtml).
 Package ipmtokens runs the ipmt semantic tokenizer used by both the LSP server (cmd/ipm-rpc) and the md-html exporter (pkg/mdhtml).
l7report
Package l7report narrates layout7's decision trace (docs/dev/layout-gen/layout-debug.md): the engine emits structured TraceEvents through its one seam (layout7.Trace); this package collects them and renders the human-readable views — Text for the terminal (`layout-debug --why`) and Explain for the narrated pipeline-ordered report (`layout-explain`).
 Package l7report narrates layout7's decision trace (docs/dev/layout-gen/layout-debug.md): the engine emits structured TraceEvents through its one seam (layout7.Trace); this package collects them and renders the human-readable views — Text for the terminal (`layout-debug --why`) and Explain for the narrated pipeline-ordered report (`layout-explain`).
layout
Package layout generates positioned graph layouts from IPM documents.
 Package layout generates positioned graph layouts from IPM documents.
layout7
Package layout7 is the v7 layout engine: an implementation of the nine layout principles specified in gl:docs/dev/layout-gen/layout-principles.md (v7P1–v7P9).
 Package layout7 is the v7 layout engine: an implementation of the nine layout principles specified in gl:docs/dev/layout-gen/layout-principles.md (v7P1–v7P9).
layoutcheck
Package layoutcheck holds the UNIVERSAL visual invariants a layout must satisfy no matter its shape — node boxes must not overlap, a routed edge must not cut through or graze a box it is not connected to, edges must not cross/cover, stub badges and chips must keep clear of boxes, and unrelated boxes must not sit at band rhythm so they read as paired.
 Package layoutcheck holds the UNIVERSAL visual invariants a layout must satisfy no matter its shape — node boxes must not overlap, a routed edge must not cut through or graze a box it is not connected to, edges must not cross/cover, stub badges and chips must keep clear of boxes, and unrelated boxes must not sit at band rhythm so they read as paired.
layouttest
markdown
mdembed
Package mdembed implements the marker grammar, hash normalization, and SVG metadata embedding shared between cmd/md-embed and any other tool that needs to read or write in-place ipmt rendering markers in Markdown.
 Package mdembed implements the marker grammar, hash normalization, and SVG metadata embedding shared between cmd/md-embed and any other tool that needs to read or write in-place ipmt rendering markers in Markdown.
mdhtml
Package mdhtml exports `.md` → `.html` for ipmt-rich docs.
 Package mdhtml exports `.md` → `.html` for ipmt-rich docs.
nameutil
nodehints
Package nodehints defines per-node rendering hints consumed by the SVG generators (pkg/ipmsvg).
 Package nodehints defines per-node rendering hints consumed by the SVG generators (pkg/ipmsvg).
nodekind
Package nodekind resolves the event/thing/concept kind of every node and emits an ipm-oriented node+edge graph.
 Package nodekind resolves the event/thing/concept kind of every node and emits an ipm-oriented node+edge graph.
tagexpr
testconfig

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.