Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

feat: extremely tentative support for JSDoc

Elijah Potter5b0b1050ffe5
diff --git a/Cargo.lock b/Cargo.lock
index e40d5e23c..d6fca02cb 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -558,6 +558,7 @@ name = "harper-comments"
version = "0.8.6"
dependencies = [
"harper-core",
+ "itertools 0.12.1",
"paste",
"tree-sitter",
"tree-sitter-c",
@@ -582,7 +583,7 @@ dependencies = [
"divan",
"hashbrown",
"is-macro",
- "itertools",
+ "itertools 0.12.1",
"once_cell",
"paste",
"pulldown-cmark",
@@ -604,7 +605,7 @@ dependencies = [
"futures",
"harper-comments",
"harper-core",
- "itertools",
+ "itertools 0.13.0",
"once_cell",
"open",
"resolve-path",
@@ -780,6 +781,15 @@ dependencies = [
"either",
]
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
[[package]]
name = "itoa"
version = "1.0.11"
diff --git a/harper-comments/Cargo.toml b/harper-comments/Cargo.toml
index e67b31ab7..22ce6cc13 100644
--- a/harper-comments/Cargo.toml
+++ b/harper-comments/Cargo.toml
@@ -22,6 +22,7 @@ tree-sitter-swift = "=0.4.0"
tree-sitter-c-sharp = "0.20.0"
tree-sitter-toml = "0.20.0"
tree-sitter-lua = "0.0.19"
+itertools = "0.12.1"
[dev-dependencies]
paste = "1.0.15"
diff --git a/harper-comments/src/comment_parsers/go.rs b/harper-comments/src/comment_parsers/go.rs
index 37ac0c354..0c90b7d81 100644
--- a/harper-comments/src/comment_parsers/go.rs
+++ b/harper-comments/src/comment_parsers/go.rs
@@ -36,6 +36,3 @@ impl Parser for Go {
new_tokens
}
}
-
-#[cfg(test)]
-mod tests {}
diff --git a/harper-comments/src/comment_parsers/jsdoc.rs b/harper-comments/src/comment_parsers/jsdoc.rs
new file mode 100644
index 000000000..f208466fb
--- /dev/null
+++ b/harper-comments/src/comment_parsers/jsdoc.rs
@@ -0,0 +1,194 @@
+use harper_core::parsers::{Markdown, Parser};
+use harper_core::{Punctuation, Token, TokenKind};
+use itertools::Itertools;
+
+use super::without_initiators;
+
+pub struct JsDoc;
+
+impl Parser for JsDoc {
+ fn parse(&mut self, source: &[char]) -> Vec<Token> {
+ dbg!();
+
+ let actual = without_initiators(source);
+
+ if actual.is_empty() {
+ return Vec::new();
+ }
+
+ let source = actual.get_content(source);
+ let mut tokens = Markdown.parse(source);
+
+ let mut cursor = 0;
+
+ // Handle inline tags
+ loop {
+ if cursor >= tokens.len() {
+ break;
+ }
+
+ if let Some(new_cursor) = &tokens[cursor..]
+ .iter()
+ .position(|t| t.kind == TokenKind::Punctuation(Punctuation::OpenCurly))
+ .map(|i| i + cursor)
+ {
+ cursor = *new_cursor;
+ } else {
+ break;
+ }
+
+ let parsers = [parse_link, parse_tutorial];
+
+ for parser in parsers {
+ if let Some(p) = parser(&tokens[cursor..], source) {
+ for tok in &mut tokens[cursor..cursor + p] {
+ tok.kind = TokenKind::Unlintable;
+ }
+
+ cursor += p;
+ continue;
+ }
+ }
+ }
+
+ // Handle the block tag, if it exists
+ if let Some(tag_start) = tokens.iter().tuple_windows().position(|(a, b)| {
+ matches!(
+ (a, b),
+ (
+ Token {
+ kind: TokenKind::Punctuation(Punctuation::At),
+ ..
+ },
+ Token {
+ kind: TokenKind::Word,
+ ..
+ }
+ )
+ )
+ }) {
+ for token in &mut tokens[tag_start..] {
+ token.kind = TokenKind::Unlintable;
+ }
+ }
+
+ for token in tokens.iter_mut() {
+ token.span.push_by(actual.start);
+ }
+
+ tokens
+ }
+}
+
+fn parse_link(tokens: &[Token], source: &[char]) -> Option<usize> {
+ parse_inline_tag(&['l', 'i', 'n', 'k'], tokens, source)
+}
+
+fn parse_tutorial(tokens: &[Token], source: &[char]) -> Option<usize> {
+ parse_inline_tag(&['t', 'u', 't', 'o', 'r', 'i', 'a', 'l'], tokens, source)
+}
+
+/// Checks if the provided token slice begins with an inline tag, returning it's
+/// end if so.
+fn parse_inline_tag(tag_name: &[char], tokens: &[Token], source: &[char]) -> Option<usize> {
+ if !matches!(
+ tokens,
+ [
+ Token {
+ kind: TokenKind::Punctuation(Punctuation::OpenCurly),
+ ..
+ },
+ Token {
+ kind: TokenKind::Punctuation(Punctuation::At),
+ ..
+ },
+ Token {
+ kind: TokenKind::Word,
+ ..
+ },
+ ..,
+ ]
+ ) {
+ return None;
+ }
+
+ dbg!(tokens[2].span.get_content(source));
+
+ if tokens[2].span.get_content(source) != tag_name {
+ dbg!();
+ return None;
+ }
+
+ let mut cursor = 3;
+
+ while !matches!(
+ tokens.get(cursor),
+ Some(Token {
+ kind: TokenKind::Punctuation(Punctuation::CloseCurly),
+ ..
+ })
+ ) {
+ cursor += 1;
+ }
+
+ Some(cursor + 1)
+}
+
+#[cfg(test)]
+mod tests {
+ use harper_core::{Document, Punctuation, TokenKind};
+
+ use crate::TreeSitterParser;
+
+ #[test]
+ fn handles_inline_link() {
+ let source = "/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}. */";
+ let parser = TreeSitterParser::new_from_language_id("javascript").unwrap();
+ let document = Document::new(source, Box::new(parser));
+
+ assert_eq!(
+ document.tokens().map(|t| t.kind).collect::<Vec<_>>(),
+ vec![
+ TokenKind::Word,
+ TokenKind::Space(1),
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Space(1),
+ TokenKind::Word,
+ TokenKind::Space(1),
+ TokenKind::Punctuation(Punctuation::OpenSquare),
+ TokenKind::Word,
+ TokenKind::Space(1),
+ TokenKind::Word,
+ TokenKind::Space(1),
+ TokenKind::Word,
+ TokenKind::Punctuation(Punctuation::CloseSquare),
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Unlintable,
+ TokenKind::Punctuation(Punctuation::Period),
+ TokenKind::Newline(1),
+ ]
+ );
+ }
+
+ #[test]
+ fn handles_class() {
+ let source = "/** @class Circle representing a circle. */";
+ let parser = TreeSitterParser::new_from_language_id("javascript").unwrap();
+ let document = Document::new(source, Box::new(parser));
+
+ assert!(document
+ .tokens()
+ .all(|t| t.kind.is_unlintable() || t.kind.is_newline()));
+ }
+}
diff --git a/harper-comments/src/comment_parsers/mod.rs b/harper-comments/src/comment_parsers/mod.rs
index 37965327d..3d1aec7e4 100644
--- a/harper-comments/src/comment_parsers/mod.rs
+++ b/harper-comments/src/comment_parsers/mod.rs
@@ -1,8 +1,10 @@
mod go;
+mod jsdoc;
mod unit;
pub use go::Go;
use harper_core::Span;
+pub use jsdoc::JsDoc;
pub use unit::Unit;
/// Get the span of a tree-sitter-produced comment that doesn't include the
diff --git a/harper-comments/src/tree_sitter_parser.rs b/harper-comments/src/tree_sitter_parser.rs
index 7ac5fee57..d1354c351 100644
--- a/harper-comments/src/tree_sitter_parser.rs
+++ b/harper-comments/src/tree_sitter_parser.rs
@@ -6,6 +6,7 @@ use harper_core::{FullDictionary, Span, Token, TokenKind};
use tree_sitter::{Language, Node, Tree, TreeCursor};
use super::comment_parsers::{Go, Unit};
+use crate::comment_parsers::JsDoc;
/// A Harper parser that wraps various comment parsers that
/// exclusively parses comments in any language supported by [`tree_sitter`].
@@ -35,6 +36,7 @@ impl TreeSitterParser {
};
let comment_parser: Box<dyn Parser> = match language_id {
+ "javascriptreact" | "typescript" | "typescriptreact" | "javascript" => Box::new(JsDoc),
"go" => Box::new(Go),
_ => Box::new(Unit)
};
diff --git a/harper-comments/tests/language_support.rs b/harper-comments/tests/language_support.rs
index 7ed44b270..0810a2d1c 100644
--- a/harper-comments/tests/language_support.rs
+++ b/harper-comments/tests/language_support.rs
@@ -28,6 +28,7 @@ macro_rules! create_test {
);
let lints = linter.lint(&document);
+ dbg!(&lints);
assert_eq!(lints.len(), $correct_expected);
}
}
@@ -37,3 +38,4 @@ macro_rules! create_test {
create_test!(multiline_comments.cpp, 3);
create_test!(multiline_comments.ts, 3);
create_test!(clean.rs, 0);
+create_test!(jsdoc.ts, 2);
diff --git a/harper-comments/tests/language_support_sources/jsdoc.ts b/harper-comments/tests/language_support_sources/jsdoc.ts
new file mode 100644
index 000000000..ccf83da39
--- /dev/null
+++ b/harper-comments/tests/language_support_sources/jsdoc.ts
@@ -0,0 +1,10 @@
+/** This is a doc comment.
+ * Since there are no keywords it _sould_ be checked. */
+function test(){}
+
+/** @class this sould be unchecked. */
+class Clazz { }
+
+/** Here is another example: {@link this sould also b unchecked} */
+
+/** However, tis should be checked, while {@link tis should not} */
diff --git a/harper-core/src/document.rs b/harper-core/src/document.rs
index c8ce19ccd..fbaab8716 100644
--- a/harper-core/src/document.rs
+++ b/harper-core/src/document.rs
@@ -56,6 +56,7 @@ impl Document {
/// Should be run after every change to the underlying [`Self::source`].
fn parse(&mut self) {
self.tokens = self.parser.parse(&self.source);
+ self.condense_spaces();
self.condense_newlines();
self.condense_contractions();
self.condense_number_suffixes();
@@ -284,6 +285,44 @@ impl Document {
self.condense_indices(&replace_starts, 2);
}
+ /// Searches for multiple sequential newline tokens and condenses them down
+ /// into one.
+ fn condense_spaces(&mut self) {
+ let mut cursor = 0;
+ let copy = self.tokens.clone();
+
+ let mut remove_these = VecDeque::new();
+
+ while cursor < self.tokens.len() {
+ // Locate a stretch of one or more newline tokens.
+ let start_tok = &mut self.tokens[cursor];
+
+ if let TokenKind::Space(start_count) = &mut start_tok.kind {
+ loop {
+ cursor += 1;
+
+ if cursor >= copy.len() {
+ break;
+ }
+
+ let child_tok = &copy[cursor];
+ if let TokenKind::Space(n) = child_tok.kind {
+ *start_count += n;
+ start_tok.span.end = child_tok.span.end;
+ remove_these.push_back(cursor);
+ cursor += 1;
+ } else {
+ break;
+ };
+ }
+ }
+
+ cursor += 1;
+ }
+
+ remove_indices(&mut self.tokens, remove_these);
+ }
+
/// Searches for multiple sequential newline tokens and condenses them down
/// into one.
fn condense_newlines(&mut self) {
@@ -429,6 +468,14 @@ impl TokenStringExt for Document {
fn iter_numbers(&self) -> impl Iterator<Item = Token> + '_ {
self.tokens.iter_numbers()
}
+
+ fn iter_at_indices(&self) -> impl Iterator<Item = usize> + '_ {
+ self.tokens.iter_at_indices()
+ }
+
+ fn iter_at(&self) -> impl Iterator<Item = Token> + '_ {
+ self.tokens.iter_at()
+ }
}
fn is_sentence_terminator(token: &TokenKind) -> bool {
@@ -469,7 +516,7 @@ fn remove_indices<T>(vec: &mut Vec<T>, mut to_remove: VecDeque<usize>) {
#[cfg(test)]
mod tests {
- use std::collections::{vec_deque, VecDeque};
+ use std::collections::VecDeque;
use super::Document;
use crate::document::remove_indices;
diff --git a/harper-core/src/span.rs b/harper-core/src/span.rs
index 4286fe98a..8411e2280 100644
--- a/harper-core/src/span.rs
+++ b/harper-core/src/span.rs
@@ -30,6 +30,12 @@ impl Span {
self.len() == 0
}
+ pub fn contains(&self, idx: usize) -> bool {
+ assert!(self.start <= self.end);
+
+ self.start <= idx && idx < self.end
+ }
+
pub fn overlaps_with(&self, other: Self) -> bool {
self.start.max(other.start) <= self.end.min(other.end)
}
diff --git a/harper-core/src/token.rs b/harper-core/src/token.rs
index 9198fe365..fbac711a5 100644
--- a/harper-core/src/token.rs
+++ b/harper-core/src/token.rs
@@ -170,6 +170,8 @@ pub trait TokenStringExt {
fn iter_quotes(&self) -> impl Iterator<Item = Token> + '_;
fn iter_number_indices(&self) -> impl Iterator<Item = usize> + '_;
fn iter_numbers(&self) -> impl Iterator<Item = Token> + '_;
+ fn iter_at_indices(&self) -> impl Iterator<Item = usize> + '_;
+ fn iter_at(&self) -> impl Iterator<Item = Token> + '_;
}
impl TokenStringExt for [Token] {
@@ -259,4 +261,19 @@ impl TokenStringExt for [Token] {
fn iter_numbers(&self) -> impl Iterator<Item = Token> + '_ {
self.iter_number_indices().map(|idx| self[idx])
}
+
+ /// Iterates through the indices of all "@" signs.
+ fn iter_at_indices(&self) -> impl Iterator<Item = usize> + '_ {
+ self.iter().enumerate().filter_map(|(idx, token)| {
+ if let TokenKind::Punctuation(Punctuation::At) = &token.kind {
+ Some(idx)
+ } else {
+ None
+ }
+ })
+ }
+
+ fn iter_at(&self) -> impl Iterator<Item = Token> + '_ {
+ self.iter_at_indices().map(|idx| self[idx])
+ }
}
diff --git a/harper-ls/Cargo.toml b/harper-ls/Cargo.toml
index 93adef964..93ceff6f3 100644
--- a/harper-ls/Cargo.toml
+++ b/harper-ls/Cargo.toml
@@ -17,7 +17,7 @@ once_cell = "1.19.0"
dirs = "5.0.1"
anyhow = "1.0.80"
serde_json = "1.0.114"
-itertools = "0.12.1"
+itertools = "0.13.0"
tracing = "0.1.40"
tracing-subscriber = "0.3.18"
resolve-path = "0.1.0"