Skip to content

IMPLEMENTATION-SUMMARY.md

Latest commit

 

History

History
250 lines (192 loc) · 6.4 KB

IMPLEMENTATION-SUMMARY.md

File metadata and controls

250 lines (192 loc) · 6.4 KB

Complete Implementation Summary

Overview

This document summarizes all bug fixes and documentation added to the Less.js codebase.

✅ Fix 1: Line Comments (//) Stripped Properly

Problem

Double-slash line comments were appearing in compiled CSS output, particularly in:

  • Custom CSS properties (--variable)
  • Permissive value parsing contexts
  • Complex selector constructs

Solution

Modified packages/less/src/less/parser/parser-input.js to handle line comments in the $parseUntil function:

case '/':
    if (input.charAt(i + 1) === '*') {
        // Block comment start: /* ... */
        i++;
        inComment = true;
        blockDepth++;
    } else if (input.charAt(i + 1) === '/') {
        // Line comment start: // ... (strip until newline)
        if (i > lastPos) {
            parseGroups.push(input.substr(lastPos, i - lastPos));
        }
        let nextNewLine = input.indexOf('\n', i + 2);
        if (nextNewLine < 0) {
            i = length;
            lastPos = i;
            continue;
        }
        i = nextNewLine;
        lastPos = i + 1;
    }
    break;

Files Changed

  • packages/less/src/less/parser/parser-input.js

Tests Added

  • packages/test-data/less/line-comments/line-comments.less - Input with various comment scenarios
  • packages/test-data/css/line-comments/line-comments.css - Expected output
  • verify-line-comments-fix.js - Standalone verification script

Verification

Run the verification script:

node verify-line-comments-fix.js

✅ Fix 2: Document Extend Variable Scope (Issue #3706)

Problem

Users expected variables defined inside an :extend() block to override extended selector values, but this doesn't work due to Less.js's compilation pipeline.

Explanation

This is by design, not a bug:

  1. Evaluation Phase: Variables resolved, expressions evaluated
  2. Extend Visitor Phase: Selectors extended (no re-evaluation)

Extend works on selectors, not values.

Solutions Documented

Solution 1: Parameterized Mixin ⭐ (Recommended)

.a-style(@color: red) {
  color: @color;
}

a { .a-style(); }
.foo a { .a-style(green); }

Solution 2: CSS Custom Properties

a { color: var(--a-color, red); }
.foo { --a-color: green; }

Solution 3: Explicit Override

.foo a {
  &:extend(a all);
  color: green;
}

Files Created

  • EXTEND-VARIABLE-SCOPE-GUIDE.md - Comprehensive guide with examples
  • packages/test-data/less/extend-variable-scope/extend-variable-scope.less - Test case
  • packages/test-data/css/extend-variable-scope/extend-variable-scope.css - Expected output

Documentation Updated

  • FIXES-SUMMARY.md - Added section documenting this behavior

📁 All Files Changed/Created

Source Code Changes

  1. packages/less/src/less/parser/parser-input.js - Line comment handling in $parseUntil

Test Files

  1. packages/test-data/less/line-comments/line-comments.less
  2. packages/test-data/css/line-comments/line-comments.css
  3. packages/test-data/less/extend-variable-scope/extend-variable-scope.less
  4. packages/test-data/css/extend-variable-scope/extend-variable-scope.css

Documentation

  1. FIXES-SUMMARY.md - Updated with new fixes
  2. EXTEND-VARIABLE-SCOPE-GUIDE.md - Comprehensive guide for extend/variable behavior
  3. IMPLEMENTATION-SUMMARY.md - This file
  4. verify-line-comments-fix.js - Verification script

🧪 Testing

Automated Tests

The test files are in the standard Less.js test structure:

  • Input: packages/test-data/less/<test-name>/<test-name>.less
  • Expected: packages/test-data/css/<test-name>/<test-name>.css

Run the full test suite:

cd packages/less
npm install
npm run build
npm test

Manual Verification

Line Comment Fix

node verify-line-comments-fix.js

Or compile manually:

cd packages/less
node bin/lessc ../../test-fixes.less output.css
cat output.css  # Should have no // comments

Extend Variable Scope

cd packages/less
node bin/lessc ../../packages/test-data/less/extend-variable-scope/extend-variable-scope.less output.css
cat output.css

Expected output:

a,
.foo a {
  color: red;
}

📊 Impact Analysis

Breaking Changes

None - All changes are either bug fixes or documentation.

Compatibility

  • Less Version: 4.4.2+
  • Node.js: 14+ (as per existing requirements)
  • Browsers: No impact (compilation only)

Performance

  • Line Comment Fix: Negligible impact (adds simple string scanning)
  • Extend Variable Scope: Documentation only, no code changes

🚀 Deployment Checklist

Before Merging

  • Source code changes implemented
  • Test cases created
  • Documentation written
  • Verification scripts created
  • Run full test suite
  • Manual verification on sample projects
  • Code review

After Merging

  • Update CHANGELOG.md with version bump
  • Tag release
  • Publish to npm
  • Close related GitHub issues (#3706)
  • Update documentation website

🔗 Related Issues

  • Line Comments: Generic parsing bug
  • Extend Variable Scope: #3706

📝 Notes for Maintainers

Line Comment Fix

  • Implementation is in $parseUntil which handles permissive parsing
  • The skipWhitespace function already handled // in normal parsing
  • This fix completes comment handling across all parsing contexts
  • No configuration needed - line comments are always stripped

Extend Variable Scope

  • This is architectural behavior, not a bug
  • Changing it would require redesigning the compilation pipeline
  • Current behavior is consistent with Less's design philosophy
  • Recommended patterns (mixins, CSS vars) are idiomatic and maintainable
  • Consider adding this to official documentation/FAQ

Testing

  • Test structure follows existing Less.js patterns
  • Each test has .less input and .css expected output
  • Verification script can be run standalone for quick checks

📚 Additional Resources

Implementation Date: October 19, 2025
Status: ✅ Complete
Version: Less.js 4.4.2+
Contributors: GitHub Copilot Agent