@aquera/nile-lint 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +231 -2
- package/SETUP.md +71 -0
- package/bin/nile-lint.js +169 -0
- package/eslint/index.js +137 -0
- package/index.d.ts +120 -0
- package/index.js +159 -0
- package/lib/angular.js +138 -0
- package/lib/baseline.js +69 -0
- package/lib/color.js +232 -0
- package/lib/config.js +85 -0
- package/lib/css-rules.js +466 -0
- package/lib/engine.js +453 -0
- package/lib/format.js +132 -0
- package/lib/manifest.js +76 -0
- package/lib/markup-rules.js +475 -0
- package/lib/markup.js +141 -0
- package/lib/rules.js +159 -0
- package/lib/suggest.js +153 -0
- package/lib/version.js +84 -0
- package/manifest.json +32247 -0
- package/package.json +70 -4
- package/stylelint/cascade.js +4 -0
- package/stylelint/index.js +129 -0
- package/stylelint/recommended.js +4 -0
- package/stylelint/strict.js +4 -0
package/README.md
CHANGED
|
@@ -1,3 +1,232 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @aquera/nile-lint
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**An agent-first linter for the Nile design system.** It checks markup and styles against the
|
|
4
|
+
real Nile manifest — every `nile-*` tag, attribute, allowed value, event, `::part`, `--ng-*`
|
|
5
|
+
token, `ng-*` class and icon — and every message says exactly what to write instead, so a coding
|
|
6
|
+
agent (or a person) can fix it in one pass.
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
src/app/card.component.html:3:25 error valid-attribute-values variant="danger" is not valid on <nile-button>. Use one of: primary, secondary, tertiary, caution, ghost, destructive, secondary-grey, secondary-blue.
|
|
10
|
+
src/app/card.component.scss:4:10 error no-raw-colors Raw color #414651 in `color`. Use var(--ng-colors-text-secondary-700) (exact match). [auto-fixable]
|
|
11
|
+
src/app/card.component.html:7:15 error no-unknown-attributes <nile-input> has no attribute "helptext". Did you mean "help-text"? …
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Inspired by [`@shadcn/lint`](https://github.com/shadcn-ui/lint), rebuilt for how Nile actually
|
|
15
|
+
works: web components (not React props), `--ng-*` tokens (not Tailwind classes), and the
|
|
16
|
+
Cascade CSS-first track.
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
yarn add -D @aquera/nile-lint # or npm i -D @aquera/nile-lint
|
|
22
|
+
npx nile-lint src
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Coding agents: read [`SETUP.md`](./SETUP.md).
|
|
26
|
+
|
|
27
|
+
## What it lints
|
|
28
|
+
|
|
29
|
+
| File | What is checked |
|
|
30
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
31
|
+
| `.css` `.scss` `.less` | every CSS rule |
|
|
32
|
+
| `.html`, `*.component.html`, `.vue`, `.svelte` | markup rules, plus `<style>` blocks and `style=""` values as CSS |
|
|
33
|
+
| `.ts` `.js` `.tsx` `.jsx` | Lit `` html`…` `` / `` css`…` `` templates and Angular `@Component({ template, styles })` |
|
|
34
|
+
|
|
35
|
+
Framework binding syntax is understood: Angular `[prop]`, `[attr.x]`, `(event)`, `[(ngModel)]`,
|
|
36
|
+
`*ngIf`, `#ref`; Lit `.prop`, `?attr`, `@event`, `${…}` holes; Vue `:x`, `@x`, `v-*`. Anything
|
|
37
|
+
dynamic is skipped rather than guessed.
|
|
38
|
+
|
|
39
|
+
## Rules
|
|
40
|
+
|
|
41
|
+
| Rule | recommended | cascade | Fix | What it catches |
|
|
42
|
+
| ------------------------ | ----------- | ------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
43
|
+
| `no-unknown-elements` | error | error | | `<nile-buton>` — tags that don't exist |
|
|
44
|
+
| `no-unknown-attributes` | error | error | | attributes/properties a component doesn't declare — incl. the Lit trap `help-text` vs `helptext`, and `@state()` fields like `nile-button` `size` |
|
|
45
|
+
| `valid-attribute-values` | error | error | | `variant="danger"` (lists the real values); `disabled="false"` (which is still _on_) |
|
|
46
|
+
| `no-unknown-events` | warn | warn | | `(nile-clik)` — event names no Nile component emits |
|
|
47
|
+
| `no-unknown-icons` | error | error | | `nile-icon`/`nile-glyph` names and Cascade sprite `#ng-*` refs that render nothing |
|
|
48
|
+
| `no-unknown-classes` | error | error | | `ng-*` classes nobody defines (Angular's own `ng-touched` etc. are ignored) |
|
|
49
|
+
| `no-raw-colors` | error | error | ✓ | hex/rgb/hsl/named colors → nearest token of the right role (text/bg/border/fg) |
|
|
50
|
+
| `no-arbitrary-values` | warn | off | ✓ | raw px/rem in spacing, radius, font-size that **is** a token → `--ng-spacing-*`, `--ng-radius-*`, `--ng-font-size-*` (`strict` also flags near-misses) |
|
|
51
|
+
| `no-unknown-tokens` | error | error | ✓ | `var(--ng-typo)` that resolves to nothing; Cascade roles (`--ng-text`) used in apps |
|
|
52
|
+
| `no-legacy-tokens` | error | error | | `--nile-*` enterprise theme tokens (component-scoped `--nile-<component>-*` props are fine) |
|
|
53
|
+
| `no-legacy-theme` | error | error | ✓ | `nile-theme-enterprise`, loading `variables.css` |
|
|
54
|
+
| `no-restyle` | error | error | | restyling a `nile-*` host from outside, unknown `::part()`s, `!important`, `::ng-deep` |
|
|
55
|
+
| `gradient-budget` | warn | error | | gradients other than `--ng-grad-brand` / `--ng-grad-ai` |
|
|
56
|
+
| `no-inline-styles` | warn | off | | `style=""` and `<style>` inside app templates |
|
|
57
|
+
| `prefer-nile-component` | warn | off | | native `<button>`, `<select>`, `<table>`, `<input type=checkbox>`… |
|
|
58
|
+
| `prefer-stroke-icons` | warn | off | ✓ | icons without `method="stroke"` (Nile house style) |
|
|
59
|
+
| `no-external-resources` | off | error | | http(s) `src`/`href`/`url()`/`@import` — Cascade pages are self-contained |
|
|
60
|
+
|
|
61
|
+
`npx nile-lint --list-rules` prints this table from the code.
|
|
62
|
+
|
|
63
|
+
### Profiles
|
|
64
|
+
|
|
65
|
+
- **`recommended`** (default) — product apps on the Nile web components (Angular, Lit, HTML).
|
|
66
|
+
- **`cascade`** — Nile Cascade pages: CSS-first, `ng-*` classes, native elements, no network.
|
|
67
|
+
Matches the contract of `nile-cascade/scripts/ci-checks.py` (hex/named colors only, `#fff`
|
|
68
|
+
allowed, px chrome allowed) and adds the component/token/icon checks on top.
|
|
69
|
+
- **`strict`** — `recommended` with every enabled rule as an error.
|
|
70
|
+
|
|
71
|
+
## CLI
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
npx nile-lint [paths/globs…] [--profile recommended|cascade|strict] [--format pretty|agent|json]
|
|
75
|
+
[--fix] [--rule id=error|warn|off] [--max-warnings n] [--quiet] [--list-rules]
|
|
76
|
+
[-v | --version]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`--version` prints the linter's version and the Nile versions its manifest was built from. The
|
|
80
|
+
`pretty` output starts with the same line (`nile-lint 0.1.0 · Nile 2.0.20`), and the `agent` summary
|
|
81
|
+
line names them too. When the project's installed `@aquera/nile-elements` is newer than the
|
|
82
|
+
manifest, a warning goes to stderr: newer components and attributes would otherwise be reported
|
|
83
|
+
as unknown — update `@aquera/nile-lint`.
|
|
84
|
+
|
|
85
|
+
`--format agent` (the default when stdout isn't a TTY) prints one self-contained line per problem
|
|
86
|
+
and ends with the exact command to re-run. `--fix` applies only exact-match fixes (a raw color
|
|
87
|
+
that _is_ a token, a px value that _is_ a token, a role with a 1:1 token) — never a guess.
|
|
88
|
+
Exit code 1 on errors.
|
|
89
|
+
|
|
90
|
+
## Adopting it on an existing app (baseline)
|
|
91
|
+
|
|
92
|
+
A real Angular app has thousands of existing problems (adminui: ~18.5k, 84% auto-fixable). Don't
|
|
93
|
+
fix them all before turning the linter on:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
npx nile-lint src --fix # clear the exact-match ones first (safe, mechanical)
|
|
97
|
+
npx nile-lint src --update-baseline # record what's left in .nile-lint-baseline.json — commit it
|
|
98
|
+
npx nile-lint src # 0 problems; from now on only NEW problems are reported
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Problems are matched by file + rule + the message's first sentence, not by line, so editing a
|
|
102
|
+
file doesn't resurface its old problems. Re-run `--update-baseline` after fixing some to shrink
|
|
103
|
+
it. `--no-baseline` shows everything; `--baseline <file>` uses another file.
|
|
104
|
+
|
|
105
|
+
## Angular
|
|
106
|
+
|
|
107
|
+
- Templates are recognised by content, so `foo.html` (`templateUrl: './foo.html'`) is linted as
|
|
108
|
+
Angular, not only `*.component.html`.
|
|
109
|
+
- Bindings that aren't the component's are not reported: Angular animations (`[@fade]`),
|
|
110
|
+
router/forms/CDK/Material directive inputs (`routerLink`, `formControlName`, `cdkTrapFocus`,
|
|
111
|
+
`matTooltip`…), ARIA/DOM properties (`[ariaDisabled]`), **your project's own directives**
|
|
112
|
+
(read from its `@Directive` declarations: selectors, `@Input()`, `input()`, `inputs: []`,
|
|
113
|
+
aliases) and **directives from its Angular library dependencies** (read from their typings).
|
|
114
|
+
- Anything else on a `nile-*` element is reported — e.g. `size` on `<nile-button>` is internal
|
|
115
|
+
`@state()` and does nothing, and `[attr.ariaLabel]` sets a meaningless `arialabel` attribute
|
|
116
|
+
(use `aria-label`).
|
|
117
|
+
|
|
118
|
+
## Config
|
|
119
|
+
|
|
120
|
+
`nile-lint.config.json`, `.nile-lintrc.json`, `nile-lint.config.js`, or `"nileLint"` in
|
|
121
|
+
`package.json` (nearest one wins):
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"profile": "recommended",
|
|
126
|
+
"rules": {
|
|
127
|
+
"prefer-nile-component": "off",
|
|
128
|
+
"no-raw-colors": ["error", { "allow": ["#fff"] }],
|
|
129
|
+
"no-unknown-attributes": ["error", { "allow": ["appTooltip"] }]
|
|
130
|
+
},
|
|
131
|
+
"ignore": ["src/legacy/**"],
|
|
132
|
+
"overrides": [{ "files": ["prototypes/**/*.html"], "profile": "cascade" }]
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Inline: `/* nile-lint-disable-next-line no-raw-colors */`, `<!-- nile-lint-disable-line -->`,
|
|
137
|
+
or `nile-lint-disable [rules]` anywhere in a file for the whole file. Say why in the comment.
|
|
138
|
+
|
|
139
|
+
## ESLint (Lit / Angular templates in TS)
|
|
140
|
+
|
|
141
|
+
Flat config (ESLint 8.57+ or 9):
|
|
142
|
+
|
|
143
|
+
```js
|
|
144
|
+
// eslint.config.js
|
|
145
|
+
const nile = require('@aquera/nile-lint/eslint');
|
|
146
|
+
module.exports = [
|
|
147
|
+
nile.configs.recommended, // or nile.configs.cascade / nile.configs.strict
|
|
148
|
+
nile.configs['recommended-templates'], // Angular *.html templates
|
|
149
|
+
{ rules: { 'nile/prefer-nile-component': 'off' } },
|
|
150
|
+
];
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The `*-templates` configs use `@angular-eslint/template-parser` when the project has it (every
|
|
154
|
+
angular-eslint setup does), so problems show in `.html` templates in the editor too. Flat config
|
|
155
|
+
only: on a legacy `.eslintrc` project, run the CLI (`nile-lint src`) in CI and a pre-commit hook.
|
|
156
|
+
|
|
157
|
+
## Stylelint (CSS / SCSS)
|
|
158
|
+
|
|
159
|
+
```json
|
|
160
|
+
{ "extends": ["@aquera/nile-lint/stylelint/recommended"] }
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
or pick rules: `{ "plugins": ["@aquera/nile-lint/stylelint"], "rules": { "nile/no-raw-colors": true } }`.
|
|
164
|
+
Secondary options take `{ "profile": "cascade" }` plus any rule option.
|
|
165
|
+
|
|
166
|
+
## API
|
|
167
|
+
|
|
168
|
+
```js
|
|
169
|
+
const { lintText, lintFiles, format } = require('@aquera/nile-lint');
|
|
170
|
+
lintText('<nile-button variant="danger">', { filename: 'x.html' });
|
|
171
|
+
const results = await lintFiles(['src'], { profile: 'recommended', fix: false });
|
|
172
|
+
console.log(format.agent(results));
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## The manifest
|
|
176
|
+
|
|
177
|
+
`manifest.json` is **generated** from this monorepo by `yarn workspace @aquera/nile-lint build`:
|
|
178
|
+
component custom-data plus a source scan of every component package (tags, attributes, values,
|
|
179
|
+
properties, events, parts), the nxtgen token CSS, Cascade roles, the legacy enterprise tokens
|
|
180
|
+
(for suggestions), the class vocabularies and the icon sets. Rebuild it whenever a component,
|
|
181
|
+
token, class or icon changes; `yarn workspace @aquera/nile-lint check-manifest` (also run by the
|
|
182
|
+
tests) fails when it's stale. `--manifest <file>` points the linter at another build.
|
|
183
|
+
|
|
184
|
+
`@aquera/nile-glyph` comes from npm, and its published package has no sources, so the build reads
|
|
185
|
+
its typings and icon files. The build refuses to write a manifest that is missing any component
|
|
186
|
+
package or the glyph icons. To build against a specific copy of a package (e.g. an unpacked npm
|
|
187
|
+
tarball), pass `--use nile-glyph=<dir>`.
|
|
188
|
+
|
|
189
|
+
## Development
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
yarn workspace @aquera/nile-lint build # regenerate manifest.json from this monorepo
|
|
193
|
+
yarn workspace @aquera/nile-lint check-manifest # fail if the committed manifest is stale
|
|
194
|
+
yarn workspace @aquera/nile-lint test # node --test (rules, plugins, adoption, versions)
|
|
195
|
+
node packages/nile-lint/bin/nile-lint.js <path> # run the CLI from source
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Releasing:
|
|
199
|
+
|
|
200
|
+
1. Branch `release/<version>/nile-lint`, bump `version` in `package.json`, rebuild the manifest
|
|
201
|
+
and add a note under Release Notes below (plus a `.changeset` entry).
|
|
202
|
+
2. CI on the branch runs `Test @aquera/nile-lint (committed manifest)`, which fails if the
|
|
203
|
+
committed manifest doesn't match the checkout.
|
|
204
|
+
3. After merge, master's `Test and Publish @aquera/nile-lint` publishes the version if it isn't on
|
|
205
|
+
npm yet: it rebuilds the manifest, runs the tests, tags `@aquera/nile-lint@<version>` and runs
|
|
206
|
+
`npm publish --access public`.
|
|
207
|
+
|
|
208
|
+
`package.json` deliberately has no `bin` in the repo: as a workspace package with a bin,
|
|
209
|
+
`yarn install` would chmod the checked-out file through `node_modules/.bin`, which fails in CI's
|
|
210
|
+
non-root puppeteer image. The publish step adds `"bin": { "nile-lint": "bin/nile-lint.js" }` just
|
|
211
|
+
before `npm publish`, so `npx nile-lint` works for everyone who installs the package. In this repo,
|
|
212
|
+
run the CLI as `node packages/nile-lint/bin/nile-lint.js`.
|
|
213
|
+
|
|
214
|
+
Master's stage-1 `Test @aquera/nile-lint` rebuilds before testing, so a component change on
|
|
215
|
+
master never blocks other packages' releases; ship it to apps with a nile-lint patch release.
|
|
216
|
+
|
|
217
|
+
## Release Notes
|
|
218
|
+
|
|
219
|
+
In this section, you can find the updates for each release of `nile-lint`. It's a good practice to maintain detailed release notes to help users and developers understand what changes have been made from one version to another and how these changes might affect their projects.
|
|
220
|
+
|
|
221
|
+
#### Version 0.1.1 (November 6, 2026)
|
|
222
|
+
|
|
223
|
+
- Nile Lint: Manifest rebuilt for nile-elements 2.0.21. `size` on `<nile-button>` is now a real attribute (`sm`, `md`, `lg`, `xl`), so it is no longer reported as an internal `@state()` that does nothing; other values such as `small` or `large` are reported by `valid-attribute-values` (UIF-1410).
|
|
224
|
+
|
|
225
|
+
#### Version 0.1.0 (November 04, 2026)
|
|
226
|
+
|
|
227
|
+
- Initial release of the `@aquera/nile-lint` package: an agent-first linter that checks markup and styles against a manifest generated from this monorepo (nile-elements 2.0.20, nile 1.3.5, nile-glyph 1.0.9; 296 elements) (UIF-1407).
|
|
228
|
+
- Nile Lint: Added 17 rules — `no-unknown-elements`, `no-unknown-attributes`, `valid-attribute-values`, `no-unknown-events`, `no-unknown-icons`, `no-unknown-classes`, `no-raw-colors`, `no-arbitrary-values`, `no-unknown-tokens`, `no-legacy-tokens`, `no-legacy-theme`, `no-restyle`, `gradient-budget`, `no-inline-styles`, `prefer-nile-component`, `prefer-stroke-icons` and `no-external-resources` — with `recommended`, `cascade` and `strict` profiles (UIF-1407).
|
|
229
|
+
- Nile Lint CLI: Added `nile-lint` with `pretty` / `agent` / `json` output, exact-match-only `--fix`, `--version` (linter and manifest Nile versions, plus a warning when the app's `@aquera/nile-elements` is newer) and `--update-baseline` / `--baseline` / `--no-baseline` to adopt it on an existing app (UIF-1407).
|
|
230
|
+
- Nile Lint ESLint plugin: Added flat configs `recommended`, `cascade` and `strict` for Lit and Angular templates in `.ts`, and `*-templates` configs for Angular `.html` templates via `@angular-eslint/template-parser` (UIF-1407).
|
|
231
|
+
- Nile Lint Stylelint plugin: Added `@aquera/nile-lint/stylelint` with `recommended`, `cascade` and `strict` presets (UIF-1407).
|
|
232
|
+
- Nile Lint Angular support: Templates are detected by content; animation triggers, ARIA/DOM properties, router/forms/CDK/Material inputs, the project's own and its libraries' directive inputs, and classes from a component's own stylesheet are not reported (UIF-1407).
|
package/SETUP.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Setting up @aquera/nile-lint — instructions for coding agents
|
|
2
|
+
|
|
3
|
+
You are adding the Nile linter to a project. Do these steps in order, then use the loop at the
|
|
4
|
+
bottom whenever you write or change UI code in this project.
|
|
5
|
+
|
|
6
|
+
## 1. Pick the profile
|
|
7
|
+
|
|
8
|
+
- The project renders Nile web components (`<nile-button>`, `<nile-input>`… from
|
|
9
|
+
`@aquera/nile-elements`), usually an Angular or Lit app → **`recommended`**.
|
|
10
|
+
- The project is Nile Cascade pages (plain HTML/CSS with `ng-*` classes and `--ng-*` tokens,
|
|
11
|
+
no web components, self-contained) → **`cascade`**.
|
|
12
|
+
- Both in one repo → `recommended` with an `overrides` entry setting `"profile": "cascade"`
|
|
13
|
+
for the Cascade folder.
|
|
14
|
+
|
|
15
|
+
## 2. Install and configure
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm i -D @aquera/nile-lint # yarn add -D / pnpm add -D — match the project's lockfile
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Create `nile-lint.config.json` at the project root:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{ "profile": "recommended", "ignore": [] }
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Add a script to `package.json`: `"lint:nile": "nile-lint src"` (use the real source folder).
|
|
28
|
+
|
|
29
|
+
Optional, when the project already uses them:
|
|
30
|
+
- ESLint flat config → add `require('@aquera/nile-lint/eslint').configs.recommended` and
|
|
31
|
+
`.configs['recommended-templates']` (Angular `.html` templates) to the array.
|
|
32
|
+
- Stylelint → add `"@aquera/nile-lint/stylelint/recommended"` to `extends`.
|
|
33
|
+
|
|
34
|
+
## 3. Baseline
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npx nile-lint src --format agent
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- Run `npx nile-lint src --fix --format agent` first: it applies only exact-match fixes.
|
|
41
|
+
- Fix the remaining **errors**. Every message names the replacement; use it.
|
|
42
|
+
- Existing app with many problems? After `--fix`, run `npx nile-lint src --update-baseline` and
|
|
43
|
+
commit `.nile-lint-baseline.json`. From then on only new problems are reported — tell the user
|
|
44
|
+
how many were baselined, and that re-running `--update-baseline` shrinks it as they're fixed.
|
|
45
|
+
- If the existing code has many **warnings** (`no-arbitrary-values`, `prefer-nile-component`,
|
|
46
|
+
`no-inline-styles`), don't rewrite the app unasked — report the count and ask whether to fix
|
|
47
|
+
them now or turn those rules to `"off"`/`"warn"` in the config.
|
|
48
|
+
- Never silence a rule to get to zero. A deliberate exception gets a comment with a reason:
|
|
49
|
+
`/* nile-lint-disable-next-line no-raw-colors -- brand logo color, not themeable */`.
|
|
50
|
+
|
|
51
|
+
## 4. The loop (every UI change, not just setup)
|
|
52
|
+
|
|
53
|
+
1. Write the markup/styles.
|
|
54
|
+
2. `npx nile-lint <changed files or folder> --format agent`
|
|
55
|
+
3. Apply the fixes the messages give. `--fix` for the `[auto-fixable]` ones.
|
|
56
|
+
4. Repeat until it prints `0 problems`. Only then call the UI work done.
|
|
57
|
+
|
|
58
|
+
## What the messages mean (so you fix the cause, not the symptom)
|
|
59
|
+
|
|
60
|
+
- `no-unknown-attributes` — Lit attribute names are the **lowercased property name** unless the
|
|
61
|
+
component declares otherwise: `helpText` → `helptext`, but some are kebab (`help-text`). Use
|
|
62
|
+
the attribute the message suggests; in Angular, `[helpText]="…"` binds the property directly.
|
|
63
|
+
- `valid-attribute-values` on a boolean — `disabled="false"` is still disabled. Remove the
|
|
64
|
+
attribute, or bind it (`[disabled]="false"` / `?disabled=${false}`).
|
|
65
|
+
- `no-raw-colors` — use the suggested `var(--ng-…)`. If the suggestion's role is wrong (a bg
|
|
66
|
+
token for text), pick the right `--ng-colors-text-*` / `-bg-*` / `-border-*` / `-fg-*` token.
|
|
67
|
+
- `no-unknown-tokens` on `--ng-text`, `--ng-surface`… — those are Cascade roles; product apps
|
|
68
|
+
must use the full nxtgen token the message names.
|
|
69
|
+
- `no-restyle` — don't override a component's look from outside. Use its attributes (variant,
|
|
70
|
+
size…), a `::part()` it documents, or its `--nile-<component>-*` custom properties.
|
|
71
|
+
- `no-legacy-tokens` / `no-legacy-theme` — the enterprise theme is gone; nxtgen only.
|
package/bin/nile-lint.js
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
const { lintFiles, RULES, PROFILES, format } = require('..');
|
|
5
|
+
const { normalizeEntry } = require('../lib/config');
|
|
6
|
+
const { loadManifest } = require('../lib/manifest');
|
|
7
|
+
const { versionInfo, versionText, staleManifestWarning } = require('../lib/version');
|
|
8
|
+
const fs = require('fs');
|
|
9
|
+
const path = require('path');
|
|
10
|
+
const { DEFAULT_BASELINE, createBaseline } = require('../lib/baseline');
|
|
11
|
+
|
|
12
|
+
const HELP = `nile-lint — agent-first linter for the Nile design system
|
|
13
|
+
|
|
14
|
+
Usage: nile-lint [paths/globs…] [options]
|
|
15
|
+
|
|
16
|
+
Lints .css .scss .html .component.html .vue .svelte and Lit/Angular templates in .ts/.js.
|
|
17
|
+
|
|
18
|
+
Options:
|
|
19
|
+
--profile <name> ${PROFILES.join(' | ')} (default: config, else recommended)
|
|
20
|
+
--format <name> pretty | agent | json (default: pretty on a TTY, agent otherwise)
|
|
21
|
+
--fix apply exact-match fixes in place
|
|
22
|
+
--rule <id>=<sev> override a rule: error | warn | off (repeatable)
|
|
23
|
+
--config <file> explicit config file (default: nearest nile-lint.config.json /
|
|
24
|
+
.nile-lintrc.json / package.json "nileLint")
|
|
25
|
+
--no-config ignore config files
|
|
26
|
+
--manifest <file> use a different Nile manifest (default: the bundled one)
|
|
27
|
+
--ignore <glob> extra ignore pattern (repeatable)
|
|
28
|
+
--max-warnings <n> exit 1 when warnings exceed n
|
|
29
|
+
--baseline <file> hide problems recorded in this baseline (default: ${DEFAULT_BASELINE}
|
|
30
|
+
in the current folder, when it exists)
|
|
31
|
+
--no-baseline report everything, ignoring any baseline
|
|
32
|
+
--update-baseline record every current problem in the baseline file and exit 0 —
|
|
33
|
+
adopt nile-lint on an existing app, then fail only on new problems
|
|
34
|
+
--quiet report errors only
|
|
35
|
+
--list-rules print the rules and their per-profile severity
|
|
36
|
+
-v, --version print the nile-lint version and the Nile versions it checks against
|
|
37
|
+
-h, --help
|
|
38
|
+
|
|
39
|
+
Exit codes: 0 clean · 1 lint errors (or too many warnings) · 2 usage/crash`;
|
|
40
|
+
|
|
41
|
+
function parseArgs(argv) {
|
|
42
|
+
const o = { patterns: [], rules: {}, ignore: [] };
|
|
43
|
+
for (let i = 0; i < argv.length; i++) {
|
|
44
|
+
const a = argv[i];
|
|
45
|
+
const next = () => {
|
|
46
|
+
if (i + 1 >= argv.length) throw new Error(`${a} needs a value`);
|
|
47
|
+
return argv[++i];
|
|
48
|
+
};
|
|
49
|
+
if (a === '-h' || a === '--help') o.help = true;
|
|
50
|
+
else if (a === '-v' || a === '--version') o.version = true;
|
|
51
|
+
else if (a === '--profile') o.profile = next();
|
|
52
|
+
else if (a === '--format' || a === '-f') o.format = next();
|
|
53
|
+
else if (a === '--fix') o.fix = true;
|
|
54
|
+
else if (a === '--rule') {
|
|
55
|
+
const [id, sev] = next().split('=');
|
|
56
|
+
o.rules[id] = normalizeEntry(sev || 'error').severity;
|
|
57
|
+
} else if (a === '--config' || a === '-c') o.config = next();
|
|
58
|
+
else if (a === '--no-config') o.config = false;
|
|
59
|
+
else if (a === '--manifest') o.manifest = next();
|
|
60
|
+
else if (a === '--ignore') o.ignore.push(next());
|
|
61
|
+
else if (a === '--max-warnings') o.maxWarnings = Number(next());
|
|
62
|
+
else if (a === '--quiet') o.quiet = true;
|
|
63
|
+
else if (a === '--baseline') o.baseline = next();
|
|
64
|
+
else if (a === '--no-baseline') o.baseline = false;
|
|
65
|
+
else if (a === '--update-baseline') o.updateBaseline = true;
|
|
66
|
+
else if (a === '--list-rules') o.listRules = true;
|
|
67
|
+
else if (a.startsWith('-')) throw new Error(`unknown option ${a}`);
|
|
68
|
+
else o.patterns.push(a);
|
|
69
|
+
}
|
|
70
|
+
return o;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function listRules() {
|
|
74
|
+
const rows = Object.entries(RULES).map(([id, r]) => {
|
|
75
|
+
const sev = (p) => (r.profiles[p] || 'off').padEnd(12);
|
|
76
|
+
return `${id.padEnd(24)} ${sev('recommended')}${sev('cascade')}${
|
|
77
|
+
r.fixable ? 'fix ' : ' '
|
|
78
|
+
}${r.description}`;
|
|
79
|
+
});
|
|
80
|
+
return [
|
|
81
|
+
`${'rule'.padEnd(24)} ${'recommended'.padEnd(12)}${'cascade'.padEnd(12)} description`,
|
|
82
|
+
...rows,
|
|
83
|
+
].join('\n');
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
async function main() {
|
|
87
|
+
let o;
|
|
88
|
+
try {
|
|
89
|
+
o = parseArgs(process.argv.slice(2));
|
|
90
|
+
} catch (e) {
|
|
91
|
+
console.error(`nile-lint: ${e.message}\n\n${HELP}`);
|
|
92
|
+
return 2;
|
|
93
|
+
}
|
|
94
|
+
if (o.help) {
|
|
95
|
+
console.log(HELP);
|
|
96
|
+
return 0;
|
|
97
|
+
}
|
|
98
|
+
const info = versionInfo(loadManifest(o.manifest).data);
|
|
99
|
+
if (o.version) {
|
|
100
|
+
console.log(versionText(info));
|
|
101
|
+
return 0;
|
|
102
|
+
}
|
|
103
|
+
if (o.listRules) {
|
|
104
|
+
console.log(listRules());
|
|
105
|
+
return 0;
|
|
106
|
+
}
|
|
107
|
+
const results = await lintFiles(o.patterns, {
|
|
108
|
+
profile: o.profile,
|
|
109
|
+
rules: o.rules,
|
|
110
|
+
fix: o.fix,
|
|
111
|
+
config: o.config,
|
|
112
|
+
manifest: o.manifest,
|
|
113
|
+
ignore: o.ignore,
|
|
114
|
+
baseline: o.updateBaseline ? false : o.baseline,
|
|
115
|
+
});
|
|
116
|
+
if (o.updateBaseline) {
|
|
117
|
+
const file = path.resolve(typeof o.baseline === 'string' ? o.baseline : DEFAULT_BASELINE);
|
|
118
|
+
const data = createBaseline(results);
|
|
119
|
+
const rel = path.relative(process.cwd(), file);
|
|
120
|
+
const shown = rel && !rel.startsWith('..') ? rel : file;
|
|
121
|
+
fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
|
|
122
|
+
const c = format.counts(results);
|
|
123
|
+
console.log(
|
|
124
|
+
`nile-lint: recorded ${c.errors + c.warnings} existing problems in ${
|
|
125
|
+
Object.keys(data.files).length
|
|
126
|
+
} files ` + `to ${shown}. Commit it; from now on only new problems are reported.`
|
|
127
|
+
);
|
|
128
|
+
return 0;
|
|
129
|
+
}
|
|
130
|
+
const baselined = results.reduce((n, r) => n + (r.baselined || 0), 0);
|
|
131
|
+
if (o.quiet)
|
|
132
|
+
for (const r of results) r.messages = r.messages.filter((d) => d.severity === 'error');
|
|
133
|
+
|
|
134
|
+
const fmt = o.format || (process.stdout.isTTY ? 'pretty' : 'agent');
|
|
135
|
+
const meta = { ...info, profile: o.profile, baselined };
|
|
136
|
+
const stale = staleManifestWarning(info);
|
|
137
|
+
if (stale) console.error(`nile-lint: warning: ${stale}`);
|
|
138
|
+
const command = [
|
|
139
|
+
'npx nile-lint',
|
|
140
|
+
...o.patterns,
|
|
141
|
+
...(o.profile ? ['--profile', o.profile] : []),
|
|
142
|
+
].join(' ');
|
|
143
|
+
if (fmt === 'json') console.log(format.json(results));
|
|
144
|
+
else if (fmt === 'agent')
|
|
145
|
+
console.log(
|
|
146
|
+
format.agent(results, { command: `${command} --format agent`, profile: o.profile, meta })
|
|
147
|
+
);
|
|
148
|
+
else if (fmt === 'pretty') console.log(format.pretty(results, { meta }));
|
|
149
|
+
else {
|
|
150
|
+
console.error(`nile-lint: unknown format "${fmt}"`);
|
|
151
|
+
return 2;
|
|
152
|
+
}
|
|
153
|
+
const fixed = results.reduce((n, r) => n + (r.fixed || 0), 0);
|
|
154
|
+
if (fixed && fmt !== 'json')
|
|
155
|
+
console.error(`nile-lint: applied ${fixed} fix${fixed === 1 ? '' : 'es'}.`);
|
|
156
|
+
|
|
157
|
+
const c = format.counts(results);
|
|
158
|
+
if (c.errors) return 1;
|
|
159
|
+
if (Number.isFinite(o.maxWarnings) && c.warnings > o.maxWarnings) return 1;
|
|
160
|
+
return 0;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
main().then(
|
|
164
|
+
(code) => process.exit(code),
|
|
165
|
+
(err) => {
|
|
166
|
+
console.error(`nile-lint crashed: ${err && err.stack ? err.stack : err}`);
|
|
167
|
+
process.exit(2);
|
|
168
|
+
}
|
|
169
|
+
);
|
package/eslint/index.js
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* ESLint plugin: every nile-lint rule, run over the Lit html``/css`` templates and Angular
|
|
5
|
+
* @Component({ template, styles }) in JS/TS files. Flat config only (ESLint 8.57+ or 9) — the
|
|
6
|
+
* legacy eslintrc resolver would look for a package named @aquera/eslint-plugin-nile-lint.
|
|
7
|
+
*
|
|
8
|
+
* // eslint.config.js
|
|
9
|
+
* const nile = require('@aquera/nile-lint/eslint');
|
|
10
|
+
* module.exports = [nile.configs.recommended]; // or .cascade / .strict
|
|
11
|
+
*
|
|
12
|
+
* Angular templates (`*.html`): add `nile.configs['recommended-templates']` too — it uses
|
|
13
|
+
* @angular-eslint/template-parser when the project has it.
|
|
14
|
+
*
|
|
15
|
+
* Profile (recommended | cascade | strict) comes from `settings.nileLint.profile`; per-rule options
|
|
16
|
+
* are the rule's first option object. CSS files are covered by the CLI and the Stylelint plugin.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
const engine = require('../lib/engine');
|
|
20
|
+
const { RULES, profileRules } = require('../lib/rules');
|
|
21
|
+
const { loadManifest } = require('../lib/manifest');
|
|
22
|
+
const pkg = require('../package.json');
|
|
23
|
+
|
|
24
|
+
/** One parse per file, shared by all rules. */
|
|
25
|
+
const prepared = new WeakMap();
|
|
26
|
+
|
|
27
|
+
function prepFor(sourceCode, filename) {
|
|
28
|
+
let p = prepared.get(sourceCode);
|
|
29
|
+
if (!p) {
|
|
30
|
+
p = engine.prepare(sourceCode.text, filename);
|
|
31
|
+
prepared.set(sourceCode, p);
|
|
32
|
+
}
|
|
33
|
+
return p;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function makeRule(id, meta) {
|
|
37
|
+
return {
|
|
38
|
+
meta: {
|
|
39
|
+
type: /^prefer-|no-inline|no-arbitrary|gradient/.test(id) ? 'suggestion' : 'problem',
|
|
40
|
+
docs: {
|
|
41
|
+
description: meta.description,
|
|
42
|
+
recommended: meta.profiles.recommended !== 'off',
|
|
43
|
+
url: `https://www.npmjs.com/package/${pkg.name}#${id}`,
|
|
44
|
+
},
|
|
45
|
+
fixable: meta.fixable ? 'code' : undefined,
|
|
46
|
+
schema: [{ type: 'object', additionalProperties: true }],
|
|
47
|
+
messages: { problem: '{{message}}' },
|
|
48
|
+
},
|
|
49
|
+
create(context) {
|
|
50
|
+
const sourceCode = context.sourceCode || context.getSourceCode();
|
|
51
|
+
const filename = context.filename || (context.getFilename && context.getFilename());
|
|
52
|
+
const settings = (context.settings && context.settings.nileLint) || {};
|
|
53
|
+
const profile = settings.profile || 'recommended';
|
|
54
|
+
const base = profileRules(profile)[id];
|
|
55
|
+
const rules = {
|
|
56
|
+
[id]: { severity: 'error', options: { ...base.options, ...(context.options[0] || {}) } },
|
|
57
|
+
};
|
|
58
|
+
return {
|
|
59
|
+
'Program:exit'() {
|
|
60
|
+
const p = prepFor(sourceCode, filename);
|
|
61
|
+
if (!p.parsed.length) return;
|
|
62
|
+
const manifest = loadManifest(settings.manifest);
|
|
63
|
+
for (const d of engine.run(p, rules, { profile, manifest })) {
|
|
64
|
+
if (d.ruleId !== id) continue;
|
|
65
|
+
context.report({
|
|
66
|
+
loc: {
|
|
67
|
+
start: { line: d.line, column: d.column - 1 },
|
|
68
|
+
end: { line: d.endLine, column: d.endColumn - 1 },
|
|
69
|
+
},
|
|
70
|
+
messageId: 'problem',
|
|
71
|
+
data: { message: d.message },
|
|
72
|
+
fix: d.fix
|
|
73
|
+
? (fixer) => fixer.replaceTextRange([d.fix.start, d.fix.end], d.fix.text)
|
|
74
|
+
: undefined,
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
},
|
|
78
|
+
};
|
|
79
|
+
},
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const rules = {};
|
|
84
|
+
for (const [id, meta] of Object.entries(RULES)) rules[id] = makeRule(id, meta);
|
|
85
|
+
|
|
86
|
+
const PREFIX = 'nile';
|
|
87
|
+
|
|
88
|
+
function ruleSeverities(profile) {
|
|
89
|
+
const out = {};
|
|
90
|
+
for (const [id, r] of Object.entries(profileRules(profile))) out[`${PREFIX}/${id}`] = r.severity;
|
|
91
|
+
return out;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const plugin = {
|
|
95
|
+
meta: { name: pkg.name, version: pkg.version },
|
|
96
|
+
rules,
|
|
97
|
+
configs: {},
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The project's Angular template parser, when installed — so `*.html` templates (Angular
|
|
102
|
+
* components' templateUrl files) are linted in the editor too. Resolved from the project, not
|
|
103
|
+
* from this package, so it works under any package manager layout.
|
|
104
|
+
*/
|
|
105
|
+
function templateParser() {
|
|
106
|
+
for (const from of [process.cwd(), __dirname]) {
|
|
107
|
+
try {
|
|
108
|
+
return require(require.resolve('@angular-eslint/template-parser', { paths: [from] }));
|
|
109
|
+
} catch {
|
|
110
|
+
/* not installed here */
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
for (const profile of ['recommended', 'cascade', 'strict']) {
|
|
117
|
+
plugin.configs[profile] = {
|
|
118
|
+
name: `nile-lint/${profile}`,
|
|
119
|
+
files: ['**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
|
|
120
|
+
plugins: { [PREFIX]: plugin },
|
|
121
|
+
settings: { nileLint: { profile } },
|
|
122
|
+
rules: ruleSeverities(profile),
|
|
123
|
+
};
|
|
124
|
+
// Angular templates (`*.html`). Uses @angular-eslint/template-parser when the project has it;
|
|
125
|
+
// otherwise your own config must set languageOptions.parser for these files.
|
|
126
|
+
const parser = templateParser();
|
|
127
|
+
plugin.configs[`${profile}-templates`] = {
|
|
128
|
+
name: `nile-lint/${profile}-templates`,
|
|
129
|
+
files: ['**/*.html'],
|
|
130
|
+
...(parser ? { languageOptions: { parser } } : {}),
|
|
131
|
+
plugins: { [PREFIX]: plugin },
|
|
132
|
+
settings: { nileLint: { profile } },
|
|
133
|
+
rules: ruleSeverities(profile),
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
module.exports = plugin;
|