{"id":22496980,"url":"https://github.com/morebec/specter","last_synced_at":"2025-03-27T21:25:18.652Z","repository":{"id":65298888,"uuid":"587141069","full_name":"Morebec/specter","owner":"Morebec","description":"Specter is a toolkit to develop simple Domain-Specific Languages (DSLs) based on HashiCorp Configuration Language (HCL).","archived":false,"fork":false,"pushed_at":"2024-09-12T05:35:14.000Z","size":234,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T23:45:11.902Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Morebec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-10T03:43:28.000Z","updated_at":"2024-09-12T05:34:50.000Z","dependencies_parsed_at":"2024-08-27T00:35:46.888Z","dependency_job_id":"38d740d2-36f7-467d-9c11-fea6b06dd36b","html_url":"https://github.com/Morebec/specter","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"53808f6b8544cbea7c86cbd5c755f395b04faccb"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Fspecter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Fspecter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Fspecter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Fspecter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Morebec","download_url":"https://codeload.github.com/Morebec/specter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245925712,"owners_count":20694947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-06T20:15:07.633Z","updated_at":"2025-03-27T21:25:18.627Z","avatar_url":"https://github.com/Morebec.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specter\n\n[![Go](https://github.com/Morebec/specter/actions/workflows/go.yml/badge.svg)](https://github.com/Morebec/specter/actions/workflows/go.yml)\n\nSpecter is a Go library designed to help developers easily build declarative DSLs (Domain-Specific Languages) and \nprocess them through an extensible pipeline. \n\nIt is currently used at [Morébec](https://morebec.com) for generating microservice APIs, code and documentation, \nmanaging configurations, automating deployments, and so many other fun things. \n\nSpecter provides a simple yet powerful framework to simplify these workflows.\n\nThe library also comes with many batteries included for common tasks such as dependency resolution \nand linting, HCL configuration loading and more.\n\n## Key Use Cases\n\nAt [Morébec](https://morebec.com) Specter is primarily used to create high-level, syntax-consistent DSLs for tools \nlike OpenAPI, Docker/Docker Compose, and Terraform. \n\nHere are some of the key use cases Specter powers for us internally:\n\n- **Code Generation:** We generate entire code bases in PHP and Go leveraging DDD/CQRS/ES in a low-code manner to focus on business logic and \nreduce plumbing work.\n- **Enforce Coding Standards**: We ensure consistency and improve development speed by automating code quality checks and \n  standardization.\n- **Configuration Management:** We use it to manage environment-specific configuration files, such as Docker or \n  Kubernetes manifests, using declarative Units.\n- **CI/CD Automation:** Automate the generation of CI/CD pipeline definitions (Jenkins, GitHub Actions, etc.) \n  by processing high-level declarative Units.\n- **Infrastructure as Code:** Describe infrastructure components declaratively and generate Terraform, \n  scripts, or other IAC artifacts.\n\n\n## How Specter Works\nSpecter is based around a simple yet powerful *pipeline* architecture. The core of the pipeline is designed to process \n*Units* — which are declarative components that represent different aspects or concepts — and produce various types \nof outputs based on them called *artifacts*.\n\nIn short, specter loads Units which it processes before outputting corresponding artifacts.\n\nFor example, in the case of our Go code generator, we first define Microservices with their Commands, Events\nand Queries in specification files that are then processed by Specter and transformed into their \ncorresponding Go implementation along with a changelog, markdown documentation and OpenAPI specification.\n\nIn this example, the Microservice/Command/Event/Query definition files are the \"Units\", while the\ngenerated code, markdown documentation, changelog, and OpenAPI are the \"artifacts\".\n\nUnits are anything that needs transforming, and artifacts are anything these units can be transformed into.\n\nTo illustrate, here's an example of a Unit File that could describe a docker container to be deployed on a \ngiven host using an HCL syntax:\n\n```\nservice \"web\" {\n  image = \"our-app:latest\"\n  ports = [\"8080:80\"]\n  volumes = [\n    {\n      type = \"bind\"\n      source = \"./html\"\n      target = \"/usr/share/nginx/html\"\n    }\n  ]\n  deploymentHost = \"primary-us-east-dev\"\n}\n```\n\n### Pipeline Stages\nThe pipeline consists of several stages, each responsible for a specific task in the workflow. \nHere's an overview of the stages and the concepts they introduce:\n\n### 1. Source Loading\nThe very first step is to acquire these units. Depending on the use cases these units could come from files, HTTP resources,\nor even Database rows. These different locations are known in Specter as Unit Sources.\n\nAs such, the Source Loading stage corresponds to loading these sources so that they can be acquired/fetched \nand read.\n\n- Inputs: Source locations\n- Outputs: (Loaded) Sources\n\n### 2. Unit Loading\nUnits are read and materialized into in-memory data structures. This stage converts raw source data into \nusable Units that can be processed according to your specific needs.\n\n- Inputs: Sources\n- Outputs: (Loaded) Units\n\n### 3. Unit Processing\nOnce the Units are loaded, Specter applies processors which are the core services responsible for generating artifacts\nbased on these units. These processors can do things like validate the Units, resolve dependencies, or convert them \ninto different representations. You can easily add custom processors to extend Specter's behavior. \n\nThe artifacts are in-memory representations of the actual desired outputs. For instance, the FileArtifact represents\na file to be outputted.\n\n- Inputs: Sources\n- Outputs: Artifacts\n\n### 4. Artifact Processing\nThe final stage of the pipeline processes artifacts that were generated during the previous step.\nThe processing of these artifacts can greatly vary based on the types of artifacts at play.\nAn artifact could be anything from a file, an API call, to a database insertion or update query, \nto a command or program to be executed.\n\n- Inputs: Artifacts\n- Outputs: Final outputs (files, API calls, etc.)\n\n## Getting Started\n\nTo start using Specter, you need to install Go and set up your Go workspace. \nThen, you can install Specter using the following command:\n\n```bash\ngo get github.com/morebec/specter\n```\n\nNext, you can create a new configuration file processor by defining your DSL in HCL and implementing the processing \npipeline. You can find more detailed instructions and examples in the [documentation](https://morebec.github.io/specter).\n\n## Examples\n\nHere are some examples of what you can do with Specter:\n\n- [Configuration file generator](https://github.com/morebec/specter-example-config-generator)\n- [Code generator](https://github.com/morebec/specter-example-code-generator)\n\n## Contributions\n\nWe welcome contributions to Specter! If you have an idea for a new feature or have found a bug, please open an issue to \ndiscuss it. If you want to contribute code, please follow \nour [contribution guidelines](https://morebec.github.io/specter/contributing) and open a pull request.\n\n## License\n\nSpecter is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorebec%2Fspecter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorebec%2Fspecter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorebec%2Fspecter/lists"}