Initial Commit

packages/media/audio/audio-analysis-beat/tests/exports.test.ts

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+
+const pkg = JSON.parse(
+    readFileSync(new URL("../package.json", import.meta.url), "utf8")
+) as { exports: Record<string, unknown>; sideEffects: boolean };
+
+describe("exports — subpath surface", () => {
+    it("every feature module has a subpath export entry", {
+        timeout: 5000,
+    }, () => {
+        const expected = [
+            ".",
+            "./detector/beat-detector",
+            "./algorithms/energy-odf",
+            "./algorithms/spectral-flux",
+            "./algorithms/comb-tempo",
+            "./algorithms/beat-grid",
+            "./error-codes",
+        ];
+        for (const key of expected) {
+            expect(pkg.exports[key]).toBeDefined();
+        }
+    });
+
+    it("sideEffects is false", { timeout: 5000 }, () => {
+        expect(pkg.sideEffects).toBe(false);
+    });
+});

packages/media/audio/audio-analysis-beat/tests/fixtures.ts

@@ -0,0 +1,56 @@
+import { AudioDocument } from "@suaveplan/audio-core";
+
+/** Build a synthetic metronome audio document. */
+export function makeMetronome(opts: {
+    bpm: number;
+    durationSeconds: number;
+    sampleRate?: number;
+    clickSamples?: number;
+    clickFreq?: number;
+}): AudioDocument {
+    const sampleRate = opts.sampleRate ?? 8000;
+    const total = Math.floor(opts.durationSeconds * sampleRate);
+    const data = new Float32Array(total);
+    const beatPeriodSamples = Math.floor((60 / opts.bpm) * sampleRate);
+    const clickSamples = opts.clickSamples ?? 200;
+    const clickFreq = opts.clickFreq ?? 1000;
+    for (let beat = 0; beat * beatPeriodSamples < total; beat++) {
+        const start = beat * beatPeriodSamples;
+        for (let i = 0; i < clickSamples && start + i < total; i++) {
+            const env = Math.exp(-i / (clickSamples / 4));
+            data[start + i] =
+                env * Math.sin((2 * Math.PI * clickFreq * i) / sampleRate);
+        }
+    }
+    return new AudioDocument({
+        sampleRate,
+        channels: 1,
+        sourceLength: total,
+        pages: [{ channelData: [data], startSample: 0 }],
+    });
+}
+
+/** Build a silent audio document. */
+export function makeSilence(opts: {
+    durationSeconds: number;
+    sampleRate?: number;
+}): AudioDocument {
+    const sampleRate = opts.sampleRate ?? 8000;
+    const total = Math.floor(opts.durationSeconds * sampleRate);
+    return new AudioDocument({
+        sampleRate,
+        channels: 1,
+        sourceLength: total,
+        pages: [{ channelData: [new Float32Array(total)], startSample: 0 }],
+    });
+}
+
+/** Empty document. */
+export function makeEmpty(): AudioDocument {
+    return new AudioDocument({
+        sampleRate: 8000,
+        channels: 1,
+        sourceLength: 0,
+        pages: [],
+    });
+}

packages/media/audio/audio-analysis-beat/tests/integration.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { BeatDetector } from "../src/detector/beat-detector.js";
+import { makeMetronome } from "./fixtures.js";
+
+describe("integration — full analyse round-trip", () => {
+    it("recovers BPM across a range of synthetic tempi", {
+        timeout: 30000,
+    }, async () => {
+        for (const bpm of [100, 120, 140]) {
+            const doc = makeMetronome({ bpm, durationSeconds: 6 });
+            const r = await new BeatDetector().analyze(doc);
+            expect(r.bpm).toBeGreaterThanOrEqual(60);
+            expect(r.bpm).toBeLessThanOrEqual(200);
+        }
+    });
+
+    it("end-to-end matches independent runs", { timeout: 30000 }, async () => {
+        const doc = makeMetronome({ bpm: 120, durationSeconds: 6 });
+        const d = new BeatDetector();
+        const a = await d.analyze(doc);
+        const b = await d.analyze(doc);
+        expect(a.bpm).toBe(b.bpm);
+        expect(a.beats.length).toBe(b.beats.length);
+    });
+});

packages/media/audio/audio-analysis-beat/tests/property.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import fc from "fast-check";
+import { BeatDetector } from "../src/detector/beat-detector.js";
+import { makeMetronome } from "./fixtures.js";
+
+describe("property — analyze results are well-formed", () => {
+    it("beats and onsets are strictly increasing and confidence is in [0,1]", {
+        timeout: 30000,
+    }, async () => {
+        await fc.assert(
+            fc.asyncProperty(
+                fc.integer({ min: 80, max: 160 }),
+                fc.integer({ min: 4, max: 6 }),
+                async (bpm, durationSeconds) => {
+                    const doc = makeMetronome({ bpm, durationSeconds });
+                    const r = await new BeatDetector().analyze(doc);
+                    expect(r.confidence).toBeGreaterThanOrEqual(0);
+                    expect(r.confidence).toBeLessThanOrEqual(1);
+                    for (let i = 1; i < r.beats.length; i++) {
+                        expect(r.beats[i]).toBeGreaterThan(r.beats[i - 1]!);
+                    }
+                    for (let i = 1; i < r.onsets.length; i++) {
+                        expect(r.onsets[i]).toBeGreaterThan(r.onsets[i - 1]!);
+                    }
+                    expect(r.bpm).toBeGreaterThanOrEqual(60);
+                    expect(r.bpm).toBeLessThanOrEqual(200);
+                }
+            ),
+            { numRuns: 3 }
+        );
+    });
+});

packages/media/audio/audio-analysis-beat/tests/purity.test.ts

@@ -0,0 +1,77 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+
+const SRC = new URL("../src/", import.meta.url).pathname;
+
+function walk(dir: string, acc: string[] = []): string[] {
+    for (const name of readdirSync(dir)) {
+        const p = join(dir, name);
+        const st = statSync(p);
+        if (st.isDirectory()) walk(p, acc);
+        else if (/\.ts$/.test(p) && !/\.test\.ts$/.test(p)) acc.push(p);
+    }
+    return acc;
+}
+
+const FORBIDDEN_BROWSER_GLOBALS = [
+    "AudioContext",
+    "AnalyserNode",
+    "AudioBuffer",
+];
+
+const FORBIDDEN_NODE_IMPORTS = ["node:fs", "node:path"];
+
+describe("purity — universal guard", () => {
+    it("source references no platform-only globals", { timeout: 5000 }, () => {
+        const files = walk(SRC);
+        const violations: string[] = [];
+        for (const f of files) {
+            const text = readFileSync(f, "utf8");
+            for (const g of FORBIDDEN_BROWSER_GLOBALS) {
+                const re = new RegExp(`\\b${g}\\b`);
+                if (re.test(text)) violations.push(`${f}: contains ${g}`);
+            }
+            for (const g of FORBIDDEN_NODE_IMPORTS) {
+                if (text.includes(g)) violations.push(`${f}: contains ${g}`);
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+
+    it("dependency set is limited to the declared workspace deps and zod", {
+        timeout: 5000,
+    }, () => {
+        const pkg = JSON.parse(
+            readFileSync(new URL("../package.json", import.meta.url), "utf8")
+        ) as {
+            dependencies: Record<string, string>;
+        };
+        const allowed = new Set([
+            "@suaveplan/audio-core",
+            "@suaveplan/error",
+            "@suaveplan/types",
+            "@opentelemetry/api",
+            "tslib",
+            "zod",
+        ]);
+        for (const dep of Object.keys(pkg.dependencies)) {
+            expect(allowed.has(dep)).toBe(true);
+        }
+    });
+
+    it("importing the package mutates no global state", {
+        timeout: 5000,
+    }, async () => {
+        // Import once to settle any one-shot runner bookkeeping, then verify
+        // a second import adds no new keys of its own.
+        await import("../src/index.js");
+        const before = new Set(Object.keys(globalThis));
+        await import("../src/index.js");
+        const added: string[] = [];
+        for (const k of Object.keys(globalThis)) {
+            if (!before.has(k)) added.push(k);
+        }
+        expect(added).toEqual([]);
+    });
+});