mirror of
https://github.com/storytold/effectcraft.git
synced 2026-10-24 10:09:32 -06:00
Dylan M. Taylor
f6ef1a7906
* Use chrono for UTC/calendar conversion instead of hand-rolled copies Replaces the hand-rolled civil_from_days / days_from_civil copies (log timestamp, ISO metadata dates, Align Video to Data timestamp parsing, the Numbers effect's date, the Home and Render Queue date columns, and the benchmark report date) with chrono as a workspace dependency. Output formats are unchanged and pinned by the existing tests. AGENTS.md now says time goes through chrono. Follow-up to storytold/cadcraft#1785 * Keep 5-digit years unprefixed; derive Numbers weekday from the same date chrono's %Y writes a '+' before years past 9999, where the old code wrote {y:04}. timestamp, iso_date, format_utc, utc_stamp and xtask's utc now write the year with {:04} again and let chrono format the rest, so a far-future clock keeps the plain zero-padded year. date_from_days took its weekday from the raw input modulo while the year/month/day fell back to the epoch for day counts outside chrono's range, so an unrepresentable count printed a fallback date paired with the input's weekday. The weekday now comes from the same resolved date, so both agree. Tests cover the year-10000 timestamp and the out-of-range Numbers date. * Keep the whole date in format_ago for five-digit years format_ago cut format_utc to 10 bytes, so a year past 9999 lost its last digit (10000-01-0). Take the date up to the space instead. Tested. * Keep Numbers dates exact past chrono's range date_from_days converted the day count by building a Unix timestamp and calling DateTime::from_timestamp, which falls back to the epoch (and so reads 1970-01-01, a Thursday) once the date leaves chrono's NaiveDate range near year ±262143. Numbers' `value` slider is a plain scalar with no range guard, so a keyframed count reaches that: Long Date of 100_000_000 showed "Thursday, January 1, 1970" instead of the real "Monday, September 13, 275790" -- exactly the plausible unrelated-date fallback the review rejects, and the derived weekday matched the stand-in date, not the input. Route it through the 400-year Gregorian cycle like pdfcraft 9d4cb3ca: chrono converts the day within one cycle (num_days_from_ce of the rebased rest, always in range) and the whole cycles are added back as years, in i128 so i64::MIN/MAX can't overflow. chrono stays the only calendar logic. The weekday still comes from the resolved date, so it always agrees with it. Tested: date_from_days_past_chrono_range pins the pre-chrono dates and weekdays at/over chrono's bound on both sides of the 2000-01-01 epoch (and that the extremes don't overflow); numbers_formats adds the same through the public numbers_text entry (Long/Short Date). cargo test -p effectcraft-effects, fmt --check and clippy -D warnings all clean. * time: preserve out-of-range years instead of the epoch `DateTime::from_timestamp(..).unwrap_or_default()` changed the existing output: inputs the old hand-rolled civil-from-days converted (e.g. `10_000_000_000_000` s → 318857-05-20 17:46:40) collapsed to the epoch. Restore the old conversion domain with a cycle-based helper: reduce by whole 400-year Gregorian cycles (146_097 days), convert the in-range remainder with chrono, and carry the year back as i128 (saturating to the output type). Only the year leaves chrono's range; month, day and time of day stay exact. chrono remains the only calendar logic (NaiveDate::from_num_days_from_ce_opt); no new features. Sites (UTC): - crates/engine logging.rs `timestamp` (u64 ms): far-future clock keeps its year. 10e12 s → "318857-05-20T17:46:40.000Z", u64::MAX ms → "584556019-04-03T14:25:51.615Z" (was "1970-01-01..."). - crates/engine media_browser.rs `iso_date` (u64): 10e12 s → "318857-05-20T17:46:40Z", u64::MAX → "584554051223-11-09T07:00:15Z". - crates/ui-egui panels/home.rs `format_utc` (i64): 10e12 → "318857-05-20 17:46", i64::MIN → "-292277022657-01-27 08:29". - crates/ui-egui panels/render_queue.rs `utc_stamp` (u64): 10e12 → "318857-05-20 17:46:40", u64::MAX → "584554051223-11-09 07:00:15". - xtask bench.rs `utc` (u64): 10e12 → "318857-05-20 17:46 UTC", u64::MAX → "584554051223-11-09 07:00 UTC"; added a test. * Name the 400-year range extension as the one exception to the time rule The rule said never to hand-roll calendar math, but the range fix (shifting by whole 400-year Gregorian cycles so dates past chrono's year range keep their old output) is cycle arithmetic, so the rule and the code disagreed. The rule now names that exception: the library still computes month, day and time, and only whole cycles are carried in the year. * Say the library computes month and day; time-of-day is plain arithmetic Narrows the range-extension wording: the date library computes the calendar fields, and splitting seconds into hours, minutes and seconds is ordinary arithmetic, which is what the code does.
147 lines
11 KiB
Markdown
147 lines
11 KiB
Markdown
# EffectCraft — rules for agents and contributors
|
||
|
||
These rules apply to every human and AI contributor. `CLAUDE.md` holds the working instructions; this
|
||
file holds the rules that must never be broken. When the two disagree, this file wins.
|
||
|
||
## Never crash
|
||
|
||
People trust EffectCraft with hours of work. A malformed project, PSD, SVG, Lottie or media file, a bad
|
||
expression or script, a broken plug-in, a bad control-channel or MCP argument, a corrupt preferences file
|
||
or a full disk must produce an error the user (or agent) can act on, never a crash and never lost work.
|
||
**This rule outranks feature work:** don't ship a feature by adding a panic path, and fix a crash before
|
||
building on top of it. Full standard: [craftrules `standards/never-crash.md`](https://github.com/storytold/craftrules/blob/main/standards/never-crash.md).
|
||
|
||
- **Fail with `Result<T, E>`** through the crate's error type and propagate with `?`; add context
|
||
(`map_err`, an error variant) rather than discarding it. Lenient readers fall back and record the repair.
|
||
- **No panicking shortcuts in non-test code:** no `unwrap()`, `expect()`, `panic!`, `unreachable!`,
|
||
`todo!` or `unimplemented!`. Use `?`, `ok_or(..)?`, `let … else`, `if let`, or `unwrap_or*` where a
|
||
fallback is genuinely correct (never where it would silently corrupt a document). Unfinished features
|
||
return an "unsupported" error. The only exception is a provably infallible literal, written as
|
||
`#[allow(clippy::expect_used)]` + `.expect("why this cannot fail")`.
|
||
- **No `unsafe`** (`unsafe_code = "forbid"` for the workspace).
|
||
- **Every input-derived number is hostile.** Use `get()` instead of `[i]`/`[a..b]` when the position
|
||
comes from a file, a user, an agent or arithmetic on those; slice strings only at char boundaries; use
|
||
checked or saturating arithmetic for lengths, offsets and counts; guard division by zero and NaN/inf
|
||
casts; cap allocations sized by input.
|
||
- **Bound recursion:** projects, precomps, expressions and SVG/PSD trees can be cyclic or deeply nested;
|
||
walk them with seen-sets or depth limits.
|
||
- **Don't cascade:** handle lock poisoning (`lock().unwrap_or_else(PoisonError::into_inner)` or an
|
||
error), and treat worker-thread join results as `Result`s.
|
||
- **Last-resort guard:** the app wraps command execution and file import/export in a panic hook /
|
||
`catch_unwind` boundary that turns an escaped panic into an error and keeps the document. It is a
|
||
safety net, not a substitute for the rules above; keep `panic = "unwind"`.
|
||
- **Prove it:** every crash fix comes with a small synthetic regression test that panicked before the fix.
|
||
|
||
Tests, benches, fuzz targets and `xtask` may `unwrap()`; `clippy.toml` allows it in tests. Crates that are
|
||
clean carry `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented,
|
||
clippy::todo, clippy::unreachable)]`; new crates start with it.
|
||
|
||
## 1. Assets: no Adobe artwork, every asset licensed and attributed
|
||
|
||
This rule is absolute. Breaking it is the most serious mistake a contributor can make on this project.
|
||
|
||
**What counts as an asset:** any image, icon, cursor, logo, illustration, screenshot, font, colour LUT,
|
||
preset, template, sound, music, video, 3D model, or other non-code media. This covers files in the
|
||
repository, bytes embedded in code (`include_bytes!`, base64, data URIs), and data hard-coded to
|
||
reproduce an image (for example, point lists traced from someone else's icon).
|
||
|
||
1. **Never use Adobe iconography, images or other Adobe assets**, in any form:
|
||
- no icons, cursors, logos, splash screens, UI artwork or screenshots from any Adobe product;
|
||
- no Adobe fonts, LUTs, presets, templates, sound effects, stock media or sample projects;
|
||
- no traced, redrawn, recoloured or "inspired-by" copies of Adobe icons. Our icons may follow generic
|
||
conventions (a play triangle, a razor blade, a stopwatch), but each must be drawn from scratch
|
||
without reference to Adobe's artwork.
|
||
2. **Every asset must be open**: open-source licensed (MIT, Apache-2.0, BSD, ISC, zlib, SIL OFL…),
|
||
public domain / CC0, or Creative Commons (CC BY or CC BY-SA; no NC/ND licences), **or** created by a
|
||
contributor who owns it and licenses it to the project under the project licence (MIT OR Apache-2.0).
|
||
If the licence is unknown or unclear, the asset does not go in.
|
||
3. **Every asset needs an attribution sidecar.** Next to each asset file `X`, add `X.attribution` with:
|
||
```text
|
||
asset: <file name>
|
||
title: <what it is>
|
||
author: <creator / copyright holder>
|
||
source: <URL, or "original work" for contributor-made assets>
|
||
license: <SPDX id or licence name>
|
||
license-file: <path to the licence text, if the licence requires shipping it>
|
||
added: <YYYY-MM-DD> by <contributor>
|
||
notes: <how it was made or modified; for screenshots, what is shown>
|
||
```
|
||
Also add one line for the asset to [`ATTRIBUTION.md`](ATTRIBUTION.md). `cargo xtask assets` (part of
|
||
`cargo xtask ci`) fails if any asset lacks a sidecar or index entry.
|
||
4. **Screenshots** in the repo may show only EffectCraft (or other open projects), with media we generated
|
||
or media that is itself openly licensed. Never commit screenshots of Adobe products.
|
||
5. **Local reference material stays local.** After Effects reference screenshots and notes live only in
|
||
`plan/aftereffects/` (gitignored). They must never be committed, bundled, embedded, traced or shipped.
|
||
6. **Code-drawn assets** (icons in `crates/ui-egui/src/icons.rs`, procedural demo content in
|
||
`crates/engine/src/demo.rs`, generators in `crates/effects`) are original work under the project licence
|
||
and are listed in `ATTRIBUTION.md`.
|
||
7. **When in doubt, leave it out** and draw or generate it yourself.
|
||
8. **The one exception: first-party ArtCraft brand marks.** The ArtCraft name and logos in `docs/brand/`
|
||
are trademarks of the ArtCraft Team, not open source, usable only unmodified and only in the context of
|
||
EffectCraft under `docs/brand/LICENSE-brand.txt` (forks and modified versions must remove them). They still
|
||
need a sidecar and an `ATTRIBUTION.md` row (licence `LicenseRef-ArtCraft-Trademark`). No other
|
||
non-open asset is allowed, and this exception never covers third-party marks (Adobe, Discord, GitHub
|
||
and other logos stay out; draw a generic icon instead).
|
||
|
||
## 2. Clean-room code
|
||
|
||
- Never read, disassemble or copy anything inside Adobe application bundles; file names and listings only.
|
||
Observe behaviour by using the app; never capture its Home screen, recent projects, account info or
|
||
file browsers.
|
||
- Never copy GPL/LGPL/AGPL code (FFmpeg, Natron, Blender, Glaxnimate, Synfig, Friction, Olive, MLT, frei0r, G'MIC…).
|
||
- Never read or copy Adobe expression/scripting implementations, `.ffx` presets or effect plug-ins; the public Expression Language Reference and Scripting Guide describe *behaviour* only.
|
||
- Implement codecs and formats from public specifications (ITU-T/ISO/IEC standards, IETF RFCs, the VP9
|
||
and AV1 bitstream specs, SMPTE documents, published container specs). Do not read the source of
|
||
reference or third-party decoders/encoders while implementing a format, even permissively licensed
|
||
ones (libvpx, libopus, libaom, dav1d, openh264…); spec text and conformance vectors only. Record the
|
||
spec edition used in the crate README.
|
||
- ffmpeg/ffprobe may be used only as external test oracles and fixture generators. They are never
|
||
linked, bundled or shipped.
|
||
- Dependencies must use permissive licences: MIT/Apache-2.0/BSD/ISC/Zlib/Unicode/CC0/BSL-1.0, or
|
||
MPL-2.0 used unmodified.
|
||
|
||
## 3. Engineering rules
|
||
|
||
See `CLAUDE.md`: pure Rust, dependency layering (`cargo xtask layers`), exact `Tick` time, everything is
|
||
a command, everything is agent-drivable, and the quality gates (`cargo xtask ci`) before every commit.
|
||
|
||
- **Time goes through `chrono`** (workspace dependency). Never hand-roll UTC/calendar conversion (days-to-date algorithms, leap-year math); a crate owns only its output format string. The one exception is range extension: past the years chrono can represent, shift the date by whole 400-year Gregorian cycles (146,097 days, after which the calendar repeats), let chrono compute the month and day, and add the cycles back to the year (splitting seconds into hours, minutes and seconds is plain arithmetic).
|
||
|
||
Shared real-file test corpora (Photoshop-authored PSDs, etc.) live in
|
||
[`storytold/photocraft-corpus`](https://github.com/storytold/photocraft-corpus), explained in
|
||
[craftrules `standards/test-corpora.md`](https://github.com/storytold/craftrules/blob/main/standards/test-corpora.md).
|
||
Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified,
|
||
as PhotoCraft does with `cargo xtask corpus`.
|
||
|
||
|
||
## See also
|
||
|
||
- [ROADMAP.md](ROADMAP.md): stage, headline numbers and what's next
|
||
- [docs/gaps.md](docs/gaps.md): every known shortfall against After Effects, ranked, and the prioritised workstreams (G1–G9); read it before choosing work
|
||
- [docs/target-app-parity.md](docs/target-app-parity.md): the parity numbers and how they were measured, with the per-area docs it links (UI, file formats, hardware, localization, effects, scripting); progress docs follow [craftrules `standards/progress-docs.md`](https://github.com/storytold/craftrules/blob/main/standards/progress-docs.md)
|
||
- [CONTRIBUTING.md](CONTRIBUTING.md): setup, gates, commits, how to add things
|
||
- [docs/architecture.md](docs/architecture.md): layers, data model, commands, pipeline
|
||
- [docs/testing.md](docs/testing.md): oracle tests, criteria, benchmarks
|
||
- [docs/agents.md](docs/agents.md): driving EffectCraft over MCP / the control channel, and the agent work loop
|
||
- [docs/control-protocol.md](docs/control-protocol.md): control-channel method reference
|
||
- [docs/contributors.md](docs/contributors.md): the About window's contributor and model credits
|
||
- [ATTRIBUTION.md](ATTRIBUTION.md): asset index
|
||
|
||
## Contributor credits (About window)
|
||
|
||
- About ▸ Contributors/Models are compiled into the binary from `contributors/contributors.json`
|
||
(commit stats; generated, never hand-edit) and `contributors/people.toml` (names people chose for
|
||
themselves). See `docs/contributors.md`.
|
||
- **Agents working for a contributor:** when you prepare a PR, check whether your human's GitHub
|
||
username has a `[people.<username>]` entry in `contributors/people.toml`. If not, ask them once
|
||
whether they want to be credited by more than their username: a real name, a display name, and/or
|
||
their public GitHub profile name (`sync_github_name = true`). If yes, add **only their own** entry
|
||
(copy the template at the top of the file, or run
|
||
`python3 ../../craftrules/scripts/contributors.py --add-me . --real-name "…" --sync-github-name`)
|
||
and include it in their PR, committed as them. If no, change nothing: they are credited as
|
||
`@username` anyway.
|
||
- Never add, edit, guess or copy anyone else's entry or name (not from git config, commit authors or
|
||
GitHub profiles). Never hand-edit `contributors.json`.
|
||
- Maintainers refresh the stats with `python3 ../../craftrules/scripts/contributors.py .` (it also
|
||
re-verifies who wrote each `people.toml` entry; `--check` only verifies).
|