Add infrastructure for linting and creating new Lints

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "compiler/qsc_fir",
     "compiler/qsc_frontend",
     "compiler/qsc_hir",
+    "compiler/qsc_linter",
     "compiler/qsc_parse",
     "compiler/qsc_passes",
     "compiler/qsc_project",

compiler/qsc/Cargo.toml

@@ -22,6 +22,7 @@ qsc_doc_gen = { path = "../qsc_doc_gen" }
 qsc_formatter = { path = "../qsc_formatter" }
 qsc_eval = { path = "../qsc_eval" }
 qsc_frontend = { path = "../qsc_frontend" }
+qsc_linter = { path = "../qsc_linter" }
 qsc_ast = { path = "../qsc_ast" }
 qsc_fir = { path = "../qsc_fir" }
 qsc_hir = { path = "../qsc_hir" }

compiler/qsc/src/compile.rs

@@ -27,6 +27,10 @@ pub enum ErrorKind {
     /// These errors are typically related to optimization, transformation, code generation, passes,
     /// and static analysis passes.
     Pass(#[from] qsc_passes::Error),
+
+    /// `Lint` variant represents lints generated during the linting stage. These diagnostics are
+    /// typically emited from the language server and happens after all other compilation passes.
+    Lint(#[from] qsc_linter::Lint),
 }
 
 #[must_use]

compiler/qsc/src/lib.rs

@@ -47,4 +47,8 @@ pub use qsc_eval::{
     state::{fmt_basis_state_label, fmt_complex, format_state_id, get_latex, get_phase},
 };
 
+pub mod linter {
+    pub use qsc_linter::{run_lints, LintConfig, LintKind, LintLevel};
+}
+
 pub use qsc_doc_gen::{display, generate_docs};

compiler/qsc_linter/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "qsc_linter"
+
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+miette = { workspace = true }
+qsc_ast = { path = "../qsc_ast" }
+qsc_hir = { path = "../qsc_hir" }
+qsc_data_structures = { path = "../qsc_data_structures" }
+qsc_frontend = { path = "../qsc_frontend" }
+serde = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+expect-test = { workspace = true }
+qsc_parse = { path = "../qsc_parse" }
+serde_json = { workspace = true }
+qsc = { path = "../qsc" }
+qsc_passes = { path = "../qsc_passes" }
+
+[lints]
+workspace = true
+
+[lib]
+doctest = false

compiler/qsc_linter/src/lib.rs

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! This crate contains the linter for the Q# language.
+//!
+//! It includes lints for the following stages of the compilation process:
+//!  - AST
+//!  - HIR
+//!
+//! # Usage
+//!
+//! The entry points to the linter is the `run_lints` function, which takes
+//! a [`qsc_frontend::compile::CompileUnit`] as input and outputs a [`Vec<Lint>`](Lint).
+//!
+//! ## Example
+//!
+//! ```
+//! use linter::run_lints;;
+//! use qsc::compile::compile;
+//!
+//! let unit: CompileUnit = compile(...);
+//!
+//! // The second argument is an optional user configuration.
+//! let lints: Vec<Lint> = run_ast_lints(&package, None);
+//! ```
+//!
+//! # How to add a new Lint
+//!
+//! We can add a new lint in two steps:
+//!  1. Declaring the lint: here you set the lint name, the default [`LintLevel`], and the message the user will see.
+//!  2. Implementing the lint: here you write the pattern matching logic of the new lint.
+//!
+//! Below is a full example of how to a new AST lint.
+//!
+//! ## Example
+//!
+//! First, we add our lint to `src/lints/ast.rs`.
+//! ```
+//! declare_ast_lints!{
+//!   ...
+//!   (DoubleParens, LintLevel::Warn, "unnecesary double parentheses"),
+//! }
+//! ```
+//!
+//! Then we implement the right `LintPass` for our new lint, in this case `linter::ast::AstLintPass`
+//! ```
+//! impl linter::ast::AstLintPass for DoubleParens {
+//!     // we only need to impl the relevant check_* method, all the other ones
+//!     // will default to an empty method that will get optmized by rust
+//!     fn check_expr(expr: &qsc_ast::ast::Expr, buffer: &mut Vec<Lint>) {
+//!         // we match the relevant pattern
+//!         if let ExprKind::Paren(ref inner_expr) = *expr.kind {
+//!             if matches!(*inner_expr.kind, ExprKind::Paren(_)) {
+//!                 // we push the lint to the buffer
+//!                 push_lint!(Self, expr.span, buffer);
+//!             }
+//!         }
+//!     }
+//! }
+//! ```
+
+#![deny(missing_docs)]
+
+mod linter;
+mod lints;
+#[cfg(test)]
+mod tests;
+
+pub use linter::{run_lints, Lint, LintConfig, LintKind, LintLevel};

compiler/qsc_linter/src/linter.rs

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+pub(crate) mod ast;
+pub(crate) mod hir;
+
+use self::{ast::run_ast_lints, hir::run_hir_lints};
+use crate::lints::{ast::AstLint, hir::HirLint};
+use miette::{Diagnostic, LabeledSpan};
+use qsc_data_structures::span::Span;
+use qsc_frontend::compile::CompileUnit;
+use serde::Deserialize;
+use std::fmt::Display;
+
+/// The entry point to the linter. It takes a [`qsc_frontend::compile::CompileUnit`]
+/// as input and outputs a [`Vec<Lint>`](Lint).
+#[must_use]
+pub fn run_lints(compile_unit: &CompileUnit, config: Option<&[LintConfig]>) -> Vec<Lint> {
+    let mut ast_lints = run_ast_lints(&compile_unit.ast.package, config);
+    let mut hir_lints = run_hir_lints(&compile_unit.package, config);
+
+    let mut lints = Vec::new();
+    lints.append(&mut ast_lints);
+    lints.append(&mut hir_lints);
+    lints
+        .into_iter()
+        .filter(|lint| !matches!(lint.level, LintLevel::Allow))
+        .collect()
+}
+
+/// A lint emited by the linter.
+#[derive(Debug, Clone, thiserror::Error)]
+pub struct Lint {
+    /// A span indicating where the diagnostic is in the source code.
+    pub span: Span,
+    /// The lint level: allow, warning, error.
+    pub level: LintLevel,
+    /// The message the user will see in the code editor.
+    pub message: &'static str,
+    /// The help text the user will see in the code editor.
+    pub help: &'static str,
+}
+
+impl std::fmt::Display for Lint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.message)
+    }
+}
+
+impl Diagnostic for Lint {
+    fn severity(&self) -> Option<miette::Severity> {
+        match self.level {
+            LintLevel::Allow => None,
+            LintLevel::Warn | LintLevel::ForceWarn => Some(miette::Severity::Warning),
+            LintLevel::Error | LintLevel::ForceError => Some(miette::Severity::Error),
+        }
+    }
+
+    fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
+        let source_span = miette::SourceSpan::from(self.span);
+        let labeled_span = LabeledSpan::new_with_span(Some(self.to_string()), source_span);
+        Some(Box::new(vec![labeled_span].into_iter()))
+    }
+
+    fn help<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        if self.help.is_empty() {
+            None
+        } else {
+            Some(Box::new(self.help))
+        }
+    }
+}
+
+/// A lint level. This defines if a lint will be treated as a warning or an error,
+/// and if the lint level can be overriden by the user.
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum LintLevel {
+    /// The lint is effectively disabled.
+    Allow,
+    /// The lint will be treated as a warning.
+    Warn,
+    /// The lint will be treated as a warning and cannot be overriden by the user.
+    ForceWarn,
+    /// The lint will be treated as an error.
+    Error,
+    /// The lint will be treated as an error and cannot be overriden by the user.
+    ForceError,
+}
+
+impl Display for LintLevel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let level = match self {
+            LintLevel::Allow => "",
+            LintLevel::Warn | LintLevel::ForceWarn => "warning",
+            LintLevel::Error | LintLevel::ForceError => "error",
+        };
+
+        write!(f, "{level}")
+    }
+}
+
+/// End-user configuration for each lint level.
+#[derive(Debug, Clone, Deserialize)]
+pub struct LintConfig {
+    #[serde(rename = "lint")]
+    /// Represents the lint name.
+    pub kind: LintKind,
+    /// The lint level.
+    pub level: LintLevel,
+}
+
+/// Represents a lint name.
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(untagged)]
+pub enum LintKind {
+    /// AST lint name.
+    Ast(AstLint),
+    /// HIR lint name.
+    Hir(HirLint),
+}