Text2System Workflow

The Text2System engineering tool provides access to the Text2System processing model through command-line operations.

The workflow has two complementary directions:

• Forward engineering
  • Start from T2S source
  • Parse, build, and validate the system definition
  • Produce the Canonical System Model
  • Project the model to target-specific artifacts
  • Create or update implementation boundaries
• Architecture recovery
  • Start from an existing Rust project or Cargo workspace
  • Recover architectural evidence from Rust source
  • Produce a recovered Canonical System Model
  • Project the recovered model to graph artifacts
  • Inspect provenance and navigate back to Rust source

The Canonical System Model is the common architectural abstraction. Source syntax, recovery evidence, graphs, documentation, and implementation artifacts remain separate projections or inputs around that model.

Forward engineering starts from a T2S source definition and projects that definition toward implementation artifacts.

Create a new project:

text2system init rust hello_system

Enter the project directory:

cd hello_system

The initialized project provides a T2S source that can be validated and projected before implementation work begins.

Validate the system definition before projection:

text2system validate hello_system.t2s

A successful validation confirms that the source can be interpreted according to the current T2S language and canonical model rules.

Project the T2S system model to Rust:

text2system project rust

The Rust projector derives target-specific Rust artifacts from the system definition. Projection does not move implementation algorithms into T2S. T2S defines system structure and contracts while Rust remains responsible for implementation behavior.

Create or update the Rust implementation boundary:

text2system implement rust

Verify the projected Rust project with Cargo:

cargo check --manifest-path projected/rust/Cargo.toml

The generated Rust boundary is a projection of the T2S model. The implementation remains normal Rust source code.

Architecture recovery starts from existing Rust source and reconstructs architectural information without requiring the Rust project to build.

Recovery is syntax-oriented. It analyzes Rust source and Cargo project structure and records recovered facts and notices separately from the Canonical System Model.

Run recovery from the Rust project directory:

text2system recover rust .

Recovery produces two primary artifacts:

• recovered.canonical_system_model.json
  • Recovered architectural model
• rust.recovery.json
  • Rust-specific recovery evidence, provenance, source locations, and notices

The same command accepts a virtual Cargo workspace:

text2system recover rust .

Workspace recovery discovers supported workspace members and keeps recovered crate namespaces distinct inside the recovered model.

The recovery process does not require cargo check, rustc semantic analysis, or a language-server service.

Recovery may report notices when source-level evidence cannot establish a stronger semantic conclusion.

For example, a trait implementation may reference a trait that is not resolved inside the recovered source set. Such a notice is evidence about the limits of syntax-only recovery and does not necessarily indicate an invalid Rust project.

Graph projection provides a visual view of a Canonical System Model. It can be used with a model produced from T2S source or with a recovered model produced from Rust source.

Project the recovered Canonical System Model:

text2system project graph recovered.canonical_system_model.json

The graph projector can produce deterministic text and self-contained SVG artifacts.

The graph is a projection of the model. Filtering, aggregation, layout, edge visibility, labels, hover information, and source navigation do not modify the Canonical System Model.

Element kinds can be selected with show and hide controls.

Example:

text2system project graph recovered.canonical_system_model.json --show system,module

Relationship predicates can also be selected.

Example:

text2system project graph recovered.canonical_system_model.json --show system,module --relationships contains

Hide controls take precedence over corresponding show controls.

Repeated display names may be aggregated for visual exploration:

text2system project graph recovered.canonical_system_model.json --show system,module --aggregate-names on

Aggregation is visual only. Original canonical identifiers remain traceable through graph projection metadata.

The SVG renderer provides complementary hierarchy and gravity layouts.

Hierarchy is the composition-oriented view.

Example:

text2system project graph recovered.canonical_system_model.json --show system,module --relationships contains --aggregate-names on --layout hierarchy

Hierarchy uses containment depth and a compact deterministic grid. With automatic edge behavior, hierarchy hides edges to reduce visual clutter.

This view is intended primarily to answer:

What is this system made of?

Gravity is the relationship-oriented view.

Example:

text2system project graph recovered.canonical_system_model.json --show system,module --relationships contains --aggregate-names on --layout gravity --edge-labels off

Gravity uses a deterministic semantic force-style layout. With automatic edge behavior, gravity renders edges.

This view is intended primarily to answer:

How does this system hang together?

SVG edge rendering can be controlled explicitly:

• --edges auto
  • Hierarchy hides edges
  • Gravity shows edges
• --edges on
  • Always render selected relationships as edges
• --edges off
  • Do not render edges

Edge visibility affects only SVG rendering. Relationships remain part of the Graph Projection Model and text graph.

Recovery traceability connects a visual graph node back to the evidence from which it was recovered.

The traceability path is:

Rust source
Recovery evidence
Canonical System Model
Graph Projection Model
SVG node
Rust source

The Canonical System Model remains free of renderer-specific source navigation behavior. Recovery provenance is attached to the graph projection separately.

When projecting recovered.canonical_system_model.json, text2system can use the corresponding rust.recovery.json evidence.

If rust.recovery.json is stored beside the recovered model, text2system can discover it automatically.

It can also be supplied explicitly:

text2system project graph recovered.canonical_system_model.json --recovery-json rust.recovery.json

Recovered SVG nodes may expose a hover panel containing available provenance information such as:

• Canonical ID
• Kind
• Multiplicity
• Rust path
• Source file
• Source span
• Evidence kind

The hover information is projection metadata. It does not alter the recovered Canonical System Model.

Source links are disabled by default.

Enable VS Code source navigation:

text2system project graph recovered.canonical_system_model.json --source-links vscode

When provenance is available, the SVG source link can open the corresponding Rust source location in Visual Studio Code.

File-based links can also be requested:

text2system project graph recovered.canonical_system_model.json --source-links file

Source navigation is an SVG rendering concern and remains outside the Canonical System Model.

A compact architecture overview can be produced with hierarchy layout:

text2system recover rust .

text2system project graph recovered.canonical_system_model.json --show system,module --relationships contains --aggregate-names on --layout hierarchy --source-links vscode

A relationship-oriented view can then be produced with gravity layout:

text2system project graph recovered.canonical_system_model.json --show system,module --relationships contains --aggregate-names on --layout gravity --edge-labels off --source-links vscode

These two projections use the same recovered Canonical System Model but answer different visual questions.

The Text2System workflows may produce source-derived and projected artifacts.

Architecture recovery:

• recovered.canonical_system_model.json
  • Recovered Canonical System Model
• rust.recovery.json
  • Rust recovery evidence and notices

Graph projection:

• recovered.canonical_system_model.graph.txt
  • Deterministic textual graph projection
• recovered.canonical_system_model.graph.svg
  • Self-contained SVG graph projection

Rust projection and implementation produce target-specific files under the initialized project structure.

Generated artifacts should not be confused with the source of truth. In forward engineering, T2S source defines the system. In architecture recovery, Rust source is the observed implementation source and the recovered model records the architectural interpretation produced from that source.

The public Text2System engineering tool should be tested through complete user-visible workflows in addition to unit and integration tests.

Verify the following sequence with a release Text2System binary:

1. Initialize a Rust-oriented T2S project
2. Validate the T2S source
3. Project the Rust boundary
4. Create or update the Rust implementation
5. Verify the projected Rust project with Cargo

The workflow should be performed outside the Text2System development repository so that repository-local state does not hide packaging or path problems.

Verify the following sequence with a release Text2System binary:

1. Recover a Rust project
2. Recover a virtual Cargo workspace
3. Inspect recovery notices
4. Project the recovered Canonical System Model to text and SVG graphs
5. Produce a hierarchy view
6. Produce a gravity view
7. Enable source navigation
8. Navigate from an SVG node back to Rust source

Release acceptance should confirm these architectural guarantees:

• Repeated projection of the same model produces deterministic graph output
• Graph filtering does not modify the Canonical System Model
• Name aggregation does not merge canonical elements
• Layout does not modify graph semantics
• SVG edge visibility does not remove relationships from the Graph Projection Model
• Recovery evidence remains separate from the Canonical System Model
• Source navigation remains a renderer concern

text2system is the public Text2System engineering tool.

The command-line interface provides system processing, validation, analysis, projection, implementation, and architecture recovery workflows.

Projectors are exposed consistently through the project command. Current projection targets include:

• project graph
• project rust
• project html
• project pdf

project doc is a shorthand alias for the HTML documentation projection.

The legacy top-level build and build-pdf commands are compatibility interfaces and are not the preferred public workflow.

Language Server Protocol support is exposed as text2system lsp, a complementary interface of the same engineering tool. The LSP interface provides editor-facing authoring capabilities while reusing the same Text2System language processing, semantic model, and validation capabilities.

The Visual Studio Code extension remains a thin editor client.

Command-line operations, LSP operations, projectors, and recovery must not create independent interpretations of T2S. They should share the same core processing model and Canonical System Model.

Text2System supports two complementary engineering directions around one canonical architectural abstraction.

Forward engineering:

T2S source
Canonical System Model
Target projection
Implementation

Architecture recovery:

Rust source
Recovery evidence
Recovered Canonical System Model
Graph projection
Source traceability

The Canonical System Model is the architectural boundary between source-specific input and target-specific views. Everything around it remains an explicit source, evidence layer, or projection.