lazyspec 0.8.0

A little TUI & CLI for project documentation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211

mod common;

use common::TestFixture;
use lazyspec::engine::config::{Config, StoreBackend};
use lazyspec::engine::store::Store;

fn config_with_git_ref_iteration() -> Config {
    let mut config = Config::default();
    for t in &mut config.documents.types {
        if t.name == "iteration" {
            t.store = StoreBackend::GitRef;
        }
    }
    config
}

fn setup_cross_backend(implements_target: &str) -> (TestFixture, Store) {
    let fixture = TestFixture::new();

    fixture.write_doc(
        "docs/stories/STORY-001-feature.md",
        "---\ntitle: \"Feature Story\"\ntype: story\nstatus: draft\nauthor: \"test\"\ndate: 2026-04-01\ntags: []\nrelated: []\n---\n\nStory body.\n",
    );

    let cache_dir = fixture.root().join(".lazyspec/cache/iteration");
    std::fs::create_dir_all(&cache_dir).unwrap();
    std::fs::write(
        cache_dir.join("ITERATION-001-impl.md"),
        format!(
            "---\ntitle: \"Impl Iteration\"\ntype: iteration\nstatus: draft\nauthor: \"agent\"\ndate: 2026-04-01\ntags: []\nrelated:\n- implements: {}\n---\n\nIteration body.\n",
            implements_target
        ),
    )
    .unwrap();

    let config = config_with_git_ref_iteration();
    let store = Store::load(fixture.root(), &config).unwrap();
    (fixture, store)
}

#[test]
fn context_resolves_chain_across_fs_story_and_git_ref_iteration() {
    let (_fixture, store) = setup_cross_backend("docs/stories/STORY-001-feature.md");

    let resolved = lazyspec::cli::context::resolve_chain(&store, "ITERATION-001").unwrap();

    assert_eq!(
        resolved.chain.len(),
        2,
        "chain should contain story + iteration; got: {:?}",
        resolved.chain.iter().map(|d| &d.title).collect::<Vec<_>>()
    );
    assert_eq!(resolved.chain[0].title, "Feature Story");
    assert_eq!(resolved.chain[1].title, "Impl Iteration");
    assert_eq!(resolved.target_index, 1);

    let json_output = lazyspec::cli::context::run_json(&store, "ITERATION-001").unwrap();
    let parsed: serde_json::Value = serde_json::from_str(&json_output).unwrap();
    let chain = parsed["chain"].as_array().unwrap();
    assert_eq!(chain.len(), 2);
    assert_eq!(chain[0]["type"], "story");
    assert_eq!(chain[1]["type"], "iteration");
}

#[test]
fn context_reverse_links_show_git_ref_iteration_from_fs_story() {
    let (_fixture, store) = setup_cross_backend("docs/stories/STORY-001-feature.md");

    let resolved = lazyspec::cli::context::resolve_chain(&store, "STORY-001").unwrap();

    assert_eq!(resolved.chain.len(), 1);
    assert_eq!(resolved.chain[0].title, "Feature Story");

    let forward_titles: Vec<&str> = resolved.forward.iter().map(|d| d.title.as_str()).collect();
    assert!(
        forward_titles.contains(&"Impl Iteration"),
        "forward deps should include git-ref iteration; got: {:?}",
        forward_titles
    );
}

#[test]
fn context_with_id_based_target() {
    let (_fixture, store) = setup_cross_backend("STORY-001");

    let resolved = lazyspec::cli::context::resolve_chain(&store, "ITERATION-001").unwrap();

    // The upward chain walk in resolve_chain does `store.get(&PathBuf::from(&rel.target))`
    // which creates PathBuf("STORY-001") -- this won't match any key in the store
    // (keys are full relative paths like "docs/stories/STORY-001-feature.md").
    // So the chain should only contain the iteration itself (parent lookup fails silently).
    //
    // NOTE: This is a pre-existing bug in resolve_chain's upward traversal (lines 30-44
    // of context.rs). It uses raw rel.target as a path key instead of resolving IDs.
    // Forward/reverse links DO handle ID resolution (via build_links -> resolve_target),
    // so the reverse direction works fine. Fixing this is out of scope for this iteration.
    assert_eq!(
        resolved.chain.len(),
        1,
        "ID-based target breaks upward chain walk; chain should only contain the iteration itself; got: {:?}",
        resolved.chain.iter().map(|d| &d.title).collect::<Vec<_>>()
    );
    assert_eq!(resolved.chain[0].title, "Impl Iteration");

    // However, reverse links (story -> iteration) still work because build_links resolves IDs.
    let story_resolved = lazyspec::cli::context::resolve_chain(&store, "STORY-001").unwrap();
    let forward_titles: Vec<&str> = story_resolved
        .forward
        .iter()
        .map(|d| d.title.as_str())
        .collect();
    assert!(
        forward_titles.contains(&"Impl Iteration"),
        "reverse links should still resolve ID-based targets; got: {:?}",
        forward_titles
    );
}

#[test]
fn fs_doc_links_to_git_ref_doc_via_related_to() {
    let fixture = TestFixture::new();

    // FS story with related-to pointing at a git-ref iteration (by ID)
    fixture.write_doc(
        "docs/stories/STORY-001-feature.md",
        "---\ntitle: \"Feature Story\"\ntype: story\nstatus: draft\nauthor: \"test\"\ndate: 2026-04-01\ntags: []\nrelated:\n- related-to: ITERATION-001\n---\n\nStory body.\n",
    );

    // Git-ref iteration in the shadow cache (no relationship back to the story)
    let cache_dir = fixture.root().join(".lazyspec/cache/iteration");
    std::fs::create_dir_all(&cache_dir).unwrap();
    std::fs::write(
        cache_dir.join("ITERATION-001-impl.md"),
        "---\ntitle: \"Impl Iteration\"\ntype: iteration\nstatus: draft\nauthor: \"agent\"\ndate: 2026-04-01\ntags: []\nrelated: []\n---\n\nIteration body.\n",
    )
    .unwrap();

    let config = config_with_git_ref_iteration();
    let store = Store::load(fixture.root(), &config).unwrap();

    let story_path = std::path::PathBuf::from("docs/stories/STORY-001-feature.md");
    let forward = store.forward_links_for(&story_path);

    let targets: Vec<&std::path::Path> = forward.iter().map(|(_, p)| p.as_path()).collect();
    let has_iteration = targets
        .iter()
        .any(|p| p.to_string_lossy().contains("ITERATION-001"));

    assert!(
        has_iteration,
        "FS story's forward links should include the git-ref iteration; got: {:?}",
        forward
    );

    // Also verify from the iteration's perspective: reverse links should point back to the story
    let iteration_path = forward
        .iter()
        .find(|(_, p)| p.to_string_lossy().contains("ITERATION-001"))
        .map(|(_, p)| p.clone())
        .unwrap();
    let reverse = store.reverse_links_for(&iteration_path);
    let reverse_sources: Vec<&std::path::Path> = reverse.iter().map(|(_, p)| p.as_path()).collect();
    assert!(
        reverse_sources
            .iter()
            .any(|p| p.to_string_lossy().contains("STORY-001")),
        "git-ref iteration's reverse links should include the FS story; got: {:?}",
        reverse
    );
}

#[test]
fn git_ref_doc_links_to_fs_doc_via_implements() {
    // This direction was tested in Task 6 via resolve_chain, but here we verify
    // it through the link graph (forward_links_for) rather than context resolution.
    let (_fixture, store) = setup_cross_backend("STORY-001");

    // Find the iteration's path in the store
    let iteration_doc = store
        .all_docs()
        .into_iter()
        .find(|d| d.id == "ITERATION-001")
        .expect("iteration should be in the store");

    let forward = store.forward_links_for(&iteration_doc.path);
    let has_story = forward
        .iter()
        .any(|(_, p)| p.to_string_lossy().contains("STORY-001"));

    assert!(
        has_story,
        "git-ref iteration's forward links should include the FS story (via ID resolution in build_links); got: {:?}",
        forward
    );

    // Verify the story has reverse links back to the iteration
    let story_path = forward
        .iter()
        .find(|(_, p)| p.to_string_lossy().contains("STORY-001"))
        .map(|(_, p)| p.clone())
        .unwrap();
    let reverse = store.reverse_links_for(&story_path);
    let has_iteration = reverse
        .iter()
        .any(|(_, p)| p.to_string_lossy().contains("ITERATION-001"));
    assert!(
        has_iteration,
        "FS story's reverse links should include the git-ref iteration; got: {:?}",
        reverse
    );
}