Skip to content

Commit 5c30eb8

Browse files
KSemenenkoKSemenenko
committed
readme
1 parent 1d8bcb7 commit 5c30eb8

File tree

14 files changed

+473
-84
lines changed

14 files changed

+473
-84
lines changed

‎.github/workflows/sdk-dotnet-coverage.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: SDK CSharp Coverage
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
- "codex/**"
9+
paths:
10+
- "SDK/dotnet/**"
11+
- "SDK/fixtures/**"
12+
- ".github/workflows/sdk-dotnet.yml"
13+
- ".github/workflows/sdk-dotnet-coverage.yml"
14+
pull_request:
15+
paths:
16+
- "SDK/dotnet/**"
17+
- "SDK/fixtures/**"
18+
- ".github/workflows/sdk-dotnet.yml"
19+
- ".github/workflows/sdk-dotnet-coverage.yml"
20+
workflow_dispatch:
21+
22+
jobs:
23+
coverage:
24+
name: Coverage 90%+
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v6
28+
- uses: actions/setup-dotnet@v5
29+
with:
30+
dotnet-version: 10.0.x
31+
- run: dotnet restore SDK/dotnet/ManagedCode.Tps.slnx
32+
- run: dotnet build SDK/dotnet/ManagedCode.Tps.slnx -warnaserror --no-restore
33+
- run: dotnet test SDK/dotnet/ManagedCode.Tps.slnx --no-build --no-restore /p:CollectCoverage=true /p:CoverletOutputFormat=json /p:ThresholdType=line%2Cbranch%2Cmethod /p:Threshold=90

‎.github/workflows/sdk-dotnet.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: SDK CSharp
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
- "codex/**"
9+
paths:
10+
- "SDK/dotnet/**"
11+
- "SDK/fixtures/**"
12+
- ".github/workflows/sdk-dotnet.yml"
13+
- ".github/workflows/sdk-dotnet-coverage.yml"
14+
pull_request:
15+
paths:
16+
- "SDK/dotnet/**"
17+
- "SDK/fixtures/**"
18+
- ".github/workflows/sdk-dotnet.yml"
19+
- ".github/workflows/sdk-dotnet-coverage.yml"
20+
workflow_dispatch:
21+
22+
jobs:
23+
build-and-test:
24+
name: Build And Test
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v6
28+
- uses: actions/setup-dotnet@v5
29+
with:
30+
dotnet-version: 10.0.x
31+
- run: dotnet restore SDK/dotnet/ManagedCode.Tps.slnx
32+
- run: dotnet build SDK/dotnet/ManagedCode.Tps.slnx -warnaserror --no-restore
33+
- run: dotnet test SDK/dotnet/ManagedCode.Tps.slnx --no-build --no-restore

‎.github/workflows/sdk-javascript-coverage.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: SDK JavaScript Coverage
2+
3+
env:
4+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
5+
6+
on:
7+
push:
8+
branches:
9+
- main
10+
- master
11+
- "codex/**"
12+
paths:
13+
- "SDK/ts/**"
14+
- "SDK/js/**"
15+
- "SDK/fixtures/**"
16+
- ".github/workflows/sdk-javascript.yml"
17+
- ".github/workflows/sdk-javascript-coverage.yml"
18+
pull_request:
19+
paths:
20+
- "SDK/ts/**"
21+
- "SDK/js/**"
22+
- "SDK/fixtures/**"
23+
- ".github/workflows/sdk-javascript.yml"
24+
- ".github/workflows/sdk-javascript-coverage.yml"
25+
workflow_dispatch:
26+
27+
jobs:
28+
coverage:
29+
name: Coverage 90%+
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v6
33+
- uses: actions/setup-node@v6
34+
with:
35+
node-version: 22
36+
- run: npm ci --prefix SDK/js
37+
- run: npm --prefix SDK/js run build:tps
38+
- run: npm --prefix SDK/js run coverage:js

‎.github/workflows/sdk-javascript.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: SDK JavaScript
2+
3+
env:
4+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
5+
6+
on:
7+
push:
8+
branches:
9+
- main
10+
- master
11+
- "codex/**"
12+
paths:
13+
- "SDK/ts/**"
14+
- "SDK/js/**"
15+
- "SDK/fixtures/**"
16+
- ".github/workflows/sdk-javascript.yml"
17+
- ".github/workflows/sdk-javascript-coverage.yml"
18+
pull_request:
19+
paths:
20+
- "SDK/ts/**"
21+
- "SDK/js/**"
22+
- "SDK/fixtures/**"
23+
- ".github/workflows/sdk-javascript.yml"
24+
- ".github/workflows/sdk-javascript-coverage.yml"
25+
workflow_dispatch:
26+
27+
jobs:
28+
build-and-test:
29+
name: Build And Test
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v6
33+
- uses: actions/setup-node@v6
34+
with:
35+
node-version: 22
36+
- run: npm ci --prefix SDK/js
37+
- run: npm --prefix SDK/js run build:tps
38+
- run: npm --prefix SDK/js run test:js

‎.github/workflows/sdk-typescript.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: SDK TypeScript
2+
3+
env:
4+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
5+
6+
on:
7+
push:
8+
branches:
9+
- main
10+
- master
11+
- "codex/**"
12+
paths:
13+
- "SDK/ts/**"
14+
- "SDK/js/**"
15+
- "SDK/fixtures/**"
16+
- ".github/workflows/sdk-typescript.yml"
17+
pull_request:
18+
paths:
19+
- "SDK/ts/**"
20+
- "SDK/js/**"
21+
- "SDK/fixtures/**"
22+
- ".github/workflows/sdk-typescript.yml"
23+
workflow_dispatch:
24+
25+
jobs:
26+
build-and-test:
27+
name: Build And Typecheck
28+
runs-on: ubuntu-latest
29+
steps:
30+
- uses: actions/checkout@v6
31+
- uses: actions/setup-node@v6
32+
with:
33+
node-version: 22
34+
- run: npm ci --prefix SDK/js
35+
- run: npm --prefix SDK/js run build:tps
36+
- run: npm --prefix SDK/js run test:types

‎SDK/README.md‎

Lines changed: 56 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,50 @@
11
# ManagedCode.Tps SDK
22

3-
`SDK/` is the runtime workspace for TPS.
3+
| Runtime | Status | Build/Test | Coverage |
4+
|---------|--------|------------|----------|
5+
| TypeScript | Active | [![SDK TypeScript](https://github.com/managedcode/TPS/actions/workflows/sdk-typescript.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-typescript.yml) | — |
6+
| JavaScript | Active | [![SDK JavaScript](https://github.com/managedcode/TPS/actions/workflows/sdk-javascript.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-javascript.yml) | [![SDK JavaScript Coverage](https://github.com/managedcode/TPS/actions/workflows/sdk-javascript-coverage.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-javascript-coverage.yml) |
7+
| C# | Active | [![SDK CSharp](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet.yml) | [![SDK CSharp Coverage](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet-coverage.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet-coverage.yml) |
8+
| Flutter | Planned | ![Status](https://img.shields.io/badge/status-planned-c4a060) | — |
9+
| Swift | Planned | ![Status](https://img.shields.io/badge/status-planned-c4a060) | — |
10+
| Java | Planned | ![Status](https://img.shields.io/badge/status-planned-c4a060) | — |
411

5-
## Layout
12+
`SDK/` is the multi-runtime workspace for `ManagedCode.Tps`.
613

7-
- `ts/`: canonical TPS source implementation
8-
- `js/`: emitted JS runtime, JS-facing tests, and the JS-local package
9-
- `dotnet/`: .NET runtime, solution, and xUnit tests
10-
- `fixtures/`: shared TPS fixtures and runtime expectations
11-
- `docs/`: SDK architecture and ADRs
12-
- `manifest.json`: enabled runtimes plus CI commands
13-
14-
## Common Contract
14+
## What This Workspace Contains
1515

16-
Every active runtime must provide:
16+
This folder is where TPS runtime implementations live. The goal is parity across active runtimes:
1717

18-
- a constants catalog for TPS keywords, tags, metadata keys, emotions, and diagnostics
18+
- constants catalog
1919
- TPS validation with actionable diagnostics
2020
- TPS parsing into a document model
2121
- TPS compilation into a JSON-friendly state machine
22-
- a player API that resolves the current presentation model from compiled data
22+
- player/runtime APIs that resolve what to display at a specific elapsed time
23+
24+
The TypeScript runtime is the canonical implementation. The JavaScript runtime is the consumer-facing built artifact of that source. The .NET runtime is an independent implementation under the `ManagedCode.Tps` namespace.
25+
26+
## Workspace Layout
27+
28+
- `ts/`: canonical TypeScript implementation
29+
- `js/`: generated JavaScript runtime, Node tests, and package metadata
30+
- `dotnet/`: .NET runtime, solution, and xUnit tests
31+
- `flutter/`: reserved Flutter runtime folder
32+
- `swift/`: reserved Swift runtime folder
33+
- `java/`: reserved Java runtime folder
34+
- `fixtures/`: shared TPS fixtures and expected runtime behavior
35+
- `docs/`: SDK ADRs and architecture notes
36+
- `manifest.json`: internal runtime matrix source for CI and site generation
37+
38+
## Runtime Guide
39+
40+
| Folder | Purpose | Edit Here When | Main Commands |
41+
|--------|---------|----------------|---------------|
42+
| `SDK/ts` | canonical runtime source | changing TPS behavior or runtime contract | `npm --prefix SDK/js run build:tps`, `npm --prefix SDK/js run test:types` |
43+
| `SDK/js` | JavaScript package and Node validation | changing JS packaging or JS-specific tests | `npm --prefix SDK/js run test:js`, `npm --prefix SDK/js run coverage:js` |
44+
| `SDK/dotnet` | C# runtime and tests | changing .NET API or .NET behavior | `dotnet build SDK/dotnet/ManagedCode.Tps.slnx -warnaserror --no-restore`, `dotnet test SDK/dotnet/ManagedCode.Tps.slnx --no-build --no-restore` |
45+
| `SDK/flutter` | placeholder | starting Flutter implementation | define runtime structure, tests, and workflow |
46+
| `SDK/swift` | placeholder | starting Swift implementation | define runtime structure, tests, and workflow |
47+
| `SDK/java` | placeholder | starting Java implementation | define runtime structure, tests, and workflow |
2348

2449
## Compiled Model
2550

@@ -31,17 +56,27 @@ The compiled TPS state machine is organized as:
3156
4. phrases
3257
5. words
3358

34-
Each compiled word carries timing plus authoring-derived metadata such as emphasis, emotion hint, speed override, pronunciation, volume, delivery mode, and edit-point markers.
59+
Each compiled word carries timing and authoring-derived metadata such as emphasis, emotion, speed override, pronunciation, volume, delivery mode, and edit-point markers.
60+
61+
## How To Work In This SDK
3562

36-
## Verification
63+
1. Change the TPS contract in `SDK/ts` first unless the work is package-specific or .NET-specific.
64+
2. Rebuild the JS runtime from the TS source.
65+
3. Run the runtime-specific tests for the SDK you changed.
66+
4. If behavior changes, keep parity across active runtimes and shared fixtures.
67+
68+
## Local Verification
3769

3870
- TypeScript: `npm --prefix SDK/js run test:types`
3971
- JavaScript: `npm --prefix SDK/js run coverage:js`
40-
- C#: `dotnet test SDK/dotnet/ManagedCode.Tps.slnx /p:CollectCoverage=true /p:CoverletOutputFormat=json /p:ThresholdType=line%2Cbranch%2Cmethod /p:Threshold=90`
41-
42-
GitHub Actions reads `SDK/manifest.json`, builds the enabled runtimes, runs their tests, and enforces a minimum runtime coverage gate of 90%.
72+
- C#: `dotnet test SDK/dotnet/ManagedCode.Tps.slnx --no-build --no-restore /p:CollectCoverage=true /p:CoverletOutputFormat=json /p:ThresholdType=line%2Cbranch%2Cmethod /p:Threshold=90`
4373

44-
## GitHub Pipelines
74+
## GitHub Workflows
4575

46-
- `.github/workflows/ci.yml`: build and test pipeline
47-
- `.github/workflows/coverage.yml`: separate coverage pipeline with the `>= 90%` gates
76+
- `.github/workflows/ci.yml`: repo-wide build/test matrix
77+
- `.github/workflows/coverage.yml`: repo-wide coverage matrix
78+
- `.github/workflows/sdk-typescript.yml`: TypeScript build and typecheck badge target
79+
- `.github/workflows/sdk-javascript.yml`: JavaScript build/test badge target
80+
- `.github/workflows/sdk-javascript-coverage.yml`: JavaScript coverage badge target
81+
- `.github/workflows/sdk-dotnet.yml`: C# build/test badge target
82+
- `.github/workflows/sdk-dotnet-coverage.yml`: C# coverage badge target

‎SDK/dotnet/README.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
# ManagedCode.Tps .NET SDK
22

3+
[![SDK CSharp](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet.yml)
4+
[![SDK CSharp Coverage](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet-coverage.yml/badge.svg?branch=main)](https://github.com/managedcode/TPS/actions/workflows/sdk-dotnet-coverage.yml)
5+
36
This folder contains the .NET TPS runtime under the `ManagedCode.Tps` namespace.
47

8+
Package identity: `ManagedCode.Tps`
9+
10+
## What This Project Is
11+
12+
`SDK/dotnet` is the C# implementation of the TPS runtime. It provides the same functional surface as the active TypeScript/JavaScript SDKs, but as a native .NET library under the `ManagedCode.Tps` namespace.
13+
14+
This is the project to change when the .NET API, serialization behavior, or .NET runtime semantics need to evolve.
15+
516
## Public API
617

718
- `TpsSpec`: TPS constants, tags, metadata keys, emotions, diagnostics, and palettes
@@ -15,14 +26,27 @@ This folder contains the .NET TPS runtime under the `ManagedCode.Tps` namespace.
1526
- `src/ManagedCode.Tps/`: runtime implementation
1627
- `tests/ManagedCode.Tps.Tests/`: xUnit coverage and parity tests
1728

18-
## Contract Notes
29+
## Technical Scope
1930

2031
- validation returns actionable `TpsDiagnostic` entries with exact ranges
2132
- parse returns the TPS document model with segments and blocks
2233
- compile returns the fully timed state machine with compiled words, phrases, blocks, and segments
2334
- player resolves the current presentation model for any elapsed timestamp
2435

25-
## Verification
36+
## How To Work With This Project
37+
38+
1. Update `src/ManagedCode.Tps/` for runtime or API changes.
39+
2. Keep behavior aligned with the active TPS contract used by the TS/JS SDKs.
40+
3. Run build, tests, and coverage checks after changes.
41+
42+
## Local Commands
2643

2744
- `dotnet build ManagedCode.Tps.slnx -warnaserror --no-restore`
45+
- `dotnet test ManagedCode.Tps.slnx --no-build --no-restore`
2846
- `dotnet test ManagedCode.Tps.slnx --no-build --no-restore /p:CollectCoverage=true /p:CoverletOutputFormat=json /p:ThresholdType=line%2Cbranch%2Cmethod /p:Threshold=90`
47+
48+
## Target Runtime
49+
50+
- `TargetFramework`: `net10.0`
51+
- `AssemblyName`: `ManagedCode.Tps`
52+
- `RootNamespace`: `ManagedCode.Tps`

‎SDK/flutter/README.md‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,32 @@
1-
# Flutter SDK Placeholder
1+
# ManagedCode.Tps Flutter SDK
2+
3+
![Status](https://img.shields.io/badge/status-planned-c4a060)
4+
![CI](https://img.shields.io/badge/ci-not%20configured-b8afa1)
25

36
This folder is reserved for a future TPS runtime in Flutter.
47

5-
Activation happens by enabling the runtime in `SDK/manifest.json` and adding build and test commands.
8+
## What This Project Is
9+
10+
`SDK/flutter` is a placeholder only. There is no Flutter TPS runtime implementation here yet.
11+
12+
## Intended Scope
13+
14+
When implemented, this project should provide:
15+
16+
- TPS constants and keywords
17+
- validation diagnostics
18+
- parser and compiler APIs
19+
- player/runtime APIs for compiled TPS playback
20+
21+
## Current State
22+
23+
- no source runtime yet
24+
- no tests yet
25+
- no CI workflow yet
26+
27+
## What To Do When Flutter Work Starts
28+
29+
1. add the actual Flutter/Dart runtime source
30+
2. add tests and fixture coverage
31+
3. add a runtime-specific workflow and badges
32+
4. document local commands in this README

0 commit comments

Comments
 (0)