js-traceability

Reusable deliverable-to-source traceability utilities and the js-traceability CLI.

The package is intentionally project-agnostic. It parses source IDs, validates Markdown/CSV research materials, checks final DOCX/XLSX/PPTX artifacts, and validates JSONL lineage manifests. Project-specific defaults stay outside the package in a traceability config module.

Zero runtime dependencies. ESM. Node >= 18.

Install

npm install js-traceability

Or use a local file dependency:

{
  "dependencies": {
    "js-traceability": "file:../js-traceability"
  }
}

Import

import { expandSourceRefs } from "js-traceability/core";
import { runTraceabilityCheck } from "js-traceability/validation";

Available subpath exports:

• js-traceability
• js-traceability/core
• js-traceability/extractors
• js-traceability/lineage
• js-traceability/lineage-schema
• js-traceability/config-loader
• js-traceability/validation
• js-traceability/cli

CLI

js-traceability check --config traceability.config.mjs --strict
js-traceability check --config traceability.config.mjs --all-numeric --json
js-traceability final --config traceability.config.mjs --artifacts word,excel,ppt --strict
js-traceability lineage validate --config traceability.config.mjs --lineage lineage/deliverable_lineage.jsonl --strict

If --config is omitted, the CLI looks for traceability.config.mjs, traceability.config.js, or traceability.config.cjs under --root or the current working directory.

Common flags:

• --root <path>: project root; defaults to process.cwd().
• --config <path>: ESM/CJS config module, relative to --root unless absolute.
• --json: print the raw audit JSON.
• --strict: fail on warnings as well as errors.

Command-specific flags:

• check --all-numeric: include configured working numeric claim files.
• final --artifacts word,excel,ppt: select final artifact families.
• lineage validate --lineage <path>: JSONL lineage manifest path. If omitted, the CLI uses config.paths.lineagePath.

API Examples

Run a research material traceability check:

import { loadTraceabilityConfig } from "js-traceability/config-loader";
import { renderTraceabilityCheckText, runTraceabilityCheck } from "js-traceability/validation";

const root = process.cwd();
const config = await loadTraceabilityConfig({ root, configPath: "traceability.config.mjs" });
const audit = await runTraceabilityCheck({ root, config, allNumeric: false });

process.stdout.write(renderTraceabilityCheckText(audit));
process.exitCode = audit.errors.length ? 1 : 0;

Validate final Office artifacts:

import { loadTraceabilityConfig } from "js-traceability/config-loader";
import { runFinalArtifactCheck } from "js-traceability/validation";

const root = process.cwd();
const config = await loadTraceabilityConfig({ root, configPath: "traceability.config.mjs" });
const audit = await runFinalArtifactCheck({ root, config, selectedArtifacts: ["word", "excel", "ppt"] });

Validate lineage:

import { loadTraceabilityConfig } from "js-traceability/config-loader";
import { validateLineage } from "js-traceability/validation";

const root = process.cwd();
const config = await loadTraceabilityConfig({ root, configPath: "traceability.config.mjs" });
const audit = await validateLineage({ root, config, lineagePath: config.paths.lineagePath });

More complete examples live under examples/.

Config Contract

Projects provide a config object as default, traceabilityConfig, or config.

export default {
  sourceIndexes: {
    public: { file: "sources/public-source-index.md", prefix: "S-P" },
  },
  sourceIndexFiles: ["sources/public-source-index.md"],
  policy: {
    sourceIdPattern: /\bS-[A-Z]+-\d{3}\b/g,
    sourceRangePattern: /\b(S-[A-Z]+)-(\d{3})\s+to\s+\1-(\d{3})\b/g,
    lowReliabilityPattern: /^(low|low-medium)$/i,
    unverifiedStatusPattern: /^(to be processed|not started|unverified)$/i,
    sourceColumnAliases: ["Source ID", "Evidence"],
    statusColumnAliases: ["Status"],
    labelColumnAliases: ["ID", "Name"],
    sourceIndexColumns: {
      id: ["Source ID"],
      title: ["Source title"],
      type: ["Type"],
      url: ["URL"],
      reliability: ["Reliability"],
      status: ["Verification status"],
      notes: ["Notes"],
    },
  },
  paths: {
    traceabilityScanDirs: ["research", "deliverables"],
    auditCsvFiles: ["research/model-inputs.csv"],
    deliverableDirs: ["deliverables"],
    workingNumericClaimFiles: [],
    finalArtifactDirs: {
      word: "deliverables/word",
      excel: "deliverables/excel",
      ppt: ["deliverables/ppt", "deliverables/pptx"],
    },
    lineagePath: "lineage/deliverable_lineage.jsonl",
  },
};

sourceIndexFiles may be omitted when sourceIndexes is present; the config loader derives it from each index's file.

Projects may customize policy.sourceIdPattern and policy.sourceRangePattern. Range patterns should either expose named captures prefix, start, and end, or use positional captures in that order.

Projects may also override policy.numericClaimDetector and policy.assumptionDetector with functions from an ESM/CJS config module when the built-in heuristics are too broad or too narrow.

Source Index Format

Source indexes are Markdown tables. By default the package expects this shape:

| Source ID | Source title | Type | URL | Reliability | Verification status | Notes |
|---|---|---|---|---|---|---|
| S-P-001 | Example annual report | Official filing | https://example.com | high | verified | Revenue anchor |

Source IDs use S-<PREFIX>-<NNN> and support ranges such as S-P-001 to S-P-003. Other ID schemes and column labels are supported through policy.sourceIdPattern, policy.sourceRangePattern, and policy.sourceIndexColumns.

Runtime Notes

Office extraction currently shells out to the system unzip command to inspect DOCX/XLSX/PPTX files. The validation APIs do not write project store metadata; workspace-specific wrappers should record audit history separately when needed.

Versioning And Releases

This package follows SemVer:

• Patch releases fix bugs without changing the public API.
• Minor releases add backwards-compatible API, CLI, config, or schema behavior.
• Major releases may change exported APIs, CLI flags, config contracts, or lineage schema semantics.

Before publishing, update package.json, CHANGELOG.md, and any affected docs, then run:

npm test
npm run pack:dry-run

The npm package is published from the repository root. Keep credentials in a local .env or npm user config only; do not commit tokens or generated .npmrc files. See docs/release.md for the full release checklist.

Test

npm test