@codefast/cli 0.10.0 → 0.11.0

package/dist/arrange/{simplify-sync.d.ts → simplify/run.d.ts}

@@ -1,13 +1,14 @@
 import type { ArrangeRunResult } from "#/arrange/domain/types";
 import type { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 import type { Result } from "#/core/result";
 /**
  * Runs the simplify pass over every target file and returns the aggregated result.
  *
  * @since 0.3.16-canary.0
  */
-export declare function runArrangeSimplify(fs: FilesystemPort, args: {
+export declare function runArrangeSimplify(fs: Filesystem, args: {
     targetPath: string;
     write: boolean;
+    foldVariantClassName?: boolean | undefined;
 }): Promise<Result<ArrangeRunResult, AppError>>;

package/dist/arrange/simplify/run.js

@@ -0,0 +1,38 @@
+import { scanArrangeTargets } from "#/arrange/scan-target";
+import { processArrangeSimplifyFile } from "#/arrange/simplify/process-file";
+import { createVariantClassNameProbe } from "#/arrange/simplify/variant-classname-probe";
+import { ok } from "#/core/result";
+/**
+ * Runs the simplify pass over every target file and returns the aggregated result.
+ *
+ * @since 0.3.16-canary.0
+ */
+export async function runArrangeSimplify(fs, args) {
+    const filePaths = scanArrangeTargets(fs, args.targetPath);
+    const modifiedFiles = [];
+    let totalFound = 0;
+    let totalChanged = 0;
+    // The type probe spawns a TypeScript server, so it is created once and only when the fold is requested.
+    const probe = args.foldVariantClassName ? await createVariantClassNameProbe() : null;
+    try {
+        for (const filePath of filePaths) {
+            const result = processArrangeSimplifyFile(fs, { filePath, write: args.write, probe });
+            totalFound += result.totalFound;
+            totalChanged += result.changed;
+            if (result.changed > 0) {
+                modifiedFiles.push(result.filePath);
+            }
+        }
+    }
+    finally {
+        probe?.dispose();
+    }
+    return ok({
+        filePaths,
+        modifiedFiles,
+        totalFound,
+        totalChanged,
+        hookError: null,
+        previewPlans: [],
+    });
+}

package/dist/arrange/simplify/variant-classname-probe.d.ts

@@ -0,0 +1,35 @@
+/** Type probe that asks whether a variant function's options accept a folded `className`. */
+/**
+ * What a variant function's `className`/`class` option accepts, resolved from its type.
+ *
+ * @since 0.11.0
+ */
+export interface VariantClassNameAcceptance {
+    readonly acceptsString: boolean;
+    readonly acceptsArray: boolean;
+}
+/**
+ * A per-file view that resolves a callee's `className` acceptance from a source offset.
+ *
+ * @since 0.11.0
+ */
+export interface FileClassNameProbe {
+    classNameAcceptance(calleeOffset: number): VariantClassNameAcceptance | null;
+}
+/**
+ * A whole-run type probe backing the opt-in `className` fold, bound to one type server.
+ *
+ * @since 0.11.0
+ */
+export interface VariantClassNameProbe {
+    forFile(filePath: string): FileClassNameProbe | null;
+    dispose(): void;
+}
+/**
+ * Creates a type probe over the native TypeScript type server for the opt-in `className` fold.
+ *
+ * @throws AppError when the `typescript` package providing the type server cannot be loaded.
+ *
+ * @since 0.11.0
+ */
+export declare function createVariantClassNameProbe(): Promise<VariantClassNameProbe>;

package/dist/arrange/simplify/variant-classname-probe.js

@@ -0,0 +1,95 @@
+/** Type probe that asks whether a variant function's options accept a folded `className`. */
+import { AppError, messageFrom } from "#/core/errors";
+// ── Type inspection ──────────────────────────────────────────────────────────────────────────────────────────────────
+/** The type of the callee's first-parameter `className` (preferred) or `class` option, if any. */
+function classNameOptionType(checker, optionsType) {
+    for (const name of ["className", "class"]) {
+        const symbol = checker.getPropertyOfType(optionsType, name);
+        if (symbol) {
+            const propertyType = checker.getTypeOfSymbol(symbol);
+            if (propertyType) {
+                return propertyType;
+            }
+        }
+    }
+    return undefined;
+}
+/** True when any constituent of the option type is array-like — the option accepts a class array. */
+function optionAcceptsArray(checker, optionType) {
+    const constituents = optionType.isUnionType() ? optionType.getTypes() : [optionType];
+    return constituents.some((constituent) => checker.isArrayType(constituent) || checker.isTupleType(constituent) || checker.isArrayLikeType(constituent));
+}
+/** Resolves how the function called at `offset` accepts a `className`, or `null` when it is not a variant function. */
+function classNameAcceptanceAt(checker, callKind, filePath, offset) {
+    const calleeType = checker.getTypeAtPosition(filePath, offset);
+    if (!calleeType) {
+        return null;
+    }
+    const signature = checker.getSignaturesOfType(calleeType, callKind)[0];
+    if (!signature) {
+        return null;
+    }
+    const parameterType = checker.getParameterType(signature, 0);
+    if (!parameterType) {
+        return null;
+    }
+    const nonNullableType = checker.getNonNullableType(parameterType);
+    if (!nonNullableType) {
+        return null;
+    }
+    const optionsType = checker.getApparentType(nonNullableType);
+    if (!optionsType) {
+        return null;
+    }
+    const optionType = classNameOptionType(checker, optionsType);
+    if (!optionType) {
+        return null;
+    }
+    return {
+        acceptsString: checker.isTypeAssignableTo(checker.getStringType(), optionType),
+        acceptsArray: optionAcceptsArray(checker, optionType),
+    };
+}
+// ── Probe lifecycle ──────────────────────────────────────────────────────────────────────────────────────────────────
+/** Loads the native TypeScript type-server API, or fails with a coded error naming the missing package. */
+async function loadTypeServer() {
+    try {
+        return await import("typescript/unstable/sync");
+    }
+    catch (cause) {
+        throw new AppError("INFRA_FAILURE", `--fold-variant-classname needs the "typescript" package (v7) resolvable from the target: ${messageFrom(cause)}`, cause);
+    }
+}
+/**
+ * Creates a type probe over the native TypeScript type server for the opt-in `className` fold.
+ *
+ * @throws AppError when the `typescript` package providing the type server cannot be loaded.
+ *
+ * @since 0.11.0
+ */
+export async function createVariantClassNameProbe() {
+    const sync = await loadTypeServer();
+    const api = new sync.API();
+    const callKind = sync.SignatureKind.Call;
+    return {
+        forFile(filePath) {
+            try {
+                const project = api.updateSnapshot({ openFiles: [filePath] }).getDefaultProjectForFile(filePath);
+                if (!project) {
+                    return null;
+                }
+                const { checker } = project;
+                return {
+                    classNameAcceptance: (offset) => classNameAcceptanceAt(checker, callKind, filePath, offset),
+                };
+            }
+            catch {
+                // A file outside any tsconfig has no project to type against — skip its fold, keep the base pass.
+                return null;
+            }
+        },
+        dispose() {
+            api.close();
+        },
+    };
+}

package/dist/arrange/source-parse.js

@@ -1,4 +1,4 @@
-import { TypeScriptAstTranslator } from "#/arrange/typescript-ast-translator";
+import { TypeScriptAstTranslator } from "#/arrange/domain/ast/translator";
 import { messageFrom } from "#/core/errors";
 import { logger } from "#/core/logger";
 const translator = new TypeScriptAstTranslator();

package/dist/audit/command.js

@@ -1,18 +1,134 @@
-import process from "node:process";
 import { Command } from "commander";
-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 { readOptionalPositionalArg } from "#/core/cli/positional";
-import { consumeCliAppError } from "#/core/cli/result-handle";
+import { exitCodeForCommentAuditResult, formatCommentAuditJsonOutput } from "#/audit/comments/cli-result";
+import { commentAuditRunRequestSchema } from "#/audit/comments/cli-schema";
+import { presentCommentAuditResult } from "#/audit/comments/output";
+import { prepareCommentAudit } from "#/audit/comments/prepare";
+import { runCommentAudit } from "#/audit/comments/run";
+import { exitCodeForDisplayNameAuditResult, formatDisplayNameAuditJsonOutput } from "#/audit/display-names/cli-result";
+import { displayNameAuditRunRequestSchema } from "#/audit/display-names/cli-schema";
+import { presentDisplayNameAuditResult } from "#/audit/display-names/output";
+import { prepareDisplayNameAudit } from "#/audit/display-names/prepare";
+import { runDisplayNameAudit } from "#/audit/display-names/run";
+import { exitCodeForImportsAuditResult, formatImportsAuditJsonOutput } from "#/audit/imports/cli-result";
+import { importsAuditRunRequestSchema } from "#/audit/imports/cli-schema";
+import { presentImportsAuditResult } from "#/audit/imports/output";
+import { prepareImportsAudit } from "#/audit/imports/prepare";
+import { runImportsAudit } from "#/audit/imports/run";
+import { exitCodeForLinkAuditResult, formatLinkAuditJsonOutput } from "#/audit/links/cli-result";
+import { linkAuditRunRequestSchema } from "#/audit/links/cli-schema";
+import { presentLinkAuditResult } from "#/audit/links/output";
+import { prepareLinkAudit } from "#/audit/links/prepare";
+import { runLinkAudit } from "#/audit/links/run";
+import { exitCodeForRtlAuditResult, formatRtlAuditJsonOutput } from "#/audit/rtl/cli-result";
+import { rtlAuditRunRequestSchema } from "#/audit/rtl/cli-schema";
+import { presentRtlAuditResult } from "#/audit/rtl/output";
+import { prepareRtlAudit } from "#/audit/rtl/prepare";
+import { runRtlAudit } from "#/audit/rtl/run";
+import { registerPipelineSubcommand } from "#/core/cli/command-pipeline";
 import { nodeFilesystem } from "#/core/filesystem/node";
-import { logger } from "#/core/logger";
-import { parseWithSchema } from "#/core/schema-parse";
+function baseAuditRequest(prelude, opts) {
+    return {
+        rootDir: prelude.rootDir,
+        targetPath: prelude.targetPath,
+        allowlist: prelude.allowlist,
+        json: !!opts.json,
+    };
+}
+const rtlCheck = {
+    name: "rtl",
+    description: "Report physical-direction Tailwind classes that should be logical or rtl:-paired",
+    targetHelp: "Directory or file to scan (default: audit.rtl.target from config)",
+    schema: rtlAuditRunRequestSchema,
+    prepare: prepareRtlAudit,
+    buildRequest: baseAuditRequest,
+    run: (fs, request) => runRtlAudit(fs, { rootDir: request.rootDir, targetPath: request.targetPath, allowlist: request.allowlist ?? [] }),
+    present: presentRtlAuditResult,
+    formatJson: formatRtlAuditJsonOutput,
+    exitCode: exitCodeForRtlAuditResult,
+};
+const linksCheck = {
+    name: "links",
+    description: "Report markdown links pointing at a missing path or an anchor the target does not offer",
+    targetHelp: "Directory or file to scan (default: the repo root)",
+    schema: linkAuditRunRequestSchema,
+    prepare: prepareLinkAudit,
+    buildRequest: baseAuditRequest,
+    run: (fs, request) => runLinkAudit(fs, { rootDir: request.rootDir, targetPath: request.targetPath, allowlist: request.allowlist ?? [] }),
+    present: presentLinkAuditResult,
+    formatJson: formatLinkAuditJsonOutput,
+    exitCode: exitCodeForLinkAuditResult,
+};
+const importsCheck = {
+    name: "imports",
+    description: "Report banned import forms (React by-name, Zod namespace in front-end packages, …)",
+    targetHelp: "Directory or file to scan (default: the repo root)",
+    schema: importsAuditRunRequestSchema,
+    prepare: prepareImportsAudit,
+    buildRequest: baseAuditRequest,
+    run: (fs, request) => runImportsAudit(fs, {
+        rootDir: request.rootDir,
+        targetPath: request.targetPath,
+        allowlist: request.allowlist ?? [],
+    }),
+    present: presentImportsAuditResult,
+    formatJson: formatImportsAuditJsonOutput,
+    exitCode: exitCodeForImportsAuditResult,
+};
+const displayNamesCheck = {
+    name: "display-names",
+    description: "Report token(), tag() and module display names that break the <namespace>:<Name> convention",
+    targetHelp: "Directory or file to scan (default: the repo root)",
+    schema: displayNameAuditRunRequestSchema,
+    prepare: prepareDisplayNameAudit,
+    buildRequest: baseAuditRequest,
+    run: (fs, request) => runDisplayNameAudit(fs, {
+        rootDir: request.rootDir,
+        targetPath: request.targetPath,
+        allowlist: request.allowlist ?? [],
+    }),
+    present: presentDisplayNameAuditResult,
+    formatJson: formatDisplayNameAuditJsonOutput,
+    exitCode: exitCodeForDisplayNameAuditResult,
+};
+const commentsCheck = {
+    name: "comments",
+    description: "Report section dividers that are not in the repo's one allowed form",
+    targetHelp: "Directory or file to scan (default: the repo root)",
+    schema: commentAuditRunRequestSchema,
+    prepare: prepareCommentAudit,
+    buildRequest: (prelude, opts) => ({ ...baseAuditRequest(prelude, opts), fix: !!opts.fix }),
+    run: (fs, request) => runCommentAudit(fs, {
+        rootDir: request.rootDir,
+        targetPath: request.targetPath,
+        allowlist: request.allowlist ?? [],
+        fix: request.fix,
+    }),
+    present: presentCommentAuditResult,
+    formatJson: formatCommentAuditJsonOutput,
+    exitCode: exitCodeForCommentAuditResult,
+    extraOptions: (command) => {
+        command.option("--fix", "Rewrite every mechanically fixable divider in place", false);
+    },
+};
+/**
+ * Adapts an `AuditCheck` descriptor onto the shared command pipeline.
+ */
+function auditCheckToPipeline(check) {
+    return {
+        name: check.name,
+        description: check.description,
+        positional: { name: "[target]", help: check.targetHelp },
+        jsonHelp: "Print one JSON summary on stdout",
+        schema: check.schema,
+        configureArgv: check.extraOptions,
+        prepare: (fs, input) => check.prepare(fs, { currentWorkingDirectory: input.currentWorkingDirectory, rawTarget: input.rawArg }),
+        buildRequest: ({ prelude, opts }) => check.buildRequest(prelude, opts),
+        run: async (fs, request) => check.run(fs, request),
+        presentHuman: ({ result }) => check.present(result),
+        formatJson: ({ result, prelude }) => check.formatJson(result, prelude.rootDir),
+        exitCode: check.exitCode,
+    };
+}
 /**
  * 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.
@@ -21,203 +137,10 @@ import { parseWithSchema } from "#/core/schema-parse";
  */
 export function createAuditCommand() {
     const cmd = new Command("audit").description("Source audits").enablePositionalOptions();
-    cmd
-        .command("rtl")
-        .description("Report physical-direction Tailwind classes that should be logical or rtl:-paired")
-        .argument("[target]", "Directory or file to scan (default: audit.rtl.target from config)")
-        .option("--json", "Print one JSON summary on stdout", false)
-        .action(async (target, opts) => {
-        const prelude = await prepareRtlAudit(nodeFilesystem, {
-            currentWorkingDirectory: process.cwd(),
-            rawTarget: readOptionalPositionalArg(target),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(rtlAuditRunRequestSchema, {
-            rootDir,
-            targetPath,
-            allowlist,
-            json: !!opts.json,
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        const outcome = runRtlAudit(nodeFilesystem, {
-            rootDir: parsed.value.rootDir,
-            targetPath: parsed.value.targetPath,
-            allowlist: parsed.value.allowlist ?? [],
-        });
-        if (!consumeCliAppError(outcome)) {
-            return;
-        }
-        if (parsed.value.json) {
-            logger.out(formatRtlAuditJsonOutput(outcome.value, rootDir));
-        }
-        else {
-            presentRtlAuditResult(outcome.value);
-        }
-        process.exitCode = exitCodeForRtlAuditResult(outcome.value);
-    });
-    cmd
-        .command("links")
-        .description("Report markdown links pointing at a missing path or an anchor the target does not offer")
-        .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 prepareLinkAudit(nodeFilesystem, {
-            currentWorkingDirectory: process.cwd(),
-            rawTarget: readOptionalPositionalArg(target),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(linkAuditRunRequestSchema, {
-            rootDir,
-            targetPath,
-            allowlist,
-            json: !!opts.json,
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        const outcome = runLinkAudit(nodeFilesystem, {
-            rootDir: parsed.value.rootDir,
-            targetPath: parsed.value.targetPath,
-            allowlist: parsed.value.allowlist ?? [],
-        });
-        if (!consumeCliAppError(outcome)) {
-            return;
-        }
-        if (parsed.value.json) {
-            logger.out(formatLinkAuditJsonOutput(outcome.value, rootDir));
-        }
-        else {
-            presentLinkAuditResult(outcome.value);
-        }
-        process.exitCode = exitCodeForLinkAuditResult(outcome.value);
-    });
-    cmd
-        .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 prepareImportsAudit(nodeFilesystem, {
-            currentWorkingDirectory: process.cwd(),
-            rawTarget: readOptionalPositionalArg(target),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(importsAuditRunRequestSchema, {
-            rootDir,
-            targetPath,
-            allowlist,
-            json: !!opts.json,
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        const outcome = runImportsAudit(nodeFilesystem, {
-            rootDir: parsed.value.rootDir,
-            targetPath: parsed.value.targetPath,
-            allowlist: parsed.value.allowlist ?? [],
-        });
-        if (!consumeCliAppError(outcome)) {
-            return;
-        }
-        if (parsed.value.json) {
-            logger.out(formatImportsAuditJsonOutput(outcome.value, rootDir));
-        }
-        else {
-            presentImportsAuditResult(outcome.value);
-        }
-        process.exitCode = exitCodeForImportsAuditResult(outcome.value);
-    });
-    cmd
-        .command("display-names")
-        .description("Report token(), tag() and module display names that break the <namespace>:<Name> convention")
-        .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 prepareDisplayNameAudit(nodeFilesystem, {
-            currentWorkingDirectory: process.cwd(),
-            rawTarget: readOptionalPositionalArg(target),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(displayNameAuditRunRequestSchema, {
-            rootDir,
-            targetPath,
-            allowlist,
-            json: !!opts.json,
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        const outcome = runDisplayNameAudit(nodeFilesystem, {
-            rootDir: parsed.value.rootDir,
-            targetPath: parsed.value.targetPath,
-            allowlist: parsed.value.allowlist ?? [],
-        });
-        if (!consumeCliAppError(outcome)) {
-            return;
-        }
-        if (parsed.value.json) {
-            logger.out(formatDisplayNameAuditJsonOutput(outcome.value, rootDir));
-        }
-        else {
-            presentDisplayNameAuditResult(outcome.value);
-        }
-        process.exitCode = exitCodeForDisplayNameAuditResult(outcome.value);
-    });
-    cmd
-        .command("comments")
-        .description("Report section dividers that are not in the repo's one allowed form")
-        .argument("[target]", "Directory or file to scan (default: the repo root)")
-        .option("--fix", "Rewrite every mechanically fixable divider in place", false)
-        .option("--json", "Print one JSON summary on stdout", false)
-        .action(async (target, opts) => {
-        const prelude = await prepareCommentAudit(nodeFilesystem, {
-            currentWorkingDirectory: process.cwd(),
-            rawTarget: readOptionalPositionalArg(target),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(commentAuditRunRequestSchema, {
-            rootDir,
-            targetPath,
-            allowlist,
-            fix: !!opts.fix,
-            json: !!opts.json,
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        const outcome = runCommentAudit(nodeFilesystem, {
-            rootDir: parsed.value.rootDir,
-            targetPath: parsed.value.targetPath,
-            allowlist: parsed.value.allowlist ?? [],
-            fix: parsed.value.fix,
-        });
-        if (!consumeCliAppError(outcome)) {
-            return;
-        }
-        if (parsed.value.json) {
-            logger.out(formatCommentAuditJsonOutput(outcome.value, rootDir));
-        }
-        else {
-            presentCommentAuditResult(outcome.value);
-        }
-        process.exitCode = exitCodeForCommentAuditResult(outcome.value);
-    });
+    registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(rtlCheck));
+    registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(linksCheck));
+    registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(importsCheck));
+    registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(displayNamesCheck));
+    registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(commentsCheck));
     return cmd;
 }

package/dist/audit/comments/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { CommentAuditResult } from "#/audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted divider still breaks the convention.
+ *
+ * @since 0.6.0
+ */
+export declare function exitCodeForCommentAuditResult(result: CommentAuditResult): number;
+/**
+ * Machine-readable comment-divider summary for `--json`.
+ *
+ * @since 0.6.0
+ */
+export declare function formatCommentAuditJsonOutput(result: CommentAuditResult, rootDir: string): string;

package/dist/audit/comments/cli-result.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#/core/exit-codes";
+/**
+ * Exit `1` when any non-allowlisted divider still breaks the convention.
+ *
+ * @since 0.6.0
+ */
+export function exitCodeForCommentAuditResult(result) {
+    return result.breakageCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Machine-readable comment-divider summary for `--json`.
+ *
+ * @since 0.6.0
+ */
+export function formatCommentAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.breakageCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}

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

@@ -0,0 +1,19 @@
+import * as z from "zod";
+/**
+ * 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>;

package/dist/audit/comments/cli-schema.js

@@ -0,0 +1,13 @@
+import * as z from "zod";
+/**
+ * Zod schema for {@link CommentAuditRunRequest}.
+ *
+ * @since 0.6.0
+ */
+export const commentAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    fix: z.boolean(),
+    json: z.boolean(),
+});

package/dist/audit/comments/output.d.ts

@@ -0,0 +1,7 @@
+import type { CommentAuditResult } from "#/audit/domain/types";
+/**
+ * Human-readable comment-divider report.
+ *
+ * @since 0.6.0
+ */
+export declare function presentCommentAuditResult(result: CommentAuditResult): void;

package/dist/audit/comments/output.js

@@ -0,0 +1,27 @@
+import { logger } from "#/core/logger";
+/**
+ * Human-readable comment-divider report.
+ *
+ * @since 0.6.0
+ */
+export function presentCommentAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.breakages) {
+            logger.out(`  ${line}: ${truncate(raw)} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.fixedCount > 0) {
+        logger.out(`\n✎ Rewrote ${result.fixedCount} divider(s)`);
+    }
+    if (result.breakageCount > 0) {
+        logger.out(`\n✖ ${result.breakageCount} comment issue(s)${allowlistSuffix} — --fix rewrites divider forms`);
+    }
+    else {
+        logger.out(`✓ ${result.dividerCount} divider(s) across ${result.scannedFileCount} file(s), no banned comment content${allowlistSuffix}`);
+    }
+}
+function truncate(raw) {
+    return raw.length <= 60 ? raw : `${raw.slice(0, 57)}…`;
+}