lemmaly 0.1.0

package/skills/lemmaly/references/memory.md

@@ -0,0 +1,118 @@
+# Memory reference
+
+Memory bugs are quiet. They don't break tests. They get noticed when a process OOMs in production at 3am.
+
+## The big classes of leak
+
+### 1. Unbounded cache
+```js
+// Bad — grows forever
+const cache = new Map();
+function get(key) {
+  if (!cache.has(key)) cache.set(key, expensive(key));
+  return cache.get(key);
+}
+
+// Good — bounded
+import { LRUCache } from 'lru-cache';
+const cache = new LRUCache({ max: 1000, ttl: 1000 * 60 * 5 });
+```
+Any `Map` / `dict` keyed by user input is a candidate leak.
+
+### 2. Event listeners not removed
+```js
+// Bad — every component instance adds a listener; unmount doesn't remove it
+useEffect(() => {
+  window.addEventListener('resize', handler);
+}, []);
+
+// Good
+useEffect(() => {
+  window.addEventListener('resize', handler);
+  return () => window.removeEventListener('resize', handler);
+}, []);
+```
+Same for: `setInterval`, `setTimeout` (for long timers), `IntersectionObserver`, `MutationObserver`, EventEmitter `.on`, Postgres / Redis client subscriptions, WebSocket.
+
+### 3. Closures retaining large parents
+```js
+// Bad — handler closes over `largeData` even though it only uses `id`
+function makeHandler(largeData) {
+  const id = largeData.id;
+  return () => doStuff(id, largeData);   // largeData stays alive as long as handler exists
+}
+
+// Better — destructure what you need
+function makeHandler({ id }) {
+  return () => doStuff(id);
+}
+```
+Watch for: handlers attached to long-lived emitters, cached partial applications, React `useCallback` deps that include big objects.
+
+### 4. Detached DOM
+```js
+// Bad — node removed from DOM, but JS still references it
+const cache = { lastTooltip: tooltipEl };
+tooltipEl.remove();   // removed from DOM but cache still holds → not GC'd
+```
+Null out references when you're done.
+
+### 5. Streams not consumed / not closed
+```js
+// Bad — leaks file handle if `process` throws
+const stream = fs.createReadStream(path);
+await process(stream);
+
+// Good
+const stream = fs.createReadStream(path);
+try { await process(stream); } finally { stream.destroy(); }
+```
+Same for: DB cursors, HTTP responses (in Node, `res.on('data')` without consuming), child processes.
+
+### 6. Globals and module-level state
+A module-level `Map`, `Array`, or counter that's appended to from request handlers but never trimmed is a leak.
+
+## Buffer vs stream
+
+If the input can be unbounded (user upload, log file, ML response), **stream** it:
+
+```js
+// Bad — loads full body into memory
+const body = await req.text();
+const data = JSON.parse(body);
+
+// Good — streaming JSON parser, or process line-by-line
+import readline from 'readline';
+const rl = readline.createInterface({ input: req });
+for await (const line of rl) handle(JSON.parse(line));
+```
+
+In Python: read `chunk = f.read(64 * 1024)` in a loop, or use generators. Don't `f.read()` an arbitrary file.
+
+## Large objects in request scope
+
+Holding a 50 MB result set in memory per concurrent request → 50 reqs = 2.5 GB. Patterns:
+
+- Paginate. Don't return "all".
+- Project (`SELECT id, name`) — don't `SELECT *`.
+- Stream the response. In Node, write chunks to `res`. In Python/Django, `StreamingHttpResponse`.
+
+## "Deep clone to be safe" anti-pattern
+
+```js
+const copy = JSON.parse(JSON.stringify(huge));   // O(n) time + O(n) memory + breaks Dates, Maps, etc.
+```
+Almost always wrong. Either you need a true clone (use `structuredClone`) or you don't (just spread the keys you need).
+
+## Observable signs in prod
+
+- RSS / heap grows monotonically over hours and doesn't drop after low traffic → cache or listener leak.
+- Pods OOM-killed during long-running migrations → buffer instead of stream.
+- Latency P99 climbs slowly during a deploy's lifetime, drops at restart → GC pressure from leak.
+
+## Tools
+
+- Node: `node --inspect`, Chrome DevTools "Memory" → take heap snapshots over time, diff them.
+- Browser: same DevTools panel, "Detached elements" view for DOM leaks.
+- Python: `tracemalloc`, `objgraph` for retention paths.
+- Production: track RSS over time; alert on monotonic growth.

package/skills/lemmaly/references/n-plus-one.md

@@ -0,0 +1,139 @@
+# N+1 query reference
+
+The single most common performance bug shipped by AI assistants. One outer query, then one query per row.
+
+## How to spot it
+
+Any of these is N+1 until proven otherwise:
+
+```js
+// JS / TS
+for (const user of users) {
+  const posts = await db.post.findMany({ where: { userId: user.id } });
+}
+
+users.map(async u => await fetchProfile(u.id));        // hidden — runs in parallel but still N calls
+await Promise.all(users.map(u => fetchProfile(u.id))); // parallel — still N HTTP calls
+```
+
+```python
+# Python / Django
+for user in users:
+    posts = Post.objects.filter(user=user)              # N+1
+    profile = user.profile                              # N+1 if not select_related
+
+# SQLAlchemy
+for user in session.query(User).all():
+    print(user.posts)                                    # lazy load = N+1
+```
+
+```ruby
+# Active Record
+@users.each do |u|
+  puts u.posts.count    # N+1 + extra count query
+end
+```
+
+Heuristic: if the loop body calls anything that hits the DB, network, or filesystem — stop and batch.
+
+## Fixes — by ORM
+
+### Prisma (TS)
+```ts
+// Bad
+for (const u of users) { u.posts = await db.post.findMany({ where: { userId: u.id } }); }
+
+// Good — eager via include
+const users = await db.user.findMany({ include: { posts: true } });
+
+// Good — explicit batch
+const posts = await db.post.findMany({ where: { userId: { in: users.map(u => u.id) } } });
+const byUser = Map.groupBy(posts, p => p.userId);   // or reduce
+```
+
+### Drizzle (TS)
+```ts
+// Bad
+for (const u of users) await db.select().from(posts).where(eq(posts.userId, u.id));
+
+// Good
+const all = await db.select().from(posts).where(inArray(posts.userId, users.map(u => u.id)));
+```
+
+### Django
+```python
+# Bad
+for u in User.objects.all():
+    print(u.profile.bio)              # N+1
+
+# Good
+for u in User.objects.select_related('profile'):    # FK / OneToOne — JOIN
+    print(u.profile.bio)
+
+for u in User.objects.prefetch_related('posts'):    # reverse FK / M2M — batched IN query
+    print(list(u.posts.all()))
+```
+
+### SQLAlchemy
+```python
+# Bad: default lazy
+users = session.query(User).all()
+for u in users: u.posts            # N+1
+
+# Good
+from sqlalchemy.orm import selectinload, joinedload
+users = session.query(User).options(selectinload(User.posts)).all()
+```
+
+### Active Record (Ruby)
+```ruby
+# Bad
+@users.each { |u| u.posts.each { |p| ... } }
+
+# Good
+@users = User.includes(:posts)
+```
+
+## Raw SQL — the underlying fix
+
+All ORMs are doing one of these under the hood:
+
+```sql
+-- JOIN (good for 1:1 and small 1:many)
+SELECT u.*, p.*
+FROM users u
+LEFT JOIN posts p ON p.user_id = u.id
+WHERE u.tenant_id = $1;
+
+-- Two queries with IN (better when "many" is large — avoids row duplication)
+SELECT * FROM users WHERE tenant_id = $1;
+SELECT * FROM posts WHERE user_id IN ($1, $2, ..., $N);
+```
+
+Prefer the second form when the "many" side is wide. JOIN-then-group inflates payload by `O(parents * children)`.
+
+## DataLoader pattern (when you can't restructure)
+
+In GraphQL / per-request batching, where requests come in one at a time but you want to coalesce:
+
+```ts
+const userLoader = new DataLoader(async (ids) => {
+  const users = await db.user.findMany({ where: { id: { in: ids } } });
+  return ids.map(id => users.find(u => u.id === id));
+});
+
+// Now N parallel resolver calls become 1 batched query within the request tick.
+await Promise.all(userIds.map(id => userLoader.load(id)));
+```
+
+## When N+1 is actually fine (rare)
+
+- N is bounded and tiny (`n <= 5` forever, e.g. enum lookup).
+- The "loop" is async-streaming over an unbounded source (e.g. event-by-event processing where batching would break correctness).
+- Each call is to a different sharded service and cannot be batched.
+
+In all these cases, **leave a comment** stating why this is intentional, otherwise the next pass will "fix" it back into an N+1.
+
+## Quick mental test
+
+Read the code aloud: "for each user, fetch its posts". If you say "for each X, fetch Y" — it's N+1. Rephrase as: "fetch all posts for these users."

package/skills/lemmaly/rules/cpp-map-double-lookup.md

@@ -0,0 +1,38 @@
+---
+id: cpp-map-double-lookup
+title: map.count(k) then map[k] — two lookups; use find()
+severity: info
+impact: MEDIUM
+impactDescription: Suboptimal; flag when n is large or on a hot path
+language: cpp
+tags: cpp, info, complexity-cuts
+---
+
+# map.count(k) then map[k] — two lookups; use find()
+
+`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.
+
+## Fix
+
+Use `auto it = m.find(k); if (it != m.end()) use(it->second);` — one lookup.
+
+## Incorrect
+
+```cpp
+if (m.count(k)) {
+  use(m[k]); // second lookup
+}
+```
+
+## Correct
+
+```cpp
+auto it = m.find(k);
+if (it != m.end()) {
+  use(it->second);
+}
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **complexity-cuts** for the corrective workflow.

package/skills/lemmaly/rules/cpp-range-loop-copy.md

@@ -0,0 +1,33 @@
+---
+id: cpp-range-loop-copy
+title: Range-for `auto x` copies each element — use `const auto&` for non-trivial types
+severity: info
+impact: MEDIUM
+impactDescription: Suboptimal; flag when n is large or on a hot path
+language: cpp
+tags: cpp, info
+---
+
+# Range-for `auto x` copies each element — use `const auto&` for non-trivial types
+
+`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.
+
+## Fix
+
+Prefer `for (const auto& x : container)` unless you intentionally need a copy.
+
+## Incorrect
+
+```cpp
+for (auto s : large_strings) {
+  process(s); // s is a fresh copy each iteration
+}
+```
+
+## Correct
+
+```cpp
+for (const auto& s : large_strings) {
+  process(s); // reference, no copy
+}
+```

package/skills/lemmaly/rules/cpp-raw-new.md

@@ -0,0 +1,36 @@
+---
+id: cpp-raw-new
+title: Raw `new` outside of smart-pointer ctor — manual delete, exception-unsafe
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: cpp
+tags: cpp, warning, invariant-guard
+---
+
+# Raw `new` outside of smart-pointer ctor — manual delete, exception-unsafe
+
+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.
+
+## Fix
+
+Use `std::make_unique<T>(...)` or `std::make_shared<T>(...)`. Reserve raw `new` for placement-new or interop with C APIs.
+
+## Incorrect
+
+```cpp
+Widget* w = new Widget(42);
+configure(w);   // if this throws, w leaks
+delete w;
+```
+
+## Correct
+
+```cpp
+auto w = std::make_unique<Widget>(42);
+configure(w.get()); // destructs on every exit path, including throw
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **invariant-guard** for the corrective workflow.

package/skills/lemmaly/rules/cpp-string-concat-in-loop.md

@@ -0,0 +1,45 @@
+---
+id: cpp-string-concat-in-loop
+title: std::string += inside loop — O(n^2) without reserve()
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: cpp
+tags: cpp, warning, complexity-cuts
+---
+
+# std::string += inside loop — O(n^2) without reserve()
+
+`std::string::operator+=` past capacity reallocates. Without a `reserve`, repeated concatenation is O(n²). `std::ostringstream` or one `reserve` fixes it.
+
+## Fix
+
+Call `s.reserve(total)` once if size known, or accumulate into a `std::ostringstream` and call `.str()` at the end.
+
+## Incorrect
+
+```cpp
+std::string s;
+for (const auto& part : parts) {
+  s += part;
+}
+```
+
+## Correct
+
+```cpp
+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;
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **complexity-cuts** for the corrective workflow.

package/skills/lemmaly/rules/cpp-vector-push-no-reserve.md

@@ -0,0 +1,40 @@
+---
+id: cpp-vector-push-no-reserve
+title: vector push_back in loop without reserve() — log-amortized reallocation
+severity: info
+impact: MEDIUM
+impactDescription: Suboptimal; flag when n is large or on a hot path
+language: cpp
+tags: cpp, info, complexity-cuts
+---
+
+# vector push_back in loop without reserve() — log-amortized reallocation
+
+`std::vector::push_back` past the current capacity doubles the backing array and copies/moves every element. Calling `reserve(n)` first does one allocation.
+
+## Fix
+
+Call `v.reserve(n)` before the loop when n is known.
+
+## Incorrect
+
+```cpp
+std::vector<int> v;
+for (int i = 0; i < n; ++i) {
+  v.push_back(compute(i)); // reallocates log(n) times
+}
+```
+
+## Correct
+
+```cpp
+std::vector<int> v;
+v.reserve(n);
+for (int i = 0; i < n; ++i) {
+  v.push_back(compute(i));
+}
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **complexity-cuts** for the corrective workflow.

package/skills/lemmaly/rules/cs-async-void.md

@@ -0,0 +1,45 @@
+---
+id: cs-async-void
+title: async void — exceptions are unobserved and crash the process
+severity: error
+impact: CRITICAL
+impactDescription: Will break or scale-fail in production
+language: csharp
+tags: csharp, error, invariant-guard
+---
+
+# async void — exceptions are unobserved and crash the process
+
+`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`).
+
+## Fix
+
+Return Task. async void is only acceptable for true event handlers (OnClick, etc.).
+
+## Incorrect
+
+```csharp
+public async void DoWork() {
+  await Task.Delay(100);
+  throw new Exception("boom"); // crashes the process
+}
+```
+
+## Correct
+
+```csharp
+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"); }
+}
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **invariant-guard** for the corrective workflow.

package/skills/lemmaly/rules/cs-disposable-no-using.md

@@ -0,0 +1,32 @@
+---
+id: cs-disposable-no-using
+title: IDisposable allocated without using — leak on exception
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: csharp
+tags: csharp, warning
+---
+
+# IDisposable allocated without using — leak on exception
+
+`IDisposable` resources allocated without `using` leak if an exception fires before `Dispose()`. `using var` ensures cleanup even on throw.
+
+## Fix
+
+Wrap in `using var x = new ...;` or `using (var x = ...) { }`.
+
+## Incorrect
+
+```csharp
+var stream = new FileStream(path, FileMode.Open);
+var data = ReadAll(stream); // if this throws, stream is never disposed
+stream.Dispose();
+```
+
+## Correct
+
+```csharp
+using var stream = new FileStream(path, FileMode.Open);
+var data = ReadAll(stream); // disposed on every exit path
+```

package/skills/lemmaly/rules/cs-list-contains-in-loop.md

@@ -0,0 +1,36 @@
+---
+id: cs-list-contains-in-loop
+title: List.Contains inside LINQ/loop — O(n*m); use HashSet<T>
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: csharp
+tags: csharp, warning, complexity-cuts
+---
+
+# List.Contains inside LINQ/loop — O(n*m); use HashSet<T>
+
+`List<T>.Contains` is O(n). Inside LINQ over m items it is O(n·m). `HashSet<T>` is O(1).
+
+## Fix
+
+Convert to HashSet once: `var s = new HashSet<T>(list); s.Contains(x);`
+
+## Incorrect
+
+```csharp
+// O(n·m)
+var active = users.Where(u => !banned.Contains(u.Id)).ToList();
+```
+
+## Correct
+
+```csharp
+// O(n+m)
+var bannedSet = new HashSet<int>(banned);
+var active = users.Where(u => !bannedSet.Contains(u.Id)).ToList();
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **complexity-cuts** for the corrective workflow.

package/skills/lemmaly/rules/cs-string-concat-in-loop.md

@@ -0,0 +1,42 @@
+---
+id: cs-string-concat-in-loop
+title: string += inside loop — O(n^2) on immutable string
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: csharp
+tags: csharp, warning, complexity-cuts
+---
+
+# string += inside loop — O(n^2) on immutable string
+
+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.
+
+## Fix
+
+Use StringBuilder: `var sb = new StringBuilder(); foreach (...) sb.Append(x); sb.ToString();`
+
+## Incorrect
+
+```csharp
+// O(n²)
+string s = "";
+foreach (var line in lines) {
+  s += line + "\n";
+}
+```
+
+## Correct
+
+```csharp
+// O(n)
+var sb = new StringBuilder(lines.Count * 80);
+foreach (var line in lines) {
+  sb.Append(line).Append('\n');
+}
+var s = sb.ToString();
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **complexity-cuts** for the corrective workflow.

package/skills/lemmaly/rules/go-defer-in-loop.md

@@ -0,0 +1,39 @@
+---
+id: go-defer-in-loop
+title: defer inside loop — defers accumulate until function returns
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: go
+tags: go, warning
+---
+
+# defer inside loop — defers accumulate until function returns
+
+`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.
+
+## Fix
+
+Wrap the body in a function so each iteration's defer fires at iteration end, or close resources explicitly.
+
+## Incorrect
+
+```go
+for _, f := range files {
+  fp, _ := os.Open(f)
+  defer fp.Close() // accumulates; nothing closes until the outer function returns
+  process(fp)
+}
+```
+
+## Correct
+
+```go
+for _, f := range files {
+  func() {
+    fp, _ := os.Open(f)
+    defer fp.Close() // closes at end of this iteration
+    process(fp)
+  }()
+}
+```

package/skills/lemmaly/rules/go-err-not-checked.md

@@ -0,0 +1,38 @@
+---
+id: go-err-not-checked
+title: Error return value discarded — silent failures
+severity: warning
+impact: HIGH
+impactDescription: Hot-path or correctness risk at realistic n
+language: go
+tags: go, warning, invariant-guard
+---
+
+# Error return value discarded — silent failures
+
+Discarding the error return with `_` is silent failure. The function looks like it succeeded; downstream code sees zero values and behaves unpredictably.
+
+## Fix
+
+Handle the error or comment why it is safe to ignore (`_ = err // <reason>`).
+
+## Incorrect
+
+```go
+data, _ := os.ReadFile(path)
+return parse(data) // parse on empty buffer if file missing
+```
+
+## Correct
+
+```go
+data, err := os.ReadFile(path)
+if err != nil {
+  return nil, fmt.Errorf("read %s: %w", path, err)
+}
+return parse(data), nil
+```
+
+## Escalate to
+
+If this pattern is widespread in the codebase, load **invariant-guard** for the corrective workflow.