@utilix-tech/sdk 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.20.0
+- Add `buildCacheControl` (cache-control-builder): assemble and explain a `Cache-Control` response header from directives, with warnings for combinations that cancel out.
+- Add `detectFillerWords` (filler-word-detector): scan text for filler words, hedge phrases, and clichés with per-phrase counts and a density score.
+
+## 0.19.0
+- Add `detectRedos` (regex-redos-detector): statically flag catastrophic-backtracking risk (nested quantifiers, overlapping alternation, adjacent overlapping quantifiers).
+
 ## 0.18.0
 - Added Present Value / Future Value Calculator (`calculateTimeValue`) and Vector Similarity Calculator (`vectorSimilarity`).
 

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**553 developer utility functions for Node.js: runs locally, no API key required.**
+**556 developer utility functions for Node.js: runs locally, no API key required.**
 
 [![npm version](https://img.shields.io/npm/v/@utilix-tech/sdk?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@utilix-tech/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@utilix-tech/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix-tech/sdk)
@@ -132,7 +132,8 @@ generateHtpasswdFile([{ username: "alice", password: "secret" }]);
 
 ```ts
 import { convertCase, slugify, countWords, generateWords, generateParagraphs,
-         escapeString, htmlToMarkdown, applyOps, detectPassiveVoice, scoreReadability } from "@utilix-tech/sdk/text";
+         escapeString, htmlToMarkdown, applyOps, detectPassiveVoice, scoreReadability,
+         detectFillerWords } from "@utilix-tech/sdk/text";
 
 convertCase("hello world", "camelCase");   // "helloWorld"
 convertCase("hello world", "PascalCase");  // "HelloWorld"
@@ -157,6 +158,10 @@ detectPassiveVoice("The report was reviewed by the committee. They approved it."
 // Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog Index
 scoreReadability("The cat sat on the mat. It was a sunny day.");
 // { fleschReadingEase: 109, fleschKincaidGrade: -0.6, gunningFog: 2.2, readingLevel: "Very easy (5th grade)", ... }
+
+// Flag filler words, hedge phrases, and clichés with counts and density
+detectFillerWords("At the end of the day, I just really think we should circle back.");
+// { totalMatches: 4, fillerCount: 2, clicheCount: 2, density: 28.6, matches: [...] }
 ```
 
 ---
@@ -315,7 +320,7 @@ calculateTimeValue(1000, 5, 10, "future");
 import { getStatusCode, isValidIp, isValidIpv4, isValidIpv6,
          searchStatusCodes, buildGeoUrl, countryCodeToFlag,
          parseHar, validateSitemap, validateRobotsTxt,
-         parseUserAgent } from "@utilix-tech/sdk/network";
+         parseUserAgent, buildCacheControl } from "@utilix-tech/sdk/network";
 
 getStatusCode(404);
 // { code: 404, text: "Not Found", description: "...", category: "Client Error" }
@@ -345,6 +350,10 @@ validateSitemap('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><ur
 // Validate a robots.txt file: User-agent groups, rules, and syntax mistakes
 validateRobotsTxt("User-agent: *\nDisallow: /admin\nSitemap: https://example.com/sitemap.xml");
 // { groups: [...], sitemaps: [...], issues: [...], valid: true }
+
+// Build and explain a Cache-Control response header from directives
+buildCacheControl({ visibility: "public", maxAge: 3600, mustRevalidate: true });
+// { header: "public, max-age=3600, must-revalidate", directives: [...], warnings: [] }
 ```
 
 ---
@@ -389,7 +398,8 @@ generateCspHeader({ "default-src": ["'self'"], "script-src": ["'self'", "cdn.exa
 
 ```ts
 import { formatSql, minifySql, testRegex, formatHtml, formatGql,
-         detectDialect, splitStatements, lookupMime, parseGithubUrl } from "@utilix-tech/sdk/code";
+         detectDialect, splitStatements, lookupMime, parseGithubUrl,
+         detectRedos } from "@utilix-tech/sdk/code";
 
 // SQL
 formatSql("SELECT id,name FROM users WHERE active=1 ORDER BY name");
@@ -421,6 +431,10 @@ lookupMime("image/jpeg");  // { kind: "mime", matches: [{ extension: "jpg", ...
 // GitHub URL parsing
 parseGithubUrl("https://github.com/facebook/react/pull/1234");
 // { owner: "facebook", repo: "react", type: "pull", number: 1234 }
+
+// Regex ReDoS (catastrophic-backtracking) detection
+detectRedos("(a+)+");
+// { risk: "high", safe: false, findings: [{ type: "nested-quantifier", ... }] }
 ```
 
 ---

package/dist/{chunk-F57WMKZO.js → chunk-2I4O5YCT.js}

@@ -20,6 +20,7 @@ __export(text_exports, {
   csvToHtml: () => csvToHtml,
   csvToMarkdown: () => csvToMarkdown,
   detectDelimiter: () => detectDelimiter,
+  detectFillerWords: () => detectFillerWords,
   detectPassiveVoice: () => detectPassiveVoice,
   diffLines: () => diffLines,
   diffLinesSimple: () => diffLinesSimple,
@@ -2457,5 +2458,103 @@ function scoreReadability(text) {
     readingLevel: readabilityGradeLabel(fleschReadingEase)
   };
 }
+var FILLER_WORDS = [
+  "very",
+  "really",
+  "just",
+  "actually",
+  "basically",
+  "literally",
+  "simply",
+  "totally",
+  "definitely",
+  "certainly",
+  "essentially",
+  "absolutely",
+  "completely",
+  "extremely",
+  "truly",
+  "honestly",
+  "seriously",
+  "obviously",
+  "clearly",
+  "quite",
+  "rather",
+  "somewhat",
+  "fairly",
+  "virtually"
+];
+var HEDGE_PHRASES = [
+  "maybe",
+  "perhaps",
+  "probably",
+  "possibly",
+  "arguably",
+  "kind of",
+  "sort of",
+  "a bit",
+  "a little",
+  "more or less",
+  "in my opinion",
+  "i think",
+  "i believe",
+  "to some extent"
+];
+var CLICHE_PHRASES = [
+  "at the end of the day",
+  "think outside the box",
+  "low-hanging fruit",
+  "move the needle",
+  "circle back",
+  "touch base",
+  "on the same page",
+  "hit the ground running",
+  "paradigm shift",
+  "win-win",
+  "game changer",
+  "best of both worlds",
+  "only time will tell",
+  "back to the drawing board",
+  "the tip of the iceberg",
+  "a perfect storm",
+  "needle in a haystack",
+  "raise the bar",
+  "push the envelope",
+  "the elephant in the room",
+  "boil the ocean",
+  "when it rains it pours"
+];
+var FILLER_DICTIONARY = [
+  ...FILLER_WORDS.map((phrase) => ({ phrase, category: "filler" })),
+  ...HEDGE_PHRASES.map((phrase) => ({ phrase, category: "hedge" })),
+  ...CLICHE_PHRASES.map((phrase) => ({ phrase, category: "cliche" }))
+];
+function _fillerRegex(phrase) {
+  const tokens = phrase.split(/\s+/).map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return new RegExp("\\b" + tokens.join("\\s+") + "\\b", "gi");
+}
+function detectFillerWords(text) {
+  const totalWords = (text.match(/[A-Za-z0-9']+/g) ?? []).length;
+  const matches = [];
+  for (const entry of FILLER_DICTIONARY) {
+    const re = _fillerRegex(entry.phrase);
+    const indices = [];
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      indices.push(m.index);
+      if (m.index === re.lastIndex) re.lastIndex++;
+    }
+    if (indices.length > 0) {
+      matches.push({ phrase: entry.phrase, category: entry.category, count: indices.length, indices });
+    }
+  }
+  matches.sort((a, b) => b.count - a.count || a.category.localeCompare(b.category) || a.phrase.localeCompare(b.phrase));
+  const fillerCount = matches.filter((x) => x.category === "filler").reduce((s, x) => s + x.count, 0);
+  const hedgeCount = matches.filter((x) => x.category === "hedge").reduce((s, x) => s + x.count, 0);
+  const clicheCount = matches.filter((x) => x.category === "cliche").reduce((s, x) => s + x.count, 0);
+  const totalMatches = fillerCount + hedgeCount + clicheCount;
+  const density = totalWords > 0 ? Math.round(totalMatches / totalWords * 1e3) / 10 : 0;
+  return { totalWords, totalMatches, fillerCount, hedgeCount, clicheCount, density, matches };
+}
 
-export { CASE_FORMATS, DEFAULT_CONVERT_OPTIONS, ESCAPE_MODES, LINE_OPS, MORSE_CODE, addBorder, analyzeText, applyOp, applyOps, centerText, convertAll, convertCase, countWords, csvToHtml, csvToMarkdown, detectDelimiter, detectPassiveVoice, diffLines, diffLinesSimple, diffStats, escapeAll, escapeString, extractHeadings, formatReadingTime, generate, generateDiff, generateHtmlTable, generateMarkdownTable, generateParagraphs, generateSentences, generateWords, getAvailableFonts, getMorseForChar, getMorseTiming, htmlToMarkdown, isValidMorse, markdownToHtml, morseToText, numberToOrdinal, numberToRoman, numberToWords, ordinalWords, parseDiff, parseTableData, readabilityScore, renderMarkdown, romanToNumber, scoreReadability, sentenceCount, slugify, slugifyAll, syllableCount, textToAscii, textToMorse, text_exports, unescapeString, wordFrequency };
+export { CASE_FORMATS, DEFAULT_CONVERT_OPTIONS, ESCAPE_MODES, LINE_OPS, MORSE_CODE, addBorder, analyzeText, applyOp, applyOps, centerText, convertAll, convertCase, countWords, csvToHtml, csvToMarkdown, detectDelimiter, detectFillerWords, detectPassiveVoice, diffLines, diffLinesSimple, diffStats, escapeAll, escapeString, extractHeadings, formatReadingTime, generate, generateDiff, generateHtmlTable, generateMarkdownTable, generateParagraphs, generateSentences, generateWords, getAvailableFonts, getMorseForChar, getMorseTiming, htmlToMarkdown, isValidMorse, markdownToHtml, morseToText, numberToOrdinal, numberToRoman, numberToWords, ordinalWords, parseDiff, parseTableData, readabilityScore, renderMarkdown, romanToNumber, scoreReadability, sentenceCount, slugify, slugifyAll, syllableCount, textToAscii, textToMorse, text_exports, unescapeString, wordFrequency };

package/dist/{chunk-L53LAVAD.js → chunk-LXKIPPDG.js}

@@ -18,6 +18,7 @@ __export(code_exports, {
   countRules: () => countRules,
   detectDialect: () => detectDialect,
   detectOperationType: () => detectOperationType,
+  detectRedos: () => detectRedos,
   envToExport: () => envToExport,
   envToJson: () => envToJson,
   formatCss: () => formatCss,
@@ -2475,5 +2476,269 @@ function parseGithubUrl(input) {
   }
   return { error: `Unsupported GitHub URL path: /${rest.join("/")}` };
 }
+var _REDOS_UNBOUNDED = /* @__PURE__ */ new Set(["*", "+"]);
+function _redosParseQuant(src, i) {
+  const ch = src[i];
+  if (ch === "*" || ch === "+" || ch === "?") {
+    let end = i + 1;
+    if (src[end] === "?" || src[end] === "+") end++;
+    return { unbounded: _REDOS_UNBOUNDED.has(ch), raw: src.slice(i, end), end };
+  }
+  if (ch === "{") {
+    const close = src.indexOf("}", i);
+    if (close === -1) return null;
+    const inner = src.slice(i + 1, close);
+    if (!/^\d+(,\d*)?$/.test(inner)) return null;
+    let end = close + 1;
+    if (src[end] === "?" || src[end] === "+") end++;
+    const unbounded = /^\d+,$/.test(inner);
+    return { unbounded, raw: src.slice(i, end), end };
+  }
+  return null;
+}
+function _redosParseAlternation(src, start, endExclusive) {
+  const alternatives = [];
+  let current = [];
+  let i = start;
+  while (i < endExclusive) {
+    const ch = src[i];
+    if (ch === "|") {
+      alternatives.push(current);
+      current = [];
+      i++;
+      continue;
+    }
+    let node;
+    if (ch === "\\") {
+      const atomEnd = i + 2 <= endExclusive ? i + 2 : i + 1;
+      node = { kind: "char", start: i, end: atomEnd, quant: null, quantEnd: atomEnd, raw: src.slice(i, atomEnd) };
+      i = atomEnd;
+    } else if (ch === "[") {
+      let j = i + 1;
+      if (src[j] === "^") j++;
+      if (src[j] === "]") j++;
+      while (j < endExclusive && src[j] !== "]") {
+        j += src[j] === "\\" ? 2 : 1;
+      }
+      const classEnd = j < endExclusive ? j + 1 : endExclusive;
+      node = { kind: "class", start: i, end: classEnd, quant: null, quantEnd: classEnd, raw: src.slice(i, classEnd) };
+      i = classEnd;
+    } else if (ch === "(") {
+      let depth = 1;
+      let j = i + 1;
+      while (j < endExclusive && depth > 0) {
+        const cj = src[j];
+        if (cj === "\\") {
+          j += 2;
+          continue;
+        }
+        if (cj === "[") {
+          j++;
+          if (src[j] === "^") j++;
+          if (src[j] === "]") j++;
+          while (j < endExclusive && src[j] !== "]") {
+            j += src[j] === "\\" ? 2 : 1;
+          }
+          j++;
+          continue;
+        }
+        if (cj === "(") depth++;
+        else if (cj === ")") depth--;
+        j++;
+      }
+      const closeIdx = depth === 0 ? j - 1 : endExclusive;
+      let contentStart = i + 1;
+      let lookaround = false;
+      if (src[i + 1] === "?") {
+        const after = src[i + 2];
+        if (after === ":") contentStart = i + 3;
+        else if (after === "=" || after === "!") {
+          contentStart = i + 3;
+          lookaround = true;
+        } else if (after === "<") {
+          const a3 = src[i + 3];
+          if (a3 === "=" || a3 === "!") {
+            contentStart = i + 4;
+            lookaround = true;
+          } else {
+            const gt = src.indexOf(">", i + 2);
+            contentStart = gt !== -1 && gt < closeIdx ? gt + 1 : i + 3;
+          }
+        }
+      }
+      node = {
+        kind: "group",
+        start: i,
+        end: closeIdx + 1,
+        quant: null,
+        quantEnd: closeIdx + 1,
+        raw: src.slice(i, closeIdx + 1),
+        alternatives: _redosParseAlternation(src, contentStart, closeIdx),
+        lookaround
+      };
+      i = closeIdx + 1;
+    } else if (ch === ".") {
+      node = { kind: "dot", start: i, end: i + 1, quant: null, quantEnd: i + 1, raw: "." };
+      i++;
+    } else if (ch === "^" || ch === "$") {
+      node = { kind: "anchor", start: i, end: i + 1, quant: null, quantEnd: i + 1, raw: ch };
+      i++;
+    } else {
+      node = { kind: "char", start: i, end: i + 1, quant: null, quantEnd: i + 1, raw: ch };
+      i++;
+    }
+    if (node.kind !== "anchor") {
+      const q = _redosParseQuant(src, i);
+      if (q) {
+        node.quant = q;
+        node.quantEnd = q.end;
+        i = q.end;
+      }
+    }
+    current.push(node);
+  }
+  alternatives.push(current);
+  return alternatives;
+}
+var _REDOS_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_ 	.,-@/:;#%&=";
+function _redosFirstMatcher(node) {
+  if (node.kind === "dot") return (c) => c !== "\n";
+  if (node.kind === "char") {
+    if (node.raw.startsWith("\\")) {
+      const body = node.raw.slice(1);
+      if (/^[dDwWsS]$/.test(body)) {
+        try {
+          const re = new RegExp("\\" + body);
+          return (c) => re.test(c);
+        } catch {
+          return null;
+        }
+      }
+      const literal = { n: "\n", t: "	", r: "\r", f: "\f", v: "\v" }[body] ?? body;
+      return (c) => c === literal;
+    }
+    const lit = node.raw;
+    return (c) => c === lit;
+  }
+  if (node.kind === "class") {
+    try {
+      const re = new RegExp(node.raw);
+      return (c) => re.test(c);
+    } catch {
+      return null;
+    }
+  }
+  if (node.kind === "group") {
+    const first = node.alternatives?.[0]?.[0];
+    return first ? _redosFirstMatcher(first) : null;
+  }
+  return null;
+}
+function _redosOverlaps(a, b) {
+  const fa = _redosFirstMatcher(a);
+  const fb = _redosFirstMatcher(b);
+  if (!fa || !fb) return false;
+  for (const c of _REDOS_ALPHABET) {
+    if (fa(c) && fb(c)) return true;
+  }
+  return false;
+}
+function _redosAnalyzeGroup(node, findings) {
+  const alts = node.alternatives ?? [];
+  const outerUnbounded = node.quant?.unbounded === true && !node.lookaround;
+  if (outerUnbounded) {
+    for (const alt of alts) {
+      const meaningful = alt.filter((n) => n.kind !== "anchor");
+      if (meaningful.length === 1 && meaningful[0].quant?.unbounded) {
+        findings.push({
+          type: "nested-quantifier",
+          severity: "high",
+          message: "Nested unbounded quantifiers: a repeated group whose body is itself unbounded-repeated can match the same input in exponentially many ways, causing catastrophic backtracking.",
+          snippet: node.raw + (node.quant?.raw ?? ""),
+          index: node.start
+        });
+        break;
+      }
+    }
+    if (alts.length > 1) {
+      const firsts = alts.map((alt) => alt.find((n) => n.kind !== "anchor")).filter((n) => !!n);
+      let flagged = false;
+      for (let x = 0; x < firsts.length && !flagged; x++) {
+        for (let y = x + 1; y < firsts.length; y++) {
+          if (_redosOverlaps(firsts[x], firsts[y])) {
+            findings.push({
+              type: "overlapping-alternation",
+              severity: "medium",
+              message: "Overlapping alternation under a repetition: two branches can match the same starting input, so the engine has multiple ways to split each repeat and may backtrack heavily.",
+              snippet: node.raw + (node.quant?.raw ?? ""),
+              index: node.start
+            });
+            flagged = true;
+            break;
+          }
+        }
+      }
+    }
+  }
+  for (const alt of alts) {
+    _redosAnalyzeSequence(alt, findings);
+  }
+}
+function _redosAnalyzeSequence(seq, findings) {
+  for (let k = 0; k + 1 < seq.length; k++) {
+    const a = seq[k];
+    const b = seq[k + 1];
+    if (a.quant?.unbounded && b.quant?.unbounded && _redosOverlaps(a, b)) {
+      findings.push({
+        type: "adjacent-quantifier",
+        severity: "medium",
+        message: "Adjacent unbounded quantifiers over overlapping characters: the engine can distribute the same input between them in many ways, causing quadratic backtracking.",
+        snippet: seq[k].raw + (a.quant?.raw ?? "") + seq[k + 1].raw + (b.quant?.raw ?? ""),
+        index: a.start
+      });
+    }
+  }
+  for (const node of seq) {
+    if (node.kind === "group") _redosAnalyzeGroup(node, findings);
+  }
+}
+function detectRedos(pattern) {
+  if (typeof pattern !== "string" || pattern === "") {
+    return { error: "Empty pattern" };
+  }
+  if (pattern.length > 5e3) {
+    return { error: "Pattern too long (max 5,000 chars)" };
+  }
+  let valid = true;
+  let compileError;
+  try {
+    new RegExp(pattern);
+  } catch (e) {
+    valid = false;
+    compileError = e instanceof Error ? e.message : String(e);
+  }
+  const findings = [];
+  const alternatives = _redosParseAlternation(pattern, 0, pattern.length);
+  for (const alt of alternatives) {
+    _redosAnalyzeSequence(alt, findings);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const unique = findings.filter((f) => {
+    const key = `${f.type}:${f.index}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  unique.sort((a, b) => a.index - b.index);
+  const risk = unique.some((f) => f.severity === "high") ? "high" : unique.length > 0 ? "medium" : "none";
+  return {
+    pattern,
+    valid,
+    ...compileError ? { compileError } : {},
+    risk,
+    safe: unique.length === 0,
+    findings: unique
+  };
+}
 
-export { ALL_FLAGS, CHEATSHEET, MIME_TABLE, OPERATIONS, SQL_DEFAULT_OPTIONS, buildDockerPull, buildDockerRun, buildGitCommand, code_exports, collapseHtmlWhitespace, collapseJsWhitespace, countProperties, countRules, detectDialect, detectOperationType, envToExport, envToJson, formatCss, formatGql, formatHtml, formatSql, getEndpointsByTag, getHtmlStats, getJsStats, getMethodColor, isValidTag, lookupMime, minifyCss, minifyGql, minifyHtml, minifyJs, minifySql, normalizeRef, parseDockerImage, parseEnv, parseGitCommand, parseGithubUrl, parseSpec, removeConsoleCalls, removeEmptyAttributes, removeHtmlComments, removeJsComments, removeRedundantAttributes, searchCheatsheet, searchEndpoints, splitStatements, testPattern, testRegex, validateEnvKey };
+export { ALL_FLAGS, CHEATSHEET, MIME_TABLE, OPERATIONS, SQL_DEFAULT_OPTIONS, buildDockerPull, buildDockerRun, buildGitCommand, code_exports, collapseHtmlWhitespace, collapseJsWhitespace, countProperties, countRules, detectDialect, detectOperationType, detectRedos, envToExport, envToJson, formatCss, formatGql, formatHtml, formatSql, getEndpointsByTag, getHtmlStats, getJsStats, getMethodColor, isValidTag, lookupMime, minifyCss, minifyGql, minifyHtml, minifyJs, minifySql, normalizeRef, parseDockerImage, parseEnv, parseGitCommand, parseGithubUrl, parseSpec, removeConsoleCalls, removeEmptyAttributes, removeHtmlComments, removeJsComments, removeRedundantAttributes, searchCheatsheet, searchEndpoints, splitStatements, testPattern, testRegex, validateEnvKey };

package/dist/{chunk-3QMUUTBH.js → chunk-Y5OOP6WN.js}

@@ -6,6 +6,7 @@ __export(network_exports, {
   DNS_RECORD_TYPES: () => DNS_RECORD_TYPES,
   HTTP_HEADERS: () => HTTP_HEADERS,
   STATUS_CODES: () => STATUS_CODES,
+  buildCacheControl: () => buildCacheControl,
   buildDnsQueryUrl: () => buildDnsQueryUrl,
   buildGeoUrl: () => buildGeoUrl,
   buildMapUrl: () => buildMapUrl,
@@ -1721,5 +1722,97 @@ function parseUserAgent(ua) {
   const device = { type: _detectUaDeviceType(s) };
   return { browser, engine, os, device, raw: s };
 }
+var _CACHE_NUM_FIELDS = ["maxAge", "sMaxAge", "staleWhileRevalidate", "staleIfError"];
+function _humanizeSeconds(s) {
+  if (s === 0) return "0 seconds";
+  const units = [
+    [86400, "day"],
+    [3600, "hour"],
+    [60, "minute"],
+    [1, "second"]
+  ];
+  const parts = [];
+  let rem = s;
+  for (const [size, label] of units) {
+    if (rem >= size) {
+      const n = Math.floor(rem / size);
+      rem -= n * size;
+      parts.push(`${n} ${label}${n === 1 ? "" : "s"}`);
+    }
+  }
+  return parts.slice(0, 2).join(" ");
+}
+function buildCacheControl(options = {}) {
+  const nums = {
+    maxAge: null,
+    sMaxAge: null,
+    staleWhileRevalidate: null,
+    staleIfError: null
+  };
+  for (const field of _CACHE_NUM_FIELDS) {
+    const v = options[field];
+    if (v === void 0 || v === null) continue;
+    if (typeof v !== "number" || !Number.isFinite(v) || !Number.isInteger(v) || v < 0) {
+      return { error: `${field} must be a non-negative integer number of seconds` };
+    }
+    nums[field] = v;
+  }
+  const directives = [];
+  const warnings = [];
+  if (options.visibility === "public") {
+    directives.push({ name: "public", value: null, explanation: "Any cache, including shared caches and CDNs, may store this response." });
+  }
+  if (options.visibility === "private") {
+    directives.push({ name: "private", value: null, explanation: "Only the user's browser may cache this response; shared caches and CDNs must not." });
+  }
+  if (options.noCache) {
+    directives.push({ name: "no-cache", value: null, explanation: "A cache may store the response but must revalidate it with the origin before every reuse." });
+  }
+  if (options.noStore) {
+    directives.push({ name: "no-store", value: null, explanation: "No cache may store any part of this request or response." });
+  }
+  if (nums.maxAge !== null) {
+    directives.push({ name: "max-age", value: String(nums.maxAge), explanation: `Considered fresh for ${_humanizeSeconds(nums.maxAge)} (${nums.maxAge}s), after which it becomes stale.` });
+  }
+  if (nums.sMaxAge !== null) {
+    directives.push({ name: "s-maxage", value: String(nums.sMaxAge), explanation: `For shared caches (CDNs, proxies) it is fresh for ${_humanizeSeconds(nums.sMaxAge)} (${nums.sMaxAge}s), overriding max-age there.` });
+  }
+  if (options.mustRevalidate) {
+    directives.push({ name: "must-revalidate", value: null, explanation: "Once stale, a cache must revalidate with the origin and never serve the stale copy." });
+  }
+  if (options.proxyRevalidate) {
+    directives.push({ name: "proxy-revalidate", value: null, explanation: "Like must-revalidate, but the requirement applies only to shared caches." });
+  }
+  if (options.immutable) {
+    directives.push({ name: "immutable", value: null, explanation: "The body will not change while fresh, so browsers should not revalidate it on reload." });
+  }
+  if (options.noTransform) {
+    directives.push({ name: "no-transform", value: null, explanation: "Intermediaries must not modify the response body (for example, recompressing images)." });
+  }
+  if (nums.staleWhileRevalidate !== null) {
+    directives.push({ name: "stale-while-revalidate", value: String(nums.staleWhileRevalidate), explanation: `A cache may serve the stale response for up to ${_humanizeSeconds(nums.staleWhileRevalidate)} (${nums.staleWhileRevalidate}s) while it revalidates in the background.` });
+  }
+  if (nums.staleIfError !== null) {
+    directives.push({ name: "stale-if-error", value: String(nums.staleIfError), explanation: `A cache may serve the stale response for up to ${_humanizeSeconds(nums.staleIfError)} (${nums.staleIfError}s) if the origin returns an error.` });
+  }
+  if (options.mustUnderstand) {
+    directives.push({ name: "must-understand", value: null, explanation: "A cache should store the response only if it understands the caching requirements of the response's status code." });
+  }
+  if (options.noStore && directives.length > 1) {
+    warnings.push("no-store means nothing is cached, so the other directives have no effect.");
+  }
+  if (options.noCache && nums.maxAge !== null) {
+    warnings.push("no-cache forces revalidation on every use, so max-age has little practical effect alongside it.");
+  }
+  if (options.immutable && nums.maxAge === null) {
+    warnings.push("immutable only applies while the response is fresh \u2014 add a max-age so it has a freshness lifetime.");
+  }
+  if (directives.length === 0) {
+    warnings.push("No directives set \u2014 an empty Cache-Control header has no effect.");
+  }
+  const header = directives.map((d) => d.value === null ? d.name : `${d.name}=${d.value}`).join(", ");
+  const snippet = `Cache-Control: ${header}`;
+  return { header, headerName: "Cache-Control", snippet, directives, warnings };
+}
 
-export { DNS_RECORD_TYPES, HTTP_HEADERS, STATUS_CODES, buildDnsQueryUrl, buildGeoUrl, buildMapUrl, countryCodeToFlag, formatCoordinates, formatTtl, getByCategory, getHeader, getHeadersByCategory, getStatusByCategory, getStatusCode, isClientError, isServerError, isSuccess, isValidIp, isValidIpv4, isValidIpv6, network_exports, parseDnsResponse, parseGeoResponse, parseHar, parseUserAgent, searchHeaders, searchStatusCodes, statusCodeToText, typeNumberToLabel, validateDomain, validateHeaderName, validateHeaderValue, validateRobotsTxt, validateSitemap };
+export { DNS_RECORD_TYPES, HTTP_HEADERS, STATUS_CODES, buildCacheControl, buildDnsQueryUrl, buildGeoUrl, buildMapUrl, countryCodeToFlag, formatCoordinates, formatTtl, getByCategory, getHeader, getHeadersByCategory, getStatusByCategory, getStatusCode, isClientError, isServerError, isSuccess, isValidIp, isValidIpv4, isValidIpv6, network_exports, parseDnsResponse, parseGeoResponse, parseHar, parseUserAgent, searchHeaders, searchStatusCodes, statusCodeToText, typeNumberToLabel, validateDomain, validateHeaderName, validateHeaderValue, validateRobotsTxt, validateSitemap };

package/dist/{code-Cn9uOIAh.d.ts → code-DaRvff2v.d.cts}

@@ -19,6 +19,7 @@
  *   - css-minifier     (minifyCss, formatCss, countRules, countProperties)
  *   - mime-lookup      (lookupMime, MIME_TABLE)
  *   - github-url-parser (parseGithubUrl)
+ *   - redos-detector   (detectRedos)
  */
 type RegexFlag = 'g' | 'i' | 'm' | 's' | 'u';
 declare const ALL_FLAGS: RegexFlag[];
@@ -307,6 +308,32 @@ interface GithubUrlInfo {
 declare function parseGithubUrl(input: string): GithubUrlInfo | {
     error: string;
 };
+type RedosSeverity = 'high' | 'medium';
+interface RedosFinding {
+    type: 'nested-quantifier' | 'overlapping-alternation' | 'adjacent-quantifier';
+    severity: RedosSeverity;
+    message: string;
+    snippet: string;
+    index: number;
+}
+interface RedosResult {
+    pattern: string;
+    valid: boolean;
+    compileError?: string;
+    risk: 'none' | 'medium' | 'high';
+    safe: boolean;
+    findings: RedosFinding[];
+}
+/**
+ * Statically analyze a regex pattern for catastrophic-backtracking (ReDoS)
+ * risk. Pass the pattern body only (no delimiters or flags). This is a
+ * heuristic linter focused on the classic exponential/quadratic constructs
+ * (nested quantifiers, overlapping alternation under a repeat, adjacent
+ * overlapping quantifiers), not a formal guarantee.
+ */
+declare function detectRedos(pattern: string): RedosResult | {
+    error: string;
+};
 
 declare const code_ALL_FLAGS: typeof ALL_FLAGS;
 type code_ApiEndpoint = ApiEndpoint;
@@ -334,6 +361,9 @@ type code_MimeEntry = MimeEntry;
 type code_MimeLookupResult = MimeLookupResult;
 declare const code_OPERATIONS: typeof OPERATIONS;
 type code_ParsedSpec = ParsedSpec;
+type code_RedosFinding = RedosFinding;
+type code_RedosResult = RedosResult;
+type code_RedosSeverity = RedosSeverity;
 type code_RegexError = RegexError;
 type code_RegexFlag = RegexFlag;
 type code_RegexMatch = RegexMatch;
@@ -354,6 +384,7 @@ declare const code_countProperties: typeof countProperties;
 declare const code_countRules: typeof countRules;
 declare const code_detectDialect: typeof detectDialect;
 declare const code_detectOperationType: typeof detectOperationType;
+declare const code_detectRedos: typeof detectRedos;
 declare const code_envToExport: typeof envToExport;
 declare const code_envToJson: typeof envToJson;
 declare const code_formatCss: typeof formatCss;
@@ -389,7 +420,7 @@ declare const code_testPattern: typeof testPattern;
 declare const code_testRegex: typeof testRegex;
 declare const code_validateEnvKey: typeof validateEnvKey;
 declare namespace code {
-  export { code_ALL_FLAGS as ALL_FLAGS, type code_ApiEndpoint as ApiEndpoint, type code_ApiInfo as ApiInfo, code_CHEATSHEET as CHEATSHEET, type code_CheatsheetEntry as CheatsheetEntry, type code_CssResult as CssResult, type code_DockerImageRef as DockerImageRef, type code_EnvEntry as EnvEntry, type code_EnvParseResult as EnvParseResult, type code_GitCommandConfig as GitCommandConfig, type code_GitCommandResult as GitCommandResult, type code_GitOperation as GitOperation, type code_GithubUrlInfo as GithubUrlInfo, type code_GithubUrlType as GithubUrlType, type code_GqlFormatResult as GqlFormatResult, type code_HtmlFormatResult as HtmlFormatResult, type code_HtmlMinifyOptions as HtmlMinifyOptions, type code_HtmlMinifyResult as HtmlMinifyResult, type code_JsMinifyOptions as JsMinifyOptions, type code_JsMinifyResult as JsMinifyResult, code_MIME_TABLE as MIME_TABLE, type code_MatchResult as MatchResult, type code_MimeEntry as MimeEntry, type code_MimeLookupResult as MimeLookupResult, code_OPERATIONS as OPERATIONS, type code_ParsedSpec as ParsedSpec, type code_RegexError as RegexError, type code_RegexFlag as RegexFlag, type code_RegexMatch as RegexMatch, type code_RegexResult as RegexResult, type code_RegexSuccess as RegexSuccess, code_SQL_DEFAULT_OPTIONS as SQL_DEFAULT_OPTIONS, type code_Segment as Segment, type code_SpecVersion as SpecVersion, type code_SqlDialect as SqlDialect, type code_SqlFormatOptions as SqlFormatOptions, type code_TestPatternResult as TestPatternResult, code_buildDockerPull as buildDockerPull, code_buildDockerRun as buildDockerRun, code_buildGitCommand as buildGitCommand, code_collapseHtmlWhitespace as collapseHtmlWhitespace, code_collapseJsWhitespace as collapseJsWhitespace, code_countProperties as countProperties, code_countRules as countRules, code_detectDialect as detectDialect, code_detectOperationType as detectOperationType, code_envToExport as envToExport, code_envToJson as envToJson, code_formatCss as formatCss, code_formatGql as formatGql, code_formatHtml as formatHtml, code_formatSql as formatSql, code_getEndpointsByTag as getEndpointsByTag, code_getHtmlStats as getHtmlStats, code_getJsStats as getJsStats, code_getMethodColor as getMethodColor, code_isValidTag as isValidTag, code_lookupMime as lookupMime, code_minifyCss as minifyCss, code_minifyGql as minifyGql, code_minifyHtml as minifyHtml, code_minifyJs as minifyJs, code_minifySql as minifySql, code_normalizeRef as normalizeRef, code_parseDockerImage as parseDockerImage, code_parseEnv as parseEnv, code_parseGitCommand as parseGitCommand, code_parseGithubUrl as parseGithubUrl, code_parseSpec as parseSpec, code_removeConsoleCalls as removeConsoleCalls, code_removeEmptyAttributes as removeEmptyAttributes, code_removeHtmlComments as removeHtmlComments, code_removeJsComments as removeJsComments, code_removeRedundantAttributes as removeRedundantAttributes, code_searchCheatsheet as searchCheatsheet, code_searchEndpoints as searchEndpoints, code_splitStatements as splitStatements, code_testPattern as testPattern, code_testRegex as testRegex, code_validateEnvKey as validateEnvKey };
+  export { code_ALL_FLAGS as ALL_FLAGS, type code_ApiEndpoint as ApiEndpoint, type code_ApiInfo as ApiInfo, code_CHEATSHEET as CHEATSHEET, type code_CheatsheetEntry as CheatsheetEntry, type code_CssResult as CssResult, type code_DockerImageRef as DockerImageRef, type code_EnvEntry as EnvEntry, type code_EnvParseResult as EnvParseResult, type code_GitCommandConfig as GitCommandConfig, type code_GitCommandResult as GitCommandResult, type code_GitOperation as GitOperation, type code_GithubUrlInfo as GithubUrlInfo, type code_GithubUrlType as GithubUrlType, type code_GqlFormatResult as GqlFormatResult, type code_HtmlFormatResult as HtmlFormatResult, type code_HtmlMinifyOptions as HtmlMinifyOptions, type code_HtmlMinifyResult as HtmlMinifyResult, type code_JsMinifyOptions as JsMinifyOptions, type code_JsMinifyResult as JsMinifyResult, code_MIME_TABLE as MIME_TABLE, type code_MatchResult as MatchResult, type code_MimeEntry as MimeEntry, type code_MimeLookupResult as MimeLookupResult, code_OPERATIONS as OPERATIONS, type code_ParsedSpec as ParsedSpec, type code_RedosFinding as RedosFinding, type code_RedosResult as RedosResult, type code_RedosSeverity as RedosSeverity, type code_RegexError as RegexError, type code_RegexFlag as RegexFlag, type code_RegexMatch as RegexMatch, type code_RegexResult as RegexResult, type code_RegexSuccess as RegexSuccess, code_SQL_DEFAULT_OPTIONS as SQL_DEFAULT_OPTIONS, type code_Segment as Segment, type code_SpecVersion as SpecVersion, type code_SqlDialect as SqlDialect, type code_SqlFormatOptions as SqlFormatOptions, type code_TestPatternResult as TestPatternResult, code_buildDockerPull as buildDockerPull, code_buildDockerRun as buildDockerRun, code_buildGitCommand as buildGitCommand, code_collapseHtmlWhitespace as collapseHtmlWhitespace, code_collapseJsWhitespace as collapseJsWhitespace, code_countProperties as countProperties, code_countRules as countRules, code_detectDialect as detectDialect, code_detectOperationType as detectOperationType, code_detectRedos as detectRedos, code_envToExport as envToExport, code_envToJson as envToJson, code_formatCss as formatCss, code_formatGql as formatGql, code_formatHtml as formatHtml, code_formatSql as formatSql, code_getEndpointsByTag as getEndpointsByTag, code_getHtmlStats as getHtmlStats, code_getJsStats as getJsStats, code_getMethodColor as getMethodColor, code_isValidTag as isValidTag, code_lookupMime as lookupMime, code_minifyCss as minifyCss, code_minifyGql as minifyGql, code_minifyHtml as minifyHtml, code_minifyJs as minifyJs, code_minifySql as minifySql, code_normalizeRef as normalizeRef, code_parseDockerImage as parseDockerImage, code_parseEnv as parseEnv, code_parseGitCommand as parseGitCommand, code_parseGithubUrl as parseGithubUrl, code_parseSpec as parseSpec, code_removeConsoleCalls as removeConsoleCalls, code_removeEmptyAttributes as removeEmptyAttributes, code_removeHtmlComments as removeHtmlComments, code_removeJsComments as removeJsComments, code_removeRedundantAttributes as removeRedundantAttributes, code_searchCheatsheet as searchCheatsheet, code_searchEndpoints as searchEndpoints, code_splitStatements as splitStatements, code_testPattern as testPattern, code_testRegex as testRegex, code_validateEnvKey as validateEnvKey };
 }
 
-export { getEndpointsByTag as $, ALL_FLAGS as A, buildDockerRun as B, CHEATSHEET as C, type DockerImageRef as D, type EnvEntry as E, buildGitCommand as F, type GitCommandConfig as G, type HtmlFormatResult as H, collapseHtmlWhitespace as I, type JsMinifyOptions as J, collapseJsWhitespace as K, countProperties as L, MIME_TABLE as M, countRules as N, OPERATIONS as O, type ParsedSpec as P, detectDialect as Q, type RegexError as R, SQL_DEFAULT_OPTIONS as S, type TestPatternResult as T, detectOperationType as U, envToExport as V, envToJson as W, formatCss as X, formatGql as Y, formatHtml as Z, formatSql as _, type ApiEndpoint as a, getHtmlStats as a0, getJsStats as a1, getMethodColor as a2, isValidTag as a3, lookupMime as a4, minifyCss as a5, minifyGql as a6, minifyHtml as a7, minifyJs as a8, minifySql as a9, normalizeRef as aa, parseDockerImage as ab, parseEnv as ac, parseGitCommand as ad, parseGithubUrl as ae, parseSpec as af, removeConsoleCalls as ag, removeEmptyAttributes as ah, removeHtmlComments as ai, removeJsComments as aj, removeRedundantAttributes as ak, searchCheatsheet as al, searchEndpoints as am, splitStatements as an, testPattern as ao, testRegex as ap, validateEnvKey as aq, type ApiInfo as b, code as c, type CheatsheetEntry as d, type CssResult as e, type EnvParseResult as f, type GitCommandResult as g, type GitOperation as h, type GithubUrlInfo as i, type GithubUrlType as j, type GqlFormatResult as k, type HtmlMinifyOptions as l, type HtmlMinifyResult as m, type JsMinifyResult as n, type MatchResult as o, type MimeEntry as p, type MimeLookupResult as q, type RegexFlag as r, type RegexMatch as s, type RegexResult as t, type RegexSuccess as u, type Segment as v, type SpecVersion as w, type SqlDialect as x, type SqlFormatOptions as y, buildDockerPull as z };
+export { formatCss as $, ALL_FLAGS as A, type SqlDialect as B, CHEATSHEET as C, type DockerImageRef as D, type EnvEntry as E, type SqlFormatOptions as F, type GitCommandConfig as G, type HtmlFormatResult as H, buildDockerPull as I, type JsMinifyOptions as J, buildDockerRun as K, buildGitCommand as L, MIME_TABLE as M, collapseHtmlWhitespace as N, OPERATIONS as O, type ParsedSpec as P, collapseJsWhitespace as Q, type RedosFinding as R, SQL_DEFAULT_OPTIONS as S, type TestPatternResult as T, countProperties as U, countRules as V, detectDialect as W, detectOperationType as X, detectRedos as Y, envToExport as Z, envToJson as _, type ApiEndpoint as a, formatGql as a0, formatHtml as a1, formatSql as a2, getEndpointsByTag as a3, getHtmlStats as a4, getJsStats as a5, getMethodColor as a6, isValidTag as a7, lookupMime as a8, minifyCss as a9, minifyGql as aa, minifyHtml as ab, minifyJs as ac, minifySql as ad, normalizeRef as ae, parseDockerImage as af, parseEnv as ag, parseGitCommand as ah, parseGithubUrl as ai, parseSpec as aj, removeConsoleCalls as ak, removeEmptyAttributes as al, removeHtmlComments as am, removeJsComments as an, removeRedundantAttributes as ao, searchCheatsheet as ap, searchEndpoints as aq, splitStatements as ar, testPattern as as, testRegex as at, validateEnvKey as au, type ApiInfo as b, code as c, type CheatsheetEntry as d, type CssResult as e, type EnvParseResult as f, type GitCommandResult as g, type GitOperation as h, type GithubUrlInfo as i, type GithubUrlType as j, type GqlFormatResult as k, type HtmlMinifyOptions as l, type HtmlMinifyResult as m, type JsMinifyResult as n, type MatchResult as o, type MimeEntry as p, type MimeLookupResult as q, type RedosResult as r, type RedosSeverity as s, type RegexError as t, type RegexFlag as u, type RegexMatch as v, type RegexResult as w, type RegexSuccess as x, type Segment as y, type SpecVersion as z };