opencode-skills-collection 3.0.35 → 3.0.36

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

@@ -0,0 +1,106 @@
+// 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/bundled-skills/vercel-optimize/lib/support-topics.mjs

@@ -0,0 +1,355 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gates } from './gates/index.mjs';
+import { SCANNER_GATES } from './gates/scanner-driven.mjs';
+import {
+  loadLibrary,
+  lookupSkillRule,
+  lookupUrl,
+  matchesFrameworkVersion,
+} from './citations.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;
+}