lint 0.0.2-preview.1

Lint rules for Zena source, each with a fix

Readme Files Dependencies Versions

lint#

Lint rules for Zena source code, each with an automated fix. The compiler and type checker drive every rule, and when a fix is applied it is type-checked again before it is kept.

Usage#

Command Line#

zena lint [--fix] [--only a,b] [--skip a,b] <paths...>
zena lint --list-rules

A path is a .zena file or a directory, searched for them. Without --fix the command prints each finding as path:line:column: message [rule] and exits 1 when there is one; with --fix it rewrites the files. -v on the command lists every fix and the text of any rejected one.

The language server (zena lsp) publishes the findings as warnings and offers each as a quick fix, plus a source.fixAll.zena code action for the whole file.

Library API#

import { LintOptions, lintFile } from 'lint';
import { Project } from 'lint/checking';
import { allRules } from 'lint/rules';

let project = new Project();
let options = new LintOptions(allRules());
let report = await lintFile(project, 'src/main.zena', options);

Rules#

Rule Rewrite
function-declaration top-level let f = (…) => … → function f(…) { … }
unnecessary-cast x as T where x: T → x (from the checker's warning, less contextually typed operands)
unnecessary-optional-chain x?.f, x?[i], f?(…) on a non-nullable target → x.f, x[i], f(…)
unnecessary-annotation let x: T = e with e: T; return types the body implies; callback parameter types
collection-literal new Array<T>() + push runs → growable<T>([…]); new Map<K, V>() + []= → {k => v}
if-initializer var x = d; if (c) { x = a; } → let x = if (c) a else d
nullish if (x != null) x else d → x ?? d; if (x != null) x.f else null → x?.f
match-to-if one- and two-arm match → if, if (x is T), if (let P = x)
else-if else { if (…) { … } } → else if (…) { … }
for-in index loops that read only xs[i] → for (let x in xs)
boolean-return if (c) { return true; } return false; → return c;; if (c) true else false → c
template-literal three or more +-joined strings → a template literal
console-to-string console.log(`${x}`) and console.log(i32ToString(x)) → console.log(x)
arrow-body (x) => { return e; } → (x) => e
prefer-let var never assigned again → let
immutable-field var field nothing assigns → immutable field (#private, or the class is not exported)
empty-constructor new() {} on a class with no other constructor → removed; the default is synthesized

Libraries#

  • lint / lint/lint — lint driver (lintFile, lintSource, LintOptions, FileReport)
  • lint/checking — compiler project wrapper and overlay host (Project, CheckedFile)
  • lint/checked — checked module wrapper (CheckedFile)
  • lint/rules — rule registry (allRules, ruleNamed)
  • lint/rule — rule runner (NamedRule, proposeEdits, messageOf)
  • lint/context — rule traversal context (RuleContext)
  • lint/source — byte-range edits (Edit, applyEdits, columnOf)
  • lint/files — .zena file discovery (collectZenaFiles)

License#

MIT

11.9 KiB Raw
/**
 * Type annotations that say what the checker already knows.
 *
 * Three places:
 *
 * - `let x: T = e` where `e` has type `T` on its own: `let x = e`.
 * - `(a: i32): i32 => body` where every value the body returns has type
 *   `i32`: the return type goes. Not on exported top-level functions,
 *   whose signature is documentation, not on a function referenced
 *   before its declaration or by itself (the checker needs the
 *   signature then), and not on `async` or `gen` functions.
 * - A callback argument whose parameters repeat the types the callee
 *   expects: `xs.forEach((x: String): void => …)` becomes
 *   `xs.forEach((x) => …)`.
 *
 * An initializer whose type comes from the annotation — a literal, a
 * `new` with inferred type arguments, an arrow — keeps it.
 */

import {
  Node, Expression, VariableDeclaration, IdentifierPattern, FunctionExpression,
  FunctionDeclaration, BlockStatement, ReturnStatement, ExpressionStatement,
  CallExpression, Identifier, Parameter, NumberLiteral, BooleanLiteral,
  UnaryExpression,
} from 'compiler/ast';
import { walkEnter, walk } from 'compiler/visitor';
import { Symbol } from 'compiler/compiler';
import { Type, FunctionType, typeContainsTypeParameter, typeToString } from 'compiler/types';
import { RuleContext } from '../context.zena';
import { skipWhitespaceBack } from '../source.zena';

let COLON = 58;
let RIGHT_PAREN = 41;

export function unnecessaryAnnotations(ctx: RuleContext): void {
  walkEnter(ctx.ast, (n) => {
    match (n) {
      case VariableDeclaration {}: { localAnnotation(ctx, n); }
      case FunctionExpression {}: { returnAnnotation(ctx, n); }
      case CallExpression {}: { callbackAnnotations(ctx, n); }
      case _: {}
    }
  });
}

/** `let x: T = e` → `let x = e`. */
function localAnnotation(ctx: RuleContext, decl: VariableDeclaration): void {
  let annotation = decl.typeAnnotation;
  if (annotation == null || !(decl.pattern is IdentifierPattern)) {
    return;
  }
  let declared = ctx.bindingTypeOf(decl.pattern);
  if (declared == null) {
    return;
  }
  if (ctx.isContextuallyTyped(decl.init)) {
    // A literal takes the annotation's type, but when that is the type
    // it would have had anyway (`var n: i32 = 0`) the annotation says
    // nothing. Only for `var`: a `let` keeps a literal's literal type.
    if (decl.kind != 'var' || !isDefaultLiteralType(ctx, decl.init, declared)) {
      return;
    }
  } else if (!ctx.sameType(declared, ctx.typeOf(decl.init))) {
    return;
  }
  ctx.removeRange(ctx.end(decl.pattern), ctx.end(annotation));
}

/** Whether `declared` is what the literal `init` would be typed without context. */
function isDefaultLiteralType(ctx: RuleContext, init: Node, declared: Type): boolean {
  let name = typeToString(ctx.unwrap(declared));
  return match (init) {
    case NumberLiteral {raw}: if (raw.contains('.')) name == 'f64' else name == 'i32'
    case BooleanLiteral {}: name == 'boolean'
    case UnaryExpression {operator, argument}: {
      operator == '-' && argument is NumberLiteral && isDefaultLiteralType(ctx, argument, declared)
    }
    case _: false
  };
}

/** `(…): T => body` → `(…) => body` when the body says `T` already. */
function returnAnnotation(ctx: RuleContext, fe: FunctionExpression): void {
  let annotation = fe.returnType;
  if (annotation == null || fe.isAsync || fe.isGenerator) {
    return;
  }
  let parent = ctx.parent(fe);
  if (parent == null) {
    return;
  }
  // A top-level function keeps its signature when it is exported, used
  // before it is declared, or recursive.
  var declaredName: Node | null = null;
  match (parent) {
    case FunctionDeclaration {name, exported}: {
      if (exported) {
        return;
      }
      declaredName = name;
    }
    case VariableDeclaration {pattern, exported}: {
      if (exported && ctx.isTopLevel(parent)) {
        return;
      }
      if (pattern is IdentifierPattern) {
        declaredName = pattern;
      }
    }
    case _: {}
  }
  if (declaredName != null) {
    let sym = ctx.declaredSymbol(declaredName);
    if (sym != null && needsSignature(ctx, sym, fe)) {
      return;
    }
  }
  let ownType = ctx.typeOf(fe);
  if (ownType == null || !(ownType is FunctionType)) {
    return;
  }
  let declared = ownType.returnType;
  if (!bodyInfers(ctx, fe, declared)) {
    return;
  }
  removeReturnType(ctx, fe);
}

/** Whether a function's body alone gives it the return type `declared`. */
function bodyInfers(ctx: RuleContext, fe: FunctionExpression, declared: Type): boolean {
  let body = fe.body;
  if (body is Expression) {
    if (ctx.isContextuallyTyped(body)) {
      return false;
    }
    return ctx.sameType(ctx.typeOf(body), declared);
  }
  let block = body;
  // Without an annotation a trailing expression is a statement, not the
  // value, so a value block needs its annotation to stay a value.
  if (block.body.length > 0 && !ctx.isVoid(declared) &&
      block.body[block.body.length - 1] is ExpressionStatement) {
    return false;
  }
  let returns = ownReturns(fe);
  if (returns.length == 0) {
    return ctx.isVoid(declared);
  }
  for (let ret in returns) {
    let argument = ret.argument;
    if (argument == null) {
      if (!ctx.isVoid(declared)) {
        return false;
      }
      continue;
    }
    if (ctx.isContextuallyTyped(argument)) {
      return false;
    }
    if (!ctx.sameType(ctx.typeOf(argument), declared)) {
      return false;
    }
  }
  return true;
}

/** The return statements of `fe`'s body, not counting nested functions'. */
function ownReturns(fe: FunctionExpression): GrowableArray<ReturnStatement> {
  let out = new Array<ReturnStatement>();
  walk(fe.body, (n) => {
    if (n is FunctionExpression) {
      return false;
    }
    if (n is ReturnStatement) {
      out.push(n);
    }
    return true;
  }, (n) => {});
  return out;
}

/**
 * Whether `sym`, bound to `fe`, is referenced before `fe` in the file
 * or from inside `fe`: either way the checker reads the signature before
 * it has checked the body.
 */
function needsSignature(ctx: RuleContext, sym: Symbol, fe: FunctionExpression): boolean {
  let start = ctx.start(fe);
  let end = ctx.end(fe);
  var needed = false;
  let model = ctx.model;
  walkEnter(ctx.ast, (n) => {
    if (needed || !(n is Identifier)) {
      return;
    }
    let s = model.resolve(n);
    if (s == null || (s.id as i32) != (sym.id as i32)) {
      return;
    }
    let at = ctx.start(n);
    if (at < start || (at >= start && at < end)) {
      needed = true;
    }
  });
  return needed;
}

/** Deletes `: T` between the parameter list and the arrow or body. */
function removeReturnType(ctx: RuleContext, fe: FunctionExpression): void {
  let annotation = fe.returnType;
  if (annotation == null) {
    return;
  }
  let colon = skipWhitespaceBack(ctx.source, ctx.start(annotation));
  if (colon < 0 || ctx.source.getByteAt(colon) != COLON) {
    return;
  }
  let paren = skipWhitespaceBack(ctx.source, colon);
  if (paren < 0 || ctx.source.getByteAt(paren) != RIGHT_PAREN) {
    return;
  }
  ctx.removeRange(paren + 1, ctx.end(annotation));
}

function describeType(t: Type | null) {
  return if (t != null) typeToString(t) else '<none>';
}

/** Parameter annotations on a callback that repeat the callee's expectation. */
function callbackAnnotations(ctx: RuleContext, call: CallExpression): void {
  var calleeType = ctx.model.getResolvedOverload(call);
  if (calleeType == null) {
    let t = ctx.typeOf(call.callee);
    if (t == null) {
      return;
    }
    let u = ctx.unwrap(t);
    if (!(u is FunctionType)) {
      return;
    }
    calleeType = u;
  }
  let ft = calleeType;
  // An overloaded callee is chosen by the argument types, which the
  // annotations are.
  if (isOverloaded(ft) || isOverloaded(ctx.typeOf(call.callee))) {
    return;
  }
  // The signature as declared: a method-level type parameter that the
  // callback's annotations are what pins down still shows there, where
  // the resolved signature has it filled in already.
  let generic = ft.genericSource ?? ft;
  var i = 0;
  while (i < call.args.length && i < ft.parameters.length) {
    let arg = call.args[i];
    let expected = functionTypeOf(ctx, ft.parameters[i]);
    if (arg is FunctionExpression && expected != null &&
        !inferredFromArgument(generic, i)) {
      stripCallbackParams(ctx, arg, expected);
    }
    i += 1;
  }
}

/** Whether the type is a function with other overloads. */
function isOverloaded(t: Type | null): boolean {
  if (t == null || !(t is FunctionType)) {
    return false;
  }
  let ft = t;
  let overloads = (ft.genericSource ?? ft).overloads;
  return overloads != null && overloads.length > 0;
}

/**
 * Whether parameter `i` of the declared signature mentions one of the
 * function's own type parameters, so that an argument's annotations may
 * be what the checker infers it from.
 */
function inferredFromArgument(generic: FunctionType, i: i32): boolean {
  let typeParameters = generic.typeParameters;
  if (typeParameters == null || typeParameters.length == 0 || i >= generic.parameters.length) {
    return false;
  }
  // Only the callback's own parameter types count: a type parameter in
  // its return position (`map<U>(f: (item: T) => U)`) is inferred from
  // the body, which the annotations do not touch.
  let declared = generic.parameters[i];
  var text = typeToString(declared);
  if (declared is FunctionType) {
    text = '';
    for (let p in declared.parameters) {
      text = `${text} ${typeToString(p)}`;
    }
  }
  for (let tp in typeParameters) {
    if (mentionsName(text, typeToString(tp))) {
      return true;
    }
  }
  return false;
}

/** Whether `name` occurs in `text` as a whole identifier. */
function mentionsName(text: String, name: String): boolean {
  var i = 0;
  while (i + name.length <= text.length) {
    if (name.regionEqualsBytes(text, i, i + name.length) &&
        (i == 0 || !isIdentifierByte(text.getByteAt(i - 1))) &&
        (i + name.length == text.length || !isIdentifierByte(text.getByteAt(i + name.length)))) {
      return true;
    }
    i += 1;
  }
  return false;
}

function isIdentifierByte(b: i32): boolean {
  return (b >= 48 && b <= 57) || (b >= 65 && b <= 90) || (b >= 97 && b <= 122) || b == 95 || b == 36;
}

/**
 * `t` as a function type, looking through aliases. A nullable function
 * type is not one: the checker does not type a callback's parameters
 * from an optional parameter's type.
 */
function functionTypeOf(ctx: RuleContext, t: Type): FunctionType | null {
  let u = ctx.unwrap(t);
  if (u is FunctionType) {
    return u;
  }
  return null;
}

function stripCallbackParams(ctx: RuleContext, fe: FunctionExpression, expected: FunctionType): void {
  if (fe.typeParameters != null) {
    return;
  }
  // A type parameter still open in the expectation would be inferred
  // from the annotation this would remove.
  if (typeContainsTypeParameter(expected)) {
    return;
  }
  var i = 0;
  while (i < fe.params.length && i < expected.parameters.length) {
    let param = fe.params[i];
    let annotation = param.typeAnnotation;
    if (annotation != null && param.pattern == null && !param.optional &&
        param.defaultValue == null && !param.isThisParam) {
      let declared = ctx.bindingTypeOf(param);
      if (ctx.sameType(declared, expected.parameters[i])) {
        ctx.removeRange(ctx.end(param.name), ctx.end(annotation));
      } else if (ctx.debug) {
        console.log(`callback param ${param.name.name}: declared ${describeType(declared)} expected ${describeType(expected.parameters[i])}`);
      }
    }
    i += 1;
  }
  // The return type too, when the callee expects what the body gives.
  // Both are needed: `(e: Error): void => log(e)` with `log` returning
  // `i32` is a `=> void` only because of the annotation.
  let returnType = fe.returnType;
  if (returnType != null && !fe.isAsync && !fe.isGenerator) {
    let ownType = ctx.typeOf(fe);
    if (ownType != null && ownType is FunctionType) {
      let declared = ownType.returnType;
      if (ctx.sameType(declared, expected.returnType) && bodyInfers(ctx, fe, declared)) {
        removeReturnType(ctx, fe);
      }
    }
  }
}
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1