const fs = require('fs'); const path = require('path'); const ROOT = process.cwd(); const METHODS_DIR = path.join(ROOT, 'methods'); const CHANGES_DIR = path.join(METHODS_DIR, 'changes'); function parseArgs(argv) { const args = { specPath: '', dryRun: false, docOnly: false, help: false, }; for (const item of argv) { if (item === '--dry-run') { args.dryRun = true; continue; } if (item === '--doc-only') { args.docOnly = true; continue; } if (item === '--help' || item === '-h') { args.help = true; continue; } if (item.startsWith('--spec=')) { const raw = String(item.slice('--spec='.length)).trim(); args.specPath = raw ? path.resolve(ROOT, raw) : ''; continue; } } if (!args.help && !args.specPath) { throw new Error('Missing required --spec= argument.'); } return args; } function printHelp() { console.log([ 'Usage:', ' npm run doc:api:update -- --spec=temp/api-doc-update.json', ' npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run', ' npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only', '', 'Options:', ' --spec= Path to the fixed update spec JSON file.', ' --dry-run Validate and print the planned changes without writing files.', ' --doc-only Update methods/.json only and skip methods/changes/.json.', ].join('\n')); } function isPlainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); } function assert(condition, message) { if (!condition) { throw new Error(message); } } function readJsonFile(filePath) { const raw = fs.readFileSync(filePath, 'utf8'); return { json: JSON.parse(raw), indent: detectIndent(raw), eol: detectEol(raw), }; } function detectIndent(raw) { // 取第一个带缩进的值行(对象键、数组元素对象 `{` 或字符串元素)作为单层缩进; // 根为数组的文档(methods/changes/*.json)首行 `[` 后紧跟元素 `{`, // 避免把第二层缩进误判为单层缩进,导致全文件重排 const match = raw.match(/^([ \t]+)[\[{"]/m); return match ? match[1] : ' '; } function detectEol(raw) { return raw.includes('\r\n') ? '\r\n' : '\n'; } function writeJsonFile(filePath, value, indent, eol) { const formatted = JSON.stringify(value, null, indent).replace(/\n/g, eol); fs.writeFileSync(filePath, `${formatted}${eol}`, 'utf8'); } function ensureString(value, fieldPath) { assert(typeof value === 'string' && value.trim(), `${fieldPath} must be a non-empty string.`); } function ensureBoolean(value, fieldPath) { assert(typeof value === 'boolean', `${fieldPath} must be a boolean.`); } function ensureArray(value, fieldPath) { assert(Array.isArray(value), `${fieldPath} must be an array.`); } function ensureStringArray(value, fieldPath) { ensureArray(value, fieldPath); value.forEach((item, index) => ensureString(item, `${fieldPath}[${index}]`)); } function validateListOption(option, fieldPath) { assert(isPlainObject(option), `${fieldPath} must be an object.`); const hasValue = Object.prototype.hasOwnProperty.call(option, 'value'); assert(hasValue, `${fieldPath}.value is required.`); } function validateNamedField(field, fieldPath, allowSource) { assert(isPlainObject(field), `${fieldPath} must be an object.`); ensureString(field.name, `${fieldPath}.name`); ensureString(field.type, `${fieldPath}.type`); ensureBoolean(field.required, `${fieldPath}.required`); ensureString(field.description, `${fieldPath}.description`); if (allowSource && Object.prototype.hasOwnProperty.call(field, 'source')) { ensureString(field.source, `${fieldPath}.source`); } if (Object.prototype.hasOwnProperty.call(field, 'list')) { ensureArray(field.list, `${fieldPath}.list`); field.list.forEach((item, index) => validateListOption(item, `${fieldPath}.list[${index}]`)); } } function validateErrorField(field, fieldPath) { assert(isPlainObject(field), `${fieldPath} must be an object.`); assert(Object.prototype.hasOwnProperty.call(field, 'code'), `${fieldPath}.code is required.`); ensureString(field.message, `${fieldPath}.message`); } function validateMethodDoc(methodDoc, fieldPath) { assert(isPlainObject(methodDoc), `${fieldPath} must be an object.`); ensureString(methodDoc.method, `${fieldPath}.method`); ensureString(methodDoc.description, `${fieldPath}.description`); ensureBoolean(methodDoc.isNeedAuth, `${fieldPath}.isNeedAuth`); ensureBoolean(methodDoc.isNeedLogin, `${fieldPath}.isNeedLogin`); ensureArray(methodDoc.headers, `${fieldPath}.headers`); ensureArray(methodDoc.params, `${fieldPath}.params`); ensureArray(methodDoc.response, `${fieldPath}.response`); ensureArray(methodDoc.errors, `${fieldPath}.errors`); methodDoc.headers.forEach((item, index) => validateNamedField(item, `${fieldPath}.headers[${index}]`, false)); methodDoc.params.forEach((item, index) => validateNamedField(item, `${fieldPath}.params[${index}]`, true)); methodDoc.response.forEach((item, index) => validateNamedField(item, `${fieldPath}.response[${index}]`, false)); methodDoc.errors.forEach((item, index) => validateErrorField(item, `${fieldPath}.errors[${index}]`)); } function validateChange(change, fieldPath) { assert(isPlainObject(change), `${fieldPath} must be an object.`); ensureString(change.version, `${fieldPath}.version`); ensureString(change.date, `${fieldPath}.date`); ensureString(change.summary, `${fieldPath}.summary`); ensureStringArray(change.methods, `${fieldPath}.methods`); ensureStringArray(change.notes, `${fieldPath}.notes`); if (Object.prototype.hasOwnProperty.call(change, 'type')) { ensureString(change.type, `${fieldPath}.type`); } } function validateCurrentDoc(doc, fieldPath) { assert(isPlainObject(doc), `${fieldPath} must be an object.`); assert(isPlainObject(doc.methods), `${fieldPath}.methods must be an object.`); ensureArray(doc.methods.groups, `${fieldPath}.methods.groups`); } function validateCurrentChanges(changes, fieldPath) { ensureArray(changes, fieldPath); } function validateSpec(spec, args) { assert(isPlainObject(spec), 'Spec root must be an object.'); ensureString(spec.docName, 'spec.docName'); assert(/^[a-z0-9_-]+$/i.test(spec.docName), 'spec.docName must contain only letters, numbers, underscore, or dash.'); const docPath = path.join(METHODS_DIR, `${spec.docName}.json`); const changePath = path.join(CHANGES_DIR, `${spec.docName}.json`); assert(fs.existsSync(docPath), `Target doc file not found: ${docPath}`); if (!args.docOnly) { assert(fs.existsSync(changePath), `Target change file not found: ${changePath}`); } if (Object.prototype.hasOwnProperty.call(spec, 'docMeta')) { assert(isPlainObject(spec.docMeta), 'spec.docMeta must be an object.'); if (Object.prototype.hasOwnProperty.call(spec.docMeta, 'updatedAt')) { ensureString(spec.docMeta.updatedAt, 'spec.docMeta.updatedAt'); } if (Object.prototype.hasOwnProperty.call(spec.docMeta, 'version')) { ensureString(spec.docMeta.version, 'spec.docMeta.version'); } } assert(isPlainObject(spec.group), 'spec.group must be an object.'); ensureString(spec.group.groupName, 'spec.group.groupName'); ensureString(spec.group.module, 'spec.group.module'); ensureArray(spec.methods, 'spec.methods'); assert(spec.methods.length > 0, 'spec.methods must contain at least one method doc.'); const methodNames = new Set(); spec.methods.forEach((item, index) => { validateMethodDoc(item, `spec.methods[${index}]`); assert(!methodNames.has(item.method), `Duplicate method in spec.methods: ${item.method}`); methodNames.add(item.method); }); let deleteMethods = []; if (Object.prototype.hasOwnProperty.call(spec, 'deleteMethods')) { ensureStringArray(spec.deleteMethods, 'spec.deleteMethods'); deleteMethods = spec.deleteMethods; } deleteMethods.forEach(item => { assert(!methodNames.has(item), `Method conflict: ${item} appears in both spec.methods and spec.deleteMethods.`); }); if (!args.docOnly) { validateChange(spec.change, 'spec.change'); } else if (Object.prototype.hasOwnProperty.call(spec, 'change')) { validateChange(spec.change, 'spec.change'); } return { docName: spec.docName, docPath, changePath, docMeta: spec.docMeta || {}, group: spec.group, methods: spec.methods, deleteMethods, change: spec.change || null, }; } function findGroupIndex(groups, groupSpec) { const byModule = groups.findIndex(group => group && group.module === groupSpec.module); if (byModule >= 0) return byModule; return groups.findIndex(group => group && group.groupName === groupSpec.groupName); } function findMethodLocation(groups, methodName) { for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) { const group = groups[groupIndex]; const list = group && Array.isArray(group.list) ? group.list : []; const methodIndex = list.findIndex(item => item && item.method === methodName); if (methodIndex >= 0) { return { groupIndex, methodIndex }; } } return null; } function cloneJson(value) { return JSON.parse(JSON.stringify(value)); } function applyDocUpdate(doc, groupSpec, methods, docMeta, deleteMethods = []) { const groups = doc.methods.groups; let groupIndex = findGroupIndex(groups, groupSpec); if (groupIndex < 0) { groups.push({ groupName: groupSpec.groupName, module: groupSpec.module, list: [], }); groupIndex = groups.length - 1; } const targetGroup = groups[groupIndex]; targetGroup.groupName = groupSpec.groupName; targetGroup.module = groupSpec.module; if (!Array.isArray(targetGroup.list)) { targetGroup.list = []; } const summary = { inserted: [], updated: [], moved: [], deleted: [], deleteNotFound: [], }; for (const methodDoc of methods) { const nextMethod = cloneJson(methodDoc); const existingLocation = findMethodLocation(groups, methodDoc.method); if (!existingLocation) { targetGroup.list.push(nextMethod); summary.inserted.push(methodDoc.method); continue; } if (existingLocation.groupIndex === groupIndex) { targetGroup.list[existingLocation.methodIndex] = nextMethod; summary.updated.push(methodDoc.method); continue; } groups[existingLocation.groupIndex].list.splice(existingLocation.methodIndex, 1); targetGroup.list.push(nextMethod); summary.moved.push(methodDoc.method); } for (const methodName of deleteMethods) { const location = findMethodLocation(groups, methodName); if (!location) { summary.deleteNotFound.push(methodName); continue; } groups[location.groupIndex].list.splice(location.methodIndex, 1); summary.deleted.push(methodName); } if (docMeta.updatedAt) { doc.updatedAt = docMeta.updatedAt; } if (docMeta.version) { doc.version = docMeta.version; } return summary; } function appendChange(changes, change) { const exists = changes.some(item => item && item.version === change.version); assert(!exists, `Duplicate change version detected: ${change.version}`); // 变更记录保持“新记录在数组开头”的顺序(与 methods/changes/*.json 现有约定一致) changes.unshift(cloneJson(change)); } function main() { const args = parseArgs(process.argv.slice(2)); if (args.help) { printHelp(); return; } assert(fs.existsSync(args.specPath), `Spec file not found: ${args.specPath}`); const specRaw = fs.readFileSync(args.specPath, 'utf8'); const spec = JSON.parse(specRaw); const normalized = validateSpec(spec, args); const docState = readJsonFile(normalized.docPath); validateCurrentDoc(docState.json, normalized.docPath); let changeState = null; if (!args.docOnly) { changeState = readJsonFile(normalized.changePath); validateCurrentChanges(changeState.json, normalized.changePath); } const docNext = cloneJson(docState.json); const summary = applyDocUpdate(docNext, normalized.group, normalized.methods, normalized.docMeta, normalized.deleteMethods); JSON.parse(JSON.stringify(docNext)); let changeNext = null; if (!args.docOnly) { changeNext = cloneJson(changeState.json); appendChange(changeNext, normalized.change); JSON.parse(JSON.stringify(changeNext)); } console.log(`docName: ${normalized.docName}`); console.log(`group: ${normalized.group.module} (${normalized.group.groupName})`); console.log(`inserted: ${summary.inserted.length ? summary.inserted.join(', ') : '-'}`); console.log(`updated: ${summary.updated.length ? summary.updated.join(', ') : '-'}`); console.log(`moved: ${summary.moved.length ? summary.moved.join(', ') : '-'}`); console.log(`deleted: ${summary.deleted.length ? summary.deleted.join(', ') : '-'}`); console.log(`delete-not-found: ${summary.deleteNotFound.length ? summary.deleteNotFound.join(', ') : '-'}`); if (!args.docOnly && normalized.change) { console.log(`change version: ${normalized.change.version}`); } if (args.dryRun) { console.log('dry-run: validated successfully, no files were written.'); return; } writeJsonFile(normalized.docPath, docNext, docState.indent, docState.eol); console.log(`wrote: ${path.relative(ROOT, normalized.docPath)}`); if (!args.docOnly) { writeJsonFile(normalized.changePath, changeNext, changeState.indent, changeState.eol); console.log(`wrote: ${path.relative(ROOT, normalized.changePath)}`); } } if (require.main === module) { try { main(); } catch (error) { console.error(error.message || error); process.exitCode = 1; } } module.exports = { applyDocUpdate, parseArgs, validateSpec, };