Tools

Reusable software utilities for the Source Engineering discipline.

This repository holds the discipline's reusable tools. The tools are the discipline's user-facing surface.

Quick start

npm install
npm run build
node dist/cli/se-trace.js inspect path/to/cots.json

15-minute quickstart

Zero to a validated COTS in one command (Advancement Plan Phase 5 adopter quickstart):

bash scripts/quickstart.sh

It fetches (or falls back to the bundled) seed COTS, runs the quick conformance check, prints the inspect/cite summaries, and renders the COTS Explorer page. See source-engineering-education/quickstart-15-minutes.md for the guided version.

Commands

# Inspect a COTS
se-trace inspect examples/legal-summarization.cots.json

# Cite a specific decision (print the evidence chain)
se-trace cite examples/legal-summarization.cots.json urn:source-engineering:decision:...

# Visualize a COTS as a Reasoning Roadmap (Mermaid + HTML)
se-trace visualize examples/legal-summarization.cots.json -o ./out

# Quick conformance check
se-trace validate examples/legal-summarization.cots.json

# Surface the Layer 2 (Runtime Validation) record of a COTS (RFC-0001)
se-trace validate-runtime examples/legal-summarization.cots.json

# Walk the evidence chains and surface recursive (model-generated) items (RFC-0002)
se-trace recursive examples/legal-summarization.cots.json

# Render the Context Graph (Mermaid + HTML, RFC-0004)
se-trace context-graph examples/legal-summarization.cots.json -o ./out

# Replay the audit trail (RFC-0005)
se-trace audit examples/legal-summarization.cots.json

# COTS Explorer: one self-contained HTML page with all four views (Advancement Plan Phase 5)
se-trace explore examples/legal-summarization.cots.json -o ./out

What is in this repository

• src/inspect.ts - the inspect command. Prints a human-readable summary of a COTS.
• src/cite.ts - the cite command. Prints the evidence chain for a specific decision.
• src/visualize.ts - the visualize command. Renders a COTS as a Mermaid diagram + HTML page.
• src/context-graph.ts - the context-graph command. Renders the Context + Evidence parts as a typed-edge graph (RFC-0004).
• src/audit.ts - the audit command. Replays the audit trail and flags append-only/linkage violations (RFC-0005).
• src/explore.ts - the COTS Explorer. One self-contained HTML page combining Reasoning Roadmap, Context Graph, summary, and audit trail.
• src/cli/se-trace.ts - the CLI entry point, including validate-runtime (RFC-0001) and recursive (RFC-0002 chain-walking).
• tests/tools.test.ts - the test suite.

SDKs

The sdks/ directory is reserved for typed-language SDKs (TypeScript, Python). Skeletons land in P3 follow-on; the conformance suite and reference implementation are the canonical sources.

Relationship to other repos

• Source-Engineering/source-engineering-conformance - the canonical conformance test suite. se-trace validate is a quick subset; the full suite is in source-engineering-conformance.
• Source-Engineering/source-engineering-reference-implementation - the reference framework that produces COTSs.
• Source-Engineering/source-engineering-specifications - the COTS schema the tools read.

Status

This is the tools slice (Phase 3). The se-trace CLI and the visualizer are working. SDK skeletons land in P3 follow-on.

License

Apache-2.0. See LICENSE.