Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions apps/workspace/src/doctor.rs
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,16 @@ fn old_controllers(base: &Path, ws: Option<&Path>, out: &mut Vec<Finding>) {
}
}

/// A brief.ts that still keeps tasks in `stages` (docs/plan.feature PL8a): they read, unread, and belong in plan.org.
fn briefs_with_tasks(base: &Path, out: &mut Vec<Finding>) {
let f = base.join("brief.ts");
let Ok(text) = std::fs::read_to_string(&f) else { return };
if text.lines().any(|l| l.trim_start().starts_with("stages:") || l.trim_start().starts_with("\"stages\":")) {
let says = format!("{}: keeps tasks in `stages`, which raea no longer reads; move each to the project's plan.org (an Org heading under its stage, its mark as TODO, DONE or DROPPED), then delete `stages`", f.display());
out.push(Finding { says, fix: Fix::No });
}
}

/// The `version:` in a SKILL.md's front matter.
fn skill_version(md: &Path) -> Option<String> {
let text = std::fs::read_to_string(md).ok()?;
Expand All @@ -101,6 +111,7 @@ pub fn findings(from: &Path, skills: &[(&str, PathBuf)], version: &str) -> Vec<F
let base = project.clone().or_else(|| ws.clone()).unwrap_or_else(|| from.to_path_buf());
old_briefs(&base, if project.is_some() { 2 } else { 1 }, &mut out);
old_controllers(&base, ws.as_deref(), &mut out);
briefs_with_tasks(&base, &mut out);
if let Some(ws) = &ws {
let name = ws.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
let keys = [("workspace.id", new_id("ws")), ("workspace.name", name), ("workspace.layout", "monorepo".to_string())];
Expand Down
7 changes: 5 additions & 2 deletions apps/workspace/src/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -83,14 +83,17 @@ fn doctor_connects_a_projects_files() {
std::fs::write(d.join("loose.tsx"), "export const Loose = () => null;\n").unwrap();
std::fs::create_dir_all(d.join("controllers")).unwrap();
std::fs::write(d.join("controllers/pace.ts"), "import { controller } from \"raea/brief\";\nexport default controller({ title: \"Pace\", fields: {} });\n").unwrap();
std::fs::write(d.join("brief.ts"), "import { brief } from \"raea/brief\";\nexport default brief({\n title: \"Old\",\n stages: [{ name: \"\", tasks: [{ text: \"Write the plan\" }] }],\n});\n").unwrap();
let found = doctor::registry_findings(&d);
let says: Vec<&String> = found.iter().map(|f| &f.says).collect();
assert_eq!(found.len(), 1, "{says:?}");
assert!(says[0].contains("loose.tsx:1: isn't a composition") && !found[0].fixable(), "{says:?}");
// a controller from before 11-20 is told where its parts go, and kept
let out = doctor::doctor(&["--fix".into(), d.display().to_string()], &[], "0.0.1", &|_| Ok(String::new())).unwrap();
assert!(out.starts_with("APPLIED 2 of 4 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}");
assert!(d.join("controllers/pace.ts").is_file(), "nothing of the person's is deleted");
assert!(out.starts_with("APPLIED 2 of 5 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}");
// a brief's old tasks are said to belong in plan.org (docs/plan.feature PL8a), and kept
assert!(out.contains("brief.ts: keeps tasks in `stages`") && out.contains("plan.org"), "{out}");
assert!(d.join("controllers/pace.ts").is_file() && std::fs::read_to_string(d.join("brief.ts")).unwrap().contains("stages"), "nothing of the person's is deleted");
let _ = std::fs::remove_dir_all(&d);
}

Expand Down
51 changes: 8 additions & 43 deletions core/brief/src/brief.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
//! A project's brief: who it's for, the one thing they should believe, what it delivers and the work to get there.
//! The facts an agent guessed are listed in `assumed`, for the person to confirm.
//! A project's brief: who it's for, the one thing they should believe and what it delivers. The facts an agent guessed
//! are listed in `assumed`, for the person to confirm. Its tasks are in the project's plan.org, not here
//! (docs/plan.feature PL8a).

use serde::{Deserialize, Serialize};
use ts_rs::TS;
Expand Down Expand Up @@ -47,10 +48,11 @@ pub struct Brief {
#[serde(default)]
#[ts(as = "Option<Vec<Reference>>", optional)]
pub references: Vec<Reference>,
/// the tasks, in stages ("Act one", "The cut")
#[serde(default)]
#[ts(as = "Option<Vec<Stage>>", optional)]
pub stages: Vec<Stage>,
/// an older brief's tasks, read only so it still loads: they belong in plan.org (docs/plan.feature PL8a), and
/// `raea doctor` says so; never written, and not in the schema an agent writes to
#[serde(default, skip_serializing)]
#[ts(skip)]
pub stages: Option<serde_json::Value>,
#[serde(default)]
#[ts(as = "Option<Vec<Agent>>", optional)]
pub agents: Vec<Agent>,
Expand Down Expand Up @@ -88,43 +90,6 @@ pub struct Reference {
pub note: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)]
#[serde(deny_unknown_fields)]
pub struct Stage {
pub name: String,
pub tasks: Vec<Task>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, TS)]
#[serde(rename_all = "lowercase")]
pub enum Mark {
#[default]
Todo,
Done,
Dropped,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(optional_fields)]
pub struct Task {
pub text: String,
/// a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones
#[serde(default)]
#[ts(as = "Option<Mark>", optional)]
pub mark: Mark,
#[serde(default)]
#[ts(as = "Option<Vec<String>>", optional)]
pub agents: Vec<String>,
pub item: Option<String>,
#[serde(default)]
#[ts(as = "Option<Vec<String>>", optional)]
pub tags: Vec<String>,
pub due: Option<String>,
/// the craft verb it was written as ("quieter"): agents read it, the page shows the text
pub verb: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)]
#[serde(deny_unknown_fields)]
#[ts(optional_fields)]
Expand Down
10 changes: 5 additions & 5 deletions core/brief/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
//! What an agent writes for raea, as Rust types: a project's brief, a script (storyboard or screenplay), a person's
//! taste and an object's plan. The agent writes them as TypeScript modules (docs/handoff/authoring.md); `raea run`
//! taste and an object's parts. The agent writes them as TypeScript modules (docs/handoff/authoring.md); `raea run`
//! evaluates one, and its default export arrives here as JSON. The TypeScript declarations are generated from these
//! types (`declarations`), so what tsc checks is exactly what this crate reads.

pub mod brief;
pub mod plan;
pub mod parts;
pub mod script;
pub mod taste;

pub use brief::Brief;
pub use plan::Plan;
pub use parts::Parts;
pub use script::Script;
pub use taste::Taste;

Expand All @@ -32,10 +32,10 @@ pub fn declarations() -> String {
let cfg = Config::new();
let mut out = vec!["// Generated from raea-core-brief (core/brief) by its `declarations`; edit the Rust, not this.".to_string()];
out.extend(decls!(cfg;
brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Stage, brief::Mark, brief::Task, brief::Agent,
brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Agent,
script::Script, script::Scene, script::Beat, script::Line,
taste::Taste, taste::TasteSection, taste::Rule, taste::RuleCheck, taste::RuleLevel, taste::Check,
plan::Plan, plan::Concept, plan::Level, plan::Count, plan::Part,
parts::Parts, parts::Concept, parts::Level, parts::Count, parts::Part,
));
out.join("\n\n") + "\n"
}
Expand Down
13 changes: 7 additions & 6 deletions core/brief/src/plan.rs → core/brief/src/parts.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
//! An object's plan, written before any geometry and frozen when building starts (docs/handoff/solids.md, "The plan
//! is the contract"). Generic over what's made: a crown, a feather and a rocking horse are all a concept and a tree of
//! An object's parts (NAME.parts.ts, `parts()` from "raea/brief"), written before any geometry and frozen when
//! building starts (docs/handoff/solids.md, "The plan is the contract"; named parts since 11-20, so "plan" is only a
//! project's plan.org, docs/plan.feature PL8a). Generic over what's made: a crown, a feather and a rocking horse are all a concept and a tree of
//! named parts, each with a level, a count, and a material and style it has or inherits.

use std::collections::BTreeMap;
Expand All @@ -9,7 +10,7 @@ use ts_rs::TS;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)]
#[serde(deny_unknown_fields)]
pub struct Plan {
pub struct Parts {
pub concept: Concept,
/// by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error
pub parts: BTreeMap<String, Part>,
Expand Down Expand Up @@ -77,7 +78,7 @@ pub struct Resolved {

/// Everything wrong with a plan that would let a build leave something behind: a parent that isn't planned, a loop,
/// no root, a range upside down, or a part that resolves to no material. Empty when the plan can be built against.
pub fn check(plan: &Plan) -> Vec<String> {
pub fn check(plan: &Parts) -> Vec<String> {
let mut out = Vec::new();
let roots: Vec<&String> = plan.parts.iter().filter(|(_, p)| p.parent.is_none()).map(|(n, _)| n).collect();
if roots.is_empty() {
Expand Down Expand Up @@ -107,7 +108,7 @@ pub fn check(plan: &Plan) -> Vec<String> {
}

/// The part and its ancestors, nearest first; none on a loop or a missing parent.
fn chain<'a>(plan: &'a Plan, name: &str) -> Option<Vec<&'a Part>> {
fn chain<'a>(plan: &'a Parts, name: &str) -> Option<Vec<&'a Part>> {
let mut out = Vec::new();
let mut at = plan.parts.get(name)?;
loop {
Expand All @@ -124,7 +125,7 @@ fn chain<'a>(plan: &'a Plan, name: &str) -> Option<Vec<&'a Part>> {

/// A part's material and style, inherited up its parents to the concept. Style always resolves (the concept has
/// one); material may not.
pub fn resolve(plan: &Plan, name: &str) -> Option<Resolved> {
pub fn resolve(plan: &Parts, name: &str) -> Option<Resolved> {
let chain = chain(plan, name)?;
let material = chain.iter().find_map(|p| p.material.clone()).or_else(|| plan.concept.material.clone())?;
let style = chain.iter().find_map(|p| p.style.clone()).unwrap_or_else(|| plan.concept.style.clone());
Expand Down
26 changes: 16 additions & 10 deletions core/brief/src/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@ fn declarations_match_the_committed_file() {
#[test]
fn a_brief_reads_and_its_doctor_asks_for_what_is_missing() {
let b: Brief = read("brief.ts", r#"{"title": "A walkthrough", "mode": ["explain"], "assumed": ["voice"], "voice": "one calm narrator",
"deliver": [{"name": "Walkthrough", "specs": ["60 s", "16:9"]}],
"stages": [{"name": "", "tasks": [{"text": "Storyboard it", "agents": ["director"], "mark": "done"}]}]}"#).unwrap();
assert_eq!(b.stages[0].tasks[0].mark, brief::Mark::Done);
"deliver": [{"name": "Walkthrough", "specs": ["60 s", "16:9"]}]}"#).unwrap();
let d = brief::doctor(&b);
assert!(d.iter().any(|m| m.contains("`believe`")), "{d:?}");
assert!(d.iter().any(|m| m.contains("no script")), "{d:?}");
Expand Down Expand Up @@ -68,26 +66,34 @@ fn a_taste_line_holds_any_check_by_name_or_path_with_values_and_a_level() {
}

#[test]
fn a_plan_leaves_nothing_without_a_material() {
let ok: Plan = read("plan.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"},
fn an_objects_parts_leave_nothing_without_a_material() {
let ok: Parts = read("feather.parts.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"},
"parts": {
"rachis": {"role": "shaft", "level": "primary"},
"vane": {"role": "vane", "level": "secondary", "parent": "rachis", "count": 2, "style": "barred brown"},
"barb": {"role": "barb", "level": "tertiary", "parent": "vane", "count": {"min": 300, "max": 500}, "near": "separate barbs, a few split gaps"}}}"#).unwrap();
assert_eq!(plan::check(&ok), Vec::<String>::new());
assert_eq!(plan::resolve(&ok, "barb").unwrap(), plan::Resolved { material: "keratin".into(), style: "barred brown".into() });
assert_eq!(parts::check(&ok), Vec::<String>::new());
assert_eq!(parts::resolve(&ok, "barb").unwrap(), parts::Resolved { material: "keratin".into(), style: "barred brown".into() });

let mut bad = ok.clone();
bad.concept.material = None;
bad.parts.get_mut("rachis").unwrap().parent = Some("calamus".into());
let e = plan::check(&bad);
let e = parts::check(&bad);
assert!(e.iter().any(|m| m.contains("`calamus` isn't planned")), "{e:?}");
assert!(e.iter().any(|m| m.contains("no root")), "{e:?}");
}

#[test]
fn a_close_view_needs_tertiary_detail() {
let p: Plan = read("plan.ts", r#"{"concept": {"what": "toy rocking horse", "style": "painted wood", "size": 0.9, "seenFrom": 0.5, "material": "beech"},
let p: Parts = read("horse.parts.ts", r#"{"concept": {"what": "toy rocking horse", "style": "painted wood", "size": 0.9, "seenFrom": 0.5, "material": "beech"},
"parts": {"body": {"role": "body", "level": "primary"}, "rocker": {"role": "rocker", "level": "secondary", "parent": "body", "count": 2}}}"#).unwrap();
assert!(plan::check(&p).iter().any(|m| m.contains("tertiary")));
assert!(parts::check(&p).iter().any(|m| m.contains("tertiary")));
}

#[test]
fn an_older_brief_with_stages_still_reads_and_never_writes_them() {
let b: Brief = read("brief.ts", r#"{"title": "Old", "stages": [{"name": "", "tasks": [{"text": "Write the plan", "mark": "todo"}]}]}"#).unwrap();
assert!(b.stages.is_some());
assert!(!serde_json::to_string(&b).unwrap().contains("stages"));
assert!(!declarations().contains("stages"), "the schema an agent writes has no stages (docs/plan.feature PL8a)");
}
2 changes: 1 addition & 1 deletion docs/manual/concepts/workspaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ raea's specs are TypeScript files whose default export is checked against a sche
| `NAME.script.ts` | A storyboard: scenes of beats, what's on screen, what each scene must land |
| `~/.raea/taste/taste.ts` | The person's taste, which beats any guide's default |
| `taste.ts` | A workspace's or a project's rules, which `raea check` holds every piece to |
| `plan.ts` | A frozen plan for a build, checked by raea |
| `NAME.parts.ts` | An object's parts, frozen before it's built, checked by raea |

```sh
raea spec brief.ts # prints the brief as JSON, checked against its schema
Expand Down
2 changes: 1 addition & 1 deletion docs/manual/reference/cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ The workspace, its projects and what a project holds.
| [`raea init`](init.md) | Add a project's starting files where they're missing: edit.tsx, cuts.ts, components/ and AGENTS.md. |
| [`raea workspace`](workspace.md) | Make, adopt or show a workspace: the git repository that holds a studio's projects and house taste. |
| [`raea project`](project.md) | Make a project in the workspace, list them, or move one between inline and a repository of its own. |
| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans. |
| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and an object's parts. |
| [`raea component`](component.md) | Copy a ready-made component or set into the project's components/, or the workspace's shared/components/, to use and change as your own. |
| [`raea part`](part.md) | The old name of raea component: copy a ready-made component into the project's components/, to use and change as your own. |
| [`raea add`](add.md) | Add, remove and install npm packages for a project, with no Node or npm: raea.lock and node_modules. |
Expand Down
8 changes: 4 additions & 4 deletions docs/manual/reference/cli/spec.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "raea spec"
summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans."
summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and an object's parts."
order: 25
sources: ["engine/cli/src/spec.rs"]
---

raea's specs are TypeScript files whose default export is data: `brief.ts`, `NAME.script.ts`, `taste.ts` and
`plan.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON,
`NAME.parts.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON,
so an agent can read a brief without running anything else, and a wrong field is caught before it matters.

```sh
Expand All @@ -20,7 +20,7 @@ raea spec notes.ts --as taste
## Usage

```sh
raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts)
raea spec FILE.ts [--as brief|script|taste|parts] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, NAME.parts.ts)
```

Headless: it needs nothing running and opens no window. Takes up to 1 argument besides its flags.
Expand All @@ -29,6 +29,6 @@ Headless: it needs nothing running and opens no window. Takes up to 1 argument b

| Flag | Takes | What it does |
| --- | --- | --- |
| `--as` | `brief\|script\|taste\|plan` | Which schema to check it against. By default from the file's name (`brief`, `script`, `plan`), and `taste` otherwise. |
| `--as` | `brief\|script\|taste\|parts` | Which schema to check it against. By default from the file's name (`brief`, `script`, `parts`), and `taste` otherwise. |

<!-- generated:end -->
Loading
Loading