WMS_MAIN/script/update-api-doc.cjs

416 lines
14 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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=<path> 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> Path to the fixed update spec JSON file.',
' --dry-run Validate and print the planned changes without writing files.',
' --doc-only Update methods/<docName>.json only and skip methods/changes/<docName>.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,
};