@codefast/cli 0.8.1 → 0.10.0

package/dist/audit/domain/import-policy.d.ts

@@ -0,0 +1,34 @@
+import type { ImportPolicyViolation } from "#/audit/domain/types";
+/**
+ * One library's import policy: which forms of importing `module` are banned, optionally limited to
+ * files whose repo-relative path matches `scope`, plus an optional UMD-global name to flag when the
+ * file references `<name>.*` without importing it.
+ *
+ * @since 0.10.0
+ */
+export interface ImportPolicyRule {
+    readonly module: string;
+    /** Banned forms: `namespace` (`import * as x`), `default` (`import x`), or `named:<name>`. */
+    readonly ban: ReadonlyArray<"namespace" | "default" | `named:${string}`>;
+    readonly scope?: ReadonlyArray<string> | undefined;
+    readonly umdGlobal?: string | undefined;
+    readonly message: string;
+}
+/**
+ * The import policies enforced across the monorepo: React members by name (never a namespace,
+ * default, or implicit `React.*` UMD global), and Zod as a namespace in front-end packages so
+ * bundlers can tree-shake it (a named `import { z }` pins Zod's full locale set into the bundle).
+ *
+ * @since 0.10.0
+ */
+export declare const defaultImportPolicyRules: ReadonlyArray<ImportPolicyRule>;
+/**
+ * Scans one TypeScript source against the given import-policy rules and returns the violations.
+ *
+ * @remarks Each rule matches import declarations from its `module` and flags the banned forms;
+ * a rule with `umdGlobal` additionally flags implicit `<name>.*` type references when nothing in
+ * the file imports that name (the case tsc accepts silently through a UMD `export as namespace`).
+ *
+ * @since 0.10.0
+ */
+export declare function auditImportPolicySource(filePath: string, sourceText: string, rules: ReadonlyArray<ImportPolicyRule>): Array<ImportPolicyViolation>;

package/dist/audit/domain/import-policy.js

@@ -0,0 +1,147 @@
+import { parseSync } from "oxc-parser";
+/**
+ * The import policies enforced across the monorepo: React members by name (never a namespace,
+ * default, or implicit `React.*` UMD global), and Zod as a namespace in front-end packages so
+ * bundlers can tree-shake it (a named `import { z }` pins Zod's full locale set into the bundle).
+ *
+ * @since 0.10.0
+ */
+export const defaultImportPolicyRules = [
+    {
+        module: "react",
+        ban: ["namespace", "default"],
+        umdGlobal: "React",
+        message: 'import React members by name from "react"',
+    },
+    {
+        module: "zod",
+        ban: ["named:z"],
+        scope: [
+            "packages/theme/**",
+            "packages/ui/**",
+            "packages/tailwind-variants/**",
+            "apps/web/**",
+            "examples/*/**",
+            "internal/benchmark-viewer/**",
+        ],
+        message: 'import Zod as a namespace so bundlers can tree-shake it: import * as z from "zod"',
+    },
+];
+function isOxcNode(value) {
+    return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function isIdentifierNamed(node, name) {
+    return isOxcNode(node) && node.type === "Identifier" && node.name === name;
+}
+function importedName(specifier) {
+    const imported = specifier.imported;
+    return isOxcNode(imported) && typeof imported.name === "string" ? imported.name : undefined;
+}
+/**
+ * Scans one TypeScript source against the given import-policy rules and returns the violations.
+ *
+ * @remarks Each rule matches import declarations from its `module` and flags the banned forms;
+ * a rule with `umdGlobal` additionally flags implicit `<name>.*` type references when nothing in
+ * the file imports that name (the case tsc accepts silently through a UMD `export as namespace`).
+ *
+ * @since 0.10.0
+ */
+export function auditImportPolicySource(filePath, sourceText, rules) {
+    const { program } = parseSync(filePath, sourceText);
+    const statements = program.body;
+    const violations = [];
+    const boundUmdNames = new Set();
+    for (const rule of rules) {
+        const bannedNamed = new Set();
+        let banNamespace = false;
+        let banDefault = false;
+        for (const form of rule.ban) {
+            if (form === "namespace") {
+                banNamespace = true;
+            }
+            else if (form === "default") {
+                banDefault = true;
+            }
+            else {
+                bannedNamed.add(form.slice("named:".length));
+            }
+        }
+        for (const statement of statements) {
+            if (statement.type !== "ImportDeclaration") {
+                continue;
+            }
+            const source = statement.source;
+            if (!isOxcNode(source) || source.value !== rule.module) {
+                continue;
+            }
+            const specifiers = Array.isArray(statement.specifiers) ? statement.specifiers.filter(isOxcNode) : [];
+            const umdGlobal = rule.umdGlobal;
+            if (umdGlobal !== undefined && specifiers.some((specifier) => isIdentifierNamed(specifier.local, umdGlobal))) {
+                boundUmdNames.add(umdGlobal);
+            }
+            for (const specifier of specifiers) {
+                if (banNamespace && specifier.type === "ImportNamespaceSpecifier") {
+                    violations.push(violationAt(sourceText, statement, `namespace import of "${rule.module}" — ${rule.message}`));
+                }
+                else if (banDefault && specifier.type === "ImportDefaultSpecifier") {
+                    violations.push(violationAt(sourceText, statement, `default import of "${rule.module}" — ${rule.message}`));
+                }
+                else if (specifier.type === "ImportSpecifier") {
+                    const name = importedName(specifier);
+                    if (name !== undefined && bannedNamed.has(name)) {
+                        violations.push(violationAt(sourceText, statement, `named import { ${name} } from "${rule.module}" — ${rule.message}`));
+                    }
+                }
+            }
+        }
+    }
+    for (const rule of rules) {
+        if (rule.umdGlobal !== undefined && !boundUmdNames.has(rule.umdGlobal)) {
+            collectUmdGlobalReferences(program, sourceText, rule, violations);
+        }
+    }
+    violations.sort((a, b) => a.line - b.line);
+    return violations;
+}
+function violationAt(sourceText, statement, reason) {
+    return {
+        line: lineOfOffset(sourceText, statement.start),
+        raw: firstLineOf(sourceText.slice(statement.start, statement.end)),
+        reason,
+    };
+}
+function collectUmdGlobalReferences(node, sourceText, rule, violations) {
+    if (node.type === "TSQualifiedName" && isIdentifierNamed(node.left, rule.umdGlobal ?? "")) {
+        violations.push({
+            line: lineOfOffset(sourceText, node.start),
+            raw: sourceText.slice(node.start, node.end),
+            reason: `implicit ${rule.umdGlobal}.* UMD global — ${rule.message}`,
+        });
+        return;
+    }
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (isOxcNode(item)) {
+                    collectUmdGlobalReferences(item, sourceText, rule, violations);
+                }
+            }
+        }
+        else if (isOxcNode(value)) {
+            collectUmdGlobalReferences(value, sourceText, rule, violations);
+        }
+    }
+}
+function lineOfOffset(sourceText, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (sourceText.charCodeAt(index) === 10) {
+            line++;
+        }
+    }
+    return line;
+}
+function firstLineOf(text) {
+    const newlineIndex = text.indexOf("\n");
+    return newlineIndex === -1 ? text : text.slice(0, newlineIndex);
+}

package/dist/audit/domain/link-references.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolves `{@link}` references against the scanned tree, so a rename that orphans one is caught.
+ */
+/**
+ * One `{@link}` occurrence found inside a comment.
+ *
+ * @since 0.6.0
+ */
+export interface LinkReference {
+    readonly line: number;
+    /** The target as written, e.g. `writeJsonlRun`, `Foo.bar`, `../fixtures/adapter.ts`. */
+    readonly target: string;
+}
+/**
+ * Every `{@link}` target in a file's comments, in source order.
+ *
+ * @since 0.6.0
+ */
+export declare function scanLinkReferences(content: string): Array<LinkReference>;
+/**
+ * The identifier a declaration-style target must resolve through — `Foo.bar` resolves via `Foo`.
+ *
+ * @since 0.6.0
+ */
+export declare function linkTargetHead(target: string): string;
+/**
+ * Whether a target names a file or URL rather than a declaration.
+ *
+ * @since 0.6.0
+ */
+export declare function isPathLinkTarget(target: string): boolean;
+/**
+ * Counts word-boundary occurrences of each head across a body of source text.
+ *
+ * @remarks A `{@link X}` occurrence itself mentions `X` once, so a target is orphaned when its
+ * total mentions do not exceed its link occurrences — a rename removes every real mention.
+ *
+ * @since 0.6.0
+ */
+export declare function countHeadMentions(contents: Iterable<string>, heads: ReadonlySet<string>): Map<string, number>;

package/dist/audit/domain/mappings.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Physical → logical replacements. Order matters: negative before positive,
+ * specific corners before general edges, with-value before bare.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const RTL_MAPPINGS: ReadonlyArray<readonly [string, string]>;
+/**
+ * translate-x has no logical equivalent — it needs an rtl:-negated twin.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const RTL_TRANSLATE_X_MAPPINGS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Classes that need an rtl:*-reverse companion.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const RTL_REVERSE_MAPPINGS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Classes that need an rtl: companion with the swapped value.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const RTL_SWAP_MAPPINGS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Anything anchored to a physical side variant stays physical: Radix resolves
+ * `side` per direction, and a border/position/slide tied to that side must follow it.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const PHYSICAL_SIDE_VARIANT: RegExp;
+/**
+ * Slide animations under direction-resolved contexts are correct as-is:
+ * Radix flips `side`/`motion` values itself under DirectionProvider.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const DIRECTION_RESOLVED_VARIANT: RegExp;
+/**
+ * The physical slide-animation class prefixes the RTL audit inspects.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const SLIDE_PREFIXES: readonly ["slide-in-from-left", "slide-in-from-right", "slide-out-to-left", "slide-out-to-right"];

package/dist/audit/domain/markdown-links.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Extracts the two things a markdown cross-reference can get wrong: where it points and what it lands on.
+ */
+/**
+ * One `[text](target)` whose target is a path in this repository.
+ *
+ * @since 0.5.0
+ */
+type MarkdownLinkReference = {
+    readonly line: number;
+    /** The path as written, with any fragment stripped. Empty when the link is fragment-only. */
+    readonly targetPath: string;
+    /** The `#fragment`, without the hash, or `null`. */
+    readonly anchor: string | null;
+};
+/**
+ * The anchors a document offers, and the references it makes.
+ *
+ * @since 0.5.0
+ */
+export type MarkdownLinkScan = {
+    readonly references: ReadonlyArray<MarkdownLinkReference>;
+    readonly anchors: ReadonlySet<string>;
+};
+/**
+ * The anchor ids a rendered document exposes: explicit `<a id>` targets plus every heading's slug.
+ *
+ * @remarks Slugging matches GitHub's — lowercase, drop everything that is not a letter, number, space
+ * or hyphen, then hyphenate spaces. Duplicate headings get a `-1` suffix there; this returns the base
+ * only, so a link to the second copy reads as dangling rather than being silently accepted.
+ *
+ * @since 0.5.0
+ */
+export declare function collectMarkdownAnchors(content: string): Set<string>;
+/**
+ * Every repo-local link a document makes, with the anchors it offers.
+ *
+ * @remarks Fenced code is stripped first: a fence showing a link is an example, not a reference, and
+ * checking it would make the audit fail on documentation that is doing its job.
+ *
+ * @since 0.5.0
+ */
+export declare function scanMarkdownLinks(content: string): MarkdownLinkScan;
+export {};

package/dist/audit/domain/since-versions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Flags `@since` tags naming a version the owning package has not reached.
+ */
+/**
+ * One impossible `@since` stamp found in a file's comments.
+ *
+ * @since 0.8.0
+ */
+export interface SinceVersionFinding {
+    readonly line: number;
+    readonly raw: string;
+}
+/**
+ * Compares two SemVer strings by precedence — positive when `left` is greater,
+ * null when either side is not a SemVer version.
+ *
+ * @since 0.8.0
+ */
+export declare function compareVersionPrecedence(left: string, right: string): number | null;
+/**
+ * Scans a file's comments for `@since` tags stamped above the package's current
+ * version — a release that has not happened, so the stamp cannot be true.
+ *
+ * @since 0.8.0
+ */
+export declare function scanImpossibleSinceTags(content: string, packageVersion: string): Array<SinceVersionFinding>;

package/dist/audit/domain/tokenize.d.ts

@@ -0,0 +1,14 @@
+import type { RtlClassToken } from "#/audit/domain/types";
+/**
+ * Splits a class token into [variant, value, modifier], colon/slash-aware of
+ * brackets and parens (arbitrary values like data-[side=left] or calc(...)).
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function splitClassName(token: string): [string | null, string, string | null];
+/**
+ * Collects the parsed class tokens from every string literal in a file's content.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function collectTokens(content: string): Array<RtlClassToken>;

package/dist/audit/domain/tsdoc-syntax.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validates every doc block against the official TSDoc grammar, not a regex approximation.
+ */
+/**
+ * One grammar diagnostic from the TSDoc parser.
+ *
+ * @since 0.6.0
+ */
+export interface TsdocSyntaxFinding {
+    readonly line: number;
+    /** The parser's stable message id, e.g. `tsdoc-escape-right-brace` — the allowlist key. */
+    readonly raw: string;
+    readonly reason: string;
+}
+/**
+ * Every TSDoc grammar diagnostic in a file's doc blocks, in source order.
+ *
+ * @since 0.6.0
+ */
+export declare function scanTsdocSyntax(content: string): Array<TsdocSyntaxFinding>;

package/dist/audit/domain/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * A class token parsed from a source string literal, split into variant, value, and modifier.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlClassToken = {
+    readonly raw: string;
+    readonly token: string;
+    readonly variant: string | null;
+    readonly value: string;
+    readonly modifier: string | null;
+    readonly line: number;
+};
+/**
+ * A physical class occurrence the RTL audit flags, with its suggested logical replacement.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlViolation = {
+    readonly line: number;
+    readonly raw: string;
+    readonly suggestion: string;
+};
+/**
+ * The RTL violations found in one file.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlFileViolations = {
+    readonly relativePath: string;
+    readonly violations: Array<RtlViolation>;
+};
+/**
+ * Outcome of one `audit rtl` run.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlAuditResult = {
+    readonly files: Array<RtlFileViolations>;
+    readonly violationCount: number;
+    readonly allowlistedCount: number;
+    readonly scannedFileCount: number;
+};
+/**
+ * An import-policy violation: a banned import form (namespace / default / named), or an implicit
+ * UMD-global type reference under a name nothing in the file imports.
+ *
+ * @since 0.10.0
+ */
+export type ImportPolicyViolation = {
+    readonly line: number;
+    /** The offending source text — the import statement or the qualified type name. */
+    readonly raw: string;
+    readonly reason: string;
+};
+/**
+ * The import-policy violations found in one file.
+ *
+ * @since 0.10.0
+ */
+export type ImportPolicyFileViolations = {
+    readonly relativePath: string;
+    readonly violations: Array<ImportPolicyViolation>;
+};
+/**
+ * Outcome of one `audit imports` run.
+ *
+ * @since 0.10.0
+ */
+export type ImportsAuditResult = {
+    readonly files: Array<ImportPolicyFileViolations>;
+    readonly violationCount: number;
+    readonly allowlistedCount: number;
+    readonly scannedFileCount: number;
+};
+/**
+ * A `token()`, `tag()` or module display name that breaks the display-name convention.
+ *
+ * @since 0.9.0
+ */
+export type DisplayNameViolation = {
+    readonly line: number;
+    /** The call as written, through its closing quote. */
+    readonly raw: string;
+    readonly reason: string;
+};
+/**
+ * The display-name violations found in one file.
+ *
+ * @since 0.9.0
+ */
+export type DisplayNameFileViolations = {
+    readonly relativePath: string;
+    readonly violations: Array<DisplayNameViolation>;
+};
+/**
+ * Outcome of one `audit display-names` run.
+ *
+ * @since 0.9.0
+ */
+export type DisplayNameAuditResult = {
+    readonly files: Array<DisplayNameFileViolations>;
+    readonly violationCount: number;
+    readonly allowlistedCount: number;
+    readonly scannedFileCount: number;
+};
+/**
+ * A broken link or anchor found by the link audit.
+ *
+ * @since 0.5.0
+ */
+export type LinkBreakage = {
+    readonly line: number;
+    /** The link target as written, fragment included. */
+    readonly raw: string;
+    readonly reason: string;
+};
+/**
+ * The link breakages found in one markdown file.
+ *
+ * @since 0.5.0
+ */
+export type LinkFileBreakages = {
+    readonly relativePath: string;
+    readonly breakages: Array<LinkBreakage>;
+};
+/**
+ * Outcome of one `audit links` run.
+ *
+ * @since 0.5.0
+ */
+export type LinkAuditResult = {
+    readonly files: Array<LinkFileBreakages>;
+    readonly breakageCount: number;
+    readonly allowlistedCount: number;
+    readonly linkCount: number;
+    readonly scannedFileCount: number;
+};
+/**
+ * A section divider that does not match the repo's one allowed form. Always `--fix`-able.
+ *
+ * @since 0.6.0
+ */
+export type DividerBreakage = {
+    readonly line: number;
+    /** The divider's opening line as written. */
+    readonly raw: string;
+    readonly reason: string;
+};
+/**
+ * @see DividerBreakage
+ *
+ * @since 0.6.0
+ */
+export type DividerFileBreakages = {
+    readonly relativePath: string;
+    readonly breakages: Array<DividerBreakage>;
+};
+/**
+ * Outcome of one `audit comments` run. `fixedCount` stays `0` unless `--fix` was passed.
+ *
+ * @since 0.6.0
+ */
+export type CommentAuditResult = {
+    readonly files: Array<DividerFileBreakages>;
+    readonly breakageCount: number;
+    readonly allowlistedCount: number;
+    readonly fixedCount: number;
+    readonly dividerCount: number;
+    readonly scannedFileCount: number;
+};

package/dist/audit/output.d.ts

@@ -0,0 +1,91 @@
+import type { CommentAuditResult, ImportsAuditResult, LinkAuditResult, RtlAuditResult, DisplayNameAuditResult } from "#/audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted violation remains.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function exitCodeForRtlAuditResult(result: RtlAuditResult): number;
+/**
+ * Human-readable RTL audit report (matches the former packages/ui script shape).
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function presentRtlAuditResult(result: RtlAuditResult): void;
+/**
+ * Machine-readable RTL audit summary for `--json`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function formatRtlAuditJsonOutput(result: RtlAuditResult, rootDir: string): string;
+/**
+ * Exit `1` when any non-allowlisted broken link remains.
+ *
+ * @since 0.5.0
+ */
+export declare function exitCodeForLinkAuditResult(result: LinkAuditResult): number;
+/**
+ * Human-readable link audit report.
+ *
+ * @since 0.5.0
+ */
+export declare function presentLinkAuditResult(result: LinkAuditResult): void;
+/**
+ * Machine-readable link audit summary for `--json`.
+ *
+ * @since 0.5.0
+ */
+export declare function formatLinkAuditJsonOutput(result: LinkAuditResult, rootDir: string): string;
+/**
+ * Exit `1` when any non-allowlisted import-policy violation remains.
+ *
+ * @since 0.10.0
+ */
+export declare function exitCodeForImportsAuditResult(result: ImportsAuditResult): number;
+/**
+ * Human-readable import-policy report.
+ *
+ * @since 0.10.0
+ */
+export declare function presentImportsAuditResult(result: ImportsAuditResult): void;
+/**
+ * Machine-readable import-policy summary for `--json`.
+ *
+ * @since 0.10.0
+ */
+export declare function formatImportsAuditJsonOutput(result: ImportsAuditResult, rootDir: string): string;
+/**
+ * Exit `1` when any non-allowlisted divider still breaks the convention.
+ *
+ * @since 0.6.0
+ */
+export declare function exitCodeForCommentAuditResult(result: CommentAuditResult): number;
+/**
+ * Human-readable comment-divider report.
+ *
+ * @since 0.6.0
+ */
+export declare function presentCommentAuditResult(result: CommentAuditResult): void;
+/**
+ * Machine-readable comment-divider summary for `--json`.
+ *
+ * @since 0.6.0
+ */
+export declare function formatCommentAuditJsonOutput(result: CommentAuditResult, rootDir: string): string;
+/**
+ * Exit `1` when any non-allowlisted display-name violation remains.
+ *
+ * @since 0.9.0
+ */
+export declare function exitCodeForDisplayNameAuditResult(result: DisplayNameAuditResult): number;
+/**
+ * Human-readable display-name report.
+ *
+ * @since 0.9.0
+ */
+export declare function presentDisplayNameAuditResult(result: DisplayNameAuditResult): void;
+/**
+ * Machine-readable display-name summary for `--json`.
+ *
+ * @since 0.9.0
+ */
+export declare function formatDisplayNameAuditJsonOutput(result: DisplayNameAuditResult, rootDir: string): string;