Skip to main content

Builder Package

The @traceweave/trf-builder package provides a fluent API for creating .twpack files programmatically.

Installation​

npm install @traceweave/trf-builder

Quick Start​

const { TwpackBuilder } = require('@traceweave/trf-builder');

const builder = new TwpackBuilder({
  id: 'my-project:v1.0',
  title: 'My Traceability Pack',
  description: 'Optional description'
});

builder.addArtifact({
  id: 'req:REQ-001',
  kind: 'requirement',
  version: '1.0',
  title: 'User Authentication Required',
  fields: {
    description: 'System shall require user authentication',
    priority: 'high'
  }
});

builder.addLink({
  id: 'link:001',
  from: 'req:REQ-001',
  to: 'test:TEST-001',
  relation: 'verified_by'
});

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

API Reference​

TwpackBuilder​

Constructor options:

interface TwpackBuilderOptions {
  id: string;          // Pack identifier (required)
  title: string;       // Pack title (required)
  description?: string; // Optional description
  version?: string;    // Format version (defaults to '2.1')
}

Methods​

addArtifact(artifact)​

Add an artifact to the pack.

builder.addArtifact({
  id: 'req:REQ-001',       // Artifact ID (required)
  kind: 'requirement',      // Artifact kind (required)
  version: '1.0',          // Version (required)
  title: 'Title',          // Title (required)
  fields: {                // Custom fields (optional)
    description: '...',
    priority: 'high'
  }
});

Add a traceability link.

builder.addLink({
  id: 'link:001',         // Link ID (required)
  from: 'req:REQ-001',    // Source artifact ID (required)
  to: 'test:TEST-001',    // Target artifact ID (required)
  relation: 'verified_by' // Relation type (required)
});

addProvenance(activity)​

Add a provenance activity.

builder.addProvenance({
  id: 'activity:001',
  type: 'build',
  timestamp: '2025-01-15T10:00:00Z',
  actor: 'ci-system',
  fields: {
    commit: 'abc123',
    branch: 'main'
  }
});

loadArtifacts(path)​

Load artifacts from a JSON file.

await builder.loadArtifacts('./artifacts.json');

Expected format:

{
  "artifacts": [
    {
      "id": "req:REQ-001",
      "kind": "requirement",
      "version": "1.0",
      "title": "...",
      "fields": { }
    }
  ]
}

loadLinks(path)​

Load links from a JSON file.

await builder.loadLinks('./links.json');

Expected format:

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

loadProvenance(path)​

Load provenance from a JSON file.

await builder.loadProvenance('./provenance.json');

build(outputPath)​

Build and write the .twpack file.

await builder.build('./output.twpack');

Complete Example​

const { TwpackBuilder } = require('@traceweave/trf-builder');

async function createPack() {
  const builder = new TwpackBuilder({
    id: 'automotive:brake-system:v1.0',
    title: 'Brake System Traceability',
    description: 'ISO 26262 ASIL-D compliance evidence'
  });

  // Add artifacts programmatically
  builder.addArtifact({
    id: 'req:BRAKE-001',
    kind: 'requirement',
    version: '1.0',
    title: 'Emergency Brake Activation',
    fields: {
      description: 'ABS shall activate within 50ms',
      safety_level: 'ASIL-D',
      priority: 'critical'
    }
  });

  builder.addArtifact({
    id: 'test:HIL-001',
    kind: 'test',
    version: '1.0',
    title: 'HIL Test - Emergency Braking',
    fields: {
      test_type: 'hardware-in-loop',
      status: 'passed',
      result: '48ms average response time'
    }
  });

  // Link requirement to test
  builder.addLink({
    id: 'link:001',
    from: 'req:BRAKE-001',
    to: 'test:HIL-001',
    relation: 'verified_by'
  });

  // Add provenance
  builder.addProvenance({
    id: 'build:001',
    type: 'automated_build',
    timestamp: new Date().toISOString(),
    actor: 'jenkins-ci',
    fields: {
      commit: process.env.GIT_COMMIT,
      branch: process.env.GIT_BRANCH,
      build_number: process.env.BUILD_NUMBER
    }
  });

  // Build the pack
  await builder.build('./brake-system.twpack');
  console.log('Pack created successfully!');
}

createPack();

Loading from Files​

const { TwpackBuilder } = require('@traceweave/trf-builder');

async function buildFromFiles() {
  const builder = new TwpackBuilder({
    id: 'project:v1.0',
    title: 'Project Traceability'
  });

  // Load all data from JSON files
  await builder.loadArtifacts('./data/artifacts.json');
  await builder.loadLinks('./data/links.json');
  await builder.loadProvenance('./data/provenance.json');

  await builder.build('./output.twpack');
}

Validation​

The builder automatically performs:

  • ID format validation
  • Reference integrity checking (links must reference existing artifacts)
  • Duplicate ID detection

Errors are thrown if validation fails:

try {
  await builder.build('./output.twpack');
} catch (error) {
  if (error.message.includes('already exists')) {
    console.error('Duplicate artifact ID');
  } else if (error.message.includes('not found')) {
    console.error('Link references non-existent artifact');
  }
}

CLI Usage​

The builder is also available via CLI:

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

See CLI Reference for details.

See Also​