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

9.2 KiB Raw
/**
 * The driver: checks a file, runs the rules, and either reports what
 * they found or applies it.
 *
 * Reporting is one pass: every rule's proposals on the file as it is,
 * less the ones that overlap an earlier one. Fixing applies them and
 * checks the result before keeping it. A rule is written to preserve
 * meaning, and the check after the rewrite is the net under it: a rewrite
 * the checker rejects is never written. When a pass's edits fail
 * together, the driver bisects them — each half alone, then smaller —
 * until the edits that cause the errors are found and set aside, and
 * reports them with the checker's message so the rule can be fixed.
 * Passes repeat until no rule has anything to say, since one rewrite
 * often enables another (`var` + `if` becomes `let x = if …`, which
 * becomes `x ?? y`).
 */

import { writeFile } from 'zena:fs';
import { Set } from 'zena:collections';
import { Project, CheckedFile } from './checking.zena';
import { NamedRule, proposeEdits, runRules } from './rule.zena';
import { Edit, disjointEdits, applyEdits, groupEdits, flattenGroups } from './source.zena';

export { NamedRule, proposeEdits, runRules, messageOf } from './rule.zena';

export final class LintOptions {
  /** Apply the fixes and write the file; otherwise report the findings. */
  var fix = false;
  /** Print every edit, not just the summary. */
  var verbose = false;
  /** Passes before giving up on a file that keeps changing. */
  var maxPasses = 8;
  rules: GrowableArray<NamedRule>;

  new(this.rules);
}

/** A rewrite (one group of edits) the checker rejected, with the first error it caused. */
export final class RejectedEdit(edits: GrowableArray<Edit>, error: String) {
  /** The edit to report the rejection at. */
  edit: Edit {
    get { return this.edits[0]; }
  }
}

export final class FileReport {
  path: String;
  /** What the rules found on the file as it is, when reporting. */
  findings = new Array<Edit>();
  /** Edits applied, across every pass, when fixing. */
  applied = new Array<Edit>();
  rejected = new Array<RejectedEdit>();
  /** The file did not check before anything was done; nothing was. */
  errorsBefore = new Array<String>();
  /** The file could not be compiled at all. */
  var failure: String | null = null;
  var passes = 0;
  var changed = false;
  /** The file's text after every pass; the original when nothing changed. */
  var result: String | null = null;

  new(this.path);
}

/**
 * Lints one file: reports its findings, or with `options.fix` rewrites it
 * in place.
 */
export async function lintFile(project: Project, path: String, options: LintOptions, write: boolean = true): Future<FileReport> {
  let report = new FileReport(path);
  let checked = await initialCheck(project, path, report);
  if (checked == null) {
    project.reset();
    return report;
  }
  let before = checked.errors();
  if (before.length > 0) {
    for (let error in before) {
      report.errorsBefore.push(error);
    }
    project.reset();
    return report;
  }
  if (!options.fix) {
    report.passes = 1;
    for (let edit in proposeEdits(checked, options.rules)) {
      if (!edit.shared) {
        report.findings.push(edit);
      }
    }
    report.result = checked.source;
    project.reset();
    return report;
  }

  var source = checked.source;
  var current = checked;
  // What the checker has already rejected, so a rule proposing it again
  // on the next pass does not cost another check or shadow its neighbours.
  let rejected = new Set<String>();
  while (report.passes < options.maxPasses) {
    report.passes += 1;
    // Supporting edits (an import a fix needs) go with every attempt and
    // are kept when any fix is; the rest are the fixes to settle.
    let proposed = new Array<Edit>();
    let shared = new Array<Edit>();
    for (let edit in runRules(current, options.rules)) {
      if (edit.shared) {
        shared.push(edit);
      } else if (!rejected.has(editKey(edit, source))) {
        proposed.push(edit);
      }
    }
    if (proposed.length == 0) {
      break;
    }
    // An edit the checker rejects may have been shadowing others that
    // overlap it; once it is out of the way they get their turn.
    var accepted = new Array<Edit>(0);
    var remaining = proposed;
    while (remaining.length > 0) {
      let candidates = groupEdits(disjointEdits(remaining));
      let before = report.rejected.length;
      accepted = flattenGroups(await settle(project, path, source, candidates, shared, report));
      if (report.rejected.length == before) {
        break;
      }
      var k = before;
      while (k < report.rejected.length) {
        for (let edit in report.rejected[k].edits) {
          rejected.add(editKey(edit, source));
        }
        k += 1;
      }
      let next = new Array<Edit>(remaining.length);
      for (let edit in remaining) {
        if (!rejected.has(editKey(edit, source))) {
          next.push(edit);
        }
      }
      remaining = next;
    }
    if (accepted.length == 0) {
      break;
    }
    for (let edit in shared) {
      accepted.push(edit);
    }
    source = applyEdits(source, disjointEdits(accepted));
    for (let edit in accepted) {
      if (!edit.shared) {
        report.applied.push(edit);
      }
    }
    report.changed = true;
    await project.override(path, source);
    current = await project.check(path);
    if (current.hasErrors()) {
      // `settle` checked this exact text; a difference here is a bug.
      throw new Error(`${path}: the accepted rewrite does not check: ${current.errors()[0]}`);
    }
  }

  report.result = source;
  if (report.changed && write) {
    await writeFile(path, source);
  }
  project.reset();
  return report;
}

/**
 * Lints source text that is not (or not yet) on disk, as if it were the
 * file at `path`: relative imports resolve from there. Nothing is
 * written; with `options.fix` the result is on the report.
 */
export async function lintSource(project: Project, path: String, source: String, options: LintOptions): Future<FileReport> {
  await project.override(path, source);
  return await lintFile(project, path, options, false);
}

/**
 * An edit's identity across passes: the rule, the text it replaces and
 * what it writes. Offsets would not do — every accepted edit above a
 * site moves it.
 */
function editKey(edit: Edit, source: String): String {
  return `${edit.rule}:${source.sliceBytes(edit.start, edit.end)}->${edit.replacement}`;
}

/** The file as it is on disk, checked; null (recorded on the report) when it cannot be. */
async function initialCheck(project: Project, path: String, report: FileReport): Future<CheckedFile | null> {
  try {
    return await project.check(path);
  } catch (e) {
    report.failure = e.message;
    return null;
  }
}

/**
 * The subset of `groups` (of disjoint edits) that checks when applied
 * together. The whole set first — the common case — then halves,
 * recursively, and finally one by one onto what has been accepted so
 * far, so that a pair of rewrites that each check alone but not together
 * is caught too.
 */
async function settle(
  project: Project,
  path: String,
  source: String,
  groups: GrowableArray<GrowableArray<Edit>>,
  shared: GrowableArray<Edit>,
  report: FileReport
): Future<GrowableArray<GrowableArray<Edit>>> {
  let failure = await tryGroups(project, path, source, groups, shared);
  if (failure == null) {
    return groups;
  }
  if (groups.length == 1) {
    report.rejected.push(new RejectedEdit(groups[0], failure));
    return new Array<GrowableArray<Edit>>(0);
  }
  let mid = groups.length - (groups.length >> 1);
  let left = await settle(project, path, source, groups.slice(0, mid), shared, report);
  let right = await settle(project, path, source, groups.slice(mid, groups.length), shared, report);
  let combined = new Array<GrowableArray<Edit>>(left.length + right.length);
  for (let g in left) {
    combined.push(g);
  }
  for (let g in right) {
    combined.push(g);
  }
  if (combined.length == 0 || (await tryGroups(project, path, source, combined, shared)) == null) {
    return combined;
  }
  // Each half checks alone and not together: add one at a time.
  let accepted = new Array<GrowableArray<Edit>>(combined.length);
  for (let g in combined) {
    let attempt = new Array<GrowableArray<Edit>>(accepted.length + 1);
    for (let a in accepted) {
      attempt.push(a);
    }
    attempt.push(g);
    let error = await tryGroups(project, path, source, attempt, shared);
    if (error == null) {
      accepted.push(g);
    } else {
      report.rejected.push(new RejectedEdit(g, error));
    }
  }
  return accepted;
}

/**
 * Null when `source` with the groups' edits (and the shared ones) applied
 * checks, else the first error.
 */
async function tryGroups(project: Project, path: String, source: String,
    groups: GrowableArray<GrowableArray<Edit>>, shared: GrowableArray<Edit>): Future<String | null> {
  let edits = flattenGroups(groups);
  for (let edit in shared) {
    edits.push(edit);
  }
  let text = applyEdits(source, disjointEdits(edits));
  try {
    // Setting the override re-reads the file, so a parse error lands here.
    await project.override(path, text);
    let checked = await project.check(path);
    let errors = checked.errors();
    if (errors.length == 0) {
      return null;
    }
    return errors[0];
  } catch (e) {
    return e.message;
  }
}
  • 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