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 use component, version, and ID as their canonical storage key; unscoped items keep bare-ID keys. Relationships are indexed and deduplicated by canonical source and target identities.

export class TraceabilityGraph {
  // Node management
  addItem(item: Item): void;
  getItem(id: string, component?: string, version?: 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, component?: string, version?: string): ItemRelationship[];
  getReverseRelationships(targetId: string, type?: string, component?: string, version?: string): ItemRelationship[];

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

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

  // Validation
  validate(): ValidationResult;
  findCircularReferences(): string[];

  // Visualization
  toDot(fromId: string, depth?: number, component?: string, version?: string): 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.

CSV node rows include id (authored ID), identity (canonical graph key), component, and version. For playbook graphs, identity combines component, version, and ID with NUL separators. For unscoped local graphs, it equals id. CSV relationship rows use canonical node keys in source and target. They retain authored endpoint IDs in sourceId and targetId. Cypher creates and matches nodes by identity.

export class Neo4jExporter {
  constructor(graph: TraceabilityGraph);

  export(options: Neo4jExportOptions): Neo4jExportResult;
}

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

export interface Neo4jExportResult {
  nodesFile?: string;
  relationshipsFile?: string;
  cypherFile?: string;
  nodeCount: number;
  relationshipCount: number;
}

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
  tags?: string[];                   // Comma-separated header tags, parsed as a list
  attributes: Record<string, string>; // Additional attributes
  sourceFile?: string;               // Repository source reference (see below)
  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;
  fromId: string;                    // Authored source item ID
  targetId: string;                  // Authored target item ID
  type: string;                      // User-defined relation type
  component?: string;                 // Source Antora component
  version?: string;                  // Source Antora version
  fromIdentity?: string;              // Canonical source identity after resolution
  targetIdentity?: string;            // Canonical target identity after resolution
  sourceFile?: string;
  line?: number;
  autoGenerated?: boolean;
  inverseOf?: string;
}

sourceFile is the item’s repository source reference, not a filesystem location. Page items use the source path given by the caller (the content catalog for Antora, the input path for the CLI), with the .adoc extension and anything up to and including the last pages/ segment stripped. For items in partial files it is the partial’s http(s) view URL when the content source provides one, and the repository-relative source path otherwise. A local content source produces a file:// view URL, which points at the build machine’s worktree, so those partial items fall back to the repository-relative path. No sourceFile value therefore exposes a build-machine directory, including when it is serialized into a graph.json snapshot or a Neo4j export.

Configuration Types

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

export interface MatrixDefinition {
  name: string;
  description?: string;
  rows: string;
  columns: string[];
  coverageRelations?: Record<string, string[]>;
  rowFilter?: string;                 // Safe status/tag expression for rows
  linkDisplayPolicy?: string;
}


export interface LinkDisplayPolicy {
  hide: LinkDisplayHideRule[];
}

export interface LinkDisplayHideRule {
  relation: string;
  currentItem: LinkDisplayItemMatcher;
  relatedItem: LinkDisplayItemMatcher;
}

export interface LinkDisplayItemMatcher {
  role?: string;
  attributes?: 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