refactor: Replace localeCompare with stable string comparison

.changeset/quiet-regions-wink.md

@@ -0,0 +1,5 @@
+---
+'@baseplate-dev/core-generators': patch
+---
+
+Add test:affected command to monorepo

.changeset/stable-string-comparison.md

@@ -0,0 +1,5 @@
+---
+'@baseplate-dev/utils': patch
+---
+
+Add stable compareStrings utility to replace localeCompare for deterministic sorting. The new compareStrings function provides consistent, locale-independent string comparison across all operating systems and environments, ensuring stable code generation and preventing merge conflicts caused by locale-dependent sorting.

AGENTS.md

@@ -255,6 +255,20 @@ Baseplate consists of two main tiers:
 - Organize complex generation with Task Phases
 - Use Dynamic Tasks for data-driven generation
 
+## String Comparison
+
+**IMPORTANT**: Always use `compareStrings` from `@baseplate-dev/utils` instead of `String.prototype.localeCompare()`.
+
+### When to Use localeCompare
+
+Only use `localeCompare()` when:
+
+1. Building user-facing features that require locale-aware sorting
+2. Displaying sorted lists in the UI
+3. Explicitly requested by product requirements
+
+For all code generation, file sorting, and internal data structures, use `compareStrings`.
+
 ## Key Reminders for Claude Code
 
 - Run `pnpm lint:affected` and `pnpm typecheck` before committing changes

examples/blog-with-auth/baseplate/generated/package.json

@@ -20,6 +20,7 @@
     "prettier:write": "turbo run prettier:write && pnpm run prettier:write:root",
     "prettier:write:root": "prettier --write . \"!apps/**\"",
     "test": "turbo run test",
+    "test:affected": "turbo run test --affected",
     "typecheck": "turbo run typecheck",
     "watch": "turbo run watch:gql"
   },

examples/blog-with-auth/package.json

@@ -20,6 +20,7 @@
     "prettier:write": "turbo run prettier:write && pnpm run prettier:write:root",
     "prettier:write:root": "prettier --write . \"!apps/**\"",
     "test": "turbo run test",
+    "test:affected": "turbo run test --affected",
     "typecheck": "turbo run typecheck",
     "watch": "turbo run watch:gql"
   },

examples/todo-with-auth0/baseplate/generated/package.json

@@ -20,6 +20,7 @@
     "prettier:write": "turbo run prettier:write && pnpm run prettier:write:root",
     "prettier:write:root": "prettier --write . \"!apps/**\"",
     "test": "turbo run test",
+    "test:affected": "turbo run test --affected",
     "typecheck": "turbo run typecheck",
     "watch": "turbo run watch:gql"
   },

examples/todo-with-auth0/package.json

@@ -20,6 +20,7 @@
     "prettier:write": "turbo run prettier:write && pnpm run prettier:write:root",
     "prettier:write:root": "prettier --write . \"!apps/**\"",
     "test": "turbo run test",
+    "test:affected": "turbo run test --affected",
     "typecheck": "turbo run typecheck",
     "watch": "turbo run watch:gql"
   },

packages/code-morph/package.json

@@ -42,6 +42,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@baseplate-dev/utils": "workspace:*",
     "@inquirer/prompts": "7.8.3",
     "change-case": "5.4.4",
     "commander": "^12.1.0",

packages/code-morph/src/morphers/utils/imports.ts

@@ -4,6 +4,7 @@ import type {
   SourceFile,
 } from 'ts-morph';
 
+import { compareStrings } from '@baseplate-dev/utils';
 import { Node } from 'ts-morph';
 
 /**
@@ -66,7 +67,7 @@ export function addOrUpdateImport(
     if (newImports.length > 0) {
       // Collect all import names (existing + new)
       const allImportNames = [...existingNames, ...newImports].sort((a, b) =>
-        a.localeCompare(b),
+        compareStrings(a, b),
       );
 
       // Replace with sorted named imports

packages/core-generators/src/generators/node/node-git-ignore/node-git-ignore.generator.ts

@@ -3,6 +3,7 @@ import {
   createGenerator,
   createGeneratorTask,
 } from '@baseplate-dev/sync';
+import { compareStrings } from '@baseplate-dev/utils';
 import { z } from 'zod';
 
 import { packageScope } from '#src/providers/scopes.js';
@@ -67,7 +68,7 @@ export const nodeGitIgnoreGenerator = createGenerator({
         ];
         if (exclusions.size > 0) {
           const sortedExclusions = [...exclusions.entries()].sort((a, b) =>
-            a[0].localeCompare(b[0]),
+            compareStrings(a[0], b[0]),
           );
           exclusionLines.push(
             ...sortedExclusions.flatMap(([, value]) => ['', ...value]),

packages/core-generators/src/renderers/extractor/plugins/template-paths/paths-file.ts

@@ -1,7 +1,7 @@
 import type { TemplateExtractorContext } from '@baseplate-dev/sync';
 
 import { TEMPLATE_EXTRACTOR_GENERATED_DIRECTORY } from '@baseplate-dev/sync';
-import { mapValuesOfMap } from '@baseplate-dev/utils';
+import { compareStrings, mapValuesOfMap } from '@baseplate-dev/utils';
 import { posixJoin } from '@baseplate-dev/utils/node';
 import { camelCase } from 'change-case';
 import { z } from 'zod';
@@ -127,7 +127,7 @@ function createPathsTask(
           methodName: root.method,
         })),
     }))
-    .toSorted((a, b) => a.providerName.localeCompare(b.providerName));
+    .toSorted((a, b) => compareStrings(a.providerName, b.providerName));
 
   const dependencies = TsCodeUtils.mergeFragmentsAsObject(
     Object.fromEntries(

packages/core-generators/src/renderers/extractor/plugins/typed-templates-file.ts

@@ -2,6 +2,7 @@ import {
   createTemplateExtractorPlugin,
   TEMPLATE_EXTRACTOR_GENERATED_DIRECTORY,
 } from '@baseplate-dev/sync';
+import { compareStrings } from '@baseplate-dev/utils';
 import { posixJoin } from '@baseplate-dev/utils/node';
 
 import { normalizeTsPathToJsPath } from '#src/utils/ts-paths.js';
@@ -76,7 +77,7 @@ export const typedTemplatesFilePlugin = createTemplateExtractorPlugin({
           templateContents: TS_TEMPLATE,
           variables: {
             TPL_TEMPLATE_FRAGMENTS: templatesFragment,
-            TPL_TEMPLATE_EXPORTS: `{ ${templateExports.toSorted((a, b) => a.localeCompare(b)).join(', ')} }`,
+            TPL_TEMPLATE_EXPORTS: `{ ${templateExports.toSorted((a, b) => compareStrings(a, b)).join(', ')} }`,
             TPL_EXPORT_NAME: exportName,
           },
           options: {

packages/core-generators/src/renderers/text/render-text-typed-templates.ts

@@ -1,6 +1,6 @@
 import type { TemplateExtractorTemplateEntry } from '@baseplate-dev/sync';
 
-import { quot, sortObjectKeys } from '@baseplate-dev/utils';
+import { compareStrings, quot, sortObjectKeys } from '@baseplate-dev/utils';
 import { camelCase } from 'change-case';
 import { groupBy } from 'es-toolkit';
 
@@ -56,7 +56,7 @@ function renderTextTypedTemplateGroup(
 ): TemplateExtractorTypedTemplate {
   const renderedTemplates = templates
     .map(({ name, config }) => renderTextTypedTemplate(name, config, context))
-    .toSorted((a, b) => a.exportName.localeCompare(b.exportName));
+    .toSorted((a, b) => compareStrings(a.exportName, b.exportName));
   const exportName = `${camelCase(groupName)}Group`;
 
   return {

packages/core-generators/src/renderers/typescript/extractor/parse-simple-replacements.ts

@@ -5,6 +5,8 @@
  * and returns a mapping for simple replacements.
  */
 
+import { compareStrings } from '@baseplate-dev/utils';
+
 const SIMPLE_REPLACEMENT_REGEX = /\/\* TPL_([A-Z0-9_]+)=([^*]*?) \*\/\n*/g;
 const ALLOWED_VALUE_PATTERN = /^[a-zA-Z0-9_$/.\-?]+$/;
 
@@ -85,7 +87,7 @@ export function generateSimpleReplacementComments(
   replacements: Record<string, string>,
 ): string[] {
   return Object.entries(replacements)
-    .sort(([, a], [, b]) => a.localeCompare(b)) // Sort by variable name
+    .sort(([, a], [, b]) => compareStrings(a, b)) // Sort by variable name
     .map(([value, variable]) => {
       // Extract just the part after TPL_
       const varName = variable.replace(/^TPL_/, '');

packages/core-generators/src/renderers/typescript/extractor/render-ts-typed-templates.ts

@@ -1,6 +1,6 @@
 import type { TemplateExtractorTemplateEntry } from '@baseplate-dev/sync';
 
-import { quot, sortObjectKeys } from '@baseplate-dev/utils';
+import { compareStrings, quot, sortObjectKeys } from '@baseplate-dev/utils';
 import { camelCase } from 'change-case';
 import { groupBy } from 'es-toolkit';
 
@@ -89,7 +89,7 @@ function renderTsTypedTemplateGroup(
 ): TemplateExtractorTypedTemplate {
   const renderedTemplates = templates
     .map(({ name, config }) => renderTsTypedTemplate(name, config, context))
-    .toSorted((a, b) => a.exportName.localeCompare(b.exportName));
+    .toSorted((a, b) => compareStrings(a.exportName, b.exportName));
   const exportName = `${camelCase(groupName)}Group`;
 
   return {

packages/core-generators/src/renderers/typescript/fragments/utils.ts

@@ -1,4 +1,4 @@
-import { toposortLocal } from '@baseplate-dev/utils';
+import { compareStrings, toposortLocal } from '@baseplate-dev/utils';
 import { isEqual, keyBy, uniqWith } from 'es-toolkit';
 
 import type { TsImportDeclaration } from '../imports/types.js';
@@ -191,7 +191,7 @@ export function mergeFragmentsWithHoistedFragments(
       // to the root fragment that uses them
       if (isARoot && !isBRoot) return -1;
       if (!isARoot && isBRoot) return 1;
-      return a.localeCompare(b);
+      return compareStrings(a, b);
     },
   );
 

packages/core-generators/src/renderers/typescript/imports/merge-ts-import-declarations.ts

@@ -1,4 +1,4 @@
-import { mapGroupBy } from '@baseplate-dev/utils';
+import { compareStrings, mapGroupBy } from '@baseplate-dev/utils';
 import { uniqBy } from 'es-toolkit';
 
 import type { TsImportDeclaration } from './types.js';
@@ -81,7 +81,7 @@ function convertToImportDeclarations(
       name: e.name as string,
       alias: e.alias === e.name ? undefined : e.alias,
     }))
-    .toSorted((a, b) => (a.alias ?? a.name).localeCompare(b.alias ?? b.name));
+    .toSorted((a, b) => compareStrings(a.alias ?? a.name, b.alias ?? b.name));
 
   const importDeclarations: TsImportDeclaration[] = [];
   const addDeclaration = (declaration: Partial<TsImportDeclaration>): void => {

packages/core-generators/src/renderers/typescript/renderers/file.ts

@@ -1,5 +1,6 @@
 import type { CodeBlockWriter, SourceFile } from 'ts-morph';
 
+import { compareStrings } from '@baseplate-dev/utils';
 import { Project } from 'ts-morph';
 
 import type {
@@ -83,7 +84,7 @@ function mergeImportsAndHoistedFragments(
   // This can be improved in the future but since the use-case is very limited,
   // we'll just throw an error if this happens.
   const sortedPositionedHoistedFragments = positionedHoistedFragments.sort(
-    (a, b) => a.key.localeCompare(b.key),
+    (a, b) => compareStrings(a.key, b.key),
   );
   if (
     new Set(sortedPositionedHoistedFragments.map((f) => f.key)).size !==

packages/core-generators/src/renderers/typescript/utils/ts-code-utils.ts

@@ -1,4 +1,4 @@
-import { quot } from '@baseplate-dev/utils';
+import { compareStrings, quot } from '@baseplate-dev/utils';
 import { sortBy } from 'es-toolkit';
 
 import type { TsCodeFragmentOptions } from '../fragments/creators.js';
@@ -270,7 +270,9 @@ export const TsCodeUtils = {
 
     const sortedKeys = disableSort
       ? keys
-      : keys.toSorted(caseSensitive ? undefined : (a, b) => a.localeCompare(b));
+      : keys.toSorted(
+          caseSensitive ? undefined : (a, b) => compareStrings(a, b),
+        );
 
     if (!disableSort && keys.some((k) => k.startsWith('...'))) {
       throw new Error('Cannot have spread keys when sorting is enabled');
@@ -350,7 +352,9 @@ export const TsCodeUtils = {
 
     const sortedKeys = disableSort
       ? keys
-      : keys.toSorted(caseSensitive ? undefined : (a, b) => a.localeCompare(b));
+      : keys.toSorted(
+          caseSensitive ? undefined : (a, b) => compareStrings(a, b),
+        );
 
     const mergedContent = sortedKeys
       .filter((key) => map.get(key))

packages/core-generators/src/test-helpers/utils.ts

@@ -1,3 +1,4 @@
+import { compareStrings } from '@baseplate-dev/utils';
 import { isDeepStrictEqual } from 'node:util';
 
 import type {
@@ -31,15 +32,18 @@ export function normalizeImports(
       ...imp,
       // Sort named imports alphabetically
       namedImports: imp.namedImports?.slice().sort((a, b) => {
-        const nameCompare = a.name.localeCompare(b.name);
+        const nameCompare = compareStrings(a.name, b.name);
         if (nameCompare !== 0) return nameCompare;
         // If names are equal, sort by alias
-        return (a.alias ?? '').localeCompare(b.alias ?? '');
+        return compareStrings(a.alias ?? '', b.alias ?? '');
       }),
     }))
     .sort((a, b) => {
       // Primary sort: module specifier
-      const moduleCompare = a.moduleSpecifier.localeCompare(b.moduleSpecifier);
+      const moduleCompare = compareStrings(
+        a.moduleSpecifier,
+        b.moduleSpecifier,
+      );
       if (moduleCompare !== 0) return moduleCompare;
 
       // Secondary sort: import type (namespace > default > named)
@@ -82,7 +86,7 @@ export function normalizeHoistedFragments(
         key: frag.key,
       } as TsHoistedFragment;
     })
-    .sort((a, b) => a.key.localeCompare(b.key));
+    .sort((a, b) => compareStrings(a.key, b.key));
 }
 
 /**

packages/fastify-generators/src/generators/core/service-file/service-file.generator.ts

@@ -15,7 +15,7 @@ import {
   createProviderType,
   createReadOnlyProviderType,
 } from '@baseplate-dev/sync';
-import { NamedArrayFieldContainer } from '@baseplate-dev/utils';
+import { compareStrings, NamedArrayFieldContainer } from '@baseplate-dev/utils';
 import { posixJoin } from '@baseplate-dev/utils/node';
 import { kebabCase } from 'change-case';
 import path from 'node:path';
@@ -140,7 +140,7 @@ export const serviceFileGenerator = createGenerator({
           build: async (builder) => {
             const orderedHeaders = headersContainer
               .getValue()
-              .sort((a, b) => a.name.localeCompare(b.name));
+              .sort((a, b) => compareStrings(a.name, b.name));
             const orderedMethods = methodsContainer
               .getValue()
               .sort((a, b) => a.order - b.order);

packages/fastify-generators/src/generators/prisma/prisma-data-service/prisma-data-service.generator.ts

@@ -12,6 +12,7 @@ import {
   createProviderType,
 } from '@baseplate-dev/sync';
 import {
+  compareStrings,
   lowercaseFirstChar,
   NamedArrayFieldContainer,
 } from '@baseplate-dev/utils';
@@ -161,7 +162,7 @@ export const prismaDataServiceGenerator = createGenerator({
               }),
             ),
           ...virtualInputFields.toSorted((a, b) =>
-            a.name.localeCompare(b.name),
+            compareStrings(a.name, b.name),
           ),
         ];
 

packages/fastify-generators/src/writers/prisma-schema/model-writer.ts

@@ -1,3 +1,5 @@
+import { compareStrings } from '@baseplate-dev/utils';
+
 import type { ScalarFieldType } from '#src/types/field-types.js';
 import type { PrismaOutputModel } from '#src/types/prisma-output.js';
 
@@ -186,7 +188,7 @@ export class PrismaModelBlockWriter {
       .sort((a, b) => a.order - b.order);
     const relationFields = this.fields
       .filter((field) => field.fieldType === 'relation')
-      .sort((a, b) => a.name.localeCompare(b.name));
+      .sort((a, b) => compareStrings(a.name, b.name));
 
     // Look for duplicated orders in scalar fields
     const orderSet = new Set(scalarFields.map((field) => field.order));

packages/project-builder-server/src/compiler/root/root-package-compiler.ts

@@ -117,6 +117,7 @@ export class RootPackageCompiler extends PackageCompiler {
         lint: `turbo run lint`,
         'lint:affected': `turbo run lint --affected`,
         test: `turbo run test`,
+        'test:affected': `turbo run test --affected`,
         'prettier:check': `turbo run prettier:check && pnpm run prettier:check:root`,
         'prettier:check:affected': `turbo run prettier:check --affected`,
         'prettier:write': `turbo run prettier:write && pnpm run prettier:write:root`,

packages/project-builder-server/src/diff/snapshot/snapshot-manifest.ts

@@ -1,4 +1,4 @@
-import { stringifyPrettyStable } from '@baseplate-dev/utils';
+import { compareStrings, stringifyPrettyStable } from '@baseplate-dev/utils';
 import {
   handleFileNotFoundError,
   readJsonWithSchema,
@@ -37,7 +37,7 @@ export async function saveSnapshotManifest(
       added: manifest.files.added.toSorted(),
       deleted: manifest.files.deleted.toSorted(),
       modified: manifest.files.modified.toSorted((a, b) =>
-        a.path.localeCompare(b.path),
+        compareStrings(a.path, b.path),
       ),
     },
   };

packages/project-builder-server/src/sync/file-id-map.ts

@@ -1,4 +1,4 @@
-import { enhanceErrorWithContext } from '@baseplate-dev/utils';
+import { compareStrings, enhanceErrorWithContext } from '@baseplate-dev/utils';
 import {
   handleFileNotFoundError,
   readJsonWithSchema,
@@ -51,7 +51,7 @@ export async function writeGeneratedFileIdMap(
   const fileIdMapPath = path.join(projectDirectory, FILE_ID_MAP_PATH);
   const fileIdMap = Object.fromEntries(
     [...fileIdToRelativePathMap.entries()].sort(([a], [b]) =>
-      a.localeCompare(b),
+      compareStrings(a, b),
     ),
   );
   await writeJson(fileIdMapPath, fileIdMap);