@traceweave/trf

Unified CLI for TRF (Traceability Report Framework) - validates, builds, analyzes, and queries .twpack files

Installation

npm install -g @traceweave/trf

Usage

The trf command provides a unified interface to all Track 2 packages:

Validate

Validate .twpack files against TRF 2.1 schemas:

# Validate a single file
trf validate my-pack.twpack

# Validate multiple files
trf validate pack1.twpack pack2.twpack pack3.twpack

# Verbose mode
trf validate my-pack.twpack --verbose

# Quiet mode (only errors)
trf validate my-pack.twpack --quiet

Build

Create .twpack files from JSON sources:

trf build create \
  --id "automotive:brake-system:v1.0" \
  --title "Brake System Traceability" \
  --artifacts ./artifacts.json \
  --links ./links.json \
  --output ./brake-system.twpack \
  --profile "automotive-safety-iso26262"

Analyze

Perform graph analytics:

# Show graph statistics
trf analyze stats -f my-pack.twpack

# Impact analysis
trf analyze impact -f my-pack.twpack -a req:BRAKE-001

# Coverage analysis
trf analyze coverage -f my-pack.twpack -k requirement
trf analyze coverage -f my-pack.twpack -k requirement -r verified_by

Query

Execute SQL queries:

# Raw SQL query
trf query sql -f my-pack.twpack \
  -q "SELECT kind, COUNT(*) as count FROM artifacts GROUP BY kind"

# Query artifacts
trf query artifacts -f my-pack.twpack -k requirement

# JSON output
trf query artifacts -f my-pack.twpack -k test --json

Features

• ✅ Unified Interface - Single CLI for all TRF operations
• ✅ Validate - Schema validation with detailed error reporting
• ✅ Build - Create packs from JSON sources
• ✅ Analyze - Impact analysis, coverage metrics, graph statistics
• ✅ Query - SQL queries and filtered searches
• ✅ JSON Output - Machine-readable output for automation

Programmatic API

The package also exports all underlying libraries:

import {
  // Validator
  validateTwpack,

  // Builder
  TwpackBuilder,

  // Analyzer
  TwpackAnalyzer,

  // Query
  TwpackQuery,

  // Types
  Artifact,
  Link
} from '@traceweave/trf';

// Use any package programmatically
const builder = new TwpackBuilder({
  id: 'my-pack',
  title: 'My Pack'
});

Examples

Complete Workflow

# 1. Create a pack
trf build create \
  -i "demo:test" \
  -t "Test Pack" \
  -a artifacts.json \
  -l links.json \
  -o test.twpack

# 2. Validate it
trf validate test.twpack

# 3. Analyze it
trf analyze stats -f test.twpack
trf analyze coverage -f test.twpack -k requirement

# 4. Query it
trf query sql -f test.twpack \
  -q "SELECT * FROM artifacts WHERE kind='requirement'"

CI/CD Integration

# .github/workflows/traceability.yml
- name: Validate Traceability Pack
  run: trf validate ./traceability.twpack --verbose

- name: Check Coverage
  run: |
    trf analyze coverage -f ./traceability.twpack -k requirement -r verified_by

Documentation

• Format Specification
• Getting Started Guide
• API Reference

License

MIT