svn-visualizer 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: Node.js CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [22.x, 24.x, 26.x]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10.17.1
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Verify pnpm
+        run: pnpm --version
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: CI checks (typecheck, lint, format, build, unit, integration)
+        run: pnpm run ci
+
+      - name: Coveralls
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          file: coverage/lcov.info
+          format: lcov
+          flag-name: node-${{ matrix.node-version }}
+          parallel: true
+
+  finish:
+    needs: build
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Coveralls Finished
+        uses: coverallsapp/github-action@v2
+        with:
+          parallel-finished: true
+          carryforward: "node-22.x,node-24.x,node-26.x"

package/.gitignore

@@ -0,0 +1,100 @@
+# ---------------------------
+# OS / Filesystem
+# ---------------------------
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# ---------------------------
+# Editor / IDE
+# ---------------------------
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# ---------------------------
+# AI
+# ---------------------------
+.opencode
+
+# ---------------------------
+# Logs
+# ---------------------------
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+
+# ---------------------------
+# Env / Secrets
+# ---------------------------
+.env
+.env.*
+!.env.example
+
+# ---------------------------
+# Dependency directories
+# ---------------------------
+node_modules/
+.pnpm-store/
+.npm/
+
+# ---------------------------
+# Build output
+# ---------------------------
+dist/
+dist-demo/
+docs/
+coverage/
+.nyc_output/
+playwright-report/
+test-results/
+.vitest-attachments/
+tmp/
+temp/
+.tmp/
+.temp/
+
+# ---------------------------
+# TypeScript
+# ---------------------------
+*.tsbuildinfo
+
+# ---------------------------
+# Package managers
+# ---------------------------
+package-lock.json
+yarn.lock
+
+# NOTE:
+# keep EXACTLY ONE lockfile depending on PM:
+# - npm  -> keep package-lock.json
+# - yarn -> keep yarn.lock
+# - pnpm -> keep pnpm-lock.yaml
+
+# ---------------------------
+# Caches
+# ---------------------------
+.cache/
+.eslintcache
+.oxc_cache
+
+# ---------------------------
+# Misc
+# ---------------------------
+*.tgz
+*.bak
+*.tmp
+
+# ---------------------------
+# Custom
+# ---------------------------
+
+# NOTE:
+# add custom ignores here
+
+/svn-data.json
+/output/

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit "$1"

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm run ci

package/.release-it.json

@@ -0,0 +1,23 @@
+{
+	"npm": {
+		"publish": false
+	},
+	"git": {
+		"requireCleanWorkingDir": true,
+		"commit": true,
+		"commitMessage": "chore: release ${version}",
+		"tag": true,
+		"tagName": "v${version}",
+		"push": true,
+		"pushArgs": ["--follow-tags"]
+	},
+	"github": {
+		"release": true,
+		"autoGenerate": true
+	},
+	"hooks": {
+		"before:init": "pnpm run ci",
+		"after:bump": "pnpm run create-changelog",
+		"before:git:commit": "git add CHANGELOG.md"
+	}
+}

package/AGENTS.md

@@ -0,0 +1,90 @@
+# Agent Guidelines: svn-visualizer
+
+This document provides essential instructions for autonomous agents (like Cursor, GitHub Copilot, or CLI agents) working on the `svn-visualizer` repository.
+
+## Build/Lint/Test
+
+- `pnpm run ci`: Runs lint, build, and all tests.
+- `pnpm run dev`: Rebuilds the CLI in watch mode.
+- `pnpm run test`: Runs unit tests.
+- `pnpm exec vitest <file>`: Runs a specific test file.
+- `pnpm run lint`: Lints the codebase with Oxlint.
+
+## Project Overview
+
+A Node.js CLI that incrementally gathers SVN history and generates a self-contained Chart.js HTML report.
+
+## Build, Lint, and Test Commands
+
+### Core Commands
+
+- **Install dependencies:** `pnpm install`
+- **Build project:** `pnpm run build`
+- **Lint code:** `pnpm run lint` (runs Oxlint)
+- **Check types:** `pnpm run typecheck`
+- **Check formatting:** `pnpm run format:check`
+- **Run all tests:** `pnpm run test` (uses `vitest` with coverage)
+- **Run CI suite:** `pnpm run ci` (lint + build + test)
+
+### Targeted Testing
+
+- **Run a single test file:** `pnpm exec vitest src/index.test.ts`
+- **Run tests matching a pattern:** `pnpm exec vitest -t "feature"`
+- **Watch mode:** `pnpm exec vitest`
+
+## Code Style & Conventions
+
+### Language & Runtime
+
+- **TypeScript:** Strict mode is mandatory. Use explicit types for function boundaries.
+- **Node.js:** Targets >= 22.0.0.
+- **ESM:** The project uses ES Modules (`"type": "module"` in `package.json`).
+
+### Imports
+
+- **Extensions:** Always use `.js` extensions in relative imports (e.g., `import { main } from './lib.js';`) to comply with ESM requirements in Node.js, even though source files are `.ts`.
+- **Built-ins:** Use the `node:` prefix for built-in modules (e.g., `import path from 'node:path';`).
+
+### Linting & Formatting Configuration
+
+This project uses a layered configuration approach:
+
+- **`oxc.config.ts`** — Managed source of truth for `oxlint` and `oxfmt` defaults. **Do not edit this file**; it is overwritten during template updates.
+- **`oxlint.config.ts`** — User-customizable linting overrides. Preserved across updates. Use this to add or relax lint rules for your project.
+- **`oxfmt.config.ts`** — User-customizable formatting overrides. Preserved across updates. Use this to adjust formatting preferences.
+- **Tooling:** oxfmt is enforced via `pnpm run lint`.
+- **Indentation:** Tabs are used for indentation.
+- **Quotes:** Single quotes for strings, except when double quotes prevent escaping.
+
+### Architecture & Types
+
+- **Modularity:** Keep logic modularized.
+- **Type Safety:** Use `zod` for runtime schema validation and `z.infer` for type definitions.
+- **Immutability:** Prefer `readonly` and `const` where possible to ensure data integrity.
+
+### Naming Conventions
+
+- **Variables/Functions:** `camelCase`.
+- **Constants:** `UPPER_SNAKE_CASE`.
+- **Files:** `kebab-case.ts`.
+
+### Error Handling
+
+- **CLI Errors:** Throw descriptive errors.
+- **Safety:** Always use `try...finally` or `using` (if applicable) to ensure resources like file handles or connections are closed.
+- **Validation:** Validate all user inputs and CLI arguments using Zod schemas before processing.
+
+## Mandatory Completion Protocol (Definition of Done)
+
+No task involving code changes is considered complete until the agent provides the following "Evidence of Done" in its final response:
+
+1. **CI Verification:** The agent MUST run `pnpm run ci` and include the full terminal output (showing `Found 0 warnings and 0 errors` and `Tests passed`).
+2. **Test Coverage:** The agent MUST ensure that all new code is covered by tests and all existing tests pass.
+
+**Failure to provide these logs means the task is INCOMPLETE.** The user is encouraged to reject any response that lacks this section.
+
+## Git Workflow
+
+- **Conventional Commits:** Adhere to the specification (e.g., `feat:`, `fix:`, `chore:`, `test:`).
+- **Hooks:** Husky runs `pnpm run ci` on pre-commit. Do not bypass hooks.
+- **Branches:** Use descriptive branch names like `feat/feature-name` or `fix/issue-description`.

package/CHANGELOG.md

@@ -0,0 +1 @@
+# 0.1.0 (2026-09-24)

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+## Commit Message Guidelines
+
+We follow the **Conventional Commits** specification. This is **enforced** by `commitlint` and is required for automated changelog generation.
+
+**Format:** `type(scope): subject`
+
+**Common Types:**
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `perf`: A code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Changes to the build process or auxiliary tools and libraries such as documentation generation
+
+**Examples:**
+- `feat(cli): add support for jsonc files`
+- `fix(parser): handle empty input gracefully`
+- `docs: update contributing guidelines`
+
+## Release Process
+
+To release a new version:
+
+```sh
+pnpm release -- patch   # or minor / major
+```
+
+This will automatically:
+1. Run the CI suite (`pnpm run ci`).
+2. Bump the version in `package.json`.
+3. Update the `CHANGELOG.md` using `conventional-changelog` with the Angular preset.
+4. Commit, tag, and push the changes.
+5. Create a GitHub release with auto-generated notes.
+6. Publish to npm (if configured).
+
+**Note:** NPM publishing is **disabled** by default for new projects. To enable it:
+1. Set `"private": false` in `package.json`.
+2. Set `"publish": true` in `.release-it.json`.
+3. Ensure you have the necessary `NPM_TOKEN` configured.
+
+## Dependencies
+
+- **zod**: TypeScript-first schema validation with static type inference.
+- **eslint-plugin-regexp**: ESLint plugin for finding regexp mistakes and style guide violations.
+- **release-it**: Interactive release-tool for Git repositories.
+- **debug**: A tiny JavaScript debugging utility modelled after Node.js core debugging technique.
+- **@commitlint/cli**: Lint commit messages to ensure they follow conventional commits.
+- **@commitlint/config-conventional**: Shareable commitlint config enforcing conventional commits.
+- **@types/debug**: TypeScript definitions for debug.
+- **@types/node**: TypeScript definitions for Node.js.
+- **@vitest/coverage-v8**: V8 coverage provider for Vitest.
+- **conventional-changelog**: Generate a changelog from git metadata.
+- **conventional-changelog-angular**: Angular preset for conventional-changelog.
+- **husky**: Modern native git hooks made easy.
+- **oxlint**: A JavaScript linter written in Rust.
+- **oxlint-tsgolint**: TypeScript-specific rules for oxlint.
+- **oxfmt**: High performance JavaScript / TypeScript formatter.
+- **typescript**: A superset of JavaScript that compiles to clean JavaScript output.
+- **vitest**: A Vite-native unit test framework.
+- **vite**: Native-ESM powered web dev build tool
+- **commander**: The complete solution for node.js command-line interfaces.
+- **cli-progress**: Easy to use progress-bar for command-line/terminal applications.
+- **@types/cli-progress**: TypeScript definitions for cli-progress.

package/GENERATED.md

@@ -0,0 +1,129 @@
+# 🚀 Project Setup Guide: svn-visualizer
+
+Welcome to your newly generated **cli** project! This document outlines what was scaffolded, the automated steps already completed, and the remaining manual adjustments required to finalize your setup.
+
+**Status:** 🟢 **Successfully Completed**
+
+## 📦 What Was Generated
+* **Project Name:** `svn-visualizer`
+* **Template Used:** `cli`
+* **Package Manager:** `pnpm`
+
+---
+
+## 📋 Initialization Checklist
+The following tasks were executed during the generation process:
+- [x] Scaffold project files and directories
+- [x] Configure `package.json` with appropriate dependencies
+- [ ] Install dependencies using `pnpm` *(Skipped)*
+- [x] Initialize Git repository (main branch)
+- [ ] Create and push GitHub repository *(Skipped)*
+- [ ] Run initial CI pipeline (lint, build, test) *(Skipped)*
+
+## ⏭️ Complete Skipped Steps Manually
+Some initialization steps were marked as *(Skipped)*. Use the guidance below to complete them yourself:
+- [ ] **Install dependencies manually:** Run `pnpm install` from the project root.
+- [ ] **Create and push GitHub repository manually:** Verify GitHub CLI auth with `gh auth status`, then run `gh repo create svn-visualizer --public --source=. --remote=origin --push`.
+- [ ] **Run CI checks manually:** After dependencies are installed, run `pnpm run ci`.
+
+---
+
+## 🛠️ Manual Adjustments Needed
+To complete your project setup, please review and manually update the following:
+- [ ] **`LICENSE`**: Verify the copyright year and author name.
+- [ ] **`package.json`**: Review the description, keywords, author, and repository links.
+- [ ] **`README.md`**: Update with project-specific instructions, architecture details, and contribution guidelines.
+- [ ] **`.gitignore`**: Note that there is a **`# Custom`** section at the end of the file for your own ignores.
+
+---
+
+## 💡 Next Steps
+1. Review the generated codebase to familiarize yourself with the structure.
+2. Start the development server using `pnpm run dev`.
+3. Make your first commit and push to your remote repository.
+
+---
+
+## 💻 Available Commands
+You can run these commands from the project root using `pnpm run <command>`:
+
+| Command | Description |
+| :--- | :--- |
+| `dev` | Starts the development server |
+| `build` | Builds the project for production |
+| `test` | Runs the unit test suite (Vitest) |
+| `lint` | Lints and formats the codebase |
+| `ci` | Runs lint, build, and test (used by CI/CD) |
+
+---
+
+## 🏗️ CLI Architecture
+This project uses `commander` for argument parsing and `@clack/prompts` for interactive CLI interfaces.
+
+### Source Files Generated
+- **`src/index.ts`**: The main execution entry point. Handles top-level errors and bootstraps the CLI application.
+- **`src/cli.ts`**: Parses command-line arguments and orchestrates your user prompts.
+
+### How to Enhance
+- Add new sub-commands directly in `src/cli.ts`.
+- Extract logic into a new `src/commands/` directory as your application scales.
+
+---
+
+## 🧪 Testing Strategy
+
+### Unit Testing (Vitest)
+This project is pre-configured with **Vitest** for blazing-fast unit testing and coverage reporting.
+- **Where to put tests**: Create files with the `.test.ts` or `.spec.ts` extension next to your source files (e.g., `src/main.test.ts`).
+- **How to run**: `pnpm run test`
+- **Watch mode**: `pnpm exec vitest` to automatically re-run tests on file changes.
+- **Coverage**: Coverage is generated automatically during the test run. Aim for high coverage on core logic!
+
+### End-to-End (E2E) Testing
+Currently, only unit tests are scaffolded by default. To enhance your project's reliability, we highly recommend adding E2E testing:
+- **For Web Apps**: Consider installing [Playwright](https://playwright.dev/) (`pnpm create playwright`) to simulate real user interactions in the browser.
+- **For CLIs**: Consider using `execa` within your Vitest suite to invoke your compiled CLI binary and assert its `stdout`/`stderr` outputs.
+
+---
+
+## 🐙 Key Git Commands
+Here are the most common Git operations you will use to manage your codebase:
+
+| Command | Description |
+| :--- | :--- |
+| `git status` | Check the current state of your working directory |
+| `git add .` | Stage all your changes for the next commit |
+| `git commit -m "feat: your feature"` | Create a new commit (following Conventional Commits) |
+| `git push` | Push your committed changes to the remote repository |
+| `git pull` | Fetch and merge changes from the remote repository |
+| `git checkout -b <branch>` | Create and switch to a new branch |
+
+---
+
+## 🐈 Key GitHub (`gh`) Commands
+The `gh` CLI provides powerful tools to interact with GitHub right from your terminal:
+
+| Command | Description |
+| :--- | :--- |
+| `gh repo view --web` | Open the repository in your default web browser |
+| `gh repo create <name> --public --source=. --remote=origin --push` | Create and push a new GitHub repository |
+| `gh pr create` | Create a new Pull Request |
+| `gh pr checkout <pr-number>` | Checkout a Pull Request branch locally |
+| `gh issue create` | Create a new Issue |
+| `gh issue list` | List all open Issues |
+| `gh repo delete <owner>/<repo> --yes` | Dangerously delete a repository completely (use with caution!) |
+
+---
+
+## 🚀 Creating a Release
+This project uses Conventional Commits and automated changelogs. To create a new release:
+1. **Run the release command:** `pnpm release`
+
+This single command will automatically run your CI suite, bump the version, generate a changelog, create a Git tag, push to GitHub, and create a GitHub release.
+
+**Note:** NPM publishing is disabled by default. See `CONTRIBUTING.md` for details on how to enable it.
+
+---
+
+<br>
+<p align="center"><i>This file was auto-generated by <b>create-template-project</b>.</i></p>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dieter Oberkofler
+
+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,63 @@
+# svn-visualizer
+
+Generate a self-contained HTML activity report from Subversion history. The repository is hosted on GitHub and the package is private; it is not published to npm.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/doberkofler/svn-visualizer/actions/workflows/ci.yml/badge.svg)](https://github.com/doberkofler/svn-visualizer/actions/workflows/ci.yml)
+
+## Requirements
+
+- Node.js 22 or newer
+- pnpm
+- The `svn` command-line client for `gather` and `report`
+
+## Install and build
+
+```bash
+pnpm install
+pnpm run build
+```
+
+The build produces the Node CLI at `dist/index.js` and a Chart.js browser bundle at `dist/client/main.js`. Report generation embeds the browser bundle into `output/index.html`; the result needs no server or external assets.
+
+## Usage
+
+Gather history incrementally:
+
+```bash
+pnpm svn-visualizer gather --url https://svn.example.com/project/trunk
+```
+
+Generate a report from local data:
+
+```bash
+pnpm svn-visualizer generate --relative-days 90 --title "Project activity"
+```
+
+Gather and generate in one command:
+
+```bash
+pnpm svn-visualizer report --url https://svn.example.com/project/trunk --output-dir output
+```
+
+`gather` uses the SVN client's existing authentication configuration when no credentials are supplied. To provide credentials non-interactively, use `--username` and place the password in `SVN_PASSWORD`, or select another environment variable with `--password-env`. There is deliberately no literal password option, and supplied credentials are not cached. Certificate failures are not bypassed.
+
+Common defaults:
+
+| Option | Default |
+| --- | --- |
+| `--data-file` | `svn-data.json` |
+| `--output-dir` | `output` |
+| `--password-env` | `SVN_PASSWORD` |
+| `--svn-binary` | `svn` |
+
+Use `--from YYYY-MM-DD` and `--to YYYY-MM-DD` for an inclusive UTC period, or `--relative-days N` for a range ending on the current UTC date. These modes cannot be combined.
+
+## Development
+
+- `pnpm run format`: Format source files.
+- `pnpm run typecheck`: Check TypeScript.
+- `pnpm run test`: Run unit tests with coverage.
+- `pnpm run ci`: Run all checks, builds, and tests.
+
+The project retains the create-template-project marker and generated tooling so template updates remain possible. Release tooling creates GitHub releases only; npm publishing is disabled.

package/commitlint.config.js

@@ -0,0 +1,5 @@
+const config = {
+	extends: ['@commitlint/config-conventional'],
+};
+
+export default config;