Skip to content

1.0.0 - #81

Merged
rtuszik merged 26 commits into
mainfrom
organize
Nov 2, 2026
Merged

rtuszik merged 26 commits into
mainfrom
organize

Conversation

@rtuszik

@rtuszik rtuszik commented May 28, 2026 •

Copy link
Copy Markdown
Owner

Theming

  • 6 built-in themes (catppuccin, dracula, gruvbox, nord, rose-pine, solarized)
  • Per-cheatsheet theme, custom CSS files, inline overrides
  • Theme tokens documented and validated

Dev tooling

  • uv for deps; Ruff via pre-commit
  • mise.toml tasks: install, lint, test, validate
  • Playwright browser tests
  • CI: lint, type check, dead code, coverage

Packaging/release

  • koalakeys entrypoint, uv_build backend
  • Release Please for versioning and PyPI publishing

Docs

  • Expanded README: quickstart, usage, theming
  • New theme docs and THIRD_PARTY_LICENSES.md (palettes, fonts)

Schema

  • JSON schema supports theme/CSS options, better field docs

@socket-security

socket-security Bot commented May 28, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Updatedvulture@​2.14 ⏵ 2.16100100100100100
Updatedruamel-yaml@​0.18.16 ⏵ 0.19.1100100100100100
Updatedpytest-cov@​7.0.0 ⏵ 7.1.0100100100100100
Addedprek@​0.5.9100100100100100
Updatedty@​0.0.11 ⏵ 0.0.95100 +1100100100100
Updatedruff@​0.14.14 ⏵ 0.17.3100 +1100100100100
Addedpytest-playwright@​0.10.0100100100100100
Addedpytest-playwright@​0.7.1100100100100100

View full report

@socket-security

This comment was marked as outdated.

@github-actions

github-actions Bot commented May 28, 2026 •

Copy link
Copy Markdown
Contributor

Coverage

Coverage Report
FileStmtsMissCoverMissing
src/koalakeys
   cli.py67297%57, 106
   generate_cheatsheet.py2182987%56–57, 109–111, 126–127, 151–153, 197–199, 208–210, 220–221, 225, 229, 235–236, 267–268, 272–273, 277–278, 295
   logger.py35391%21, 42–43
   template_renderer.py16288%20–21
   theming.py1821592%114, 137, 168–171, 173, 179, 182, 186, 216, 239, 264, 291, 300
TOTAL7035193% 
Tests Skipped Failures Errors Time
198 0 💤 0 ❌ 0 🔥 3.209s ⏱️

@rtuszik rtuszik changed the title Organize 1.0.0 Jun 9, 2026
@rtuszik

This comment was marked as outdated.

@coderabbitai

This comment was marked as outdated.

@coderabbitai

coderabbitai Bot commented Jun 22, 2026 •

Copy link
Copy Markdown

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review
Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 6277b162-a2b1-4660-9533-c10cec8d592d
Commits

Reviewing files that changed from the base of the PR and between e180560 and 849c7b9.

Files selected for processing: 7
  • docs/themes.md
  • src/koalakeys/cli.py
  • src/koalakeys/templates/cheatsheets/assets/cheatsheets.css
  • src/koalakeys/themes/catppuccin.yaml
  • tests/test_browser.py
  • tests/test_cli.py
  • yaml_cheatsheet_spec.md
Files skipped from review as they are similar to previous changes: 3
  • src/koalakeys/themes/catppuccin.yaml
  • src/koalakeys/templates/cheatsheets/assets/cheatsheets.css
  • yaml_cheatsheet_spec.md

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

Walkthrough

The package adds theme-aware cheatsheet generation, six built-in themes, user-theme inheritance, and commands to initialise projects, generate output, and validate cheatsheets. It also updates templates, packaging, tests, documentation, CI workflows, and release automation.

Changes: KoalaKeys theme and generation workflow

Layer / File(s) Summary
Theme definitions and resolution
src/koalakeys/theming.py, src/koalakeys/themes/*, docs/schema/cheatsheet.schema.json, src/koalakeys/validate_yaml.py, yaml_cheatsheet_spec.md, tests/test_theming.py, tests/test_validate_yaml.py
Adds theme resolution, inheritance, token validation, and CSS sanitisation. Adds six built-in theme definitions and validates theme and custom CSS fields. The schema and guide describe these options.
Theme-aware generation and rendering
src/koalakeys/generate_cheatsheet.py, src/koalakeys/templates/*, src/koalakeys/layouts/*, src/koalakeys/logger.py, src/koalakeys/template_renderer.py, tests/test_generate_cheatsheet.py, tests/test_integration.py, tests/test_browser.py, tests/conftest.py
Generation resolves theme and custom CSS data for rendering. Templates apply theme tokens and conditionally render dark-mode controls. The package adds keyboard layouts and platform key mappings. Tests cover generated output and browser interactions.
CLI, scaffolding, and validation
src/koalakeys/cli.py, src/koalakeys/scaffold/*, src/koalakeys/validate_yaml.py, tests/test_cli.py, tests/test_scaffold.py
Adds init, generate, and validate commands. init writes a starter cheatsheet and can skip or replace an existing example. Validation checks styling fields and rejects non-mapping YAML documents.
Packaging, documentation, and automation
pyproject.toml, .pre-commit-config.yml, pytest.ini, mise.toml, .github/actions/setup-python/action.yml, .github/workflows/*, .release-please-manifest.json, release-please-config.json, README.md, THIRD_PARTY_LICENSES.md
Adds the koalakeys entry point and build configuration. Updates development tooling and documents installation, usage, themes, and third-party licences. Adds release automation, adjusts workflow permissions and checkout credentials, and configures browser tests for pull requests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Merge Risk: Moderate · previous review 849c7

The Windows test failure should be fixed before merging. PowerShell users can also receive a next-step command that enters the wrong directory, and the CSS documentation needs correction.

Pre-merge checks: Passed 3 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Title check Inconclusive The title is a version number and does not identify the main changes, such as the new CLI, package structure, theming support, or release workflow. Replace the title with a concise description of the primary change, such as "Add CLI, theming, and package structure support".
Passed Passed checks: 3 passed
Check name Status Explanation
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description accurately summarises the pull request changes, including theming, development tooling, packaging, release automation, documentation, and schema updates.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

coderabbitai[bot]

This comment was marked as outdated.

coderabbitai[bot]

This comment was marked as outdated.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (2)

Major · Replace the flagged prek release before merge. · pyproject.toml:14

pyproject.toml:14
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Replace the flagged prek release before merge.

uv.lock resolves the development dependency to prek==0.3.6 and records PyPI distribution URLs and hashes. This is the release flagged by Socket Security. Replace it with a vetted release and regenerate uv.lock, or remove the dependency.

Minor · Correct the current-directory statement. · README.md:95

README.md:95
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Correct the current-directory statement.

init [path] can scaffold a directory other than the current directory. State that generate and validate use the current directory, while init uses its path argument.

🔇 Additional comments: 2
pyproject.toml: 1

3-10: LGTM!

Also applies to: 13-13, 15-20, 23-29, 34-37, 64-81

README.md-15-15: 1

15-15: Minor · Maintainability & Code Quality · Quick win

⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Split the quick-start instruction into separate steps.

The punctuation makes the command sequence unclear. LanguageTool also reports DOUBLE_PUNCTUATION on this line. Use separate sentences or an ordered list.

Source: Linters/SAST tools


Review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: b7a4da03-740a-43b1-bfd0-f945d6ed974f
Commits

Reviewing files that changed from the base of the PR and between 3b31401 and fb76c1a.

Files ignored due to path filters: 1
  • uv.lock is excluded by !**/*.lock
Files selected for processing: 2
  • README.md
  • pyproject.toml

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


Review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8b36972f-54a1-4187-bcbc-3cb9199432c0
Commits

Reviewing files that changed from the base of the PR and between fb76c1a and 8989865.

Files ignored due to path filters: 2
  • assets/images/KoalaKeys_Example.png is excluded by !**/*.png
  • uv.lock is excluded by !**/*.lock
Files selected for processing: 52
  • .github/actions/setup-python/action.yml
  • .github/workflows/lint.yml
  • .github/workflows/pytest.yml
  • .pre-commit-config.yml
  • README.md
  • docs/schema/cheatsheet.schema.json
  • pyproject.toml
  • pytest.ini
  • src/koalakeys/__init__.py
  • src/koalakeys/cli.py
  • src/koalakeys/generate_cheatsheet.py
  • src/koalakeys/layouts/keyboard_layouts.yaml
  • src/koalakeys/layouts/system_mappings.yaml
  • src/koalakeys/logger.py
  • src/koalakeys/scaffold/__init__.py
  • src/koalakeys/scaffold/example.yaml
  • src/koalakeys/template_renderer.py
  • src/koalakeys/templates/base.html
  • src/koalakeys/templates/cheatsheets/assets/cheatsheets.css
  • src/koalakeys/templates/cheatsheets/cheatsheet-template.html
  • src/koalakeys/templates/cheatsheets/components/body.html
  • src/koalakeys/templates/cheatsheets/scripts/main.js
  • src/koalakeys/templates/index/assets/index.css
  • src/koalakeys/templates/index/components/body.html
  • src/koalakeys/templates/index/components/footer.html
  • src/koalakeys/templates/index/index_template.html
  • src/koalakeys/templates/index/scripts/main.js
  • src/koalakeys/themes/catppuccin.yaml
  • src/koalakeys/themes/dracula.yaml
  • src/koalakeys/themes/gruvbox.yaml
  • src/koalakeys/themes/nord.yaml
  • src/koalakeys/themes/rose-pine.yaml
  • src/koalakeys/themes/solarized.yaml
  • src/koalakeys/theming.py
  • src/koalakeys/validate_yaml.py
  • src/layouts/keyboard_layouts.yaml
  • src/layouts/system_mappings.yaml
  • src/templates/cheatsheets/assets/cheatsheets.css
  • src/templates/cheatsheets/cheatsheet-template.html
  • src/templates/index/assets/index.css
  • tests/__init__.py
  • tests/conftest.py
  • tests/test_browser.py
  • tests/test_cli.py
  • tests/test_generate_cheatsheet.py
  • tests/test_integration.py
  • tests/test_replace_shortcut_names.py
  • tests/test_scaffold.py
  • tests/test_template_renderer.py
  • tests/test_theming.py
  • tests/test_validate_yaml.py
  • yaml_cheatsheet_spec.md
Files with no reviewable changes: 11
  • src/koalakeys/templates/index/components/body.html
  • tests/init.py
  • src/koalakeys/init.py
  • src/layouts/system_mappings.yaml
  • src/koalakeys/templates/index/components/footer.html
  • src/koalakeys/templates/index/scripts/main.js
  • src/templates/index/assets/index.css
  • src/templates/cheatsheets/assets/cheatsheets.css
  • src/templates/cheatsheets/cheatsheet-template.html
  • src/layouts/keyboard_layouts.yaml
  • src/koalakeys/templates/index/index_template.html
Files skipped from review as they are similar to previous changes: 1
  • src/koalakeys/templates/index/assets/index.css

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

Comment thread README.md Resolved
Comment thread src/koalakeys/cli.py Resolved
Comment thread src/koalakeys/cli.py Resolved
Comment thread src/koalakeys/theming.py Resolved
Comment thread src/koalakeys/theming.py Resolved
Comment thread src/koalakeys/theming.py Resolved
Comment thread yaml_cheatsheet_spec.md Outdated
sheet exactly like a built-in: `theme: my-dracula`.

The full token list (all color, typography, and spacing tokens a theme can set)
is documented in [docs/themes/tokens.md](docs/themes/tokens.md).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Maintainability & Code Quality · Quick win

🔎 Supported by static analysis

Script executed:

#!/bin/bash
fd -i 'tokens.md' docs
rg -n 'docs/themes/tokens.md' --glob '*.md' --glob '*.yaml' --glob '*.css'

Repository: rtuszik/KoalaKeys

Length of output: 453


Script executed:

test -e docs/themes/tokens.md && echo "target: present" || echo "target: absent"
test -d docs && echo "docs dir: present" || echo "docs dir: absent"
ls -la docs 2>&1 || true
git ls-files | rg -i 'tokens' || test "$?" -eq 1
git ls-files | rg -i '^docs/' || test "$?" -eq 1

Repository: rtuszik/KoalaKeys

Length of output: 379


Add the missing token reference or fix the broken link.

The link in yaml_cheatsheet_spec.md points to docs/themes/tokens.md, and that file does not exist in the checkout. The docs/ directory contains only docs/schema/cheatsheet.schema.json. Readers who follow the link reach a missing page. They cannot find the token list that the Theming section says is documented there.

Either add docs/themes/tokens.md or change the link to a document that exists. Also update the other references to the same path in src/koalakeys/themes/catppuccin.yaml:5 and src/koalakeys/templates/cheatsheets/assets/cheatsheets.css:5, so that they do not point to a missing file.

Comment thread .github/workflows/release.yml Resolved
Comment thread README.md Resolved
Comment thread release-please-config.json Resolved
Comment thread src/koalakeys/cli.py Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (2)

Minor · Add layout to the required top-level keys. · validate_yaml.py:17-23

src/koalakeys/validate_yaml.py:17-23
Minor · Functional Correctness · Quick win

Add layout to the required top-level keys.

validate_required_keys checks only title and shortcuts. validate_layout returns True when layout is absent. A cheatsheet without layout therefore passes validate_yaml, even though the spec lists layout as required.

Generation then continues with default values. main() calls the same validator through validate_and_lint, and get_layout_info assigns US and Darwin when layout is missing. The generated page can show the wrong keyboard and system without reporting an error. The file does not fail to generate.

Suggested fix
 def validate_required_keys(data):
-    required_keys = ["title", "shortcuts"]
+    required_keys = ["title", "layout", "shortcuts"]
     for key in required_keys:
         if key not in data:
             logger.error(f"Missing required top-level key: '{key}'")
             return False
     return True
Minor · Require both keys in a present layout object. · validate_yaml.py:68-70

src/koalakeys/validate_yaml.py:68-70
Minor · Data Integrity & Integration · Quick win

Require both keys in a present layout object.

{layout: {}} passes validate_yaml because validate_layout checks only keys that are present. This violates the schema and specification, which require both keyboard and system.

main then generates the cheatsheet. get_layout_info silently defaults the missing values to US and Darwin. This is independent of the top-level missing-layout case because the empty object takes the present-layout path.

Suggested fix
     if not isinstance(data["layout"], dict):
         logger.error("Layout must be a dictionary")
         return False
 
+    required_fields = ("keyboard", "system")
+    missing_fields = [field for field in required_fields if field not in data["layout"]]
+    if missing_fields:
+        logger.error(f"Layout must contain: {', '.join(missing_fields)}")
+        return False
+
     valid_keyboards = ["US", "UK", "DE", "FR", "ES", "DVORAK"]

Review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 9f3cd244-ea59-4613-9c53-8e0eb1362511
Commits

Reviewing files that changed from the base of the PR and between aef89e4 and 872316b.

Files ignored due to path filters: 2
  • assets/images/KoalaKeys_Example.png is excluded by !**/*.png
  • assets/images/KoalaKeys_Themes.png is excluded by !**/*.png
Files selected for processing: 2
  • README.md
  • THIRD_PARTY_LICENSES.md
Files skipped from review as they are similar to previous changes: 1
  • README.md

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

- templates: store darkMode only on toggle click so each sheet uses its
  theme default_mode until the visitor chooses
- cli: platform-specific quoting for the cd hint, mention uvx
- release-please: drop permanent release-as override

Release-As: 1.0.0

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up Comments

Outside diff Quote Windows shell metacharacters.

17-17: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Quote Windows shell metacharacters.

For a project named R&D, list2cmdline returns R&D without quotes. The printed cd R&D command is split at & by cmd, so it does not enter the project directory and can run an unintended command. Quote paths for the target shell and test a path containing &. (raw.githubusercontent.com)

Open the source location

Nitpick Cover the dark-default destination with a contrasting preference.

124-125: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the dark-default destination with a contrasting preference.

The dark sheet passes assert self._is_dark(page) from its default alone. It can ignore the saved "true" preference without failing this assertion. The later light-sheet assertion covers the opposite-default destination, so this is an additional test-coverage improvement, not a production defect. Save "false" before revisiting the dark sheet and assert that it remains light; checking localStorage alone is not sufficient.

Suggested test extension
         page.goto(sheets["light"])
         assert self._is_dark(page)
 
+        reverse_context = browser.new_context()
+        reverse_page = reverse_context.new_page()
+        reverse_page.goto(sheets["dark"])
+        reverse_page.click("#dark-mode-toggle")
+        assert not self._is_dark(reverse_page)
+        reverse_page.goto(sheets["light"])
+        reverse_page.goto(sheets["dark"])
+        assert not self._is_dark(reverse_page)
+        reverse_context.close()
+
         context.close()

Open the source location

Comment thread tests/test_cli.py Resolved
- quote paths with spaces or & | < > ^ ( ) , ; = on win32
- pin platform in POSIX quoting test
- test that a light choice overrides a dark-default sheet
Comment thread docs/themes.md Resolved
Comment thread src/koalakeys/cli.py Resolved
Comment thread tests/test_cli.py Resolved
@rtuszik
rtuszik merged commit 8283520 into main Nov 2, 2026
9 checks passed
@rtuszik
rtuszik deleted the organize branch November 2, 2026 21:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant