@codefast/cli 0.8.1 → 0.10.0

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

@@ -0,0 +1,99 @@
+import { 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 {};

package/dist/core/config/schema.js

@@ -12,27 +12,10 @@ const mirrorCssConfigSchema = z.union([
     })
         .strict(),
 ]);
-/**
- * Per-package mirror configuration. Setting a package to `false` skips it entirely.
- *
- * - `source` — include a `source` condition pointing to the original `.ts` file (default `true`).
- *   Pass a string to override the root-export source path explicitly.
- * - `types` — include the `types` condition when `.d.ts` files exist (default `true`).
- * - `import` — include the `import` condition (default `true`).
- * - `css` — CSS export configuration (wildcard or per-file).
- *
- * @since 0.3.16-canary.0
- */
 const mirrorPackageConfigSchema = z
     .object({
-    /** Preserve the existing `package.json#exports` map and only add missing conditions
-     *  (`source`, `types`, `import`). No dist/ scan is performed. */
     preserve: z.boolean().optional(),
     strip: z.string().optional(),
-    /** 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: z.array(z.string()).optional(),
     exports: z.record(z.string(), z.string()).optional(),
     source: z.union([z.boolean(), z.string()]).default(true),
@@ -42,95 +25,44 @@ const mirrorPackageConfigSchema = z
 })
     .strict();
 /**
- * Mirror config: a record keyed by package name. Set a package to `false` to skip it;
- * omit it entirely to process it with default settings.
+ * Zod validator for the `mirror` configuration record; its output is a {@link MirrorConfig}.
  *
  * @since 0.3.16-canary.0
  */
 export const mirrorConfigSchema = z.record(z.string(), z.union([z.literal(false), mirrorPackageConfigSchema]));
-/**
- * Zod schema for the `tag` command's configuration.
- *
- * @since 0.3.16-canary.0
- */
 const codefastTagConfigSchema = z
     .object({
     skipPackages: z.array(z.string()).optional(),
     onAfterWrite: afterWriteHookSchema.optional(),
 })
     .strict();
-/**
- * Zod schema for the `arrange` command's configuration.
- *
- * @since 0.3.16-canary.0
- */
 const codefastArrangeConfigSchema = z
     .object({
     onAfterWrite: afterWriteHookSchema.optional(),
 })
     .strict();
-/**
- * RTL audit defaults — `target` is relative to the repo root (where `codefast.config` lives).
- *
- * @since 0.3.16-canary.0
- */
 const codefastAuditRtlConfigSchema = z
     .object({
-    /** Directory or file to scan when no CLI target is passed. */
     target: z.string().optional(),
-    /** Bare class tokens or `repo/relative/path.tsx:token` entries to ignore. */
-    allowlist: z.array(z.string()).optional(),
-})
-    .strict();
-/**
- * Link audit defaults — the scan always starts at the repo root, so only exceptions are configured.
- *
- * @since 0.5.0
- */
-const codefastAuditLinksConfigSchema = z
-    .object({
-    /** Bare link targets or `repo/relative/doc.md:target` entries to ignore. */
     allowlist: z.array(z.string()).optional(),
 })
     .strict();
-/**
- * Comment-divider audit defaults — the scan always starts at the repo root, so only exceptions are configured.
- *
- * @since 0.6.0
- */
-const codefastAuditCommentsConfigSchema = z
+const codefastAuditAllowlistConfigSchema = z
     .object({
-    /** Divider lines as written, or `repo/relative/path.ts:<divider>` entries, to ignore. */
     allowlist: z.array(z.string()).optional(),
 })
     .strict();
-/**
- * React import-policy audit defaults — the scan always starts at the repo root, so only
- * exceptions are configured.
- *
- * @since 0.8.0
- */
-const codefastAuditReactConfigSchema = z
-    .object({
-    /** Offending source text as written, or `repo/relative/path.tsx:<text>` entries, to ignore. */
-    allowlist: z.array(z.string()).optional(),
-})
-    .strict();
-/**
- * Zod schema grouping the per-audit configurations under `audit`.
- *
- * @since 0.3.16-canary.0
- */
 const codefastAuditConfigSchema = z
     .object({
     rtl: codefastAuditRtlConfigSchema.optional(),
-    links: codefastAuditLinksConfigSchema.optional(),
-    comments: codefastAuditCommentsConfigSchema.optional(),
-    react: codefastAuditReactConfigSchema.optional(),
+    links: codefastAuditAllowlistConfigSchema.optional(),
+    comments: codefastAuditAllowlistConfigSchema.optional(),
+    imports: codefastAuditAllowlistConfigSchema.optional(),
+    displayNames: codefastAuditAllowlistConfigSchema.optional(),
 })
     .strict();
 /**
- * Root `codefast.config` Zod schema — single source of truth for both validation and TS types.
+ * Zod validator for a raw `codefast.config` object; its output is a {@link CodefastConfig}.
  *
  * @since 0.3.16-canary.0
  */

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

@@ -0,0 +1,6 @@
+/**
+ * Prints each config schema warning as a highlighted line.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function reportSchemaWarnings(warnings: ReadonlyArray<string>): void;

package/dist/core/config.d.ts

@@ -0,0 +1,12 @@
+import type { CodefastConfig } from "#/core/config/schema";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Loads the `codefast.config.js` for a workspace root, reporting schema warnings along the way.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function loadCodefastConfig(rootDir: string, fs: FilesystemPort): Promise<Result<{
+    config: CodefastConfig;
+}, AppError>>;

package/dist/core/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cross-context application errors for Result-based flows.
+ * Does not extend the global `Error` type — instances are carried in `Result` values, not thrown.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type AppErrorCode = "NOT_FOUND" | "VALIDATION_ERROR" | "INFRA_FAILURE";
+/**
+ * A coded application error carried in `Result` values rather than thrown.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare class AppError {
+    readonly name: "AppError";
+    readonly code: AppErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    constructor(code: AppErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Stable, user-facing text for values caught as `unknown`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function messageFrom(value: unknown): string;

package/dist/core/exit-codes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Process exit codes for the `codefast` CLI.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const CLI_EXIT_SUCCESS = 0;
+/**
+ * The exit code for a run that failed for any reason other than bad usage.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const CLI_EXIT_GENERAL_ERROR = 1;
+/**
+ * The exit code for invalid arguments or configuration.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const CLI_EXIT_USAGE = 2;

package/dist/core/filesystem/node.d.ts

@@ -0,0 +1,7 @@
+import type { FilesystemPort } from "#/core/filesystem/port";
+/**
+ * The `FilesystemPort` implementation backed by Node's real filesystem.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const nodeFilesystem: FilesystemPort;

package/dist/core/filesystem/node.js

@@ -29,6 +29,7 @@ export const nodeFilesystem = {
         }
         return raw;
     },
+    globSync: (pattern, options) => fsSync.globSync(pattern, options),
     rename: (oldPath, newPath) => fsPromises.rename(oldPath, newPath),
     unlink: (filePath) => fsPromises.unlink(filePath),
 };

package/dist/core/filesystem/port.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Filesystem surface for CLI flows (real implementation: {@link nodeFilesystem}).
+ *
+ * @since 0.3.16-canary.0
+ */
+export type CliFileEncoding = "utf8";
+/**
+ * A directory listing entry with its name, parent path, and kind predicates.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface DirectoryEntry {
+    readonly name: string;
+    readonly parentPath: string;
+    isFile(): boolean;
+    isDirectory(): boolean;
+}
+/**
+ * The filesystem operations a CLI flow depends on, swappable for tests.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface FilesystemPort {
+    existsSync(filePath: string): boolean;
+    canonicalPathSync(inputPath: string): string;
+    statSync(filePath: string): {
+        isDirectory(): boolean;
+        isFile(): boolean;
+    };
+    readFileSync(filePath: string, encoding: CliFileEncoding): string;
+    writeFileSync(filePath: string, data: string, encoding: CliFileEncoding): void;
+    readdirSync(filePath: string): Array<string>;
+    readFile(filePath: string, encoding: CliFileEncoding): Promise<string>;
+    writeFile(filePath: string, data: string, encoding: CliFileEncoding): Promise<void>;
+    readdir(filePath: string, options?: {
+        recursive?: boolean;
+        withFileTypes?: boolean;
+    }): Promise<Array<string> | Array<DirectoryEntry>>;
+    globSync(pattern: string, options: {
+        readonly cwd: string;
+    }): Array<string>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    unlink(filePath: string): Promise<void>;
+}

package/dist/core/glob.d.ts

@@ -0,0 +1,19 @@
+import picomatch from "picomatch";
+/**
+ * A predicate over a string — returns `true` when the value matches.
+ *
+ * @since 0.5.0-canary.0
+ */
+export type StringMatcher = (value: string) => boolean;
+/**
+ * Compile a list of glob patterns into a predicate that returns `true` when its
+ * argument matches **any** of them (picomatch semantics). Returns a never-match
+ * predicate when no patterns are supplied.
+ *
+ * Shared by every "match a name/path against a configured pattern list" use
+ * (workspace excludes, `tag.skipPackages`, …) so the compile-then-`some` logic
+ * lives in one place.
+ *
+ * @since 0.5.0-canary.0
+ */
+export declare function createAnyGlobMatcher(patterns: ReadonlyArray<string> | undefined, options?: Parameters<typeof picomatch>[1]): StringMatcher;

package/dist/core/logger.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The CLI's line-oriented writer for stdout and stderr.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const logger: {
+    out(line: string): void;
+    err(line: string): void;
+};

package/dist/core/result.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Lightweight functional Result type for CLI boundaries.
+ */
+type Ok<Value> = {
+    readonly ok: true;
+    readonly value: Value;
+};
+type Err<ErrorValue> = {
+    readonly ok: false;
+    readonly error: ErrorValue;
+};
+/**
+ * A discriminated success-or-error union tagged by its `ok` flag.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type Result<Value, ErrorValue> = Ok<Value> | Err<ErrorValue>;
+/**
+ * Wraps a value in a success `Result`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function ok<Value>(value: Value): Ok<Value>;
+/**
+ * Wraps an error in a failure `Result`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function err<ErrorValue>(error: ErrorValue): Err<ErrorValue>;
+export {};

package/dist/core/schema-parse.d.ts

@@ -0,0 +1,9 @@
+import type { ZodType } from "zod";
+import { AppError } from "#/core/errors";
+import type { Result } from "#/core/result";
+/**
+ * Parses an input against a Zod schema and returns a `Result` with the value or a validation `AppError`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function parseWithSchema<Value>(schema: ZodType<Value>, input: unknown): Result<Value, AppError>;

package/dist/core/source-text-edit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure string utilities for applying non-overlapping text edits and reading line indentation.
+ */
+type SourceTextEdit = Readonly<{
+    start: number;
+    end: number;
+    replacement: string;
+}>;
+/**
+ * Returns the leading whitespace of the line containing a position.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function indentOfLineContaining(source: string, pos: number): string;
+/**
+ * Returns the text from the start of a position's line up to that position.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function textPrefixFromLineStartToPosition(source: string, pos: number): string;
+/**
+ * Extends a token's end position past any whitespace-separated trailing comma.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function endAfterOptionalCommaFollowingInSource(source: string, tokenEnd: number): number;
+/**
+ * Applies non-overlapping text edits from the highest offset down and returns the edited source.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function applyEditsDescending(sourceText: string, edits: ReadonlyArray<SourceTextEdit>): string;
+export {};

package/dist/core/verbose-diagnostics.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reports whether the `CODEFAST_VERBOSE` environment variable enables verbose diagnostics.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function isVerboseCliDiagnostics(): boolean;

package/dist/core/workspace/ancestor-directories.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Each directory from `fromDirectory` up to and including the filesystem root.
+ *
+ * @since 0.10.0
+ */
+export declare function ancestorDirectories(fromDirectory: string): Generator<string>;
+/**
+ * The nearest ancestor directory (starting at `fromDirectory`) the predicate accepts, or undefined at the filesystem root.
+ *
+ * @since 0.10.0
+ */
+export declare function findNearestAncestor(fromDirectory: string, isMatch: (directoryPath: string) => boolean): string | undefined;

package/dist/core/workspace/ancestor-directories.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+/**
+ * Each directory from `fromDirectory` up to and including the filesystem root.
+ *
+ * @since 0.10.0
+ */
+export function* ancestorDirectories(fromDirectory) {
+    let directoryPath = path.resolve(fromDirectory);
+    for (;;) {
+        yield directoryPath;
+        const parent = path.dirname(directoryPath);
+        if (parent === directoryPath) {
+            return;
+        }
+        directoryPath = parent;
+    }
+}
+/**
+ * The nearest ancestor directory (starting at `fromDirectory`) the predicate accepts, or undefined at the filesystem root.
+ *
+ * @since 0.10.0
+ */
+export function findNearestAncestor(fromDirectory, isMatch) {
+    for (const directoryPath of ancestorDirectories(fromDirectory)) {
+        if (isMatch(directoryPath)) {
+            return directoryPath;
+        }
+    }
+    return undefined;
+}

package/dist/core/workspace/markdown-walk.d.ts

@@ -0,0 +1,7 @@
+import type { FilesystemPort } from "#/core/filesystem/port";
+/**
+ * Every markdown file under a root, skipping build output and vendored trees.
+ *
+ * @since 0.5.0
+ */
+export declare function walkMarkdownFiles(rootDirectoryPath: string, fs: FilesystemPort): Array<string>;

package/dist/core/workspace/markdown-walk.js

@@ -1,27 +1,9 @@
-import path from "node:path";
-import { defaultSkipDirectoryNames } from "#/core/workspace/skip-directories";
+import { walkFiles } from "#/core/workspace/walk-files";
 /**
  * Every markdown file under a root, skipping build output and vendored trees.
  *
  * @since 0.5.0
  */
 export function walkMarkdownFiles(rootDirectoryPath, fs) {
-    const result = [];
-    visitMarkdownPaths(result, rootDirectoryPath, fs);
-    return result;
-}
-function visitMarkdownPaths(result, entryPath, fs) {
-    const entryStats = fs.statSync(entryPath);
-    if (entryStats.isDirectory()) {
-        for (const childName of fs.readdirSync(entryPath)) {
-            if (defaultSkipDirectoryNames.has(childName)) {
-                continue;
-            }
-            visitMarkdownPaths(result, path.join(entryPath, childName), fs);
-        }
-        return;
-    }
-    if (entryPath.endsWith(".md")) {
-        result.push(entryPath);
-    }
+    return walkFiles(rootDirectoryPath, fs, (filePath) => filePath.endsWith(".md"));
 }

package/dist/core/workspace/package-version.d.ts

@@ -0,0 +1,9 @@
+import type { FilesystemPort } from "#/core/filesystem/port";
+/**
+ * Finds the `version` of the nearest enclosing `package.json`, or null when the first
+ * one found declares none (the private workspace root is version-less by design).
+ *
+ * @since 0.8.0
+ */
+declare function findNearestPackageVersion(fs: FilesystemPort, targetPath: string): string | null;
+export { findNearestPackageVersion };

package/dist/core/workspace/package-version.js

@@ -1,4 +1,6 @@
 import path from "node:path";
+import { findNearestAncestor } from "#/core/workspace/ancestor-directories";
+import { packageJsonFileName } from "#/core/workspace/well-known-files";
 /**
  * Finds the `version` of the nearest enclosing `package.json`, or null when the first
  * one found declares none (the private workspace root is version-less by design).
@@ -7,18 +9,12 @@ import path from "node:path";
  */
 function findNearestPackageVersion(fs, targetPath) {
     const resolved = path.resolve(targetPath);
-    let current = fs.statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
-    while (true) {
-        const packageJsonPath = path.join(current, "package.json");
-        if (fs.existsSync(packageJsonPath)) {
-            const version = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")).version;
-            return typeof version === "string" && version.length > 0 ? version : null;
-        }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
+    const startDirectory = fs.statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
+    const packageDirectory = findNearestAncestor(startDirectory, (directoryPath) => fs.existsSync(path.join(directoryPath, packageJsonFileName)));
+    if (packageDirectory === undefined) {
+        return null;
     }
+    const version = JSON.parse(fs.readFileSync(path.join(packageDirectory, packageJsonFileName), "utf8")).version;
+    return typeof version === "string" && version.length > 0 ? version : null;
 }
 export { findNearestPackageVersion };

package/dist/core/workspace/resolver.d.ts

@@ -0,0 +1,39 @@
+import type { FilesystemPort } from "#/core/filesystem/port";
+/**
+ * A resolved project root and whether it is a pnpm workspace or a standalone single package.
+ *
+ * @since 0.10.0
+ */
+export type ResolvedProjectRoot = {
+    readonly rootDir: string;
+    readonly mode: "workspace" | "single-package";
+};
+/**
+ * Resolves the project root: the `pnpm-workspace.yaml` directory, or the nearest `package.json` for a single package.
+ *
+ * @since 0.10.0
+ */
+export declare function resolveProjectRoot(fromDirectory: string, fs: FilesystemPort): ResolvedProjectRoot;
+/**
+ * Where the workspace package patterns came from.
+ *
+ * @since 0.3.16-canary.0
+ */
+type WorkspacePackageLayoutSource = "pnpm-workspace-yaml" | "default-patterns" | "declared-empty" | "single-package";
+/**
+ * The discovered workspace package directories together with how the layout was determined.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type WorkspacePackageLayoutOutcome = {
+    readonly packageDirectoryPathsAbsolute: Array<string>;
+    readonly layoutSource: WorkspacePackageLayoutSource;
+    readonly hasPnpmWorkspaceYamlFile: boolean;
+};
+/**
+ * Lists the workspace's package directories per `pnpm-workspace.yaml`, falling back to default patterns.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function listWorkspacePackageDirectories(rootDirectoryPathAbsolute: string, fs: FilesystemPort, suppressGlobPermissionDiagnostics?: boolean): Promise<WorkspacePackageLayoutOutcome>;
+export {};