@traceweave/trf-query

SQL-like query engine for .twpack files - TRF (Traceability Report Framework)

Installation

npm install @traceweave/trf-query

Usage

Programmatic API

import { TwpackQuery } from '@traceweave/trf-query';

// Create query instance
const query = new TwpackQuery();

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

// Query artifacts by kind
const requirements = query.getByKind('requirement');
console.log(`Found ${requirements.length} requirements`);

// Execute raw SQL
const result = query.sql('SELECT kind, COUNT(*) as count FROM artifacts GROUP BY kind');
console.table(result.rows);

// Query with filters
const artifacts = query.queryArtifacts({
  kind: 'test',
  titleContains: 'integration'
});

// Find artifacts matching a predicate
const asilD = query.findArtifacts(a =>
  a.fields.safety_level === 'ASIL-D'
);

// Count artifacts
const testCount = query.count('test');
console.log(`Total tests: ${testCount}`);

CLI

Query artifacts

# Get all artifacts
trf-query artifacts -f ./my-pack.twpack

# Filter by kind
trf-query artifacts -f ./my-pack.twpack -k requirement

# Output as JSON
trf-query artifacts -f ./my-pack.twpack -k test --json

Query links

# Get all links
trf-query links -f ./my-pack.twpack

# Filter by relation
trf-query links -f ./my-pack.twpack -r verified_by

Execute SQL queries

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

# Find ASIL-D requirements (requires JSON parsing in SQL)
trf-query sql -f ./my-pack.twpack \
  -q "SELECT id, title FROM artifacts WHERE kind = 'requirement'"

# Complex join query
trf-query sql -f ./my-pack.twpack \
  -q "SELECT a.id, a.kind, COUNT(l.id) as link_count
      FROM artifacts a
      LEFT JOIN links l ON a.id = l.from_id
      GROUP BY a.id"

Features

• ✅ SQL Queries - Execute raw SQL on twpack data
• ✅ Filtered Queries - Query artifacts and links with filters
• ✅ Helper Methods - Convenient methods for common queries
• ✅ Predicate Filtering - JavaScript predicates for complex filtering
• ✅ CLI Tool - Command-line interface for quick queries
• ✅ JSON Output - Machine-readable output for automation
• ✅ SQLite Backend - Fast, proven query engine

API Reference

TwpackQuery

Main class for querying twpack data.

Methods

• loadTwpack(path) - Load a .twpack file
• loadData(artifacts, links) - Load data directly
• sql(query, params?) - Execute raw SQL query
• queryArtifacts(filters?, options?) - Query artifacts with filters
• queryLinks(filters?, options?) - Query links with filters
• getByKind(kind) - Get artifacts by kind
• getByRelation(relation) - Get links by relation
• findArtifacts(predicate) - Find artifacts matching predicate
• count(kind?) - Count artifacts (optionally by kind)
• close() - Close database connection

Filters

Artifact Filters

• kind - Filter by artifact kind
• version - Filter by version
• titleContains - Filter by title substring

Link Filters

• from - Filter by source artifact
• to - Filter by target artifact
• relation - Filter by relation type

Options

• limit - Limit number of results
• offset - Skip number of results

SQL Schema

The query engine uses the following SQLite schema:

-- Artifacts table
CREATE TABLE artifacts (
  id TEXT PRIMARY KEY,
  kind TEXT NOT NULL,
  version TEXT NOT NULL,
  title TEXT,
  fields TEXT NOT NULL  -- JSON string
);

-- Links table
CREATE TABLE links (
  id TEXT PRIMARY KEY,
  from_id TEXT NOT NULL,
  to_id TEXT NOT NULL,
  relation TEXT NOT NULL,
  metadata TEXT  -- JSON string
);

Examples

Safety Analysis

// Find all ASIL-D requirements
const asilD = query.findArtifacts(a =>
  a.kind === 'requirement' && a.fields.safety_level === 'ASIL-D'
);

// Check test coverage for ASIL-D requirements
const verified = query.sql(`
  SELECT r.id, r.title, COUNT(l.id) as test_count
  FROM artifacts r
  LEFT JOIN links l ON r.id = l.from_id AND l.relation = 'verified_by'
  WHERE r.kind = 'requirement'
  GROUP BY r.id
  HAVING test_count = 0
`);

Compliance Reporting

// Generate traceability matrix
const matrix = query.sql(`
  SELECT
    l.from_id as requirement,
    l.to_id as test,
    l.relation
  FROM links l
  WHERE l.relation = 'verified_by'
`);

// Count artifacts by domain
const byDomain = query.sql(`
  SELECT kind, COUNT(*) as count
  FROM artifacts
  GROUP BY kind
  ORDER BY count DESC
`);

License

MIT