CSS Module Import Validator

A tool that processes CSS Modules files containing composes declarations and validates the import order to detect circular dependencies and nondeterministic import ordering.

Problem Description

CSS Modules allow developers to compose styles from different files using the composes syntax. However, when multiple CSS files have interdependent compositions, the order in which imports are resolved becomes critical. Your task is to build a validator that processes CSS files with composes declarations and detects import ordering issues.

Requirements

Your solution should:

1. Process CSS files with composes declarations: Accept CSS content containing composes declarations that import from other CSS files.

2. Detect nondeterministic import order: When multiple CSS rules reference the same imports in different orders, creating ambiguous dependency relationships, your validator should detect this and report an error.

3. Handle valid import orders: When imports have a clear, deterministic order (no conflicts), the validator should successfully process them without errors.

4. Extract and transform imports: Transform composes declarations into explicit import rules and generate unique identifiers for imported class names.

Test Cases

Valid Import Order { .test-group }

• Given CSS with two rules where .aa composes from a.css then b.css, and .bb composes from a.css then b.css (same order), the validator processes successfully without errors. @test

• Given CSS with a single rule composing from multiple files, the validator successfully transforms the composes declaration and generates unique import identifiers. @test

Nondeterministic Import Detection { .test-group }

• Given CSS where .aa composes from b.css then c.css, but .bb composes from c.css then b.css (conflicting order), the validator throws an error indicating nondeterministic import order. @test

• Given CSS with three rules creating a circular dependency pattern, the validator detects the cycle and throws an appropriate error. @test

Implementation

@generates

API

/**
 * Validates CSS content with composes declarations and detects import order issues.
 *
 * @param {string} cssContent - The CSS content to validate
 * @param {Object} options - Configuration options
 * @param {boolean} options.failOnWrongOrder - Whether to throw errors on nondeterministic order
 * @returns {Promise<string>} The transformed CSS with explicit import rules
 * @throws {Error} When nondeterministic import order or circular dependencies are detected
 */
async function validateCssModuleImports(cssContent, options = {}) {
  // Implementation here
}

module.exports = { validateCssModuleImports };

Dependencies { .dependencies }

postcss { .dependency }

Provides CSS parsing and AST manipulation capabilities.

@satisfied-by

postcss-modules-extract-imports { .dependency }

Transforms CSS Modules composes declarations into explicit import rules with topological sorting and cycle detection.

@satisfied-by