feat(linter): add avoid-as rule (#262)

DonIsaac · web-flow · commit 87e8d47ce1b2 · 2025-03-16T22:01:09.000-07:00
&gt; AI generated bc im feeling lazy

This pull request introduces a new linting rule to disallow the use of
`@as()` when types can be inferred, along with the necessary changes to
integrate this rule into the existing system.

### New Linting Rule:

* Added a new rule `avoid-as` that disallows the use of `@as()` when
types can be inferred. This rule is categorized as `pedantic` and is
enabled by default as a warning.
[[1]](diffhunk://#diff-eca5dc407c141ea5b0c0e57df9f7d5d859bb57158b92836db34c1cfa214aabe4R1-R42)
[[2]](diffhunk://#diff-f0b74904761a925e1f9e35ab917c5a2eaf91b7afeb7673e69a854fbd3b62b47eR1-R201)

### Integration of the New Rule:

* Updated `rules_config.zig` to include the new `avoid-as` rule in the
`RulesConfig` struct.
* Updated `rules.zig` to import the new `avoid_as.zig` file.

### Supporting Changes:

* Added a snapshot file `avoid-as.snap` for the new rule to provide
diagnostic messages and suggestions.
* Enhanced the `Span` and `LabeledSpan` structs in `span.zig` to include
conversion functions from various types, which are used in the new rule
implementation.
[[1]](diffhunk://#diff-35d3d2d0cf701ff9be24302e2c679f08f5f040b793d8a864702a1294fc0eaf20R64)
[[2]](diffhunk://#diff-35d3d2d0cf701ff9be24302e2c679f08f5f040b793d8a864702a1294fc0eaf20R152-R172)
diff --git a/docs/rules/avoid-as.md b/docs/rules/avoid-as.md
@@ -0,0 +1,42 @@
+# `avoid-as`
+
+> Category: pedantic
+>
+> Enabled by default?: Yes (warning)
+
+## What This Rule Does
+
+Disallows using `@as()` when types can be otherwise inferred.
+
+Zig has powerful [Result Location Semantics](https://ziglang.org/documentation/master/#Result-Location-Semantics) for inferring what type
+something should be. This happens in function parameters, return types,
+and type annotations. `@as()` is a last resort when no other contextual
+information is available. In any other case, other type inference mechanisms
+should be used.
+
+> [!NOTE]
+> Checks for function parameters and return types are not yet implemented.
+
+## Examples
+
+Examples of **incorrect** code for this rule:
+
+```zig
+const x = @as(u32, 1);
+
+fn foo(x: u32) u64 {
+  return @as(u64, x); // type is inferred from return type
+}
+foo(@as(u32, 1)); // type is inferred from function signature
+```
+
+Examples of **correct** code for this rule:
+
+```zig
+const x: u32 = 1;
+
+fn foo(x: u32) void {
+  // ...
+}
+foo(1);
+```
diff --git a/src/linter/config/rules_config.zig b/src/linter/config/rules_config.zig
@@ -15,4 +15,5 @@ pub const RulesConfig = struct {
     unused_decls: RuleConfig(rules.UnusedDecls) = .{},
     useless_error_return: RuleConfig(rules.UselessErrorReturn) = .{},
     empty_file: RuleConfig(rules.EmptyFile) = .{},
+    avoid_as: RuleConfig(rules.AvoidAs) = .{},
 };
diff --git a/src/linter/rules.zig b/src/linter/rules.zig
@@ -9,3 +9,4 @@ pub const UnsafeUndefined = @import("./rules/unsafe_undefined.zig");
 pub const UnusedDecls = @import("./rules/unused_decls.zig");
 pub const UselessErrorReturn = @import("./rules/useless_error_return.zig");
 pub const EmptyFile = @import("./rules/empty_file.zig");
+pub const AvoidAs = @import("./rules/avoid_as.zig");
diff --git a/src/linter/rules/avoid_as.zig b/src/linter/rules/avoid_as.zig
@@ -0,0 +1,219 @@
+//! ## What This Rule Does
+//!
+//! Disallows using `@as()` when types can be otherwise inferred.
+//!
+//! Zig has powerful [Result Location Semantics](https://ziglang.org/documentation/master/#Result-Location-Semantics) for inferring what type
+//! something should be. This happens in function parameters, return types,
+//! and type annotations. `@as()` is a last resort when no other contextual
+//! information is available. In any other case, other type inference mechanisms
+//! should be used.
+//!
+//! > [!NOTE]
+//! > Checks for function parameters and return types are not yet implemented.
+//!
+//! ## Examples
+//!
+//! Examples of **incorrect** code for this rule:
+//! ```zig
+//! const x = @as(u32, 1);
+//!
+//! fn foo(x: u32) u64 {
+//!   return @as(u64, x); // type is inferred from return type
+//! }
+//! foo(@as(u32, 1)); // type is inferred from function signature
+//! ```
+//!
+//! Examples of **correct** code for this rule:
+//! ```zig
+//! const x: u32 = 1;
+//!
+//! fn foo(x: u32) void {
+//!   // ...
+//! }
+//! foo(1);
+//! ```
+
+const std = @import("std");
+const util = @import("util");
+const semantic = @import("../../semantic.zig");
+const Semantic = semantic.Semantic;
+const _rule = @import("../rule.zig");
+const _span = @import("../../span.zig");
+
+const Ast = std.zig.Ast;
+const Node = Ast.Node;
+const LinterContext = @import("../lint_context.zig");
+const Rule = _rule.Rule;
+const NodeWrapper = _rule.NodeWrapper;
+const Fix = @import("../fix.zig").Fix;
+
+const Error = @import("../../Error.zig");
+const Cow = util.Cow(false);
+
+// Rule metadata
+const AvoidAs = @This();
+pub const meta: Rule.Meta = .{
+    .name = "avoid-as",
+    .category = .pedantic,
+    .default = .warning,
+    .fix = .safe_fix,
+};
+
+fn preferTypeAnnotationDiagnostic(ctx: *LinterContext, as_tok: Ast.TokenIndex) Error {
+    var e = ctx.diagnostic(
+        "Prefer using type annotations over @as().",
+        .{ctx.spanT(as_tok)},
+    );
+    e.help = Cow.static("Use a type annotation instead.");
+    return e;
+}
+
+fn lolTheresAlreadyATypeAnnotationDiagnostic(ctx: *LinterContext, as_tok: Ast.TokenIndex) Error {
+    var e = ctx.diagnostic(
+        "Unnecessary use of @as().",
+        .{ctx.spanT(as_tok)},
+    );
+    e.help = Cow.static("Remove the @as() call.");
+    return e;
+}
+
+// Runs on each node in the AST. Useful for syntax-based rules.
+pub fn runOnNode(_: *const AvoidAs, wrapper: NodeWrapper, ctx: *LinterContext) void {
+    const node = wrapper.node;
+    if (node.tag != .builtin_call_two and node.tag != .builtin_call_comma) {
+        return;
+    }
+
+    const builtin_name = ctx.semantic.tokenSlice(node.main_token);
+    if (!std.mem.eql(u8, builtin_name, "@as")) {
+        return;
+    }
+
+    const tags: []const Node.Tag = ctx.ast().nodes.items(.tag);
+    const datas: []const Node.Data = ctx.ast().nodes.items(.data);
+    const parent = ctx.links().getParent(wrapper.idx) orelse return;
+
+    switch (tags[parent]) {
+        .simple_var_decl => {
+            const data = datas[parent];
+            const ty_annotation = data.lhs;
+            const diagnostic = if (ty_annotation == Semantic.NULL_NODE)
+                preferTypeAnnotationDiagnostic(ctx, node.main_token)
+            else
+                lolTheresAlreadyATypeAnnotationDiagnostic(ctx, node.main_token);
+
+            ctx.reportWithFix(
+                VarFixer{ .var_decl = parent, .var_decl_data = data, .as_args = node.data },
+                diagnostic,
+                VarFixer.replaceWithTypeAnnotation,
+            );
+        },
+
+        else => {},
+    }
+}
+
+const VarFixer = struct {
+    /// this is a simple_var_decl node
+    var_decl: Ast.Node.Index,
+    var_decl_data: Node.Data,
+    /// `@as(lhs, rhs)`
+    as_args: Ast.Node.Data,
+
+    fn replaceWithTypeAnnotation(this: VarFixer, builder: Fix.Builder) !Fix {
+        // invalid, @as() has no args: `const x = @as();`
+        if (this.as_args.lhs == Semantic.NULL_NODE or this.as_args.rhs == Semantic.NULL_NODE) {
+            @branchHint(.unlikely);
+            return builder.noop();
+        }
+
+        const nodes = builder.ctx.ast().nodes;
+        const toks = builder.ctx.ast().tokens;
+        const tok_tags: []const Semantic.Token.Tag = toks.items(.tag);
+
+        const ty_annotation = this.var_decl_data.lhs;
+        if (ty_annotation == Semantic.NULL_NODE) {
+            // `const` or `var`
+            var tok = nodes.items(.main_token)[this.var_decl];
+            const is_const = tok_tags[tok] == .keyword_const;
+            tok += 1; // next tok is the identifier
+            util.debugAssert(tok_tags[tok] == .identifier, "Expected identifier, got {}", .{tok_tags[tok]});
+
+            const ident = builder.ctx.semantic.tokenSlice(tok);
+            const ty_text = builder.snippet(.node, this.as_args.lhs);
+            const expr_text = builder.snippet(.node, this.as_args.rhs);
+            return builder.replace(
+                builder.spanCovering(.node, this.var_decl),
+                try Cow.fmt(
+                    builder.allocator,
+                    "{s} {s}: {s} = {s}",
+                    .{
+                        if (is_const) "const" else "var",
+                        ident,
+                        ty_text,
+                        expr_text,
+                    },
+                ),
+            );
+        } else {
+            const expr = builder.snippet(.node, this.as_args.rhs);
+            return builder.replace(
+                builder.spanCovering(.node, this.var_decl_data.rhs),
+                Cow.initBorrowed(expr),
+            );
+        }
+    }
+};
+
+// Used by the Linter to register the rule so it can be run.
+pub fn rule(self: *AvoidAs) Rule {
+    return Rule.init(self);
+}
+
+const RuleTester = @import("../tester.zig");
+test AvoidAs {
+    const t = std.testing;
+
+    var avoid_as = AvoidAs{};
+    var runner = RuleTester.init(t.allocator, avoid_as.rule());
+    defer runner.deinit();
+
+    // Code your rule should pass on
+    const pass = &[_][:0]const u8{
+        // TODO: add test cases
+        "const x = 1;",
+        "const x: u32 = 1;",
+    };
+
+    // Code your rule should fail on
+    const fail = &[_][:0]const u8{
+        // TODO: add test cases
+        "const x = @as(u32, 1);",
+        "const x: u32 = @as(u32, 1);",
+    };
+
+    const fix = &[_]RuleTester.FixCase{
+        .{
+            .src = "const x = @as(u32, 1);",
+            .expected = "const x: u32 = 1;",
+        },
+        .{
+            .src = "var x = @as(u32, 1);",
+            .expected = "var x: u32 = 1;",
+        },
+        .{
+            .src = "const x: u32 = @as(u32, 1);",
+            .expected = "const x: u32 = 1;",
+        },
+        .{
+            .src = "var x: u32 = @as(u32, 1);",
+            .expected = "var x: u32 = 1;",
+        },
+    };
+
+    try runner
+        .withPass(pass)
+        .withFail(fail)
+        .withFix(fix)
+        .run();
+}
diff --git a/src/linter/rules/snapshots/avoid-as.snap b/src/linter/rules/snapshots/avoid-as.snap
@@ -0,0 +1,14 @@
+  𝙭 avoid-as: Prefer using type annotations over @as().
+   ╭─[avoid-as.zig:1:11]
+ 1 │ const x = @as(u32, 1);
+   ·           ───
+   ╰────
+  help: Use a type annotation instead.
+
+  𝙭 avoid-as: Unnecessary use of @as().
+   ╭─[avoid-as.zig:1:16]
+ 1 │ const x: u32 = @as(u32, 1);
+   ·                ───
+   ╰────
+  help: Remove the @as() call.
+
diff --git a/src/span.zig b/src/span.zig
@@ -61,6 +61,7 @@ pub const Span = struct {
     pub fn from(value: anytype) Span {
         return switch (@TypeOf(value)) {
             Span => value, // base case
+            LabeledSpan => value.span,
             std.zig.Ast.Span => .{ .start = value.start, .end = value.end },
             std.zig.Token.Loc => .{ .start = @intCast(value.start), .end = @intCast(value.end) },
             [2]u32 => .{ .start = value[0], .end = value[1] },
@@ -148,6 +149,27 @@ pub const LabeledSpan = struct {
             .span = .{ .start = start, .end = end },
         };
     }
+    pub fn from(value: anytype) LabeledSpan {
+        return switch (@TypeOf(value)) {
+            LabeledSpan => value, // base case
+            Span => .{ .span = value },
+            std.zig.Ast.Span => .{ .span = Span.from(value) },
+            std.zig.Token.Loc => .{ .span = Span.from(value) },
+            [2]u32 => .{ .span = Span.from(value) },
+            else => |T| {
+                const info = @typeInfo(T);
+                switch (info) {
+                    .@"struct", .@"enum" => {
+                        if (@hasField(T, "span")) {
+                            return LabeledSpan.from(@field(value, "span"));
+                        }
+                    },
+                    else => {},
+                }
+                @compileError("Cannot convert type " ++ @typeName(T) ++ "into a LabeledSpan.");
+            },
+        };
+    }
 };
 
 pub const Location = struct {
