speccoder_runtime/format/
mod.rs

1//! The spec-format seam: everything the runtime knows about
2//! a spec format comes from an [`Adapter`] — where the intent lives, what a
3//! planning skill may write, what the model is told, how a task is ticked.
4//! The judge (verification, evidence, commits) is the same for every format.
5//!
6//! Spec Kit is the reference format; OpenSpec runs too. Kiro is
7//! detected, so a project in it gets a clear answer instead of "not a
8//! project".
9
10pub mod openspec;
11pub mod speckit;
12mod stubs;
13
14use std::path::{Path, PathBuf};
15use std::sync::OnceLock;
16
17use speccoder_core::snapshot::{Diagnostic, ParsedTasks, ProjectSnapshot, Severity};
18use speccoder_core::spec::{FormatKind, ScenarioRef};
19use speccoder_core::{ChecklistStatus, CommandStatus};
20
21use crate::context::{Bundle, BundleError};
22
23pub use speckit::Workspace;
24
25/// Where a quick change was recorded.
26#[derive(Debug, Clone, PartialEq, Eq)]
27pub struct Recorded {
28    /// The unit's name (`004-quick-changes`).
29    pub feature: String,
30    /// Its directory, project-relative.
31    pub dir: String,
32    /// The task (`T003`).
33    pub task: String,
34    /// The requirement (`FR-003`).
35    pub requirement: String,
36    /// The change's title.
37    pub title: String,
38}
39
40/// An installed extension of the format, as its inventory lists it.
41#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
42pub struct Extension {
43    /// Its id (`bug`).
44    pub id: String,
45    /// Its version.
46    pub version: String,
47    /// Enabled (a disabled one counts as not installed).
48    pub enabled: bool,
49    /// Where it was installed from, as the format says (`local`, a catalog).
50    pub source: String,
51}
52
53/// Which source the inventory was read from.
54#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
55#[serde(rename_all = "snake_case")]
56pub enum InventorySource {
57    /// The format's own command-line tool.
58    Cli,
59    /// The format's registry files.
60    Files,
61}
62
63/// The format's installed extensions.
64#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
65pub struct Inventory {
66    /// What was read.
67    pub source: InventorySource,
68    /// Every extension listed.
69    pub entries: Vec<Extension>,
70}
71
72impl Inventory {
73    /// The extension `id`, if installed and enabled.
74    #[must_use]
75    pub fn enabled(&self, id: &str) -> Option<&Extension> {
76        self.entries.iter().find(|e| e.id == id && e.enabled)
77    }
78}
79
80/// Why a bug cannot be recorded or read here.
81#[derive(Debug, Clone, PartialEq, Eq)]
82pub struct BugRefusal {
83    /// The catalog code (`BUG-NO-UNIT`, `BUG-ASSESSMENT-DRIFT`, …).
84    pub code: &'static str,
85    /// What the person is told.
86    pub message: String,
87}
88
89impl BugRefusal {
90    /// A refusal with `code`.
91    #[must_use]
92    pub fn new(code: &'static str, message: impl Into<String>) -> Self {
93        Self {
94            code,
95            message: message.into(),
96        }
97    }
98}
99
100/// A bug the adapter recorded in a standing unit.
101#[derive(Debug, Clone, PartialEq, Eq)]
102pub struct RecordedBug {
103    /// The unit (`007-bugfixes`).
104    pub unit: String,
105    /// The unit's directory, project-relative.
106    pub dir: String,
107    /// The requirement (`FR-003`).
108    pub requirement: String,
109    /// The task (`T003`).
110    pub task: String,
111    /// The title.
112    pub title: String,
113    /// The files it wrote, project-relative.
114    pub files: Vec<String>,
115}
116
117/// How a format's own bug step is run: the hosted skill, its arguments
118/// and what it may write.
119#[derive(Debug, Clone, Copy)]
120pub struct BugStep {
121    /// The installed skill that creates a bug.
122    pub skill: &'static str,
123    /// Its arguments: the person's labelled triad and the slug.
124    pub arguments: fn(&speccoder_core::bug::Triad, &str) -> String,
125    /// The policy's rules while it runs: it writes only the bug directory.
126    pub rules: &'static Rules,
127}
128
129/// The triad as a format's own bug file holds it.
130#[derive(Debug, Clone, PartialEq, Eq)]
131pub struct ReadBug {
132    /// Current statements (the first is the symptom).
133    pub current: Vec<String>,
134    /// Expected statements.
135    pub expected: Vec<String>,
136    /// Unchanged statements.
137    pub unchanged: Vec<String>,
138    /// The title the file gives.
139    pub title: Option<String>,
140    /// The file it was read from, project-relative.
141    pub file: String,
142}
143
144/// Why a project in a format this build detects but does not run has no
145/// place for a bug (`BUG-NO-UNIT`), if it is one.
146#[must_use]
147pub fn bug_refusal_unsupported(start: &Path) -> Option<BugRefusal> {
148    Detect::root(&stubs::KIRO, start).map(|_| BugRefusal::new("BUG-NO-UNIT", stubs::KIRO_BUGS))
149}
150
151/// A requirement a review writes tests for: the format's
152/// requirement (`US1`) with the scenario ids its tests cite (`US1-1`).
153#[derive(Debug, Clone, PartialEq, Eq)]
154pub struct OracleRequirement {
155    /// Stable within the unit (`US1`).
156    pub key: String,
157    /// Its title.
158    pub title: String,
159    /// Its whole text, scenarios included.
160    pub text: String,
161    /// The scenarios its tests cite, with the spec's words.
162    pub scenarios: Vec<ScenarioRef>,
163}
164
165impl OracleRequirement {
166    /// `sha256:<hex>` of `title + "\n" + text`: the wording a frozen oracle
167    /// is bound to; any change of title, body or scenario lapses it.
168    #[must_use]
169    pub fn digest(&self) -> String {
170        format!(
171            "sha256:{}",
172            crate::integrity::sha256_hex(format!("{}\n{}", self.title, self.text).as_bytes())
173        )
174    }
175}
176
177/// What a new project asks of the format's own init.
178#[derive(Debug, Clone, PartialEq, Eq)]
179pub struct FormatInit {
180    /// Extensions the person chose (Spec Kit).
181    pub extensions: Vec<speccoder_core::new_project::ExtensionChoice>,
182    /// Install the format's evidence preset with the init where it has one
183    /// (Spec Kit: the bundled `speccoder` preset).
184    pub preset: bool,
185    /// speccoder's state directory (where a bundled preset is extracted).
186    pub state: PathBuf,
187    /// speccoder's private cache for this tool: where its settings go
188    /// instead of the person's config directory.
189    pub cache: PathBuf,
190}
191
192/// One command of the format's own init, as a new project's plan runs it.
193#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct InitStep {
195    /// The command, exactly.
196    pub argv: Vec<String>,
197    /// The hosts it reaches; empty: local.
198    pub hosts: Vec<String>,
199    /// What it writes, in one line.
200    pub writes: String,
201    /// Variables it runs with beside the person's.
202    pub env: Vec<(String, String)>,
203    /// Its effect, for resuming: done when this path exists in the folder.
204    pub marker: &'static str,
205    /// A note the plan shows beside it.
206    pub note: Option<String>,
207    /// It installs the format's evidence preset.
208    pub preset: bool,
209}
210
211/// What kind of phase a task sits in, as the format's structure says.
212#[derive(Debug, Clone, Copy, PartialEq, Eq)]
213pub enum PhaseKind {
214    /// Shared setup (Spec Kit: *Setup*).
215    Setup,
216    /// Prerequisites every story builds on (Spec Kit: *Foundational*).
217    Foundational,
218    /// A user story's phase.
219    Story,
220    /// Cross-cutting polish.
221    Polish,
222    /// Anything else.
223    Other,
224}
225
226/// One task as the plan checks read it.
227#[derive(Debug, Clone, PartialEq, Eq)]
228pub struct PlannedTask {
229    /// Task ID.
230    pub id: String,
231    /// Its title.
232    pub title: String,
233    /// Its phase's kind.
234    pub phase: PhaseKind,
235    /// Its story (`US1`), when it has one.
236    pub story: Option<String>,
237    /// The code spans of its title, in order.
238    pub spans: Vec<String>,
239    /// Ticked.
240    pub done: bool,
241}
242
243/// A unit's plan structure: phases and stories. Formats without
244/// that structure have none.
245#[derive(Debug, Clone, PartialEq, Eq, Default)]
246pub struct PlanStructure {
247    /// Every task, in document order.
248    pub tasks: Vec<PlannedTask>,
249    /// Each story's text (its scenarios), by story.
250    pub stories: std::collections::BTreeMap<String, String>,
251}
252
253/// The code spans of a text (between single backticks).
254#[must_use]
255pub fn code_spans(text: &str) -> Vec<String> {
256    text.split('`')
257        .enumerate()
258        .filter(|(i, _)| i % 2 == 1)
259        .map(|(_, s)| s.to_owned())
260        .filter(|s| !s.trim().is_empty())
261        .collect()
262}
263
264/// One spec format the runtime can run.
265pub trait Adapter: Send + Sync + std::fmt::Debug {
266    /// Which format.
267    fn kind(&self) -> FormatKind;
268
269    /// The project root containing `start`, by the format's marker.
270    fn detect(&self, start: &Path) -> Option<PathBuf>;
271
272    /// Discovers the project containing `start` and selects `feature`.
273    /// Read-only.
274    fn inspect(&self, start: &Path, feature: Option<&str>) -> Option<ProjectSnapshot>;
275
276    /// [`Adapter::inspect`] for a command a person ran: the format's own
277    /// selection settings (its environment variables) apply.
278    fn open(&self, start: &Path, feature: Option<&str>) -> Option<ProjectSnapshot> {
279        self.inspect(start, feature)
280    }
281
282    /// Parses a task list.
283    fn parse_tasks(&self, path: &str, text: &str) -> (ParsedTasks, Vec<Diagnostic>);
284
285    /// Which paths are intent and what planning may write.
286    fn rules(&self) -> &'static Rules;
287
288    /// What the model is told about the format.
289    fn wording(&self) -> &'static Wording;
290
291    /// What a person is told.
292    fn messages(&self) -> &'static Messages;
293
294    /// Hosted planning skills.
295    fn planning(&self) -> &'static Planning;
296
297    /// The context bundle for `task` of the selected unit.
298    fn bundle(&self, snapshot: &ProjectSnapshot, task: &str) -> Result<Bundle, BundleError>;
299
300    /// The scenarios `task`'s acceptance tests cite, with the spec's words
301    /// (judge-side: the implementer sees the spec text, not this list).
302    fn scenarios(&self, snapshot: &ProjectSnapshot, task: &str) -> Vec<ScenarioRef>;
303
304    /// Whether the bundle states acceptance examples to derive tests from.
305    fn acceptance_testable(&self, bundle: &Bundle) -> bool;
306
307    /// Whether a task closes a gap found after implementation (its phase).
308    fn is_convergence(&self, phase: &str) -> bool;
309
310    /// What the convergence assessment reads, in order: the project's rules,
311    /// the spec, the plan, the task list (each may be empty).
312    fn convergence_texts(&self, root: &Path, unit_dir: &Path) -> [String; 4];
313
314    /// Diagnostics that stop a run of the selected unit before any model
315    /// call (the format's preflight).
316    fn blocking<'s>(&self, _snapshot: &'s ProjectSnapshot) -> Vec<&'s Diagnostic> {
317        Vec::new()
318    }
319
320    /// The format's own tools' opinion of the selected unit, when they are
321    /// installed (read-only commands through `runner`).
322    fn crosscheck(
323        &self,
324        _snapshot: &ProjectSnapshot,
325        _runner: &dyn crate::verify::process::CommandRunner,
326    ) -> Vec<Diagnostic> {
327        Vec::new()
328    }
329
330    /// The unit's unfinished-checklist state.
331    fn checklists(&self, root: &Path, unit_dir: &str) -> Vec<ChecklistStatus>;
332
333    /// The selected unit's phases and stories, for the plan checks that
334    /// need them (`None`: the format has no such structure).
335    fn plan_structure(&self, _snapshot: &ProjectSnapshot) -> Option<PlanStructure> {
336        None
337    }
338
339    /// The format's own checks of what its tool needs on this machine, as
340    /// `doctor` rows, given the person's environment `env`.
341    fn doctor_checks(
342        &self,
343        _root: &Path,
344        _env: &dyn Fn(&str) -> Option<String>,
345    ) -> Vec<speccoder_core::DoctorCheck> {
346        Vec::new()
347    }
348
349    /// The format's own command-line tool and how to install it, for
350    /// `doctor` (`None`: the format has none).
351    fn tool(&self) -> Option<(&'static str, &'static str)> {
352        None
353    }
354
355    /// The commands of the format's own init that make a folder a project
356    /// of it (New Project); empty: speccoder cannot initialise
357    /// this format, the person does ([`Messages::make_project`]).
358    fn init_steps(&self, _choices: &FormatInit) -> Vec<InitStep> {
359        Vec::new()
360    }
361
362    /// Writes what [`Adapter::init_steps`] names in speccoder's state
363    /// before they run (Spec Kit: the bundled preset, extracted).
364    ///
365    /// # Errors
366    ///
367    /// The state directory cannot be written.
368    fn prepare_init(&self, _choices: &FormatInit) -> Result<(), String> {
369        Ok(())
370    }
371
372    /// The unit's document that defines its requirements (`spec.md` in
373    /// Spec Kit), relative to the unit's directory; `None` when the format
374    /// has no requirement identifiers.
375    fn requirements_file(&self) -> Option<&'static str> {
376        None
377    }
378
379    /// The requirements `text` (the requirements file) defines, each with
380    /// the line that defines it, in the document's order.
381    fn requirements_in(&self, _text: &str) -> Vec<(String, String)> {
382        Vec::new()
383    }
384
385    /// Records a quick change: `request` (with acceptance `checks`)
386    /// becomes a story, a requirement and a task in the format's standing
387    /// unit for such changes. `Err`: the format has none.
388    fn record_change(
389        &self,
390        _root: &Path,
391        _request: &str,
392        _checks: &[String],
393    ) -> Result<Recorded, String> {
394        Err("this spec format has no place for quick changes: write a spec for it".to_owned())
395    }
396
397    /// The format's installed extensions, from its own inventory (`None`:
398    /// the format has none, or none could be read). The only reader of the
399    /// format's extension files.
400    fn extensions(&self, _root: &Path) -> Option<Inventory> {
401        None
402    }
403
404    /// Where a bug lives: the format's own bug structure when it
405    /// has one, else its standing bug-fix unit. `Err`: neither
406    /// (`BUG-NO-UNIT`).
407    ///
408    /// # Errors
409    ///
410    /// The format has no place for a bug.
411    fn bug_unit(&self, _root: &Path) -> Result<speccoder_core::bug::BugHome, BugRefusal> {
412        Err(BugRefusal::new(
413            "BUG-NO-UNIT",
414            "this spec format has no place for a bug: write a spec for the fix, or `speccoder do` for a change without a reproduction",
415        ))
416    }
417
418    /// Records `triad` as a story, an approved-to-be requirement and a task
419    /// in the standing bug-fix unit `home` names (appends only, verified at
420    /// write time).
421    ///
422    /// # Errors
423    ///
424    /// The home is not a standing unit, or the files changed meanwhile.
425    fn record_bug(
426        &self,
427        _root: &Path,
428        _home: &speccoder_core::bug::BugHome,
429        _triad: &speccoder_core::bug::Triad,
430    ) -> Result<RecordedBug, BugRefusal> {
431        Err(BugRefusal::new(
432            "BUG-NO-UNIT",
433            "this spec format has no standing unit for bugs",
434        ))
435    }
436
437    /// The format's own bug step, for a native home.
438    fn bug_step(&self) -> Option<BugStep> {
439        None
440    }
441
442    /// A native home's directory for `slug`, project-relative, and its
443    /// unit name.
444    fn bug_dir(
445        &self,
446        _home: &speccoder_core::bug::BugHome,
447        _slug: &str,
448    ) -> Option<(String, String)> {
449        None
450    }
451
452    /// A new slug for `title` that no bug of `home` has yet.
453    fn bug_slug(&self, _root: &Path, _home: &speccoder_core::bug::BugHome, _title: &str) -> String {
454        String::new()
455    }
456
457    /// The triad as the home holds it: the bug `key` (a native home's slug,
458    /// a standing unit's requirement). Pure: no model, no tool.
459    ///
460    /// # Errors
461    ///
462    /// The file is missing or not in a shape the adapter reads.
463    fn read_bug(
464        &self,
465        _root: &Path,
466        _home: &speccoder_core::bug::BugHome,
467        _key: &str,
468    ) -> Result<ReadBug, BugRefusal> {
469        Err(BugRefusal::new("BUG-NO-UNIT", "no bug home"))
470    }
471
472    /// The selected unit's requirements with their scenarios, in document
473    /// order: what a review writes tests for. None when the format yields
474    /// no requirement with scenarios.
475    fn oracle_requirements(&self, _snapshot: &ProjectSnapshot) -> Vec<OracleRequirement> {
476        Vec::new()
477    }
478
479    /// The project's standing units and their rungs (a quick change's, a
480    /// bug's): what `speccoder_core::ladder::rung_of` decides by.
481    fn standing_units(&self, _root: &Path) -> Vec<(String, speccoder_core::ladder::Rung)> {
482        Vec::new()
483    }
484
485    /// The unit's requirement identifiers, each with the hash of the line
486    /// that defines it (`FR-001`, `SC-002` in Spec Kit): the rows of the
487    /// trace matrix. None when the format has no such identifiers.
488    fn requirement_ids(&self, root: &Path, unit_dir: &str) -> Vec<(String, String)> {
489        let Some(file) = self.requirements_file() else {
490            return Vec::new();
491        };
492        let text = std::fs::read_to_string(root.join(unit_dir).join(file)).unwrap_or_default();
493        self.requirements_in(&text)
494            .into_iter()
495            .map(|(id, line)| (id, crate::integrity::sha256_hex(line.as_bytes())))
496            .collect()
497    }
498
499    /// The format's per-checkout pointer to the current unit
500    /// (repository-relative), if it has one.
501    fn current_pointer(&self) -> Option<&'static str> {
502        None
503    }
504
505    /// Records `unit_dir` (repository-relative) as the current unit in the
506    /// format's own per-checkout pointer, or clears it (`None`); returns the
507    /// pointer's path. `Err`: the format has no current unit.
508    fn set_current(&self, _root: &Path, _unit_dir: Option<&str>) -> Result<String, String> {
509        Err(self.messages().no_current.to_owned())
510    }
511
512    /// Ticks `task` (one byte, under the line-hash guard).
513    fn tick(&self, tasks_file: &Path, task: &str, line_hash: &str) -> Result<(), String>;
514
515    /// Appends convergence tasks (prefix-guarded); returns their IDs.
516    fn append(
517        &self,
518        tasks_file: &Path,
519        file_hash: &str,
520        items: &[String],
521    ) -> Result<Vec<String>, String>;
522
523    /// What must be committed before a worktree is made; paths are
524    /// repository-relative, `join` maps a project-relative path to one.
525    fn commit_precondition(
526        &self,
527        root: &Path,
528        join: &dyn Fn(&str) -> String,
529        unit_dir: &str,
530    ) -> CommitPrecondition;
531}
532
533/// [`Rules::found_env`]: the variables, given a lookup of the command's
534/// environment.
535pub type FoundEnv = fn(&dyn Fn(&str) -> Option<String>) -> Vec<(String, String)>;
536
537/// No variables found.
538#[must_use]
539pub fn no_found_env(_: &dyn Fn(&str) -> Option<String>) -> Vec<(String, String)> {
540    Vec::new()
541}
542
543/// A format's ruling on a command (`argv`, whether a planning skill asks):
544/// `Some(Ok)` allowed, `Some(Err(why))` refused, `None` no opinion.
545pub type CommandRule = fn(&[String], bool) -> Option<Result<(), String>>;
546
547/// Which paths are the format's intent, and what a hosted planning skill may
548/// touch.
549#[derive(Debug)]
550pub struct Rules {
551    /// Globs of the intent: never written during implementation.
552    pub intent: &'static [&'static str],
553    /// Why an intent write is refused.
554    pub intent_reason: &'static str,
555    /// What a planning skill writes without asking.
556    pub authoring_path: fn(&str) -> bool,
557    /// The format's own commands: `Some(Ok)` runs without asking,
558    /// `Some(Err(why))` is refused, `None` is classified like any command.
559    /// The flag is whether a hosted planning skill asks.
560    pub command: CommandRule,
561    /// Environment variables every command of the project gets.
562    pub env: &'static [(&'static str, &'static str)],
563    /// Variables found on this machine every command of the project gets,
564    /// given a lookup of the command's environment; a variable already in
565    /// it (the person's) is kept.
566    pub found_env: FoundEnv,
567    /// Why a planning skill's other write needs approval (`path` given).
568    pub authoring_refusal: fn(&str) -> String,
569    /// The unit's judged files, relative to its directory (no trailing
570    /// `/`): what a planning task never writes — the requirements, the task
571    /// list, the person's review.
572    pub judged: fn(&str) -> bool,
573    /// The unit's plan, relative to its directory: with the judged files,
574    /// what its ticks were judged against (other design documents are not).
575    pub plan: &'static str,
576}
577
578/// Model-facing fragments; the prompts around them are the same for every
579/// format.
580#[derive(Debug)]
581pub struct Wording {
582    /// The format as the model is told it, e.g. `GitHub Spec Kit`.
583    pub product: &'static str,
584    /// The format's short name, e.g. `Spec Kit`.
585    pub name: &'static str,
586    /// What one unit of work is called, e.g. `feature`.
587    pub unit: &'static str,
588    /// The intent paths, e.g. `.specify/, specs/`.
589    pub intent_paths: &'static str,
590    /// The same as code spans.
591    pub intent_code: &'static str,
592    /// The documents convergence reads, e.g. `spec.md, plan.md and tasks.md`.
593    pub documents: &'static str,
594    /// What a planning skill may do, e.g. `write Spec Kit artifacts (…) and
595    /// run Spec Kit's own scripts under …`.
596    pub authoring: &'static str,
597    /// What a planning skill may leave a commit to, e.g. `a Spec Kit script`.
598    pub authoring_tool: &'static str,
599    /// The heading of the requirement text in a bundle.
600    pub story: &'static str,
601    /// The heading of the project-wide rules (`Project constitution`).
602    pub constitution: &'static str,
603    /// The heading of the unit's plan in the attempt prompt (`Feature plan`).
604    pub plan: &'static str,
605    /// The same in the external agent's prompt (`Plan`).
606    pub plan_short: &'static str,
607    /// What acceptance tests are derived from.
608    pub examples: &'static str,
609    /// A task closing a gap: `A task in a Convergence phase`.
610    pub convergence_task: &'static str,
611    /// The spec, plan and task list headings, as convergence shows them.
612    pub files: [&'static str; 3],
613    /// How convergence is told what to assess.
614    pub assess: Assess,
615}
616
617/// The format's words in the convergence assessment.
618#[derive(Debug)]
619pub struct Assess {
620    /// The governing constraints, e.g. `the constitution`.
621    pub rules: &'static str,
622    /// What each finding is checked against.
623    pub targets: &'static str,
624    /// A rule whose violation is `contradicts`, e.g. `a constitution MUST`.
625    pub must: &'static str,
626    /// What `unrequested` code is not called for by.
627    pub sources: &'static str,
628    /// What makes a finding CRITICAL.
629    pub critical: &'static str,
630    /// Examples of `source_ref`.
631    pub refs: &'static str,
632}
633
634/// What a person is told; texts name the format's own files and commands.
635#[derive(Debug)]
636pub struct Messages {
637    /// The task list's file name.
638    pub tasks_file: &'static str,
639    /// How to make the task list.
640    pub make_tasks: &'static str,
641    /// No project at or above the path (path given).
642    pub not_a_project: fn(&Path) -> String,
643    /// The short form, for commands that only need the root.
644    pub no_project: &'static str,
645    /// A worktree lost its project.
646    pub no_project_in_worktree: &'static str,
647    /// The project is not in a git repository.
648    pub not_in_git: &'static str,
649    /// No skills are installed.
650    pub no_skills: &'static str,
651    /// Unchecked checklists stop a run (the list given).
652    pub checklists: fn(&str) -> String,
653    /// What a unit is called: `feature`, `change`.
654    pub unit: &'static str,
655    /// Why there is no current unit to set.
656    pub no_current: &'static str,
657    /// Who else reads the pointer, said when it changes.
658    pub current_shared: &'static str,
659    /// The command that makes a project of this format here, and why.
660    pub make_project: (&'static str, &'static str),
661}
662
663/// Hosted planning skills.
664#[derive(Debug)]
665pub struct Planning {
666    /// The prefix installed skills carry (`plan` runs `<prefix>plan`).
667    pub prefix: &'static str,
668    /// Skills whose `before_<name>` / `after_<name>` hooks run.
669    pub core: &'static [&'static str],
670    /// Why a skill is not hosted, and what to use instead.
671    pub refused: fn(&str) -> Option<String>,
672    /// Core skills that create a new unit (Spec Kit: `specify`): they get
673    /// no current-unit variable, and the unit they create becomes current.
674    pub creates: &'static [&'static str],
675    /// The variable the format's own scripts read the current unit from
676    /// (Spec Kit: `SPECIFY_FEATURE_DIRECTORY`), passed to planning commands.
677    pub current_env: Option<&'static str>,
678    /// The skills that lead from what exists to a task list, given whether
679    /// a plan exists (Spec Kit: `plan`, `tasks`).
680    pub toward_tasks: fn(bool) -> &'static [&'static str],
681    /// The skill that revises a written spec from a person's comments
682    /// (Spec Kit: `clarify`), if the format has one.
683    pub revises: Option<&'static str>,
684    /// The skill that checks the planning files for consistency (Spec
685    /// Kit: `analyze`), if the format has one.
686    pub checks: Option<&'static str>,
687    /// The skill that explores an idea before a spec (OpenSpec:
688    /// `explore`), if the format has one; `spec explore` hosts it
689    /// read-only, else speccoder's own fallback.
690    pub explores: Option<&'static str>,
691    /// What that skill may write: the format's own exploration artifacts.
692    pub explore_paths: fn(&str) -> bool,
693    /// The read-only commands it may run (argv prefixes).
694    pub explore_commands: &'static [&'static [&'static str]],
695}
696
697/// No exploration artifacts.
698#[must_use]
699pub const fn writes_nothing(_rel: &str) -> bool {
700    false
701}
702
703impl Planning {
704    /// The part the skill `short` (without the prefix) plays: it creates a
705    /// unit, leads toward the task list, revises a spec, checks the
706    /// planning, or something else — in that order of precedence.
707    #[must_use]
708    pub fn role_of(&self, short: &str) -> speccoder_core::actions::SkillRole {
709        use speccoder_core::actions::SkillRole;
710        let toward = |plan| (self.toward_tasks)(plan).contains(&short);
711        if self.creates.contains(&short) {
712            SkillRole::Create
713        } else if toward(false) || toward(true) {
714            SkillRole::TowardTasks
715        } else if self.revises == Some(short) {
716            SkillRole::Revise
717        } else if self.checks == Some(short) {
718            SkillRole::Check
719        } else {
720            SkillRole::Other
721        }
722    }
723}
724
725/// What a worktree needs committed: a worktree contains only commits.
726#[derive(Debug, Clone)]
727pub struct CommitPrecondition {
728    /// Nothing untracked, ignored or modified under these.
729    pub strict: Vec<String>,
730    /// Nothing untracked or modified under these (the format ignores its
731    /// own per-checkout files), except runtime state.
732    pub tracked: Vec<String>,
733    /// Runtime state under `tracked` that is not intent.
734    pub runtime: fn(&str) -> bool,
735    /// Files that must be tracked at all.
736    pub essentials: Vec<String>,
737    /// The refusal.
738    pub message: &'static str,
739    /// How to fix it.
740    pub hint: &'static str,
741    /// How to fix a repository without commits.
742    pub no_commits_hint: &'static str,
743}
744
745impl CommitPrecondition {
746    /// Every path whose change after the fork means the spec moved.
747    #[must_use]
748    pub fn paths(&self) -> Vec<String> {
749        self.tracked.iter().chain(&self.strict).cloned().collect()
750    }
751}
752
753/// The formats this build knows, in detection order.
754fn all() -> [&'static dyn Detect; 3] {
755    [&speckit::SPECKIT, &openspec::OPENSPEC, &stubs::KIRO]
756}
757
758/// What every known format implements: finding its marker.
759pub trait Detect: Send + Sync {
760    /// Which format.
761    fn kind(&self) -> FormatKind;
762    /// The root containing `start`, by the format's marker.
763    fn root(&self, start: &Path) -> Option<PathBuf>;
764    /// The adapter, when this build runs the format.
765    fn adapter(&self) -> Option<&'static dyn Adapter>;
766}
767
768/// Every adapter this build runs, in detection order.
769#[must_use]
770pub fn adapters() -> Vec<&'static dyn Adapter> {
771    all().into_iter().filter_map(|d| d.adapter()).collect()
772}
773
774/// The adapter of `kind`, if this build runs it.
775#[must_use]
776pub fn adapter(kind: FormatKind) -> Option<&'static dyn Adapter> {
777    all()
778        .into_iter()
779        .find(|d| d.kind() == kind)
780        .and_then(|d| d.adapter())
781}
782
783/// The reference format, the default where no project decides.
784#[must_use]
785pub fn reference() -> &'static dyn Adapter {
786    &speckit::SPECKIT
787}
788
789static REQUEST: OnceLock<FormatKind> = OnceLock::new();
790
791/// `--format` / `SPECCODER_FORMAT`: chosen once, by the binary, before any
792/// command runs.
793pub fn request(kind: FormatKind) {
794    let _ = REQUEST.set(kind);
795}
796
797/// The project's format, resolved and opened.
798pub struct Opened {
799    /// The format's adapter.
800    pub adapter: &'static dyn Adapter,
801    /// What it sees.
802    pub snapshot: ProjectSnapshot,
803}
804
805/// Why no project was opened.
806#[derive(Debug, Clone, PartialEq, Eq)]
807pub struct Refused {
808    /// How it ends.
809    pub status: CommandStatus,
810    /// Why.
811    pub message: String,
812    /// No format's marker was found at all.
813    pub unmarked: bool,
814}
815
816/// Opens the project containing `start` in the requested, configured or
817/// detected format.
818pub fn open(start: &Path, feature: Option<&str>) -> Result<Opened, Refused> {
819    open_with(start, feature, REQUEST.get().copied())
820}
821
822/// [`open`] with an explicit choice instead of the process-wide request.
823pub fn open_with(
824    start: &Path,
825    feature: Option<&str>,
826    explicit: Option<FormatKind>,
827) -> Result<Opened, Refused> {
828    let configured = match explicit {
829        Some(_) => None,
830        None => configured(start)?,
831    };
832    let (adapter, mut warnings) = resolve(start, explicit.or(configured), &all())?;
833    let mut snapshot = adapter.open(start, feature).ok_or_else(|| Refused {
834        status: CommandStatus::NotAProject,
835        message: (adapter.messages().not_a_project)(start),
836        unmarked: true,
837    })?;
838    snapshot.diagnostics.append(&mut warnings);
839    Ok(Opened { adapter, snapshot })
840}
841
842/// The adapter of a project already opened at `root` (a worktree's project,
843/// a snapshot's root): resolved the way [`open`] resolved it, the reference
844/// format where nothing decides.
845#[must_use]
846pub fn at(root: &Path) -> &'static dyn Adapter {
847    let chosen = REQUEST
848        .get()
849        .copied()
850        .or_else(|| configured(root).ok().flatten());
851    resolve(root, chosen, &all()).map_or_else(|_| reference(), |(a, _)| a)
852}
853
854/// The adapter of an inspected project.
855#[must_use]
856pub fn of(snapshot: &ProjectSnapshot) -> &'static dyn Adapter {
857    at(Path::new(&snapshot.root))
858}
859
860/// The format of the project at `start`: `chosen` when given, else the one
861/// supported format whose marker is nearest. Markers of formats this build
862/// does not run, at the same root, become warnings.
863fn resolve(
864    start: &Path,
865    chosen: Option<FormatKind>,
866    formats: &[&'static dyn Detect],
867) -> Result<(&'static dyn Adapter, Vec<Diagnostic>), Refused> {
868    let refuse = |message: String| Refused {
869        status: CommandStatus::NotAProject,
870        message,
871        unmarked: false,
872    };
873    if let Some(kind) = chosen {
874        return formats
875            .iter()
876            .find(|d| d.kind() == kind)
877            .and_then(|d| d.adapter())
878            .map(|a| (a, Vec::new()))
879            .ok_or_else(|| refuse(not_yet(kind)));
880    }
881    // The nearest project decides: one nested in another repository's
882    // project is its own. Only markers at the same root compete.
883    let mut found: Vec<(&'static dyn Detect, PathBuf)> = formats
884        .iter()
885        .filter_map(|d| d.root(start).map(|r| (*d, r)))
886        .collect();
887    let nearest = found.iter().map(|(_, r)| r.components().count()).max();
888    found.retain(|(_, r)| Some(r.components().count()) == nearest);
889    let supported: Vec<&'static dyn Adapter> =
890        found.iter().filter_map(|(d, _)| d.adapter()).collect();
891    let others = || found.iter().filter(|(d, _)| d.adapter().is_none());
892    match supported.as_slice() {
893        [one] => {
894            let warnings = others()
895                .map(|(d, root)| {
896                    Diagnostic::new(
897                        Severity::Warning,
898                        "format.unsupported-marker",
899                        format!(
900                            "{} is also present at {}; {}",
901                            d.kind().title(),
902                            root.display(),
903                            not_yet(d.kind())
904                        ),
905                    )
906                })
907                .collect();
908            Ok((*one, warnings))
909        }
910        [] => match others().next() {
911            Some((d, root)) => Err(refuse(format!(
912                "found {} project at {}; {}",
913                article(d.kind()),
914                root.display(),
915                not_yet(d.kind())
916            ))),
917            // No marker at all: the reference format's own answer.
918            None => Ok((reference(), Vec::new())),
919        },
920        many => Err(Refused {
921            unmarked: false,
922            status: CommandStatus::DiagnosticsError,
923            message: format!(
924                "this project is in more than one format ({}); choose one with --format",
925                many.iter()
926                    .map(|a| a.kind().name())
927                    .collect::<Vec<_>>()
928                    .join(", ")
929            ),
930        }),
931    }
932}
933
934fn not_yet(kind: FormatKind) -> String {
935    match kind {
936        FormatKind::Kiro => {
937            "speccoder runs Spec Kit and OpenSpec projects, not Kiro specs".to_owned()
938        }
939        k => format!("speccoder does not run {} projects", k.title()),
940    }
941}
942
943fn article(kind: FormatKind) -> String {
944    match kind {
945        FormatKind::Openspec => "an OpenSpec".to_owned(),
946        k => format!("a {}", k.title()),
947    }
948}
949
950/// `[spec] format` of the nearest `speccoder.toml` at or above `start`.
951fn configured(start: &Path) -> Result<Option<FormatKind>, Refused> {
952    let Some(dir) = crate::verify::find_config(start) else {
953        return Ok(None);
954    };
955    let Ok(text) = std::fs::read_to_string(dir.join(crate::verify::config::FILE)) else {
956        return Ok(None);
957    };
958    parse_config(&text).map_err(|e| Refused {
959        unmarked: false,
960        status: CommandStatus::ConfigError,
961        message: format!("speccoder.toml: {e}"),
962    })
963}
964
965/// `[spec] format` from a `speccoder.toml`'s text.
966pub fn parse_config(text: &str) -> Result<Option<FormatKind>, String> {
967    #[derive(serde::Deserialize)]
968    #[serde(deny_unknown_fields)]
969    struct Spec {
970        format: Option<String>,
971    }
972    // An unreadable file is the configuration loader's to report.
973    let Ok(table) = toml::from_str::<toml::Table>(text) else {
974        return Ok(None);
975    };
976    let Some(spec) = table.get("spec") else {
977        return Ok(None);
978    };
979    let spec: Spec = spec
980        .clone()
981        .try_into()
982        .map_err(|e: toml::de::Error| format!("[spec]: {}", e.message()))?;
983    let [a, b, c] = FormatKind::ALL.map(FormatKind::name);
984    spec.format
985        .map(|f| {
986            f.parse()
987                .map_err(|_| format!("[spec]: format = \"{f}\" ({a}, {b} or {c})"))
988        })
989        .transpose()
990}
991
992#[cfg(test)]
993mod tests {
994    use super::*;
995
996    struct Fake(FormatKind, bool);
997
998    impl Detect for Fake {
999        fn kind(&self) -> FormatKind {
1000            self.0
1001        }
1002        fn root(&self, _: &Path) -> Option<PathBuf> {
1003            Some(PathBuf::from("/p"))
1004        }
1005        fn adapter(&self) -> Option<&'static dyn Adapter> {
1006            self.1.then(reference)
1007        }
1008    }
1009
1010    struct At(FormatKind, &'static str);
1011
1012    impl Detect for At {
1013        fn kind(&self) -> FormatKind {
1014            self.0
1015        }
1016        fn root(&self, _: &Path) -> Option<PathBuf> {
1017            Some(PathBuf::from(self.1))
1018        }
1019        fn adapter(&self) -> Option<&'static dyn Adapter> {
1020            Some(reference())
1021        }
1022    }
1023
1024    #[test]
1025    fn the_nearest_project_decides() {
1026        static OUTER: At = At(FormatKind::Speckit, "/repo");
1027        static INNER: At = At(FormatKind::Openspec, "/repo/sub/project");
1028        let (_, w) = resolve(Path::new("/repo/sub/project/x"), None, &[&OUTER, &INNER]).unwrap();
1029        assert!(w.is_empty());
1030        static TWIN: At = At(FormatKind::Speckit, "/repo/sub/project");
1031        assert!(resolve(Path::new("/x"), None, &[&TWIN, &INNER]).is_err());
1032    }
1033
1034    static SK: Fake = Fake(FormatKind::Speckit, true);
1035    static OS: Fake = Fake(FormatKind::Openspec, false);
1036    static OS_RUNS: Fake = Fake(FormatKind::Openspec, true);
1037    static KIRO: Fake = Fake(FormatKind::Kiro, false);
1038
1039    #[test]
1040    fn a_choice_wins_and_an_unsupported_one_is_refused() {
1041        let p = Path::new("/p");
1042        let (a, w) = resolve(p, Some(FormatKind::Speckit), &[&SK, &OS]).unwrap();
1043        assert_eq!((a.kind(), w.len()), (FormatKind::Speckit, 0));
1044        let r = resolve(p, Some(FormatKind::Openspec), &[&SK, &OS])
1045            .err()
1046            .unwrap();
1047        assert_eq!(r.status, CommandStatus::NotAProject);
1048        assert_eq!(r.message, "speccoder does not run OpenSpec projects");
1049        let r = resolve(p, Some(FormatKind::Kiro), &[&SK, &KIRO])
1050            .err()
1051            .unwrap();
1052        assert!(r.message.ends_with("not Kiro specs"));
1053    }
1054
1055    #[test]
1056    fn detection_warns_about_other_markers_and_refuses_ambiguity() {
1057        let p = Path::new("/p");
1058        let (a, w) = resolve(p, None, &[&SK, &OS]).unwrap();
1059        assert_eq!(a.kind(), FormatKind::Speckit);
1060        assert_eq!(w.len(), 1);
1061        assert_eq!(w[0].code, "format.unsupported-marker");
1062        let r = resolve(p, None, &[&OS]).err().unwrap();
1063        assert_eq!(
1064            r.message,
1065            "found an OpenSpec project at /p; speccoder does not run OpenSpec projects"
1066        );
1067        let r = resolve(p, None, &[&SK, &OS_RUNS]).err().unwrap();
1068        assert_eq!(r.status, CommandStatus::DiagnosticsError);
1069        assert!(
1070            r.message.contains("choose one with --format"),
1071            "{}",
1072            r.message
1073        );
1074    }
1075
1076    #[test]
1077    fn the_spec_section_names_a_format() {
1078        assert_eq!(parse_config(""), Ok(None));
1079        assert_eq!(
1080            parse_config("[spec]\nformat = \"openspec\"\n"),
1081            Ok(Some(FormatKind::Openspec))
1082        );
1083        assert_eq!(
1084            parse_config("[spec]\nformat = \"x\"\n"),
1085            Err("[spec]: format = \"x\" (speckit, openspec or kiro)".to_owned())
1086        );
1087        assert!(
1088            parse_config("[spec]\nkind = 1\n")
1089                .unwrap_err()
1090                .starts_with("[spec]: unknown field")
1091        );
1092        assert_eq!(parse_config("[format]\nargv = [\"x\"]\n"), Ok(None));
1093    }
1094}
speccoder_runtime/format/mod.rs

speccoder_runtime/format/
mod.rs
