@fairfox/polly 0.82.1 → 0.84.0

package/dist/tools/quality/src/index.d.ts

@@ -36,7 +36,9 @@ export { type CssVarsOptions, checkCssVars } from "./css/check-vars.ts";
 export type { CssCheckResult, CssViolation } from "./css/shared.ts";
 export { logger, type QualityLogger, resetLogger, } from "./logger.ts";
 export { type CheckResult, checkNoAsCasting, isLineClean, suggestFix, type Violation, } from "./no-as-casting";
+export { checkNoFixedWaits, type FixedWaitViolation, type NoFixedWaitsOptions, type NoFixedWaitsResult, scanText, } from "./no-fixed-waits";
 export { checkNoRequire, isLineRequireClean, type NoRequireCheckOptions, type NoRequireCheckResult, type NoRequireViolation, } from "./no-require";
+export { checkNoTautologyEnsures, type NoTautologyEnsuresOptions, type NoTautologyEnsuresResult, splitTopLevelArgs, type TautologyViolation, tautologyReason, } from "./no-tautology-ensures";
 export { type CheckGitignoreOptions, type CheckSecretsOptions, checkGitignoreCoversAllowlist, checkSecrets, type GitignoreCheckResult, type SecretsCheckResult, } from "./secrets.ts";
 export { type AttestOptions, type AttestResult, digestRun, runAttest, summariseRunReport, } from "./attest";
 export { type CacheEntry, type CacheInputs, computeInputsHash, getCachedOutcome, setCachedOutcome, } from "./cache";

package/dist/tools/quality/src/index.js

@@ -841,9 +841,109 @@ async function checkNoAsCasting(options) {
   }
   return { violations, print: () => printViolations(violations) };
 }
-// tools/quality/src/no-require.ts
+// tools/quality/src/no-fixed-waits.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 import { Glob as Glob2 } from "bun";
+var HINT = "wait on a real condition (poll loop, web-first assertion, microtask flush) or a sanctioned delay primitive";
+var RULES = [
+  { pattern: /\.waitForTimeout\s*\(/, message: `waitForTimeout is a fixed sleep — ${HINT}` },
+  { pattern: /\bBun\.sleep\s*\(/, message: `Bun.sleep is a fixed sleep — ${HINT}` },
+  {
+    pattern: /\bsetTimeout\s*\(\s*(?:resolve|r|res|done)\s*,/,
+    message: `setTimeout resolving a promise is a fixed sleep — ${HINT}`
+  },
+  {
+    pattern: /\bsetTimeout\s*\(\s*\(\s*\)\s*=>\s*(?:resolve|r|res|done)\b/,
+    message: `setTimeout resolving a promise is a fixed sleep — ${HINT}`
+  },
+  {
+    pattern: /new\s+Promise\b.*\(\s*\(?\s*([A-Za-z_$][\w$]*)\s*\)?\s*=>.*\bsetTimeout\s*\(\s*\1\b/,
+    message: `Promise wrapping setTimeout is a fixed sleep — ${HINT}`
+  }
+];
+var DEFAULT_EXCLUDE = ["node_modules", "dist", ".git", ".bun", "build", "coverage"];
+function skipString(text, i) {
+  const quote = text[i];
+  if (quote !== '"' && quote !== "'" && quote !== "`")
+    return i;
+  let j = i + 1;
+  while (j < text.length && text[j] !== quote) {
+    if (text[j] === "\\")
+      j++;
+    j++;
+  }
+  return j;
+}
+function codeOnly(line) {
+  let out = "";
+  for (let i = 0;i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipString(line, i);
+      out += " ".repeat(end - i + 1);
+      i = end;
+      continue;
+    }
+    if (ch === "/" && line[i + 1] === "/")
+      break;
+    out += ch;
+  }
+  return out;
+}
+function scanText(content, filePath = "<text>") {
+  const violations = [];
+  const lines = content.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+      continue;
+    }
+    const code = codeOnly(line);
+    const rule = RULES.find((r) => r.pattern.test(code));
+    if (rule)
+      violations.push({ file: filePath, line: i + 1, content: trimmed, message: rule.message });
+  }
+  return violations;
+}
+function isExcluded(relative3, excludeDirs, excludeFiles) {
+  if (relative3.split("/").some((s) => excludeDirs.has(s)))
+    return true;
+  const normalized = relative3.replace(/\\/g, "/");
+  return excludeFiles.some((suffix) => normalized.endsWith(suffix));
+}
+function printViolations2(violations) {
+  if (violations.length === 0) {
+    logger.log("[no-fixed-waits] ✅ No violations found.");
+    return;
+  }
+  logger.log(`[no-fixed-waits] ❌ ${violations.length} fixed-duration wait(s) found:
+`);
+  for (const v of violations) {
+    logger.log(`  ${v.file}:${v.line}`);
+    logger.log(`    ${v.content}`);
+    logger.log(`    \uD83D\uDCA1 ${v.message}`);
+    logger.log("");
+  }
+}
+async function checkNoFixedWaits(options) {
+  const { rootDir } = options;
+  const excludeDirs = new Set(options.exclude ?? DEFAULT_EXCLUDE);
+  const excludeFiles = [...options.excludeFiles ?? [], "no-fixed-waits.ts"];
+  const glob = new Glob2(options.filePatterns ?? "**/*.{ts,tsx}");
+  const violations = [];
+  for await (const file of glob.scan({ cwd: rootDir, absolute: true })) {
+    const relative3 = file.replace(`${rootDir}/`, "");
+    if (isExcluded(relative3, excludeDirs, excludeFiles))
+      continue;
+    violations.push(...scanText(readFileSync2(file, "utf-8"), relative3));
+  }
+  return { violations, print: () => printViolations2(violations) };
+}
+// tools/quality/src/no-require.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { Glob as Glob3 } from "bun";
 function isLineRequireClean(line) {
   if (!line.includes("require")) {
     return true;
@@ -911,7 +1011,7 @@ async function checkNoRequire(options) {
   const rootDir = options.rootDir;
   const excludeDirs = new Set(options.exclude ?? ["node_modules", "dist", ".git", ".bun"]);
   const pattern = options.filePatterns ?? "**/*.{ts,tsx}";
-  const glob = new Glob2(pattern);
+  const glob = new Glob3(pattern);
   const violations = [];
   for await (const file of glob.scan({ cwd: rootDir, absolute: true })) {
     const relative3 = file.replace(`${rootDir}/`, "");
@@ -919,7 +1019,7 @@ async function checkNoRequire(options) {
     if (segments.some((s) => excludeDirs.has(s))) {
       continue;
     }
-    const content = readFileSync2(file, "utf-8");
+    const content = readFileSync3(file, "utf-8");
     violations.push(...findRequireViolations(relative3, content));
   }
   return {
@@ -927,6 +1027,157 @@ async function checkNoRequire(options) {
     print: () => printRequireViolations(violations)
   };
 }
+// tools/quality/src/no-tautology-ensures.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import { Glob as Glob4 } from "bun";
+var DEFAULT_PRIMITIVES = ["ensures", "requires"];
+var DEFAULT_EXCLUDE2 = [
+  "node_modules",
+  "dist",
+  ".git",
+  ".bun",
+  "coverage",
+  "specs",
+  "tests",
+  "__tests__",
+  "examples"
+];
+var LITERAL = /^(true|false|null|undefined|\d+(\.\d+)?|"[^"]*"|'[^']*'|`[^`]*`)$/;
+function tautologyReason(predicate) {
+  const trimmed = predicate.trim();
+  if (LITERAL.test(trimmed))
+    return `literal '${trimmed}'`;
+  const cmp = trimmed.match(/^(.+?)\s*(===|!==|==|!=)\s*(.+)$/);
+  if (cmp) {
+    const lhs = cmp[1]?.trim() ?? "";
+    const rhs = cmp[3]?.trim() ?? "";
+    if (LITERAL.test(lhs) && LITERAL.test(rhs))
+      return `literal-vs-literal '${trimmed}'`;
+  }
+  return;
+}
+function skipString2(text, i) {
+  const quote = text[i];
+  if (quote !== '"' && quote !== "'" && quote !== "`")
+    return i;
+  let j = i + 1;
+  while (j < text.length && text[j] !== quote) {
+    if (text[j] === "\\")
+      j++;
+    j++;
+  }
+  return j;
+}
+function findClosingParen(text, openIdx) {
+  let depth = 0;
+  for (let i = openIdx;i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "(") {
+      depth++;
+    } else if (ch === ")") {
+      if (--depth === 0)
+        return i;
+    } else {
+      i = skipString2(text, i);
+    }
+  }
+  return -1;
+}
+function splitTopLevelArgs(args) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0;i < args.length; i++) {
+    const ch = args[i];
+    if (ch === "(" || ch === "[" || ch === "{") {
+      depth++;
+    } else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+    } else if (ch === "," && depth === 0) {
+      parts.push(args.slice(start, i));
+      start = i + 1;
+    } else {
+      i = skipString2(args, i);
+    }
+  }
+  parts.push(args.slice(start));
+  return parts.map((p) => p.trim());
+}
+function isFileExcluded2(relative3, excludeDirs, excludeFiles) {
+  const segments = relative3.split("/");
+  if (segments.some((s) => excludeDirs.has(s)))
+    return true;
+  const basename = segments[segments.length - 1] ?? "";
+  return excludeFiles.has(basename) || excludeFiles.has(relative3);
+}
+function isNonCall(line, lineBefore) {
+  const isImport = /\b(import|export)\b/.test(line) && line.includes("{") && !line.includes(";");
+  const isFrom = /\b(import|export)\b.*\bfrom\b/.test(line);
+  return isImport || isFrom || lineBefore.includes("//");
+}
+function findViolations2(relative3, content, callPattern) {
+  const results = [];
+  callPattern.lastIndex = 0;
+  let match = callPattern.exec(content);
+  while (match !== null) {
+    const current = match;
+    match = callPattern.exec(content);
+    const openIdx = current.index + current[0].length - 1;
+    const lineStart = content.lastIndexOf(`
+`, current.index) + 1;
+    const lineEnd = content.indexOf(`
+`, current.index);
+    const line = content.slice(lineStart, lineEnd === -1 ? content.length : lineEnd);
+    if (isNonCall(line, content.slice(lineStart, current.index)))
+      continue;
+    const closeIdx = findClosingParen(content, openIdx);
+    if (closeIdx === -1)
+      continue;
+    const predicate = splitTopLevelArgs(content.slice(openIdx + 1, closeIdx))[0];
+    const reason = predicate ? tautologyReason(predicate) : undefined;
+    if (reason === undefined)
+      continue;
+    results.push({
+      file: relative3,
+      line: content.slice(0, current.index).split(`
+`).length,
+      content: line.trim(),
+      reason: `${current[1] ?? "ensures"}(...) predicate is a ${reason}`
+    });
+  }
+  return results;
+}
+function printViolations3(violations) {
+  if (violations.length === 0) {
+    logger.log("[no-tautology-ensures] ✅ No violations found.");
+    return;
+  }
+  logger.log(`[no-tautology-ensures] ❌ ${violations.length} violation(s) found:
+`);
+  for (const v of violations) {
+    logger.log(`  ${v.file}:${v.line}`);
+    logger.log(`    ${v.content}`);
+    logger.log(`    \uD83D\uDCA1 ${v.reason}`);
+    logger.log("");
+  }
+  logger.log("[no-tautology-ensures] A verify predicate must reference state — a literal asserts nothing.");
+}
+async function checkNoTautologyEnsures(options) {
+  const { rootDir } = options;
+  const excludeDirs = new Set(options.exclude ?? DEFAULT_EXCLUDE2);
+  const excludeFiles = new Set([...options.excludeFiles ?? [], "no-tautology-ensures.ts"]);
+  const primitives = options.primitives ?? DEFAULT_PRIMITIVES;
+  const callPattern = new RegExp(`\\b(${primitives.join("|")})\\s*\\(`, "g");
+  const glob = new Glob4(options.filePatterns ?? "**/*.{ts,tsx}");
+  const violations = [];
+  for await (const file of glob.scan({ cwd: rootDir, absolute: true })) {
+    const relative3 = file.replace(`${rootDir}/`, "");
+    if (isFileExcluded2(relative3, excludeDirs, excludeFiles))
+      continue;
+    violations.push(...findViolations2(relative3, readFileSync4(file, "utf-8"), callPattern));
+  }
+  return { violations, print: () => printViolations3(violations) };
+}
 // tools/quality/src/secrets.ts
 import { readFile } from "node:fs/promises";
 import { join as join3 } from "node:path";
@@ -1462,7 +1713,7 @@ import { join as join11 } from "node:path";
 
 // tools/quality/src/plugins/core.ts
 import { join as join10 } from "node:path";
-import { Glob as Glob5 } from "bun";
+import { Glob as Glob7 } from "bun";
 
 // tools/quality/src/plugins/cliche-checks.ts
 import { readdir as readdir3 } from "node:fs/promises";
@@ -1885,7 +2136,7 @@ var additionalCoreChecks = [
 // tools/quality/src/plugins/extra-checks.ts
 import { readdir as readdir5 } from "node:fs/promises";
 import { join as join8, relative as relative5 } from "node:path";
-import { Glob as Glob3 } from "bun";
+import { Glob as Glob5 } from "bun";
 var SKIP_DIRS_DEFAULT2 = ["node_modules", ".git", "dist", ".bun", ".cache"];
 function isCommentLine2(trimmed) {
   return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
@@ -2023,7 +2274,7 @@ function buildHookRegex(banned) {
 }
 function isAllowedByGlob(rel, allowedFiles) {
   for (const pattern of allowedFiles) {
-    if (new Glob3(pattern).match(rel))
+    if (new Glob5(pattern).match(rel))
       return true;
   }
   return false;
@@ -2090,7 +2341,7 @@ var DEFAULT_TYPOGRAPHIC = {
 };
 function fileMatchesAnyGlob(rel, globs) {
   for (const g of globs) {
-    if (new Glob3(g).match(rel))
+    if (new Glob5(g).match(rel))
       return true;
   }
   return false;
@@ -2158,7 +2409,7 @@ var extraCoreChecks = [
 // tools/quality/src/plugins/import-checks.ts
 import { readdir as readdir6 } from "node:fs/promises";
 import { join as join9, relative as relative6 } from "node:path";
-import { Glob as Glob4 } from "bun";
+import { Glob as Glob6 } from "bun";
 var SKIP_DIRS_DEFAULT3 = ["node_modules", ".git", "dist", ".bun", ".cache"];
 function isCommentLine3(trimmed) {
   return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
@@ -2185,7 +2436,7 @@ async function walkScannableFiles2(dir, skipDirs, out) {
 }
 function isAllowedByGlob2(rel, globs) {
   for (const g of globs) {
-    if (new Glob4(g).match(rel))
+    if (new Glob6(g).match(rel))
       return true;
   }
   return false;
@@ -2413,7 +2664,7 @@ async function runTscFor(packagePath, rootDir) {
 async function findWorkspaces(rootDir, patterns) {
   const out = [];
   for (const pattern of patterns) {
-    const glob = new Glob4(`${pattern}/tsconfig.json`);
+    const glob = new Glob6(`${pattern}/tsconfig.json`);
     for await (const file of glob.scan({ cwd: rootDir, absolute: true })) {
       out.push(file.replace(/\/tsconfig\.json$/, ""));
     }
@@ -2471,7 +2722,7 @@ async function scanFiles(rootDir, cfg) {
   const excludePackages = new Set(cfg.excludePackages ?? []);
   const excludeFiles = new Set(cfg.excludeFiles ?? []);
   const pattern = cfg.filePatterns ?? "**/*.{ts,tsx}";
-  const glob = new Glob5(pattern);
+  const glob = new Glob7(pattern);
   const out = [];
   for await (const file of glob.scan({ cwd: rootDir, absolute: true })) {
     const rel = file.replace(`${rootDir}/`, "");
@@ -2526,6 +2777,42 @@ var noRequire = {
     };
   }
 };
+var noTautologyEnsures = {
+  id: "polly:no-tautology-ensures",
+  description: "Ban ensures/requires whose predicate is a literal (asserts nothing)",
+  filesRead: (cfg, root) => scanFiles(root, resolveScanConfig(cfg)),
+  run: async ({ rootDir, config }) => {
+    const cfg = resolveScanConfig(config);
+    const result = await checkNoTautologyEnsures({
+      rootDir,
+      ...cfg.exclude ? { exclude: cfg.exclude } : {},
+      ...cfg.excludeFiles ? { excludeFiles: cfg.excludeFiles } : {},
+      ...cfg.filePatterns ? { filePatterns: cfg.filePatterns } : {}
+    });
+    return {
+      ok: result.violations.length === 0,
+      messages: result.violations.map((v) => `${v.file}:${v.line}: ${v.content} — ${v.reason}`)
+    };
+  }
+};
+var noFixedWaits = {
+  id: "polly:no-fixed-waits",
+  description: "Ban fixed-duration sleeps (waitForTimeout / Bun.sleep / promise-wrapped setTimeout)",
+  filesRead: (cfg, root) => scanFiles(root, resolveScanConfig(cfg)),
+  run: async ({ rootDir, config }) => {
+    const cfg = resolveScanConfig(config);
+    const result = await checkNoFixedWaits({
+      rootDir,
+      exclude: cfg.exclude ?? DEFAULT_EXCLUDES,
+      ...cfg.excludeFiles ? { excludeFiles: cfg.excludeFiles } : {},
+      ...cfg.filePatterns ? { filePatterns: cfg.filePatterns } : {}
+    });
+    return {
+      ok: result.violations.length === 0,
+      messages: result.violations.map((v) => `${v.file}:${v.line}: ${v.content} — ${v.message}`)
+    };
+  }
+};
 var secrets = {
   id: "polly:secrets",
   description: "Run `gitleaks detect` against the working tree",
@@ -2587,13 +2874,15 @@ var gitignoreCrossCheck = {
     };
   }
 };
-var POLLY_CORE_VERSION = "0.48.0";
+var POLLY_CORE_VERSION = "0.49.0";
 var pollyCorePlugin = {
   name: "polly",
   version: POLLY_CORE_VERSION,
   checks: [
     noAsCasting,
     noRequire,
+    noTautologyEnsures,
+    noFixedWaits,
     secrets,
     gitignoreCrossCheck,
     ...additionalCoreChecks,
@@ -2624,14 +2913,14 @@ async function loadQualityConfig(rootDir, explicitPath) {
 // tools/quality/src/plugins/polly-ui.ts
 import { readdir as readdir7 } from "node:fs/promises";
 import { join as join12, relative as relative7 } from "node:path";
-import { Glob as Glob6 } from "bun";
+import { Glob as Glob8 } from "bun";
 var SKIP_DIRS_DEFAULT4 = ["node_modules", ".git", "dist", ".bun", ".cache"];
 function isCommentLine4(trimmed) {
   return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
 }
 function isAllowedByGlob3(rel, globs) {
   for (const g of globs) {
-    if (new Glob6(g).match(rel))
+    if (new Glob8(g).match(rel))
       return true;
   }
   return false;
@@ -2823,9 +3112,12 @@ var pollyUiPlugin = {
 };
 export {
   validateRunConfig,
+  tautologyReason,
   summariseRunReport,
   suggestFix,
+  splitTopLevelArgs,
   setCachedOutcome,
+  scanText,
   runChecks,
   runAttest,
   resetLogger,
@@ -2842,7 +3134,9 @@ export {
   computeInputsHash,
   checkSharedComponents,
   checkSecrets,
+  checkNoTautologyEnsures,
   checkNoRequire,
+  checkNoFixedWaits,
   checkNoAsCasting,
   checkGitignoreCoversAllowlist,
   checkCssVars,
@@ -2854,4 +3148,4 @@ export {
   DEFAULT_SHARED_COMPONENT_RULES
 };
 
-//# debugId=DB1C98BCB50FC2FD64756E2164756E21
+//# debugId=553633575181BC3064756E2164756E21