Feature/file based project

.claude/commands/improve-pr-coverage.md

@@ -0,0 +1,29 @@
+Improve test coverage for this PR's changed code.
+
+Follow these steps in order:
+
+1. **Identify PR scope:** Run `git diff main...HEAD --name-only` to find all files changed in this branch. These are the only files you should care about. Exclude anything in the `legacy` namespace entirely.
+
+2. **Understand what changed:** Read the changed files and build a mental model of the new/modified features, public APIs, branching logic, and edge cases introduced by this PR.
+
+3. **Run coverage baseline:** Build and run the coverage tool in `tests/coverage` to generate a report. Parse the output to extract per-file and per-function coverage percentages for the changed files only.
+
+4. **Prioritize gaps:** From the changed files, rank uncovered or under-covered areas by size and importance:
+   - Prefer covering entire uncovered functions/methods over chasing individual branch misses
+   - Prefer public API surface over internal helpers
+   - Prefer complex branching logic and error handling over straight-line code
+   - Skip trivial getters/setters and boilerplate
+
+5. **Write tests:** Add or extend tests targeting the largest coverage gaps first. For each test:
+   - Place it in the appropriate existing test file/directory following the project's conventions
+   - Name it descriptively for what behavior it verifies
+   - Cover the happy path, then key error/edge cases
+   - Stop working on a file once it reaches ~85% coverage — do not chase 100%
+
+6. **Verify:** Re-run the coverage tool after writing tests. Confirm that the changed files are at or near 85%. If any file is still significantly below, do another pass on the biggest remaining gap only.
+
+**Constraints:**
+- Do NOT modify any source code — only add/edit test files
+- Do NOT touch or add tests for anything in the `legacy` namespace
+- Do NOT add tests for code outside the PR's changed files
+- Target 85% coverage on changed files, not the whole repo

.codecov.yml

@@ -9,3 +9,5 @@ ignore:
   - "modules/tracktion_core/3rd_party"
   - "modules/tracktion_graph/3rd_party"
   - "modules/tracktion_engine/3rd_party"
+  - "**/tracktion_ArchiveFile.*"
+  - "**/tracktion_ExportJob.*"

.github/workflows/generate_coverage.yaml

@@ -73,7 +73,9 @@ jobs:
             --exclude "modules/3rd_party/*" \
             --exclude "/Applications*" \
             --exclude "/usr*" \
-            --exclude "*examples*"
+            --exclude "*examples*" \
+            --exclude "*/tracktion_ArchiveFile.*" \
+            --exclude "*/tracktion_ExportJob.*"
 
       # - name: macOS coverage
       #   if: runner.os == 'macOS'
@@ -107,7 +109,7 @@ jobs:
 
       - name: Upload Linux coverage to Codecov
         if: runner.os == 'Linux'
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           files: ./tests/coverage/build/coverage.info
-          token: ${{ secrets.CODECOV_TOKEN_V4 }}
+          token: ${{ secrets.CODECOV_TOKEN_V5 }}

BREAKING-CHANGES.md

@@ -2,6 +2,132 @@
 
 ___
 
+### Change
+`TracktionArchiveFile` and `ExportJob` moved to `legacy::` namespace.
+
+#### Possible Issues
+Code using `TracktionArchiveFile` or `ExportJob` directly will no longer compile.
+
+#### Workaround
+Qualify with `legacy::` (e.g. `legacy::TracktionArchiveFile`). For new code, use `ArchiveJob` instead, which produces standard zip files. Use `isArchive()` and `isLegacyArchive()` to detect archive formats.
+
+#### Rationale
+The legacy `.trkarch` format is replaced by standard zip archives. The old classes are preserved in a `legacy::` namespace for reading existing archives.
+
+___
+
+### Change
+`ProjectSearchIndex`, `SearchOperation`, and related APIs have been removed.
+
+#### Possible Issues
+Code using `ProjectSearchIndex`, `SearchOperation`, `createSearchForKeywords()`, or `Project::searchFor()` will no longer compile. The header `tracktion_ProjectSearchIndex.h` has been deleted.
+
+#### Workaround
+Use plain string matching or Levenshtein distance on project item names/descriptions.
+
+#### Rationale
+The search infrastructure was tightly coupled to file-based project internals and not applicable to folder-based projects. Simpler alternatives are sufficient.
+
+___
+
+### Change
+`Edit::createEditForExamining(Engine&, ValueTree, EditRole, LoadContext*)` overload is now `[[deprecated]]`.
+
+#### Possible Issues
+Deprecation warnings when calling this overload.
+
+#### Workaround
+Use `loadEditForExamining(ProjectManager&, ProjectItemRef)` instead.
+
+#### Rationale
+The new function works with both file-based and folder-based projects and handles source resolution correctly.
+
+___
+
+### Change
+`Project::getAllItemIDs()` has been removed.
+
+#### Possible Issues
+Code that calls `getAllItemIDs()` will no longer compile.
+
+#### Workaround
+Use `getAllProjectItemRefs()` instead to iterate over project items.
+
+#### Rationale
+The method was unused and redundant with `getAllProjectItemRefs()`.
+
+___
+
+### Change
+`ProjectItemRef::getProjectItemID()` now returns `std::optional<ProjectItemID>` instead of a bare `ProjectItemID`.
+
+#### Possible Issues
+Code that chains method calls on the return value (e.g. `.isValid()`, `.getProjectID()`, `.getRawID()`) will no longer compile.
+
+#### Workaround
+Use `has_value()` or bool conversion instead of `.isValid()`. Use `->` to access members when the optional is known to contain a value (e.g. `pid->getProjectID()`). Use `*` to extract the value when passing to functions that expect `ProjectItemID`.
+
+#### Rationale
+Returning `std::optional` makes the fallibility explicit at the type level, preventing accidental use of an invalid `ProjectItemID`.
+
+___
+
+### Change
+`Project::getProjectID()` now returns `ProjectID` instead of `int`. `ProjectItemID` constructors and `createNewID` take `ProjectID` instead of `int`. `ProjectManager::getProject()` takes `ProjectID` instead of `int`.
+
+#### Possible Issues
+Code that stores or passes project IDs as raw `int` values will no longer compile.
+
+#### Workaround
+Wrap raw ints with `ProjectID(myInt)` and extract with `.toInt()`. For example: `ProjectID pid = project.getProjectID();` instead of `int pid = project.getProjectID();`.
+
+#### Rationale
+A strong type prevents accidental misuse of raw integers as project identifiers and makes the API self-documenting.
+
+___
+
+### Change
+`ProjectItemRef` replaces raw `ProjectItemID` in many APIs. `Project::getProjectItemRef()`, `getProjectItemFor()`, `removeProjectItem()`, and `getIndexOf()` now use `ProjectItemRef`. `ProjectItem::getProjectItemRef()` returns `const ProjectItemRef&`. `ProjectManager::getProjectItem()` and `findSourceFile()` have new `ProjectItemRef` overloads.
+
+#### Possible Issues
+Code that explicitly types return values as `ProjectItemID` from these methods will no longer compile.
+
+#### Workaround
+`ProjectItemRef` has an implicit constructor from `ProjectItemID`, so most call sites compile unchanged. For return values, use `auto` or `ProjectItemRef`. If you need the old type, call `.getProjectItemID()` on the ref after checking `isProjectItemID()`.
+
+#### Rationale
+`ProjectItemRef` supports both ID-based references (file-based projects) and path-based references (folder-based projects) in a single type.
+
+___
+
+### Change
+`ProjectManager::createNewProject`, `createNewProjectInteractively`, `createNewProjectFromTemplate`, and the `TempProject` constructor now accept a `ProjectType` parameter (`ProjectType::fileBased` or `ProjectType::folderBased`).
+
+#### Possible Issues
+None for existing code — the parameter defaults to `ProjectType::fileBased`.
+
+#### Workaround
+No changes required. Pass `ProjectType::folderBased` to create folder-based projects.
+
+#### Rationale
+Enables creation of folder-based projects through the existing project creation APIs.
+
+___
+
+### Change
+`Project::findOrphanItems()` has been deprecated in favour of `findOrphanItemRefs()`.
+
+#### Possible Issues
+Deprecation warnings when calling `findOrphanItems()`.
+
+#### Workaround
+Replace `findOrphanItems()` with `findOrphanItemRefs()`, which returns `juce::Array<ProjectItemRef>` instead of `juce::Array<ProjectItem::Ptr>`.
+
+#### Rationale
+The new method returns `ProjectItemRef` values that work with both file-based and folder-based project backends.
+
+___
+
 ### Change
 `AudioClipBase::melodyneProxy` public member has been removed. Use the new `getARAProxy()` accessor instead.
 

README.md

@@ -104,3 +104,4 @@ Tracktion Engine utilises and contains copies of the following libraries. Please
 - [magic_enum](https://www.github.com/Neargye/magic_enum) - MIT
 - [farbot](https://www.github.com/hogliux/farbot) - MIT
 - [doctest](https://www.github.com/doctest/doctest) - MIT
+- [signalsmith-stretch](https://www.github.com/Signalsmith-Audio/signalsmith-stretch) - MIT