enhancement-fix(spec): improve config semantic validation errors

[jaya6400]

Added validateConfigSemantics() that runs on successful parse and before the upgrade fallback, with helpers for legacy-upgrade detection and unknown bucket ID resolution (v1 path→type vs v1.1+ type→config formats).

New error messages:

• Missing source: Source locale is required. Add "locale.source" to your i18n.json (e.g. "en").
• Empty targets: At least one target locale is required. Add locale targets to your i18n.json (e.g. ["es", "fr"]).
• Duplicate targets: Duplicate target locale(s): es. Remove duplicates from locale.targets.
• No buckets: No buckets configured. Add at least one bucket to i18n.json under "buckets"
• Unknown bucket types: Unknown bucket type(s): invalid, not-a-bucket. Supported types: ail, android, csv.
  Also added .min(1) on localeSchema.targets as schema-level defense.

Tests: All 35 spec tests pass (pnpm --filter "@lingo.dev/_spec" test).

Testing

• All tests pass locally

Visuals

Required for UI/UX changes:

• Before/after screenshots attached
• Video demo for interactions (< 30s)

Checklist

• Tests cover business logic (not just happy path)
• No breaking changes (or documented below)

Closes #561

Summary by CodeRabbit

• Bug Fixes
  • Improved configuration validation with clearer, more descriptive error messages. Users now receive better feedback when source locales are missing, target locales are empty or contain duplicates, bucket configurations are missing or empty, or when unrecognized bucket types are encountered.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR enhances i18n configuration validation by introducing semantic validation logic that aggregates all validation errors and reports them with descriptive messages. The semantic validator runs after structural schema validation and in both standard and config-upgrade parse paths to catch missing source locales, empty or duplicate target locales, missing buckets, and unknown bucket types.

Changes

Configuration Validation Enhancement

Layer / File(s)	Summary
Semantic validation logic packages/spec/src/config.ts	Adds validateConfigSemantics function with bucket-type allowlisting, legacy upgrade detection, and comprehensive semantic checks; accumulates all errors and throws as single combined message.
Schema constraints and parse integration packages/spec/src/config.ts	Updates localeSchema to enforce targets.min(1); calls validateConfigSemantics after Zod parsing and around the upgrader path to catch semantic failures in both standard and schema-extension parse flows.
Test coverage and release notes packages/spec/src/config.spec.ts, .changeset/improve-config-validation-errors.md	Introduces createLatestConfig test helper and test cases validating error messages for missing source, empty/duplicate targets, empty buckets, and unknown bucket types; documents patch release.

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• cherkanovart
• moygospadin
• SreedharThappeta

🐰 A rabbit hops through config files with glee,
Validation now sings errors crystal clear!
No more silent breaks from a misconfigured tree,
These helpful messages make the path appear.
Configuration troubles? They now disappear! 🌿✨

🚥 Pre-merge checks | ✅ 4 | ❌ 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 (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description covers the key changes, new error messages, implementation details, and confirms all tests pass, aligning well with the template's requirements for summary, changes, and testing sections.
Linked Issues check	✅ Passed	The PR fully addresses issue #561 by implementing validateConfigSemantics() with descriptive error messages for missing source locales, empty/duplicate target locales, missing buckets, and unknown bucket types.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to improving config validation errors: validateConfigSemantics() function, enhanced error messages, updated localeSchema, and corresponding test cases.
Title check	✅ Passed	The title accurately summarizes the main change: improving config semantic validation errors in the spec module, which is the core objective of this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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]

🧹 Nitpick comments (1)

packages/spec/src/config.ts (1)

217-217: 💤 Low value

Consider removing redundant semantic validation or validating the upgrade result.

This validates rawConfig after the upgrade completes, but the same rawConfig was already validated at Line 213 before the upgrade. This is redundant. If the intent is to verify upgrade correctness, validate result instead: validateConfigSemantics(result). Otherwise, remove this line to reduce confusion.

♻️ Options to resolve redundancy

Option 1: Remove redundant validation

  const baseConfig = definition.parse(rawConfig);
  const result = upgrader(baseConfig);
- validateConfigSemantics(rawConfig);
  return result;

Option 2: Validate upgrade output

  const baseConfig = definition.parse(rawConfig);
  const result = upgrader(baseConfig);
- validateConfigSemantics(rawConfig);
+ validateConfigSemantics(result);
  return result;

🤖 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 `@packages/spec/src/config.ts` at line 217, The call to validateConfigSemantics
after the upgrade is validating rawConfig again (redundant); change that
invocation to validate the upgraded configuration by replacing
validateConfigSemantics(rawConfig) with validateConfigSemantics(result) so the
upgrade output is verified (reference: validateConfigSemantics, rawConfig,
result).

🤖 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.

Nitpick comments:
In `@packages/spec/src/config.ts`:
- Line 217: The call to validateConfigSemantics after the upgrade is validating
rawConfig again (redundant); change that invocation to validate the upgraded
configuration by replacing validateConfigSemantics(rawConfig) with
validateConfigSemantics(result) so the upgrade output is verified (reference:
validateConfigSemantics, rawConfig, result).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3e283904-6b18-40af-be33-cb192039e20d

📥 Commits

Reviewing files that changed from the base of the PR and between 20ca833 and 60b86fd.

📒 Files selected for processing (3)

• .changeset/improve-config-validation-errors.md
• packages/spec/src/config.spec.ts
• packages/spec/src/config.ts

[jaya6400]

Hi, could a maintainer please approve the pending workflows for this PR? Thanks!
@maxprilutskiy @moygospadin @sumitsaurabh927 @cherkanovart @AndreyHirsa