@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/scanners/unoptimized-image.mjs

@@ -0,0 +1,127 @@
+// Four image-optimization checks emitted as `unoptimized-image` findings.
+// `subtype` distinguishes raw-img / global-unoptimized / image-fill-no-sizes
+// / image-svg-no-unoptimized so the recommender can frame each separately.
+
+export const metadata = {
+  id: "unoptimized-image",
+  title: "Image optimization gap (raw <img>, global flag, missing sizes, or SVG mis-routed)",
+  severity: "high",
+  billingDimension: "image-optimization",
+  trafficIndependent: false,
+  description:
+    'Four shapes of image-cost waste: raw <img> tags bypass the framework Image component; `images.unoptimized: true` disables Vercel image optimization globally; <Image fill> without `sizes` forces serving the largest source variant; <Image src=".svg"> without `unoptimized` routes vector data through the raster pipeline.',
+  fix: 'For raw <img>: switch to next/image, enhanced-img (SvelteKit), <Image /> (Astro), or NuxtImg. For global unoptimized:true: remove the flag unless the project is hosted outside Vercel. For fill without sizes: add `sizes="(max-width: 768px) 100vw, 50vw"` or whatever matches your layout. For SVG: add `unoptimized` so the raw SVG ships instead of rastering it.',
+  citations: [
+    "https://nextjs.org/docs/app/api-reference/components/image",
+    "https://vercel.com/docs/image-optimization",
+  ],
+  excludeGlobs: [
+    "node_modules/**",
+    ".next/**",
+    "dist/**",
+    "__tests__/**",
+    "cypress/**",
+    "*.test.*",
+  ],
+  includeGlobs: ["**/*.{tsx,jsx,html,svelte,astro,vue,js,mjs,ts}"],
+};
+
+const IMG_RE = /<img\s+[^>]*src\s*=\s*["'{`]/g;
+const GLOBAL_UNOPT_RE = /images\s*:\s*\{[^}]*\bunoptimized\s*:\s*true/;
+const IMAGE_TAG_RE = /<Image\b[^>]*?\/?>/g;
+const NEXT_IMAGE_IMPORT_RE = /from\s+['"]next\/image['"]/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (isJsxLike(path)) {
+      let m;
+      IMG_RE.lastIndex = 0;
+      while ((m = IMG_RE.exec(content)) !== null) {
+        out.push({
+          pattern: metadata.id,
+          subtype: "raw-img",
+          file: path,
+          line: lineOf(content, m.index),
+          evidence: snippet(content, m.index),
+          trafficIndependent: metadata.trafficIndependent,
+        });
+      }
+    }
+
+    if (isNextConfig(path)) {
+      const match = GLOBAL_UNOPT_RE.exec(content);
+      if (match) {
+        out.push({
+          pattern: metadata.id,
+          subtype: "global-unoptimized",
+          file: path,
+          line: lineOf(content, match.index),
+          evidence:
+            "images: { unoptimized: true } — disables Vercel image optimization for the entire project",
+          // Config-level flag affects every image regardless of route.
+          trafficIndependent: true,
+        });
+      }
+    }
+
+    // Only fire if next/image is imported — otherwise `Image` is some
+    // other component.
+    if (isJsxLike(path) && NEXT_IMAGE_IMPORT_RE.test(content)) {
+      let m;
+      IMAGE_TAG_RE.lastIndex = 0;
+      while ((m = IMAGE_TAG_RE.exec(content)) !== null) {
+        const tag = m[0];
+        const hasFill = /\bfill\b/.test(tag);
+        const hasSizes = /\bsizes\s*=/.test(tag);
+        if (hasFill && !hasSizes) {
+          out.push({
+            pattern: metadata.id,
+            subtype: "image-fill-no-sizes",
+            file: path,
+            line: lineOf(content, m.index),
+            evidence: tag.slice(0, 200),
+            trafficIndependent: metadata.trafficIndependent,
+          });
+        }
+        // Inline data: URLs never round-trip through the optimizer.
+        const srcMatch = /\bsrc\s*=\s*["']([^"']+)["']/.exec(tag);
+        if (srcMatch) {
+          const src = srcMatch[1];
+          if (
+            /\.svg(\?|$)/i.test(src) &&
+            !src.startsWith("data:") &&
+            !/\bunoptimized\b/.test(tag)
+          ) {
+            out.push({
+              pattern: metadata.id,
+              subtype: "image-svg-no-unoptimized",
+              file: path,
+              line: lineOf(content, m.index),
+              evidence: tag.slice(0, 200),
+              trafficIndependent: metadata.trafficIndependent,
+            });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+import { lineOf } from "../util.mjs";
+
+function isJsxLike(path) {
+  return /\.(tsx|jsx|html|svelte|astro|vue)$/.test(path);
+}
+function isNextConfig(path) {
+  return /(?:^|\/)next\.config\.(js|mjs|ts|cjs)$/.test(path);
+}
+function snippet(text, idx) {
+  const start = text.lastIndexOf("\n", idx) + 1;
+  const end = text.indexOf("\n", idx);
+  return text
+    .slice(start, end === -1 ? text.length : end)
+    .trim()
+    .slice(0, 160);
+}

package/skills/craft/vercel-optimize/lib/scanners/use-cache-date-stamp.mjs

@@ -0,0 +1,112 @@
+// Detects time/randomness primitives that destabilize `'use cache'` cache keys,
+// which manifests as ISR write amplification when the cached output embeds a timestamp
+// that changes per request.
+//
+// Triggers when a file contains the `'use cache'` directive AND uses `new Date(`,
+// `Date.now(`, or `Math.random(` outside client-only hooks (useEffect / useCallback /
+// useMemo). Replacing module-scope `new Date().getFullYear()` with a build-time
+// `buildYear` constant, and removing dates passed as `'use cache'` function
+// arguments, prevents repeated writes when the rendered output is otherwise stable.
+
+import { lineOf } from "../util.mjs";
+
+export const metadata = {
+  id: "use-cache-date-stamp",
+  title: "new Date() / Date.now() / Math.random() inside a 'use cache' file",
+  severity: "high",
+  billingDimension: "isr",
+  trafficIndependent: false,
+  description:
+    "`'use cache'` memoizes by argument identity AND prerender output. A timestamp baked into the cached output (`new Date().getFullYear()` in a footer, `Date.now()` in a payload field) forces a fresh ISR write on every regeneration even when the underlying data is unchanged. Random values have the same failure mode.",
+  fix: "Replace module-scope `new Date()` with a build-time constant (`const buildYear = new Date().getFullYear()`) or move per-request timestamps into a client component inside `useEffect`. Do not pass dates as arguments to `'use cache'` functions — they invalidate the cache every call.",
+  citations: [
+    "https://nextjs.org/docs/app/api-reference/directives/use-cache",
+    "https://nextjs.org/docs/app/api-reference/functions/cacheLife",
+  ],
+  excludeGlobs: [
+    "node_modules/**",
+    ".next/**",
+    "dist/**",
+    "__tests__/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+  ],
+  includeGlobs: [
+    "**/page.{ts,tsx,js,jsx}",
+    "**/layout.{ts,tsx,js,jsx}",
+    "**/route.{ts,tsx,js,jsx}",
+    "**/lib/**/*.{ts,tsx,js,jsx}",
+    "**/app/**/*.{ts,tsx,js,jsx}",
+    "**/components/**/*.{ts,tsx,js,jsx}",
+  ],
+};
+
+const USE_CACHE_RE = /^[\t ]*['"]use cache['"]/m;
+const SUSPECT_RE = /\b(new Date\(|Date\.now\(|Math\.random\()/g;
+// Client-only hooks that don't affect server-side cache keys.
+const CLIENT_HOOK_RE = /\b(useEffect|useCallback|useMemo|useLayoutEffect)\s*\(/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!USE_CACHE_RE.test(content)) continue;
+
+    const clientHookRanges = collectRanges(content, CLIENT_HOOK_RE);
+    let match;
+    SUSPECT_RE.lastIndex = 0;
+    while ((match = SUSPECT_RE.exec(content)) !== null) {
+      if (isInsideAnyRange(match.index, clientHookRanges)) continue;
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, match.index),
+        evidence: match[0],
+        trafficIndependent: metadata.trafficIndependent,
+        subtype: classifySubtype(content, match.index),
+      });
+    }
+  }
+  return out;
+}
+
+function collectRanges(content, hookRe) {
+  const ranges = [];
+  hookRe.lastIndex = 0;
+  let m;
+  while ((m = hookRe.exec(content)) !== null) {
+    const open = content.indexOf("(", m.index);
+    if (open < 0) continue;
+    const close = findMatchingParen(content, open);
+    if (close < 0) continue;
+    ranges.push([open, close]);
+  }
+  return ranges;
+}
+
+function findMatchingParen(content, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < content.length; i++) {
+    const c = content[i];
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function isInsideAnyRange(idx, ranges) {
+  for (const [a, b] of ranges) {
+    if (idx >= a && idx <= b) return true;
+  }
+  return false;
+}
+
+// `module-scope` if the suspect appears before the first function/class declaration.
+// `in-cache-fn` otherwise (likely inside a render or helper function body).
+function classifySubtype(content, idx) {
+  const head = content.slice(0, idx);
+  if (!/\bfunction\b|\bclass\b|=>\s*\{/.test(head)) return "module-scope";
+  return "in-cache-fn";
+}

package/skills/craft/vercel-optimize/lib/support-topics.mjs

@@ -0,0 +1,365 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadLibrary, lookupSkillRule, lookupUrl, matchesFrameworkVersion } from "./citations.mjs";
+import { gates } from "./gates/index.mjs";
+import { SCANNER_GATES } from "./gates/scanner-driven.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TOPICS_DIR = join(HERE, "..", "references", "support-topics");
+
+export const SUPPORT_TOPIC_LIMIT = 3;
+export const SUPPORT_TOPIC_TOTAL_CHAR_LIMIT = 2400;
+const DEFAULT_MAX_BRIEF_CHARS = 900;
+
+export const KNOWN_CANDIDATE_KINDS = new Set([
+  ...gates.map((g) => g.metadata?.id).filter((id) => id && id !== "scanner-driven"),
+  ...SCANNER_GATES.map((g) => g.id),
+]);
+
+export async function supportTopicSubset({
+  candidate,
+  signals = {},
+  framework,
+  version,
+  profile,
+  frameworkPlaybookId,
+  maxTopics = SUPPORT_TOPIC_LIMIT,
+  maxChars = SUPPORT_TOPIC_TOTAL_CHAR_LIMIT,
+} = {}) {
+  const stack = signals?.stack ?? signals?.codebase?.stack ?? {};
+  const fw = framework ?? stack.framework ?? "unknown";
+  const fwVersion = version ?? stack.frameworkVersion ?? "unknown";
+  const candidates = await loadSupportTopics();
+  const selected = [];
+  let usedChars = 0;
+
+  const sorted = candidates
+    .filter((t) => t.status === "active")
+    .filter((t) => matchesCandidateKind(t, candidate?.kind))
+    .filter((t) => matchesFrameworks(t.frameworks, fw, fwVersion))
+    .filter((t) => matchesOptionalList(t.profiles, profile))
+    .filter((t) => matchesOptionalList(t.frameworkPlaybooks, frameworkPlaybookId))
+    .filter((t) => matchesRouter(t.routers, stack))
+    .filter((t) => matchesCandidateMetrics(t.metrics, candidate))
+    .filter((t) => matchesCandidateRoutePatterns(t.routePatterns, candidate))
+    .filter((t) => matchesScannerPatterns(t.scannerPatterns, candidate))
+    .sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));
+
+  for (const topic of sorted) {
+    if (!(await topicCitationsApply(topic, candidate?.kind, fw, fwVersion))) continue;
+    if (selected.length >= maxTopics) break;
+    const renderedChars = topic.title.length + topic.body.length + topic.id.length + 20;
+    if (selected.length > 0 && usedChars + renderedChars > maxChars) continue;
+    selected.push(topic);
+    usedChars += renderedChars;
+  }
+
+  return selected;
+}
+
+export async function loadSupportTopics({ includeDraft = false } = {}) {
+  let names = [];
+  try {
+    names = await readdir(TOPICS_DIR);
+  } catch (err) {
+    if (err?.code === "ENOENT") return [];
+    throw err;
+  }
+
+  const topics = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith(".md") || name === "README.md") continue;
+    const path = join(TOPICS_DIR, name);
+    const raw = await readFile(path, "utf-8");
+    const topic = parseSupportTopic(raw, path);
+    if (includeDraft || topic.status === "active") topics.push(topic);
+  }
+  return topics.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export async function validateSupportTopics() {
+  const topics = await loadSupportTopics({ includeDraft: true });
+  const errors = [];
+  const seen = new Set();
+  for (const topic of topics) {
+    errors.push(...(await validateSupportTopic(topic)));
+    if (seen.has(topic.id)) errors.push(`${topic.path}: duplicate topic id "${topic.id}"`);
+    seen.add(topic.id);
+  }
+  return { ok: errors.length === 0, errors, topics };
+}
+
+export function renderSupportTopics(topics = []) {
+  if (!Array.isArray(topics) || topics.length === 0) return [];
+  const lines = [];
+  lines.push("## Support topics (investigation guardrails)");
+  lines.push("");
+  lines.push(
+    "These are deterministic, candidate-scoped hints selected from `references/support-topics/`. They do not create recommendations. Use them only to decide what evidence to check, what to rule out, and when to abstain.",
+  );
+  lines.push("");
+  for (const topic of topics) {
+    lines.push(`### ${topic.title} (\`${topic.id}\`)`);
+    lines.push("");
+    lines.push(topic.body.trim());
+    lines.push("");
+  }
+  return lines;
+}
+
+export function parseSupportTopic(raw, path = "<memory>") {
+  const { frontmatter, body } = splitFrontmatter(raw, path);
+  const metadata = parseFrontmatter(frontmatter, path);
+  return normalizeTopic({ ...metadata, body: body.trim(), path });
+}
+
+function splitFrontmatter(raw, path) {
+  const text = String(raw ?? "");
+  if (!text.startsWith("---\n")) {
+    throw new Error(`${path}: support topic must start with --- frontmatter`);
+  }
+  const end = text.indexOf("\n---\n", 4);
+  if (end === -1) {
+    throw new Error(`${path}: support topic frontmatter must end with ---`);
+  }
+  return {
+    frontmatter: text.slice(4, end),
+    body: text.slice(end + "\n---\n".length),
+  };
+}
+
+function parseFrontmatter(src, path) {
+  const out = {};
+  for (const rawLine of src.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/);
+    if (!m) throw new Error(`${path}: unsupported frontmatter line "${rawLine}"`);
+    const [, key, value] = m;
+    out[key] = parseFrontmatterValue(value, path, key);
+  }
+  return out;
+}
+
+function parseFrontmatterValue(value, path, key) {
+  if (value.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) throw new Error("not an array");
+      return parsed;
+    } catch (err) {
+      throw new Error(`${path}: ${key} must use strict JSON array syntax (${err.message})`);
+    }
+  }
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  const quoted = value.match(/^"(.*)"$/) ?? value.match(/^'(.*)'$/);
+  return quoted ? quoted[1] : value;
+}
+
+function normalizeTopic(topic) {
+  const maxBriefChars = Number.isFinite(topic.maxBriefChars)
+    ? topic.maxBriefChars
+    : DEFAULT_MAX_BRIEF_CHARS;
+  return {
+    id: topic.id,
+    title: topic.title,
+    status: topic.status,
+    candidateKinds: toStringArray(topic.candidateKinds),
+    frameworks: toStringArray(topic.frameworks),
+    profiles: toStringArray(topic.profiles),
+    frameworkPlaybooks: toStringArray(topic.frameworkPlaybooks),
+    routers: toStringArray(topic.routers),
+    metrics: toStringArray(topic.metrics),
+    routePatterns: toStringArray(topic.routePatterns),
+    scannerPatterns: toStringArray(topic.scannerPatterns),
+    billingDimensions: toStringArray(topic.billingDimensions),
+    citations: toStringArray(topic.citations),
+    priority: Number(topic.priority),
+    maxBriefChars,
+    body: topic.body,
+    path: topic.path,
+  };
+}
+
+async function validateSupportTopic(topic) {
+  const errors = [];
+  const label = topic.path ?? topic.id ?? "<topic>";
+  const fileId = basename(label).replace(/\.md$/, "");
+
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(topic.id ?? "")) {
+    errors.push(`${label}: id must be kebab-case`);
+  }
+  if (fileId !== topic.id) errors.push(`${label}: filename must match id`);
+  if (!nonEmptyString(topic.title)) errors.push(`${label}: title is required`);
+  if (!["active", "draft", "deprecated"].includes(topic.status)) {
+    errors.push(`${label}: status must be active, draft, or deprecated`);
+  }
+  if (!Number.isFinite(topic.priority)) errors.push(`${label}: priority must be a number`);
+  if (
+    !Number.isFinite(topic.maxBriefChars) ||
+    topic.maxBriefChars < 200 ||
+    topic.maxBriefChars > 1400
+  ) {
+    errors.push(`${label}: maxBriefChars must be between 200 and 1400`);
+  }
+  if (!nonEmptyArray(topic.candidateKinds)) {
+    errors.push(`${label}: candidateKinds must be a non-empty array`);
+  } else {
+    for (const kind of topic.candidateKinds) {
+      if (kind !== "*" && !KNOWN_CANDIDATE_KINDS.has(kind)) {
+        errors.push(`${label}: unknown candidate kind "${kind}"`);
+      }
+    }
+  }
+  if (!nonEmptyArray(topic.frameworks)) {
+    errors.push(`${label}: frameworks must be a non-empty array`);
+  } else {
+    for (const fw of topic.frameworks) {
+      if (fw !== "*" && !/^[\w-]+@/.test(fw)) {
+        errors.push(`${label}: framework "${fw}" must be "*" or "framework@range"`);
+      }
+    }
+  }
+  if (!nonEmptyArray(topic.citations)) {
+    errors.push(`${label}: citations must be a non-empty array`);
+  } else {
+    for (const citation of topic.citations) {
+      if (!(await knownCitation(citation))) {
+        errors.push(`${label}: unknown citation "${citation}"`);
+      }
+    }
+  }
+  for (const pattern of topic.routePatterns) {
+    try {
+      new RegExp(pattern);
+    } catch (err) {
+      errors.push(`${label}: invalid routePatterns regex "${pattern}" (${err.message})`);
+    }
+  }
+  for (const heading of [
+    "## Investigation Brief",
+    "## Evidence To Check",
+    "## Do Not Recommend When",
+    "## Verification",
+  ]) {
+    if (!topic.body.includes(heading)) errors.push(`${label}: missing heading "${heading}"`);
+  }
+  if (topic.body.length > topic.maxBriefChars) {
+    errors.push(
+      `${label}: body length ${topic.body.length} exceeds maxBriefChars ${topic.maxBriefChars}`,
+    );
+  }
+  if (/https?:\/\//.test(topic.body)) {
+    errors.push(`${label}: put URLs in frontmatter citations, not body text`);
+  }
+  if (/\/Users\/|(?:^|[\s`"'])apps\/[^/\s`"']+\/|[A-Za-z0-9_-]+\.ts:\d+/.test(topic.body)) {
+    errors.push(`${label}: body leaks internal implementation details`);
+  }
+  return errors;
+}
+
+function matchesCandidateKind(topic, candidateKind) {
+  if (!candidateKind) return false;
+  return topic.candidateKinds.includes("*") || topic.candidateKinds.includes(candidateKind);
+}
+
+function matchesFrameworks(frameworks, framework, version) {
+  return frameworks.some(
+    (pattern) => pattern === "*" || matchesFrameworkVersion(pattern, framework, version),
+  );
+}
+
+function matchesOptionalList(values, actual) {
+  if (!Array.isArray(values) || values.length === 0) return true;
+  return values.includes("*") || (actual != null && values.includes(actual));
+}
+
+function matchesRouter(routers, stack) {
+  if (!Array.isArray(routers) || routers.length === 0) return true;
+  if (routers.includes("*")) return true;
+  return (
+    (routers.includes("app") && stack?.hasAppRouter) ||
+    (routers.includes("pages") && stack?.hasPagesRouter)
+  );
+}
+
+function matchesCandidateMetrics(metrics, candidate) {
+  if (!Array.isArray(metrics) || metrics.length === 0) return true;
+  if (metrics.includes("*")) return true;
+  const observed = new Set(
+    [candidate?.evidence?.metric, ...(candidate?.evidence?.issues ?? []).map((i) => i?.metric)]
+      .filter(Boolean)
+      .map((m) => String(m).toUpperCase()),
+  );
+  return metrics.some((m) => observed.has(String(m).toUpperCase()));
+}
+
+function matchesCandidateRoutePatterns(patterns, candidate) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return true;
+  if (patterns.includes("*")) return true;
+  const route = candidate?.route ?? candidate?.path;
+  if (typeof route !== "string" || route.length === 0) return false;
+  return patterns.some((p) => new RegExp(p).test(route));
+}
+
+function matchesScannerPatterns(patterns, candidate) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return true;
+  const observed = new Set(
+    [
+      ...(candidate?.evidence?.patterns ?? []),
+      ...(candidate?.evidence?.deepDive?.patterns ?? []),
+    ].filter(Boolean),
+  );
+  if (observed.size === 0) return false;
+  return patterns.some((p) => observed.has(p));
+}
+
+function topicCitationsApply(topic, candidateKind, framework, version) {
+  if (!candidateKind) return false;
+  return topic.citations.every((citation) =>
+    citationApplies(citation, candidateKind, framework, version),
+  );
+}
+
+async function citationApplies(citation, candidateKind, framework, version) {
+  const lib = await loadLibrary();
+  const rule = lib.ruleSkillRefs.find((r) => `${r.skill}:${r.rule}` === citation);
+  if (rule) {
+    return (
+      rule.applicableFrameworks.includes("*") ||
+      rule.applicableFrameworks.some((p) => matchesFrameworkVersion(p, framework, version))
+    );
+  }
+
+  const url = lib.urls.find((u) => u.url === citation);
+  if (!url) return false;
+  const kindOk =
+    !Array.isArray(url.appliesTo) ||
+    url.appliesTo.length === 0 ||
+    url.appliesTo.includes(candidateKind);
+  const versionOk =
+    url.applicableFrameworks.includes("*") ||
+    url.applicableFrameworks.some((p) => matchesFrameworkVersion(p, framework, version));
+  return kindOk && versionOk;
+}
+
+async function knownCitation(citation) {
+  return Boolean((await lookupUrl(citation)) || (await lookupSkillRule(citation)));
+}
+
+function toStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string" && v.length > 0);
+}
+
+function nonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}