Skip to content
TwoWellsPublic

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Lattice

crates.io docs.rs CI license

A markdown predicate linter and backlink reconciler, shipped as an LSP server.

Lattice encodes link predicates in CommonMark title text and maintains backlinks in YAML frontmatter. The graph lives in the files themselves — no database, everything in git.

Installation

cargo install lattice

Or download a prebuilt binary (Linux, macOS, Windows) from the latest release. Building from source needs Rust 1.95 or newer.

Usage

# Lint all markdown files in the current project (exit 1 on errors)
lattice lint

# Run as an LSP server (used by editors)
lattice serve

# Print the full configuration reference (every option, with defaults)
lattice config

# Print the version (with git commit and dirty state)
lattice --version

Neovim

Lattice is not shipped by nvim-lspconfig, so configure it directly. On Neovim 0.11+:

vim.lsp.config.lattice = {
  cmd = { "lattice", "serve" },
  filetypes = { "markdown" },
  root_markers = { ".lattice.toml", ".git" },
}
vim.lsp.enable("lattice")

Diagnostics appear inline on open, change, and save. When the editor supports LSP dynamic file-watch registration (workspace/didChangeWatchedFiles), Lattice also registers watches for .lattice.toml and project .md files, so config edits hot-reload (no restart) and on-disk changes made outside the editor (e.g. a git checkout) update the graph live; without that support, both apply only on restart. Lattice is diagnostic-first, but the server is a full markdown LSP: completion (paths, headings, predicates, reference labels, footnotes), hover, document and workspace symbols, references, rename, folding, document links, formatting, semantic tokens (emphasis styling, below), and go-to-definition/declaration/type/implementation plus call and type hierarchy over the predicate graph.

Emphasis styling (semantic tokens)

Lattice emits semantic tokens for emphasis runs: one token type, markup, carrying bold, italic, and strikethrough modifiers. Neovim maps each modifier to an @lsp.mod.<name> highlight group, and neither Neovim core nor common colorschemes define these, so the tokens paint nothing until you do — once, after your colorscheme loads (a ColorScheme autocmd survives reloads):

vim.api.nvim_set_hl(0, "@lsp.mod.bold", { bold = true })
vim.api.nvim_set_hl(0, "@lsp.mod.italic", { italic = true })
vim.api.nvim_set_hl(0, "@lsp.mod.strikethrough", { strikethrough = true })

Tokens are served for any opened markdown document, rooted or not: a scratch file outside every workspace root (a note in /tmp, say) gets the same emphasis styling as a project file. Workspace roots gate only the graph-linting tier — backlinks, predicates, connectivity.

Treesitter's own markdown emphasis highlighting stays active alongside, and extmark attributes merge — so a span the grammar gets wrong stays lit no matter what Lattice says (tree-sitter-markdown-inline approximates GFM flanking rules and will, for example, pair a single-tilde strikethrough across a soft line break). To hand emphasis styling to Lattice entirely, blank the language-qualified treesitter groups; the qualified name shadows the generic @markup.* for markdown only, and every other filetype keeps its styling:

vim.api.nvim_set_hl(0, "@markup.strong.markdown_inline", {})
vim.api.nvim_set_hl(0, "@markup.italic.markdown_inline", {})
vim.api.nvim_set_hl(0, "@markup.strikethrough.markdown_inline", {})

Leave treesitter itself enabled for markdown: it still provides the structural highlighting (headings, links, code spans) and the injected highlighting inside fenced code blocks; only its emphasis captures go quiet. Emphasis styling then updates at semantic-token cadence (on server response) rather than per keystroke.

On Neovim older than 0.11, start it per buffer instead:

vim.api.nvim_create_autocmd("FileType", {
  pattern = "markdown",
  callback = function(args)
    vim.lsp.start({
      name = "lattice",
      cmd = { "lattice", "serve" },
      root_dir = vim.fs.root(args.buf, { ".lattice.toml", ".git" }),
    })
  end,
})

Continuous integration and hooks

Both lattice lint and lattice format --check share one exit-code contract, so they slot into any gate: exit 0 = clean, exit 1 = errors (a broken link, unknown predicate, or unformatted frontmatter). Warnings — missing backlinks, bare paths — do not fail the build; pass --strict to lattice lint to gate on those too. So a PR with a broken link fails, a warnings-only PR passes, and a clean project passes silently.

lattice format --check writes nothing: it exits 1 and lists any file whose backlink frontmatter is not sorted/normalized, and exits 0 when every file is already formatted. Run lattice format (no --check) to rewrite them in place — this is a graph no-op, changing only frontmatter bytes, never the diagnostics lattice lint produces.

Both commands check the scope they are invoked in and stop at every nested-scope boundary (see Nested scopes): one invocation, one graph. In a repository containing nested scopes, run each once from every marker directory.

GitHub Actions

Reference the bundled composite action from a workflow. It installs lattice, runs lattice lint, then lattice format --check:

# .github/workflows/lattice.yml
name: Lattice
on: [push, pull_request]
jobs:
  lattice:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: TwoWells/Lattice/.github/actions/lattice@v1
        # with:
        #   version: "0.4.1"    # pin a crates.io version (default: latest)
        #   path: "docs"        # scope to a subtree (default: repo root)
        #   strict: "true"      # also fail on warnings (default: false)
        #   format-check: "false" # skip the format gate (default: true)

Pre-commit

For projects using pre-commit, add Lattice as a hook repo in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/TwoWells/Lattice
    rev: v0.4.1
    hooks:
      - id: lattice-lint
      - id: lattice-format-check

lattice-format-check fails the commit on unformatted frontmatter; run lattice format to fix it. Drop the lattice-format-check entry if you only want the graph lint.

Plain git hook

Without pre-commit, add to .githooks/pre-commit or .git/hooks/pre-commit:

#!/bin/sh
lattice lint && lattice format --check

Commits with broken links, unknown predicates, missing backlinks, or unformatted frontmatter will be rejected.

Configuration

An optional .lattice.toml at the project root overrides defaults:

[predicates]
supersedes = "superseded_by"
implements = "implemented_by"
depends_on = "dependency_of"
amends = "amended_by"
blocks = "blocked_by"
references = "referenced_by"

[policy]
predicates = "optional"    # or "required"
backlinks = true
bare_paths = "warn"        # or "deny", "disabled"
stale_references = "warn"  # or "hint", "deny", "disabled" — dangling `.md` references
# fragments = "github"    # or "gitlab", "vscode"; omit to try all
# connectivity = "off"    # or "no-orphans", "no-islands", "reachable"
# roots = ["README.md"]   # entry points for "reachable"; default = root README

# Opt-in convention checks (off by default — they flag valid CommonMark, not defects):
# code_block_language = "disabled"  # or "hint", "warn", "deny" — flag untagged code fences
# multiple_h1 = false               # flag more than one H1 heading
# skipped_heading_level = false     # flag a skipped heading level (e.g. H1 -> H3)
# image_empty_alt = false           # flag images with empty alt text

# Cross-repo references: a `{Name}/path` citation (backtick/quoted/bare, not a
# link) is checked existence-only against an aliased directory — never read,
# indexed, or treated as a graph edge. An undefined alias, or one whose
# directory is absent, is exempt; a present directory with a missing file is a
# stale reference. Relative (sibling-checkout) values are preferred.
# [external]
# Themis = "../Themis"

Nested scopes

A .lattice.toml marks the root of a graph. A nested .lattice.toml (or a nested .git — a submodule or vendored repo) marks the root of a different, smaller graph: the marker partitions the tree into disjoint scopes, each self-describing under its own marker (never the outer vocabulary), and each behaving exactly as if it were a sibling. Membership stops at every strictly-deeper marker, so no backlink expectation crosses a boundary in either direction. Discovery is entry-point independent — linting from the outer root, from inside the nested scope, or via an editor session rooted at either agrees on where each graph begins. A nested .git without its own .lattice.toml is a non-root environment: excluded from the host graph and never indexed.

A plain relative link (or a ../ escape) whose target lands in another scope is a defect, not a reference — it errors with link target … is outside this scope — reference it through an [external] alias (a boundary-crossing path-shaped mention is its warn-tier sibling). Rewrite it as a {Name}/path citation and alias Name in the referrer's own [external] table. Reach for a nested marker when a subtree is a separable unit (its own graph); reach for an [[override]] when a subtree just wants different strictness within one graph.

Migration. Before this release a nested .lattice.toml was inert — its subtree was swallowed into the outer graph. It now splits into its own graph: cross-boundary plain links surface as steering errors, and stale backlink entries across the boundary become removable. This is a one-time, diagnostic-guided cleanup; stage large ones with [[override]] count-keys.

Per-reference exceptions

A path-shaped string that is deliberately not a live reference (a worked example, a counterexample, a knowingly-dead link) can be excepted from the stale_references / bare_paths lints in the document's own frontmatter, keyed by the literal reference with a required reason as the value:

---
exceptions:
  stale_references:
    "tickets/acquire/DESIGN.md": "hypothetical path in the worked example"
    "{Themis}/old/layout.md": "pre-refactor path, kept for the changelog note"
  bare_paths:
    "README.md": "naming the file, deliberately not a link"
---

Exceptions are reconciled like backlinks, not silenced: an entry that matches no live diagnostic — its reference gone, or now resolving — is itself flagged as an unused exception whose message echoes the stored reason, and an entry with an empty reason is flagged too. Lattice flags, never auto-removes — the reason is the surviving record of a vanished reference's intent. A {Name}/… key flows through identically. An exception is never a graph edge and imposes no backlink obligation.

Agent instructions

Add this to your project's AGENTS or CLAUDE file:

Markdown links follow Lattice conventions: predicates are encoded in title text, e.g. [Doc](doc.md "supersedes"). The predicate vocabulary is: supersedes, implements, depends_on, amends, blocks, references. Backlinks are maintained in YAML frontmatter.

License

AGPL-3.0-or-later. Commercial license available — contact Two Wells.

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages