build: Add Makefile; replace inline knit logic with Makefile target in GitHub workflow

.github/workflows/checks.yml

@@ -209,20 +209,7 @@ jobs:
       - uses: gradle/actions/setup-gradle@v5
       - name: Verify code snippets in docs
         run: |
-          echo "Starting knit generation..."
-          FILES_BEFORE_KNIT=$(find docs/src/ -name "*.kt" 2>/dev/null | wc -l || echo "0")
-          echo "Files before knit: $FILES_BEFORE_KNIT"
-
-          ./gradlew :docs:knit 
-
-          FILES_AFTER_KNIT=$(find docs/src/ -name "*.kt" 2>/dev/null | wc -l || echo "0")
-          echo "Files after knit: $FILES_AFTER_KNIT"
-
-          KNIT_GENERATED_FILES=$((FILES_AFTER_KNIT - FILES_BEFORE_KNIT))
-          echo "Knit generated $KNIT_GENERATED_FILES files"
-
-          echo "Starting assemble..."
-          ./gradlew :docs:assemble
+          make knit
 
   dokka:
     needs: changes

CONTRIBUTING.md

@@ -177,6 +177,23 @@ This project is built with Gradle.
 * Run `./gradlew <module>:check` to test the module you are looking and to speed
   things up during development.
 
+There is also a [Makefile](Makefile) with Gradle command shortcuts that encode the correct flags and task ordering so you don't have to remember them.
+Run `make help` for a full list. Key targets:
+
+* `make help` — shows available commands with descriptions.
+* `make all` — runs clean, format, lint, test, and knit (default target).
+* `make format` — format code with ktlintFormat.
+* `make lint` — run detekt and ktlintCheck.
+* `make test` — run unit tests (JVM) and check ABI compatibility.
+* `make it` — run integration tests.
+* `make ios-test` — run iOS simulator tests.
+* `make knit` — verify that all code snippets in documentation are up-to-date.
+* `make clean` — clean the project.
+* `make publish` — publish to Maven Local.
+* `make build-compose-example` — build the Compose demo app (runs publish first).
+* `make pom` — generate POM files for JVM publications.
+* `make apidocs` — generate API documentation with Dokka.
+
 You can import this project into IDEA, but you have to delegate build actions
 to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Build and run).
 

Makefile

@@ -0,0 +1,78 @@
+# Default task
+.PHONY: all
+all: clean format lint test knit
+
+# Show available targets
+.PHONY: help
+help:
+	@echo "Available targets:"
+	@echo "  make all                 - Run clean, format, lint, test, and knit"
+	@echo "  make format              - Format code with ktlintFormat"
+	@echo "  make lint                - Run detekt and ktlintCheck"
+	@echo "  make test                - Run unit tests (JVM) and check ABI"
+	@echo "  make it                  - Run integration tests"
+	@echo "  make ios-test            - Run iOS simulator tests"
+	@echo "  make knit                - Generate and verify doc code snippets"
+	@echo "  make clean               - Clean the project"
+	@echo "  make publish             - Publish to Maven Local"
+	@echo "  make build-compose-example - Build Compose demo app (runs publish first)"
+	@echo "  make pom                 - Generate POM files for JVM publications"
+	@echo "  make apidocs             - Generate API docs with Dokka"
+
+# Format the code
+.PHONY: format
+format:
+	./gradlew ktlintFormat
+
+# Lint the code
+.PHONY: lint
+lint:
+	./gradlew detekt ktlintCheck
+
+# Publish to Maven Local (clears previous koog artifacts to ensure a clean publish)
+.PHONY: publish
+publish:
+	rm -rf ~/.m2/repository/ai/koog
+	./gradlew publishToMavenLocal
+
+# Build the Compose demo app (publishes to Maven Local first)
+.PHONY: build-compose-example
+build-compose-example: publish
+	cd examples/demo-compose-app && \
+	./gradlew assemble
+
+# Run unit tests
+.PHONY: test
+test:
+	./gradlew checkLegacyAbi jvmTest :integration-tests:jvmTestClasses --exclude-task :integration-tests:jvmTest
+
+# Run integration tests
+.PHONY: it
+it:
+	./gradlew :integration-tests:jvmIntegrationTest
+
+# Run iOS simulator tests
+.PHONY: ios-test
+ios-test:
+	./gradlew iosSimulatorArm64Test --exclude-task :integration-tests:jvmTest
+
+# Clean the project
+.PHONY: clean
+clean:
+	./gradlew clean
+
+# Generate POM files for JVM publications
+.PHONY: pom
+pom:
+	./gradlew generatePomFileForJvmPublication
+
+# Generate and verify documentation code snippets
+.PHONY: knit
+knit:
+	@echo "Starting knit generation..."
+	./gradlew :docs:knitAssemble
+
+# Generate API documentation with Dokka
+.PHONY: apidocs
+apidocs:
+	./gradlew dokkaGenerate -Pdokka.jvmOnly=true