weftens 0.0.1 → 0.1.1

package/agent-cores/paid-search/test/parse.test.mjs

@@ -0,0 +1,56 @@
+// Parser tests — run with `node --test`, zero install. Confirms the CSV tokenizer,
+// Google Ads header detection, and currency/percent coercion do real work.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseCsv, parseReport, toNumber, toShare } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const stCsv = readFileSync(join(__dirname, 'fixtures', 'search-terms.csv'), 'utf8');
+const cCsv = readFileSync(join(__dirname, 'fixtures', 'campaigns.csv'), 'utf8');
+
+test('parseCsv handles quoted fields with embedded commas', () => {
+  const rows = parseCsv('a,"b,c",d\n1,2,3\n');
+  assert.deepEqual(rows[0], ['a', 'b,c', 'd']);
+  assert.deepEqual(rows[1], ['1', '2', '3']);
+});
+
+test('toNumber strips currency, commas, and quotes', () => {
+  assert.equal(toNumber('$1,234.50'), 1234.5);
+  assert.equal(toNumber('--'), null);
+  assert.equal(toNumber(''), null);
+  assert.equal(toNumber('42'), 42);
+});
+
+test('toShare normalizes percent, decimal, and Google floor/ceiling forms', () => {
+  assert.equal(toShare('35%'), 0.35);
+  assert.equal(toShare('0.35'), 0.35);
+  assert.equal(toShare('< 10%'), 0.1);
+  assert.equal(toShare('> 90%'), 0.9);
+  assert.equal(toShare('--'), null);
+});
+
+test('parseReport skips title/date/total rows and maps canonical fields', () => {
+  const st = parseReport(stCsv);
+  // 7 data rows, the "Total:" row dropped
+  assert.equal(st.length, 7);
+  const first = st[0];
+  assert.equal(first.searchTerm, 'buy blue widgets');
+  assert.equal(first.campaign, 'Generic');
+  assert.equal(first.clicks, 40);
+  assert.equal(first.cost, 120);
+  assert.equal(first.conversions, 6);
+});
+
+test('parseReport maps share + bidding columns on the campaign report', () => {
+  const c = parseReport(cCsv);
+  assert.equal(c.length, 3);
+  const generic = c.find((x) => x.campaign === 'Generic');
+  assert.equal(generic.searchIS, 0.45);
+  assert.equal(generic.lostISBudget, 0.35);
+  assert.equal(generic.biddingStrategy, 'Maximize conversions');
+  assert.equal(generic.sharedBudget, 'Shared-1');
+});

package/agent-cores/seo-content/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/seo-content",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Content & entity SEO strategy engine. Deterministic: parse a GSC/Semrush/Ahrefs export, compute striking-distance, low-CTR, and cannibalization opportunities with the math shown. No LLM in the core.",
+  "bin": {
+    "seo-content": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "strategy": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/seo-content/src/cli.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Real CLI:
+//   seo-content <export.csv|export.json> [--pretty]
+// Reads a GSC/Semrush/Ahrefs search-performance export, computes the keyword
+// strategy, prints JSON to stdout and a one-line read to stderr.
+
+import { readFileSync } from 'node:fs';
+import { parseRecords } from './parse.mjs';
+import { buildStrategy } from './strategy.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--pretty') args.pretty = true;
+    else if (a === '--target') args.target = Number(argv[++i]);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const file = args._[0];
+  if (!file) {
+    console.error('Usage: seo-content <export.csv|export.json> [--pretty] [--target <position>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const text = readFileSync(file, 'utf8');
+  const records = parseRecords(text);
+  const options = {};
+  if (Number.isFinite(args.target)) options.strikingTarget = args.target;
+  const result = buildStrategy(records, options);
+
+  console.error(`seo-content: ${result.summary}`);
+  console.log(JSON.stringify(result, null, args.pretty ? 2 : 0));
+}
+
+main();

package/agent-cores/seo-content/src/parse.mjs

@@ -0,0 +1,141 @@
+// Dependency-free parsing for search-performance exports.
+// Handles GSC ("Queries" tab), Semrush "Organic Positions", and Ahrefs "Organic
+// keywords" CSVs, plus a JSON array of the same records. The core downstream
+// (strategy.mjs) never sees raw columns — only normalized numeric records.
+
+// --- RFC-4180-ish CSV parser: quoted fields, embedded commas/newlines, "" escapes ---
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  let sawAny = false;
+
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i += 1; }
+        else inQuotes = false;
+      } else {
+        field += c;
+      }
+    } else if (c === '"') {
+      inQuotes = true;
+      sawAny = true;
+    } else if (c === ',') {
+      row.push(field); field = ''; sawAny = true;
+    } else if (c === '\r') {
+      // ignore CR; LF terminates
+    } else if (c === '\n') {
+      row.push(field); rows.push(row); row = []; field = ''; sawAny = false;
+    } else {
+      field += c; sawAny = true;
+    }
+  }
+  if (sawAny || field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  // drop fully-blank lines
+  return rows.filter((r) => !(r.length === 1 && r[0].trim() === ''));
+}
+
+// header aliases -> canonical field. Compared lowercase, punctuation-stripped.
+const HEADER_MAP = [
+  ['query', ['query', 'queries', 'keyword', 'keywords', 'search term', 'searchterm', 'top queries', 'term']],
+  ['url', ['url', 'page', 'landing page', 'address', 'top pages', 'urls', 'current url']],
+  ['clicks', ['clicks', 'url clicks', 'organic clicks']],
+  ['impressions', ['impressions', 'impr', 'impressions.']],
+  ['ctr', ['ctr', 'click through rate', 'clickthrough rate', 'url ctr']],
+  ['position', ['position', 'avg position', 'average position', 'pos', 'current position', 'rank']],
+  ['volume', ['volume', 'search volume', 'vol']],
+];
+
+function normalizeHeader(h) {
+  const key = h.toLowerCase().replace(/[.%]/g, '').replace(/[_-]+/g, ' ').replace(/\s+/g, ' ').trim();
+  for (const [canon, aliases] of HEADER_MAP) {
+    if (aliases.includes(key)) return canon;
+  }
+  return null;
+}
+
+// "1,234" -> 1234 ; "5.2%" -> 5.2 ; "" -> null
+function parseNumber(raw) {
+  if (raw == null) return null;
+  const s = String(raw).replace(/[,%\s$]/g, '').trim();
+  if (s === '') return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+
+// CTR can arrive as "5.20%", "5.2", or "0.052". Return a fraction in [0,1].
+function parseCtr(raw) {
+  if (raw == null) return null;
+  const hadPercent = String(raw).includes('%');
+  const n = parseNumber(raw);
+  if (n == null) return null;
+  if (hadPercent) return n / 100;
+  return n > 1 ? n / 100 : n; // bare "5.2" is 5.2%, "0.052" is already a fraction
+}
+
+function rowsToRecords(rows) {
+  if (rows.length === 0) return [];
+  const header = rows[0].map(normalizeHeader);
+  const records = [];
+  for (let r = 1; r < rows.length; r += 1) {
+    const cells = rows[r];
+    const rec = {};
+    for (let c = 0; c < header.length; c += 1) {
+      if (header[c]) rec[header[c]] = cells[c];
+    }
+    const norm = normalizeRecord(rec);
+    if (norm) records.push(norm);
+  }
+  return records;
+}
+
+function normalizeRecord(rec) {
+  const query = (rec.query ?? '').toString().trim();
+  if (!query) return null;
+  const clicks = parseNumber(rec.clicks);
+  const impressions = parseNumber(rec.impressions);
+  let ctr = parseCtr(rec.ctr);
+  const position = parseNumber(rec.position);
+  const volume = parseNumber(rec.volume);
+  // Derive CTR when both counts are present but CTR is missing.
+  if ((ctr == null || Number.isNaN(ctr)) && clicks != null && impressions != null && impressions > 0) {
+    ctr = clicks / impressions;
+  }
+  return {
+    query,
+    url: (rec.url ?? '').toString().trim() || null,
+    clicks: clicks ?? 0,
+    impressions: impressions ?? 0,
+    ctr: ctr ?? 0,
+    position: position ?? null,
+    volume: volume ?? null,
+  };
+}
+
+// Accepts a raw file body. JSON array/object -> records; otherwise CSV.
+export function parseRecords(text) {
+  const trimmed = text.trimStart();
+  if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+    const data = JSON.parse(text);
+    const arr = Array.isArray(data) ? data : (Array.isArray(data.rows) ? data.rows : [data]);
+    return arr
+      .map((o) => {
+        const rec = {};
+        for (const [k, v] of Object.entries(o)) {
+          const canon = normalizeHeader(k);
+          if (canon) rec[canon] = v;
+        }
+        return normalizeRecord(rec);
+      })
+      .filter(Boolean);
+  }
+  return rowsToRecords(parseCsv(text));
+}
+
+export const _internal = { parseNumber, parseCtr, normalizeHeader };

package/agent-cores/seo-content/src/strategy.mjs

@@ -0,0 +1,266 @@
+// Deterministic content & entity SEO strategy engine. No LLM.
+//
+// Input: normalized search-performance records (query, url, clicks, impressions,
+// ctr, position, volume). Output: a keyword strategy — striking-distance keywords,
+// high-impression/low-CTR opportunities, cannibalization, topic clusters, and a
+// ranked opportunity list with the arithmetic shown on every row.
+//
+// Every projection is a modeled ESTIMATE (labeled). Cannibalization is observed
+// directly in the data (labeled verified-in-data). Nothing here writes prose.
+
+// Organic click-through rate by SERP position. Conservative industry-style curve;
+// used to model the click ceiling a page is leaving on the table. Estimates only.
+const CTR_CURVE = {
+  1: 0.283, 2: 0.157, 3: 0.110, 4: 0.080, 5: 0.061,
+  6: 0.048, 7: 0.040, 8: 0.033, 9: 0.028, 10: 0.025,
+  11: 0.015, 12: 0.013, 13: 0.012, 14: 0.011, 15: 0.010,
+  16: 0.009, 17: 0.008, 18: 0.008, 19: 0.007, 20: 0.007,
+};
+
+export function expectedCtr(position) {
+  if (position == null || !Number.isFinite(position)) return 0;
+  if (position < 1) return CTR_CURVE[1];
+  if (position > 20) return 0.005;
+  const lo = Math.floor(position);
+  const hi = Math.ceil(position);
+  if (lo === hi) return CTR_CURVE[lo];
+  const frac = position - lo;
+  return CTR_CURVE[lo] + (CTR_CURVE[hi] - CTR_CURVE[lo]) * frac; // linear interpolation
+}
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'to', 'for', 'of', 'in', 'on', 'at', 'and', 'or', 'with',
+  'my', 'your', 'is', 'are', 'how', 'what', 'best', 'near', 'me', 'do', 'i',
+  'can', 'you', 'vs', 'get', 'use',
+]);
+
+// Deterministic intent staging from lexical signals. Precedence: act > compare > learn.
+const INTENT_RULES = [
+  ['act', /\b(buy|price|pricing|cost|costs|cheap|cheapest|deal|deals|coupon|discount|order|shop|hire|book|booking|near me|for sale|quote|demo|sign ?up|trial|subscribe|download|free)\b/],
+  ['compare', /\b(best|top|vs|versus|review|reviews|comparison|compare|alternative|alternatives|which|better)\b/],
+  ['learn', /\b(how|what|why|when|who|where|guide|tutorial|ideas|examples|tips|meaning|definition|learn|explained)\b/],
+];
+
+export function classifyIntent(query) {
+  const q = ` ${query.toLowerCase()} `;
+  for (const [stage, re] of INTENT_RULES) {
+    if (re.test(q)) return stage;
+  }
+  return 'unknown';
+}
+
+const round = (n, d = 0) => {
+  const f = 10 ** d;
+  return Math.round(n * f) / f;
+};
+const pct = (fraction) => `${round(fraction * 100, 1)}%`;
+
+export function buildStrategy(records, options = {}) {
+  const cfg = {
+    strikingMin: 11,
+    strikingMax: 20,
+    strikingTarget: 5, // realistic mid-page-one landing spot to model against
+    lowCtrMaxPosition: 10,
+    lowCtrMinImpressions: 100,
+    lowCtrRatio: 0.7, // flag when actual CTR is below 70% of the position's expected CTR
+    cannibalMinImpressions: 1,
+    ...options,
+  };
+
+  const rows = records
+    .filter((r) => r.query)
+    .map((r) => ({ ...r, intent: classifyIntent(r.query) }));
+
+  const strikingDistance = [];
+  const lowCtrOpportunities = [];
+  const opportunities = [];
+
+  for (const r of rows) {
+    const pos = r.position;
+    if (pos == null) continue;
+
+    // --- Striking distance: page-two keywords one push from page one ---
+    if (pos >= cfg.strikingMin && pos <= cfg.strikingMax) {
+      const projectedCtr = expectedCtr(cfg.strikingTarget);
+      const projectedClicks = r.impressions * projectedCtr;
+      const gain = Math.max(0, projectedClicks - r.clicks);
+      const rec = {
+        query: r.query,
+        url: r.url,
+        intent: r.intent,
+        position: pos,
+        impressions: r.impressions,
+        clicks: r.clicks,
+        ctr: r.ctr,
+        lever: 'improve-rank',
+        target: `position ${cfg.strikingTarget}`,
+        projectedCtr: round(projectedCtr, 4),
+        projectedClicks: round(projectedClicks, 1),
+        opportunityClicks: round(gain, 1),
+        confidence: 'estimated',
+        math: `pos ${round(pos, 1)} (page 2) → target pos ${cfg.strikingTarget}: `
+          + `${r.impressions} impr × ${pct(projectedCtr)} = ${round(projectedClicks, 1)} est. clicks `
+          + `− ${r.clicks} now = +${round(gain, 1)}`,
+      };
+      strikingDistance.push(rec);
+      opportunities.push(rec);
+      continue;
+    }
+
+    // --- High-impression / low-CTR: ranks on page one but underclicks its slot ---
+    if (pos <= cfg.lowCtrMaxPosition && r.impressions >= cfg.lowCtrMinImpressions) {
+      const expCtr = expectedCtr(pos);
+      if (expCtr > 0 && r.ctr < expCtr * cfg.lowCtrRatio) {
+        const projectedClicks = r.impressions * expCtr;
+        const gain = Math.max(0, projectedClicks - r.clicks);
+        const rec = {
+          query: r.query,
+          url: r.url,
+          intent: r.intent,
+          position: pos,
+          impressions: r.impressions,
+          clicks: r.clicks,
+          ctr: r.ctr,
+          lever: 'improve-ctr',
+          target: 'title/meta rewrite',
+          projectedCtr: round(expCtr, 4),
+          projectedClicks: round(projectedClicks, 1),
+          opportunityClicks: round(gain, 1),
+          confidence: 'estimated',
+          math: `pos ${round(pos, 1)}: actual CTR ${pct(r.ctr)} vs expected ${pct(expCtr)}; `
+            + `${r.impressions} impr × ${pct(expCtr)} = ${round(projectedClicks, 1)} est. clicks `
+            + `− ${r.clicks} now = +${round(gain, 1)}`,
+        };
+        lowCtrOpportunities.push(rec);
+        opportunities.push(rec);
+      }
+    }
+  }
+
+  const cannibalization = detectCannibalization(rows, cfg);
+  const clusters = clusterTopics(rows);
+
+  // Ranked opportunity list: highest modeled click gain first, deterministic tie-break.
+  const cmp = (a, b) => (b.opportunityClicks - a.opportunityClicks)
+    || a.query.localeCompare(b.query)
+    || (a.url || '').localeCompare(b.url || '');
+  opportunities.sort(cmp);
+  strikingDistance.sort(cmp);
+  lowCtrOpportunities.sort(cmp);
+
+  const totalOpportunityClicks = round(
+    opportunities.reduce((s, o) => s + o.opportunityClicks, 0), 1,
+  );
+
+  return {
+    input: {
+      rows: rows.length,
+      hasUrls: rows.some((r) => r.url),
+      withPosition: rows.filter((r) => r.position != null).length,
+    },
+    summary: buildSummary({
+      rows, strikingDistance, lowCtrOpportunities, cannibalization,
+      opportunities, totalOpportunityClicks,
+    }),
+    totalOpportunityClicks,
+    strikingDistance,
+    lowCtrOpportunities,
+    cannibalization,
+    clusters,
+    opportunities,
+  };
+}
+
+function detectCannibalization(rows, cfg) {
+  const byQuery = new Map();
+  for (const r of rows) {
+    if (!r.url) continue;
+    if (r.impressions < cfg.cannibalMinImpressions) continue;
+    if (!byQuery.has(r.query)) byQuery.set(r.query, new Map());
+    const urls = byQuery.get(r.query);
+    // aggregate in case the same query+url appears on multiple rows
+    const prev = urls.get(r.url) || { url: r.url, clicks: 0, impressions: 0, position: r.position };
+    prev.clicks += r.clicks;
+    prev.impressions += r.impressions;
+    // keep the best (lowest) position seen for that url
+    if (r.position != null && (prev.position == null || r.position < prev.position)) prev.position = r.position;
+    urls.set(r.url, prev);
+  }
+
+  const out = [];
+  for (const [query, urlMap] of byQuery) {
+    if (urlMap.size < 2) continue;
+    const urls = [...urlMap.values()].sort(
+      (a, b) => (b.impressions - a.impressions) || a.url.localeCompare(b.url),
+    );
+    const totalImpr = urls.reduce((s, u) => s + u.impressions, 0);
+    const primary = urls[0];
+    const competing = urls.slice(1);
+    const splitImpr = totalImpr - primary.impressions;
+    const splitShare = totalImpr > 0 ? splitImpr / totalImpr : 0;
+    out.push({
+      query,
+      urlCount: urls.length,
+      urls: urls.map((u) => ({
+        url: u.url,
+        clicks: u.clicks,
+        impressions: u.impressions,
+        position: u.position,
+      })),
+      primaryUrl: primary.url,
+      competingUrls: competing.map((u) => u.url),
+      splitShare: round(splitShare, 3),
+      severity: splitShare >= 0.2 ? 'warn' : 'info',
+      confidence: 'verified-in-data',
+      note: `${urls.length} URLs rank for "${query}"; ${pct(splitShare)} of impressions land off the primary URL (${primary.url}).`,
+    });
+  }
+  out.sort((a, b) => (b.splitShare - a.splitShare) || a.query.localeCompare(b.query));
+  return out;
+}
+
+// Heuristic (not semantic) topic clustering: group queries by their highest-signal
+// shared token. Deterministic; used to sketch pillar/cluster structure.
+function clusterTopics(rows) {
+  const freq = new Map();
+  const tokenize = (q) => q.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t && t.length > 2 && !STOPWORDS.has(t));
+  for (const r of rows) {
+    for (const t of new Set(tokenize(r.query))) freq.set(t, (freq.get(t) || 0) + 1);
+  }
+  const clusters = new Map();
+  for (const r of rows) {
+    const tokens = tokenize(r.query);
+    let label = tokens[0] || r.query.toLowerCase();
+    let bestFreq = -1;
+    for (const t of tokens) {
+      const f = freq.get(t) || 0;
+      if (f > bestFreq || (f === bestFreq && t < label)) { bestFreq = f; label = t; }
+    }
+    if (!clusters.has(label)) clusters.set(label, { topic: label, queries: [], impressions: 0, clicks: 0 });
+    const c = clusters.get(label);
+    c.queries.push(r.query);
+    c.impressions += r.impressions;
+    c.clicks += r.clicks;
+  }
+  return [...clusters.values()]
+    .map((c) => ({ ...c, size: c.queries.length, queries: [...c.queries].sort() }))
+    .sort((a, b) => (b.impressions - a.impressions) || (b.size - a.size) || a.topic.localeCompare(b.topic));
+}
+
+// Factual, templated read — filled from the numbers, not generated prose.
+function buildSummary(s) {
+  const parts = [];
+  parts.push(`${s.rows.length} queries analyzed; ${s.opportunities.length} carry modeled upside worth ~${s.totalOpportunityClicks} est. clicks/mo.`);
+  if (s.strikingDistance.length) {
+    const top = s.strikingDistance[0];
+    parts.push(`${s.strikingDistance.length} striking-distance keyword(s) (page 2) — biggest: "${top.query}" (+${top.opportunityClicks} est. clicks if moved to top of page 1).`);
+  }
+  if (s.lowCtrOpportunities.length) {
+    const top = s.lowCtrOpportunities[0];
+    parts.push(`${s.lowCtrOpportunities.length} page-one keyword(s) underclicking their slot — biggest: "${top.query}" (title/meta lever, +${top.opportunityClicks} est. clicks).`);
+  }
+  if (s.cannibalization.length) {
+    parts.push(`${s.cannibalization.length} query(ies) split across multiple URLs (cannibalization) — consolidate to one canonical page.`);
+  }
+  return parts.join(' ');
+}

package/agent-cores/seo-content/test/fixtures/gsc-sample.csv

@@ -0,0 +1,11 @@
+Query,Landing Page,Clicks,Impressions,CTR,Position
+crm for real estate agents,https://acme.example/crm-real-estate,20,"2,000",1.00%,14.0
+best crm for solar installers,https://acme.example/crm-solar,8,900,0.89%,17.4
+free crm,https://acme.example/free-crm,50,"5,000",1.00%,4.0
+crm pricing,https://acme.example/pricing,40,800,5.00%,6.0
+crm pricing,https://acme.example/plans,5,300,1.67%,9.0
+best crm software,https://acme.example/best-crm,110,"1,000",11.00%,3.0
+how to use a crm,https://acme.example/crm-guide,300,"3,000",10.00%,2.0
+buy crm software online,https://acme.example/checkout,2,60,3.33%,8.0
+enterprise crm platform,https://acme.example/enterprise,1,1200,0.08%,42.0
+crm integrations,https://acme.example/integrations,12,1500,0.80%,7.0

package/agent-cores/seo-content/test/parse.test.mjs

@@ -0,0 +1,59 @@
+// Parser tests — run with `node --test`. Confirms the CSV/JSON normalizer turns
+// messy real-export columns into clean numeric records.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseRecords, parseCsv, _internal } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'gsc-sample.csv'), 'utf8');
+
+test('CSV parser respects quoted fields with embedded commas', () => {
+  const rows = parseCsv('a,b\n"1,234",x\n');
+  assert.deepEqual(rows, [['a', 'b'], ['1,234', 'x']]);
+});
+
+test('thousands separators and percent CTR parse to real numbers', () => {
+  const recs = parseRecords(csv);
+  const rre = recs.find((r) => r.query === 'crm for real estate agents');
+  assert.equal(rre.impressions, 2000, '"2,000" -> 2000');
+  assert.equal(rre.clicks, 20);
+  assert.equal(rre.ctr, 0.01, '1.00% -> 0.01');
+  assert.equal(rre.position, 14);
+});
+
+test('bare CTR ">1" is treated as a percentage, "<=1" as a fraction', () => {
+  const near = (a, b) => assert.ok(Math.abs(a - b) < 1e-9, `${a} ~= ${b}`);
+  near(_internal.parseCtr('5.2'), 0.052);
+  near(_internal.parseCtr('0.052'), 0.052);
+  near(_internal.parseCtr('5.2%'), 0.052);
+});
+
+test('header aliases normalize across GSC/Semrush/Ahrefs naming', () => {
+  assert.equal(_internal.normalizeHeader('Keyword'), 'query');
+  assert.equal(_internal.normalizeHeader('Avg. Position'), 'position');
+  assert.equal(_internal.normalizeHeader('URL Clicks'), 'clicks');
+  assert.equal(_internal.normalizeHeader('Search Volume'), 'volume');
+});
+
+test('CTR is derived from clicks/impressions when the column is absent', () => {
+  const recs = parseRecords('Keyword,URL,Clicks,Impressions,Position\nx,https://a,25,1000,6\n');
+  assert.equal(recs[0].ctr, 0.025);
+});
+
+test('JSON input yields the same normalized shape as CSV', () => {
+  const recs = parseRecords(JSON.stringify([
+    { query: 'x', url: 'https://a', clicks: 10, impressions: 500, ctr: '2%', position: 8 },
+  ]));
+  assert.equal(recs.length, 1);
+  assert.deepEqual(recs[0], {
+    query: 'x', url: 'https://a', clicks: 10, impressions: 500, ctr: 0.02, position: 8, volume: null,
+  });
+});
+
+test('all ten fixture rows parse (none dropped)', () => {
+  assert.equal(parseRecords(csv).length, 10);
+});