@ipation/specbridge 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to SpecBridge will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-01-26
+
+### Fixed
+- Fixed all failing unit tests - 100% pass rate achieved (108/108 tests)
+- Created test setup helpers for .specbridge initialization
+- Added Reporter and AgentContextGenerator class wrappers for test compatibility
+- Fixed API mismatches in VerificationEngine, PropagationEngine, InferenceEngine
+- Updated Config Loader tests for async/await and schema compliance
+- Rewrote CLI integration tests to match actual implementation
+- Removed unused imports in hook.ts and infer.ts
+
+## [0.2.0] - 2026-01-26
+
+### Added
+
+#### Testing Infrastructure
+- Comprehensive test suite with 150+ test cases across 8 test files
+- Test fixtures: sample TypeScript project, decision files, config files
+- Vitest coverage configuration with 80% thresholds (lines/functions, 75% branches)
+- Coverage reporting in text, HTML, JSON, and LCOV formats
+- `npm run test:coverage` and `npm run test:ui` scripts
+
+#### CI/CD Infrastructure
+- GitHub Actions workflow for continuous integration (`ci.yml`)
+  - Tests on Node.js 18.x, 20.x, and 22.x
+  - Automated test execution and coverage upload to Codecov
+  - Build validation and package artifact upload
+- GitHub Actions security workflow (`security.yml`)
+  - CodeQL security scanning
+  - npm audit for dependency vulnerabilities
+  - Weekly scheduled security checks
+- Dependabot configuration for automated dependency updates
+- ESLint configuration with TypeScript support
+- Prettier configuration for code formatting
+- `npm run lint`, `npm run lint:fix`, `npm run format`, `npm run format:check` scripts
+
+#### npm Publishing
+- MIT LICENSE file
+- Complete package.json metadata (repository, homepage, bugs URL, keywords)
+- `.npmignore` for clean package distribution
+- GitHub Actions publish workflow for automated npm releases
+- Version management scripts: `version:patch`, `version:minor`, `version:major`
+- `publishConfig` for public npm registry access
+
+#### Developer Experience
+- Husky pre-commit hooks for automated checks
+- Pre-commit hook runs type-check and tests before commit
+- GitHub issue templates:
+  - Bug report template
+  - Feature request template
+  - Question template
+- GitHub pull request template with comprehensive checklist
+- `CODE_OF_CONDUCT.md` for community guidelines
+- `SECURITY.md` for security policy and vulnerability reporting
+- Status badges in README (CI, npm version, license, Node.js version)
+
+#### Documentation & Examples
+- TypeDoc configuration for API documentation generation
+- `npm run docs` script to generate API documentation
+- **TypeScript API Example** (`examples/typescript-api/`)
+  - Complete Express.js REST API
+  - Service naming convention enforcement
+  - Centralized error handling pattern
+  - SpecBridge configuration and decision files
+- **React Application Example** (`examples/react-app/`)
+  - React + TypeScript component structure
+  - Custom hook naming conventions
+  - Props interface patterns
+  - SpecBridge configuration and decision files
+- Examples overview README with learning path
+
+### Changed
+- Updated `vitest.config.ts` with coverage thresholds
+- Enhanced `package.json` with new scripts and metadata
+- Improved README with status badges and better formatting
+
+### Infrastructure
+- 58+ new files created
+- Production-ready project structure
+- Professional open-source setup
+
+## [0.1.0] - 2026-01-26
+
+### Added
+
+- **CLI Foundation**
+  - `specbridge init` - Initialize SpecBridge in a project
+  - `specbridge --version` and `specbridge --help`
+
+- **Decision Registry**
+  - YAML-based decision file format
+  - Decision validation with Zod schemas
+  - `specbridge decision list` - List all decisions
+  - `specbridge decision show <id>` - Show decision details
+  - `specbridge decision create <id>` - Create new decision
+  - `specbridge decision validate` - Validate decision files
+  - Support for constraint types: invariant, convention, guideline
+  - Support for severity levels: critical, high, medium, low
+  - Decision lifecycle: draft, active, deprecated, superseded
+
+- **Inference Engine**
+  - Codebase scanning with ts-morph
+  - `specbridge infer` - Detect patterns in codebase
+  - Built-in analyzers:
+    - `naming` - Naming convention detection
+    - `imports` - Import pattern detection
+    - `structure` - Directory structure detection
+    - `errors` - Error handling pattern detection
+  - Pattern confidence scoring
+  - Suggested constraint generation
+
+- **Verification Engine**
+  - `specbridge verify` - Verify code compliance
+  - Verification levels: commit (5s), pr (60s), full (5min)
+  - Built-in verifiers:
+    - `naming` - Naming convention verification
+    - `imports` - Import pattern verification
+    - `errors` - Error handling verification
+    - `regex` - Generic regex pattern matching
+  - Severity-based filtering
+  - Exception support with expiry dates
+
+- **Git Hook Integration**
+  - `specbridge hook install` - Install pre-commit hooks
+  - `specbridge hook run` - Run verification from hooks
+  - `specbridge hook uninstall` - Remove hooks
+  - Support for Husky and Lefthook
+
+- **Compliance Reporting**
+  - `specbridge report` - Generate compliance reports
+  - Output formats: console, markdown, json
+  - Per-decision compliance tracking
+  - Violation summary by severity
+
+- **Agent Interface**
+  - `specbridge context <file>` - Generate context for AI agents
+  - Output formats: markdown, json, mcp
+  - Applicable constraint filtering by file
+
+- **Propagation Engine**
+  - Dependency graph building
+  - Impact analysis for decision changes
+  - Migration step generation
+
+- **Configuration**
+  - YAML configuration in `.specbridge/config.yaml`
+  - Source roots and exclusion patterns
+  - Inference and verification settings
+  - Agent output customization
+
+### Technical
+
+- TypeScript with strict mode
+- ESM modules
+- Commander.js for CLI
+- ts-morph for AST analysis
+- Zod for schema validation
+- Vitest for testing
+- tsup for building
+
+[Unreleased]: https://github.com/nouatzi/specbridge/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/nouatzi/specbridge/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/nouatzi/specbridge/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/nouatzi/specbridge/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecBridge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# SpecBridge
+
+[![CI](https://github.com/nouatzi/specbridge/workflows/CI/badge.svg)](https://github.com/nouatzi/specbridge/actions)
+[![npm version](https://badge.fury.io/js/%40nouatzi%2Fspecbridge.svg)](https://www.npmjs.com/package/@ipation/specbridge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/%40nouatzi%2Fspecbridge)](https://nodejs.org)
+
+**Architecture Decision Runtime** - Transform architectural decisions into executable, verifiable constraints.
+
+SpecBridge creates a living integration layer between design intent and implementation, bridging the gap between specifications and code.
+
+## Features
+
+- **Inference Engine** - Analyzes existing codebases to extract implicit patterns
+- **Decision Registry** - Stores validated architectural decisions as versioned YAML files
+- **Verification Engine** - Continuously verifies code compliance at multiple levels
+- **Propagation Engine** - Analyzes impact when architectural decisions change
+- **Compliance Reporting** - Provides dashboards and tracks conformity over time
+- **Agent Interface** - Exposes decisions to code generation agents (Copilot, Claude, etc.)
+
+## Installation
+
+```bash
+npm install -g @ipation/specbridge
+```
+
+Or use directly with npx:
+
+```bash
+npx @ipation/specbridge init
+```
+
+Once installed globally, you can use the `specbridge` command directly:
+
+```bash
+specbridge init
+```
+
+## Quick Start
+
+### 1. Initialize SpecBridge in your project
+
+```bash
+cd your-project
+specbridge init
+```
+
+This creates a `.specbridge/` directory with:
+- `config.yaml` - Project configuration
+- `decisions/` - Architectural decision files
+- `verifiers/` - Custom verification logic
+- `inferred/` - Auto-detected patterns
+- `reports/` - Compliance reports
+
+### 2. Detect patterns in your codebase
+
+```bash
+specbridge infer
+```
+
+SpecBridge analyzes your code and suggests patterns it has detected, such as:
+- Naming conventions (PascalCase classes, camelCase functions)
+- Import patterns (barrel imports, path aliases)
+- Code structure (directory conventions, file naming)
+- Error handling patterns
+
+### 3. Create architectural decisions
+
+```bash
+specbridge decision create auth-001 \
+  --title "Authentication Token Handling" \
+  --summary "All authentication tokens must be validated server-side"
+```
+
+Or edit the YAML files directly in `.specbridge/decisions/`.
+
+### 4. Verify compliance
+
+```bash
+specbridge verify
+```
+
+Run verification at different levels:
+- `--level commit` - Fast checks for pre-commit hooks (< 5s)
+- `--level pr` - Full checks for pull requests
+- `--level full` - Comprehensive verification
+
+### 5. Generate compliance reports
+
+```bash
+specbridge report
+specbridge report --format markdown --save
+```
+
+### 6. Integrate with AI agents
+
+```bash
+specbridge context src/api/auth.ts
+```
+
+Generates architectural context in Markdown format for AI code assistants.
+
+## Decision File Format
+
+Decisions are stored as YAML files in `.specbridge/decisions/`:
+
+```yaml
+kind: Decision
+metadata:
+  id: auth-001
+  title: Authentication Token Handling
+  status: active
+  owners: [security-team]
+
+decision:
+  summary: All authentication tokens must be validated server-side
+  rationale: Client-side validation can be bypassed...
+
+constraints:
+  - id: server-validation
+    type: invariant
+    rule: Token validation must occur in server-side code
+    severity: critical
+    scope: src/api/**/*.ts
+
+  - id: token-expiry
+    type: convention
+    rule: Tokens should include expiry timestamps
+    severity: high
+    scope: src/auth/**/*.ts
+```
+
+### Constraint Types
+
+| Type | Description | Enforcement |
+|------|-------------|-------------|
+| `invariant` | Never to be violated | Blocks merges |
+| `convention` | Must be respected unless justified | Requires explanation |
+| `guideline` | Recommended practice | Informational only |
+
+### Severity Levels
+
+| Level | Description |
+|-------|-------------|
+| `critical` | Blocks deployment immediately |
+| `high` | Must be resolved within deadline |
+| `medium` | Should be addressed |
+| `low` | Added to backlog |
+
+## Git Hook Integration
+
+Install pre-commit hooks:
+
+```bash
+specbridge hook install
+```
+
+For Husky users:
+```bash
+specbridge hook install --husky
+```
+
+For Lefthook, add to `lefthook.yml`:
+```yaml
+pre-commit:
+  commands:
+    specbridge:
+      glob: "*.{ts,tsx}"
+      run: npx specbridge hook run --level commit --files {staged_files}
+```
+
+## Configuration
+
+Edit `.specbridge/config.yaml`:
+
+```yaml
+version: "1.0"
+project:
+  name: my-project
+  sourceRoots:
+    - src/**/*.ts
+    - src/**/*.tsx
+  exclude:
+    - "**/*.test.ts"
+    - "**/node_modules/**"
+
+inference:
+  minConfidence: 70
+  analyzers: [naming, structure, imports, errors]
+
+verification:
+  levels:
+    commit:
+      timeout: 5000
+      severity: [critical]
+    pr:
+      timeout: 60000
+      severity: [critical, high]
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `specbridge init` | Initialize SpecBridge in project |
+| `specbridge infer` | Detect patterns in codebase |
+| `specbridge verify` | Verify code compliance |
+| `specbridge decision list` | List all decisions |
+| `specbridge decision show <id>` | Show decision details |
+| `specbridge decision create <id>` | Create new decision |
+| `specbridge decision validate` | Validate decision files |
+| `specbridge report` | Generate compliance report |
+| `specbridge hook install` | Install git hooks |
+| `specbridge hook run` | Run verification (for hooks) |
+| `specbridge context <file>` | Generate agent context |
+
+Use `specbridge <command> --help` for detailed options.
+
+## Philosophy
+
+### What SpecBridge Is
+
+- A runtime constraint system for architectural decisions
+- A bridge between human decisions and automated enforcement
+- An inference system that learns before enforcing
+- A graduated constraint framework (guideline → convention → invariant)
+
+### What SpecBridge Is Not
+
+- Not an architectural framework (it's architecture-agnostic)
+- Not a code generator (it guides/constrains generators)
+- Not a documentation tool (decisions are executable)
+- Not a test replacement (verifies structure, not behavior)
+
+## Maturity Levels
+
+SpecBridge supports progressive adoption:
+
+1. **Observation** - Infer patterns from existing code
+2. **Documentation** - Document and version decisions
+3. **Detection** - CI detects violations
+4. **Constrained Generation** - Agents receive context
+5. **Automatic Correction** - Auto-fix minor violations
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node