@d3lm/lint-preset 1.4.5 → 1.5.0

package/dist/comments.d.ts

@@ -0,0 +1,257 @@
+type StyleIssueType = 'semicolon' | 'em-dash' | 'dash' | 'label-colon' | 'emphasis' | 'banner';
+
+interface WrapOptions {
+    /**
+     * Sets whether a line may not end with the first word of a sentence, clause, or parenthetical,
+     * like `This`, `the` after a comma, or `(the`. Such a word moves to the next line instead.
+     * It also sets whether the first of two lines ends with a sentence instead of the start of the
+     * next one, as long as the second line is then no longer than the first.
+     */
+    readonly avoidSentenceOrphans: boolean;
+    /**
+     * Sets how many columns a line may exceed its limit before it counts as overflowing.
+     */
+    readonly tolerance: number;
+    /**
+     * Sets how many extra columns a complete parenthetical may use beyond the preferred line limit.
+     */
+    readonly parentheticalOverflow?: number;
+}
+type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced';
+/**
+ * JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay intact like code spans.
+ */
+declare function tokenize(text: string): string[];
+/**
+ * The first line can have a different limit than the rest, e.g. when a list marker takes up space
+ * only on the first line.
+ */
+declare function wrapTokens(tokens: readonly string[], firstLimit: number, restLimit: number, options: WrapOptions): string[][];
+
+type CommentKind = 'jsdoc' | 'block';
+type ParagraphKind = 'prose' | 'list' | 'tag' | 'code' | 'other';
+interface AnalyzeOptions extends WrapOptions {
+    /**
+     * Sets the preferred line length, including indentation and the comment prefix.
+     */
+    readonly width: number;
+    /**
+     * Sets the hard limit for measured prose. Parentheticals may exceed `width` up to this limit.
+     * When omitted, the existing width and tolerance behavior is retained.
+     */
+    readonly maxWidth?: number;
+    /**
+     * Sets the maximum length of the line that holds a comment whose whole text is one
+     * prose paragraph. Such a comment stays on one line up to this length, even past
+     * `width`. It defaults to `width`.
+     */
+    readonly singleLineWidth?: number;
+    readonly tabWidth: number;
+    /**
+     * Whether to report prose style issues like semicolons, em-dashes, and section banners.
+     */
+    readonly style: boolean;
+}
+type IssueType = LineIssueType | StyleIssueType;
+type IssueTier = 'verdict' | 'hint';
+interface IssueReport {
+    readonly type: IssueType;
+    readonly tier: IssueTier;
+    readonly line: number;
+    readonly length: number;
+}
+interface ParagraphReport {
+    readonly kind: ParagraphKind;
+    readonly startLine: number;
+    readonly endLine: number;
+    /**
+     * Whether the paragraph is prose that can be rewrapped. When `false`, `reason` says why.
+     */
+    readonly reflowable: boolean;
+    readonly reason?: string;
+    readonly issues: readonly IssueReport[];
+    /**
+     * Holds the exact source lines for `startLine` through `endLine` when the paragraph is
+     * greedily wrapped to the width, or `null` when the paragraph isn't prose, e.g. code,
+     * a table, a diagram, or `@example`.
+     */
+    readonly suggestion: readonly string[] | null;
+}
+interface CommentReport {
+    readonly file: string;
+    readonly kind: CommentKind;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly indent: string;
+    readonly width: number;
+    readonly maxWidth?: number;
+    /**
+     * Holds the length of each source line from `startLine` through `endLine`, with tabs expanded.
+     */
+    readonly lengths: readonly number[];
+    readonly text: string;
+    readonly paragraphs: readonly ParagraphReport[];
+}
+/**
+ * Finds all own-line block and JSDoc comments in a JavaScript or TypeScript source file and reports
+ * how each paragraph deviates from a greedy wrap at `options.width`. Line comments (`//`) are never
+ * analyzed. A source with a syntax error that stops the parser has no reports.
+ */
+declare function analyzeSource(source: string, filename: string, options: AnalyzeOptions): CommentReport[];
+/**
+ * Whether the comment has any issue, including hints, which makes it worth handing to the agent.
+ */
+declare function isSuspicious(report: CommentReport): boolean;
+/**
+ * Whether the comment has an issue that isn't a hint, so it breaks the rules no matter what
+ * the agent decided.
+ */
+declare function hasVerdictIssues(report: CommentReport): boolean;
+/**
+ * Returns the comment's source text with every prose paragraph replaced by its suggestion.
+ * Code, tables, diagrams, and similar paragraphs are kept as they are.
+ */
+declare function rewrapComment(report: CommentReport): string;
+/**
+ * Returns the syntax tree of the source as JSON, without positions or comments, used to verify
+ * that only comments changed. Moving or rewording a comment keeps it the same, while any change
+ * to a string, template, regex, JSX text, or where a statement ends changes it. A source that
+ * doesn't parse has no tree to compare, so all of its text counts.
+ */
+declare function codeFingerprint(source: string, filename: string): string;
+
+type AgentRunner = 'claude' | 'codex' | 'cursor';
+type HookMode = 'agent' | 'report' | 'off';
+type AgentScope = 'suspicious' | 'all';
+interface AgentConfig {
+    /**
+     * Names the agent CLI to spawn. Defaults to the host that triggered the hook, or `claude`
+     * when run standalone.
+     */
+    readonly runner?: AgentRunner;
+    /**
+     * Names the model passed to the runner. Defaults to `haiku` for Claude Code and to the
+     * CLI's default otherwise.
+     */
+    readonly model?: string;
+    /**
+     * Lists extra arguments appended to the runner's command line.
+     */
+    readonly args?: readonly string[];
+    /**
+     * Sets a fully custom command, e.g. `['my-agent', '--prompt', '{prompt}']`. Without a `{prompt}`
+     * placeholder, the prompt is written to stdin. Overrides `runner`, `model`, and `args`.
+     */
+    readonly command?: readonly string[];
+    /**
+     * Sets how many seconds to wait for each agent before giving up. Defaults to 300.
+     */
+    readonly timeout?: number;
+    /**
+     * Sets the most comments to hand to one agent. More comments are split across several agents.
+     * A file's comments always go to the same agent, since parallel agents editing one file would
+     * overwrite each other's edits, so a file with more comments than this gets an agent of its
+     * own. Defaults to 20.
+     */
+    readonly batchSize?: number;
+    /**
+     * Sets the most files to hand to one agent, since an agent editing many files is slower and less
+     * careful. More files are split across several agents. Defaults to 10.
+     */
+    readonly maxFiles?: number;
+    /**
+     * Caps how many agents run at once. The other agents wait, and each one starts when a running
+     * agent finishes. Defaults to 6.
+     */
+    readonly maxAgents?: number;
+    /**
+     * Points to a Markdown file with formatting rules, relative to the config file.
+     * Replaces the built-in rules.
+     */
+    readonly rules?: string;
+    /**
+     * Holds extra instructions appended to the rules.
+     */
+    readonly instructions?: string;
+    /**
+     * Selects which comments the agent sees. `suspicious` (default) is a triage, not a full review.
+     * It only sends comments with hints, like a possible semicolon or a line that may end with the
+     * first word of a sentence, and comments with issues in parts the tool never rewraps, so most
+     * runs never call the agent. The tool fixes the layout of prose itself. `all` sends every comment
+     * in changed lines, so that the agent reviews the wording of each against its rules.
+     */
+    readonly scope?: AgentScope;
+}
+interface HookConfig {
+    /**
+     * Sets what the stop hook does with comments in changed lines.
+     *
+     * - `agent` (default): hand them to an agent and report any that still don't fit afterwards.
+     * - `report`: only report suspicious comments.
+     * - `off`: do nothing.
+     */
+    readonly mode?: HookMode;
+}
+interface CommentsConfig {
+    /**
+     * Sets the preferred line length for comments, including indentation and the comment prefix.
+     * Defaults to prettier's `printWidth`, or 80.
+     */
+    readonly width?: number;
+    /**
+     * Sets the hard limit for measured prose. Defaults to 120, or `width` when it is larger.
+     * Parentheticals may use the space between `width` and this limit to stay together.
+     */
+    readonly maxWidth?: number;
+    /**
+     * Sets the maximum length of the line that holds a comment whose whole text is one prose
+     * paragraph. Such a comment stays on one line up to this length, even past `width`, and is
+     * wrapped to `width` beyond it. Defaults to 120 and never exceeds `maxWidth`.
+     */
+    readonly singleLineWidth?: number;
+    /**
+     * Sets a legacy hard limit of `width + tolerance` when `maxWidth` is omitted.
+     * An explicit `maxWidth` takes precedence.
+     */
+    readonly tolerance?: number;
+    /**
+     * Keep the first word of a new sentence or parenthetical off the end of a line, e.g.
+     * `...the module. This` or `...reflows (the` followed by the rest on the next line.
+     * A paragraph of two lines also ends its first line with a sentence when the rest fits
+     * on the second line and is no longer than the first, instead of with the start of the
+     * next sentence, like `...the module. This one`. Defaults to `true`.
+     */
+    readonly avoidSentenceOrphans?: boolean;
+    /**
+     * Looks for possible style issues (semicolons, em-dashes and dashes, `label: explanation` colons,
+     * asterisk emphasis, and section banners) and reports them as hints, so that the `suspicious` scope
+     * hands those comments to the agent too. It only controls this search, and the agent's rules apply
+     * to every comment the agent sees either way. Defaults to `true`.
+     */
+    readonly style?: boolean;
+    /**
+     * Lists the file extensions to process. Defaults to JavaScript and TypeScript extensions.
+     */
+    readonly extensions?: readonly string[];
+    /**
+     * Lists glob patterns, relative to the repository root, of files to skip.
+     */
+    readonly ignore?: readonly string[];
+    readonly agent?: AgentConfig;
+    readonly hook?: HookConfig;
+}
+declare function defineConfig(config: CommentsConfig): CommentsConfig;
+declare function loadConfig(cwd: string, options?: {
+    explicitPath?: string;
+    stopDir?: string;
+}): Promise<{
+    config: CommentsConfig;
+    filepath: string;
+} | {
+    config: {};
+    filepath?: undefined;
+}>;
+
+declare const DEFAULT_RULES: string;
+
+export { type AgentConfig, type AgentRunner, type AgentScope, type AnalyzeOptions, type CommentKind, type CommentReport, type CommentsConfig, DEFAULT_RULES, type HookConfig, type HookMode, type IssueReport, type IssueTier, type ParagraphKind, type ParagraphReport, analyzeSource, codeFingerprint, defineConfig, hasVerdictIssues, isSuspicious, loadConfig, rewrapComment, tokenize, wrapTokens };