@codefast/cli 0.8.1 → 0.10.0

package/dist/arrange/source-parse.d.ts

@@ -0,0 +1,7 @@
+import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+/**
+ * Parses source text into a domain source file via the shared `oxc-parser` translator.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function parseDomainSourceFile(filePath: string, sourceText: string): DomainSourceFile;

package/dist/arrange/suggest.d.ts

@@ -0,0 +1,8 @@
+import type { ArrangeSuggestGroupsRequest } from "#/arrange/cli-schema";
+import type { ArrangeSuggestGroupsOutput } from "#/arrange/domain/types";
+/**
+ * Formats the suggested grouping for an inline class string as `arrange group` output lines.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function suggestCnGroupsFromCli(request: ArrangeSuggestGroupsRequest): ArrangeSuggestGroupsOutput;

package/dist/arrange/sync.d.ts

@@ -0,0 +1,11 @@
+import type { ArrangeSyncRunRequest } from "#/arrange/cli-schema";
+import type { ArrangeRunResult } from "#/arrange/domain/types";
+import type { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Runs the grouping pipeline over every target file and returns the aggregated result.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runArrangeSync(fs: FilesystemPort, request: ArrangeSyncRunRequest): Promise<Result<ArrangeRunResult, AppError>>;

package/dist/arrange/typescript-ast-translator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anti-corruption layer: maps the oxc-parser ESTree AST to the arrange domain AST.
+ * This is the only place that parses TypeScript source for arrange AST translation.
+ */
+import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+/**
+ * The translator mapping the `oxc-parser` ESTree AST to the arrange domain AST.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare class TypeScriptAstTranslator {
+    translateSourceFile(filePath: string, sourceText: string): DomainSourceFile;
+    /**
+     * Own child nodes in source-declaration order, mirroring `ts.forEachChild`:
+     * recurses into nested node objects and arrays of nodes, skipping primitives
+     * and plain records (e.g. a template element's `value`) that carry no `type`.
+     */
+    private childNodesOf;
+    private translateUnknown;
+    private stringLiteralText;
+    private noSubstitutionTemplateText;
+    private mapBinaryOperator;
+    private translateImportDeclaration;
+    private buildImportClause;
+    private buildNamespaceImport;
+    private buildNamedImports;
+    private buildImportSpecifier;
+    private translateIdentifier;
+    private translateNode;
+    private parseDomainSourceFile;
+}

package/dist/arrange/workspace.d.ts

@@ -0,0 +1,13 @@
+import type { ArrangeTargetWorkspaceAndConfig } from "#/arrange/domain/types";
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+/**
+ * Resolves the arrange target, repo root, and loaded config an arrange run needs.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function prepareArrangeWorkspace(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<ArrangeTargetWorkspaceAndConfig, AppError>>;

package/dist/arrange/workspace.js

@@ -3,7 +3,7 @@ import { loadCodefastConfig } from "#/core/config";
 import { AppError } from "#/core/errors";
 import { messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
-import { findRepoRoot } from "#/core/workspace/resolver";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
 /**
  * Resolves the arrange target, repo root, and loaded config an arrange run needs.
  *
@@ -19,7 +19,7 @@ export async function prepareArrangeWorkspace(fs, args) {
     }
     let rootDir;
     try {
-        rootDir = findRepoRoot(args.currentWorkingDirectory, fs);
+        rootDir = resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir;
     }
     catch (caughtError) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));

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

@@ -0,0 +1,93 @@
+import { z } from "zod";
+/**
+ * Resolved request for a single RTL audit run.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link RtlAuditRunRequest}.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const rtlAuditRunRequestSchema: z.ZodType<RtlAuditRunRequest>;
+/**
+ * Resolved request for a single link audit run.
+ *
+ * @since 0.5.0
+ */
+export type LinkAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link LinkAuditRunRequest}.
+ *
+ * @since 0.5.0
+ */
+export declare const linkAuditRunRequestSchema: z.ZodType<LinkAuditRunRequest>;
+/**
+ * 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>;
+/**
+ * Resolved request for a single import-policy audit run.
+ *
+ * @since 0.10.0
+ */
+export type ImportsAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link ImportsAuditRunRequest}.
+ *
+ * @since 0.10.0
+ */
+export declare const importsAuditRunRequestSchema: z.ZodType<ImportsAuditRunRequest>;
+/**
+ * Resolved request for a single display-name audit run.
+ *
+ * @since 0.9.0
+ */
+export type DisplayNameAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link DisplayNameAuditRunRequest}.
+ *
+ * @since 0.9.0
+ */
+export declare const displayNameAuditRunRequestSchema: z.ZodType<DisplayNameAuditRunRequest>;
+/**
+ * Resolves a path that may be absolute or relative to `rootDir`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function resolveRepoRelativePath(rootDir: string, maybeRelative: string): string;

package/dist/audit/cli-schema.js

@@ -35,11 +35,22 @@ export const commentAuditRunRequestSchema = z.object({
     json: z.boolean(),
 });
 /**
- * Zod schema for {@link ReactAuditRunRequest}.
+ * Zod schema for {@link ImportsAuditRunRequest}.
  *
- * @since 0.8.0
+ * @since 0.10.0
  */
-export const reactAuditRunRequestSchema = z.object({
+export const importsAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});
+/**
+ * Zod schema for {@link DisplayNameAuditRunRequest}.
+ *
+ * @since 0.9.0
+ */
+export const displayNameAuditRunRequestSchema = z.object({
     rootDir: z.string().min(1),
     targetPath: z.string().min(1),
     allowlist: z.array(z.string()).optional(),

package/dist/audit/command.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * 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.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function createAuditCommand(): Command;

package/dist/audit/command.js

@@ -1,12 +1,13 @@
 import process from "node:process";
 import { Command } from "commander";
-import { commentAuditRunRequestSchema, linkAuditRunRequestSchema, reactAuditRunRequestSchema, rtlAuditRunRequestSchema, } from "#/audit/cli-schema";
-import { exitCodeForCommentAuditResult, exitCodeForLinkAuditResult, exitCodeForReactAuditResult, exitCodeForRtlAuditResult, formatCommentAuditJsonOutput, formatLinkAuditJsonOutput, formatReactAuditJsonOutput, formatRtlAuditJsonOutput, presentCommentAuditResult, presentLinkAuditResult, presentReactAuditResult, presentRtlAuditResult, } from "#/audit/output";
-import { prepareCommentAudit, prepareLinkAudit, prepareReactAudit, prepareRtlAudit } from "#/audit/prepare";
+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 { runReactAudit } from "#/audit/run-react";
 import { readOptionalPositionalArg } from "#/core/cli/positional";
 import { consumeCliAppError } from "#/core/cli/result-handle";
 import { nodeFilesystem } from "#/core/filesystem/node";
@@ -99,12 +100,12 @@ export function createAuditCommand() {
         process.exitCode = exitCodeForLinkAuditResult(outcome.value);
     });
     cmd
-        .command("react")
-        .description("Report React namespace/default imports and implicit React.* UMD-global type references")
+        .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 prepareReactAudit(nodeFilesystem, {
+        const prelude = await prepareImportsAudit(nodeFilesystem, {
             currentWorkingDirectory: process.cwd(),
             rawTarget: readOptionalPositionalArg(target),
         });
@@ -112,7 +113,7 @@ export function createAuditCommand() {
             return;
         }
         const { rootDir, targetPath, allowlist } = prelude.value;
-        const parsed = parseWithSchema(reactAuditRunRequestSchema, {
+        const parsed = parseWithSchema(importsAuditRunRequestSchema, {
             rootDir,
             targetPath,
             allowlist,
@@ -121,7 +122,7 @@ export function createAuditCommand() {
         if (!consumeCliAppError(parsed)) {
             return;
         }
-        const outcome = runReactAudit(nodeFilesystem, {
+        const outcome = runImportsAudit(nodeFilesystem, {
             rootDir: parsed.value.rootDir,
             targetPath: parsed.value.targetPath,
             allowlist: parsed.value.allowlist ?? [],
@@ -130,12 +131,51 @@ export function createAuditCommand() {
             return;
         }
         if (parsed.value.json) {
-            logger.out(formatReactAuditJsonOutput(outcome.value, rootDir));
+            logger.out(formatImportsAuditJsonOutput(outcome.value, rootDir));
         }
         else {
-            presentReactAuditResult(outcome.value);
+            presentImportsAuditResult(outcome.value);
         }
-        process.exitCode = exitCodeForReactAuditResult(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")

package/dist/audit/domain/audit-file.d.ts

@@ -0,0 +1,7 @@
+import type { RtlViolation } from "#/audit/domain/types";
+/**
+ * Detects physical-direction Tailwind classes that should be logical or rtl:-paired.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function auditFileContent(content: string): Array<RtlViolation>;

package/dist/audit/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/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/domain/comment-dividers.js

@@ -11,12 +11,31 @@ const RULE_GLYPH = "─";
 const LEAD_GLYPHS = "──";
 /** Every glyph a divider has historically been drawn with, so legacy forms are recognised too. */
 const RULE_CHARACTER_CLASS = String.raw `[-=─_*~#]`;
-const ruleOnlyLinePattern = new RegExp(String.raw `^(?<indent>[ \t]*)(?:\/\/|\/\*|\*)[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*(?:\*\/)?[ \t]*$`);
-const titledLinePattern = new RegExp(String.raw `^(?<indent>[ \t]*)(?:\/\/|\/\*)[ \t]*${RULE_CHARACTER_CLASS}{2,}[ \t]+(?<title>.*?)[ \t]+${RULE_CHARACTER_CLASS}{2,}[ \t]*(?:\*\/)?[ \t]*$`);
-const commentLinePattern = /^[ \t]*(?:\/\/|\/\*|\*)/;
-const bareRuleClosePattern = new RegExp(String.raw `^[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*\*\/[ \t]*$`);
+// The comment lead each syntax opens a divider with — `#` for ignore files, slash forms for code.
+const commentLeadByLanguage = {
+    css: String.raw `\/\/|\/\*|\*`,
+    ignore: String.raw `#`,
+    js: String.raw `\/\/|\/\*|\*`,
+};
+// One compiled pattern set per language — the comment lead is the only part that varies.
+const patternsByLanguage = new Map();
+function patternsFor(language) {
+    const cached = patternsByLanguage.get(language);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const lead = commentLeadByLanguage[language];
+    const built = {
+        ruleOnly: new RegExp(String.raw `^(?<indent>[ \t]*)(?:${lead})[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*(?:\*\/)?[ \t]*$`),
+        titled: new RegExp(String.raw `^(?<indent>[ \t]*)(?:${lead})[ \t]*${RULE_CHARACTER_CLASS}{2,}[ \t]+(?<title>.*?)[ \t]+${RULE_CHARACTER_CLASS}{2,}[ \t]*(?:\*\/)?[ \t]*$`),
+        commentLine: new RegExp(String.raw `^[ \t]*(?:${lead})`),
+        bareRuleClose: new RegExp(String.raw `^[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*\*\/[ \t]*$`),
+        commentPrefix: new RegExp(String.raw `^[ \t]*(?:${lead})[ \t]?`),
+    };
+    patternsByLanguage.set(language, built);
+    return built;
+}
 const rulesOnlyPattern = new RegExp(String.raw `^(?:${RULE_CHARACTER_CLASS}|[ \t])*$`);
-const commentPrefixPattern = /^[ \t]*(?:\/\/|\/\*|\*)[ \t]?/;
 const commentSuffixPattern = /[ \t]*\*\/[ \t]*$/;
 /** A banner spanning more lines than this is prose that happens to start with a rule, not a divider. */
 const MAX_BANNER_SPAN = 16;
@@ -36,7 +55,8 @@ export function renderDivider(indent, title, language) {
         const head = `${indent}/* ${LEAD_GLYPHS} ${title} `;
         return `${head}${RULE_GLYPH.repeat(Math.max(2, DIVIDER_COLUMN - head.length - 3))} */`;
     }
-    const head = `${indent}// ${LEAD_GLYPHS} ${title} `;
+    const prefix = language === "ignore" ? "#" : "//";
+    const head = `${indent}${prefix} ${LEAD_GLYPHS} ${title} `;
     return `${head}${RULE_GLYPH.repeat(Math.max(2, DIVIDER_COLUMN - head.length))}`;
 }
 /**
@@ -80,7 +100,8 @@ export function applyCommentDividerFixes(content, language) {
 }
 function readRegionAt(lines, index, language) {
     const line = lines[index];
-    const titled = titledLinePattern.exec(line);
+    const patterns = patternsFor(language);
+    const titled = patterns.titled.exec(line);
     const title = titled?.groups?.title?.trim();
     if (titled !== null && title !== undefined && title.length > 0 && !rulesOnlyPattern.test(title)) {
         const indent = titled.groups?.indent ?? "";
@@ -94,26 +115,29 @@ function readRegionAt(lines, index, language) {
             defect: line === canonical ? null : usesCanonicalGlyphs(line) ? "bad-width" : "legacy-form",
         };
     }
-    const ruleOnly = ruleOnlyLinePattern.exec(line);
+    const ruleOnly = patterns.ruleOnly.exec(line);
     if (ruleOnly === null) {
         return null;
     }
-    return readBannerAt(lines, index, ruleOnly.groups?.indent ?? "");
+    return readBannerAt(lines, index, ruleOnly.groups?.indent ?? "", language);
 }
-function readBannerAt(lines, index, indent) {
+function readBannerAt(lines, index, indent, language) {
     const line = lines[index];
+    const patterns = patternsFor(language);
     // An unterminated `/*` opens a block whose body needs no per-line marker, so the run ends at `*/`.
     const insideBlock = line.trimStart().startsWith("/*") && !line.includes("*/");
     const body = [];
     let cursor = index + 1;
-    while (cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && !isBannerClose(lines[cursor], insideBlock)) {
-        if (!insideBlock && !commentLinePattern.test(lines[cursor])) {
+    while (cursor < lines.length &&
+        cursor - index <= MAX_BANNER_SPAN &&
+        !isBannerClose(lines[cursor], insideBlock, language)) {
+        if (!insideBlock && !patterns.commentLine.test(lines[cursor])) {
             break;
         }
-        body.push(stripCommentPrefix(lines[cursor]));
+        body.push(stripCommentPrefix(lines[cursor], language));
         cursor++;
     }
-    const closed = cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && isBannerClose(lines[cursor], insideBlock);
+    const closed = cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && isBannerClose(lines[cursor], insideBlock, language);
     const meaningful = body.filter((entry) => entry.length > 0);
     // A frame around prose is a doc block, and an unclosed rule is prose formatting inside one.
     if (!closed || meaningful.length !== 1 || !looksLikeTitle(meaningful[0])) {
@@ -131,15 +155,19 @@ function readBannerAt(lines, index, indent) {
 function looksLikeTitle(text) {
     return text.length <= MAX_TITLE_LENGTH && !text.endsWith(".");
 }
-function isBannerClose(line, insideBlock) {
-    if (ruleOnlyLinePattern.test(line)) {
+function isBannerClose(line, insideBlock, language) {
+    const patterns = patternsFor(language);
+    if (patterns.ruleOnly.test(line)) {
         return true;
     }
-    return insideBlock && bareRuleClosePattern.test(line);
+    return insideBlock && patterns.bareRuleClose.test(line);
 }
 function usesCanonicalGlyphs(line) {
-    return line.trimStart().startsWith(`// ${LEAD_GLYPHS} `) || line.trimStart().startsWith(`/* ${LEAD_GLYPHS} `);
+    const trimmed = line.trimStart();
+    return (trimmed.startsWith(`// ${LEAD_GLYPHS} `) ||
+        trimmed.startsWith(`/* ${LEAD_GLYPHS} `) ||
+        trimmed.startsWith(`# ${LEAD_GLYPHS} `));
 }
-function stripCommentPrefix(line) {
-    return line.replace(commentPrefixPattern, "").replace(commentSuffixPattern, "").trim();
+function stripCommentPrefix(line, language) {
+    return line.replace(patternsFor(language).commentPrefix, "").replace(commentSuffixPattern, "").trim();
 }

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

@@ -0,0 +1,11 @@
+/** The display-name convention: a name is spelled like the TS symbol it stands for, under its owner's namespace. */
+import type { DisplayNameViolation } from "#/audit/domain/types";
+/**
+ * Scans one source or markdown text for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @remarks Runs on markdown as well as TypeScript because a doc sample is what a reader copies:
+ * a convention the docs break is not one the docs teach.
+ *
+ * @since 0.9.0
+ */
+export declare function auditDisplayNames(sourceText: string): Array<DisplayNameViolation>;

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

@@ -0,0 +1,71 @@
+/** The owner: a kebab-case package, app or feature slug, or a scoped package name. */
+const NAMESPACE = /^(?:@[a-z0-9-]+\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A token or module stands for a type or a unit of composition. */
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9]*$/;
+/** A tag key stands for an attribute a request selects on, so it reads like a property. */
+const CAMEL_CASE = /^[a-z][A-Za-z0-9]*$/;
+/**
+ * A bare `token(…)` / `tag(…)` call, or a module factory call, whose first argument is a string literal.
+ *
+ * @remarks Generic arguments are skipped up to four levels of nesting, which is deeper than any
+ * declaration in the repo. Template literals are not matched: an interpolated name has no fixed
+ * text to check. The closing parenthesis is kept when the name is the only argument, so the
+ * reported text reads as the call was written.
+ */
+const DISPLAY_NAME_CALL = /(?<![\w$.])(?:(token|tag)\s*(?:<(?:[^<>]|<(?:[^<>]|<(?:[^<>]|<[^<>]*>)*>)*>)*>)?|((?:Sync|Async)?Module)\s*\.\s*create(?:Async)?)\s*\(\s*(["'])((?:(?!\3)[^\\\n]|\\.)*)\3(\s*\))?/g;
+const KIND_LABEL = {
+    token: "token display name",
+    tag: "tag key",
+    module: "module name",
+};
+/**
+ * Scans one source or markdown text for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @remarks Runs on markdown as well as TypeScript because a doc sample is what a reader copies:
+ * a convention the docs break is not one the docs teach.
+ *
+ * @since 0.9.0
+ */
+export function auditDisplayNames(sourceText) {
+    const violations = [];
+    for (const match of sourceText.matchAll(DISPLAY_NAME_CALL)) {
+        const kind = match[1] === undefined ? "module" : match[1];
+        const reason = reasonFor(kind, match[4]);
+        if (reason === null) {
+            continue;
+        }
+        violations.push({ line: lineOfOffset(sourceText, match.index), raw: match[0], reason });
+    }
+    return violations;
+}
+/** Why a display name breaks the convention, or `null` when it holds. */
+function reasonFor(kind, name) {
+    const segments = name.split(":");
+    const label = KIND_LABEL[kind];
+    if (segments.length < 2) {
+        return `${label} '${name}' has no namespace — write '<namespace>:${name}'`;
+    }
+    const local = segments.at(-1);
+    for (const namespace of segments.slice(0, -1)) {
+        if (!NAMESPACE.test(namespace)) {
+            return `namespace '${namespace}' in '${name}' is not kebab-case (or a scoped package name)`;
+        }
+    }
+    if (kind === "tag") {
+        return CAMEL_CASE.test(local)
+            ? null
+            : `${label} '${local}' in '${name}' is not camelCase — a tag key names an attribute`;
+    }
+    return PASCAL_CASE.test(local)
+        ? null
+        : `${label} '${local}' in '${name}' is not PascalCase — a ${kind} stands for a ${kind === "token" ? "type" : "unit of composition"}`;
+}
+function lineOfOffset(sourceText, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (sourceText.charCodeAt(index) === 10) {
+            line++;
+        }
+    }
+    return line;
+}