Skip to content

Wave 12: compiler-github package - #14

Merged
ThePlenkov merged 4 commits into
wave-11-checksfrom
wave-12-compiler-github
Aug 11, 2026
Merged

ThePlenkov merged 4 commits into
wave-11-checksfrom
wave-12-compiler-github

Conversation

@ThePlenkov

@ThePlenkov ThePlenkov commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

User description

Summary

  • @sverka/compiler-github package: pure function compileGithubWorkflow(plan, config?) that compiles a canonical Sverka Plan IR to a GitHub Actions workflow YAML string
  • Thin wrapper per ADR-004: single job runs sverka execute .sverka/plan.json
  • Maps plan credentials (CredentialDeclaration.envVar) to job-level env: block with ${{ secrets.VAR }} references
  • camelCase → kebab-case conversion for permissions (securityEvents → security-events) and triggers (pullRequest → pull_request, workflowDispatch → workflow_dispatch)
  • Deterministic output: same plan + config → identical YAML
  • No custom errors (pure function on validated Plan; native Error propagates)
  • 13 tests pass (compile 10, public-api 3)

Stack: main → #1 → #2 → #3 → #5 → #6 → #7 → #8 → #9 → #10 → #11 → #13 (wave-11-checks) → this PR

Test plan

  • compiler-github vitest: 13 pass (2 files)
  • typecheck: 0 errors
  • lint: 0 errors
  • build: dist/index.mjs + dist/index.d.mts emitted
  • full monorepo: 16 projects green (test + typecheck + lint + build, --skip-nx-cache)
  • no any types in implementation
  • exports match spec 1:1 (1 function + 3 types)
  • YAML output verified valid GitHub Actions (on: key, pull_request: null, env block, step order)
  • spec test plan items 1-10 all covered

Generated with Devin


Summary by cubic

Adds @sverka/compiler-github, a pure compileGithubWorkflow(plan, config?) that compiles a Sverka Plan into a deterministic GitHub Actions workflow. Generates one job that checks out, sets up Node 24 and Bun, installs Sverka, runs sverka execute, and uploads .sverka/output/ artifacts.

  • New Features

    • Single job: actions/checkout@v4, actions/setup-node@v4 (Node "24"), oven-sh/setup-bun@v2, bun install -g sverka@<version>, sverka execute, upload .sverka/output/ via actions/upload-artifact@v4 (if: always()).
    • Credentials → job env: with ${{ secrets.VAR }} (deduped); omits env: when none.
    • Defaults: name "Sverka", runner ubuntu-latest, permissions: { contents: "read" }, triggers push: [main] + pull_request; optional workflow_dispatch.
  • Bug Fixes

    • Correct kebab-case conversion (no leading hyphen); restrict id-token to "write".
    • Removed the .sverka/plan.json arg from sverka execute; added explicit Bun setup via oven-sh/setup-bun@v2.

Written for commit 095dc11. Summary will update on new commits.

Review in cubic


CodeAnt-AI Description

Generate configurable GitHub Actions workflows from Sverka plans

What Changed

  • Added a public compiler that turns a Sverka plan into a deterministic GitHub Actions workflow YAML string
  • Generated workflows check out the repository, set up Node and Bun, install the selected Sverka version, run sverka execute, and upload output artifacts even when execution fails
  • Added configurable workflow names, runners, tool versions, triggers, and GitHub permissions, with defaults for common CI use
  • Declared plan credentials are exposed through GitHub Secrets in a deduplicated job-level environment block
  • Added coverage for default and custom workflows, triggers, credentials, permissions, deterministic output, empty plans, and the public API

Impact

✅ Faster setup for GitHub Actions workflows
✅ Credentials available from GitHub Secrets
✅ Artifacts preserved after failed checks

🔄 Retrigger CodeAnt AI Review

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

@codeant-ai

codeant-ai Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

🤖 CodeAnt AI — Review Status

Status Commit Started (UTC) Finished (UTC)
✅ Incremental review completed f5420b8 Aug 11, 2026 · 08:44 08:45
✅ Incremental review completed d9ec4d3 Aug 11, 2026 · 06:26 06:26
✅ Incremental review completed 2155ccb Aug 11, 2026 · 00:50 00:51
✅ Incremental review completed 5c2a220 Aug 10, 2026 · 20:27 20:28
✅ Reviewed your PR e89a8c0 Aug 10, 2026 · 08:39 08:42

@coderabbitai

coderabbitai Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Summary by CodeRabbit

  • New Features

    • Added a GitHub Actions workflow compiler that generates ready-to-use YAML from execution plans.
    • Supports configurable workflow metadata, triggers, permissions, runners, runtime versions, and credential-based secret environment variables.
    • Generated workflows include checkout, setup, installation, execution, and artifact upload steps.
    • Provides deterministic output and sensible defaults, including support for plans with no operations.
  • Documentation

    • Added implementation and specification documentation for the GitHub compiler.
  • Tests

    • Added coverage for configuration, credentials, permissions, defaults, determinism, and public API behavior.

Walkthrough

The PR defines a synchronous GitHub workflow compiler, adds its public types and exports, implements deterministic YAML generation from Plan data, maps credentials to GitHub secrets, and adds package configuration and Vitest coverage.

Changes

GitHub workflow compilation

Layer / File(s) Summary
Compiler scope and public contract
engdocs/architecture/wave-12-compiler-github-plan.md, specs/12-compiler-github/spec.md
The specification and implementation plan define a synchronous thin-wrapper API, supported configuration, credential mapping, deterministic serialization, excluded features, and verification gates.
Compiler implementation and package wiring
packages/compiler-github/src/types.ts, packages/compiler-github/src/compile.ts, packages/compiler-github/src/index.ts, packages/compiler-github/package.json, packages/compiler-github/project.json
The package adds typed configuration, workflow generation, trigger and permission conversion, credential secret mapping, execution steps, artifact upload, YAML serialization, public exports, dependencies, and updated package commands.
Fixtures and compiler validation
packages/compiler-github/src/__tests__/*
Vitest coverage verifies defaults, custom settings, triggers, credentials, permissions, deterministic output, empty plans, fixtures, and public runtime exports.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Plan
  participant compileGithubWorkflow
  participant yaml
  participant GitHubActions
  Plan->>compileGithubWorkflow: provide plan and compiler configuration
  compileGithubWorkflow->>compileGithubWorkflow: construct workflow triggers, permissions, env, and steps
  compileGithubWorkflow->>yaml: serialize workflow
  yaml-->>compileGithubWorkflow: return YAML
  compileGithubWorkflow-->>GitHubActions: consume generated workflow
Loading

Possibly related PRs

  • sverka-dev/sverka#2: Provides the Plan and PlanOperation types consumed by the compiler.
  • sverka-dev/sverka#11: Provides plan conversion and credential environment data used by workflow generation.
  • sverka-dev/sverka#16: Adds an analogous synchronous thin-wrapper compiler with deterministic YAML output.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 77.78% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title identifies the Wave 12 compiler-github package, which is the main change in the pull request.
Description check ✅ Passed The description clearly explains the new compiler package, generated workflows, configuration, credential mapping, tests, and validation.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch wave-12-compiler-github

Comment @coderabbitai help to get the list of available commands.

@codeant-ai codeant-ai Bot added the size:XL This PR changes 500-999 lines, ignoring generated files label Aug 10, 2026
@baz-reviewer

baz-reviewer Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Merger

Needs Review

Generated credential mappings are not usable by operations: the SDK supplies empty credentials and the host executor forwards only its PATH allowlist, so GitHub secret environment variables are dropped before checks run. This concrete security/correctness issue needs human review, and no CI ran for the non-trivial change.

Commit 095dc11 · Evaluated 2026-08-11 16:20 UTC

Review this PR on Baz | Customize your next review

@amazon-q-developer amazon-q-developer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review Summary

This PR introduces the @sverka/compiler-github package that compiles Sverka Plan IR to GitHub Actions workflows. I've identified critical logic errors that prevent the code from functioning correctly and must be fixed before merge.

Critical Issues Found (4)

  1. toKebab() function creates invalid output - Produces leading hyphens for capitalized strings (e.g., "Contents" → "-contents"), which will generate malformed GitHub Actions YAML
  2. buildTriggers() silently drops user push configurations - Creates push trigger structure but never assigns to result object
  3. buildTriggers() silently drops user pullRequest configurations - Creates pull_request trigger structure but never assigns to result object
  4. Test validates incorrect YAML escaping - Tests expect escaped ${{ }} syntax that GitHub Actions cannot parse, masking the string escaping bug in buildCredentialEnv()

Impact

These defects will cause:

  • Invalid permission keys in generated workflows
  • User-specified triggers being silently ignored
  • Credentials incorrectly escaped, causing workflow failures
  • Tests passing while masking broken functionality

All issues have specific fixes provided. Please address these before merging.


You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/__tests__/compile.test.ts
@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Add @sverka/compiler-github to compile Plan IR into GitHub Actions YAML

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Grey Divider

AI Description

• Introduces a pure Plan→GitHub Actions YAML compiler using a thin-wrapper workflow (ADR-004).
• Maps Plan credential envVars to job-level env secrets and normalizes trigger/permission keys.
• Adds comprehensive vitest coverage and updates package scaffolding + spec/docs for v1 scope.
Diagram

graph TD
  A["Plan IR (validated)"] --> B["compileGithubWorkflow()"] --> C["workflow object"] --> D["YAML stringify"] --> E["workflow.yml string"]
  F["GithubCompilerConfig"] --> B
  B --> G["GitHub Actions"]

  subgraph Legend
    direction LR
    _data["Input/Output"] ~~~ _fn["Pure function"] ~~~ _ext["External system"]
  end
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Template-based YAML emission (string builder)
  • ➕ Absolute control over emitted YAML shape/formatting (e.g., null vs empty map).
  • ➕ Avoids YAML library dependency and any surprising serializer behaviors.
  • ➖ Harder to evolve safely (indentation/escaping/key-order bugs).
  • ➖ More manual effort to keep deterministic and valid across edge cases.
2. Stronger internal workflow typing (schema-aligned types)
  • ➕ Reduces use of Record and catches structure errors at compile time.
  • ➕ Makes future expansion (native job expansion) less error-prone.
  • ➖ More upfront type modeling effort for GitHub Actions schema subset.
  • ➖ May still need escape hatches for uncommon keys/structures.
3. Add native job expansion in v1
  • ➕ Improved CI visibility (per-check jobs), potentially better GitHub UI integration.
  • ➖ Contradicts ADR-004/thin-wrapper scope; significantly higher complexity and maintenance.
  • ➖ Requires additional mapping decisions (SARIF, artifacts per op, permissions).

Recommendation: Keep the current thin-wrapper + yaml stringify approach: it matches ADR-004, stays small/pure, and the included tests cover key contract points (defaults, config overrides, triggers, permissions, credentials, determinism). If formatting control ever becomes a pain point, prefer adding schema-aligned types over switching to manual string templates.

Files changed (11) +870 / -180

Enhancement (3) +160 / -0
compile.tsImplement compileGithubWorkflow Plan→GitHub Actions YAML compiler +124/-0

Implement compileGithubWorkflow Plan→GitHub Actions YAML compiler

• Builds deterministic workflow YAML via yaml.stringify with defaults for name/runner/versions, converts camelCase→kebab-case for permissions and trigger keys, and maps unique Plan credential envVars to job env secrets.

packages/compiler-github/src/compile.ts

index.tsExport compiler entrypoint and public types +7/-0

Export compiler entrypoint and public types

• Defines the package’s public API: compileGithubWorkflow plus type-only exports for config/triggers/permissions.

packages/compiler-github/src/index.ts

types.tsDefine GithubCompilerConfig/Triggers/Permissions types +29/-0

Define GithubCompilerConfig/Triggers/Permissions types

• Adds the configuration surface for workflow naming, triggers, runner/version selection, and permissions in a TS-friendly shape.

packages/compiler-github/src/types.ts

Tests (3) +210 / -0
compile.test.tsAdd compiler-github behavior tests (defaults, triggers, env, perms) +134/-0

Add compiler-github behavior tests (defaults, triggers, env, perms)

• Introduces coverage for default workflow structure, config overrides, trigger key mapping, credential env emission/deduplication, permissions kebab-case mapping, determinism, and empty-plan behavior.

packages/compiler-github/src/tests/compile.test.ts

fixtures.tsAdd typed Plan/Operation fixtures for tests +58/-0

Add typed Plan/Operation fixtures for tests

• Provides minimal, valid PlanOperation/Plan builders and a helper to generate plans with credential declarations for env mapping tests.

packages/compiler-github/src/tests/helpers/fixtures.ts

public-api.test.tsAdd public API surface tests +18/-0

Add public API surface tests

• Verifies compileGithubWorkflow is exported and ensures no unexpected runtime exports leak (type-only exports remain erased).

packages/compiler-github/src/tests/public-api.test.ts

Documentation (2) +486 / -174
wave-12-compiler-github-plan.mdAdd Wave 12 compiler-github implementation plan +412/-0

Add Wave 12 compiler-github implementation plan

• Documents scoped v1 design decisions (thin wrapper only), file layout, TDD steps, and edge-case guidance for triggers/permissions/credentials/determinism.

engdocs/architecture/wave-12-compiler-github-plan.md

spec.mdRefocus spec on thin-wrapper v1 and credential env mapping +74/-174

Refocus spec on thin-wrapper v1 and credential env mapping

• Removes native expansion, custom error/warning types, schedule/secrets fields, SARIF upload, and schema validation; clarifies defaults, credential→env secrets behavior, deterministic YAML generation, and vitest-based test plan.

specs/12-compiler-github/spec.md

Other (3) +14 / -6
bun.lockLock workspace deps for compiler-github (yaml + @sverka/ir) +4/-0

Lock workspace deps for compiler-github (yaml + @sverka/ir)

• Adds the new package entry and records runtime dependencies on @sverka/ir and yaml in the Bun lockfile.

bun.lock

package.jsonFix exports to .mjs/.d.mts and declare runtime deps +9/-5

Fix exports to .mjs/.d.mts and declare runtime deps

• Switches main/module/types/exports to ESM .mjs and .d.mts outputs and adds @sverka/ir + yaml as dependencies with standard build/test/lint/typecheck scripts.

packages/compiler-github/package.json

project.jsonAlign Nx lint command with flat ESLint config +1/-1

Align Nx lint command with flat ESLint config

• Removes the deprecated --ext .ts flag from the lint target command to match repo ESLint configuration.

packages/compiler-github/project.json

Comment thread packages/compiler-github/src/types.ts Outdated
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts Outdated
Comment thread packages/compiler-github/src/compile.ts
@codacy-production

codacy-production Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 22 complexity · 0 duplication

Metric Results
Complexity 22
Duplication 0

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

Run reviewer

TIP This summary will be updated as you push new changes.

@codacy-production codacy-production Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

The PR introduces the @sverka/compiler-github package. While the implementation aligns with the architectural intent of ADR-004, the Codacy analysis indicates the code is not up to standards with 164 new issues.

There are several critical issues that should prevent merging:

  • Broken Workflow Permissions: The current logic for custom permissions will unintentionally disable the default contents: read permission, causing repository checkout to fail.
  • Environment Incompatibility: The workflow targets the ubuntu-latest runner but relies on bun, which is not pre-installed, leading to inevitable CI failures.
  • Maintainability Risks: The core compilation logic in compile.ts has been flagged for high cyclomatic complexity and lacks unit test coverage, posing a long-term stability risk.

About this PR

  • The PR has introduced 164 new quality issues according to Codacy. Please review the linting and style guidelines for the workspace to ensure the new package meets the project's quality standards.

Test suggestions

  • Default configuration produces expected workflow structure, steps, and default triggers (push on main, pull_request)
  • Custom configuration overrides defaults for name, runner, sverka version, and node version
  • Trigger mapping correctly handles custom branch lists and workflow_dispatch toggle
  • Credential declarations from multiple operations are collected, deduplicated, and mapped to the env block
  • Permission mapping correctly converts camelCase keys to kebab-case (e.g., security-events)
  • Empty operations list results in a valid workflow that still executes the plan
  • The compiler output is identical when given the same plan and configuration inputs
  • Public API correctly exports the compiler function and necessary types without exposing internal logic
  • Automate unit tests for compile.ts to address coverage gaps in complex logic
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Automate unit tests for compile.ts to address coverage gaps in complex logic

TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback

Comment thread packages/compiler-github/src/types.ts
Comment thread packages/compiler-github/src/compile.ts Outdated
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts Outdated
@qodo-code-review

qodo-code-review Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Empty triggers disable workflow ✗ Dismissed 🐞 Bug ≡ Correctness
Description
buildTriggers() can return an empty on: mapping when config.on is provided but no events are
enabled (e.g. {}), producing a workflow that never triggers. It also emits push.branches: [] for
push: [], which matches no branches and is inconsistent with the empty-array behavior used for
pullRequest.
Code

packages/compiler-github/src/compile.ts[R27-30]

+  const result: Record<string, unknown> = {};
+  if (triggers.push) {
+    result.push = { branches: [...triggers.push] };
+  }
Evidence
The new implementation constructs a trigger object by conditionally adding keys; when none match, it
returns {}. It also directly spreads triggers.push into branches even when the array is empty,
which creates a branch filter that matches no branches.

packages/compiler-github/src/compile.ts[20-41]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`buildTriggers()` returns `{}` for an explicitly-provided but empty `config.on` object, yielding a workflow with no effective triggers. It also treats `push: []` as enabled and generates `branches: []`, which matches nothing and is likely not what callers intend.

### Issue Context
This behavior is introduced in the new GitHub compiler and affects generated workflows.

### Fix Focus Areas
- packages/compiler-github/src/compile.ts[20-41]

### Implementation notes
Choose one explicit policy and implement it consistently:
- If `config.on` is provided but results in no enabled events, throw an `Error` (with a clear message), OR fall back to the default triggers.
- Treat `push: []` consistently with `pullRequest: []`:
 - either interpret empty arrays as “all branches” (emit `push: null` / omit `branches`),
 - or reject empty arrays as invalid configuration.
- Add/adjust unit tests to cover `{ on: {} }` and `{ on: { push: [] } }`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. Bun not installed ✓ Resolved 🐞 Bug ☼ Reliability
Description
The generated workflow runs bun install -g sverka@... but never installs or sets up Bun, so the
output is not self-contained and will fail on runners where Bun isn’t preinstalled. Add a Bun setup
step or switch to an install method that only requires Node.
Code

packages/compiler-github/src/compile.ts[R100-103]

+        uses: "actions/setup-node@v4",
+        with: { "node-version": nodeVersion },
+      },
+      { run: `bun install -g sverka@${sverkaVersion}` },
Evidence
The emitted steps include Node setup and then immediately call bun install, with no prior Bun
installation step. GitHub provides a dedicated action to install Bun in workflows, indicating Bun
setup is normally explicit.

packages/compiler-github/src/compile.ts[95-105]
🌐 Provides an action (oven-sh/setup-bun) to download, install, and set up Bun in GitHub Actions workflows.

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The compiled workflow invokes `bun install` but the steps only set up Node. This makes the generated workflow dependent on the runner image having Bun already installed.

### Issue Context
The compiler currently emits:
- `actions/setup-node@v4`
- then `bun install -g ...`
with no Bun setup.

### Fix Focus Areas
- packages/compiler-github/src/compile.ts[95-110]

### Implementation notes
Pick one:
1) Add Bun setup:
  - Insert `- uses: oven-sh/setup-bun@v2` (optionally configurable version) before the `bun install` command.
2) Avoid Bun dependency:
  - Replace `bun install -g sverka@...` with `npm install -g sverka@...` (or `corepack`-based approach) so only Node is required.
Update tests to assert the presence of the chosen setup/install mechanism.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. envVar breaks secrets refs ✗ Dismissed 🐞 Bug ≡ Correctness
Description
buildCredentialEnv() interpolates CredentialDeclaration.envVar directly into `${{
secrets.<ENV_VAR> }}, but Plan validation only requires envVar` to be a non-empty string. This
allows validated Plans to generate invalid GitHub secret references and/or invalid env keys when
envVar doesn’t meet GitHub secret naming rules.
Code

packages/compiler-github/src/compile.ts[R71-73]

+  for (const envVar of envVars) {
+    env[envVar] = `\${{ secrets.${envVar} }}`;
+  }
Evidence
The compiler constructs secret references using dot-notation from envVar without sanitization,
while the IR validator only checks envVar is non-empty. GitHub documents stricter constraints on
secret names, so some validated Plans can still produce invalid workflows.

packages/compiler-github/src/compile.ts[63-75]
packages/ir/src/validate.ts[303-325]
🌐 Secret names can only contain alphanumeric characters or underscores, must not start with a number, and must not start with the GITHUB_ prefix.

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`buildCredentialEnv()` uses `envVar` verbatim both as an `env:` key and in `secrets.<envVar>` expression form. The IR validator currently only checks `envVar` is non-empty, so invalid names can pass validation and still produce workflows that GitHub cannot resolve correctly.

### Issue Context
- `@sverka/ir` validation rule for `credentials[].envVar` is only “non-empty string”.
- GitHub restricts secret names to alphanumeric/underscore and forbids starting with a number or `GITHUB_`.

### Fix Focus Areas
- packages/compiler-github/src/compile.ts[63-75]
- packages/ir/src/validate.ts[303-325]

### Implementation notes
Prefer rejecting invalid input over silently renaming:
- Add a validation step (either in the compiler or in `@sverka/ir` `validatePlan`) that enforces GitHub secret naming constraints for `CredentialDeclaration.envVar` when targeting GitHub.
 - Suggested check: `^[A-Za-z_][A-Za-z0-9_]*$` and not starting with `GITHUB_`.
- If invalid, throw `Error` (compiler) or return a validation error (IR), so callers don’t ship a broken workflow.
- Add a unit test demonstrating that an invalid `envVar` is rejected.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context
✅ Web pages:
  +17 more
Review mode: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 15/18, lines 1050/200; both must reach the floor). Router rationale: This introduces a new runtime compiler with YAML generation, trigger/permission/credential mappings, public API and package integration across many independent edit sites, creating a dense set of subtle contract and workflow-validity defects that benefit from redundant review.

Grey Divider

Tip of the day
💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts
Comment thread packages/compiler-github/src/compile.ts Outdated
ThePlenkov added a commit that referenced this pull request Aug 10, 2026
…-bun, execute cmd, interface order

Address PR #14 review feedback:

1. toKebab leading hyphen: regex added offset check so capitalized first
   chars don't get a leading hyphen (amazon-q).
2. idToken permission: removed "read" — GitHub Actions only supports
   "write" for id-token (codeant-ai).
3. sverka execute: removed .sverka/plan.json positional arg — CLI uses
   strict yargs and rejects unknown args (codeant-ai, critical).
4. setup-bun: added oven-sh/setup-bun@v2 step — ubuntu-latest doesn't
   include bun (codacy).
5. Interface ordering: moved GithubTriggers and GithubPermissions before
   GithubCompilerConfig (codacy).

Tests: 13 pass. Full monorepo 16 projects green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@codeant-ai codeant-ai Bot added size:XXL This PR changes 1000+ lines, ignoring generated files and removed size:XL This PR changes 500-999 lines, ignoring generated files labels Aug 10, 2026
ThePlenkov added a commit that referenced this pull request Aug 10, 2026
…-bun, execute cmd, interface order

Address PR #14 review feedback:

1. toKebab leading hyphen: regex added offset check so capitalized first
   chars don't get a leading hyphen (amazon-q).
2. idToken permission: removed "read" — GitHub Actions only supports
   "write" for id-token (codeant-ai).
3. sverka execute: removed .sverka/plan.json positional arg — CLI uses
   strict yargs and rejects unknown args (codeant-ai, critical).
4. setup-bun: added oven-sh/setup-bun@v2 step — ubuntu-latest doesn't
   include bun (codacy).
5. Interface ordering: moved GithubTriggers and GithubPermissions before
   GithubCompilerConfig (codacy).

Tests: 13 pass. Full monorepo 16 projects green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@ThePlenkov
ThePlenkov force-pushed the wave-12-compiler-github branch from 5c2a220 to 66da355 Compare August 10, 2026 20:46
ThePlenkov added a commit that referenced this pull request Aug 10, 2026
…-bun, execute cmd, interface order

Address PR #14 review feedback:

1. toKebab leading hyphen: regex added offset check so capitalized first
   chars don't get a leading hyphen (amazon-q).
2. idToken permission: removed "read" — GitHub Actions only supports
   "write" for id-token (codeant-ai).
3. sverka execute: removed .sverka/plan.json positional arg — CLI uses
   strict yargs and rejects unknown args (codeant-ai, critical).
4. setup-bun: added oven-sh/setup-bun@v2 step — ubuntu-latest doesn't
   include bun (codacy).
5. Interface ordering: moved GithubTriggers and GithubPermissions before
   GithubCompilerConfig (codacy).

Tests: 13 pass. Full monorepo 16 projects green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@ThePlenkov
ThePlenkov force-pushed the wave-12-compiler-github branch from 66da355 to 6e2a4e1 Compare August 10, 2026 20:53
ThePlenkov added a commit that referenced this pull request Aug 10, 2026
…-bun, execute cmd, interface order

Address PR #14 review feedback:

1. toKebab leading hyphen: regex added offset check so capitalized first
   chars don't get a leading hyphen (amazon-q).
2. idToken permission: removed "read" — GitHub Actions only supports
   "write" for id-token (codeant-ai).
3. sverka execute: removed .sverka/plan.json positional arg — CLI uses
   strict yargs and rejects unknown args (codeant-ai, critical).
4. setup-bun: added oven-sh/setup-bun@v2 step — ubuntu-latest doesn't
   include bun (codacy).
5. Interface ordering: moved GithubTriggers and GithubPermissions before
   GithubCompilerConfig (codacy).

Tests: 13 pass. Full monorepo 16 projects green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@ThePlenkov
ThePlenkov force-pushed the wave-12-compiler-github branch from 6e2a4e1 to 4f66797 Compare August 10, 2026 20:57
@ThePlenkov
ThePlenkov force-pushed the wave-12-compiler-github branch from a9a2614 to 4cb448e Compare August 11, 2026 11:07
ThePlenkov added a commit that referenced this pull request Aug 11, 2026
…-bun, execute cmd, interface order

Address PR #14 review feedback:

1. toKebab leading hyphen: regex added offset check so capitalized first
   chars don't get a leading hyphen (amazon-q).
2. idToken permission: removed "read" — GitHub Actions only supports
   "write" for id-token (codeant-ai).
3. sverka execute: removed .sverka/plan.json positional arg — CLI uses
   strict yargs and rejects unknown args (codeant-ai, critical).
4. setup-bun: added oven-sh/setup-bun@v2 step — ubuntu-latest doesn't
   include bun (codacy).
5. Interface ordering: moved GithubTriggers and GithubPermissions before
   GithubCompilerConfig (codacy).

Tests: 13 pass. Full monorepo 16 projects green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@ThePlenkov
ThePlenkov force-pushed the wave-12-compiler-github branch 2 times, most recently from 63df124 to da5a17b Compare August 11, 2026 12:46

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
specs/12-compiler-github/spec.md (1)

59-65: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Restrict GithubPermissions.idToken to "write".

GitHub Actions supports "write" and "none" for id-token, but not "read". Align the specification with the public type by removing "read".

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@specs/12-compiler-github/spec.md` around lines 59 - 65, Update the
GithubPermissions.idToken property type to allow only "write", removing "read"
while leaving the other permission properties unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@engdocs/architecture/wave-12-compiler-github-plan.md`:
- Around line 73-83: Specify the `text` language on the fenced file-tree code
block in the architecture plan by changing its opening fence, while leaving the
tree content unchanged.

In `@packages/compiler-github/src/__tests__/compile.test.ts`:
- Around line 48-57: Update the workflow trigger test around the pullRequest
configuration to use a non-default branch such as "release" instead of "main",
and assert that the generated pull_request trigger includes "release". Preserve
the existing assertions for workflow_dispatch and the other configured branch.
- Around line 130-135: Update the empty-plan test in the “compileGithubWorkflow
— empty operations” suite to parse the generated yaml before asserting it.
Validate the parsed workflow structure, including the required jobs entry and
sverka execute command, rather than relying only on substring checks.

In `@specs/12-compiler-github/spec.md`:
- Around line 9-11: The v1 GitHub workflow specification currently invokes the
unsupported plan-file form of the CLI. Update the documented workflow, ADR-004,
architecture plan, and related tests to invoke `sverka execute` without
`.sverka/plan.json`, preserving SDK config loading or auto-discovery and the
single-job wrapper behavior.

---

Outside diff comments:
In `@specs/12-compiler-github/spec.md`:
- Around line 59-65: Update the GithubPermissions.idToken property type to allow
only "write", removing "read" while leaving the other permission properties
unchanged.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3ab74e1b-5658-4c87-90a9-4588802e5971

📥 Commits

Reviewing files that changed from the base of the PR and between a1026a5 and da5a17b.

⛔ Files ignored due to path filters (1)
  • bun.lock is excluded by !**/*.lock
📒 Files selected for processing (10)
  • engdocs/architecture/wave-12-compiler-github-plan.md
  • packages/compiler-github/package.json
  • packages/compiler-github/project.json
  • packages/compiler-github/src/__tests__/compile.test.ts
  • packages/compiler-github/src/__tests__/helpers/fixtures.ts
  • packages/compiler-github/src/__tests__/public-api.test.ts
  • packages/compiler-github/src/compile.ts
  • packages/compiler-github/src/index.ts
  • packages/compiler-github/src/types.ts
  • specs/12-compiler-github/spec.md
📜 Review details
🧰 Additional context used
🪛 LanguageTool
engdocs/architecture/wave-12-compiler-github-plan.md

[uncategorized] ~49-~49: The official name of this software platform is spelled with a capital “H”.
Context: ...DK uses temp dir for artifacts). The github/codeql-action/upload-sarif@v3 step ...

(GITHUB)

🪛 markdownlint-cli2 (0.23.2)
engdocs/architecture/wave-12-compiler-github-plan.md

[warning] 73-73: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (8)
packages/compiler-github/package.json (1)

5-11: LGTM!

Also applies to: 21-24

packages/compiler-github/project.json (1)

18-23: LGTM!

packages/compiler-github/src/types.ts (1)

1-29: LGTM!

packages/compiler-github/src/compile.ts (1)

1-140: LGTM!

packages/compiler-github/src/index.ts (1)

3-8: LGTM!

packages/compiler-github/src/__tests__/compile.test.ts (1)

5-43: LGTM!

Also applies to: 60-128

packages/compiler-github/src/__tests__/helpers/fixtures.ts (1)

1-58: LGTM!

packages/compiler-github/src/__tests__/public-api.test.ts (1)

1-18: LGTM!

Comment thread engdocs/architecture/wave-12-compiler-github-plan.md Outdated
Comment thread packages/compiler-github/src/__tests__/compile.test.ts
Comment thread packages/compiler-github/src/__tests__/compile.test.ts
Comment thread specs/12-compiler-github/spec.md
@sonarqubecloud

Copy link
Copy Markdown

@ThePlenkov
ThePlenkov force-pushed the wave-12-compiler-github branch from 0c84f73 to 5a115ba Compare August 11, 2026 13:02
@sonarqubecloud

Copy link
Copy Markdown

❌ The last analysis has failed.

See analysis details on SonarQube Cloud

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@engdocs/architecture/wave-12-compiler-github-plan.md`:
- Line 388: Remove the hardcoded /home/pepl/projects/sverka directory change
from the verification block and replace it with a checkout-independent root
transition using cd ../.. after the package-level commands or git rev-parse
--show-toplevel.
- Line 166: Update the documented command examples and acceptance criteria at
the referenced architecture-plan sections and in the compiler GitHub
specification to use `sverka execute` without the `.sverka/plan.json` argument,
matching the compiler and package tests.
- Around line 253-256: Update the YAML test around the parsed workflow output to
assert the structured values at on.push.branches, on.pull_request.branches, and
on.workflow_dispatch rather than relying only on string containment. Explicitly
map pullRequest to pull_request and workflowDispatch to workflow_dispatch when
building or reading the expected trigger structure; do not use generic
camelCase-to-kebab-case conversion.
- Around line 289-302: Update the GithubPermissions definition to add optional
idToken with only the "write" value, and update buildPermissions to emit it as
the kebab-case YAML key id-token. Preserve the existing camelCase-to-kebab-case
mapping and reject or avoid supporting idToken: "read".

In `@packages/compiler-github/src/__tests__/compile.test.ts`:
- Around line 114-121: Update the permissions tests around compileGithubWorkflow
so the default workflow permissions are parsed and explicitly verified not to
include id-token. Preserve the existing custom-permission assertion for
securityEvents kebab-case conversion, while ensuring the default-permission
coverage rejects id-token: write.
- Around line 64-111: Update the credential tests around compileGithubWorkflow
to parse the serialized workflow and assert the expected mappings are located
specifically at jobs.sverka.env. Replace substring-based checks in the
declared-credentials test with an exact environment-object assertion, and in the
deduplication test assert jobs.sverka.env contains exactly one TOKEN key.
- Around line 7-28: Update the tests around compileGithubWorkflow to parse the
generated YAML and assert workflow fields at their required paths: jobs.sverka
for runner, tool versions, and steps/actions; on for default triggers; and
permissions for contents access. Apply the same structured assertions to the
default and custom workflow cases, while retaining validation that each
generated document is valid YAML.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f47e49bf-b2e5-4907-8d02-3b79e0bd9f4a

📥 Commits

Reviewing files that changed from the base of the PR and between da5a17b and 04ddc86.

📒 Files selected for processing (2)
  • engdocs/architecture/wave-12-compiler-github-plan.md
  • packages/compiler-github/src/__tests__/compile.test.ts
📜 Review details
🧰 Additional context used
🪛 LanguageTool
engdocs/architecture/wave-12-compiler-github-plan.md

[uncategorized] ~49-~49: The official name of this software platform is spelled with a capital “H”.
Context: ...DK uses temp dir for artifacts). The github/codeql-action/upload-sarif@v3 step ...

(GITHUB)

🔇 Additional comments (4)
packages/compiler-github/src/__tests__/compile.test.ts (3)

1-4: LGTM!


46-60: LGTM!


124-147: LGTM!

engdocs/architecture/wave-12-compiler-github-plan.md (1)

159-171: 🩺 Stability & Availability

No Bun setup change is required. The workflow already adds oven-sh/setup-bun@v2 before bun install, and the default test asserts it.

			> Likely an incorrect or invalid review comment.

Comment thread engdocs/architecture/wave-12-compiler-github-plan.md
Comment thread engdocs/architecture/wave-12-compiler-github-plan.md
Comment thread engdocs/architecture/wave-12-compiler-github-plan.md
Comment thread engdocs/architecture/wave-12-compiler-github-plan.md
Comment thread packages/compiler-github/src/__tests__/compile.test.ts
Comment thread packages/compiler-github/src/__tests__/compile.test.ts
Comment thread packages/compiler-github/src/__tests__/compile.test.ts
@sonarqubecloud

Copy link
Copy Markdown

ThePlenkov and others added 4 commits August 11, 2026 16:08
Pure function compileGithubWorkflow(plan, config?) that compiles a canonical
Sverka Plan to a GitHub Actions workflow YAML string. Thin wrapper per
ADR-004: single job runs `sverka execute .sverka/plan.json`. Maps plan
credentials to job-level env block with ${{ secrets.VAR }} references.
camelCase→kebab-case conversion for permissions and triggers. Deterministic
output. No custom errors (pure function on validated Plan). 13 tests pass.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…-bun, execute cmd, interface order

Address PR #14 review feedback:

1. toKebab leading hyphen: regex added offset check so capitalized first
   chars don't get a leading hyphen (amazon-q).
2. idToken permission: removed "read" — GitHub Actions only supports
   "write" for id-token (codeant-ai).
3. sverka execute: removed .sverka/plan.json positional arg — CLI uses
   strict yargs and rejects unknown args (codeant-ai, critical).
4. setup-bun: added oven-sh/setup-bun@v2 step — ubuntu-latest doesn't
   include bun (codacy).
5. Interface ordering: moved GithubTriggers and GithubPermissions before
   GithubCompilerConfig (codacy).

Tests: 13 pass. Full monorepo 16 projects green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…mplexity

Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
- Mark file-tree fence as  in architecture plan
- Test pullRequest trigger with a non-default branch and parse the YAML
- Parse empty-plan YAML output and assert required workflow structure

Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

baz: needs review size:XL This PR changes 500-999 lines, ignoring generated files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant