Initial commit

Signed-off-by: Alex Nelson <[email protected]>

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# Portions of this file contributed by NIST are governed by the
+# following statement:
+#
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to Title 17 Section 105 of the
+# United States Code, this software is not subject to copyright
+# protection within the United States. NIST assumes no responsibility
+# whatsoever for its use by other parties, and makes no guarantees,
+# expressed or implied, about its quality, reliability, or any other
+# characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+  schedule:
+    - cron: '15 5 * * TUE'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - '3.9'
+          - '3.11'
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Pre-commit Checks
+      run: |
+        pip -q install pre-commit
+        pre-commit run --all-files
+    - name: Start from clean state
+      run: make clean
+    - name: Run tests
+      run: make PYTHON3=python3 check

.github/workflows/supply-chain.yml

@@ -0,0 +1,49 @@
+# Portions of this file contributed by NIST are governed by the
+# following statement:
+#
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to Title 17 Section 105 of the
+# United States Code, this software is not subject to copyright
+# protection within the United States. NIST assumes no responsibility
+# whatsoever for its use by other parties, and makes no guarantees,
+# expressed or implied, about its quality, reliability, or any other
+# characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+# This workflow uses Make to review direct dependencies of this
+# repository.
+
+name: Supply Chain
+
+on:
+  schedule:
+    - cron: '15 5 * * 1,2,3,4,5'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - '3.9'
+          - '3.11'
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        # This enables supply chain review against only a selected
+        # branch.  For those using the "Git-Flow" style of branching,
+        # the ref value should be 'develop', so an upstream dependency
+        # only relevant for, say, code formatting does not need to
+        # induce a new commit on 'main', or a release.
+        # https://cyberdomainontology.org/ontology/development/#branching-cdo-git-flow
+        ref: main
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Review dependencies
+      run: make check-supply-chain

.gitignore

@@ -0,0 +1,8 @@
+*.egg-info
+*.swp
+.DS_Store
+.git_submodule_init.done.log
+.venv-pre-commit
+__pycache__
+build
+dist

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.9.1
+    hooks:
+      - id: black
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.1.0
+    hooks:
+      - id: flake8
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        name: isort (python)

LICENSE

@@ -0,0 +1,39 @@
+Portions of this repository contributed by NIST are governed by
+the following license.
+
+
+# NIST Software Licensing Statement
+
+NIST-developed software is provided by NIST as a public service.
+You may use, copy, and distribute copies of the software in any
+medium, provided that you keep intact this entire notice. You may
+improve, modify, and create derivative works of the software or
+any portion of the software, and you may copy and distribute such
+modifications or works. Modified works should carry a notice
+stating that you changed the software and should note the date
+and nature of any such change. Please explicitly acknowledge the
+National Institute of Standards and Technology as the source of
+the software.
+
+NIST-developed software is expressly provided "AS IS." NIST MAKES
+NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT, OR ARISING BY
+OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+NON-INFRINGEMENT, AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR
+WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED
+OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES
+NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE
+SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE
+CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE
+SOFTWARE.
+
+You are solely responsible for determining the appropriateness of
+using and distributing the software and you assume all risks
+associated with its use, including but not limited to the risks
+and costs of program errors, compliance with applicable laws,
+damage to or loss of data, programs or equipment, and the
+unavailability or interruption of operation. This software is not
+intended to be used in any situation where a failure could cause
+risk of injury or damage to property. The software developed by
+NIST employees is not subject to copyright protection within the
+United States.

Makefile

@@ -0,0 +1,94 @@
+#!/usr/bin/make -f
+
+# Portions of this file contributed by NIST are governed by the
+# following statement:
+#
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to Title 17 Section 105 of the
+# United States Code, this software is not subject to copyright
+# protection within the United States. NIST assumes no responsibility
+# whatsoever for its use by other parties, and makes no guarantees,
+# expressed or implied, about its quality, reliability, or any other
+# characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+SHELL := /bin/bash
+
+PYTHON3 ?= python3
+
+all: \
+  .venv-pre-commit/var/.pre-commit-built.log
+
+.PHONY: \
+  check-supply-chain \
+  check-supply-chain-mypy \
+  check-supply-chain-pre-commit
+
+.git_submodule_init.done.log: \
+  .gitmodules
+	git submodule update --init
+	touch $@
+
+# This virtual environment is meant to be built once and then persist, even through 'make clean'.
+# If a recipe is written to remove this flag file, it should first run `pre-commit uninstall`.
+.venv-pre-commit/var/.pre-commit-built.log:
+	rm -rf .venv-pre-commit
+	test -r .pre-commit-config.yaml \
+	  || (echo "ERROR:Makefile:pre-commit is expected to install for this repository, but .pre-commit-config.yaml does not seem to exist." >&2 ; exit 1)
+	$(PYTHON3) -m venv \
+	  .venv-pre-commit
+	source .venv-pre-commit/bin/activate \
+	  && pip install \
+	    --upgrade \
+	    pip \
+	    setuptools \
+	    wheel
+	source .venv-pre-commit/bin/activate \
+	  && pip install \
+	    pre-commit
+	source .venv-pre-commit/bin/activate \
+	  && pre-commit install
+	mkdir -p \
+	  .venv-pre-commit/var
+	touch $@
+
+check: \
+  check-supply-chain-mypy \
+  .venv-pre-commit/var/.pre-commit-built.log
+	$(MAKE) \
+	  PYTHON3=$(PYTHON3) \
+	  --directory tests \
+	  check
+
+# This target's dependencies potentially modify the working directory's Git state, so it is intentionally not a dependency of check.
+check-supply-chain: \
+  check-supply-chain-pre-commit \
+  check-supply-chain-mypy
+
+check-supply-chain-mypy: \
+  .git_submodule_init.done.log
+	$(MAKE) \
+	  PYTHON3=$(PYTHON3) \
+	  --directory tests \
+	  check-mypy
+
+check-supply-chain-pre-commit: \
+  .venv-pre-commit/var/.pre-commit-built.log
+	source .venv-pre-commit/bin/activate \
+	  && pre-commit autoupdate
+	git diff \
+	  --exit-code \
+	  .pre-commit-config.yaml
+
+clean:
+	@rm -rf \
+	  *.egg-info \
+	  build \
+	  dist
+	@$(MAKE) \
+	  --directory tests \
+	  clean
+	@rm -f \
+	  .git_submodule_init.done.log

README.md

@@ -0,0 +1,75 @@
+# CASE Implementation Template: CLI Example
+
+[![Continuous Integration](https://github.com/casework/CASE-Implementation-Template-Python-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/casework/CASE-Implementation-Template-Python-CLI/actions/workflows/ci.yml)
+![CASE Version](https://img.shields.io/badge/CASE%20Version-1.2.0-green)
+
+_(Please see the [NIST disclaimer](#disclaimer).)_
+
+This template repository is provided for those looking to develop command-line utilities using ontologies within the [Cyber Domain Ontology](https://cyberdomainontology.org) ecosystem, particularly [CASE](https://caseontology.org) and [UCO](https://unifiedcyberontology.org).
+
+This template repository provides a [Make](https://en.wikipedia.org/wiki/Make_%28software%29)-based test workflow used in some other CASE projects.  The workflow exercises this project as a command-line interface (CLI) application (under [`tests/cli/`](tests/cli/)), and as a package (under [`tests/package/`](tests/package/)).
+
+This is only one possible application development style, and templates are available to support other styles.  See for instance:
+
+* [casework/CASE-Mapping-Template-Python](https://github.com/casework/CASE-Mapping-Template-Python), which demonstrates an approach based on constructing Python `dict`s and checking generated results afterwards for CASE conformance with the [CASE Validation Action](https://github.com/kchason/case-validation-action).
+
+Testing procedures run in _this_ repository are:
+
+* _GitHub Actions_: [Workflows](.github/workflows/) are defined to run testing as they would be run in a local command-line environment, reviewing on pushes and pull requests to certain branches.
+* _Supply chain review_: [One workflow](.github/workflows/supply-chain.yml) checks dependencies on a schedule, confirming pinned dependencies are the latest, and loosely-pinned dependencies do not impact things like type review.
+* _Type review_: `mypy --strict` reviews the package source tree and the tests directory.
+* _Code style_: `pre-commit` reviews code patches in Continuous Integration testing and in local development.  Running `make` will install `pre-commit` in a special virtual environment dedicated to the cloned repository instance.
+* _Doctests_: Module docstrings' inlined tests are run with `pytest`.
+* _CASE validation_: Unit tests that generate CASE graph files are written to run `case_validate` before considering the file "successfully" built.
+* _Editable package installation_: The test suite installs the package in an "editable" mode into the virtual environment under `tests/venv/`.  Activating the virtual environment (e.g. for Bash users, running `source tests/venv/bin/activate` from the repository's top source directory) enables "live code" testing.
+* _Parallel Make runs_: Tests based on `make` have dependencies specified in a manner that enables `make --jobs` to run testing in parallel.
+* _Directory-local Make runs_: The Makefiles are written to run regardless of the present working directory within the top source directory or the [`tests/`](tests/) directory, assuming `make check` has been run from the top source directory at least once.  If a test is failing, `cd`'ing into that test's directory and running `make check` should reproduce the failure quickly and focus development effort.
+
+
+## Usage
+
+To use the template, push the "Use this template" button on GitHub, and adapt files as suits your new project's needs.  The README should be revised at least from its top to the "Versioning" section.  Source files should be renamed and revised, and any other files with a `TODO` within it should be adjusted.
+
+After any revisions, running `make check` (or `make -j check`) from the top source directory should have unit tests continue to pass.
+
+_Below this line is sample text to use and adapt for your project.  Most text above this line is meant to document the template, rather than projects using the template._
+
+To install this software, clone this repository, and run `pip install .` from within this directory.  (You might want to do this in a virtual environment.)
+
+This provides a standalone command:
+
+```bash
+case_cli_example output.rdf
+```
+
+The tests build several examples of output for the command line mode, under [`tests/cli`](tests/cli/).
+
+The installation also provides a package to import:
+
+```python
+import case_cli_example
+help(case_cli_example.foo)
+```
+
+
+## Versioning
+
+This project follows [SEMVER 2.0.0](https://semver.org/) where versions are declared.
+
+
+## Make targets
+
+Some `make` targets are defined for this repository:
+* `all` - Installs `pre-commit` for this cloned repository instance.
+* `check` - Run unit tests.  *NOTE*: The tests entail an installation of this project's source tree, including prerequisites downloaded from PyPI.
+* `clean` - Remove test build files.
+
+
+## Licensing
+
+Portions of this repository contributed by NIST are governed by the [NIST Software Licensing Statement](LICENSE).
+
+
+## Disclaimer
+
+Participation by NIST in the creation of the documentation of mentioned software is not intended to imply a recommendation or endorsement by the National Institute of Standards and Technology, nor is it intended to imply that any specific software is necessarily the best available for the purpose.

case_cli_example/__init__.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+
+# Portions of this file contributed by NIST are governed by the
+# following statement:
+#
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to Title 17 Section 105 of the
+# United States Code, this software is not subject to copyright
+# protection within the United States. NIST assumes no responsibility
+# whatsoever for its use by other parties, and makes no guarantees,
+# expressed or implied, about its quality, reliability, or any other
+# characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+# TODO - Adapt below.
+
+"""
+case_cli_example is a command that demonstrates making a CLI application tested with a Make-based workflow.
+"""
+
+__version__ = "0.0.1"
+
+
+def foo() -> str:
+    """
+    This function is provided to demonstrate the doctests system templated in this repository.  If all doctests from the package source directory are removed, the 'check-doctest' recipe in /tests/Makefile will also need to be removed, because pytest reports a failure if no tests are found.
+
+    >>> foo()
+    'x'
+    """
+    return "x"