feat: add validator radar document (#16)

* feat: add validator radar document and alias to .csv files

package.json

@@ -25,6 +25,7 @@
  "eslint-config-qiwi": "^1.13.1",
  "jest": "^27.0.4",
  "jest-esm-transformer": "^1.0.0",
+ "jsdoc": "^3.6.7",
  "prettier": "^2.3.1",
  "prettier-config-qiwi": "^1.4.1",
  "terser": "^5.3.7",
@@ -36,7 +37,9 @@
  },
  "dependencies": {
  "@11ty/eleventy": "^0.12.1",
+ "ajv": "^8.6.0",
  "csv-parse": "^4.12.0",
+ "find-cache-dir": "^3.3.1",
  "fs-extra": "^10.0.0",
  "globby": "^11.0.4",
  "html-minifier": "^4.0.0",

radar data/tech-radar-ios.csv

@@ -0,0 +1,84 @@
+title
+QIWI iOS Tech Radar
+===
+date
+21-06-2021
+===
+name,quadrant,ring,description
+Дизайн-система,tech,adopt,
+Модульная архитектура,tech,adopt,
+Continuous delivery,tech,adopt,"Каждый спринт отправляем сборки в стор, с помощью teamcity и прохождения автоматических автотестов"
+Continuous integration,tech,adopt,"Каждый пулл реквест проверяется автоматическими чеками: swiftLint, unit tests, smoke ui tests"
+MVVM,tech,adopt,Паттерн проектирования
+REST,tech,adopt,REST (от англ. Representational State Transfer — «передача состояния представления») — архитектурный стиль взаимодействия компонентов распределённого приложения в сети.
+SOA,tech,adopt,Service-oriented architecture
+SOLID,tech,adopt,Мнемонический акроним для 5 основных принципов объектно-ориентированного программирования и проектирования.
+UI tests,tech,adopt,Каждая фича покрывается UI тестами
+Unit tests,tech,adopt,Каждая фича покрывается unit тестами
+GraphQL,tech,ASSESS,A query language for APIs and a runtime for fulfilling those queries with your existing data
+Redux,tech,ASSESS,Архитектурный паттерн
+Composable architecture,tech,HOLD,Архитектурный паттерн
+Appium,Tools,ADOPT,Tool for automation UI tests
+Confluence,Tools,ADOPT,Wiki
+Fastlane,Tools,ADOPT,"Тул для автоматизации CI/CD и других штук, которые гоняем в Team City"
+Figma,Tools,ADOPT,"В ней дизайнеры накидыват интерфейсы, а мы затаскиваем их к себе в проект"
+Github,Tools,ADOPT,Система контроля версий исползуемая в основном frontend'ового кода.
+Intellij idea,Tools,ADOPT,IDE для разработки на Java/Kotlin
+Jira,Tools,ADOPT,Bug tracker
+Kaiten,Tools,ADOPT,Система управления задачами
+Kibana,Tools,ADOPT,Визуализация логов
+SwiftLint,Tools,ADOPT,Linter for Swift code
+Tableau,Tools,ADOPT,Решение для построения дашбордов
+TeamCity,Tools,ADOPT,Сервер для CI/CD
+TestFlight,Tools,ADOPT,Share test builds for testers
+Xcode,Tools,ADOPT,IDE для разработки под iOS
+Grafana,Tools,TRIAL,Решение для построения дашбордов и мониторинга
+Zeplin,Tools,HOLD,"An organized workspace to publish designs, where the entire team can collaborate"
+Firebase Crashlytics,Platforms,ADOPT,Креш трекер
+Firebase Remote Config,Platforms,ADOPT,"С его помощью делаем фича флаги, раскатываем фичи и проводим A/B тесты"
+Google Maps,Platforms,ADOPT,Карта терминалов
+Goluber,Platforms,TRIAL,лоток для логов
+Yandex AppMetrica,Platforms,TRIAL,Analytics framework
+CHIPageControl,Language,ADOPT,A set of cool animated page controls to replace boring UIPageControl
+DeviceKit,Language,ADOPT,DeviceKit is a value-type replacement of UIDevice
+FormattableTextView,Language,ADOPT,A framework which allows you to format user input according to your mask
+InAppProvisioningUtils,Language,ADOPT,Библиотека для работы с Apple Pay в приложении.
+KeychainAccess,Language,ADOPT,Keychain framework
+Kingfisher,Language,ADOPT,"A powerful, pure-Swift library for downloading and caching images from the web"
+MaterialTextView,Language,ADOPT,Реализация текстовых полей по Material Design
+Python,Language,ADOPT,Язык программирования
+QiwiButtons,Language,ADOPT,Customizable buttons for iOS apps.
+SnapKit,Language,ADOPT,DSL to make Auto Layout easy on iOS
+SnapshotTesting,Language,ADOPT,Delightful Swift snapshot testing.
+Swagger,Language,ADOPT,Фреймворк описания API
+Swift,Language,ADOPT,Язык программирования
+Swift PM,Language,ADOPT,Менеджер зависимостей
+Edna,Language,TRIAL,Фрейморк для чата с пользователями
+Kotlin Multiplatform,Language,TRIAL,"Повзоляет писать общий код логики для iOS, Android, JS на едином стеке Kotlin, но пока вдоступна только alfa-версия. На проде одна фича на платформе Android (поиск elasticsearch), в процессе оптимизация под iOs"
+SwagGen,Language,TRIAL,OpenAPI/Swagger 3.0 Parser and Swift code generator
+XCTAssertNoLeak,Language,TRIAL,Фреймворк для обнаружения утечек памяти
+Alamofire,Language,ASSESS,An HTTP networking library written in Swift
+Apollo GraphQL,Language,ASSESS,GraphQL framework for Swift
+MetricKit,Language,ASSESS,"A framework which aggregates and analyzes per-device reports on exception and crash diagnostics, and on power and performance metrics."
+ReactiveCocoa,Language,ASSESS,Фрейморк для реактивного программирования
+SwiftUI,Language,ASSESS,UI framework
+Swinject,Language,ASSESS,A lightweight dependency injection framework for Swift
+Adjust,Language,HOLD,Marketing analytics framework
+AFNetworking,Language,HOLD,Network layer framework
+Carthage,Language,HOLD,Менеджер зависимостей
+CocoaPods,Language,HOLD,Менеджер зависимостей
+Combine,Language,HOLD,Reactive framework от Apple
+Dwifft,Language,HOLD,"""A small Swift library that tells you what the """"diff"""" is between two collections"""
+MBProgressHUD,Language,HOLD,Индикатор загрузки
+Objective-C,Language,HOLD,Язык программирования
+ReactiveObjc,Language,HOLD,Objective-C фрейморк для реактивного программирования
+RxSwift,Language,HOLD,Swift фрейморк для реактивного программирования
+SDWebImage,Language,HOLD,Async image downloader with cache support
+SwipeCellKit,Language,HOLD,"Swipeable UITableViewCell/UICollectionViewCell based on the stock Mail.app, implemented in Swift"
+TTTAttributedLabel,Language,HOLD,"A drop-in replacement for UILabel that supports attributes, data detectors, links, and more"
+Typhoon,Language,HOLD,Dependency Injection framework
+YapDatabase,Language,HOLD,A collection/key/value store.
+===
+quadrant,alias
+languages-and-frameworks,Language
+Techniques,tech

radar data/tech-radar-js.csv

@@ -0,0 +1,33 @@
+title
+QIWI JS Tech Radar
+===
+date
+21-06-2021
+===
+name,quadrant,ring,description
+TypeScript,languages-and-frameworks,Adopt,Статически типизированный ЖС
+JavaScript,languages-and-frameworks,Adopt,ЖС
+Flow,languages-and-frameworks,Hold,Статически типизированный ЖС
+Nestjs,languages-and-frameworks,Trial,Spring для TS
+React,languages-and-frameworks,Adopt,
+Redux,languages-and-frameworks,Adopt,Стейт-менеджмент провайдер
+Rematch,languages-and-frameworks,Trial,Shortcut-flow абстракция над redux
+lodash,languages-and-frameworks,Adopt,Стандартаная библиотека
+express,languages-and-frameworks,Hold,Мидвары поверх http-server
+emotion,languages-and-frameworks,Trial,CSS in JS
+jest,languages-and-frameworks,Adopt,Фреймворк для unit автотестов
+cypress,languages-and-frameworks,Assess,Фреймворк для e2e тестов
+Nodejs,Platforms,Adopt,
+Kuber,Platforms,Adopt,
+Pijma,Platforms,Trial,
+Yarn,Tools,Adopt,Пакетный менеджер вместо npm
+semantic-relese,Tools,Trial,"Движение к CD, чтобы катать семантические релизы"
+Travis-ci,Tools,Trial,CI для OSS
+eslint,Tools,Trial,"Перекатываемся, tslint deprecated скоро"
+flp,Tools,Assess,Провайдер клиентских событий
+mocha,Tools,Hold,Либа для автотестов
+codeclimate,Tools,Trial,Статический анализатор кода
+Monorepo,Techniques,Trial,Обобщение кодовой базы на уровне домена продукта
+Trunk-based Development,Techniques,Adopt,Фиче-флаги вместо фич-бранчей
+Гексагональная архитектура,Techniques,Assess,Унификации контракта интерфейсов различных слоев приложений
+OSS,Techniques,Trial,Публичная разработка

src/main/js/11ty/.eleventy.cjs

@@ -5,8 +5,8 @@ const terser = require('terser')
 
 module.exports = (config) => {
  const pathPrefix = process.env.PATHPREFIX
- const tempDir = global._11ty_.temp
- const assetsPath = tempDir + '/assets'
+ const {temp, output, title} = global._11ty_
+ const assetsPath = temp + '/assets'
  config.addPassthroughCopy({
  [assetsPath]: '/',
  })
@@ -27,7 +27,7 @@ module.exports = (config) => {
 
  const radarSettings = {
  ...settings,
- title: global._11ty_.title,
+ title,
  entries,
  }
 
@@ -59,8 +59,8 @@ module.exports = (config) => {
 
  return {
  dir: {
- input: tempDir,
- output: global._11ty_.outDir,
+ input: temp,
+ output: output,
  layouts: '_layouts',
  },
  pathPrefix,

src/main/js/constants.js

@@ -5,25 +5,34 @@ export const platforms = 'platforms'
 export const tools = 'tools'
 export const techniques = 'techniques'
 
-export const quadrantAliases = {
- [langAndFw]: langAndFw,
- 'languages-and-framework': langAndFw,
- language: langAndFw,
- lang: langAndFw,
- lf: langAndFw,
- fw: langAndFw,
- framework: langAndFw,
-
- [platforms]: platforms,
- platform: platforms,
- pf: platforms,
-
- [tools]: tools,
- tool: tools,
+export const tplDir = path.resolve('src/main/tpl')
+export const tempDir = 'radar-temp'
 
- [techniques]: techniques,
- tech: techniques,
+export const radarSchema = {
+ type: 'object',
+ properties: {
+ data: {
+ type: 'array',
+ items: {
+ type: 'object',
+ properties: {
+ name: { type: 'string' },
+ quadrant: { type: 'string' },
+ ring: { type: 'string' },
+ description: { type: ['string', 'null'] },
+ moved: { type: ['string', 'integer', 'null'] },
+ },
+ required: ['name', 'quadrant', 'ring', 'description'],
+ },
+ },
+ meta: {
+ type: 'object',
+ properties: {
+ title: { type: 'string' },
+ date: { type: 'string' },
+ legend: { type: ['string', 'null'] },
+ },
+ required: ['title', 'date'],
+ },
+ },
 }
-
-export const tplDir = path.resolve('src/main/tpl')
-export const tempDir = (() => 'temp')() // TODO https://github.com/antongolub/yarn-audit-fix/blob/master/src/main/ts/util.ts#L172

src/main/js/generateMdAssets.js

@@ -1,21 +1,28 @@
+import fs from 'fs'
 import fsExtra from 'fs-extra'
 import path from 'path'
 
-import { quadrantAliases, tplDir } from './constants.js'
+import { tplDir } from './constants.js'
 
+/**
+ * generate path to .md file
+ * @param {string} name
+ * @param {string} quadrant
+ * @param {string} temp - temp directory
+ * @returns {string}
+ */
 export function genMdPath({ name, quadrant, temp }) {
  const entryMdName = name + '.md'
- const quadrantAlias = quadrantAliases[quadrant.toLowerCase()]
-
- if (!quadrantAlias) {
- throw new Error(
- `Parsing error: invalid quadrant - "${quadrant}" name - "${name}"`,
- )
- }
-
- return path.join(temp, '/entries', quadrantAlias, entryMdName)
+ return path.join(temp, '/entries', quadrant, entryMdName)
 }
 
+/**
+ * generate content .md file
+ * @param ring
+ * @param description
+ * @param moved - optional parameter
+ * @returns {string}
+ */
 export function genMdContent({ ring, description, moved }) {
  return `---
 ring: ${ring.toLowerCase()}
@@ -24,16 +31,29 @@ moved: ${moved || 0}
 ${description}`
 }
 
+/**
+ * generate assets .md files from radarDocument to temp directory
+ * @param doc - radarDocument
+ * @param temp - temp directory
+ */
 export const genMdAssets = (doc, temp) => {
  fsExtra.copySync(tplDir, temp)
 
  doc.data.forEach(({ name, quadrant, ring, description, moved }) => {
  try {
- const entryPath = genMdPath({ name, quadrant, temp })
+ const quadrantAlias = getQuadrant(quadrant, doc)
+ const entryPath = genMdPath({ name, quadrant: quadrantAlias, temp })
  const content = genMdContent({ ring, description, moved })
- fsExtra.writeFileSync(entryPath, content)
+ fs.writeFileSync(entryPath, content)
  } catch (err) {
- console.error(err)
+ console.error('genMdAssets', err)
  }
  })
 }
+
+export const getQuadrant = (quadrant, doc) => {
+ if (!('quadrantAliases' in doc)) return quadrant.toLowerCase()
+ return doc.quadrantAliases[quadrant.toLowerCase()]
+ ? doc.quadrantAliases[quadrant.toLowerCase()]
+ : quadrant.toLowerCase()
+}

src/main/js/generateStatic.js

@@ -2,11 +2,22 @@ import Eleventy from '@11ty/eleventy'
 import fsExtra from 'fs-extra'
 import path from 'path'
 
-import { tempDir } from './constants.js'
+import { radarSchema, tempDir } from './constants.js'
 import { genMdAssets } from './generateMdAssets.js'
+import { validate } from './validator.js'
 
+/**
+ * generate static sites from array radarDocument
+ * @param docs
+ * @param dirs
+ * @param _output
+ */
 export const genStatics = async (docs, dirs, _output) =>
  docs.reduce(async (r, doc, i) => {
+ const _m = await r
+ if (!validate(doc, radarSchema) || Object.keys(doc).length === 0)
+ return [..._m]
+
  const temp = tempDir
  const output = dirs[i] ? path.join(_output, dirs[i]) : _output
 
@@ -15,20 +26,24 @@ export const genStatics = async (docs, dirs, _output) =>
  output,
  temp,
  }
-
  try {
  genMdAssets(doc, temp)
  await genEleventy(temp, output)
  } catch (err) {
- console.error(err)
+ console.error('genStatics', err)
  }
- return [...(await r), output]
+ return [..._m, output]
  }, [])
 
+/**
+ * generate static site with using 11ty
+ * @param temp
+ * @param output
+ */
 export const genEleventy = async (temp, output) => {
  const elev = new Eleventy(temp, output)
  elev.setConfigPathOverride('src/main/js/11ty/.eleventy.cjs')
  await elev.init()
  await elev.write()
- await fsExtra.remove(temp)
+ fsExtra.removeSync(temp)
 }

src/main/js/index.js

@@ -8,6 +8,12 @@ import { genStatics } from './generateStatic.js'
 import { read } from './reader.js'
 import { makeUniq, reverse } from './util.js'
 
+/**
+ * generate static sites from csv/json/yml files to the output directory
+ * @param input - globby pattern for input files
+ * @param output - output directory
+ * @param cwd - current working directory
+ */
 export const run = async ({ input, output, cwd = process.cwd() } = {}) => {
  try {
  // TODO check that `output` is not a dir if exists
@@ -18,19 +24,31 @@ export const run = async ({ input, output, cwd = process.cwd() } = {}) => {
 
  console.log('statics=', statics)
  } finally {
- await fsExtra.remove(tempDir)
+ fsExtra.removeSync(tempDir)
  }
 }
-
+/**
+ * gives array of all file paths matching the globby pattern
+ * @param input - globby pattern for input files
+ * @param cwd - current working directory
+ * @returns {string[]}
+ */
 export const getSources = async (input, cwd) =>
  globby.sync([input], {
  onlyFiles: true,
  absolute: true,
  cwd,
  })
-
+/**
+ * returns parsed data in radarDocument format
+ * @param inputs
+ * @returns {radarDocument[]}
+ */
 export const getDocuments = (inputs) => inputs.map(read)
-
+/**
+ * gives unique dirs names for static sites
+ * @param sources
+ */
 export const getDirs = (sources) =>
  makeUniq(sources.map((s) => s.slice(0, -path.extname(s).length)))
  .map((s) => reverse(s.split(path.sep)).filter((v) => v))