@codefast/cli 0.9.0 → 0.11.0

package/dist/audit/rtl/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { AuditCommandPrelude } from "#/audit/prepare";
+import { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * Loads config and resolves the scan target for `audit rtl`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function prepareRtlAudit(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/rtl/prepare.js

@@ -0,0 +1,41 @@
+import { resolveRepoRelativePath } from "#/audit/prepare";
+import { loadCodefastConfig } from "#/core/config";
+import { AppError, messageFrom } from "#/core/errors";
+import { err, ok } from "#/core/result";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
+/**
+ * Loads config and resolves the scan target for `audit rtl`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export async function prepareRtlAudit(fs, args) {
+    let rootDir;
+    try {
+        // Realpath so allowlist keys (`path.relative(rootDir, file)`) stay stable when cwd is a symlink.
+        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
+    if (!loadedOutcome.ok) {
+        return loadedOutcome;
+    }
+    const { config } = loadedOutcome.value;
+    const rtlConfig = config.audit?.rtl ?? {};
+    const targetFromCli = args.rawTarget;
+    const targetFromConfig = rtlConfig.target;
+    const resolvedTargetInput = targetFromCli ?? targetFromConfig;
+    if (resolvedTargetInput === undefined) {
+        return err(new AppError("VALIDATION_ERROR", "Missing scan target: pass a path argument or set audit.rtl.target in codefast.config"));
+    }
+    const targetPath = resolveRepoRelativePath(targetFromCli !== undefined ? args.currentWorkingDirectory : rootDir, resolvedTargetInput);
+    if (!fs.existsSync(targetPath)) {
+        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
+    }
+    return ok({
+        rootDir,
+        targetPath: fs.canonicalPathSync(targetPath),
+        allowlist: rtlConfig.allowlist ?? [],
+    });
+}

package/dist/audit/rtl/run.d.ts

@@ -0,0 +1,14 @@
+import type { RtlAuditResult } from "#/audit/domain/types";
+import { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * Scans a target path for physical-direction Tailwind class violations.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function runRtlAudit(fs: Filesystem, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<RtlAuditResult, AppError>;

package/dist/audit/{run.js → rtl/run.js}

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { auditFileContent } from "#/audit/domain/audit-file";
+import { auditFileContent } from "#/audit/rtl/domain/audit-file";
 import { AppError, messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
 import { walkTsxFiles } from "#/core/workspace/typescript-walk";

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs the `codefast` CLI over the given argv and returns the process exit code.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runCli(argv: Array<string>): Promise<number>;

package/dist/core/cli/command-pipeline.d.ts

@@ -0,0 +1,91 @@
+import type { Command } from "commander";
+import type { ZodType } from "zod";
+import type { GlobalCliOptions } from "#/core/cli/global-options";
+import type { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * The options every command shares: the `--json` machine-output flag. Per-command option shapes extend this.
+ *
+ * @since 0.11.0
+ */
+export interface BaseCommandOptions {
+    readonly json?: boolean | undefined;
+}
+/**
+ * A pipeline's `prepare` slot: resolves the argv context (cwd, positional, global options) into the command's prelude.
+ *
+ * @since 0.11.0
+ */
+export type CommandPrepare<Prelude> = (fs: Filesystem, input: {
+    readonly currentWorkingDirectory: string;
+    readonly rawArg: string | undefined;
+    readonly globals: GlobalCliOptions;
+}) => Promise<Result<Prelude, AppError>>;
+/** The prelude and options a request is built from, before the run. */
+interface BuildInput<Prelude, Opts> {
+    readonly prelude: Prelude;
+    readonly opts: Opts;
+    readonly globals: GlobalCliOptions;
+}
+/** The run result and its surrounding context, for the report phase. */
+interface ReportInput<Prelude, RunResult, Presenter, Opts> {
+    readonly result: RunResult;
+    readonly prelude: Prelude;
+    readonly opts: Opts;
+    readonly presenter: Presenter | undefined;
+    readonly elapsedSeconds: number;
+}
+/**
+ * The invariant shape every workspace command and subcommand shares: resolve a prelude, build and
+ * validate a request, run it, then report to one of two audiences and record a single exit code.
+ *
+ * @remarks The optional slots carry the per-command variations — a working-tree guard and a streaming
+ * presenter — so the control flow itself is written once.
+ *
+ * @since 0.11.0
+ */
+export interface CommandPipeline<Prelude, Request, RunResult, Presenter = never, Opts extends BaseCommandOptions = BaseCommandOptions> {
+    readonly name?: string | undefined;
+    readonly description?: string | undefined;
+    readonly positional?: {
+        readonly name: string;
+        readonly help: string;
+    } | undefined;
+    readonly jsonHelp?: string | undefined;
+    readonly configureArgv?: ((command: Command) => void) | undefined;
+    readonly prepare: CommandPrepare<Prelude>;
+    readonly guard?: ((input: {
+        readonly prelude: Prelude;
+        readonly opts: Opts;
+    }) => Promise<Result<void, AppError>>) | undefined;
+    readonly schema: ZodType<Request>;
+    readonly buildRequest: (input: BuildInput<Prelude, Opts>) => unknown;
+    readonly createPresenter?: ((input: BuildInput<Prelude, Opts>) => Presenter) | undefined;
+    readonly run: (fs: Filesystem, request: Request, presenter: Presenter | undefined) => Promise<Result<RunResult, AppError>>;
+    readonly presentHuman?: ((input: ReportInput<Prelude, RunResult, Presenter, Opts>) => void) | undefined;
+    readonly formatJson: (input: ReportInput<Prelude, RunResult, Presenter, Opts>) => string;
+    readonly exitCode: (result: RunResult) => number;
+}
+/**
+ * A pipeline that names itself, so it can register as a subcommand under a parent command.
+ *
+ * @since 0.11.0
+ */
+export type NamedCommandPipeline<Prelude, Request, RunResult, Presenter = never, Opts extends BaseCommandOptions = BaseCommandOptions> = CommandPipeline<Prelude, Request, RunResult, Presenter, Opts> & {
+    readonly name: string;
+    readonly description: string;
+};
+/**
+ * Wires a pipeline onto a named Command: the shared positional, `--json`, any extra options, and the action.
+ *
+ * @since 0.11.0
+ */
+export declare function applyCommandPipeline<Prelude, Request, RunResult, Presenter, Opts extends BaseCommandOptions>(command: Command, fs: Filesystem, pipeline: CommandPipeline<Prelude, Request, RunResult, Presenter, Opts>): Command;
+/**
+ * Registers a pipeline as a subcommand under `parent`, taking its name and description from the pipeline.
+ *
+ * @since 0.11.0
+ */
+export declare function registerPipelineSubcommand<Prelude, Request, RunResult, Presenter, Opts extends BaseCommandOptions>(parent: Command, fs: Filesystem, pipeline: NamedCommandPipeline<Prelude, Request, RunResult, Presenter, Opts>): void;
+export {};

package/dist/core/cli/command-pipeline.js

@@ -0,0 +1,83 @@
+import process from "node:process";
+import { globalCliCommanderOptionsSchema } from "#/core/cli/global-options";
+import { readOptionalPositionalArg } from "#/core/cli/positional";
+import { consumeCliAppError } from "#/core/cli/result-handle";
+import { logger } from "#/core/logger";
+import { parseWithSchema } from "#/core/schema-parse";
+const DEFAULT_JSON_HELP = "Print one JSON summary on stdout (suppresses human progress)";
+function readGlobalOptions(command) {
+    return (command.optsWithGlobals?.() ?? command.opts());
+}
+function makeAction(fs, pipeline) {
+    return async (rawArg, opts, command) => {
+        const globalsOutcome = parseWithSchema(globalCliCommanderOptionsSchema, readGlobalOptions(command));
+        if (!consumeCliAppError(globalsOutcome)) {
+            return;
+        }
+        const globals = globalsOutcome.value;
+        const prelude = await pipeline.prepare(fs, {
+            currentWorkingDirectory: process.cwd(),
+            rawArg: readOptionalPositionalArg(rawArg),
+            globals,
+        });
+        if (!consumeCliAppError(prelude)) {
+            return;
+        }
+        if (pipeline.guard) {
+            const guarded = await pipeline.guard({ prelude: prelude.value, opts });
+            if (!consumeCliAppError(guarded)) {
+                return;
+            }
+        }
+        const parsed = parseWithSchema(pipeline.schema, pipeline.buildRequest({ prelude: prelude.value, opts, globals }));
+        if (!consumeCliAppError(parsed)) {
+            return;
+        }
+        const json = !!opts.json;
+        const presenter = !json && pipeline.createPresenter
+            ? pipeline.createPresenter({ prelude: prelude.value, opts, globals })
+            : undefined;
+        const startedAt = performance.now();
+        const outcome = await pipeline.run(fs, parsed.value, presenter);
+        if (!consumeCliAppError(outcome)) {
+            return;
+        }
+        const elapsedSeconds = (performance.now() - startedAt) / 1000;
+        const report = {
+            result: outcome.value,
+            prelude: prelude.value,
+            opts,
+            presenter,
+            elapsedSeconds,
+        };
+        if (json) {
+            logger.out(pipeline.formatJson(report));
+        }
+        else {
+            pipeline.presentHuman?.(report);
+        }
+        process.exitCode = pipeline.exitCode(outcome.value);
+    };
+}
+/**
+ * Wires a pipeline onto a named Command: the shared positional, `--json`, any extra options, and the action.
+ *
+ * @since 0.11.0
+ */
+export function applyCommandPipeline(command, fs, pipeline) {
+    if (pipeline.positional) {
+        command.argument(pipeline.positional.name, pipeline.positional.help);
+    }
+    command.option("--json", pipeline.jsonHelp ?? DEFAULT_JSON_HELP, false);
+    pipeline.configureArgv?.(command);
+    command.action(makeAction(fs, pipeline));
+    return command;
+}
+/**
+ * Registers a pipeline as a subcommand under `parent`, taking its name and description from the pipeline.
+ *
+ * @since 0.11.0
+ */
+export function registerPipelineSubcommand(parent, fs, pipeline) {
+    applyCommandPipeline(parent.command(pipeline.name).description(pipeline.description), fs, pipeline);
+}

package/dist/core/cli/format-error.d.ts

@@ -0,0 +1,7 @@
+import type { AppError } from "#/core/errors";
+/**
+ * Formats an `AppError` as a `[CODE] message` line for CLI output.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function formatAppError(error: AppError): string;

package/dist/core/cli/global-options.d.ts

@@ -0,0 +1,15 @@
+import * as z from "zod";
+/**
+ * The validated global CLI options shared by every subcommand.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface GlobalCliOptions {
+    color?: boolean | undefined;
+}
+/**
+ * Commander global opts shape validated before mirror prelude (`color` from `--no-color`).
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const globalCliCommanderOptionsSchema: z.ZodType<GlobalCliOptions>;

package/dist/core/cli/global-options.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 /**
  * Commander global opts shape validated before mirror prelude (`color` from `--no-color`).
  *

package/dist/core/cli/positional.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Coerce a raw Commander positional argument to a string, or undefined when absent.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function readOptionalPositionalArg(candidate: unknown): string | undefined;

package/dist/core/cli/resolve-root.d.ts

@@ -0,0 +1,9 @@
+import { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * Resolves the project root as a `Result`, mapping a resolution failure to an `INFRA_FAILURE` error.
+ *
+ * @since 0.11.0
+ */
+export declare function resolveProjectRootResult(fs: Filesystem, currentWorkingDirectory: string): Result<string, AppError>;

package/dist/core/cli/resolve-root.js

@@ -0,0 +1,16 @@
+import { AppError, messageFrom } from "#/core/errors";
+import { err, ok } from "#/core/result";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
+/**
+ * Resolves the project root as a `Result`, mapping a resolution failure to an `INFRA_FAILURE` error.
+ *
+ * @since 0.11.0
+ */
+export function resolveProjectRootResult(fs, currentWorkingDirectory) {
+    try {
+        return ok(resolveProjectRoot(currentWorkingDirectory, fs).rootDir);
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+}

package/dist/core/cli/result-handle.d.ts

@@ -0,0 +1,13 @@
+import type { AppError } from "#/core/errors";
+import type { Result } from "#/core/result";
+/**
+ * Narrows a `Result`, reporting a failure and setting the exit code, or logging an optional success message.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function consumeCliAppError<Value>(outcome: Result<Value, AppError>, options?: {
+    readonly successMessage?: string;
+}): outcome is {
+    readonly ok: true;
+    readonly value: Value;
+};

package/dist/core/cli/result-handle.js

@@ -38,17 +38,4 @@ export function consumeCliAppError(outcome, options) {
         logger.out(options.successMessage);
     }
     return true;
-}
-/**
- * Awaits a `Result`, hands a success to `onSuccess`, and records the returned exit code on the process.
- *
- * @since 0.3.16-canary.0
- */
-export async function runCliResultAsync(outcomePromise, onSuccess) {
-    const outcome = await outcomePromise;
-    if (!consumeCliAppError(outcome)) {
-        return;
-    }
-    const exit = await onSuccess(outcome.value);
-    process.exitCode = exit === undefined ? 0 : exit;
 }

package/dist/core/config/define-config.d.ts

@@ -0,0 +1,7 @@
+import type { CodefastConfig } from "#/core/config/schema";
+/**
+ * Types a `codefast.config.*` object for editor autocomplete and type-checking; returns it unchanged.
+ *
+ * @since 0.10.0
+ */
+export declare function defineConfig(config: CodefastConfig): CodefastConfig;

package/dist/core/config/define-config.js

@@ -0,0 +1,8 @@
+/**
+ * Types a `codefast.config.*` object for editor autocomplete and type-checking; returns it unchanged.
+ *
+ * @since 0.10.0
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/core/config/loader.d.ts

@@ -0,0 +1,18 @@
+import type { CodefastConfig } from "#/core/config/schema";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+/**
+ * A loaded config together with its schema warnings and the path it was read from.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type LoadConfigPayload = {
+    readonly config: CodefastConfig;
+    readonly warnings: Array<string>;
+    readonly configPath?: string;
+};
+/**
+ * Loads and caches the config payload for a directory, sharing one load per resolved path.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function loadConfigPayload(startDir: string, fs: Filesystem): Promise<LoadConfigPayload>;

package/dist/core/config/loader.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import jiti from "jiti";
 import { codefastConfigRootSchema } from "#/core/config/schema";
+import { ancestorDirectories } from "#/core/workspace/ancestor-directories";
 function formatZodError(error, filePath) {
     const formatted = error.issues
         .map((issue) => {
@@ -22,8 +23,7 @@ const configJson = "codefast.config.json";
 const cachedLoads = new Map();
 function listConfigCandidates(startDir, fs) {
     const candidates = [];
-    let current = path.resolve(startDir);
-    while (true) {
+    for (const current of ancestorDirectories(startDir)) {
         for (const name of configJsPriority) {
             const candidate = path.join(current, name);
             if (fs.existsSync(candidate)) {
@@ -34,11 +34,6 @@ function listConfigCandidates(startDir, fs) {
         if (fs.existsSync(jsonCandidate)) {
             candidates.push(jsonCandidate);
         }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            break;
-        }
-        current = parent;
     }
     return candidates;
 }

package/dist/core/config/schema.d.ts

@@ -0,0 +1,99 @@
+import * as z from "zod";
+/**
+ * A config hook invoked with the written file paths after a command rewrites files.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type CodefastAfterWriteHook = (context: {
+    files: Array<string>;
+}) => void | Promise<void>;
+/**
+ * CSS export configuration for a mirrored package — a flag, or per-file overrides.
+ */
+type MirrorCssConfig = boolean | {
+    enabled?: boolean | undefined;
+    customExports?: Record<string, string> | undefined;
+    forceExportFiles?: boolean | undefined;
+};
+/**
+ * Per-package mirror configuration. Setting a package to `false` skips it entirely.
+ */
+interface MirrorPackageConfig {
+    /** Preserve the existing `package.json#exports` map and only add missing conditions
+     *  (`source`, `types`, `import`); no `dist/` scan is performed. */
+    preserve?: boolean | undefined;
+    strip?: string | undefined;
+    /** Specifiers to leave out of the generated map, so a package's public surface is a decision
+     *  rather than a consequence of its `dist/` layout. Matched against the specifier as it would
+     *  appear in `exports` (after `strip`); a trailing `/*` excludes a whole subtree. The root
+     *  export and `./package.json` are never excluded. */
+    exclude?: Array<string> | undefined;
+    exports?: Record<string, string> | undefined;
+    /** All three default to `true`; the mirror resolves an omitted value the same as `true`. */
+    source?: boolean | string | undefined;
+    types?: boolean | undefined;
+    import?: boolean | undefined;
+    css?: MirrorCssConfig | undefined;
+}
+/**
+ * The validated `mirror` configuration, keyed by package name.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type MirrorConfig = Record<string, false | MirrorPackageConfig>;
+/**
+ * The validated `tag` command configuration.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface CodefastTagConfig {
+    skipPackages?: Array<string> | undefined;
+    onAfterWrite?: CodefastAfterWriteHook | undefined;
+}
+/**
+ * The validated `arrange` command configuration.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface CodefastArrangeConfig {
+    onAfterWrite?: CodefastAfterWriteHook | undefined;
+}
+/** An audit's per-command defaults: entries to ignore, as bare tokens or `repo/relative/path:token`. */
+interface CodefastAuditAllowlistConfig {
+    allowlist?: Array<string> | undefined;
+}
+/** Per-audit defaults grouped under `audit`; the scan always starts at the repo root. */
+interface CodefastAuditConfig {
+    rtl?: {
+        target?: string | undefined;
+        allowlist?: Array<string> | undefined;
+    } | undefined;
+    links?: CodefastAuditAllowlistConfig | undefined;
+    comments?: CodefastAuditAllowlistConfig | undefined;
+    imports?: CodefastAuditAllowlistConfig | undefined;
+    displayNames?: CodefastAuditAllowlistConfig | undefined;
+}
+/**
+ * The validated root `codefast.config` shape.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface CodefastConfig {
+    mirror?: MirrorConfig | undefined;
+    tag?: CodefastTagConfig | undefined;
+    arrange?: CodefastArrangeConfig | undefined;
+    audit?: CodefastAuditConfig | undefined;
+}
+/**
+ * Zod validator for the `mirror` configuration record; its output is a {@link MirrorConfig}.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const mirrorConfigSchema: z.ZodType<MirrorConfig>;
+/**
+ * Zod validator for a raw `codefast.config` object; its output is a {@link CodefastConfig}.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const codefastConfigRootSchema: z.ZodType<CodefastConfig>;
+export {};