frameyard 0.8.0 → 0.9.0

package/dist/lint.js

@@ -0,0 +1,265 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { COMPOSITION_FORMAT_UNRESOLVED_MESSAGE } from "./composition/index.js";
+import { FrameyardError, errorMessage, isFrameyardError } from "./errors.js";
+import { validateHtmlComposition } from "./html/validate.js";
+import { evaluateKeyframeTrack } from "./timeline/keyframes.js";
+import { planTimelineRender } from "./timeline/plan.js";
+import { resolveProjectTimeline } from "./timeline/resolve.js";
+import { projectSceneAtFrame } from "./timeline/scene.js";
+import { KEYFRAME_CHANNELS } from "./timeline/schema.js";
+const DETERMINISM_PATTERNS = [
+    { pattern: /\bMath\.random\s*\(/, label: "Math.random()" },
+    { pattern: /\bDate\.now\s*\(/, label: "Date.now()" },
+    { pattern: /\bnew\s+Date\s*\(\s*\)/, label: "new Date()" },
+    { pattern: /\bperformance\.now\s*\(/, label: "performance.now()" },
+    { pattern: /\bsetTimeout\s*\(/, label: "setTimeout()" },
+    { pattern: /\bsetInterval\s*\(/, label: "setInterval()" },
+    { pattern: /\brequestAnimationFrame\s*\(/, label: "requestAnimationFrame()" },
+];
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new FrameyardError("CANCELLED", "Operation cancelled.");
+    }
+}
+function diagnosticKey(diagnostic) {
+    return JSON.stringify([diagnostic.severity, diagnostic.code, diagnostic.message, diagnostic.details ?? null]);
+}
+function addDiagnostic(diagnostics, diagnostic) {
+    const key = diagnosticKey(diagnostic);
+    if (!diagnostics.some((existing) => diagnosticKey(existing) === key)) {
+        diagnostics.push(diagnostic);
+    }
+}
+function lineColumnAt(source, index) {
+    const before = source.slice(0, index);
+    const lines = before.split("\n");
+    return {
+        line: lines.length,
+        column: (lines[lines.length - 1]?.length ?? 0) + 1,
+    };
+}
+function publicController(controller) {
+    if (controller === null) {
+        return null;
+    }
+    if (controller.kind === "external") {
+        return {
+            kind: "external",
+            ...(controller.src !== undefined ? { src: controller.src } : {}),
+        };
+    }
+    return { kind: "inline" };
+}
+async function scanController(controller, entry, projectRoot) {
+    if (controller === null) {
+        return [];
+    }
+    let source;
+    let sourcePath;
+    if (controller.kind === "inline") {
+        source = controller.source;
+        sourcePath = entry;
+    }
+    else if (controller.src !== undefined) {
+        sourcePath = controller.src;
+        try {
+            source = await readFile(path.resolve(projectRoot, controller.src), "utf8");
+        }
+        catch {
+            return [];
+        }
+    }
+    if (source === undefined) {
+        return [];
+    }
+    const diagnostics = [];
+    for (const { pattern, label } of DETERMINISM_PATTERNS) {
+        const index = source.search(pattern);
+        if (index === -1) {
+            continue;
+        }
+        const position = lineColumnAt(source, index);
+        const line = controller.kind === "inline" ? (controller.line ?? 1) + position.line - 1 : position.line;
+        const column = controller.kind === "inline" && position.line === 1
+            ? (controller.column ?? 1) + position.column - 1
+            : position.column;
+        diagnostics.push({
+            severity: "warning",
+            code: "DETERMINISM_WARNING",
+            message: `Controller source uses ${label}; derive animation from frame and props instead.`,
+            details: {
+                ...(sourcePath !== undefined ? { path: sourcePath } : {}),
+                line,
+                column,
+                controller: { kind: controller.kind },
+                suggestion: 'Use frame/props or random("stable:key") from frameyard/runtime.',
+            },
+        });
+    }
+    return diagnostics;
+}
+function collectCompositionSources(timeline, sources) {
+    for (const clip of timeline.clips) {
+        if (clip.source.kind === "composition") {
+            sources.push(clip.source);
+        }
+        else if (clip.source.kind === "timeline") {
+            collectCompositionSources(clip.source.timeline, sources);
+        }
+    }
+}
+function controllerKey(source) {
+    const controller = source.controller;
+    return [source.entry, controller?.kind ?? "none", controller?.src ?? "", controller?.source ?? ""].join("\u0000");
+}
+/**
+ * Validates a resolved timeline and projects every frame without launching
+ * Chromium. This catches scene and keyframe channel errors before `check`.
+ */
+export async function lintResolvedTimeline(options) {
+    const startedAt = performance.now();
+    const { timeline } = options;
+    const diagnostics = [...options.diagnostics];
+    const sources = [];
+    collectCompositionSources(timeline, sources);
+    const scanned = new Set();
+    for (const source of sources) {
+        const key = controllerKey(source);
+        if (scanned.has(key)) {
+            continue;
+        }
+        scanned.add(key);
+        for (const diagnostic of await scanController(source.controller, source.entry, options.projectRoot)) {
+            addDiagnostic(diagnostics, diagnostic);
+        }
+    }
+    for (let frame = 0; frame < timeline.durationInFrames; frame += 1) {
+        throwIfAborted(options.signal);
+        let scene;
+        try {
+            scene = projectSceneAtFrame(timeline, frame);
+        }
+        catch (error) {
+            addDiagnostic(diagnostics, {
+                severity: "error",
+                code: isFrameyardError(error) ? error.code : "TIMELINE_CLIP_INVALID",
+                message: `Timeline frame ${frame}: ${errorMessage(error)}`,
+                details: { timeline: timeline.id, timelineFrame: frame },
+            });
+            continue;
+        }
+        for (const layer of scene.layers) {
+            if (layer.keyframes === undefined) {
+                continue;
+            }
+            const localFrame = frame - layer.clip.start;
+            for (const channel of KEYFRAME_CHANNELS) {
+                const track = layer.keyframes[channel];
+                if (track === undefined) {
+                    continue;
+                }
+                try {
+                    evaluateKeyframeTrack(track, localFrame);
+                }
+                catch (error) {
+                    addDiagnostic(diagnostics, {
+                        severity: "error",
+                        code: isFrameyardError(error) ? error.code : "TIMELINE_CLIP_INVALID",
+                        message: `Timeline frame ${frame}, clip "${layer.clip.id}" channel ${channel}: ${errorMessage(error)}`,
+                        details: {
+                            timeline: timeline.id,
+                            clip: layer.clip.id,
+                            channel,
+                            timelineFrame: frame,
+                            frame: localFrame,
+                        },
+                    });
+                }
+            }
+        }
+    }
+    const plan = planTimelineRender(timeline);
+    return {
+        kind: "timeline",
+        timeline: timeline.id,
+        entry: timeline.entry,
+        format: timeline.format,
+        durationInFrames: timeline.durationInFrames,
+        framesProjected: timeline.durationInFrames,
+        tracks: timeline.tracks.length,
+        clips: timeline.clips.length,
+        transitions: timeline.transitions.length,
+        segments: plan.segments.length,
+        diagnostics,
+        elapsedMs: performance.now() - startedAt,
+    };
+}
+/** Validates one composition document and its controller source without Chromium. */
+export async function lintComposition(options) {
+    throwIfAborted(options.signal);
+    const startedAt = performance.now();
+    const composition = options.project.compositions.get(options.compositionId);
+    if (!composition) {
+        const available = [...options.project.compositions.keys()].join(", ") || "(none)";
+        throw new FrameyardError("COMPOSITION_NOT_FOUND", `Composition "${options.compositionId}" is not listed in fy.config.js. Available: ${available}.`);
+    }
+    const validation = await validateHtmlComposition({
+        projectRoot: options.project.root,
+        entry: composition.entry,
+        props: options.props,
+        ...(options.project.format ? { format: options.project.format } : {}),
+    });
+    const errors = validation.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (!validation.info || errors.length > 0) {
+        const first = errors[0];
+        if (!first && validation.formatUnresolved) {
+            throw new FrameyardError("COMPOSITION_FORMAT_UNRESOLVED", `Composition "${options.compositionId}": ${COMPOSITION_FORMAT_UNRESOLVED_MESSAGE}`, { diagnostics: validation.diagnostics });
+        }
+        throw new FrameyardError(first?.code ?? "COMPOSITION_INVALID", `Composition "${options.compositionId}": ${first?.message ?? "static validation failed."}`, { diagnostics: validation.diagnostics });
+    }
+    const diagnostics = [...validation.diagnostics];
+    for (const diagnostic of await scanController(validation.info.controller, composition.entry, options.project.root)) {
+        addDiagnostic(diagnostics, diagnostic);
+    }
+    return {
+        kind: "composition",
+        composition: options.compositionId,
+        entry: composition.entry,
+        controller: publicController(validation.info.controller),
+        metadata: validation.info.metadata,
+        framesProjected: 0,
+        diagnostics,
+        elapsedMs: performance.now() - startedAt,
+    };
+}
+/** Validates a project timeline without capturing frames or launching Chromium. */
+export async function lintTimeline(options) {
+    throwIfAborted(options.signal);
+    const projectTimeline = options.project.timelines.get(options.timelineId);
+    if (!projectTimeline) {
+        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in fy.config.js.`);
+    }
+    const resolved = await resolveProjectTimeline({
+        project: options.project,
+        timeline: projectTimeline,
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.propsOverrides ? { propsOverrides: options.propsOverrides } : {}),
+    });
+    const firstError = resolved.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+    if (!resolved.timeline || firstError) {
+        throw new FrameyardError(firstError?.code ?? "TIMELINE_INVALID", firstError?.message ?? "Timeline resolution failed.", { diagnostics: resolved.diagnostics });
+    }
+    const result = await lintResolvedTimeline({
+        timeline: resolved.timeline,
+        projectRoot: options.project.root,
+        diagnostics: resolved.diagnostics,
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const lintError = result.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+    if (lintError) {
+        throw new FrameyardError(lintError.code, lintError.message, { diagnostics: result.diagnostics });
+    }
+    return result;
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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"}

package/dist/policy.d.ts

@@ -0,0 +1,69 @@
+/** Project-local resource policy file discovered from the working directory upward. */
+export declare const POLICY_FILE_NAME = "fy.policy.json";
+export declare const POLICY_TIERS: readonly ["light", "authoring", "full"];
+export type PolicyTier = (typeof POLICY_TIERS)[number];
+export declare const RESOURCE_PROFILES: readonly ["shared-cpu"];
+export type ResourceProfile = (typeof RESOURCE_PROFILES)[number];
+export declare const MAX_STILL_FRAMES = 32;
+export declare const SHARED_CPU_MAX_WORKERS = 2;
+export declare const SHARED_CPU_MAX_CONCURRENCY = 1;
+export declare const TIER_DEFAULTS: Record<PolicyTier, {
+    maxStillFrames: number;
+    allowOverwrite: boolean;
+}>;
+export type PolicyOperation = "lint" | "context" | "doctor" | "init" | "dev" | "check" | "still" | "font" | "tts" | "transcribe" | "render";
+export interface LoadedResourcePolicy {
+    tier: PolicyTier;
+    profile?: ResourceProfile;
+    maxStillFrames: number;
+    allowOverwrite: boolean;
+    source: "default" | "file" | "env";
+    /** Absolute path of the policy file when `source` is `"file"`. */
+    path?: string;
+}
+export interface PolicyDescription {
+    policy: PolicyTier;
+    profile?: ResourceProfile;
+    maxStillFrames: number;
+    allowOverwrite: boolean;
+    source: LoadedResourcePolicy["source"];
+    path?: string;
+}
+/** Walks up from a directory until it finds fy.policy.json. */
+export declare function findPolicyFile(start?: string): Promise<string | undefined>;
+/**
+ * Loads the resource policy for the current workspace.
+ *
+ * `FRAMEYARD_POLICY` replaces the policy file entirely, so an explicit human
+ * override also resets the file's profile and tightened limits. Without the
+ * variable, the nearest `fy.policy.json` from `cwd` upward wins; without
+ * a file, the default is `full`.
+ */
+export declare function loadResourcePolicy(options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<LoadedResourcePolicy>;
+/** Resolves the effective profile from the CLI flag and the policy file. */
+export declare function resolveProfile(policy: LoadedResourcePolicy, requested: string | undefined): ResourceProfile | undefined;
+/** Returns the operation allowlist for a tier. */
+export declare function allowedOperations(tier: PolicyTier): PolicyOperation[];
+export declare function operationAllowed(tier: PolicyTier, operation: PolicyOperation): boolean;
+export declare function assertOperationAllowed(policy: LoadedResourcePolicy, operation: PolicyOperation, options?: {
+    dryRun?: boolean;
+}): void;
+/** Requires a minimum tier for subcommands that share one policy operation. */
+export declare function assertPolicyTier(policy: LoadedResourcePolicy, required: PolicyTier, operation: string): void;
+export declare function assertStillFrameLimit(policy: LoadedResourcePolicy, requested: number): void;
+export declare function assertOverwriteAllowed(policy: LoadedResourcePolicy, operation: "overwrite" | "force"): void;
+export declare function assertProfileLimit(profile: ResourceProfile, option: "workers" | "concurrency", requested: number, limit: number): void;
+export declare function shouldLowerPriority(policy: LoadedResourcePolicy, profile: ResourceProfile | undefined, requested: boolean): boolean;
+/**
+ * Lowers the current process priority so it yields to a local model. Children
+ * inherit the nice value on Unix. This is best effort on platforms that do not
+ * expose process priorities.
+ */
+export declare function lowerProcessPriority(): void;
+/** Serializable policy details for JSON results and diagnostics. */
+export declare function policyDetails(policy: LoadedResourcePolicy): PolicyDescription;
+export declare function describePolicy(policy: LoadedResourcePolicy): string;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}