periderm-cli 0.1.62 → 0.1.63

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,8 +8,8 @@
8
8
  import traverseDefault from "@babel/traverse";
9
9
  import { reportCliError } from "../error-report.js";
10
10
  // @babel/traverse ships CJS; pick the default export defensively.
11
- const traverse = traverseDefault.default
12
- ?? traverseDefault;
11
+ const traverse = traverseDefault.default ??
12
+ traverseDefault;
13
13
  const lineOf = (source, idx) => source.slice(0, idx).split("\n").length;
14
14
  function stripStrings(source) {
15
15
  return source.replace(/`[^`]*`|"[^"\n]*"|'[^'\n]*'/g, "''");
@@ -47,7 +47,8 @@ const silentCatch = (source, file, ast) => {
47
47
  id: "silent-catch",
48
48
  category: "Runtime Stability",
49
49
  severity: "high",
50
- file, line: p.node.loc?.start.line ?? 1,
50
+ file,
51
+ line: p.node.loc?.start.line ?? 1,
51
52
  message: "Empty catch block swallows errors.",
52
53
  why: "When this fails, you and your users will have no idea. Bugs become invisible, support tickets get vague.",
53
54
  fix: "Log the error with context, surface a user-facing error state, or report to your error tracker.",
@@ -59,17 +60,18 @@ const silentCatch = (source, file, ast) => {
59
60
  if (stmt.type !== "ExpressionStatement")
60
61
  return false;
61
62
  const e = stmt.expression;
62
- return e.type === "CallExpression"
63
- && e.callee.type === "MemberExpression"
64
- && e.callee.object.type === "Identifier"
65
- && e.callee.object.name === "console";
63
+ return (e.type === "CallExpression" &&
64
+ e.callee.type === "MemberExpression" &&
65
+ e.callee.object.type === "Identifier" &&
66
+ e.callee.object.name === "console");
66
67
  });
67
68
  if (onlyConsole) {
68
69
  out.push(mkFinding({
69
70
  id: "silent-catch-console",
70
71
  category: "Runtime Stability",
71
72
  severity: "medium",
72
- file, line: p.node.loc?.start.line ?? 1,
73
+ file,
74
+ line: p.node.loc?.start.line ?? 1,
73
75
  message: "Catch block only logs — no recovery, no user feedback.",
74
76
  why: "Logging is not handling. Your users will still see a broken UI or stuck spinner.",
75
77
  fix: "Set an error state, retry, or render a fallback. console.error is for you; users need a visible signal.",
@@ -99,7 +101,8 @@ const envLeak = (source, file) => {
99
101
  id: "env-leak",
100
102
  category: "Security",
101
103
  severity: "critical",
102
- file, line: lineOf(source, m.index),
104
+ file,
105
+ line: lineOf(source, m.index),
103
106
  message: `Secret-shaped env var \`${name}\` accessed in a non-server file.`,
104
107
  why: "If this file ships to the client, the secret leaks. Bundlers inline process.env at build time.",
105
108
  fix: "Move the read into a server function / server route, or rename + expose only via VITE_ if it's truly public.",
@@ -121,7 +124,8 @@ const tsIgnore = (source, file) => {
121
124
  id: "ts-ignore",
122
125
  category: "Data Integrity",
123
126
  severity: "medium",
124
- file, line: lineOf(source, m.index),
127
+ file,
128
+ line: lineOf(source, m.index),
125
129
  message: `\`${m[1].trim()}\` suppresses a real type error.`,
126
130
  why: "Suppressed type errors are bug seeds. They almost always become runtime errors under unexpected input.",
127
131
  fix: "Fix the type, narrow the value, or accept it explicitly with a typed assertion that documents why.",
@@ -150,10 +154,11 @@ const imgAlt = (source, file, ast) => {
150
154
  id: "img-alt",
151
155
  category: "Accessibility",
152
156
  severity: "medium",
153
- file, line: p.node.loc?.start.line ?? 1,
157
+ file,
158
+ line: p.node.loc?.start.line ?? 1,
154
159
  message: "<img> is missing an `alt` attribute.",
155
- why: "Screen readers can't describe it, and if the image fails to load there's no fallback text.",
156
- fix: "Add a descriptive `alt`. Use `alt=\"\"` only for purely decorative images.",
160
+ why: "Screen readers can't describe it, and if the image fails to load there's nothing to fall back on. Missing alt text fails WCAG 1.1.1 — one of the most common findings in ADA/EAA audits — and costs you twice: assistive-tech users lose the content, and search engines lose the image's context, hurting your SEO.",
161
+ fix: 'Add a descriptive `alt`. Use `alt=""` only for purely decorative images.',
157
162
  aiPrompt: `In ${file} near line ${p.node.loc?.start.line ?? 1}, add a descriptive alt attribute to the <img> element. If decorative, use alt="".`,
158
163
  }));
159
164
  }
@@ -184,10 +189,11 @@ const clickableDiv = (source, file, ast) => {
184
189
  id: "clickable-div",
185
190
  category: "Accessibility",
186
191
  severity: "medium",
187
- file, line: p.node.loc?.start.line ?? 1,
192
+ file,
193
+ line: p.node.loc?.start.line ?? 1,
188
194
  message: `<${n.name}> has onClick but no role/keyboard handler.`,
189
- why: "Keyboard users can't activate it. Screen readers won't announce it as interactive.",
190
- fix: "Use a <button>, or add role=\"button\", tabIndex={0} and an onKeyDown that fires on Enter/Space.",
195
+ why: "Keyboard users can't activate it and screen readers won't announce it as interactive — for users with motor or vision disabilities this control might as well not exist. It fails WCAG 2.1.1 (Keyboard) & 4.1.2, both part of the WCAG 2.1 AA bar used in ADA/EAA enforcement, and it's a direct blocker for anyone navigating by keyboard.",
196
+ fix: 'Use a <button>, or add role="button", tabIndex={0} and an onKeyDown that fires on Enter/Space.',
191
197
  aiPrompt: `In ${file} near line ${p.node.loc?.start.line ?? 1}, replace this clickable <${n.name}> with a <button>, or add role="button", tabIndex={0}, and an onKeyDown handler that triggers on Enter and Space.`,
192
198
  }));
193
199
  }
@@ -207,7 +213,8 @@ const nPlusOne = (source, file) => {
207
213
  id: "n-plus-one",
208
214
  category: "Runaway Cloud Costs",
209
215
  severity: "high",
210
- file, line: lineOf(source, m.index),
216
+ file,
217
+ line: lineOf(source, m.index),
211
218
  message: "Awaited network call inside .map() — N+1 pattern.",
212
219
  why: "One user action = N sequential round trips. Slow for users, expensive on serverless / paid APIs.",
213
220
  fix: "Batch the request, use Promise.all on a mapped array of promises, or move the loop into a single SQL/API query.",
@@ -238,7 +245,8 @@ const recursiveRunaway = (source, file, ast) => {
238
245
  id: "recursive-runaway",
239
246
  category: "Runaway Cloud Costs",
240
247
  severity: "critical",
241
- file, line: p.node.loc?.start.line ?? 1,
248
+ file,
249
+ line: p.node.loc?.start.line ?? 1,
242
250
  message: `Function \`${name}\` calls itself with no visible termination guard.`,
243
251
  why: "On serverless this can bill you for a weekend. Locally it crashes with a stack overflow on first run.",
244
252
  fix: "Add a base case (if/return) and a hard recursion-depth limit. Consider rewriting as a loop.",
@@ -265,7 +273,8 @@ const dangerousHtml = (source, file) => {
265
273
  id: "dangerous-html",
266
274
  category: "Security",
267
275
  severity: "high",
268
- file, line: lineOf(source, m.index),
276
+ file,
277
+ line: lineOf(source, m.index),
269
278
  message: "dangerouslySetInnerHTML with a non-literal value (XSS risk).",
270
279
  why: "If any part of that value came from a user or an API, you have an XSS vector.",
271
280
  fix: "Sanitize with DOMPurify before injecting, or render through React text/markdown components.",
@@ -295,7 +304,8 @@ const deadLink = (source, file) => {
295
304
  id: "raw-anchor-route",
296
305
  category: "Routing & Navigation",
297
306
  severity: "medium",
298
- file, line: lineOf(source, m.index),
307
+ file,
308
+ line: lineOf(source, m.index),
299
309
  message: `Raw <a href="${m[1]}"> in a router-aware file — bypasses type-safe routing.`,
300
310
  why: "If the route is renamed or removed, the type checker won't flag the broken link. Users hit a dead end.",
301
311
  fix: `Use <Link to="${m[1]}"> from @tanstack/react-router so the route is type-checked.`,
@@ -322,7 +332,8 @@ const missingCleanup = (source, file) => {
322
332
  id: "missing-cleanup",
323
333
  category: "Runtime Stability",
324
334
  severity: "high",
325
- file, line: lineOf(source, m.index),
335
+ file,
336
+ line: lineOf(source, m.index),
326
337
  message: "useEffect sets up an interval/listener/subscription but returns no cleanup.",
327
338
  why: "On every re-render or unmount you leak a timer or listener. The page slows, costs climb, and weird bugs appear.",
328
339
  fix: "Return a cleanup function from the effect that clears the interval / removes the listener / unsubscribes.",
@@ -345,7 +356,10 @@ const hardcodedSecret = (source, file) => {
345
356
  [/AKIA[0-9A-Z]{16}/g, "AWS access key id"],
346
357
  [/AIza[0-9A-Za-z_\-]{30,}/g, "Google API key"],
347
358
  [/gsk_[A-Za-z0-9]{40,}/g, "Groq API key"],
348
- [/eyJ[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}/g, "JWT / Supabase service-role-shaped token"],
359
+ [
360
+ /eyJ[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}/g,
361
+ "JWT / Supabase service-role-shaped token",
362
+ ],
349
363
  ];
350
364
  for (const [re, label] of patterns) {
351
365
  let m;
@@ -354,7 +368,8 @@ const hardcodedSecret = (source, file) => {
354
368
  id: "hardcoded-secret",
355
369
  category: "Security",
356
370
  severity: "critical",
357
- file, line: lineOf(source, m.index),
371
+ file,
372
+ line: lineOf(source, m.index),
358
373
  message: `Hardcoded ${label} detected in source.`,
359
374
  why: "Anyone who reads the repo (or the built JS bundle) gets your key. Rotate it immediately.",
360
375
  fix: "Move the value into a server-only secret (Lovable Cloud / process.env), rotate the leaked key, and read it inside a server function.",
@@ -380,7 +395,8 @@ const consoleLog = (source, file) => {
380
395
  id: "console-log-prod",
381
396
  category: "Observability",
382
397
  severity: "low",
383
- file, line: lineOf(source, idx),
398
+ file,
399
+ line: lineOf(source, idx),
384
400
  message: `console.log left in source (${matches.length} occurrence${matches.length === 1 ? "" : "s"}).`,
385
401
  why: "Production logs are noisy at best and leak data at worst (tokens, user emails, internal IDs).",
386
402
  fix: "Remove debug logs, or route through a logger you can disable in production.",
@@ -408,7 +424,8 @@ const todoLeftover = (source, file) => {
408
424
  id: "todo-leftover",
409
425
  category: "Polish & Embarrassment Risks",
410
426
  severity: "low",
411
- file, line: lineOf(source, firstIdx),
427
+ file,
428
+ line: lineOf(source, firstIdx),
412
429
  message: `${count} TODO/FIXME comment${count === 1 ? "" : "s"} left in source.`,
413
430
  why: "Leftover TODOs are unspoken known-issues. They become bug reports the day after launch.",
414
431
  fix: "Resolve, file as a tracked issue, or delete.",
@@ -431,7 +448,8 @@ const placeholderContent = (source, file) => {
431
448
  id: "placeholder-content",
432
449
  category: "Polish & Embarrassment Risks",
433
450
  severity: "medium",
434
- file, line: lineOf(source, m.index),
451
+ file,
452
+ line: lineOf(source, m.index),
435
453
  message: `Placeholder content detected: "${m[1]}".`,
436
454
  why: "Visible placeholder content is the #1 sign of an unfinished app. Users notice instantly.",
437
455
  fix: "Replace with real copy, or remove the section until it's ready.",
@@ -452,14 +470,15 @@ const unhandledFetch = (source, file) => {
452
470
  while ((m = re.exec(source))) {
453
471
  // Look 200 chars in either direction for .catch or try
454
472
  const window = source.slice(Math.max(0, m.index - 80), m.index + 400);
455
- const handled = /\.catch\s*\(|try\s*\{[\s\S]*?await\s+[\s\S]{0,40}fetch/.test(window)
456
- || /try\s*\{/.test(source.slice(Math.max(0, m.index - 200), m.index));
473
+ const handled = /\.catch\s*\(|try\s*\{[\s\S]*?await\s+[\s\S]{0,40}fetch/.test(window) ||
474
+ /try\s*\{/.test(source.slice(Math.max(0, m.index - 200), m.index));
457
475
  if (!handled) {
458
476
  out.push(mkFinding({
459
477
  id: "unhandled-fetch",
460
478
  category: "Runtime Stability",
461
479
  severity: "high",
462
- file, line: lineOf(source, m.index),
480
+ file,
481
+ line: lineOf(source, m.index),
463
482
  message: "fetch call has no visible .catch or try/catch.",
464
483
  why: "Network requests fail. Without a catch, the UI silently breaks and the user has no idea why.",
465
484
  fix: "Wrap in try/catch (for await) or chain .catch — set an error state and surface a retry path.",
@@ -484,7 +503,8 @@ const unsafeUserAccess = (source, file) => {
484
503
  id: "unsafe-user-access",
485
504
  category: "Reality & Resilience",
486
505
  severity: "high",
487
- file, line: lineOf(source, m.index),
506
+ file,
507
+ line: lineOf(source, m.index),
488
508
  message: `\`${m[0]}\` assumes nested user data exists.`,
489
509
  why: "Real users often have missing avatars, names, or phones. This crashes the UI with 'Cannot read properties of undefined'.",
490
510
  fix: "Use optional chaining (`?.`) and provide a fallback. Render a default avatar / placeholder string when data is missing.",
@@ -500,12 +520,14 @@ const sourceMaps = (source, file) => {
500
520
  const out = [];
501
521
  if (!/(vite|next|webpack)\.config\.(ts|js)$/.test(file))
502
522
  return out;
503
- if (/sourcemap:\s*true/.test(source) && !/process\.env\.NODE_ENV\s*===\s*['"]development['"]/.test(source)) {
523
+ if (/sourcemap:\s*true/.test(source) &&
524
+ !/process\.env\.NODE_ENV\s*===\s*['"]development['"]/.test(source)) {
504
525
  out.push(mkFinding({
505
526
  id: "exposed-sourcemaps",
506
527
  category: "Security",
507
528
  severity: "medium",
508
- file, line: 1,
529
+ file,
530
+ line: 1,
509
531
  message: "Source maps enabled in production.",
510
532
  why: "Source maps expose your original, unminified source code to everyone.",
511
533
  fix: "Set sourcemap to false in production, or restrict access to source maps.",
@@ -526,14 +548,16 @@ const unauthAdmin = (source, file) => {
526
548
  // Routes inside _authenticated/ are protected by the parent layout's beforeLoad.
527
549
  if (/_authenticated[/\\]/.test(file))
528
550
  return out;
529
- const isRoute = /export const Route =|createFileRoute/i.test(source) || /export default function /i.test(source);
551
+ const isRoute = /export const Route =|createFileRoute/i.test(source) ||
552
+ /export default function /i.test(source);
530
553
  const hasAuth = /useAuth|getUser|requireAuth|protected|middleware/i.test(source);
531
554
  if (isRoute && !hasAuth && !/components?\/|lib\//.test(file)) {
532
555
  out.push(mkFinding({
533
556
  id: "unauth-admin",
534
557
  category: "Security",
535
558
  severity: "critical",
536
- file, line: 1,
559
+ file,
560
+ line: 1,
537
561
  message: "Admin page missing authentication check.",
538
562
  why: "Anyone who guesses the URL can access your admin dashboard.",
539
563
  fix: "Add an authentication check (e.g. getUser()) and redirect unauthenticated users.",
@@ -557,7 +581,8 @@ const missingRateLimit = (source, file) => {
557
581
  id: "missing-rate-limit",
558
582
  category: "Runaway Cloud Costs",
559
583
  severity: "high",
560
- file, line: 1,
584
+ file,
585
+ line: 1,
561
586
  message: "API endpoint touching paid service lacks rate limiting.",
562
587
  why: "A malicious user (or buggy script) can drain your API credits or run up thousands of dollars in charges.",
563
588
  fix: "Add a rate limiter (e.g., Upstash Redis) to restrict requests per IP or user.",
@@ -582,7 +607,8 @@ const idorDataFetch = (source, file) => {
582
607
  id: "idor-data-fetch",
583
608
  category: "Security",
584
609
  severity: "critical",
585
- file, line: lineOf(source, m.index),
610
+ file,
611
+ line: lineOf(source, m.index),
586
612
  message: "Fetching record by ID without checking user ownership.",
587
613
  why: "Taking a user URL into another PC or browser gives access to that user's data (IDOR).",
588
614
  fix: "Chain \`.eq('user_id', auth.uid)\` to the query so users can only access their own records.",
@@ -617,7 +643,8 @@ const deadEndPage = (source, file) => {
617
643
  id: "dead-end-page",
618
644
  category: "Routing & Navigation",
619
645
  severity: "high",
620
- file, line: 1,
646
+ file,
647
+ line: 1,
621
648
  message: "Page appears to be a dead end with no layout or navigation links.",
622
649
  why: "If a user lands on this page, they cannot navigate away without using the browser's back button. This traps users.",
623
650
  fix: "Wrap the page content in your application's layout component (e.g., <DashShell>) or add a <Link> back to the previous page.",
@@ -650,7 +677,7 @@ const dbPollingAbuse = (source, file) => {
650
677
  file,
651
678
  line: lineOf(source, m.index),
652
679
  message: `${label} set to ${ms}ms — polling the database/API several times per second.`,
653
- why: "Vibecoded \"live feedback\" loops hammer your DB/API on every tab open. On Supabase/Firebase/serverless this can burn through free tiers and bankrupt you overnight. Use websockets, Supabase Realtime, or SSE instead.",
680
+ why: 'Vibecoded "live feedback" loops hammer your DB/API on every tab open. On Supabase/Firebase/serverless this can burn through free tiers and bankrupt you overnight. Use websockets, Supabase Realtime, or SSE instead.',
654
681
  fix: "Replace polling with Supabase Realtime (.channel/.subscribe), WebSockets, or server-sent events. If you must poll, use ≥30s intervals and pause when the tab is hidden.",
655
682
  aiPrompt: `In ${file} near line ${lineOf(source, m.index)}, ${label} is ${ms}ms — far too aggressive for live updates. Refactor to Supabase Realtime channels or WebSockets for push updates, or raise the interval to 30s+ with visibility-based pausing.`,
656
683
  }));
@@ -689,7 +716,7 @@ const dbPollingAbuse = (source, file) => {
689
716
  file,
690
717
  line: lineOf(source, m.index),
691
718
  message: "useEffect sets up interval polling against the database/API.",
692
- why: "Polling in useEffect is a common vibecoder pattern for \"live\" dashboards. It scales linearly with users and tabs, unlike websocket subscriptions.",
719
+ why: 'Polling in useEffect is a common vibecoder pattern for "live" dashboards. It scales linearly with users and tabs, unlike websocket subscriptions.',
693
720
  fix: "Switch to Supabase Realtime subscriptions or WebSockets. Add cleanup if you keep any polling.",
694
721
  aiPrompt: `In ${file} near line ${lineOf(source, m.index)}, useEffect starts interval polling for data. Replace with a Realtime subscription (supabase.channel) or WebSocket listener, and return an unsubscribe cleanup.`,
695
722
  }));
@@ -741,10 +768,11 @@ const iconButtonNoLabel = (source, file) => {
741
768
  id: "icon-only-no-label",
742
769
  category: "Accessibility",
743
770
  severity: "high",
744
- file, line: lineOf(source, m.index),
771
+ file,
772
+ line: lineOf(source, m.index),
745
773
  message: `Icon-only <${m[1]}> has no accessible name.`,
746
- why: "Screen readers announce this control as 'button' with no label. Keyboard and assistive-tech users can't tell what it does. WCAG 2.1 SC 4.1.2 (Name, Role, Value).",
747
- fix: "Add aria-label=\"...\" (or wrap the icon with a visually-hidden <span className=\"sr-only\">Description</span>).",
774
+ why: "Screen readers announce this control as 'button' with no label, so keyboard and assistive-tech users can't tell what it does and can't reliably complete the action. This fails WCAG 2.1 SC 4.1.2 (Name, Role, Value) — the de facto bar in ADA Title III and EU European Accessibility Act enforcement: thousands of US web-accessibility lawsuits are filed every year, and WCAG 2.1 AA failures are what they cite. For the ~1 in 6 people living with a disability, an unnamed control is a dead end.",
775
+ fix: 'Add aria-label="..." (or wrap the icon with a visually-hidden <span className="sr-only">Description</span>).',
748
776
  aiPrompt: `In ${file} near line ${lineOf(source, m.index)}, an icon-only <${m[1]}> has no accessible text. Infer intent from surrounding code and add aria-label (or an sr-only span) describing the action.`,
749
777
  }));
750
778
  reported++;
@@ -774,26 +802,26 @@ const formInputNoLabel = (source, file) => {
774
802
  while (i < source.length && i < m.index + 1200) {
775
803
  const ch = source[i];
776
804
  if (inStr) {
777
- if (ch === inStr && source[i - 1] !== '\\')
805
+ if (ch === inStr && source[i - 1] !== "\\")
778
806
  inStr = null;
779
807
  }
780
- else if (ch === '"' || ch === "'" || ch === '`') {
808
+ else if (ch === '"' || ch === "'" || ch === "`") {
781
809
  inStr = ch;
782
810
  }
783
- else if (ch === '{') {
811
+ else if (ch === "{") {
784
812
  // Skip balanced braces (JSX expression attributes like onChange={...})
785
813
  let depth = 1;
786
814
  i++;
787
815
  while (i < source.length && depth > 0) {
788
- if (source[i] === '{')
816
+ if (source[i] === "{")
789
817
  depth++;
790
- else if (source[i] === '}')
818
+ else if (source[i] === "}")
791
819
  depth--;
792
820
  i++;
793
821
  }
794
822
  continue;
795
823
  }
796
- else if (ch === '>') {
824
+ else if (ch === ">") {
797
825
  closeIdx = i;
798
826
  break;
799
827
  }
@@ -822,10 +850,11 @@ const formInputNoLabel = (source, file) => {
822
850
  id: "input-no-label",
823
851
  category: "Accessibility",
824
852
  severity: "medium",
825
- file, line: lineOf(source, m.index),
853
+ file,
854
+ line: lineOf(source, m.index),
826
855
  message: `<${tag}> has no associated <label> or aria-label.`,
827
- why: "Screen readers announce the field with no name. Disabled users have no idea what to type. Violates WCAG 2.1 SC 1.3.1 & 3.3.2.",
828
- fix: "Either wrap the field in a <label>, add htmlFor={id}, or set aria-label=\"...\" on the field itself.",
856
+ why: "Screen readers announce the field with no name, so assistive-tech users have to guess what to type — they mistype or abandon the form entirely. This violates WCAG 2.1 SC 1.3.1 & 3.3.2, the standard referenced in ADA Title III and EU EAA enforcement; unlabeled form fields are a common basis for accessibility demand letters, and every abandoned form is a lost signup or sale.",
857
+ fix: 'Either wrap the field in a <label>, add htmlFor={id}, or set aria-label="..." on the field itself.',
829
858
  aiPrompt: `In ${file} near line ${lineOf(source, m.index)}, the <${tag}> is missing a label. Add a <label htmlFor="..."> or aria-label describing what the user should enter.`,
830
859
  }));
831
860
  reported++;
@@ -850,9 +879,10 @@ const tabIndexPositive = (source, file) => {
850
879
  id: "positive-tabindex",
851
880
  category: "Accessibility",
852
881
  severity: "medium",
853
- file, line: lineOf(source, m.index),
882
+ file,
883
+ line: lineOf(source, m.index),
854
884
  message: `tabIndex={${val}} forces a manual tab order.`,
855
- why: "Any positive tabIndex hijacks the natural document order. Keyboard users end up on random elements first, and it desyncs the moment new fields are added. WCAG 2.4.3 (Focus Order).",
885
+ why: "A positive tabIndex hijacks the natural document order — keyboard users land on random elements first, and it desyncs the moment the page changes. This breaks WCAG 2.4.3 (Focus Order), part of the WCAG 2.1 AA bar used in ADA/EAA enforcement; for keyboard-dependent users it can make your core flow unusable, which is exactly the kind of failure automated audits flag.",
856
886
  fix: "Use tabIndex={0} to make an element focusable, or tabIndex={-1} for programmatic focus. Never a positive value.",
857
887
  aiPrompt: `In ${file} near line ${lineOf(source, m.index)}, replace tabIndex={${val}} with tabIndex={0} (focusable in DOM order) or restructure the DOM so the natural order matches the intended focus flow.`,
858
888
  }));
@@ -880,9 +910,10 @@ const autoFocusStealsFocus = (source, file) => {
880
910
  id: "autofocus-on-load",
881
911
  category: "Accessibility",
882
912
  severity: "medium",
883
- file, line: lineOf(source, idx),
913
+ file,
914
+ line: lineOf(source, idx),
884
915
  message: "autoFocus used outside a modal/dialog scrolls and steals focus on page load.",
885
- why: "Screen-reader users lose their place, keyboard users are yanked past the header, and the page jumps for everyone. WCAG 2.4.3 & 3.2.1.",
916
+ why: "Screen-reader users lose their place, keyboard users get yanked past the header, and the page visibly jumps for everyone. It fails WCAG 2.4.3 & 3.2.1, and focus theft on load is a documented reason assistive-tech users leave a page immediately — and a recurring complaint in accessibility feedback and audits.",
886
917
  fix: "Remove autoFocus on landing pages/forms. Only use it after an intentional user action opens a dialog.",
887
918
  aiPrompt: `In ${file}, remove the autoFocus attribute unless it lives inside a modal/dialog that was just opened by user action.`,
888
919
  }));
@@ -910,7 +941,8 @@ const sqlStringConcat = (source, file) => {
910
941
  id: "sql-string-concat",
911
942
  category: "Security",
912
943
  severity: "critical",
913
- file, line: lineOf(source, m.index),
944
+ file,
945
+ line: lineOf(source, m.index),
914
946
  message: "Raw SQL built from string interpolation / concatenation.",
915
947
  why: "Any value that came from a user, URL, or fetch body can inject SQL. This is one of the oldest and still most-exploited vulnerabilities.",
916
948
  fix: "Use parameterised queries: pg → client.query('... WHERE id = $1', [id]); Prisma → $queryRaw`...${Prisma.sql`...`}`; Knex → knex('t').where({id}).",
@@ -940,7 +972,8 @@ const mysqlNoUtf8mb4 = (source, file) => {
940
972
  id: "mysql-not-utf8mb4",
941
973
  category: "Reality & Resilience",
942
974
  severity: "high",
943
- file, line: lineOf(source, Math.max(idx, 0)),
975
+ file,
976
+ line: lineOf(source, Math.max(idx, 0)),
944
977
  message: "MySQL/MariaDB connection does not set charset: 'utf8mb4'.",
945
978
  why: "The default 'utf8' in MySQL is really 3-byte utf8, so any 4-byte character (every emoji, plus loads of CJK and math symbols) will throw 'Incorrect string value' the first time a real user pastes one. This bricks signups, comments and chat messages.",
946
979
  fix: "Pass { charset: 'utf8mb4' } to createPool/createConnection AND make sure the table + column collation is utf8mb4 (e.g. utf8mb4_unicode_ci).",
@@ -957,12 +990,30 @@ const heavyLibImport = (source, file) => {
957
990
  return out;
958
991
  // package → { human size, lighter alternative }
959
992
  const heavy = {
960
- "moment": { size: "~290 KB min", fix: "swap for dayjs (~7 KB) or date-fns (per-function imports)" },
961
- "lodash": { size: "~70 KB min", fix: "import per-method (`import debounce from 'lodash/debounce'`) or use lodash-es with a bundler that tree-shakes" },
962
- "chart.js": { size: "~180 KB min", fix: "use the tree-shakable subpath imports (`import { Chart, LineController, ... } from 'chart.js'`) and only register what you draw" },
963
- "rxjs": { size: "~140 KB min", fix: "import operators from 'rxjs/operators' individually, or drop RxJS if you only need a couple of observables" },
964
- "three": { size: "~600 KB min", fix: "lazy-load the 3D route with React.lazy / dynamic import so it isn't in the initial bundle" },
965
- "jquery": { size: "~90 KB min", fix: "delete jQuery — every browser since 2015 covers the same API natively" },
993
+ moment: {
994
+ size: "~290 KB min",
995
+ fix: "swap for dayjs (~7 KB) or date-fns (per-function imports)",
996
+ },
997
+ lodash: {
998
+ size: "~70 KB min",
999
+ fix: "import per-method (`import debounce from 'lodash/debounce'`) or use lodash-es with a bundler that tree-shakes",
1000
+ },
1001
+ "chart.js": {
1002
+ size: "~180 KB min",
1003
+ fix: "use the tree-shakable subpath imports (`import { Chart, LineController, ... } from 'chart.js'`) and only register what you draw",
1004
+ },
1005
+ rxjs: {
1006
+ size: "~140 KB min",
1007
+ fix: "import operators from 'rxjs/operators' individually, or drop RxJS if you only need a couple of observables",
1008
+ },
1009
+ three: {
1010
+ size: "~600 KB min",
1011
+ fix: "lazy-load the 3D route with React.lazy / dynamic import so it isn't in the initial bundle",
1012
+ },
1013
+ jquery: {
1014
+ size: "~90 KB min",
1015
+ fix: "delete jQuery — every browser since 2015 covers the same API natively",
1016
+ },
966
1017
  };
967
1018
  for (const [pkg, info] of Object.entries(heavy)) {
968
1019
  // Namespace import or default import of the whole package
@@ -976,10 +1027,12 @@ const heavyLibImport = (source, file) => {
976
1027
  id: "heavy-lib-import",
977
1028
  category: "Performance & Bundle Size",
978
1029
  severity: "medium",
979
- file, line: lineOf(source, idx),
1030
+ file,
1031
+ line: lineOf(source, idx),
980
1032
  message: `\`${pkg}\` imported at top level (${info.size}) — ships to every visitor.`,
981
1033
  why: "Every KB in the initial bundle delays Time-to-Interactive on mobile and cellular. Bundling a huge date/util/graphics lib for a single helper is the #1 self-inflicted perf wound.",
982
- fix: info.fix + ". For truly optional features, wrap the route/component in React.lazy() so the lib only loads on demand.",
1034
+ fix: info.fix +
1035
+ ". For truly optional features, wrap the route/component in React.lazy() so the lib only loads on demand.",
983
1036
  aiPrompt: `In ${file}, ${pkg} is imported at the module top-level. ${info.fix}. If the feature is only used on one route, additionally wrap it in React.lazy() + <Suspense> so it code-splits out of the initial bundle.`,
984
1037
  }));
985
1038
  }
@@ -1001,13 +1054,17 @@ const missingErrorTyping = (source, file, ast) => {
1001
1054
  const propAccessRegex = new RegExp(`\\b${errorName}\\.(message|code|name|stack)\\b`);
1002
1055
  if (propAccessRegex.test(catchBodySrc)) {
1003
1056
  // Check if there is a type narrowing guard
1004
- const hasGuard = new RegExp(`instanceof\\s+Error|typeof\\s+${errorName}\\s*===?\\s*['"]object['"]|${errorName}\\s+is\\s+|as\\s+Error`).test(catchBodySrc) || new RegExp(`\\b${errorName}\\s+instanceof\\b`).test(catchBodySrc) || /Error\s*\(/.test(catchBodySrc) || new RegExp(`isError\\s*\\(\\s*${errorName}\\s*\\)`).test(catchBodySrc);
1057
+ const hasGuard = new RegExp(`instanceof\\s+Error|typeof\\s+${errorName}\\s*===?\\s*['"]object['"]|${errorName}\\s+is\\s+|as\\s+Error`).test(catchBodySrc) ||
1058
+ new RegExp(`\\b${errorName}\\s+instanceof\\b`).test(catchBodySrc) ||
1059
+ /Error\s*\(/.test(catchBodySrc) ||
1060
+ new RegExp(`isError\\s*\\(\\s*${errorName}\\s*\\)`).test(catchBodySrc);
1005
1061
  if (!hasGuard) {
1006
1062
  out.push(mkFinding({
1007
1063
  id: "missing-error-typing",
1008
1064
  category: "Data Integrity",
1009
1065
  severity: "medium",
1010
- file, line: p.node.loc?.start.line ?? 1,
1066
+ file,
1067
+ line: p.node.loc?.start.line ?? 1,
1011
1068
  message: `Error property accessed without type narrowing.`,
1012
1069
  why: "In TypeScript, caught errors are of type `unknown` or `any`. Accessing properties like `.message` directly can crash if the thrown value is a string or null.",
1013
1070
  fix: "Check if the error is an instance of Error (e.g. `if (e instanceof Error)`) before accessing its properties, or safely cast it.",
@@ -1015,7 +1072,7 @@ const missingErrorTyping = (source, file, ast) => {
1015
1072
  }));
1016
1073
  }
1017
1074
  }
1018
- }
1075
+ },
1019
1076
  });
1020
1077
  return out;
1021
1078
  };
@@ -1037,16 +1094,19 @@ const unusedVariablesImports = (source, file, ast) => {
1037
1094
  if (name === "React")
1038
1095
  continue; // Ignore React import if unused
1039
1096
  // Ignore exports
1040
- if (binding.path.parentPath?.isExportDeclaration() || binding.path.parentPath?.isExportDefaultDeclaration())
1097
+ if (binding.path.parentPath?.isExportDeclaration() ||
1098
+ binding.path.parentPath?.isExportDefaultDeclaration())
1041
1099
  continue;
1042
1100
  if (binding.path.isExportDeclaration() || binding.path.isExportDefaultDeclaration())
1043
1101
  continue;
1044
1102
  // Ignore type imports and type declarations
1045
- if (binding.path.parentPath?.isImportDeclaration() && binding.path.parentPath.node.importKind === "type")
1103
+ if (binding.path.parentPath?.isImportDeclaration() &&
1104
+ binding.path.parentPath.node.importKind === "type")
1046
1105
  continue;
1047
1106
  if (binding.path.isImportSpecifier() && binding.path.node.importKind === "type")
1048
1107
  continue;
1049
- if (binding.path.parentPath?.isTSTypeAliasDeclaration() || binding.path.parentPath?.isTSInterfaceDeclaration())
1108
+ if (binding.path.parentPath?.isTSTypeAliasDeclaration() ||
1109
+ binding.path.parentPath?.isTSInterfaceDeclaration())
1050
1110
  continue;
1051
1111
  // Babel sometimes misses type references, so skip uppercase identifiers (common convention for types/interfaces)
1052
1112
  if (/^[A-Z]/.test(name))
@@ -1056,7 +1116,8 @@ const unusedVariablesImports = (source, file, ast) => {
1056
1116
  id: `unused-${typeLabel}`,
1057
1117
  category: "Polish & Embarrassment Risks",
1058
1118
  severity: "low",
1059
- file, line: binding.identifier.loc?.start.line ?? 1,
1119
+ file,
1120
+ line: binding.identifier.loc?.start.line ?? 1,
1060
1121
  message: `Unused ${typeLabel}: '${name}'.`,
1061
1122
  why: "Unused variables and imports clutter the codebase, increase bundle size, and make code harder to read.",
1062
1123
  fix: `Remove the unused ${typeLabel}.`,
@@ -1074,7 +1135,8 @@ const unusedVariablesImports = (source, file, ast) => {
1074
1135
  id: "unused-variable",
1075
1136
  category: "Polish & Embarrassment Risks",
1076
1137
  severity: "low",
1077
- file, line: binding.identifier.loc?.start.line ?? 1,
1138
+ file,
1139
+ line: binding.identifier.loc?.start.line ?? 1,
1078
1140
  message: `Unused variable: '${name}'.`,
1079
1141
  why: "Unused variables clutter the codebase and make code harder to read.",
1080
1142
  fix: "Remove the unused variable.",
@@ -1082,7 +1144,7 @@ const unusedVariablesImports = (source, file, ast) => {
1082
1144
  }));
1083
1145
  }
1084
1146
  }
1085
- }
1147
+ },
1086
1148
  });
1087
1149
  return out;
1088
1150
  };
@@ -1100,7 +1162,9 @@ const emptyLinkText = (source, file, ast) => {
1100
1162
  const n = p.node.name;
1101
1163
  if (n.type !== "JSXIdentifier" || n.name !== "a")
1102
1164
  return;
1103
- const hasAriaLabel = p.node.attributes.some((a) => a.type === "JSXAttribute" && a.name.type === "JSXIdentifier" && (a.name.name === "aria-label" || a.name.name === "aria-labelledby"));
1165
+ const hasAriaLabel = p.node.attributes.some((a) => a.type === "JSXAttribute" &&
1166
+ a.name.type === "JSXIdentifier" &&
1167
+ (a.name.name === "aria-label" || a.name.name === "aria-labelledby"));
1104
1168
  if (hasAriaLabel)
1105
1169
  return;
1106
1170
  const parent = p.parentPath.node;
@@ -1122,7 +1186,11 @@ const emptyLinkText = (source, file, ast) => {
1122
1186
  if (child.type === "JSXElement") {
1123
1187
  const childName = child.openingElement.name;
1124
1188
  if (childName.type === "JSXIdentifier" && childName.name === "img") {
1125
- const hasAlt = child.openingElement.attributes.some(a => a.type === "JSXAttribute" && a.name.type === "JSXIdentifier" && a.name.name === "alt" && a.value?.type === "StringLiteral" && a.value.value.trim().length > 0);
1189
+ const hasAlt = child.openingElement.attributes.some((a) => a.type === "JSXAttribute" &&
1190
+ a.name.type === "JSXIdentifier" &&
1191
+ a.name.name === "alt" &&
1192
+ a.value?.type === "StringLiteral" &&
1193
+ a.value.value.trim().length > 0);
1126
1194
  if (hasAlt)
1127
1195
  hasTextOrImgWithAlt = true;
1128
1196
  }
@@ -1138,9 +1206,10 @@ const emptyLinkText = (source, file, ast) => {
1138
1206
  id: "empty-link",
1139
1207
  category: "Accessibility",
1140
1208
  severity: "medium",
1141
- file, line: p.node.loc?.start.line ?? 1,
1209
+ file,
1210
+ line: p.node.loc?.start.line ?? 1,
1142
1211
  message: "Link (<a>) contains no text content or accessible name.",
1143
- why: "Screen reader users won't know the purpose of the link. It fails WCAG 2.4.4 (Link Purpose).",
1212
+ why: "Screen-reader users can't tell where this link goes, so navigation becomes guesswork (WCAG 2.4.4). Meaningful link text is required for WCAG 2.1 AA — the standard cited in ADA Title III and EU EAA enforcement — and a run of unnamed links is one of the first things automated accessibility audits and demand letters call out.",
1144
1213
  fix: "Provide text inside the link, or use aria-label.",
1145
1214
  aiPrompt: `In ${file} near line ${p.node.loc?.start.line ?? 1}, the <a> tag is empty or contains no accessible text. Add text content or an aria-label attribute.`,
1146
1215
  }));
@@ -1201,11 +1270,23 @@ export function runChecks(source, file, ast) {
1201
1270
  message: `Scanner rule crashed on ${file}`,
1202
1271
  stack: err.stack,
1203
1272
  where: c.name || "anonymous check",
1204
- extra: { file, rawError: String(e) }
1273
+ extra: { file, rawError: String(e) },
1205
1274
  }).catch(() => { });
1206
- out.push(mkFinding({ id: "internal-error", category: "Runtime Stability", severity: "high", file, line: 1, message: `Scanner crashed: ${e}`, why: "Internal exception in scanner rule.", fix: "Report this issue.", aiPrompt: "Fix the crash in the scanner rule." }));
1275
+ out.push(mkFinding({
1276
+ id: "internal-error",
1277
+ category: "Runtime Stability",
1278
+ severity: "high",
1279
+ file,
1280
+ line: 1,
1281
+ message: `Scanner crashed: ${e}`,
1282
+ why: "Internal exception in scanner rule.",
1283
+ fix: "Report this issue.",
1284
+ aiPrompt: "Fix the crash in the scanner rule.",
1285
+ }));
1207
1286
  }
1208
1287
  }
1209
1288
  return out;
1210
1289
  }
1211
- function mkFinding(f) { return f; }
1290
+ function mkFinding(f) {
1291
+ return f;
1292
+ }