Skip to main content

Quick Start

Build and validate your first TWPack in less than ten minutes using the TRF CLI.

1. Install TRF​

npm install -g @traceweave/trf

2. Validate an Example Pack​

Get the TRF repository with example packs:

git clone https://github.com/TraceWeave-KR/TRF.git
cd TRF

Validate one of the domain-specific examples:

trf validate examples/automotive-iso26262-example.twpack
# ✅ Valid twpack file

3. Build Your First Pack​

Create artifact and link files:

artifacts.json:

{
  "artifacts": [
    {
      "id": "req:AUTH-001",
      "kind": "requirement",
      "version": "1.0",
      "title": "User Authentication Required",
      "fields": {
        "description": "System shall require user authentication",
        "priority": "high"
      }
    },
    {
      "id": "test:AUTH-TEST-001",
      "kind": "test",
      "version": "1.0",
      "title": "Authentication Test",
      "fields": {
        "test_type": "integration",
        "status": "passed"
      }
    }
  ]
}

links.json:

{
  "links": [
    {
      "id": "link:001",
      "from": "req:AUTH-001",
      "to": "test:AUTH-TEST-001",
      "relation": "verified_by"
    }
  ]
}

Build the pack:

trf build create \
  --id "my-project:v1.0" \
  --title "My First Pack" \
  --artifacts ./artifacts.json \
  --links ./links.json \
  --output ./my-first-pack.twpack

4. Analyze Your Pack​

Get statistics:

trf analyze stats -f my-first-pack.twpack
# 📊 Total Artifacts: 2
# 📊 Total Links: 1

Impact analysis:

trf analyze impact -f my-first-pack.twpack -a req:AUTH-001
# 🔍 Total Impacted: 1 artifacts

Coverage analysis:

trf analyze coverage -f my-first-pack.twpack -k requirement
# 📈 Coverage: 100.0%

5. Query Your Pack​

Get all requirements:

trf query artifacts -f my-first-pack.twpack -k requirement

Run SQL queries:

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

6. Programmatic Usage​

const { TwpackBuilder, validateTwpack, TwpackAnalyzer } = require('@traceweave/trf');

async function example() {
  // Build
  const builder = new TwpackBuilder({
    id: 'my-project:v1.0',
    title: 'My Pack'
  });

  builder.addArtifact({
    id: 'req:REQ-001',
    kind: 'requirement',
    version: '1.0',
    title: 'My Requirement',
    fields: { priority: 'high' }
  });

  await builder.build('./my-pack.twpack');

  // Validate
  const result = await validateTwpack('./my-pack.twpack');
  console.log('Valid:', result.valid);

  // Analyze
  const analyzer = new TwpackAnalyzer();
  await analyzer.loadTwpack('./my-pack.twpack');
  const stats = analyzer.getStats();

  analyzer.close();
}

Where to go next​