@codefast/cli 0.8.1 → 0.10.0

package/dist/audit/output.js

@@ -83,19 +83,19 @@ export function formatLinkAuditJsonOutput(result, rootDir) {
     });
 }
 /**
- * Exit `1` when any non-allowlisted React import-policy violation remains.
+ * Exit `1` when any non-allowlisted import-policy violation remains.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export function exitCodeForReactAuditResult(result) {
+export function exitCodeForImportsAuditResult(result) {
     return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
 }
 /**
- * Human-readable React import-policy report.
+ * Human-readable import-policy report.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export function presentReactAuditResult(result) {
+export function presentImportsAuditResult(result) {
     for (const file of result.files) {
         logger.out(`\n${file.relativePath}`);
         for (const { line, raw, reason } of file.violations) {
@@ -104,18 +104,18 @@ export function presentReactAuditResult(result) {
     }
     const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
     if (result.violationCount > 0) {
-        logger.out(`\n✖ ${result.violationCount} React import violation(s)${allowlistSuffix}`);
+        logger.out(`\n✖ ${result.violationCount} import-policy violation(s)${allowlistSuffix}`);
     }
     else {
-        logger.out(`✓ No namespace/default React imports or React.* UMD globals across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
+        logger.out(`✓ No import-policy violations across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
     }
 }
 /**
- * Machine-readable React import-policy summary for `--json`.
+ * Machine-readable import-policy summary for `--json`.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export function formatReactAuditJsonOutput(result, rootDir) {
+export function formatImportsAuditJsonOutput(result, rootDir) {
     return JSON.stringify({
         schemaVersion: 1,
         ok: result.violationCount === 0,
@@ -169,4 +169,45 @@ export function formatCommentAuditJsonOutput(result, rootDir) {
 }
 function truncate(raw) {
     return raw.length <= 60 ? raw : `${raw.slice(0, 57)}…`;
+}
+/**
+ * Exit `1` when any non-allowlisted display-name violation remains.
+ *
+ * @since 0.9.0
+ */
+export function exitCodeForDisplayNameAuditResult(result) {
+    return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Human-readable display-name report.
+ *
+ * @since 0.9.0
+ */
+export function presentDisplayNameAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.violations) {
+            logger.out(`  ${line}: ${raw} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.violationCount > 0) {
+        logger.out(`\n✖ ${result.violationCount} display name(s) off the convention${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ Every token, tag and module display name follows <namespace>:<Name> across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
+    }
+}
+/**
+ * Machine-readable display-name summary for `--json`.
+ *
+ * @since 0.9.0
+ */
+export function formatDisplayNameAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.violationCount === 0,
+        cwd: rootDir,
+        result,
+    });
 }

package/dist/audit/prepare.d.ts

@@ -0,0 +1,70 @@
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Shared prelude for `audit rtl`: repo root and the canonicalized scan target with its allowlist.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlAuditCommandPrelude = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+};
+/**
+ * Loads config and resolves the scan target for `audit rtl`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function prepareRtlAudit(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
+/**
+ * Loads config and resolves the scan target for `audit links`.
+ *
+ * @remarks Defaults to the repo root rather than a configured path: a link audit that only covers one
+ * package cannot see the cross-package references that are the ones most likely to rot.
+ *
+ * @since 0.5.0
+ */
+export declare function prepareLinkAudit(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
+/**
+ * Loads config and resolves the scan target for `audit imports`.
+ *
+ * @remarks Defaults to the repo root: the import policy is repo-wide, and generated or vendored
+ * trees are already excluded by the shared walk.
+ *
+ * @since 0.10.0
+ */
+export declare function prepareImportsAudit(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
+/**
+ * Loads config and resolves the scan target for `audit comments`.
+ *
+ * @remarks Defaults to the repo root: a divider convention that only holds inside one package
+ * is not a convention.
+ *
+ * @since 0.6.0
+ */
+export declare function prepareCommentAudit(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
+/**
+ * Loads config and resolves the scan target for `audit display-names`.
+ *
+ * @remarks Defaults to the repo root: a display name collides across packages, so the convention
+ * has to hold across them.
+ *
+ * @since 0.9.0
+ */
+export declare function prepareDisplayNameAudit(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<RtlAuditCommandPrelude, AppError>>;

package/dist/audit/prepare.js

@@ -2,7 +2,7 @@ import { resolveRepoRelativePath } from "#/audit/cli-schema";
 import { loadCodefastConfig } from "#/core/config";
 import { AppError, messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
-import { findRepoRoot } from "#/core/workspace/resolver";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
 /**
  * Loads config and resolves the scan target for `audit rtl`.
  *
@@ -12,7 +12,7 @@ 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(findRepoRoot(args.currentWorkingDirectory, fs));
+        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
     }
     catch (caughtError) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
@@ -50,7 +50,7 @@ export async function prepareRtlAudit(fs, args) {
 export async function prepareLinkAudit(fs, args) {
     let rootDir;
     try {
-        rootDir = fs.canonicalPathSync(findRepoRoot(args.currentWorkingDirectory, fs));
+        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
     }
     catch (caughtError) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
@@ -71,17 +71,17 @@ export async function prepareLinkAudit(fs, args) {
     });
 }
 /**
- * Loads config and resolves the scan target for `audit react`.
+ * Loads config and resolves the scan target for `audit imports`.
  *
  * @remarks Defaults to the repo root: the import policy is repo-wide, and generated or vendored
  * trees are already excluded by the shared walk.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export async function prepareReactAudit(fs, args) {
+export async function prepareImportsAudit(fs, args) {
     let rootDir;
     try {
-        rootDir = fs.canonicalPathSync(findRepoRoot(args.currentWorkingDirectory, fs));
+        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
     }
     catch (caughtError) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
@@ -90,7 +90,7 @@ export async function prepareReactAudit(fs, args) {
     if (!loadedOutcome.ok) {
         return loadedOutcome;
     }
-    const reactConfig = loadedOutcome.value.config.audit?.react ?? {};
+    const importsConfig = loadedOutcome.value.config.audit?.imports ?? {};
     const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
     if (!fs.existsSync(targetPath)) {
         return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
@@ -98,7 +98,7 @@ export async function prepareReactAudit(fs, args) {
     return ok({
         rootDir,
         targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: reactConfig.allowlist ?? [],
+        allowlist: importsConfig.allowlist ?? [],
     });
 }
 /**
@@ -112,7 +112,7 @@ export async function prepareReactAudit(fs, args) {
 export async function prepareCommentAudit(fs, args) {
     let rootDir;
     try {
-        rootDir = fs.canonicalPathSync(findRepoRoot(args.currentWorkingDirectory, fs));
+        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
     }
     catch (caughtError) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
@@ -131,4 +131,35 @@ export async function prepareCommentAudit(fs, args) {
         targetPath: fs.canonicalPathSync(targetPath),
         allowlist: commentsConfig.allowlist ?? [],
     });
+}
+/**
+ * Loads config and resolves the scan target for `audit display-names`.
+ *
+ * @remarks Defaults to the repo root: a display name collides across packages, so the convention
+ * has to hold across them.
+ *
+ * @since 0.9.0
+ */
+export async function prepareDisplayNameAudit(fs, args) {
+    let rootDir;
+    try {
+        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 displayNamesConfig = loadedOutcome.value.config.audit?.displayNames ?? {};
+    const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
+    if (!fs.existsSync(targetPath)) {
+        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
+    }
+    return ok({
+        rootDir,
+        targetPath: fs.canonicalPathSync(targetPath),
+        allowlist: displayNamesConfig.allowlist ?? [],
+    });
 }

package/dist/audit/run-comments.d.ts

@@ -0,0 +1,17 @@
+import type { CommentAuditResult } from "#/audit/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Reports every comment off the repo's conventions: divider form (which `fix` rewrites), banned
+ * content — document pointers, JSDoc types, tag misuse — `{@link}` targets nothing declares, and
+ * every diagnostic the official TSDoc parser raises against a doc block's grammar.
+ *
+ * @since 0.6.0
+ */
+export declare function runCommentAudit(fs: FilesystemPort, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+    readonly fix: boolean;
+}): Result<CommentAuditResult, AppError>;

package/dist/audit/run-comments.js

@@ -68,30 +68,34 @@ export function runCommentAudit(fs, args) {
                 }
                 breakages.push({ line: region.startLine, raw: region.raw, reason: reasonByDefect[region.defect] });
             }
-            for (const finding of scanCommentContent(content, language)) {
-                if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
-                    allowlistedCount++;
-                    continue;
-                }
-                breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect[finding.defect] });
-            }
-            const packageVersion = nearestVersion(fs, absolutePath, versionByDirectory);
-            if (packageVersion !== null) {
-                for (const finding of scanImpossibleSinceTags(content, packageVersion)) {
+            // The content rules — banned fragments, `@since`, TSDoc grammar — govern doc comments in
+            // code; an ignore file carries only the divider convention.
+            if (language !== "ignore") {
+                for (const finding of scanCommentContent(content, language)) {
                     if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
                         allowlistedCount++;
                         continue;
                     }
-                    breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect["since-impossible"] });
+                    breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect[finding.defect] });
                 }
-            }
-            if (language === "js") {
-                for (const finding of scanTsdocSyntax(content)) {
-                    if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
-                        allowlistedCount++;
-                        continue;
+                const packageVersion = nearestVersion(fs, absolutePath, versionByDirectory);
+                if (packageVersion !== null) {
+                    for (const finding of scanImpossibleSinceTags(content, packageVersion)) {
+                        if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
+                            allowlistedCount++;
+                            continue;
+                        }
+                        breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect["since-impossible"] });
+                    }
+                }
+                if (language === "js") {
+                    for (const finding of scanTsdocSyntax(content)) {
+                        if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
+                            allowlistedCount++;
+                            continue;
+                        }
+                        breakages.push({ line: finding.line, raw: finding.raw, reason: finding.reason });
                     }
-                    breakages.push({ line: finding.line, raw: finding.raw, reason: finding.reason });
                 }
             }
             if (breakages.length > 0) {

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

@@ -0,0 +1,14 @@
+import type { DisplayNameAuditResult } from "#/audit/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Scans a target path for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @since 0.9.0
+ */
+export declare function runDisplayNameAudit(fs: FilesystemPort, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<DisplayNameAuditResult, AppError>;

package/dist/audit/run-display-names.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { auditDisplayNames } from "#/audit/domain/display-names";
+import { AppError, messageFrom } from "#/core/errors";
+import { err, ok } from "#/core/result";
+import { walkMarkdownFiles } from "#/core/workspace/markdown-walk";
+import { walkTsxFiles } from "#/core/workspace/typescript-walk";
+/**
+ * Trees the convention does not reach: a test or benchmark token is scoped by its file and never
+ * meets another author's, and a changelog quotes names as they were.
+ */
+const SKIPPED_SEGMENTS = new Set(["tests", "benchmarks", ".changeset"]);
+const SKIPPED_BASENAMES = new Set(["CHANGELOG.md"]);
+/**
+ * Scans a target path for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @since 0.9.0
+ */
+export function runDisplayNameAudit(fs, args) {
+    try {
+        const allowlist = new Set(args.allowlist);
+        const { rootDir, targetPath } = args;
+        const filesToScan = collectScanPaths(fs, rootDir, targetPath);
+        const files = [];
+        let violationCount = 0;
+        let allowlistedCount = 0;
+        for (const absolutePath of filesToScan) {
+            const relativePath = toPosixPath(path.relative(rootDir, absolutePath));
+            const content = fs.readFileSync(absolutePath, "utf8");
+            const remaining = auditDisplayNames(content).filter(({ raw }) => {
+                const isAllowed = allowlist.has(raw) || allowlist.has(`${relativePath}:${raw}`);
+                if (isAllowed) {
+                    allowlistedCount++;
+                }
+                return !isAllowed;
+            });
+            if (remaining.length === 0) {
+                continue;
+            }
+            violationCount += remaining.length;
+            files.push({ relativePath, violations: remaining });
+        }
+        return ok({ files, violationCount, allowlistedCount, scannedFileCount: filesToScan.length });
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+}
+function collectScanPaths(fs, rootDir, targetPath) {
+    const stats = fs.statSync(targetPath);
+    const candidates = stats.isFile()
+        ? [targetPath]
+        : [...walkTsxFiles(targetPath, fs), ...walkMarkdownFiles(targetPath, fs)];
+    return candidates.filter((absolutePath) => {
+        const relative = path.relative(rootDir, absolutePath).split(path.sep);
+        return !relative.some((segment) => SKIPPED_SEGMENTS.has(segment)) && !SKIPPED_BASENAMES.has(relative.at(-1));
+    });
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join("/");
+}

package/dist/audit/run-imports.d.ts

@@ -0,0 +1,14 @@
+import type { ImportsAuditResult } from "#/audit/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Scans a target path for import-policy violations, applying each rule only to files in its scope.
+ *
+ * @since 0.10.0
+ */
+export declare function runImportsAudit(fs: FilesystemPort, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<ImportsAuditResult, AppError>;

package/dist/audit/{run-react.js → run-imports.js}

@@ -1,25 +1,35 @@
 import path from "node:path";
-import { auditReactImportSource } from "#/audit/domain/react-imports";
+import { defaultImportPolicyRules } from "#/audit/domain/import-policy";
+import { auditImportPolicySource } from "#/audit/domain/import-policy";
 import { AppError, messageFrom } from "#/core/errors";
+import { createAnyGlobMatcher } from "#/core/glob";
 import { err, ok } from "#/core/result";
 import { walkTsxFiles } from "#/core/workspace/typescript-walk";
 /**
- * Scans a target path for React import-policy violations.
+ * Scans a target path for import-policy violations, applying each rule only to files in its scope.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export function runReactAudit(fs, args) {
+export function runImportsAudit(fs, args) {
     try {
         const allowlist = new Set(args.allowlist);
         const { rootDir, targetPath } = args;
+        const scopedRules = defaultImportPolicyRules.map((rule) => ({
+            rule,
+            isInScope: rule.scope ? createAnyGlobMatcher(rule.scope, { dot: true }) : () => true,
+        }));
         const filesToScan = collectScanPaths(fs, targetPath);
         const files = [];
         let violationCount = 0;
         let allowlistedCount = 0;
         for (const absolutePath of filesToScan) {
             const relativePath = toPosixPath(path.relative(rootDir, absolutePath));
+            const applicableRules = scopedRules.filter(({ isInScope }) => isInScope(relativePath)).map(({ rule }) => rule);
+            if (applicableRules.length === 0) {
+                continue;
+            }
             const content = fs.readFileSync(absolutePath, "utf8");
-            const remaining = auditReactImportSource(absolutePath, content).filter(({ raw }) => {
+            const remaining = auditImportPolicySource(absolutePath, content, applicableRules).filter(({ raw }) => {
                 const isAllowed = allowlist.has(raw) || allowlist.has(`${relativePath}:${raw}`);
                 if (isAllowed) {
                     allowlistedCount++;

package/dist/audit/run-links.d.ts

@@ -0,0 +1,14 @@
+import type { LinkAuditResult } from "#/audit/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Reports markdown links that point at nothing — a missing path, or an anchor the target does not offer.
+ *
+ * @since 0.5.0
+ */
+export declare function runLinkAudit(fs: FilesystemPort, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<LinkAuditResult, AppError>;

package/dist/audit/run.d.ts

@@ -0,0 +1,14 @@
+import type { RtlAuditResult } from "#/audit/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+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: FilesystemPort, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<RtlAuditResult, AppError>;

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/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 { 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/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/result-handle.d.ts

@@ -0,0 +1,19 @@
+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;
+};
+/**
+ * Awaits a `Result`, hands a success to `onSuccess`, and records the returned exit code on the process.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runCliResultAsync<Value>(outcomePromise: Promise<Result<Value, AppError>>, onSuccess: (value: Value) => number | void | Promise<number | void>): Promise<void>;

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 { FilesystemPort } from "#/core/filesystem/port";
+/**
+ * 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: FilesystemPort): 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;
 }