3squaredcircles/insipio repository overview

Visit https://docs.3squaredcircles.com⁠ for a deep dive into configuration.

Feedback welcomed at https://www.linkedin.com/company/3-squared-circles/⁠

⁠3SC Insipio

The Automated Semantic Versioning and Impact Analyst for Your CI/CD Pipeline.

3SC Insipio is a polyglot semantic versioning engine that automates version calculation and release tagging by performing a deep, semantic analysis of your code. It moves beyond simple commit message conventions (feat:, fix:) to understand the actual impact of your code changes.

The tool works by comparing the "before" and "after" states of your codebase's Abstract Syntax Tree (AST). It detects breaking changes like modified method signatures, removed public classes, or altered interface contracts. Based on a configurable set of rules, it automatically determines whether a change constitutes a MAJOR, MINOR, or PATCH version increment, generates the appropriate Git tags, and produces a detailed metadata artifact for your release process.

⁠A Note on the Name

Insipio is derived from the Latin verb īnspiciō, which means "to inspect, examine, or look into." This name was chosen because the tool performs a deep inspection of your source code's structure to understand the true nature and impact of every change, going far beyond surface-level analysis.

---

⁠For the Manager (VP, Director of Engineering)

As a leader, you need a reliable, predictable, and automated release process. Manual versioning is prone to human error, leading to incorrect release tags, broken downstream dependencies, and a loss of trust in your versioning scheme. Insipio replaces manual guesswork with automated, data-driven precision.

Insipio answers your critical questions:

• "How can we be 100% certain that a breaking API change results in a MAJOR version bump, every single time?"
• "How do we stop wasting developer time debating whether a change is a MINOR feature or a PATCH fix?"
• "How can we create a fully automated, auditable history of every version change and the specific code changes that justified it?"
• "How can we enforce a consistent versioning and release tagging strategy across all our teams and repositories?"

⁠Key Business Values:

• Enforce Semantic Versioning Automatically: Insipio acts as a CI gate that guarantees your version numbers accurately reflect the impact of your code changes, preventing accidental breaking changes in minor/patch releases.
• Accelerate Release Cadence: By automating the versioning and tagging process, you can eliminate a slow, manual step in your release workflow, enabling faster and more frequent deployments.
• Improve Downstream Reliability: Consumers of your packages and APIs can trust your version numbers, knowing that a PATCH release will never contain a breaking change. This reduces integration failures across your organization.
• Create a Perfect Audit Trail: Because the tool's analysis and version decision are captured in a version-controlled artifact (insipio-metadata.json), you have a complete, auditable record of why every version was created.

---

⁠For the Architect & Engineer

As a developer, you want to focus on writing code, not on administrative release tasks. Insipio integrates into your CI/CD pipeline and automates the tedious process of versioning and tagging.

Insipio understands your code, not just your commit messages.

⁠Key Technical Values:

• Deep Semantic Analysis: The tool goes beyond Git history, parsing your code into an AST to detect high-impact changes that commit-message parsers would miss, such as:
  • A public method's signature changing.
  • A class no longer implementing an interface.
  • A new, required parameter being added to a public constructor.
• Configurable Impact Rules: You define what constitutes a MAJOR, MINOR, or PATCH change in a simple, version-controlled insipio/config.json file. This allows you to tailor the versioning rules to your project's specific needs.
• Automated Git Tagging: Once the analysis is complete, Insipio automatically generates and pushes the correct semantic and marketing version tags to your Git repository.
• Polyglot Support: The tool supports a wide range of popular programming languages, allowing you to standardize your versioning process across your entire tech stack.

---

⁠For the Platform Engineer (DevOps, SRE)

As an operator, you need tools that are predictable, configurable, and easy to integrate. Insipio is a containerized application designed for seamless inclusion in any CI/CD pipeline.

⁠Execution Modes:

• init: A one-time setup command that creates a default insipio/config.json file in your repository and applies the initial version tags (e.g., v0.0.0).
• execute The primary CI mode. It analyzes the changes since the last version tag, calculates the next version, generates the insipio-metadata.json artifact, and pushes the new version tags to Git.
• interactive: Starts a local web server to host the "Governance Hub" UI, which provides a "Codebase Explorer" to visualize your project's structure and helps you build and test your impact rules.
• serve-docs: Starts a lightweight server to display embedded tool documentation.