testownik-converter 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to npm registry
+
+permissions:
+  id-token: write # Required for OIDC
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org/
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: npm install --global npm@latest
+      - run: npm publish --provenance

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konrad Guzek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# Testownik Converter
+
+This is a command-line utility for converting text-base single-choice or multiple-choice quizzes into the JSON format used by [Testownik](https://testownik.solvro.pl).
+
+## Adapters
+
+Currently, the only supported adapter is for converting quizzes exported from CCNA exams.
+
+### CCNA
+
+Invoke this adapter by running: 
+
+```sh
+npx testownik-converter ccna <filename>
+```
+
+## Options
+
+For a list of globally-available command-line options, run the command without arguments.
+
+```sh
+npx testownik-converter
+```
+
+For more information about adapter-specific options, use the `help` command:
+
+```sh
+npx testowink-converter help ccna
+```
+
+## Copyright
+
+Copyright © 2026 Konrad Guzek
+
+This file, along with all other source code files found in this repository, is a part of the Testownik Converter project, licensed under the [MIT license](./LICENSE).
+
+This tool is not affiliated with, endorsed by, or sponsored by Cisco Systems, Inc. Cisco® is a registered trademark of Cisco Systems, Inc.
+
+It is also not endorsed neither by Testownik nor by KN Solvro, although you should [check out their projects](https://solvro.pwr.edu.pl)!

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "testownik-converter",
+  "version": "1.0.0",
+  "description": "A command-line utility to convert quizzes into Solvro's Testownik format.",
+  "type": "module",
+  "author": "Konrad Guzek",
+  "license": "MIT",
+  "homepage": "https://github.com/kguzek/testownik-converter#readme",
+  "bugs": {
+    "url": "https://github.com/kguzek/testownik-converter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kguzek/testownik-converter.git"
+  },
+  "bin": {
+    "testownik-converter": "node dist/index.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}

package/src/adapters/base-adapter.ts

@@ -0,0 +1,34 @@
+import type { AdapterOptions, TestownikQuestion, TestownikQuiz } from "@/types";
+import { readFileSync, writeFileSync } from "node:fs";
+
+export abstract class BaseAdapter {
+  protected inputContent!: string;
+  protected options!: AdapterOptions;
+
+  constructor(options: AdapterOptions) {
+    const content = readFileSync(options.inputFilename, "utf8");
+
+    this.inputContent = content;
+    this.options = options;
+  }
+
+  protected abstract convertQuestions(): TestownikQuestion[];
+
+  private createQuiz(): TestownikQuiz {
+    const questions = this.convertQuestions();
+    const quiz: TestownikQuiz = {
+      title: this.options.quizTitle,
+      ...(this.options.quizDescription == null
+        ? {}
+        : { description: this.options.quizDescription }),
+      questions,
+    };
+    return quiz;
+  }
+
+  writeOutput(): void {
+    const quiz = this.createQuiz();
+    const data = JSON.stringify(quiz, null, 2);
+    writeFileSync(this.options.outputFilename, data, "utf8");
+  }
+}

package/src/adapters/ccna-adapter.ts

@@ -0,0 +1,54 @@
+import { BaseAdapter } from "./base-adapter";
+import type { TestownikQuestion, TestownikAnswer } from "@/types";
+
+const QUESTION_REGEX = new RegExp(
+  String.raw`^(?:(?<number>\d+)\.\s+)?(?<question>.+)$\n(?<answers>(?:(?=^-\s).+$\n?)+\n?)`,
+  "gm",
+);
+
+const ANSWER_REGEX = new RegExp(
+  String.raw`^- (?<correct>\[✓\] )?(?<question>.+)$`,
+  "gm",
+);
+
+export class CcnaAdapter extends BaseAdapter {
+  convertQuestions() {
+    QUESTION_REGEX.lastIndex = 0;
+    const questions: TestownikQuestion[] = [];
+    let questionMatch: RegExpExecArray | null;
+    while (
+      (questionMatch = QUESTION_REGEX.exec(this.inputContent)) != null &&
+      questionMatch.groups != null
+    ) {
+      const answers: TestownikAnswer[] = [];
+      ANSWER_REGEX.lastIndex = 0;
+
+      const rawAnswers = questionMatch.groups.answers;
+      let answerMatch: RegExpExecArray | null;
+      while (
+        (answerMatch = ANSWER_REGEX.exec(rawAnswers)) != null &&
+        answerMatch.groups != null
+      ) {
+        const answer: TestownikAnswer = {
+          text: answerMatch.groups.question,
+          is_correct: answerMatch.groups.correct != null,
+        };
+        answers.push(answer);
+      }
+      if (answers.length === 0) {
+        continue;
+      }
+      const question: TestownikQuestion = {
+        text: questionMatch.groups.question,
+        answers,
+        multiple: answers.filter((answer) => answer.is_correct).length > 1,
+      };
+      if (questionMatch.groups.number != null) {
+        question.order = Number(questionMatch.groups.number);
+      }
+      questions.push(question);
+    }
+
+    return questions;
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,42 @@
+import { Command } from "commander";
+import { CcnaAdapter } from "@/adapters/ccna-adapter";
+import { REPO_NAME, REPO_URL } from "@/constants";
+
+const program = new Command();
+program
+  .name("testownik-converter")
+  .description(
+    "A command-line converter of quizzes into KN Solvro's Testownik format.",
+  )
+  .option("-t, --title <string>", "quiz title", "Testownik Quiz")
+  .option(
+    "-d, --description <string>",
+    "quiz description",
+    `Generated by ${REPO_NAME}: ${REPO_URL}`,
+  )
+  .option("-o, --output <filename>", "output JSON filename", "testownik.json")
+  .version("1.0.0");
+
+program
+  .command("ccna")
+  .argument("<filename>", "input text filename")
+  .description("Parses questions from Cisco's CCNA exam format.")
+  .action((inputFilename: string) => {
+    const options = program.opts();
+
+    const outputFilename: string = options.output;
+    const quizTitle: string = options.title;
+    const quizDescription: string | undefined = options.description;
+
+    const adapter = new CcnaAdapter({
+      inputFilename,
+      outputFilename,
+      quizTitle,
+      quizDescription,
+    });
+
+    adapter.writeOutput();
+    console.log(`Quiz written to ${options.output}!`);
+  });
+
+program.parse(process.argv);

package/src/constants/index.ts

@@ -0,0 +1,5 @@
+export const REPO_NAME = "testownik-converter";
+
+export const AUTHOR_URL = "https://github.com/kguzek";
+
+export const REPO_URL = `${AUTHOR_URL}/${REPO_NAME}`;

package/src/types/adapters.ts

@@ -0,0 +1,6 @@
+export interface AdapterOptions {
+  inputFilename: string;
+  outputFilename: string;
+  quizTitle: string;
+  quizDescription?: string;
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export type { AdapterOptions } from "./adapters";
+
+export type { TestownikQuiz, TestownikQuestion } from "./testownik";

package/src/types/testownik.ts

@@ -0,0 +1,21 @@
+interface QuizPart {
+  text: string;
+  order?: number;
+  image_url?: string;
+}
+
+interface TestownikAnswer extends QuizPart {
+  is_correct: boolean;
+}
+
+export interface TestownikQuestion extends QuizPart {
+  answers: TestownikAnswer[];
+  multiple?: boolean; // default: false
+  explanation?: string | null;
+}
+
+export interface TestownikQuiz {
+  title: string;
+  description?: string;
+  questions: TestownikQuestion[];
+}

package/tsconfig.json

@@ -0,0 +1,46 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "esnext",
+    "target": "esnext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "moduleResolution": "bundler",
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+  }
+}

package/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig([
+  {
+    entry: ["src/cli/index.ts"],
+    clean: true,
+    shims: true,
+    format: "esm",
+    splitting: false,
+    sourcemap: true,
+    outDir: "dist",
+  },
+]);