@openparachute/vault 0.4.4-rc.14 → 0.4.5

package/core/src/portable-md.test.ts

@@ -31,8 +31,12 @@ import {
   noteToPortable,
   parseFrontmatter,
   portableExportFilePath,
+  probeCaseSensitive,
   SIDECAR_DIR,
+  NOTES_META_DIR,
+  supportsInlineFrontmatter,
   toPortableMarkdown,
+  toSidecarYaml,
   type PortableNote,
 } from "./portable-md.js";
 
@@ -294,6 +298,25 @@ describe("portableExportFilePath", () => {
       id: "01HABC", content: "", created_at: "2026-05-12T00:00:00.000Z",
     })).toBe("_unpathed/01HABC.md");
   });
+
+  it("honors the note's extension for pathless notes (vault#329 F4)", () => {
+    expect(portableExportFilePath({
+      id: "01HXCSV",
+      content: "a,b\n1,2",
+      created_at: "2026-05-12T00:00:00.000Z",
+      extension: "csv",
+    })).toBe("_unpathed/01HXCSV.csv");
+  });
+
+  it("honors the note's extension for pathed notes (vault#329 F4)", () => {
+    expect(portableExportFilePath({
+      id: "x",
+      content: "",
+      created_at: "2026-05-12T00:00:00.000Z",
+      path: "Inbox/y",
+      extension: "mdx",
+    })).toBe("Inbox/y.mdx");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1021,3 +1044,511 @@ note body
     expect(existsSync(wouldBeEscape)).toBe(false);
   });
 });
+
+// ---------------------------------------------------------------------------
+// File-extension support — non-markdown notes (vault#328)
+// ---------------------------------------------------------------------------
+//
+// Two pinned behaviors per the design issue:
+//   1. supportsInlineFrontmatter: md + mdx return true; everything else
+//      returns false.
+//   2. Round-trip integration: vault containing csv/yaml/json/mdx/empty
+//      notes survives export → blow-away import → re-export byte-equiv.
+
+describe("supportsInlineFrontmatter (vault#328)", () => {
+  it("returns true for md and mdx", () => {
+    expect(supportsInlineFrontmatter("md")).toBe(true);
+    expect(supportsInlineFrontmatter("mdx")).toBe(true);
+    // Case-insensitive — guard against caller-supplied 'MD'.
+    expect(supportsInlineFrontmatter("MD")).toBe(true);
+  });
+
+  it("returns false for sidecar-required formats", () => {
+    expect(supportsInlineFrontmatter("csv")).toBe(false);
+    expect(supportsInlineFrontmatter("yaml")).toBe(false);
+    expect(supportsInlineFrontmatter("json")).toBe(false);
+    expect(supportsInlineFrontmatter("txt")).toBe(false);
+    expect(supportsInlineFrontmatter("org")).toBe(false); // not yet in the set
+  });
+});
+
+describe("toPortableMarkdown — extension awareness (vault#328)", () => {
+  it(".md note still gets inline frontmatter", () => {
+    const out = toPortableMarkdown({
+      id: "1",
+      path: "Inbox/a",
+      extension: "md",
+      content: "hello\n",
+      created_at: "2026-05-15T00:00:00.000Z",
+    });
+    expect(out.startsWith("---\n")).toBe(true);
+    expect(out).toContain("id: '1'");
+    expect(out).toContain("hello");
+  });
+
+  it(".mdx note also gets inline frontmatter", () => {
+    const out = toPortableMarkdown({
+      id: "1",
+      path: "Components/Card",
+      extension: "mdx",
+      content: "import X from './x';\n\n<X/>\n",
+      created_at: "2026-05-15T00:00:00.000Z",
+    });
+    expect(out.startsWith("---\n")).toBe(true);
+    expect(out).toContain("extension: mdx");
+  });
+
+  it(".csv note returns raw content — no frontmatter prepend", () => {
+    const out = toPortableMarkdown({
+      id: "1",
+      path: "Tabular/budget",
+      extension: "csv",
+      content: "month,total\n2026-01,9000\n",
+      created_at: "2026-05-15T00:00:00.000Z",
+    });
+    expect(out.startsWith("---\n")).toBe(false);
+    expect(out).toBe("month,total\n2026-01,9000\n");
+  });
+
+  it("toSidecarYaml emits the same key set as inline frontmatter, always includes extension", () => {
+    const sidecar = toSidecarYaml({
+      id: "abc",
+      path: "Tabular/budget",
+      extension: "csv",
+      tags: ["budget"],
+      content: "irrelevant — sidecar carries metadata only",
+      metadata: { fiscal_year: 2026 },
+      created_at: "2026-05-15T00:00:00.000Z",
+      updated_at: "2026-05-15T00:00:00.000Z",
+    });
+    expect(sidecar).toContain("id: abc");
+    expect(sidecar).toContain("path: Tabular/budget");
+    expect(sidecar).toContain("extension: csv");
+    expect(sidecar).toContain("tags:");
+    expect(sidecar).toContain("budget");
+    expect(sidecar).toContain("fiscal_year");
+  });
+});
+
+describe("portable-md non-markdown round-trip (vault#328)", async () => {
+  const tmpBase = join(tmpdir(), "parachute-portable-ext");
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    try { rmSync(tmpBase, { recursive: true }); } catch {}
+    mkdirSync(tmpBase, { recursive: true });
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("csv/yaml/json/mdx/empty notes survive export → blow-away import → byte-equivalent re-export", async () => {
+    // Seed a vault that hits every extension axis the brief calls out:
+    //   - .csv (sidecar-required, non-empty)
+    //   - .yaml (sidecar-required, non-empty)
+    //   - .json (sidecar-required, non-empty)
+    //   - .mdx (frontmatter-compatible, non-empty)
+    //   - .csv empty-content (the vault#323 edge case, vault#328 sidecar path)
+    //   - .md (back-compat baseline — same shape as pre-vault#328)
+    await store.createNote("month,total\n2026-01,9000\n", {
+      id: "csv-1",
+      path: "Tabular/budget",
+      extension: "csv",
+      tags: ["budget"],
+      metadata: { fiscal_year: 2026, currency: "USD" },
+    });
+    await store.createNote("- one\n- two\n", {
+      id: "yaml-1",
+      path: "Config/options",
+      extension: "yaml",
+    });
+    await store.createNote(`{"k":1}\n`, {
+      id: "json-1",
+      path: "Data/sample",
+      extension: "json",
+    });
+    await store.createNote("import X from './x';\n\n<X/>\n", {
+      id: "mdx-1",
+      path: "Components/Card",
+      extension: "mdx",
+      tags: ["component"],
+    });
+    await store.createNote("", {
+      id: "csv-empty",
+      path: "Tabular/skeleton",
+      extension: "csv",
+    });
+    await store.createNote("plain markdown body\n", {
+      id: "md-1",
+      path: "Inbox/note",
+      tags: ["inbox"],
+    });
+
+    // Export A.
+    const outA = join(tmpBase, "outA");
+    const statsA = await exportVaultToDir(store, {
+      outDir: outA,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+    });
+    expect(statsA.notes).toBe(6);
+    // Four sidecar-required notes (csv ×2, yaml, json) → four sidecars.
+    // md + mdx carry frontmatter inline so they don't get sidecars.
+    expect(statsA.sidecars).toBe(4);
+
+    // Sidecar files exist with the right basenames (note ids).
+    const sidecarDir = join(outA, SIDECAR_DIR, NOTES_META_DIR);
+    expect(readdirSync(sidecarDir).sort()).toEqual([
+      "csv-1.yaml",
+      "csv-empty.yaml",
+      "json-1.yaml",
+      "yaml-1.yaml",
+    ]);
+
+    // Content files at the user-visible paths with the right suffixes.
+    expect(existsSync(join(outA, "Tabular/budget.csv"))).toBe(true);
+    expect(existsSync(join(outA, "Config/options.yaml"))).toBe(true);
+    expect(existsSync(join(outA, "Data/sample.json"))).toBe(true);
+    expect(existsSync(join(outA, "Components/Card.mdx"))).toBe(true);
+    expect(existsSync(join(outA, "Tabular/skeleton.csv"))).toBe(true);
+    expect(existsSync(join(outA, "Inbox/note.md"))).toBe(true);
+
+    // .csv content is RAW — no `---` frontmatter prepend.
+    const csvFile = readFileSync(join(outA, "Tabular/budget.csv"), "utf-8");
+    expect(csvFile.startsWith("---")).toBe(false);
+    expect(csvFile).toBe("month,total\n2026-01,9000\n");
+
+    // .mdx content has inline frontmatter (same as .md).
+    const mdxFile = readFileSync(join(outA, "Components/Card.mdx"), "utf-8");
+    expect(mdxFile.startsWith("---\n")).toBe(true);
+    expect(mdxFile).toContain("extension: mdx");
+
+    // Blow-away import into a fresh store.
+    const restored = new SqliteStore(new Database(":memory:"));
+    const importStats = await importPortableVault(restored, { inDir: outA, blowAway: true });
+    expect(importStats.notes_created).toBe(6);
+
+    // Verify each note round-tripped its content + extension.
+    const csvRestored = await restored.getNote("csv-1");
+    expect(csvRestored).not.toBeNull();
+    expect(csvRestored!.content).toBe("month,total\n2026-01,9000\n");
+    expect(csvRestored!.extension).toBe("csv");
+    expect(csvRestored!.metadata).toEqual({ fiscal_year: 2026, currency: "USD" });
+    expect(csvRestored!.tags).toContain("budget");
+
+    const emptyCsv = await restored.getNote("csv-empty");
+    expect(emptyCsv!.content).toBe("");
+    expect(emptyCsv!.extension).toBe("csv");
+    expect(emptyCsv!.path).toBe("Tabular/skeleton");
+
+    const mdxRestored = await restored.getNote("mdx-1");
+    expect(mdxRestored!.extension).toBe("mdx");
+    expect(mdxRestored!.content).toBe("import X from './x';\n\n<X/>\n");
+
+    const mdRestored = await restored.getNote("md-1");
+    expect(mdRestored!.extension).toBe("md");
+    expect(mdRestored!.tags).toContain("inbox");
+
+    // Re-export B from the restored store.
+    const outB = join(tmpBase, "outB");
+    await exportVaultToDir(restored, {
+      outDir: outB,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+    });
+
+    // Byte-equivalence — every file in outA matches outB.
+    const compareTree = (a: string, b: string, prefix = "") => {
+      const aEntries = readdirSync(a).sort();
+      const bEntries = readdirSync(b).sort();
+      expect(bEntries).toEqual(aEntries);
+      for (const entry of aEntries) {
+        const aPath = join(a, entry);
+        const bPath = join(b, entry);
+        const aStat = statSync(aPath);
+        const bStat = statSync(bPath);
+        expect(bStat.isDirectory()).toBe(aStat.isDirectory());
+        if (aStat.isDirectory()) {
+          compareTree(aPath, bPath, prefix + entry + "/");
+        } else {
+          const aBuf = readFileSync(aPath, "utf-8");
+          const bBuf = readFileSync(bPath, "utf-8");
+          if (aBuf !== bBuf) {
+            // eslint-disable-next-line no-console
+            console.error(`drift at ${prefix}${entry}:\n--- outA ---\n${aBuf}\n--- outB ---\n${bBuf}`);
+          }
+          expect(bBuf).toBe(aBuf);
+        }
+      }
+    };
+    compareTree(outA, outB);
+  });
+
+  it("records orphan sidecars in ImportStats.skipped_sidecars (vault#330 S2)", async () => {
+    // Build a portable-md export by hand with an orphan sidecar: a
+    // sidecar YAML at .parachute/notes-meta/<id>.yaml whose
+    // (path, extension) doesn't point to any real content file on
+    // disk. Import should record it in skipped_sidecars without
+    // crashing.
+    const outDir = join(tmpBase, "orphan-sidecar");
+    mkdirSync(join(outDir, SIDECAR_DIR, NOTES_META_DIR), { recursive: true });
+    writeFileSync(
+      join(outDir, SIDECAR_DIR, "vault.yaml"),
+      "export_format_version: 1\nexported_at: '2026-05-15T00:00:00.000Z'\n",
+    );
+    writeFileSync(
+      join(outDir, SIDECAR_DIR, NOTES_META_DIR, "orphan-1.yaml"),
+      "id: orphan-1\npath: Tabular/missing\nextension: csv\ncreated_at: '2026-05-15T00:00:00.000Z'\nupdated_at: '2026-05-15T00:00:00.000Z'\n",
+    );
+
+    const restored = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(restored, { inDir: outDir });
+    expect(stats.notes_created).toBe(0);
+    expect(stats.skipped_sidecars).toHaveLength(1);
+    expect(stats.skipped_sidecars[0]!.sidecar_id).toBe("orphan-1");
+    expect(stats.skipped_sidecars[0]!.expected_path).toBe("Tabular/missing");
+    expect(stats.skipped_sidecars[0]!.expected_extension).toBe("csv");
+    expect(stats.skipped_sidecars[0]!.reason).toMatch(/no content file/);
+  });
+
+  it("skipped_sidecars stays empty on a clean export-then-import", async () => {
+    // Sanity pin: when every sidecar pairs with a content file, the
+    // leftover-drain produces no entries.
+    await store.createNote("month,total\n2026-01,9000", {
+      id: "csv-1",
+      path: "Tabular/budget",
+      extension: "csv",
+    });
+    const outDir = join(tmpBase, "clean-sidecars");
+    await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+    });
+    const restored = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(restored, { inDir: outDir, blowAway: true });
+    expect(stats.skipped_sidecars).toEqual([]);
+  });
+
+  it("import refuses content files lacking a sidecar (orphaned non-md file)", async () => {
+    // Build a minimal portable-md directory by hand: a valid vault.yaml
+    // + a .csv content file with NO matching sidecar. The importer
+    // should skip the orphaned file rather than crashing or creating
+    // a sidecar-less note.
+    const outDir = join(tmpBase, "orphan");
+    mkdirSync(join(outDir, SIDECAR_DIR), { recursive: true });
+    writeFileSync(
+      join(outDir, SIDECAR_DIR, "vault.yaml"),
+      "export_format_version: 1\nexported_at: '2026-05-15T00:00:00.000Z'\n",
+    );
+    mkdirSync(join(outDir, "Tabular"), { recursive: true });
+    writeFileSync(join(outDir, "Tabular/orphan.csv"), "a,b\n1,2\n");
+
+    const restored = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(restored, { inDir: outDir });
+    // No sidecar → no DB row.
+    expect(stats.notes_created).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Wikilink ambiguity policy (vault#328)
+// ---------------------------------------------------------------------------
+//
+// When two notes share a path differing only by extension (e.g. `Foo.md`
+// and `Foo.csv`), `[[Foo]]` is ambiguous. The resolver must:
+//   - refuse to resolve the bare form and record it as unresolved
+//   - resolve `[[Foo.md]]` and `[[Foo.csv]]` to their respective notes
+
+describe("wikilink ambiguity across extensions (vault#328)", async () => {
+  it("refuses ambiguous bare-form wikilinks when path collides on extension", async () => {
+    const store = new SqliteStore(new Database(":memory:"));
+    const md = await store.createNote("# MD note", { path: "Foo", id: "foo-md" });
+    const csv = await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    // Sanity — both rows landed under the composite uniqueness key.
+    expect(md.path).toBe("Foo");
+    expect(csv.path).toBe("Foo");
+
+    // A third note linking to bare `[[Foo]]` should be UNRESOLVED.
+    await store.createNote("see [[Foo]]", { id: "linker", path: "Linker" });
+    const outboundLinks = await store.getLinks("linker", { direction: "outbound" });
+    expect(outboundLinks).toHaveLength(0);
+  });
+
+  it("resolves explicit-extension wikilinks unambiguously", async () => {
+    const store = new SqliteStore(new Database(":memory:"));
+    await store.createNote("# MD note", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+
+    await store.createNote("see [[Foo.csv]]", { id: "linker", path: "Linker" });
+    const outbound = await store.getLinks("linker", { direction: "outbound" });
+    expect(outbound).toHaveLength(1);
+    expect(outbound[0]!.targetId).toBe("foo-csv");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Case-collision detection + auto-disambiguation (vault#327)
+// ---------------------------------------------------------------------------
+//
+// macOS APFS-default + Windows NTFS-default + FAT/exFAT are case-
+// insensitive — two notes whose paths differ only by case collapse
+// into one file on naive export. The fix probes the filesystem then
+// either ships as-is (case-sensitive) or disambiguates with an
+// `__<id-short>` filename suffix (case-insensitive). The note's
+// stored `path` stays canonical; only the on-disk filename is suffixed.
+
+describe("case-collision detection (vault#327)", async () => {
+  const tmpBase = join(tmpdir(), "parachute-portable-case");
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    try { rmSync(tmpBase, { recursive: true }); } catch {}
+    mkdirSync(tmpBase, { recursive: true });
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("probeCaseSensitive runs cleanly and returns a boolean", () => {
+    // Documenting behavior rather than asserting a specific value:
+    // macOS dev environments + most Linux CI runners produce different
+    // results. We just pin that the probe is well-formed (doesn't throw,
+    // returns boolean, cleans up its tempfile).
+    const result = probeCaseSensitive(tmpBase);
+    expect(typeof result).toBe("boolean");
+    // After the probe runs the dir should contain no leftover probe files.
+    const leftovers = readdirSync(tmpBase).filter((e) => e.includes("_parachute_cs_probe_"));
+    expect(leftovers).toEqual([]);
+  });
+
+  it("ships as-is when FS is case-sensitive (override=true)", async () => {
+    // Two notes with case-only-differing paths. With the case-sensitive
+    // override, both files land at their canonical paths — no
+    // disambiguation, no collisions in stats.
+    await store.createNote("# in Balance", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/2025-05-26 Technology in Balance",
+    });
+    await store.createNote("# in balance", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/2025-05-26 Technology in balance",
+    });
+
+    const outDir = join(tmpBase, "cs-on");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: true,
+    });
+    expect(stats.notes).toBe(2);
+    expect(stats.case_insensitive_fs).toBe(false);
+    expect(stats.disambiguated_paths).toHaveLength(0);
+  });
+
+  it("disambiguates colliding paths on case-insensitive FS (override=false)", async () => {
+    // Same fixture as above; force the case-insensitive code path. The
+    // second note (deterministic order: queryNotes sorts ASC on
+    // created_at — the IDs sort lexicographically so 'aaaaaa' lands
+    // first, 'bbbbbb' second) gets its filename suffixed.
+    await store.createNote("# in Balance", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/2025-05-26 Technology in Balance",
+    });
+    await store.createNote("# in balance", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/2025-05-26 Technology in balance",
+    });
+
+    const outDir = join(tmpBase, "ci-on");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+    });
+    expect(stats.notes).toBe(2);
+    expect(stats.case_insensitive_fs).toBe(true);
+    expect(stats.disambiguated_paths).toHaveLength(1);
+    expect(stats.disambiguated_paths[0]!.note_id).toBe("2025-05-26-09-15-42-bbbbbb");
+    expect(stats.disambiguated_paths[0]!.disambiguated_filename).toMatch(/__2025-05-/);
+
+    // Both files exist on disk under their respective filenames.
+    expect(existsSync(join(outDir, "Journal/2025-05-26 Technology in Balance.md"))).toBe(true);
+    expect(existsSync(join(outDir, stats.disambiguated_paths[0]!.disambiguated_filename))).toBe(true);
+
+    // The disambiguated file's inline frontmatter still carries the
+    // canonical (original) path, NOT the disambiguated filename — that
+    // way an import on a case-sensitive filesystem (or a future re-
+    // export on a case-sensitive FS) recovers the truth.
+    const disambigFile = readFileSync(
+      join(outDir, stats.disambiguated_paths[0]!.disambiguated_filename),
+      "utf-8",
+    );
+    expect(disambigFile).toContain("path: Journal/2025-05-26 Technology in balance");
+  });
+
+  it("disambiguated content round-trips through import (md inline frontmatter path)", async () => {
+    await store.createNote("# upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Same-Case Different",
+    });
+    await store.createNote("# lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/same-case different",
+    });
+
+    const outDir = join(tmpBase, "rt-md");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+    });
+    expect(stats.disambiguated_paths).toHaveLength(1);
+
+    const restored = new SqliteStore(new Database(":memory:"));
+    const importStats = await importPortableVault(restored, { inDir: outDir, blowAway: true });
+    expect(importStats.notes_created).toBe(2);
+
+    // Both notes recovered their canonical paths from the frontmatter.
+    const upper = await restored.getNote("2025-05-26-09-15-42-aaaaaa");
+    const lower = await restored.getNote("2025-05-26-09-15-42-bbbbbb");
+    expect(upper!.path).toBe("Journal/Same-Case Different");
+    expect(lower!.path).toBe("Journal/same-case different");
+  });
+
+  it("disambiguated sidecar-required content round-trips (csv with sidecar lookup fallback)", async () => {
+    // The disambig fallback in the import loop kicks in: the sidecar
+    // is keyed by canonical (path, ext) so the walker's
+    // `<base>__<id8>.csv` filename doesn't match the index — but the
+    // id-prefix lookup recovers the sidecar.
+    await store.createNote("month,total\n2026-01,9000", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Tabular/Budget-2026",
+      extension: "csv",
+    });
+    await store.createNote("month,total\n2026-01,1", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Tabular/budget-2026",
+      extension: "csv",
+    });
+
+    const outDir = join(tmpBase, "rt-csv");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+    });
+    expect(stats.disambiguated_paths).toHaveLength(1);
+
+    const restored = new SqliteStore(new Database(":memory:"));
+    const importStats = await importPortableVault(restored, { inDir: outDir, blowAway: true });
+    expect(importStats.notes_created).toBe(2);
+
+    const upper = await restored.getNote("2025-05-26-09-15-42-aaaaaa");
+    const lower = await restored.getNote("2025-05-26-09-15-42-bbbbbb");
+    expect(upper!.path).toBe("Tabular/Budget-2026");
+    expect(upper!.content).toBe("month,total\n2026-01,9000");
+    expect(lower!.path).toBe("Tabular/budget-2026");
+    expect(lower!.content).toBe("month,total\n2026-01,1");
+  });
+});