iwe-org/iwe iwe-v0.11.0

v0.11.0

on GitHub

iwe

Added

• new --key <KEY> — create a document at an explicit key, bypassing the template's key derivation. Subdirectory keys (e.g. people/ada) are allowed; omit the file extension.
• new --if-exists fail — report an error and exit non-zero when the document already exists. It is the default when --key is given (an explicit key asserts an identity), where previously an existing key silently gained a -1 suffix.
• retrieve --expand-includes / --expand-included-by / --expand-references / --expand-referenced-by — one flag per expansion direction, each taking an optional depth (bare flag = one level, 0 = unbounded, omitted = not followed). --expand-referenced-by (pull documents that reference a seed) and transitive --expand-references are new directions.
• retrieve --lexical / --fuzzy — a one-shot form that searches for seed documents within the candidate set (-k / --filter / anchors) and then expands the graph around the ordered seeds.
• retrieve --max-documents N — cap the number of documents returned after expansion, trimming periphery documents first (0 = unlimited).

Changed

• retrieve --limit now caps the selected seed documents before expansion — top-N by relevance when searching, the first N of the selection otherwise (previously it capped the number of documents returned after expansion; use --max-documents for that).
• retrieve no longer expands by default: with no --expand-* flag (and no deprecated flag) it returns the requested document(s) only. The previous implicit -d 1 -c 1 is now written explicitly as --expand-includes 1 --expand-included-by 1.

Deprecated

• retrieve -d / --depth, -c / --context, -l / --links — retained as hidden aliases for --expand-includes N / --expand-included-by N / --expand-references 1 (keeping their legacy 0 = off meaning). Passing one together with its --expand-* counterpart is an error.

iwec

Added

• iwe_create gains an optional key parameter — create a document at an explicit key instead of a title-derived slug. Derive it from stable metadata (entity name, session date); subdirectory keys (e.g. people/ada) are allowed; omit the file extension. Creation fails if a document with that key already exists.
• iwe_query find operations accept a search clause (search: { lexical, fuzzy }) — relevance selection that restricts and orders results; a lexical query with no searchable terms returns an empty array plus a warning content block.
• iwe_retrieve gains search / fuzzy (seed queries), expand (object over includes / includedBy / references / referencedBy → integer depths, 0 = unbounded), and max_documents (cap the documents returned after expansion). With a search query the tool finds seed documents within the candidate set (keys + selector) and expands the graph around the ordered seeds.

Changed

• iwe_retrieve limit now caps the seed documents before expansion (top-N by relevance when searching, the first N of the selection otherwise); use max_documents for the post-expansion document cap.
• iwe_retrieve no longer expands by default — omit expand and it returns the requested document(s) only (previously the implicit behavior was one level of children and parents).
• iwe_delete and iwe_query deletes now also remove any parent directory left empty by a removed document, matching the CLI (previously empty directories were kept).

Deprecated

• iwe_retrieve depth / context / links — retained as aliases for expand's includes / includedBy / references; passing expand together with any of them is an error.

liwe

Added

• Changes::merge — fold another Changes into this one, deduplicating by key so a later update replaces an earlier one for the same document.
• operations gains the section/reference selection helpers (sections, select_section, references, select_reference, SelectError, SectionRef, InclusionRef) and attach_reference / AttachTarget, so all operations live in liwe::operations alongside extract, inline, delete, and rename.
• search clause on FindOp (SearchSpec { lexical, fuzzy }) — a relevance stage that restricts membership to documents matching the query and supplies the default ordering, jointly with filter; search + sort keeps membership from search while sort supplies the order. The ranking logic (query::search::ranked / matched, RRF fusion) is now a shared stage used by both DocumentFinder and the query engine.
• RetrieveOptions expansion generalized to four edge-named depths — includes, included_by, references, referenced_by (u32, 0 = off, UNBOUNDED = no limit) — replacing the depth / context / links fields. Inbound-reference expansion (referenced_by) and transitive outbound-reference expansion (references > 1) are now expressible; retrieve::expand_depth maps an --expand value (0 = unbounded) to a depth.
• format::DocumentFormat trait (read / write / write_skip_frontmatter) as the format boundary, with the built-in MarkdownFormat and (feature-gated) DjotFormat implementations and a format::format_for constructor.
• query::QueryScores and query::execute_with_scores — the query engine now ranks a search clause from caller-injected per-key relevance scores instead of computing them itself, keeping the kernel free of any search index.

Changed

• Djot support is now behind an opt-in djot cargo feature; jotdown is an optional dependency and the djot module compiles only when the feature is enabled. Markdown remains built in. Enable features = ["djot"] to read and write .dj documents.
• The BM25 search index left the kernel: Graph no longer builds or holds one, so Graph::search, has_search_index, search_scores, and lexical_query_has_terms are removed, and Graph::from_state / Graph::import no longer take a search_language argument. The BM25 index and the search scoring (ranked / matched) moved to the diwe crate; query::SearchSpec stays as the DSL type.
• Graph::has_search_index() reports whether the graph carries a BM25 index; running a find with a search clause against a graph without one is an execution-time error (EvalError::SearchIndexMissing).
• RetrieveOptions.limit now caps the seed set before DocumentReader::retrieve_many expands (it was a post-expansion cap on the number of documents returned); the post-expansion cap moves to the new RetrieveOptions.max_documents field. Both are Option<usize>, None / Some(0) = unlimited.
• EdgeRef moved from retrieve to query::edges.

Removed

• The engine modules (find, retrieve, stats, tokens, fs, file) and the .iwe/config.toml mapping (Configuration, LibraryOptions, CompletionOptions, SearchOptions, Command, ActionDefinition and its variants, NoteTemplate, load_config) moved to the new diwe crate; liwe keeps the document kernel and the format/option types (Format, FormatOptions, MarkdownOptions, DjotOptions, FormattingOptions, LinkType, InlineType, TargetType, Operation) in liwe::model::config.
• Graph::from_path — the filesystem-loading constructor moved to diwe; build a State from disk and call Graph::from_state.

diwe

Added

• diwe is the IWE engine library carved out of liwe. It carries the app-facing layer: find (BM25 / fuzzy search), retrieve (document expansion with token budgeting), stats, tokens, fs (filesystem / workspace loading), graph_from_path, and the .iwe/config.toml mapping (config::Configuration, config::load_config). It depends on liwe for the document kernel and re-exports liwe's format/option types from diwe::config.
• search (the BM25 index) and search_query (BM25 + fuzzy resolvers, RRF fusion, build_index, ranked / matched, and an execute wrapper that resolves a query's search clause into scores and injects them into the liwe engine). DocumentFinder::with_index takes a caller-built index.
• fs::apply_changes — write a Changes set to a workspace (creates, updates, and removals), pruning any parent directories left empty by a removal.