rekordbox-edit 0.7.0.dev69__tar.gz → 0.7.0.dev72__tar.gz

rekordbox_edit-0.7.0.dev72/.github/actions/build-release-notes/action.yml

@@ -0,0 +1,25 @@
+name: "Build Release Notes"
+description: "Generate categorized, per-commit release notes with each commit's PR resolved and its author credited"
+inputs:
+  from_tag:
+    description: "Tag to start the changelog range from (exclusive). Leave empty for full history."
+    required: false
+    default: ""
+  to_tag:
+    description: "Tag to end the changelog range at (inclusive)"
+    required: true
+  github_token:
+    description: "GitHub token for API access"
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Generate release notes
+      shell: bash
+      run: python3 "${GITHUB_ACTION_PATH}/build_release_notes.py"
+      env:
+        FROM_TAG: ${{ inputs.from_tag }}
+        TO_TAG: ${{ inputs.to_tag }}
+        OUTPUT_FILE: release-notes.md
+        REPO: ${{ github.repository }}
+        GH_TOKEN: ${{ inputs.github_token }}

rekordbox_edit-0.7.0.dev72/.github/actions/build-release-notes/build_release_notes.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Build categorized release notes from commits, linking each commit's PR.
+
+Lists one entry per commit (not per PR) between ``FROM_TAG`` (exclusive) and
+``TO_TAG`` (inclusive). Each entry links the pull request that introduced the
+commit and credits its author. The PR (number and author login) is resolved via
+``GET /repos/{repo}/commits/{sha}/pulls``, which works for both squash and
+rebase merges. Commits with no associated PR fall back to a short-SHA reference
+and the git author name.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+# Category matchers, evaluated in order; first match wins. Mirrors the
+# conventional-commit types accepted by the project's commitizen schema.
+_BREAKING_TITLE = re.compile(r"^(BREAKING(\(.*\))?:|(\w+)?(\(.*\))?!:)")
+_BREAKING_BODY = re.compile(r"BREAKING[\- ]CHANGE")
+_CATEGORY_TITLE_RULES: list[tuple[str, re.Pattern[str]]] = [
+    ("## Features", re.compile(r"^feat(\(.*\))?:")),
+    ("## Fixes", re.compile(r"^fix(?!\(deps\))(\(.*\))?:")),
+    (
+        "## Chores",
+        re.compile(
+            r"^(chore(?!\(deps\))|refactor|ci|docs|style|perf|test|build)(\(.*\))?:"
+        ),
+    ),
+    ("## Dependency Updates", re.compile(r"^(chore|fix)\(deps\):")),
+]
+_BREAKING_TITLE_HEADER = "## Breaking Changes"
+_UNCATEGORIZED_HEADER = "## Uncategorized"
+_CATEGORY_ORDER = [
+    _BREAKING_TITLE_HEADER,
+    "## Features",
+    "## Fixes",
+    "## Chores",
+    "## Dependency Updates",
+    _UNCATEGORIZED_HEADER,
+]
+
+# Commits that are noise in a changelog: merge commits are dropped at the
+# ``git log`` level (--no-merges); version-bump commits are filtered here.
+_SKIP_SUBJECT = re.compile(r"^bump:")
+# A trailing "(#NN)" left by squash merges, stripped so it is not duplicated
+# alongside the resolved reference.
+_TRAILING_PR = re.compile(r"\s*\(#\d+\)\s*$")
+
+_RECORD_SEP = "\x1e"
+_FIELD_SEP = "\x1f"
+
+
+@dataclass
+class Commit:
+    sha: str
+    subject: str
+    body: str
+    author: str
+
+
+@dataclass
+class Category:
+    header: str
+    lines: list[str] = field(default_factory=list)
+
+
+def _run(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(args, capture_output=True, text=True, encoding="utf-8")
+
+
+def read_commits(from_tag: str, to_tag: str) -> list[Commit]:
+    rng = f"{from_tag}..{to_tag}" if from_tag else to_tag
+    fmt = _FIELD_SEP.join(["%H", "%s", "%b", "%an"]) + _RECORD_SEP
+    result = _run(["git", "log", "--no-merges", f"--format={fmt}", rng])
+    if result.returncode != 0:
+        raise SystemExit(f"git log failed for range '{rng}': {result.stderr.strip()}")
+
+    commits: list[Commit] = []
+    for record in result.stdout.split(_RECORD_SEP):
+        record = record.strip("\n")
+        if not record:
+            continue
+        sha, subject, body, author = (record.split(_FIELD_SEP) + ["", "", ""])[:4]
+        commits.append(
+            Commit(
+                sha=sha,
+                subject=subject.strip(),
+                body=body.strip(),
+                author=author.strip(),
+            )
+        )
+    return commits
+
+
+def resolve_pr(repo: str, sha: str) -> tuple[int, str] | None:
+    """Return the (number, author_login) of a commit's PR, or None if unresolved."""
+    result = _run(["gh", "api", f"repos/{repo}/commits/{sha}/pulls"])
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    try:
+        prs = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return None
+    merged = [pr for pr in prs if pr.get("merged_at")]
+    chosen = merged[0] if merged else (prs[0] if prs else None)
+    if not chosen:
+        return None
+    login = (chosen.get("user") or {}).get("login", "")
+    return chosen["number"], login
+
+
+def categorize(commit: Commit) -> str:
+    if _BREAKING_TITLE.match(commit.subject) or _BREAKING_BODY.search(commit.body):
+        return _BREAKING_TITLE_HEADER
+    for header, pattern in _CATEGORY_TITLE_RULES:
+        if pattern.match(commit.subject):
+            return header
+    return _UNCATEGORIZED_HEADER
+
+
+def render_line(commit: Commit, repo: str) -> str:
+    subject = _TRAILING_PR.sub("", commit.subject)
+    pr = resolve_pr(repo, commit.sha)
+    if pr is not None:
+        number, login = pr
+        credit = f"#{number} by @{login}" if login else f"#{number}"
+        return f"- {subject} ({credit})"
+    return f"- {subject} ({commit.sha[:7]} by {commit.author})"
+
+
+def build_notes(commits: list[Commit], repo: str) -> str:
+    categories = {header: Category(header) for header in _CATEGORY_ORDER}
+    for commit in commits:
+        if _SKIP_SUBJECT.match(commit.subject):
+            continue
+        categories[categorize(commit)].lines.append(render_line(commit, repo))
+
+    sections = [
+        f"{cat.header}\n" + "\n".join(cat.lines)
+        for header in _CATEGORY_ORDER
+        if (cat := categories[header]).lines
+    ]
+    return "\n\n".join(sections) if sections else "_No changes._"
+
+
+def main() -> None:
+    to_tag = os.environ.get("TO_TAG", "").strip()
+    if not to_tag:
+        raise SystemExit("TO_TAG is required")
+    from_tag = os.environ.get("FROM_TAG", "").strip()
+    repo = os.environ.get("REPO") or os.environ.get("GITHUB_REPOSITORY", "")
+    if not repo:
+        raise SystemExit("REPO (or GITHUB_REPOSITORY) is required")
+    output_file = os.environ.get("OUTPUT_FILE", "release-notes.md")
+
+    commits = read_commits(from_tag, to_tag)
+    notes = build_notes(commits, repo)
+    with open(output_file, "w", encoding="utf-8") as handle:
+        handle.write(notes + "\n")
+    print(notes, file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/.gitignore

@@ -48,9 +48,7 @@ Thumbs.db
 .coverage
 
 .claude
-docs/superpowers
-docs/decisions
-research
+ai-docs
 
 # MkDocs build output
 site/

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/AGENTS.md

@@ -91,7 +91,10 @@ Every module should get and use its own `logger` for all logging purposes and fo
 - Commit descriptions should be terse and use active tenses (e.g. "add feature")
 - Commit bodies are completely optional, and should be used to describe changes when they aren't easily inferred by the main message, they should not include agent conversation context, decisions, or plan notes.
 - The agent may commit. But the user always handles pushes, PR creation, and rebases after merges.
-- Do not commit spec, brainstorming, or design documents (e.g. anything under `docs/superpowers/specs/`).
+- Do not commit spec, brainstorming, or design documents (e.g. anything under `ai-docs/`).
+- **Save plans to:** `ai-docs/YYYYMMDD-HHmm-{session-slug}/plan.md` instead of the plugin or skill presets.
+- **Save specs to:** `ai-docs/YYYYMMDD-HHmm-{session-slug}/specs.md` instead of the plugin or skill presets.
+- **Save decision records to:** `ai-docs/decisions/{topic}.md` (not session-scoped).
 
 ## Tooling
 

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/CHANGELOG.md

@@ -1,6 +1,9 @@
-## v0.7.0.dev69 (2026-07-31)
+## v0.7.0.dev72 (2026-07-31)
 
 
+- ci: more precise changelogs on releases
+- chore: update AGENTS.md
+- docs: pave FAQ page based on convert + analysis research
 - feat(convert): verify source codec against FileType before converting
 - test(cli): mock rekordbox pid check in edit CLI tests
 - feat: add probe/file-type matcher and codec_mismatch skip reason

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rekordbox-edit
-Version: 0.7.0.dev69
+Version: 0.7.0.dev72
 Summary: Tools for managing and modifying a RekordBox library en-masse
 Project-URL: Homepage, https://github.com/jviall/rekordbox-edit
 Project-URL: Repository, https://github.com/jviall/rekordbox-edit

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/docs/commands/convert.md

@@ -1,6 +1,6 @@
 # convert
 
-Convert audio files between formats and update the Rekordbox database to point at the new files. Your cues, analysis, beatgrids, and all metadata are preserved.
+Convert audio files between formats and update the Rekordbox database to point at the new files. Cues, analysis, beatgrids, and all other metadata are preserved — see [Frequently Asked Questions](../faqs.md) for more info.
 
 ## Supported Formats
 
@@ -50,6 +50,7 @@ rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
 ### Guardrails
 - Without flags, `convert` shows every planned change and asks once before applying. `--interactive` confirms each track individually; `--dry-run` previews without writing; `--yes` confirms the default choice for all prompts without asking.
 - Editing while Rekordbox is open risks corrupting your database. By default `convert` warns and asks for confirmation (defaulting to no, so a `--yes` would exit); in a non-interactive mode (e.g. `--print ids`) it throws an error.
+- Before a large run, walk through the checklist in [What Should I Do Before Converting?](../faqs.md#what-should-i-do-before-converting)
 
 ## Reference
 

rekordbox_edit-0.7.0.dev72/docs/faqs.md

@@ -0,0 +1,50 @@
+# Frequently Asked Questions
+
+Messing with your Rekordbox library is bound to raise some questions and concerns, particularly around preserving all the manual work you've done to organize, catalog, and prepare your library for gigs. This page is dedicated to answering those questions around what the impact and risks are of editing your rekordbox library or the underlying audio files using rekordbox-edit. If your question isn't answered here, please ask it in [a discussion](https://github.com/jviall/rekordbox-edit/discussions/new/choose).
+
+## How Does Rekordbox's Analysis Work?
+
+Analysis touches two places in your library. The database gets the summary values for things like tempo, key, and the flags Rekordbox uses to track analysis state. The heavier artifacts live in a per-track folder of analysis files (.ANLZ) containing the beat grid, waveforms, and phrase data. Your cues and loops live in neither; they are separate database records that only your own edits change.
+
+What analysis writes is a deterministic estimate. Deterministic, because the same file analyzed twice produces byte-identical results. An estimate, because tempo, grid, and key are inferred from the audio, and Rekordbox's inference is sometimes wrong. Both aspects are worth considering; when the analysis of a converted file produces a different result, it is simply a different estimate from different data.
+
+## How Does Converting a Track Affect the Analysis?
+
+The reason conversion is safe comes down to how Rekordbox stores analysis: positions are timestamps. The beat grid is a list of times in milliseconds, cues are stored in milliseconds, and phrases are anchored to beats. None of it references sample counts or byte positions in the audio file. Change the codec, the sample rate, or the bit depth, and every stored position still names the same musical moment.
+
+`rbe convert` therefore only has to update what identifies the file: the track's database row (the file path, sample rate, bit depth, and similar columns) and the path recorded inside the analysis files. It rewrites nothing else.
+
+There are a few minor things left stale by a conversion (without any consequence that I have observed yet):
+
+- The waveform still draws the old audio: identical unless you converted to MP3, and then only imperceptibly off.
+- A FLAC-specific seek index goes stale when you convert away from FLAC, which would be removed on any later analysis.
+
+Converting *to* FLAC does not create that seek index automatically either; only an analysis can. I have *not* tested (yet) whether that matters in practice, but it makes a stronger case for re-analyzing after a conversion to FLAC than for other targets. FLAC also is not the most ideal target format in general for Rekordbox (even though it's preferred for streaming and music hoarders), because only the more recent Pioneer devices support it. AIFF is what I would pick if you insist on lossless.
+
+## Does Converting to MP3 Shift the Audio?
+
+No. `rbe` uses LAME's gapless-playback encoding to avoid any start-of-file offset, and across many tests the MP3 320 output never differed in timing, sample for sample, from its lossless source. Cues and the beat grid stay exactly in register.
+
+The only artifact is visual: the drawn waveform still reflects the lossless original rather than the MP3. A re-analysis would redraw it, but you'd be hard-pressed to notice the difference.
+
+## Will My Cues and Beatgrid Survive?
+
+Yes. Cues, loops, and memory points are records in your library database, positioned in milliseconds and attached to the track's database entry, and `rbe convert` does not touch them. The beat grid lives in the analysis files, which convert also leaves alone. In all my testing, every cue and beat grid has been completely unchanged by a conversion, and works just as it did prior.
+
+This includes hand-tuned grids. Because convert never rewrites the grid a manually corrected beat grid survives conversion unchanged. The one operation that can replace it is a re-analysis you run yourself; see below.
+
+## Should I Re-Analyze After Converting?
+
+You do not need to. The existing analysis remains correct for the converted file, and Rekordbox never re-analyzes on its own; it waits for you to ask. Skipping re-analysis keeps your grid and cues exactly as they are.
+
+If you do re-analyze, the outcome depends on whether the conversion changed the audio samples. A pure container swap (WAV to FLAC or AIFF at the same depth and rate) reproduces the previous analysis exactly. A conversion that resamples, reduces bit depth, or lossily compresses to MP3 produces a slightly different estimate: about half a BPM of tempo difference, a first beat shifted by tens of milliseconds, cues sitting up to roughly 20 ms off the new grid. The new grid is not necessarily more or less correct than the previous; your ears and eyes will be the best judges of that. Ultimately it is the same song being analyzed, but Rekordbox made a fresh estimate on different underlying data. I would argue, though, that an analysis of a high-res file is more likely to be accurate than one of a lower-fidelity file.
+
+One real hazard: re-analysis replaces manually edited beat grids on any track that is not locked. If you plan to re-analyze after a bulk conversion, turn on Analysis Lock first for tracks whose grids you have tuned by hand.
+
+## What Should I Do Before Converting?
+
+- **Preview with `--dry-run`.** See exactly which tracks will convert and where the files will go before anything is written.
+- **Close Rekordbox.** Writing to the database while Rekordbox has it open risks corruption.
+- **Make fresh backups of your music and your Rekordbox database.** Conversion rewrites files and database rows in place; a current backup makes any surprise reversible.
+- **Keep your originals until you are satisfied.** The default `--delete-originals lossless` only deletes a source when no audio information was lost. Be deliberate before choosing `all`.
+- **Lock hand-tuned beat grids if you plan to re-analyze.** Conversion won't mess with your grids, but a later bulk re-analysis replaces grids on unlocked tracks. Analysis Lock exists for exactly this.

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/docs/filtering.md

@@ -104,4 +104,4 @@ rbe search --artist "Daft Punk" --artist "Justice" --print ids \
   | rbe convert --format-out mp3 --dry-run
 ```
 
-For richer pipelines, `--print json` emits the same selection as structured data for `jq` and other shell tools. Use the [API functions](/api/#functions) if you want to build a more complex python script.
+For richer pipelines, `--print json` emits the same selection as structured data for `jq` and other shell tools. Use the [API functions](api.md#functions) if you want to build a more complex python script.

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/mkdocs.yml

@@ -4,9 +4,6 @@ site_url: https://rekordbox-edit.readthedocs.io/
 repo_url: https://github.com/jviall/rekordbox-edit
 repo_name: jviall/rekordbox-edit
 
-exclude_docs: |
-  superpowers/
-
 theme:
   name: material
   palette:
@@ -60,4 +57,5 @@ nav:
       - search: commands/search.md
       - edit: commands/edit.md
       - convert: commands/convert.md
+  - FAQs: faqs.md
   - API Reference: api.md

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.7.0.dev69"
+version = "0.7.0.dev72"
 description = "Tools for managing and modifying a RekordBox library en-masse"
 authors = [{ name = "James Viall", email= "jamesviall@pm.me"}]
 license = "MIT"
@@ -91,8 +91,8 @@ message_template = "{{change_type}}{{scope}}: {{message}}"
 example = "feat(convert): add new conversion feature"
 schema = "<type>(<scope>): <body>"
 schema_pattern = "^(BREAKING|feat|fix|refactor|ci|test|docs|chore)(\\([^)]*\\))?!?: .+"
-bump_pattern = "^(BREAKING|feat|fix|perf|hotfix|refactor)"
-bump_map = { "BREAKING" = "MAJOR", "feat" = "MINOR", "fix" = "PATCH", "refactor" = "PATCH" }
+bump_pattern = "^((BREAKING[\\-\\ ]CHANGE|BREAKING|feat|fix|perf|hotfix|refactor)(\\(.+\\))?!?):"
+bump_map = { "^.+!$" = "MAJOR", "^BREAKING" = "MAJOR", "^feat" = "MINOR", "^fix" = "PATCH", "^refactor" = "PATCH" }
 
 [[tool.commitizen.customize.questions]]
 type = "list"

{rekordbox_edit-0.7.0.dev69 → rekordbox_edit-0.7.0.dev72}/uv.lock

@@ -1268,7 +1268,7 @@ wheels = [
 
 [[package]]
 name = "rekordbox-edit"
-version = "0.7.0.dev69"
+version = "0.7.0.dev72"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

rekordbox_edit-0.7.0.dev69/.github/actions/build-release-notes/action.yml

@@ -1,88 +0,0 @@
-name: "Build Release Notes"
-description: "Generate categorized release notes from conventional commits between two tags"
-inputs:
-  from_tag:
-    description: "Tag to start the changelog range from (exclusive)"
-    required: true
-  to_tag:
-    description: "Tag to end the changelog range at (inclusive)"
-    required: true
-  github_token:
-    description: "GitHub token for API access"
-    required: true
-runs:
-  using: "composite"
-  steps:
-    - uses: mikepenz/release-changelog-builder-action@c9bcd8238b6f41e05561348339429d360b1c0247 # v6.2.3
-      with:
-        outputFile: release-notes.md
-        configurationJson: |
-          {
-            "categories": [
-              {
-                "title": "## Breaking Changes",
-                "labels": [],
-                "rules": [
-                  {
-                    "pattern": "^(\\w+)?(\\(.*\\))?!:",
-                    "on_property": "title"
-                  }
-                ]
-              },
-              {
-                "title": "## Features",
-                "labels": [],
-                "rules": [
-                  {
-                    "pattern": "^feat(\\(.*\\))?:",
-                    "on_property": "title"
-                  }
-                ]
-              },
-              {
-                "title": "## Fixes",
-                "labels": [],
-                "rules": [
-                  {
-                    "pattern": "^fix(?!\\(deps\\))(\\(.*\\))?:",
-                    "on_property": "title"
-                  }
-                ]
-              },
-              {
-                "title": "## Chores",
-                "labels": [],
-                "rules": [
-                  {
-                    "pattern": "^(chore(?!\\(deps\\))|refactor|ci|docs|style|perf|test|build)(\\(.*\\))?:",
-                    "on_property": "title"
-                  }
-                ]
-              },
-              {
-                "title": "## Dependency Updates",
-                "labels": [],
-                "rules": [
-                  {
-                    "pattern": "^(chore|fix)\\(deps\\):",
-                    "on_property": "title"
-                  }
-                ]
-              }
-            ],
-            "exhaustive": true,
-            "sort": {
-              "order": "ASC",
-              "on_property": "title"
-            },
-            "template": "#{{CHANGELOG}}\n\n## Uncategorized\n#{{UNCATEGORIZED}}",
-            "pr_template": "- #{{TITLE}} (##{{NUMBER}} by @#{{AUTHOR}})",
-            "empty_template": "- No changes",
-            "tag_resolver": {
-              "method": "sort"
-            }
-          }
-        fromTag: ${{ inputs.from_tag }}
-        toTag: ${{ inputs.to_tag }}
-      env:
-        GITHUB_TOKEN: ${{ inputs.github_token }}