@gscdump/sdk 7.12.0 → 7.13.0

package/dist/indexing/overview.d.mts

@@ -0,0 +1,158 @@
+import { SearchConsoleStageIssue } from "../search-console-stage.mjs";
+import { TrustGate } from "./trust-gate.mjs";
+import { GscdumpIndexingUrl } from "@gscdump/contracts";
+export type IndexingDiagnosisReason = 'none' | 'crawl_blocked' | 'canonical_or_indexability_blocked' | 'unknown_to_google_discovery_gap' | 'discovered_not_crawled' | 'crawled_not_indexed_quality_selection' | 'not_indexed_unspecified' | 'mixed_indexing_failure' | 'data_incomplete';
+export type IndexingDiagnosisActionId = 'complete-indexing-data' | 'fix-crawl-access' | 'align-indexability-signals' | 'improve-discovery' | 'strengthen-crawl-priority' | 'improve-or-consolidate-content' | 'run-url-level-triage';
+/** The part of a diagnosis the Indexing overview reads. */
+export interface IndexingOverviewDiagnosis {
+  reason: IndexingDiagnosisReason;
+  recommendedActions: ReadonlyArray<{
+    id: IndexingDiagnosisActionId;
+  }>;
+}
+/** What the caller's diagnosis function receives. */
+export interface IndexingDiagnoseInput<Row> {
+  totalUrls: number;
+  indexed: number;
+  issues: SearchConsoleStageIssue[];
+  sampleUrls?: Row[];
+}
+/** One inspected URL, as far as the Inspection stages are concerned. */
+export type InspectionStageRow = Partial<Pick<GscdumpIndexingUrl, 'verdict' | 'indexingState' | 'robotsTxtState' | 'pageFetchState' | 'lastCrawlTime'>>;
+export interface InspectionStageSource {
+  urls: ReadonlyArray<InspectionStageRow>;
+  pagination: {
+    total: number;
+    hasMore: boolean;
+  };
+  inspectedCount: number;
+}
+export interface AvailableInspectionStages {
+  _tag: 'available';
+  inspected: number;
+  crawled: number;
+  indexable: number;
+  indexed: number;
+}
+export interface UnavailableInspectionStages {
+  _tag: 'unavailable';
+  reason: 'partial_rows' | 'scope_mismatch';
+}
+export type InspectionStageCounts = AvailableInspectionStages | UnavailableInspectionStages;
+export interface IndexingOverviewInput<Row = unknown> {
+  totalUrls: number;
+  indexed: number;
+  issues: SearchConsoleStageIssue[];
+  indexingStatus: 'pending' | 'partial' | 'complete' | null;
+  inspectedCount: number;
+  sitemapTotal: number;
+  /** Sitemap URL counts by day, in any order. */
+  sitemapHistory: ReadonlyArray<{
+    date: string;
+    urlCount: number;
+  }>;
+  sampleUrls?: Row[];
+  stages: InspectionStageCounts;
+  trust: TrustGate;
+}
+export interface IndexingOverviewCount {
+  id: string;
+  value: number;
+  label: string;
+}
+export interface IndexingOverviewReason {
+  issueType: string;
+  label: string;
+  count: number;
+  countLabel: string;
+  severity: NonNullable<SearchConsoleStageIssue['severity']>;
+}
+export type IndexingReasonGroupId = 'crawl_fetch' | 'discovery' | 'indexability' | 'selection' | 'unknown' | 'other';
+export interface IndexingOverviewReasonGroup {
+  id: IndexingReasonGroupId;
+  label: string;
+  countLabel: string;
+  reasons: IndexingOverviewReason[];
+}
+export interface IndexingOverviewAction {
+  engineActionId: IndexingDiagnosisActionId;
+  issueType: string | null;
+  label: string;
+  detail: string;
+  buttonLabel: string;
+}
+export interface IndexingOverviewScope {
+  inspected: number;
+  indexed: number;
+  indexedLabel: string;
+  sitemapTotal: number;
+  complete: boolean;
+}
+export interface InspectionStageStep {
+  id: 'inspected' | 'crawled' | 'indexable' | 'indexed';
+  label: 'Inspected' | 'Crawled' | 'Indexable' | 'Indexed';
+  value: number;
+  countLabel: string;
+}
+export interface InspectionStageSteps {
+  _tag: 'available';
+  steps: [InspectionStageStep, InspectionStageStep, InspectionStageStep, InspectionStageStep];
+  largestLoss: {
+    from: InspectionStageStep['label'];
+    to: InspectionStageStep['label'];
+    count: number;
+  } | null;
+}
+export interface IndexingOverviewWaiting {
+  _tag: 'waiting';
+  /** `not_connected` needs a connect action; `pending` needs patience. */
+  state: 'not_connected' | 'pending';
+  reason: string;
+  progress: {
+    inspected: number;
+    total: number;
+  } | null;
+}
+export interface IndexingOverviewTrustFailure {
+  _tag: 'trust_failure';
+  reason: string;
+  state: 'unknown' | 'broken' | 'no_sitemap';
+}
+export interface IndexingOverviewVerifyScope {
+  _tag: 'verify_scope';
+  current: number;
+  highWater: number;
+  reason: string;
+}
+export interface IndexingOverviewPartialScope {
+  _tag: 'partial_scope';
+  scope: IndexingOverviewScope;
+  reason: string;
+}
+export interface IndexingOverviewDiagnosisState<Diagnosis extends IndexingOverviewDiagnosis = IndexingOverviewDiagnosis> {
+  _tag: 'diagnosis';
+  diagnosis: Diagnosis;
+  scope: IndexingOverviewScope;
+  counts: IndexingOverviewCount[];
+  reasonGroups: IndexingOverviewReasonGroup[];
+  stages: InspectionStageSteps | UnavailableInspectionStages;
+  primaryAction: IndexingOverviewAction | null;
+  trustNote: string | null;
+}
+export type IndexingOverviewModel<Diagnosis extends IndexingOverviewDiagnosis = IndexingOverviewDiagnosis> = IndexingOverviewWaiting | IndexingOverviewTrustFailure | IndexingOverviewVerifyScope | IndexingOverviewPartialScope | IndexingOverviewDiagnosisState<Diagnosis>;
+/**
+ * Count the Inspection stages from the inspected rows. Refuses a partial page:
+ * stages drawn from 500 of 4,000 rows read as a 4,000-URL answer.
+ */
+export declare function countInspectionStages(input: InspectionStageSource): InspectionStageCounts;
+/** The recommended action that addresses one issue type, if the diagnosis has one. */
+export declare function indexingActionForIssue<Action extends {
+  id: IndexingDiagnosisActionId;
+}>(diagnosis: {
+  recommendedActions: ReadonlyArray<Action>;
+}, issueType: string): Action | undefined;
+/**
+ * The Indexing overview for one Site. `diagnose` is called only once the Trust
+ * gate and the sitemap scope allow a diagnosis.
+ */
+export declare function buildIndexingOverviewModel<Row, Diagnosis extends IndexingOverviewDiagnosis>(input: IndexingOverviewInput<Row>, diagnose: (input: IndexingDiagnoseInput<Row>) => Diagnosis): IndexingOverviewModel<Diagnosis>;

package/dist/indexing/overview.mjs

@@ -0,0 +1,310 @@
+import { compareCurrentSitemapScope } from "./trust-gate.mjs";
+const hardCrawlIssueTypes = /* @__PURE__ */ new Set([
+	"blocked_robots",
+	"server_error",
+	"access_denied",
+	"access_forbidden",
+	"blocked_4xx",
+	"redirect_error",
+	"crawl_error",
+	"not_found",
+	"soft_404"
+]);
+const issueGroupByType = {
+	blocked_robots: "crawl_fetch",
+	server_error: "crawl_fetch",
+	access_denied: "crawl_fetch",
+	access_forbidden: "crawl_fetch",
+	blocked_4xx: "crawl_fetch",
+	redirect_error: "crawl_fetch",
+	crawl_error: "crawl_fetch",
+	not_found: "crawl_fetch",
+	soft_404: "crawl_fetch",
+	discovered_not_indexed: "discovery",
+	canonical_mismatch: "indexability",
+	canonical_cross_domain: "indexability",
+	noindex: "indexability",
+	duplicate_no_canonical: "indexability",
+	crawled_not_indexed: "selection",
+	unknown_to_google: "unknown"
+};
+const reasonGroupLabels = {
+	crawl_fetch: "Crawl or fetch faults",
+	discovery: "Discovered, not crawled",
+	indexability: "Canonical or indexability faults",
+	selection: "Crawled, not indexed",
+	unknown: "Unknown to Google",
+	other: "Other indexing reasons"
+};
+function formatNumber(value) {
+	return new Intl.NumberFormat("en").format(Math.max(0, Math.round(value)));
+}
+function denominatorLabel(value, inspected) {
+	return `${formatNumber(value)} of ${formatNumber(inspected)} inspected`;
+}
+function countInspectionStages(input) {
+	const inspected = Math.max(0, Math.round(input.inspectedCount));
+	const total = Math.max(0, Math.round(input.pagination.total));
+	if (input.pagination.hasMore || input.urls.length !== total) return {
+		_tag: "unavailable",
+		reason: "partial_rows"
+	};
+	if (total !== inspected) return {
+		_tag: "unavailable",
+		reason: "scope_mismatch"
+	};
+	let crawled = 0;
+	let indexable = 0;
+	let indexed = 0;
+	for (const row of input.urls) {
+		const isIndexed = row.verdict === "PASS";
+		const isCrawled = isIndexed || Boolean(row.lastCrawlTime) || row.pageFetchState === "SUCCESSFUL";
+		const isIndexable = isIndexed || isCrawled && row.pageFetchState === "SUCCESSFUL" && row.indexingState === "INDEXING_ALLOWED" && row.robotsTxtState !== "DISALLOWED";
+		if (isCrawled) crawled++;
+		if (isIndexable) indexable++;
+		if (isIndexed) indexed++;
+	}
+	return {
+		_tag: "available",
+		inspected,
+		crawled,
+		indexable,
+		indexed
+	};
+}
+function inspectionStageSteps(stages, inspected) {
+	if (stages._tag === "unavailable") return stages;
+	if (stages.inspected !== inspected) return {
+		_tag: "unavailable",
+		reason: "scope_mismatch"
+	};
+	const values = [
+		stages.inspected,
+		Math.min(stages.inspected, stages.crawled),
+		Math.min(stages.crawled, stages.indexable),
+		Math.min(stages.indexable, stages.indexed)
+	];
+	const labels = [
+		"Inspected",
+		"Crawled",
+		"Indexable",
+		"Indexed"
+	];
+	const ids = [
+		"inspected",
+		"crawled",
+		"indexable",
+		"indexed"
+	];
+	const steps = values.map((value, index) => ({
+		id: ids[index],
+		label: labels[index],
+		value,
+		countLabel: denominatorLabel(value, inspected)
+	}));
+	let largestLoss = null;
+	for (let index = 1; index < steps.length; index++) {
+		const previous = steps[index - 1];
+		const current = steps[index];
+		const count = previous.value - current.value;
+		if (count > 0 && (!largestLoss || count > largestLoss.count)) largestLoss = {
+			from: previous.label,
+			to: current.label,
+			count
+		};
+	}
+	return {
+		_tag: "available",
+		steps,
+		largestLoss
+	};
+}
+function issueTypeForAction(actionId, issues) {
+	if (actionId === "fix-crawl-access") return issues.filter((issue) => hardCrawlIssueTypes.has(issue.type) && issue.count > 0).sort((a, b) => b.count - a.count).at(0)?.type ?? null;
+	return (() => {
+		switch (actionId) {
+			case "align-indexability-signals": return [
+				"canonical_cross_domain",
+				"canonical_mismatch",
+				"noindex",
+				"duplicate_no_canonical"
+			];
+			case "improve-discovery": return ["unknown_to_google"];
+			case "strengthen-crawl-priority": return ["discovered_not_indexed"];
+			case "improve-or-consolidate-content":
+			case "run-url-level-triage": return ["crawled_not_indexed", "not_indexed"];
+			case "complete-indexing-data": return [];
+		}
+	})().map((type) => issues.find((issue) => issue.type === type && issue.count > 0)).find(Boolean)?.type ?? null;
+}
+const actionIdsByReason = {
+	none: [],
+	crawl_blocked: ["fix-crawl-access"],
+	canonical_or_indexability_blocked: ["align-indexability-signals"],
+	unknown_to_google_discovery_gap: ["improve-discovery"],
+	discovered_not_crawled: ["strengthen-crawl-priority"],
+	crawled_not_indexed_quality_selection: ["improve-or-consolidate-content", "run-url-level-triage"],
+	not_indexed_unspecified: ["run-url-level-triage"],
+	mixed_indexing_failure: ["run-url-level-triage"],
+	data_incomplete: ["complete-indexing-data"]
+};
+function actionForDiagnosis(diagnosis) {
+	const alignedIds = actionIdsByReason[diagnosis.reason];
+	return diagnosis.recommendedActions.find((action) => alignedIds.includes(action.id)) ?? diagnosis.recommendedActions[0];
+}
+function indexingActionForIssue(diagnosis, issueType) {
+	const alignedIds = (() => {
+		if (hardCrawlIssueTypes.has(issueType)) return ["fix-crawl-access"];
+		if ([
+			"noindex",
+			"canonical_mismatch",
+			"canonical_cross_domain",
+			"duplicate_no_canonical",
+			"alternate_canonical"
+		].includes(issueType)) return ["align-indexability-signals"];
+		if (issueType === "unknown_to_google") return ["improve-discovery"];
+		if (issueType === "discovered_not_indexed") return ["strengthen-crawl-priority"];
+		if (["crawled_not_indexed", "not_indexed"].includes(issueType)) return ["improve-or-consolidate-content", "run-url-level-triage"];
+		return [];
+	})();
+	return diagnosis.recommendedActions.find((action) => alignedIds.includes(action.id));
+}
+const actionCopy = {
+	"fix-crawl-access": {
+		label: "Fix crawl or fetch blockers",
+		detail: "Remove unintended robots blocks, response errors, authentication, or redirect failures.",
+		buttonLabel: "Review blocked URLs"
+	},
+	"align-indexability-signals": {
+		label: "Align indexability signals",
+		detail: "Remove unintended noindex directives and align canonicals, redirects, sitemap URLs, and internal links.",
+		buttonLabel: "Review conflicting URLs"
+	},
+	"improve-discovery": {
+		label: "Make these URLs discoverable",
+		detail: "Put canonical URLs in the sitemap and link to them from indexed pages.",
+		buttonLabel: "Review unknown URLs"
+	},
+	"strengthen-crawl-priority": {
+		label: "Strengthen crawl priority",
+		detail: "Reduce low-value URL inventory and link to important canonical pages from already-indexed pages.",
+		buttonLabel: "Review uncrawled URLs"
+	},
+	"improve-or-consolidate-content": {
+		label: "Improve or consolidate these pages",
+		detail: "Compare rendered content, duplicate intent, canonicals, and internal links before requesting indexing again.",
+		buttonLabel: "Review crawled URLs"
+	},
+	"run-url-level-triage": {
+		label: "Inspect crawled URLs before changing content",
+		detail: "Check fetch, robots, noindex, canonicals, rendered content, and duplication before changing pages in bulk.",
+		buttonLabel: "Review crawled URLs"
+	},
+	"complete-indexing-data": {
+		label: "Complete URL Inspection data",
+		detail: "Finish URL Inspection collection before assigning a cause.",
+		buttonLabel: "View inspected URLs"
+	}
+};
+function groupReasons(issues, inspected, primaryIssueType) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const issue of issues) {
+		if (issue.count <= 0 || issue.type === "not_indexed") continue;
+		const groupId = issueGroupByType[issue.type];
+		if (!groupId) continue;
+		const group = groups.get(groupId) ?? [];
+		group.push({
+			issueType: issue.type,
+			label: issue.label,
+			count: issue.count,
+			countLabel: denominatorLabel(issue.count, inspected),
+			severity: issue.severity ?? "info"
+		});
+		groups.set(groupId, group);
+	}
+	const primaryGroup = primaryIssueType ? issueGroupByType[primaryIssueType] ?? "other" : null;
+	return Array.from(groups.entries(), ([id, reasons]) => ({
+		id,
+		label: reasonGroupLabels[id],
+		countLabel: denominatorLabel(reasons.reduce((total, reason) => total + reason.count, 0), inspected),
+		reasons: reasons.sort((left, right) => Number(right.issueType === primaryIssueType) - Number(left.issueType === primaryIssueType) || right.count - left.count).slice(0, 3)
+	})).sort((left, right) => Number(right.id === primaryGroup) - Number(left.id === primaryGroup) || Math.max(...right.reasons.map((reason) => reason.count)) - Math.max(...left.reasons.map((reason) => reason.count))).slice(0, 3);
+}
+function buildIndexingOverviewModel(input, diagnose) {
+	if (input.trust.state === "not_connected" || input.trust.state === "pending") return {
+		_tag: "waiting",
+		state: input.trust.state,
+		reason: input.trust.reason,
+		progress: input.sitemapTotal > 0 ? {
+			inspected: Math.max(0, input.inspectedCount),
+			total: Math.max(0, input.sitemapTotal)
+		} : null
+	};
+	if (input.trust.state === "unknown" || input.trust.state === "broken" || input.trust.state === "no_sitemap") return {
+		_tag: "trust_failure",
+		state: input.trust.state,
+		reason: input.trust.reason
+	};
+	const sitemapScope = compareCurrentSitemapScope(input.sitemapHistory);
+	if (sitemapScope?.collapsed) return {
+		_tag: "verify_scope",
+		current: sitemapScope.current,
+		highWater: sitemapScope.highWater,
+		reason: `Today's sitemap scope is ${formatNumber(sitemapScope.current)} URLs, down from a recent high of ${formatNumber(sitemapScope.highWater)}.`
+	};
+	const inspected = Math.max(0, input.inspectedCount || input.totalUrls);
+	const complete = input.indexingStatus === "complete" && (input.sitemapTotal <= 0 || inspected >= input.sitemapTotal);
+	const scope = {
+		inspected,
+		indexed: Math.max(0, input.indexed),
+		indexedLabel: denominatorLabel(input.indexed, inspected),
+		sitemapTotal: Math.max(0, input.sitemapTotal),
+		complete
+	};
+	const diagnosis = diagnose({
+		totalUrls: input.totalUrls,
+		indexed: input.indexed,
+		issues: input.issues,
+		sampleUrls: input.sampleUrls
+	});
+	if (diagnosis.reason === "none" && !complete) return {
+		_tag: "partial_scope",
+		scope,
+		reason: `${formatNumber(inspected)} of ${formatNumber(input.sitemapTotal)} sitemap URLs are inspected. Keep collecting evidence before calling coverage complete.`
+	};
+	const action = actionForDiagnosis(diagnosis);
+	const primaryAction = action ? {
+		engineActionId: action.id,
+		issueType: issueTypeForAction(action.id, input.issues),
+		...actionCopy[action.id]
+	} : null;
+	const reasonGroups = groupReasons(input.issues, inspected, primaryAction?.issueType ?? null);
+	const notIndexed = Math.max(0, input.totalUrls - input.indexed);
+	return {
+		_tag: "diagnosis",
+		diagnosis,
+		scope,
+		counts: [
+			{
+				id: "indexed",
+				value: input.indexed,
+				label: denominatorLabel(input.indexed, inspected)
+			},
+			{
+				id: "not-indexed",
+				value: notIndexed,
+				label: denominatorLabel(notIndexed, inspected)
+			},
+			...reasonGroups.flatMap((group) => group.reasons).map((reason) => ({
+				id: reason.issueType,
+				value: reason.count,
+				label: reason.countLabel
+			}))
+		],
+		reasonGroups,
+		stages: inspectionStageSteps(input.stages, inspected),
+		primaryAction,
+		trustNote: input.trust.state === "blip" ? input.trust.reason : null
+	};
+}
+export { buildIndexingOverviewModel, countInspectionStages, indexingActionForIssue };

package/dist/indexing/portfolio-markdown.d.mts

@@ -0,0 +1,60 @@
+import { Period } from "../period.mjs";
+/** One day of a Site's exported trend. */
+export interface IndexingMarkdownTrendPoint {
+  date: string;
+  /** Indexed share at this point, 0 to 100. */
+  indexedPercent: number;
+  /** Crawl errors at this point: not found, soft 404, and server errors. */
+  errors: number;
+}
+export interface IndexingMarkdownIssues {
+  notFound: number;
+  soft404: number;
+  serverError: number;
+}
+export interface IndexingMarkdownSite {
+  name: string;
+  hostname: string;
+  hasGsc: boolean;
+  /** The Site reading at the window end. */
+  indexed: number | null;
+  totalUrls: number | null;
+  indexedPercent: number | null;
+  change7d: number | null;
+  change28d: number | null;
+  /** The window's daily series. */
+  trend: IndexingMarkdownTrendPoint[] | null;
+  /** Crawl errors from the reading at the window end. */
+  latestIssues: IndexingMarkdownIssues | null;
+}
+export interface IndexingMarkdownInput {
+  title: string;
+  periodLabel: string;
+  range: {
+    start: string;
+    end: string;
+  } | null;
+  sites: IndexingMarkdownSite[];
+}
+export interface IndexingMarkdownBucket {
+  start: string;
+  end: string;
+  /** Mean indexed share across the bucket's days. */
+  indexedPercent: number;
+  /** Summed errors across the bucket's days. */
+  errors: number;
+}
+/** Days per exported bucket for a Period. */
+export declare function indexingMarkdownBucketDays(period: Period | string): number;
+/**
+ * Bucket a daily series into rolling equal-length windows anchored to the most
+ * recent date, so the latest bucket is always full. The indexed share is the
+ * bucket mean; errors are summed. Oldest first.
+ */
+export declare function bucketIndexingSeries(trend: readonly IndexingMarkdownTrendPoint[], bucketDays: number): IndexingMarkdownBucket[];
+/**
+ * The Markdown indexing payload for a set of Sites. With one Site (a row copy)
+ * the Portfolio table is skipped; with many (a Portfolio copy) it leads. Sites
+ * without indexing data are dropped, and the Markdown says how many.
+ */
+export declare function buildIndexingPortfolioMarkdown(input: IndexingMarkdownInput, period: Period | string): string;

package/dist/indexing/portfolio-markdown.mjs

@@ -0,0 +1,127 @@
+const BUCKET_DAYS = {
+	"7d": 1,
+	"28d": 7,
+	"3m": 7,
+	"6m": 14,
+	"12m": 30
+};
+function indexingMarkdownBucketDays(period) {
+	return Object.hasOwn(BUCKET_DAYS, period) ? BUCKET_DAYS[period] : 7;
+}
+function dayNumber(date) {
+	return Math.floor(Date.parse(`${date}T00:00:00Z`) / 864e5);
+}
+function bucketIndexingSeries(trend, bucketDays) {
+	if (!trend.length) return [];
+	const sorted = trend.toSorted((a, b) => a.date.localeCompare(b.date));
+	const maxDay = dayNumber(sorted.at(-1).date);
+	const groups = /* @__PURE__ */ new Map();
+	for (const point of sorted) {
+		const index = Math.floor((maxDay - dayNumber(point.date)) / bucketDays);
+		const group = groups.get(index) ?? [];
+		group.push(point);
+		groups.set(index, group);
+	}
+	return [...groups.keys()].sort((a, b) => b - a).map((index) => {
+		const points = groups.get(index);
+		return {
+			start: points[0].date,
+			end: points.at(-1).date,
+			indexedPercent: points.reduce((sum, point) => sum + point.indexedPercent, 0) / points.length,
+			errors: points.reduce((sum, point) => sum + point.errors, 0)
+		};
+	});
+}
+function mergeTrend(sites) {
+	const days = /* @__PURE__ */ new Map();
+	for (const site of sites) for (const point of site.trend ?? []) {
+		const day = days.get(point.date) ?? {
+			percentSum: 0,
+			percentCount: 0,
+			errors: 0
+		};
+		day.percentSum += point.indexedPercent;
+		day.percentCount += 1;
+		day.errors += point.errors;
+		days.set(point.date, day);
+	}
+	return [...days.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([date, day]) => ({
+		date,
+		indexedPercent: day.percentSum / day.percentCount,
+		errors: day.errors
+	}));
+}
+function formatCount(value) {
+	return Math.round(value).toLocaleString("en-US");
+}
+function signed(value, digits, suffix = "") {
+	return `${value >= 0 ? "+" : ""}${value.toFixed(digits)}${suffix}`;
+}
+function issuesLabel(issues) {
+	if (!issues) return "n/a";
+	const total = issues.notFound + issues.soft404 + issues.serverError;
+	if (total === 0) return "0";
+	const parts = [];
+	if (issues.notFound) parts.push(`not-found ${formatCount(issues.notFound)}`);
+	if (issues.soft404) parts.push(`soft-404 ${formatCount(issues.soft404)}`);
+	if (issues.serverError) parts.push(`server-error ${formatCount(issues.serverError)}`);
+	return `${formatCount(total)} (${parts.join(", ")})`;
+}
+function trendTable(buckets) {
+	const lines = ["| Period | Indexed % | Errors |", "| --- | ---: | ---: |"];
+	for (const bucket of buckets) lines.push(`| ${bucket.start} → ${bucket.end} | ${bucket.indexedPercent.toFixed(1)}% | ${formatCount(bucket.errors)} |`);
+	return lines.join("\n");
+}
+function siteSummary(site) {
+	const lines = [];
+	if (site.indexed != null && site.totalUrls != null) {
+		const percent = site.indexedPercent != null ? ` (${site.indexedPercent.toFixed(1)}%)` : "";
+		lines.push(`Indexed: ${formatCount(site.indexed)} / ${formatCount(site.totalUrls)}${percent}`);
+	}
+	const deltas = [];
+	if (site.change7d != null) deltas.push(`Δ 7d ${signed(site.change7d, 1, "%")}`);
+	if (site.change28d != null) deltas.push(`Δ 28d ${signed(site.change28d, 1, "%")}`);
+	if (deltas.length) lines.push(deltas.join("   "));
+	lines.push(`Errors: ${issuesLabel(site.latestIssues)}`);
+	return lines.join("\n");
+}
+const SCOPE_NOTE = "Scope: registered host only, subdomains excluded. Source: Google Search Console URL Inspection / coverage.";
+const METHOD_NOTE = "Buckets are rolling and equal-length, oldest first. Indexed % is the mean across the bucket's days; errors are summed.";
+function buildIndexingPortfolioMarkdown(input, period) {
+	const sites = input.sites.filter((site) => site.hasGsc && site.trend && site.trend.length);
+	const bucketDays = indexingMarkdownBucketDays(period);
+	const out = [`# Indexing coverage: ${input.title}`];
+	const range = input.range ? ` (${input.range.start} → ${input.range.end})` : "";
+	out.push(`Period: ${input.periodLabel}${range}.`);
+	out.push(SCOPE_NOTE);
+	out.push(METHOD_NOTE);
+	if (sites.length < input.sites.length) out.push(`Coverage: ${sites.length} of ${input.sites.length} sites have indexing data; the rest are omitted.`);
+	out.push("");
+	if (!sites.length) {
+		out.push("_No indexing data available for the selected period._");
+		return `${out.join("\n").trim()}\n`;
+	}
+	if (sites.length > 1) {
+		let indexed = 0;
+		let total = 0;
+		for (const site of sites) {
+			indexed += site.indexed ?? 0;
+			total += site.totalUrls ?? 0;
+		}
+		out.push(`## Portfolio (${sites.length} sites)`);
+		out.push(`Indexed: ${formatCount(indexed)} / ${formatCount(total)}${total > 0 ? ` (${(indexed / total * 100).toFixed(1)}%)` : ""}`);
+		out.push("");
+		out.push(trendTable(bucketIndexingSeries(mergeTrend(sites), bucketDays)));
+		out.push("");
+	}
+	for (const site of sites) {
+		const label = site.hostname && site.hostname !== site.name ? `${site.name} (${site.hostname})` : site.name;
+		out.push(`## ${label}`);
+		out.push(siteSummary(site));
+		out.push("");
+		out.push(trendTable(bucketIndexingSeries(site.trend, bucketDays)));
+		out.push("");
+	}
+	return `${out.join("\n").trim()}\n`;
+}
+export { bucketIndexingSeries, buildIndexingPortfolioMarkdown, indexingMarkdownBucketDays };