You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds @sverka/decorators, a TC39-standard decorator authoring layer that synthesizes the same Definition Graph as the Construct/SDK APIs. Removes pipeline-level @output; step outputs now come from StepOptions.outputs or StepBuilder.outputs().
Summary
Public API: @pipeline, @step, @step(options)/@stepWithOptions, @entry(trigger), @input, decoratePipeline(PipelineClass, project, id).
Method steps: methods may return a StepBuilder or use this.sh to compose commands joined with " && "; supports string/number/boolean/Reference interpolation and collects inputs.
Options parity: applies runtime, timeout, outputs, and dependsOn to both ShellStep and StepBuilder.
Metadata: shared per-class store on Symbol.for('sverka:pipeline:metadata') with fields at Symbol.for('sverka:fields'); decorators use context.metadata or addInitializer.
Validation and errors: input/options validation; errors include INVALID_FIELD, MISSING_INITIALIZER, INVALID_OPTIONS, DUPLICATE_FIELD, NOT_A_PIPELINE. Preserves source order and matches Construct/SDK graphs in specs/tests.
Migration
Replace any @output usage with StepOptions.outputs or StepBuilder.outputs(...).
Written for commit ab2ea85. Summary will update on new commits.
CodeAnt-AI Description
Add a decorator-based way to author Sverka pipelines
What Changed
Added @sverka/decorators with @pipeline, @step, @stepWithOptions, @entry, and @input
Decorated classes can now create pipelines with shell commands, step builders, outputs, dependencies, triggers, and validated inputs
Step methods can return builders or combine multiple shell operations, including references to inputs and step outputs
Added clear validation errors for missing or invalid fields, options, inputs, duplicate decorators, and non-pipeline classes
Decorator-authored pipelines preserve source order and produce the same definition graph as Construct API pipelines
Added an active specification and coverage for the public API, supported authoring styles, validation, and graph conformance
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.
Running ultrareview automatically — This PR introduces a new public decorator authoring layer with metadata-based pipeline synthesis, a large new package (~845 lines) that could hide subtle bugs in decorator semantics, metadata handling, and graph construction affecting end users.. I'll post findings when complete.
I can't run this ultrareview because you've reached your trial's review limit. Trial plans have lower review limits than paid plans. Upgrade now to resume reviews.
To help optimise your usage, you can tune cubic to get the most out of your usage limits:
**/*.{ts,tsx}: - No any: Use unknown and narrow. Strict TypeScript.
Error handling: Custom error classes per package.
Files:
packages/decorators/src/synthesize.ts
🔇 Additional comments (1)
packages/decorators/src/synthesize.ts (1)
217-218: LGTM!
📝 Walkthrough
Summary by CodeRabbit
New Features
Added decorator-based pipeline authoring for pipelines, steps, entries, and inputs.
Added configurable step options, including runtime, timeout, outputs, and dependencies.
Added pipeline synthesis from decorated classes, preserving declaration order and supporting method-based steps.
Added structured decorator errors with validation codes.
Published the decorators package with a complete public API.
Documentation
Added a specification covering decorator usage, behavior, validation, and API requirements.
Tests
Added coverage for decorator behavior, pipeline generation, ordering, validation, and public exports.
Walkthrough
Added @sverka/decorators with TC39 pipeline, step, entry, and input decorators. Added metadata registration, pipeline synthesis, validation errors, public exports, package configuration, tests, and an active authoring specification.
Changes
Decorator Pipeline Authoring
Layer / File(s)
Summary
Decorator contracts and specification packages/decorators/src/types.ts, packages/decorators/src/errors.ts, specs/04-authoring-decorators/spec.md
Instantiates decorated classes, validates inputs, creates steps and entries in source order, evaluates method-based steps, interpolates references, and reports validation errors.
Package wiring and public API packages/decorators/package.json, packages/decorators/tsconfig.json, packages/decorators/src/index.ts, packages/decorators/src/__tests__/public-api.test.ts
Adds package configuration, TypeScript settings, public exports, and API conformance tests.
The new decorator authoring path can reject a valid second synthesis of the same class and accept malformed entry definitions, which may lead to failed pipeline creation or invalid graphs. Merge readiness is moderate until these bounded correctness issues are fixed or explicitly accepted by the owner.
Sequence Diagram(s)
sequenceDiagram
participant DecoratedClass
participant decoratePipeline
participant Project
participant Pipeline
participant ShellStep
participant Entry
DecoratedClass->>decoratePipeline: instantiate and read decorator metadata
decoratePipeline->>Project: create pipeline construct
decoratePipeline->>Pipeline: collect inputs and process fields in source order
decoratePipeline->>ShellStep: synthesize string, builder, or method-based steps
decoratePipeline->>Entry: synthesize validated entry targets and triggers
Loading
Possibly related PRs
sverka-dev/sverka#1: Provides the core Pipeline, StepBuilder, and Entry APIs used by decorator synthesis.
sverka-dev/sverka#37: Defines the authoring-decorators architecture implemented by this package.
sverka-dev/sverka#38: Provides the Project, Pipeline, ShellStep, and Entry constructs consumed during synthesis.
Suggested labels:baz: needs review
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check name
Status
Explanation
Resolution
Docstring Coverage
⚠️ Warning
Docstring coverage is 40.00% 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.
Description check
✅ Passed
The description clearly explains the new decorator package, APIs, synthesis behavior, validation, testing, and migration impact.
Title check
✅ Passed
The title is concise and accurately identifies the decorator authoring layer added by the pull request.
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
Create stacked PR
Commit on current branch
🛠️ Fix failing CI checks 💡
Create stacked PR
Commit on current branch
🧪 Generate unit tests (beta)
Create PR with unit tests
Commit unit tests in branch v0-d-decorators
Comment @coderabbitai help to get the list of available commands.
Fallback decorator metadata registration is not idempotent: a second decoratePipeline call on the same class re-runs initializers and throws DUPLICATE_FIELD in runtimes without Symbol.metadata. This is an untested correctness issue in a new public API, compounded by no CI run.
The reason will be displayed to describe this comment to others. Learn more.
Review Summary
This PR introduces a new decorator authoring layer for Sverka pipelines with comprehensive test coverage. While the implementation demonstrates good architectural design and proper TC39 decorator usage, there are 5 critical defects that must be addressed before merge:
Critical Issues (Must Fix)
Null pointer risk in pipeline decorator - Non-null assertion on context.metadata! can store undefined, causing silent failures
Unhandled constructor errors - Pipeline class instantiation lacks error handling, leading to unclear crash behavior
Unsafe method execution - User methods execute arbitrary code without isolation during synthesis
Type safety violation - Duck typing with "type" in value accepts invalid Input objects
Dead code - Unused registerInputOnMetadata function creates maintenance burden
Test Coverage
All 11 tests pass with good conformance validation, but runtime error handling paths remain untested.
Recommendation: Address the 5 critical defects before merging to prevent runtime failures and security risks in production.
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.
• Introduce new @sverka/decorators package for authoring pipelines via TC39 decorators.
• Add decoratePipeline() to synthesize decorated classes into Constructs-based pipelines.
• Add conformance + API tests ensuring decorator pipelines match Construct API graphs.
Diagram
graph TD
A([Pipeline author]) --> B["Decorated pipeline class"] --> C[("Per-class metadata")]
C --> D["decoratePipeline()"] --> E["@sverka/constructs (Pipeline/Steps/Entry)"] --> F["@sverka/core synthesize()"] --> G[("Definition Graph")]
subgraph Legend
direction LR
_actor([Actor]) ~~~ _comp["Component/Function"] ~~~ _store[(Store/Artifact)]
end
Loading
High-Level Assessment
The following are alternative approaches to this PR:
1. Use experimentalDecorators + reflect-metadata
➕ Mature ecosystem patterns and examples
➕ Can avoid instantiating the class to read some metadata
➖ Contradicts the stated goal of TC39 standard decorators
➖ Adds runtime dependency and potentially leaks design-time types into runtime
➖ Harder to make portable across runtimes (Bun/Node) and bundlers
2. Static registry on the class (no context.metadata)
➕ Simpler mental model: class fields push into ClassName.__sverkaRegistry
➕ No reliance on decorator metadata semantics
➖ More boilerplate and easier for users to accidentally mutate/overwrite
➖ Harder to ensure per-class isolation across inheritance/rewrites
➖ Less aligned with TC39 direction and future Symbol.metadata support
3. Codegen/compile-time transform from decorated classes
➕ No runtime class instantiation required; can detect invalid patterns at build time
➕ Potentially richer features (forward refs, validation)
➖ Harder to keep the authoring surface runtime-agnostic and lightweight
Recommendation: The current approach (TC39 decorators + symbol-attached per-class metadata + runtime synthesis via decoratePipeline) is the best fit for v0: it avoids experimentalDecorators/reflect-metadata, stays portable, and keeps the authoring surface lightweight while still proving conformance via graph-level tests. The main tradeoff—instantiating the pipeline class to read initializers—is acceptable for v0 and matches the stated spec/constraints.
Files changed (12) +834 / -11
Enhancement (5) +417 / -0
decorators.tsImplement TC39 decorators and metadata recording+180/-0
Implement TC39 decorators and metadata recording
• Implements @pipeline, @step (bare), @stepWithOptions (factory), @entry, @input, and @output using TC39 standard decorators and context.metadata. Stores per-class metadata behind a symbol on the constructor and records decorated fields (and options/trigger) in insertion/source order with validation and duplicate detection.
errors.tsDefine DecoratorError and error codes+20/-0
Define DecoratorError and error codes
• Adds a dedicated error type with stable error codes for invalid fields/options, missing initializers, duplicates, and non-pipeline usage, including an explicit (readonly) cause field.
synthesize.tsImplement decoratePipeline() synthesis into Constructs+189/-0
Implement decoratePipeline() synthesis into Constructs
• Instantiates decorated pipeline classes, reads recorded field metadata, collects @input values from instance initializers, and creates Pipeline/ShellStep/Entry constructs in source order. Supports step values as string shorthand or StepBuilder; validates entry fields and throws DecoratorError for invalid/missing data.
types.tsAdd public decorator types (StepOptions, FieldMetadata)+22/-0
Add public decorator types (StepOptions, FieldMetadata)
• Defines the type model for decorator metadata including step options (runtime/timeout/outputs/dependsOn), entry targets, and field kinds used across decorators and synthesis.
public-api.test.tsAdd public API export surface tests+49/-0
Add public API export surface tests
• Verifies all decorator functions and decoratePipeline are exported, DecoratorError shape is correct, and key public types are importable (compile-time check).
spec.mdWrite Spec 04 for decorator authoring surface+130/-11
Write Spec 04 for decorator authoring surface
• Promotes Spec 04 from stub to active with goals/non-goals, API examples, metadata model, error codes, and an explicit test plan including conformance requirements.
• Adds the new decorators package to the Bun lockfile/workspace map with its internal dependencies on @sverka/constructs and @sverka/sdk and dev dependencies for build/test/typecheck.
The reason will be displayed to describe this comment to others. Learn more.
Pull Request Overview
This PR introduces the decorator-based authoring layer, but several key features are non-functional or unaddressed. Most notably, the @output decorator is currently a 'no-op' as the synthesis logic completely ignores output metadata. Additionally, the implementation for method-based steps is logically unreachable and type-restricted, which directly contradicts the acceptance criteria.
Codacy analysis indicates the PR is not up to standards. The synthesis engine ('synthesize.ts') exhibits high complexity and code duplication between the string-shorthand and method-planning paths. Several validation scenarios and the entirety of the @output functionality lack test coverage. These architectural and logical issues should be resolved before merging to ensure the authoring layer behaves as specified.
About this PR
The synthesis engine is currently incomplete. Metadata for @output is collected via decorators but is never evaluated or applied during the decoratePipeline synthesis process.
There is a systemic misalignment between the decorator definitions and the synthesizer regarding method-based steps. The decorators are typed only for fields, while the synthesizer contains (currently broken) logic for methods.
Test suggestions
@step string shorthand creates a ShellStep with the correct command
@stepWithOptions correctly applies timeout and other options to the step
@step with SDK StepBuilder (sh...) correctly builds the step
@step as a method decorator for planning multiple operations
@entry correctly registers triggers and root step IDs
decoratePipeline throws NOT_A_PIPELINE for classes missing the @pipeline decorator
Validation error: duplicate field decorators on the same class
Validation error: @entry field initializer is not an array of strings
Unit test for sh template handler with non-string interpolations
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. @step as a method decorator for planning multiple operations
2. @output registers pipeline-level output parameters
3. Validation error: duplicate field decorators on the same class
4. Validation error: @entry field initializer is not an array of strings
5. Unit test for `sh` template handler with non-string interpolations
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 10
🤖 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 `@packages/decorators/src/__tests__/decorators.test.ts`:
- Around line 155-165: Replace the partial pipeline length and step/entry ID
assertions in the definition graph comparison test with a complete deep-equality
assertion using expect(graph1).toEqual(graph2), ensuring all graph properties
are compared.
In `@packages/decorators/src/__tests__/public-api.test.ts`:
- Around line 43-47: Remove the tautological runtime assertions for
_opts.timeout, _target, _meta.kind, _kind, and _code in the public API test.
Keep the case as a compile-time-only type check, or replace the literal
comparisons with an assertion that validates the exported types.
In `@packages/decorators/src/decorators.ts`:
- Around line 170-180: Refactor createStepFromField to reduce cognitive
complexity by extracting focused helpers for field-value classification, builder
synthesis, and method synthesis. Keep each helper responsible for one stage and
preserve the existing behavior and output of createStepFromField.
- Around line 12-14: Update FIELDS_KEY in packages/decorators/src/decorators.ts
lines 12-14 and packages/decorators/src/synthesize.ts lines 11-12 to use the
shared Symbol.for("sverka:fields") metadata key instead of a string, preserving
the same key consistently in both files.
- Around line 20-25: Update the pipeline decorator around pipeline and
getPipelineMetadata so each class receives usable per-class metadata when
Symbol.metadata is unavailable. Initialize the Symbol.metadata polyfill before
decoration or use an equivalent per-class registry, and ensure pipeline stores
and getPipelineMetadata retrieves that same metadata object instead of
undefined.
- Around line 58-63: The step and stepWithOptions decorators must support method
contexts in addition to field contexts. Update both decorators to accept method
contexts and process function-valued steps before the invalid-value branch, then
update the planning context in synthesize to expose bare sh calls that record
commands alongside this.sh. Add coverage for an optioned step method asserting
the joined shell command; update packages/decorators/src/decorators.ts:58-63 and
packages/decorators/src/synthesize.ts:110-135 accordingly.
In `@packages/decorators/src/synthesize.ts`:
- Around line 103-106: Update the StepBuilder handling in the value synthesis
path to apply the field’s StepOptions—runtime, timeout, outputs, and
dependsOn—to the builder before invoking build(pipeline, name). Preserve
existing behavior for other field values, and add coverage for
`@stepWithOptions`(...) applied to a builder-valued field.
- Around line 41-46: Update the input-field handling in synthesize so every
`@input` field is validated instead of silently omitted: reject undefined, null,
missing type, or invalid type values by throwing DecoratorError with code
INVALID_FIELD, and only assign valid values to inputs[name].
- Around line 63-67: The input/output cases in the synthesis switch currently
discard `@output` metadata, so either implement end-to-end pipeline output storage
and synthesis through decoratePipeline and Pipeline, or remove `@output` from the
public decorator API and specification until supported. Keep the chosen behavior
consistent across decorator definitions, pipeline handling, and core synthesis.
In `@specs/04-authoring-decorators/spec.md`:
- Around line 149-150: Update the `@step` without initializer test-plan entry to
expect `MISSING_INITIALIZER` instead of `INVALID_FIELD`, matching the error
thrown by `createStepFromField`; leave the `decoratePipeline` case 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: 82846138-3607-42e5-b0bb-aca97b7e4c51
📥 Commits
Reviewing files that changed from the base of the PR and between 17c5892 and 06b63e4.
##[group]✅ > nx run checks:build
> bun run tsdown
�[34mℹ�[39m �[34mtsdown v0.22.14�[39m powered by �[38;2;255;126;23mrolldown v1.2.3�[39m
�[34mℹ�[39m config file: �[4m/home/runner/work/sverka/sverka/packages/checks/tsdown.config.ts�[24m
�[34mℹ�[39m entry: �[34msrc/index.ts�[39m
�[34mℹ�[39m tsconfig: �[34mtsconfig.json�[39m
�[34mℹ�[39m Build start
�[34mℹ�[39m �[2mdist/�[22m�[1mindex.mjs�[22m �[2m 7.87 kB�[22m �[2m│ gzip: 2.34 kB�[22m
�[34mℹ�[39m �[2mdist/�[22mindex.mjs.map �[2m15.70 kB�[22m �[2m│ gzip: 4.27 kB�[22m
�[34mℹ�[39m �[2mdist/�[22mindex.d.mts.map �[2m 0.46 kB�[22m �[2m│ gzip: 0.29 kB�[22m
�[34mℹ�[39m �[2mdist/�[22m�[32m�[1mindex.d.mts�[22m�[39m �[2m 2.70 kB�[22m �[2m│ gzip: 1.05 kB�[22m
�[34mℹ�[39m 4 files, total: 26.73 kB
�[32m✔�[39m Build complete in �[32m1516ms�[39m
##[endgroup]
NX Running target build for 18 projects failed
Tasks not run because their dependencies failed or --nx-bail=true:
- runtime-docker:build
- runtime-host:build
- cli:build
Failed tasks:
- engine-native:build
NX Nx Cloud wasn't able to store artifacts to the remote cache.
NX Nx Cloud encountered some problems
This Nx Cloud organization has been disabled due to exceeding the FREE plan.
Your organization can be re-enabled immediately by an organization admin upgrading to the Team plan at https://cloud.nx.app/orgs/6a7a1e77cff5d2abcf16725d/plans. (code: 401)
##[error]Process completed with exit code 130.
##[group]✅ > nx run checks:build
> bun run tsdown
�[34mℹ�[39m �[34mtsdown v0.22.14�[39m powered by �[38;2;255;126;23mrolldown v1.2.3�[39m
�[34mℹ�[39m config file: �[4m/home/runner/work/sverka/sverka/packages/checks/tsdown.config.ts�[24m
�[34mℹ�[39m entry: �[34msrc/index.ts�[39m
�[34mℹ�[39m tsconfig: �[34mtsconfig.json�[39m
�[34mℹ�[39m Build start
�[34mℹ�[39m �[2mdist/�[22m�[1mindex.mjs�[22m �[2m 7.87 kB�[22m �[2m│ gzip: 2.34 kB�[22m
�[34mℹ�[39m �[2mdist/�[22mindex.mjs.map �[2m15.70 kB�[22m �[2m│ gzip: 4.27 kB�[22m
�[34mℹ�[39m �[2mdist/�[22mindex.d.mts.map �[2m 0.46 kB�[22m �[2m│ gzip: 0.29 kB�[22m
�[34mℹ�[39m �[2mdist/�[22m�[32m�[1mindex.d.mts�[22m�[39m �[2m 2.70 kB�[22m �[2m│ gzip: 1.05 kB�[22m
�[34mℹ�[39m 4 files, total: 26.73 kB
�[32m✔�[39m Build complete in �[32m1516ms�[39m
##[endgroup]
NX Running target build for 18 projects failed
Tasks not run because their dependencies failed or --nx-bail=true:
- runtime-docker:build
- runtime-host:build
- cli:build
Failed tasks:
- engine-native:build
NX Nx Cloud wasn't able to store artifacts to the remote cache.
NX Nx Cloud encountered some problems
This Nx Cloud organization has been disabled due to exceeding the FREE plan.
Your organization can be re-enabled immediately by an organization admin upgrading to the Team plan at https://cloud.nx.app/orgs/6a7a1e77cff5d2abcf16725d/plans. (code: 401)
##[error]Process completed with exit code 130.
[warning] 155-155: Prefer "expect(graph1.project.pipelines).toHaveLength(graph2.project.pipelines.length)" over this generic assertion for better reporting; it works on any object with a numeric length property.
1. Options ignored for StepBuilder✓ Resolved🐞 Bug≡ Correctness
Description
When a @step field is initialized with an SDK StepBuilder (from sh\...\`), decoratePipeline`
calls builder.build(...) and ignores decorator options (timeout, runtime, dependsOn,
outputs), so @stepWithOptions has no effect for builder-based steps.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
The synthesize logic applies options only for string-based steps; for builder-based steps it calls
build() directly. StepOptions includes fields like timeout/runtime, and StepBuilder
supports configuring those before build() constructs a ShellStep.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
### Issue description
For `StepBuilder` step values, decorator-provided options are currently dropped. This makes `@stepWithOptions({ timeout: ... })` (and the documented `@step({ ... })`) silently ineffective for `sh`-authored steps.
### Issue Context
`StepBuilder` already exposes fluent setters (`timeout`, `runtime`, `dependsOn`, `outputs`) and `build()` ultimately creates the `ShellStep`. The decorator should merge/apply options before building.
### Fix Focus Areas
- packages/decorators/src/synthesize.ts[83-108]
- packages/decorators/src/types.ts[5-10]
### What to change
- In the `StepBuilder` branch, apply `options` by chaining on the builder before calling `build()`, e.g.:
- `let b = builder; if (options?.timeout) b = b.timeout(options.timeout); ...; b.build(...)`
- Define precedence rules (document and implement), e.g.:
- decorator options override builder settings, or
- decorator options act as defaults only when builder has not set them.
- Add a test covering `@stepWithOptions` + `sh` builder to ensure `timeout`/`dependsOn` are applied.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
The code and spec claim @step(options) is supported, but step is only implemented as a bare
decorator (value, context) => void; using it as a factory via @step({timeout: ...}) will call it
with no context and crash at class definition time.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
The spec explicitly shows @step({ timeout: ... }), but the exported step function has the
standard decorator signature and always expects a context parameter; it does not return a
decorator function when called with options.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
### Issue description
`step` is documented as supporting both `@step` and `@step(options)`, but the exported implementation only supports `@step` (bare). Using `@step({ ... })` will invoke `step(options)` with no `context` argument and then dereference `context.metadata`, causing a runtime error.
### Issue Context
The spec example uses `@step({ timeout: 600000 })` for a builder step.
### Fix Focus Areas
- packages/decorators/src/decorators.ts[43-76]
- specs/04-authoring-decorators/spec.md[38-52]
### What to change
- Implement an overload/dispatch for `step`:
- If called with 1 argument (options), validate and return a decorator function (delegate to `stepWithOptions`).
- If called with 2 arguments (value, context), treat as bare decorator.
- Ensure the public docs/spec either:
- continue to support `@step(options)` (preferred since spec already shows it), or
- explicitly remove/replace it everywhere with `@stepWithOptions(...)`.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
3. Decorator metadata may be undefined✓ Resolved🐞 Bug☼ Reliability
Description
The decorators assume context.metadata is always a shared object, but it can be undefined when
Symbol.metadata isn’t available; @pipeline stores context.metadata! anyway, and other
decorators fall back to fresh {} objects, losing registrations and causing decoratePipeline to
throw NOT_A_PIPELINE or synthesize an empty pipeline.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
@pipeline stores context.metadata! without ensuring it’s defined, while field decorators use
context.metadata ?? {} which can be a new object per decorator invocation. TypeScript documents
that Symbol.metadata needs a polyfill and its decorator lib types explicitly allow metadata to
be undefined when Symbol.metadata is absent.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
### Issue description
`context.metadata` is typed/allowed to be `undefined` when the runtime doesn't provide `Symbol.metadata`. Current code writes `context.metadata!` onto the class and registers fields into `context.metadata ?? {}`, which can result in storing `undefined` for pipelines and/or registering into throwaway objects.
### Issue Context
TypeScript’s decorator metadata requires a runtime `Symbol.metadata` polyfill to guarantee `context.metadata` is present. Without it, this package’s core API can fail at class definition time or during `decoratePipeline`.
### Fix Focus Areas
- packages/decorators/src/decorators.ts[20-26]
- packages/decorators/src/decorators.ts[58-99]
### What to change
- Stop depending on `context.metadata` being defined.
- Implement an explicit, shared per-class metadata store:
- Use `context.addInitializer(...)` in field/method decorators to attach metadata onto the class constructor (e.g., `this.constructor[PIPELINE_SYMBOL] ??= {}`) and register the field there.
- In `@pipeline`, ensure the constructor is marked as a pipeline and ensure the same metadata object exists.
- Alternatively (if you prefer), add/document a required `Symbol.metadata` polyfill and fail fast with a clear error if it’s missing (but don’t silently fall back to `{}` per-decorator).
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
View high (1) 4. Method steps unsupported✓ Resolved🐞 Bug≡ Correctness
Description
The spec claims @step can be used as a planning method, but decoratePipeline never handles
function values: prototype methods read as function and fall through to INVALID_FIELD, and the
current “method” branch is unreachable because it only runs when the step value is undefined.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
The synthesis code only treats method steps as value === undefined, but real methods are
functions. The spec simultaneously documents method-step support, making the current behavior a
contract break.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
### Issue description
The implementation advertises method-based steps, but the synthesis logic rejects function-valued steps and the method-handling block is gated by `value === undefined`, which does not match how methods appear on instances.
### Issue Context
Spec 04 describes method-based steps and includes them in the test plan.
### Fix Focus Areas
- packages/decorators/src/synthesize.ts[89-146]
- specs/04-authoring-decorators/spec.md[99-105]
### What to change
Choose one:
1) **Implement method steps end-to-end**
- Update the decorator(s) to support method decorators (use `ClassMethodDecoratorContext` or a union with `ClassFieldDecoratorContext`).
- Record method steps distinctly in metadata.
- In `decoratePipeline`, handle `typeof value === "function"` (or use recorded kind) and execute planning with a well-defined API (and tests).
2) **Remove method-step claims**
- Delete the unreachable method-step code path.
- Remove method-step examples and test-plan items from the spec until implemented.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
createStepFromField() implements method-based steps (planning context and
MISSING_INITIALIZER/INVALID_FIELD errors), but the added tests cover only field-initializer
forms and the NOT_A_PIPELINE error. Untested branches increase risk of regressions in the new
decorator authoring surface.
+ if (value === undefined) {+ // Could be a method-based step — check if the method exists.+ const method = (instance as Record<string, unknown>)[name];+ if (typeof method === "function") {
Relevance
●●● Strong
Repo has precedent accepting requests to add tests for non-trivial logic/branches.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
PR Compliance ID 2649776 requires tests for non-trivial implementation changes. The PR adds
method-based step execution and related error paths in synthesize.ts, but the tests added cover
string shorthand, options, StepBuilder, entry/input behavior, conformance, and only the
NOT_A_PIPELINE error—leaving method-step planning and missing-initializer errors untested.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
New non-trivial behavior in `decoratePipeline` (method-based `@step` planning + error branches like `MISSING_INITIALIZER`) is not exercised by automated tests.
## Issue Context
Compliance requires tests for all non-trivial implementation changes. `createStepFromField()` contains logic for method-based steps via a planning context (`createPlanningContext`) and specific error cases that currently have no direct test coverage.
## Fix Focus Areas
- packages/decorators/src/synthesize.ts[110-146]
- packages/decorators/src/__tests__/decorators.test.ts[15-179]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
decoratePipeline silently ignores @input fields whose initializer isn’t an object with a type
property, which can leave pipelines missing declared inputs with no error and very confusing
downstream behavior.
+ if (meta.kind === "input") {+ const value = (instance as Record<string, unknown>)[name];+ if (value !== undefined && typeof value === "object" && value !== null && "type" in value) {+ inputs[name] = value as Input;
Relevance
●●● Strong
Team has accepted changes to avoid silent failures; likely will add error/warning for invalid
@input.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
The input collection loop only registers inputs when a minimal shape check passes; there is no
else branch to raise an error for invalid/missing initializers, so decorated inputs can be
silently excluded from PipelineProps.inputs.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
### Issue description
An `@input` decorator signals that a field is intended to become a pipeline input, but the current implementation only adds it if a loose shape-check passes and otherwise drops it silently.
### Issue Context
The spec says an `@input` initializer is an `Input` object; silent omission makes typos/missing initializers hard to debug.
### Fix Focus Areas
- packages/decorators/src/synthesize.ts[38-47]
- specs/04-authoring-decorators/spec.md[110-113]
### What to change
- If a field is decorated with `@input`:
- Throw `DecoratorError("INVALID_FIELD")` (or a dedicated code) when the initializer is missing or not a valid `Input` shape, instead of silently skipping.
- Optionally perform stronger validation than just `'type' in value` (e.g., ensure `type` is an expected string literal).
- Add a test that `@input` with an invalid initializer throws a `DecoratorError`.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
7. Spec file not numbered 📘 Rule violation⚙ Maintainability
Description
The modified specification document is specs/04-authoring-decorators/spec.md, but the file name
spec.md does not start with a numeric identifier as required. This breaks the repository’s spec
naming convention and makes specs harder to track and reference consistently.
No clear repo precedent on spec filename numbering beyond directory; rule may be interpreted as
satisfied already.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
PR Compliance ID 2663931 requires specification documents introduced or modified to be placed under
specs/ and have filenames that begin with a numeric identifier. This PR modifies
specs/04-authoring-decorators/spec.md, where the filename spec.md does not include the required
numeric prefix.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
A specification document modified in this PR does not follow the required numbering convention for spec filenames.
## Issue Context
The checklist requires that each specification document introduced or modified lives under `specs/` *and* that the spec file name begins with a numeric identifier (e.g., `001_...`, `002-...`). This PR updates `specs/04-authoring-decorators/spec.md`, whose filename `spec.md` does not include the numeric prefix.
## Fix Focus Areas
- specs/04-authoring-decorators/spec.md[1-5]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Review mode: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 13/18, lines 845/200; both must reach the floor). Router rationale: This is a new decorator authoring surface with substantial metadata, synthesis, runtime evaluation, and API logic across many independent paths, creating a dense set of easy-to-miss behavioral defects.
Tip of the day
💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR
New @sverka/decorators package — the third authoring surface. Uses TC39
standard decorators (TypeScript 5.0+, no experimentalDecorators).
Decorators:
- @pipeline: class decorator marking a Sverka pipeline
- @step: field decorator for string shorthand or StepBuilder
- @stepWithOptions(options): factory form for step with runtime/timeout/outputs
- @entry(trigger): field decorator for entry definitions
- @input: field decorator for pipeline inputs
- @output: field decorator for pipeline outputs
decoratePipeline(PipelineClass, project, id) creates a Pipeline construct
from a decorated class, producing the same Definition Graph as the Construct
and SDK APIs.
Metadata is stored via context.metadata (TC39 per-class metadata object),
retrieved from the class constructor via a Symbol property (Symbol.metadata
is not yet widely implemented in Bun).
11 decorator tests (8 behavior + 3 public API). 102 tests across 4 packages.
No any types. override readonly cause present.
Specs: 04-authoring-decorators (§9.3–9.8, §12, §14, §15).
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
codeant-ai
Bot
added
the
size:XL
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
baz-reviewer
Bot
added
baz: needs review
baz: ready to merge
and removed
baz: ready to merge
baz: needs review
labels
User description
Summary
@sverka/decoratorspackage — 3rd authoring surface (after Construct API and SDK)@pipeline,@step,@stepWithOptions,@entry,@input,@outputdecoratePipeline(PipelineClass, project, id)creates a Pipeline construct from a decorated class@stepsplit into@step(bare) and@stepWithOptions(factory) to avoid TDZ issues under esbuild/vitestTest plan
anytypesGenerated with Devin
Summary by cubic
Adds
@sverka/decorators, a TC39-standard decorator authoring layer that synthesizes the same Definition Graph as the Construct/SDK APIs. Removes pipeline-level@output; step outputs now come fromStepOptions.outputsorStepBuilder.outputs().Summary
@pipeline,@step,@step(options)/@stepWithOptions,@entry(trigger),@input,decoratePipeline(PipelineClass, project, id).StepBuilderor usethis.shto compose commands joined with " && "; supports string/number/boolean/Reference interpolation and collects inputs.runtime,timeout,outputs, anddependsOnto bothShellStepandStepBuilder.Symbol.for('sverka:pipeline:metadata')with fields atSymbol.for('sverka:fields'); decorators usecontext.metadataoraddInitializer.INVALID_FIELD,MISSING_INITIALIZER,INVALID_OPTIONS,DUPLICATE_FIELD,NOT_A_PIPELINE. Preserves source order and matches Construct/SDK graphs in specs/tests.Migration
@outputusage withStepOptions.outputsorStepBuilder.outputs(...).Written for commit ab2ea85. Summary will update on new commits.
CodeAnt-AI Description
Add a decorator-based way to author Sverka pipelines
What Changed
@sverka/decoratorswith@pipeline,@step,@stepWithOptions,@entry, and@inputImpact
✅ Decorator-authored pipelines✅ Reusable step methods with output references✅ Clearer pipeline authoring errors💡 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:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
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:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
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.