kata-spectacle

Spectacle

⚠️ WARNING: Not production ready code, instead a Code Kata intended to hone my programming skills through practice and repetition.

Discover projects within a hosted git platform that contain an OpenAPI Specifications so that an index can be generated.

• Getting Started
• Verification
• Design
• Security
• References
• License

Getting Started

Prepare

Begin by installing Go (go.dev) if you have not done so already.

You can test your install by calling the following command:

go version

Your version must be greater than or equal to the version defined in ./go.mod file.

Install, Verify, and Build

Install, verify, and build ./spectacle binary.

nvm use && make

Help

Learn about the available commands in the help menu.

./spectacle --help

See Commands section for more information.

Verification

Linting

make lint

These rules can then be automatically applied:

make format

Unit Testing

make test

Design

Repository Structure

🚧 indicates a feature that has not yet been implemented.

Features

🚧 indicates a feature that has not yet been implemented.

• ✅ CodeQL (codeql.github.com)
• ✅ GitHub Actions (github.com)
• ✅ Go Test (pkg.go.dev)
• ✅ Gofmt (pkg.go.dev)
• ✅ Husky (typicode.github.io)
• ✅ PNPM (pnpm.io)
• ✅ Prettier (prettier.io)
• ✅ Snyk (snyk.io)
• 🚧 GraphQL (graphql.org)
• 🚧 Internationalization
• 🚧 JestJS (jestjs.io)
• 🚧 Scss (sass-lang.com)
• 🚧 Svelte (svelte.dev)
• 🚧 TypeScript (typescriptlang.org)
• 🚧 ViteJS (vitejs.dev)

Commands

discover

Perform discovery operation to find api specifications.

serve

Start a web server to provide web interface and graphql service.

Noun, Verb Command Line Interface

To provide an easily understood command line interface, the noun verb pattern has been chosen. This pattern is similar to resource action pattern seen in web apis. The exception to this pattern is when a verb is used on its own. In this instance, no noun is required. Examples include serve and help.

Event Sourcing

The source of truth is a series of Historical Facts that are processed to form multiple projections. Each projection is specifically designed to support different use cases.

SpecificationRecord

Repository + Path + Commit

id: "${UUID}"
data:
    repository:
        git: "git@github.com:dbtedman/kata-spectacle.git"
        https: "https://github.com/dbtedman/kata-spectacle.git"
        public: "https://github.com/dbtedman/kata-spectacle"
    filePath: "docs/openapi.yaml"

Internationalization

💡️ Perhaps using a package like nicksnyder/go-i18n. The currently selected language could be discovered from the environment, e.g. LANG=en_AU.UTF-8 for command line and Accept-Language header, e.g. Accept-Language: en-AU,en;q=0.9 for the web ui.

Security

See the Security Policy.

References

💡 Resources referenced during the development of this project.

• Cobra: A Framework for Modern CLI Apps in Go (cobra.dev)
• Generating the SHA hash of a string using golang (stackoverflow.com)
• Go by Example: SHA256 Hashes (gobyexample.com)

License

The MIT License is used by this project.