@codefast/cli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @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

package/README.md

@@ -22,7 +22,9 @@ encode an opinionated house style (called out below) that you can adopt, ignore,
 
 ## Requirements
 
-- **Node.js ≥ 22.12** (the CLI is published as ESM).
+- **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
@@ -108,7 +110,10 @@ codefast                              # Codefast monorepo developer CLI
 │  ├─ 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)
@@ -139,14 +144,17 @@ Every command also responds to `--help`; each command's section below explains w
 | `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 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`
 
@@ -244,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
@@ -332,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`
@@ -367,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.*`
@@ -500,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`
+    },
   },
 };
 ```
@@ -551,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/domain/ast/translator.js

@@ -4,9 +4,26 @@
  */
 import { parseSync } from "oxc-parser";
 import { DomainBinaryOperator, DomainSyntaxKind } from "#arrange/domain/ast/ast-node";
-function isOxcNode(value) {
-    return typeof value === "object" && value !== null && typeof value.type === "string";
-}
+import { isOxcNode, programStatements } from "#core/oxc-node";
+/**
+ * Stands in for a child while its parent is built first, so the child has a parent to point at; the
+ * build replaces it before the node leaves the translator.
+ */
+const PENDING_NODE = Object.freeze({
+    kind: DomainSyntaxKind.Unknown,
+    pos: -1,
+    end: -1,
+    parent: null,
+    children: [],
+});
+/** The same stand-in for a child typed as an identifier. */
+const PENDING_IDENTIFIER = Object.freeze({
+    kind: DomainSyntaxKind.Identifier,
+    pos: -1,
+    end: -1,
+    parent: null,
+    text: "",
+});
 function nodeName(node) {
     return typeof node.name === "string" ? node.name : "";
 }
@@ -87,15 +104,13 @@ export class TypeScriptAstTranslator {
             end: node.end,
             parent,
             importClause: undefined,
-            moduleSpecifier: undefined,
+            moduleSpecifier: PENDING_NODE,
         };
         if (specifiers.length > 0) {
             self.importClause = this.buildImportClause(node, specifiers, self);
         }
         const source = isOxcNode(node.source) ? node.source : undefined;
-        self.moduleSpecifier = source
-            ? this.translateNode(source, self)
-            : this.translateUnknown(node, self);
+        self.moduleSpecifier = source ? this.translateNode(source, self) : this.translateUnknown(node, self);
         return self;
     }
     buildImportClause(declaration, specifiers, parent) {
@@ -131,7 +146,7 @@ export class TypeScriptAstTranslator {
             pos: specifier.start,
             end: specifier.end,
             parent,
-            name: undefined,
+            name: PENDING_IDENTIFIER,
         };
         self.name = this.translateIdentifier(local, self);
         return self;
@@ -158,7 +173,7 @@ export class TypeScriptAstTranslator {
             end: specifier.end,
             parent,
             propertyName: undefined,
-            name: undefined,
+            name: PENDING_IDENTIFIER,
         };
         if (imported && imported.type === "Identifier" && nodeName(imported) !== nodeName(local)) {
             self.propertyName = this.translateIdentifier(imported, self);
@@ -220,7 +235,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                     arguments: [],
                 };
                 self.expression = this.translateNode(callee, self);
@@ -238,8 +253,8 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
-                    name: undefined,
+                    expression: PENDING_NODE,
+                    name: PENDING_IDENTIFIER,
                 };
                 self.expression = this.translateNode(object, self);
                 self.name = this.translateNode(property, self);
@@ -273,8 +288,8 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    name: undefined,
-                    initializer: undefined,
+                    name: PENDING_NODE,
+                    initializer: PENDING_NODE,
                 };
                 self.name = this.translateNode(key, self);
                 self.initializer = this.translateNode(value, self);
@@ -305,7 +320,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                 };
                 self.expression = this.translateNode(argument, self);
                 return self;
@@ -317,7 +332,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                 };
                 self.expression = this.translateNode(expression, self);
                 return self;
@@ -329,7 +344,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                 };
                 self.expression = this.translateNode(expression, self);
                 return self;
@@ -341,7 +356,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                 };
                 self.expression = this.translateNode(expression, self);
                 return self;
@@ -353,7 +368,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                 };
                 self.expression = this.translateNode(expression, self);
                 return self;
@@ -367,9 +382,9 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    condition: undefined,
-                    whenTrue: undefined,
-                    whenFalse: undefined,
+                    condition: PENDING_NODE,
+                    whenTrue: PENDING_NODE,
+                    whenFalse: PENDING_NODE,
                 };
                 self.condition = this.translateNode(test, self);
                 self.whenTrue = this.translateNode(consequent, self);
@@ -384,9 +399,9 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    left: undefined,
+                    left: PENDING_NODE,
                     operator: this.mapBinaryOperator(node.operator),
-                    right: undefined,
+                    right: PENDING_NODE,
                 };
                 self.left = this.translateNode(left, self);
                 self.right = this.translateNode(right, self);
@@ -399,7 +414,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    expression: undefined,
+                    expression: PENDING_NODE,
                 };
                 self.expression = this.translateNode(expression, self);
                 return self;
@@ -412,7 +427,7 @@ export class TypeScriptAstTranslator {
                     pos,
                     end,
                     parent,
-                    name: undefined,
+                    name: PENDING_NODE,
                     initializer: undefined,
                 };
                 self.name = this.translateNode(name, self);
@@ -442,8 +457,7 @@ export class TypeScriptAstTranslator {
     parseDomainSourceFile(filePath, sourceText) {
         // Best-effort parse to mirror `ts.createSourceFile` leniency — recoverable syntax
         // errors still yield a usable tree, so `parseSync` errors are intentionally ignored.
-        const program = parseSync(filePath, sourceText).program;
-        const statements = program.body.map((statement) => this.translateNode(statement, null));
+        const statements = programStatements(parseSync(filePath, sourceText).program).map((statement) => this.translateNode(statement, null));
         return {
             fileName: filePath,
             text: sourceText,

package/dist/arrange/simplify/process-file.d.ts

@@ -6,7 +6,7 @@ import type { Filesystem } from "#core/filesystem/filesystem";
  *
  * @since 0.3.16-canary.0
  */
-export declare function processArrangeSimplifyFile(fs: Filesystem, args: {
+export declare function processArrangeSimplifyFile(fs: Pick<Filesystem, "readFileSync" | "writeFileSync">, args: {
     readonly filePath: string;
     readonly write: boolean;
     readonly probe?: VariantClassNameProbe | null;

package/dist/audit/assertions/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { AssertionAuditResult } from "#audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted type-assertion violation remains.
+ *
+ * @since 0.13.0
+ */
+export declare function exitCodeForAssertionAuditResult(result: AssertionAuditResult): number;
+/**
+ * Machine-readable type-assertion summary for `--json`.
+ *
+ * @since 0.13.0
+ */
+export declare function formatAssertionAuditJsonOutput(result: AssertionAuditResult, rootDir: string): string;

package/dist/audit/assertions/cli-result.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
+/**
+ * Exit `1` when any non-allowlisted type-assertion violation remains.
+ *
+ * @since 0.13.0
+ */
+export function exitCodeForAssertionAuditResult(result) {
+    return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Machine-readable type-assertion summary for `--json`.
+ *
+ * @since 0.13.0
+ */
+export function formatAssertionAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.violationCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}

package/dist/audit/assertions/cli-schema.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod";
+/**
+ * Resolved request for a single type-assertion audit run.
+ *
+ * @since 0.13.0
+ */
+export type AssertionAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link AssertionAuditRunRequest}.
+ *
+ * @since 0.13.0
+ */
+export declare const assertionAuditRunRequestSchema: z.ZodType<AssertionAuditRunRequest>;

package/dist/audit/assertions/cli-schema.js

@@ -0,0 +1,12 @@
+import * as z from "zod";
+/**
+ * Zod schema for {@link AssertionAuditRunRequest}.
+ *
+ * @since 0.13.0
+ */
+export const assertionAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});

package/dist/audit/assertions/domain/double-assertion.d.ts

@@ -0,0 +1,20 @@
+import type { AssertionViolation } from "#audit/domain/types";
+/**
+ * The comment that keeps one double assertion, with the reason it has to stay.
+ *
+ * @remarks It covers an assertion on its own line or the line below it, and must carry a reason
+ * after the colon; one that covers nothing is reported, so a kept assertion cannot outlive its cause.
+ *
+ * @since 0.13.0
+ */
+export declare const DOUBLE_ASSERTION_DIRECTIVE = "codefast-allow-double-assertion";
+/**
+ * Scans one TypeScript source for double assertions through `unknown` or `any`, and for directives
+ * that keep none or give no reason.
+ *
+ * @remarks `x as unknown as T`, `(x as unknown) as T` and `<T><unknown>x` are one shape: the
+ * compiler found the two types unrelated, and the pair silences it instead of reconciling them.
+ *
+ * @since 0.13.0
+ */
+export declare function auditDoubleAssertionSource(filePath: string, sourceText: string): Array<AssertionViolation>;

package/dist/audit/assertions/domain/double-assertion.js

@@ -0,0 +1,122 @@
+import { parseSync } from "oxc-parser";
+import { isOxcNode } from "#core/oxc-node";
+import { firstLineOf, lineOfOffset } from "#core/source-position";
+/**
+ * The comment that keeps one double assertion, with the reason it has to stay.
+ *
+ * @remarks It covers an assertion on its own line or the line below it, and must carry a reason
+ * after the colon; one that covers nothing is reported, so a kept assertion cannot outlive its cause.
+ *
+ * @since 0.13.0
+ */
+export const DOUBLE_ASSERTION_DIRECTIVE = "codefast-allow-double-assertion";
+const DOUBLE_ASSERTION_REASON = "double assertion through `unknown`/`any` — make the types agree, narrow with a type guard, or keep it " +
+    `with // ${DOUBLE_ASSERTION_DIRECTIVE}: <reason>`;
+// Most files hold neither, so a text probe spares them the parse.
+const CANDIDATE_TEXT = new RegExp(`\\bas\\s+(?:unknown|any)\\b|<(?:unknown|any)>|${DOUBLE_ASSERTION_DIRECTIVE}`);
+function isAssertion(node) {
+    return node.type === "TSAsExpression" || node.type === "TSTypeAssertion";
+}
+/** The assertion an outer one wraps, through any parentheses, when it erases to `unknown` or `any`. */
+function erasingInnerAssertion(outer) {
+    let inner = outer.expression;
+    while (isOxcNode(inner) && inner.type === "ParenthesizedExpression") {
+        inner = inner.expression;
+    }
+    if (!isOxcNode(inner) || !isAssertion(inner) || !isOxcNode(inner.typeAnnotation)) {
+        return undefined;
+    }
+    const erasedTo = inner.typeAnnotation.type;
+    return erasedTo === "TSUnknownKeyword" || erasedTo === "TSAnyKeyword" ? inner : undefined;
+}
+function collectDoubleAssertions(node, found) {
+    let next = node;
+    if (isAssertion(node)) {
+        const inner = erasingInnerAssertion(node);
+        if (inner !== undefined) {
+            found.push(node);
+            // The erased pair is one finding; what it wraps is walked on its own.
+            next = inner;
+        }
+    }
+    for (const value of Object.values(next)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (isOxcNode(item)) {
+                    collectDoubleAssertions(item, found);
+                }
+            }
+        }
+        else if (isOxcNode(value)) {
+            collectDoubleAssertions(value, found);
+        }
+    }
+}
+function parseDirective(sourceText, comment) {
+    if (comment.type !== "Line") {
+        return undefined;
+    }
+    const text = comment.value.trim();
+    if (!text.startsWith(DOUBLE_ASSERTION_DIRECTIVE)) {
+        return undefined;
+    }
+    const reason = /^:\s*(\S.*)$/.exec(text.slice(DOUBLE_ASSERTION_DIRECTIVE.length))?.[1] ?? "";
+    return {
+        line: lineOfOffset(sourceText, comment.start),
+        raw: sourceText.slice(comment.start, comment.end),
+        reason,
+        isUsed: false,
+    };
+}
+/**
+ * Scans one TypeScript source for double assertions through `unknown` or `any`, and for directives
+ * that keep none or give no reason.
+ *
+ * @remarks `x as unknown as T`, `(x as unknown) as T` and `<T><unknown>x` are one shape: the
+ * compiler found the two types unrelated, and the pair silences it instead of reconciling them.
+ *
+ * @since 0.13.0
+ */
+export function auditDoubleAssertionSource(filePath, sourceText) {
+    if (!CANDIDATE_TEXT.test(sourceText)) {
+        return [];
+    }
+    const { program, comments } = parseSync(filePath, sourceText);
+    const directives = comments.map((comment) => parseDirective(sourceText, comment)).filter((d) => d !== undefined);
+    const found = [];
+    if (isOxcNode(program)) {
+        collectDoubleAssertions(program, found);
+    }
+    const violations = [];
+    for (const assertion of found) {
+        const line = lineOfOffset(sourceText, assertion.start);
+        const directive = directives.find((candidate) => candidate.reason !== "" && (candidate.line === line || candidate.line === line - 1));
+        if (directive !== undefined) {
+            directive.isUsed = true;
+            continue;
+        }
+        violations.push({
+            line,
+            raw: firstLineOf(sourceText.slice(assertion.start, assertion.end)),
+            reason: DOUBLE_ASSERTION_REASON,
+        });
+    }
+    for (const directive of directives) {
+        if (directive.reason === "") {
+            violations.push({
+                line: directive.line,
+                raw: directive.raw,
+                reason: `a ${DOUBLE_ASSERTION_DIRECTIVE} directive states why after a colon`,
+            });
+        }
+        else if (!directive.isUsed) {
+            violations.push({
+                line: directive.line,
+                raw: directive.raw,
+                reason: `this ${DOUBLE_ASSERTION_DIRECTIVE} directive keeps no double assertion — remove it`,
+            });
+        }
+    }
+    violations.sort((a, b) => a.line - b.line);
+    return violations;
+}

package/dist/audit/assertions/output.d.ts

@@ -0,0 +1,7 @@
+import type { AssertionAuditResult } from "#audit/domain/types";
+/**
+ * Human-readable type-assertion report.
+ *
+ * @since 0.13.0
+ */
+export declare function presentAssertionAuditResult(result: AssertionAuditResult): void;

package/dist/audit/assertions/output.js

@@ -0,0 +1,21 @@
+import { logger } from "#core/logger";
+/**
+ * Human-readable type-assertion report.
+ *
+ * @since 0.13.0
+ */
+export function presentAssertionAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.violations) {
+            logger.out(`  ${line}: ${raw} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.violationCount > 0) {
+        logger.out(`\n✖ ${result.violationCount} type-assertion violation(s)${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ No double assertions across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
+    }
+}