import { spawnSync } from 'node:child_process';

import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';

import fs from 'node:fs';

import os from 'node:os';

import path from 'node:path';

import { fileURLToPath } from 'node:url';

import { createMarkdownProcessor } from '@astrojs/markdown-remark';

import semver from 'semver';

const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));

export const DEFAULT_DOCS_REPO_ROOT = path.resolve(SCRIPT_DIR, '..');

export const DEFAULT_RELEASE_NOTES_REPOSITORY = 'HagiCode-org/release-notes';

export const DEFAULT_GITHUB_API_BASE_URL = 'https://api.github.com';

export const RELEASE_NOTES_LOCALES = ['zh-CN', 'en'];

export const RELEASE_NOTES_ASSET_PATTERN = /^release-notes-(.+)-history\.zip$/u;

export const GENERATED_MARKER = 'Generated by scripts/sync-release-notes.mjs. Do not edit manually.';

export const DEFAULT_FETCH_OUTPUT = path.join('.tmp', 'release-notes.sync.json');

export const RELEASE_NOTES_LOCAL_SOURCE = 'local-repository';

export const DEFAULT_RELEASE_NOTES_SOURCE_MODE = 'auto';

export const RELEASE_NOTES_SOURCE_MODES = new Set(['auto', 'github', 'local']);

let releaseNotesMarkdownProcessorPromise;

function assert(condition, message) {

if (!condition) {

throw new Error(message);

}

}

function isRecord(value) {

return typeof value === 'object' && value !== null && !Array.isArray(value);

}

function assertNonEmptyString(value, fieldName) {

assert(

typeof value === 'string' && value.trim().length > 0,

`Invalid release-notes payload: ${fieldName} must be a non-empty string`,

);

return value.trim();

}

function toPosixPath(value) {

return value.split(path.sep).join('/');

}

function relativeFromRepo(repoRoot, absolutePath) {

return toPosixPath(path.relative(repoRoot, absolutePath));

}

function ensureJsonResponse(response, context) {

if (!response?.ok) {

const detail =

response?.status === 404

? ' Check the repository slug and provide a token with access to the upstream release-notes repository.'

: '';

throw new Error(`${context} failed with status ${response?.status ?? 'unknown'}.${detail}`);

}

const contentType = response.headers?.get?.('content-type') ?? '';

if (!contentType.toLowerCase().includes('application/json')) {

throw new Error(`${context} expected application/json but received ${contentType || 'unknown content-type'}`);

}

}

function escapeYamlString(value) {

return JSON.stringify(value ?? '');

}

function stripLeadingHeading(markdown) {

const trimmed = markdown.replace(/^\uFEFF/, '');

return trimmed.replace(/^# .+\n+(?=\S)/u, '');

}

async function getReleaseNotesMarkdownProcessor() {

if (!releaseNotesMarkdownProcessorPromise) {

releaseNotesMarkdownProcessorPromise = createMarkdownProcessor();

}

return releaseNotesMarkdownProcessorPromise;

}

async function renderLandingBodyHtml(markdown) {

const processor = await getReleaseNotesMarkdownProcessor();

const bodyMarkdown = stripLeadingHeading(markdown).trim();

const rendered = await processor.render(bodyMarkdown);

return rendered.code.trim();

}

function normalizeDateOnly(value) {

if (typeof value !== 'string' || value.trim().length === 0) {

return null;

}

const trimmed = value.trim();

if (/^\d{4}-\d{2}-\d{2}$/u.test(trimmed)) {

return trimmed;

}

const parsed = new Date(trimmed);

if (Number.isNaN(parsed.getTime())) {

return null;

}

return parsed.toISOString().slice(0, 10);

}

function createExcerpt(markdown) {

const lines = markdown

.replace(/\r\n/g, '\n')

.split('\n')

.map((line) => line.trim())

.filter(Boolean)

.filter((line) => !line.startsWith('#'))

.map((line) => line.replace(/^[-*+]\s+/u, '').replace(/^\d+\.\s+/u, '').trim())

.filter(Boolean);

const excerpt = lines[0] ?? '';

if (excerpt.length <= 180) {

return excerpt;

}

return `${excerpt.slice(0, 177).trimEnd()}...`;

}

function buildReleaseSortValue(tag) {

const normalized = tag.startsWith('v') ? tag.slice(1) : tag;

const valid = semver.valid(normalized);

return valid ?? normalized;

}

export function normalizeReleaseNotesAnchorId(tag) {

const trimmedTag = assertNonEmptyString(tag, 'tag');

const normalizedTag = trimmedTag.replace(/^v+/iu, '').toLowerCase();

return `v${normalizedTag}`;

}

function compareReleaseEntries(left, right) {

const leftSortVersion = left.sortVersion ?? left.tag;

const rightSortVersion = right.sortVersion ?? right.tag;

const semverComparison = semver.valid(leftSortVersion) && semver.valid(rightSortVersion)

? semver.rcompare(leftSortVersion, rightSortVersion)

: 0;

if (semverComparison !== 0) {

return semverComparison;

}

const leftPublishedAt = left.publishedAt ?? '';

const rightPublishedAt = right.publishedAt ?? '';

if (leftPublishedAt !== rightPublishedAt) {

return rightPublishedAt.localeCompare(leftPublishedAt);

}

return right.tag.localeCompare(left.tag, 'en', { numeric: true, sensitivity: 'base' });

}

function createGitHubHeaders({ token, accept }) {

return {

accept,

'user-agent': 'hagicode-docs-release-notes-sync',

...(token ? { authorization: `Bearer ${token}` } : {}),

};

}

function runCommand(command, args, options = {}) {

const result = spawnSync(command, args, {

cwd: options.cwd,

env: options.env ? { ...process.env, ...options.env } : process.env,

encoding: 'utf8',

stdio: ['ignore', 'pipe', 'pipe'],

});

if (result.error) {

throw result.error;

}

if ((result.status ?? 0) !== 0) {

const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();

throw new Error(

`${command} ${args.join(' ')} failed with exit code ${result.status}${detail ? `: ${detail}` : ''}`,

);

}

return {

stdout: result.stdout ?? '',

stderr: result.stderr ?? '',

status: result.status ?? 0,

};

}

function listZipEntries(zipPath) {

return runCommand('unzip', ['-Z1', zipPath]).stdout

.split('\n')

.map((line) => line.trim())

.filter(Boolean)

.filter((entry) => !entry.endsWith('/'));

}

function readZipEntryText(zipPath, entryPath) {

return runCommand('unzip', ['-p', zipPath, entryPath]).stdout.replace(/\r\n/g, '\n');

}

function resolveReleaseDate({ releasePublishedAt, generatedAt, repositoryRanges }) {

const latestCommitDate = repositoryRanges

.flatMap((entry) => entry.commits)

.map((commit) => normalizeDateOnly(commit.date))

.find(Boolean);

return (

normalizeDateOnly(releasePublishedAt)

?? normalizeDateOnly(generatedAt)

?? latestCommitDate

?? null

);

}

function normalizeRepositoryRanges(payload) {

const repositories = isRecord(payload.repositories) ? payload.repositories : {};

return Object.entries(repositories)

.map(([repository, value]) => {

const record = isRecord(value) ? value : {};

const group = isRecord(record.group) ? record.group : {};

const commits = Array.isArray(group.commits)

? group.commits

.filter(isRecord)

.map((commit) => ({

hash: typeof commit.hash === 'string' ? commit.hash : '',

shortHash: typeof commit.shortHash === 'string' ? commit.shortHash : '',

date: typeof commit.date === 'string' ? commit.date : '',

author: typeof commit.author === 'string' ? commit.author : '',

subject: typeof commit.subject === 'string' ? commit.subject : '',

}))

: [];

return {

repository,

path: typeof record.path === 'string' ? record.path : '',

label: typeof group.label === 'string' ? group.label : '',

fromTag: typeof group.fromTag === 'string' ? group.fromTag : null,

toTag: typeof group.toTag === 'string' ? group.toTag : null,

range: typeof group.range === 'string' ? group.range : null,

commitCount: commits.length,

commits,

};

})

.sort((left, right) => left.repository.localeCompare(right.repository));

}

function normalizeAcceptedReleaseNote({ accepted, synchronizedAt }) {

const repositoryRanges = normalizeRepositoryRanges(accepted.payload);

const releaseDate = resolveReleaseDate({

releasePublishedAt: accepted.candidate.releasePublishedAt,

generatedAt: accepted.payload.generatedAt,

repositoryRanges,

});

return {

tag: accepted.tag,

displayTag: accepted.tag,

sortVersion: buildReleaseSortValue(accepted.tag),

releaseDate,

publishedAt: accepted.candidate.releasePublishedAt ?? accepted.payload.generatedAt ?? null,

synchronizedAt,

upstreamGeneratedAt: typeof accepted.payload.generatedAt === 'string' ? accepted.payload.generatedAt : null,

anchorId: normalizeReleaseNotesAnchorId(accepted.tag),

summary: {

'zh-CN': createExcerpt(accepted.bodies['zh-CN']),

en: createExcerpt(accepted.bodies.en),

},

repositoryRanges: repositoryRanges.map((entry) => ({

repository: entry.repository,

path: entry.path,

label: entry.label,

fromTag: entry.fromTag,

toTag: entry.toTag,

range: entry.range,

commitCount: entry.commitCount,

})),

totalCommitCount: repositoryRanges.reduce((sum, entry) => sum + entry.commitCount, 0),

source: {

releaseName: accepted.candidate.releaseName,

releaseUrl: accepted.candidate.releaseHtmlUrl,

assetName: accepted.candidate.assetName,

assetUrl: accepted.candidate.assetDownloadUrl,

jsonPath: accepted.jsonPath,

bodies: accepted.bodyPaths,

},

bodies: accepted.bodies,

};

}

export function resolveDocsRepoRoot(repoRoot = DEFAULT_DOCS_REPO_ROOT) {

return path.resolve(repoRoot);

}

export function parseRepositorySlug(repository) {

const slug = assertNonEmptyString(repository, 'repository');

const [owner, repo, ...rest] = slug.split('/');

assert(owner && repo && rest.length === 0, `Invalid repository slug: ${slug}`);

return { owner, repo, repository: `${owner}/${repo}` };

}

export function resolveReleaseNotesConfig({ repoRoot = DEFAULT_DOCS_REPO_ROOT, env = process.env } = {}) {

const resolvedRoot = resolveDocsRepoRoot(repoRoot);

const repository = env.DOCS_RELEASE_NOTES_REPOSITORY ?? DEFAULT_RELEASE_NOTES_REPOSITORY;

const { owner, repo } = parseRepositorySlug(repository);

const githubApiBaseUrl = env.DOCS_GITHUB_API_BASE_URL ?? DEFAULT_GITHUB_API_BASE_URL;

const sourceMode = String(env.DOCS_RELEASE_NOTES_SOURCE ?? DEFAULT_RELEASE_NOTES_SOURCE_MODE).trim().toLowerCase();

const fetchOutputPath = path.resolve(

resolvedRoot,

env.DOCS_RELEASE_NOTES_FETCH_OUTPUT ?? DEFAULT_FETCH_OUTPUT,

);

assert(

RELEASE_NOTES_SOURCE_MODES.has(sourceMode),

`Invalid release-notes source mode: ${sourceMode}. Expected one of auto, github, local.`,

);

const configuredLocalRepoRoot =

typeof env.DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT === 'string'

&& env.DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT.trim().length > 0

? path.resolve(resolvedRoot, env.DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT)

: null;

const useLocalSource = sourceMode === 'local' || (sourceMode === 'auto' && configuredLocalRepoRoot);

assert(

!(sourceMode === 'local' && !configuredLocalRepoRoot),

'DOCS_RELEASE_NOTES_SOURCE=local requires DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT.',

);

return {

repoRoot: resolvedRoot,

repository,

owner,

repo,

githubApiBaseUrl,

sourceMode,

resolvedSource: useLocalSource ? 'local' : 'github',

localRepoRoot: configuredLocalRepoRoot,

token:

env.DOCS_RELEASE_NOTES_TOKEN

?? env.DOCS_GITHUB_TOKEN

?? env.GITHUB_TOKEN

?? '',

allowStaleOnSourceError:

String(env.DOCS_RELEASE_NOTES_ALLOW_STALE_ON_SOURCE_ERROR ?? '').toLowerCase() === 'true',

fetchOutputPath,

outputPaths: {

indexJson: path.join(resolvedRoot, 'src', 'data', 'release-notes.index.json'),

zhDir: path.join(resolvedRoot, 'src', 'content', 'docs', 'release-notes'),

enDir: path.join(resolvedRoot, 'src', 'content', 'docs', 'en', 'release-notes'),

},

};

}

export function discoverReleaseNoteAssets(releases) {

assert(Array.isArray(releases), 'GitHub release discovery requires an array payload');

return releases

.filter(isRecord)

.flatMap((release) => {

const assets = Array.isArray(release.assets) ? release.assets : [];

return assets

.filter(isRecord)

.map((asset) => {

const assetName = typeof asset.name === 'string' ? asset.name : '';

const match = assetName.match(RELEASE_NOTES_ASSET_PATTERN);

if (!match) {

return null;

}

const tag = match[1];

return {

tag,

assetName,

assetId: asset.id ?? null,

assetApiUrl: typeof asset.url === 'string' ? asset.url : null,

assetDownloadUrl:

typeof asset.browser_download_url === 'string' ? asset.browser_download_url : null,

assetUpdatedAt: typeof asset.updated_at === 'string' ? asset.updated_at : null,

releaseId: release.id ?? null,

releaseName:

typeof release.name === 'string' && release.name.trim().length > 0

? release.name.trim()

: typeof release.tag_name === 'string'

? release.tag_name

: tag,

releaseTagName: typeof release.tag_name === 'string' ? release.tag_name : tag,

releasePublishedAt:

typeof release.published_at === 'string' ? release.published_at : null,

releaseHtmlUrl: typeof release.html_url === 'string' ? release.html_url : null,

};

})

.filter(Boolean);

})

.sort((left, right) => {

const publishedComparison = (right.releasePublishedAt ?? '').localeCompare(

left.releasePublishedAt ?? '',

);

if (publishedComparison !== 0) {

return publishedComparison;

}

return right.tag.localeCompare(left.tag, 'en', { numeric: true, sensitivity: 'base' });

});

}

export async function fetchGitHubReleases({ config, fetchImpl = globalThis.fetch }) {

assert(typeof fetchImpl === 'function', 'GitHub release discovery requires a fetch implementation');

const releases = [];

for (let page = 1; page <= 20; page += 1) {

const url = new URL(`${config.githubApiBaseUrl}/repos/${config.owner}/${config.repo}/releases`);

url.searchParams.set('per_page', '100');

url.searchParams.set('page', String(page));

const response = await fetchImpl(url, {

headers: createGitHubHeaders({

token: config.token,

accept: 'application/vnd.github+json',

}),

});

ensureJsonResponse(response, `GitHub release discovery for ${config.repository}`);

const pagePayload = await response.json();

assert(Array.isArray(pagePayload), 'GitHub Releases API returned a non-array payload');

releases.push(...pagePayload);

if (pagePayload.length < 100) {

break;

}

}

return releases;

}

export async function downloadReleaseAsset({

assetDownloadUrl,

outputPath,

token,

fetchImpl = globalThis.fetch,

}) {

assertNonEmptyString(assetDownloadUrl, 'assetDownloadUrl');

assertNonEmptyString(outputPath, 'outputPath');

assert(typeof fetchImpl === 'function', 'Release asset download requires a fetch implementation');

const response = await fetchImpl(assetDownloadUrl, {

headers: createGitHubHeaders({

token,

accept: 'application/octet-stream',

}),

});

if (!response?.ok) {

throw new Error(

`Failed to download release-notes asset from ${assetDownloadUrl}: ${response?.status ?? 'unknown status'}`,

);

}

const buffer = Buffer.from(await response.arrayBuffer());

await mkdir(path.dirname(outputPath), { recursive: true });

await writeFile(outputPath, buffer);

return outputPath;

}

export function inspectReleaseNoteArchive({ zipPath, candidate }) {

const tag = assertNonEmptyString(candidate?.tag, 'candidate.tag');

const entries = listZipEntries(zipPath);

const requiredJsonPath = `artifacts/tags/${tag}/${tag}.json`;

if (!entries.includes(requiredJsonPath)) {

return {

accepted: false,

tag,

reason: 'missing_required_payload',

message: `Archive is missing ${requiredJsonPath}.`,

};

}

let payload;

try {

payload = JSON.parse(readZipEntryText(zipPath, requiredJsonPath));

} catch (error) {

return {

accepted: false,

tag,

reason: 'invalid_required_payload',

message: `Archive JSON payload ${requiredJsonPath} is malformed: ${error.message}`,

};

}

const payloadTag = isRecord(payload) && typeof payload.tag === 'string' ? payload.tag.trim() : '';

if (payloadTag !== tag) {

return {

accepted: false,

tag,

reason: 'tag_mismatch',

message: `Archive tag ${tag} does not match payload tag ${payloadTag || '<missing>'}.`,

};

}

const bodies = {};

const bodyPaths = {};

for (const locale of RELEASE_NOTES_LOCALES) {

const bodyPath = `published/${tag}.${locale}.md`;

if (!entries.includes(bodyPath)) {

return {

accepted: false,

tag,

reason: 'missing_locale_body',

message: `Archive is incomplete for docs sync; missing required published body for ${locale}: ${bodyPath}.`,

locale,

};

}

const body = readZipEntryText(zipPath, bodyPath).trim();

if (body.length === 0) {

return {

accepted: false,

tag,

reason: 'empty_locale_body',

message: `Archive body ${bodyPath} is empty.`,

locale,

};

}

bodies[locale] = body;

bodyPaths[locale] = bodyPath;

}

return {

accepted: true,

tag,

candidate,

payload,

jsonPath: requiredJsonPath,

bodies,

bodyPaths,

};

}

export function normalizeSynchronizedReleaseNotes({ acceptedEntries, config, synchronizedAt }) {

const entries = acceptedEntries

.map((entry) => normalizeAcceptedReleaseNote({ accepted: entry, synchronizedAt }))

.sort(compareReleaseEntries);

return {

generatedAt: synchronizedAt,

source: {

repository: config.resolvedSource === 'local' ? RELEASE_NOTES_LOCAL_SOURCE : config.repository,

githubApiBaseUrl: config.resolvedSource === 'local' ? null : config.githubApiBaseUrl,

mode: config.resolvedSource,

locales: RELEASE_NOTES_LOCALES,

},

entries,

};

}

async function inspectLocalReleaseNoteTag({ config, tag }) {

const jsonPath = path.join(config.localRepoRoot, 'artifacts', 'tags', tag, `${tag}.json`);

if (!fs.existsSync(jsonPath) || !fs.statSync(jsonPath).isFile()) {

return {

accepted: false,

tag,

reason: 'missing_required_payload',

message: `Local source is missing artifacts/tags/${tag}/${tag}.json.`,

};

}

let payload;

try {

payload = JSON.parse(await readFile(jsonPath, 'utf8'));

} catch (error) {

return {

accepted: false,

tag,

reason: 'invalid_required_payload',

message: `Local JSON payload for ${tag} is malformed: ${error.message}`,

};

}

const payloadTag = isRecord(payload) && typeof payload.tag === 'string' ? payload.tag.trim() : '';

if (payloadTag !== tag) {

return {

accepted: false,

tag,

reason: 'tag_mismatch',

message: `Local tag ${tag} does not match payload tag ${payloadTag || '<missing>'}.`,

};

}

const bodies = {};

const bodyPaths = {};

for (const locale of RELEASE_NOTES_LOCALES) {

const bodyPath = path.join(config.localRepoRoot, 'published', `${tag}.${locale}.md`);

if (!fs.existsSync(bodyPath) || !fs.statSync(bodyPath).isFile()) {

return {

accepted: false,

tag,

reason: 'missing_locale_body',

message: `Local source is incomplete for docs sync; missing published/${tag}.${locale}.md.`,

locale,

};

}

const body = (await readFile(bodyPath, 'utf8')).replace(/\r\n/g, '\n').trim();

if (body.length === 0) {

return {

accepted: false,

tag,

reason: 'empty_locale_body',

message: `Local source is incomplete for docs sync because published/${tag}.${locale}.md is empty.`,

locale,

};

}

bodies[locale] = body;

bodyPaths[locale] = `published/${tag}.${locale}.md`;

}

return {

accepted: true,

tag,

candidate: {

tag,

assetName: `release-notes-${tag}-history.zip`,

assetDownloadUrl: null,

releasePublishedAt: typeof payload.generatedAt === 'string' ? payload.generatedAt : null,

releaseHtmlUrl: null,

releaseName: tag,

},

payload,

jsonPath: `artifacts/tags/${tag}/${tag}.json`,

bodies,

bodyPaths,

};

}

async function fetchLocalReleaseNotesSnapshot({ config }) {

const synchronizedAt = new Date().toISOString();

const tagsRoot = path.join(config.localRepoRoot, 'artifacts', 'tags');

assert(

fs.existsSync(tagsRoot) && fs.statSync(tagsRoot).isDirectory(),

`Local release-notes tags directory not found: ${tagsRoot}`,

);

const entries = await readdir(tagsRoot, { withFileTypes: true });

const tagNames = entries

.filter((entry) => entry.isDirectory())

.map((entry) => entry.name)

.filter((tag) => tag !== 'unreleased')

.sort((left, right) => left.localeCompare(right, 'en', { numeric: true, sensitivity: 'base' }));

const acceptedEntries = [];

const skippedEntries = [];

for (const tag of tagNames) {

const inspection = await inspectLocalReleaseNoteTag({ config, tag });

if (inspection.accepted) {

acceptedEntries.push(inspection);

} else {

skippedEntries.push({

tag,

assetName: `release-notes-${tag}-history.zip`,

reason: inspection.reason,

message: inspection.message,

});

}

}

const normalized = normalizeSynchronizedReleaseNotes({

acceptedEntries,

config,

synchronizedAt,

});

return {

...normalized,

skipped: skippedEntries,

counts: {

releases: tagNames.length,

discovered: tagNames.length,

synchronized: normalized.entries.length,

skipped: skippedEntries.length,

},

};

}

async function writeJsonFile(filePath, payload) {

await mkdir(path.dirname(filePath), { recursive: true });

await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');

}

async function resetManagedDirectory(directoryPath) {

await rm(directoryPath, { recursive: true, force: true });

await mkdir(directoryPath, { recursive: true });

}

function createLandingPageContent(locale) {

const title = locale === 'en' ? 'Release Notes' : '版本更新说明';

const description =

locale === 'en'

? 'Browse synchronized HagiCode release notes across all published versions.'

: '浏览已同步到文档站的 HagiCode 版本更新说明。';

return `---

title: ${escapeYamlString(title)}

description: ${escapeYamlString(description)}

---

import ReleaseNotesLanding from '@/components/ReleaseNotesLanding.astro';

<ReleaseNotesLanding locale=${escapeYamlString(locale)} />

`;

}

export async function materializeReleaseNotes({ snapshot, config }) {

assert(isRecord(snapshot), 'Release-notes materialization requires an object snapshot');

const entries = Array.isArray(snapshot.entries) ? snapshot.entries : [];

const indexEntries = await Promise.all(entries.map(async (entry) => ({

tag: entry.tag,

displayTag: entry.displayTag,

sortVersion: entry.sortVersion,

releaseDate: entry.releaseDate,

publishedAt: entry.publishedAt,

synchronizedAt: entry.synchronizedAt,

upstreamGeneratedAt: entry.upstreamGeneratedAt,

anchorId: entry.anchorId ?? normalizeReleaseNotesAnchorId(entry.tag),

summary: entry.summary,

repositoryRanges: entry.repositoryRanges,

totalCommitCount: entry.totalCommitCount,

source: entry.source,

landingBodyHtml: {

'zh-CN': await renderLandingBodyHtml(entry.bodies['zh-CN']),

en: await renderLandingBodyHtml(entry.bodies.en),

},

})));

const indexPayload = {

generatedAt: snapshot.generatedAt ?? new Date().toISOString(),

source: snapshot.source ?? {

repository: config.repository,

githubApiBaseUrl: config.githubApiBaseUrl,

locales: RELEASE_NOTES_LOCALES,

},

entries: indexEntries,

};

await writeJsonFile(config.outputPaths.indexJson, indexPayload);

await resetManagedDirectory(config.outputPaths.zhDir);

await resetManagedDirectory(config.outputPaths.enDir);

const writtenFiles = [relativeFromRepo(config.repoRoot, config.outputPaths.indexJson)];

const zhLandingPath = path.join(config.outputPaths.zhDir, 'index.mdx');

const enLandingPath = path.join(config.outputPaths.enDir, 'index.mdx');

await writeFile(zhLandingPath, createLandingPageContent('zh-CN'), 'utf8');

await writeFile(enLandingPath, createLandingPageContent('en'), 'utf8');

writtenFiles.push(relativeFromRepo(config.repoRoot, zhLandingPath));

writtenFiles.push(relativeFromRepo(config.repoRoot, enLandingPath));

return {

indexPath: relativeFromRepo(config.repoRoot, config.outputPaths.indexJson),

writtenFiles,

};

}

export async function fetchReleaseNotesSnapshot({ config, fetchImpl = globalThis.fetch }) {

if (config.resolvedSource === 'local') {

return fetchLocalReleaseNotesSnapshot({ config });

}

const synchronizedAt = new Date().toISOString();

const releases = await fetchGitHubReleases({ config, fetchImpl });

const candidates = discoverReleaseNoteAssets(releases);

const acceptedEntries = [];

const skippedEntries = [];

const stagingRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'docs-release-notes-'));

try {

for (const candidate of candidates) {

const zipPath = path.join(stagingRoot, candidate.assetName);

try {

await downloadReleaseAsset({

assetDownloadUrl: candidate.assetDownloadUrl ?? candidate.assetApiUrl,

outputPath: zipPath,

token: config.token,

fetchImpl,

});

} catch (error) {

skippedEntries.push({

tag: candidate.tag,

assetName: candidate.assetName,

reason: 'asset_download_failed',

message: error.message,

});

continue;

}

const inspection = inspectReleaseNoteArchive({ zipPath, candidate });

if (!inspection.accepted) {

skippedEntries.push({

tag: candidate.tag,

assetName: candidate.assetName,

reason: inspection.reason,

message: inspection.message,

});

continue;

}

acceptedEntries.push(inspection);

}

} finally {

await rm(stagingRoot, { recursive: true, force: true });

}

const normalized = normalizeSynchronizedReleaseNotes({

acceptedEntries,

config,

synchronizedAt,

});

return {

...normalized,

skipped: skippedEntries.sort((left, right) =>

left.tag.localeCompare(right.tag, 'en', { numeric: true, sensitivity: 'base' }),

),

counts: {

releases: releases.length,

discovered: candidates.length,

synchronized: normalized.entries.length,

skipped: skippedEntries.length,

},

};

}

export async function writeFetchedSnapshot({ snapshot, outputPath }) {

await writeJsonFile(outputPath, snapshot);

return outputPath;

}

export async function readSnapshotFromFile(filePath) {

return JSON.parse(await readFile(filePath, 'utf8'));

}

export async function hasManagedReleaseNotesOutput(config) {

const requiredPaths = [

config.outputPaths.indexJson,

path.join(config.outputPaths.zhDir, 'index.mdx'),

path.join(config.outputPaths.enDir, 'index.mdx'),

];

return requiredPaths.every((filePath) => fs.existsSync(filePath) && fs.statSync(filePath).isFile());

}

export function createSourceFailureSummary({ config, error }) {

const repositoryLabel = config.resolvedSource === 'local'

? `local source at ${config.localRepoRoot}`

: config.repository;

return [

'# Release Notes Sync',

'',

`- Repository: \`${repositoryLabel}\``,

'- Result: preserved existing managed outputs',

`- Reason: ${error.message}`,

'',

'No generated files were changed during this run.',

'',

].join('\n');

}

export function createSyncSummaryMarkdown({ snapshot, materialized }) {

const sourceMode = snapshot.source?.mode ?? 'github';

const discoveredLabel = sourceMode === 'local' ? 'Discovered tags' : 'Discovered assets';

const lines = [

'# Release Notes Sync',

'',

`- Repository: \`${snapshot.source?.repository ?? DEFAULT_RELEASE_NOTES_REPOSITORY}\``,

`- Source mode: \`${sourceMode}\``,

`- Generated at: \`${snapshot.generatedAt}\``,

`- ${discoveredLabel}: ${snapshot.counts?.discovered ?? 0}`,

`- Synchronized tags: ${snapshot.counts?.synchronized ?? snapshot.entries?.length ?? 0}`,

`- Skipped tags: ${snapshot.counts?.skipped ?? snapshot.skipped?.length ?? 0}`,

'',

];

if (Array.isArray(snapshot.entries) && snapshot.entries.length > 0) {

lines.push('## Synchronized Tags', '');

for (const entry of snapshot.entries) {

const anchorId = entry.anchorId ?? normalizeReleaseNotesAnchorId(entry.tag);

lines.push(`- \`${entry.tag}\` -> /release-notes/#${anchorId} | /en/release-notes/#${anchorId}`);

}

lines.push('');

}

if (Array.isArray(snapshot.skipped) && snapshot.skipped.length > 0) {

lines.push('## Skipped Tags', '');

for (const entry of snapshot.skipped) {

lines.push(`- \`${entry.tag}\` (${entry.reason}): ${entry.message}`);

}

lines.push('');

}

if (materialized?.writtenFiles?.length) {

lines.push('## Managed Outputs', '');

for (const filePath of materialized.writtenFiles) {

lines.push(`- \`${filePath}\``);

}

lines.push('');

}

return `${lines.join('\n').trim()}\n`;

}