P3 consolidated: Supply chain security, TS/JS coupling adapter, mutation testing reference (Groups 5, 9, 10-TS/JS)

[jflowers]

Summary

Consolidated issue for all P3/future items: supply chain security tooling, the TS/JS coupling adapter, and a reference note on mutation testing (intentionally not a standalone effort).

RFC: https://github.com/orgs/unbound-force/discussions/483 — Groups 5 (partial), 9, 10 (TS/JS)
Phase: P3 (Multi-language) / Future

---

A. Supply Chain Security (Group 9)

OSV-Scanner

• Integrate OSV-Scanner per project for known vulnerability detection
• Run as part of CI pipeline
• Fail on critical/high severity vulnerabilities

SBOM Generation

• Generate Software Bill of Materials using cyclonedx-gomod for Go projects
• Store SBOMs as build artifacts
• Consider SBOM generation for other languages as adapters are added

License Compliance

• Scan dependencies for license compatibility
• Flag copyleft or unknown licenses
• Configurable allow/deny list

---

B. TS/JS Coupling Adapter (Group 10 — TS/JS)

Implementation

• Build a TS/JS coupling analyzer conforming to vibe-check's ExternalAdapter JSON-RPC 2.0 protocol (as defined in openspec/changes/universal-coupling-model/specs/analyzer-protocol/spec.md)
• Analyze TypeScript/JavaScript module-level coupling metrics
• Invoked by vibe-check as an ExternalAdapter subprocess (stdin/stdout JSON-RPC)
• Output JSON with language: "typescript" or language: "javascript"
• Handle CommonJS and ES module import styles

Metrics

• Same 7 metrics as Go and Python adapters (Ca, Ce, I, A, D, LCOM, circular deps)
• Abstractness adapted for TypeScript interfaces/abstract classes
• Output must conform to metrics.ModuleGraph schema (validated by metrics.Validate)

---

C. Mutation Testing Reference (Group 5)

Decision: Mutation testing was evaluated and downgraded to P3/optional. The existing Gaze contract coverage mechanism (37 side-effect types with behavioral assertions) provides substantial overlap with what mutation testing validates. If revisited, consider:

• go-mutesting or similar
• Scope to critical packages only (not full codebase)
• Run on a separate schedule (not per-PR due to performance)

This is a reference note, not a standalone work item.

---

Acceptance Criteria

Supply Chain

• OSV-Scanner integrated into CI
• SBOM generation via cyclonedx-gomod
• License compliance scanning configured
• Fail CI on critical vulnerabilities

TS/JS Adapter

• TS/JS analyzer conforms to vibe-check ExternalAdapter JSON-RPC 2.0 protocol
• All 7 coupling metrics computed for TS/JS modules
• JSON output with language field, conforming to metrics.ModuleGraph schema
• Handles CommonJS and ES module styles
• Integration with vibe-check analyze tested (registered as ExternalAdapter)

Mutation Testing

• Reference documented; no implementation required unless revisited

Dependencies

• Depends on: Design universal multi-language coupling metrics model (Group 10 — architecture) #1 (completed) — universal coupling model (ExternalAdapter protocol)
• Depends on: vibe-check analyze — Go-native package-level coupling metrics #2 — vibe-check analyze command (for ExternalAdapter registration)

[jflowers]

Amendment: Language-Specific Extensions (TS/JS Adapter)

Background

A gap analysis against the comprehensive Martin metrics framework identified three TypeScript/JavaScript-specific metrics absent from the current scope:

Metric	Description	Source
Type Coverage %	Ratio of typed AST nodes to total AST nodes. Measures how much of the codebase has explicit or inferred types.	type-coverage npm package
Type Instantiation Depth	Maximum depth of recursive conditional types and template literal types. Deep instantiation causes tsc slowdowns and Type instantiation is excessively deep errors.	TypeScript --extendedDiagnostics
Architectural Boundary Compliance	Count of cross-layer import violations (e.g., UI importing from data layer, bypassing service layer).	eslint-plugin-boundaries or equivalent

Proposed Integration

These use the same extensions mechanism proposed in the #2 amendment. The TS/JS adapter populates language-specific metrics via ModuleResult.Extensions.

1. Type Coverage %

The adapter analyzes each module's AST to compute the ratio of nodes with resolved types:

• typescript.typeCoverage — float64 in range [0.0, 1.0]. Ratio of typed AST nodes to total AST nodes.

Implementation options (adapter's choice):

• Invoke type-coverage as a subprocess (if available on PATH)
• Use TypeScript compiler API directly to count typed/untyped nodes
• Emit a Warning with code "type-coverage-unavailable" if neither method works

2. Type Instantiation Depth

The adapter runs tsc --extendedDiagnostics (or equivalent compiler API call) and extracts:

• typescript.typeInstantiationDepth — int, the maximum type instantiation depth encountered. High values (>50) indicate types that may cause compilation failures or slowdowns.

Fallback: If the project does not use TypeScript (pure JS), this extension is omitted.

3. Architectural Boundary Compliance

The adapter detects cross-layer import violations based on configurable layer definitions:

• typescript.boundaryViolations — []object, each with:
  • source — importing module path
  • target — imported module path
  • rule — which boundary rule was violated (e.g., "ui-imports-data")

Configuration: The adapter reads boundary rules from the project's ESLint config (eslint-plugin-boundaries settings) or a dedicated .vibe-check.boundaries.json file. If no boundary config exists, this extension is omitted with a Warning (code: "no-boundary-config").

4. New Capability Constants

const CAP_TYPE_COVERAGE = "typescript.typeCoverage";
const CAP_TYPE_INSTANTIATION_DEPTH = "typescript.typeInstantiationDepth";
const CAP_BOUNDARY_COMPLIANCE = "typescript.boundaryViolations";

These are optional capabilities declared in the adapter's capabilities response.

Additional Acceptance Criteria

Appended to the existing TS/JS adapter criteria:

• Adapter populates typescript.typeCoverage when type information is available
• Adapter populates typescript.typeInstantiationDepth for TypeScript projects
• Adapter populates typescript.boundaryViolations when boundary config exists
• Fallback warnings emitted when optional tooling is unavailable
• All three extension capabilities declared in capabilities response
• Extension values are valid JSON (adapter is responsible for structure)
• Pure JavaScript projects omit TypeScript-only extensions gracefully

Non-Goals

• No CI gate flags for extension metrics in this issue
• No bundling of type-coverage or eslint-plugin-boundaries — adapter uses what is on PATH
• No boundary rule authoring — adapter reads existing project config
• No javascript. namespace — JS modules use typescript.typeCoverage when processed by the TS adapter (they share the same adapter binary)