shapelang

Shape

Shape is a typed architecture conformance language for making architectural claims explicit and checkable.

Application code can be messy, implicit, and spread across many files. Shape gives the system a small human-readable model in .shape files:

• resources, traits, and invariants
• components, ownership, capabilities, and structural relations
• function effect summaries with source evidence
• model updates for architecture changes
• coverage rules for governed source paths
• bindings that require paired review-surface changes, such as docs updates
• typed design memory for refactor-sensitive functions
• constrained project rules such as hypercycle bans over the structural hypergraph

The checker does not prove the application implementation is correct. It checks that the declared architecture model is coherent. That is the product boundary: humans and LLMs write reviewable claims, then a deterministic checker accepts or rejects those claims.

Quick Start

Install the released shp typechecker binary. Pin the version in scripts and CI so checks are reproducible.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/timbrinded/shapelang/releases/download/v0.4.1/install.sh | sh

On Windows:

irm https://github.com/timbrinded/shapelang/releases/download/v0.4.1/install.ps1 | iex

Run the checker from a repo that contains Shape files:

shp check
shp fmt --check
shp coverage --changed-files changed.txt
shp memory
shp obligations

For local developer installs, update the released binary explicitly:

shp update
shp update --dry-run

shp update --path PATH can replace a custom install path, but an existing target must already identify itself as the Shape CLI and report a valid version.

shp check scans these paths when no files are provided:

shape/**/*.shape

In GitHub Actions, install the same pinned release with the setup action:

steps:
  - uses: actions/checkout@v4
  - uses: timbrinded/shapelang@v0.4.1
  - run: shp check

Manual archive downloads are available on the GitHub release if you do not want to run the installer script.

What It Catches

The first core use case is append-only resource protection.

If a resource is declared AppendOnly, then a function that emits HardDelete<Resource> is rejected even if the component grants that effect. Final forbids win over grants.

Shape also covers:

• unknown effects in protected components
• missing grants for declared function effects
• governed source files changed without a Shape update or current attestation
• Shape-affecting files changed without a bound docs update or docs_not_needed attestation
• refactor-sensitive functions changed without a recorded reevaluation
• required design context or descriptions missing from non-obvious function shapes
• semantic hypercycles in the structural hypergraph with witness paths
• project-specific rules like "only Gateway may provide JsonRpcEndpoint", expressed over provides relation hyperedges
• optional analyzer hints for obvious DELETE, TRUNCATE, and DROP operations

See Refactor Constraints for the design-memory workflow around rationale, memory, and reevaluation.

Example Shape File

Shape files use the .shape extension. This example declares an append-only audit resource and two allowed functions:

module audit

trait AppendOnly<T: Resource> {
  allow Append<T>
  allow Read<T>
  forbid final DropStorage<T>
  forbid final HardDelete<T>
  forbid final Truncate<T>
}

resource AuditEvent : AppendOnly

component AuditStore {
  owns AuditEvent
  grants Append<AuditEvent>
  grants Read<AuditEvent>

  fn appendEvent
    source ts("src/audit/store.ts#appendEvent")
    effects complete {
      Append<AuditEvent>
        evidence ts("src/audit/store.ts:8-14")
    }

  fn listEvents
    source ts("src/audit/store.ts#listEvents")
    effects complete {
      Read<AuditEvent>
        evidence ts("src/audit/store.ts:18-25")
    }
}

A source-backed model update can add a new function directly to the global Shape model:

module audit

component AuditStore {
  grants HardDelete<AuditEvent>
  fn purgeOldEvents
    source ts("src/audit/purge.ts#purgeOldEvents")
    effects complete {
      HardDelete<AuditEvent>
        evidence ts("src/audit/purge.ts:12-16")
    }
}

That model update fails because AuditEvent : AppendOnly derives a final forbid for HardDelete<AuditEvent>.

How It Works

The checker pipeline is:

1. Parse .shape files with Langium.
2. Lower declarations into facts such as resources, traits, effects, grants, relation hyperedges, and governed paths.
3. Evaluate deterministic rules.
4. Emit diagnostics with provenance, including the declarations that caused a violation.