@webority/repo-checks 0.149.0 → 0.152.0

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 CHANGED
@@ -14,8 +14,12 @@ pnpm add -D --save-exact @webority/repo-checks
14
14
  pnpm exec webority-repo-checks # every app in the repository
15
15
  pnpm exec webority-repo-checks apps/portal # one app folder
16
16
  pnpm exec webority-repo-checks --offline # no advisory audit, so no network
17
+ pnpm exec webority-repo-checks --build # quick rules only, for a build script
18
+ pnpm exec webority-repo-checks --skip-lint # leave out the Biome run, for a gate that already lints
17
19
  ```
18
20
 
21
+ A product's build script runs `--build` before its bundler, for example `"build": "webority-repo-checks --build && vite build"`.
22
+
19
23
  An app is a `package.json` whose `dependencies` hold `react-native` (mobile) or `react-dom` (web). A `react-dom` folder that also has `react-native-web` is a react-native-web demo: it gets the pnpm and Biome checks, not the portal rules. Biome and `@webority/biome-config` are read from the `package.json` beside the `biome.json` in effect (a nested config with `"root": false` defers to the one above), so a sub-folder linted by the root config does not repeat them. A `workspace:`, `file:` or `link:` reference is local and never counts as a lockstep version.
20
24
  A package with `agentation` in its `dependencies` is a build tool, not an app. It and anything else (tooling roots, libraries) get only the lockfile check.
21
25
 
@@ -28,7 +32,7 @@ The `missing-export:<file>` check runs the Biome installed beside the app or in
28
32
  | `required:<name>` | A dependency every app carries (Biome and the shared preset, the core and UI packages, Bootstrap and react-bootstrap on web, Crashlytics on mobile) |
29
33
  | `not-exact:<name>` | A `^` or `~` range. Web pins `@webority/*` and `bootstrap` exactly; a React Native app pins every dependency exactly |
30
34
  | `lockstep:<set>` | Packages that publish together at one version are pinned at different versions |
31
- | `pnpm:*` | A committed `package-lock.json` or `yarn.lock`, no `pnpm-lock.yaml`, no `devEngines.packageManager` of `{ "name": "pnpm", "version": "<x.y.z>", "onFail": "error" }` (a plain `npm install` fails, and pnpm refuses any other version), a leftover `packageManager` field (pnpm ignores it beside devEngines), or a `pnpm-workspace.yaml` without `engineStrict: true` and `strictPeerDependencies: true` |
35
+ | `pnpm:*` | A committed `package-lock.json` or `yarn.lock`, no `pnpm-lock.yaml`, no `devEngines.packageManager` of `{ "name": "pnpm", "version": "<x.y.z>", "onFail": "error" }` (a plain `npm install` fails, and pnpm refuses any other version), a leftover `packageManager` field (pnpm ignores it beside devEngines), or a `pnpm-workspace.yaml` without `engineStrict: true` and `strictPeerDependencies: true`, or a pinned pnpm version that differs from the pnpm version in the machine prerequisites list (`pnpm:version`; skipped where the machine prerequisites list does not exist, and `WEBORITY_PREREQUISITES` points the check at another list) |
32
36
  | `biome:*` | No Biome config, a config that does not extend `@webority/biome-config/biome.jsonc`, a `formatter.lineEnding` or root `linter.rules`, or (mobile) no `__DEV__` global, either top-level or in an override whose `includes` cover the app folder |
33
37
  | `catalogue-copy:<file>` | A `.jsx` or `.tsx` file anywhere under `src/` of a web app, or of a workspace package that depends on `@webority/ui-react`, named like a `@webority/ui-react` export |
34
38
  | `android-release-signing` | `android/app/build.gradle` has no guard that throws a `GradleException` when a requested task name contains `release` and a signing setting or the upload key is missing |
@@ -38,9 +42,16 @@ The `missing-export:<file>` check runs the Biome installed beside the app or in
38
42
  | `endpoint-name:<name>` | Two RTK Query endpoints in an app's `src` share a name (a `name: build.query(`, `build.mutation(` or `build.infiniteQuery(` key in a file that calls `injectEndpoints` or `createApi`); RTK Query keeps one, so the other screen calls the wrong URL. Warns until a release enforces it (`REPO_CHECKS_ENFORCE=endpoint-name` fails it now) |
39
43
  | `mobile-production-stamps:<file>` | A mobile app's Android manifest or iOS `Expo.plist` points over-the-air updates at the Staging or Development feed, or `android/gradle.properties` carries a `.staging` or `.development` app id, left by `mobile-tools prebuild`. Run `mobile-tools prebuild --env Production` before committing |
40
44
  | `spa-host-immutable-assets:<file>` | A web app's `web.config`, `staticwebapp.config.json`, `_headers` or `spa-host*.json` sets Cache-Control with `immutable` |
45
+ | `build-typecheck:<script>` | A web portal's `build` or `build:*` script runs no `tsc --noEmit` and no `typecheck` script, itself or through the build scripts it calls; react.md → Language. Warns until a release enforces it |
46
+ | `library-copy:<file>:<name>` | A web portal's source file under `src/` declares or exports, itself, a name `@webority/web-core` exports (its logger, error helpers, store set-up, reload helpers, refresh lock, JWT helpers, India validators); a re-export from the package passes. Warns until a release enforces it |
47
+ | `mobile-library-pin:<name>` | A React Native app pins a `@webority/mobile-*` package below this checker's own version, which is the current phone library version. Warns until a release enforces it |
48
+ | `root-file:<name>` | A web portal has no `.nvmrc` in its folder or above, lacks `spa-host.json` or a `spa-host.<Environment>.json`, has a JavaScript Vite config, has no `codeSplitting` groups, or sets `build.target`; react.md, as the starter does. Warns until a release enforces it |
49
+ | `tracking-plan:<missing\|invalid\|extends>` | A product repo (it has `.github/workflows/production.yml`) has no `.webority/tracking-plan.json`, one that is not a JSON object, or one whose `extends` is not `@webority/analytics/fleet`; product-analytics.md. Warns until a release enforces it |
50
+ | `web-folder:<folder>` | A web portal has `src/components/base/` or a flat `src/components/features/`; react.md → Folder layout. Warns until a release enforces it |
41
51
  | `stale-theme-name:<file>` | A web style or source file reads a pre-0.89.0 theme name as a whole token (`var(--radius)`, `--color-primary-ink`). No alias ships for these. Run `webority upgrade 0.89.0 --path <folder>` once, then `webority brand`. `--color-primary-text` is not flagged. Never recorded in the baseline |
42
- | `lint:<file>` | Biome's check, with warnings as errors, over the app folder: any error or warning. Never recorded in the baseline; fix the finding |
52
+ | `lint:<file>` | Biome's check, with warnings as errors, over the app folder: any error or warning. Never recorded in the baseline; fix the finding; `--skip-lint` leaves it out |
43
53
  | `web-import-axios:<file>` | A web source file under `src/` imports `axios`; HTTP goes through `@webority/web-core` |
54
+ | `web-import-axios-types:<file>` | A web source file imports types from `axios` with `import type` or `export type`; import `AxiosError`, `AxiosInstance`, `AxiosRequestConfig` and `AxiosResponse` from `@webority/web-core`. Warns until a release enforces it |
44
55
  | `web-import-router:<file>` | A web source file imports `BrowserRouter` or `Routes` from `react-router` or `react-router-dom`; routes are objects for `createBrowserRouter` |
45
56
  | `web-import-env-branch:<file>` | A web source file reads `import.meta.env.DEV` or `import.meta.env.PROD`; branch on `AppSettings.ENVIRONMENT` |
46
57
  | `missing-export:<file>` | A file imports a name its module does not export; Biome's React false alarms, unresolved aliases and a name a relative module re-exports from a package are not reported |
@@ -59,6 +70,12 @@ The `missing-export:<file>` check runs the Biome installed beside the app or in
59
70
  | `single-use-component:<file>` | A file under `src/components/<feature>/` (not `layout/`), or a shared partial under `Pages/Shared/` or a `*.Web.Common` project, that fewer than two files use; move it next to the page that uses it. A layout is skipped: a `_…Layout.cshtml` file, or one that a `_ViewStart.cshtml` of the same project names with `Layout = "<name>"`, because areas find it by that name. A Razor file whose first line is `@* layering-allow single-use-component: <reason> *@` is skipped too; a mark with no reason is a finding. Counted per file. |
60
71
  | `error-summary-title:<file>` | A `.cshtml` `<app-error-summary>` sets a `title` with the old generic wording ("Please fix the following", "There were errors"); drop it, the library writes the standard heading. A computed title or one naming the failed action is not counted. Counted per file. |
61
72
  | `route-internal-id:<file>` | A route binds a record's internal number: a `.cshtml` `@page` or a C# `[Route]`, `[Http*]` or `Map*` template whose `id` or `...Id` parameter is constrained `int` or `long`, or an `asp-route-*` link that passes a record's `.Id`. Route by the public id (`{publicId:guid}`) instead. An untyped `{id}` is not counted. Counted per file. |
73
+ | `razor-page-handler:<file>` | A Razor page names a handler its page model does not declare: a literal `asp-page-handler`, a `?handler=` in a literal `href`, `action`, `formaction` or inline script string, or the handler argument of `Url.Page`, `RedirectToPage` or `RedirectToPagePermanent` (read like `RedirectToPage`). A handler `X` matches `On<Verb>X` or `On<Verb>XAsync` on the model or a base class in the repo. A `?handler=` is checked only in an address with no path before the `?`; one naming another path is counted as not checked. A page whose model derives from a package class is not checked. Counted per file. |
74
+ | `razor-page-link:<file>` | A literal `asp-page`, or the page argument of `Url.Page`, `RedirectToPage` or `RedirectToPagePermanent`, names no page in the project, the projects it references, or a host project that references it, resolved as ASP.NET Core does (absolute within the area, relative to the linking page's folder, `asp-area=""` for the root). A link into an area no folder in the repo holds is a package's page and is not counted. Counted per file. What the check cannot read (a dynamic `asp-page`, a page name in a variable, a constant C# member lookup cannot pin to one value, a model outside the repo) is not a finding; the run prints how many links it skipped and why. |
75
+ | `web-route-literal:<file>` | A router link or navigate call in a portal with a literal path instead of `href(...)` from the route table, so a link to a route that does not exist fails the type check. A template that starts with a substitution is not counted. Counted per file. |
76
+ | `api-thunk:<file>` | A call of `createAsyncThunk`, or of a name the file binds to `createAsyncThunk.withTypes`, in an app's source; an API call moves to an RTK Query endpoint in `services/api` (react.md: API data). Counted per file. |
77
+ | `screen-service-import:<file>` | A file under `src/screens/` imports from its head's `services/` folder other than the RTK Query api module (`services/api` or `services/api/*`); a screen reads data through that module. Counted per file. |
78
+ | `api-call:<file>` | A hand-written URL in an app's `src`: a `.get(`, `.post(`, `.put(`, `.patch(` or `.delete(` call whose first argument is a string or template starting with `/` or `api/`, or a function in a `services` folder declared to return `Promise<unknown>`. The reply type and the URL come from the generated contract: call the operation through `api("<OperationId>", request)` from `src/services/api/api.ts`. Counted per file. Warns until a release enforces it (`REPO_CHECKS_ENFORCE=api-call` fails it now). |
62
79
  | `oversize:<file>` | A `.jsx`, `.tsx` or `.cshtml` file over 600 lines (over 800 says to split it along its concerns). A warning only: it never fails, even outside the baseline. Counted per file. |
63
80
  | `hook:drift` | The root `.husky/pre-commit` is missing or differs from the shared hook this package ships (CRLF is ignored) |
64
81
  | `tracked-case:<path>` | A tracked file or folder whose name on disk differs only by letter case, a rename done by hand on a Mac that git never saw; a Linux checkout cannot find the import. Run the `git mv` the message gives. A folder is reported once. Always fails. |
@@ -68,6 +85,44 @@ The `missing-export:<file>` check runs the Biome installed beside the app or in
68
85
 
69
86
  Comment lines (`//`, `/*`, `*`) and `.test.` or `.spec.` files are not read by the import checks.
70
87
 
88
+ ## Where each rule runs
89
+
90
+ | Rule | What it checks | `--build` (product build) | Full run (push) |
91
+ |---|---|---|---|
92
+ | `banned`, `required`, `not-exact`, `lockstep` | Retired or forbidden packages, required packages, exact pins and lockstep versions | yes | yes |
93
+ | `pnpm:*` | The lockfile, manifest and workspace rules, including a committed npm or yarn lockfile | yes | yes |
94
+ | `biome:*` | The Biome config: the shared preset, line endings, root rules and the `__DEV__` global | yes | yes |
95
+ | `hook:drift` | The root pre-commit hook matches the shared one | yes | yes |
96
+ | `tracked-case` | A tracked name that differs only by letter case | yes | yes |
97
+ | `catalogue-copy` | A web source file named like a `@webority/ui-react` export | yes | yes |
98
+ | `android-release-signing`, `android-edge-to-edge` | Android Gradle release signing and edge-to-edge settings | yes | yes |
99
+ | `rn-mainactivity-oncreate-bundle`, `mobile-production-stamps`, `spa-host-immutable-assets` | Native entry points, production update stamps and immutable host caching | yes | yes |
100
+ | `folder-layout`, `cross-feature-import`, `import-into-screens`, `screen-imports-screen`, `shared-single-importer`, `library-wrapper`, `screen-length`, `mobile-pins-lockstep`, `local-theme`, `width-scaling`, `raw-primitive` | Phone app layering: folder layout, import direction, screen size and library use | yes | yes |
101
+ | `metro-bridge` | The development bridge is wired in a React Native app | yes | yes |
102
+ | `web-import-axios`, `web-import-axios-types`, `web-import-router`, `web-import-env-branch` | Web imports that bypass the shared packages or the app settings | yes | yes |
103
+ | `endpoint-name` | Two RTK Query endpoints share a name | yes | yes |
104
+ | `build-typecheck`, `library-copy`, `mobile-library-pin`, `root-file`, `web-folder` | Portal build script, library copies, phone pins, root files and folder layout (warn first) | yes | yes |
105
+ | `tracking-plan` | A product repo keeps a tracking plan that extends the shared plan (warn first) | yes | yes |
106
+ | `lint`, `missing-export` | Biome over every file: lint findings, and imports a module does not export | no | yes |
107
+ | `stale-theme-name` | Pre-0.89.0 theme names read as a whole token | no | yes |
108
+ | `advisory` | Known advisories from `pnpm audit` (needs the network) | no | yes |
109
+ | `raw-measure`, `palette-read`, `raw-colour`, `root-font-size`, `raw-motion`, `dark-read` | Counted style rules: raw sizes, colours and motion, palette reads and the root font size | no | yes |
110
+ | `missing-canvas-key`, `repeated-canvas-key` | List items without a key, and repeated keys | no | yes |
111
+ | `raw-bootstrap`, `library-class-restyle`, `rename-wrapper`, `shadowed-library-name`, `single-use-component` | Raw Bootstrap classes, product CSS restyling the library, wrappers, shadowed names and single-use components | no | yes |
112
+ | `error-summary-title`, `route-internal-id`, `oversize` | Error summary titles, internal ids in routes and file size | no | yes |
113
+ | `api-thunk`, `screen-service-import`, `api-call` | Hand-written API thunks, screens that import services other than the RTK Query api module, and hand-written API URLs | no | yes |
114
+ | `razor-page-handler`, `razor-page-link`, `web-route-literal` | Razor handlers and page links that name nothing, and portal links written as literal paths | no | yes |
115
+
116
+ `--build` skips the rules in `BUILD_SKIPPED_RULES` (exported from `src/check.ts`) because they start Biome, read every file's content or call the network. It prints no stale or fallen baseline lines, and it combines with `--json`, `--offline` and folder arguments, but not with the `--baseline-*` flags or `--sync-hook`.
117
+
118
+ ## Build mode
119
+
120
+ A portal's `build` script runs `pnpm exec webority-repo-checks --build` as its first step, so every build fails on a new finding (exit 1). Build mode skips these 26 rules: `lint`, `missing-export`, `stale-theme-name`, `advisory`, `raw-measure`, `palette-read`, `raw-colour`, `root-font-size`, `raw-motion`, `dark-read`, `missing-canvas-key`, `repeated-canvas-key`, `raw-bootstrap`, `library-class-restyle`, `rename-wrapper`, `shadowed-library-name`, `single-use-component`, `error-summary-title`, `route-internal-id`, `razor-page-handler`, `razor-page-link`, `web-route-literal`, `api-thunk`, `screen-service-import`, `api-call` and `oversize`. Those rules run only in a full run (`pnpm exec webority-repo-checks` with no `--build`), which the push check still runs. Any rule not named here runs in both.
121
+
122
+ `--skip-lint` skips only the `lint` rule; it combines with `--json`, `--offline` and folder arguments, and with `--build`, but not with the `--baseline-*` flags or `--sync-hook`.
123
+
124
+ `--build` cannot be combined with `--baseline-init`, `--baseline-shrink`, `--baseline-accept`, `--baseline-adopt` or `--sync-hook`; with one of them it prints a usage message and exits 2. The exit codes are 0 for nothing new, 1 for a new finding and 2 for a usage or setup error.
125
+
71
126
  ## Token rules: counted per file
72
127
 
73
128
  The four rules read every tracked `.scss`, `.css`, `.cshtml`, `.jsx` and `.tsx` file, and each `.js` or
@@ -78,7 +133,7 @@ a plain `Email` folder of admin screens stays checked), a path containing `wwwro
78
133
  a `.min.css` name, a `.test.` or `.spec.` script, and any path the repo lists under `generated[].paths` in
79
134
  `.webority/map.json` (a trailing `/` names a folder; `*` matches within one segment). List a compiled
80
135
  stylesheet there: it bundles the shared theme, so its library rules are not the product's code, and the
81
- rules still read the SCSS it is built from. They also skip any path the repo lists under `fixtures` in the
136
+ rules still read the SCSS it is built from. They also skip a path the repo's root `.gitattributes` marks `linguist-generated` (for example `Webority.Canvas.Kits/** linguist-generated`; a later `-linguist-generated` line for a narrower path takes it back, as in Git; nested `.gitattributes` files are not read). They also skip any path the repo lists under `fixtures` in the
82
137
  same map, with the same pattern syntax (`"fixtures": ["corpus/"]`): a test fixture that imitates captured
83
138
  device output holds literal colours and sizes on purpose.
84
139
 
@@ -103,7 +158,7 @@ colours: one finding per read, and a declaration is not a read.
103
158
  `raw-motion` counts a non-zero time or an easing in the six properties `transition`, `transition-duration`,
104
159
  `transition-timing-function`, `animation`, `animation-duration` and `animation-timing-function`. Motion comes
105
160
  from the tokens `--wui-duration-fast`, `--wui-duration-default`, `--wui-duration-slow` and `--wui-ease-out`,
106
- `--wui-ease-in-out`, `--wui-ease-ui` and `--wui-ease-elastic`; a delay and a zero are not counted.
161
+ `--wui-ease-in-out`, `--wui-ease-ui`, `--wui-ease-elastic` and `--wui-ease-linear`; a delay and a zero are not counted.
107
162
 
108
163
  `dark-read` counts each read of the private dark tier (`var(--wui-dark-*)`). A dark band is a scope with
109
164
  `data-theme="dark"`, never a direct read, so a read of the dark tier stays dark in light mode.
@@ -120,9 +175,10 @@ src/assets/styles/_home.scss:12: color: var(--wui-primary);
120
175
 
121
176
  ## New rules start as warnings
122
177
 
123
- `lint`, `rn-mainactivity-oncreate-bundle`, `spa-host-immutable-assets` and `oversize` print as warnings and do not fail until
178
+ `lint`, `rn-mainactivity-oncreate-bundle`, `spa-host-immutable-assets`, `oversize`, `advisory`, `endpoint-name`, `api-call`, `api-thunk`, `screen-service-import`, `build-typecheck`, `library-copy`, `mobile-library-pin`, `root-file`, `web-folder`, `web-import-axios-types` and `tracking-plan` print as warnings and do not fail until
124
179
  `REPO_CHECKS_ENFORCE` names them: `REPO_CHECKS_ENFORCE=lint,rn-mainactivity-oncreate-bundle`, or `all`. A release
125
180
  removes a rule from the warning list when no repository has a hit. `--json` carries the warnings under `warnings`.
181
+ For `advisory` the severity decides: a `high` or `critical` advisory fails, and any other severity warns, whatever `REPO_CHECKS_ENFORCE` names.
126
182
 
127
183
  ## The advisory audit
128
184
 
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "npm": [
3
+ "@webority/api-contract",
3
4
  "@webority/biome-config",
4
5
  "@webority/canvas-kit",
5
6
  "@webority/insights-react",