course-format-ts 1.0.0

package/src/courseFormat/EduCourse.ts

@@ -0,0 +1,41 @@
+import { Course } from "./Course"
+import { MARKETPLACE } from "./EduFormatNames"
+import { JSON_FORMAT_VERSION } from "./EduVersions"
+
+export class EduCourse extends Course {
+  get itemType(): string {
+    return this.isMarketplace ? MARKETPLACE : super.itemType
+  }
+
+  get isStepikRemote(): boolean {
+    return this.id !== 0 && !this.isMarketplace
+  }
+
+  get isMarketplaceRemote(): boolean {
+    return this.id !== 0 && this.isMarketplace
+  }
+
+  formatVersion = JSON_FORMAT_VERSION
+  isUpToDate = true
+  learnersCount = 0
+  reviewScore = 0.0
+  generatedEduId?: string
+  isPreview = false
+  sectionIds: number[] = []
+  instructors: number[] = []
+  isStepikPublic = false
+  reviewSummary = 0
+
+  convertToLocal(): void {
+    if (this.isMarketplace) {
+      this.marketplaceCourseVersion = 1
+    }
+    else {
+      this.isStepikPublic = false
+      this.sectionIds = []
+      this.instructors = []
+    }
+    this.id = 0
+    this.updateDate = new Date(0)
+  }
+}

package/src/courseFormat/EduFile.ts

@@ -0,0 +1,133 @@
+import {
+  BinaryContents,
+  FileContents,
+  InMemoryTextualContents,
+  InMemoryUndeterminedContents,
+  TextualContents,
+  UndeterminedContents,
+} from "./FileContents"
+import { EduFileErrorHighlightLevel } from "./EduFileErrorHighlightLevel"
+import { exceedsBase64ContentLimit, getBinaryFileLimit, isBinary, mimeFileType } from "./fileUtils"
+import { logger } from "./loggerUtils"
+import type { TaskFile } from "./TaskFile"
+
+export class EduFile {
+  name = ""
+
+  private _contents: FileContents = UndeterminedContentsEmpty
+
+  get text(): string {
+    return this.contents.textualRepresentation
+  }
+
+  set text(value: string) {
+    this.contents = new InMemoryUndeterminedContents(value)
+  }
+
+  get contents(): FileContents {
+    return this._contents
+  }
+
+  set contents(value: FileContents) {
+    this._contents = value
+  }
+
+  setContentsIfEquals(expectedValue: FileContents, newValue: FileContents): boolean {
+    if (this._contents === expectedValue) {
+      this._contents = newValue
+      return true
+    }
+    return false
+  }
+
+  get isBinary(): boolean | undefined {
+    if (isTextualContents(this.contents)) return false
+    if (isBinaryContents(this.contents)) return true
+    return undefined
+  }
+
+  isTrackChanges = true
+  errorHighlightLevel: EduFileErrorHighlightLevel = EduFileErrorHighlightLevel.TEMPORARY_SUPPRESSION
+  isVisible = false
+  isEditable = true
+  isPropagatable = true
+  isLearnerCreated = false
+
+  constructor(name?: string, contents?: FileContents | string) {
+    if (name !== undefined) {
+      this.name = name
+    }
+    if (contents !== undefined) {
+      if (typeof contents === "string") {
+        this.contents = new InMemoryTextualContents(contents)
+      }
+      else {
+        this.contents = contents
+      }
+    }
+  }
+
+  getTextToSerialize(): string | null {
+    if (!(this instanceof requireTaskFile().TaskFile) || !this.task.course.needWriteYamlText) {
+      return null
+    }
+
+    if (isBinaryContents(this.contents)) return null
+    if (isUndeterminedContents(this.contents)) {
+      const contentType = mimeFileType(this.name)
+      if (contentType && isBinary(String(contentType))) return null
+    }
+
+    const text = this.contents.textualRepresentation
+    if (exceedsBase64ContentLimit(text)) {
+      logger("EduFile").warn(
+        `Base64 encoding of \`${this.name}\` file exceeds limit (${getBinaryFileLimit()}), its content isn't serialized`
+      )
+      return null
+    }
+
+    return text
+  }
+
+  get pathInCourse(): string {
+    const pathPrefix = this instanceof requireTaskFile().TaskFile ? this.task.pathInCourse : ""
+    const pathInCourse = `${pathPrefix}/${this.name}`
+    return pathInCourse.startsWith("/") ? pathInCourse.substring(1) : pathInCourse
+  }
+
+  get pathInArchive(): string {
+    return this.pathInCourse
+  }
+}
+
+function requireTaskFile(): { TaskFile: typeof TaskFile } {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require("./TaskFile")
+}
+
+function isTextualContents(contents: FileContents): contents is TextualContents {
+  return (contents as TextualContents).text !== undefined
+}
+
+function isBinaryContents(contents: FileContents): contents is BinaryContents {
+  return (contents as BinaryContents).bytes !== undefined
+}
+
+function isUndeterminedContents(contents: FileContents): contents is UndeterminedContents {
+  return (contents as UndeterminedContents).textualRepresentation !== undefined && !isTextualContents(contents)
+}
+
+const UndeterminedContentsEmpty: UndeterminedContents = {
+  textualRepresentation: "",
+  get text() {
+    return this.textualRepresentation
+  },
+  get bytes() {
+    try {
+      return Buffer.from(this.textualRepresentation, "base64")
+    }
+    catch {
+      return new Uint8Array()
+    }
+  },
+}

package/src/courseFormat/EduFileErrorHighlightLevel.ts

@@ -0,0 +1,5 @@
+export enum EduFileErrorHighlightLevel {
+  NONE = "NONE",
+  ALL_PROBLEMS = "ALL_PROBLEMS",
+  TEMPORARY_SUPPRESSION = "TEMPORARY_SUPPRESSION",
+}

package/src/courseFormat/EduFormatNames.ts

@@ -0,0 +1,95 @@
+import { message } from "./uiMessages"
+
+export const EDU_PREFIX = "edu"
+export const REST_PREFIX = "api"
+export const CODE_ARGUMENT = "code"
+
+export const MARKETPLACE = "Marketplace"
+export const COURSE_META_FILE = "course.json"
+export const COURSE_ICON_FILE = "courseIcon.svg"
+export const COURSE_CONTENTS_FOLDER = "contents"
+
+export const COURSE = "course"
+export const SECTION = "section"
+export const LESSON = "lesson"
+export const FRAMEWORK = "framework"
+export const TASK = "task"
+export const ITEM = "item"
+
+export const SOLUTION = "solution"
+export const STATES_ON_CLOSE = "states_on_close"
+export const SUBMISSIONS = "submissions"
+
+export const EMAIL = "email"
+export const NAME = "name"
+export const URL = "url"
+
+export const CORRECT = "correct"
+export const WRONG = "wrong"
+export const UNCHECKED = "unchecked"
+
+export const TIME_LEFT = "time_left"
+export const ID = "id"
+export const TIME = "time"
+export const STEP = "step"
+export const DATASET = "dataset"
+export const STATUS = "status"
+export const USER = "user"
+
+export const IS_MULTIPLE_CHOICE = "is_multiple_choice"
+export const OPTIONS = "options"
+export const PAIRS = "pairs"
+export const ROWS = "rows"
+export const COLUMNS = "columns"
+export const IS_CHECKBOX = "is_checkbox"
+
+export const DEFAULT_ENVIRONMENT = ""
+
+export const PYCHARM = "PyCharm"
+
+export const TITLE = "title"
+export const THEORY_ID = "theory"
+export const STEP_ID = "step"
+export const IS_COMPLETED = "is_completed"
+export const DESCRIPTION = "description"
+export const IDE_FILES = "ide_files"
+export const USE_IDE = "use_ide"
+export const LANGUAGE = "language"
+export const ENVIRONMENT = "environment"
+export const IS_TEMPLATE_BASED = "is_template_based"
+export const HYPERSKILL_PROBLEMS = "Problems"
+export const HYPERSKILL_TOPICS = "Topics"
+export const TOPICS = "topics"
+export const HYPERSKILL_PROJECTS_URL = "https://hyperskill.org/projects"
+export const HYPERSKILL = "Hyperskill"
+
+export const COURSERA = "Coursera"
+
+export const STEPIK = "Stepik"
+export const ATTEMPT = "attempt"
+export const CHECK_PROFILE = "check_profile"
+
+export const JAVA = "JAVA"
+export const KOTLIN = "kotlin"
+export const PYTHON = "Python"
+export const SCALA = "Scala"
+export const JAVASCRIPT = "JavaScript"
+export const RUST = "Rust"
+export const SHELL = "Shell Script"
+export const CPP = "C++"
+export const OBJECTIVE_C = "ObjectiveC"
+export const GO = "go"
+export const PHP = "PHP"
+export const CSHARP = "C#"
+
+export const PYTHON_2_VERSION = "2.x"
+export const PYTHON_3_VERSION = "3.x"
+
+export const TROUBLESHOOTING_GUIDE_URL =
+  "https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/troubleshooting-guide.html"
+export const NO_TESTS_URL = `${TROUBLESHOOTING_GUIDE_URL}#no_tests_have_run`
+export const FAILED_TO_CHECK_URL = `${TROUBLESHOOTING_GUIDE_URL}#failed_to_launch_checking`
+export const FAILED_TO_DELETE_SUBMISSIONS =
+  `${TROUBLESHOOTING_GUIDE_URL}#failed_to_delete_submissions`
+
+export const LOGIN_NEEDED_MESSAGE = message("check.error.login.needed")

package/src/courseFormat/EduTestInfo.ts

@@ -0,0 +1,87 @@
+import { CheckResultDiff } from "./CheckResult"
+
+export class EduTestInfo {
+  readonly name: string
+  readonly status: number
+  readonly message: string
+  readonly details?: string
+  readonly checkResultDiff?: CheckResultDiff
+
+  private readonly isSuccessInternal: boolean
+
+  constructor(
+    name = "",
+    status = -1,
+    message = "",
+    details?: string | null,
+    isFinishedSuccessfully?: boolean | null,
+    checkResultDiff?: CheckResultDiff | null
+  ) {
+    this.name = name
+    this.status = status
+    this.message = message
+    this.details = details ?? undefined
+    this.checkResultDiff = checkResultDiff ?? undefined
+    this.isSuccessInternal =
+      isFinishedSuccessfully === true ||
+      (EduTestInfo.get(status) !== undefined && EduTestInfo.isSuccess(EduTestInfo.get(status)!))
+  }
+
+  get isSuccess(): boolean {
+    return this.isSuccessInternal
+  }
+
+  toString(): string {
+    return `[${EduTestInfo.getPresentableStatus(this.status)}] ${this.name}`
+  }
+
+  static firstFailed(tests: EduTestInfo[]): EduTestInfo | undefined {
+    return tests.find((test) => !test.isSuccess)
+  }
+}
+
+export namespace EduTestInfo {
+  export enum PresentableStatus {
+    SKIPPED = 0,
+    COMPLETED = 1,
+    NOT_RUN = 2,
+    RUNNING = 3,
+    TERMINATED = 4,
+    IGNORED = 5,
+    FAILED = 6,
+    ERROR = 8,
+  }
+
+  const STATUS_TITLES: Record<PresentableStatus, string> = {
+    [PresentableStatus.SKIPPED]: "Skipped",
+    [PresentableStatus.COMPLETED]: "Completed",
+    [PresentableStatus.NOT_RUN]: "Not run",
+    [PresentableStatus.RUNNING]: "Running",
+    [PresentableStatus.TERMINATED]: "Terminated",
+    [PresentableStatus.IGNORED]: "Ignored",
+    [PresentableStatus.FAILED]: "Failed",
+    [PresentableStatus.ERROR]: "Error",
+  }
+
+  export function get(status: number): PresentableStatus | undefined {
+    return (Object.values(PresentableStatus) as Array<string | number>)
+      .filter((value) => typeof value === "number")
+      .map((value) => value as number)
+      .includes(status)
+      ? (status as PresentableStatus)
+      : undefined
+  }
+
+  export function getPresentableStatus(status: number): string {
+    const value = get(status)
+    return value === undefined ? "Unknown" : STATUS_TITLES[value]
+  }
+
+  export function isSuccess(status: PresentableStatus): boolean {
+    return (
+      status === PresentableStatus.COMPLETED ||
+      status === PresentableStatus.SKIPPED ||
+      status === PresentableStatus.IGNORED
+    )
+  }
+}

package/src/courseFormat/EduVersions.ts

@@ -0,0 +1,2 @@
+export const JSON_FORMAT_VERSION = 22
+export const JSON_FORMAT_VERSION_WITH_NEW_LANGUAGE_VERSION = 16

package/src/courseFormat/FileContents.ts

@@ -0,0 +1,97 @@
+export interface FileContents {
+  readonly textualRepresentation: string
+}
+
+export interface DeterminedContents extends FileContents {}
+
+export interface TextualContents extends DeterminedContents {
+  readonly text: string
+}
+
+export interface BinaryContents extends DeterminedContents {
+  readonly bytes: Uint8Array
+}
+
+export interface UndeterminedContents extends FileContents {
+  readonly textualRepresentation: string
+  readonly text: string
+  readonly bytes: Uint8Array
+}
+
+export const TextualContentsEmpty: TextualContents = {
+  text: "",
+  get textualRepresentation() {
+    return this.text
+  },
+}
+
+export const BinaryContentsEmpty: BinaryContents = {
+  bytes: new Uint8Array(),
+  get textualRepresentation() {
+    return Buffer.from(this.bytes).toString("base64")
+  },
+}
+
+export const UndeterminedContentsEmpty: UndeterminedContents = {
+  textualRepresentation: "",
+  get text() {
+    return this.textualRepresentation
+  },
+  get bytes() {
+    try {
+      return Buffer.from(this.textualRepresentation, "base64")
+    }
+    catch {
+      return new Uint8Array()
+    }
+  },
+}
+
+export class InMemoryBinaryContents implements BinaryContents {
+  readonly bytes: Uint8Array
+
+  constructor(bytes: Uint8Array) {
+    this.bytes = bytes
+  }
+
+  get textualRepresentation(): string {
+    return Buffer.from(this.bytes).toString("base64")
+  }
+
+  static parseBase64Encoding(base64: string): InMemoryBinaryContents {
+    return new InMemoryBinaryContents(Buffer.from(base64, "base64"))
+  }
+}
+
+export class InMemoryTextualContents implements TextualContents {
+  readonly text: string
+
+  constructor(text: string) {
+    this.text = text
+  }
+
+  get textualRepresentation(): string {
+    return this.text
+  }
+}
+
+export class InMemoryUndeterminedContents implements UndeterminedContents {
+  readonly textualRepresentation: string
+
+  constructor(textualRepresentation: string) {
+    this.textualRepresentation = textualRepresentation
+  }
+
+  get text(): string {
+    return this.textualRepresentation
+  }
+
+  get bytes(): Uint8Array {
+    try {
+      return Buffer.from(this.textualRepresentation, "base64")
+    }
+    catch {
+      return new Uint8Array()
+    }
+  }
+}

package/src/courseFormat/FileContentsFactory.ts

@@ -0,0 +1,19 @@
+import type { EduFile } from "./EduFile"
+import type { BinaryContents, TextualContents } from "./FileContents"
+
+/**
+ * Factory used to create file contents during deserialization of EduFile, TaskFile.
+ * Used when json or yaml do not have the contents themselves (text field is empty).
+ */
+export interface FileContentsFactory {
+  /**
+   * [file] is the EduFile object that will contain these contents.
+   * This file may not be fully initialized at the moment of the call.
+   */
+  createBinaryContents(file: EduFile): BinaryContents
+
+  /**
+   * see createBinaryContents
+   */
+  createTextualContents(file: EduFile): TextualContents
+}

package/src/courseFormat/FrameworkLesson.ts

@@ -0,0 +1,29 @@
+import { Lesson } from "./Lesson"
+import { FRAMEWORK } from "./EduFormatNames"
+import { Task } from "./tasks/Task"
+
+export class FrameworkLesson extends Lesson {
+  currentTaskIndex = 0
+  isTemplateBased = true
+
+  constructor(lesson?: Lesson) {
+    super()
+    if (lesson) {
+      this.id = lesson.id
+      this.updateDate = lesson.updateDate
+      this.name = lesson.name
+      this.items = lesson.items
+      this.parent = lesson.parent
+      this.index = lesson.index
+      this.customPresentableName = lesson.customPresentableName
+    }
+  }
+
+  currentTask(): Task | undefined {
+    return this.taskList[this.currentTaskIndex]
+  }
+
+  get itemType(): string {
+    return FRAMEWORK
+  }
+}

package/src/courseFormat/ItemContainer.ts

@@ -0,0 +1,47 @@
+import { StudyItem } from "./StudyItem"
+
+export abstract class ItemContainer extends StudyItem {
+  private _items: StudyItem[] = []
+
+  get items(): StudyItem[] {
+    return this._items
+  }
+
+  set items(value: StudyItem[]) {
+    this._items = [...value]
+  }
+
+  override init(parentItem: ItemContainer, isRestarted: boolean): void {
+    this.parent = parentItem
+    this.items.forEach((item, index) => {
+      item.index = index + 1
+      item.init(this, isRestarted)
+    })
+  }
+
+  getItem(name: string): StudyItem | undefined {
+    return this.items.find((item) => item.name === name)
+  }
+
+  addItem(item: StudyItem): void {
+    this._items.push(item)
+  }
+
+  addItemAt(index: number, item: StudyItem): void {
+    this._items.splice(index, 0, item)
+  }
+
+  replaceItem(existingItem: StudyItem, newItem: StudyItem): void {
+    const index = this._items.indexOf(existingItem)
+    if (index < 0) return
+    this._items[index] = newItem
+  }
+
+  removeItem(item: StudyItem): void {
+    this._items = this._items.filter((value) => value !== item)
+  }
+
+  sortItems(): void {
+    this._items.sort((a, b) => a.index - b.index)
+  }
+}

package/src/courseFormat/JBAccountUserInfo.ts

@@ -0,0 +1,21 @@
+import { UserInfo } from "./UserInfo"
+
+export class JBAccountUserInfo implements UserInfo {
+  email = ""
+  name = ""
+  jbaLogin = ""
+
+  constructor(userName?: string) {
+    if (userName) {
+      this.name = userName
+    }
+  }
+
+  getFullName(): string {
+    return this.name
+  }
+
+  toString(): string {
+    return this.getFullName()
+  }
+}

package/src/courseFormat/Language.ts

@@ -0,0 +1,31 @@
+const languages: Record<string, string> = {
+  Python: "Python",
+  "C++": "C/C++",
+  ObjectiveC: "C/C++",
+  go: "Go",
+  JAVA: "Java",
+  kotlin: "Kotlin",
+  Scala: "Scala",
+  JavaScript: "JavaScript",
+  Rust: "Rust",
+  PHP: "PHP",
+  "Shell Script": "Shell Script",
+  SQL: "SQL",
+  "C#": "C#",
+  unity: "unity",
+  TEXT: "Plain text",
+  FakeGradleBasedLanguage: "FakeGradleBasedLanguage",
+}
+
+export const Language = {
+  findLanguageByID(id: string): string | undefined {
+    return languages[id]
+  },
+  findLanguageByName(name: string): string | undefined {
+    if (name === "C/C++") {
+      return "C++"
+    }
+    const entry = Object.entries(languages).find(([, value]) => value === name)
+    return entry ? entry[0] : undefined
+  },
+}

package/src/courseFormat/Lesson.ts

@@ -0,0 +1,69 @@
+import { LessonContainer } from "./LessonContainer"
+import type { Course } from "./Course"
+import type { Section } from "./Section"
+import { Task } from "./tasks/Task"
+import { LESSON } from "./EduFormatNames"
+import { ItemContainer } from "./ItemContainer"
+
+function getLessonContainerModule(): { Section: typeof Section } {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require("./Section")
+}
+
+export class Lesson extends LessonContainer {
+  override init(parentItem: ItemContainer, isRestarted: boolean): void {
+    if (!(parentItem instanceof LessonContainer)) {
+      throw new Error(`Parent for lesson ${this.name} should be either course or section`)
+    }
+    super.init(parentItem, isRestarted)
+  }
+
+  get taskList(): Task[] {
+    return this.items.filter((item): item is Task => item instanceof Task)
+  }
+
+  get course(): Course {
+    return this.parent.course
+  }
+
+  get section(): Section | undefined {
+    return this.parent instanceof getLessonContainerModule().Section ? this.parent : undefined
+  }
+
+  get content(): Task[] {
+    return this.items.filter((item): item is Task => item instanceof Task)
+  }
+
+  get itemType(): string {
+    return LESSON
+  }
+
+  addTask(task: Task): void {
+    this.addItem(task)
+  }
+
+  addTaskAt(index: number, task: Task): void {
+    this.addItemAt(index, task)
+  }
+
+  removeTask(task: Task): void {
+    this.removeItem(task)
+  }
+
+  getTask(name: string): Task | undefined
+  getTask(id: number): Task | undefined
+  getTask(param: string | number): Task | undefined {
+    if (typeof param === "string") {
+      return this.taskList.find((task) => task.name === param)
+    }
+    return this.taskList.find((task) => task.id === param)
+  }
+
+  get container(): LessonContainer {
+    return this.section ?? this.course
+  }
+
+  visitTasks(visit: (task: Task) => void): void {
+    this.taskList.forEach(visit)
+  }
+}