@traceweave/trf-analyzer

Graph analytics for .twpack files - TRF (Traceability Report Framework)

Installation

npm install @traceweave/trf-analyzer

Usage

Basic Analysis

import { TwpackAnalyzer } from '@traceweave/trf-analyzer';

// Create analyzer instance
const analyzer = new TwpackAnalyzer();

// Load a .twpack file
await analyzer.loadTwpack('./my-pack.twpack');

// Get graph statistics
const stats = analyzer.getStats();
console.log(`Total Artifacts: ${stats.totalArtifacts}`);
console.log(`Total Links: ${stats.totalLinks}`);
console.log(`Artifacts by Kind:`, stats.artifactsByKind);

Impact Analysis

Find all artifacts affected by a change to a given artifact:

const impact = analyzer.impactAnalysis('req:BRAKE-001');

console.log(`Total Impacted: ${impact.totalImpacted}`);
impact.impactedArtifacts.forEach(artifact => {
  console.log(`- ${artifact.id} (distance: ${artifact.distance})`);
  console.log(`  Path: ${artifact.path.join(' -> ')}`);
});

Root Cause Analysis

Find potential root causes that could have led to an issue:

const rootCause = analyzer.rootCauseAnalysis('test:FAILED-001');

console.log(`Total Root Causes: ${rootCause.totalRootCauses}`);
rootCause.rootCauses.forEach(cause => {
  console.log(`- ${cause.id} (distance: ${cause.distance})`);
});

Coverage Analysis

Check if artifacts of a given kind are properly linked (e.g., test coverage):

// Check if all requirements are verified by tests
const coverage = analyzer.coverageAnalysis('requirement', 'verified_by');

console.log(`Coverage: ${coverage.coveragePercentage.toFixed(1)}%`);
console.log(`Covered: ${coverage.coveredArtifacts}/${coverage.totalArtifacts}`);

if (coverage.uncoveredArtifacts.length > 0) {
  console.log('Uncovered requirements:');
  coverage.uncoveredArtifacts.forEach(id => console.log(`- ${id}`));
}

Path Finding

Find trace paths between two artifacts:

const paths = analyzer.findPaths('req:BRAKE-001', 'test:HIL-ABS-042');

paths.paths.forEach((path, index) => {
  console.log(`Path ${index + 1} (length ${path.length}):`);
  console.log(`  ${path.path.join(' -> ')}`);
  console.log(`  Relations: ${path.relations.join(' -> ')}`);
});

Features

• ✅ Impact Analysis - Forward graph traversal to find affected artifacts
• ✅ Root Cause Analysis - Backward graph traversal to find potential causes
• ✅ Coverage Analysis - Check linkage coverage by artifact kind
• ✅ Path Finding - Find trace paths between artifacts
• ✅ Graph Statistics - Overall graph metrics and analysis
• ✅ SQLite Storage - Efficient in-memory or persistent storage
• ✅ Performance - Sub-second queries for 10K-100K artifacts

API Reference

TwpackAnalyzer

Main class for graph analytics.

Methods

• loadTwpack(path: string) - Load a .twpack file
• loadData(artifacts, links) - Load data directly
• impactAnalysis(artifactId) - Perform impact analysis
• rootCauseAnalysis(artifactId) - Perform root cause analysis
• coverageAnalysis(kind, relation?) - Perform coverage analysis
• findPaths(from, to, maxPaths?) - Find paths between artifacts
• getStats() - Get graph statistics
• getArtifact(id) - Get artifact by ID
• getAllArtifacts() - Get all artifacts
• getArtifactsByKind(kind) - Get artifacts by kind
• close() - Close database connection

Use Cases

Safety-Critical Development

// Find all tests impacted by a requirement change
const impact = analyzer.impactAnalysis('req:SAFETY-042');

// Check if all ASIL-D requirements are verified
const coverage = analyzer.coverageAnalysis('requirement');
const asilDReqs = analyzer.getArtifactsByKind('requirement')
  .filter(r => r.fields.safety_level === 'ASIL-D');

Compliance Auditing

// Verify traceability from requirement to test
const paths = analyzer.findPaths('req:ISO26262-1.2.3', 'test:HIL-001');
if (paths.paths.length === 0) {
  console.error('Missing traceability!');
}

// Check test coverage
const testCoverage = analyzer.coverageAnalysis('requirement', 'verified_by');

License

MIT