[ISSUE 7] Automated diagram generation

.gitignore

@@ -134,3 +134,7 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+
+# VSCode settings
+.vscode/

README.md

@@ -58,7 +58,7 @@ A modernization effort for Grants.gov.
 1. Visit [localhost:9001](https://localhost:9001) to view the server
 -->
 
-### Setting up development tools 
+### Setting up development tools
 
 #### Configuring pre-commit hooks
 

milestone-cli/Makefile

@@ -0,0 +1,35 @@
+diagram_path := ./diagram.mmd
+summary_path := ./summary.md
+
+install:
+	poetry install
+
+lint:
+	poetry run black milestone_cli tests
+	poetry run ruff milestone_cli tests --fix
+	poetry run mypy milestone_cli tests
+
+requirements:
+	poetry export -f requirements.txt -o requirements.txt --with dev --without-hashes
+	echo ".  # installs project" >> requirements.txt
+
+tox:
+	make requirements
+	poetry run tox
+
+milestones-check:
+	poetry run milestones validate
+
+milestones-diagram:
+ifneq ($(output_path),)
+	poetry run milestones populate diagram $(output_path)
+else
+	poetry run milestones populate diagram $(diagram_path)
+endif
+
+milestones-summary:
+ifneq ($(output_path),)
+	poetry run milestones populate summary $(output_path)
+else
+	poetry run milestones populate summary $(summary_path)
+endif

milestone-cli/README.md

@@ -0,0 +1,48 @@
+# Milestone CLI Tool
+
+The milestone CLI tool streamlines the process of validating and publishing changes to the milestone summary yaml file.
+
+## Getting Started
+
+### Prerequisites
+
+The following items are pre-requisites for installing this CLI tool:
+
+- Python version 3.10 or greater
+- Poetry
+
+Validate that these requirements are met with:
+```shell
+python --version
+poetry --version
+```
+
+### Quickstart
+
+1. Install the package: `make install`
+2. Validate the milestone yaml file: `make milestones_check`
+3. Populate the files:
+   - Diagram: `make milestones_diagram`
+   - Summary: `make milestones_summary`
+
+
+## Made with
+
+- Project Dependencies
+  - pydantic - Extends python dataclasses for data (de)serialization and validation
+  - typer - Enables building simple but powerful command-line interfaces
+  - Jinja2 - Templating engine used to populate documents with data
+  - PyYAML - (De)serializes data between yaml files and python objects
+- Dev Dependencies
+  - poetry - Python build tool and dependency manager
+  - ruff - Fast python linter built in Rust
+  - black - Auto-formatting for python
+  - pytest - Unit test framework
+  - tox - Test and linting orchestrator
+
+
+## Roadmap
+
+- Simplify setup with Makefile
+- Expand validations that are run on load
+- Improve exception handling and error messages

milestone-cli/milestone_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

milestone-cli/milestone_cli/cli.py

@@ -0,0 +1,96 @@
+"""Defines the command line entry points to load and populate milestone files"""
+from pathlib import Path
+
+import typer
+
+from milestone_cli.utils import (
+    load_milestones_from_yaml_file,
+    render_milestone_template,
+    create_or_replace_file,
+    MilestoneSummary,
+)
+
+# path to root of the repository
+REPO_ROOT_DIR = Path(__file__).absolute().parent.parent.parent
+
+# path to project directories and files
+PROJECT_ROOT = REPO_ROOT_DIR / "milestone-cli"
+TEMPLATE_DIR = PROJECT_ROOT / "milestone_cli" / "templates"
+DIAGRAM_TEMPLATE = TEMPLATE_DIR / "milestone-diagram.mmd"
+SUMMARY_TEMPLATE = TEMPLATE_DIR / "milestone-summary.md"
+
+# external directories and files
+MILESTONE_DIR = REPO_ROOT_DIR / "documentation" / "milestones"
+MILESTONE_FILE = MILESTONE_DIR / "milestone-summaries.yaml"
+
+
+app = typer.Typer(name="Milestone CLI")
+
+
+@app.command(name="hello")
+def hello_world(name: str | None = None):
+    """Say hello to a given name or Hello World by default"""
+    print(f"Hello {name if name else 'world'}")
+
+
+@app.command(name="validate")
+def validate_yaml_file_contents(
+    yaml_file: str | None = None,
+) -> MilestoneSummary | None:
+    """Loads MilestoneSummary from yaml file and validates contents
+
+    Args:
+        yaml_file: Pathlike string to the yaml file which contains milestone details
+
+    Returns:
+        An instance of MilestoneSummary when the details can be parsed from the
+        yaml file, None if the file doesn't exist or there are parsing errors
+    """
+    if not yaml_file:
+        file_path = MILESTONE_FILE
+    else:
+        file_path = Path(yaml_file).absolute()
+    if not file_path.exists():
+        print(f"No file found at {file_path}")
+        return None
+    if file_path.suffix not in (".yaml", ".yml"):
+        print(f"{file_path} is not a path to a yaml file")
+        return None
+    milestones = load_milestones_from_yaml_file(file_path)
+    print("Everything looks good")
+    return milestones
+
+
+@app.command(name="populate")
+def populate_output_file(
+    kind: str,
+    output_file: str,
+    yaml_file: str | None = None,
+) -> None:
+    """Populate either the diagram or the summary file
+
+    Args:
+        kind: The type of document we are populating, must be "diagram" or "summary"
+        output_file: Pathlike string to the output file to populate
+        yaml_file: Pathlike string to yaml file from which to load milestone details
+    """
+    if kind == "diagram":
+        template_path = DIAGRAM_TEMPLATE
+    elif kind == "summary":
+        template_path = SUMMARY_TEMPLATE
+    else:
+        print("Command must either be 'populate summary' or 'populate diagram'")
+    # load milestones and get output path
+    milestones = validate_yaml_file_contents(yaml_file)
+    if not milestones:
+        return
+    file_path = Path(output_file).absolute()
+    print(f"Writing {kind} to {file_path}")
+    # create or replace output file with rendered template
+    create_or_replace_file(
+        file_path=file_path,
+        new_contents=render_milestone_template(
+            template_path,
+            milestones.export_jinja_params(),
+        ),
+    )

milestone-cli/milestone_cli/schemas.py

@@ -0,0 +1,121 @@
+"""Defines the data interfaces for milestone details"""
+from pydantic import BaseModel
+
+
+class MilestoneBase(BaseModel):
+    """Contains fields shared by Milestone and Section
+
+    Attributes:
+        heading: The heading as it will appear in the summary markdown doc
+        description: The description as it will appear in the summary markdown doc
+        diagram_name: The name as it will appear in the mermaid diagram
+    """
+
+    heading: str
+    description: str
+    diagram_name: str
+
+
+class Milestone(MilestoneBase):
+    """Contains a summary of details about a project milestone
+
+    Attributes:
+        status: The status of the milestone, which appears in the summary doc and
+            determines the styling applied to the node in the mermaid diagram
+        dependencies: A list of the upstream dependencies for this milestone
+    """
+
+    status: str | None = None
+    dependencies: list[str] | None = None
+
+
+class MilestoneSection(MilestoneBase):
+    """Represents a group of project milestones
+
+    Attributes:
+        milestones: The list of milestones that fall under this section
+    """
+
+    milestones: dict[str, Milestone]
+
+
+class Dependency(BaseModel):
+    """Documents a (downstream) milestone's dependency on an upstream milestone
+
+    Attributes:
+        upstream: The milestone that the downstream milestone depends on
+        downstream: The downstream milestone that is blocked by the upstream milestone
+    """
+
+    upstream: Milestone
+    downstream: Milestone
+
+    def jinja_export(self) -> dict:
+        """Export just the diagram names for jinja templating
+
+        Returns:
+            A dictionary of the diagram names for upstream and downstream dependencies
+        """
+        return {
+            "upstream": self.upstream.diagram_name,
+            "downstream": self.downstream.diagram_name,
+        }
+
+
+class MilestoneSummary(BaseModel):
+    """Stores the list of milestones and the sections they belong to
+
+    Attributes:
+        version: Version of the milestone summary pulled from the yaml file
+        sections: A dictionary that maps MilestoneSections to their keys
+    """
+
+    version: str
+    sections: dict[str, MilestoneSection]
+
+    def map_dependencies(self, milestone: Milestone) -> list[Dependency] | None:
+        """Split milestone dependencies into a list of Dependency objects
+
+        Args:
+            milestone: A Milestone object to map dependencies for
+
+        Returns:
+            A list of Dependency objects for the given Milestone if it has
+            upstream depdencies, None otherwise
+        """
+        if not milestone.dependencies:
+            return None
+        deps = []
+        for parent in milestone.dependencies:
+            upstream = self.milestones.get(parent)
+            if not upstream:
+                # TODO: Change to custom error type
+                raise KeyError(f"'{parent}' not found in list of milestones")
+            deps.append(Dependency(upstream=upstream, downstream=milestone))
+        return deps
+
+    @property
+    def dependencies(self) -> list[Dependency]:
+        """Returns a list of Dependency objects across all milestones"""
+        results = []
+        for milestone in self.milestones.values():
+            dependencies = self.map_dependencies(milestone)
+            if dependencies:
+                results.extend(dependencies)
+        return results
+
+    @property
+    def milestones(self) -> dict[str, Milestone]:
+        """Returns a combined dictionary of Milestone objects mapped to their key"""
+        return {
+            milestone: details
+            for section in self.sections.values()
+            for milestone, details in section.milestones.items()
+        }
+
+    def export_jinja_params(self) -> dict:
+        """Exports sections and milestones for use in jinja templates"""
+        return {
+            **self.dict(),
+            "dependencies": [dep.jinja_export() for dep in self.dependencies],
+        }

milestone-cli/milestone_cli/templates/milestone-diagram.mmd

@@ -0,0 +1,38 @@
+%% A note on syntax:
+%% 1. Since node IDs cannot have spaces, prefer to give each milestone a short name with any spaces replaced by `-`. For instance, "Development Tools Implemented" becomes "Dev-Tools".
+
+%% For unclear reasons, PyCharm's mermaid editor does not support title attributes. Comment on or off the title as needed.
+
+%% ---
+%% title: Grants.gov modernization milestones
+%% ---
+
+%% Diagram is oriented left-to-right ("LR") rather than top-to-bottom
+
+flowchart LR
+
+    {% for section in params.sections.values() %}
+    subgraph {{ section.diagram_name -}}
+        {% for milestone in section.milestones.values() %}
+        {{ milestone.diagram_name }}:::{{ milestone.status if milestone.status else 'TODO' -}}
+        {% endfor %}
+    end
+    {% endfor %}
+
+    subgraph Legend
+        direction LR
+        a1[This milestone is finished]:::finished      -->  a2[This milestone is being executed]:::executing
+        a3[This milestone is being planned]:::planning -->  a4[This milestone is not yet planned]
+        a5[This milestone is a 'north star' milestone]:::northStar
+    end
+
+    %% List relationships %%
+    {%- for dependency in params.dependencies %}
+    {{ dependency.upstream }} --> {{ dependency.downstream -}}
+    {% endfor %}
+
+    %% Define some styles
+    classDef planning fill:#9999FF
+    classDef executing fill:#FF6633
+    classDef finished fill:#99FF33
+    classDef northStar fill:#cc99ff