Developer Guide

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

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

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[] }

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

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

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

  generateMatrix(name: string): GeneratedMatrix;
  generateDefaultMatrix(): GeneratedMatrix;
  generateCoverageReport(): { overall: number; complete: number; partial: number; missing: number; total: number };
}

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

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[];
}

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

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

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

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

name: requirements-engineering
description: "..."
version: 1.0.0
compatibility:
  minExtensionVersion: 0.7.0
traceability:
  roles: [...]
  relations: {...}
  matrices: [...]
neo4j:
  queries: [...]
documentation:
  description: "..."

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

  getTraceabilityExtension(): RequirementsTraceabilityExtension;
}

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
}

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;
}

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

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

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

git clone <repo-url>
cd antora-asciidoc-tracing
npm install
npm run build
npm test

npm run build          # Compile TypeScript
npm test               # Run all tests (compiles test files first)
npm run test:coverage  # Run tests with c8 coverage
npm run lint           # Run biome checks
npm run format         # Auto-format with biome

import { expect } from 'chai';
import { RequirementsTraceabilityExtension } from '../src/index.js';

describe('MyFeature', () => {
  it('should do something', () => {
    const extension = new RequirementsTraceabilityExtension();
    extension.process(`...[#X, item, role=requirement]...`, { sourceFile: 'test.adoc' });
    expect(extension.getAllItems()).to.have.lengthOf(1);
  });
});

npx mocha 'lib/test/graph-and-api.test.js'

feat: add new feature
fix: fix a bug
docs: update documentation
test: add or update tests
refactor: restructure code
chore: maintenance tasks

npm run build

{
  "exports": {
    ".": "./lib/index.js",
    "./antora-extension": "./lib/src/antora-extension.js",
    "./package.json": "./package.json"
  },
  "bin": {
    "antora-req-trace": "./lib/cli.js"
  }
}

npm version 0.7.0    # Bump version
npm run build         # Fresh build
npm test              # Verify all 181 tests pass
npm publish           # Publish to npm