lemmaly 0.1.0

package/cli/gen-rule-docs.js

@@ -0,0 +1,885 @@
+#!/usr/bin/env node
+// Generates one MD file per CLI rule into skills/lemmaly/rules/
+// Source of truth: rules/*.json. Examples are hand-authored here.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const OUT = path.join(ROOT, 'skills', 'lemmaly', 'rules');
+const SEV_TO_IMPACT = { error: 'CRITICAL', warning: 'HIGH', info: 'MEDIUM' };
+const SEV_TO_DESC = {
+  error: 'Will break or scale-fail in production',
+  warning: 'Hot-path or correctness risk at realistic n',
+  info: 'Suboptimal; flag when n is large or on a hot path',
+};
+
+const EXAMPLES = {
+  'js-await-in-for-loop': {
+    why: 'Awaiting inside a `for` over independent items serializes wall-clock work into O(n × latency). For network or DB calls this is the N+1 problem.',
+    bad: `// Wall-clock: O(n × latency)
+for (const id of ids) {
+  const user = await db.users.findById(id);
+  results.push(user);
+}`,
+    good: `// Wall-clock: O(latency); one bulk query
+const users = await db.users.findMany({ where: { id: { in: ids } } });
+
+// Or, if calls are truly independent:
+const results = await Promise.all(ids.map(id => db.users.findById(id)));`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-async-in-foreach': {
+    why: '`Array.prototype.forEach` ignores return values. Passing an `async` function returns promises that are dropped — errors are swallowed and the caller continues before the work finishes.',
+    bad: `// Promises dropped; errors silently swallowed
+items.forEach(async (item) => {
+  await save(item);
+});
+console.log('done'); // logs before any save completes`,
+    good: `// Sequential, with errors propagated
+for (const item of items) {
+  await save(item);
+}
+
+// Parallel
+await Promise.all(items.map((item) => save(item)));`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-deep-clone-via-json': {
+    why: '`JSON.parse(JSON.stringify(x))` is slow, allocates twice, and silently loses `Date`, `Map`, `Set`, `undefined`, `BigInt`, `RegExp`, and any non-enumerable property. It is also unsafe on cyclic structures.',
+    bad: `const copy = JSON.parse(JSON.stringify(state));
+// state.createdAt was a Date — now a string`,
+    good: `const copy = structuredClone(state); // preserves Date, Map, Set, cycles
+
+// Or, when you only need a few fields:
+const copy = { id: state.id, name: state.name };`,
+    lang: 'ts',
+    chainTo: null,
+  },
+  'js-useeffect-missing-deps': {
+    why: 'A `useEffect` with no dependency array runs after every render. If the effect updates state, you can get a render loop or wasted work each frame.',
+    bad: `useEffect(() => {
+  setUser(fetchUser(id));
+}); // no deps — runs every render`,
+    good: `useEffect(() => {
+  setUser(fetchUser(id));
+}, [id]); // runs when id changes`,
+    lang: 'tsx',
+    chainTo: null,
+  },
+  'js-inline-object-jsx-prop': {
+    why: 'An inline object literal in JSX creates a new reference every render. If the child is `React.memo`, this defeats the memoization. If it is a dependency of a hook in the child, it re-fires that hook every render.',
+    bad: `<Chart options={{ animated: true, color: 'red' }} />`,
+    good: `// Hoist if static
+const CHART_OPTIONS = { animated: true, color: 'red' };
+<Chart options={CHART_OPTIONS} />
+
+// Memoize if derived
+const options = useMemo(() => ({ animated, color }), [animated, color]);
+<Chart options={options} />`,
+    lang: 'tsx',
+    chainTo: null,
+  },
+  'js-anonymous-handler-jsx': {
+    why: 'An anonymous arrow handler is a new function every render. For an ordinary child, this is fine. For a `React.memo` child, it breaks equality and forces a re-render every time.',
+    bad: `// Child is React.memo — this defeats it
+<MemoButton onClick={() => save(id)} />`,
+    good: `const onClick = useCallback(() => save(id), [id]);
+<MemoButton onClick={onClick} />`,
+    lang: 'tsx',
+    chainTo: null,
+  },
+  'js-nested-for-loops': {
+    why: 'Two `for` loops that check membership between arrays are O(n × m). Hashing one side into a `Set` makes it O(n + m).',
+    bad: `// O(n × m)
+const matches = [];
+for (const a of left) {
+  for (const b of right) {
+    if (a.id === b.id) matches.push([a, b]);
+  }
+}`,
+    good: `// O(n + m)
+const rightById = new Map(right.map((b) => [b.id, b]));
+const matches = [];
+for (const a of left) {
+  const b = rightById.get(a.id);
+  if (b) matches.push([a, b]);
+}`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-spread-in-reduce': {
+    why: 'Object-spread in a reducer copies the accumulator on every iteration — O(n²) work and O(n²) allocation. The result is the same as mutating once.',
+    bad: `// O(n²)
+const byId = items.reduce((acc, x) => ({ ...acc, [x.id]: x }), {});`,
+    good: `// O(n)
+const byId = Object.fromEntries(items.map((x) => [x.id, x]));
+
+// Or mutate the accumulator
+const byId = items.reduce((acc, x) => { acc[x.id] = x; return acc; }, {});`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-includes-in-iterator': {
+    why: '`.includes` on an array is O(n). Calling it inside `.map`/`.filter`/`.forEach` over m items is O(n × m). A `Set` lookup is O(1).',
+    bad: `// O(n × m)
+const allowed = ['admin', 'editor', 'owner'];
+const result = users.filter((u) => allowed.includes(u.role));`,
+    good: `// O(n + m)
+const allowed = new Set(['admin', 'editor', 'owner']);
+const result = users.filter((u) => allowed.has(u.role));`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-unique-via-indexof': {
+    why: '`.filter((x, i, a) => a.indexOf(x) === i)` is the textbook O(n²) dedupe. A `Set` does it in O(n).',
+    bad: `// O(n²)
+const unique = arr.filter((x, i, a) => a.indexOf(x) === i);`,
+    good: `// O(n)
+const unique = Array.from(new Set(arr));`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-helper-call-in-iterator': {
+    why: 'A `get*`/`find*`/`fetch*` helper inside an iterator usually means N independent lookups. If the helper hits a DB or network, this is N+1. If it scans an array, it is O(n × m).',
+    bad: `// N round trips
+const enriched = orders.map((o) => ({
+  ...o,
+  user: getUserById(o.userId),
+}));`,
+    good: `// 1 round trip
+const userIds = [...new Set(orders.map((o) => o.userId))];
+const users = await db.users.findMany({ where: { id: { in: userIds } } });
+const userById = new Map(users.map((u) => [u.id, u]));
+const enriched = orders.map((o) => ({ ...o, user: userById.get(o.userId) }));`,
+    lang: 'ts',
+    chainTo: 'complexity-cuts',
+  },
+  'js-array-key-index': {
+    why: '`key={index}` is fine for a static list. For a list that reorders, inserts, or deletes in the middle, it forces React to mismatch component state with the wrong row — losing input focus, animation, and local state.',
+    bad: `{items.map((item, i) => <Row key={i} item={item} />)}`,
+    good: `{items.map((item) => <Row key={item.id} item={item} />)}`,
+    lang: 'tsx',
+    chainTo: null,
+  },
+  'py-mutable-default-arg': {
+    why: 'Python evaluates default arguments once, at function definition. A mutable default (list, dict, set) is **shared across every call** — calls accumulate state from previous calls.',
+    bad: `def collect(item, bucket=[]):  # shared across all calls!
+    bucket.append(item)
+    return bucket`,
+    good: `def collect(item, bucket=None):
+    if bucket is None:
+        bucket = []
+    bucket.append(item)
+    return bucket`,
+    lang: 'python',
+    chainTo: 'invariant-guard',
+  },
+  'py-string-concat-in-loop': {
+    why: 'Python strings are immutable. `s += x` in a loop allocates and copies the whole `s` each iteration — O(n²) total work. A list join is O(n).',
+    bad: `# O(n²)
+s = ""
+for line in lines:
+    s += line + "\\n"`,
+    good: `# O(n)
+s = "\\n".join(lines) + "\\n"
+
+# Or, for incremental building:
+parts = []
+for line in lines:
+    parts.append(line)
+s = "\\n".join(parts)`,
+    lang: 'python',
+    chainTo: 'complexity-cuts',
+  },
+  'py-range-len': {
+    why: '`for i in range(len(xs))` then indexing `xs[i]` is un-Pythonic, slower, and forces you to think about indices when you usually want the items. `enumerate` is idiomatic and faster.',
+    bad: `for i in range(len(xs)):
+    process(xs[i])`,
+    good: `for x in xs:
+    process(x)
+
+# When you actually need the index
+for i, x in enumerate(xs):
+    process(i, x)`,
+    lang: 'python',
+    chainTo: null,
+  },
+  'py-in-list-literal': {
+    why: '`x in [a, b, c, ...]` is an O(n) linear scan. Inside a loop over m items, this is O(n × m). A `set` (or a literal `{a, b, c}` for membership) is O(1).',
+    bad: `# O(n × m)
+roles = ["admin", "editor", "owner"]
+result = [u for u in users if u.role in roles]`,
+    good: `# O(n + m)
+roles = {"admin", "editor", "owner"}
+result = [u for u in users if u.role in roles]`,
+    lang: 'python',
+    chainTo: 'complexity-cuts',
+  },
+  'py-django-loop-without-eager': {
+    why: 'Iterating a Django QuerySet that touches a related model triggers one extra query per row — classic N+1. `select_related` (foreign key, one query with JOIN) or `prefetch_related` (reverse / many-to-many, two queries) fixes it.',
+    bad: `# N+1 queries
+for order in Order.objects.all():
+    print(order.user.email)  # extra query per order`,
+    good: `# 1 query with JOIN
+for order in Order.objects.select_related("user"):
+    print(order.user.email)
+
+# For reverse FK / M2M:
+for user in User.objects.prefetch_related("orders"):
+    for order in user.orders.all():
+        ...`,
+    lang: 'python',
+    chainTo: 'complexity-cuts',
+  },
+  'py-bare-except': {
+    why: 'Bare `except:` catches `SystemExit`, `KeyboardInterrupt`, `MemoryError`, and `GeneratorExit` — things you almost never want to swallow. It hides timeouts, OOM, and Ctrl-C.',
+    bad: `try:
+    do_work()
+except:
+    log("failed")  # also swallows Ctrl-C, OOM, timeouts`,
+    good: `try:
+    do_work()
+except Exception as e:  # excludes SystemExit, KeyboardInterrupt
+    log(f"failed: {e}")`,
+    lang: 'python',
+    chainTo: 'invariant-guard',
+  },
+  'py-open-without-with': {
+    why: '`open()` returns a file object. Without `with`, an exception between open and close leaks the file descriptor. Long-running processes (servers, workers) eventually exhaust the OS limit.',
+    bad: `f = open(path)
+data = f.read()
+f.close()  # skipped if read() raises`,
+    good: `with open(path) as f:
+    data = f.read()
+# f is closed even if read() raises`,
+    lang: 'python',
+    chainTo: null,
+  },
+  'sql-select-star': {
+    why: '`SELECT *` fetches every column, defeating index-only scans, inflating wire traffic, and breaking downstream code when a column is added/renamed. Project only what you need.',
+    bad: `SELECT * FROM users WHERE id = $1;`,
+    good: `SELECT id, email, created_at FROM users WHERE id = $1;`,
+    lang: 'sql',
+    chainTo: null,
+  },
+  'sql-leading-wildcard-like': {
+    why: 'A B-tree index sorts by prefix. `LIKE \'%foo\'` cannot use it — the query scans the table. Use a trigram index (Postgres `pg_trgm`), reverse the column for suffix search, or a full-text search index.',
+    bad: `SELECT * FROM products WHERE name LIKE '%phone';`,
+    good: `-- Postgres: GIN index on trigrams
+CREATE INDEX products_name_trgm ON products USING gin (name gin_trgm_ops);
+SELECT * FROM products WHERE name ILIKE '%phone%';
+
+-- Or full-text:
+SELECT * FROM products WHERE to_tsvector(name) @@ to_tsquery('phone');`,
+    lang: 'sql',
+    chainTo: null,
+  },
+  'sql-not-in-subquery': {
+    why: '`NOT IN (subquery)` is null-unsafe: if any row in the subquery is NULL, the whole predicate is NULL (not TRUE), and the outer row is dropped. `NOT EXISTS` is null-safe and usually has a better plan.',
+    bad: `SELECT * FROM orders
+WHERE user_id NOT IN (SELECT id FROM banned_users);
+-- One NULL in banned_users.id → returns zero rows`,
+    good: `SELECT o.* FROM orders o
+WHERE NOT EXISTS (
+  SELECT 1 FROM banned_users b WHERE b.id = o.user_id
+);`,
+    lang: 'sql',
+    chainTo: 'invariant-guard',
+  },
+  'sql-select-no-limit': {
+    why: 'A query with no `LIMIT` returns however many rows match. On a small table this is fine; on a growing one it eventually OOMs the client or the page. Add a bound, or paginate.',
+    bad: `SELECT id, email FROM users ORDER BY created_at DESC;`,
+    good: `SELECT id, email FROM users
+ORDER BY created_at DESC
+LIMIT 100;
+
+-- Keyset pagination for next page:
+SELECT id, email FROM users
+WHERE created_at < $1
+ORDER BY created_at DESC
+LIMIT 100;`,
+    lang: 'sql',
+    chainTo: null,
+  },
+  'sql-or-in-where': {
+    why: 'A query planner can use an index on one side of an `OR` but often not both, falling back to a sequential scan. `UNION ALL` or `IN (...)` (when both sides are equality on the same column) usually wins.',
+    bad: `SELECT * FROM events
+WHERE user_id = $1 OR account_id = $1;`,
+    good: `SELECT * FROM events WHERE user_id = $1
+UNION ALL
+SELECT * FROM events WHERE account_id = $1;
+
+-- Or, when both sides are the same column:
+SELECT * FROM events WHERE user_id IN ($1, $2, $3);`,
+    lang: 'sql',
+    chainTo: null,
+  },
+  'sql-update-no-where': {
+    why: 'An `UPDATE` or `DELETE` without a `WHERE` clause rewrites every row in the table. In production this is an incident, not a bug.',
+    bad: `UPDATE users SET active = false;
+DELETE FROM sessions;`,
+    good: `UPDATE users SET active = false WHERE last_seen_at < NOW() - INTERVAL '90 days';
+DELETE FROM sessions WHERE expires_at < NOW();`,
+    lang: 'sql',
+    chainTo: 'invariant-guard',
+  },
+
+  // ---------- Java ----------
+  'java-string-concat-in-loop': {
+    why: 'Java `String` is immutable. `s += x` allocates a fresh `String` (and an underlying `char[]`) each iteration — O(n²) total work. `StringBuilder` reuses one buffer.',
+    bad: `// O(n²)
+String s = "";
+for (var line : lines) {
+  s += line + "\\n";
+}`,
+    good: `// O(n)
+var sb = new StringBuilder(lines.size() * 80);
+for (var line : lines) {
+  sb.append(line).append('\\n');
+}
+String s = sb.toString();`,
+    lang: 'java',
+    chainTo: 'complexity-cuts',
+  },
+  'java-list-contains-in-loop': {
+    why: '`List.contains` is O(n). Used inside a stream/iterator over m items it is O(n·m). A `HashSet` lookup is O(1).',
+    bad: `// O(n·m)
+var active = users.stream()
+    .filter(u -> !banned.contains(u.id))
+    .toList();`,
+    good: `// O(n+m)
+var bannedSet = new HashSet<>(banned);
+var active = users.stream()
+    .filter(u -> !bannedSet.contains(u.id))
+    .toList();`,
+    lang: 'java',
+    chainTo: 'complexity-cuts',
+  },
+  'java-arraylist-remove-in-for-i': {
+    why: 'Removing from an `ArrayList` inside a `for (int i = 0; i < list.size(); i++)` shifts indices and skips elements — and on a `Collections.synchronizedList` or in concurrent code, it throws `ConcurrentModificationException`.',
+    bad: `for (int i = 0; i < list.size(); i++) {
+  if (shouldRemove(list.get(i))) {
+    list.remove(i); // shifts everything; next element is skipped
+  }
+}`,
+    good: `// Idiomatic and correct
+list.removeIf(this::shouldRemove);
+
+// Or, with an explicit iterator:
+var it = list.iterator();
+while (it.hasNext()) {
+  if (shouldRemove(it.next())) it.remove();
+}`,
+    lang: 'java',
+    chainTo: 'invariant-guard',
+  },
+  'java-bare-catch-exception': {
+    why: '`catch (Exception e)` with an empty body or just `printStackTrace()` swallows the root cause. The bug lives on, the stack trace evaporates, the production incident has no breadcrumbs.',
+    bad: `try {
+  riskyCall();
+} catch (Exception e) {
+  e.printStackTrace(); // swallowed; caller thinks everything is fine
+}`,
+    good: `try {
+  riskyCall();
+} catch (IOException e) {
+  // narrow exception, rethrow as domain error with cause preserved
+  throw new ReadFailedException("riskyCall failed for " + ctx, e);
+}`,
+    lang: 'java',
+    chainTo: 'invariant-guard',
+  },
+
+  // ---------- C# ----------
+  'cs-string-concat-in-loop': {
+    why: 'C# `string` is immutable. `s += x` allocates a new string each iteration — O(n²). `StringBuilder` reuses one buffer; or use `string.Concat` / `string.Join` for known parts.',
+    bad: `// O(n²)
+string s = "";
+foreach (var line in lines) {
+  s += line + "\\n";
+}`,
+    good: `// O(n)
+var sb = new StringBuilder(lines.Count * 80);
+foreach (var line in lines) {
+  sb.Append(line).Append('\\n');
+}
+var s = sb.ToString();`,
+    lang: 'csharp',
+    chainTo: 'complexity-cuts',
+  },
+  'cs-list-contains-in-loop': {
+    why: '`List<T>.Contains` is O(n). Inside LINQ over m items it is O(n·m). `HashSet<T>` is O(1).',
+    bad: `// O(n·m)
+var active = users.Where(u => !banned.Contains(u.Id)).ToList();`,
+    good: `// O(n+m)
+var bannedSet = new HashSet<int>(banned);
+var active = users.Where(u => !bannedSet.Contains(u.Id)).ToList();`,
+    lang: 'csharp',
+    chainTo: 'complexity-cuts',
+  },
+  'cs-async-void': {
+    why: '`async void` cannot be awaited. Exceptions raised inside are unobserved and crash the process — they bypass `try/catch` at the call site. The only legitimate use is true event handlers (e.g. `OnClick`).',
+    bad: `public async void DoWork() {
+  await Task.Delay(100);
+  throw new Exception("boom"); // crashes the process
+}`,
+    good: `public async Task DoWork() {
+  await Task.Delay(100);
+  throw new Exception("boom"); // caller can await + catch
+}
+
+// Event handlers stay async void with a try/catch at the boundary:
+private async void OnClick(object s, EventArgs e) {
+  try { await DoWorkAsync(); }
+  catch (Exception ex) { _log.LogError(ex, "OnClick failed"); }
+}`,
+    lang: 'csharp',
+    chainTo: 'invariant-guard',
+  },
+  'cs-disposable-no-using': {
+    why: '`IDisposable` resources allocated without `using` leak if an exception fires before `Dispose()`. `using var` ensures cleanup even on throw.',
+    bad: `var stream = new FileStream(path, FileMode.Open);
+var data = ReadAll(stream); // if this throws, stream is never disposed
+stream.Dispose();`,
+    good: `using var stream = new FileStream(path, FileMode.Open);
+var data = ReadAll(stream); // disposed on every exit path`,
+    lang: 'csharp',
+    chainTo: null,
+  },
+
+  // ---------- Go ----------
+  'go-loop-var-capture': {
+    why: 'Before Go 1.22, the loop variable in `for ... := range` was reused across iterations. Goroutines that closed over it all read the *same* (final) value. Go 1.22+ fixes this at the language level, but the pattern still appears in libraries that target older versions.',
+    bad: `// Pre-1.22: all goroutines print the last item
+for _, v := range items {
+  go func() {
+    fmt.Println(v)
+  }()
+}`,
+    good: `// Pin the variable explicitly
+for _, v := range items {
+  v := v
+  go func() { fmt.Println(v) }()
+}
+
+// Or pass as a parameter
+for _, v := range items {
+  go func(v string) { fmt.Println(v) }(v)
+}`,
+    lang: 'go',
+    chainTo: 'invariant-guard',
+  },
+  'go-string-concat-in-loop': {
+    why: 'Go strings are immutable. `s += x` allocates each iteration — O(n²). `strings.Builder` reuses one backing array.',
+    bad: `// O(n²)
+var s string
+for _, line := range lines {
+  s += line + "\\n"
+}`,
+    good: `// O(n)
+var sb strings.Builder
+sb.Grow(len(lines) * 80)
+for _, line := range lines {
+  sb.WriteString(line)
+  sb.WriteByte('\\n')
+}
+s := sb.String()`,
+    lang: 'go',
+    chainTo: 'complexity-cuts',
+  },
+  'go-defer-in-loop': {
+    why: '`defer` fires when the enclosing *function* returns, not when the loop body ends. Deferring inside a loop over N files holds N open handles until the function exits — easy way to exhaust file descriptors.',
+    bad: `for _, f := range files {
+  fp, _ := os.Open(f)
+  defer fp.Close() // accumulates; nothing closes until the outer function returns
+  process(fp)
+}`,
+    good: `for _, f := range files {
+  func() {
+    fp, _ := os.Open(f)
+    defer fp.Close() // closes at end of this iteration
+    process(fp)
+  }()
+}`,
+    lang: 'go',
+    chainTo: null,
+  },
+  'go-err-not-checked': {
+    why: 'Discarding the error return with `_` is silent failure. The function looks like it succeeded; downstream code sees zero values and behaves unpredictably.',
+    bad: `data, _ := os.ReadFile(path)
+return parse(data) // parse on empty buffer if file missing`,
+    good: `data, err := os.ReadFile(path)
+if err != nil {
+  return nil, fmt.Errorf("read %s: %w", path, err)
+}
+return parse(data), nil`,
+    lang: 'go',
+    chainTo: 'invariant-guard',
+  },
+  'go-slice-append-no-cap': {
+    why: 'A slice grown by repeated `append` reallocates and copies its backing array each time it crosses a capacity boundary. Preallocating with `make([]T, 0, n)` does one allocation total.',
+    bad: `var out []int
+for _, x := range in {
+  out = append(out, x*2) // grows; reallocates log(n) times
+}`,
+    good: `out := make([]int, 0, len(in))
+for _, x := range in {
+  out = append(out, x*2)
+}`,
+    lang: 'go',
+    chainTo: 'complexity-cuts',
+  },
+
+  // ---------- Rust ----------
+  'rs-unwrap-in-prod': {
+    why: '`.unwrap()` and `.expect()` panic on `None`/`Err`. In production code they crash the process and lose the structured error. Rust gives you `?`, `match`, and `ok_or` to surface the error to the caller.',
+    bad: `let value = map.get(&key).unwrap(); // panics if key missing`,
+    good: `let value = map.get(&key).ok_or(Error::MissingKey)?;
+
+// Or, when None has a meaningful default:
+let value = map.get(&key).copied().unwrap_or_default();`,
+    lang: 'rust',
+    chainTo: 'invariant-guard',
+  },
+  'rs-clone-in-loop': {
+    why: 'A `.clone()` inside an iterator allocates a fresh copy per element. If a borrow (`&x`) or `Rc::clone` (cheap atomic increment for shared ownership) would do, the deep clone is wasted work.',
+    bad: `// Deep clones every element
+let names: Vec<String> = users.iter().map(|u| u.name.clone()).collect();`,
+    good: `// Borrow when possible
+let names: Vec<&str> = users.iter().map(|u| u.name.as_str()).collect();
+
+// Cheap reference-counted clone when shared ownership is needed
+let shared: Vec<Rc<String>> = users.iter().map(|u| Rc::clone(&u.name)).collect();`,
+    lang: 'rust',
+    chainTo: 'complexity-cuts',
+  },
+  'rs-vec-push-no-capacity': {
+    why: '`Vec::new()` starts with capacity 0; each `push` past the current capacity reallocates and copies. Preallocating with `Vec::with_capacity(n)` does one allocation.',
+    bad: `let mut out = Vec::new();
+for x in input.iter() {
+  out.push(transform(x)); // grows; reallocates log(n) times
+}`,
+    good: `let mut out = Vec::with_capacity(input.len());
+for x in input.iter() {
+  out.push(transform(x));
+}
+
+// Or, when transform is pure:
+let out: Vec<_> = input.iter().map(transform).collect();`,
+    lang: 'rust',
+    chainTo: 'complexity-cuts',
+  },
+  'rs-string-push-no-capacity': {
+    why: '`String::new()` starts at capacity 0. Each `push_str` past capacity reallocates. `with_capacity` or `join` avoids it.',
+    bad: `let mut s = String::new();
+for part in parts.iter() {
+  s.push_str(part); // reallocates as it grows
+}`,
+    good: `let total: usize = parts.iter().map(|p| p.len()).sum();
+let mut s = String::with_capacity(total);
+for part in parts.iter() {
+  s.push_str(part);
+}
+
+// Or, simplest:
+let s = parts.join("");`,
+    lang: 'rust',
+    chainTo: 'complexity-cuts',
+  },
+
+  // ---------- C++ ----------
+  'cpp-vector-push-no-reserve': {
+    why: '`std::vector::push_back` past the current capacity doubles the backing array and copies/moves every element. Calling `reserve(n)` first does one allocation.',
+    bad: `std::vector<int> v;
+for (int i = 0; i < n; ++i) {
+  v.push_back(compute(i)); // reallocates log(n) times
+}`,
+    good: `std::vector<int> v;
+v.reserve(n);
+for (int i = 0; i < n; ++i) {
+  v.push_back(compute(i));
+}`,
+    lang: 'cpp',
+    chainTo: 'complexity-cuts',
+  },
+  'cpp-string-concat-in-loop': {
+    why: '`std::string::operator+=` past capacity reallocates. Without a `reserve`, repeated concatenation is O(n²). `std::ostringstream` or one `reserve` fixes it.',
+    bad: `std::string s;
+for (const auto& part : parts) {
+  s += part;
+}`,
+    good: `std::ostringstream os;
+for (const auto& part : parts) {
+  os << part;
+}
+auto s = os.str();
+
+// Or, if size known:
+std::string s;
+s.reserve(total_size);
+for (const auto& part : parts) s += part;`,
+    lang: 'cpp',
+    chainTo: 'complexity-cuts',
+  },
+  'cpp-raw-new': {
+    why: 'Raw `new` requires a matching `delete` on every exit path. If an exception fires between `new` and `delete`, the memory leaks. Smart pointers (`unique_ptr`, `shared_ptr`) destruct automatically.',
+    bad: `Widget* w = new Widget(42);
+configure(w);   // if this throws, w leaks
+delete w;`,
+    good: `auto w = std::make_unique<Widget>(42);
+configure(w.get()); // destructs on every exit path, including throw`,
+    lang: 'cpp',
+    chainTo: 'invariant-guard',
+  },
+  'cpp-range-loop-copy': {
+    why: '`for (auto x : container)` copies each element into `x`. For non-trivial types (`std::string`, `std::vector<…>`, custom types) this is expensive. `const auto&` borrows, `auto&` mutates in place.',
+    bad: `for (auto s : large_strings) {
+  process(s); // s is a fresh copy each iteration
+}`,
+    good: `for (const auto& s : large_strings) {
+  process(s); // reference, no copy
+}`,
+    lang: 'cpp',
+    chainTo: null,
+  },
+  'cpp-map-double-lookup': {
+    why: '`m.count(k)` then `m[k]` does two hash lookups (and for `std::map`, two binary searches). `find` returns an iterator that gives both presence and value in one lookup.',
+    bad: `if (m.count(k)) {
+  use(m[k]); // second lookup
+}`,
+    good: `auto it = m.find(k);
+if (it != m.end()) {
+  use(it->second);
+}`,
+    lang: 'cpp',
+    chainTo: 'complexity-cuts',
+  },
+
+  // ---------- PHP ----------
+  'php-count-in-for-condition': {
+    why: 'PHP recomputes the loop condition every iteration. `count($a)` on a 100k-element array, called 100k times, is 10B element traversals. Hoist it.',
+    bad: `<?php
+for ($i = 0; $i < count($a); $i++) {
+  echo $a[$i];
+}`,
+    good: `<?php
+// Hoist the length
+for ($i = 0, $n = count($a); $i < $n; $i++) {
+  echo $a[$i];
+}
+
+// Or, idiomatic
+foreach ($a as $x) {
+  echo $x;
+}`,
+    lang: 'php',
+    chainTo: 'complexity-cuts',
+  },
+  'php-in-array-in-loop': {
+    why: '`in_array` is a linear scan. Used inside a loop over m items it is O(n·m). `array_flip + isset` is O(1) per check.',
+    bad: `<?php
+foreach ($users as $u) {
+  if (in_array($u->id, $banned)) continue;
+  ship($u);
+}`,
+    good: `<?php
+$bannedSet = array_flip($banned); // O(n) once
+foreach ($users as $u) {
+  if (isset($bannedSet[$u->id])) continue; // O(1)
+  ship($u);
+}`,
+    lang: 'php',
+    chainTo: 'complexity-cuts',
+  },
+  'php-query-in-loop': {
+    why: 'A SQL query inside a loop is the textbook N+1 problem. 1000 orders, 1000 round-trips to the DB. Batch with `WHERE id IN (...)` or eager-load in your ORM.',
+    bad: `<?php
+foreach ($orderIds as $id) {
+  $row = $db->query("SELECT * FROM orders WHERE id = $id"); // 1 query per id
+  process($row);
+}`,
+    good: `<?php
+// One bulk query
+$placeholders = implode(',', array_fill(0, count($orderIds), '?'));
+$stmt = $db->prepare("SELECT * FROM orders WHERE id IN ($placeholders)");
+$stmt->execute($orderIds);
+foreach ($stmt->fetchAll() as $row) {
+  process($row);
+}
+
+// Eloquent / Doctrine: use eager loading
+$orders = Order::with('items')->whereIn('id', $orderIds)->get();`,
+    lang: 'php',
+    chainTo: 'complexity-cuts',
+  },
+  'php-loose-equality': {
+    why: 'PHP `==` does type coercion in surprising ways (`"0" == false` is `true`, `"abc" == 0` was `true` before PHP 8). `===` compares value AND type — no surprises.',
+    bad: `<?php
+if ($status == 0) { /* matches "", "0", false, null, 0, "abc" pre-PHP 8 */ }`,
+    good: `<?php
+if ($status === 0) { /* matches only int 0 */ }`,
+    lang: 'php',
+    chainTo: 'invariant-guard',
+  },
+
+  // ---------- Ruby ----------
+  'rb-include-in-iterator': {
+    why: '`Array#include?` is O(n). Used inside an iterator over m items it is O(n·m). `Set#include?` is O(1).',
+    bad: `# O(n·m)
+users.select { |u| banned.include?(u.id) }`,
+    good: `# O(n+m)
+require 'set'
+banned_set = Set.new(banned)
+users.select { |u| banned_set.include?(u.id) }`,
+    lang: 'ruby',
+    chainTo: 'complexity-cuts',
+  },
+  'rb-n-plus-one-activerecord': {
+    why: 'Iterating an ActiveRecord scope and touching an association fires one extra query per row. `includes` (preload or eager_load) fetches everything in a constant number of queries.',
+    bad: `# N+1 queries
+Post.all.each do |p|
+  puts p.author.name # 1 extra query per post
+end`,
+    good: `# 2 queries total (or 1 with eager_load)
+Post.includes(:author).each do |p|
+  puts p.author.name
+end`,
+    lang: 'ruby',
+    chainTo: 'complexity-cuts',
+  },
+  'rb-bare-rescue': {
+    why: 'A bare `rescue` (without a class) catches `StandardError` — including `NoMethodError`, `ArgumentError`, and other bugs you almost always want to surface. Catch the specific class.',
+    bad: `begin
+  fetch_remote
+rescue
+  retry # also catches typos and bugs in fetch_remote
+end`,
+    good: `begin
+  fetch_remote
+rescue Net::ReadTimeout, Net::OpenTimeout => e
+  retry
+end`,
+    lang: 'ruby',
+    chainTo: 'invariant-guard',
+  },
+  'rb-string-concat-in-loop': {
+    why: '`s += x` creates a new string each iteration — O(n²). `<<` mutates in place (O(n) amortized). `Array#join` is O(n) and idiomatic.',
+    bad: `s = ""
+parts.each { |p| s += p } # O(n²)`,
+    good: `# Mutating concat
+s = String.new
+parts.each { |p| s << p }
+
+# Idiomatic
+s = parts.join`,
+    lang: 'ruby',
+    chainTo: 'complexity-cuts',
+  },
+
+  // ---------- Shell / Bash ----------
+  'sh-set-e-no-pipefail': {
+    why: '`set -e` exits on a failed command, but a failure in the middle of a pipe is masked — only the *last* command\'s exit status counts. `set -o pipefail` fixes it. `set -u` catches unset variables.',
+    bad: `#!/bin/bash
+set -e
+some_failing_step | grep needle # if some_failing_step fails, script keeps going`,
+    good: `#!/bin/bash
+set -euo pipefail
+some_failing_step | grep needle # any failure in the pipe aborts the script`,
+    lang: 'shell',
+    chainTo: 'invariant-guard',
+  },
+  'sh-unquoted-var': {
+    why: 'An unquoted `$var` is subject to word splitting (on `$IFS`) and glob expansion. A path with a space, a tab, or a `*` will silently do the wrong thing.',
+    bad: `if [ -d $dir ]; then echo yes; fi
+# If $dir = "/tmp/with space", expands to: [ -d /tmp/with space ] — syntax error`,
+    good: `if [ -d "$dir" ]; then echo yes; fi
+# Always quote. For arrays: "\${arr[@]}".`,
+    lang: 'shell',
+    chainTo: 'invariant-guard',
+  },
+  'sh-useless-cat-pipe': {
+    why: '`cat file | cmd` reads the file and pipes through `cat` just to feed `cmd`. Every command that takes a file argument can read it directly — one fewer process, clearer intent.',
+    bad: `cat access.log | grep "500"`,
+    good: `grep "500" access.log
+
+# Or stdin redirection if the command takes only stdin:
+cmd < access.log`,
+    lang: 'shell',
+    chainTo: null,
+  },
+  'sh-for-ls': {
+    why: '`for f in $(ls ...)` breaks on filenames with spaces, tabs, newlines, or globs. The output of `ls` is meant for humans, not programs. Use a glob or `find -print0 | xargs -0`.',
+    bad: `for f in $(ls *.txt); do
+  process "$f"  # breaks on "my file.txt"
+done`,
+    good: `# Glob directly
+for f in *.txt; do
+  process "$f"
+done
+
+# Or, when find is necessary
+find . -name '*.txt' -print0 | xargs -0 -n1 process`,
+    lang: 'shell',
+    chainTo: 'invariant-guard',
+  },
+};
+
+function render(rule, lang) {
+  const ex = EXAMPLES[rule.id];
+  if (!ex) throw new Error('No example authored for ' + rule.id);
+  const tags = [lang, rule.severity, ex.chainTo].filter(Boolean).join(', ');
+  const chain = ex.chainTo
+    ? `\n## Escalate to\n\nIf this pattern is widespread in the codebase, load **${ex.chainTo}** for the corrective workflow.\n`
+    : '';
+  return `---
+id: ${rule.id}
+title: ${rule.title.replace(/"/g, '\\"')}
+severity: ${rule.severity}
+impact: ${SEV_TO_IMPACT[rule.severity]}
+impactDescription: ${SEV_TO_DESC[rule.severity]}
+language: ${lang}
+tags: ${tags}
+---
+
+# ${rule.title}
+
+${ex.why}
+
+## Fix
+
+${rule.fix}
+
+## Incorrect
+
+\`\`\`${ex.lang}
+${ex.bad}
+\`\`\`
+
+## Correct
+
+\`\`\`${ex.lang}
+${ex.good}
+\`\`\`
+${chain}`;
+}
+
+const counts = {};
+const LANG_FILES = fs
+  .readdirSync(path.join(ROOT, 'rules'))
+  .filter((f) => f.endsWith('.json'))
+  .map((f) => f.replace(/\.json$/, ''));
+
+for (const langFile of LANG_FILES) {
+  const j = JSON.parse(fs.readFileSync(path.join(ROOT, 'rules', langFile + '.json'), 'utf8'));
+  counts[langFile] = 0;
+  for (const rule of j.rules) {
+    const out = render(rule, j.language);
+    fs.writeFileSync(path.join(OUT, rule.id + '.md'), out);
+    counts[langFile]++;
+  }
+}
+console.log('Generated rule docs:', counts);
+console.log('Total:', Object.values(counts).reduce((a, b) => a + b, 0));