Skip to content

Move the top-level return into the workflow entrypoint in df12-build.js (#6) - #53

Open
pandalump wants to merge 1 commit into
mainfrom
issue-6-claude-top-level-return
Open

pandalump wants to merge 1 commit into
mainfrom
issue-6-claude-top-level-return

Conversation

@pandalump

Copy link
Copy Markdown
Collaborator

Summary

Fixes the Biome Illegal return statement outside of a function diagnostic in
the hand-maintained Claude Code workflow workflows/df12-build.js.

The worker-pool orchestration previously ran as flat module-scope code
terminating in a bare return {…} at module scope. The repository's own
make workflow-parse gate wraps the body in a synthetic async function so it
tolerates the top-level return, but Biome (CI) rightly rejects it.

This change encloses the pool state, control loop, end-of-run flush, and result
assembly in a single async function workflowMain() (whose return {…} is now
legal) and drives it from module scope with a bare await workflowMain() — a
valid top-level await in this ESM module (it already exports meta), and legal
under the launcher's async-function wrap. The configuration constants, schemas,
prompt builders, and the runTask/runAudit/runTriage helpers stay at module
scope and are reached through closure.

The result contract is preserved byte-for-byte: all nine fields (base,
maxParallel, processed, results, audits, remediationTriage,
pendingProposals, halted, summary) and their semantics are unchanged. A
whitespace-ignoring diff (git diff -w) shows only the enclosing function and
the trailing invocation were added.

This is the Claude Code workflow only; the generated ODW sibling
(workflows/df12-build-odw.js) legitimately ends with return await workflowMain() and is unaffected.

Validation

  • make workflow-parse: workflows/df12-build.js: wrapped JavaScript parses.
  • No return statement remains at column 0 anywhere in the file.
  • Biome is a CI-only gate here (not installed locally); commit gates pending in CI.

Closes #6

Biome flags an illegal return statement outside of a function in
workflows/df12-build.js: the worker-pool orchestration ran as flat
module-scope code terminating in a bare return {...}. The repository's
own workflow-parse gate wraps the body in a synthetic async function so
it tolerates the top-level return, but Biome in CI rightly rejects it.

Enclose the pool state, control loop, end-of-run flush, and result
assembly in a single async function workflowMain(), so its return {...}
is legal, and drive it from module scope with a bare await
workflowMain() (a valid top-level await in this ESM module that already
exports meta). The configuration, schemas, prompt builders, and the
runTask/runAudit/runTriage helpers stay at module scope and are reached
through closure, so they remain reusable.

The result contract is unchanged: all nine fields (base, maxParallel,
processed, results, audits, remediationTriage, pendingProposals,
halted, summary) and their semantics are preserved byte-for-byte; the
only edits are the enclosing function, its indentation, and the
trailing invocation.

Closes #6

@sourcery-ai sourcery-ai 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.

Sorry @pandalump, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

@coderabbitai

coderabbitai Bot commented Jul 7, 2026 •

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Summary

  • Move worker-pool orchestration, control flow, final flush, and result assembly into async workflowMain().
  • Invoke workflowMain() with top-level await to remove invalid module-scope return statements.
  • Preserve helper declarations, workflow behaviour, generated ODW output, and the nine-field result contract.
  • Validate parsing with make workflow-parse and confirm that no column-zero return statements remain.
  • Resolve issue #6.

Walkthrough

Encapsulate the existing worker-pool orchestration in workflowMain(). Start the workflow with await workflowMain() while preserving task handling, remediation processing, result construction, and error behaviour.

Changes

Workflow entrypoint

Layer / File(s) Summary
Encapsulate worker-pool orchestration
workflows/df12-build.js
Move worker-pool state, task spawning, pool draining, audit and remediation processing, result construction, and error handling into async workflowMain(). Invoke the entrypoint with await workflowMain().

Possibly related PRs

  • leynos/dakar#3: Uses the same async workflowMain() workflow-compilation and orchestration pattern.

Suggested labels: Issue

Suggested reviewers: leynos

Poem

A workflow steps inside its gate,
Workers queue and tasks await.
Audits settle, results align,
Errors follow the same design.
workflowMain() now leads the line.

🚥 Pre-merge checks | ✅ 17 | ❌ 3

❌ Failed checks (1 warning, 2 inconclusive)

Check name Status Explanation Resolution
Developer Documentation ⚠️ Warning The PR adds the internal workflowMain() boundary and top-level invocation, but changes only workflows/df12-build.js; docs/developers-guide.md does not document this Claude Code entrypoint. Document the Claude Code workflow contract in docs/developers-guide.md, including workflowMain(), top-level await, the ESM/loader parsing constraint, and the result contract.
Testing (Unit And Behavioural) ❓ Inconclusive Investigation is still in progress. Gather direct evidence about tests for workflows/df12-build.js and the native workflow-loading boundary.
Concurrency And State ❓ Inconclusive Investigation is still in progress. Inspect the workflow loader and available tests before deciding whether the state and task-lifetime requirements are met.
✅ Passed checks (17 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately describes moving the top-level return into the workflow entrypoint and links issue #6.
Description check ✅ Passed The description clearly explains the Biome fix, preserved result contract, validation, and affected workflow scope.
Linked Issues check ✅ Passed The change satisfies issue #6 by removing the module-scope return, preserving workflow results, and avoiding unrelated control-flow changes.
Out of Scope Changes check ✅ Passed The changes are limited to the stated workflow restructuring and do not introduce unrelated code or scope.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Testing (Overall) ✅ Passed This PR is a pure refactoring that wraps existing module-scope code in an async function and immediately invokes it. No new functionality, behavioural changes, or control-flow logic alterations wer...
User-Facing Documentation ✅ Passed PR contains only internal refactoring: moving worker orchestration into async function to fix Biome linting error. No user-facing functionality or behaviour changed; meta export, result contract, a...
Module-Level Documentation ✅ Passed The module-level meta.description and whenToUse clearly document the workflow purpose and use, while phases describe its function; no further docstring is needed.
Testing (Property / Proof) ✅ Passed The change is a code organisation refactoring. No new algorithmic logic, invariants over input/state ranges, or proof assumptions were introduced. The control loop, task scheduling, remediation tri...
Testing (Compile-Time / Ui) ✅ Passed The check specifies compile-time tests for Rust or TypeScript. The modified file (workflows/df12-build.js) is plain JavaScript, outside the check's scope. Parse-time validation exists via make work...
Unit Architecture ✅ Passed The PR only wraps existing orchestration in workflowMain and invokes it; it adds no new query, command, dependency, or side-effect path.
Domain Architecture ✅ Passed Keep the change: the only file changed is the workflow, and the whitespace-insensitive diff only adds workflowMain() and its invocation; no domain or adapter boundary changes occur.
Observability ✅ Passed Pass this check: the diff only adds the workflowMain() wrapper and invocation; existing control flow and contextual logs remain unchanged, so no new observability is required.
Security And Privacy ✅ Passed The commit changes only workflow scope and invocation; syntax passes, and scans found no new secrets, credentials, environment access, or sensitive I/O.
Performance And Resource Use ✅ Passed Keep this change: the parent-normalised workflow body is identical, and the diff only adds the wrapper and invocation; no loop, I/O, allocation, or concurrency path changed.
Architectural Complexity And Maintainability ✅ Passed Keep the required entrypoint wrapper: the diff adds only workflowMain() around existing orchestration and one explicit invocation, with no new dependency, layer, registry, or speculative abstract...
Rust Compiler Lint Integrity ✅ Passed The commit changes only workflows/df12-build.js; no Rust files, Rust lint suppressions, or clone changes are present, so this Rust-specific check is not applicable.
📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #6

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-6-claude-top-level-return

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

@leynos
leynos marked this pull request as ready for review July 28, 2026 23:50

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1b24480e8c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread workflows/df12-build.js
(halted ? ` | halted: ${halted}` : ' | clean stop (no more unblocked tasks).'),
}

await workflowMain()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Return the workflow result from the launcher wrapper

When the Claude Code launcher executes this body inside its async wrapper, this expression awaits workflowMain() but discards its returned object, so every completed run resolves to undefined instead of exposing processed, results, halted, summary, and the other documented result fields. This is reproducible even with an empty mocked frontier using the wrapper mirrored by make workflow-parse; use return await workflowMain() so the result propagates to the caller.

AGENTS.md reference: AGENTS.md:L6-L8

Useful? React with 👍 / 👎.

@buzzybee-df12

Copy link
Copy Markdown
Collaborator

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 6, 2026 •

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot added the Issue label Aug 6, 2026

@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: 1

🤖 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 `@workflows/df12-build.js`:
- Around line 709-717: Move the self-contained mutex factory out of
workflowMain() to module scope alongside the other helper functions, preserving
its promise-chain serialization and queue recovery behavior. Leave
workflowMain() responsible only for creating mergeLock by calling mutex().
🪄 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: a115cc73-9513-4681-9ea4-6298ac73f8cb

📥 Commits

Reviewing files that changed from the base of the PR and between 4c327bc and 1b24480.

📒 Files selected for processing (1)
  • workflows/df12-build.js
🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

  • leynos/nixie (auto-detected)

Comment thread workflows/df12-build.js
Comment on lines +709 to +717
function mutex() {
let tail = Promise.resolve()
return (fn) => {
const result = tail.then(() => fn())
tail = result.then(() => {}, () => {}) // keep the queue alive regardless of outcome
return result
}
}
}
const mergeLock = mutex()

let selectSeq = 0
async function doSelect(excludeIds) {
phase('Select')
return await agent(selectPrompt(excludeIds), { phase: 'Select', label: `select#${++selectSeq}`, schema: SELECTION_SCHEMA })
}
const mergeLock = mutex()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Move mutex() to module scope.

mutex() closes over nothing inside workflowMain(). It is a self-contained factory. Nesting it adds depth to an already large entrypoint and hides its reusability. Keep workflowMain() focused on orchestration state.

♻️ Proposed refactor

Declare the factory at module scope, next to the other helpers:

// Minimal async mutex: serialize callers through a promise chain. Used as a
// merge queue so only one task rebases + squash-merges + pushes BASE at a time.
function mutex() {
  let tail = Promise.resolve()
  return (fn) => {
    const result = tail.then(() => fn())
    tail = result.then(() => {}, () => {}) // keep the queue alive regardless of outcome
    return result
  }
}

Then reduce the entrypoint to the call:

-  // Minimal async mutex: serialize callers through a promise chain. Used as a
-  // merge queue so only one task rebases + squash-merges + pushes BASE at a time.
-  function mutex() {
-    let tail = Promise.resolve()
-    return (fn) => {
-      const result = tail.then(() => fn())
-      tail = result.then(() => {}, () => {}) // keep the queue alive regardless of outcome
-      return result
-    }
-  }
   const mergeLock = mutex()

As per coding guidelines: "prefer clarity over cleverness, small single-responsibility functions".

🤖 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 `@workflows/df12-build.js` around lines 709 - 717, Move the self-contained
mutex factory out of workflowMain() to module scope alongside the other helper
functions, preserving its promise-chain serialization and queue recovery
behavior. Leave workflowMain() responsible only for creating mergeLock by
calling mutex().

Source: Coding guidelines

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

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Move top-level return into the workflow entrypoint in workflows/df12-build.js

2 participants