Harper preset-based options (#17)

Copilot · cyanzhong · web-flow · commit 319d0ff63818 · 2026-03-14T17:38:51.000+08:00
* Initial plan * feat: add conservative Harper defaults and configurable lint settings Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * refactor: align proofreading settings naming and docs Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * docs: keep README references user-facing Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * docs: add user-facing settings and rules links Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * Initial plan * refactor: rename lintProfile→lintPreset, implement 3 severity presets (strict/standard/relaxed), remove disabledLintKinds Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * improve: make parseLintPreset explicitly check all valid values Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * refactor: switch from lint_kind filtering to setLintConfig rule-based approach Use organizedLints() to discover rule→kind mapping at init, then disable rules via setLintConfig() instead of filtering lints after the fact. This properly leverages Harper's configuration API per the docs at https://writewithharper.com/docs/harperjs/configurerules Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * improve: check all lints for kind match, add sample text documentation Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * refactor: replace fragile organizedLints discovery with static rule lists Remove the sample text + organizedLints() approach for discovering rule→kind mappings. Instead, define presets as static lists of specific rule names to disable via setLintConfig(), sourced from Harper's rules documentation and source code. This is simpler, predictable, and directly uses the configurerules API. Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * make preset rule arrays readonly and pre-compute relaxed list Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * refactor: move rule lists from settings.ts to rules.ts Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * rename lintRules to lintRuleOverrides Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * combine rules-based and kind-based filtering for preset robustness Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * extract kinds to kinds.ts, add configurable disabledLintKinds, rename variable, fix prefix Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * docs: document all available lint kinds in README Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> * refactor: rename options.test.ts to settings.test.ts to match source file convention Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: cyanzhong <6745066+cyanzhong@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -1,3 +1,37 @@
 # MarkEdit-proofreading
 
 [MarkEdit](https://github.com/MarkEdit-app/MarkEdit) grammar checker based on [Harper](https://writewithharper.com/).
+
+## Configuration
+
+This extension provides three presets to control how aggressively Harper checks your writing. Presets disable specific [rules](https://writewithharper.com/docs/rules) via [`setLintConfig`](https://writewithharper.com/docs/harperjs/configurerules) and filter by lint kind as a safety net:
+
+- `"strict"`: All Harper rules are active
+- `"standard"` (default): Disables Enhancement, Style, and WordChoice rules
+- `"relaxed"`: Also disables Readability, Redundancy, and Repetition rules
+
+You can customize behavior from `settings.json` with the `extension.markeditProofreading` section (see [MarkEdit advanced settings](https://github.com/MarkEdit-app/MarkEdit/wiki/Customization#advanced-settings)):
+
+```json
+{
+  "extension.markeditProofreading": {
+    "lintPreset": "relaxed",
+    "lintRuleOverrides": {
+      "SpelledNumbers": false,
+      "NoOxfordComma": true
+    },
+    "disabledLintKinds": ["Regionalism"]
+  }
+}
+```
+
+- `lintPreset`: `"strict"`, `"standard"` (default), or `"relaxed"`
+- `lintRuleOverrides`: per-rule overrides (`true` / `false` / `null`) applied on top of the preset
+- `disabledLintKinds`: additional lint kinds to filter out, available kinds:
+  - `Agreement`, `BoundaryError`, `Capitalization`, `Eggcorn`, `Enhancement`
+  - `Formatting`, `Grammar`, `Malapropism`, `Miscellaneous`, `Nonstandard`
+  - `Punctuation`, `Readability`, `Redundancy`, `Regionalism`, `Repetition`
+  - `Spelling`, `Style`, `Typo`, `Usage`, `WordChoice`
+
+For a full list of available rule names, see:
+https://writewithharper.com/docs/rules
diff --git a/src/kinds.ts b/src/kinds.ts
@@ -0,0 +1,16 @@
+import type { LintPreset } from './settings';
+
+// Lint kinds disabled per preset, used as a safety net to catch rules not in static lists.
+const standardDisabledKinds: readonly string[] = ['Enhancement', 'Style', 'WordChoice'];
+const relaxedDisabledKinds: readonly string[] = [...standardDisabledKinds, 'Readability', 'Redundancy', 'Repetition'];
+
+export function presetDisabledKinds(preset: LintPreset): ReadonlySet<string> {
+  switch (preset) {
+    case 'strict':
+      return new Set();
+    case 'standard':
+      return new Set(standardDisabledKinds);
+    case 'relaxed':
+      return new Set(relaxedDisabledKinds);
+  }
+}
diff --git a/src/lint.ts b/src/lint.ts
@@ -1,7 +1,56 @@
-import { LocalLinter, binaryInlined } from 'harper.js';
+import { LocalLinter, binaryInlined, type LintConfig } from 'harper.js';
+import { MarkEdit } from 'markedit-api';
+import { getProofreadingSettings } from './settings';
+import { presetDisabledRules } from './rules';
+import { presetDisabledKinds } from './kinds';
 
 const linter = new LocalLinter({ binary: binaryInlined });
+const settings = getProofreadingSettings(MarkEdit.userSettings);
+const disabledKinds = resolveDisabledKinds();
+const linterReady = configureLinter().catch(error => {
+  console.warn('[MarkEdit-proofreading] Failed to configure linter.', error);
+});
 
 export async function lint(text: string) {
-  return await linter.lint(text);
+  await linterReady;
+  const lints = await linter.lint(text);
+
+  // Post-filter by kind as a safety net for rules not covered by the static lists
+  if (disabledKinds.size === 0) {
+    return lints;
+  }
+
+  return lints.filter(lint => !disabledKinds.has(lint.lint_kind()));
+}
+
+function resolveDisabledKinds(): ReadonlySet<string> {
+  const fromPreset = presetDisabledKinds(settings.lintPreset);
+  if (settings.disabledLintKinds.length === 0) {
+    return fromPreset;
+  }
+
+  return new Set([...fromPreset, ...settings.disabledLintKinds]);
+}
+
+async function configureLinter() {
+  const disabledRules = presetDisabledRules(settings.lintPreset);
+
+  if (disabledRules.length === 0 && Object.keys(settings.lintRuleOverrides).length === 0) {
+    return;
+  }
+
+  const config: LintConfig = await linter.getDefaultLintConfig();
+
+  for (const rule of disabledRules) {
+    if (rule in config) {
+      config[rule] = false;
+    }
+  }
+
+  // Apply user rule overrides on top
+  for (const [name, val] of Object.entries(settings.lintRuleOverrides)) {
+    config[name] = val;
+  }
+
+  await linter.setLintConfig(config);
 }
diff --git a/src/rules.ts b/src/rules.ts
@@ -0,0 +1,50 @@
+import type { LintPreset } from './settings';
+
+// Rules disabled in the "standard" preset (Enhancement, Style, WordChoice).
+// Rule names from https://writewithharper.com/docs/rules
+const standardDisabledRules: readonly string[] = [
+  // Enhancement
+  'BoringWords', 'Excellent', 'Freezing', 'Starving',
+  // Style
+  'AOkHyphen', 'Addicting', 'AdjectiveOfA', 'ArriveOnWeekday', 'ClickThroughRate', 'Cybersec',
+  'ExpandAlloc', 'ExpandArgument', 'ExpandBecause', 'ExpandControl', 'ExpandDecl',
+  'ExpandDependencies', 'ExpandDeref', 'ExpandForward', 'ExpandMemoryShorthands',
+  'ExpandMinimum', 'ExpandParameter', 'ExpandPointer', 'ExpandPrevious',
+  'ExpandStandardInputAndOutput', 'ExpandThrough', 'ExpandTimeShorthands',
+  'ExpandWith', 'ExpandWithout',
+  'FatalOutcome', 'MoreAdjective', 'PasswordProtectedHyphen', 'RainbowColoredHyphen',
+  'SendAnEmailTo', 'SomewhatSomething', 'TrueToWord', 'WordPressDotcom', 'WouldNeverHave',
+  // WordChoice
+  'Alongside', 'AsFarBackAs', 'AsOfCurrently', 'AsOfLately', 'AtFaceValue',
+  'AtTheEndOfTheDay', 'Brutality', 'DespiteOf', 'Insensitive', 'Insurmountable',
+  'LastNight', 'ModalOf', 'RoadMap', 'TongueInCheek', 'VeryUnique', 'WaveFunction',
+];
+
+// Additional rules disabled in the "relaxed" preset (Readability, Redundancy, Repetition).
+const relaxedOnlyDisabledRules: readonly string[] = [
+  // Readability
+  'LongSentences',
+  // Redundancy
+  'ACoupleMore', 'AnAnother', 'AnotherAn', 'AsIfThough', 'AvoidAndAlso',
+  'CondenseAllThe', 'KindOf', 'MissingDeterminer', 'RedundantAcronyms',
+  'RedundantAdditiveAdverbs', 'RedundantIIRC', 'RedundantPretty',
+  'RedundantSuperlatives', 'RedundantThat', 'TickingTimeClock', 'Towards',
+  // Repetition
+  'RepeatedWords',
+];
+
+const relaxedDisabledRules: readonly string[] = [
+  ...standardDisabledRules,
+  ...relaxedOnlyDisabledRules,
+];
+
+export function presetDisabledRules(preset: LintPreset): readonly string[] {
+  switch (preset) {
+    case 'strict':
+      return [];
+    case 'standard':
+      return standardDisabledRules;
+    case 'relaxed':
+      return relaxedDisabledRules;
+  }
+}
diff --git a/src/settings.ts b/src/settings.ts
@@ -0,0 +1,67 @@
+import type { LintConfig } from 'harper.js';
+import type { MarkEdit } from 'markedit-api';
+
+const settingsKey = 'extension.markeditProofreading';
+
+export type LintPreset = 'strict' | 'standard' | 'relaxed';
+
+type JSONObject = MarkEdit['userSettings'];
+type JSONValue = JSONObject[string];
+
+export interface ProofreadingSettings {
+  lintPreset: LintPreset;
+  lintRuleOverrides: LintConfig;
+  disabledLintKinds: string[];
+}
+
+export function getProofreadingSettings(userSettings: JSONObject | undefined): ProofreadingSettings {
+  const defaults: ProofreadingSettings = {
+    lintPreset: 'standard',
+    lintRuleOverrides: {},
+    disabledLintKinds: [],
+  };
+
+  const root = asObject(userSettings);
+  const raw = asObject(root?.[settingsKey]);
+  if (!raw) {
+    return defaults;
+  }
+
+  const lintPreset = parseLintPreset(raw.lintPreset);
+
+  const lintRuleOverrides = Object.fromEntries(
+    Object.entries(asObject(raw.lintRuleOverrides) ?? {}).filter(([, value]) => isLintRuleValue(value)),
+  ) as LintConfig;
+
+  const disabledLintKinds = parseStringArray(raw.disabledLintKinds);
+
+  return { lintPreset, lintRuleOverrides, disabledLintKinds };
+}
+
+function parseLintPreset(value: JSONValue): LintPreset {
+  if (value === 'strict' || value === 'standard' || value === 'relaxed') {
+    return value;
+  }
+
+  return 'standard';
+}
+
+function asObject(value: JSONValue | undefined): JSONObject | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value as JSONObject;
+}
+
+function isLintRuleValue(value: JSONValue): value is boolean | null {
+  return typeof value === 'boolean' || value === null;
+}
+
+function parseStringArray(value: JSONValue): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((item): item is string => typeof item === 'string');
+}
diff --git a/tests/settings.test.ts b/tests/settings.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { getProofreadingSettings } from '../src/settings';
+import { presetDisabledRules } from '../src/rules';
+import { presetDisabledKinds } from '../src/kinds';
+
+describe('proofreading settings', () => {
+  it('uses standard defaults when no settings are provided', () => {
+    const settings = getProofreadingSettings(undefined);
+
+    expect(settings.lintPreset).toBe('standard');
+    expect(settings.lintRuleOverrides).toEqual({});
+    expect(settings.disabledLintKinds).toEqual([]);
+  });
+
+  it('parses lint preset, per-rule overrides from user settings', () => {
+    const settings = getProofreadingSettings({
+      'extension.markeditProofreading': {
+        lintPreset: 'strict',
+        lintRuleOverrides: {
+          SpelledNumbers: true,
+          NoOxfordComma: false,
+          Keep: null,
+          InvalidStringValue: 'yes',
+        },
+        disabledLintKinds: ['Regionalism', 'Enhancement'],
+      },
+    });
+
+    expect(settings.lintPreset).toBe('strict');
+    expect(settings.lintRuleOverrides).toEqual({
+      SpelledNumbers: true,
+      NoOxfordComma: false,
+      Keep: null,
+    });
+    expect(settings.disabledLintKinds).toEqual(['Regionalism', 'Enhancement']);
+  });
+
+  it('filters non-string values from disabledLintKinds', () => {
+    const settings = getProofreadingSettings({
+      'extension.markeditProofreading': {
+        disabledLintKinds: ['Enhancement', 42, true, 'Style'],
+      },
+    });
+
+    expect(settings.disabledLintKinds).toEqual(['Enhancement', 'Style']);
+  });
+
+  it('provides three presets with increasing disabled rule counts', () => {
+    const strict = presetDisabledRules('strict');
+    const standard = presetDisabledRules('standard');
+    const relaxed = presetDisabledRules('relaxed');
+
+    expect(strict).toEqual([]);
+    expect(standard.length).toBeGreaterThan(0);
+    expect(relaxed.length).toBeGreaterThan(standard.length);
+
+    // relaxed includes all standard rules plus more
+    for (const rule of standard) {
+      expect(relaxed).toContain(rule);
+    }
+  });
+
+  it('provides matching disabled kinds for each preset', () => {
+    const strict = presetDisabledKinds('strict');
+    const standard = presetDisabledKinds('standard');
+    const relaxed = presetDisabledKinds('relaxed');
+
+    expect(strict.size).toBe(0);
+    expect(standard).toEqual(new Set(['Enhancement', 'Style', 'WordChoice']));
+    expect(relaxed).toEqual(new Set(['Enhancement', 'Style', 'WordChoice', 'Readability', 'Redundancy', 'Repetition']));
+
+    // relaxed includes all standard kinds
+    for (const kind of standard) {
+      expect(relaxed.has(kind)).toBe(true);
+    }
+  });
+
+  it('falls back to standard for unrecognized preset values', () => {
+    const settings = getProofreadingSettings({
+      'extension.markeditProofreading': {
+        lintPreset: 'unknown',
+      },
+    });
+
+    expect(settings.lintPreset).toBe('standard');
+  });
+});
