harper.js
Version:
The grammar checker that respects your privacy.
583 lines (551 loc) • 24.5 kB
TypeScript
export declare interface BinaryModule {
url: string | URL;
glueFlavor?: WasmGlueFlavor;
getDefaultLintConfigAsJSON(): Promise<string>;
getDefaultLintConfig(): Promise<LintConfig>;
toTitleCase(text: string): Promise<string>;
setup(): Promise<void>;
}
/** A wrapper around the underlying WebAssembly module that contains Harper's core code. Used to construct a `Linter`, as well as access some miscellaneous other functions. */
declare class BinaryModuleImpl {
url: string | URL;
glueFlavor: WasmGlueFlavor;
private inner;
/** Load a binary from a specified URL. This is the only recommended way to construct this type. */
static create(url: string | URL, glueFlavor?: WasmGlueFlavor): BinaryModuleImpl;
getDefaultLintConfigAsJSON(): Promise<string>;
getDefaultLintConfig(): Promise<LintConfig>;
toTitleCase(text: string): Promise<string>;
setup(): Promise<void>;
}
export declare function createBinaryModuleFromUrl(url: string, glueFlavor?: WasmGlueFlavor): BinaryModule;
/**
* Specifies an English Dialect, often used for linting.
*/
export declare enum Dialect {
American = 0,
British = 1,
Australian = 2,
Canadian = 3,
Indian = 4,
}
declare enum Language {
Plain = 0,
Markdown = 1,
Typst = 2,
}
/**
* An error found in provided text.
*
* May include zero or more suggestions that may fix the problematic text.
*/
export declare class Lint {
private constructor();
free(): void;
[Symbol.dispose](): void;
static from_json(json: string): Lint;
/**
* Get the content of the source material pointed to by [`Self::span`]
*/
get_problem_text(): string;
/**
* Get a string representing the general category of the lint.
*/
lint_kind(): string;
/**
* Get a string representing the general category of the lint.
*/
lint_kind_pretty(): string;
/**
* Get a description of the error.
*/
message(): string;
/**
* Get a description of the error as HTML.
*/
message_html(): string;
/**
* Get the location of the problematic text.
*/
span(): Span;
/**
* Equivalent to calling `.length` on the result of `suggestions()`.
*/
suggestion_count(): number;
/**
* Get an array of any suggestions that may resolve the issue.
*/
suggestions(): Suggestion[];
to_json(): string;
}
/** A linting rule configuration dependent on upstream Harper's available rules.
* This is a record, since you shouldn't hard-code the existence of any particular rules and should generalize based on this struct. */
export declare type LintConfig = Record<string, boolean | null>;
/** An interface for an object that can perform linting actions. */
export declare interface Linter {
/** Complete any setup that is necessary before linting. This may include downloading and compiling the WebAssembly binary.
* This setup will complete when needed regardless of whether you call this function.
* This function exists to allow you to do this work when it is of least impact to the user experiences (i.e. while you're loading something else). */
setup(): Promise<void>;
/** Lint the provided text. */
lint(text: string, options?: LintOptions): Promise<Lint[]>;
/** Lint the provided text, maintaining the relationship with the source rule. */
organizedLints(text: string, options?: LintOptions): Promise<Record<string, Lint[]>>;
/** Apply a suggestion from a lint to text, returning the changed text. */
applySuggestion(text: string, lint: Lint, suggestion: Suggestion): Promise<string>;
/** Determine if the provided text is likely to be intended to be English.
* The algorithm can be described as "proof of concept" and as such does not work terribly well.*/
isLikelyEnglish(text: string): Promise<boolean>;
/** Determine which parts of a given string are intended to be English, returning those bits.
* The algorithm can be described as "proof of concept" and as such does not work terribly well.*/
isolateEnglish(text: string): Promise<string>;
/** Get the linter's current configuration. */
getLintConfig(): Promise<LintConfig>;
/** Get the default (unset) linter configuration as JSON.
* This method does not affect the caller's lint configuration, nor does it return the current one. */
getDefaultLintConfigAsJSON(): Promise<string>;
/** Get the default (unset) linter configuration.
* This method does not affect the caller's lint configuration, nor does it return the current one. */
getDefaultLintConfig(): Promise<LintConfig>;
/** Get the linter's current structured configuration.
* This is intended for organizing and rendering settings UIs.
* Persisted config changes must still be applied through the flat `setLintConfig` API. */
getStructuredLintConfig(): Promise<StructuredLintConfig>;
/** Get the linter's current structured configuration as JSON.
* This is a presentation-oriented view over the underlying flat config.
* Persisted config changes must still be applied through the flat `setLintConfig` API. */
getStructuredLintConfigJSON(): Promise<string>;
/** Set the linter's current configuration. */
setLintConfig(config: LintConfig): Promise<void>;
/** Get the linter's current configuration as JSON. */
getLintConfigAsJSON(): Promise<string>;
/** Set the linter's current configuration from JSON. */
setLintConfigWithJSON(config: string): Promise<void>;
/** Get the linting rule descriptions as a JSON map, formatted in Markdown. */
getLintDescriptionsAsJSON(): Promise<string>;
/** Get the linting rule descriptions as an object, formatted in Markdown. */
getLintDescriptions(): Promise<Record<string, string>>;
/** Get the linting rule descriptions as a JSON map, formatted in HTML.
* Wraps the function on the BinaryModule by the same name. */
getLintDescriptionsHTMLAsJSON(): Promise<string>;
/** Get the linting rule descriptions as an object, formatted in HTML.
* Wraps the function on the BinaryModule by the same name. */
getLintDescriptionsHTML(): Promise<Record<string, string>>;
/** Convert a string to Chicago-style title case.
Wraps the function on the BinaryModule by the same name. */
toTitleCase(text: string): Promise<string>;
/** Release resources held by this linter instance. */
dispose(): Promise<void>;
/** Ignore future instances of a lint from a previous linting run in future invocations. */
ignoreLint(source: string, lint: Lint): Promise<void>;
/** Ignore future instances of lints from a previous linting run in future invocations. */
ignoreLints(source: string, lints: Lint[]): Promise<void>;
/** Ignore future instances of a lint from a previous linting run in future invocations using its hash. */
ignoreLintHash(hash: bigint): Promise<void>;
/** Export the ignored lints to a JSON list of privacy-respecting hashes. */
exportIgnoredLints(): Promise<string>;
/** Import ignored lints from a JSON list to the linter.
* This function appends to the existing lints, if any. */
importIgnoredLints(json: string): Promise<void>;
/** Produce a context-sensitive hash that represents a lint. */
contextHash(source: string, lint: Lint): Promise<bigint>;
/** Clear records of all previously ignored lints. */
clearIgnoredLints(): Promise<void>;
/** Clear the words which have been added to the dictionary. This will not clear words from the curated dictionary. */
clearWords(): Promise<void>;
/** Import words into the dictionary. This is a significant operation, so try to batch words. */
importWords(words: string[]): Promise<void>;
/** Export all added words from the dictionary. Note that this will NOT export anything from the curated dictionary,
* only words from previous calls to `this.importWords`. */
exportWords(): Promise<string[]>;
/** Get the dialect of English this linter was constructed for. */
getDialect(): Promise<Dialect>;
/** Get the dialect of English this linter was constructed for. */
setDialect(dialect: Dialect): Promise<void>;
/** Summarize the linter's usage statistics.
* You may optionally pass in a start and/or end time.
*
* If so, the summary with only include data from _after_ the start time but _before_ the end time. */
summarizeStats(start?: bigint, end?: bigint): Promise<Summary>;
/** Generate a statistics log file you can save to permanent storage. */
generateStatsFile(): Promise<string>;
/** Import a statistics log file. */
importStatsFile(statsFile: string): Promise<void>;
/**
* Load a Weirpack from a Blob, merging its rules into the current linter.
* Returns `undefined` when the Weirpack tests pass and the rules are imported,
* otherwise returns a map of rule names → failing tests so the caller can
* surface the broken expectations.
*/
loadWeirpackFromBlob(blob: Blob): Promise<WeirpackTestFailures | undefined>;
/**
* Load a Weirpack from an array of bytes, merging its rules into the current linter.
* Returns the same failure report structure as `loadWeirpackFromBlob`.
*/
loadWeirpackFromBytes(bytes: Uint8Array): Promise<WeirpackTestFailures | undefined>;
}
declare class Linter_2 {
private constructor();
free(): void;
[Symbol.dispose](): void;
/**
* Apply a suggestion from a given lint.
* This action will be logged to the Linter's statistics.
*/
apply_suggestion(source_text: string, lint: Lint, suggestion: Suggestion): string;
clear_ignored_lints(): void;
/**
* Clear the user dictionary.
*/
clear_words(): void;
/**
* Compute the context hash of a given lint.
*/
context_hash(source_text: string, lint: Lint): bigint;
/**
* Export the linter's ignored lints as a privacy-respecting JSON list of hashes.
*/
export_ignored_lints(): string;
/**
* Export words from the dictionary.
* Note: this will only return words previously added by [`Self::import_words`].
*/
export_words(): string[];
generate_stats_file(): string;
/**
* Get the dialect this struct was constructed for.
*/
get_dialect(): Dialect;
get_lint_config_as_json(): string;
get_lint_config_as_object(): any;
/**
* Get a JSON map containing the descriptions of all the linting rules, formatted as Markdown.
*/
get_lint_descriptions_as_json(): string;
/**
* Get a Record containing the descriptions of all the linting rules, formatted as Markdown.
*/
get_lint_descriptions_as_object(): any;
/**
* Get a JSON map containing the descriptions of all the linting rules, formatted as HTML.
*/
get_lint_descriptions_html_as_json(): string;
/**
* Get a Record containing the descriptions of all the linting rules, formatted as HTML.
*/
get_lint_descriptions_html_as_object(): any;
get_structured_lint_config_as_json(): string;
get_structured_lint_config_as_object(): any;
/**
* Add a specific context hash to the ignored lints list.
*/
ignore_hashes(hashes: BigUint64Array): void;
ignore_lints(source_text: string, lints: Lint[]): void;
/**
* Import into the linter's ignored lints from a privacy-respecting JSON list of hashes.
*/
import_ignored_lints(json: string): void;
import_stats_file(file: string): void;
/**
* Load a Weirpack from raw bytes, merging its rules into the current linter.
* Returns test failures if any are found, and does not import in that case.
*/
import_weirpack(bytes: Uint8Array): any;
/**
* Import words into the dictionary.
*/
import_words(additional_words: string[]): void;
/**
* Helper method to quickly check if a plain string is likely intended to be English
*/
is_likely_english(text: string): boolean;
/**
* Helper method to remove non-English text from a plain English document.
*/
isolate_english(text: string): string;
/**
* Perform the configured linting on the provided text.
*
* If the provided regex mask cannot be parsed, this method will return an empty array.
*/
lint(text: string, language: Language, all_headings: boolean, regex_mask: string | null | undefined, dedup: boolean, isolate_english: boolean): Lint[];
/**
* Construct a new `Linter`.
* Note that this can mean constructing the curated dictionary, which is the most expensive operation
* in Harper.
*/
static new(dialect: Dialect): Linter_2;
organized_lints(text: string, language: Language, all_headings: boolean, regex_mask: string | null | undefined, dedup: boolean, isolate_english: boolean): OrganizedGroup[];
set_lint_config_from_json(json: string): void;
set_lint_config_from_object(object: any): void;
summarize_stats(start_time?: bigint | null, end_time?: bigint | null): any;
}
/** The properties and information needed to construct a Linter. */
export declare interface LinterInit {
/** The module or path to the WebAssembly binary. */
binary: BinaryModule;
/** The dialect of English Harper should use. If omitted, Harper will default to American English. */
dialect?: Dialect;
}
export declare type LintKind = 'Agreement' | 'BoundaryError' | 'Capitalization' | 'Eggcorn' | 'Enhancement' | 'Formatting' | 'Grammar' | 'Malapropism' | 'Miscellaneous' | 'Nonstandard' | 'Punctuation' | 'Readability' | 'Redundancy' | 'Regionalism' | 'Repetition' | 'Spelling' | 'Style' | 'Typo' | 'Usage' | 'WordChoice' | 'WordOrder';
/** Options available to configure Harper's parser for an individual linting operation. */
export declare interface LintOptions {
/** The markup language that is being passed. Defaults to `markdown`. */
language?: 'plaintext' | 'markdown' | 'typst';
regex_mask?: string;
/** Force the entirety of the document to be composed of headings. An undefined value is assumed to be false.*/
forceAllHeadings?: boolean;
/** Remove overlapping lints. An undefined value is assumed to be true. */
dedup?: boolean;
/** Ignore text that is unlikely to be English. An undefined value is assumed to be false. */
isolateEnglish?: boolean;
}
/** A Linter that runs in the current JavaScript context (meaning it is allowed to block the event loop).
* See the interface definition for more details. */
export declare class LocalLinter implements Linter {
binary: SuperBinaryModule;
private inner;
private disposed;
constructor(init: LinterInit);
private createInner;
setup(): Promise<void>;
lint(text: string, options?: LintOptions): Promise<Lint[]>;
organizedLints(text: string, options?: LintOptions): Promise<Record<string, Lint[]>>;
applySuggestion(text: string, lint: Lint, suggestion: Suggestion): Promise<string>;
isLikelyEnglish(text: string): Promise<boolean>;
isolateEnglish(text: string): Promise<string>;
getLintConfig(): Promise<LintConfig>;
getDefaultLintConfigAsJSON(): Promise<string>;
getDefaultLintConfig(): Promise<LintConfig>;
getStructuredLintConfig(): Promise<StructuredLintConfig>;
getStructuredLintConfigJSON(): Promise<string>;
setLintConfig(config: LintConfig): Promise<void>;
getLintConfigAsJSON(): Promise<string>;
setLintConfigWithJSON(config: string): Promise<void>;
toTitleCase(text: string): Promise<string>;
getLintDescriptions(): Promise<Record<string, string>>;
getLintDescriptionsAsJSON(): Promise<string>;
getLintDescriptionsHTML(): Promise<Record<string, string>>;
getLintDescriptionsHTMLAsJSON(): Promise<string>;
ignoreLint(source: string, lint: Lint): Promise<void>;
ignoreLints(source: string, lints: Lint[]): Promise<void>;
ignoreLintHash(hash: bigint): Promise<void>;
exportIgnoredLints(): Promise<string>;
importIgnoredLints(json: string): Promise<void>;
contextHash(source: string, lint: Lint): Promise<bigint>;
clearIgnoredLints(): Promise<void>;
clearWords(): Promise<void>;
importWords(words: string[]): Promise<void>;
exportWords(): Promise<string[]>;
getDialect(): Promise<Dialect>;
setDialect(dialect: Dialect): Promise<void>;
summarizeStats(start?: bigint, end?: bigint): Promise<any>;
generateStatsFile(): Promise<string>;
importStatsFile(statsFile: string): Promise<void>;
/**
* Load a Weirpack from a Blob.
*
* Returns `undefined` if tests pass and rules are imported, otherwise returns
* the Weirpack test failures.
*/
loadWeirpackFromBlob(blob: Blob): Promise<WeirpackTestFailures | undefined>;
/**
* Load a Weirpack from a byte array.
*
* Returns `undefined` if tests pass and rules are imported, otherwise returns
* the Weirpack test failures.
*/
loadWeirpackFromBytes(bytes: Uint8Array | number[]): Promise<WeirpackTestFailures | undefined>;
dispose(): Promise<void>;
}
/**
* Used exclusively for [`Linter::organized_lints`]
*/
declare class OrganizedGroup {
private constructor();
free(): void;
[Symbol.dispose](): void;
group: string;
lints: Lint[];
}
/** Convert a Weirpack file system into a real Weirpack binary by compressing and serializing them into a byte array.
*
* For clarity on what a Weirpack is, read [the Weir documentation.](https://writewithharper.com/docs/weir#Weirpacks) */
export declare function packWeirpackFiles(files: Map<string, string>): Uint8Array;
/**
* A struct that represents two character indices in a string: a start and an end.
*/
export declare class Span {
private constructor();
free(): void;
[Symbol.dispose](): void;
static from_json(json: string): Span;
is_empty(): boolean;
len(): number;
static new(start: number, end: number): Span;
to_json(): string;
end: number;
start: number;
}
export declare interface StructuredLintBoolSetting {
Bool: {
name: string;
state: boolean;
label?: string | null;
};
}
export declare interface StructuredLintConfig {
settings: StructuredLintSetting[];
}
export declare interface StructuredLintGroupSetting {
Group: {
label: string;
description: string;
child: StructuredLintConfig;
};
}
export declare interface StructuredLintOneOfManySetting {
OneOfMany: {
names: string[];
name?: string | null;
labels?: string[] | null;
};
}
export declare type StructuredLintSetting = StructuredLintBoolSetting | StructuredLintOneOfManySetting | StructuredLintGroupSetting;
/**
* A suggestion to fix a Lint.
*/
export declare class Suggestion {
private constructor();
free(): void;
[Symbol.dispose](): void;
static from_json(json: string): Suggestion;
/**
* Get the text that is going to replace the problematic section.
* If [`Self::kind`] is `SuggestionKind::Remove`, this will return an empty
* string.
*/
get_replacement_text(): string;
kind(): SuggestionKind;
to_json(): string;
}
/**
* Tags the variant of suggestion.
*/
export declare enum SuggestionKind {
/**
* Replace the problematic text.
*/
Replace = 0,
/**
* Remove the problematic text.
*/
Remove = 1,
/**
* Insert additional text after the error.
*/
InsertAfter = 2,
}
/**
* Represents the summary of linting results and history.
* Useful to show linting statistics or insights to the user.
*/
export declare interface Summary {
/**
* An object mapping each lint type to its count.
* Example: `{ "Spelling": 4, "Capitalization": 1 }`
*/
lint_counts: Record<string, number>;
/**
* The total number of fixes applied.
*/
total_applied: number;
/**
* An object mapping misspelled words to their occurrence counts.
* Example: `{ "mispelled": 1, "mispell": 1, "thigs": 2 }`
*/
misspelled: Record<string, number>;
}
declare class SuperBinaryModule extends BinaryModuleImpl {
createLinter(dialect?: Dialect): Promise<Linter_2>;
getBinaryModule(): Promise<any>;
}
/** Decompress and deserialize a Weirpack from a byte array. */
export declare function unpackWeirpackBytes(bytes: Uint8Array): WeirpackArchive;
declare type WasmGlueFlavor = 'full' | 'slim';
export declare type WeirpackArchive = {
manifest: Record<string, unknown>;
files: Map<string, string>;
};
export declare interface WeirpackTestFailure {
expected: string;
got: string;
}
export declare type WeirpackTestFailures = Record<string, WeirpackTestFailure[]>;
/** A Linter that spins up a dedicated web worker to do processing on a separate thread.
* Main benefit: this Linter will not block the event loop for large documents.
*
* NOTE: This class will not work properly in Node. In that case, just use `LocalLinter`. */
export declare class WorkerLinter implements Linter {
private binary;
private serializer;
private dialect?;
private worker;
private requestQueue;
private working;
private disposed;
constructor(init: LinterInit);
private setupMainEventListeners;
setup(): Promise<void>;
lint(text: string, options?: LintOptions): Promise<Lint[]>;
organizedLints(text: string, options?: LintOptions): Promise<Record<string, Lint[]>>;
applySuggestion(text: string, lint: Lint, suggestion: Suggestion): Promise<string>;
isLikelyEnglish(text: string): Promise<boolean>;
isolateEnglish(text: string): Promise<string>;
getLintConfig(): Promise<LintConfig>;
setLintConfig(config: LintConfig): Promise<void>;
getLintConfigAsJSON(): Promise<string>;
setLintConfigWithJSON(config: string): Promise<void>;
toTitleCase(text: string): Promise<string>;
getLintDescriptionsAsJSON(): Promise<string>;
getLintDescriptions(): Promise<Record<string, string>>;
getLintDescriptionsHTMLAsJSON(): Promise<string>;
getLintDescriptionsHTML(): Promise<Record<string, string>>;
getDefaultLintConfigAsJSON(): Promise<string>;
getDefaultLintConfig(): Promise<LintConfig>;
getStructuredLintConfig(): Promise<StructuredLintConfig>;
getStructuredLintConfigJSON(): Promise<string>;
dispose(): Promise<void>;
ignoreLint(source: string, lint: Lint): Promise<void>;
ignoreLints(source: string, lints: Lint[]): Promise<void>;
ignoreLintHash(hash: bigint): Promise<void>;
exportIgnoredLints(): Promise<string>;
importIgnoredLints(json: string): Promise<void>;
contextHash(source: string, lint: Lint): Promise<bigint>;
clearIgnoredLints(): Promise<void>;
clearWords(): Promise<void>;
importWords(words: string[]): Promise<void>;
exportWords(): Promise<string[]>;
getDialect(): Promise<Dialect>;
setDialect(dialect: Dialect): Promise<void>;
summarizeStats(start?: bigint, end?: bigint): Promise<any>;
generateStatsFile(): Promise<string>;
importStatsFile(statsFile: string): Promise<void>;
/**
* Load a Weirpack from a Blob via the worker thread.
*
* Returns `undefined` when the tests pass and the pack is imported, otherwise
* forwards the failure report back to the caller.
*/
loadWeirpackFromBlob(blob: Blob): Promise<WeirpackTestFailures | undefined>;
/**
* Load a Weirpack from bytes via the worker thread.
*
* Returns the failure report if tests fail or `undefined` when the pack is imported.
*/
loadWeirpackFromBytes(bytes: Uint8Array | number[]): Promise<WeirpackTestFailures | undefined>;
/** Run a procedure on the remote worker. */
private rpc;
private submitRemainingRequests;
}
export { }