API Reference

RequirementsTraceabilityExtension

src/index.ts — the orchestrator. Owns the TraceabilityGraph, delegates processing to DocumentParser, generation to MatrixGenerator, and export to Neo4jExporter.

export class RequirementsTraceabilityExtension {
  readonly graph: TraceabilityGraph;
  configLoader?: ConfigLoader;
  currentFile: string | null;
}

// Factory methods
RequirementsTraceabilityExtension.createWithConfig(configPath?: string): Promise<RequirementsTraceabilityExtension>;
RequirementsTraceabilityExtension.createWithPreset(presetName: string): RequirementsTraceabilityExtension;

Methods

Method Description

process(content, options)

Parse AsciiDoc content, register items and relationships in the graph, return ParserResult

processFiles(files)

Process multiple files, return per-file results and aggregate

getAllItems()

All items in the graph

getAllRelationships()

All relationships in the graph

getItemsByRole(role)

Filter items by role

getRelationships(id, type?)

Relationships from an item, optionally filtered by type

getRelatedItems(id, type?)

Items targeted by relationships from an item

getRoleStatistics()

Item counts per role

validate()

Run graph validation (dangling references, circular references)

getCoverageReport()

Per-role item counts and matrix-specific coverage

getConfigErrors()

Configuration validation errors

createNeo4jExporter()

Create a Neo4jExporter for the current graph

exportToNeo4jCSV(options)

Export directly to CSV

getMatrixDefinitions()

Matrix definitions from loaded config

isKnownRole(role)

Check if a role is in the loaded config

isRelationAllowed(src, tgt, type)

Check if a relation is allowed by config

getAllowedRelations(src, tgt)

Get allowed relation types between roles

listPresets()

List all built-in presets

getPreset(name)

Get a specific preset

clear()

Clear graph and reset state

resetWithConfig(configLoader)

Set a new ConfigLoader and update graph

Delegate methods

Forwarded to graph:

findPath(from, to, maxDepth?)

BFS path between items

getImpactAnalysis(id)

All reachable items in both directions

getRelationshipsByRoles(src, tgt)

Relationships between two roles

getNextId(prefix)

Next available sequential ID for a given prefix

TraceabilityGraph

src/TraceabilityGraph.ts — in-memory directed graph. Items stored in a Map<string, Item> keyed by id. Relationships stored in a Map<string, ItemRelationship> keyed by composite key fromId-type-targetId.

export class TraceabilityGraph {
  // Node management
  addItem(item: Item): void;
  getItem(id: string): Item | undefined;
  getAllItems(): Item[];
  getItemsByRole(role: string): Item[];
  getAllRoles(): string[];

  // Relationship management
  addRelationship(relationship: ItemRelationship): void;
  getRelationship(id: string): ItemRelationship | undefined;
  getAllRelationships(): ItemRelationship[];
  getRelationships(fromId: string, type?: string): ItemRelationship[];
  getReverseRelationships(targetId: string, type?: string): ItemRelationship[];

  // Query
  getRelatedItems(itemId: string, relationType?: string): Item[];
  getItemsWithRelationTo(itemId: string, relationType?: string): Item[];
  getRelationshipsByRoles(sourceRole: string, targetRole: string): ItemRelationship[];
  getRoleStatistics(): Record<string, number>;

  // Graph algorithms
  findPath(fromId: string, toId: string, maxDepth?: number): string[] | null;
  getImpactAnalysis(itemId: string): string[];

  // Validation
  validate(): ValidationResult;  // { errors: string[], warnings: string[] }
  findCircularReferences(): string[];

  // Visualization
  toDot(fromId: string, depth?: number): string;
  toVegaLite(itemId?: string): string;

  // ID generation
  getNextId(prefix: string): string;

  // Lifecycle
  clear(): void;
  merge(other: TraceabilityGraph): void;
  setConfigLoader(configLoader: ConfigLoader): void;
}

interface ValidationResult {
  errors: string[];
  warnings: string[];
}

addRelationship validates: source exists, target exists, relation is allowed (if ConfigLoader is set). Invalid relations are stored with a warning. validate() runs findCircularReferences(), a DFS-based cycle detector.

DocumentParser

src/DocumentParser.ts — regex-based AsciiDoc parser.

export interface ParserResult {
  items: Item[];
  relationships: ItemRelationship[];
  warnings: ParserWarning[];
  errors: ParserError[];
}

Two-pass approach: find [item] block macros, then scan content for inline relationship macros (<type>:<TARGET-ID>[]). Supports verbatim block exclusion, source file and line tracking.

MatrixGenerator

src/MatrixGenerator.ts — config-driven matrix generation.

export class MatrixGenerator {
  constructor(graph: TraceabilityGraph, configLoader?: ConfigLoader);

  generateMatrix(name: string): GeneratedMatrix;
  generateDefaultMatrix(): GeneratedMatrix;
  generateCoverageReport(): CoverageReport;
}

export interface GeneratedMatrix {
  name: string;
  description?: string;
  rows: MatrixRow[];
  coverage: CoverageStats;
  generatedAt: string;
}

Neo4jExporter

src/Neo4jExporter.ts — exports the graph to Neo4j-compatible formats.

export class Neo4jExporter {
  constructor(graph: TraceabilityGraph);

  export(options: Neo4jExportOptions): Neo4jExportResult;
}

export interface Neo4jExportOptions {
  outputDir: string;
  format: 'csv' | 'cypher';
  includeContent?: boolean;       // default: true
  includeAllAttributes?: boolean;  // default: true
}

export interface Neo4jExportResult {
  format: 'csv' | 'cypher';
  nodeCount: number;
  relationshipCount: number;
  files: string[];
}

TemplateRenderer

src/TemplateRenderer.ts — Mustache template engine wrapper.

export class TemplateRenderer {
  constructor(templateDir?: string);

  render(templateName: string, data: any): string;
  renderMatrix(matrix: GeneratedMatrix, template?: string): string;
}

Falls back to built-in templates when custom template directory is provided but specific files are missing.

ConfigLoader

src/config/TraceabilityConfig.ts — loads, validates, and exposes configuration.

export class ConfigLoader {
  load(configPath?: string): CompleteConfig;
  loadPreset(presetName: string): Preset;
  getConfig(): CompleteConfig;
  reload(): CompleteConfig;
  listPresets(): { name: string; description: string; version: string }[];

  isKnownRole(role: string): boolean;
  isRelationAllowed(sourceRole, targetRole, relationType): boolean;
  getAllowedRelations(sourceRole, targetRole): string[];
  getMatrices(): MatrixDefinition[];
  getMatrix(name: string): MatrixDefinition | undefined;
}

GraphDiff

src/GraphDiff.ts — derives a delta between two graph snapshots by stable item ID. Config-agnostic: no role names are hardcoded.

export interface ItemDelta {
  id: string;
  kind: "added" | "removed" | "modified";
  role: string;
  old?: Item;
  new?: Item;
  changedFields: string[];
}

export interface RelationshipDelta {
  kind: "added" | "removed";
  rel: ItemRelationship;
}

export interface GraphDiff {
  items: ItemDelta[];
  relationships: RelationshipDelta[];
}

export function diffGraphs(prev: TraceabilityGraph, next: TraceabilityGraph): GraphDiff;

export function diffSnapshots(prev: GraphSnapshot, next: GraphSnapshot): GraphDiff;

Items are matched by component-qualified identity (component, then version when present, then id); items without a component fall back to bare ID. Items present only in next are added, only in prev are removed, and survivors are compared field-by-field (title, content, role, status, attributes) for modified. Relationship changes are reported only for surviving items, except supersedes history links.

GraphSnapshot

src/GraphSnapshot.ts — the canonical JSON snapshot format shared by site-graph, diff-graphs, and the extension’s per-version graph.json.

export interface GraphSnapshot {
  format: number;                    // schema version, currently 1
  items: Item[];
  relationships: ItemRelationship[];
}

export const SNAPSHOT_FORMAT = 1;

export function serializeSnapshot(graph: TraceabilityGraph): string;
export function deserializeSnapshot(json: string): GraphSnapshot;

serializeSnapshot keeps item scope fields (component, module, version) and drops per-page pubUrl. deserializeSnapshot rejects unknown format values and malformed snapshots.

Data Model

src/types.ts:

export interface Item {
  id: string;                        // Unique identifier
  title: string;                     // Display title
  content?: string;                  // Raw AsciiDoc content
  role: string;                      // User-defined role
  status?: string;                   // Free-form status
  attributes: Record<string, string>; // Additional attributes
  sourceFile?: string;               // Source AsciiDoc file
  sourceLine?: number;               // Line number in source
  component?: string;                // Antora component name (absent for CLI)
  module?: string;                   // Antora module name (absent for CLI)
  version?: string;                  // Antora component version (absent for CLI)
  pubUrl?: string;                   // Antora published URL (absent for CLI)
}

export interface ItemRelationship {
  id: string;                        // Composite: "fromId-type-targetId"
  fromId: string;                    // Source item id
  targetId: string;                  // Target item id
  type: string;                      // User-defined relation type
  sourceFile?: string;
  line?: number;
  autoGenerated?: boolean;
  inverseOf?: string;
}

Configuration Types

export interface TraceabilityConfig {
  roles: string[];
  relations: Record<string, Record<string, string[]>>;
  matrices: MatrixDefinition[];
  extends?: string;
}

export interface MatrixDefinition {
  name: string;
  description?: string;
  rows: string;
  columns: string[];
  coverageRelations: Record<string, string[]>;
}

export interface Preset extends PresetMetadata {
  tracer: TraceabilityConfig;
  neo4j?: { queries: Neo4jQuery[] };
  documentation?: { description: string };
}

Antora Integration

src/antora-extension.ts — Antora extension entry point.

export class AntoraTraceabilityExtension {
  static register(context: AntoraExtensionContext): void;
  getTraceabilityExtension(): RequirementsTraceabilityExtension;
}

Event handlers: contentClassified (process items and register matrices), sitePublished (write standalone traceability output).

Related