import type { DbcParser, DbcEntrySchema } from '../../../parser/dbc-parser.types.js'; import type { DbcAstAdapter, DbcExportedEntity, DbcSignatureInfo } from '../../dbc-ast-adapter.types.js'; import type { DbcLinter, DbcLintReport, DbcLintFixReport, DbcLintError, DbcLintOptions } from '../../dbc-linter.types.js'; /** * @purpose Pure-function validator that compares parsed contract entries against | a code signature and returns structural mismatches. * @invariant Never throws. Unknown `kind` returns an empty error array. * @invariant Errors are returned in stable order: PARAM_MISSING → PARAM_EXTRA → | PARAM_ORDER → RETURNS_MISSING → RETURNS_UNEXPECTED → TYPE_REDUNDANT. * @param entries Parsed contract entries from `DbcParser.parse()`. * @param signature Signature information extracted from AST. * @param kind Entity or member kind — drives the validation matrix (FR-24). * @returns Array of lint errors (empty when contract matches signature). */ export declare function validate(entries: DbcEntrySchema[], signature: DbcSignatureInfo, kind: string): DbcLintError[]; /** * @purpose TypeScript adapter implementing the DbcLinter contract. | Pass 1: AST extraction. Pass 2: contract validation + signature matching. | Pass 3: ESLint report. Pass 4: autofix chain. * @implements {DbcLinter} in ../../dbc-linter.types.ts * @invariant Never throws — all errors are returned via report objects. * @invariant Error order is stable (top-to-bottom by entity position). */ export declare class DbcTsLinter implements DbcLinter { /** @purpose DBC parser for parsing contract text */ protected _parser: DbcParser; /** @purpose AST adapter for parsing TypeScript source files */ protected _astAdapter: DbcAstAdapter; /** * @purpose Construct a linter with injected parser and AST adapter. * @param parser DbcParser instance for contract parsing. * @param astAdapter DbcAstAdapter instance for source file parsing. */ constructor(parser: DbcParser, astAdapter: DbcAstAdapter); /** * @param filePath Path to the source file to check. * @param [options] Optional lint configuration. * @returns Full lint report with errors and a formatting function. * @see {DbcLinter#lint} in ../../dbc-linter.types.ts */ lint(filePath: string, options?: DbcLintOptions): Promise; /** * @param filePath Path to the source file to check. * @param [options] Optional lint configuration. * @returns Combined report with errors and count of auto-fixed issues. * @see {DbcLinter#lintAndFix} in ../../dbc-linter.types.ts */ lintAndFix(filePath: string, options?: DbcLintOptions): Promise; /** * @purpose Walk all exported entities and their members, collecting lint errors. * @param entities Exported entities from AST parse result. * @param filePath Source file path for error attribution. * @returns Array of lint errors collected from entities and members. */ protected _lintEntities(entities: DbcExportedEntity[], filePath: string): DbcLintError[]; /** * @purpose Parse a contract text and validate it, returning both parser issues * (translated per FR-23) and structural mismatches via DbcContractMatchValidator. * @param contractText Raw JSDoc contract text to parse and validate. * @param signature Signature info from AST for parameter/returns matching. * @param kind Entity or member kind for validation matrix lookup. * @param filePath Source file path for error attribution. * @param startLine Contract start line in source for error position. * @param startCol Contract start column in source for error position. * @returns Array of lint errors from parser issues and structural mismatches. */ protected _validateContract(contractText: string, signature: DbcSignatureInfo, kind: string, filePath: string, startLine: number, startCol: number): DbcLintError[]; /** @purpose Internal record of a contract block with context for autofix. */ protected _ContractBlock: { new (text: string, kind: string, signature: DbcSignatureInfo): { text: string; kind: string; signature: DbcSignatureInfo; }; }; /** * @purpose Walk entities and members, collecting all JSDoc contract blocks * with their associated kind and signature for autofix processing. * @param entities Exported entities from AST parse result. * @returns Array of contract blocks with kind and signature context. */ protected _collectContracts(entities: DbcExportedEntity[]): InstanceType[]; /** * @purpose Expand single-line pipe contracts to multi-line for callable kinds or >3 tags. * @param jsdocText Raw JSDoc comment text. * @param [kind] Entity kind — callable kinds or pipe with >3 tags are expanded. * @returns JSDoc text in multi-line format if applicable. */ protected _expandToMultiline(jsdocText: string, kind?: string): string; /** * @purpose Remove redundant `{dataType}` annotations from @param and @returns tags. * @param jsdocText Raw JSDoc comment text. * @returns JSDoc text with types stripped. */ protected _removeRedundantTypes(jsdocText: string): string; /** * @purpose Adjust @param specifiers to wrap optional params in `[brackets]` and remove brackets from required params. * @param jsdocText Raw JSDoc comment text. * @param signature Signature with optionality flags. * @returns JSDoc text with normalized brackets. */ protected _normalizeParamBrackets(jsdocText: string, signature: DbcSignatureInfo): string; /** * @purpose Remove @param entries whose specifier does not match any signature parameter. | Handles both multi-line and single-line contracts. * @param jsdocText Raw JSDoc comment text. * @param signature Signature to match against. * @returns JSDoc text with extra params removed. */ protected _removeExtraParams(jsdocText: string, signature: DbcSignatureInfo): string; /** * @purpose Remove @returns tag when the kind does not allow it or return type is void. * @param jsdocText Raw JSDoc comment text. * @param kind Entity or member kind. * @param [signature] Optional signature info to check void return type. * @returns JSDoc text with unexpected @returns removed. */ protected _removeUnexpectedReturns(jsdocText: string, kind: string, signature?: DbcSignatureInfo): string; /** * @purpose Reorder @param entries to match the signature parameter order. * @param jsdocText Raw JSDoc comment text. * @param signature Signature with desired parameter order. * @returns JSDoc text with params reordered. */ protected _reorderParams(jsdocText: string, signature: DbcSignatureInfo): string; /** * @purpose Reorder contract tags to canonical DBC order. | Order: description → purpose → implements → invariant → pre → param(*) → | throws → returns → post → sideEffect → other tags. * @param jsdocText Raw JSDoc comment text. * @returns JSDoc text with tags in canonical order. */ protected _reorderTags(jsdocText: string): string; /** * @purpose Normalize multi-line JSDoc format: ensure closing marker is on its own line | and opening marker is bare (no content after it). | Preserves original indentation by patching specific format issues | rather than reconstructing the entire block. * @invariant Single-line contracts pass through unchanged. * @param jsdocText Raw JSDoc comment text. * @returns Normalized JSDoc text. */ protected _normalizeMultiLine(jsdocText: string): string; /** * @purpose Detect the indentation pattern used by content lines. | Returns the whitespace prefix before `*` on the first content line, | or the indent of the opening line as fallback. * @param lines All lines of the JSDoc block (may be mutated by Step 1). * @returns Indent string for `*`-prefixed content lines. */ protected _detectContentIndent(lines: string[]): string; /** * @purpose Attempt to convert a multi-line JSDoc comment to single-line format. | Inlines only single-tag contracts (1 @tag); multi-tag contracts stay multi-line. | Performs a dry-run through the parser: if the inline version introduces new | parse errors, the original multi-line text is returned unchanged. * @param jsdocText Raw JSDoc comment text. * @returns Inline text if safe, otherwise the original text. */ protected _inlineIfSafe(jsdocText: string): string; /** * @purpose Extract the specifier (parameter name) from a @param tag line. | Example: `@param userId Description` → `userId` * @param line Trimmed line content starting with `@param`. * @returns The specifier or empty string. */ protected _extractParamSpecifier(line: string): string; }