@codefast/cli 0.9.0 → 0.11.0

package/dist/audit/command.js

@@ -1,18 +1,134 @@
-import process from "node:process";
 import { Command } from "commander";
-import { commentAuditRunRequestSchema, linkAuditRunRequestSchema, reactAuditRunRequestSchema, rtlAuditRunRequestSchema, displayNameAuditRunRequestSchema, } from "#/audit/cli-schema";
-import { exitCodeForCommentAuditResult, exitCodeForLinkAuditResult, exitCodeForReactAuditResult, exitCodeForRtlAuditResult, exitCodeForDisplayNameAuditResult, formatCommentAuditJsonOutput, formatLinkAuditJsonOutput, formatReactAuditJsonOutput, formatRtlAuditJsonOutput, formatDisplayNameAuditJsonOutput, presentCommentAuditResult, presentLinkAuditResult, presentReactAuditResult, presentRtlAuditResult, presentDisplayNameAuditResult, } from "#/audit/output";
-import { prepareCommentAudit, prepareLinkAudit, prepareReactAudit, prepareRtlAudit, prepareDisplayNameAudit, } from "#/audit/prepare";
-import { runRtlAudit } from "#/audit/run";
-import { runCommentAudit } from "#/audit/run-comments";
-import { runDisplayNameAudit } from "#/audit/run-display-names";
-import { runLinkAudit } from "#/audit/run-links";
-import { runReactAudit } from "#/audit/run-react";
-import { readOptionalPositionalArg } from "#/core/cli/positional";
-import { consumeCliAppError } from "#/core/cli/result-handle";
+import { 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("react")
-        .description("Report React namespace/default imports and implicit React.* UMD-global type references")
-        .argument("[target]", "Directory or file to scan (default: the repo root)")
-        .option("--json", "Print one JSON summary on stdout", false)
-        .action(async (target, opts) => {
-        const prelude = await prepareReactAudit(nodeFilesystem, {
-            currentWorkingDirectory: process.cwd(),
-            rawTarget: readOptionalPositionalArg(target),
-        });
-        if (!consumeCliAppError(prelude)) {
-            return;
-        }
-        const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(reactAuditRunRequestSchema, {
-            rootDir,
-            targetPath,
-            allowlist,
-            json: !!opts.json,
-        });
-        if (!consumeCliAppError(parsed)) {
-            return;
-        }
-        const outcome = runReactAudit(nodeFilesystem, {
-            rootDir: parsed.value.rootDir,
-            targetPath: parsed.value.targetPath,
-            allowlist: parsed.value.allowlist ?? [],
-        });
-        if (!consumeCliAppError(outcome)) {
-            return;
-        }
-        if (parsed.value.json) {
-            logger.out(formatReactAuditJsonOutput(outcome.value, rootDir));
-        }
-        else {
-            presentReactAuditResult(outcome.value);
-        }
-        process.exitCode = exitCodeForReactAuditResult(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/domain/comment-content.d.ts

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

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

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

package/dist/audit/comments/domain/link-references.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolves `{@link}` references against the scanned tree, so a rename that orphans one is caught.
+ */
+/**
+ * One `{@link}` occurrence found inside a comment.
+ *
+ * @since 0.6.0
+ */
+export interface LinkReference {
+    readonly line: number;
+    /** The target as written, e.g. `writeJsonlRun`, `Foo.bar`, `../fixtures/adapter.ts`. */
+    readonly target: string;
+}
+/**
+ * Every `{@link}` target in a file's comments, in source order.
+ *
+ * @since 0.6.0
+ */
+export declare function scanLinkReferences(content: string): Array<LinkReference>;
+/**
+ * The identifier a declaration-style target must resolve through — `Foo.bar` resolves via `Foo`.
+ *
+ * @since 0.6.0
+ */
+export declare function linkTargetHead(target: string): string;
+/**
+ * Whether a target names a file or URL rather than a declaration.
+ *
+ * @since 0.6.0
+ */
+export declare function isPathLinkTarget(target: string): boolean;
+/**
+ * Counts word-boundary occurrences of each head across a body of source text.
+ *
+ * @remarks A `{@link X}` occurrence itself mentions `X` once, so a target is orphaned when its
+ * total mentions do not exceed its link occurrences — a rename removes every real mention.
+ *
+ * @since 0.6.0
+ */
+export declare function countHeadMentions(contents: Iterable<string>, heads: ReadonlySet<string>): Map<string, number>;

package/dist/audit/comments/domain/since-versions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Flags `@since` tags naming a version the owning package has not reached.
+ */
+/**
+ * One impossible `@since` stamp found in a file's comments.
+ *
+ * @since 0.8.0
+ */
+export interface SinceVersionFinding {
+    readonly line: number;
+    readonly raw: string;
+}
+/**
+ * Compares two SemVer strings by precedence — positive when `left` is greater,
+ * null when either side is not a SemVer version.
+ *
+ * @since 0.8.0
+ */
+export declare function compareVersionPrecedence(left: string, right: string): number | null;
+/**
+ * Scans a file's comments for `@since` tags stamped above the package's current
+ * version — a release that has not happened, so the stamp cannot be true.
+ *
+ * @since 0.8.0
+ */
+export declare function scanImpossibleSinceTags(content: string, packageVersion: string): Array<SinceVersionFinding>;

package/dist/audit/comments/domain/tsdoc-syntax.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validates every doc block against the official TSDoc grammar, not a regex approximation.
+ */
+/**
+ * One grammar diagnostic from the TSDoc parser.
+ *
+ * @since 0.6.0
+ */
+export interface TsdocSyntaxFinding {
+    readonly line: number;
+    /** The parser's stable message id, e.g. `tsdoc-escape-right-brace` — the allowlist key. */
+    readonly raw: string;
+    readonly reason: string;
+}
+/**
+ * Every TSDoc grammar diagnostic in a file's doc blocks, in source order.
+ *
+ * @since 0.6.0
+ */
+export declare function scanTsdocSyntax(content: string): Array<TsdocSyntaxFinding>;

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)}…`;
+}

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

@@ -0,0 +1,16 @@
+import type { AuditCommandPrelude } from "#/audit/prepare";
+import type { 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 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: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/comments/prepare.js

@@ -0,0 +1,12 @@
+import { prepareRepoRootAudit } from "#/audit/prepare";
+/**
+ * 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 async function prepareCommentAudit(fs, args) {
+    return prepareRepoRootAudit(fs, args, (config) => config.audit?.comments?.allowlist ?? []);
+}