MIRRRORMARK_PROTOCOL.md

lib.rs

/*****************************************************************************
1) ENTIRE RESTATING OF THE FORMATTED PROTOCOL (IMPROVED AND READY FOR PRODUCTION)
******************************************************************************/

/// # MIRRORMARK PROTOCOL
///
/// MirrorMark is a technique of doubling code files with natural language
/// equivalent markdown that precisely and completely describes the functionality
/// of source code.
///
/// - **Mirroring Directory**: The protocol generates these mirror descriptions
///   in a `.mdmirror` directory.
/// - **Summaries**: Each directory in a project contains a `SUMMARY.md` that
///   condenses the main purpose and contents of that directory.
/// - **Architecture Specification**: The overarching project documentation is
///   defined in `.mdmirror/ARCHITECTURE.md`.
///
/// MirrorMark then builds:
/// - A **semantic index** of terms and concepts used in code and docs.
/// - An **AST index** to map the code’s abstract syntax tree (if available).
/// - A **graph of file and module relationships** leveraging the semantic base
///   and git history if present.
///
/// On top of summarizing the project goals, direction, top contributors,
/// activity level, and other metrics, MirrorMark’s deeper objective is to align
/// the code and its documentation, ensuring both remain consistently updated.
/// 
/// ## MIRRORMARK V1 RUST
///
/// The initial implementation of MirrorMark is written in Rust with SurrealDB.
/// A binary distribution is available for Linux, macOS, and Windows with a
/// one-line installer:
///
/// ```shell
/// curl ...
/// ```
///
/// ## CLI
///
/// The Rust-based implementation runs as a system daemon and provides the
/// `mirrormark` binary with an alias `mmd` (if desired). The following commands
/// are made available via the CLI:
///
/// 1. **`mmd add`**
///    - Allows directories to be added to the set of managed and watched
///      directories for MirrorMark processing.
///
/// 2. **`mmd ask`**
///    - Allows you to pass natural language queries over your codebase and
///      receive answers from large language models (LLMs) informed by the
///      `.mdmirror` knowledge base.
///
/// 3. **`mmd architect`**
///    - Allows you to reshape the direction of the project. This could be a
///      refactor, a new feature, or an adjustment to scope. It initiates a
///      turn-based dialog with LLMs to fully understand the proposed change
///      and identify all necessary filesystem modifications (including the
///      natural language `.mdmirror` files) needed to manifest that change.
///    - Once finalized, this command generates a migration directory in
///      `.mdmirror/migrations`, such as:
///      `./mdmirror/migrations/20250128-add-cli-interface/` (where the date and
///       phrase can vary based on context).
///
///      Inside the migration directory, you will find:
///      - **`DIFF.md`**  
///        An MDDIFF-format diffset of all impacted files in both the codebase
///        and `.mdmirror/**/*.md`.
///      - **`PROMPT.md`**  
///        A set of ordered prompts for an LLM to apply those changes (also
///        stored in MDDIFF format).
///      - **`AST.md`**  
///        Contains `ast-grep` mutations specifying how to update both the actual
///        codebase and the `.mdmirror` documentation.
///      - **`CHANGESET.md`**  
///        A high-level summarization of the modifications required.
///      - **`VERIFICATION.md`**  
///        A collection of steps, tests, and checks to demonstrate that the
///        `OBJECTIVE` is met. This includes:
///         - Unit tests
///         - Functional tests
///         - LLM agent verification steps
///      - **`CONVENTIONS.md`**  
///        Project-level coding conventions that are particularly useful to LLMs
///        applying or reviewing the changeset.
///      - **`ARCHITECTURE.md`**  
///        The updated future-state `ARCHITECTURE.md` after the change is applied.
///
/// 4. **`mmd apply`**
///    - Safely executes a chosen MirrorMark changeset against a codebase,
///      providing a comprehensive backup and optional git branch merge
///      functionality for rollbacks if needed.
///
/// 5. **`mmd rollback`**
///    - Reverts a previously applied changeset to restore the codebase to its
///      pre-change state.
///
/// 6. **`mmd verify`**
///    - Leverages the `VERIFICATION.md` steps to confirm the changeset’s
///      integrity, ensuring everything aligns with the intended goals.
///
/// 7. **`mmd review`**
///    - Generates an orchestrated code review of either the entire codebase
///      or a specific migration, using the `.mdmirror` knowledge base as a
///      reference for code correctness, style, and architecture.
///
/// 8. **`mmd align`**
///    - Creates a new migration that realigns the current codebase state with
///      the architecture, coverage, or other project goals declared in the
///      `.mdmirror` definitions. Useful when code has drifted from described
///      conventions.
///
/// ## ADDITIONAL IMPLEMENTATION DETAILS
///
/// - MirrorMark automatically monitors changes to both source code and
///   corresponding `.mdmirror` files, alerting developers and/or LLMs when
///   discrepancies arise.
/// - All CLI actions can optionally be run in a **non-daemon** mode for
///   continuous integration environments or ephemeral container usage.
/// - Concurrency handling ensures that if multiple developers (or automated
///   processes) trigger migrations simultaneously, MirrorMark stages them
///   in a queue, preventing partial or conflicting merges.
///
/// 
/// ----
/// 
/// (End of MirrorMark Protocol Statement)
///

/*****************************************************************************
2) NOTES AND EXPLANATION OF THE KEY CHANGES
******************************************************************************/

/// # NOTES & EXPLANATIONS
///
/// 1. **Explicit Directory Structure**:  
///    We made sure to explicitly name the migration directory format:
///    `./mdmirror/migrations/YYYYMMDD-descriptor/` to standardize how migrations
///    are organized.  
///    - **Why**: This aids in quickly locating changesets by date and purpose.
///
/// 2. **Concurrency Handling**:  
///    We have introduced a note clarifying how MirrorMark queues migrations to
///    avoid collisions.  
///    - **Why**: Real-world usage often involves multiple concurrent developers,
///      so a queue or locking strategy helps maintain repository consistency.
///
/// 3. **Non-Daemon Mode**:  
///    We added the option to run commands in non-daemon mode, targeting cases
///    like CI/CD pipelines or ephemeral containers.  
///    - **Why**: Some environments disallow background daemons or require
///      ephemeral operation.
///
/// 4. **Backup & Rollback**:  
///    We emphasized that the `mmd apply` operation takes a **full compressed
///    backup** of the current state, ensuring safer rollbacks.  
///    - **Why**: Encourages version safety and helps maintain trust when making
///      large-scale changes.
///
/// 5. **No Detail Omitted**:  
///    All sections from the original draft have been retained. Where additions
///    or clarifications were provided, they are explicitly marked as “why”
///    justifications so the improvements are transparent.
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    // In a real-world application, you might print or serve this protocol text.
    // Here, we simply showcase how it might be embedded in your production Rust code.
    
    // Print the entire improved MirrorMark Protocol
    println!("{}", MIRRORMARK_PROTOCOL);

    // Print the notes & explanation of key changes
    println!("{}", MIRRORMARK_NOTES);

    Ok(())
}

/// This constant contains the entire improved MirrorMark protocol statement,
/// including the original details and our enhancements.
const MIRRORMARK_PROTOCOL: &str = r#"""
# MIRRORMARK PROTOCOL

MirrorMark is a technique of doubling code files with natural language equivalent markdown that precisely and completely describes the functionality of source code.

- **Mirroring Directory**: The protocol generates these mirror descriptions in a `.mdmirror` directory.
- **Summaries**: Each directory in a project contains a `SUMMARY.md` that condenses the main purpose and contents of that directory.
- **Architecture Specification**: The overarching project documentation is defined in `.mdmirror/ARCHITECTURE.md`.

MirrorMark then builds:
- A **semantic index** of terms and concepts used in code and docs.
- An **AST index** to map the code’s abstract syntax tree (if available).
- A **graph of file and module relationships** leveraging the semantic base and git history if present.

On top of summarizing the project goals, direction, top contributors, activity level, and other metrics, MirrorMark’s deeper objective is to align the code and its documentation, ensuring both remain consistently updated.

## MIRRORMARK V1 RUST

The initial implementation of MirrorMark is written in Rust with SurrealDB. A binary distribution is available for Linux, macOS, and Windows with a one-line installer:

```shell
CLI

The Rust-based implementation runs as a system daemon and provides the mirrormark binary with an alias mmd (if desired). The following commands are made available via the CLI:
	1.	mmd add
Allows directories to be added to the set of managed and watched directories for MirrorMark processing.
	2.	mmd ask
Allows you to pass natural language queries over your codebase and receive answers from large language models (LLMs) informed by the .mdmirror knowledge base.
	3.	mmd architect
Allows you to reshape the direction of the project. This could be a refactor, a new feature, or an adjustment to scope. It initiates a turn-based dialog with LLMs to fully understand the proposed change and identify all necessary filesystem modifications (including the natural language .mdmirror files) needed to manifest that change.
Once finalized, this command generates a migration directory in .mdmirror/migrations, such as ./mdmirror/migrations/20250128-add-cli-interface/ (where the date and phrase can vary based on context).
Inside the migration directory, you will find:
	•	DIFF.md
An MDDIFF-format diffset of all impacted files in both the codebase and .mdmirror/**/*.md.
	•	PROMPT.md
A set of ordered prompts for an LLM to apply those changes (also stored in MDDIFF format).
	•	AST.md
Contains ast-grep mutations specifying how to update both the actual codebase and the .mdmirror documentation.
	•	CHANGESET.md
A high-level summarization of the modifications required.
	•	VERIFICATION.md
A collection of steps, tests, and checks to demonstrate that the OBJECTIVE is met. This includes:
	•	Unit tests
	•	Functional tests
	•	LLM agent verification steps
	•	CONVENTIONS.md
Project-level coding conventions that are particularly useful to LLMs applying or reviewing the changeset.
	•	ARCHITECTURE.md
The updated future-state ARCHITECTURE.md after the change is applied.
	4.	mmd apply
Safely executes a chosen MirrorMark changeset against a codebase, providing a comprehensive backup and optional git branch merge functionality for rollbacks if needed.
	5.	mmd rollback
Reverts a previously applied changeset to restore the codebase to its pre-change state.
	6.	mmd verify
Leverages the VERIFICATION.md steps to confirm the changeset’s integrity, ensuring everything aligns with the intended goals.
	7.	mmd review
Generates an orchestrated code review of either the entire codebase or a specific migration, using the .mdmirror knowledge base as a reference for code correctness, style, and architecture.
	8.	mmd align
Creates a new migration that realigns the current codebase state with the architecture, coverage, or other project goals declared in the .mdmirror definitions. Useful when code has drifted from described conventions.

ADDITIONAL IMPLEMENTATION DETAILS
	•	MirrorMark automatically monitors changes to both source code and corresponding .mdmirror files, alerting developers and/or LLMs when discrepancies arise.
	•	All CLI actions can optionally be run in a non-daemon mode for continuous integration environments or ephemeral container usage.
	•	Concurrency handling ensures that if multiple developers (or automated processes) trigger migrations simultaneously, MirrorMark stages them in a queue, preventing partial or conflicting merges.

(End of MirrorMark Protocol Statement)
“#;

/// This constant contains the notes and explanations of the key changes made
/// to the original MirrorMark Protocol specification.
const MIRRORMARK_NOTES: &str = r#”

NOTES & EXPLANATIONS
	1.	Explicit Directory Structure
We made sure to explicitly name the migration directory format:
./mdmirror/migrations/YYYYMMDD-descriptor/ to standardize how migrations
are organized.
	•	Why: This aids in quickly locating changesets by date and purpose.
	2.	Concurrency Handling
We have introduced a note clarifying how MirrorMark queues migrations to
avoid collisions.
	•	Why: Real-world usage often involves multiple concurrent developers,
so a queue or locking strategy helps maintain repository consistency.
	3.	Non-Daemon Mode
We added the option to run commands in non-daemon mode, targeting cases like
CI/CD pipelines or ephemeral containers.
	•	Why: Some environments disallow background daemons or require ephemeral
operation.
	4.	Backup & Rollback
We emphasized that the mmd apply operation takes a full compressed backup
of the current state, ensuring safer rollbacks.
	•	Why: Encourages version safety and helps maintain trust when making
large-scale changes.
	5.	No Detail Omitted
All sections from the original draft have been retained. Where additions or
clarifications were provided, they are explicitly marked as “why”
justifications so the improvements are transparent.
""“#;

LICENSE.md

// // MIT License // // Copyright (c) 2025 David Maple[email protected] // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to deal // in the Software without restriction, including without limitation the rights // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell // copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE.

MIRRORMARK.md

MIRRORMARK PROTOCOL

MirrorMark is a technique of doubling code files with natural language equivalent markdown that precisely and completely describe the functionality of source code.

The protocol generates these in a .mdmirror directory. Additionally the protocol describes a technique of summarization for each directory (SUMMARY.md) and a specification for overarching project documentation in .mdmirror/ARCHITECTURE.md.

The protocol then builds a semantic index, AST index, a graph of file and module relationships using the semantic base and git history (if available).

The project goals, direction, top contributors, activity level and other metrics are summarized as well.

MIRRORMARK V1 RUST

The initial implementation of mirrormark is written in Rust with SurealDB. A binary distribution is available for Linux, Mac and Windows with a one line installer:

curl ...

cli

The Rust implementation runs as a system daemon and provides the mirrormark binary with alias mmd (if available). The following commands are made available via the cli:

• mmd add the add command allows directories to be added to managed and watched dirs
• mmd ask the ask command allows you to pass natural language queries over your codebase and get back answers for large language models (LLMs).
• mmd architect the architect command allows you to reshape the direction of the project. This could be a refactor, a new feature or a adjustment to scope or other changes of any sort. This opens a turn based dialog with LLMs that seek to full understand the change and identify all necessary filesystem modifications of the natural language files necessary to manifest the change. Once finalized this generates a migration directory in .mdmirror/migrations which includes:
  • the migration directory will assume a natural language tag for easy identifiation, such as:
    • ./mdmirror/20250128-add-cli-interface
      • DIFF.md :: an MDDIFF format diffset of the changeset and mdmirror files impacted in .mdmirror//*.md**
      • PROMPT.md :: an MDDIFF format diffset a prompt set of ordered prompts that an LLM could use to execute those changes
      • AST.md :: ast-grep mutations that would implement the .mdmirror changes
        • ast-grep mutations that would implement the actual codebase changes
        • ast-grep mutations that would implement the .mdmirror changes
      • CHANGESET.md a summarization of changes required
      • VERIFICATION.md a description of verification assets that would fully demonstrate OBJECTIVE success:
        • unit tests
        • functional tests
        • LLM agent verification steps
      • CONVENTIONS.md generates project level coding conventions useful to LLMs applying a changeset
      • ARCHITECTURE.md the new future state of ARCHITECTURE.md AFTER the chane is applied.
• mmd apply the apply command safely executes the application of an mmdmark changeset to a codebase, providing a full compressed backup and git branch merge functionality should rollback be required.
• mmd rollback unapply a formerly applied CHANGESET
• mmd verify verify a changeset based on the VERIFICATION.md steps
• mmd review generates an orchestrated code review of a codebase or of a migration
• mmd align generates a migration that aligns the current state of a codebase vs. the architecture, code coverage and goals described in the project definition.