@hoardodile/host 0.0.0

package/dist/contract/index.js

@@ -0,0 +1,187 @@
+import { Readable } from 'stream';
+import { afterAll, describe, test, expect } from 'vitest';
+
+// src/contract/container-fixture.ts
+function createContainerFixture(config = {}) {
+  const files = config.files ?? {};
+  function bytesOf(relPath) {
+    const content = files[relPath];
+    if (content === void 0) return void 0;
+    return typeof content === "string" ? new TextEncoder().encode(content) : content;
+  }
+  return {
+    async listEntries() {
+      return Object.keys(files);
+    },
+    async readEntry(relPath) {
+      const bytes = bytesOf(relPath);
+      if (bytes === void 0) {
+        throw new Error(`fixture container has no entry ${relPath}`);
+      }
+      return Buffer.from(bytes);
+    },
+    async readEntrySlice(relPath, start, end) {
+      const bytes = bytesOf(relPath);
+      if (bytes === void 0) {
+        throw new Error(`fixture container has no entry ${relPath}`);
+      }
+      const clampedStart = Math.min(Math.max(0, start), bytes.length);
+      const clampedEnd = Math.min(Math.max(clampedStart, end), bytes.length);
+      return Buffer.from(bytes.subarray(clampedStart, clampedEnd));
+    },
+    async openEntryStream(relPath) {
+      const bytes = bytesOf(relPath);
+      if (bytes === void 0) {
+        throw new Error(`fixture container has no entry ${relPath}`);
+      }
+      return { stream: Readable.from(bytes), size: bytes.length };
+    },
+    async resolveByteRange(relPath) {
+      const bytes = bytesOf(relPath);
+      return bytes === void 0 ? void 0 : { size: bytes.length };
+    }
+  };
+}
+var CONTAINER_CONTRACT_CASES = [
+  { name: "empty container", files: {} },
+  {
+    name: "flat files",
+    files: { "a.txt": "alpha", "b.bin": "beta", "c.jpg": "gamma" }
+  },
+  {
+    name: "nested entry names",
+    files: { "dir/a.txt": "nested a", "dir/sub/b.txt": "nested b" }
+  },
+  {
+    name: "binary content",
+    files: { "blob.bin": Uint8Array.from([0, 1, 2, 250, 255, 128]) }
+  },
+  { name: "empty entry", files: { "empty.txt": "" } },
+  {
+    name: "unicode entry names",
+    files: { "\u0424\u043E\u0442\u043E/\u044F.jpg": "unicode" }
+  }
+];
+function toBytes(content) {
+  return typeof content === "string" ? new TextEncoder().encode(content) : content;
+}
+async function collectManifest(api) {
+  const files = [...await api.listFileNames()].sort();
+  const manifest = {};
+  manifest.files = files;
+  for (const name of files) {
+    manifest[`stat:${name}`] = await api.statFile(name);
+    manifest[`read:${name}`] = Array.from(await api.readFile(name));
+    manifest[`range:${name}`] = Array.from(
+      await api.readFile(name, { start: 1, end: 3 })
+    );
+    manifest[`type:${name}`] = await api.sniff(name);
+    manifest[`probe:${name}`] = await api.probe(name);
+  }
+  const batched = await api.statFiles(files);
+  manifest.statAll = files.map((name, i) => ({
+    name,
+    stat: batched[i]
+  }));
+  manifest.missingStat = await api.statFile("missing-entry.bin");
+  manifest.missingStatAll = await api.statFiles(["missing-entry.bin"]);
+  return manifest;
+}
+function containerContractSuite(backends) {
+  afterAll(async () => {
+    await Promise.all(backends.map((b) => b.cleanup?.()));
+  });
+  describe("container contract", () => {
+    for (const backend of backends) {
+      describe(backend.name, () => {
+        for (const c of CONTAINER_CONTRACT_CASES) {
+          test(`case "${c.name}": core semantics`, async () => {
+            const api = await backend.build(c.files);
+            const names = Object.keys(c.files);
+            expect([...await api.listFileNames()].sort()).toEqual(
+              [...names].sort()
+            );
+            for (const name of names) {
+              const content = c.files[name];
+              if (content === void 0) continue;
+              const expected = toBytes(content);
+              expect(Array.from(await api.readFile(name))).toEqual([
+                ...expected
+              ]);
+              const mid = await api.readFile(name, {
+                start: 1,
+                end: Math.min(3, expected.length)
+              });
+              expect(Array.from(mid)).toEqual([
+                ...expected.slice(1, Math.min(3, expected.length))
+              ]);
+              const past = await api.readFile(name, {
+                start: expected.length + 5,
+                end: expected.length + 9
+              });
+              expect(past.byteLength).toBe(0);
+              expect(await api.statFile(name)).toEqual({
+                sizeBytes: expected.length
+              });
+            }
+            await expect(api.readFile("missing-entry.bin")).rejects.toThrow();
+            await expect(
+              api.statFile("missing-entry.bin")
+            ).resolves.toBeUndefined();
+            const singleStats = names.map(
+              (n) => c.files[n] !== void 0 ? { sizeBytes: toBytes(c.files[n]).length } : void 0
+            );
+            const batchStats = await api.statFiles(names);
+            expect(batchStats.length).toBe(names.length);
+            for (let i = 0; i < names.length; i++) {
+              expect(batchStats[i]).toEqual(singleStats[i]);
+            }
+            await expect(api.statFiles(["missing-entry.bin"])).resolves.toEqual(
+              [void 0]
+            );
+            for (const name of names) {
+              const type = await api.sniff(name);
+              const probed = await api.probe(name);
+              if (type !== void 0 && type.kind !== "other") {
+                expect(probed).toEqual({
+                  kind: "unknown",
+                  reason: "unavailable"
+                });
+              } else if (type !== void 0) {
+                expect(probed).toEqual({ kind: "other", mime: type.mime });
+              } else {
+                expect(probed).toEqual({
+                  kind: "unknown",
+                  reason: "unsupported"
+                });
+              }
+            }
+            await expect(
+              api.sniff("missing-entry.bin")
+            ).resolves.toBeUndefined();
+            await expect(api.probe("missing-entry.bin")).resolves.toEqual({
+              kind: "unknown",
+              reason: "unsupported"
+            });
+          });
+        }
+      });
+    }
+    for (const c of CONTAINER_CONTRACT_CASES) {
+      test(`case "${c.name}": identical results across backends`, async () => {
+        const results = [];
+        for (const backend of backends) {
+          const api = await backend.build(c.files);
+          results.push(await collectManifest(api));
+        }
+        for (let i = 1; i < results.length; i++) {
+          expect(results[i]).toEqual(results[0]);
+        }
+      });
+    }
+  });
+}
+
+export { CONTAINER_CONTRACT_CASES, containerContractSuite, createContainerFixture };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/contract/container-fixture.ts","../../src/contract/suite.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { Readable } from \"node:stream\"\nimport type { ResourceContainer } from \"../container.ts\"\n\n/** Declarative in-memory content for a {@link ResourceContainer}. */\nexport type ContainerFixtureConfig = {\n\t/** Entry name → content. Names may contain `/` for nesting. */\n\treadonly files?: Readonly<Record<string, string | Uint8Array>>\n}\n\n/**\n * An in-memory {@link ResourceContainer} driven by a declarative config.\n * The test double in the container contract suite: every assertion runs\n * against it, the directory container and the zip container, and the\n * three must agree.\n */\nexport function createContainerFixture(\n\tconfig: ContainerFixtureConfig = {},\n): ResourceContainer {\n\tconst files = config.files ?? {}\n\n\tfunction bytesOf(relPath: string): Uint8Array | undefined {\n\t\tconst content = files[relPath]\n\t\tif (content === undefined) return undefined\n\t\treturn typeof content === \"string\"\n\t\t\t? new TextEncoder().encode(content)\n\t\t\t: content\n\t}\n\n\treturn {\n\t\tasync listEntries(): Promise<readonly string[]> {\n\t\t\treturn Object.keys(files)\n\t\t},\n\n\t\tasync readEntry(relPath: string): Promise<Buffer> {\n\t\t\tconst bytes = bytesOf(relPath)\n\t\t\tif (bytes === undefined) {\n\t\t\t\tthrow new Error(`fixture container has no entry ${relPath}`)\n\t\t\t}\n\t\t\treturn Buffer.from(bytes)\n\t\t},\n\n\t\tasync readEntrySlice(\n\t\t\trelPath: string,\n\t\t\tstart: number,\n\t\t\tend: number,\n\t\t): Promise<Buffer> {\n\t\t\tconst bytes = bytesOf(relPath)\n\t\t\tif (bytes === undefined) {\n\t\t\t\tthrow new Error(`fixture container has no entry ${relPath}`)\n\t\t\t}\n\t\t\tconst clampedStart = Math.min(Math.max(0, start), bytes.length)\n\t\t\tconst clampedEnd = Math.min(Math.max(clampedStart, end), bytes.length)\n\t\t\treturn Buffer.from(bytes.subarray(clampedStart, clampedEnd))\n\t\t},\n\n\t\tasync openEntryStream(relPath: string): Promise<{\n\t\t\treadonly stream: Readable\n\t\t\treadonly size: number\n\t\t}> {\n\t\t\tconst bytes = bytesOf(relPath)\n\t\t\tif (bytes === undefined) {\n\t\t\t\tthrow new Error(`fixture container has no entry ${relPath}`)\n\t\t\t}\n\t\t\treturn { stream: Readable.from(bytes), size: bytes.length }\n\t\t},\n\n\t\tasync resolveByteRange(\n\t\t\trelPath: string,\n\t\t): Promise<{ readonly size: number } | undefined> {\n\t\t\tconst bytes = bytesOf(relPath)\n\t\t\treturn bytes === undefined ? undefined : { size: bytes.length }\n\t\t},\n\t}\n}\n","import { afterAll, describe, expect, test } from \"vitest\"\nimport type { ResourceAPI } from \"../types.ts\"\n\n/**\n * Shared contract suite for the container-backed {@link ResourceAPI}\n * implementations. Every backend (in-memory fixture, directory, zip\n * archive, and the server's own artifact view) must behave identically:\n * same entries, same bytes, same clamping, same probe semantics.\n *\n * Consumers build each backend from a declarative file map, then run the\n * whole suite with `containerContractSuite([...])` inside a test file.\n */\n\n/** A declarative container case: entry name → content. */\nexport type ContainerContractCase = {\n\treadonly name: string\n\treadonly files: Readonly<Record<string, string | Uint8Array>>\n}\n\nexport const CONTAINER_CONTRACT_CASES: readonly ContainerContractCase[] = [\n\t{ name: \"empty container\", files: {} },\n\t{\n\t\tname: \"flat files\",\n\t\tfiles: { \"a.txt\": \"alpha\", \"b.bin\": \"beta\", \"c.jpg\": \"gamma\" },\n\t},\n\t{\n\t\tname: \"nested entry names\",\n\t\tfiles: { \"dir/a.txt\": \"nested a\", \"dir/sub/b.txt\": \"nested b\" },\n\t},\n\t{\n\t\tname: \"binary content\",\n\t\tfiles: { \"blob.bin\": Uint8Array.from([0, 1, 2, 250, 255, 128]) },\n\t},\n\t{ name: \"empty entry\", files: { \"empty.txt\": \"\" } },\n\t{\n\t\tname: \"unicode entry names\",\n\t\tfiles: { \"Фото/я.jpg\": \"unicode\" },\n\t},\n]\n\nexport type ContractBackend = {\n\treadonly name: string\n\t/**\n\t * Build a {@link ResourceAPI} from a declarative file map. Called\n\t * once per case; must produce an independent instance each time.\n\t */\n\treadonly build: (\n\t\tfiles: Readonly<Record<string, string | Uint8Array>>,\n\t) => Promise<ResourceAPI>\n\t/** Optional teardown for resources created by `build` calls. */\n\treadonly cleanup?: () => Promise<void> | void\n}\n\nfunction toBytes(content: string | Uint8Array): Uint8Array {\n\treturn typeof content === \"string\"\n\t\t? new TextEncoder().encode(content)\n\t\t: content\n}\n\nasync function collectManifest(api: ResourceAPI): Promise<unknown> {\n\tconst files = [...(await api.listFileNames())].sort()\n\tconst manifest: Record<string, unknown> = {}\n\tmanifest.files = files\n\tfor (const name of files) {\n\t\tmanifest[`stat:${name}`] = await api.statFile(name)\n\t\tmanifest[`read:${name}`] = Array.from(await api.readFile(name))\n\t\tmanifest[`range:${name}`] = Array.from(\n\t\t\tawait api.readFile(name, { start: 1, end: 3 }),\n\t\t)\n\t\t// Identification must agree across backends too — the sniffer\n\t\t// reads through the same container abstraction.\n\t\tmanifest[`type:${name}`] = await api.sniff(name)\n\t\tmanifest[`probe:${name}`] = await api.probe(name)\n\t}\n\t// Batch stat: positions preserved, missing entries undefined.\n\tconst batched = await api.statFiles(files)\n\tmanifest.statAll = files.map((name, i) => ({\n\t\tname,\n\t\tstat: batched[i],\n\t}))\n\tmanifest.missingStat = await api.statFile(\"missing-entry.bin\")\n\tmanifest.missingStatAll = await api.statFiles([\"missing-entry.bin\"])\n\treturn manifest\n}\n\n/**\n * Run the full container contract suite against the given backends.\n * Must be called from within a vitest test file.\n */\nexport function containerContractSuite(\n\tbackends: readonly ContractBackend[],\n): void {\n\tafterAll(async () => {\n\t\tawait Promise.all(backends.map((b) => b.cleanup?.()))\n\t})\n\n\tdescribe(\"container contract\", () => {\n\t\tfor (const backend of backends) {\n\t\t\tdescribe(backend.name, () => {\n\t\t\t\tfor (const c of CONTAINER_CONTRACT_CASES) {\n\t\t\t\t\ttest(`case \"${c.name}\": core semantics`, async () => {\n\t\t\t\t\t\tconst api = await backend.build(c.files)\n\t\t\t\t\t\tconst names = Object.keys(c.files)\n\n\t\t\t\t\t\texpect([...(await api.listFileNames())].sort()).toEqual(\n\t\t\t\t\t\t\t[...names].sort(),\n\t\t\t\t\t\t)\n\n\t\t\t\t\t\tfor (const name of names) {\n\t\t\t\t\t\t\tconst content = c.files[name]\n\t\t\t\t\t\t\tif (content === undefined) continue\n\t\t\t\t\t\t\tconst expected = toBytes(content)\n\t\t\t\t\t\t\texpect(Array.from(await api.readFile(name))).toEqual([\n\t\t\t\t\t\t\t\t...expected,\n\t\t\t\t\t\t\t])\n\n\t\t\t\t\t\t\tconst mid = await api.readFile(name, {\n\t\t\t\t\t\t\t\tstart: 1,\n\t\t\t\t\t\t\t\tend: Math.min(3, expected.length),\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\texpect(Array.from(mid)).toEqual([\n\t\t\t\t\t\t\t\t...expected.slice(1, Math.min(3, expected.length)),\n\t\t\t\t\t\t\t])\n\n\t\t\t\t\t\t\tconst past = await api.readFile(name, {\n\t\t\t\t\t\t\t\tstart: expected.length + 5,\n\t\t\t\t\t\t\t\tend: expected.length + 9,\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\texpect(past.byteLength).toBe(0)\n\n\t\t\t\t\t\t\texpect(await api.statFile(name)).toEqual({\n\t\t\t\t\t\t\t\tsizeBytes: expected.length,\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Missing entries: readFile rejects, statFile is undefined.\n\t\t\t\t\t\tawait expect(api.readFile(\"missing-entry.bin\")).rejects.toThrow()\n\t\t\t\t\t\tawait expect(\n\t\t\t\t\t\t\tapi.statFile(\"missing-entry.bin\"),\n\t\t\t\t\t\t).resolves.toBeUndefined()\n\n\t\t\t\t\t\t// Batch stat matches the single-stats, in order.\n\t\t\t\t\t\tconst singleStats = names.map((n) =>\n\t\t\t\t\t\t\tc.files[n] !== undefined\n\t\t\t\t\t\t\t\t? { sizeBytes: toBytes(c.files[n]!).length }\n\t\t\t\t\t\t\t\t: undefined,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tconst batchStats = await api.statFiles(names)\n\t\t\t\t\t\texpect(batchStats.length).toBe(names.length)\n\t\t\t\t\t\tfor (let i = 0; i < names.length; i++) {\n\t\t\t\t\t\t\texpect(batchStats[i]).toEqual(singleStats[i])\n\t\t\t\t\t\t}\n\t\t\t\t\t\tawait expect(api.statFiles([\"missing-entry.bin\"])).resolves.toEqual(\n\t\t\t\t\t\t\t[undefined],\n\t\t\t\t\t\t)\n\n\t\t\t\t\t\t// Contract backends wire no probe implementations, so\n\t\t\t\t\t\t// identified media reports the dedicated \"no backend\"\n\t\t\t\t\t\t// reason instead of looking like a decode failure,\n\t\t\t\t\t\t// while non-media entries still identify normally.\n\t\t\t\t\t\tfor (const name of names) {\n\t\t\t\t\t\t\tconst type = await api.sniff(name)\n\t\t\t\t\t\t\tconst probed = await api.probe(name)\n\t\t\t\t\t\t\tif (type !== undefined && type.kind !== \"other\") {\n\t\t\t\t\t\t\t\texpect(probed).toEqual({\n\t\t\t\t\t\t\t\t\tkind: \"unknown\",\n\t\t\t\t\t\t\t\t\treason: \"unavailable\",\n\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t} else if (type !== undefined) {\n\t\t\t\t\t\t\t\texpect(probed).toEqual({ kind: \"other\", mime: type.mime })\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\texpect(probed).toEqual({\n\t\t\t\t\t\t\t\t\tkind: \"unknown\",\n\t\t\t\t\t\t\t\t\treason: \"unsupported\",\n\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Neither call rejects on a missing entry.\n\t\t\t\t\t\tawait expect(\n\t\t\t\t\t\t\tapi.sniff(\"missing-entry.bin\"),\n\t\t\t\t\t\t).resolves.toBeUndefined()\n\t\t\t\t\t\tawait expect(api.probe(\"missing-entry.bin\")).resolves.toEqual({\n\t\t\t\t\t\t\tkind: \"unknown\",\n\t\t\t\t\t\t\treason: \"unsupported\",\n\t\t\t\t\t\t})\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t})\n\t\t}\n\n\t\tfor (const c of CONTAINER_CONTRACT_CASES) {\n\t\t\ttest(`case \"${c.name}\": identical results across backends`, async () => {\n\t\t\t\tconst results = []\n\t\t\t\tfor (const backend of backends) {\n\t\t\t\t\tconst api = await backend.build(c.files)\n\t\t\t\t\tresults.push(await collectManifest(api))\n\t\t\t\t}\n\t\t\t\tfor (let i = 1; i < results.length; i++) {\n\t\t\t\t\texpect(results[i]).toEqual(results[0])\n\t\t\t\t}\n\t\t\t})\n\t\t}\n\t})\n}\n"]}