Add spec module (#3)

* Add preflight-spec module and upgrade Gradle to 9.3.1

Introduces the preflight-spec module — a standalone markdown parsing/writing
library for Preflight test spec files. Each spec is a markdown file that
serves as both living documentation and a machine-parseable test definition.

- New module: preflight-core/preflight-spec with TestSpecReader, TestSpecWriter,
  data model (TestSpec, Stub, StubMode), and internal parsers for front matter
  and HTML comment directives
- 46 tests covering parsing, writing, round-trip, and error cases
- MarkdownSpec base class in preflight-runtime for executing spec files as
  Kotest tests
- Upgraded all Gradle wrappers from 8.13 to 9.3.1 (bundles Kotlin 2.2.21,
  required for Orbital 0.37.0-SNAPSHOT compatibility)
- Fixed KafkaContainerSupport for removed emitConsumerInfoMessages parameter
- Removed broken ExamplesSpec that referenced compileOnly types from test source

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Gitignore .idea/kotlinc.xml

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add ResultFormat to support typedInstance qualifier in Expected Results

The Expected Results code block info string can now include a format
qualifier (e.g. `json typedInstance`) to distinguish plain JSON from
Orbital TypedInstance JSON. Defaults to plain JSON for backwards
compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Auto-discover and execute .spec.md files as tests

The Gradle plugin now generates a PreflightSpecRunner test class that
extends MarkdownSpec, so any .spec.md files in test-resources/specs/
are automatically discovered and run as tests without hand-written code.

MarkdownSpec now filters for the .spec.md suffix specifically.

Includes a new spec-project example demonstrating spec-only testing
with no Kotlin test files required.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add BUILDING.md and fix release workflow

Add build/release documentation covering local builds, Maven Local
publishing, version bumping, and the release process.

Fix release.yml to also publish preflight-spec to the Orbital Maven
repo and add missing AWS credentials for S3 authentication.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* added docs on new spec format

* Default the version on TestSpec

* Update default versions of Taxi and Orbital

* Added building notes

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: martypitt

.github/workflows/release.yml

@@ -31,12 +31,14 @@ jobs:
       run: echo "GPG key loaded"
 
     - name: Build and publish
-      run: ./gradlew build :preflight-core:preflight-gradle-plugin:publishPlugins :preflight-core:preflight-runtime:publishMavenPublicationToOrbitalRepository
+      run: ./gradlew build :preflight-core:preflight-gradle-plugin:publishPlugins :preflight-core:preflight-runtime:publishMavenPublicationToOrbitalRepository :preflight-core:preflight-spec:publishMavenPublicationToOrbitalRepository
       env:
         GRADLE_PUBLISH_KEY: ${{ secrets.GRADLE_PUBLISH_KEY }}
         GRADLE_PUBLISH_SECRET: ${{ secrets.GRADLE_PUBLISH_SECRET }}
         GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
         GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
 
     - name: Create GitHub Release
       uses: softprops/action-gh-release@v1

.gitignore

@@ -19,6 +19,7 @@
 .idea/**/contentModel.xml
 
 # Sensitive or high-churn files
+.idea/**/kotlinc.xml
 .idea/**/dataSources/
 .idea/**/dataSources.ids
 .idea/**/dataSources.local.xml

.idea/kotlinc.xml

@@ -0,0 +1,107 @@
+# Building and Releasing
+
+## Building locally
+
+```bash
+cd preflight-core
+./gradlew build
+```
+
+This builds all modules (`preflight-spec`, `preflight-runtime`, `preflight-gradle-plugin`) and runs their tests.
+
+To also run the example project tests:
+
+```bash
+# From the repo root
+./gradlew build
+```
+
+## Installing to local Maven repo
+
+To test changes locally before releasing, publish all modules to `~/.m2`:
+
+```bash
+cd preflight-core
+./gradlew publishAllMavenLocal
+```
+
+### Using a local pre-release version in another project
+
+Consuming projects need `mavenLocal()` in their `pluginManagement` repositories so Gradle can find the locally-published plugin:
+
+```kotlin
+// settings.gradle.kts
+pluginManagement {
+    repositories {
+        mavenLocal()
+        gradlePluginPortal()
+    }
+}
+```
+
+Then reference the local version in `build.gradle.kts`:
+
+```kotlin
+plugins {
+    id("com.orbitalhq.preflight") version "0.1.0" // matches the version you published locally
+}
+```
+
+The plugin itself injects the Orbital Maven repositories automatically, so no other repository configuration is needed in the consuming project.
+
+## Bumping the version
+
+The version is set in one place: `preflight-core/build.gradle.kts`
+
+```kotlin
+allprojects {
+    group = "com.orbitalhq.preflight"
+    version = "0.1.0"  // <-- change this
+}
+```
+
+All submodules inherit this version. The Gradle plugin also embeds it at build time via a generated `Versions.kt` constant.
+
+## Releasing
+
+Releases are triggered by pushing a git tag. GitHub Actions handles building, signing, and publishing.
+
+```bash
+# 1. Make sure you're on main with a clean tree
+git checkout main
+git pull
+
+# 2. Bump the version in preflight-core/build.gradle.kts, commit
+
+# 3. Tag the release
+git tag v0.1.0
+
+# 4. Push the commit and tag
+git push origin main
+git push origin v0.1.0
+```
+
+The `release.yml` workflow then:
+1. Builds the project with JDK 21
+2. Signs artifacts with GPG
+3. Publishes the Gradle plugin to the **Gradle Plugin Portal**
+4. Publishes `preflight-runtime` and `preflight-spec` to the **Orbital Maven repository** (`s3://repo.orbitalhq.com/release`)
+5. Creates a GitHub Release with JARs and auto-generated notes
+
+## Where artifacts are published
+
+| Artifact                                | Destination                                               | How consumers resolve it                                    |
+|-----------------------------------------|-----------------------------------------------------------|-------------------------------------------------------------|
+| `com.orbitalhq.preflight` Gradle plugin | [Gradle Plugin Portal](https://plugins.gradle.org/)       | `plugins { id("com.orbitalhq.preflight") }`                 |
+| `preflight-runtime`                     | Orbital Maven repo (`https://repo.orbitalhq.com/release`) | `maven { url = uri("https://repo.orbitalhq.com/release") }` |
+| `preflight-spec`                        | Orbital Maven repo (same)                                 | Same repository config                                      |
+
+Nothing is published to Maven Central. Consumers need the Orbital Maven repository in their `repositories {}` block to resolve the runtime (the Gradle plugin injects this automatically).
+
+## Required CI secrets
+
+These must be configured in the GitHub repository settings:
+
+- `GRADLE_PUBLISH_KEY` / `GRADLE_PUBLISH_SECRET` — Gradle Plugin Portal credentials
+- `GPG_PRIVATE_KEY` / `GPG_PASSPHRASE` — artifact signing
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — S3 access for Orbital Maven repo

.idea/modules.xml

@@ -2,6 +2,7 @@ export default {
     // Controlling the order these are shown in the sidebar
     "index": "Getting started",
     "writing-tests" : "Writing tests",
+    "spec-files" : "Spec files",
     "stubbing" : "Stubbing responses",
     "integration-testing": "Integration testing",
     "environment-variables" : "Environment variables",

BUILDING.md

@@ -89,15 +89,19 @@ Here's the directory structure:
 ```
 ├── src
 │   └── schema.taxi
-├── test
+├── test                        (Optional - for Kotlin tests)
 │   └── SchemaSpec.kt
-└── test-resources (Optional)
-    └── env.conf (Optional)
+├── test-resources
+│   ├── env.conf                (Optional - environment variables)
+│   └── specs                   (Optional - markdown spec files)
+│       └── my-test.spec.md
 taxi.conf
 build.gradle.kts
 settings.gradle.kts (Often blank)
 ```
 
+Tests can be written as Kotlin code in `test/` (see [Writing tests](/writing-tests)), as markdown spec files in `test-resources/specs/` (see [Spec files](/spec-files)), or both.
+
 Then, to write your first test, create a folder `test` next to your `src` folder.
 By convention, these are named ending in `Spec.kt` or `Test.kt`.