@zthun/janitor-lint 19.5.0 → 19.5.1

package/README.md

@@ -1,411 +1,203 @@
 # Janitor Lint
 
-Code gets messy. You will find that most places you work at will always have a
-big long list of tech debt tasks that need to be taken care of and this becomes
-a maintenance nightmare as it becomes very expensive to fix. Companies rarely
-want to let developers fix these issues because they tend to only look at the
-short term ROI, which isn't high for this kind of task. What then happens is
-that more functional, but messy, code gets introduced and the software begins to
-rot.
-
-One way to fix something like this is to start with linters. Linters will scour
-through your code base and notify you that you have various issues. In a good
-development pipeline, they will prevent developers from generating a messy room
-and will force them to write clean consistent code with the rest of the
-development team. They aren't a silver bullet, and messy solutions can still
-crop up, but linters take care of most of the inconsistent and formatting errors
-that can develop in a code base. Good developers love them - it keeps the entire
-team consistent in their code structure.
-
-Of course, linters are not without their issues as well. There's an outrageous
-amount of them out there and you have to be well versed in each one of them in
-order to set each one of them up and run them in your pipeline to verify all of
-the different code files you have. There's linters for code, applications,
-spelling, and formatting; it's easy to get overwhelmed.
-
-**Janitor Lint** was created under the guise that there is beauty in simplicity.
-Having a single application that takes care of ones needs leads to greater
-happiness then having to piece meal together tons of tools, each with individual
-needs and maintainability issues. Just let **Janitor Lint** do the heavy lifting
-for you.
-
-## Getting Started
+Code gets messy. Most places you work will have a long backlog of tech-debt tasks
+that never quite get addressed, and over time this becomes a maintenance nightmare.
+Fixing old problems is expensive, and companies tend to focus on short-term ROI —
+which means these issues often stay unresolved. New features get built on top of
+messy foundations, and the software slowly begins to rot.
+
+A common way to fight this is to start with linters. Linters scan your codebase
+and notify you of issues. In a healthy development pipeline, they prevent developers
+from creating a metaphorical messy room and encourage clean, consistent code across
+the team. They’re not a silver bullet — messy solutions can still appear — but
+linters eliminate most inconsistent patterns and formatting errors. Good developers
+love them because they keep everyone aligned.
+
+However, linters come with their own problems. There are so many of them. Each
+has its own configuration style, quirks, and ecosystem. To cover your full
+codebase, you often need multiple tools: ones for code quality, formatting, spelling,
+applications, and more. It’s easy to feel overwhelmed, and maintaining a stack of
+linters becomes its own form of tech debt.
+
+Janitor Lint was created with the belief that there is beauty in simplicity. A
+single tool that handles your linting needs is far better than stitching together
+a pile of utilities, each with its own configuration and upkeep. Let Janitor
+Lint take on the heavy lifting so you can keep your codebase clean — and your
+developers happy.
+
+## Install
 
 ```sh
-# NPM
-npm install @zthun/janitor-lint --save-dev
-# Yarn
-yarn add @zthun/janitor-lint --dev
+yarn add -D @zthun/janitor-lint
+# Optionally pull in the shared rules
+yarn add -D @zthun/janitor-lint-config
 ```
 
-## Configuration
-
-Janitor Lint uses an opt-in approach to linting, meaning that it will not lint
-any files that you do not tell it to lint. You will need to add a configuration
-file that describes the list of files to lint and the sub configurations of each
-internal linter. Each linter is described in further detail. In the end, the
-expectation is that you will provide you're own collection of shared
-configurations that you can reuse in all your projects.
+## CLI
 
-Janitor Lint uses the [cosmiconfig](https://www.npmjs.com/package/cosmiconfig)
-standard for loading its configuration. In short, it will search the current
-working directory for the following files:
+```sh
+janitor-lint
+```
 
-1. A property in your package.json named **janitor-lint**.
-1. A json file or yaml file named **janitor-lintrc**.
-1. A json file named **janitor-lintrc.json**.
-1. A yaml file named **janitor-lintrc.yaml** or **janitor-lintrc.yml**.
-1. A javascript file named **janitor-lintrc.js**, **janitor-lint.config.js**.
+- `--config` is optional. Without it, the CLI searches for a `janitor`
+  config using cosmiconfig (in order: `package.json#janitor`, `janitorrc`,
+  `janitorrc.json`, `janitorrc.yaml|yml`, `janitorrc.mjs`).
+- Exit code is `0` when every enabled linter passes and `1` when any fail.
 
-> It is highly recommended to use a config.js convention for these types of
-> configurations. The main reason is that config.js offers the most flexible way
-> to configure an application and also naturally allows you to use the module
-> syntax to import other configurations.
+## Configuration shape
 
-The configuration file uses the following schema.
+Janitor Lint reads a `janitor` options config object with a `lint` section. Every
+field is optional—only the linters you configure will run. You can configure this
+manually, OR you can use the package, @zthun/janitor-options, to just build a
+configuration.
 
 ```ts
-{
-  // The configuration file or module for ECMAScript based linting.
+/**
+ * Represents options for linting in the zthunworks janitor system.
+ */
+export interface IZJanitorOptionsLint {
+  /**
+   * The path to the config file for eslint.
+   */
   esConfig?: string;
-  // The configuration file or module for CSS, Less, and Sass based linting.
-  styleConfig?: string;
-  // The configuration file or module for HTML linting.
+  /**
+   * The path to the config file for htmlhint.
+   */
   htmlConfig?: string;
-  // The configuration file or module for Markdown based linting
+  /**
+   * The path to the config file for markdownlint.
+   */
   markdownConfig?: string;
-  // The configuration file or module for Spelling checks
-  spellingConfig?: string;
-  // The configuration file or module for formatting checks
+  /**
+   * The path to the config file for prettier.
+   */
   prettyConfig?: string;
+  /**
+   * The path to the config file for cspell.
+   */
+  spellingConfig?: string;
+  /**
+   * The path to the config file for stylelint.
+   */
+  styleConfig?: string;
 
-  // The white list of ECMAScript globs to lint.  This should
-  // include JavaScript and TypeScript based files
-  // Note that eslint supports excludes directly in the
-  // config file so there is no exclude support for it here.
+  /**
+   * The file globs to lint with eslint.
+   */
   esFiles?: string[];
-  // The white list of CSS, Less, and Sass globs to lint.
-  // Note that stylelint supports excludes directly in
-  // the config file so there is no exclude support for it here.
-  styleFiles?: string[];
-  // The white list of HTML globs to lint.
+  /**
+   * The file globs to lint with htmlhint.
+   */
   htmlFiles?: string[];
-  // The black list of HTML globs to exclude from linting.
-  htmlFilesExclude?: string[];
-  // The white list of Markdown globs to lint.
-  markdownFiles?: string[];
-  // The black list of Markdown globs to exclude from linting.
-  markdownFilesExclude?: string[];
-  // The white list of JSON globs to lint.
+  /**
+   * The file globs to lint with json.
+   */
   jsonFiles?: string[];
-  // The black list of JSON globs to exclude from linting.
-  jsonFilesExclude?: string[];
-  // The white list of YAML globs to lint.
-  yamlFiles?: string[];
-  // The black list of YAML globs to exclude from linting.
-  yamlFilesExclude?: string[];
-  // The white list of globs to check for spelling errors.
-  spellingFiles?: string[];
-  // The black list of globs to exclude from spell checking.
-  spellingFilesExclude?: string[];
-  // The white list of globs to check for code formatting.
+  /**
+   * The file globs to lint with markdownlint.
+   */
+  markdownFiles?: string[];
+  /**
+   * The file globs to lint with prettier.
+   */
   prettyFiles?: string[];
-  // The black list of globs to exclude from code formatting.
-  prettyFilesExclude?: string[];
-}
-```
-
-The following is an example configuration that janitor-lint will read.
-
-```js
-// janitor-lint.config.js
-
-module.exports = {
-  // Configurations are generally optional and will load using the
-  // default rules of the application if not specified.  However, you
-  // can always override the configurations in this file.
-  esConfig: 'configs/.eslintrc',
-  // Using globs to find files
-  esFiles: ['packages/**/src/**/*.ts'],
-  // The configurations can also be shared configuration modules
-  // found in node_modules if you're not using IDE extensions.
-  styleConfig: '@zthun/janitor-stylelint-config';
-  // Globs are relative to the current working directory.
-  styleFiles: ['packages/**/src/**/*.less'],
-  // See notes on html below
-  htmlFiles: ['packages/**/src/**/*.html'],
-  // You can have as many globs as you want.
-  markdownFiles: ['packages/**/*.md', '*.md'],
-  // You can also exclude files from the include list.  These are normally
-  // used for code generated files and should not be linted.
-  markdownFilesExclude: ['**/CHANGELOG.md'],
-  // You can also specify specific files - json and yaml have no
-  // configurations as they are very specific formats.
-  jsonFiles: ['package.json'],
-  // Removes the linter
-  spellingFiles: null
-};
-```
-
-In your package json, add the following
+  /**
+   * The file globs to lint with cspell.
+   */
+  spellingFiles?: string[];
+  /**
+   * The file globs to lint with stylelint.
+   */
+  styleFiles?: string[];
+  /**
+   * The file globs to lint with yaml.
+   */
+  yamlFiles?: string[];
 
-```json
-{
-  "scripts": {
-    "lint": "janitor-lint"
-  }
+  /**
+   * The files globs to exclude from linting with htmlhint.
+   */
+  htmlFilesExclude?: string[];
+  /**
+   * The files globs to exclude from linting with json.
+   */
+  jsonFilesExclude?: string[];
+  /**
+   * The files globs to exclude from linting with markdownlint.
+   */
+  markdownFilesExclude?: string[];
+  /**
+   * The files globs to exclude from linting with prettier.
+   */
+  prettyFilesExclude?: string[];
+  /**
+   * The files globs to exclude from linting with cspell.
+   */
+  spellingFilesExclude?: string[];
+  /**
+   * The files to exclude from linting with stylelint.
+   */
+  styleFilesExclude?: string[];
+  /**
+   * The files globs to exclude from linting with yaml.
+   */
+  yamlFilesExclude?: string[];
 }
-```
-
-Now you can lint everything with a single command.
-
-```sh
-# NPM
-npm run lint
-# Yarn
-yarn lint
-# NPX
-npx janitor-lint
-```
-
-## Command Line
-
-You can always run janitor-lint on the command line using npx or if it is
-installed globally, which is not recommended. There are very few command line
-options, as janitor-lint intends to be fully driven by the config file.
-
-**janitor-lint** [options]
 
-```json
-[
-  {
-    "option": "--version",
-    "description": "Show version number",
-    "type": "boolean"
-  },
-  {
-    "option": "--config",
-    "alias": "-c",
-    "description": "Optional config file to use",
-    "type": "string"
-  },
-  {
-    "option": "--help",
-    "description": "Show help",
-    "type": "boolean"
-  }
-]
-```
-
-## Linters
-
-### Shared Configurations
-
-While you can always recreate individual configurations for each linter, it is
-**HIGHLY** recommended to create a set of shared configurations for your
-organization. Most linters supported by Janitor Lint have some form of support
-for extending configurations and sharing them so you don't need to reinvent the
-wheel. In the place that such extensions are missing, Janitor Lint attempts to
-bridge this gap but it will not add support for IDE based tooling and
-extensions. You'll have to decide what's best for your project and your
-organization.
-
-One note is that the housing repository for janitor-lint contains multiple
-shared configurations used by zthun scoped projects. You can use them, but it is
-recommended for your organization to create it's own set of configurations that
-meets its needs.
-
-### JSON and YAML
-
-JSON does not use an external tool. It's impossible to have lint errors in JSON
-as if there are, it wouldn't be valid JSON and you won't be able to parse it.
-Thus, when we talk about linting JSON, it's really just a parse check to make
-sure you're JSON is valid.
-
-For YAML, the same rule applies. It's just a parse check, but since YAML isn't
-supported in JavaScript out of the box, it uses
-[js-yaml](https://www.npmjs.com/package/js-yaml) under the hood to parse and
-check your files.
-
-Neither of these checks verify schemas so be warned about that.
-
-### ECMAScript
-
-The linter of choice for ECMAScript, is [ESLint](https://eslint.org/). ESLint
-has a very large eco system with support for shared configurations and plugins.
-It supports both TypeScript and JavaScript so it covers the entire feature
-spectrum. The configuration file for ESLint uses something similar to a
-[cosmiconfig](https://www.npmjs.com/package/cosmiconfig) standard but it's more
-restrictive.
-
-There is also a
-[VisualStudio Code plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
-that will give you highlighting for any linting errors while you type. This
-makes ESLint the go to linter for web based ECMAScript code.
-
-For the configuration schema, you can find it
-[at the eslint configuration guide](https://eslint.org/docs/user-guide/configuring/).
-If you create a shared configuration, as recommended, you can simply add that to
-the extends key in the ESLint configuration file to share configuration throughout
-your organization.
-
-```js
-// .eslintrc.js
-module.exports = require("@zthun/janitor-eslint-config");
-```
-
-### Styles (CSS, Less, SASS)
-
-There are several linters for style based files.
-
-1. [CSSLint](https://github.com/CSSLint/csslint)
-2. [SassLint](https://github.com/sasstools/sass-lint)
-3. [StyleLint](https://stylelint.io/)
-
-CSSLint and SassLint are no longer actively maintained. Thus, for linting style
-based files, Janitor Lint uses StyleLint under the hood.
-
-StyleLint is similar to [ESLint](https://eslint.org/). It too, has a nice
-ecosystem of plugins and it supports shared configurations.
-
-You can find the configuration schema [in the user guid for stylelint](https://stylelint.io/user-guide/configure)
-and you can use the extends key in the configuration to load a shared configuration.
-
-```jsonc
-// .stylelintrc.json
-{
-  "extends": ["@zthun/janitor-stylelint-config"],
+/**
+ * Options for the zthunworks janitor system.
+ */
+export interface IZJanitorOptions {
+  /**
+   * Linting options for janitor-lint.
+   */
+  lint?: IZJanitorOptionsLint;
 }
 ```
 
-### HTML
-
-There is not a lot of support for HTML linters, so we are using HTMLHint.
+The value of each `*Config` can be a local path or a shared module such as
+`@zthun/janitor-*-config`. HTMLHint and Markdownlint configs support `extends`
+via Janitor Lint even though the underlying tools have limited support.
 
-HTMLHint does NOT support shared configurations at all. To do that,
-[this issue](https://github.com/htmlhint/HTMLHint/issues/621) would need to be
-approved and supported. In the meantime, Janitor Lint bridges this gap by
-sending just the content to HTMLHint instead of the file list. This allows Lint
-Janitor to implement a [cosmiconfig](https://www.npmjs.com/package/cosmiconfig)
-standard for loading and extending the configuration to support shared configs.
-It will be up to you if you want to do this because the
-[VisualStudio Code plugin](https://marketplace.visualstudio.com/items?itemName=mkaufman.HTMLHint)
-does not support this and expects the standard json file to be at the root of
-your project.
+## Example config
 
-If you do choose to use a shared configuration, you can just use a
-htmlhint.config.js file at the root of your repository.
+The repo keeps its settings in `.config/janitorrc.mjs`:
 
 ```js
-//htmlhint.config.js
-module.exports = require("@zthun/janitor-htmlhint-config");
+// .config/janitorrc.mjs
+import {
+  ZJanitorOptionsBuilder,
+  ZJanitorOptionsLintBuilder,
+} from "@zthun/janitor-options";
+
+const lint = new ZJanitorOptionsLintBuilder()
+  // Conventional globs for this workspace
+  .commonEsFiles()
+  .commonCssFiles()
+  .commonLessFiles()
+  .commonSassFiles()
+  .commonHtmlFiles()
+  .commonMarkdownFiles()
+  .commonJsonFiles()
+  .commonYamlFiles()
+  // Reuse the same files for spell checks and format checks
+  .generateSpellingFiles()
+  .generatePrettyFiles()
+  // Ignore build artifacts and vendored content
+  .commonExcludes()
+  .build();
+
+export default new ZJanitorOptionsBuilder().lint(lint).build();
 ```
 
-### Markdown
-
-Good old markdown has a couple of linters available, but considering that
-[MarkdownLint](https://github.com/DavidAnson/markdownlint) has a working
-[VisualStudio Code plugin](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint),
-that's the one that Janitor Lint uses.
-
-There's not a lot of rules to markdown. You can find
-the list of rules [at the markdown lint github](https://github.com/DavidAnson/markdownlint).
-
-### Spelling
-
-This one is pretty optional, but it's useful in that it keeps you honest. With
-spelling, you won't use a shared configuration as this is truly unique across
-all projects. It is not possible to have a be all end all language that knows
-every word in existence so this will look for the
-[CSpell](https://www.npmjs.com/package/cspell) configuration at the root of the
-repository. If you combine this with the
-[VisualStudio Code plugin](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker),
-it's pretty powerful and lets you add words as the repository vocabulary grows.
-When using spelling here, you'll need to decide if there are words you want to
-support, what dictionaries your repository is going to support, and what are
-your forbidden words and phrases. There are no rules here, just lists of allowed
-words and dictionaries.
-
-You may want to consider having a shared dictionary for your organizations
-custom lingo. You can do this through the dictionaryDefinitions key, but you'll
-have to export a txt file for reuse.
-
-```json
-// cspell.json
-{
-  "version": "0.1",
-  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/master/cspell.schema.json",
-  "language": "en",
-  "words": ["errored"],
-  "dictionaries": ["typescript", "en_US"]
-}
-```
-
-### Formatting
-
-Finally, and possibly most importantly, is code formatting consistency. There
-are generally two tools that are used for this.
-
-1. [EditorConfig](https://editorconfig.org/)
-1. [Prettier](https://prettier.io/)
-
-For code formatting, Janitor Lint went with Prettier since it supports all the
-features of EditorConfig and a bunch of others. Prettier also supports shared
-configurations and is highly recommended to use them because the
-[VisualStudio Code plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
-has support to auto format your files when you save them, making sure that your
-teams formatting is completely consistent.
-
-It's file lookup is similar to that of ESLint, but we recommended using
-.prettierrc.js to enable support for shared configurations.
+Point to shared configs if you want opinionated defaults:
 
 ```js
-//.prettierrc.js
-module.exports = require("@zthun/janitor-prettier-config");
+const lint = new ZJanitorOptionsLintBuilder()
+  .esConfig("@zthun/janitor-eslint-config")
+  .styleConfig("@zthun/janitor-stylelint-config")
+  .htmlConfig("@zthun/janitor-htmlhint-config")
+  .markdownConfig("@zthun/janitor-markdownlint-config")
+  .prettyConfig("@zthun/janitor-prettier-config")
+  .build();
 ```
-
-Options are [located at the prettier documentation](https://prettier.io/docs/en/options.html),
-and there's not a lot of them. See [why](https://prettier.io/docs/en/option-philosophy.html),
-as there's a good reason for this.
-
-When doing formatting linting, only the formatting is checked and you are
-notified if the files are formatted or unformatted. The best way to prevent
-these issues all together is to just use the Prettier IDE extension and auto
-format as you type.
-
-### FAQ
-
-Q. Can this support my other favorite linter?
-
-A. Possibly, but whether or not Janitor Lint will bother at the moment depends
-on a few factors:
-
-1. Is there an IDE plugin that makes it so you can validate, lint, and cleanup
-   while you go along so you're not left with a lot of surprises at the end?
-1. Does the linter support shared configuration to not reinvent the wheel
-   everywhere? Does Janitor Lint have to bridge that gap?
-1. Is the linter in question a node linter that has its API exported and can be
-   integrated into a node application? **Important!**
-
-If you answered No to the last question, then the answer is No. Janitor Lint
-does not invoke external command lines of linters and instead calls into their
-node API directly. This is how Janitor Lint succeeds in not having you worry
-about what tools to install and what versions to use; it uses transitive
-dependencies.
-
-If the last question is a Yes, then it becomes a question of, is it worth it?
-That'll need to be prioritized. For the most part, using
-[Prettier](https://prettier.io/) takes care of almost all linting issues so you
-may not need more than what is available here. If you need the mother of all
-linters, there is the heavy
-[Mega Linter](https://github.com/nvuillam/mega-linter) which aggregates every
-linter in existence. Very cool, but a bit overkill for the solution we are
-trying to solve with Janitor Lint.
-
-Q. Is there an IDE plugin for Janitor Lint?
-
-A. Not yet. That would solve the issue of wanting an IDE plugin for each
-individual linter and would allow you to just have a single
-janitor-lint.config.js file at the root of your repository that would handle all
-linting needs. There is one planned, but it still need to be researched and
-scoped out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zthun/janitor-lint",
-  "version": "19.5.0",
+  "version": "19.5.1",
   "description": "Style checks with tools for web projects using common rules.",
   "keywords": [
     "linters"
@@ -33,7 +33,7 @@
   },
   "author": "Anthony Bonta",
   "dependencies": {
-    "@zthun/janitor-options": "^19.5.0",
+    "@zthun/janitor-options": "^19.5.1",
     "chalk": "^5.6.2",
     "cosmiconfig": "^9.0.0",
     "cspell": "^9.3.2",
@@ -51,11 +51,11 @@
     "dist"
   ],
   "devDependencies": {
-    "@zthun/janitor-build-config": "^19.5.0",
+    "@zthun/janitor-build-config": "^19.5.1",
     "typescript": "~5.9.3",
     "vite": "^7.2.2",
     "vitest": "^4.0.10",
     "vitest-mock-extended": "^3.1.0"
   },
-  "gitHead": "4fa19cda4d37c34db1b5aae9f4a958a247ce3f46"
+  "gitHead": "8b2a09566d2d71c762189c7e94dcb1b8500f1863"
 }