@revola-ai/video-craft 0.2.1

package/src/types.ts

@@ -0,0 +1,181 @@
+import type { SourceFile } from "ts-morph";
+
+/** A live code location a prose rule asserts something about. */
+export type CodeAnchor = {
+  /** Repo-relative POSIX path. */
+  file: string;
+  /** Optional top-level symbol that must still exist in that file. */
+  symbol?: string;
+};
+
+export type SourceFinding = {
+  /** Repo-relative POSIX path. */
+  file: string;
+  /** 1-based. Diagnostic only; exceptions key on `match`, not on this. */
+  line: number;
+  /**
+   * The exact source text that triggered the finding (kept short, first ~60
+   * chars for larger nodes). This is what KNOWN_EXCEPTIONS keys on, so it
+   * must be stable under unrelated edits elsewhere in the file.
+   */
+  match: string;
+  message: string;
+};
+
+export type SourceCheck = {
+  /**
+   * Repo-relative globs. Explicit per project, because layouts differ:
+   * qpa-video/03_scenes/**\/*.jsx against revola-video/src/scenes/**\/*.tsx.
+   * "Scene files" is not a term this repo defines, so an implicit default
+   * would make each check's blast radius a guess.
+   */
+  include: string[];
+  /**
+   * Coarse escape hatch: globs a rule never applies to (a whole legacy
+   * subproject, a generated directory). Match-level KNOWN_EXCEPTIONS are the
+   * fine one. Merged into the runner's built-in ignore list.
+   */
+  exclude?: string[];
+  /** Pure over one parsed file. `relPath` is repo-relative POSIX; `root` is
+   *  the absolute scan root `relPath` resolves against. Threaded explicitly
+   *  because this package runs installed inside consumer repos, where any
+   *  walk-up-from-module-location guess points at the wrong tree. */
+  run: (file: SourceFile, relPath: string, root: string) => SourceFinding[];
+};
+
+/**
+ * The pipeline stages an agent can be dispatched for. Stage assignment is an
+ * audience property (who must read a rule), not part of the rule's claim, so
+ * it lives in the central `STAGES` table in `stages.ts` rather than on each
+ * rule: one file is auditable at a glance, and a mis-scoped rule is a
+ * one-line fix instead of an edit buried among 100 rule files.
+ *
+ * Scoping narrows attention, never authority: every rule still binds every
+ * stage. CLAUDE.md carries the gates and any waived rule in full and names the
+ * rest by id (video-toolchain-cg6); HOW_I_BUILD_VIDEOS.md is the one doc with
+ * every rule's claim, why and provenance. Stage sheets
+ * exist so a dispatched vo:record agent does not spend its attention on seam
+ * geometry, which is how prose rules get paraphrased (Track B measured 9 of
+ * 22 declared names dropped from an all-prose contract).
+ */
+export type Stage =
+  | "recon"
+  | "plan"
+  | "scene"
+  | "amplify"
+  | "review"
+  | "vo"
+  | "audio"
+  | "ship";
+
+export type Scope =
+  | { kind: "pipeline" }
+  | {
+      kind: "component";
+      /** Kit component slug, e.g. "rolling-number". */
+      slug: string;
+      field: "whenToUse" | "whenNotToUse" | "gotcha";
+    };
+
+export type Enforcement =
+  | { kind: "source"; check: SourceCheck }
+  | { kind: "prose"; anchor: CodeAnchor }
+  | { kind: "prose"; unanchorable: string };
+
+/**
+ * How much a violation costs, which decides where the rule is projected.
+ *
+ * Trial 3 run 1 spent three of five rebuild rounds on one defect whose rule was
+ * read and ticked off, and lost a brand mark to a rule nobody could verify. The
+ * registry was a flat list at the time, so a rule that costs a rebuild round
+ * rendered identically to a note about comment hygiene, and an agent short on
+ * context had no basis for choosing which to keep.
+ *
+ * - `gate`    a violation ships a broken film or blocks release. Must carry
+ *             `verify`: the command or procedure that settles it.
+ * - `craft`   applied by judgement while building. The bulk of the registry.
+ * - `process` how to work rather than what to draw - diff discipline, evidence,
+ *             build notes. Verifiable from the session, not from the render.
+ */
+export type Tier = "gate" | "craft" | "process";
+
+/**
+ * A client-directed waiver scoped to one project. The rule stays in force
+ * everywhere else; inside `project` the decision is settled, and a session must
+ * not "fix" the violation back to compliance - that is exactly the failure this
+ * field exists to prevent, because the claims are projected into CLAUDE.md and
+ * an unwaivered claim reads as an instruction.
+ *
+ * A waiver is not a deletion: the rule's claim, why and provenance stay
+ * intact, and the exception names where the overriding decision is recorded so
+ * the next reader can weigh it rather than inherit it blindly.
+ */
+export type RuleException = {
+  /** Project directory the waiver covers, e.g. "qse-qguard-video". */
+  project: string;
+  /** What was decided, one line. Names the decider when that is the point. */
+  decision: string;
+  /** Repo-relative POSIX path of the document recording the decision. */
+  recordedIn: string;
+  /**
+   * Named scope, finer than the whole project: a specific element (a
+   * component/symbol a finding's `where.symbol` names) the waiver covers.
+   * Omit for a film-wide waiver. At most one of `element`/`seam` is expected
+   * per exception - a waiver names either a standing element or a seam, not
+   * both - but that is a radar-side (`applyWaivers`) invariant, not enforced
+   * here.
+   */
+  element?: string;
+  /** Named scope: a specific seam (e.g. "once-stolen") the waiver covers,
+   *  matched the same way `element` is - against a finding's `where.symbol`,
+   *  since the radar's Finding schema carries no separate seam identity field. */
+  seam?: string;
+};
+
+export type Rule = {
+  /** Stable kebab-case id. Referenced from notes files, so it must not churn. */
+  id: string;
+  /** One imperative line. */
+  claim: string;
+  /** The concrete failure this prevents. */
+  why: string;
+  /**
+   * Required and deliberately un-defaulted. An optional tier would let every
+   * new rule land in whichever bucket the type happened to pick, which is the
+   * same silent-default failure that left every source check's `include` glob
+   * excluding qse-qguard-video for its entire build.
+   */
+  tier: Tier;
+  /**
+   * The command or one-line procedure that settles this rule, e.g.
+   * "video render-twice --project <dir> --comp <id>". Required on `gate`.
+   *
+   * A gate whose verify is a manual procedure is honest and useful: it states
+   * the check that is owed. A gate with no verify at all is a claim nobody can
+   * discharge, which is how `hero-fills-the-frame` was violated by a hero
+   * occupying a third of the screen - the words its own claim uses.
+   */
+  verify?: string;
+  /** Repo-relative path of the notes file it was mined from. History; immutable. */
+  learnedFrom: string;
+  /** Cite an upstream Remotion rule rather than restating it, e.g. "remotion:rules/timing.md". */
+  upstream?: string;
+  /** Per-project client-directed waivers. Rendered into every projection. */
+  exceptions?: RuleException[];
+  /**
+   * What discharges this rule's obligation in practice: either a radar
+   * check id (validated against the generated `radar-check-ids.json` - the
+   * check-id list crosses the video-cli/video-craft boundary as a generated
+   * artifact, the same direction `waiverProjection.ts` crosses it the other
+   * way, since craft must never runtime-import cli) or the literal string
+   * `"coherence"` for a rule the live coherence agent discharges by
+   * judgement rather than an automated check (e.g. `motion-density-floor`).
+   * Optional and un-projected onto every rule on purpose: most craft rules
+   * are outside the radar's domain entirely (a kit-pinning discipline, a
+   * process rule about diff hygiene) and naming an owner for one would be a
+   * fabricated claim, not a fact.
+   */
+  owner?: string;
+  scope: Scope;
+  enforcement: Enforcement;
+};

package/src/variants.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+import { COMPONENT_VARIANTS } from "./variants";
+
+describe("COMPONENT_VARIANTS", () => {
+  test("covers exactly the three Tier A components", () => {
+    expect(Object.keys(COMPONENT_VARIANTS).sort()).toEqual([
+      "animated-bar-chart",
+      "animated-line-chart",
+      "rolling-number",
+    ]);
+  });
+
+  test("every component has at least two variants and the default variant is listed first", () => {
+    expect(COMPONENT_VARIANTS["rolling-number"]).toEqual(["odometer", "slam"]);
+    expect(COMPONENT_VARIANTS["animated-bar-chart"]).toEqual(["grow", "cascade"]);
+    expect(COMPONENT_VARIANTS["animated-line-chart"]).toEqual(["draw", "sweep"]);
+  });
+
+  test("variant names are kebab-safe lowercase", () => {
+    for (const variants of Object.values(COMPONENT_VARIANTS)) {
+      for (const v of variants) expect(v).toMatch(/^[a-z0-9-]+$/);
+    }
+  });
+});

package/src/variants.ts

@@ -0,0 +1,13 @@
+/**
+ * Declared variant unions per Tier A component slug: the single source of
+ * truth that generate.ts projects into the .meta.ts sidecars (and from there
+ * into the manifest). The kit closes the loop with a drift test asserting
+ * each component's exported *_VARIANTS const equals its sidecar's variants,
+ * so a variant added in only one place fails the suite.
+ * Order matters: the FIRST entry is the component's default variant.
+ */
+export const COMPONENT_VARIANTS: Record<string, readonly string[]> = {
+  "rolling-number": ["odometer", "slam"],
+  "animated-bar-chart": ["grow", "cascade"],
+  "animated-line-chart": ["draw", "sweep"],
+};

package/src/waiverProjection.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { renderWaivers, renderWaiversJson } from "./waiverProjection";
+import type { Rule } from "./types";
+
+const rule = (over: Partial<Rule> = {}): Rule => ({
+  id: "some-rule",
+  claim: "c",
+  why: "w",
+  tier: "craft",
+  learnedFrom: "notes.md",
+  scope: { kind: "pipeline" },
+  enforcement: { kind: "prose", unanchorable: "no anchor" },
+  ...over,
+});
+
+describe("renderWaivers", () => {
+  it("projects every exception, tagged with its owning rule id", () => {
+    const rules = [rule({
+      id: "no-stacked-fades-at-a-cut",
+      exceptions: [{ project: "qse-qguard-video", decision: "d", recordedIn: "qse-qguard-video/docs/motion-brand-spec.md" }],
+    })];
+    expect(renderWaivers(rules)).toEqual([
+      { ruleId: "no-stacked-fades-at-a-cut", project: "qse-qguard-video", recordedIn: "qse-qguard-video/docs/motion-brand-spec.md" },
+    ]);
+  });
+
+  it("carries element/seam scope when the exception declares it", () => {
+    const rules = [rule({
+      id: "hero-fills-the-frame",
+      exceptions: [{ project: "acme-video", decision: "d", recordedIn: "acme-video/docs/spec.md", element: "logo" }],
+    })];
+    expect(renderWaivers(rules)[0]).toMatchObject({ element: "logo" });
+    expect(renderWaivers(rules)[0]).not.toHaveProperty("seam");
+  });
+
+  it("a rule with no exceptions contributes nothing", () => {
+    expect(renderWaivers([rule({ id: "no-exceptions-rule" })])).toEqual([]);
+  });
+
+  it("aggregates exceptions across every rule in the registry", () => {
+    const rules = [
+      rule({ id: "a", exceptions: [{ project: "p1", decision: "d", recordedIn: "p1/x.md" }] }),
+      rule({ id: "b", exceptions: [{ project: "p2", decision: "d", recordedIn: "p2/x.md" }] }),
+    ];
+    expect(renderWaivers(rules)).toHaveLength(2);
+  });
+});
+
+describe("renderWaiversJson", () => {
+  it("is deterministic (sorted) regardless of registry order", () => {
+    const a = rule({ id: "a", exceptions: [{ project: "p1", decision: "d", recordedIn: "p1/x.md" }] });
+    const b = rule({ id: "b", exceptions: [{ project: "p2", decision: "d", recordedIn: "p2/x.md" }] });
+    expect(renderWaiversJson([a, b])).toBe(renderWaiversJson([b, a]));
+  });
+
+  it("ends with a trailing newline", () => {
+    expect(renderWaiversJson([])).toBe("[]\n");
+  });
+});

package/src/waiverProjection.ts

@@ -0,0 +1,45 @@
+// Projects every rule's `exceptions` into the radar's waiver source. video-cli
+// must not runtime-import video-craft (that drags ts-morph into the CLI, and
+// craft already cannot import cli - see radar/waivers.ts's own header), so the
+// bridge is a generated JSON file: `scripts/generate.ts` calls
+// `renderWaiversJson` and writes `packages/video-cli/src/radar/
+// waivers.generated.json`, exactly the `radar-check-ids.json` mechanism
+// (Task 23) pointed the other way, with `drift.test.ts` guarding it never goes
+// stale.
+import type { Rule } from "./types";
+
+export type RuleWaiver = {
+  ruleId?: string;
+  checkId?: string;
+  project: string;
+  element?: string;
+  seam?: string;
+  recordedIn: string;
+};
+
+/** Every rule's exceptions, flattened and tagged with the owning rule's id.
+ *  No `checkId`-keyed waiver is ever produced from the registry - a rule
+ *  without a stable radar checkId equivalent doesn't exist today, so that
+ *  path (a check waivable by checkId alone) is fixture-tested only in
+ *  `waivers.test.ts`, not sourced from here. */
+export function renderWaivers(rules: Rule[]): RuleWaiver[] {
+  return rules.flatMap((rule) =>
+    (rule.exceptions ?? []).map((ex) => ({
+      ruleId: rule.id,
+      project: ex.project,
+      ...(ex.element !== undefined ? { element: ex.element } : {}),
+      ...(ex.seam !== undefined ? { seam: ex.seam } : {}),
+      recordedIn: ex.recordedIn,
+    })),
+  );
+}
+
+/** Sort key: same rule/project/scope always lands in the same place, so the
+ *  generated file's bytes don't depend on registry array order - the drift
+ *  test compares bytes, and a reordering-only change must not appear stale. */
+const sortKey = (w: RuleWaiver): string => `${w.ruleId ?? w.checkId ?? ""}:${w.project}:${w.element ?? ""}:${w.seam ?? ""}`;
+
+export function renderWaiversJson(rules: Rule[]): string {
+  const sorted = [...renderWaivers(rules)].sort((a, b) => (sortKey(a) < sortKey(b) ? -1 : sortKey(a) > sortKey(b) ? 1 : 0));
+  return JSON.stringify(sorted, null, 2) + "\n";
+}