Baseline: tree as shared
This commit is contained in:
commit
659c03bbf8
1471 files changed
+990535
No files matched your search
@@ -0,0 +1,661 @@
|
||||
/**
|
||||
* The best-practices helper (restructure plan, section 2.6): the gap between the literal Mojo the translator writes
|
||||
* and the Mojo a person would write, as things to learn from. DOM-free, and never imported by the translator (a
|
||||
* grep gate keeps it so): the Bridge's Mojo stays the literal translation whether the helper is on or off.
|
||||
*
|
||||
* A rule reads the parsed module and the source and returns findings. A finding says where, why, shows a before
|
||||
* and an after, links the manual, and carries a one-click fix only when the rewrite is safe: it is verified by the
|
||||
* tests to pass the checker and to print what the original printed. A rule that cannot promise that explains and
|
||||
* leaves the editing to the student.
|
||||
*/
|
||||
import type { QuickFix, Diagnostic } from '../core/types.js';
|
||||
import { parseModule, type Expr, type Module, type Stmt } from './parse.js';
|
||||
import { checkMojo } from './check.js';
|
||||
import { MOJO_PRELUDE_RAISES } from './generated/stdlib.js';
|
||||
|
||||
const MANUAL = 'https://mojolang.org/docs/manual';
|
||||
|
||||
export const PRACTICES_ORIGIN = 'best practices';
|
||||
|
||||
export interface PracticeFinding {
|
||||
rule: string;
|
||||
/** The first Mojo line it is about (1-based). */
|
||||
line: number;
|
||||
/** The last line, when it spans several. */
|
||||
endLine?: number;
|
||||
/** The reason, in a sentence or two. */
|
||||
message: string;
|
||||
before: string;
|
||||
after: string;
|
||||
docUrl: string;
|
||||
/** One click, when the rewrite is safe. It replaces whole lines. */
|
||||
fix?: QuickFix;
|
||||
/** In the Bridge: how to write the pseudo or lingo so the translator writes the better form, where that is true. */
|
||||
pseudoHint?: string;
|
||||
}
|
||||
|
||||
export interface PracticeRule {
|
||||
id: string;
|
||||
title: string;
|
||||
why: string;
|
||||
docUrl: string;
|
||||
/** A whole program in the literal form, and the same program as the rule would have it. Both run, and print the same. */
|
||||
example: { before: string; after: string; /** The compiler refuses the "before" with this message (the rule is about something it forbids); the "after" must pass. */ beforeRefused?: string };
|
||||
/** Standard-library methods the rewrite names, as [type, method]: each is checked against the harvested index. */
|
||||
apis: Array<[string, string]>;
|
||||
detect(mod: Module, source: string): PracticeFinding[];
|
||||
}
|
||||
|
||||
/* ---------- reading the tree ---------- */
|
||||
|
||||
type Node = { [key: string]: unknown };
|
||||
const STMT_KINDS = new Set(['expr', 'var', 'assign', 'aug', 'if', 'while', 'for', 'break', 'continue', 'pass', 'return', 'raise', 'try', 'with', 'assert', 'def', 'struct', 'trait', 'import', 'from', 'global', 'unread']);
|
||||
const isNode = (x: unknown): x is Node => typeof x === 'object' && x !== null && typeof (x as Node).k === 'string';
|
||||
const isStmt = (x: unknown): x is Stmt => isNode(x) && STMT_KINDS.has(x.k as string);
|
||||
|
||||
function walk(x: unknown, fn: (n: Node) => void): void {
|
||||
if (Array.isArray(x)) { for (const y of x) walk(y, fn); return; }
|
||||
if (typeof x !== 'object' || x === null) return;
|
||||
if (isNode(x)) fn(x);
|
||||
for (const v of Object.values(x)) if (typeof v === 'object' && v !== null) walk(v, fn);
|
||||
}
|
||||
const mentions = (x: unknown, id: string): boolean => { let hit = false; walk(x, (n) => { if (n.k === 'name' && n.id === id) hit = true; }); return hit; };
|
||||
const countMentions = (x: unknown, id: string): number => { let c = 0; walk(x, (n) => { if (n.k === 'name' && n.id === id) c++; }); return c; };
|
||||
|
||||
/** Every statement list in the module: the module's own, and each body inside it. */
|
||||
function blocksOf(mod: Module): Stmt[][] {
|
||||
const out: Stmt[][] = [];
|
||||
const visit = (x: unknown): void => {
|
||||
if (Array.isArray(x)) {
|
||||
if (x.length && x.every(isStmt)) out.push(x as Stmt[]);
|
||||
for (const y of x) visit(y);
|
||||
return;
|
||||
}
|
||||
if (typeof x !== 'object' || x === null) return;
|
||||
for (const v of Object.values(x)) if (typeof v === 'object' && v !== null) visit(v);
|
||||
};
|
||||
out.push(mod.body);
|
||||
visit(mod.body);
|
||||
return out;
|
||||
}
|
||||
|
||||
/** The def that contains a statement, with its nearest enclosing block. */
|
||||
function defsOf(mod: Module): Array<Extract<Stmt, { k: 'def' }>> {
|
||||
const out: Array<Extract<Stmt, { k: 'def' }>> = [];
|
||||
walk(mod.body, (n) => { if (n.k === 'def') out.push(n as unknown as Extract<Stmt, { k: 'def' }>); });
|
||||
return out;
|
||||
}
|
||||
|
||||
const lines = (source: string): string[] => source.split('\n');
|
||||
const indentOf = (l: string): string => /^\s*/.exec(l)![0];
|
||||
const balanced = (l: string): boolean => {
|
||||
let d = 0, q: string | null = null;
|
||||
for (let i = 0; i < l.length; i++) {
|
||||
const c = l[i];
|
||||
if (q) { if (c === '\\') i++; else if (c === q) q = null; }
|
||||
else if (c === '"' || c === "'") q = c;
|
||||
else if (c === '#') break;
|
||||
else if ('([{'.includes(c)) d++;
|
||||
else if (')]}'.includes(c)) d--;
|
||||
}
|
||||
return d === 0 && !q;
|
||||
};
|
||||
const stripComment = (l: string): string => {
|
||||
let q: string | null = null;
|
||||
for (let i = 0; i < l.length; i++) { const c = l[i]; if (q) { if (c === '\\') i++; else if (c === q) q = null; } else if (c === '"' || c === "'") q = c; else if (c === '#') return l.slice(0, i).trimEnd(); }
|
||||
return l;
|
||||
};
|
||||
const lastLineOf = (x: unknown): number => { let m = 0; walk(x, (n) => { const p = n.pos as { line?: number } | undefined; if (p?.line && p.line > m) m = p.line; }); return m; };
|
||||
const wholeLines = (line: number, endLine: number, text: string): QuickFix => ({ label: '', line, endLine, col: 1, endCol: null, text });
|
||||
const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
|
||||
/* ---------- 1. declare, then assign ---------- */
|
||||
|
||||
const declareThenAssign: PracticeRule = {
|
||||
id: 'declare-then-assign',
|
||||
title: 'Declare and set a variable in one line',
|
||||
why: 'Mojo lets `var n = …` declare a variable and give it its first value together, and the type follows from the value. Declaring first and assigning later leaves a stretch where the name exists but holds nothing.',
|
||||
docUrl: `${MANUAL}/variables/`,
|
||||
example: {
|
||||
before: 'def main():\n var n: Int\n n = 5\n print(n)\n',
|
||||
after: 'def main():\n var n = 5\n print(n)\n',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
for (const block of blocksOf(mod)) {
|
||||
block.forEach((d, i) => {
|
||||
if (d.k !== 'var' || d.comptime || d.ref || d.value || d.targets.k !== 'name') return;
|
||||
const id = d.targets.id;
|
||||
for (let j = i + 1; j < block.length; j++) {
|
||||
const t = block[j];
|
||||
if (!mentions(t, id)) continue;
|
||||
if (t.k === 'assign' && t.targets.length === 1 && t.targets[0].k === 'name' && t.targets[0].id === id && !mentions(t.value, id)) {
|
||||
const dl = src[d.pos.line - 1] ?? '', al = src[t.pos.line - 1] ?? '';
|
||||
const dm = new RegExp(`^(\\s*)var\\s+${escapeRe(id)}\\s*(?::\\s*(.+?))?\\s*(#.*)?$`).exec(dl);
|
||||
const am = new RegExp(`^(\\s*)${escapeRe(id)}\\s*=\\s*(.+?)\\s*$`).exec(al);
|
||||
if (!dm || !am || !balanced(al) || (d.type && !dm[2])) return;
|
||||
const ty = d.type ? dm[2] : null;
|
||||
const v = t.value;
|
||||
const inferable = !ty || (ty === 'Int' && ((v.k === 'num' && !v.float) || (v.k === 'call' && ((v.fn.k === 'attr' && v.fn.name === 'count_codepoints') || (v.fn.k === 'name' && v.fn.id === 'len')))))
|
||||
|| (ty === 'Float64' && v.k === 'num' && v.float) || (ty === 'String' && v.k === 'str' && !v.t) || (ty === 'Bool' && v.k === 'name' && (v.id === 'True' || v.id === 'False'));
|
||||
const rhs = stripComment(am[2]);
|
||||
const nl = `${am[1]}var ${id}${ty && !inferable ? `: ${ty}` : ''} = ${rhs}`;
|
||||
const between = src.slice(d.pos.line, t.pos.line - 1);
|
||||
const text = [...between, nl].join('\n');
|
||||
out.push({
|
||||
rule: 'declare-then-assign', line: d.pos.line, endLine: t.pos.line,
|
||||
message: `\`${id}\` is declared on line ${d.pos.line} and first given a value on line ${t.pos.line}. Write \`var ${id} = …\` where it gets its value.`,
|
||||
before: `${dl.trim()}\n${al.trim()}`, after: nl.trim(),
|
||||
docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(d.pos.line, t.pos.line, text), label: `Declare ${id} where it is set` },
|
||||
});
|
||||
}
|
||||
return;
|
||||
}
|
||||
});
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 2. x = x + 1 -> x += 1 ---------- */
|
||||
|
||||
const augmentedAssign: PracticeRule = {
|
||||
id: 'augmented-assign',
|
||||
title: 'Use += for a running total',
|
||||
why: '`x += 1` says "change x by 1" in one step and names `x` once, so there is no way to mistype the second one. It is the same operation as `x = x + 1`.',
|
||||
docUrl: `${MANUAL}/operators/`,
|
||||
example: {
|
||||
before: 'def main():\n var total = 0\n for i in range(4):\n total = total + i\n print(total)\n',
|
||||
after: 'def main():\n var total = 0\n for i in range(4):\n total += i\n print(total)\n',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
walk(mod.body, (n) => {
|
||||
const s = n as unknown as Stmt;
|
||||
if (s.k !== 'assign' || s.targets.length !== 1 || s.targets[0].k !== 'name') return;
|
||||
const v = s.value;
|
||||
if (v.k !== 'binary' || !['+', '-', '*'].includes(v.op) || v.l.k !== 'name' || v.l.id !== s.targets[0].id) return;
|
||||
const id = s.targets[0].id;
|
||||
const l = src[s.pos.line - 1] ?? '';
|
||||
const m = new RegExp(`^(\\s*)${escapeRe(id)}\\s*=\\s*${escapeRe(id)}\\s*\\${v.op}\\s*(.+?)\\s*$`).exec(l);
|
||||
if (!m || !balanced(l)) return;
|
||||
const nl = `${m[1]}${id} ${v.op}= ${stripComment(m[2])}`;
|
||||
out.push({
|
||||
rule: 'augmented-assign', line: s.pos.line,
|
||||
message: `\`${id} = ${id} ${v.op} …\` can be \`${id} ${v.op}= …\`.`,
|
||||
before: l.trim(), after: nl.trim(), docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(s.pos.line, s.pos.line, nl), label: `Write ${id} ${v.op}= …` },
|
||||
});
|
||||
});
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 3. an index loop that only reads codepoints ---------- */
|
||||
|
||||
const codepointLoop: PracticeRule = {
|
||||
id: 'codepoint-loop',
|
||||
title: 'Loop over the letters, not their positions',
|
||||
why: 'When the loop index is only used to read one letter of a string, `for cp in text.codepoint_slices()` gives the letters directly. There is no count to keep in step with the string and no index to get wrong.',
|
||||
docUrl: `${MANUAL}/control-flow/`,
|
||||
example: {
|
||||
before: 'def count_a(t: String) -> Int:\n var n = t.count_codepoints()\n var total = 0\n for i in range(n):\n if String(t[codepoint=i]) == "A":\n total += 1\n return total\n\n\ndef main():\n print(count_a("GATTACA"))\n',
|
||||
after: 'def count_a(t: String) -> Int:\n var n = t.count_codepoints()\n var total = 0\n for cp in t.codepoint_slices():\n if String(cp) == "A":\n total += 1\n return total\n\n\ndef main():\n print(count_a("GATTACA"))\n',
|
||||
},
|
||||
apis: [['String', 'codepoint_slices'], ['String', 'count_codepoints']],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
const taken = new Set<string>();
|
||||
walk(mod.body, (n) => { if (n.k === 'name') taken.add(n.id as string); });
|
||||
for (const d of defsOf(mod)) {
|
||||
// names set to `X.count_codepoints()` in this function, and never to anything else
|
||||
const counts = new Map<string, string>();
|
||||
const other = new Set<string>();
|
||||
walk(d.body, (n) => {
|
||||
const s = n as unknown as Stmt;
|
||||
const tgt = s.k === 'var' && s.value ? s.targets : s.k === 'assign' && s.targets.length === 1 ? s.targets[0] : null;
|
||||
const val = s.k === 'var' ? s.value : s.k === 'assign' ? s.value : null;
|
||||
if (!tgt || tgt.k !== 'name' || !val) return;
|
||||
if (val.k === 'call' && val.fn.k === 'attr' && val.fn.name === 'count_codepoints' && val.args.length === 0 && val.fn.obj.k === 'name') {
|
||||
if (counts.has(tgt.id) && counts.get(tgt.id) !== val.fn.obj.id) other.add(tgt.id);
|
||||
counts.set(tgt.id, val.fn.obj.id);
|
||||
} else other.add(tgt.id);
|
||||
});
|
||||
walk(d.body, (n) => {
|
||||
const f = n as unknown as Stmt;
|
||||
if (f.k !== 'for' || f.comptime || f.orelse.length || f.target.k !== 'name') return;
|
||||
const it = f.iter;
|
||||
if (it.k !== 'call' || it.fn.k !== 'name' || it.fn.id !== 'range' || it.args.length !== 1 || it.args[0].name) return;
|
||||
const a = it.args[0].value;
|
||||
let text: string | null = null;
|
||||
if (a.k === 'call' && a.fn.k === 'attr' && a.fn.name === 'count_codepoints' && a.fn.obj.k === 'name') text = a.fn.obj.id;
|
||||
else if (a.k === 'name' && counts.has(a.id) && !other.has(a.id) && !mentions(f.body, a.id)) text = counts.get(a.id)!;
|
||||
if (!text) return;
|
||||
const i = f.target.id, X = text;
|
||||
// every use of the index is `X[codepoint=i]`, inside String(…)
|
||||
let uses = 0, ok = true;
|
||||
const asIndex = (e: Expr): boolean => e.k === 'index' && e.obj.k === 'name' && e.obj.id === X && e.args.length === 1 && e.args[0].name === 'codepoint' && e.args[0].value.k === 'name' && e.args[0].value.id === i;
|
||||
walk(f.body, (m) => {
|
||||
if (m.k === 'call') {
|
||||
const c = m as unknown as Extract<Expr, { k: 'call' }>;
|
||||
if (c.fn.k === 'name' && c.fn.id === 'String' && c.args.length === 1 && !c.args[0].name && asIndex(c.args[0].value)) uses++;
|
||||
}
|
||||
});
|
||||
const idx = countMentions(f.body, i);
|
||||
if (uses === 0 || idx !== uses) ok = false;
|
||||
// the string must not be reassigned inside the loop
|
||||
let reassigned = false;
|
||||
walk(f.body, (m) => { const s = m as unknown as Stmt; if ((s.k === 'assign' && s.targets.some((t) => mentions(t, X))) || (s.k === 'aug' && mentions(s.target, X))) reassigned = true; });
|
||||
if (!ok || reassigned) return;
|
||||
let cp = 'cp'; for (let k = 2; taken.has(cp); k++) cp = `cp${k}`;
|
||||
const re = new RegExp(`String\\(\\s*${escapeRe(X)}\\[\\s*codepoint\\s*=\\s*${escapeRe(i)}\\s*\\]\\s*\\)`, 'g');
|
||||
const first = f.pos.line, last = lastLineOf(f.body);
|
||||
const body = src.slice(first, last).map((l) => l.replace(re, `String(${cp})`));
|
||||
const hit = src.slice(first, last).reduce((c, l) => c + (l.match(re)?.length ?? 0), 0);
|
||||
if (hit !== uses) return; // a use the line text does not show plainly: leave it alone
|
||||
const head = src[first - 1] ?? '';
|
||||
const hm = new RegExp(`^(\\s*)for\\s+${escapeRe(i)}\\s+in\\s+range\\(.*\\)\\s*:\\s*$`).exec(head);
|
||||
if (!hm) return;
|
||||
const nh = `${hm[1]}for ${cp} in ${X}.codepoint_slices():`;
|
||||
const lastUse = body.reduce((m, l, k) => (l.includes(`String(${cp})`) ? k : m), 0);
|
||||
const text2 = [nh, ...body.slice(0, lastUse + 1)].join('\n');
|
||||
out.push({
|
||||
rule: 'codepoint-loop', line: first, endLine: first + lastUse + 1,
|
||||
message: `\`${i}\` is only used to read one letter of \`${X}\`. Loop over the letters directly.`,
|
||||
before: `${head.trim()}\n … String(${X}[codepoint=${i}]) …`, after: `${nh.trim()}\n … String(${cp}) …`,
|
||||
docUrl: this.docUrl,
|
||||
pseudoHint: 'In pseudo, `FOR EACH C IN T` (in lingo, "For each letter c of T") is a loop over the letters, where `FOR I <- 0 TO LENGTH(T)` is a loop over positions.',
|
||||
fix: { ...wholeLines(first, first + lastUse + 1, text2), label: `Loop over the letters of ${X}` },
|
||||
});
|
||||
});
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 4. raises on a function that cannot raise ---------- */
|
||||
|
||||
const SAFE_CALLS = new Set(['print', 'range', 'len', 'String', 'Int', 'Float64', 'Bool', 'min', 'max', 'abs', 'List', 'Dict', 'Set', 'ord', 'chr']);
|
||||
const SAFE_METHODS = new Set(['append', 'count_codepoints', 'codepoint_slices', 'reserve', 'copy', 'upper', 'lower', 'startswith', 'endswith', 'strip', 'find', 'pop', 'extend', 'insert', 'clear', 'bytes', 'count']);
|
||||
|
||||
const needlessRaises: PracticeRule = {
|
||||
id: 'unneeded-raises',
|
||||
title: 'Drop `raises` from a function that cannot raise',
|
||||
why: '`raises` tells every caller that this function may fail, so each of them has to handle an error that never comes. Mojo checks the claim in the other direction, so when nothing in the body can raise, the word only costs.',
|
||||
docUrl: `${MANUAL}/errors/`,
|
||||
example: {
|
||||
before: 'def double(n: Int) raises -> Int:\n return n * 2\n\n\ndef main() raises:\n print(double(4))\n',
|
||||
after: 'def double(n: Int) -> Int:\n return n * 2\n\n\ndef main():\n print(double(4))\n',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
const raising = new Set<string>(MOJO_PRELUDE_RAISES);
|
||||
let usesDict = false;
|
||||
walk(mod.body, (n) => { if (n.k === 'name' && (n.id === 'Dict' || n.id === 'Python')) usesDict = true; });
|
||||
let usesStruct = false;
|
||||
walk(mod.body, (n) => { if (n.k === 'struct') usesStruct = true; });
|
||||
const defs = defsOf(mod);
|
||||
for (const d of defs) if (d.raises) raising.add(d.name);
|
||||
const baseErrors = checkMojo(source).diagnostics.filter((x) => x.severity === 'error').length;
|
||||
for (const d of defs) {
|
||||
if (!d.raises || d.raisesType || d.name.startsWith('test_')) continue; // a test function says raises because its runner expects it
|
||||
// a body that is only `pass` or `...` is a placeholder (often a demonstration of `raises` itself); a user type's indexing may raise
|
||||
let bad = usesDict || d.body.every((x) => x.k === 'pass' || (x.k === 'expr' && x.e.k === 'ellipsis')) || (usesStruct && d.body.some((x) => { let ix = false; walk(x, (n) => { if (n.k === 'index') ix = true; }); return ix; }));
|
||||
walk(d.body, (n) => {
|
||||
if (n.k === 'raise' || n.k === 'try' || n.k === 'with' || n.k === 'import' || n.k === 'from' || n.k === 'lambda') bad = true;
|
||||
if (n.k === 'call') {
|
||||
const c = n as unknown as Extract<Expr, { k: 'call' }>;
|
||||
if (c.fn.k === 'name') { const fid = c.fn.id; if (raising.has(fid) || !(SAFE_CALLS.has(fid) || defs.some((x) => x.name === fid && !x.raises))) bad = true; }
|
||||
else if (c.fn.k === 'attr') { if (!SAFE_METHODS.has(c.fn.name)) bad = true; }
|
||||
else bad = true;
|
||||
}
|
||||
});
|
||||
if (bad) continue;
|
||||
const l = src[d.pos.line - 1] ?? '';
|
||||
const nl = l.replace(/\)\s*raises\b/, ')');
|
||||
if (nl === l || !/:\s*$/.test(nl)) continue;
|
||||
const trial = [...src]; trial[d.pos.line - 1] = nl;
|
||||
const after = checkMojo(trial.join('\n')).diagnostics.filter((x) => x.severity === 'error').length;
|
||||
if (after > baseErrors) continue;
|
||||
out.push({
|
||||
rule: 'unneeded-raises', line: d.pos.line,
|
||||
message: `\`${d.name}\` says it raises, but nothing in it can. Callers have to handle an error that never comes.`,
|
||||
before: l.trim(), after: nl.trim(), docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(d.pos.line, d.pos.line, nl), label: `Remove raises from ${d.name}` },
|
||||
});
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 5. a value that never changes ---------- */
|
||||
|
||||
const constantValue: PracticeRule = {
|
||||
id: 'comptime-constant',
|
||||
title: 'A value that never changes can be `comptime`',
|
||||
why: 'A `comptime` name is worked out while the program is compiled and can never be assigned again, so the compiler holds you to it. A `var` that is only ever read says less than it could.',
|
||||
docUrl: `${MANUAL}/metaprogramming/comptime-evaluation/`,
|
||||
example: {
|
||||
before: 'def main():\n var width = 4\n for i in range(width):\n print(i)\n',
|
||||
after: 'def main():\n comptime width = 4\n for i in range(width):\n print(i)\n',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
const written = new Set<string>();
|
||||
walk(mod.body, (n) => {
|
||||
const s = n as unknown as Stmt;
|
||||
if (s.k === 'assign') for (const t of s.targets) walk(t, (m) => { if (m.k === 'name') written.add(m.id as string); });
|
||||
if (s.k === 'aug') walk(s.target, (m) => { if (m.k === 'name') written.add(m.id as string); });
|
||||
if (n.k === 'walrus') written.add(n.name as string);
|
||||
if (s.k === 'for') walk(s.target, (m) => { if (m.k === 'name') written.add(m.id as string); });
|
||||
});
|
||||
const declared = new Map<string, number>();
|
||||
walk(mod.body, (n) => { const s = n as unknown as Stmt; if (s.k === 'var' && s.targets.k === 'name') declared.set(s.targets.id, (declared.get(s.targets.id) ?? 0) + 1); });
|
||||
for (const d of defsOf(mod)) {
|
||||
for (const s of d.body) {
|
||||
if (s.k !== 'var' || s.comptime || s.ref || s.type || !s.value || s.targets.k !== 'name') continue;
|
||||
const v = s.value, id = s.targets.id;
|
||||
const literal = v.k === 'num' || (v.k === 'str' && !v.t) || (v.k === 'name' && (v.id === 'True' || v.id === 'False'));
|
||||
if (!literal || written.has(id) || declared.get(id) !== 1) continue;
|
||||
// read only: used as an argument of a builtin or in an expression, never handed to a function that might change it
|
||||
let handed = false;
|
||||
walk(d.body, (n) => {
|
||||
if (n.k === 'call') for (const a of (n as unknown as Extract<Expr, { k: 'call' }>).args) if (a.value.k === 'name' && a.value.id === id) {
|
||||
const fn = (n as unknown as Extract<Expr, { k: 'call' }>).fn;
|
||||
if (!(fn.k === 'name' && SAFE_CALLS.has(fn.id))) handed = true;
|
||||
}
|
||||
if (n.k === 'attr' && (n as unknown as Extract<Expr, { k: 'attr' }>).obj.k === 'name' && ((n as unknown as Extract<Expr, { k: 'attr' }>).obj as { id: string }).id === id) handed = true;
|
||||
});
|
||||
if (handed) continue;
|
||||
// only the number that sizes something is worth saying: a loop bound, a type parameter
|
||||
let sizes = false;
|
||||
walk(d.body, (n) => {
|
||||
if (n.k === 'call') { const c = n as unknown as Extract<Expr, { k: 'call' }>; if (c.fn.k === 'name' && c.fn.id === 'range' && c.args.some((a) => a.value.k === 'name' && a.value.id === id)) sizes = true; }
|
||||
if (n.k === 'index') { const x = n as unknown as Extract<Expr, { k: 'index' }>; if (x.obj.k !== 'name' || /^[A-Z]/.test(x.obj.id)) if (x.args.some((a) => a.value.k === 'name' && a.value.id === id)) sizes = true; }
|
||||
});
|
||||
if (!sizes || v.k !== 'num') continue;
|
||||
const l = src[s.pos.line - 1] ?? '';
|
||||
out.push({
|
||||
rule: 'comptime-constant', line: s.pos.line,
|
||||
message: `\`${id}\` is set once and never changed. Written as \`comptime ${id} = …\`, the compiler holds it to that.`,
|
||||
before: l.trim(), after: l.trim().replace(/^var\b/, 'comptime'), docUrl: this.docUrl,
|
||||
});
|
||||
}
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 6. argument conventions ---------- */
|
||||
|
||||
const argConventions: PracticeRule = {
|
||||
id: 'argument-convention',
|
||||
title: 'Say only the argument convention you need',
|
||||
why: 'An argument is `imm` (immutable) unless the function says otherwise: it can look at the caller\'s value but not change it, and nothing is copied. `mut` is for a function that changes the caller\'s value, and `var` for one that takes ownership. Writing `imm` adds nothing, and `mut` on an argument the function never changes promises a change that does not happen.',
|
||||
docUrl: `${MANUAL}/values/ownership/`,
|
||||
example: {
|
||||
before: 'def show(imm n: Int):\n print(n)\n\n\ndef main():\n show(3)\n',
|
||||
after: 'def show(n: Int):\n print(n)\n\n\ndef main():\n show(3)\n',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
for (const d of defsOf(mod)) {
|
||||
const l = src[d.pos.line - 1] ?? '';
|
||||
for (const p of d.params) {
|
||||
if (p.star || !p.convention || p.name === 'self') continue;
|
||||
const re = new RegExp(`\\b${p.convention}\\s+${escapeRe(p.name)}\\b`);
|
||||
if (!re.test(l)) continue;
|
||||
const nl = l.replace(re, p.name);
|
||||
if (!/:\s*$/.test(nl)) continue;
|
||||
if (p.convention === 'imm') {
|
||||
out.push({
|
||||
rule: 'argument-convention', line: d.pos.line,
|
||||
message: `\`imm\` is what \`${p.name}\` already is without it: the function sees the caller's value and cannot change it.`,
|
||||
before: l.trim(), after: nl.trim(), docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(d.pos.line, d.pos.line, nl), label: `Leave out imm on ${p.name}` },
|
||||
});
|
||||
} else if (p.convention === 'mut') {
|
||||
// never written, never handed on, never called on
|
||||
let touched = false;
|
||||
walk(d.body, (n) => {
|
||||
const s = n as unknown as Stmt;
|
||||
if (s.k === 'assign') for (const t of s.targets) if (mentions(t, p.name)) touched = true;
|
||||
if (s.k === 'aug' && mentions(s.target, p.name)) touched = true;
|
||||
if (n.k === 'transfer' && mentions(n, p.name)) touched = true;
|
||||
if (n.k === 'call') {
|
||||
const c = n as unknown as Extract<Expr, { k: 'call' }>;
|
||||
if (c.fn.k === 'attr' && mentions(c.fn.obj, p.name)) touched = true;
|
||||
for (const a of c.args) if (a.value.k === 'name' && a.value.id === p.name && !(c.fn.k === 'name' && ['print', 'String', 'len', 'Int', 'Float64'].includes(c.fn.id))) touched = true;
|
||||
}
|
||||
if (n.k === 'for' && mentions((n as unknown as Extract<Stmt, { k: 'for' }>).iter, p.name)) touched = true;
|
||||
if (n.k === 'walrus') touched = true;
|
||||
});
|
||||
if (touched) continue;
|
||||
out.push({
|
||||
rule: 'argument-convention', line: d.pos.line,
|
||||
message: `\`mut ${p.name}\` promises the function changes the caller's value, but it never does. Without \`mut\` it is \`imm\`.`,
|
||||
before: l.trim(), after: nl.trim(), docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(d.pos.line, d.pos.line, nl), label: `Leave out mut on ${p.name}` },
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 7. reserve ---------- */
|
||||
|
||||
const reserveList: PracticeRule = {
|
||||
id: 'reserve',
|
||||
title: 'Reserve room when you know how many items are coming',
|
||||
why: 'A List that grows one append at a time may have to move its contents to bigger storage several times. When the loop count is known up front, `reserve` asks for the room once.',
|
||||
docUrl: `${MANUAL}/types/`,
|
||||
example: {
|
||||
before: 'def main():\n var xs = List[Int]()\n for i in range(5):\n xs.append(i * i)\n print(len(xs))\n',
|
||||
after: 'def main():\n var xs = List[Int]()\n xs.reserve(5)\n for i in range(5):\n xs.append(i * i)\n print(len(xs))\n',
|
||||
},
|
||||
apis: [['List', 'reserve'], ['List', 'append']],
|
||||
detect(mod, source) {
|
||||
const src = lines(source);
|
||||
const out: PracticeFinding[] = [];
|
||||
const simple = (e: Expr): boolean => e.k === 'num' || e.k === 'name' || (e.k === 'call' && e.args.length === 0 && e.fn.k === 'attr' && e.fn.name === 'count_codepoints' && e.fn.obj.k === 'name') || (e.k === 'call' && e.fn.k === 'name' && e.fn.id === 'len' && e.args.length === 1 && e.args[0].value.k === 'name');
|
||||
for (const block of blocksOf(mod)) {
|
||||
block.forEach((d, i) => {
|
||||
if (d.k !== 'var' || d.targets.k !== 'name' || !d.value) return;
|
||||
const v = d.value;
|
||||
const emptyList = (v.k === 'call' && v.args.length === 0 && ((v.fn.k === 'index' && v.fn.obj.k === 'name' && v.fn.obj.id === 'List') || (v.fn.k === 'name' && v.fn.id === 'List'))) || (v.k === 'list' && v.items.length === 0);
|
||||
if (!emptyList) return;
|
||||
const id = d.targets.id;
|
||||
for (let j = i + 1; j < block.length; j++) {
|
||||
const f = block[j];
|
||||
if (!mentions(f, id)) continue;
|
||||
if (f.k !== 'for' || f.comptime || f.orelse.length) return;
|
||||
const it = f.iter;
|
||||
if (it.k !== 'call' || it.fn.k !== 'name' || it.fn.id !== 'range' || it.args.length !== 1 || !simple(it.args[0].value)) return;
|
||||
const bound = it.args[0].value;
|
||||
// the loop appends once per pass, at the top level of its body, and does not leave early
|
||||
const appends = f.body.filter((s) => s.k === 'expr' && s.e.k === 'call' && s.e.fn.k === 'attr' && s.e.fn.name === 'append' && s.e.fn.obj.k === 'name' && s.e.fn.obj.id === id).length;
|
||||
let early = false; walk(f.body, (n) => { if (n.k === 'break' || n.k === 'return') early = true; });
|
||||
if (!appends || early) return;
|
||||
// the bound must not be changed by the loop
|
||||
if (bound.k === 'name') {
|
||||
const bid = bound.id; let w = false;
|
||||
walk(f.body, (n) => { const s2 = n as unknown as Stmt; if ((s2.k === 'assign' && s2.targets.some((t) => mentions(t, bid))) || (s2.k === 'aug' && mentions(s2.target, bid))) w = true; });
|
||||
if (w) return;
|
||||
}
|
||||
const l = src[f.pos.line - 1] ?? '';
|
||||
const bm = /range\((.*)\)\s*:\s*$/.exec(l);
|
||||
if (!bm) return;
|
||||
const ins = `${indentOf(l)}${id}.reserve(${bm[1]})`;
|
||||
out.push({
|
||||
rule: 'reserve', line: f.pos.line,
|
||||
message: `\`${id}\` is filled by a loop that runs ${bm[1]} times. Ask for the room first.`,
|
||||
before: l.trim(), after: `${ins.trim()}\n${l.trim()}`, docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(f.pos.line, f.pos.line, `${ins}\n${l}`), label: `Reserve ${bm[1]} places in ${id}` },
|
||||
});
|
||||
return;
|
||||
}
|
||||
});
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 8. a value that is handed over for good: ^ ---------- */
|
||||
|
||||
const localKind = (e: Expr | null): boolean => !!e && ((e.k === 'list') || (e.k === 'str' && !e.t) || (e.k === 'call' && ((e.fn.k === 'name' && (e.fn.id === 'String' || e.fn.id === 'List')) || (e.fn.k === 'index' && e.fn.obj.k === 'name' && e.fn.obj.id === 'List'))));
|
||||
|
||||
const transferLast: PracticeRule = {
|
||||
id: 'transfer-last-use',
|
||||
title: 'Hand a value over with ^ when you are done with it',
|
||||
why: 'A function that takes its argument as `var` owns it. Passing a name copies the value unless this is its last use, and `name^` says so: the value moves, nothing is copied, and the name is not used again.',
|
||||
docUrl: `${MANUAL}/values/ownership/`,
|
||||
example: {
|
||||
before: 'def total(var xs: List[Int]) -> Int:\n var t = 0\n for x in xs:\n t += x\n return t\n\n\ndef main():\n var xs = [1, 2, 3]\n print(total(xs))\n',
|
||||
after: 'def total(var xs: List[Int]) -> Int:\n var t = 0\n for x in xs:\n t += x\n return t\n\n\ndef main():\n var xs = [1, 2, 3]\n print(total(xs^))\n',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const out: PracticeFinding[] = [];
|
||||
const src = lines(source);
|
||||
const defs = defsOf(mod);
|
||||
for (const block of blocksOf(mod)) {
|
||||
block.forEach((s, j) => {
|
||||
walk(s, (n) => {
|
||||
if (n.k !== 'call') return;
|
||||
const c = n as unknown as Extract<Expr, { k: 'call' }>;
|
||||
if (c.fn.k !== 'name') return;
|
||||
const target = defs.find((x) => x.name === (c.fn as { id: string }).id);
|
||||
if (!target) return;
|
||||
c.args.forEach((a, k) => {
|
||||
if (a.name || a.star || a.value.k !== 'name') return;
|
||||
const p = target.params[k];
|
||||
if (!p || p.star || (p.convention !== 'var' && p.convention !== 'owned')) return;
|
||||
const id = a.value.id;
|
||||
// a local that holds a List or String, declared earlier in this block, with no use after this statement
|
||||
const decl = block.slice(0, j).find((x) => x.k === 'var' && x.targets.k === 'name' && x.targets.id === id);
|
||||
if (!decl || decl.k !== 'var' || !localKind(decl.value)) return;
|
||||
if (block.slice(j + 1).some((x) => mentions(x, id)) || countMentions(s, id) !== 1) return;
|
||||
// not inside a loop or a branch of this statement that could run again
|
||||
if (s.k === 'for' || s.k === 'while') return;
|
||||
const l = src[a.value.pos.line - 1] ?? '';
|
||||
const at = a.value.pos.col - 1;
|
||||
if (l.slice(at, at + id.length) !== id || l[at + id.length] === '^') return;
|
||||
const nl = `${l.slice(0, at)}${id}^${l.slice(at + id.length)}`;
|
||||
out.push({
|
||||
rule: 'transfer-last-use', line: a.value.pos.line,
|
||||
message: `\`${id}\` is not used after this call, and \`${target.name}\` takes it as \`var\`. Move it with \`${id}^\` instead of copying it.`,
|
||||
before: l.trim(), after: nl.trim(), docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(a.value.pos.line, a.value.pos.line, nl), label: `Move ${id} with ^` },
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
}
|
||||
// one finding per spot
|
||||
return out.filter((f, i) => out.findIndex((g) => g.line === f.line && g.before === f.before) === i);
|
||||
},
|
||||
};
|
||||
|
||||
/* ---------- 9. a copy that should say so ---------- */
|
||||
|
||||
const explicitCopy: PracticeRule = {
|
||||
id: 'explicit-copy',
|
||||
title: 'Say .copy() when you mean a copy',
|
||||
why: 'A List is not copied behind your back in Mojo. `var b = a` while `a` is still needed is an implicit copy, which the compiler refuses; `a.copy()` says you want a second list, and shows a reader where the cost is.',
|
||||
docUrl: `${MANUAL}/values/ownership/`,
|
||||
example: {
|
||||
before: 'def main():\n var a = List[Int]()\n a.append(1)\n var b = a\n b.append(4)\n print(len(a), len(b))\n',
|
||||
after: 'def main():\n var a = List[Int]()\n a.append(1)\n var b = a.copy()\n b.append(4)\n print(len(a), len(b))\n',
|
||||
beforeRefused: 'cannot be implicitly copied',
|
||||
},
|
||||
apis: [],
|
||||
detect(mod, source) {
|
||||
const out: PracticeFinding[] = [];
|
||||
const src = lines(source);
|
||||
for (const block of blocksOf(mod)) {
|
||||
block.forEach((s, j) => {
|
||||
if (s.k !== 'var' || !s.value || s.value.k !== 'name' || s.targets.k !== 'name') return;
|
||||
const id = s.value.id;
|
||||
const decl = block.slice(0, j).find((x) => x.k === 'var' && x.targets.k === 'name' && x.targets.id === id);
|
||||
if (!decl || decl.k !== 'var' || !decl.value || (decl.value.k !== 'list' && !(decl.value.k === 'call' && ((decl.value.fn.k === 'name' && decl.value.fn.id === 'List') || (decl.value.fn.k === 'index' && decl.value.fn.obj.k === 'name' && decl.value.fn.obj.id === 'List'))))) return;
|
||||
if (!block.slice(j + 1).some((x) => mentions(x, id))) return; // the last use is a move, not a copy
|
||||
const l = src[s.value.pos.line - 1] ?? '';
|
||||
const at = s.value.pos.col - 1;
|
||||
if (l.slice(at, at + id.length) !== id) return;
|
||||
const nl = `${l.slice(0, at)}${id}.copy()${l.slice(at + id.length)}`;
|
||||
out.push({
|
||||
rule: 'explicit-copy', line: s.value.pos.line,
|
||||
message: `\`${s.targets.id} = ${id}\` copies the list while \`${id}\` is still used below. Say \`.copy()\`.`,
|
||||
before: l.trim(), after: nl.trim(), docUrl: this.docUrl,
|
||||
fix: { ...wholeLines(s.value.pos.line, s.value.pos.line, nl), label: `Copy ${id} explicitly` },
|
||||
});
|
||||
});
|
||||
}
|
||||
return out;
|
||||
},
|
||||
};
|
||||
|
||||
export const RULES: readonly PracticeRule[] = [declareThenAssign, augmentedAssign, codepointLoop, needlessRaises, constantValue, argConventions, reserveList, transferLast, explicitCopy];
|
||||
|
||||
/* ---------- running them ---------- */
|
||||
|
||||
/** Every finding of every rule, in line order. */
|
||||
export function findPractices(source: string, module?: Module): PracticeFinding[] {
|
||||
const mod = module ?? parseModule(source);
|
||||
if (mod.findings.some((f) => f.severity === 'error')) return []; // advice on code that does not read yet is noise
|
||||
const all: PracticeFinding[] = [];
|
||||
for (const r of RULES) { try { all.push(...r.detect(mod, source)); } catch { /* a rule that cannot read this shape says nothing */ } }
|
||||
return all.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
|
||||
}
|
||||
|
||||
/** Apply one quick fix to the text (whole-line fixes: the same edit the editor makes). */
|
||||
export function applyQuickFix(source: string, f: QuickFix): string {
|
||||
const ls = source.split('\n');
|
||||
const last = Math.min(f.endLine ?? f.line, ls.length);
|
||||
return [...ls.slice(0, f.line - 1), ...f.text.split('\n'), ...ls.slice(last)].join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply every safe rewrite to a copy: one at a time, finding again after each (the lines move), and keeping one
|
||||
* only when the checker finds no more errors than before. Returns the new text and how many rewrites were applied.
|
||||
*/
|
||||
export function applyPractices(source: string, only?: ReadonlySet<string>): { source: string; applied: PracticeFinding[] } {
|
||||
let cur = source;
|
||||
const applied: PracticeFinding[] = [];
|
||||
const baseErrors = checkMojo(source).diagnostics.filter((d) => d.severity === 'error').length;
|
||||
const refused = new Set<string>();
|
||||
for (let n = 0; n < 60; n++) {
|
||||
const f = findPractices(cur).find((x) => x.fix && !refused.has(`${x.rule}:${x.before}`) && (!only || only.has(x.rule)));
|
||||
if (!f) break;
|
||||
const next = applyQuickFix(cur, f.fix!);
|
||||
if (next === cur || checkMojo(next).diagnostics.filter((d) => d.severity === 'error').length > baseErrors) { refused.add(`${f.rule}:${f.before}`); continue; }
|
||||
cur = next; applied.push(f);
|
||||
}
|
||||
return { source: cur, applied };
|
||||
}
|
||||
|
||||
/** Findings as editor diagnostics: always `note`, never an error or a warning, so they never pass for the compiler. */
|
||||
export function findingsToDiagnostics(findings: readonly PracticeFinding[]): Diagnostic[] {
|
||||
return findings.map((f) => ({
|
||||
lang: 'mojo' as const, severity: 'note' as const, id: `practice-${f.rule}`, line: f.line, message: f.message,
|
||||
origin: PRACTICES_ORIGIN, docUrl: f.docUrl, ...(f.fix ? { fix: f.fix } : {}),
|
||||
}));
|
||||
}
|
||||
|
||||
export function practiceDiagnostics(source: string, module?: Module): Diagnostic[] {
|
||||
return findingsToDiagnostics(findPractices(source, module));
|
||||
}
|
||||
Reference in new issue
Block a user