Integrations - Tessera Design Toolkit

Why Automate?

Plain-text files + Git + CI/CD = automatic quality gates for your engineering data. Catch issues before they become problems.

✓ Validate schemas on every commit

✓ Ensure traceability coverage

✓ Detect broken links automatically

✓ Generate reports on release

✓ Block merges with failing tests

✓ Change history with git

GitHub Actions

Add validation to your CI/CD pipeline. This workflow validates all Tessera files, checks traceability, and generates reports on every push.

.github/workflows/tdt-validate.yml YAML

name: Tessera Validation

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-action@stable

      - name: Install Tessera
        run: cargo install tessera-design-toolkit

      - name: Validate all entities
        run: tdt validate --strict

      - name: Check traceability coverage
        run: |
          coverage=$(tdt trace matrix --rvm -f json | jq '.coverage')
          if (( $(echo "$coverage < 80" | bc -l) )); then
            echo "::error::Traceability coverage below 80%: $coverage%"
            exit 1
          fi

      - name: Check for high-risk items
        run: |
          high_risk=$(tdt risk list --min-rpn 100 --count)
          if [ "$high_risk" -gt 0 ]; then
            echo "::warning::$high_risk unmitigated high-risk items"
          fi

.github/workflows/tdt-reports.yml YAML

name: Generate Reports

on:
  release:
    types: [published]

jobs:
  reports:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-action@stable

      - name: Install Tessera
        run: cargo install tessera-design-toolkit

      - name: Generate all reports
        run: |
          mkdir -p reports
          tdt report bom -f md > reports/bom.md
          tdt report fmea -f md > reports/fmea.md
          tdt report rvm -f md > reports/rvm.md
          tdt dsm -o dot > reports/architecture.dot

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: tdt-reports
          path: reports/

Pre-commit Hooks

Catch issues before they're committed. These hooks validate Tessera files locally, ensuring only valid data enters your repository.

.pre-commit-config.yaml YAML

repos:
  - repo: local
    hooks:
      - id: tdt-validate
        name: Validate Tessera files
        entry: tdt validate
        language: system
        files: '\.tdt\.yaml$'
        pass_filenames: false

      - id: tdt-check-links
        name: Check entity links
        entry: tdt validate --check-links
        language: system
        files: '\.tdt\.yaml$'
        pass_filenames: false

Installing pre-commit hooks

# Install pre-commit
$ pip install pre-commit

# Install the hooks
$ pre-commit install

# Now validation runs automatically on commit
$ git commit -m "Update motor requirements"
Validate Tessera files..................................................Passed
Check entity links....................................................Passed
[main 3a5bc12] Update motor requirements

Manual Git Hooks

For teams not using pre-commit, you can set up hooks directly in your repository.

.git/hooks/pre-commit Bash

#!/bin/bash
# Tessera validation pre-commit hook

echo "Validating Tessera files..."

if ! tdt validate; then
    echo "Tessera validation failed. Fix errors before committing."
    exit 1
fi

# Check for orphaned requirements
orphans=$(tdt trace orphans --count)
if [ "$orphans" -gt 0 ]; then
    echo "Warning: $orphans orphaned requirements found"
    tdt trace orphans
fi

exit 0

SysML v2 Interchange

Export project data to SysML v2 textual notation for use with MBSE tools (Cameo, Capella, etc.), or import SysML v2 files to populate your Tessera project. Full round-trip fidelity with metadata preservation.

✓ Requirements as requirement def with doc blocks

✓ Tests as verification def with method annotations

✓ Components as part def elements

✓ Traceability via satisfy and verify relationships

✓ Round-trip ID and metadata preservation

✓ Test results as structured comments with verdicts

SysML v2 Export & Import

# Export entire project to SysML v2 textual notation
$ tdt export sysml -f model.sysml
✓ Exported 7 requirements, 4 tests, 4 results, 3 components

# Preview the generated SysML
$ tdt export sysml --package MyProject
package MyProject {
    import Requirements::*;
    import VerificationCases::*;

    requirement def <'REQ-01KC8FF44V...'> StrokeLength {
        doc /* The actuator shall have a min stroke of 100mm. */
        @TdtMetadata { status = approved; author = "Jack"; }
    }

    verification def <'TEST-01KC99PD5A...'> ShaftClearanceCheck {
        doc /* Verify shaft-bushing clearance. */
        @VerificationMethod { kind = VerificationMethodKind::inspect; }
        objective { verify requirement : StrokeLength; }
        return verdict : VerdictKind;
    }

    part def <'CMP-01KC8FHP5Z...'> ActuatorShaft;

    satisfy requirement : StrokeLength by ActuatorShaft;
}

# Import a SysML file into a Tessera project
$ tdt import sysml model.sysml
✓ Imported 7 requirements, 4 tests, 3 components
  Links: 4 verified_by, 3 satisfied_by

# Dry-run to preview import without writing files
$ tdt import sysml model.sysml --dry-run

External Tool Integration

Tessera's JSON and CSV exports integrate with any tool in your workflow.

📊

Excel / Sheets

Export CSV for spreadsheet analysis, cost modeling, or stakeholder review.

🐍

Python / Pandas

Load JSON directly into DataFrames for custom analysis and visualization.

📈

Graphviz

Generate architecture diagrams from DSM DOT output.

⚙

SysML v2 / MBSE

Export and import SysML v2 textual notation for Cameo, Capella, and other MBSE tools.

🤖

AI Assistants

Plain text works perfectly with Claude, ChatGPT, and Copilot.

Integration Examples

# Import into Python
$ python3 << 'EOF'
import json
import subprocess

result = subprocess.run(['tdt', 'risk', 'list', '-f', 'json'], capture_output=True)
risks = json.loads(result.stdout)

high_risk = [r for r in risks if r.get('rpn', 0) > 100]
print(f"High-risk items: {len(high_risk)}")
EOF
High-risk items: 2

# Generate architecture diagram
$ tdt dsm -o dot | dot -Tsvg -o architecture.svg

# Query with jq
$ tdt cmp list -f json | jq '[.[] | select(.category=="mechanical")] | length'
12

# Send to AI assistant
$ cat requirements/inputs/*.yaml | claude "Review these requirements for completeness"

Design Baselines

Create tagged baselines at design milestones and compare changes between versions. See the workflow documentation for complete git integration details.

Baseline Management

# Create a baseline at design freeze
$ tdt baseline create v1.0-design-freeze
✓ Created baseline: tdt-v1.0-design-freeze

# Continue development...
$ tdt req new --title "Add thermal monitoring" -t input --no-edit
$ tdt risk new --title "Overheating risk" -t design --no-edit

# Create another baseline
$ tdt baseline create v2.0-release
✓ Created baseline: tdt-v2.0-release

# Compare changes between baselines
$ tdt baseline compare tdt-v1.0-design-freeze tdt-v2.0-release

Changes between v1.0-design-freeze and v2.0-release:
──────────────────────────────────────────────────────
Added:
  + REQ-01KC5D... "Add thermal monitoring"
  + RISK-01KC5E... "Overheating risk"
  + TEST-01KC5F... "Thermal test protocol"

Modified:
  ~ CMP-01HC2J... "Motor Assembly" (revision 2 → 3)

Deleted:
  (none)

Summary: +3 added, 1 modified, 0 deleted