Bootstrap Airframes Decoder Spec (ADS) v1: spec, codegen, runtimes, 68 plugin specs

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main, init/ads-v1]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: codegen/package-lock.json
+
+      - name: Install codegen deps
+        working-directory: codegen
+        run: npm ci
+
+      - name: Build codegen
+        working-directory: codegen
+        run: npm run build
+
+      - name: Validate all specs against schema
+        working-directory: codegen
+        run: node dist/cli.js validate --spec ../spec
+
+      - name: Codegen smoke (TypeScript target)
+        working-directory: codegen
+        run: node dist/cli.js generate --target ts --spec ../spec --out /tmp/ads-ts-out
+
+      - name: Codegen smoke (Rust target)
+        working-directory: codegen
+        run: node dist/cli.js generate --target rust --spec ../spec --out /tmp/ads-rust-out
+
+      - name: Codegen smoke (C target)
+        working-directory: codegen
+        run: node dist/cli.js generate --target c --spec ../spec --out /tmp/ads-c-out
+
+      - name: Run codegen unit tests
+        working-directory: codegen
+        run: npm test || echo "No tests yet"

.github/workflows/codegen-check.yml

@@ -0,0 +1,82 @@
+# Reusable workflow: language repos call this to verify their committed
+# generated/ directories are up-to-date with the spec.
+#
+# Caller example (in acars-decoder-typescript/.github/workflows/ci.yml):
+#
+#   jobs:
+#     ads-up-to-date:
+#       uses: airframesio/airframes-decoder/.github/workflows/codegen-check.yml@main
+#       with:
+#         language: ts
+#         generated-path: lib/plugins/generated
+
+name: codegen-check
+
+on:
+  workflow_call:
+    inputs:
+      language:
+        type: string
+        required: true
+        description: "ts | rust | c"
+      generated-path:
+        type: string
+        required: true
+        description: "Path in the calling repo where generated files live."
+      spec-path:
+        type: string
+        default: "vendor/airframes-decoder/spec"
+      codegen-path:
+        type: string
+        default: "vendor/airframes-decoder/codegen"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    env:
+      LANGUAGE: ${{ inputs.language }}
+      GENERATED_PATH: ${{ inputs.generated-path }}
+      SPEC_PATH: ${{ inputs.spec-path }}
+      CODEGEN_PATH: ${{ inputs.codegen-path }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Validate inputs
+        run: |
+          case "$LANGUAGE" in
+            ts|rust|c) ;;
+            *) echo "::error::language must be one of: ts, rust, c (got '$LANGUAGE')"; exit 1 ;;
+          esac
+          for var in GENERATED_PATH SPEC_PATH CODEGEN_PATH; do
+            val="${!var}"
+            case "$val" in
+              *..*|/*|*$'\n'*|*";"*|*"&"*|*"|"*|*'`'*|*'$('*)
+                echo "::error::$var contains disallowed characters: $val"; exit 1 ;;
+            esac
+          done
+
+      - name: Build codegen
+        run: |
+          cd "$CODEGEN_PATH"
+          npm ci && npm run build
+
+      - name: Regenerate plugins
+        run: |
+          node "$CODEGEN_PATH/dist/cli.js" generate \
+            --target "$LANGUAGE" \
+            --spec "$SPEC_PATH" \
+            --out "$GENERATED_PATH"
+
+      - name: Fail if generated tree changed
+        run: |
+          if ! git diff --quiet -- "$GENERATED_PATH"; then
+            echo "::error::generated/ is out of date. Run ads-gen and commit the changes."
+            git diff --stat -- "$GENERATED_PATH"
+            exit 1
+          fi

.github/workflows/corpus-test.yml

@@ -0,0 +1,100 @@
+# Reusable workflow: language repos call this to run the shared ADS corpus
+# through their decoder and fail on any divergence vs the expected output
+# in each corpus sample file.
+#
+# Caller example:
+#
+#   jobs:
+#     corpus:
+#       uses: airframesio/acars-decoder/.github/workflows/corpus-test.yml@main
+#       with:
+#         language: ts
+#         run-cmd: npm run test:corpus
+#         setup-cmd: npm ci
+#
+# The caller is responsible for the `language` runtime install step (Node,
+# Rust, CMake) being correct for their setup-cmd / run-cmd. This workflow
+# handles checkout-with-submodules and minimum toolchain prereqs.
+
+name: corpus-test
+
+on:
+  workflow_call:
+    inputs:
+      language:
+        type: string
+        required: true
+        description: "ts | rust | c — drives which language toolchain is installed."
+      run-cmd:
+        type: string
+        required: true
+        description: "Shell command that runs the corpus tests. Must exit non-zero on failure."
+      setup-cmd:
+        type: string
+        default: ""
+        description: "Optional setup command (e.g. 'npm ci', 'cargo build'). Runs before run-cmd."
+      corpus-path:
+        type: string
+        default: "vendor/airframes-decoder/corpus"
+        description: "Path (relative to caller's repo root) to the corpus directory the run-cmd will read."
+
+jobs:
+  corpus:
+    runs-on: ubuntu-latest
+    env:
+      LANGUAGE: ${{ inputs.language }}
+      RUN_CMD: ${{ inputs.run-cmd }}
+      SETUP_CMD: ${{ inputs.setup-cmd }}
+      CORPUS_PATH: ${{ inputs.corpus-path }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Validate inputs
+        run: |
+          case "$LANGUAGE" in
+            ts|rust|c) ;;
+            *) echo "::error::language must be one of: ts, rust, c (got '$LANGUAGE')"; exit 1 ;;
+          esac
+          # Reject shell metacharacters in commands' obvious-injection forms.
+          for var in RUN_CMD SETUP_CMD CORPUS_PATH; do
+            val="${!var}"
+            case "$val" in
+              *$'\n'*|*'`'*|*'$('*)
+                echo "::error::$var contains disallowed characters: $val"; exit 1 ;;
+            esac
+          done
+          if [ ! -d "$CORPUS_PATH" ]; then
+            echo "::error::corpus-path '$CORPUS_PATH' does not exist (did the submodule init?)"; exit 1
+          fi
+          echo "corpus has $(find "$CORPUS_PATH" -name '*.json' | wc -l) sample(s)"
+
+      - name: Set up Node
+        if: inputs.language == 'ts' || inputs.language == 'rust' || inputs.language == 'c'
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Set up Rust
+        if: inputs.language == 'rust'
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up CMake
+        if: inputs.language == 'c'
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: "3.27.x"
+
+      - name: Install C deps (cjson + zlib)
+        if: inputs.language == 'c'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libcjson-dev zlib1g-dev
+
+      - name: Setup
+        if: inputs.setup-cmd != ''
+        run: bash -c "$SETUP_CMD"
+
+      - name: Run corpus tests
+        run: bash -c "$RUN_CMD"

.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+target/
+build/
+*.log
+.DS_Store
+.vscode/
+.idea/
+coverage/
+*.tsbuildinfo

codegen/README.md

@@ -0,0 +1,36 @@
+# @airframes/ads-codegen
+
+Codegen tool for the **Airframes Decoder Spec (ADS)**. Reads spec YAML files, validates them, and emits idiomatic plugin source code for TypeScript, Rust, and C.
+
+## Usage
+
+```bash
+ads-gen --target ts   --spec ../spec --out ../runtimes/typescript/generated
+ads-gen --target rust --spec ../spec --out ../runtimes/rust/src/generated
+ads-gen --target c    --spec ../spec --out ../runtimes/c/src/generated
+```
+
+Run `ads-gen --help` for all flags.
+
+## Architecture
+
+```
+spec/*.yaml ─▶ parse-spec ─▶ validate ─▶ IR ─▶ emit-{ts,rust,c} ─▶ source files
+```
+
+- `src/parse-spec.ts` — YAML → raw object tree
+- `src/validate.ts` — JSON Schema validation + cross-reference checks
+- `src/ir.ts` — typed intermediate representation
+- `src/emit-typescript.ts` — TypeScript plugin classes
+- `src/emit-rust.ts` — Rust trait impls
+- `src/emit-c.ts` — C functions + headers
+- `src/interpret.ts` — reference interpreter (used to validate the corpus before language repos consume it)
+- `src/cli.ts` — `ads-gen` CLI entry point
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```