@diplodoc/cli 4.15.1 → 4.16.1

package/package.json

@@ -3,7 +3,7 @@
   "author": "Yandex Data UI Team <data-ui@yandex-team.ru>",
   "description": "Make documentation using yfm-docs in Markdown and HTML formats",
   "license": "MIT",
-  "version": "4.15.1",
+  "version": "4.16.1",
   "repository": {
     "type": "git",
     "url": "git@github.com:diplodoc-platform/cli.git"
@@ -15,6 +15,7 @@
   "files": [
     "build",
     "assets",
+    "schemas",
     "src"
   ],
   "scripts": {
@@ -62,13 +63,13 @@
     "ajv": "^8.11.0",
     "async": "^3.2.4",
     "axios": "^1.6.7",
-    "chalk": "4.1.2",
+    "chalk": "^4.1.2",
     "esbuild": "^0.20.0",
     "glob": "^8.0.3",
     "html-escaper": "^3.0.3",
     "husky": "8.0.3",
     "js-yaml": "4.1.0",
-    "lint-staged": "13.2.2",
+    "lint-staged": "^12.5.0",
     "lodash": "4.17.21",
     "mime-types": "2.1.35",
     "minimatch": "^9.0.3",

package/schemas/leading-schema.yaml

@@ -0,0 +1,56 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+$id: 'https://diplodoc.com/schemas/leading/draft-01/schema#'
+title: Leading page file schema
+type: object
+properties:
+  title:
+    $ref: '#/definitions/TextItems'
+
+  description:
+    $ref: '#/definitions/TextItems'
+
+  meta:
+    type: object
+    properties:
+      title:
+        $ref: '#/definitions/TextItems'
+      description:
+        $ref: '#/definitions/TextItems'
+      noIndex:
+        type: boolean
+    additionalProperties: false
+
+  nav:
+    type: object
+    properties:
+      title:
+        $ref: '#/definitions/TextItems'
+    additionalProperties: false
+
+  links:
+    type: array
+    items:
+      type: object
+      properties:
+        title:
+          type: string
+          translate: md
+        description:
+          type: string
+          translate: md
+        href:
+          type: string
+          format: url
+      additionalProperties: false
+
+additionalProperties: false
+
+definitions:
+  TextItems:
+    oneOf:
+      - type: string
+      - type: array
+        items:
+          type: string
+          translate: md
+

package/schemas/presets-schema.yaml

@@ -0,0 +1,31 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+$id: 'https://diplodoc.com/schemas/presets/draft-01/schema#'
+title: Presets file schema
+type: object
+properties:
+  default:
+    $ref: '#/definitions/preset'
+patternProperties:
+  '^[a-zA-Z0-9\.\-_]+$':
+    $ref: '#/definitions/preset'
+
+definitions:
+  preset:
+    type: object
+    properties:
+      i18n:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            $ref: '#/definitions/property'
+    additionalProperties: true
+
+  property:
+    oneOf:
+      - type: string
+        translate: md
+      - type: number
+      - type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            $ref: '#/definitions/property'

package/schemas/toc-schema.yaml

@@ -0,0 +1,302 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+$id: 'https://diplodoc.com/schemas/toc/draft-01/schema#'
+title: Table of content file schema
+type: object
+properties:
+  title:
+    type: string
+    translate: md
+  href:
+    type: string
+    format: url
+  stage:
+    type: string
+  base:
+    type: string
+  singlePage:
+    type: boolean
+  when:
+    type:
+      - string
+      - boolean
+  navigation:
+    $ref: '#/definitions/Navigation'
+  items:
+    $ref: '#/definitions/TocItems'
+
+definitions:
+  TocItems:
+    type: array
+    items:
+      $ref: '#/definitions/TocItem'
+
+  TocItem:
+    type: object
+    properties:
+      name:
+        type: string
+        translate: md
+      expanded:
+        type: boolean
+      hidden:
+        type:
+          - boolean
+          - string
+      items:
+        $ref: '#/definitions/TocItems'
+    oneOf:
+      - $ref: '#/definitions/TocItemWithLink'
+      - $ref: '#/definitions/TocItemWithInclude'
+
+  TocItemWithLink:
+    required: ['name']
+    properties:
+      name:
+        type: string
+        translate: md
+      href:
+        type: string
+
+  TocItemWithInclude:
+    required: ['include']
+    properties:
+      name:
+        type: string
+        translate: md
+      include:
+        $ref: '#/definitions/Include'
+
+  Include:
+    type: object
+    properties:
+      mode:
+        type: string
+        enum: ['link', 'merge', 'root_merge']
+      path:
+        type: string
+      includers:
+        type: array
+        items:
+          $ref: '#/definitions/Includer'
+    additionalProperties: false
+
+  Includer:
+    type: object
+    required: ['name']
+    properties:
+      name:
+        type: string
+    additionalProperties: true
+
+  OpenApiIncluder:
+    type: object
+    required: ['input']
+    properties:
+      input:
+        type: string
+      filter:
+        $ref: '#/definitions/OpenApiIncluderFilter'
+      noindex:
+        $ref: '#/definitions/OpenApiIncluderFilter'
+      hidden:
+        $ref: '#/definitions/OpenApiIncluderFilter'
+      sandbox:
+        type: object
+        properties:
+          tabName:
+            type: string
+            translate: text
+          host:
+            type: string
+            format: url
+      leadingPage:
+        type: object
+        properties:
+          name:
+            type: string
+          mode:
+            type: string
+            enum: ['section', 'leaf']
+          spec:
+            type: object
+            properties:
+              renderMode:
+                type: string
+                enum: ['inline', 'hidden']
+
+  OpenApiIncluderFilter:
+    type: object
+    properties:
+      endpoint:
+        type: string
+      tag:
+        type: string
+
+  Navigation:
+    type: object
+    properties:
+      logo:
+        $ref: '#/definitions/NavigationLogo'
+      header:
+        $ref: '#/definitions/NavigationHeader'
+
+  NavigationLogo:
+    type: object
+    properties:
+      text:
+        type: string
+      url:
+        type: string
+        format: url
+      urlTitle:
+        type: string
+      icon:
+        type: string
+        format: url
+      dark:
+        $ref: '#/definitions/NavigationLogo'
+      light:
+        $ref: '#/definitions/NavigationLogo'
+
+  NavigationHeader:
+    type: object
+    properties:
+      leftItems:
+        $ref: '#/definitions/NavigationItems'
+      rightItems:
+        $ref: '#/definitions/NavigationItems'
+      iconSize:
+        type: number
+
+  NavigationItems:
+    type: array
+    items:
+      $ref: '#/definitions/NavigationItem'
+
+  NavigationItem:
+    type: object
+    required: ['type']
+    properties:
+      type:
+        type: string
+    allOf:
+      - $ref: '#/definitions/NavigationBaseItem'
+      - oneOf:
+        - $ref: '#/definitions/NavigationLinkItem'
+        - $ref: '#/definitions/NavigationButtonItem'
+        - $ref: '#/definitions/NavigationDropdownItem'
+        - $ref: '#/definitions/NavigationControlsItem'
+
+  NavigationBaseItem:
+    type: object
+    properties:
+      text:
+        type: string
+        translate: md
+      url:
+        type: string
+        format: url
+      icon:
+        type: string
+        format: url
+      iconSize:
+        type: number
+
+  NavigationLinkItem:
+    type: object
+    properties:
+      type:
+        type: string
+        pattern: '^link$'
+      target:
+        $ref: '#/definitions/NavigationLinkTarget'
+      arrow:
+        type: boolean
+    required: ['type', 'text']
+
+  NavigationButtonItem:
+    properties:
+      type:
+        type: string
+        pattern: '^button$'
+      urlTitle:
+        type: string
+        translate: md
+      primary:
+        type: boolean
+      size:
+        type: string
+      theme:
+        type: string
+      img:
+        oneOf:
+          - type: string
+          - type: object
+            required: ['data']
+            properties:
+              data:
+                type: string
+              position:
+                type: string
+                enum: ['left', 'right']
+              alt:
+                type: string
+                translate: md
+      analyticsEvents:
+        oneOf:
+          - $ref: '#/definitions/NavigationAnalyticsEvent'
+          - type: array
+            items:
+              $ref: '#/definitions/NavigationAnalyticsEvent'
+      target:
+        $ref: '#/definitions/NavigationLinkTarget'
+      width:
+        type: string
+        enum: ['auto', 'max']
+    required: ['type', 'text', 'url']
+
+  NavigationDropdownItem:
+    type: object
+    properties:
+      type:
+        type: string
+        pattern: '^dropdown$'
+      items:
+        type: array
+        items:
+          $ref: '#/definitions/NavigationLinkItem'
+    required: ['type', 'items']
+
+  NavigationControlsItem:
+    type: object
+    properties:
+      type:
+        type: string
+        pattern: '^controls$'
+    required: ['type']
+
+  NavigationLinkTarget:
+    type: string
+    enum: ['_self', '_blank', '_parent', '_top']
+
+  NavigationAnalyticsEvent:
+    type: object
+    required: ['name']
+    properties:
+      name:
+        type: string
+      type:
+        type: string
+      counters:
+        type: object
+        properties:
+          include:
+            type: array
+            items:
+              type: string
+          exclude:
+            type: array
+            items:
+              type: string
+      context:
+        type: string

package/src/cmd/translate/compose.ts

@@ -100,15 +100,7 @@ function pipeline(input: string, output: string, {useSource}: ComposeOptions) {
             loadFile<string>(join(input, file.xliff)),
         ]);
 
-        let schemas;
-        if (['.yaml', '.json'].includes(file.ext)) {
-            schemas = resolveSchemas(file.path);
-
-            if (!schemas) {
-                return;
-            }
-        }
-
+        const schemas = await resolveSchemas(file.path);
         const result = _compose(skeleton, xliff, {useSource, schemas});
         const filePath = join(output, file.path);
 

package/src/cmd/translate/extract.ts

@@ -121,24 +121,21 @@ function pipeline(params: PipelineParameters) {
         const xliffPath = join(outputRoot, outputPath + '.xliff');
         const skeletonPath = join(outputRoot, outputPath + '.skl');
 
-        let schemas;
-        if (['.yaml', '.json'].includes(ext)) {
-            schemas = resolveSchemas(path);
-
-            if (!schemas) {
-                return;
-            }
-        }
-
+        const schemas = await resolveSchemas(path);
         const content = await loadFile(inputPath);
 
         await mkdir(dirname(xliffPath), {recursive: true});
 
-        const {xliff, skeleton} = _extract(content, {
+        const {xliff, skeleton, units} = _extract(content, {
             source,
             target,
+            schemas,
         });
 
+        if (!units.length) {
+            return;
+        }
+
         await Promise.all([dumpFile(skeletonPath, skeleton), dumpFile(xliffPath, xliff)]);
     };
 }

package/src/cmd/translate/handler.ts

@@ -22,6 +22,7 @@ import {
     extract,
     loadFile,
     normalizeParams,
+    resolveSchemas,
 } from './utils';
 
 const REQUESTS_LIMIT = 20;
@@ -262,6 +263,7 @@ function translator(params: TranslatorParams, split: Split) {
             return;
         }
 
+        const schemas = await resolveSchemas(path);
         const {units, skeleton} = extract(content, {
             compact: true,
             source: {
@@ -272,6 +274,7 @@ function translator(params: TranslatorParams, split: Split) {
                 language: targetLanguage,
                 locale: 'US',
             },
+            schemas,
         });
 
         if (!units.length) {
@@ -280,7 +283,7 @@ function translator(params: TranslatorParams, split: Split) {
         }
 
         const parts = await split(path, units);
-        const composed = compose(skeleton, parts, {useSource: true});
+        const composed = compose(skeleton, parts, {useSource: true, schemas});
 
         await dumpFile(outputPath, composed);
     };

package/src/cmd/translate/utils/fs.ts

@@ -1,17 +1,30 @@
 import {JSONValue, resolveRefs} from '@diplodoc/translation';
-import {extname} from 'path';
 import {dump, load} from 'js-yaml';
 import {readFile, writeFile} from 'fs/promises';
 
+function last<T>(array: T[]): T | undefined {
+    return array[array.length - 1];
+}
+
+function ext(path: string) {
+    const parts = path.split('.');
+
+    if (last(parts) === 'skl') {
+        parts.pop();
+    }
+
+    return last(parts);
+}
+
 function parseFile(text: string, path: string): JSONValue | string {
     if (typeof text !== 'string') {
         return text;
     }
 
-    switch (extname(path)) {
-        case '.yaml':
+    switch (ext(path)) {
+        case 'yaml':
             return load(text) as object;
-        case '.json':
+        case 'json':
             return JSON.parse(text);
         default:
             return text;
@@ -23,22 +36,22 @@ function stringifyFile(content: JSONValue | string, path: string): string {
         return content;
     }
 
-    switch (extname(path)) {
-        case '.yaml':
+    switch (ext(path)) {
+        case 'yaml':
             return dump(content);
-        case '.json':
+        case 'json':
             return JSON.stringify(content);
         default:
             return content as unknown as string;
     }
 }
 
-export async function loadFile<T = string | JSONValue>(path: string): Promise<T> {
+export async function loadFile<T = string | JSONValue>(path: string, resolve = true): Promise<T> {
     const text = await readFile(path, 'utf8');
 
     let content = parseFile(text, path);
 
-    if (content && typeof content === 'object') {
+    if (content && typeof content === 'object' && resolve) {
         content = await resolveRefs(content, path, parseFile);
     }
 
@@ -50,3 +63,27 @@ export async function dumpFile(path: string, content: string | JSONValue) {
 
     await writeFile(path, text, 'utf8');
 }
+
+/**
+ * Takes toc schema if file matched as toc.
+ * Takes leading schema if file matched as leading page.
+ * Takes presets schema if file matched as presets.
+ * Any way translation inner logic will search `$schema` attribute with high priority.
+ * If `$schema` attribute not found anc precise schema not resolved,
+ * we think that current yaml is a part of complex toc.yaml
+ */
+export async function resolveSchemas(path: string) {
+    if (path.endsWith('toc.yaml')) {
+        return [await loadFile('schemas/toc-schema.yaml', false)];
+    }
+
+    if (path.endsWith('index.yaml')) {
+        return [await loadFile('schemas/leading-schema.yaml', false)];
+    }
+
+    if (path.endsWith('presets.yaml')) {
+        return [await loadFile('schemas/presets-schema.yaml', false)];
+    }
+
+    return [await loadFile('schemas/toc-schema.yaml', false)];
+}

package/src/cmd/translate/utils/index.ts

@@ -3,7 +3,7 @@ import {basename, dirname, extname, resolve} from 'path';
 import {readFileSync} from 'node:fs';
 import glob from 'glob';
 
-export {dumpFile, loadFile} from './fs';
+export {dumpFile, loadFile, resolveSchemas} from './fs';
 export {extract, compose} from './translate';
 export {TranslateError, LimitExceed, RequestError, AuthError} from './errors';
 
@@ -138,10 +138,6 @@ function normalizeInput(params: TranslateArgs, language: string, exts: string[])
     return {input, files};
 }
 
-export function resolveSchemas(_path: string) {
-    return null;
-}
-
 export class Defer<T = string> {
     resolve!: (text: T) => void;