npm package: @financial-times/ft-sass-to-css
Description: A CLI tool that reports on usage of Origami Sass functions, mixins and variables.
Author: origami.support@ft.com
Latest version: 0.4.9

# ft-sass-to-css

A CLI tool that reports on usage of Origami Sass functions, mixins and variables and provides a set of codemods to convert to o3 web tokens.

## Installation

```
npm i -g @financial-times/ft-sass-to-css
```

## Usage

### Report

The report function can be used to view a breakdown of the component usage for a given path, broken down into mixins, functions and variables.

```bash
ft-sass-to-css report --path="./path/to/sass/**/*"
```

Example output:

```
Origami Sass Report:
┌────────────────────────┬────────┬───────────┬───────────┬───────┐
│        (index)         │ Mixins │ Functions │ Variables │ Total │
├────────────────────────┼────────┼───────────┼───────────┼───────┤
│        o-colors        │   5    │    20     │     1     │  26   │
│ o-editorial-typography │   5    │     0     │     0     │   5   │
│        o-fonts         │   0    │     1     │     0     │   1   │
│          ---           │        │           │           │       │
│         Total          │  10    │    21     │     1     │  32   │
└────────────────────────┴────────┴───────────┴───────────┴───────┘
```

The --path uses a [glob pattern](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/) to capture scss files. Here's a few examples of the most common patterns:

```bash
ft-sass-to-css report --path="./**/*" # all scss files within active directory

ft-sass-to-css report --path="src/*" # all scss files within the src directory ONLY

ft-sass-to-css report --path="src/components/styles.scss" # single file
```

### CSV

Like above, but more indepth, the CSV function runs a dryRun "modifying" all sass files with a given path and outputs all successes, warnings and errors into a CSV file. You might find this useful for using it to go through and use to do the migration manually.

![image](./demo/csv-screenshot.png)

```bash
ft-sass-to-css csv --path="src/*" --brand="core" --fileName="migration-report" # Checks scss against core branding and outputs a report file named "migration-report.csv"

ft-sass-to-css csv --path="src/*" --brand="core" --fileName="migration-report" --typeFilter="warning" # same as above but filter display only certain types warning, error or successs
```

### Dryrun

The `dryrun` command will attempt to perform the available codemods against a given path and return the modified file's content to the console. It **will not** modify any files. To learn about which components are currently supported view the [Support](#support) section below.

```bash
ft-sass-to-css dryrun --path="src/*" --component="component-name" --brand="brand-name"
```

You may get a lot of content back from this command, as it'll return the entire Sass file's contents. It might be easier to pipe the output from the command to a text file to validate the changes.

```bash
ft-sass-to-css dryrun --path="src/*" --component="component-name" --brand="brand-name" > output.txt
```

> [!IMPORTANT]
> Supported Brands: `core`, `internal`, `professional`, `whitelabel`.

### Modify

**We recommend running the `dryrun` command before this step.**

The `modify` command will perform the available codemods and overwrite your Sass files with the updated values. To learn about which components are currently supported view the [Support](#support) section below.

```bash
ft-sass-to-css modify --path="./**/*" --component="component-name" --brand="brand-name"
```

> [!IMPORTANT]
> Supported Brands: `core`, `internal`, `professional`, `whitelabel`.

Once the process is complete you'll see an output in the console breaking down how many files were modified.

### Help

You can learn more about the usage commands by using the following help command

```bash
ft-sass-to-css help
```

### Support

Please refer to the list below to see which components and their respective functions, mixins and variables are currently supported by the `dryrun` and `modify` commands. We're continually working on adding more components.

#### o-colors

Functions:

- `oColorsByName()`
- `oColorsByUseCase()`
- `oColorsMix()`
  - There is only some (~20%) support for oColorsMix. You may be mixing a color that doesn't exist as a new Origami variable token. Please refer to the [o-colors Migration Guide](https://github.com/Financial-Times/origami/blob/main/components/o-colors/MIGRATION.md#migrating-from-v6-to-o3-foundation) for more info.

#### o-spacing

Funtions:

- `oSpacingByName()`
- `oSpacingByIncrement()`\*

#### o-typography

Mixins:

- `oTypographySans()`
- `oTypographySerif()`
- `oTypographyDisplay()`

Functions:

- `oTypographyMaxLineWidth()`\*

\* These codemods replace the function with its compiled output, as they have no direct equivalent in o3-foundation.

## Local Development

### Installation and configuration

```bash
git clone git@github.com:Financial-Times/ft-sass-to-css.git
cd ft-sass-to-css
npm install
npm link
```

### Execution

You can run the report, dryrun and modify CLI commands against the files within the `demo` directory with the following shortcuts:

```bash
npm run report-demo
npm run dryrun-demo
npm run modify-demo
```

### Testing

The following command runs Jest and tests core functionality:

```
npm run test
```

These tests are executed as part of the CircleCI process; it will not deploy with failing tests.

### Coding Standards

We drive secure maintainable code through the use of ESlint and Snyk via regular execution of the following commands:

```
npm run lint             # View linting errors
npm run lint:fix         # Attempt to fix linting errors automatically
```

### Deploying the Application

You can release a new version to NPM by creating a Github release following semantic version numbering, preceeded by a `v`, e.g `v0.0.1`