Skip to content

Commit

Permalink
docs: 📘 documenting README.md
Browse files Browse the repository at this point in the history
documenting README.md
  • Loading branch information
Tal Rofe committed Apr 22, 2022
1 parent 5bcffc0 commit 1bc3def
Show file tree
Hide file tree
Showing 9 changed files with 190 additions and 38 deletions.
154 changes: 153 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1 +1,153 @@
🚧 This package is in progress... 🚧
![Logo](assets/logo.png)

# Inflint

> Inflint is a tool which scans and verifies file name conventions.
Inflint allows you to easily set file names convention in your repository.

[![npm version](https://img.shields.io/npm/v/inflint.svg?style=flat-square)](https://www.npmjs.org/package/inflint)

[![npm downloads](https://img.shields.io/npm/dm/inflint.svg?style=flat-square)](http://npm-stat.com/charts.html?package=inflint)

## Demo

![inflint](assets/basic-demo.gif)

## Installation

**Globally**

```bash
npm install --global inflint
```

**Locally**

```bash
npm install --save-dev inflint
```

Add this to your `package.json`:

## Usage

```sh
$ inflint [options] [files]
```

## Configuration

You can specify the configuration of Inflint through various options.
Configuration can be set in the following files:

- a `package.json` property: `"inflint": {...}`
- a `.inflintrc` file in JSON or YAML format
- a `.inflintrc.json`, `.inflintrc.yaml`, `.inflintrc.yml`, `.inflintrc.js`, or `.inflintrc.cjs` file
- a `inflint.config.js` or `inflint.config.cjs` CommonJS module exporting an object

You can set a configuration file using our wizard:
```bash
npx inflint --init
```

### Rules format
When applying rules either via the CLI or other conifguration, you must follow the rules format.
`1` and `warn` are warnings rules, `2` and `error` are errors rules.
Each rule has key and value. The key represents the glob pattern. When a file matches the pattern, it will be enfocred by the rule.
They rule value represents the rule enforcement.
Rules enforcement format:
- Set rules of files-existence: `1 | 2 | 'warn' | 'error' | [1] | [2] | ['warn'] | ['error']`
**Example**: `{ 'src/**/*': 2 }` → Inflint will emit error if there are any files/folders inside `src` folder
- Set rules to match file names conventions: `[1, <convention>] | [2, <convention>] | ['warn', <convention>]| ['error', <convention>]`
**Example**: `{ 'src/**/*': [1, 'kebab-case'] }` &rarr; Inflint will emit error if there are any files/folder with "kebab-case" convention name inside `src` folder
- Set rules options: `[1, <convention>(optional), <options>] | [2, <convention>(optional), <options>] | ['warn', <convention>(optional), <options>] | ['error', <convention>(optional), <options>]`
**Example1**: `{ 'src/**/*': [1, { onlyFiles: true }] }` &rarr; Inflint will emit error if there are any files inside `src` folder (and ignores folders if there are)
**Example2**: `{ 'src/**/*': [1, 'point.case', { onlyFiles: true }] }` &rarr; Inflint will emit error if there are any files with "point-case" convention name inside `src` folder (and ignores folders if there are)

### File names conventions
You can set file names conventions rules using known ones. Inflint allows you to set the following:
| Convention | Alias | Description |
| :------------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------ |
| lowercase | `lowercase` | Every letter must be lowercase. Ignores non-letters |
| camelcase | `camelCase` | Must be in "camelCase" format. Only letters and digits are allowed |
| camelcase-point | `camelCase.point` | Must be in "camelCase" format. Only letters, digits and `.` are allowed |
| pascalcase | `PascalCase` | Must be in "PascalCase" format. Only letters and digits are allowed |
| pascalcase-point | `PascalCase.Point` | Must be in "PascalCase" format. Only letters, digits and `.` are allowed |
| snakecase | `snake_case` | Must be in "snake_case" format. Only lowercase letters, digits and `_` are allowed |
| snakecase-point | `snake_case.point` | Must be in "snake_case" format. Only lowercase letters, digits, `_` and `.` are allowed |
| screamingsnakecase | `SCREAMING_SNAKE_CASE` | Must be in "SCREAMING_SNAKE_CASE" format. Only uppercase letters, digits and `_` are allowed |
| screamingsnakecase-point | `SCREAMING_SNAKE_CASE.POINT` | Must be in "SCREAMING_SNAKE_CASE" format. Only uppercase letters, digits, `_` and `.` are allowed |
| kebabcase | `kebab-case` | Must be in "kebab-case" format. Only lowercase letters, digits and `-` are allowed |
| kebabcase-point | `kebab-case.point` | Must be in "kebab-case" format. Only lowercase letters, digits, `-` and `.` are allowed |
| pointcase | `point.case` | Must be in "point.case" format. Only lowercase letters, digits and `.` are allowed |

### CLI Rules
When adding rules via the CLI, you need to provide a valid JSON for the `--rule` argument. You can provide multiple rules.
The JSON should follow the rules format described above.
**Example**: `inflint --rule "{ \"src/**/*\": [1] }"`

### Aliases
You can use the readymade conventions, or you can add your own by applying aliases, via the CLI or other configuration.
To use the aliases, simply use the alias name as you would use readymade convention.
Aliases should be applied with the following format:
- `<alias_name>: <regex>` Inflint will apply the alias name to match the provided regex.
**Example**: Applying the alias `{ myAlias: '^.*$' }` and the rule `{ 'src/**/*': [2, 'myAlias'] }` &rarr; Inflint will match any file/folder in `src` directory and validates the provided regex matches it.
- `<alias_name>: [<regex>, <regex_flags>]` Inflint will apply the alias name to match the provided regex with given flags.
**Example**: `{ myAlias: ['^.*$', 'i'] }` &rarr; Any rule applied with `myAlias` alias will try to match file names by the provided regex and the `i` regex flag.

### CLI Aliases
When adding aliases via the CLI, you need to provide a valid JSON for the `--alias` argument. You can provide multiple aliases.
The JSON should follow the aliases format described above.
**Example**: `inflint --alias "{ \"myAlias\": \"^\\.\" }"`

> You can escape aliases regex with in the CLI if you prefix character with `\\`.
> `"^\\."` will match any string begins with dot (`.`)


| CLI | Configuration key | Type | default | Description |
| :---------------------- | :-------------------- | :---------------- | :--------------- | :----------------------------------------------------------------------------------------------------- |
| - | `extends` | String | - | A path to configuration file to extend configurations from |
| `--no-inflintrc` | - | Boolean | `false` | Whether Inflint ignores any configuration file |
| `-c`, `--config` | - | String | - | The path to a configuration file which will be used by Inflint |
| `--rule` | `rules` | Above | - | Inflint rules to use against files |
| `--alias` | `aliases` | Above | - | Inflint aliases to use together with rules |
| `--ignore-path` | `ignorePath` | String | `.inflintignore` | Ignore file path Inflint will use to ignore patterns |
| `--no-ignore` | `ignore` | Boolean | `false` | Disable use of ignore files and patterns |
| `--ignore-pattern` | `ignorePatterns` | String[] | `[]` | Patterns of files to ignore (in addition to those in .inflintignore) |
| `--quiet` | `quiet` | Boolean | `false` | Whether to report errors only |
| `--max-warnings` | `maxWarnings` | Number | `0` | Number of warnings to trigger non-zero exit code |
| `--bail` | `bail` | Boolean or Number | `0` | Number of failures (errors) to make Inflint to exit. Setting "bail" to true is the same as setting "1" |
| `-o`, `--output-file` | `outputFile` | String | - | Specify file to write report to |
| `--color`, `--no-color` | - | Boolean | `true` | Force enabling/disabling of color |
| `--init` | - | Boolean | `false` | Run configuration initialization wizard |
| `-h`, `--help` | - | Boolean | `false` | Show help |
| `-v`, `--version` | - | Boolean | `false` | Output the version number |
| `--env-info` | - | Boolean | `false` | Output the environment version |

## Examples

- [landing-page](https://github.com/Vinyl-Depository/landing-page)
- [landing-page](https://github.com/Vinyl-Depository/inflint)
- [cz-vinyl](https://github.com/Vinyl-Depository/cz-vinyl)

## Support

For support, email [email protected] or open an issue at [inflint issues](https://github.com/Vinyl-Depository/inflint/issues).

## Contributing

Contributions are always welcome!

See `CONTRIBUTING.md` for ways to get started.

Please adhere to this project's `CODE_OF_CONDUCT.md`.

## Authors

- [@tal-rofe](https://github.com/tal-rofe)

## License

[MIT](https://choosealicense.com/licenses/mit/)
24 changes: 12 additions & 12 deletions src/modules/app/functions/lint-files.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@ export const lintFiles = async (
if (!rules) {
CLILoggerModule.service.lintSummary(0, 0);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, [], []);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, [], []);
}

return 0;
Expand Down Expand Up @@ -106,8 +106,8 @@ export const lintFiles = async (
if (errors.length === configuration.bail) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

return 1;
Expand All @@ -126,8 +126,8 @@ export const lintFiles = async (
if (warnings.length === configuration.maxWarnings) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

return 1;
Expand Down Expand Up @@ -164,8 +164,8 @@ export const lintFiles = async (
if (errors.length === configuration.bail) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

return 1;
Expand Down Expand Up @@ -202,8 +202,8 @@ export const lintFiles = async (
if (warnings.length === configuration.maxWarnings) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

return 1;
Expand All @@ -214,8 +214,8 @@ export const lintFiles = async (

CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

return 0;
Expand Down
2 changes: 1 addition & 1 deletion src/modules/app/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ const Bootstrap = async () => {
if (lintingConfiguration.ignore === false) {
delete lintingConfiguration['ignorePatterns'];
} else {
const ignorePatternsFromFile = await readIgnoreFile(lintingConfiguration.ignoreFilePath);
const ignorePatternsFromFile = await readIgnoreFile(lintingConfiguration.ignorePath);

lintingConfiguration = mergeConfigurations(lintingConfiguration, {
ignorePatterns: ignorePatternsFromFile,
Expand Down
4 changes: 2 additions & 2 deletions src/modules/app/models/alias.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ export const DEFAULT_ALIASES = {
'camelCase': validateCamelCase,
'camelCase.point': validateCamelCasePoint,
'PascalCase': validatePascalCase,
'PascalCase.point': validatePascalCasePoint,
'PascalCase.Point': validatePascalCasePoint,
'snake_case': validateSnakeCase,
'snake_case.point': validateSnakeCasePoint,
'SCREAMING_SNAKE_CASE': validateScreamingSnakeCase,
'SCREAMING_SNAKE_CASE.point': validateScreamingSnakeCasePoint,
'SCREAMING_SNAKE_CASE.POINT': validateScreamingSnakeCasePoint,
'kebab-case': validateKebabCase,
'kebab-case.point': validateKebabCasePoint,
'point.case': validatePointCase,
Expand Down
4 changes: 2 additions & 2 deletions src/modules/app/validators/alias.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ export const validatePascalCase = (input: string) => {
};

/**
* The function validates a given input is in "PascalCase.point" format
* The function validates a given input is in "PascalCase.Point" format
* @param input the input to validate
* @returns a boolean flag indicates whether the input is valid
*/
Expand Down Expand Up @@ -75,7 +75,7 @@ export const validateScreamingSnakeCase = (input: string) => {
};

/**
* The function validates a given input is in "SCREAMING_SNAKE_CASE.point" format
* The function validates a given input is in "SCREAMING_SNAKE_CASE.POINT" format
* @param input the input to validate
* @returns a boolean flag indicates whether the input is valid
*/
Expand Down
4 changes: 2 additions & 2 deletions src/modules/cli/utils/cli-configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ export const getConfiguration = (argv: ParsedArgs) => {
),
rules: validateRules(argv['rule'], 'Must provide valid JSON syntax to "--rule"'),
aliases: validateAliases(argv['alias'], 'Must provide valid JSON syntax to "--alias"'),
ignoreFilePath: validateString(argv['ignore-path'], 'Must provide string value to "--ignore-path"'),
ignorePath: validateString(argv['ignore-path'], 'Must provide string value to "--ignore-path"'),
ignore: validateBoolean(argv['ignore'], 'Must provide boolean value to "--no-ignore"'),
ignorePatterns: validateSringsArrayOrString(
argv['ignore-pattern'],
Expand All @@ -30,7 +30,7 @@ export const getConfiguration = (argv: ParsedArgs) => {
'Must provide >= 0 safe integer value to "--max-warnings"',
),
bail: validateBail(argv['bail'], 'Must provide >=0 safe integer or boolean value to "--bail"'),
outputFilePath: validateString(
outputFile: validateString(
argv['o'] || argv['output-file'],
'Must provide string value to "-o, --output-file"',
),
Expand Down
8 changes: 4 additions & 4 deletions src/modules/configuration/validators/configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ export const validateConfiguration = (configuration: Record<string, unknown>) =>
extends: validateString(configuration['extends'], 'Must provide a string value "extends"'),
rules: validateRules(configuration['rules']),
aliases: validateAliases(configuration['aliases']),
ignoreFilePath: validateString(
configuration['ignoreFilePath'],
'Must provide a string value to "ignoreFilePath"',
ignorePath: validateString(
configuration['ignorePath'],
'Must provide a string value to "ignorePath"',
),
ignore: validateBoolean(configuration['ignore'], 'Must provide a boolean value to "ignore"'),
ignorePatterns: validateSringsArray(configuration['ignorePatterns']),
Expand All @@ -29,7 +29,7 @@ export const validateConfiguration = (configuration: Record<string, unknown>) =>
configuration['bail'],
'Must provide >=0 safe integer or boolean value to "--bail"',
),
outputFilePath: validateString(
outputFile: validateString(
configuration['outputFile'],
'Must provide a string value to "outputFile"',
),
Expand Down
24 changes: 12 additions & 12 deletions src/modules/core/functions/lint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ export const lint = async (
if (!rules) {
CLILoggerModule.service.lintSummary(0, 0);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, [], []);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, [], []);
}

process.exit(0);
Expand Down Expand Up @@ -76,8 +76,8 @@ export const lint = async (
if (errors.length === configuration.bail) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

process.exit(1);
Expand All @@ -100,8 +100,8 @@ export const lint = async (
if (warnings.length === configuration.maxWarnings) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

process.exit(1);
Expand Down Expand Up @@ -142,8 +142,8 @@ export const lint = async (
if (errors.length === configuration.bail) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

process.exit(1);
Expand Down Expand Up @@ -184,8 +184,8 @@ export const lint = async (
if (warnings.length === configuration.maxWarnings) {
CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}

process.exit(1);
Expand All @@ -196,7 +196,7 @@ export const lint = async (

CLILoggerModule.service.lintSummary(errors.length, warnings.length);

if (configuration.outputFilePath) {
await outputFile(configuration.outputFilePath, errors, warnings);
if (configuration.outputFile) {
await outputFile(configuration.outputFile, errors, warnings);
}
};
4 changes: 2 additions & 2 deletions src/shared/interfaces/configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ import { IRuleValue } from './rule';
export interface IBaseConfiguration {
readonly rules?: Record<string, IRuleValue>;
readonly aliases?: Record<string, IAliasValue>;
readonly ignoreFilePath?: string;
readonly ignorePath?: string;
readonly ignore?: boolean;
ignorePatterns?: string[];
readonly quiet?: boolean;
readonly maxWarnings?: number;
readonly bail?: number;
readonly outputFilePath?: string;
readonly outputFile?: string;
}

export interface ICLIConfiguration extends IBaseConfiguration {
Expand Down

0 comments on commit 1bc3def

Please sign in to comment.