Change --concurrency-factor from int multiplier to float64 CPU ratio

[mason-sharp]

On large machines (e.g. 96 CPUs), the old integer multiplier on runtime.NumCPU() created excessive workers with no way to reduce below 1× CPU count. Changing to a float64 ratio (default 0.5) lets users dial concurrency down on large hosts (e.g. 0.5 on 96 CPUs = 48 workers).

• CLI flag: IntFlag → Float64Flag, default 0.5, valid range (0.0, 4.0]
• All struct fields and config: int → float64
• Computation: math.Round(NumCPU * factor) with floor of 1
• API handler, jobs config, HTML reporter updated accordingly
• Documentation and OpenAPI spec updated

[coderabbitai]

📝 Walkthrough

Walkthrough

The change converts the concurrency_factor parameter from an integer worker count (1–10) to a floating-point CPU ratio (0.0–4.0) with a reduced default from 1 to 0.5. Updates span command-line interfaces, HTTP API structures, configuration schemas, internal task definitions, and documentation files across all diff operations.

Changes

Cohort / File(s)	Summary
Documentation docs/api.md, docs/commands/diff/table-diff.md, docs/commands/diff/schema-diff.md, docs/commands/diff/repset-diff.md, docs/configuration.md, docs/design/table_diff.md, docs/performance.md, docs/http-api.md, docs/openapi.yaml	Updated concurrency-factor descriptions from integer worker count (1–10) to CPU ratio (0.0–4.0); changed default from 1 to 0.5. Added new CLI flags (--quiet, --debug, --schedule, --every) in command docs. Updated OpenAPI schemas to reflect float type and new default value.
CLI Configuration internal/cli/cli.go, internal/cli/default_config.yaml	Converted concurrency-factor flag from IntFlag to Float64Flag with default 0.5 and updated description. Updated flag assignments across TableDiffCLI, SchemaDiffCLI, and RepsetDiffCLI to use ctx.Float64 instead of ctx.Int. Reduced default in config file from 1 to 0.5.
HTTP API Structures internal/api/http/handler.go	Changed Concurrency field from int to float64 in tableDiffRequest, schemaDiffRequest, and repsetDiffRequest structs. Updated resolveConcurrency method signature and default return value from 1 to 0.5.
Diff Task Definitions internal/consistency/diff/table_diff.go, internal/consistency/diff/schema_diff.go, internal/consistency/diff/repset_diff.go	Changed ConcurrencyFactor field from int to float64 in TableDiffTask, SchemaDiffCmd, and RepsetDiffCmd. Updated table_diff.go validation logic to enforce range >0 and ≤4.0, with maxConcurrent calculation using floating-point arithmetic and minimum of 1 worker.
Config & Type Definitions pkg/config/config.go, pkg/types/types.go, pkg/common/html_reporter.go	Changed DiffConfig.ConcurrencyFactor and DiffSummary.ConcurrencyFactor from int to float64. Updated HTML report rendering to use FormatFloat for concurrency factor display.
Job Configuration internal/jobs/config.go	Added float64Arg helper function to parse concurrency_factor as float64 from args map. Replaced integer parsing with generic float64 parsing across table-diff, schema-diff, and repset-diff jobs. Updated default fallback from 1 to 0.5.

Poem

🐰 Hopping through concurrency with grace,
From fixed integers to ratios—what a pace!
Half the CPUs now, a lighter load,
Float64s smooth the diff-checking road!
More flexible, more nimble, more refined,
Our rabbit-blessed changes realigned! 🐇

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: converting --concurrency-factor from an integer multiplier to a float64 CPU ratio, which is the central focus of the PR.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation and technical implementation details of converting concurrency-factor from int to float64 with clear examples.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch task/ACE-163/concurrency-factor

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

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

⚠️ Outside diff range comments (1)

docs/commands/diff/table-diff.md (1)

47-48: ⚠️ Potential issue | 🟡 Minor

Sample output shows 16 workers on 16 CPUs, which implies --concurrency-factor 1.0 rather than the new default 0.5.

With the default of 0.5, a 16-CPU machine would produce 8 workers. The sample output could confuse users who expect the default to match what's shown. Consider updating to Using 16 CPUs, max concurrent workers = 8 (or adding an explicit --concurrency-factor 1.0 to the example command) so the output aligns with the documented default.

🤖 Fix all issues with AI agents

In `@docs/commands/diff/repset-diff.md`:
- Around line 24-27: The markdown table rows for flags `--block-size`,
`--concurrency-factor`, `--compare-unit-size`, and `--output` currently place
the default values inside the Description column; split each row into four cells
so the fourth cell contains the Default (e.g., move "Default `100000`", "Default
`0.5`", "Default `10000`", "Default `json`" into the fourth column), ensuring
the pipe separators produce four columns per row and match the table header
format used in `schema-diff.md`.

In `@docs/commands/diff/schema-diff.md`:
- Around line 24-28: Table rows for the flags (--skip-file, --block-size,
--concurrency-factor, --compare-unit-size, --output) are missing the dedicated
"Default" column cell; move the default values out of the Description cell and
into a separate fourth cell so each row has four pipe-separated cells matching
the header (e.g., add a cell containing the default like `Default: 100000` or
just `100000` for `--block-size`). Update the rows for `--skip-file`,
`--block-size`, `--concurrency-factor`, `--compare-unit-size`, and `--output` to
include the fourth cell and ensure spacing/pipe alignment matches the table
format used elsewhere.

🧹 Nitpick comments (1)

docs/openapi.yaml (1)

459-461: Consider adding minimum/maximum constraints to enforce the documented range.

The description documents a valid range of (0.0–4.0], but the schema has no minimum/maximum or exclusiveMinimum constraints. Without these, API consumers won't get schema-level validation errors for out-of-range values (e.g., -1 or 10.0). The same applies to the SchemaDiffRequest (Line 564) and RepsetDiffRequest (Line 598) schemas.

Suggested fix for TableDiffRequest (apply similarly to the other two)

         concurrency_factor:
           type: number
+          exclusiveMinimum: 0
+          maximum: 4
           description: CPU ratio for concurrency (0.0–4.0). Defaults to table_diff.concurrency_factor or 0.5.