slidev-theme-practicum 0.1.0 → 0.1.2

package/scripts/check-build-artifact.mjs

@@ -0,0 +1,243 @@
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import process from 'node:process'
+import {
+  EXPECTED_THEME_ASSETS,
+  EXPECTED_THEME_DECORS,
+  EXPECTED_THEME_PHOTOS,
+  toPosixPath,
+} from './theme-asset-inventory.mjs'
+import {
+  findThemeAssetOccurrences,
+  readArtifactContentsWithinLimit,
+} from './build-artifact-assets.mjs'
+
+const MAX_BUILD_SIZE = 20 * 1024 * 1024
+const PROJECT_ROOT = resolve(import.meta.dirname, '..')
+const DIST_DIR = join(PROJECT_ROOT, 'dist')
+const errors = []
+
+/**
+ * @param {string} root
+ * @param {string} path
+ */
+function isContained(root, path) {
+  const relativePath = toPosixPath(relative(root, path))
+
+  return relativePath === ''
+    || (relativePath !== '..' && !relativePath.startsWith('../') && !isAbsolute(relativePath))
+}
+
+/**
+ * @param {string} directory
+ * @param {string} distRealPath
+ * @returns {Promise<Array<{ path: string, relativePath: string, size: number }>>}
+ */
+async function listFiles(directory, distRealPath) {
+  const entries = await readdir(directory)
+  const nestedFiles = await Promise.all(entries.map(async (entry) => {
+    const path = join(directory, entry)
+    const fileStat = await lstat(path)
+    const relativePath = toPosixPath(relative(DIST_DIR, path))
+
+    if (fileStat.isSymbolicLink()) {
+      errors.push(`dist не должен содержать symlink: ${relativePath}`)
+      return []
+    }
+
+    const realPath = await realpath(path)
+    if (!isContained(distRealPath, realPath)) {
+      errors.push(`dist asset выходит за пределы dist: ${relativePath}`)
+      return []
+    }
+
+    if (fileStat.isDirectory())
+      return listFiles(path, distRealPath)
+
+    if (!fileStat.isFile()) {
+      errors.push(`dist содержит недопустимый тип файла: ${relativePath}`)
+      return []
+    }
+
+    return [{
+      path,
+      relativePath,
+      size: fileStat.size,
+    }]
+  }))
+
+  return nestedFiles.flat()
+}
+
+/**
+ * @param {string} relativePath
+ * @param {string} distRealPath
+ */
+async function validateRequiredAsset(relativePath, distRealPath) {
+  const path = resolve(DIST_DIR, relativePath)
+
+  if (!isContained(DIST_DIR, path)) {
+    errors.push(`обязательный asset выходит за пределы dist: ${relativePath}`)
+    return
+  }
+
+  try {
+    const fileStat = await lstat(path)
+
+    if (fileStat.isSymbolicLink()) {
+      errors.push(`обязательный asset не должен быть symlink: ${relativePath}`)
+      return
+    }
+
+    if (!fileStat.isFile()) {
+      errors.push(`обязательный asset должен быть файлом: ${relativePath}`)
+      return
+    }
+
+    const realPath = await realpath(path)
+    if (!isContained(distRealPath, realPath))
+      errors.push(`обязательный asset выходит за пределы dist: ${relativePath}`)
+  }
+  catch {
+    errors.push(`обязательный asset отсутствует: ${relativePath}`)
+  }
+}
+
+/**
+ * @param {string} label
+ * @param {string[]} actualPaths
+ * @param {readonly string[]} expectedPaths
+ */
+function compareInventory(label, actualPaths, expectedPaths) {
+  const actual = new Set(actualPaths)
+  const expected = new Set(expectedPaths)
+  const missing = expectedPaths.filter(path => !actual.has(path))
+  const unexpected = actualPaths.filter(path => !expected.has(path))
+
+  if (missing.length > 0)
+    errors.push(`${label} не содержит: ${missing.join(', ')}`)
+
+  if (unexpected.length > 0)
+    errors.push(`${label} содержит неожиданные файлы: ${unexpected.join(', ')}`)
+}
+
+let files = []
+let distRealPath = ''
+
+try {
+  const distStat = await lstat(DIST_DIR)
+
+  if (distStat.isSymbolicLink())
+    errors.push('dist не должен быть symlink')
+  else if (!distStat.isDirectory())
+    errors.push('dist должен быть директорией')
+  else {
+    distRealPath = await realpath(DIST_DIR)
+    files = await listFiles(DIST_DIR, distRealPath)
+  }
+}
+catch {
+  errors.push('dist отсутствует: сначала запустите npm run test:build')
+}
+
+if (distRealPath) {
+  const expectedAssets = EXPECTED_THEME_ASSETS.map(path => `theme/${path}`)
+  await Promise.all(expectedAssets.map(path => validateRequiredAsset(path, distRealPath)))
+}
+
+const relativeFiles = files.map(file => file.relativePath)
+const relativeFileSet = new Set(relativeFiles)
+const expectedPhotoFiles = EXPECTED_THEME_PHOTOS.map(path => `theme/${path}`)
+const expectedDecorFiles = EXPECTED_THEME_DECORS.map(path => `theme/${path}`)
+const actualPhotoFiles = relativeFiles.filter(path => path.startsWith('theme/photos/'))
+const actualDecorFiles = relativeFiles.filter(path => path.startsWith('theme/decor/'))
+const {
+  filesWithContent,
+  overLimit,
+  totalBytes,
+} = await readArtifactContentsWithinLimit(
+  files,
+  MAX_BUILD_SIZE,
+  async file => await readFile(file.path),
+)
+
+if (overLimit) {
+  errors.push(`dist ${totalBytes} байт превышает лимит ${MAX_BUILD_SIZE} байт`)
+  for (const error of errors)
+    console.error(`- ${error}`)
+  process.exit(1)
+}
+
+compareInventory('dist/theme/photos', actualPhotoFiles, expectedPhotoFiles)
+compareInventory('dist/theme/decor', actualDecorFiles, expectedDecorFiles)
+
+for (let number = 1; number <= 30; number++) {
+  for (const path of [
+    `photos/photo-${number}.png`,
+    `theme/photos/photo-${number}.png`,
+  ]) {
+    if (relativeFileSet.has(path))
+      errors.push(`dist не должен содержать ${path}`)
+  }
+}
+
+try {
+  await lstat(join(DIST_DIR, 'photos'))
+  errors.push('dist/photos не должен существовать')
+}
+catch {
+  // Ожидаем отсутствие deck-level photos.
+}
+
+const duplicatePaths = relativeFiles
+  .filter(path => path.startsWith('theme/'))
+  .map(path => path.slice('theme/'.length))
+  .filter(path => relativeFileSet.has(path))
+
+if (duplicatePaths.length > 0)
+  errors.push(`dist содержит дубли theme assets: ${duplicatePaths.join(', ')}`)
+
+const expectedThemeAssetPaths = new Set(EXPECTED_THEME_ASSETS.map(path => `theme/${path}`))
+const themeAssetsWithContent = filesWithContent.filter(file =>
+  expectedThemeAssetPaths.has(file.relativePath),
+)
+
+for (const { assetPath, occurrences } of findThemeAssetOccurrences(
+  themeAssetsWithContent,
+  filesWithContent,
+)) {
+  if (occurrences.length !== 1) {
+    errors.push(
+      `${assetPath} должен встречаться в dist по содержимому ровно один раз; `
+      + `найдено ${occurrences.length}: ${occurrences.join(', ')}`,
+    )
+  }
+}
+
+const htmlContents = filesWithContent
+  .filter(file => file.relativePath.endsWith('.html'))
+  .map(file => ({
+    path: file.relativePath,
+    content: file.content.toString(),
+  }))
+const rootFaviconReferences = htmlContents
+  .filter(file => /(?:href|src)=["']\/favicon\.svg(?:[?#][^"']*)?["']/.test(file.content))
+  .map(file => file.path)
+
+if (rootFaviconReferences.length > 0)
+  errors.push(`HTML ссылается на /favicon.svg: ${rootFaviconReferences.join(', ')}`)
+
+if (!htmlContents.some(file => file.content.includes('/theme/favicon.svg')))
+  errors.push('HTML не содержит ссылку на /theme/favicon.svg')
+
+if (errors.length > 0) {
+  for (const error of errors)
+    console.error(`- ${error}`)
+
+  process.exit(1)
+}
+
+console.log(
+  `Артефакт сборки: ${totalBytes} байт, ${files.length} файлов, `
+  + `фото=${actualPhotoFiles.length}, декоров=${actualDecorFiles.length}`,
+)

package/scripts/check-package.mjs

@@ -0,0 +1,132 @@
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import process from 'node:process'
+import {
+  EXPECTED_THEME_ASSETS,
+  EXPECTED_THEME_DECORS,
+  EXPECTED_THEME_PHOTOS,
+  validateAssetDirectory,
+} from './theme-asset-inventory.mjs'
+import { getNpmSpawnConfig, normalizeSpawnFailure } from './npm-spawn.mjs'
+
+const MAX_PACKAGE_SIZE = 10 * 1024 * 1024
+const PROJECT_ROOT = resolve(import.meta.dirname, '..')
+const cacheDir = mkdtempSync(join(tmpdir(), 'slidev-theme-practicum-pack-'))
+
+try {
+  const {
+    command: npmCommand,
+    args: npmArgs,
+    shell,
+    env,
+  } = getNpmSpawnConfig(process.platform, cacheDir)
+  const result = spawnSync(npmCommand, npmArgs, {
+    cwd: PROJECT_ROOT,
+    encoding: 'utf8',
+    env,
+    shell,
+  })
+
+  if (result.error || result.status !== 0) {
+    const failure = normalizeSpawnFailure(result)
+    process.stderr.write(failure.message.endsWith('\n') ? failure.message : `${failure.message}\n`)
+    process.exitCode = failure.status
+  }
+  else {
+    const [pack] = JSON.parse(result.stdout)
+    const files = new Set(pack.files.map(file => file.path))
+    const manifest = JSON.parse(readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf8'))
+    const errors = []
+    const expectedPhotoFiles = EXPECTED_THEME_PHOTOS.map(file => `public/${file}`)
+    const expectedDecorFiles = EXPECTED_THEME_DECORS.map(file => `public/${file}`)
+    const expectedAssetFiles = EXPECTED_THEME_ASSETS.map(file => `public/${file}`)
+    const packedPhotoFiles = [...files].filter(file => file.startsWith('public/photos/'))
+    const packedDecorFiles = [...files].filter(file => file.startsWith('public/decor/'))
+
+    try {
+      await validateAssetDirectory(
+        join(PROJECT_ROOT, 'public/photos'),
+        EXPECTED_THEME_PHOTOS.map(file => file.slice('photos/'.length)),
+      )
+      await validateAssetDirectory(
+        join(PROJECT_ROOT, 'public/decor'),
+        EXPECTED_THEME_DECORS.map(file => file.slice('decor/'.length)),
+      )
+    }
+    catch (error) {
+      errors.push(error instanceof Error ? error.message : 'source inventory не прошёл проверку')
+    }
+
+    for (const file of expectedAssetFiles) {
+      if (!files.has(file))
+        errors.push(`package не содержит обязательный theme asset: ${file}`)
+    }
+
+    for (const file of packedPhotoFiles) {
+      if (!expectedPhotoFiles.includes(file))
+        errors.push(`package содержит неожиданный photo asset: ${file}`)
+    }
+
+    for (const file of packedDecorFiles) {
+      if (!expectedDecorFiles.includes(file))
+        errors.push(`package содержит неожиданный decor asset: ${file}`)
+    }
+
+    for (let number = 1; number <= 30; number++) {
+      const pngPath = `public/photos/photo-${number}.png`
+      if (files.has(pngPath))
+        errors.push(`package не должен содержать ${pngPath}`)
+    }
+
+    if (!files.has('LICENSE'))
+      errors.push('package должен содержать LICENSE')
+
+    if (!files.has('skills/slidev-practicum/SKILL.md'))
+      errors.push('package должен содержать skills/slidev-practicum/SKILL.md')
+
+    if (!files.has('example.md'))
+      errors.push('package должен содержать example.md как каноническую колоду для авторов')
+
+    const defaultDeckTargets = new Set(
+      Object.values(manifest.scripts ?? {})
+        .flatMap(script => String(script).match(/\b[\w-]+\.md\b/g) ?? []),
+    )
+    for (const target of defaultDeckTargets) {
+      if (!files.has(target))
+        errors.push(`package script ссылается на отсутствующий deck target: ${target}`)
+    }
+
+    for (const guidancePath of ['README.md', 'skills/slidev-practicum/SKILL.md']) {
+      const guidance = readFileSync(join(PROJECT_ROOT, guidancePath), 'utf8')
+      if (!guidance.includes('example.md'))
+        errors.push(`${guidancePath} должен ссылаться на канонический example.md`)
+    }
+
+    if (files.has('vite.config.mjs'))
+      errors.push('package не должен содержать локальный vite.config.mjs')
+
+    if (manifest.slidev?.defaults?.favicon !== '/theme/favicon.svg')
+      errors.push('package manifest должен задавать favicon как /theme/favicon.svg')
+
+    if (pack.size > MAX_PACKAGE_SIZE)
+      errors.push(`package ${pack.size} bytes превышает лимит ${MAX_PACKAGE_SIZE} bytes`)
+
+    if (errors.length > 0) {
+      for (const error of errors)
+        console.error(`- ${error}`)
+
+      process.exitCode = 1
+    }
+    else {
+      console.log(
+        `Артефакт пакета: ${pack.size} байт, ${pack.files.length} файлов, `
+        + `фото=${expectedPhotoFiles.length}, декоров=${expectedDecorFiles.length}`,
+      )
+    }
+  }
+}
+finally {
+  rmSync(cacheDir, { recursive: true, force: true })
+}

package/scripts/check-test-architecture.mjs

@@ -0,0 +1,176 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+import { findDisallowedRawSourceReads } from './test-architecture-policy.mjs'
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url))
+const testsDirectory = join(projectRoot, 'tests')
+const testFiles = readdirSync(testsDirectory)
+  .filter(file => file.endsWith('.test.cjs'))
+  .sort()
+
+function listHelperFiles(directory) {
+  return readdirSync(directory, { withFileTypes: true })
+    .flatMap((entry) => {
+      const path = join(directory, entry.name)
+
+      if (entry.isDirectory())
+        return listHelperFiles(path)
+      return entry.isFile() && entry.name.endsWith('.cjs') ? [path] : []
+    })
+}
+
+const helperFiles = listHelperFiles(join(testsDirectory, 'helpers')).sort()
+
+function parseTestFile(relativeFile, source) {
+  return ts.createSourceFile(
+    relativeFile,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.JS,
+  )
+}
+
+function countRegexLiterals(sourceFile) {
+  let count = 0
+
+  function visit(node) {
+    if (ts.isRegularExpressionLiteral(node))
+      count += 1
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+
+  return count
+}
+
+function analyseReferences(sourceFile) {
+  const calledMethods = new Set()
+  const identifiers = new Set()
+  const imports = new Set()
+
+  function visit(node) {
+    if (ts.isIdentifier(node))
+      identifiers.add(node.text)
+
+    if (
+      ts.isCallExpression(node)
+      && ts.isIdentifier(node.expression)
+      && node.expression.text === 'require'
+      && node.arguments.length === 1
+      && ts.isStringLiteral(node.arguments[0])
+    ) {
+      imports.add(node.arguments[0].text)
+    }
+
+    if (
+      ts.isCallExpression(node)
+      && ts.isPropertyAccessExpression(node.expression)
+    ) {
+      calledMethods.add(node.expression.name.text)
+    }
+
+    ts.forEachChild(node, visit)
+  }
+
+  visit(sourceFile)
+  return { calledMethods, identifiers, imports }
+}
+
+const measurements = testFiles.map((file) => {
+  const absoluteFile = join(testsDirectory, file)
+  const source = readFileSync(absoluteFile, 'utf8')
+  const sourceFile = parseTestFile(relative(projectRoot, absoluteFile), source)
+
+  return {
+    ...analyseReferences(sourceFile),
+    file,
+    lines: source.split('\n').length,
+    regexLiterals: countRegexLiterals(sourceFile),
+    disallowedRawReads: file === 'text-fit-contract.test.cjs'
+      ? findDisallowedRawSourceReads(source, file)
+      : [],
+  }
+})
+const helperMeasurements = helperFiles.map((absoluteFile) => {
+  const source = readFileSync(absoluteFile, 'utf8')
+
+  return {
+    file: relative(testsDirectory, absoluteFile),
+    lines: source.split('\n').length,
+  }
+})
+const lineMeasurements = [...measurements, ...helperMeasurements]
+const totalRegexLiterals = measurements.reduce((total, measurement) => total + measurement.regexLiterals, 0)
+const foundationRegexLiterals = measurements
+  .filter(({ file }) => file.startsWith('foundation-') || file === 'layout-public-api.test.cjs')
+  .reduce((total, measurement) => total + measurement.regexLiterals, 0)
+const longest = lineMeasurements.reduce(
+  (current, measurement) => measurement.lines > current.lines ? measurement : current,
+  { file: '', lines: 0 },
+)
+const failures = []
+
+for (const measurement of lineMeasurements) {
+  if (measurement.lines > 500)
+    failures.push(`${measurement.file}: ${measurement.lines} строк (максимум 500)`)
+}
+for (const measurement of measurements) {
+  for (const rawRead of measurement.disallowedRawReads)
+    failures.push(`${measurement.file}: запрещено читать исходник .vue/.ts как обычный текст (${rawRead})`)
+}
+if (totalRegexLiterals > 250)
+  failures.push(`tests/*.test.cjs: ${totalRegexLiterals} литералов регулярных выражений (максимум 250)`)
+if (foundationRegexLiterals > 70)
+  failures.push(`foundation/layout: ${foundationRegexLiterals} литералов регулярных выражений (максимум 70)`)
+
+const textFitFixtureImport = './helpers/text-fit-runtime-fixtures.cjs'
+const textFitResponsibilitySuites = measurements.filter(measurement =>
+  measurement.imports.has(textFitFixtureImport),
+)
+
+if (!textFitResponsibilitySuites.length)
+  failures.push(`наборы тестов ответственности text-fit должны импортировать ${textFitFixtureImport}`)
+
+const coveredEntrypoints = new Set()
+for (const suite of textFitResponsibilitySuites) {
+  const callsElement = suite.calledMethods.has('useElement')
+  const callsGroup = suite.calledMethods.has('useGroup')
+  const elementOnlySuite = /-element(?:[.-])/.test(suite.file)
+  const groupOnlySuite = /-group(?:[.-])/.test(suite.file)
+  const browserSuite = /-browser(?:[.-])/.test(suite.file)
+
+  if (callsElement)
+    coveredEntrypoints.add('useElement')
+  if (callsGroup)
+    coveredEntrypoints.add('useGroup')
+  if (elementOnlySuite && (callsGroup || suite.identifiers.has('handleType')))
+    failures.push(`${suite.file} смешивает тесты useElement с координацией групп`)
+  if (groupOnlySuite && (callsElement || suite.identifiers.has('handleType')))
+    failures.push(`${suite.file} смешивает тесты useGroup с жизненным циклом элемента`)
+  if (callsElement && callsGroup && !browserSuite)
+    failures.push(`${suite.file} смешивает useElement/useGroup вне браузерной ответственности`)
+}
+
+for (const entrypoint of ['useElement', 'useGroup']) {
+  if (!coveredEntrypoints.has(entrypoint))
+    failures.push(`наборы тестов ответственности text-fit не покрывают ${entrypoint}`)
+}
+
+console.log(
+  `Архитектура тестов: ${measurements.length} тестовых файлов и `
+  + `${helperMeasurements.length} вспомогательных файлов; максимум ${longest.lines} строк (${longest.file}).`,
+)
+console.log(
+  `Регулярные выражения: ${totalRegexLiterals}/250 всего; `
+  + `${foundationRegexLiterals}/70 в foundation/layout.`,
+)
+
+if (failures.length) {
+  console.error('Нарушения архитектуры тестов:')
+  for (const failure of failures)
+    console.error(`- ${failure}`)
+  process.exitCode = 1
+}

package/scripts/npm-spawn.mjs

@@ -0,0 +1,31 @@
+import process from 'node:process'
+
+export function getNpmSpawnConfig(platform, cacheDir, environment = process.env) {
+  const isWindows = platform === 'win32'
+  const env = Object.fromEntries(
+    Object.entries(environment).filter(([key]) => key.toLowerCase() !== 'npm_config_cache'),
+  )
+  env.npm_config_cache = cacheDir
+
+  return {
+    command: isWindows ? 'npm.cmd' : 'npm',
+    args: ['pack', '--dry-run', '--json'],
+    shell: isWindows,
+    env,
+  }
+}
+
+export function normalizeSpawnFailure(result) {
+  const errorMessage = result.error instanceof Error ? result.error.message : ''
+  const stderr = typeof result.stderr === 'string' ? result.stderr : ''
+  const stdout = typeof result.stdout === 'string' ? result.stdout : ''
+
+  return {
+    message:
+      errorMessage
+      || stderr
+      || stdout
+      || 'npm pack завершился без диагностического вывода',
+    status: typeof result.status === 'number' ? result.status : 1,
+  }
+}