refactor(cli): dedupe locale path prefixing

[bgub]

Summary

• add a shared localizePathSegment helper for locale-prefixed path values
• reuse it for Mintlify frontmatter URLs and OpenAPI docs directory localization
• add focused helper coverage for prefixing, locale replacement, skips, whitespace, and empty paths

Checks

• pnpm --filter gt test -- localizePathSegment localizeMintlifyFrontmatterUrls processOpenApi
• pnpm --filter gt typecheck
• pnpm format
• git diff --check

Greptile Summary

This PR consolidates duplicate locale-prefixing logic from localizeMintlifyFrontmatterUrls.ts and processOpenApi.ts into a single localizePathSegment helper. Both callers are updated to use the new function, with localizeMintlifyFrontmatterUrls passing { trailingSlashWhenEmpty: true } to preserve its original trailing-slash behavior for empty URL paths, while processOpenApi omits the option to preserve its no-trailing-slash directory behavior.

• New helper (localizePathSegment.ts): handles leading slash preservation, surrounding whitespace, known-locale prefix replacement, skip patterns (external/anchor/relative), and an optional trailing-slash mode for empty paths.
• Behavior parity: both callers' inline implementations are faithfully replicated; no observable behavior change for Mintlify frontmatter URLs or OpenAPI directory localization.
• Test coverage: focused unit tests for the new helper covering the main branches; one minor gap around bare locale-only replacement (/en → /es) noted in a comment.

Confidence Score: 4/5

Safe to merge; the refactor faithfully preserves both callers' original behavior and the only gap is a missing test for an edge case that the implementation already handles correctly.

The extracted helper is a clean deduplication with no logic changes. The trailingSlashWhenEmpty option correctly differentiates the two callers' behaviors, and the existing tests confirm the main code paths. The only gap is the missing test for a bare locale-prefix replacement (/en → /es), which is a coverage concern rather than a defect.

The test file at packages/cli/src/utils/tests/localizePathSegment.test.ts would benefit from a test for bare locale-prefix replacement; all other files are straightforward.

Important Files Changed

Filename	Overview
packages/cli/src/utils/localizePathSegment.ts	New shared helper; logic is a faithful extraction of both callers' inline implementations, correctly handling leading slash, surrounding whitespace, locale replacement, skip patterns, and the trailingSlashWhenEmpty option.
packages/cli/src/utils/tests/localizePathSegment.test.ts	Good coverage of the main paths; missing an explicit test for bare locale-only replacement (e.g. /en → /es), which exercises the empty restSegments.join('/') branch.
packages/cli/src/utils/localizeMintlifyFrontmatterUrls.ts	Removes the now-redundant normalizeMintlifyFrontmatterUrl and delegates to localizePathSegment with trailingSlashWhenEmpty: true, preserving the original trailing-slash behavior for empty URL paths.
packages/cli/src/utils/processOpenApi.ts	localizeDocsJsonDirectory simplified to a one-liner; the omission of trailingSlashWhenEmpty correctly preserves the original no-trailing-slash behavior for directory paths.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[localizePathSegment
value, targetLocale, knownLocales, options] --> B{trimmed empty
or SKIPPABLE_URL_REGEX?}
    B -- yes --> C[return null]
    B -- no --> D[extract leadingWhitespace
trailingWhitespace
leadingSlash
pathBody
firstSegment + restSegments]
    D --> E{firstSegment
=== targetLocale?}
    E -- yes --> F[reconstruct normalized
= leadingWS + leadingSlash + pathBody + trailingWS]
    F --> G{normalized === value?}
    G -- yes --> C
    G -- no --> H[return normalized]
    E -- no --> I{knownLocales
has firstSegment?}
    I -- yes --> J[unprefixedPath = restSegments.join slash]
    I -- no --> K[unprefixedPath = pathBody]
    J --> L{unprefixedPath
non-empty?}
    K --> L
    L -- yes --> M[localizedPath =
targetLocale/unprefixedPath]
    L -- no --> N{trailingSlashWhenEmpty?}
    N -- yes --> O[localizedPath = targetLocale/]
    N -- no --> P[localizedPath = targetLocale]
    M --> Q[return normalized
leadingWS + leadingSlash
+ localizedPath + trailingWS]
    O --> Q
    P --> Q

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[localizePathSegment
value, targetLocale, knownLocales, options] --> B{trimmed empty
or SKIPPABLE_URL_REGEX?}
    B -- yes --> C[return null]
    B -- no --> D[extract leadingWhitespace
trailingWhitespace
leadingSlash
pathBody
firstSegment + restSegments]
    D --> E{firstSegment
=== targetLocale?}
    E -- yes --> F[reconstruct normalized
= leadingWS + leadingSlash + pathBody + trailingWS]
    F --> G{normalized === value?}
    G -- yes --> C
    G -- no --> H[return normalized]
    E -- no --> I{knownLocales
has firstSegment?}
    I -- yes --> J[unprefixedPath = restSegments.join slash]
    I -- no --> K[unprefixedPath = pathBody]
    J --> L{unprefixedPath
non-empty?}
    K --> L
    L -- yes --> M[localizedPath =
targetLocale/unprefixedPath]
    L -- no --> N{trailingSlashWhenEmpty?}
    N -- yes --> O[localizedPath = targetLocale/]
    N -- no --> P[localizedPath = targetLocale]
    M --> Q[return normalized
leadingWS + leadingSlash
+ localizedPath + trailingWS]
    O --> Q
    P --> Q

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
packages/cli/src/utils/__tests__/localizePathSegment.test.ts:16-19
**Missing test: bare locale-only replacement**

The "replaces existing known-locale prefixes" block only covers a multi-segment path (`/en/docs/api`). The branch that produces `unprefixedPath = restSegments.join('/') = ''` (i.e., the input is just a locale prefix with nothing after it, like `/en`) is exercised by both callers but has no dedicated test. A case like `localizePathSegment('/en', 'es', knownLocales)` → `'/es'` would confirm that `restSegments.join('/')` correctly returns an empty string and the function falls through to the `trailingSlashWhenEmpty` logic rather than emitting `'es/'` unexpectedly.

_{Reviews (1): Last reviewed commit: "refactor(cli): dedupe locale path prefix..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[greptile-apps]

Missing test: bare locale-only replacement

The "replaces existing known-locale prefixes" block only covers a multi-segment path (/en/docs/api). The branch that produces unprefixedPath = restSegments.join('/') = '' (i.e., the input is just a locale prefix with nothing after it, like /en) is exercised by both callers but has no dedicated test. A case like localizePathSegment('/en', 'es', knownLocales) → '/es' would confirm that restSegments.join('/') correctly returns an empty string and the function falls through to the trailingSlashWhenEmpty logic rather than emitting 'es/' unexpectedly.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/cli/src/utils/__tests__/localizePathSegment.test.ts
Line: 16-19

Comment:
**Missing test: bare locale-only replacement**

The "replaces existing known-locale prefixes" block only covers a multi-segment path (`/en/docs/api`). The branch that produces `unprefixedPath = restSegments.join('/') = ''` (i.e., the input is just a locale prefix with nothing after it, like `/en`) is exercised by both callers but has no dedicated test. A case like `localizePathSegment('/en', 'es', knownLocales)` → `'/es'` would confirm that `restSegments.join('/')` correctly returns an empty string and the function falls through to the `trailingSlashWhenEmpty` logic rather than emitting `'es/'` unexpectedly.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!