@codefast/cli 0.9.0 → 0.10.0

package/dist/arrange/source-parse.d.ts

@@ -0,0 +1,7 @@
+import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+/**
+ * Parses source text into a domain source file via the shared `oxc-parser` translator.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function parseDomainSourceFile(filePath: string, sourceText: string): DomainSourceFile;

package/dist/arrange/suggest.d.ts

@@ -0,0 +1,8 @@
+import type { ArrangeSuggestGroupsRequest } from "#/arrange/cli-schema";
+import type { ArrangeSuggestGroupsOutput } from "#/arrange/domain/types";
+/**
+ * Formats the suggested grouping for an inline class string as `arrange group` output lines.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function suggestCnGroupsFromCli(request: ArrangeSuggestGroupsRequest): ArrangeSuggestGroupsOutput;

package/dist/arrange/sync.d.ts

@@ -0,0 +1,11 @@
+import type { ArrangeSyncRunRequest } from "#/arrange/cli-schema";
+import type { ArrangeRunResult } from "#/arrange/domain/types";
+import type { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Runs the grouping pipeline over every target file and returns the aggregated result.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runArrangeSync(fs: FilesystemPort, request: ArrangeSyncRunRequest): Promise<Result<ArrangeRunResult, AppError>>;

package/dist/arrange/typescript-ast-translator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anti-corruption layer: maps the oxc-parser ESTree AST to the arrange domain AST.
+ * This is the only place that parses TypeScript source for arrange AST translation.
+ */
+import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+/**
+ * The translator mapping the `oxc-parser` ESTree AST to the arrange domain AST.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare class TypeScriptAstTranslator {
+    translateSourceFile(filePath: string, sourceText: string): DomainSourceFile;
+    /**
+     * Own child nodes in source-declaration order, mirroring `ts.forEachChild`:
+     * recurses into nested node objects and arrays of nodes, skipping primitives
+     * and plain records (e.g. a template element's `value`) that carry no `type`.
+     */
+    private childNodesOf;
+    private translateUnknown;
+    private stringLiteralText;
+    private noSubstitutionTemplateText;
+    private mapBinaryOperator;
+    private translateImportDeclaration;
+    private buildImportClause;
+    private buildNamespaceImport;
+    private buildNamedImports;
+    private buildImportSpecifier;
+    private translateIdentifier;
+    private translateNode;
+    private parseDomainSourceFile;
+}

package/dist/arrange/workspace.d.ts

@@ -0,0 +1,13 @@
+import type { ArrangeTargetWorkspaceAndConfig } from "#/arrange/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Resolves the arrange target, repo root, and loaded config an arrange run needs.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function prepareArrangeWorkspace(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<ArrangeTargetWorkspaceAndConfig, AppError>>;

package/dist/arrange/workspace.js

@@ -3,7 +3,7 @@ import { loadCodefastConfig } from "#/core/config";
 import { AppError } from "#/core/errors";
 import { messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
-import { findRepoRoot } from "#/core/workspace/resolver";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
 /**
  * Resolves the arrange target, repo root, and loaded config an arrange run needs.
  *
@@ -19,7 +19,7 @@ export async function prepareArrangeWorkspace(fs, args) {
     }
     let rootDir;
     try {
-        rootDir = findRepoRoot(args.currentWorkingDirectory, fs);
+        rootDir = resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir;
     }
     catch (caughtError) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));

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

@@ -0,0 +1,93 @@
+import { z } from "zod";
+/**
+ * Resolved request for a single RTL audit run.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link RtlAuditRunRequest}.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const rtlAuditRunRequestSchema: z.ZodType<RtlAuditRunRequest>;
+/**
+ * Resolved request for a single link audit run.
+ *
+ * @since 0.5.0
+ */
+export type LinkAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link LinkAuditRunRequest}.
+ *
+ * @since 0.5.0
+ */
+export declare const linkAuditRunRequestSchema: z.ZodType<LinkAuditRunRequest>;
+/**
+ * Resolved request for a single comment-divider audit run.
+ *
+ * @since 0.6.0
+ */
+export type CommentAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly fix: boolean;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link CommentAuditRunRequest}.
+ *
+ * @since 0.6.0
+ */
+export declare const commentAuditRunRequestSchema: z.ZodType<CommentAuditRunRequest>;
+/**
+ * Resolved request for a single import-policy audit run.
+ *
+ * @since 0.10.0
+ */
+export type ImportsAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link ImportsAuditRunRequest}.
+ *
+ * @since 0.10.0
+ */
+export declare const importsAuditRunRequestSchema: z.ZodType<ImportsAuditRunRequest>;
+/**
+ * Resolved request for a single display-name audit run.
+ *
+ * @since 0.9.0
+ */
+export type DisplayNameAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link DisplayNameAuditRunRequest}.
+ *
+ * @since 0.9.0
+ */
+export declare const displayNameAuditRunRequestSchema: z.ZodType<DisplayNameAuditRunRequest>;
+/**
+ * Resolves a path that may be absolute or relative to `rootDir`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function resolveRepoRelativePath(rootDir: string, maybeRelative: string): string;

package/dist/audit/cli-schema.js

@@ -35,11 +35,11 @@ export const commentAuditRunRequestSchema = z.object({
     json: z.boolean(),
 });
 /**
- * Zod schema for {@link ReactAuditRunRequest}.
+ * Zod schema for {@link ImportsAuditRunRequest}.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export const reactAuditRunRequestSchema = z.object({
+export const importsAuditRunRequestSchema = z.object({
     rootDir: z.string().min(1),
     targetPath: z.string().min(1),
     allowlist: z.array(z.string()).optional(),

package/dist/audit/command.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * Top-level `audit` command — the source scans. Every one of them reports by default; only
+ * `comments --fix` writes, and only where the rewrite discards nothing a person wrote.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function createAuditCommand(): Command;

package/dist/audit/command.js

@@ -1,13 +1,13 @@
 import process from "node:process";
 import { Command } from "commander";
-import { commentAuditRunRequestSchema, linkAuditRunRequestSchema, reactAuditRunRequestSchema, rtlAuditRunRequestSchema, displayNameAuditRunRequestSchema, } from "#/audit/cli-schema";
-import { exitCodeForCommentAuditResult, exitCodeForLinkAuditResult, exitCodeForReactAuditResult, exitCodeForRtlAuditResult, exitCodeForDisplayNameAuditResult, formatCommentAuditJsonOutput, formatLinkAuditJsonOutput, formatReactAuditJsonOutput, formatRtlAuditJsonOutput, formatDisplayNameAuditJsonOutput, presentCommentAuditResult, presentLinkAuditResult, presentReactAuditResult, presentRtlAuditResult, presentDisplayNameAuditResult, } from "#/audit/output";
-import { prepareCommentAudit, prepareLinkAudit, prepareReactAudit, prepareRtlAudit, prepareDisplayNameAudit, } from "#/audit/prepare";
+import { commentAuditRunRequestSchema, linkAuditRunRequestSchema, importsAuditRunRequestSchema, rtlAuditRunRequestSchema, displayNameAuditRunRequestSchema, } from "#/audit/cli-schema";
+import { exitCodeForCommentAuditResult, exitCodeForLinkAuditResult, exitCodeForImportsAuditResult, exitCodeForRtlAuditResult, exitCodeForDisplayNameAuditResult, formatCommentAuditJsonOutput, formatLinkAuditJsonOutput, formatImportsAuditJsonOutput, formatRtlAuditJsonOutput, formatDisplayNameAuditJsonOutput, presentCommentAuditResult, presentLinkAuditResult, presentImportsAuditResult, presentRtlAuditResult, presentDisplayNameAuditResult, } from "#/audit/output";
+import { prepareCommentAudit, prepareLinkAudit, prepareImportsAudit, prepareRtlAudit, prepareDisplayNameAudit, } from "#/audit/prepare";
 import { runRtlAudit } from "#/audit/run";
 import { runCommentAudit } from "#/audit/run-comments";
 import { runDisplayNameAudit } from "#/audit/run-display-names";
+import { runImportsAudit } from "#/audit/run-imports";
 import { runLinkAudit } from "#/audit/run-links";
-import { runReactAudit } from "#/audit/run-react";
 import { readOptionalPositionalArg } from "#/core/cli/positional";
 import { consumeCliAppError } from "#/core/cli/result-handle";
 import { nodeFilesystem } from "#/core/filesystem/node";
@@ -100,12 +100,12 @@ export function createAuditCommand() {
         process.exitCode = exitCodeForLinkAuditResult(outcome.value);
     });
     cmd
-        .command("react")
-        .description("Report React namespace/default imports and implicit React.* UMD-global type references")
+        .command("imports")
+        .description("Report banned import forms (React by-name, Zod namespace in front-end packages, …)")
         .argument("[target]", "Directory or file to scan (default: the repo root)")
         .option("--json", "Print one JSON summary on stdout", false)
         .action(async (target, opts) => {
-        const prelude = await prepareReactAudit(nodeFilesystem, {
+        const prelude = await prepareImportsAudit(nodeFilesystem, {
             currentWorkingDirectory: process.cwd(),
             rawTarget: readOptionalPositionalArg(target),
         });
@@ -113,7 +113,7 @@ export function createAuditCommand() {
             return;
         }
         const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(reactAuditRunRequestSchema, {
+        const parsed = parseWithSchema(importsAuditRunRequestSchema, {
             rootDir,
             targetPath,
             allowlist,
@@ -122,7 +122,7 @@ export function createAuditCommand() {
         if (!consumeCliAppError(parsed)) {
             return;
         }
-        const outcome = runReactAudit(nodeFilesystem, {
+        const outcome = runImportsAudit(nodeFilesystem, {
             rootDir: parsed.value.rootDir,
             targetPath: parsed.value.targetPath,
             allowlist: parsed.value.allowlist ?? [],
@@ -131,12 +131,12 @@ export function createAuditCommand() {
             return;
         }
         if (parsed.value.json) {
-            logger.out(formatReactAuditJsonOutput(outcome.value, rootDir));
+            logger.out(formatImportsAuditJsonOutput(outcome.value, rootDir));
         }
         else {
-            presentReactAuditResult(outcome.value);
+            presentImportsAuditResult(outcome.value);
         }
-        process.exitCode = exitCodeForReactAuditResult(outcome.value);
+        process.exitCode = exitCodeForImportsAuditResult(outcome.value);
     });
     cmd
         .command("display-names")

package/dist/audit/domain/audit-file.d.ts

@@ -0,0 +1,7 @@
+import type { RtlViolation } from "#/audit/domain/types";
+/**
+ * Detects physical-direction Tailwind classes that should be logical or rtl:-paired.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function auditFileContent(content: string): Array<RtlViolation>;

package/dist/audit/domain/comment-content.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Recognises comment content the repo bans outright: repo-document pointers and JSDoc type syntax.
+ */
+/**
+ * Why a comment's content fails the convention. None is mechanical — the writer restates the
+ * invariant, lets the type carry the type, or moves the tag.
+ *
+ * @since 0.6.0
+ */
+export type CommentContentDefectKind = "detached-doc" | "doc-pointer" | "jsdoc-type" | "param-coverage" | "param-hyphen" | "since-order" | "stacked-doc";
+/**
+ * One banned fragment found inside a comment.
+ *
+ * @since 0.6.0
+ */
+export interface CommentContentFinding {
+    readonly line: number;
+    readonly raw: string;
+    readonly defect: CommentContentDefectKind;
+}
+/**
+ * Scans a source file's comments for banned content, in source order.
+ *
+ * @since 0.6.0
+ */
+export declare function scanCommentContent(content: string, language: "css" | "js"): Array<CommentContentFinding>;

package/dist/audit/domain/comment-dividers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Recognises section dividers in source text and renders them in the one form the repo allows.
+ */
+/**
+ * The column every divider's rule ends at — `oxfmt`'s `printWidth`, indentation included.
+ *
+ * @since 0.6.0
+ */
+export declare const DIVIDER_COLUMN = 120;
+/**
+ * Which comment syntax a divider is written in.
+ *
+ * @since 0.6.0
+ */
+export type DividerLanguage = "css" | "ignore" | "js";
+/**
+ * Why a divider fails the convention. Both kinds are mechanical, so every report is one `--fix` away.
+ *
+ * @since 0.6.0
+ */
+export type DividerDefectKind = "bad-width" | "legacy-form";
+/**
+ * One divider found in a file, with the verdict on its form.
+ *
+ * @since 0.6.0
+ */
+export interface DividerRegion {
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly indent: string;
+    readonly title: string;
+    readonly raw: string;
+    readonly defect: DividerDefectKind | null;
+}
+/**
+ * Renders a divider in the canonical form.
+ *
+ * @param indent - leading whitespace copied from the site, counted toward the column
+ * @param title - the section name, already trimmed
+ * @param language - which comment syntax to draw the divider in
+ *
+ * @since 0.6.0
+ */
+export declare function renderDivider(indent: string, title: string, language: DividerLanguage): string;
+/**
+ * Every section divider in a file, canonical ones included, in source order.
+ *
+ * @remarks A rule-framed comment that carries prose is a doc block, not a divider, and never
+ * appears here — the two are different things and only one of them has a fixed form.
+ *
+ * @since 0.6.0
+ */
+export declare function scanCommentDividers(content: string, language: DividerLanguage): Array<DividerRegion>;
+/**
+ * Rewrites every off-convention divider into the canonical form.
+ *
+ * @since 0.6.0
+ */
+export declare function applyCommentDividerFixes(content: string, language: DividerLanguage): {
+    readonly content: string;
+    readonly fixedCount: number;
+};

package/dist/audit/domain/display-names.d.ts

@@ -0,0 +1,11 @@
+/** The display-name convention: a name is spelled like the TS symbol it stands for, under its owner's namespace. */
+import type { DisplayNameViolation } from "#/audit/domain/types";
+/**
+ * Scans one source or markdown text for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @remarks Runs on markdown as well as TypeScript because a doc sample is what a reader copies:
+ * a convention the docs break is not one the docs teach.
+ *
+ * @since 0.9.0
+ */
+export declare function auditDisplayNames(sourceText: string): Array<DisplayNameViolation>;

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"];