Skip to content

Normalize internal API spelling - #236

Open
leynos wants to merge 1 commit into
mainfrom
fix-api-spelling
Open

Normalize internal API spelling#236
leynos wants to merge 1 commit into
mainfrom
fix-api-spelling

Conversation

@leynos

@leynos leynos commented Aug 16, 2026

Copy link
Copy Markdown
Owner

Summary

This branch standardizes internal API identifiers and call sites on Oxford
British spelling, using -ize forms and artefact where applicable. It also
updates diagnostics, tests and documentation so every internal reference uses
the renamed APIs.

The generated spelling configuration now checks inline code, preventing the
previous documentation/API mismatch from recurring.

Review walkthrough

Validation

  • make check-fmt: passed
  • make lint: passed
  • make test: passed (765 tests, 72 snapshots)
  • make typecheck: passed
  • make spelling: passed (15 spelling-policy tests)
  • make markdownlint: passed
  • make nixie: passed

References

Rename internal spelling identifiers and call sites to Oxford `-ize`
forms, and align diagnostics, test fixtures, and documentation.

Refresh the generated spelling configuration so inline API references
are checked.
@coderabbitai

coderabbitai Bot commented Aug 16, 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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e575ae2b-c9a7-4505-a84c-bb0f897cccab

📥 Commits

Reviewing files that changed from the base of the PR and between b8291b9 and 7ba89a8.

📒 Files selected for processing (45)
  • Makefile
  • docs/developers-guide.md
  • docs/documentation-style-guide.md
  • docs/execplans/regenerate-lockfiles.md
  • docs/lading-design.md
  • docs/roadmap.md
  • docs/scripting-standards.md
  • lading/cli.py
  • lading/commands/bump.py
  • lading/commands/publish.py
  • lading/commands/publish_diagnostics.py
  • lading/commands/publish_index_check.py
  • lading/commands/publish_preflight.py
  • lading/config.py
  • lading/runtime/runner.py
  • lading/runtime/subprocess_runner.py
  • lading/testing/cmd_mox_runner.py
  • lading/utils/__init__.py
  • lading/utils/path.py
  • lading/workspace/graph_build.py
  • lading/workspace/metadata.py
  • tests/bdd/features/cli.feature
  • tests/bdd/steps/test_bump_steps.py
  • tests/bdd/steps/test_publish_given_steps.py
  • tests/bdd/steps/test_publish_infrastructure.py
  • tests/unit/publish/test_command_helpers.py
  • tests/unit/publish/test_formatting_helpers.py
  • tests/unit/publish/test_packaging.py
  • tests/unit/publish/test_phase_dispatch.py
  • tests/unit/publish/test_preflight_arguments.py
  • tests/unit/publish/test_preflight_cargo_runner.py
  • tests/unit/publish/test_preflight_checks.py
  • tests/unit/publish/test_publish_diagnostics.py
  • tests/unit/publish/test_publish_execution_helpers.py
  • tests/unit/publish/test_run_preflight.py
  • tests/unit/publish/test_run_workspace_config.py
  • tests/unit/test_bump_lockfile_path_resolution.py
  • tests/unit/test_bump_manifest_updates.py
  • tests/unit/test_cli.py
  • tests/unit/test_config.py
  • tests/unit/test_publish_staging.py
  • tests/unit/test_workspace_models_validation.py
  • tests/unit/utils/test_metrics.py
  • tests/unit/utils/test_path.py
  • typos.toml
🔗 Linked repositories identified

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

  • leynos/cmd-mox (auto-detected)
  • leynos/cuprum (auto-detected)
  • leynos/shared-actions (auto-detected)
💤 Files with no reviewable changes (1)
  • typos.toml

Included review availability: 4 reviews are currently available. Based on recent review activity, included reviews refill at 5 per hour.


Summary

Standardize internal API identifiers and call sites on Oxford spelling, including -ize forms and artefact.

  • Rename workspace, environment, command, and test-exclusion helpers.
  • Update imports, call sites, diagnostics, tests, fixtures, and documentation.
  • Align terminology with the documentation style guide and lading design notes.
  • Update spelling configuration to check inline code references.

Validation

Formatting, linting, tests, type checking, spelling, Markdown linting, and Nixie validation pass.

The test suite reports 765 tests and 72 snapshots.

Walkthrough

The pull request standardises spelling across public and private identifiers, documentation, tests, diagnostics, examples, and typo-checking configuration. Runtime behaviour remains unchanged.

Changes

Spelling normalisation

Layer / File(s) Summary
Rename workspace helpers
lading/utils/*, lading/workspace/*, lading/cli.py, lading/commands/*, tests/unit/*, docs/*
Rename workspace normalisation helpers to normalize names and update their callers, tests, and documentation.
Rename command and runtime helpers
lading/commands/*, lading/runtime/*, lading/testing/*, tests/unit/publish/*, tests/bdd/steps/*
Rename command, environment, diagnostic, and preflight helpers while preserving their behaviour.
Align test terminology
tests/bdd/*, tests/unit/*
Update test names, variables, messages, and scenarios to use consistent spelling.
Update spelling policy
Makefile, docs/*, typos.toml
Update spelling guidance, examples, comments, and typo-checking exclusions.

Possibly related PRs

Suggested reviewers: codescene-access

Poem

Rename each helper; let clear names arise.
Align every test, comment, and guide.
Let artefacts march with consistent spelling.
Keep behaviour steady, with no logic unsettling.
Run the checks, and let clean words abide.

Merge Risk: ⚪ Minimal · up to 7ba89

This PR standardizes internal API spelling and updates its references; the supplied validation checks pass, and no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 18 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
User-Facing Documentation ⚠️ Warning The PR removes public lading.utils.normalise_workspace_root and exposes normalize_workspace_root; docs/users-guide.md is unchanged and has no migration note. Document the breaking API rename in docs/users-guide.md, including the replacement import and migration guidance for existing callers.
Developer Documentation ⚠️ Warning The diff renames several internal helpers, but the developer guide documents only normalize_workspace_root and _normalize_test_excludes; it omits normalize_environment, cmd-mox, graph, stagin... Document each renamed internal API and its contract in docs/developers-guide.md, or record why private spelling-only helpers are outside the guide's scope.
✅ Passed checks (18 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly describes the main change: standardising internal API spelling and identifiers.
Description check ✅ Passed The description accurately summarises the spelling changes, affected areas, validation results, and documentation updates.
Docstring Coverage ✅ Passed Docstring coverage is 97.06% which is sufficient. The required threshold is 80.00%.
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.
Testing (Overall) ✅ Passed Initial evidence shows a spelling-only refactor with existing tests updated to call renamed helpers and assert artefact diagnostics; inspect remaining diff for regressions.
Module-Level Documentation ✅ Passed Keep the check passing: every changed Python module retains a module docstring, and the diagnostics docstring still states its purpose after the spelling update.
Testing (Unit And Behavioural) ✅ Passed Pass this check: renamed unit tests retain edge cases and invariants, while the updated BDD scenario invokes python -m lading.cli and checks the observable diagnostic.
Testing (Property / Proof) ✅ Passed Pass: the diff contains spelling and identifier substitutions only; all 36 changed Python files retain identical syntax shape after identifier/literal normalisation, so no new invariant requires pr...
Testing (Compile-Time / Ui) ✅ Passed Pass this check: no Rust or TypeScript files changed, and the diagnostic wording has focused unit and BDD assertions for the heading, path, and tail.
Unit Architecture ✅ Passed The diff only renames identifiers, terminology, and spelling-check configuration; it does not change queries, commands, dependencies, fallibility, state mutation, or unit boundaries.
Domain Architecture ✅ Passed Keep the domain boundary unchanged: production Python diffs are spelling-only renames or documentation edits, parse successfully, and leave domain models untouched.
Observability ✅ Passed The diff only renames helpers, variables, and diagnostic spelling, plus documentation/configuration edits; it adds no operational failure mode or changed throughput, latency, retry, or boundary beh...
Security And Privacy ✅ Passed Pass this check: the parent diff contains spelling and identifier substitutions only; diagnostic data flow is unchanged, with no added secrets, permissions, sinks, or sensitive-data exposure.
Performance And Resource Use ✅ Passed The parent-to-HEAD diff only renames identifiers and spelling/text; executable ASTs match after normalization, with no new loops, collections, I/O, retries, or blocking paths.
Concurrency And State ✅ Passed Parent-to-HEAD diff shows identifier, variable, docstring, and diagnostic-text spelling changes only; thread/process control, shared state, locks, and task lifetimes are unchanged.
Architectural Complexity And Maintainability ✅ Passed The parent-to-HEAD diff contains spelling-only edits across existing files, with no new files, dependencies, structural declarations, or architectural indirection; existing utility boundaries remai...
Rust Compiler Lint Integrity ✅ Passed Mark PASS: the diff changes only Python, documentation, tests, Makefile and config; neither revision contains Rust sources or Rust lint/clone changes.
✨ 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 fix-api-spelling

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

@sourcery-ai

sourcery-ai Bot commented Aug 16, 2026

Copy link
Copy Markdown

Reviewer's Guide

Standardizes internal APIs and surrounding diagnostics/tests/docs on Oxford spelling (notably normalize_* and artefact), with the canonical normalize_workspace_root helper and aligned compiletest stderr artefact handling; ensures all call sites, configurations, and BDD expectations use the renamed APIs and updates spelling policy to enforce inline-code consistency.

Sequence diagram for compiletest stderr artefact diagnostics formatting

sequenceDiagram
    actor Caller
    participant append as _append_compiletest_diagnostics
    participant discover as _discover_stderr_artefacts
    participant trim as _trim_artefact_token
    participant format as _format_artefact_diagnostics

    Caller->>append: _append_compiletest_diagnostics(message, stdout, stderr, tail_lines)
    append->>discover: _discover_stderr_artefacts(stdout)
    discover->>trim: _trim_artefact_token(token)
    trim-->>discover: trimmed_token
    discover-->>append: tuple[Path]
    append->>discover: _discover_stderr_artefacts(stderr)
    discover->>trim: _trim_artefact_token(token)
    trim-->>discover: trimmed_token
    discover-->>append: tuple[Path]
    append->>format: _format_artefact_diagnostics(artefact, tail_lines)
    format-->>append: list[str]
    append-->>Caller: augmented_message
Loading

Flow diagram for normalize_workspace_root usage across modules

flowchart LR
    subgraph utils
        A[normalize_workspace_root]
    end

    B[cli.main]
    C[bump._initialize_bump_context]
    D[publish.run]
    E[config.build_loader]
    F[workspace.metadata.load_cargo_metadata]

    B --> A
    C --> A
    D --> A
    E --> A
    F --> A
Loading

File-Level Changes

Change Details Files
Rename workspace path helper to normalize_workspace_root and update all imports, call sites, and documentation.
  • Update lading.utils.path to expose normalize_workspace_root and adjust docstrings/examples.
  • Switch all callers (CLI, publish, bump, config, workspace metadata, workspace graph, tests) to import/use normalize_workspace_root.
  • Align developer and design documentation references to the new helper name and behaviour.
lading/utils/path.py
lading/utils/__init__.py
lading/cli.py
lading/commands/publish.py
lading/commands/bump.py
lading/config.py
lading/workspace/metadata.py
lading/workspace/graph_build.py
tests/unit/utils/test_path.py
tests/unit/test_cli.py
tests/unit/publish/test_run_workspace_config.py
tests/unit/test_bump_manifest_updates.py
docs/developers-guide.md
docs/lading-design.md
docs/roadmap.md
Normalize spelling around compiletest stderr artefact discovery/diagnostics and ensure tests/BDD features match the new wording.
  • Rename internal helpers and variables from artifact to artefact in diagnostics handling.
  • Update diagnostics messages from "artifacts" to "artefacts".
  • Adjust unit tests and BDD step definitions/feature text to expect the new wording and behaviour.
lading/commands/publish_diagnostics.py
tests/unit/publish/test_publish_diagnostics.py
tests/unit/publish/test_preflight_cargo_runner.py
tests/unit/publish/test_preflight_checks.py
tests/bdd/steps/test_publish_given_steps.py
tests/bdd/features/cli.feature
Standardize various normalization helpers and related tests from normalise_* to normalize_* for environment, test excludes, preflight responses, summaries, plans, and cmd-mox commands.
  • Rename environment coercion helper to normalize_environment and propagate to subprocess invocation helpers/tests.
  • Rename test-exclude normalization helper and preflight response normalizer to normalize_* and adjust tests.
  • Update cmd-mox command normalizer and all uses (BDD steps, unit tests) to normalize_cmd_mox_command.
  • Rename summary/plan/message normalization helpers in tests to normalize_* and keep snapshot expectations aligned.
lading/runtime/subprocess_runner.py
lading/commands/publish_preflight.py
lading/testing/cmd_mox_runner.py
tests/unit/publish/test_command_helpers.py
tests/bdd/steps/test_publish_infrastructure.py
tests/unit/publish/test_preflight_arguments.py
tests/unit/publish/test_run_preflight.py
tests/unit/publish/test_formatting_helpers.py
tests/unit/publish/test_run_workspace_config.py
tests/unit/publish/test_packaging.py
Align miscellaneous spelling in helpers, metrics, scripting standards, index checks, and docs on Oxford forms (normalize, artefacts, etc.).
  • Update text-only docstrings, comments, and documentation to use normalize/normalization and artefact as per policy.
  • Adjust metrics tests and config helpers to describe normalization consistently.
  • Rename Makefile and execution plan references from "artifacts" to "artefacts" where appropriate.
  • Clarify documentation style guide rule to use Oxford spelling in internal APIs and inline code.
lading/runtime/runner.py
lading/commands/publish_index_check.py
lading/utils/metrics.py
lading/commands/publish.py
lading/commands/publish_index_check.py
lading/config.py
docs/scripting-standards.md
docs/documentation-style-guide.md
docs/execplans/regenerate-lockfiles.md
Makefile
tests/unit/utils/test_metrics.py
tests/unit/test_config.py
tests/unit/test_workspace_models_validation.py
tests/unit/test_bump_lockfile_path_resolution.py
tests/unit/publish/test_phase_dispatch.py
Tighten spelling configuration so inline code is checked, preventing future API/documentation spelling drift.
  • Remove the pattern that exempted backticked inline code from spelling checks.
  • Ensure updated docs and code use the canonical spellings so the stricter policy passes.
typos.toml

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@codescene-access codescene-access 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.

Our agent can fix these. Install it.

Gates Passed
6 Quality Gates Passed

Absence of Expected Change Pattern

  • lading/lading/commands/publish.py is usually changed with: lading/tests/bdd/steps/test_publish_steps.py

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

@codescene-access codescene-access 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.

No quality gates enabled for this code.

@leynos
leynos marked this pull request as ready for review August 16, 2026 18:40

@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 @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

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

ℹ️ 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 lading/utils/__init__.py
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant