create-react-admin-template 0.0.0-stage → 0.1.0

package/template/tools/openapi/templates/default/procedure-call.eta

@@ -0,0 +1,99 @@
+<%
+const { utils, route, config } = it;
+const { requestBodyInfo, responseBodyInfo, specificArgNameResolver } = route;
+const { _, getInlineParseContent, getParseContent, parseSchema, getComponentByRef, require } = utils;
+const { parameters, path, method, payload, query, formData, security, requestParams } = route.request;
+const { type, errorType, contentTypes } = route.response;
+const { HTTP_CLIENT, RESERVED_REQ_PARAMS_ARG_NAMES } = config.constants;
+const routeDocs = includeFile("./route-docs", { config, route, utils });
+const queryName = (query && query.name) || "query";
+const pathParams = _.values(parameters);
+const pathParamsNames = _.map(pathParams, "name");
+
+const isFetchTemplate = config.httpClientType === HTTP_CLIENT.FETCH;
+
+const requestConfigParam = {
+    name: specificArgNameResolver.resolve(RESERVED_REQ_PARAMS_ARG_NAMES),
+    optional: true,
+    type: "RequestParams",
+    defaultValue: "{}",
+}
+
+const argToTmpl = ({ name, optional, type, defaultValue }) => `${name}${!defaultValue && optional ? '?' : ''}: ${type}${defaultValue ? ` = ${defaultValue}` : ''}`;
+
+const rawWrapperArgs = config.extractRequestParams ?
+    _.compact([
+        requestParams && {
+          name: pathParams.length ? `{ ${_.join(pathParamsNames, ", ")}, ...${queryName} }` : queryName,
+          optional: false,
+          type: getInlineParseContent(requestParams),
+        },
+        ...(!requestParams ? pathParams : []),
+        payload,
+        requestConfigParam,
+    ]) :
+    _.compact([
+        ...pathParams,
+        query,
+        payload,
+        requestConfigParam,
+    ])
+
+const wrapperArgs = _
+    // Sort by optionality
+    .sortBy(rawWrapperArgs, [o => o.optional])
+    .map(argToTmpl)
+    .join(', ')
+
+// RequestParams["type"]
+const requestContentKind = {
+    "JSON": "ContentType.Json",
+    "URL_ENCODED": "ContentType.UrlEncoded",
+    "FORM_DATA": "ContentType.FormData",
+}
+// RequestParams["format"]
+const responseContentKind = {
+    "JSON": '"json"',
+    "IMAGE": '"blob"',
+    "FORM_DATA": isFetchTemplate ? '"formData"' : '"document"'
+}
+
+const bodyTmpl = _.get(payload, "name") || null;
+const queryTmpl = (query != null && queryName) || null;
+const bodyContentKindTmpl = requestContentKind[requestBodyInfo.contentKind] || null;
+const responseFormatTmpl = responseContentKind[responseBodyInfo.success && responseBodyInfo.success.schema && responseBodyInfo.success.schema.contentKind] || null;
+const securityTmpl = security ? 'true' : null;
+
+const describeReturnType = () => {
+    if (!config.toJS) return "";
+
+    switch(config.httpClientType) {
+        case HTTP_CLIENT.AXIOS: {
+          return `Promise<AxiosResponse<${type}>>`
+        }
+        default: {
+          return `Promise<HttpResponse<${type}, ${errorType}>`
+        }
+    }
+}
+
+%>
+/**
+<%~ routeDocs.description %>
+
+ * <% /* Here you can add some other JSDoc tags */ %>
+
+<%~ routeDocs.lines %>
+
+ */
+<%~ route.routeName.usage %><%~ route.namespace ? ': ' : ' = ' %>(<%~ wrapperArgs %>)<%~ config.toJS ? `: ${describeReturnType()}` : "" %> =>
+    <%~ config.singleHttpClient ? 'this.http.request' : 'this.request' %><<%~ type %>, <%~ errorType %>>({
+        path: `<%~ path %>`,
+        method: '<%~ _.upperCase(method) %>',
+        <%~ queryTmpl ? `query: ${queryTmpl},` : '' %>
+        <%~ bodyTmpl ? `body: ${bodyTmpl},` : '' %>
+        <%~ securityTmpl ? `secure: ${securityTmpl},` : '' %>
+        <%~ bodyContentKindTmpl ? `type: ${bodyContentKindTmpl},` : '' %>
+        <%~ responseFormatTmpl ? `format: ${responseFormatTmpl},` : '' %>
+        ...<%~ _.get(requestConfigParam, "name") %>,
+    })<%~ route.namespace ? ',' : '' %>

package/template/tools/openapi/templates/default/route-docs.eta

@@ -0,0 +1,40 @@
+<%
+const { config, route, utils } = it;
+const { _, formatDescription, fmtToJSDocLine, classNameCase, require } = utils;
+const { raw, request, routeName } = route;
+let originalRef = "";
+
+try {
+  originalRef = route.responseBodySchema.content['*/*'].schema.originalRef;
+} catch {}
+
+const jsDocDescription = raw.description ?
+    ` * @description ${formatDescription(raw.description, true)}` :
+    fmtToJSDocLine('No description', { eol: false });
+let jsDocLines = _.compact([
+    _.size(raw.tags) && ` * @tags ${raw.tags.join(", ")}`,
+    ` * @name ${classNameCase(routeName.usage)}`,
+    raw.summary && ` * @summary ${raw.summary}`,
+    ` * @request ${_.upperCase(request.method)}:${raw.route}`,
+    raw.deprecated && ` * @deprecated`,
+    routeName.duplicate && ` * @originalName ${routeName.original}`,
+    routeName.duplicate && ` * @duplicate`,
+    request.security && ` * @secure`,
+    ...(config.generateResponses && raw.responsesTypes.length
+    ? raw.responsesTypes.map(
+        ({ type, status, description, isSuccess }) =>
+            ` * @response \`${status}\` \`${type}\` ${description}`,
+        )
+    : []),    
+]).join("\n");
+
+if (originalRef) {
+    originalRef = originalRef.replace(/«/g, "<").replace(/»/g, ">");
+    jsDocLines += `\n * @type ${originalRef}`
+}
+
+return {
+  description: jsDocDescription,
+  lines: jsDocLines,
+}
+%>

package/template/tools/openapi/templates/default/route-types.eta

@@ -0,0 +1,28 @@
+<%
+const { utils, config, routes, modelTypes } = it;
+const { _, classNameCase } = utils;
+const dataContracts = config.modular ? _.map(modelTypes, "name") : [];
+%>
+
+<% if (dataContracts.length) { %>
+import { <%~ dataContracts.join(", ") %> } from "./<%~ config.fileNames.dataContracts %>"
+<% } %>
+
+<%
+/* TODO: outOfModule, combined should be attributes of route, which will allow to avoid duplication of code */
+%>
+
+<% routes.outOfModule && routes.outOfModule.forEach(({ routes = [] }) => { %>
+    <% routes.forEach((route) => { %>
+        <%~ includeFile('@base/route-type.eta', { ...it, route }) %>
+    <% }) %>
+<% }) %>
+
+<% routes.combined && routes.combined.forEach(({ routes = [], moduleName }) => { %>
+    export namespace <%~ classNameCase(moduleName) %> {
+    <% routes.forEach((route) => { %>
+        <%~ includeFile('@base/route-type.eta', { ...it, route }) %>
+    <% }) %>
+    }
+
+<% }) %>

package/template/tools/openapi/templates/modular/README.md

@@ -0,0 +1,7 @@
+# swagger-typescript-api
+
+# templates/modular
+
+This templates use for multiple api files (`--modular` option)
+
+path prefix `@modular`

package/template/tools/openapi/templates/modular/api.eta

@@ -0,0 +1,28 @@
+<%
+const { utils, route, config, modelTypes } = it;
+const { _, classNameCase, require } = utils;
+const apiClassName = classNameCase(route.moduleName);
+const routes = route.routes;
+const dataContracts = _.map(modelTypes, "name");
+%>
+
+<% if (config.httpClientType === config.constants.HTTP_CLIENT.AXIOS) { %> import { AxiosRequestConfig, AxiosResponse } from "axios"; <% } %>
+
+import { HttpClient, RequestParams, ContentType } from "./<%~ config.fileNames.httpClient %>";
+<% if (dataContracts.length) { %>
+import { <%~ dataContracts.join(", ") %> } from "./<%~ config.fileNames.dataContracts %>"
+<% } %>
+
+export class <%= apiClassName %><SecurityDataType = unknown><% if (!config.singleHttpClient) { %> extends HttpClient<SecurityDataType> <% } %> {
+<% if(config.singleHttpClient) { %>
+  http: HttpClient<SecurityDataType>;
+
+  constructor (http: HttpClient<SecurityDataType>) {
+    this.http = http;
+  }
+<% } %>
+
+    <% routes.forEach((route) => { %>
+        <%~ includeFile('./procedure-call.eta', { ...it, route }) %>
+    <% }) %>
+}

package/template/tools/openapi/templates/modular/procedure-call.eta

@@ -0,0 +1,99 @@
+<%
+const { utils, route, config } = it;
+const { requestBodyInfo, responseBodyInfo, specificArgNameResolver } = route;
+const { _, getInlineParseContent, getParseContent, parseSchema, getComponentByRef, require } = utils;
+const { parameters, path, method, payload, query, formData, security, requestParams } = route.request;
+const { type, errorType, contentTypes } = route.response;
+const { HTTP_CLIENT, RESERVED_REQ_PARAMS_ARG_NAMES } = config.constants;
+const routeDocs = includeFile("@base/route-docs", { config, route, utils });
+const queryName = (query && query.name) || "query";
+const pathParams = _.values(parameters);
+const pathParamsNames = _.map(pathParams, "name");
+
+const isFetchTemplate = config.httpClientType === HTTP_CLIENT.FETCH;
+
+const requestConfigParam = {
+    name: specificArgNameResolver.resolve(RESERVED_REQ_PARAMS_ARG_NAMES),
+    optional: true,
+    type: "RequestParams",
+    defaultValue: "{}",
+}
+
+const argToTmpl = ({ name, optional, type, defaultValue }) => `${name}${!defaultValue && optional ? '?' : ''}: ${type}${defaultValue ? ` = ${defaultValue}` : ''}`;
+
+const rawWrapperArgs = config.extractRequestParams ?
+    _.compact([
+        requestParams && {
+          name: pathParams.length ? `{ ${_.join(pathParamsNames, ", ")}, ...${queryName} }` : queryName,
+          optional: false,
+          type: getInlineParseContent(requestParams),
+        },
+        ...(!requestParams ? pathParams : []),
+        payload,
+        requestConfigParam,
+    ]) :
+    _.compact([
+        ...pathParams,
+        query,
+        payload,
+        requestConfigParam,
+    ])
+
+const wrapperArgs = _
+    // Sort by optionality
+    .sortBy(rawWrapperArgs, [o => o.optional])
+    .map(argToTmpl)
+    .join(', ')
+
+// RequestParams["type"]
+const requestContentKind = {
+    "JSON": "ContentType.Json",
+    "URL_ENCODED": "ContentType.UrlEncoded",
+    "FORM_DATA": "ContentType.FormData",
+}
+// RequestParams["format"]
+const responseContentKind = {
+    "JSON": '"json"',
+    "IMAGE": '"blob"',
+    "FORM_DATA": isFetchTemplate ? '"formData"' : '"document"'
+}
+
+const bodyTmpl = _.get(payload, "name") || null;
+const queryTmpl = (query != null && queryName) || null;
+const bodyContentKindTmpl = requestContentKind[requestBodyInfo.contentKind] || null;
+const responseFormatTmpl = responseContentKind[responseBodyInfo.success && responseBodyInfo.success.schema && responseBodyInfo.success.schema.contentKind] || null;
+const securityTmpl = security ? 'true' : null;
+
+const describeReturnType = () => {
+    if (!config.toJS) return "";
+
+    switch(config.httpClientType) {
+        case HTTP_CLIENT.AXIOS: {
+          return `Promise<AxiosResponse<${type}>>`
+        }
+        default: {
+          return `Promise<HttpResponse<${type}, ${errorType}>`
+        }
+    }
+}
+
+%>
+/**
+<%~ routeDocs.description %>
+
+ * <% /* Here you can add some other JSDoc tags */ %>
+
+<%~ routeDocs.lines %>
+
+ */
+<%~ route.routeName.usage %> = (<%~ wrapperArgs %>)<%~ config.toJS ? `: ${describeReturnType()}` : "" %> =>
+    <%~ config.singleHttpClient ? 'this.http.request' : 'this.request' %><<%~ type %>, <%~ errorType %>>({
+        path: `<%~ path %>`,
+        method: '<%~ _.upperCase(method) %>',
+        <%~ queryTmpl ? `query: ${queryTmpl},` : '' %>
+        <%~ bodyTmpl ? `body: ${bodyTmpl},` : '' %>
+        <%~ securityTmpl ? `secure: ${securityTmpl},` : '' %>
+        <%~ bodyContentKindTmpl ? `type: ${bodyContentKindTmpl},` : '' %>
+        <%~ responseFormatTmpl ? `format: ${responseFormatTmpl},` : '' %>
+        ...<%~ _.get(requestConfigParam, "name") %>,
+    })

package/template/tools/openapi/templates/modular/route-types.eta

@@ -0,0 +1,18 @@
+<%
+const { utils, config, route, modelTypes } = it;
+const { _, classNameCase } = utils;
+const { routes, moduleName } = route;
+const dataContracts = config.modular ? _.map(modelTypes, "name") : [];
+
+%>
+<% if (dataContracts.length) { %>
+import { <%~ dataContracts.join(", ") %> } from "./<%~ config.fileNames.dataContracts %>"
+<% } %>
+
+export namespace <%~ classNameCase(moduleName) %> {
+    <% _.forEach(routes, (route) => { %>
+
+        <%~ includeFile('@base/route-type.eta', { ...it, route }) %>
+
+    <% }) %>
+}

package/template/tools/release/artifact.mjs

@@ -0,0 +1,258 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const strScriptPath = fileURLToPath(import.meta.url)
+const strDefaultProjectRoot = path.resolve(path.dirname(strScriptPath), '../..')
+const strRuntimeConfigFile = 'runtime-config.json'
+const strViteManifestFile = '.vite/manifest.json'
+
+const fnHashBuffer = (objValue) =>
+  createHash('sha256').update(objValue).digest('hex')
+
+const fnResolveCommit = (strProjectRoot) => {
+  const strEnvironmentCommit =
+    process.env.CI_COMMIT_SHA?.trim() ?? process.env.GIT_COMMIT_SHA?.trim()
+  if (strEnvironmentCommit) return strEnvironmentCommit
+
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: strProjectRoot,
+      encoding: 'utf8',
+    }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+const fnListFiles = async (strDirectory, strRelativeDirectory = '') => {
+  const arrEntries = await readdir(
+    path.resolve(strDirectory, strRelativeDirectory),
+    { withFileTypes: true }
+  )
+  const arrFiles = []
+
+  for (const objEntry of arrEntries.sort((objLeft, objRight) =>
+    objLeft.name.localeCompare(objRight.name, 'en')
+  )) {
+    const strRelativePath = path.posix.join(
+      strRelativeDirectory.split(path.sep).join(path.posix.sep),
+      objEntry.name
+    )
+    if (objEntry.isDirectory()) {
+      arrFiles.push(...(await fnListFiles(strDirectory, strRelativePath)))
+    } else if (objEntry.isFile()) {
+      arrFiles.push(strRelativePath)
+    } else {
+      throw new TypeError(
+        `发布产物不允许符号链接或特殊文件：${strRelativePath}`
+      )
+    }
+  }
+
+  return arrFiles
+}
+
+const fnReadMetadata = async (strMetadataPath) => {
+  const objMetadata = JSON.parse(await readFile(strMetadataPath, 'utf8'))
+  if (
+    objMetadata.nSchemaVersion !== 1 ||
+    typeof objMetadata.strCommit !== 'string' ||
+    typeof objMetadata.strManifestSha256 !== 'string' ||
+    objMetadata.strRuntimeConfig !== 'external' ||
+    typeof objMetadata.strVersion !== 'string'
+  ) {
+    throw new TypeError('artifact-metadata.json 不符合发布产物契约。')
+  }
+  return objMetadata
+}
+
+const fnParseManifest = (strManifest) => {
+  const arrEntries = strManifest
+    .split('\n')
+    .filter(Boolean)
+    .map((strLine) => {
+      const objMatch = /^([a-f0-9]{64}) {2}(.+)$/.exec(strLine)
+      if (!objMatch) throw new TypeError('产物校验清单格式无效。')
+      const [, strSha256, strRelativePath] = objMatch
+      if (
+        strRelativePath === strRuntimeConfigFile ||
+        path.posix.isAbsolute(strRelativePath) ||
+        strRelativePath.split('/').includes('..')
+      ) {
+        throw new TypeError(`产物校验清单包含非法路径：${strRelativePath}`)
+      }
+      return { strRelativePath, strSha256 }
+    })
+
+  if (
+    new Set(arrEntries.map((objEntry) => objEntry.strRelativePath)).size !==
+    arrEntries.length
+  ) {
+    throw new TypeError('产物校验清单包含重复路径。')
+  }
+  return arrEntries
+}
+
+/** 从已通过质量门禁的 dist 创建不包含环境运行时配置的发布产物。 */
+export async function fnPrepareReleaseArtifact({
+  strProjectRoot = strDefaultProjectRoot,
+  strCommit = fnResolveCommit(strProjectRoot),
+} = {}) {
+  const strDistRoot = path.resolve(strProjectRoot, 'dist')
+  const strReleaseRoot = path.resolve(strProjectRoot, '.artifacts/release')
+  const strSiteRoot = path.resolve(strReleaseRoot, 'site')
+  const objPackage = JSON.parse(
+    await readFile(path.resolve(strProjectRoot, 'package.json'), 'utf8')
+  )
+  const arrDistFiles = await fnListFiles(strDistRoot)
+
+  if (!arrDistFiles.includes('index.html')) {
+    throw new TypeError('dist/index.html 不存在，请先执行 pnpm verify。')
+  }
+
+  await rm(strReleaseRoot, { force: true, recursive: true })
+  await mkdir(strSiteRoot, { recursive: true })
+
+  const arrManifestEntries = []
+  for (const strRelativePath of arrDistFiles) {
+    if (
+      strRelativePath === strRuntimeConfigFile ||
+      strRelativePath === strViteManifestFile
+    ) {
+      continue
+    }
+    const strSourcePath = path.resolve(strDistRoot, strRelativePath)
+    const strDestinationPath = path.resolve(strSiteRoot, strRelativePath)
+    const objContents = await readFile(strSourcePath)
+    await mkdir(path.dirname(strDestinationPath), { recursive: true })
+    await copyFile(strSourcePath, strDestinationPath)
+    arrManifestEntries.push({
+      strRelativePath,
+      strSha256: fnHashBuffer(objContents),
+    })
+  }
+
+  const strManifest = `${arrManifestEntries
+    .map((objEntry) => `${objEntry.strSha256}  ${objEntry.strRelativePath}`)
+    .join('\n')}\n`
+  const objMetadata = {
+    nSchemaVersion: 1,
+    strCommit,
+    strManifestSha256: fnHashBuffer(strManifest),
+    strRuntimeConfig: 'external',
+    strVersion: String(objPackage.version),
+  }
+
+  await Promise.all([
+    writeFile(
+      path.resolve(strReleaseRoot, 'artifact-manifest.sha256'),
+      strManifest,
+      'utf8'
+    ),
+    writeFile(
+      path.resolve(strReleaseRoot, 'artifact-metadata.json'),
+      `${JSON.stringify(objMetadata, null, 2)}\n`,
+      'utf8'
+    ),
+  ])
+
+  return objMetadata
+}
+
+/** 校验发布目录没有缺失、篡改、额外文件或提交身份漂移。 */
+export async function fnVerifyReleaseArtifact({
+  strExpectedCommit,
+  strProjectRoot = strDefaultProjectRoot,
+} = {}) {
+  const strReleaseRoot = path.resolve(strProjectRoot, '.artifacts/release')
+  const strSiteRoot = path.resolve(strReleaseRoot, 'site')
+  const [strManifest, objMetadata, arrSiteFiles] = await Promise.all([
+    readFile(path.resolve(strReleaseRoot, 'artifact-manifest.sha256'), 'utf8'),
+    fnReadMetadata(path.resolve(strReleaseRoot, 'artifact-metadata.json')),
+    fnListFiles(strSiteRoot),
+  ])
+  const arrManifestEntries = fnParseManifest(strManifest)
+  const arrManifestFiles = arrManifestEntries.map(
+    (objEntry) => objEntry.strRelativePath
+  )
+
+  if (fnHashBuffer(strManifest) !== objMetadata.strManifestSha256) {
+    throw new TypeError('发布产物清单摘要与元数据不一致。')
+  }
+  if (strExpectedCommit && objMetadata.strCommit !== strExpectedCommit) {
+    throw new TypeError('发布产物提交身份与当前流水线不一致。')
+  }
+  if (JSON.stringify(arrSiteFiles) !== JSON.stringify(arrManifestFiles)) {
+    throw new TypeError('发布目录与校验清单的文件集合不一致。')
+  }
+
+  for (const objEntry of arrManifestEntries) {
+    const objContents = await readFile(
+      path.resolve(strSiteRoot, objEntry.strRelativePath)
+    )
+    if (fnHashBuffer(objContents) !== objEntry.strSha256) {
+      throw new TypeError(`发布文件摘要不一致：${objEntry.strRelativePath}`)
+    }
+  }
+
+  return objMetadata
+}
+
+const fnReadArgument = (strName) => {
+  const nIndex = process.argv.indexOf(`--${strName}`)
+  return nIndex >= 0 ? process.argv[nIndex + 1] : undefined
+}
+
+const fnRunCli = async () => {
+  const strCommand = process.argv[2]
+  if (strCommand === 'prepare') {
+    if (process.argv.length > 3) {
+      throw new TypeError('prepare 子命令不接受其他参数。')
+    }
+    const objMetadata = await fnPrepareReleaseArtifact()
+    process.stdout.write(
+      `发布产物已准备：${objMetadata.strCommit} / v${objMetadata.strVersion}\n`
+    )
+    return
+  }
+  if (strCommand === 'verify') {
+    const arrArguments = process.argv.slice(3)
+    if (
+      arrArguments.length > 0 &&
+      (arrArguments.length !== 2 ||
+        arrArguments[0] !== '--commit' ||
+        !arrArguments[1])
+    ) {
+      throw new TypeError('verify 只接受可选的 --commit <sha> 参数。')
+    }
+    const objMetadata = await fnVerifyReleaseArtifact({
+      strExpectedCommit: fnReadArgument('commit'),
+    })
+    process.stdout.write(
+      `发布产物校验通过：${objMetadata.strCommit} / v${objMetadata.strVersion}\n`
+    )
+    return
+  }
+  throw new TypeError('请使用 prepare 或 verify 子命令。')
+}
+
+if (path.resolve(process.argv[1] ?? '') === strScriptPath) {
+  try {
+    await fnRunCli()
+  } catch (objError) {
+    const strMessage =
+      objError instanceof Error ? objError.message : '发生未知发布产物错误。'
+    process.stderr.write(`[RELEASE_ARTIFACT_INVALID] ${strMessage}\n`)
+    process.exitCode = 1
+  }
+}