CSS Module Import Sorter

Build a tool that processes CSS Modules files and determines the correct import order based on their dependencies. The tool should analyze CSS files containing composes declarations and output the files in an order that respects their dependency relationships.

Problem Description

CSS Modules use composes to inherit styles from other classes. When classes compose from external files, those files must be loaded in the correct order. Your task is to build a system that:

1. Parses CSS files to extract composition dependencies
2. Builds a dependency graph showing which files depend on which other files
3. Determines a valid topological order for loading the files
4. Detects circular dependencies and reports them as errors

Input Format

Your tool will receive a list of CSS file paths and their contents. Each CSS file may contain composes declarations like:

.button {
  composes: base from "./theme.css";
  color: blue;
}

This indicates that the current file depends on theme.css and therefore theme.css must be loaded first.

Output Requirements

Your tool should output:

• A list of file paths in a valid dependency order (dependencies before dependents)
• If circular dependencies exist, throw an error indicating which files are involved

Test Cases

• When given three files where A depends on B and B depends on C, the order should be [C, B, A] @test
• When given two files with no dependencies between them, either order is valid @test
• When given files where A depends on B and C, and B also depends on C, the order should have C first, then B, then A @test
• When given files with a circular dependency (A depends on B, B depends on A), an error should be thrown @test

Implementation

@generates

API

/**
 * Analyzes CSS module files and determines the correct load order
 *
 * @param {Object} files - Map of file paths to CSS content
 * @returns {Array<string>} - Ordered list of file paths
 * @throws {Error} - If circular dependencies are detected
 */
function sortModulesByDependency(files) {
  // IMPLEMENTATION HERE
}

module.exports = { sortModulesByDependency };

Dependencies { .dependencies }

postcss-modules-extract-imports { .dependency }

A PostCSS plugin that processes CSS Modules and manages dependency graphs for import ordering.