Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(audit): keep AI recommendations to page facts and 150-character copy (#1132)

Cihan393dc6a34376
diff --git a/server/src/lib/audit/host.js b/server/src/lib/audit/host.js
index c0952bd14..63051c0a2 100644
--- a/server/src/lib/audit/host.js
+++ b/server/src/lib/audit/host.js
@@ -24,3 +24,12 @@ export function normStoredDomain(domain) {
const value = String(domain).trim();
return normHost(/^https?:\/\//i.test(value) ? value : `https://${value}`);
}
+
+/** True when `url` is on one of the stored brand domains or a subdomain of one. */
+export function onBrandDomain(url, domains) {
+ const host = normHost(url);
+ if (!host) return false;
+ return (domains ?? [])
+ .map(normStoredDomain)
+ .some((d) => d && (host === d || host.endsWith(`.${d}`)));
+}
diff --git a/server/src/lib/audit/host.test.js b/server/src/lib/audit/host.test.js
index e4504dc32..da074b976 100644
--- a/server/src/lib/audit/host.test.js
+++ b/server/src/lib/audit/host.test.js
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { normHost, normStoredDomain } from './host.js';
+import { normHost, normStoredDomain, onBrandDomain } from './host.js';
describe('normHost', () => {
it('lowercases, strips a leading www. and ignores path, query and fragment', () => {
@@ -51,3 +51,18 @@ describe('normStoredDomain', () => {
expect(normStoredDomain('not a domain')).toBeNull();
});
});
+
+describe('onBrandDomain', () => {
+ it('matches the brand domain however it is stored, and its subdomains', () => {
+ expect(onBrandDomain('https://www.acme.com/pricing', ['https://Acme.com/'])).toBe(true);
+ expect(onBrandDomain('https://blog.acme.com/post', ['acme.com'])).toBe(true);
+ expect(onBrandDomain('https://shop.example.org/', ['acme.com', 'example.org'])).toBe(true);
+ });
+
+ it('rejects another site, a look-alike host and a brand without domains', () => {
+ expect(onBrandDomain('https://competitor.com/pricing', ['acme.com'])).toBe(false);
+ expect(onBrandDomain('https://notacme.com/', ['acme.com'])).toBe(false);
+ expect(onBrandDomain('https://acme.com/', [])).toBe(false);
+ expect(onBrandDomain('not a url', ['acme.com'])).toBe(false);
+ });
+});
diff --git a/server/src/lib/audit/recommendation-guard.js b/server/src/lib/audit/recommendation-guard.js
new file mode 100644
index 000000000..038313ece
--- /dev/null
+++ b/server/src/lib/audit/recommendation-guard.js
@@ -0,0 +1,457 @@
+/**
+ * Keeps AI fix recommendations truthful and short before they're saved. The
+ * model gets the same rules in its prompt; this is the server-side check.
+ *
+ * - Facts: a number, percentage, price, date or company name must appear in
+ * the page or in the brand data the model was given. Anything else becomes
+ * a [placeholder] the user fills in with real data.
+ * - Length: the explanation and every sentence of the paste-able draft are at
+ * most 150 characters. Code (JSON-LD/HTML) is exempt from the length rule,
+ * not from the facts rule.
+ */
+
+export const MAX_COPY_CHARS = 150;
+
+export const PLACEHOLDER = {
+ name: '[customer name]',
+ metric: '[real metric]',
+ price: '[price]',
+ date: '[date]',
+};
+
+// A placeholder already in the text, e.g. "[customer name]". Letters and
+// spaces only, so a JSON array such as ["a", "b"] never reads as one.
+const PLACEHOLDER_SOURCE = String.raw`\[[A-Za-z][A-Za-z ]{1,38}\]`;
+
+// Left as they are: URLs and domains (their digits aren't claims) and the
+// placeholders the model already wrote.
+const MASK_RE = new RegExp(
+ [
+ String.raw`\bhttps?:\/\/[^\s"'<>)]+`,
+ String.raw`\bwww\.[^\s"'<>)]+`,
+ String.raw`\b[\w-]+(?:\.[\w-]+)*\.(?:com|org|net|io|ai|co|dev|app|edu|gov|info)\b(?:\/[^\s"'<>)]*)?`,
+ PLACEHOLDER_SOURCE,
+ ].join('|'),
+ 'gi',
+);
+
+const NUM = String.raw`\d+(?:[.,]\d+)*`;
+const MONTH = String.raw`(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)`;
+
+// One pass over the text, most specific shape first.
+const VALUE_RE = new RegExp(
+ [
+ `(?<date>\\b\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?(?![\\w-])|\\b${MONTH}\\.?\\s+\\d{1,2}(?:st|nd|rd|th)?(?:,?\\s+\\d{4})?\\b|\\b\\d{1,2}(?:st|nd|rd|th)?\\s+${MONTH}\\.?(?:\\s+\\d{4})?\\b|\\b${MONTH}\\.?\\s+\\d{4}\\b)`,
+ `(?<price>[$€£¥₹₺]\\s?${NUM}(?:\\s?(?:k|m|bn)\\b)?|\\b${NUM}\\s?(?:usd|eur|gbp|try|dollars?|euros?|pounds?)\\b)`,
+ `(?<percent>\\b${NUM}\\s?(?:%|percent\\b|per cent\\b))`,
+ `(?<year>\\b(?:19|20)\\d{2}\\b)`,
+ `(?<number>(?<![\\w.#/-])${NUM}(?:\\s?[–-]\\s?${NUM})?(?:[kmx×+](?![a-z])|\\s?(?:million|billion|thousand)\\b)?(?![\\w%]))`,
+ ].join('|'),
+ 'gi',
+);
+
+// "Write a 120–150 character description", "add 3–5 questions": writing
+// instructions, not claims. Only the explanation may use them.
+const INSTRUCTION_UNIT_RE =
+ /^\s*(?:[a-z-]+\s+){0,2}(?:characters?|chars?|words?|sentences?|paragraphs?|questions?|q&as?|pairs?|answers?|items?|bullets?|points?|steps?|headings?|subheadings?|h[1-6]s?|sections?|links?|sources?|citations?|examples?|faqs?|lines?|tips?|terms?|definitions?|quotes?|quotations?|statistics?|stats?|images?)\b/i;
+
+// "A Flesch reading ease of 60", "a score above 70": targets to aim for.
+const TARGET_BEFORE_RE =
+ /\b(?:score|ease|grade|rating|ratio|density)\s+(?:of\s+)?(?:at least\s+|above\s+|below\s+|under\s+|over\s+|around\s+)?$/i;
+
+// "Step 2", "Top 10", or "1." at the start of a line: numbering, not data.
+const NUMBERING_WORD_RE = /\b(?:step|part|phase|tier|level|top)\s*$/i;
+const NUMBERING_AFTER_RE = /^[.)]\s/;
+// JSON-LD keys whose numbers are structure, not claims ("position": 1).
+const STRUCTURAL_JSON_KEY_RE = /^(?:position|width|height)$/i;
+
+// Words that introduce a company or customer name: "brands like TechFlow".
+const NAME_CUE_RE =
+ /\b(?:(?:brands|companies|customers|clients|teams|partners|businesses|organi[sz]ations)\s+(?:like|such as|including)|trusted by|used by|loved by|chosen by|relied on by|teams at|worked with)\s+/gi;
+// CamelCase names such as "TechFlow" or "HubSpot".
+const CAMEL_RE = /\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+\b/g;
+const CAPITALISED_RE = /^[A-Z][\w&'’.-]*/;
+
+// Platforms a recommendation may always name: the AI engines and sources the
+// whole product is about.
+const ALWAYS_KNOWN_NAMES = new Set(
+ [
+ 'Google',
+ 'ChatGPT',
+ 'OpenAI',
+ 'Perplexity',
+ 'Gemini',
+ 'Claude',
+ 'Anthropic',
+ 'Copilot',
+ 'Microsoft',
+ 'Bing',
+ 'Grok',
+ 'DeepSeek',
+ 'Meta',
+ 'Wikipedia',
+ 'Wikidata',
+ 'YouTube',
+ 'Reddit',
+ 'LinkedIn',
+ 'Quora',
+ 'GitHub',
+ 'G2',
+ 'Capterra',
+ 'Trustpilot',
+ 'Schema.org',
+ 'JavaScript',
+ 'WordPress',
+ 'TypeScript',
+ 'PageSpeed',
+ 'OpenGraph',
+ // AI crawlers a recommendation may name
+ 'PerplexityBot',
+ 'ClaudeBot',
+ 'SearchBot',
+ 'SaaS',
+ 'PhD',
+ 'AI Overviews',
+ 'AI Mode',
+ // schema.org types a recommendation may name
+ 'HowTo',
+ 'BlogPosting',
+ 'NewsArticle',
+ 'WebPage',
+ 'WebSite',
+ 'AboutPage',
+ 'ContactPage',
+ 'CollectionPage',
+ 'ProfilePage',
+ 'LocalBusiness',
+ 'SoftwareApplication',
+ 'ItemList',
+ 'ListItem',
+ 'BreadcrumbList',
+ 'AggregateRating',
+ 'QAPage',
+ 'ImageObject',
+ 'VideoObject',
+ 'ContactPoint',
+ 'PostalAddress',
+ 'DefinedTerm',
+ 'DefinedTermSet',
+ 'JobPosting',
+ ].map((n) => n.toLowerCase()),
+);
+
+function normNumber(raw) {
+ const n = Number(raw.replace(/,/g, ''));
+ return Number.isFinite(n) ? String(n) : raw;
+}
+
+function digitGroups(text) {
+ return text.match(/\d+(?:[.,]\d+)*/g) ?? [];
+}
+
+// Numbers the known text uses as percentages, and as prices (next to a
+// currency, or as a JSON-LD price).
+const KNOWN_PERCENT_RE = /(\d+(?:[.,]\d+)*)\s?(?:%|percent\b|per cent\b)/gi;
+const KNOWN_PRICE_RE =
+ /[$€£¥₹₺]\s?(\d+(?:[.,]\d+)*)|(\d+(?:[.,]\d+)*)\s?(?:usd|eur|gbp|try|dollars?|euros?|pounds?)\b|"(?:price|lowPrice|highPrice|amount)"\s*:\s*"?(\d+(?:[.,]\d+)*)/gi;
+
+function numberSet(groups) {
+ const set = new Set();
+ for (const group of groups) {
+ set.add(normNumber(group));
+ set.add(group);
+ }
+ return set;
+}
+
+/**
+ * @typedef {Object} KnownFacts
+ * @property {string} text all known text, lowercased
+ * @property {Set<string>} numbers every number in it
+ * @property {Set<string>} percents numbers it uses as percentages
+ * @property {Set<string>} prices numbers it uses as prices
+ */
+
+/**
+ * Everything a recommendation may quote: the page's text, title, meta tags
+ * and JSON-LD, plus the brand data the model was given.
+ *
+ * @param {{ pageText?: string, extras?: string[], brand?: { name?: string|null, description?: string|null, domains?: string[] } | null }} input
+ * @returns {KnownFacts}
+ */
+export function buildKnownFacts({ pageText = '', extras = [], brand = null } = {}) {
+ const parts = [pageText, ...extras];
+ if (brand) parts.push(brand.name ?? '', brand.description ?? '', ...(brand.domains ?? []));
+ const text = parts.filter(Boolean).join(' \n ');
+ return {
+ text: text.toLowerCase(),
+ numbers: numberSet(digitGroups(text)),
+ percents: numberSet([...text.matchAll(KNOWN_PERCENT_RE)].map((m) => m[1])),
+ prices: numberSet([...text.matchAll(KNOWN_PRICE_RE)].map((m) => m[1] ?? m[2] ?? m[3])),
+ };
+}
+
+/** Runs `fn` on the stretches of `text` outside URLs and placeholders. */
+function outsideMasks(text, fn) {
+ let out = '';
+ let last = 0;
+ for (const m of text.matchAll(MASK_RE)) {
+ out += fn(text.slice(last, m.index), out);
+ out += m[0];
+ last = m.index + m[0].length;
+ }
+ return out + fn(text.slice(last), out);
+}
+
+function numbersIn(value, set) {
+ return digitGroups(value).every((g) => set.has(normNumber(g)) || set.has(g));
+}
+
+// The JSON-LD key a value belongs to.
+function jsonKey(before) {
+ return before.match(/"([@\w]+)"\s*:\s*"?[^"]*$/)?.[1] ?? '';
+}
+
+// In JSON-LD, the key a value belongs to picks the placeholder: "price": 49
+// becomes "price": "[price]".
+function jsonPlaceholder(key, fallback) {
+ if (/price|amount|cost/i.test(key)) return PLACEHOLDER.price;
+ if (/date|time|year/i.test(key)) return PLACEHOLDER.date;
+ return fallback;
+}
+
+/**
+ * Replaces numbers, percentages, prices and dates that the page and brand
+ * data don't contain.
+ *
+ * @param {string} text
+ * @param {KnownFacts} known
+ * @param {{ field: 'recommendation' | 'draft' | 'code' }} opts
+ * @returns {{ text: string, hits: number }}
+ */
+export function replaceUnknownValues(text, known, { field }) {
+ let hits = 0;
+ const result = outsideMasks(text, (chunk, done) =>
+ chunk.replace(VALUE_RE, (match, ...args) => {
+ const groups = args.at(-1);
+ const offset = args.at(-3);
+ const before = done + chunk.slice(0, offset);
+ const after = chunk.slice(offset + match.length);
+
+ // "2000 words" is a count, not a year.
+ const isYear = groups.year && !INSTRUCTION_UNIT_RE.test(after);
+ let placeholder;
+ if (groups.date) {
+ // An ISO date is known when its day is, whatever time follows it.
+ const day = /^\d{4}-\d{2}-\d{2}/.test(match) ? match.slice(0, 10) : match;
+ if (known.text.includes(day.toLowerCase())) return match;
+ placeholder = PLACEHOLDER.date;
+ } else if (groups.price) {
+ if (numbersIn(match, known.prices)) return match;
+ placeholder = PLACEHOLDER.price;
+ } else if (groups.percent) {
+ if (numbersIn(match, known.percents)) return match;
+ placeholder = PLACEHOLDER.metric;
+ } else if (isYear) {
+ if (numbersIn(match, known.numbers)) return match;
+ placeholder = PLACEHOLDER.date;
+ } else {
+ if (numbersIn(match, known.numbers)) return match;
+ if (field === 'recommendation' && INSTRUCTION_UNIT_RE.test(after)) return match;
+ if (field === 'recommendation' && TARGET_BEFORE_RE.test(before)) return match;
+ if (field === 'code' && STRUCTURAL_JSON_KEY_RE.test(jsonKey(before))) return match;
+ if (field !== 'code' && /^\d+$/.test(match)) {
+ const line = before.slice(before.lastIndexOf('\n') + 1);
+ if (NUMBERING_WORD_RE.test(line)) return match;
+ if (/^\s*$/.test(line) && NUMBERING_AFTER_RE.test(after)) return match;
+ }
+ placeholder = PLACEHOLDER.metric;
+ }
+
+ hits += 1;
+ if (field !== 'code') return placeholder;
+ const chosen = jsonPlaceholder(jsonKey(before), placeholder);
+ // A bare JSON number needs quotes to stay valid JSON.
+ return /:\s*$/.test(before) ? `"${chosen}"` : chosen;
+ }),
+ );
+ return { text: result, hits };
+}
+
+function nameKnown(name, known) {
+ const lower = name.toLowerCase();
+ return ALWAYS_KNOWN_NAMES.has(lower) || known.text.includes(lower);
+}
+
+// The names listed right after a cue: "TechFlow, Acme Corp and Zenith".
+function namesAfterCue(rest) {
+ const names = [];
+ let pos = 0;
+ for (;;) {
+ const lead = rest.slice(pos).match(/^\s*/)[0].length;
+ const word = rest.slice(pos + lead).match(CAPITALISED_RE);
+ if (!word) break;
+ let start = pos + lead;
+ let end = start + word[0].length;
+ // Further capitalised words belong to the same name ("Blue Bottle Coffee").
+ for (let m; (m = rest.slice(end).match(/^\s+([A-Z][\w&'’.-]*)/)); ) end += m[0].length;
+ const raw = rest.slice(start, end);
+ const name = raw.replace(/[.,;:]+$/, '');
+ names.push({ start, end: start + name.length, name });
+ const sep = rest.slice(start + name.length).match(/^\s*(?:,|and\b|or\b|&)\s*/i);
+ if (!sep) break;
+ pos = start + name.length + sep[0].length;
+ }
+ return names;
+}
+
+/**
+ * Replaces company and customer names the page and brand data don't contain:
+ * CamelCase names anywhere, and capitalised names after "like", "such as",
+ * "trusted by" and similar.
+ *
+ * @param {string} text
+ * @param {KnownFacts} known
+ * @returns {{ text: string, hits: number }}
+ */
+export function replaceUnknownNames(text, known) {
+ let hits = 0;
+ const result = outsideMasks(text, (chunk) => {
+ const spans = [];
+ for (const cue of chunk.matchAll(NAME_CUE_RE)) {
+ const from = cue.index + cue[0].length;
+ for (const n of namesAfterCue(chunk.slice(from))) {
+ spans.push({ start: from + n.start, end: from + n.end, name: n.name });
+ }
+ }
+ for (const m of chunk.matchAll(CAMEL_RE)) {
+ spans.push({ start: m.index, end: m.index + m[0].length, name: m[0] });
+ }
+ const unknown = spans
+ .filter((s) => !nameKnown(s.name, known))
+ .sort((a, b) => a.start - b.start)
+ .filter((s, i, all) => i === 0 || s.start >= all[i - 1].end);
+ let out = '';
+ let last = 0;
+ for (const s of unknown) {
+ out += chunk.slice(last, s.start) + PLACEHOLDER.name;
+ last = s.end;
+ hits += 1;
+ }
+ return out + chunk.slice(last);
+ });
+ // "[customer name], [customer name] and [customer name]" reads as one.
+ const collapsed = result.replace(
+ /\[customer name\](?:\s*(?:,|and|or|&)\s*\[customer name\])+/g,
+ PLACEHOLDER.name,
+ );
+ return { text: collapsed, hits };
+}
+
+/**
+ * The facts rule for one recommendation.
+ *
+ * @template {{ recommendation: string, draft: string|null, code?: string|null }} R
+ * @param {R} rec
+ * @param {KnownFacts} known
+ * @returns {{ rec: R, hits: number }}
+ */
+export function guardFacts(rec, known) {
+ let hits = 0;
+ const prose = (text, field) => {
+ if (!text) return text ?? null;
+ const values = replaceUnknownValues(text, known, { field });
+ const names = replaceUnknownNames(values.text, known);
+ hits += values.hits + names.hits;
+ return names.text;
+ };
+ const recommendation = prose(rec.recommendation, 'recommendation');
+ const draft = prose(rec.draft, 'draft');
+ let code = rec.code ?? null;
+ if (code) {
+ const values = replaceUnknownValues(code, known, { field: 'code' });
+ hits += values.hits;
+ code = values.text;
+ }
+ return { rec: { ...rec, recommendation, draft, code }, hits };
+}
+
+// Where one sentence of a line ends and the next begins.
+const SENTENCE_BREAK_RE = /(?<=[.!?…])\s+(?=["“'([A-Z0-9])/;
+
+/** Sentences of a draft, line by line. */
+export function sentencesOf(text) {
+ return (text ?? '')
+ .split('\n')
+ .flatMap((line) => line.split(SENTENCE_BREAK_RE))
+ .map((s) => s.trim())
+ .filter(Boolean);
+}
+
+/** Which parts of a recommendation are over the limit. */
+export function tooLongParts(rec) {
+ return {
+ recommendation: (rec.recommendation ?? '').length > MAX_COPY_CHARS,
+ draft: sentencesOf(rec.draft).some((s) => s.length > MAX_COPY_CHARS),
+ };
+}
+
+/** True when the explanation or a draft sentence is over the limit. */
+export function needsShortening(rec) {
+ const parts = tooLongParts(rec);
+ return parts.recommendation || parts.draft;
+}
+
+/**
+ * Cuts `text` to at most `max` characters at a word boundary, ending in "…".
+ * A link the cut would split is left out whole.
+ */
+export function cutAtWord(text, max = MAX_COPY_CHARS) {
+ if (text.length <= max) return text;
+ let head = text.slice(0, max - 1);
+ const link = [...text.matchAll(/https?:\/\/\S+/g)].find(
+ (m) => m.index < max - 1 && m.index + m[0].length > max - 1,
+ );
+ if (link) head = text.slice(0, link.index);
+ else {
+ const space = head.lastIndexOf(' ');
+ if (space > max * 0.6) head = head.slice(0, space);
+ }
+ return `${head.replace(/[\s,;:–-]+$/, '')}…`;
+}
+
+/**
+ * The last resort after one rewrite: the explanation keeps its first
+ * sentence when that fits, and any long sentence is cut at a word boundary.
+ *
+ * @template {{ recommendation: string, draft: string|null }} R
+ * @param {R} rec
+ * @returns {{ rec: R, cuts: number }}
+ */
+export function cutToLength(rec) {
+ let cuts = 0;
+ let recommendation = rec.recommendation ?? '';
+ if (recommendation.length > MAX_COPY_CHARS) {
+ const first = sentencesOf(recommendation)[0] ?? '';
+ recommendation = first.length <= MAX_COPY_CHARS ? first : cutAtWord(recommendation);
+ cuts += 1;
+ }
+ let draft = rec.draft ?? null;
+ if (draft && needsShortening({ recommendation: '', draft })) {
+ draft = draft
+ .split('\n')
+ .map((line) =>
+ line
+ .split(SENTENCE_BREAK_RE)
+ .map((s) => {
+ if (s.trim().length <= MAX_COPY_CHARS) return s;
+ cuts += 1;
+ const lead = s.match(/^\s*/)[0];
+ return lead + cutAtWord(s.trim());
+ })
+ .join(' '),
+ )
+ .join('\n');
+ }
+ return { rec: { ...rec, recommendation, draft }, cuts };
+}
diff --git a/server/src/lib/audit/recommendation-guard.test.js b/server/src/lib/audit/recommendation-guard.test.js
new file mode 100644
index 000000000..9ee58bc5d
--- /dev/null
+++ b/server/src/lib/audit/recommendation-guard.test.js
@@ -0,0 +1,291 @@
+import { describe, expect, it } from 'vitest';
+import {
+ MAX_COPY_CHARS,
+ buildKnownFacts,
+ cutAtWord,
+ cutToLength,
+ guardFacts,
+ needsShortening,
+ replaceUnknownNames,
+ replaceUnknownValues,
+ sentencesOf,
+} from './recommendation-guard.js';
+
+// The pricing page from the spec's bug report, cut down.
+const PRICING_PAGE =
+ 'Ansvisor pricing. Starter $49 per month: 100 site audits, 50 prompts. ' +
+ 'Growth $249 per month: 500 site audits. Track ChatGPT, Perplexity and Google AI Overviews. ' +
+ 'Last updated October 2026.';
+
+const known = buildKnownFacts({
+ pageText: PRICING_PAGE,
+ extras: ['Ansvisor pricing: plans for every team'],
+ brand: { name: 'Ansvisor', description: 'AI visibility platform', domains: ['ansvisor.com'] },
+});
+
+const rec = (over = {}) => ({
+ signalKey: 'case-study-evidence',
+ priority: 'medium',
+ recommendation: 'Add one real customer result next to the plans.',
+ draft: null,
+ code: null,
+ ...over,
+});
+
+describe('guardFacts', () => {
+ it("replaces the spec's invented customer and percentage with placeholders", () => {
+ const { rec: out, hits } = guardFacts(
+ rec({
+ draft:
+ "Join brands like TechFlow, which saw a 34% increase in 'Recommended' citations with Growth.",
+ }),
+ known,
+ );
+ expect(out.draft).toBe(
+ "Join brands like [customer name], which saw a [real metric] increase in 'Recommended' citations with Growth.",
+ );
+ expect(hits).toBe(2);
+ });
+
+ it('replaces a price the page does not show and keeps the ones it does', () => {
+ const { rec: out } = guardFacts(
+ rec({ draft: 'Starter is $49 per month, Growth $249, and Pro costs $799 per month.' }),
+ known,
+ );
+ expect(out.draft).toBe(
+ 'Starter is $49 per month, Growth $249, and Pro costs [price] per month.',
+ );
+ });
+
+ it('keeps the brand, the AI platforms and known names, and replaces an unknown CamelCase name', () => {
+ const { rec: out } = guardFacts(
+ rec({
+ recommendation: 'Say Ansvisor tracks ChatGPT and Perplexity answers, as HubSpot does.',
+ }),
+ known,
+ );
+ expect(out.recommendation).toBe(
+ 'Say Ansvisor tracks ChatGPT and Perplexity answers, as [customer name] does.',
+ );
+ });
+
+ it('turns a list of unknown customers into one placeholder', () => {
+ const { rec: out, hits } = guardFacts(
+ rec({ draft: 'Trusted by Acme Corp, Zenith and Bolt Labs to track AI answers.' }),
+ known,
+ );
+ expect(out.draft).toBe('Trusted by [customer name] to track AI answers.');
+ expect(hits).toBe(3);
+ });
+
+ it('keeps writing-instruction numbers in the explanation only', () => {
+ const { rec: out } = guardFacts(
+ rec({
+ recommendation: 'Write a 120–150 character meta description and add 3–5 FAQ questions.',
+ draft: 'Answer 7 common questions about plans.',
+ }),
+ known,
+ );
+ expect(out.recommendation).toBe(
+ 'Write a 120–150 character meta description and add 3–5 FAQ questions.',
+ );
+ expect(out.draft).toBe('Answer [real metric] common questions about plans.');
+ });
+
+ it('keeps list numbering and the numbers the page has', () => {
+ const { rec: out } = guardFacts(
+ rec({ draft: '1. Pick a plan with 500 site audits.\nStep 2: connect 50 prompts.' }),
+ known,
+ );
+ expect(out.draft).toBe('1. Pick a plan with 500 site audits.\nStep 2: connect 50 prompts.');
+ });
+
+ it("keeps known dates and the page's month, and replaces an invented date or year", () => {
+ const { rec: out } = guardFacts(
+ rec({
+ draft: 'Updated October 2026. Launched in March 2021 and rated best tool of 2023.',
+ }),
+ known,
+ );
+ expect(out.draft).toBe(
+ 'Updated October 2026. Launched in [date] and rated best tool of [date].',
+ );
+ });
+
+ it('keeps the names of AI crawlers and Open Graph', () => {
+ const { rec: out, hits } = guardFacts(
+ rec({
+ recommendation: 'Add OpenGraph tags and let PerplexityBot, ClaudeBot and OAI-SearchBot in.',
+ }),
+ known,
+ );
+ expect(hits).toBe(0);
+ expect(out.recommendation).toContain('OpenGraph');
+ });
+
+ it('leaves URLs, domains and existing placeholders alone', () => {
+ const draft =
+ 'Cite developers.google.com/search/docs/2024 and https://example.org/report-2025?id=7 for [real metric].';
+ const { rec: out, hits } = guardFacts(rec({ draft }), known);
+ expect(out.draft).toBe(draft);
+ expect(hits).toBe(0);
+ });
+
+ it('keeps the JSON-LD valid: an unknown price becomes a quoted placeholder', () => {
+ const code = JSON.stringify(
+ {
+ '@context': 'https://schema.org',
+ '@type': 'Product',
+ name: 'Ansvisor Growth',
+ offers: { '@type': 'Offer', price: 799, priceCurrency: 'USD' },
+ aggregateRating: { '@type': 'AggregateRating', ratingValue: '4.8', reviewCount: 312 },
+ datePublished: '2024-01-15',
+ itemListElement: [{ '@type': 'ListItem', position: 1 }],
+ },
+ null,
+ 2,
+ );
+ const { rec: out } = guardFacts(rec({ code }), known);
+ const parsed = JSON.parse(out.code);
+ expect(parsed.offers.price).toBe('[price]');
+ expect(parsed.aggregateRating.ratingValue).toBe('[real metric]');
+ expect(parsed.aggregateRating.reviewCount).toBe('[real metric]');
+ expect(parsed.datePublished).toBe('[date]');
+ expect(parsed.itemListElement[0].position).toBe(1);
+ expect(parsed['@context']).toBe('https://schema.org');
+ });
+
+ it('keeps a known plan price in JSON-LD', () => {
+ const { rec: out } = guardFacts(
+ rec({ code: '{"price": "249.00", "priceCurrency": "USD"}' }),
+ known,
+ );
+ expect(out.code).toBe('{"price": "249.00", "priceCurrency": "USD"}');
+ });
+
+ it('checks nothing from the brand data when none was given', () => {
+ const pageOnly = buildKnownFacts({ pageText: 'A coffee roaster in Leeds.' });
+ expect(replaceUnknownNames('Teams at Ansvisor, like ExampleCo.', pageOnly).text).toBe(
+ 'Teams at [customer name], like [customer name].',
+ );
+ });
+});
+
+describe('replaceUnknownValues', () => {
+ it('replaces an invented ISO datetime whole, and keeps one whose day the page has', () => {
+ const page = buildKnownFacts({ pageText: 'Updated 2026-10-01.' });
+ expect(
+ replaceUnknownValues('{"dateModified": "2024-05-01T10:00:00Z"}', page, { field: 'code' })
+ .text,
+ ).toBe('{"dateModified": "[date]"}');
+ expect(
+ replaceUnknownValues('{"dateModified": "2026-10-01T08:30:00+03:00"}', page, { field: 'code' })
+ .text,
+ ).toBe('{"dateModified": "2026-10-01T08:30:00+03:00"}');
+ });
+
+ it('reads a year-shaped count as a count', () => {
+ const page = buildKnownFacts({ pageText: 'A short guide.' });
+ expect(
+ replaceUnknownValues('Expand the guide to about 2000 words.', page, {
+ field: 'recommendation',
+ }).text,
+ ).toBe('Expand the guide to about 2000 words.');
+ expect(
+ replaceUnknownValues('A 2000 word guide, updated since 2019.', page, { field: 'draft' }).text,
+ ).toBe('A [real metric] word guide, updated since [date].');
+ });
+
+ it('needs a percentage or price to be one on the page, not just the same number', () => {
+ const page = buildKnownFacts({
+ pageText: 'Free shipping over $30. Ships in 48 hours. 20% off.',
+ });
+ expect(
+ replaceUnknownValues('48% reorder, 30% save and 20% off; from $48, over $30.', page, {
+ field: 'draft',
+ }).text,
+ ).toBe('[real metric] reorder, [real metric] save and 20% off; from [price], over $30.');
+ });
+
+ it('keeps score targets in the explanation', () => {
+ const page = buildKnownFacts({ pageText: 'Long paragraphs.' });
+ expect(
+ replaceUnknownValues('Aim for a Flesch reading ease of 60 or a score above 70.', page, {
+ field: 'recommendation',
+ }).text,
+ ).toBe('Aim for a Flesch reading ease of 60 or a score above 70.');
+ });
+
+ const page = buildKnownFacts({ pageText: 'Over 1,200 roasters use it.' });
+
+ it('matches numbers written with or without thousands separators', () => {
+ expect(replaceUnknownValues('Join 1200 roasters.', page, { field: 'draft' }).text).toBe(
+ 'Join 1200 roasters.',
+ );
+ expect(replaceUnknownValues('Join 5,000+ roasters.', page, { field: 'draft' }).text).toBe(
+ 'Join [real metric] roasters.',
+ );
+ });
+
+ it('treats a percentage, a multiple and "k" amounts as metrics', () => {
+ const { text, hits } = replaceUnknownValues('Grew 3x to 40k visits, up 25 percent.', page, {
+ field: 'draft',
+ });
+ expect(text).toBe('Grew [real metric] to [real metric] visits, up [real metric].');
+ expect(hits).toBe(3);
+ });
+
+ it('ignores digits that are part of a word, such as H2 or v3', () => {
+ expect(
+ replaceUnknownValues('Use an H2 per question in v3.', page, { field: 'draft' }).text,
+ ).toBe('Use an H2 per question in v3.');
+ });
+});
+
+describe('length', () => {
+ const long = `${'Explain how each plan maps to team size, '.repeat(4)}and which audits are included.`;
+
+ it('flags an explanation or a draft sentence over 150 characters', () => {
+ expect(long.length).toBeGreaterThan(MAX_COPY_CHARS);
+ expect(needsShortening(rec({ recommendation: long }))).toBe(true);
+ expect(needsShortening(rec({ draft: `Short one. ${long}` }))).toBe(true);
+ expect(needsShortening(rec({ draft: 'Short one.\nAnother short one.' }))).toBe(false);
+ });
+
+ it('never counts the code', () => {
+ expect(needsShortening(rec({ code: `{"text": "${long}${long}"}` }))).toBe(false);
+ });
+
+ it('cuts at a word boundary, ending in an ellipsis, within the limit', () => {
+ const cut = cutAtWord(long);
+ expect(cut.length).toBeLessThanOrEqual(MAX_COPY_CHARS);
+ expect(cut.endsWith('…')).toBe(true);
+ expect(long.startsWith(cut.slice(0, -1))).toBe(true);
+ expect(long[cut.length - 1]).toBe(' ');
+ });
+
+ it('leaves a link out whole rather than cutting through it', () => {
+ const text = `${'Cite the guide on structured data for answers, '.repeat(2)}see https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data for details.`;
+ const cut = cutAtWord(text);
+ expect(cut.length).toBeLessThanOrEqual(MAX_COPY_CHARS);
+ expect(cut).not.toContain('https://');
+ expect(cut.endsWith('see…')).toBe(true);
+ });
+
+ it("keeps the explanation's first sentence when that fits", () => {
+ const { rec: out, cuts } = cutToLength(
+ rec({ recommendation: `Add a customer result next to the plans. ${long}` }),
+ );
+ expect(out.recommendation).toBe('Add a customer result next to the plans.');
+ expect(cuts).toBe(1);
+ });
+
+ it('cuts only the long sentences of a draft and keeps its lines', () => {
+ const { rec: out, cuts } = cutToLength(rec({ draft: `Plans for every team.\nShort. ${long}` }));
+ const lines = out.draft.split('\n');
+ expect(lines[0]).toBe('Plans for every team.');
+ expect(lines[1].startsWith('Short. ')).toBe(true);
+ expect(sentencesOf(out.draft).every((s) => s.length <= MAX_COPY_CHARS)).toBe(true);
+ expect(cuts).toBe(1);
+ });
+});
diff --git a/server/src/lib/audit/recommendations.js b/server/src/lib/audit/recommendations.js
index 5059fe11b..68bef918c 100644
--- a/server/src/lib/audit/recommendations.js
+++ b/server/src/lib/audit/recommendations.js
@@ -8,6 +8,10 @@
* Mechanical/config signals (add a video, enable HTTPS, fix viewport,
* alt-text…) are excluded — their generic howToFix is already actionable and
* the LLM can't add page-specific value.
+ *
+ * Before saving, recommendation-guard.js swaps facts the page and brand data
+ * don't contain for [placeholders] and holds the copy to 150 characters per
+ * sentence (one rewrite, then a cut at a word boundary).
*/
import { generateObject } from 'ai';
@@ -16,6 +20,15 @@ import { resolveModel } from '../ai-provider.js';
import { signalsByKey } from './rubric.js';
import { withRetry } from '../retry.js';
import { logger } from '../logger.js';
+import { onBrandDomain } from './host.js';
+import {
+ MAX_COPY_CHARS,
+ buildKnownFacts,
+ cutToLength,
+ guardFacts,
+ needsShortening,
+ tooLongParts,
+} from './recommendation-guard.js';
const DEFAULT_MODEL = 'google/gemini-3-flash-preview';
@@ -61,32 +74,127 @@ const recommendationsSchema = z.object({
priority: z.enum(['high', 'medium', 'low']),
recommendation: z.string().max(600),
draft: z.string().max(2000).nullable(),
+ code: z.string().max(4000).nullable(),
}),
),
});
+const rewriteSchema = z.object({
+ recommendations: z.array(
+ z.object({
+ ref: z.string(),
+ recommendation: z.string().max(600),
+ draft: z.string().max(2000).nullable(),
+ }),
+ ),
+});
+
+const FACTS_RULE = `Facts: use only facts that appear in the PAGE TEXT or the BRAND DATA. Never invent customers, testimonials, case studies, statistics, percentages, prices, dates, awards or quotes. When a fact is needed but unknown, write a placeholder in square brackets instead: [customer name], [real metric], [price], [date], [source URL].`;
+
+const LENGTH_RULE = `Length: "recommendation" is one imperative sentence of at most ${MAX_COPY_CHARS} characters, specific to this page. Every sentence in "draft" is at most ${MAX_COPY_CHARS} characters.`;
+
const SYSTEM_PROMPT = `You are an AEO/GEO content strategist. For each failing signal you are given, write ONE concrete recommendation tailored specifically to THIS page — never generic boilerplate, never restate the rule.
+${FACTS_RULE}
+
+${LENGTH_RULE}
+
When the fix is content the user can paste, put the ready-to-use text in "draft":
-- meta-description → a 130–155 char description
+- meta-description → a 120–150 character description
- h1-quality → a single improved H1
- bluf-answer / direct-answer → an opening paragraph that leads with the answer
-- faq-schema → 3–5 Q&A pairs AND a valid FAQPage JSON-LD block
+- faq-schema → 3–5 Q&A pairs in "draft" AND a valid FAQPage JSON-LD block in "code"
- definitions → the key terms defined inline
- outbound-authority-links / citation-density → specific authoritative sources to cite
- readability → a simplified rewrite of one representative paragraph (shorter sentences, plainer words)
- length → which specific sections to expand or trim (draft can be null)
+Put markup (JSON-LD, HTML) only in "code", never in "draft". Code has no length limit but uses the same placeholders for unknown values, e.g. "price": "[price]".
+
When suggesting sources to cite (outbound-authority-links, citation-density, statistic-density), prefer the most recent, currently-authoritative references and do not present older material as if it were current. Never invent URLs or fabricate statistics/dates — only suggest sources you are confident exist.
-Keep "recommendation" to 1–3 sentences. Set "draft" to null when the fix isn't a paste-able snippet. Prioritize by impact. Only return items you can make genuinely specific and useful.`;
+Set "draft" and "code" to null when they don't apply. Prioritize by impact. Only return items you can make genuinely specific and useful.`;
+
+const REWRITE_PROMPT = `You shorten AEO/GEO recommendations that broke the length rule. Keep each item's meaning, its [placeholders] and its ref, add no new facts, and return every item you are given.
+
+${LENGTH_RULE}`;
+
+/** The page's title, meta tags and JSON-LD: facts the body text leaves out. */
+function pageExtras(ctx) {
+ const $ = ctx.$;
+ if (!$) return [];
+ return [
+ $('title').first().text(),
+ $('meta[name="description"]').attr('content') ?? '',
+ $('meta[property="og:title"]').attr('content') ?? '',
+ $('meta[property="og:description"]').attr('content') ?? '',
+ $('script[type="application/ld+json"]')
+ .map((_, el) => $(el).text())
+ .get()
+ .join(' '),
+ ];
+}
+
+/**
+ * The brand data a recommendation may quote, when `url` is on one of the
+ * brand's domains. Null for any other page, so an audit of a competitor's
+ * page never borrows this brand's facts.
+ */
+export function brandFactsFor(url, brandRow, domainRows) {
+ const domains = (domainRows ?? []).map((d) => d.domain).filter(Boolean);
+ if (!onBrandDomain(url, domains)) return null;
+ return { name: brandRow?.name ?? null, description: brandRow?.description ?? null, domains };
+}
+
+function brandBlock(brand) {
+ if (!brand) return '';
+ const lines = [
+ brand.name && `- Name: ${brand.name}`,
+ brand.description && `- Description: ${brand.description}`,
+ brand.domains?.length && `- Domains: ${brand.domains.join(', ')}`,
+ ].filter(Boolean);
+ if (lines.length === 0) return '';
+ return `\nBRAND DATA (the brand that owns this page; facts you may reuse):\n${lines.join('\n')}\n`;
+}
+
+/**
+ * One rewrite of the items over the length limit, each sent with a `ref`.
+ * Returns the rewritten items by ref; an empty map when the call fails.
+ */
+async function rewriteTooLong(model, items) {
+ try {
+ const { object } = await withRetry(
+ () =>
+ generateObject({
+ model,
+ schema: rewriteSchema,
+ system: REWRITE_PROMPT,
+ prompt: `Rewrite these so they follow the length rule:\n${JSON.stringify(
+ items.map(({ ref, item }) => ({
+ ref,
+ recommendation: item.recommendation,
+ draft: item.draft,
+ })),
+ null,
+ 2,
+ )}`,
+ }),
+ { label: 'recommendations-rewrite' },
+ );
+ return new Map((object.recommendations || []).map((r) => [r.ref, r]));
+ } catch (err) {
+ logger.warn({ err }, '[audit] recommendation rewrite failed; cutting instead');
+ return new Map();
+ }
+}
/**
* @param {import('./context.js').AuditContext} ctx
- * @param {{ results: Array<{key:string,status:string,evidence:object}>, queries?: string[] }} opts
- * @returns {Promise<Array<{ signalKey: string, label: string, category: string|null, priority: string, recommendation: string, draft: string|null }>>}
+ * @param {{ results: Array<{key:string,status:string,evidence:object}>, brand?: { name?: string|null, description?: string|null, domains?: string[] } | null, auditId?: string }} opts
+ * `brand` only when the page is on one of the brand's domains.
+ * @returns {Promise<Array<{ signalKey: string, label: string, category: string|null, priority: string, recommendation: string, draft: string|null, code: string|null }>>}
*/
-export async function generateRecommendations(ctx, { results } = {}) {
+export async function generateRecommendations(ctx, { results, brand = null, auditId } = {}) {
const failing = (results || []).filter(
(r) => RECOMMENDABLE_SIGNALS.has(r.key) && (r.status === 'fail' || r.status === 'warn'),
);
@@ -114,10 +222,11 @@ export async function generateRecommendations(ctx, { results } = {}) {
});
try {
+ const model = resolveModel(modelString);
const { object } = await withRetry(
() =>
generateObject({
- model: resolveModel(modelString),
+ model,
schema: recommendationsSchema,
system: SYSTEM_PROMPT,
prompt: `Today's date is ${today}.
@@ -125,7 +234,7 @@ export async function generateRecommendations(ctx, { results } = {}) {
PAGE URL: ${ctx.url}
Improve THIS page for its own topic/intent (infer it from the content below). Never introduce subject matter the page isn't already about.
-
+${brandBlock(brand)}
FAILING SIGNALS TO FIX:
${issues}
@@ -139,16 +248,73 @@ Return prioritized, page-specific recommendations.`,
{ label: 'recommendations' },
);
- return (object.recommendations || [])
+ // Today's date was given to the model, so a freshness date isn't invented.
+ const month = new Date(ctx.now ?? Date.now()).toLocaleDateString('en-US', {
+ year: 'numeric',
+ month: 'long',
+ });
+ const known = buildKnownFacts({
+ pageText: ctx.text,
+ extras: [...pageExtras(ctx), today, month],
+ brand,
+ });
+ let facts = 0;
+ const guard = (r) => {
+ const out = guardFacts(r, known);
+ facts += out.hits;
+ return out.rec;
+ };
+
+ let items = (object.recommendations || [])
.filter((r) => RECOMMENDABLE_SIGNALS.has(r.signalKey))
- .map((r) => ({
- signalKey: r.signalKey,
- label: signalsByKey[r.signalKey]?.label ?? r.signalKey,
- category: signalsByKey[r.signalKey]?.category ?? null,
- priority: r.priority,
- recommendation: r.recommendation,
- draft: r.draft || null,
- }));
+ .map((r) => guard({ ...r, draft: r.draft || null, code: r.code || null }));
+
+ // Items are matched back by position: one signal can have several.
+ const tooLong = items
+ .map((item, i) => ({ ref: String(i), item }))
+ .filter(({ item }) => needsShortening(item));
+ let rewritten = 0;
+ if (tooLong.length > 0) {
+ const rewrites = await rewriteTooLong(model, tooLong);
+ items = items.map((r, i) => {
+ const next = rewrites.get(String(i));
+ if (!next) return r;
+ rewritten += 1;
+ // Only the parts over the limit are replaced; a part that was fine,
+ // or that the rewrite left empty, stays as it was.
+ const long = tooLongParts(r);
+ return guard({
+ ...r,
+ recommendation:
+ long.recommendation && next.recommendation ? next.recommendation : r.recommendation,
+ draft: long.draft && next.draft ? next.draft : r.draft,
+ });
+ });
+ }
+
+ let cuts = 0;
+ items = items.map((r) => {
+ const out = cutToLength(r);
+ cuts += out.cuts;
+ return out.rec;
+ });
+
+ if (facts + rewritten + cuts > 0) {
+ logger.info(
+ { auditId, url: ctx.url, facts, tooLong: tooLong.length, rewritten, cuts },
+ '[audit] recommendation guard changed the model output',
+ );
+ }
+
+ return items.map((r) => ({
+ signalKey: r.signalKey,
+ label: signalsByKey[r.signalKey]?.label ?? r.signalKey,
+ category: signalsByKey[r.signalKey]?.category ?? null,
+ priority: r.priority,
+ recommendation: r.recommendation,
+ draft: r.draft || null,
+ code: r.code || null,
+ }));
} catch (err) {
logger.error({ err, model: modelString }, '[audit] recommendations failed');
return [];
diff --git a/server/src/lib/audit/recommendations.test.js b/server/src/lib/audit/recommendations.test.js
new file mode 100644
index 000000000..d184c0ec4
--- /dev/null
+++ b/server/src/lib/audit/recommendations.test.js
@@ -0,0 +1,277 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as cheerio from 'cheerio';
+
+const generateObject = vi.fn();
+vi.mock('ai', () => ({ generateObject: (...args) => generateObject(...args) }));
+vi.mock('../ai-provider.js', () => ({ resolveModel: () => ({}) }));
+vi.mock('../retry.js', () => ({ withRetry: (fn) => fn() }));
+const logger = vi.hoisted(() => ({ error: vi.fn(), info: vi.fn(), warn: vi.fn() }));
+vi.mock('../logger.js', () => ({ logger, default: logger }));
+
+const { brandFactsFor, generateRecommendations } = await import('./recommendations.js');
+const { MAX_COPY_CHARS, sentencesOf } = await import('./recommendation-guard.js');
+
+// The pricing page from the spec's bug report, cut down.
+const html = `<html><head><title>Ansvisor pricing</title>
+<meta name="description" content="Plans from $49 a month.">
+<script type="application/ld+json">{"@type":"Offer","price":"249"}</script></head>
+<body><h1>Pricing</h1><p>Starter $49 per month: 100 site audits. Growth: 500 site audits.</p></body></html>`;
+
+const ctx = {
+ url: 'https://ansvisor.com/pricing',
+ $: cheerio.load(html),
+ text: 'Pricing Starter $49 per month: 100 site audits. Growth: 500 site audits.',
+ now: Date.UTC(2026, 9, 17),
+};
+
+const results = [
+ { key: 'case-study-evidence', status: 'fail', evidence: { reason: 'No customer results' } },
+ { key: 'faq-schema', status: 'warn', evidence: {} },
+ { key: 'h1-quality', status: 'fail', evidence: {} },
+ { key: 'https', status: 'fail', evidence: {} },
+];
+
+const brand = {
+ name: 'Ansvisor',
+ description: 'AI visibility platform',
+ domains: ['ansvisor.com'],
+};
+
+const tooLong = `${'Show how each plan fits a team size, '.repeat(4)}and what it includes.`;
+
+function modelReturns(...answers) {
+ for (const recommendations of answers) {
+ if (recommendations instanceof Error) generateObject.mockRejectedValueOnce(recommendations);
+ else generateObject.mockResolvedValueOnce({ object: { recommendations } });
+ }
+}
+
+const firstAnswer = [
+ {
+ signalKey: 'case-study-evidence',
+ priority: 'medium',
+ recommendation: 'Add one real customer result next to the plans.',
+ draft: "Join brands like TechFlow, which saw a 34% increase in 'Recommended' citations.",
+ code: null,
+ },
+ {
+ signalKey: 'faq-schema',
+ priority: 'high',
+ recommendation: tooLong,
+ draft: 'How much is Starter? Starter costs $49 a month.',
+ code: '{"@type": "FAQPage", "mainEntity": [], "dateModified": "2024-03-01"}',
+ },
+ {
+ signalKey: 'h1-quality',
+ priority: 'high',
+ recommendation: 'Use a descriptive H1 that says what the plans cover.',
+ draft: 'Ansvisor pricing: AI visibility plans for every team size',
+ code: null,
+ },
+ // Not a recommendable signal: dropped.
+ { signalKey: 'https', priority: 'low', recommendation: 'Enable HTTPS.', draft: null, code: null },
+];
+
+beforeEach(() => {
+ generateObject.mockReset();
+ vi.clearAllMocks();
+});
+
+describe('generateRecommendations', () => {
+ it('replaces invented facts, rewrites the long item once and keeps the rest', async () => {
+ modelReturns(firstAnswer, [
+ {
+ ref: '1',
+ recommendation: 'Add an FAQ on plan prices with FAQPage markup.',
+ draft: 'How much is Starter? Starter costs $49 a month.',
+ },
+ ]);
+
+ const recs = await generateRecommendations(ctx, { results, brand, auditId: 'a1' });
+
+ expect(recs.map((r) => r.signalKey)).toEqual([
+ 'case-study-evidence',
+ 'faq-schema',
+ 'h1-quality',
+ ]);
+ expect(recs[0]).toMatchObject({
+ label: expect.any(String),
+ category: 'eeat',
+ draft:
+ "Join brands like [customer name], which saw a [real metric] increase in 'Recommended' citations.",
+ code: null,
+ });
+ expect(recs[1]).toMatchObject({
+ recommendation: 'Add an FAQ on plan prices with FAQPage markup.',
+ draft: 'How much is Starter? Starter costs $49 a month.',
+ // Code keeps its markup; only the invented date goes.
+ code: '{"@type": "FAQPage", "mainEntity": [], "dateModified": "[date]"}',
+ });
+ expect(recs[2].draft).toBe('Ansvisor pricing: AI visibility plans for every team size');
+
+ // The rewrite got only the long item, without its code.
+ expect(generateObject).toHaveBeenCalledTimes(2);
+ const rewritePrompt = generateObject.mock.calls[1][0].prompt;
+ expect(rewritePrompt).toContain('"ref": "1"');
+ expect(rewritePrompt).toContain('Show how each plan fits a team size');
+ expect(rewritePrompt).not.toContain('Add one real customer result');
+ expect(rewritePrompt).not.toContain('FAQPage", "mainEntity');
+
+ expect(logger.info).toHaveBeenCalledWith(
+ expect.objectContaining({ auditId: 'a1', facts: 3, tooLong: 1, rewritten: 1, cuts: 0 }),
+ expect.any(String),
+ );
+ });
+
+ it('gives the model the rules, the brand data and the page', async () => {
+ modelReturns([]);
+ await generateRecommendations(ctx, { results, brand });
+
+ const { system, prompt } = generateObject.mock.calls[0][0];
+ expect(system).toContain('Never invent customers');
+ expect(system).toContain(`at most ${MAX_COPY_CHARS} characters`);
+ expect(system).toContain('[customer name], [real metric], [price], [date], [source URL]');
+ expect(prompt).toContain('BRAND DATA');
+ expect(prompt).toContain('- Name: Ansvisor');
+ expect(prompt).toContain('- Description: AI visibility platform');
+ expect(prompt).toContain('- Domains: ansvisor.com');
+ });
+
+ it('sends no brand data for another site, and the brand name there is unknown', async () => {
+ modelReturns([
+ {
+ signalKey: 'case-study-evidence',
+ priority: 'medium',
+ recommendation: 'Add one real customer result next to the plans.',
+ draft: 'Teams at Ansvisor cut audit time.',
+ code: null,
+ },
+ ]);
+ const other = {
+ ...ctx,
+ url: 'https://competitor.com/pricing',
+ $: cheerio.load('<html><head><title>Competitor pricing</title></head><body></body></html>'),
+ text: 'Competitor pricing: plans for teams.',
+ };
+ const recs = await generateRecommendations(other, { results, brand: null });
+
+ expect(generateObject.mock.calls[0][0].prompt).not.toContain('BRAND DATA');
+ expect(recs[0].draft).toBe('Teams at [customer name] cut audit time.');
+ });
+
+ it("keeps the page's prices from its meta tags and JSON-LD, and today's month", async () => {
+ modelReturns([
+ {
+ signalKey: 'h1-quality',
+ priority: 'high',
+ recommendation: 'Name both plans and their prices in the H1.',
+ draft: 'Plans from $49 to $249 a month, updated October 2026',
+ code: null,
+ },
+ ]);
+ const recs = await generateRecommendations(ctx, { results, brand });
+ expect(recs[0].draft).toBe('Plans from $49 to $249 a month, updated October 2026');
+ expect(logger.info).not.toHaveBeenCalled();
+ });
+
+ it('cuts at a word boundary when the rewrite fails', async () => {
+ modelReturns(
+ [
+ {
+ signalKey: 'h1-quality',
+ priority: 'high',
+ recommendation: 'Use a descriptive H1.',
+ draft: tooLong,
+ code: null,
+ },
+ ],
+ new Error('model down'),
+ );
+ const recs = await generateRecommendations(ctx, { results, brand });
+
+ expect(sentencesOf(recs[0].draft).every((s) => s.length <= MAX_COPY_CHARS)).toBe(true);
+ expect(recs[0].draft.endsWith('…')).toBe(true);
+ expect(logger.warn).toHaveBeenCalled();
+ expect(logger.info).toHaveBeenCalledWith(
+ expect.objectContaining({ tooLong: 1, rewritten: 0, cuts: 1 }),
+ expect.any(String),
+ );
+ });
+
+ it('cuts a rewrite that is still too long', async () => {
+ modelReturns(
+ [
+ {
+ signalKey: 'h1-quality',
+ priority: 'high',
+ recommendation: tooLong,
+ draft: null,
+ code: null,
+ },
+ ],
+ [{ ref: '0', recommendation: `${tooLong} Still long.`, draft: null }],
+ );
+ const recs = await generateRecommendations(ctx, { results, brand });
+ expect(recs[0].recommendation.length).toBeLessThanOrEqual(MAX_COPY_CHARS);
+ });
+
+ it('matches rewrites by position and keeps the parts that were within the limit', async () => {
+ const draft = 'Acme pricing: plans for every team size';
+ modelReturns(
+ [
+ { signalKey: 'h1-quality', priority: 'high', recommendation: tooLong, draft, code: null },
+ {
+ signalKey: 'h1-quality',
+ priority: 'medium',
+ recommendation: 'Name the plans in the H1.',
+ draft: 'Starter and Growth plans',
+ code: null,
+ },
+ ],
+ // The rewrite leaves the draft out; the short second item isn't sent.
+ [{ ref: '0', recommendation: 'Say what the plans cover in the H1.', draft: null }],
+ );
+ const recs = await generateRecommendations(ctx, { results, brand });
+
+ expect(recs).toMatchObject([
+ { recommendation: 'Say what the plans cover in the H1.', draft },
+ { recommendation: 'Name the plans in the H1.', draft: 'Starter and Growth plans' },
+ ]);
+ const sent = generateObject.mock.calls[1][0].prompt;
+ expect(sent).toContain('"ref": "0"');
+ expect(sent).not.toContain('"ref": "1"');
+ });
+
+ it('calls no model when nothing it can help with failed', async () => {
+ const recs = await generateRecommendations(ctx, {
+ results: [{ key: 'https', status: 'fail', evidence: {} }],
+ });
+ expect(recs).toEqual([]);
+ expect(generateObject).not.toHaveBeenCalled();
+ });
+
+ it('returns nothing when the model fails', async () => {
+ modelReturns(new Error('model down'));
+ expect(await generateRecommendations(ctx, { results, brand })).toEqual([]);
+ expect(logger.error).toHaveBeenCalled();
+ });
+});
+
+describe('brandFactsFor', () => {
+ const row = { name: 'Ansvisor', description: 'AI visibility platform' };
+ const domains = [{ domain: 'ansvisor.com' }, { domain: null }];
+
+ it("gives the brand's facts for a page on its domains", () => {
+ expect(brandFactsFor('https://www.ansvisor.com/pricing', row, domains)).toEqual({
+ name: 'Ansvisor',
+ description: 'AI visibility platform',
+ domains: ['ansvisor.com'],
+ });
+ });
+
+ it("gives none for another site's page, or a brand without domains", () => {
+ expect(brandFactsFor('https://competitor.com/pricing', row, domains)).toBeNull();
+ expect(brandFactsFor('https://ansvisor.com/pricing', row, [])).toBeNull();
+ expect(brandFactsFor('https://ansvisor.com/pricing', row, null)).toBeNull();
+ });
+});
diff --git a/server/src/routes/audits.js b/server/src/routes/audits.js
index 04d17707b..bf649e7ec 100644
--- a/server/src/routes/audits.js
+++ b/server/src/routes/audits.js
@@ -28,7 +28,7 @@ import { buildTrendPoints, parseListPage, TREND_LIMIT } from '../lib/audit/histo
import { runSignals } from '../lib/audit/engine.js';
import { evaluateLlmSignals } from '../lib/audit/llm-signals.js';
import { evaluateBrandEntity } from '../lib/audit/external-signals.js';
-import { generateRecommendations } from '../lib/audit/recommendations.js';
+import { brandFactsFor, generateRecommendations } from '../lib/audit/recommendations.js';
import { scoreAudit } from '../lib/audit/scorer.js';
import { signalsByKey, TOTAL_SIGNALS, RUBRIC_VERSION } from '../lib/audit/rubric.js';
@@ -82,15 +82,14 @@ function assembleAudit(audit, signalRows) {
*/
async function runAuditJob(auditId, brandId, url, orgId) {
try {
- // The brand name is only needed for the Wikidata brand-entity lookup. The
- // page is otherwise evaluated entirely on its own terms — the LLM infers
- // the page's own target topic from its content, so an arbitrary URL (a
+ // The brand name is needed for the Wikidata brand-entity lookup. The page
+ // is otherwise evaluated entirely on its own terms — the LLM infers the
+ // page's own target topic from its content, so an arbitrary URL (a
// competitor blog, any page) is never judged against this brand's topics.
- const { data: brandRow } = await supabaseAdmin
- .from('brands')
- .select('name')
- .eq('id', brandId)
- .single();
+ const [{ data: brandRow }, { data: domainRows }] = await Promise.all([
+ supabaseAdmin.from('brands').select('name, description').eq('id', brandId).single(),
+ supabaseAdmin.from('brand_domains').select('domain').eq('brand_id', brandId),
+ ]);
const ctx = await buildAuditContext(url);
@@ -118,8 +117,13 @@ async function runAuditJob(auditId, brandId, url, orgId) {
if (sigErr) throw sigErr;
// AI fix recommendations for the fixable failing signals (own LLM call;
- // degrades to [] on failure so it never blocks completion).
- const recommendations = await generateRecommendations(ctx, { results });
+ // degrades to [] on failure so it never blocks completion). Brand facts
+ // (name, description, domains) may be reused only on the brand's own pages.
+ const recommendations = await generateRecommendations(ctx, {
+ results,
+ brand: brandFactsFor(ctx.url, brandRow, domainRows),
+ auditId,
+ });
const { error: completeErr } = await supabaseAdmin
.from('site_audits')
diff --git a/web/messages/en.json b/web/messages/en.json
index 54aa8d6ec..9868f7226 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -2114,6 +2114,8 @@
"copied": "Copied",
"copyFailed": "Copy failed",
"copyDraft": "Copy draft",
+ "copyCode": "Copy code",
+ "placeholderNote": "Replace placeholders in [brackets] with your real data before publishing.",
"finding": "Finding",
"why": "Why",
"recommendedFix": "Recommended fix",
diff --git a/web/src/components/audit/audit-report.test.tsx b/web/src/components/audit/audit-report.test.tsx
new file mode 100644
index 000000000..e24a9da95
--- /dev/null
+++ b/web/src/components/audit/audit-report.test.tsx
@@ -0,0 +1,110 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { NextIntlClientProvider } from 'next-intl';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import messages from '../../../messages/en.json';
+import type { AuditRecommendation, AuditResult } from '@/lib/actions/audits';
+import { AuditReport } from './audit-report';
+
+(
+ globalThis as typeof globalThis & {
+ IS_REACT_ACT_ENVIRONMENT: boolean;
+ }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const NOTE = 'Replace placeholders in [brackets] with your real data before publishing.';
+
+const rec = (over: Partial<AuditRecommendation> = {}): AuditRecommendation => ({
+ signalKey: 'case-study-evidence',
+ label: 'Case study evidence',
+ category: 'eeat',
+ priority: 'medium',
+ recommendation: 'Add one real customer result next to the plans.',
+ draft: null,
+ ...over,
+});
+
+const audit = (recommendations: AuditRecommendation[]): AuditResult => ({
+ id: 'a1',
+ brandId: 'b1',
+ url: 'https://ansvisor.com/pricing',
+ finalUrl: 'https://ansvisor.com/pricing',
+ status: 'completed',
+ totalScore: 0.63,
+ categoryScores: {},
+ signalsEvaluated: 45,
+ signalsTotal: 47,
+ rubricVersion: '1',
+ error: null,
+ createdAt: '2026-10-17T09:00:00.000Z',
+ completedAt: '2026-10-17T09:01:00.000Z',
+ signals: [],
+ recommendations,
+});
+
+let container: HTMLDivElement;
+let root: Root;
+
+function render(recommendations: AuditRecommendation[]) {
+ act(() => {
+ root.render(
+ <NextIntlClientProvider locale="en" messages={messages} timeZone="UTC">
+ <AuditReport audit={audit(recommendations)} />
+ </NextIntlClientProvider>,
+ );
+ });
+}
+
+const marks = () => [...container.querySelectorAll('pre mark')].map((m) => m.textContent);
+
+beforeEach(() => {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+});
+
+describe('AuditReport recommendations', () => {
+ it('highlights the placeholders in a draft and says to replace them', () => {
+ render([rec({ draft: '[customer name] grew AI citations by [real metric] with Growth.' })]);
+
+ expect(container.querySelector('pre')?.textContent).toBe(
+ '[customer name] grew AI citations by [real metric] with Growth.',
+ );
+ expect(marks()).toEqual(['[customer name]', '[real metric]']);
+ expect(container.textContent).toContain(NOTE);
+ });
+
+ it('shows the code in its own block with its own copy button', () => {
+ render([
+ rec({
+ signalKey: 'faq-schema',
+ draft: 'How much is Starter? Starter costs $49 a month.',
+ code: '{"@type": "FAQPage", "dateModified": "[date]", "mainEntity": ["a", "b"]}',
+ }),
+ ]);
+
+ const blocks = [...container.querySelectorAll('pre')].map((p) => p.textContent);
+ expect(blocks).toEqual([
+ 'How much is Starter? Starter costs $49 a month.',
+ '{"@type": "FAQPage", "dateModified": "[date]", "mainEntity": ["a", "b"]}',
+ ]);
+ expect(container.querySelector('[aria-label="Copy draft"]')).not.toBeNull();
+ expect(container.querySelector('[aria-label="Copy code"]')).not.toBeNull();
+ // A JSON array is not a placeholder.
+ expect(marks()).toEqual(['[date]']);
+ expect(container.textContent).toContain(NOTE);
+ });
+
+ it('adds no note to copy without placeholders, or to an older audit without code', () => {
+ render([rec({ draft: 'Ansvisor pricing: AI visibility plans for every team size' })]);
+
+ expect(container.querySelectorAll('pre')).toHaveLength(1);
+ expect(marks()).toEqual([]);
+ expect(container.textContent).not.toContain(NOTE);
+ });
+});
diff --git a/web/src/components/audit/audit-report.tsx b/web/src/components/audit/audit-report.tsx
index aeb6780ac..8fcee28d3 100644
--- a/web/src/components/audit/audit-report.tsx
+++ b/web/src/components/audit/audit-report.tsx
@@ -105,10 +105,17 @@ export function ScoreGauge({ score }: { score: number | null }) {
);
}
-function DraftBlock({ draft }: { draft: string }) {
+// A value the user fills in, e.g. "[customer name]" or "[price]".
+const PLACEHOLDER = /(\[[A-Za-z][A-Za-z ]{1,38}\])/;
+
+function hasPlaceholder(text: string | null | undefined): boolean {
+ return !!text && PLACEHOLDER.test(text);
+}
+
+function DraftBlock({ text, copyLabel }: { text: string; copyLabel: string }) {
const t = useTranslations('audit');
const copy = () => {
- navigator.clipboard.writeText(draft).then(
+ navigator.clipboard.writeText(text).then(
() => toast.success(t('copied')),
() => toast.error(t('copyFailed')),
);
@@ -120,17 +127,43 @@ function DraftBlock({ draft }: { draft: string }) {
size="icon"
className="absolute right-1 top-1 h-7 w-7"
onClick={copy}
- aria-label={t('copyDraft')}
+ aria-label={copyLabel}
>
<Copy className="h-3.5 w-3.5" />
</Button>
<pre className="whitespace-pre-wrap pr-8 text-xs leading-relaxed text-foreground">
- {draft}
+ {text.split(PLACEHOLDER).map((part, i) =>
+ i % 2 === 1 ? (
+ <mark
+ key={i}
+ className="rounded bg-amber-100 px-0.5 font-medium text-amber-900 dark:bg-amber-500/20 dark:text-amber-200"
+ >
+ {part}
+ </mark>
+ ) : (
+ part
+ ),
+ )}
</pre>
</div>
);
}
+/** The draft and code to paste, with a reminder when they hold placeholders. */
+function PasteBlocks({ rec }: { rec: AuditRecommendation }) {
+ const t = useTranslations('audit');
+ if (!rec.draft && !rec.code) return null;
+ return (
+ <>
+ {rec.draft && <DraftBlock text={rec.draft} copyLabel={t('copyDraft')} />}
+ {rec.code && <DraftBlock text={rec.code} copyLabel={t('copyCode')} />}
+ {(hasPlaceholder(rec.draft) || hasPlaceholder(rec.code)) && (
+ <p className="text-xs text-muted-foreground">{t('placeholderNote')}</p>
+ )}
+ </>
+ );
+}
+
function SignalRow({
signal,
recommendation,
@@ -193,7 +226,7 @@ function SignalRow({
</span>{' '}
{recommendation.recommendation}
</p>
- {recommendation.draft && <DraftBlock draft={recommendation.draft} />}
+ <PasteBlocks rec={recommendation} />
</div>
) : (
signal.status !== 'pass' &&
@@ -222,7 +255,7 @@ function RecommendationItem({ rec }: { rec: AuditRecommendation }) {
<span className="text-sm font-medium">{rec.label}</span>
</div>
<p className="text-sm text-muted-foreground">{rec.recommendation}</p>
- {rec.draft && <DraftBlock draft={rec.draft} />}
+ <PasteBlocks rec={rec} />
</div>
);
}
diff --git a/web/src/lib/actions/audits.ts b/web/src/lib/actions/audits.ts
index a80a1fb21..864e56a2c 100644
--- a/web/src/lib/actions/audits.ts
+++ b/web/src/lib/actions/audits.ts
@@ -33,6 +33,8 @@ export interface AuditRecommendation {
priority: 'high' | 'medium' | 'low';
recommendation: string;
draft: string | null;
+ /** JSON-LD or HTML to paste. Older audits keep markup in `draft` and lack this. */
+ code?: string | null;
}
export interface AuditResult {