Migrating Sass from @import to modules

// Compiles a site that still loads Bootstrap with @import, and reports where its deprecation warnings come from.
// Run it in this folder after `npm install` in the examples folder: node report.mjs
import { spawnSync } from 'node:child_process';
import { createRequire } from 'node:module';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import * as sass from 'sass';
import { installBootstrap } from '../vendor.mjs';

installBootstrap('.');
// The command-line program of the sass package (the same one `npx sass` runs).
const SASS = join(dirname(createRequire(import.meta.url).resolve('sass')), 'sass.js');

// 1. Every warning (verbose), sorted by type and by origin: your files, or files reached through a load path.
const table = {};
sass.compile('site.scss', {
  loadPaths: ['node_modules'],
  verbose: true,
  logger: {
    warn(_message, { deprecationType, span }) {
      const type = deprecationType?.id ?? 'other';
      const file = span?.url ? fileURLToPath(span.url) : '';
      const origin = file.includes('/node_modules/') ? 'dependency' : 'yours';
      table[type] ??= { yours: 0, dependency: 0 };
      table[type][origin]++;
    },
  },
});
console.log('type              yours  dependency');
for (const [type, n] of Object.entries(table).sort()) console.log(`${type.padEnd(16)} ${String(n.yours).padStart(6)} ${String(n.dependency).padStart(11)}`);

// 2. What the command line prints by default, and with --quiet-deps.
const cli = (...flags) => spawnSync(process.execPath, [SASS, '--load-path=node_modules', '--no-source-map', ...flags, 'site.scss', 'site.css'], { encoding: 'utf8' }).stderr;
const terse = cli();
const blocks = terse.split(/\n(?=DEPRECATION WARNING|WARNING:)/);
console.log(`\n$ sass --load-path=node_modules site.scss site.css\n${blocks.filter((b) => b.startsWith('DEPRECATION')).length} warnings printed, then:\n${blocks.find((b) => b.startsWith('WARNING:'))?.trim()}`);
console.log(`\nThe first one in full:\n${blocks[0].trim()}`);
const quiet = cli('--quiet-deps').split(/\n(?=DEPRECATION WARNING)/).filter((b) => b.startsWith('DEPRECATION'));
console.log(`\n$ sass --load-path=node_modules --quiet-deps site.scss site.css\n${quiet.length} warnings printed:`);
for (const b of quiet) console.log(`  ${b.split('\n')[0]}\n    at ${b.trim().split('\n').at(-1).trim()}`);

type              yours  dependency
color-functions       0           6
global-builtin        1         156
if-function           0          83
import                1          87
slash-div             1           0

$ sass --load-path=node_modules site.scss site.css
21 warnings printed, then:
WARNING: 314 repetitive deprecation warnings omitted.
Run in verbose mode to see all warnings.

The first one in full:
DEPRECATION WARNING [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

  ╷
5 │ @import "bootstrap/scss/bootstrap";
  │         ^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
    site.scss 5:9  root stylesheet

$ sass --load-path=node_modules --quiet-deps site.scss site.css
3 warnings printed:
  DEPRECATION WARNING [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.
    at site.scss 5:9  root stylesheet
  DEPRECATION WARNING [global-builtin]: Global built-in functions are deprecated and will be removed in Dart Sass 3.0.0.
    at site.scss 8:14  root stylesheet
  DEPRECATION WARNING [slash-div]: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.
    at site.scss 10:18  root stylesheet

// Migrates the legacy project to the module system with sass-migrator, one migration at a time, and proves after
// each step that the CSS has not changed. Run it in this folder after `npm install`: node migrate.mjs
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { cpSync, readFileSync, readdirSync, rmSync } from 'node:fs';
import { createRequire } from 'node:module';
import * as sass from 'sass';

const MIGRATOR = createRequire(import.meta.url).resolve('sass-migrator/sass-migrator.js');

// Work on a copy, so legacy/ keeps the original files to compare with.
rmSync('project', { recursive: true, force: true });
cpSync('legacy', 'project', { recursive: true });

/** Compiles the project and counts its deprecation warnings by type. */
function compile() {
  const warnings = {};
  const { css } = sass.compile('project/style.scss', {
    verbose: true,
    logger: { warn: (_message, { deprecationType }) => { const id = deprecationType?.id ?? 'other'; warnings[id] = (warnings[id] ?? 0) + 1; } },
  });
  const total = Object.values(warnings).reduce((a, b) => a + b, 0);
  const types = Object.entries(warnings).map(([id, n]) => `${id} ${n}`).join(', ');
  return { css, summary: `${total} deprecation warnings${total ? ` (${types})` : ''}` };
}

/** The changed lines of two versions of a file, with one line of context (a small LCS diff). */
function diff(before, after) {
  const a = before.split('\n');
  const b = after.split('\n');
  const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
  for (let i = a.length - 1; i >= 0; i--) for (let j = b.length - 1; j >= 0; j--) lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
  const lines = [];
  let i = 0;
  let j = 0;
  while (i < a.length && j < b.length) {
    if (a[i] === b[j]) {
      lines.push([' ', a[i++]]);
      j++;
    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) lines.push(['-', a[i++]]);
    else lines.push(['+', b[j++]]);
  }
  while (i < a.length) lines.push(['-', a[i++]]);
  while (j < b.length) lines.push(['+', b[j++]]);
  const changed = (k) => lines[k] !== undefined && lines[k][0] !== ' ';
  const kept = lines.map((l, k) => k).filter((k) => changed(k) || changed(k - 1) || changed(k + 1));
  return kept.map((k, n) => `${n && k > kept[n - 1] + 1 ? '  …\n' : ''}${lines[k][0]} ${lines[k][1]}`.trimEnd()).join('\n');
}

const files = () => readdirSync('project').filter((f) => f.endsWith('.scss')).sort();
const snapshot = () => Object.fromEntries(files().map((f) => [f, readFileSync(`project/${f}`, 'utf8')]));
const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);

const baseline = compile();
console.log(`Before: ${baseline.summary}; CSS ${baseline.css.length} bytes, sha256 ${sha(baseline.css)}`);

for (const migration of ['module', 'division', 'color', 'if-function']) {
  const before = snapshot();
  const run = spawnSync(process.execPath, [MIGRATOR, migration, '--migrate-deps', 'style.scss'], { cwd: 'project', encoding: 'utf8' });
  console.log(`\n$ sass-migrator ${migration} --migrate-deps style.scss  (exit ${run.status})`);
  const said = `${run.stdout}${run.stderr}`.trim();
  if (said) console.log(said);
  for (const [file, text] of Object.entries(snapshot())) {
    if (text !== before[file]) console.log(`--- ${file}\n${diff(before[file], text)}`);
  }
  const now = compile();
  console.log(`After ${migration}: ${now.summary}; CSS ${now.css === baseline.css ? 'byte-identical' : 'CHANGED'} (sha256 ${sha(now.css)})`);
}

Before: 11 deprecation warnings (import 3, slash-div 2, global-builtin 4, color-functions 2); CSS 374 bytes, sha256 30144ee30bbc

$ sass-migrator module --migrate-deps style.scss  (exit 0)
--- _button.scss
+ @use "sass:color";
+ @use "sass:map";
+ @use "sass:math";
+ @use "helpers";
+ @use "tokens";
+
  // The button component.
  …
    display: inline-block;
-   padding: half($gap) $gap;
-   border-radius: $radius;
-   background: $brand;
+   padding: helpers.half(tokens.$gap) tokens.$gap;
+   border-radius: tokens.$radius;
+   background: tokens.$brand;
    color: white;
-   font-size: map-get($sizes, md);
+   font-size: map.get(tokens.$sizes, md);

    &:hover {
-     background: darken($brand, 8%);
+     background: color.adjust(tokens.$brand, $lightness: -8%);
    }
  …
    &:focus-visible {
-     @include focus-ring($brand);
+     @include helpers.focus-ring(tokens.$brand);
    }
  …
    &--wide {
-     width: percentage(1/3);
+     width: math.percentage(1/3);
    }
--- _helpers.scss
+ @use "sass:color";
  // Helpers used by every component.
  …
  @mixin focus-ring($color) {
-   outline: 2px solid lighten($color, 20%);
+   outline: 2px solid color.adjust($color, $lightness: 20%);
    outline-offset: 2px;
--- style.scss
  // The site's entry point.
- $brand: #0f766e;

- @import "tokens";
- @import "helpers";
- @import "button";
+ @use "tokens" with ($brand: #0f766e);
+ @use "helpers";
+ @use "button";

After module: 2 deprecation warnings (slash-div 2); CSS byte-identical (sha256 30144ee30bbc)

$ sass-migrator division --migrate-deps style.scss  (exit 0)
--- _button.scss
    &--wide {
-     width: math.percentage(1/3);
+     width: math.percentage(math.div(1, 3));
    }
--- _helpers.scss
  @function half($value) {
-   @return $value / 2;
+   @return $value * 0.5;
  }
After division: 0 deprecation warnings; CSS byte-identical (sha256 30144ee30bbc)

$ sass-migrator color --migrate-deps style.scss  (exit 0)
Nothing to migrate!
After color: 0 deprecation warnings; CSS byte-identical (sha256 30144ee30bbc)

$ sass-migrator if-function --migrate-deps style.scss  (exit 0)
Nothing to migrate!
After if-function: 0 deprecation warnings; CSS byte-identical (sha256 30144ee30bbc)

// Two nested @imports, what sass-migrator makes of them, and the mixin that fixes the one it breaks.
// Run it in this folder after `npm install` in the examples folder: node nested.mjs
import { spawnSync } from 'node:child_process';
import { copyFileSync, readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import * as sass from 'sass';

const MIGRATOR = createRequire(import.meta.url).resolve('sass-migrator/sass-migrator.js');
const compile = (file) => {
  try {
    return sass.compile(file, { logger: sass.Logger.silent }).css;
  } catch (error) {
    return `Error: ${error.message.split('\n')[0]}\n${error.message.trim().split('\n').at(-1).trim()}`;
  }
};

for (const name of ['sidebar', 'card']) {
  const before = compile(`${name}.scss`);
  copyFileSync(`${name}.scss`, `${name}-migrated.scss`);
  spawnSync(process.execPath, [MIGRATOR, 'module', `${name}-migrated.scss`], { encoding: 'utf8' });
  console.log(`=== ${name}.scss with @import:\n${before}\n`);
  console.log(`--- after sass-migrator module:\n${readFileSync(`${name}-migrated.scss`, 'utf8').trim()}\n`);
  console.log(`--- which compiles to:\n${compile(`${name}-migrated.scss`)}\n`);
}
console.log(`=== card-mixin.scss:\n${compile('card-mixin.scss')}`);

=== sidebar.scss with @import:
.sidebar .title {
  font-weight: 600;
}
.sidebar .body {
  margin: 0;
}

--- after sass-migrator module:
@use "sass:meta";
.sidebar {
  @include meta.load-css("widget");
}

--- which compiles to:
.sidebar .title {
  font-weight: 600;
}
.sidebar .body {
  margin: 0;
}

=== card.scss with @import:
.card__title {
  font-weight: 600;
}
.card__body {
  margin: 0;
}

--- after sass-migrator module:
@use "sass:meta";
.card {
  @include meta.load-css("card-parts");
}

--- which compiles to:
Error: A top-level selector may not contain a parent selector with a suffix.
card-migrated.scss 3:3  root stylesheet

=== card-mixin.scss:
.card__title {
  font-weight: 600;
}
.card__body {
  margin: 0;
}

// An @extend across files before and after the module migration, and the one-line fix.
// Run it in this folder after `npm install` in the examples folder: node extend.mjs
import { spawnSync } from 'node:child_process';
import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import * as sass from 'sass';

const MIGRATOR = createRequire(import.meta.url).resolve('sass-migrator/sass-migrator.js');
const compile = (file) => {
  try {
    return sass.compile(file, { logger: sass.Logger.silent }).css;
  } catch (error) {
    return `Error: ${error.message.split('\n').slice(0, 2).join('\n')}`;
  }
};

// Work on a copy, so the files above stay as they are.
rmSync('project', { recursive: true, force: true });
mkdirSync('project');
for (const file of ['main.scss', '_base.scss', '_link.scss']) copyFileSync(file, `project/${file}`);
const before = compile('project/main.scss');
console.log(`=== With @import:\n${before}\n`);

spawnSync(process.execPath, [MIGRATOR, 'module', '--migrate-deps', 'main.scss'], { cwd: 'project' });
console.log(`=== After sass-migrator module, main.scss:\n${readFileSync('project/main.scss', 'utf8').trim()}\n`);
console.log(`=== Compiled:\n${compile('project/main.scss')}\n`);

// The fix: the extending module loads the module that defines the selector it extends.
writeFileSync('project/_link.scss', `@use "base";\n\n${readFileSync('project/_link.scss', 'utf8')}`);
const fixed = compile('project/main.scss');
console.log(`=== With @use "base"; added to _link.scss:\n${fixed}\n\nSame CSS as with @import: ${fixed === before ? 'yes' : 'no'}`);

=== With @import:
.btn, .link-button {
  padding: 4px 12px;
}

.link-button {
  color: #1d4ed8;
}

=== After sass-migrator module, main.scss:
@use "base";
@use "link";

=== Compiled:
Error: The target selector was not found.
Use "@extend .btn !optional" to avoid this error.

=== With @use "base"; added to _link.scss:
.btn, .link-button {
  padding: 4px 12px;
}

.link-button {
  color: #1d4ed8;
}

Same CSS as with @import: yes

// Tries sass-migrator on a site that @imports Bootstrap 5.3.8, then compares the hand-migrated version with it.
// Run it in this folder after `npm install` in the examples folder: node bootstrap.mjs
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { copyFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import * as sass from 'sass';
import { installBootstrap } from '../vendor.mjs';

installBootstrap('.');
const MIGRATOR = createRequire(import.meta.url).resolve('sass-migrator/sass-migrator.js');

copyFileSync('site.scss', 'site-migrated.scss');
const run = spawnSync(process.execPath, [MIGRATOR, 'module', '--migrate-deps', '--load-path=node_modules', 'site-migrated.scss'], { encoding: 'utf8' });
console.log(`$ sass-migrator module --migrate-deps --load-path=node_modules site-migrated.scss  (exit ${run.status})\n${`${run.stdout}${run.stderr}`.trim()}\n`);

function compile(file, options) {
  let warnings = 0;
  const { css } = sass.compile(file, { verbose: true, logger: { warn: () => warnings++ }, ...options });
  const sha = createHash('sha256').update(css).digest('hex').slice(0, 12);
  console.log(`${file.padEnd(14)} ${String(warnings).padStart(3)} warnings, ${css.length.toLocaleString('en')} bytes, sha256 ${sha}`);
  return css;
}
const before = compile('site.scss', { loadPaths: ['node_modules'] });
const after = compile('site-use.scss', { importers: [new sass.NodePackageImporter()], quietDeps: true });
console.log(`The two compiled stylesheets are ${before === after ? 'byte-identical' : 'different'}.`);

$ sass-migrator module --migrate-deps --load-path=node_modules site-migrated.scss  (exit 1)
Error: The migrator wants to rename a member in node_modules/bootstrap/scss/_functions.scss, but it is not being migrated. You should re-run the migrator with --migrate-deps or with node_modules/bootstrap/scss/_functions.scss as one of your entrypoints.
Migration failed!

site.scss      333 warnings, 278,478 bytes, sha256 785a37c9a021
site-use.scss    0 warnings, 278,478 bytes, sha256 785a37c9a021
The two compiled stylesheets are byte-identical.

// The CI step: compile with every migrated deprecation fatal for your own files, and Bootstrap's warnings quiet.
// Run it in this folder after `npm install` in the examples folder: node ci.mjs
import { spawnSync } from 'node:child_process';
import { statSync } from 'node:fs';
import { createRequire } from 'node:module';
import { dirname, join } from 'node:path';
import { installBootstrap } from '../vendor.mjs';

installBootstrap('.');
const SASS = join(dirname(createRequire(import.meta.url).resolve('sass')), 'sass.js');
const FLAGS = ['--pkg-importer=node', '--quiet-deps', '--fatal-deprecation=import,global-builtin,slash-div,color-functions,if-function', '--no-error-css', '--no-source-map'];

for (const file of ['app.scss', 'app-fixed.scss']) {
  const out = file.replace('.scss', '.css');
  const run = spawnSync(process.execPath, [SASS, ...FLAGS, file, out], { encoding: 'utf8' });
  console.log(`$ sass ${FLAGS.join(' ')} ${file} ${out}`);
  if (run.stderr.trim()) console.log(run.stderr.trim());
  let size = 'not written';
  try {
    size = `${statSync(out).size.toLocaleString('en')} bytes`;
  } catch {}
  console.log(`exit status ${run.status}; ${out}: ${size}\n`);
}

$ sass --pkg-importer=node --quiet-deps --fatal-deprecation=import,global-builtin,slash-div,color-functions,if-function --no-error-css --no-source-map app.scss app.css
Error: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

This is only an error because you've set the import deprecation to be fatal.
Remove this setting if you need to keep using this feature.
  ╷
3 │ @import "banner";
  │         ^^^^^^^^
  ╵
  app.scss 3:9  root stylesheet
exit status 65; app.css: not written

$ sass --pkg-importer=node --quiet-deps --fatal-deprecation=import,global-builtin,slash-div,color-functions,if-function --no-error-css --no-source-map app-fixed.scss app-fixed.css
exit status 0; app-fixed.css: 276,989 bytes

// Sample tests for the exercise: the CI settings, the CSS against the original, and what is left to migrate.
// Run it in this folder after `npm install` in the examples folder: node check.mjs
import { createHash } from 'node:crypto';
import { readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import * as sass from 'sass';

// What src/main.scss compiled to before the migration (Dart Sass 1.105.1).
const ORIGINAL = `.button {
  padding: 0.625rem 1.5rem;
  border-radius: 4px;
  background: #0f766e;
  color: white;
}
.button:hover {
  background: rgb(3.6267138434%, 28.5301489017%, 26.5959015185%);
}

.card {
  padding: 12px;
  border: 1px solid rgb(30.9361639393%, 91.2206988058%, 86.5384048356%);
}
.card__title {
  font-size: 1.25rem;
}
.card__media {
  border-radius: 4px 4px 0 0;
}
@media (min-width: 768px) {
  .card {
    flex: 0 0 50%;
  }
}`;
const VENDOR_SHA256 = 'f6874f7bf0b6cfe1865728c21e96d9962ef999d1def6658cdee50546d11f2e60';
const FATAL = ['import', 'global-builtin', 'slash-div', 'color-functions'];

const files = (dir) => readdirSync(dir, { recursive: true }).filter((f) => f.endsWith('.scss')).map((f) => join(dir, f));

let ci = null;
let ciError = null;
try {
  ci = sass.compile('src/main.scss', { loadPaths: ['vendor'], quietDeps: true, fatalDeprecations: FATAL, logger: sass.Logger.silent }).css;
} catch (error) {
  ciError = error.message.split('\n')[0];
}

let own = 0;
try {
  sass.compile('src/main.scss', {
    loadPaths: ['vendor'],
    verbose: true,
    logger: { warn: (_m, { span }) => { if (span?.url && !fileURLToPath(span.url).includes(`${join('/', 'vendor', '/')}`)) own++; } },
  });
} catch {
  own = NaN;
}
const imports = files('src').filter((f) => /^\s*@import\b/m.test(readFileSync(f, 'utf8')));
const vendor = createHash('sha256').update(readFileSync('vendor/grid/_index.scss')).digest('hex');

const tests = [
  ['src/main.scss compiles with the CI settings', ci !== null, ciError],
  ['the CSS is byte-identical to the original', ci === ORIGINAL, ci === null ? 'nothing to compare' : 'the CSS differs'],
  ['no deprecation warnings from src/', own === 0, Number.isNaN(own) ? 'it does not compile' : `${own} warnings`],
  ['no @import rules left in src/', imports.length === 0, `still in ${imports.join(', ')}`],
  ['vendor/ is unchanged', vendor === VENDOR_SHA256, 'vendor/grid/_index.scss was edited'],
];

let failed = 0;
for (const [name, ok, why] of tests) {
  if (!ok) failed++;
  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : ` (${why})`}`);
}
console.log(`\n${tests.length - failed} of ${tests.length} tests pass`);
process.exitCode = failed ? 1 : 0;

FAIL  src/main.scss compiles with the CI settings (Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.)
FAIL  the CSS is byte-identical to the original (nothing to compare)
FAIL  no deprecation warnings from src/ (14 warnings)
FAIL  no @import rules left in src/ (still in src/main.scss, src/components/_card.scss)
PASS  vendor/ is unchanged

1 of 5 tests pass