ts-flp 1.0.5 → 1.1.0

package/README.md

@@ -160,6 +160,14 @@ interface PluginRef {
 | `getFlVersion(parsed)`               | Get the FL Studio version string                   |
 | `getPPQ(parsed)`                     | Get the PPQ (Pulses Per Quarter note)              |
 
+### Write behavior
+
+- `undefined` leaves the corresponding value unchanged.
+- `null` clears text metadata, leaves BPM unchanged, and resets time values to zero.
+- Missing metadata and timestamp events are created in the project preamble.
+- BPM values are validated against the limits supported by the detected FL Studio version.
+- Invalid dates, negative work times, and non-finite numeric values throw an error.
+
 ## Constraints and limitations
 
 ### What this library does
@@ -197,6 +205,9 @@ src/
 # Install dependencies
 pnpm install
 
+# Add at least one private .flp file directly to test_projs/
+# These fixtures are ignored by Git and are required by the integration tests.
+
 # Type checking
 pnpm run typecheck
 
@@ -215,7 +226,7 @@ pnpm run build
 
 ## License
 
-[GPL-3.0](LICENSE)
+[MIT](LICENSE)
 
 ---
 
@@ -224,3 +235,40 @@ pnpm run build
 A huge thank you to **[@demberto](https://github.com/demberto)** ([PyFLP](https://github.com/demberto/PyFLP)), **[@monadgroup](https://github.com/monadgroup)** ([FLParser](https://github.com/monadgroup/FLParser)), and **FLPEdit** for their incredible reverse-engineering work on the FL Studio `.flp` format.
 
 This project would never have been possible without them.
+
+## Optional sample inspection
+
+Existing `listSamples(parsed)` remains synchronous and returns the same
+`{ eventIndex, path }` entries without accessing disk. Use the additive API:
+
+```typescript
+import { inspectSamples } from 'ts-flp';
+const samples = await inspectSamples(parsed, {
+  mode: 'check', // default: 'resolve', which does not access the filesystem
+  projectPath: '/music/Project/Song.flp',
+  searchRoots: [],
+});
+```
+
+Results preserve occurrences (`referenceIndex` is the original event index) and
+include `recordedPath`, `pathType`, `relativePath`, `candidates`, `resolvedPath`,
+`status`, and `reason`. Status is `unchecked`, `found`, `missing`, `unresolved`,
+`ambiguous`, or `inaccessible`. Found means a regular file, not validated audio.
+Missing means absent at the checked locations, not absent everywhere.
+
+Relative paths use explicit `projectRoot`, or the parent of `projectPath`.
+Context paths must be native absolute paths; no implicit cwd resolution.
+Foreign Windows paths on POSIX and unexpanded DAW placeholders remain unresolved.
+`searchRoots` opt into recursive discovery in check mode only; name-only matches
+remain suggestions (`confidence: 'name-only'`) and never resolve automatically.
+Multiple existing exact candidates also remain ambiguous.
+
+Checks are asynchronous with `concurrency` (default 8, maximum 64), optional
+`signal` cancellation, per-call caching and `maxSearchEntries` (default 100,000).
+Directory symlinks encountered during search are not traversed. No project or
+sample files are modified. Dependency files hidden inside plugin state are not
+inventoried by this API. The result is a filesystem snapshot and can become stale.
+
+Release preparation: after building, run `pnpm run check:package` to inspect a
+real npm archive, install it in isolation and verify ESM/CommonJS imports.
+This does not publish a package or change its version.

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   getEventString: () => getEventString,
   getFlVersion: () => getFlVersion,
   getPPQ: () => getPPQ,
+  inspectSamples: () => inspectSamples,
   listPlugins: () => listPlugins,
   listSamples: () => listSamples,
   parseFlp: () => parseFlp,
@@ -65,6 +66,9 @@ var WORD = 64;
 var DWORD = 128;
 var TEXT = 192;
 var DATA = 208;
+var FIXED_SIZE_OVERRIDES = {
+  172: 3
+};
 var NEW_TEXT_IDS = [
   TEXT + 49,
   // ArrangementID.Name
@@ -211,6 +215,7 @@ var EVENT_ID = {
   // 236
 };
 var EVENT_KIND = {
+  [172]: "unknown",
   // Project events
   [EVENT_ID.PROJECT_LOOP_ACTIVE]: "u8",
   [EVENT_ID.PROJECT_SHOW_INFO]: "u8",
@@ -319,6 +324,10 @@ function getEventKind(eventId) {
   }
 }
 function getEventFixedSize(eventId) {
+  const override = FIXED_SIZE_OVERRIDES[eventId];
+  if (override !== void 0) {
+    return override;
+  }
   if (eventId < WORD) {
     return 1;
   } else if (eventId < DWORD) {
@@ -595,62 +604,9 @@ function varIntSize(value) {
 }
 
 // src/parser/FlpParser.ts
-var KNOWN_DWORD_IDS = new Set(
-  Object.keys(EVENT_KIND).map(Number).filter((id) => id >= DWORD && id < TEXT)
-);
 var FLP_HEADER_MAGIC = "FLhd";
 var FLP_DATA_MAGIC = "FLdt";
 var FLP_HEADER_SIZE = 6;
-var LOOKAHEAD_BYTES = 200;
-var LOOKAHEAD_VARINT_MAX = 1e5;
-function readVarIntRaw(buf, off, end) {
-  let shift = 0;
-  let size = 0;
-  const start = off;
-  while (true) {
-    if (off >= end) return { size: -1, bytesRead: 0 };
-    const byte = buf[off];
-    off++;
-    size |= (byte & 127) << shift;
-    shift += 7;
-    if (!(byte & 128)) break;
-  }
-  return { size, bytesRead: off - start };
-}
-function scoreAlignment(buf, off, end, bytesToCheck) {
-  const limit = Math.min(off + bytesToCheck, end);
-  let textDataCount = 0;
-  let consecutiveSmallByte = 0;
-  let maxConsecutiveSmallByte = 0;
-  while (off < limit) {
-    const id = buf[off];
-    if (id < WORD) {
-      off += 2;
-      if (id < 32 && !KNOWN_DWORD_IDS.has(id)) {
-        consecutiveSmallByte++;
-        maxConsecutiveSmallByte = Math.max(maxConsecutiveSmallByte, consecutiveSmallByte);
-      } else {
-        consecutiveSmallByte = 0;
-      }
-    } else if (id < DWORD) {
-      off += 3;
-      consecutiveSmallByte = 0;
-    } else if (id < TEXT) {
-      off += 5;
-      consecutiveSmallByte = 0;
-    } else {
-      const vi = readVarIntRaw(buf, off + 1, end);
-      if (vi.size >= 0 && vi.size < LOOKAHEAD_VARINT_MAX && off + 1 + vi.bytesRead + vi.size <= end) {
-        textDataCount++;
-        off = off + 1 + vi.bytesRead + vi.size;
-      } else {
-        return -100;
-      }
-      consecutiveSmallByte = 0;
-    }
-  }
-  return textDataCount * 10 - maxConsecutiveSmallByte * 3;
-}
 function parseFlp(buffer) {
   const reader = new BinaryReader(buffer);
   const headerMagic = reader.readBytes(4).toString("ascii");
@@ -662,8 +618,8 @@ function parseFlp(buffer) {
     throw new Error(`Invalid header size: expected ${FLP_HEADER_SIZE}, got ${headerSize}`);
   }
   const format = reader.readI16LE();
-  const channelCount = reader.readU16LE();
-  const ppq = reader.readU16LE();
+  reader.readU16LE();
+  reader.readU16LE();
   if (format < -1 || format > 80) {
     throw new Error(`Invalid file format: ${format}`);
   }
@@ -690,39 +646,10 @@ function parseFlp(buffer) {
     const eventId = reader.readU8();
     let payloadSize;
     let headerSize2;
-    if (eventId < WORD) {
-      payloadSize = 1;
-      headerSize2 = 1;
-    } else if (eventId < DWORD) {
-      payloadSize = 2;
+    const fixedSize = getEventFixedSize(eventId);
+    if (fixedSize >= 0) {
+      payloadSize = fixedSize;
       headerSize2 = 1;
-    } else if (eventId < TEXT) {
-      if (KNOWN_DWORD_IDS.has(eventId)) {
-        payloadSize = 4;
-        headerSize2 = 1;
-      } else {
-        const afterDword = eventStart + 1 + 4;
-        const vi = readVarIntRaw(buffer, eventStart + 1, eventsEnd);
-        if (vi.size < 0 || vi.size > LOOKAHEAD_VARINT_MAX || eventStart + 1 + vi.bytesRead + vi.size > eventsEnd) {
-          payloadSize = 4;
-          headerSize2 = 1;
-        } else if (vi.size === 3) {
-          payloadSize = 4;
-          headerSize2 = 1;
-        } else {
-          const afterVarInt = eventStart + 1 + vi.bytesRead + vi.size;
-          const dwordScore = scoreAlignment(buffer, afterDword, eventsEnd, LOOKAHEAD_BYTES);
-          const varIntScore = scoreAlignment(buffer, afterVarInt, eventsEnd, LOOKAHEAD_BYTES);
-          if (varIntScore > dwordScore + 2) {
-            payloadSize = vi.size;
-            reader.seek(eventStart + 1 + vi.bytesRead);
-            headerSize2 = 1 + vi.bytesRead;
-          } else {
-            payloadSize = 4;
-            headerSize2 = 1;
-          }
-        }
-      }
     } else {
       const sizeStart = reader.tell();
       payloadSize = reader.readVarInt();
@@ -905,6 +832,46 @@ function createNumberPayload(value, kind) {
 }
 
 // src/api/ProjectApi.ts
+var PROJECT_EVENT_ORDER = [
+  EVENT_ID.PROJECT_TEMPO,
+  EVENT_ID.PROJECT_TITLE,
+  EVENT_ID.PROJECT_GENRE,
+  EVENT_ID.PROJECT_ARTISTS,
+  EVENT_ID.PROJECT_COMMENTS,
+  EVENT_ID.PROJECT_TIMESTAMP
+];
+function insertProjectEvent(parsed, event) {
+  const orderIndex = PROJECT_EVENT_ORDER.indexOf(event.id);
+  let insertionIndex = -1;
+  if (orderIndex >= 0) {
+    const laterIds = new Set(PROJECT_EVENT_ORDER.slice(orderIndex + 1));
+    insertionIndex = parsed.events.findIndex((candidate) => laterIds.has(candidate.id));
+    if (insertionIndex < 0) {
+      const previousIds = new Set(PROJECT_EVENT_ORDER.slice(0, orderIndex + 1));
+      for (let index = parsed.events.length - 1; index >= 0; index--) {
+        if (previousIds.has(parsed.events[index].id)) {
+          insertionIndex = index + 1;
+          break;
+        }
+      }
+    }
+  }
+  if (insertionIndex < 0) {
+    insertionIndex = parsed.events.findIndex((candidate) => candidate.id === EVENT_ID.CHANNEL_NEW);
+  }
+  if (insertionIndex < 0) {
+    const versionIndex = parsed.events.findIndex(
+      (candidate) => candidate.id === EVENT_ID.PROJECT_FL_VERSION
+    );
+    insertionIndex = versionIndex >= 0 ? versionIndex + 1 : parsed.events.length;
+  }
+  const events = [...parsed.events];
+  events.splice(insertionIndex, 0, event);
+  return { ...parsed, events };
+}
+function replaceEventPayload(parsed, target, payload) {
+  return patchEvents(parsed, (event) => event === target ? { ...event, payload } : event);
+}
 function readBpm(parsed) {
   const tempoEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TEMPO);
   if (tempoEvent) {
@@ -934,48 +901,97 @@ function readProjectMeta(parsed) {
     bpm: readBpm(parsed)
   };
 }
+function compareVersion(version, expected) {
+  const actual = version.split(".").map((part) => Number.parseInt(part, 10));
+  const length = Math.max(actual.length, expected.length);
+  for (let index = 0; index < length; index++) {
+    const difference = (actual[index] ?? 0) - (expected[index] ?? 0);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}
+function validateBpm(parsed, bpm) {
+  if (!Number.isFinite(bpm)) {
+    throw new RangeError("BPM must be a finite number");
+  }
+  const legacyHighTempo = compareVersion(parsed.flVersion, [1, 4, 2]) >= 0 && compareVersion(parsed.flVersion, [11]) < 0;
+  const maximum = legacyHighTempo ? 999 : 522;
+  if (bpm < 10 || bpm > maximum) {
+    throw new RangeError(`BPM must be between 10 and ${maximum} for FL Studio ${parsed.flVersion}`);
+  }
+  if (parsed.flVersion !== "0.0.0" && compareVersion(parsed.flVersion, [3, 4]) < 0 && !Number.isInteger(bpm)) {
+    throw new TypeError(`FL Studio ${parsed.flVersion} does not support decimal BPM values`);
+  }
+}
+function writeTextProjectEvent(parsed, eventId, value) {
+  if (value === void 0) return parsed;
+  const payload = createTextPayload(value ?? "", parsed.useUnicode);
+  const existing = findFirstEvent(parsed, eventId);
+  return existing ? replaceEventPayload(parsed, existing, payload) : insertProjectEvent(parsed, createEvent(eventId, payload));
+}
+function writeProjectBpm(parsed, bpm) {
+  if (bpm === void 0 || bpm === null) return parsed;
+  validateBpm(parsed, bpm);
+  const scaledBpm = Math.round(bpm * 1e3);
+  const coarseBpm = Math.floor(scaledBpm / 1e3);
+  const fineBpm = scaledBpm % 1e3;
+  const modernEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TEMPO);
+  const coarseEvent = findFirstEvent(parsed, EVENT_ID.PROJECT__TEMPO_COARSE);
+  const fineEvent = findFirstEvent(parsed, EVENT_ID.PROJECT__TEMPO_FINE);
+  let result = parsed;
+  if (modernEvent) {
+    result = replaceEventPayload(result, modernEvent, createNumberPayload(scaledBpm, "u32"));
+  }
+  if (coarseEvent) {
+    result = replaceEventPayload(result, coarseEvent, createNumberPayload(coarseBpm, "u16"));
+  }
+  if (fineEvent) {
+    result = replaceEventPayload(result, fineEvent, createNumberPayload(fineBpm, "u16"));
+  }
+  if (!modernEvent && !coarseEvent && !fineEvent) {
+    result = insertProjectEvent(
+      result,
+      createEvent(EVENT_ID.PROJECT_TEMPO, createNumberPayload(scaledBpm, "u32"))
+    );
+  } else if (!modernEvent && coarseEvent && !fineEvent && fineBpm > 0) {
+    const updatedCoarse = findFirstEvent(result, EVENT_ID.PROJECT__TEMPO_COARSE);
+    const index = result.events.indexOf(updatedCoarse) + 1;
+    const events = [...result.events];
+    events.splice(
+      index,
+      0,
+      createEvent(EVENT_ID.PROJECT__TEMPO_FINE, createNumberPayload(fineBpm, "u16"))
+    );
+    result = { ...result, events };
+  } else if (!modernEvent && !coarseEvent && fineEvent) {
+    const updatedFine = findFirstEvent(result, EVENT_ID.PROJECT__TEMPO_FINE);
+    const index = result.events.indexOf(updatedFine);
+    const events = [...result.events];
+    events.splice(
+      index,
+      0,
+      createEvent(EVENT_ID.PROJECT__TEMPO_COARSE, createNumberPayload(coarseBpm, "u16"))
+    );
+    result = { ...result, events };
+  }
+  return result;
+}
 function writeProjectMeta(parsed, meta) {
-  return patchEvents(parsed, (event) => {
-    if (meta.name !== void 0 && event.id === EVENT_ID.PROJECT_TITLE) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.name ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.description !== void 0 && event.id === EVENT_ID.PROJECT_COMMENTS) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.description ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.artist !== void 0 && event.id === EVENT_ID.PROJECT_ARTISTS) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.artist ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.genre !== void 0 && event.id === EVENT_ID.PROJECT_GENRE) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.genre ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.bpm && Math.abs(meta.bpm) > 0 && event.id === EVENT_ID.PROJECT_TEMPO) {
-      return {
-        ...event,
-        payload: createNumberPayload(Math.round(Math.abs(meta.bpm) * 1e3), "u32")
-      };
-    }
-    return event;
-  });
+  let result = parsed;
+  result = writeProjectBpm(result, meta.bpm);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_TITLE, meta.name);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_GENRE, meta.genre);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_ARTISTS, meta.artist);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_COMMENTS, meta.description);
+  return result;
 }
-var DELPHI_EPOCH = new Date(1899, 11, 30);
+var DELPHI_EPOCH_MS = Date.UTC(1899, 11, 30);
 function delphiToDate(days) {
   const ms = days * 24 * 60 * 60 * 1e3;
-  return new Date(DELPHI_EPOCH.getTime() + ms);
+  return new Date(DELPHI_EPOCH_MS + ms);
 }
 function dateToDelphiDays(date) {
-  const ms = date.getTime() - DELPHI_EPOCH.getTime();
+  const ms = date.getTime() - DELPHI_EPOCH_MS;
   return ms / (24 * 60 * 60 * 1e3);
 }
 function readProjectTimeInfo(parsed) {
@@ -996,41 +1012,33 @@ function readProjectTimeInfo(parsed) {
   };
 }
 function writeProjectTimeInfo(parsed, info) {
+  if (info.creationDate === void 0 && info.workTimeSeconds === void 0) {
+    return parsed;
+  }
   const current = readProjectTimeInfo(parsed);
-  return patchEvents(parsed, (event) => {
-    if (event.id !== EVENT_ID.PROJECT_TIMESTAMP) {
-      return event;
-    }
-    const writer = new BinaryWriter();
-    if (info.creationDate !== void 0 && info.creationDate !== null) {
-      writer.writeF64LE(dateToDelphiDays(info.creationDate));
-    } else if (current.creationDate !== null) {
-      writer.writeF64LE(dateToDelphiDays(current.creationDate));
-    } else {
-      writer.writeF64LE(0);
-    }
-    if (info.workTimeSeconds !== void 0 && info.workTimeSeconds !== null) {
-      writer.writeF64LE(info.workTimeSeconds / (24 * 60 * 60));
-    } else if (current.workTimeSeconds !== null) {
-      writer.writeF64LE(current.workTimeSeconds / (24 * 60 * 60));
-    } else {
-      writer.writeF64LE(0);
-    }
-    return {
-      ...event,
-      payload: writer.toBuffer()
-    };
-  });
+  if (info.creationDate !== void 0 && info.creationDate !== null && Number.isNaN(info.creationDate.getTime())) {
+    throw new RangeError("creationDate must be a valid Date");
+  }
+  if (info.workTimeSeconds !== void 0 && info.workTimeSeconds !== null && (!Number.isFinite(info.workTimeSeconds) || info.workTimeSeconds < 0)) {
+    throw new RangeError("workTimeSeconds must be a finite, non-negative number");
+  }
+  const creationDateDays = info.creationDate === null ? 0 : info.creationDate !== void 0 ? dateToDelphiDays(info.creationDate) : current.creationDate !== null ? dateToDelphiDays(current.creationDate) : 0;
+  const workTimeDays = info.workTimeSeconds === null ? 0 : info.workTimeSeconds !== void 0 ? info.workTimeSeconds / (24 * 60 * 60) : current.workTimeSeconds !== null ? current.workTimeSeconds / (24 * 60 * 60) : 0;
+  const writer = new BinaryWriter();
+  writer.writeF64LE(creationDateDays);
+  writer.writeF64LE(workTimeDays);
+  const timestampEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TIMESTAMP);
+  return timestampEvent ? replaceEventPayload(parsed, timestampEvent, writer.toBuffer()) : insertProjectEvent(parsed, createEvent(EVENT_ID.PROJECT_TIMESTAMP, writer.toBuffer()));
 }
 function listSamples(parsed) {
   const samples = [];
   parsed.events.forEach((event, index) => {
     if (event.id === EVENT_ID.CHANNEL_SAMPLE_PATH) {
-      const path = getEventString(event, parsed.useUnicode);
-      if (path && path.length > 0) {
+      const path2 = getEventString(event, parsed.useUnicode);
+      if (path2 && path2.length > 0) {
         samples.push({
           eventIndex: index,
-          path
+          path: path2
         });
       }
     }
@@ -1158,6 +1166,147 @@ function getPPQ(parsed) {
   reader.seek(12);
   return reader.readU16LE();
 }
+
+// src/samples/inspectReferences.ts
+var import_node_path = __toESM(require("path"), 1);
+var fs = __toESM(require("fs/promises"), 1);
+function pathType(p) {
+  if (!p || Array.from(p).some((c) => c.charCodeAt(0) < 32)) return "unknown";
+  if (/^[A-Za-z]:/.test(p) || p.startsWith("\\")) return "windows";
+  if (p.startsWith("/")) return "posix";
+  if (/^[A-Za-z][\w+.-]*:/.test(p) || /[%$]/.test(p)) return "daw";
+  return "relative";
+}
+function nativeAbsolute(p) {
+  const kind = pathType(p);
+  return process.platform === "win32" ? kind === "windows" && import_node_path.default.win32.isAbsolute(p) && !/^[\\/][^\\/]/.test(p) : kind === "posix";
+}
+function localRelative(p) {
+  return pathType(p) === "relative";
+}
+function abort(signal) {
+  if (signal?.aborted) {
+    const e = new Error("Sample inspection aborted");
+    e.name = "AbortError";
+    throw e;
+  }
+}
+async function inspectReferences(refs, options = {}) {
+  const mode = options.mode ?? "resolve";
+  if (mode !== "resolve" && mode !== "check") throw new TypeError("Unknown sample inspection mode");
+  const concurrency = options.concurrency ?? 8;
+  const maxEntries = options.maxSearchEntries ?? 1e5;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 64) throw new RangeError("Concurrency must be between 1 and 64");
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) throw new RangeError("Search limit must be a positive safe integer");
+  for (const p of [options.projectPath, options.projectRoot, ...Object.values(options.relativeRoots ?? {}), ...options.searchRoots ?? []]) {
+    if (p !== void 0 && !nativeAbsolute(p)) throw new TypeError("Inspection context paths must be native absolute paths");
+  }
+  abort(options.signal);
+  const results = refs.map((ref) => {
+    const kind = pathType(ref.path);
+    const candidates = [];
+    const add = (p, source) => {
+      const normalized = import_node_path.default.normalize(p);
+      if (!candidates.some((c) => c.path === normalized)) candidates.push({ path: normalized, source, confidence: "exact" });
+    };
+    if (ref.supported !== false) {
+      if (nativeAbsolute(ref.path)) add(ref.path, "declared");
+      const base = ref.relativeBase === "project-file" ? options.projectRoot ?? (options.projectPath ? import_node_path.default.dirname(options.projectPath) : void 0) : options.relativeRoots?.[ref.relativeType ?? ""] ?? (ref.relativeType === "3" ? options.projectRoot : void 0);
+      const relative = ref.relativePath || (kind === "relative" ? ref.path : null);
+      if (base && relative && localRelative(relative)) add(import_node_path.default.resolve(base, relative.replace(/\\/g, import_node_path.default.sep)), "relative");
+    }
+    return {
+      referenceIndex: ref.referenceIndex,
+      recordedPath: ref.path,
+      pathType: ref.supported === false ? "unknown" : kind,
+      relativePath: ref.relativePath ?? (kind === "relative" ? ref.path : null),
+      candidates,
+      resolvedPath: null,
+      status: candidates.length ? "unchecked" : "unresolved",
+      reason: candidates.length ? null : "No interpretable path in the supplied context"
+    };
+  });
+  if (mode === "resolve") return results;
+  const checks = /* @__PURE__ */ new Map();
+  const check = (p) => {
+    let pending = checks.get(p);
+    if (!pending) {
+      pending = fs.stat(p).then((s) => s.isFile() ? "file" : "absent", (e) => e.code === "ENOENT" || e.code === "ENOTDIR" ? "absent" : "inaccessible");
+      checks.set(p, pending);
+    }
+    return pending;
+  };
+  let index = 0;
+  await Promise.all(Array.from({ length: Math.min(concurrency, results.length) }, async () => {
+    while (index < results.length) {
+      abort(options.signal);
+      const result = results[index++];
+      const found = [];
+      let inaccessible = false;
+      for (const candidate of result.candidates) {
+        abort(options.signal);
+        const status = await check(candidate.path);
+        if (status === "file") found.push(candidate.path);
+        if (status === "inaccessible") inaccessible = true;
+      }
+      result.status = found.length > 1 ? "ambiguous" : found.length === 1 ? "found" : inaccessible ? "inaccessible" : result.candidates.length ? "missing" : "unresolved";
+      result.resolvedPath = result.status === "found" ? found[0] : null;
+      if (result.status === "inaccessible") result.reason = "A candidate could not be checked";
+    }
+  }));
+  abort(options.signal);
+  const unresolved = results.filter((r) => r.status !== "found");
+  if (unresolved.length && options.searchRoots?.length) {
+    const names = /* @__PURE__ */ new Map();
+    const needed = new Set(unresolved.map((r) => import_node_path.default.posix.basename(r.recordedPath.replace(/\\/g, "/")).normalize("NFC").toLowerCase()));
+    const queue = [...new Set(options.searchRoots.map((r) => import_node_path.default.normalize(r)))];
+    const visited = /* @__PURE__ */ new Set();
+    let entries = 0;
+    let incomplete = false;
+    while (queue.length) {
+      abort(options.signal);
+      const directory = queue.pop();
+      if (visited.has(directory)) continue;
+      visited.add(directory);
+      try {
+        const handle = await fs.opendir(directory);
+        for await (const entry of handle) {
+          abort(options.signal);
+          if (++entries > maxEntries) throw new RangeError("Sample search entry limit exceeded");
+          const p = import_node_path.default.join(directory, entry.name);
+          if (entry.isDirectory()) queue.push(p);
+          else if (entry.isFile()) {
+            const name = entry.name.normalize("NFC").toLowerCase();
+            if (needed.has(name)) names.set(name, [...names.get(name) ?? [], p]);
+          }
+        }
+      } catch (e) {
+        if (e instanceof RangeError || e instanceof Error && e.name === "AbortError") throw e;
+        incomplete = true;
+      }
+    }
+    for (const result of unresolved) {
+      const name = import_node_path.default.posix.basename(result.recordedPath.replace(/\\/g, "/")).normalize("NFC").toLowerCase();
+      const matches = names.get(name) ?? [];
+      for (const p of matches) if (!result.candidates.some((c) => c.path === p)) result.candidates.push({ path: p, source: "search", confidence: "name-only" });
+      if (result.status === "ambiguous") continue;
+      if (matches.length) {
+        result.status = matches.length > 1 ? "ambiguous" : "unresolved";
+        result.reason = "Name-only candidates require caller confirmation";
+      } else if (incomplete && result.status !== "inaccessible") {
+        result.status = "inaccessible";
+        result.reason = "Search could not inspect every requested directory";
+      }
+    }
+  }
+  abort(options.signal);
+  return results;
+}
+
+// src/api/inspectSamples.ts
+function inspectSamples(parsed, options = {}) {
+  return inspectReferences(listSamples(parsed).map((s) => ({ referenceIndex: s.eventIndex, path: s.path, relativeBase: "project-file" })), options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BinaryReader,
@@ -1176,6 +1325,7 @@ function getPPQ(parsed) {
   getEventString,
   getFlVersion,
   getPPQ,
+  inspectSamples,
   listPlugins,
   listSamples,
   parseFlp,