Pre Release

1// Append a caveat (don't drop — customer may opt in to canary) when a
2// fix needs a canary/rc/beta dep version.
3
4import { matchesFrameworkVersion } from '../citations.mjs';
5
6const PRE_RELEASE_FEATURES = [
7  {
8    match: /\bppr\b|partial[- ]?prerendering/i,
9    requires: 'next@canary',
10    message: 'PPR is experimental — verify your Next.js version supports it as stable',
11  },
12  {
13    match: /\buse cache['"]?\s*directive\b|"use cache"|'use cache'/i,
14    requires: 'next@>=15.0.0',
15    message: 'use cache directive is stable in 15+',
16  },
17  {
18    match: /\bcacheLife\(/i,
19    requires: 'next@>=15.0.0',
20    message: 'cacheLife is stable in 15+',
21  },
22  {
23    match: /\bcacheTag\(/i,
24    requires: 'next@>=15.0.0',
25    message: 'cacheTag is stable in 15+',
26  },
27];
28
29const SEMVER_PRE_RELEASE_RE = /\b([\w-]+)@(\d+\.\d+\.\d+-(?:rc|beta|canary|alpha|next|exp)[\w.-]*)/g;
30
31export const metadata = {
32  id: 'pre-release',
33  description: 'Append caveat when fix targets a canary/rc/beta feature.',
34};
35
36export function apply(rec, ctx = {}) {
37  const text = [rec.fix, rec.currentBehavior, rec.desiredBehavior]
38    .filter((s) => typeof s === 'string')
39    .join('\n');
40  if (!text) return {};
41
42  const tags = [];
43  const caveats = [];
44
45  for (const feat of PRE_RELEASE_FEATURES) {
46    if (feat.match.test(text)) {
47      if (featureAvailableForStack(feat, ctx)) continue;
48      const tag = `pre-release:${feat.requires}`;
49      if (!tags.includes(tag)) {
50        tags.push(tag);
51        caveats.push(`Requires ${feat.requires} (${feat.message}).`);
52      }
53    }
54  }
55
56  for (const m of text.matchAll(SEMVER_PRE_RELEASE_RE)) {
57    const [, pkg, version] = m;
58    const tag = `pre-release:${pkg}@${version}`;
59    if (!tags.includes(tag)) {
60      tags.push(tag);
61      caveats.push(`Requires pre-release version: \`${pkg}@${version}\`.`);
62    }
63  }
64
65  if (tags.length === 0) return {};
66  const caveatBlock = '\n\n_Note: ' + caveats.join(' ') + '_';
67  if (typeof rec.fix === 'string') rec.fix += caveatBlock;
68  return { tags, needsReview: true };
69}
70
71function featureAvailableForStack(feat, ctx) {
72  if (!ctx?.framework || !ctx?.version) return false;
73  return matchesFrameworkVersion(feat.requires, ctx.framework, ctx.version);
74}