@codefast/cli 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @codefast/cli
 
+## 0.13.0
+
+### Minor Changes
+
+- [#951](https://github.com/codefastlabs/codefast/pull/951) Add `codefast audit assertions`, which reports every double type assertion through `unknown` or `any` —
+  `x as unknown as T`, `(x as unknown) as T`, `<T><unknown>x` and the `any` spellings — in `.ts`/`.tsx` files, tests
+  included. Where the erasure is the point, keep one with `// codefast-allow-double-assertion: <reason>` on its line or
+  the line above; a directive with no reason, or one that keeps no assertion, is reported too. Exceptions can also go in
+  `audit.assertions.allowlist`.
+
+  `Filesystem.readdir` is replaced by `readdirEntries(path, { recursive })`, which always returns directory entries: every
+  caller asked for them, and the old `string[] | DirectoryEntry[]` union forced each one to cast or guard.
+
+- [#894](https://github.com/codefastlabs/codefast/pull/894) `codefast audit constants` reports every upper-case `const` bound to a number in a library's sources whose comment names
+  none of the three kinds a number may be — a constant of the machine, a value the contract fixes, or one derived from
+  bind-time data. Sentinel values (`0`, `1`, `-1`) are exempt; `audit.constants.target` and `audit.constants.allowlist` in
+  `codefast.config` scope and except it.
+
+- [#980](https://github.com/codefastlabs/codefast/pull/980) `audit publish` also reports a shipped stylesheet whose Tailwind `@source` paths reach none of the files the slimmed
+  tarball ships, naming any `files` entry missing on disk so an unbuilt `dist` reads as such. A workspace resolves those
+  paths against `src`, so only the published layout used to show the failure.
+
+- [#976](https://github.com/codefastlabs/codefast/pull/976) `engines.node` is now `>=24.0.0`, up from `>=22.12.0`, and Node 22 is no longer supported. Node 24.0.0 is the first
+  release with explicit resource management built in (`using`, `await using`, `DisposableStack`, `AsyncDisposableStack`,
+  `SuppressedError`) and all of ES2025, so the packages use both as the platform ships them instead of shimming them for
+  an older line, and the CI matrix runs the unit suite on 24.0.0 itself. Move to Node 24, or stay on the current minor
+  while a deployment still runs Node 22.
+
+### Patch Changes
+
+- [#965](https://github.com/codefastlabs/codefast/pull/965) The optional `typescript` peer is now `>=7.0.0`. It was published as the repository's own `^7.0.2` pin, which excluded
+  TypeScript 8 and would have risen with each pin bump instead of staying at the supported floor.
+
+- [#965](https://github.com/codefastlabs/codefast/pull/965) `README.md` now states TypeScript 7 or later as the floor for the package's types — the one compiler every `@codefast/*`
+  package is built and checked with. No code or declaration changed.
+
+## 0.12.0
+
+### Minor Changes
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Add `codefast audit publish`, a static publish-surface check. It flags `#/`-prefixed internal import specifiers — valid
+  to the in-repo runners but rejected by Node's ESM resolver on the supported floor, so they break the published package —
+  and any `exports`/`imports` target the slimmed publish manifest would not ship. It joins the `audit` family and gates
+  CI, replacing an external `publint` step.
+
+### Patch Changes
+
+- [#885](https://github.com/codefastlabs/codefast/pull/885) [`8580a2b`](https://github.com/codefastlabs/codefast/commit/8580a2b2dd9f502d7c330e5a2f0a3942041633b6) Thanks [@thevuong](https://github.com/thevuong)! - Match GitHub's heading-slug algorithm in `audit links`, so a cross-reference that resolves on GitHub resolves in the
+  audit.
+
+  Heading anchors are now slugged the way GitHub does: each space becomes its own hyphen with runs left intact,
+  underscores are kept as slug characters, and repeated headings gain `-1`, `-2`, … suffixes in heading order. The
+  previous slugger collapsed whitespace, dropped underscores, and offered only the base slug for duplicates, so a link a
+  browser lands on could be reported as dangling — the `@remarks` already claimed GitHub parity the code did not deliver.
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Lower the monorepo's Node floor from 24 to 22.12, so the packages install and run on the active Node 22 LTS line.
+
+  `engines.node` becomes `>=22.12.0` across every package — the floor the shared toolchain (oxlint, Vite, Vitest, TanStack
+  Start) already requires. Development stays on the latest Node (`.node-version`) for speed, and a CI matrix exercises the
+  floor and the active LTS directly, so the floor is a contract CI proves rather than one everyone has to run.
+  `@types/node` is pinned to the floor's major (`^22`), with a workspace override holding the whole tree there so a dev
+  tool's `@types/node: "*"` peer can no longer pull a newer major and mask an API the floor lacks. The floor stays
+  mechanical, not advisory: `@codefast/di` keeps its own `Map` upsert helpers rather than the ES2025
+  `Map.prototype.getOrInsert` (which would raise the floor to 26) and its `lib` stays `ES2024`. `@codefast/cli`'s mirror
+  step now calls the `node:path` functions directly instead of aliasing them, which the floor's types correctly flag as
+  unbound methods.
+
+  The shared `@codefast/typescript-config` presets pin `lib` and `target` to `ES2024` (was `ESNext`) so the compiler's
+  ECMAScript surface matches the Node floor: an ES2025 builtin such as `Map.prototype.getOrInsert` now fails to type-check
+  rather than compiling and crashing on Node 22.12. `@codefast/di` and `@codefast/di-testing` already pinned `lib` and are
+  unchanged.
+
+  Internal subpath imports move from a `#/` prefix to a bare `#` (`#core/token`, not `#/core/token`), and the
+  `package.json#imports` keys become `#*`/`#tests/*`/`#examples/*` to match. Node's native ESM resolver rejects a
+  `#/`-prefixed specifier with `ERR_INVALID_MODULE_SPECIFIER` on the whole Node 22 line (and on Node 24 before 24.14), and
+  each package ships those specifiers verbatim inside its published `dist/*.js` for a consumer's Node to resolve — so this
+  rename is what actually lets the packages import on the new floor. Purely internal: a consumer's own import paths are
+  unchanged.
+
+- [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Fix `pack-slim` stripping the stylesheet source of packages that export CSS.
+
+  `codefast pack-slim` removed the whole `src` directory from a package's published `files`, but `@codefast/ui` and
+  `@codefast/tracking` ship Tailwind source through `./css/*` → `./src/css/*`, so their published tarballs went out with
+  no CSS at all and the `./css/*` export resolved to nothing. pack-slim now keeps the `src` subtrees a surviving
+  `exports`/`imports` target still points into (e.g. `src/css`) and drops the rest of `src`, so the stylesheets ship while
+  the TypeScript source stays out. Surfaced and now guarded by the new `codefast audit publish` check.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -16,13 +16,15 @@ encode an opinionated house style (called out below) that you can adopt, ignore,
 
 - **Safe by default.** Every writing command supports `--dry-run`, and every audit is read-only except
   `audit comments --fix`.
-- **Scriptable.** `--json` prints one JSON object on stdout and suppresses the human progress output.
+- **Scriptable.** `--json` prints one JSON object on stdout instead of the human-readable output.
 - **CI-ready.** Audits exit non-zero when findings remain, so they gate a pipeline with no extra glue.
 - **Configurable.** An optional `codefast.config.*` file, validated by a strict schema, adjusts every command.
 
 ## Requirements
 
 - **Node.js ≥ 24** (the CLI is published as ESM).
+- **TypeScript ≥ 7** to type-check a config written with `defineConfig`, and for
+  `arrange simplify --fold-variant-classname`, the one command that loads `typescript` (an optional peer).
 - **A project root — workspace or single package.** Commands resolve their root by walking up from the current
   directory: the nearest `pnpm-workspace.yaml` marks a **workspace** (every package under it is in scope), and with no
   workspace file the nearest `package.json` marks a **single package** (that one package is the whole scope). Only
@@ -75,28 +77,84 @@ codefast audit links                               # find broken markdown cross-
   `codefast mirror --no-color`.
 - **Writing commands write by default; pass `--dry-run` to preview.** The audits are read-only — the one exception is
   `audit comments --fix`, which repairs section dividers in place.
-- **`--json` prints a single JSON object on stdout** and suppresses the human-readable progress output, so any command
-  can gate a script or a CI job.
+- **`--json` prints a single JSON object on stdout** instead of the human-readable output, so any command can gate a
+  script or a CI job.
+- **Set `CODEFAST_VERBOSE=1` (or `true`) for verbose error diagnostics.** On an unexpected infrastructure failure the
+  CLI also prints the underlying stack trace. This is distinct from `mirror --verbose`, which adds per-package progress
+  detail to that one command.
 
 ## Commands at a glance
 
+```text
+codefast                              # Codefast monorepo developer CLI
+│  ├─ --no-color                      # disable ANSI color output
+│  └─ --version
+│
+├─ arrange [target]                   # regroup Tailwind classes in cn()/tv() in render-pipeline order
+│  │   ├─ --dry-run                   # preview, without writing files
+│  │   ├─ --with-class-name           # append className as the final cn() argument (alias: --with-classname)
+│  │   ├─ --cn-import <spec>          # override the module specifier when adding a cn import
+│  │   └─ --json
+│  │
+│  ├─ inspect [target]                # report long strings, cn nested in tv() (read-only)
+│  │   └─ --json
+│  ├─ simplify [target]               # flatten grouped arrays & static cn() to plain strings in tv() slots
+│  │   ├─ --dry-run
+│  │   └─ --fold-variant-class-name   # fold cn() overrides into the variant's className option (uses the TS type server)
+│  └─ group <tokens...>               # group a pasted class string (stdout: cn(...) or a tv() array with --tv)
+│      ├─ --tv                        # emit a tv()-style array instead of a cn() call
+│      ├─ --with-class-name
+│      └─ --json
+│
+├─ audit                              # source audits (read-only source scans)
+│  ├─ rtl [target]                    # physical-direction Tailwind classes to make logical / rtl:-paired
+│  ├─ links [target]                  # markdown links pointing at a missing path/anchor
+│  ├─ imports [target]                # banned import forms (React by-name, Zod namespace in front-end, …)
+│  ├─ assertions [target]             # double type assertions through unknown/any (x as unknown as T)
+│  ├─ constants [target]              # numeric constants whose comment names none of the three kinds
+│  ├─ display-names [target]          # token()/tag()/module names breaking the <namespace>:<Name> convention
+│  ├─ publish [target]                # what breaks a consumer's install: #/ imports, unshipped targets, @source paths
+│  └─ comments [target]               # section dividers not in the one allowed form
+│      └─ --fix                       # rewrite every fixable divider in place (the only audit that writes)
+│      (each audit also takes [target] + --json)
+│
+├─ mirror [package]                   # write package.json#exports from dist/ for workspace packages
+│  ├─ --dry-run
+│  ├─ -v, --verbose
+│  └─ --json
+│
+├─ pack-slim [package]                # strip src, source conditions, dev-only scripts/devDeps, source maps before publish
+│  ├─ --dry-run
+│  ├─ --force                         # run even if the git working tree has uncommitted changes
+│  └─ --json
+│
+└─ tag [target]                       # add @since <version> to exported declarations
+   ├─ --dry-run
+   └─ --json
+```
+
+Every command also responds to `--help`; each command's section below explains what its flags do.
+
 | Command               | What it does                                                               | Writes?           |
 | --------------------- | -------------------------------------------------------------------------- | ----------------- |
 | `arrange`             | Regroup Tailwind classes in `cn()` / `tv()` calls in render-pipeline order | yes (`--dry-run`) |
 | `mirror`              | Write each package's `package.json#exports` from its built `dist/`         | yes (`--dry-run`) |
 | `pack-slim`           | Strip the dev-only surface from a package right before publish             | yes (`--dry-run`) |
 | `tag`                 | Stamp `@since <version>` on exported declarations that lack one            | yes (`--dry-run`) |
-| `audit links`         | Report markdown cross-references that resolve to nothing                   | no                |
 | `audit rtl`           | Report physical-direction Tailwind classes that should be logical          | no                |
+| `audit links`         | Report markdown cross-references that resolve to nothing                   | no                |
 | `audit imports`       | Enforce the import policy (React by-name, Zod namespace in front-end)      | no (report only)  |
-| `audit comments`      | Check doc-comment conventions; repair section dividers                     | `--fix` only      |
+| `audit assertions`    | Report double type assertions through `unknown` / `any`, tests included    | no                |
+| `audit constants`     | Require every tuned numeric constant to name the kind of number it is      | no                |
 | `audit display-names` | Enforce the `namespace:Name` display-name convention                       | no                |
+| `audit publish`       | Report what would break a consumer's install of a published package        | no                |
+| `audit comments`      | Check doc-comment conventions; repair section dividers                     | `--fix` only      |
 
-**Which of these are for you?** `arrange`, `mirror`, `pack-slim`, `tag`, and `audit links` are general-purpose — they
-work for any pnpm workspace or single package that builds with `tsc`. The other four audits encode codefast's own house
-style (logical Tailwind directions, named React imports, a specific comment/divider grammar, a `namespace:Name` scheme
-for `@codefast/di` tokens). Adopt them if they fit your project; otherwise skip them, or use an allowlist to narrow
-their scope.
+**Which of these are for you?** `arrange`, `mirror`, `pack-slim`, `tag`, `audit links`, `audit assertions`, and
+`audit publish` are general-purpose — they work for any pnpm workspace or single package that builds with `tsc`. The
+other five audits encode codefast's own house style (logical Tailwind directions, named React imports, a specific
+comment/divider grammar, a `namespace:Name` scheme for `@codefast/di` tokens, a named kind for every tuned numeric
+constant). Adopt them if they fit your project; otherwise skip them, or use an allowlist to narrow their scope.
 
 ## `arrange`
 
@@ -120,13 +178,6 @@ intentional; pass such a file explicitly to process it.
 `#lib/utils` re-export, any `…/utils` path, or a dedicated `cn.ts` module — so an unrelated local `cn` is left alone.
 Long static JSX `className` strings are regrouped regardless of where `cn` comes from.
 
-| Flag                 | Description                                                                   |
-| -------------------- | ----------------------------------------------------------------------------- |
-| `--dry-run`          | Preview suggested replacements without writing files.                         |
-| `--with-classname`   | Append `className` as the final `cn()` argument (alias: `--with-class-name`). |
-| `--cn-import <spec>` | Override the module specifier used when a missing `cn` import is added.       |
-| `--json`             | Print one JSON summary on stdout (suppresses human progress).                 |
-
 Exits `1` when the `arrange.onAfterWrite` hook fails, `0` otherwise.
 
 ### `arrange inspect [target]`
@@ -139,12 +190,6 @@ Flattens grouped arrays and static-only `cn()` calls back to plain strings in `t
 In a mixed `cn()` call it coalesces only _adjacent_ static literals and keeps argument order, so tailwind-merge
 precedence is unchanged (a later argument still overrides an earlier one).
 
-| Flag                       | Description                                                                                              |
-| -------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `--dry-run`                | Show what simplify would change without writing files.                                                   |
-| `--fold-variant-classname` | Fold `cn()` overrides into a variant function's `className` option (alias: `--fold-variant-class-name`). |
-| `--json`                   | Print one JSON summary on stdout.                                                                        |
-
 With `--fold-variant-classname`, `cn(buttonVariants({ size: "sm" }), "flex-1")` becomes
 `buttonVariants({ size: "sm", className: "flex-1" })`, and a dynamic or multi-part override folds into a `className`
 array. The fold fires only when the native TypeScript type server confirms the callee's options accept a `className` (or
@@ -162,11 +207,7 @@ codefast arrange group "relative flex h-10 w-full items-center rounded-md bg-pri
 codefast arrange group --tv "flex items-center gap-2"
 ```
 
-| Flag               | Description                                                                   |
-| ------------------ | ----------------------------------------------------------------------------- |
-| `--tv`             | Emit a `tv()`-style array instead of a `cn()` call.                           |
-| `--with-classname` | Append `className` as the final `cn()` argument (alias: `--with-class-name`). |
-| `--json`           | Emit `{ schemaVersion, primaryLine, bucketsCommentLine }` on stdout.          |
+With `--json`, that object is `{ schemaVersion, primaryLine, bucketsCommentLine }`.
 
 ## `mirror`
 
@@ -181,12 +222,6 @@ codefast mirror packages/ui     # one package (path relative to repo root)
 codefast mirror --dry-run       # report changes without writing
 ```
 
-| Flag              | Description                                                   |
-| ----------------- | ------------------------------------------------------------- |
-| `--dry-run`       | Report what would change without writing any `package.json`.  |
-| `-v`, `--verbose` | Print extra diagnostics.                                      |
-| `--json`          | Print one JSON summary on stdout (suppresses human progress). |
-
 Exits `1` when any package fails, `0` otherwise.
 
 ### Per-package `mirror` configuration
@@ -217,12 +252,13 @@ apply (see the [Configuration](#configuration) example for their shape):
 ## `pack-slim`
 
 Slims a published package down to what a consumer's `tsc` and Node actually read, so the npm tarball ships `dist`
-runtime and types only. Where `mirror` writes the full exports — including the `source` condition — for local
-development, `pack-slim` removes that development lane for publish: it drops `src` from `files`, every `source`
-condition from `exports`/`imports`, every `imports` entry left pointing outside `files`, every script that is not an
-install or publish lifecycle hook, `devDependencies`, and the `dist` source maps plus their dangling `sourceMappingURL`
-directives. Private packages are skipped. It is meant to run on an ephemeral CI checkout right before publish, so its
-result is **never committed**.
+runtime and types, plus any `src` subtree an export still points into (a raw stylesheet export such as `./css/*`). Where
+`mirror` writes the full exports — including the `source` condition — for local development, `pack-slim` removes that
+development lane for publish: it drops the rest of `src` from `files`, every `source` condition from
+`exports`/`imports`, every `imports` entry left pointing outside `files`, every script that is not an install or publish
+lifecycle hook, `devDependencies`, and the `dist` source maps plus their dangling `sourceMappingURL` directives. Private
+packages are skipped. It is meant to run on an ephemeral CI checkout right before publish, so its result is **never
+committed**.
 
 Because that result must never be committed, `pack-slim` refuses to write when the git working tree has uncommitted
 tracked changes — a guard against an accidental local run landing on real work. `--dry-run` is exempt (it writes
@@ -235,12 +271,6 @@ codefast pack-slim packages/ui     # one package (path relative to repo root)
 codefast pack-slim --dry-run       # report what would be stripped without touching a file
 ```
 
-| Flag        | Description                                                       |
-| ----------- | ----------------------------------------------------------------- |
-| `--dry-run` | Report what would be stripped without touching any file.          |
-| `--force`   | Run even if the git working tree has uncommitted tracked changes. |
-| `--json`    | Print one JSON summary on stdout (suppresses human progress).     |
-
 Exits `1` when any package fails, `0` otherwise.
 
 ## `tag`
@@ -256,11 +286,6 @@ codefast tag packages/ui/src   # tag one directory or file
 codefast tag --dry-run         # summary only, no writes
 ```
 
-| Flag        | Description                                                   |
-| ----------- | ------------------------------------------------------------- |
-| `--dry-run` | Show summary without writing files.                           |
-| `--json`    | Print one JSON summary on stdout (suppresses human progress). |
-
 Exits `1` when no target is selected, when any target fails, or when the `tag.onAfterWrite` hook fails.
 
 ## `audit`
@@ -316,6 +341,50 @@ codefast audit imports --json                # machine-readable summary
 Configure exceptions via `audit.imports.allowlist` — each entry is the offending source text as written or
 `repo/relative/path.tsx:<text>`.
 
+### `audit assertions`
+
+Reports every double type assertion through `unknown` or `any` in `.ts`/`.tsx` files, tests included —
+`x as unknown as T`, `(x as unknown) as T`, `<T><unknown>x` and the `any` spellings. The pair tells the compiler two
+types are unrelated and silences it anyway; no oxlint rule targets it (`typescript/no-unnecessary-type-assertion`
+catches the redundant ones only). Make the types agree, narrow with a type guard, or — where the erasure is the point —
+keep it with a directive that states why, on the assertion's line or the line above:
+
+```ts
+// codefast-allow-double-assertion: the host stores each plugin's config untyped; the plugin owns its shape
+const config = host.configFor(plugin.id) as unknown as PluginConfig;
+```
+
+A directive with no reason, or one that keeps no assertion, is itself reported, so a kept assertion cannot outlive its
+cause.
+
+```bash
+codefast audit assertions                  # whole repo
+codefast audit assertions packages/di      # explicit target
+codefast audit assertions --json           # machine-readable summary
+```
+
+Configure exceptions via `audit.assertions.allowlist` — each entry is the assertion as written or
+`repo/relative/path.ts:<assertion>` — though the inline directive keeps the reason beside the code it excuses.
+
+### `audit publish`
+
+Reports what would break a consumer's install of a published package, while it can still be fixed:
+
+- a `#/`-prefixed internal import, which Node's ESM resolver rejects on Node 24 before 24.14 while every in-repo runner
+  accepts it;
+- an `exports`/`imports` target the slimmed manifest does not ship, found by applying the same slim as `pack-slim`;
+- a shipped stylesheet whose Tailwind `@source` paths reach none of the files the tarball ships. A workspace still
+  resolves them against `src`, so only the published layout shows it: the consumer's Tailwind registers no class names
+  and the components render unstyled.
+
+It reads the built output, so run it after the build; a `files` entry missing on disk, such as an unbuilt `dist`, is
+named in the report. Private packages are skipped, and it takes no allowlist.
+
+```bash
+codefast audit publish                     # every published package in the workspace
+codefast audit publish --json              # machine-readable summary
+```
+
 ### `audit comments`
 
 _House style._ Checks doc-comment conventions. Section dividers not in the one allowed form are mechanical, so `--fix`
@@ -331,11 +400,6 @@ codefast audit comments --fix              # rewrite fixable dividers in place
 codefast audit comments --json             # machine-readable summary
 ```
 
-| Flag     | Description                                          |
-| -------- | ---------------------------------------------------- |
-| `--fix`  | Rewrite every mechanically fixable divider in place. |
-| `--json` | Print one JSON summary on stdout.                    |
-
 Configure exceptions via `audit.comments.allowlist` — each entry is a divider line as written or
 `repo/relative/path.ts:<divider>`.
 
@@ -356,6 +420,30 @@ codefast audit display-names --json                # machine-readable summary
 Configure exceptions via `audit.displayNames.allowlist` — each entry is the call as written, through its closing quote
 (or parenthesis when the name is the only argument), or `repo/relative/path.ts:<call>`.
 
+### `audit constants`
+
+_House style._ Holds library sources to one rule for tuned numbers: a numeric constant says which kind of number it is.
+It flags an upper-case `const NAME = <number>` in a `.ts`/`.tsx` file under a `src` directory — tests, benchmarks, apps,
+and examples are out of scope — unless the comment directly above it, a `/* … */` block or a run of `//` lines, names
+one of three kinds:
+
+- `a constant of the machine` — a width of the platform the code runs on;
+- `a value the contract fixes` — a number the documented contract promises;
+- `derived from bind-time data` — a figure computed from what a caller hands in.
+
+A count that merely looks reasonable is none of them, so it is reported. `0`, `1`, and `-1` are skipped: they stand for
+absence or identity, not for a tuned size.
+
+```bash
+codefast audit constants                   # uses audit.constants.target from config
+codefast audit constants packages/di/src   # explicit target
+codefast audit constants --json            # machine-readable summary
+```
+
+With no `[target]`, the scan root is `audit.constants.target` from the config; when neither is set the command fails.
+Configure exceptions via `audit.constants.allowlist` — each entry is the constant's name or `repo/relative/path.ts:NAME`
+— for a measured policy that has to stay a tuned number.
+
 ## Configuration
 
 **You do not need a config file.** Every command has sensible defaults and works with none. Add a `codefast.config.*`
@@ -489,7 +577,12 @@ export default {
     links: { allowlist: [] }, // bare link target, or `repo/relative/doc.md:target`
     comments: { allowlist: [] }, // divider as written, or `repo/relative/path.ts:<divider>`
     imports: { allowlist: [] }, // offending import text as written, or `repo/relative/path.tsx:<text>`
+    assertions: { allowlist: [] }, // assertion as written, or `repo/relative/path.ts:<assertion>`
     displayNames: { allowlist: [] }, // call as written, or `repo/relative/path.ts:<call>`
+    constants: {
+      target: "packages/core/src", // default scan root when no CLI arg is passed
+      allowlist: [], // constant name, or `repo/relative/path.ts:NAME`
+    },
   },
 };
 ```
@@ -540,7 +633,10 @@ pnpm run cli:audit:links            # codefast audit links
 pnpm run cli:audit:rtl              # codefast audit rtl
 pnpm run cli:audit:comments         # codefast audit comments
 pnpm run cli:audit:imports          # codefast audit imports
+pnpm run cli:audit:assertions       # codefast audit assertions
 pnpm run cli:audit:display-names    # codefast audit display-names
+pnpm run cli:audit:constants        # codefast audit constants
+pnpm run cli:audit:publish          # codefast audit publish
 ```
 
 `pnpm run version-packages` runs `changeset version` and then `codefast tag`, so published APIs are stamped at release,

package/dist/arrange/command.js

@@ -1,27 +1,27 @@
 import { Command } from "commander";
-import { formatArrangeGroupJsonOutput } from "#/arrange/group/cli-result";
-import { arrangeSuggestGroupsRequestSchema } from "#/arrange/group/cli-schema";
-import { presentArrangeGroupResult } from "#/arrange/group/output";
-import { suggestCnGroupsFromCli } from "#/arrange/group/suggest";
-import { formatArrangeAnalyzeJsonOutput } from "#/arrange/inspect/cli-result";
-import { arrangeAnalyzeDirectoryRequestSchema } from "#/arrange/inspect/cli-schema";
-import { presentAnalyzeReport } from "#/arrange/inspect/output";
-import { runArrangeInspect } from "#/arrange/inspect/run";
-import { prepareArrangeWorkspace } from "#/arrange/prepare";
-import { exitCodeForArrangeResult, formatArrangeJsonOutput } from "#/arrange/regroup/cli-result";
-import { arrangeRunRequestSchema } from "#/arrange/regroup/cli-schema";
-import { presentArrangeResult, presentGroupFilePreviewFromWork } from "#/arrange/regroup/output";
-import { runArrange } from "#/arrange/regroup/run";
-import { formatArrangeSimplifyJsonOutput } from "#/arrange/simplify/cli-result";
-import { arrangeSimplifyRunRequestSchema } from "#/arrange/simplify/cli-schema";
-import { presentSimplifyResult } from "#/arrange/simplify/output";
-import { runArrangeSimplify } from "#/arrange/simplify/run";
-import { applyCommandPipeline, registerPipelineSubcommand } from "#/core/cli/command-pipeline";
-import { consumeCliAppError } from "#/core/cli/result-handle";
-import { CLI_EXIT_SUCCESS } from "#/core/exit-codes";
-import { nodeFilesystem } from "#/core/filesystem/node";
-import { logger } from "#/core/logger";
-import { parseWithSchema } from "#/core/schema-parse";
+import { formatArrangeGroupJsonOutput } from "#arrange/group/cli-result";
+import { arrangeSuggestGroupsRequestSchema } from "#arrange/group/cli-schema";
+import { presentArrangeGroupResult } from "#arrange/group/output";
+import { suggestCnGroupsFromCli } from "#arrange/group/suggest";
+import { formatArrangeAnalyzeJsonOutput } from "#arrange/inspect/cli-result";
+import { arrangeAnalyzeDirectoryRequestSchema } from "#arrange/inspect/cli-schema";
+import { presentAnalyzeReport } from "#arrange/inspect/output";
+import { runArrangeInspect } from "#arrange/inspect/run";
+import { prepareArrangeWorkspace } from "#arrange/prepare";
+import { exitCodeForArrangeResult, formatArrangeJsonOutput } from "#arrange/regroup/cli-result";
+import { arrangeRunRequestSchema } from "#arrange/regroup/cli-schema";
+import { presentArrangeResult, presentGroupFilePreviewFromWork } from "#arrange/regroup/output";
+import { runArrange } from "#arrange/regroup/run";
+import { formatArrangeSimplifyJsonOutput } from "#arrange/simplify/cli-result";
+import { arrangeSimplifyRunRequestSchema } from "#arrange/simplify/cli-schema";
+import { presentSimplifyResult } from "#arrange/simplify/output";
+import { runArrangeSimplify } from "#arrange/simplify/run";
+import { applyCommandPipeline, registerPipelineSubcommand } from "#core/cli/command-pipeline";
+import { consumeCliAppError } from "#core/cli/result-handle";
+import { CLI_EXIT_SUCCESS } from "#core/exit-codes";
+import { nodeFilesystem } from "#core/filesystem/node";
+import { logger } from "#core/logger";
+import { parseWithSchema } from "#core/schema-parse";
 const targetHelp = "Directory or file (default: nearest package directory from cwd)";
 const prepareWorkspace = (fs, input) => prepareArrangeWorkspace(fs, { currentWorkingDirectory: input.currentWorkingDirectory, rawTarget: input.rawArg });
 const regroupPipeline = {
@@ -58,7 +58,6 @@ const inspectPipeline = {
     name: "inspect",
     description: "Report long strings, nested cn in tv(), and related findings (read-only)",
     positional: { name: "[target]", help: targetHelp },
-    jsonHelp: "Print one JSON object on stdout instead of a human report",
     schema: arrangeAnalyzeDirectoryRequestSchema,
     prepare: prepareWorkspace,
     buildRequest: ({ prelude }) => ({ analyzeRootPath: prelude.resolvedTarget }),
@@ -113,7 +112,7 @@ export function createArrangeCommand() {
         .argument("<tokens...>", "Class tokens (quote a single string if it contains spaces)")
         .option("--tv", "Emit tv()-style array instead of cn() call", false)
         .option("--with-classname, --with-class-name", "Append className as final cn() argument", false)
-        .option("--json", "Print one JSON object on stdout instead of plain lines", false)
+        .option("--json", "Print one JSON object on stdout instead of the human-readable output", false)
         .action(async (classTokenSeries, opts) => {
         const parsed = parseWithSchema(arrangeSuggestGroupsRequestSchema, {
             inlineClasses: classTokenSeries.join(" ").trim(),

package/dist/arrange/domain/ast/collectors-cn.d.ts

@@ -1,5 +1,5 @@
-import type { DomainAstNode } from "#/arrange/domain/ast/ast-node";
-import type { ForEachStringLiteralInClassExpressionOptions, TailwindClassLiteral } from "#/arrange/domain/types";
+import type { DomainAstNode } from "#arrange/domain/ast/ast-node";
+import type { ForEachStringLiteralInClassExpressionOptions, TailwindClassLiteral } from "#arrange/domain/types";
 /**
  * Visits every static class literal reachable inside a class expression.
  *

package/dist/arrange/domain/ast/collectors-cn.js

@@ -1,5 +1,5 @@
-import { DomainBinaryOperator, DomainSyntaxKind, isDomainArrayLiteralExpression, isDomainTailwindClassLiteral, } from "#/arrange/domain/ast/ast-node";
-import { MAX_CLASS_EXPR_DEPTH } from "#/arrange/domain/constants";
+import { DomainBinaryOperator, DomainSyntaxKind, isDomainArrayLiteralExpression, isDomainTailwindClassLiteral, } from "#arrange/domain/ast/ast-node";
+import { MAX_CLASS_EXPR_DEPTH } from "#arrange/domain/constants";
 /**
  * Visits every static class literal reachable inside a class expression.
  *

package/dist/arrange/domain/ast/collectors-jsx.d.ts

@@ -1,5 +1,5 @@
-import type { DomainJsxAttribute } from "#/arrange/domain/ast/ast-node";
-import type { JsxClassNameStatic } from "#/arrange/domain/types";
+import type { DomainJsxAttribute } from "#arrange/domain/ast/ast-node";
+import type { JsxClassNameStatic } from "#arrange/domain/types";
 /**
  * Extracts the static literal of a JSX `className` attribute, or `undefined` when it is not static.
  *

package/dist/arrange/domain/ast/collectors-jsx.js

@@ -1,4 +1,4 @@
-import { isDomainIdentifier, isDomainJsxExpression, isDomainTailwindClassLiteral } from "#/arrange/domain/ast/ast-node";
+import { isDomainIdentifier, isDomainJsxExpression, isDomainTailwindClassLiteral } from "#arrange/domain/ast/ast-node";
 /**
  * Extracts the static literal of a JSX `className` attribute, or `undefined` when it is not static.
  *

package/dist/arrange/domain/ast/collectors-tv.d.ts

@@ -1,5 +1,5 @@
-import type { DomainCallExpression, DomainObjectLiteralExpression, DomainSourceFile } from "#/arrange/domain/ast/ast-node";
-import type { StringNode, TailwindClassLiteral } from "#/arrange/domain/types";
+import type { DomainCallExpression, DomainObjectLiteralExpression, DomainSourceFile } from "#arrange/domain/ast/ast-node";
+import type { StringNode, TailwindClassLiteral } from "#arrange/domain/types";
 type StringNodeVisitor = (classLiteral: TailwindClassLiteral, sourceFile: DomainSourceFile, cnCall?: DomainCallExpression) => void;
 /**
  * Visits every class literal reachable inside a `tv({ ... })` object, including `cn()` arguments.

package/dist/arrange/domain/ast/collectors-tv.js

@@ -1,8 +1,8 @@
-import { isDomainArrayLiteralExpression, isDomainCallExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral, forEachDomainChild, } from "#/arrange/domain/ast/ast-node";
-import { CN_APPLY_LITERAL_WALK_OPTS, collectUnconditionalTailwindLiteralsFromCnArguments, forEachStringLiteralInClassExpression, isUnsafeLiteralForCnStyleApplySplit, } from "#/arrange/domain/ast/collectors-cn";
-import { buildKnownCnTvBindings, isCnOrTvIdentifier, propertyAssignmentNameText } from "#/arrange/domain/ast/helpers";
-import { APPLY_MIN_TOKENS, MAX_OBJECT_DEPTH } from "#/arrange/domain/constants";
-import { tokenizeClassString } from "#/arrange/domain/tailwind-token";
+import { isDomainArrayLiteralExpression, isDomainCallExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral, forEachDomainChild, } from "#arrange/domain/ast/ast-node";
+import { CN_APPLY_LITERAL_WALK_OPTS, collectUnconditionalTailwindLiteralsFromCnArguments, forEachStringLiteralInClassExpression, isUnsafeLiteralForCnStyleApplySplit, } from "#arrange/domain/ast/collectors-cn";
+import { buildKnownCnTvBindings, isCnOrTvIdentifier, propertyAssignmentNameText } from "#arrange/domain/ast/helpers";
+import { APPLY_MIN_TOKENS, MAX_OBJECT_DEPTH } from "#arrange/domain/constants";
+import { tokenizeClassString } from "#arrange/domain/tailwind-token";
 /**
  * Visits every class literal reachable inside a `tv({ ... })` object, including `cn()` arguments.
  *

package/dist/arrange/domain/ast/helpers.d.ts

@@ -1,5 +1,5 @@
-import type { DomainAstNode, DomainCallExpression, DomainPropertyAssignment, DomainSourceFile } from "#/arrange/domain/ast/ast-node";
-import { applyEditsDescending } from "#/core/source-text-edit";
+import type { DomainAstNode, DomainCallExpression, DomainPropertyAssignment, DomainSourceFile } from "#arrange/domain/ast/ast-node";
+import { applyEditsDescending } from "#core/source-text-edit";
 /**
  * Builds a set of local binding names that are imported from a known cn/tv
  * module in `sourceFile`.

package/dist/arrange/domain/ast/helpers.js

@@ -1,6 +1,6 @@
-import { isDomainIdentifier, isDomainImportDeclaration, isDomainNamedImports, isDomainNamespaceImport, isDomainPropertyAccessExpression, isDomainStringLiteral, lineOfSourcePosition, } from "#/arrange/domain/ast/ast-node";
-import { EMPTY_CN_TV_BINDINGS } from "#/arrange/domain/constants";
-import { applyEditsDescending, indentOfLineContaining } from "#/core/source-text-edit";
+import { isDomainIdentifier, isDomainImportDeclaration, isDomainNamedImports, isDomainNamespaceImport, isDomainPropertyAccessExpression, isDomainStringLiteral, lineOfSourcePosition, } from "#arrange/domain/ast/ast-node";
+import { EMPTY_CN_TV_BINDINGS } from "#arrange/domain/constants";
+import { applyEditsDescending, indentOfLineContaining } from "#core/source-text-edit";
 /**
  * Known module specifiers that export `cn` / `tv`.
  */
@@ -12,7 +12,6 @@ const KNOWN_CN_TV_MODULES = new Set([
     // from "tailwind-variants"; new code should prefer "@codefast/tailwind-variants".
     "tailwind-variants",
     "#lib/utils",
-    "#/lib/utils",
     "~/lib/utils",
     "@/lib/utils",
 ]);

package/dist/arrange/domain/ast/simplify-targets.d.ts

@@ -1,4 +1,4 @@
-import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+import type { DomainSourceFile } from "#arrange/domain/ast/ast-node";
 /**
  * A planned text replacement produced by the simplify pass.
  *

package/dist/arrange/domain/ast/simplify-targets.js

@@ -1,8 +1,8 @@
-import { forEachDomainChild, isDomainArrayLiteralExpression, isDomainCallExpression, isDomainJsxAttribute, isDomainJsxExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral, } from "#/arrange/domain/ast/ast-node";
-import { buildKnownCnTvBindings, isCnOrTvIdentifier } from "#/arrange/domain/ast/helpers";
-import { MAX_OBJECT_DEPTH } from "#/arrange/domain/constants";
-import { escapeTsStringLiteralContent } from "#/arrange/domain/source-text-formatters";
-import { indentOfLineContaining } from "#/core/source-text-edit";
+import { forEachDomainChild, isDomainArrayLiteralExpression, isDomainCallExpression, isDomainJsxAttribute, isDomainJsxExpression, isDomainObjectLiteralExpression, isDomainPropertyAssignment, isDomainSpreadElement, isDomainTailwindClassLiteral, } from "#arrange/domain/ast/ast-node";
+import { buildKnownCnTvBindings, isCnOrTvIdentifier } from "#arrange/domain/ast/helpers";
+import { MAX_OBJECT_DEPTH } from "#arrange/domain/constants";
+import { escapeTsStringLiteralContent } from "#arrange/domain/source-text-formatters";
+import { indentOfLineContaining } from "#core/source-text-edit";
 function toFlatString(text) {
     return `"${escapeTsStringLiteralContent(text.trim())}"`;
 }

package/dist/arrange/domain/ast/targets.d.ts

@@ -1,5 +1,5 @@
-import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
-import type { GroupTarget, PlannedGroupEdit } from "#/arrange/domain/types";
+import type { DomainSourceFile } from "#arrange/domain/ast/ast-node";
+import type { GroupTarget, PlannedGroupEdit } from "#arrange/domain/types";
 /**
  * Resolves the source position where a group target's replacement begins.
  *