@olives/devos 2.1.0

package/.agents/skills/vercel-optimize/scripts/build-docs.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Regenerates references/{scanner-patterns,candidates}.md from lib/{scanners,gates}/*
+// metadata. The .mjs files are the source of truth; check-docs-fresh.mjs blocks
+// PRs where the regenerated output diverges from what's checked in.
+
+import { writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { scanners } from '../lib/scanners/index.mjs';
+import { gates, MAX_CODE_CANDIDATES, GATE_VERSION } from '../lib/gates/index.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REFS = join(HERE, '..', 'references');
+
+const GENERATED_BANNER =
+  '<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->\n' +
+  '<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->\n' +
+  '<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->\n\n';
+
+async function main() {
+  await writeFile(join(REFS, 'scanner-patterns.md'), renderScanners());
+  await writeFile(join(REFS, 'candidates.md'), renderCandidates());
+  console.error('[build-docs] wrote scanner-patterns.md + candidates.md');
+}
+
+function renderScanners() {
+  const sorted = scanners.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Scanner patterns\n\n';
+  out += 'AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.\n\n';
+  out += `Total scanners: ${sorted.length}.\n\n`;
+  out += '## Patterns\n\n';
+  for (const s of sorted) {
+    const m = s.metadata;
+    out += `### \`${m.id}\` — ${m.title}\n\n`;
+    out += `- **Severity**: ${m.severity}\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Traffic-independent**: ${m.trafficIndependent ? 'yes (cold-path findings survive the doctrine drop)' : 'no (cold-path findings get dropped)'}\n\n`;
+    out += `**Description.** ${m.description}\n\n`;
+    out += `**Fix.** ${m.fix}\n\n`;
+    if (m.citations?.length) {
+      out += `**Citations:**\n${m.citations.map((c) => `- \`${c}\``).join('\n')}\n\n`;
+    }
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function renderCandidates() {
+  const sorted = gates.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Candidate gates\n\n';
+  out += 'The deterministic threshold expressions that turn observability signals into investigation candidates. Pure JS, no LLM. Thresholds live in `lib/gates/*.mjs`.\n\n';
+  out += `Total gates: ${sorted.length}. Budget cap: \`MAX_CODE_CANDIDATES = ${MAX_CODE_CANDIDATES}\`. Gate version: \`${GATE_VERSION}\`.\n\n`;
+  out += '## Gates\n\n';
+  for (const g of sorted) {
+    const m = g.metadata;
+    out += `### \`${m.id}\`\n\n`;
+    out += `- **Threshold**: \`${m.threshold}\`\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Scope**: ${m.scope}\n`;
+    out += `- **Source citation**: \`${m.sourceCitation}\`\n\n`;
+    out += `${m.description}\n\n`;
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function trimTrailingBlankLine(value) {
+  return value.replace(/\n{2,}$/, '\n');
+}
+
+main().catch((err) => {
+  console.error('[build-docs] FAILED:', err.message);
+  process.exit(1);
+});

package/.agents/skills/vercel-optimize/scripts/check-citations.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Offline citation-library consistency checks. This intentionally does not
+// fetch URLs; it validates the local allow-list contract used by sanitizers.
+
+import { loadLibrary, matchesFrameworkVersion } from '../lib/citations.mjs';
+
+const URL_RE = /^https:\/\/[A-Za-z0-9.-]+\/\S*$/;
+const SKILL_REF_RE = /^[\w-]+:[\w-]+$/;
+const BANNED_STALE_URLS = new Set([
+  'https://nextjs.org/docs/app/api-reference/functions/cache-life',
+  'https://nextjs.org/docs/app/api-reference/functions/cache-tag',
+  'https://nextjs.org/docs/app/api-reference/functions/revalidate-tag',
+  'https://nextjs.org/docs/app/api-reference/functions/revalidate-path',
+  'https://nextjs.org/docs/app/api-reference/functions/cache',
+]);
+
+async function main() {
+  const lib = await loadLibrary();
+  const errors = [];
+
+  if (!Array.isArray(lib.urls)) errors.push('docs-library.urls must be an array');
+  if (!Array.isArray(lib.ruleSkillRefs)) errors.push('docs-library.ruleSkillRefs must be an array');
+
+  for (const [i, entry] of (lib.urls ?? []).entries()) {
+    const label = `urls[${i}]`;
+    if (!URL_RE.test(entry?.url ?? '')) errors.push(`${label}.url must be an https URL`);
+    if (BANNED_STALE_URLS.has(entry?.url)) {
+      errors.push(`${label}.url uses a stale Next.js docs path: ${entry.url}`);
+    }
+    if (typeof entry.topic !== 'string' || entry.topic.trim() === '') errors.push(`${label}.topic is required`);
+    if (!Array.isArray(entry.appliesTo)) errors.push(`${label}.appliesTo must be an array`);
+    validateFrameworks(entry.applicableFrameworks, `${label}.applicableFrameworks`, errors);
+  }
+
+  const seenRules = new Set();
+  for (const [i, entry] of (lib.ruleSkillRefs ?? []).entries()) {
+    const label = `ruleSkillRefs[${i}]`;
+    const ref = `${entry?.skill ?? ''}:${entry?.rule ?? ''}`;
+    if (!SKILL_REF_RE.test(ref)) errors.push(`${label} must contain skill + rule identifiers`);
+    if (seenRules.has(ref)) errors.push(`${label} duplicate: ${ref}`);
+    seenRules.add(ref);
+    if (typeof (entry.description ?? entry.topic) !== 'string' || (entry.description ?? entry.topic).trim() === '') {
+      errors.push(`${label}.topic or .description is required`);
+    }
+    validateFrameworks(entry.applicableFrameworks, `${label}.applicableFrameworks`, errors);
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`[check-citations] ${error}`);
+    process.exit(1);
+  }
+
+  console.error(`[check-citations] OK — ${lib.urls.length} URLs, ${lib.ruleSkillRefs.length} skill-rule refs`);
+}
+
+function validateFrameworks(patterns, label, errors) {
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    errors.push(`${label} must be a non-empty array`);
+    return;
+  }
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string' || pattern.trim() === '') {
+      errors.push(`${label} contains an empty pattern`);
+      continue;
+    }
+    if (pattern === '*') continue;
+    // Smoke-check parser coverage with a modern Next version. Unknown framework
+    // patterns are still valid as long as the syntax is recognizable.
+    if (!/^[\w-]+@(?:\*|\d+(?:\.\d+){0,2}|[<>]=?\s*\d+(?:\.\d+){0,2})(?:\s*\|\|\s*[\w-]+@(?:\*|\d+(?:\.\d+){0,2}|[<>]=?\s*\d+(?:\.\d+){0,2}))*$/.test(pattern)) {
+      errors.push(`${label} has unsupported pattern: ${pattern}`);
+      continue;
+    }
+    matchesFrameworkVersion(pattern, 'next', '16.0.0');
+  }
+}
+
+main().catch((err) => {
+  console.error('[check-citations] FAILED:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});

package/.agents/skills/vercel-optimize/scripts/check-docs-fresh.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// CI gate: regenerate the reference docs in memory and diff against what's
+// checked in. Non-zero exit forces contributors to run build-docs.mjs.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { scanners } from '../lib/scanners/index.mjs';
+import { gates, MAX_CODE_CANDIDATES, GATE_VERSION } from '../lib/gates/index.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REFS = join(HERE, '..', 'references');
+
+const GENERATED_BANNER =
+  '<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->\n' +
+  '<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->\n' +
+  '<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->\n\n';
+
+async function main() {
+  const expected = {
+    'scanner-patterns.md': renderScanners(),
+    'candidates.md': renderCandidates(),
+  };
+
+  let stale = false;
+  for (const [name, content] of Object.entries(expected)) {
+    let actual;
+    try { actual = await readFile(join(REFS, name), 'utf-8'); }
+    catch {
+      console.error(`[check-docs-fresh] ${name} does not exist. Run \`node scripts/build-docs.mjs\`.`);
+      stale = true;
+      continue;
+    }
+    if (actual !== content) {
+      console.error(`[check-docs-fresh] ${name} is stale. Run \`node scripts/build-docs.mjs\` and commit.`);
+      stale = true;
+    }
+  }
+
+  if (stale) process.exit(1);
+  console.error('[check-docs-fresh] OK — generated docs match source');
+}
+
+// MUST stay byte-identical to build-docs.mjs renderers — duplication is the contract.
+function renderScanners() {
+  const sorted = scanners.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Scanner patterns\n\n';
+  out += 'AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.\n\n';
+  out += `Total scanners: ${sorted.length}.\n\n`;
+  out += '## Patterns\n\n';
+  for (const s of sorted) {
+    const m = s.metadata;
+    out += `### \`${m.id}\` — ${m.title}\n\n`;
+    out += `- **Severity**: ${m.severity}\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Traffic-independent**: ${m.trafficIndependent ? 'yes (cold-path findings survive the doctrine drop)' : 'no (cold-path findings get dropped)'}\n\n`;
+    out += `**Description.** ${m.description}\n\n`;
+    out += `**Fix.** ${m.fix}\n\n`;
+    if (m.citations?.length) {
+      out += `**Citations:**\n${m.citations.map((c) => `- \`${c}\``).join('\n')}\n\n`;
+    }
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function renderCandidates() {
+  const sorted = gates.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + '# Candidate gates\n\n';
+  out += 'The deterministic threshold expressions that turn observability signals into investigation candidates. Pure JS, no LLM. Thresholds live in `lib/gates/*.mjs`.\n\n';
+  out += `Total gates: ${sorted.length}. Budget cap: \`MAX_CODE_CANDIDATES = ${MAX_CODE_CANDIDATES}\`. Gate version: \`${GATE_VERSION}\`.\n\n`;
+  out += '## Gates\n\n';
+  for (const g of sorted) {
+    const m = g.metadata;
+    out += `### \`${m.id}\`\n\n`;
+    out += `- **Threshold**: \`${m.threshold}\`\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Scope**: ${m.scope}\n`;
+    out += `- **Source citation**: \`${m.sourceCitation}\`\n\n`;
+    out += `${m.description}\n\n`;
+    out += '---\n\n';
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function trimTrailingBlankLine(value) {
+  return value.replace(/\n{2,}$/, '\n');
+}
+
+main().catch((err) => {
+  console.error('[check-docs-fresh] FAILED:', err.message);
+  process.exit(1);
+});