improve generated style sorting (#82)

Author: ryanatkn

.changeset/yellow-paths-add.md

@@ -0,0 +1,5 @@
+---
+'@fuzdev/fuz_css': patch
+---
+
+improve generated style sorting

src/lib/class_variable_index.ts

@@ -23,7 +23,7 @@ export interface CssClassVariableIndex {
  * Builds an index of CSS variables used by each class definition.
  *
  * @param definitions - CSS class definitions to index
- * @returns CssClassVariableIndex with variable lookups
+ * @returns `CssClassVariableIndex` with variable lookups
  */
 export const build_class_variable_index = (
 	definitions: Record<string, CssClassDefinition | undefined>,
@@ -74,9 +74,9 @@ const extract_variables_from_definition = (definition: CssClassDefinition): Set<
 /**
  * Gets variables used by a specific class.
  *
- * @param index - The class variable index
- * @param class_name - Name of the class to lookup
- * @returns Set of variable names (without -- prefix), or null if class not found
+ * @param index - the class variable index
+ * @param class_name - name of the class to lookup
+ * @returns set of variable names (without -- prefix), or null if class not found
  */
 export const get_class_variables = (
 	index: CssClassVariableIndex,
@@ -86,9 +86,9 @@ export const get_class_variables = (
 /**
  * Collects all variables used by a set of classes.
  *
- * @param index - The class variable index
- * @param class_names - Class names to collect variables from
- * @returns Set of all variable names used by the classes
+ * @param index - the class variable index
+ * @param class_names - class names to collect variables from
+ * @returns set of all variable names used by the classes
  */
 export const collect_class_variables = (
 	index: CssClassVariableIndex,
@@ -111,9 +111,9 @@ export const collect_class_variables = (
 /**
  * Gets all class names that use a specific variable.
  *
- * @param index - The class variable index
- * @param variable_name - Variable name to search for (without -- prefix)
- * @returns Array of class names that use this variable
+ * @param index - the class variable index
+ * @param variable_name - variable name to search for (without -- prefix)
+ * @returns array of class names that use this variable
  */
 export const get_classes_using_variable = (
 	index: CssClassVariableIndex,

src/lib/css_bundled_resolution.ts

@@ -50,36 +50,39 @@ const TYPO_SIMILARITY_THRESHOLD = 0.6;
  *
  * See variable_graph.ts for the Levenshtein-based approach used for variables.
  */
-const string_similarity = (a: string, b: string): number => {
-	if (a === b) return 1;
-	if (a.length < 2 || b.length < 2) return 0;
-
-	const bigrams_a: Set<string> = new Set();
-	for (let i = 0; i < a.length - 1; i++) {
-		bigrams_a.add(a.slice(i, i + 2));
+const build_bigrams = (str: string): Set<string> => {
+	const bigrams: Set<string> = new Set();
+	for (let i = 0; i < str.length - 1; i++) {
+		bigrams.add(str.slice(i, i + 2));
 	}
+	return bigrams;
+};
 
+const string_similarity = (bigrams_a: Set<string>, len_a: number, b: string): number => {
+	if (len_a < 2 || b.length < 2) return 0;
 	let matches = 0;
 	for (let i = 0; i < b.length - 1; i++) {
 		if (bigrams_a.has(b.slice(i, i + 2))) matches++;
 	}
-
-	return (2 * matches) / (a.length - 1 + b.length - 1);
+	return (2 * matches) / (len_a - 1 + b.length - 1);
 };
 
 /**
  * Finds the most similar name from a set of known names.
  *
- * @param name - The name to find similar matches for
- * @param known_names - Set of known valid names
- * @returns The most similar name, or null if none are similar enough
+ * @param name - the name to find similar matches for
+ * @param known_names - set of known valid names
+ * @returns the most similar name, or null if none are similar enough
  */
 const find_similar_name = (name: string, known_names: Set<string>): string | null => {
+	if (name === '') return null;
+	const bigrams_a = build_bigrams(name);
 	let best_match: string | null = null;
 	let best_similarity = TYPO_SIMILARITY_THRESHOLD;
 
 	for (const known of known_names) {
-		const similarity = string_similarity(name, known);
+		if (name === known) return known; // exact match fast path
+		const similarity = string_similarity(bigrams_a, name.length, known);
 		if (similarity > best_similarity) {
 			best_similarity = similarity;
 			best_match = known;
@@ -182,8 +185,8 @@ export interface CssResolutionOptions {
  * 3. Resolve transitive variable dependencies
  * 4. Generate output: theme_css (light+dark), base_css (source order)
  *
- * @param options - Resolution options including indexes, detected usage, and config
- * @returns Resolution result with theme CSS, base CSS, and diagnostics
+ * @param options - resolution options including indexes, detected usage, and config
+ * @returns resolution result with theme CSS, base CSS, and diagnostics
  */
 export const resolve_css = (options: CssResolutionOptions): CssResolutionResult => {
 	const {
@@ -430,10 +433,10 @@ export interface GenerateBundledCssOptions {
 /**
  * Generates combined CSS output from resolution result.
  *
- * @param result - Resolution result from resolve_css
- * @param utility_css - Generated utility CSS (from generate_classes_css)
- * @param options - Output options
- * @returns Combined CSS string
+ * @param result - resolution result from `resolve_css`
+ * @param utility_css - generated utility CSS (from `generate_classes_css`)
+ * @param options - output options
+ * @returns combined CSS string
  */
 export const generate_bundled_css = (
 	result: CssResolutionResult,

src/lib/css_cache.ts

@@ -61,9 +61,9 @@ export interface CachedExtraction {
  * Computes the cache file path for a source file.
  * Cache structure mirrors source tree: `src/lib/Foo.svelte` → `.fuz/cache/css/src/lib/Foo.svelte.json`
  *
- * @param source_path - Absolute path to the source file
- * @param cache_dir - Absolute path to the cache directory
- * @param project_root - Normalized project root (must end with `/`)
+ * @param source_path - absolute path to the source file
+ * @param cache_dir - absolute path to the cache directory
+ * @param project_root - normalized project root (must end with `/`)
  */
 export const get_cache_path = (
 	source_path: string,
@@ -82,9 +82,9 @@ export const get_cache_path = (
  * Internal files use relative paths mirroring source tree.
  * External files (outside project root) use hashed absolute paths in `_external/`.
  *
- * @param file_id - Absolute path to the source file
- * @param cache_dir - Absolute path to the cache directory
- * @param project_root - Normalized project root (must end with `/`)
+ * @param file_id - absolute path to the source file
+ * @param cache_dir - absolute path to the cache directory
+ * @param project_root - normalized project root (must end with `/`)
  */
 export const get_file_cache_path = (
 	file_id: string,
@@ -102,8 +102,8 @@ export const get_file_cache_path = (
  * Returns `null` if the cache is missing, corrupted, or has a version mismatch.
  * This makes the cache self-healing: any error triggers re-extraction.
  *
- * @param ops - Filesystem operations for dependency injection
- * @param cache_path - Absolute path to the cache file
+ * @param ops - filesystem operations for dependency injection
+ * @param cache_path - absolute path to the cache file
  */
 export const load_cached_extraction = async (
 	ops: CacheOperations,
@@ -133,10 +133,10 @@ export const load_cached_extraction = async (
  * Uses atomic write (temp file + rename) for crash safety.
  * Normalizes empty collections to null to avoid allocation overhead on load.
  *
- * @param ops - Filesystem operations for dependency injection
- * @param cache_path - Absolute path to the cache file
+ * @param ops - filesystem operations for dependency injection
+ * @param cache_path - absolute path to the cache file
  * @param content_hash - SHA-256 hash of the source file contents
- * @param extraction - Extraction data to cache
+ * @param extraction - extraction data to cache
  */
 export const save_cached_extraction = async (
 	ops: CacheOperations,
@@ -184,8 +184,8 @@ export const save_cached_extraction = async (
  * Deletes a cached extraction file.
  * Silently succeeds if the file doesn't exist.
  *
- * @param ops - Filesystem operations for dependency injection
- * @param cache_path - Absolute path to the cache file
+ * @param ops - filesystem operations for dependency injection
+ * @param cache_path - absolute path to the cache file
  */
 export const delete_cached_extraction = async (
 	ops: CacheOperations,
@@ -198,7 +198,7 @@ export const delete_cached_extraction = async (
  * Converts a cached extraction back to the runtime format.
  * Preserves null semantics (null = empty).
  *
- * @param cached - Cached extraction data
+ * @param cached - cached extraction data
  */
 export const from_cached_extraction = (cached: CachedExtraction): ExtractionData => ({
 	classes: cached.classes ? new Map(cached.classes) : null,

src/lib/css_class_definitions.ts

@@ -321,9 +321,9 @@ export const css_class_definitions: Record<string, CssClassDefinition | undefine
  * Merges user class definitions with the built-in defaults.
  * User definitions take precedence over defaults with the same name.
  *
- * @param user_definitions - User-provided class definitions to merge
- * @param include_defaults - Whether to include built-in definitions
- * @returns Merged class definitions
+ * @param user_definitions - user-provided class definitions to merge
+ * @param include_defaults - whether to include built-in definitions
+ * @returns merged class definitions
  * @throws Error if `include_defaults` is false and no user definitions provided
  */
 export const merge_class_definitions = (

src/lib/css_class_extractor.ts

@@ -140,8 +140,8 @@ export class SourceIndex {
 	 * Converts a character offset to a source location.
 	 *
 	 * @param offset - 0-based character offset in the source
-	 * @param file - File path for the location
-	 * @returns SourceLocation with 1-based line and column
+	 * @param file - file path for the location
+	 * @returns `SourceLocation` with 1-based line and column
 	 */
 	get_location(offset: number, file: string): SourceLocation {
 		// Binary search for line
@@ -159,10 +159,10 @@ export class SourceIndex {
 /**
  * Adds a class with its location to the extraction result.
  *
- * @param classes - Map of classes to locations
- * @param class_name - Class name to add
- * @param location - Source location where the class was found
- * @mutates classes - Adds or appends to the map entry
+ * @param classes - map of classes to locations
+ * @param class_name - class name to add
+ * @param location - source location where the class was found
+ * @mutates classes - adds or appends to the map entry
  */
 const add_class_with_location = (
 	classes: Map<string, Array<SourceLocation>>,
@@ -285,9 +285,9 @@ const location_from_offset = (state: WalkState, offset: number): SourceLocation
 /**
  * Extracts CSS classes from a Svelte file using AST parsing.
  *
- * @param source - The Svelte file source code
- * @param file - File path for location tracking
- * @returns Extraction result with classes, tracked variables, elements, and diagnostics
+ * @param source - the Svelte file source code
+ * @param file - file path for location tracking
+ * @returns extraction result with classes, tracked variables, elements, and diagnostics
  */
 export const extract_from_svelte = (source: string, file = '<unknown>'): ExtractionResult => {
 	const source_index = new SourceIndex(source);
@@ -474,10 +474,10 @@ const extract_fuz_comments_from_script = (
 /**
  * Extracts CSS classes from a TypeScript/JS file using AST parsing.
  *
- * @param source - The TS/JS file source code
- * @param file - File path for location tracking
- * @param acorn_plugins - Additional acorn plugins (e.g., acorn-jsx for React)
- * @returns Extraction result with classes, tracked variables, elements, and diagnostics
+ * @param source - the TS/JS file source code
+ * @param file - file path for location tracking
+ * @param acorn_plugins - additional acorn plugins (e.g., acorn-jsx for React)
+ * @returns extraction result with classes, tracked variables, elements, and diagnostics
  */
 export const extract_from_ts = (
 	source: string,
@@ -547,9 +547,9 @@ export const extract_from_ts = (
  * Unified extraction function that auto-detects file type.
  * Returns just the class names as a Set.
  *
- * @param source - The file source code
- * @param options - Extraction options
- * @returns Set of class names, or null if none found
+ * @param source - the file source code
+ * @param options - extraction options
+ * @returns set of class names, or null if none found
  */
 export const extract_css_classes = (
 	source: string,
@@ -563,9 +563,9 @@ export const extract_css_classes = (
  * Unified extraction function that auto-detects file type.
  * Returns full extraction result with locations and diagnostics.
  *
- * @param source - The file source code
- * @param options - Extraction options
- * @returns Full extraction result with classes, tracked variables, and diagnostics
+ * @param source - the file source code
+ * @param options - extraction options
+ * @returns full extraction result with classes, tracked variables, and diagnostics
  */
 export const extract_css_classes_with_locations = (
 	source: string,