iec-builder 0.1.0

package/src/services/catalog.test.ts

@@ -0,0 +1,1389 @@
+import { describe, it, expect, vi, afterEach, beforeAll } from 'vitest'
+import { mkdir, writeFile, rm } from 'fs/promises'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { randomUUID } from 'crypto'
+
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}))
+
+const mockEnv = vi.hoisted(() => ({
+  ENFORCE_MINIMUM_CATALOG_VERSION: 'false',
+}))
+
+vi.mock('../config/env.js', () => ({
+  env: mockEnv,
+}))
+
+import { parseCatalogInfo } from './catalog.js'
+
+async function createFixture(catalogYaml: string): Promise<string> {
+  const dir = join(tmpdir(), `iec-catalog-test-${randomUUID()}`)
+  await mkdir(dir, { recursive: true })
+  await writeFile(join(dir, 'catalog-info.yaml'), catalogYaml, 'utf-8')
+  return dir
+}
+
+describe('catalog defaults', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should apply correct static framework defaults', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-static-site
+  description: A simple static site
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: static
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.framework).toBe('static')
+    expect(result!.buildCommand).toBe('true')
+    expect(result!.outputDir).toBe('.')
+    expect(result!.port).toBe(80)
+    expect(result!.healthEndpoint).toBe('/health')
+    // startCommand falls back to 'npm start' because '' is falsy in the || chain
+    expect(result!.startCommand).toBe('npm start')
+  })
+
+  it('should allow annotation overrides for static framework', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-static-site
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: static
+    insureco.io/build-command: "npm run build"
+    insureco.io/output-dir: "dist"
+    insureco.io/port: "8080"
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.framework).toBe('static')
+    expect(result!.buildCommand).toBe('npm run build')
+    expect(result!.outputDir).toBe('dist')
+    expect(result!.port).toBe(8080)
+  })
+
+  it('should return null when no catalog-info.yaml exists', async () => {
+    const dir = join(tmpdir(), `iec-catalog-test-${randomUUID()}`)
+    await mkdir(dir, { recursive: true })
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).toBeNull()
+  })
+
+  it('should apply express framework defaults', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.framework).toBe('express')
+    expect(result!.buildCommand).toBe('npm run build')
+    expect(result!.outputDir).toBe('dist')
+    expect(result!.port).toBe(3000)
+    expect(result!.healthEndpoint).toBe('/health')
+  })
+})
+
+describe('catalog version validation', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should reject catalog with missing version annotation', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'missing the required "insureco.io/catalog-version" annotation'
+    )
+  })
+
+  it('should reject catalog with invalid semver format', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'Invalid catalog version format'
+    )
+  })
+
+  it('should include docs URL in missing version error', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'https://tawa.insureco.io/docs/catalog-reference'
+    )
+  })
+
+  it('should reject catalog with incompatible major version', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1.0.0"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'not compatible with this builder'
+    )
+  })
+
+  it('should reject catalog version ahead of builder', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.9.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'not supported by this builder'
+    )
+  })
+
+  it('should warn but accept catalog with lower minor version', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.1.0"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.catalogVersion).toBe('0.1.0')
+  })
+
+  it('should accept legacy version "1" as "0.1.0"', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.catalogVersion).toBe('0.1.0')
+  })
+
+  it('should accept catalog with current version 0.2.0', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.catalogVersion).toBe('0.2.0')
+  })
+
+  it('should reject 0.2.0 catalog missing required framework annotation', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'requires the "insureco.io/framework" annotation'
+    )
+  })
+
+  it('should reject 0.2.0 catalog missing required health-endpoint annotation', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'requires the "insureco.io/health-endpoint" annotation'
+    )
+  })
+
+  it('should accept catalog with current version', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.name).toBe('my-api')
+    expect(result!.framework).toBe('express')
+  })
+
+  it('should reject catalog with no annotations at all', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'missing the required "insureco.io/catalog-version" annotation'
+    )
+  })
+})
+
+describe('catalog config declarations', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should parse spec.config declarations with all fields', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  config:
+    - key: NEXTAUTH_SECRET
+      secret: true
+      required: true
+    - key: LOG_LEVEL
+      default: "info"
+    - key: STRIPE_API_KEY
+      secret: true
+      required: true
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.configDeclarations).toEqual([
+      { key: 'NEXTAUTH_SECRET', secret: true, required: true },
+      { key: 'LOG_LEVEL', default: 'info' },
+      { key: 'STRIPE_API_KEY', secret: true, required: true },
+    ])
+  })
+
+  it('should default to empty array when spec.config is missing', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.configDeclarations).toEqual([])
+  })
+
+  it('should reject declarations with invalid key names', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  config:
+    - key: "INVALID KEY WITH SPACES"
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow('Invalid config declaration key')
+  })
+
+  it('should reject duplicate declaration keys', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  config:
+    - key: STRIPE_KEY
+      secret: true
+    - key: STRIPE_KEY
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow('Duplicate config declaration key: "STRIPE_KEY"')
+  })
+
+  it('should skip non-object entries in config array', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  config:
+    - key: VALID_KEY
+    - "just a string"
+    - 42
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.configDeclarations).toEqual([{ key: 'VALID_KEY' }])
+  })
+
+  it('should parse minimal declarations with only key', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  config:
+    - key: APP_NAME
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.configDeclarations).toEqual([
+      { key: 'APP_NAME' },
+    ])
+  })
+})
+
+describe('catalog auth parsing', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should parse auth mode sso', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  auth:
+    mode: sso
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.authMode).toBe('sso')
+  })
+
+  it('should parse auth mode service-only', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: worker-svc
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  auth:
+    mode: service-only
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.authMode).toBe('service-only')
+  })
+
+  it('should parse auth mode none', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: public-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  auth:
+    mode: none
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.authMode).toBe('none')
+  })
+
+  it('should return undefined authMode when spec.auth is not specified', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.authMode).toBeUndefined()
+  })
+
+  it('should throw for invalid auth mode value', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  auth:
+    mode: invalid-mode
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow('Invalid spec.auth.mode: "invalid-mode"')
+  })
+})
+
+describe('catalog consumesDatabase parsing', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should parse consumesDatabase with envVar override in 0.2.0 catalog', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: portal
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: nextjs
+    insureco.io/health-endpoint: /api/health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  consumesDatabase:
+    - service: bio
+      type: mongodb
+      envVar: MONGODB_URI
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.consumesDatabase).toEqual([
+      { service: 'bio', type: 'mongodb', envVar: 'MONGODB_URI' },
+    ])
+  })
+
+  it('should ignore consumesDatabase in 0.1.0 catalog', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: portal
+  annotations:
+    insureco.io/catalog-version: "0.1.0"
+    insureco.io/framework: nextjs
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  consumesDatabase:
+    - service: bio
+      type: mongodb
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.consumesDatabase).toEqual([])
+  })
+
+  it('should parse databases with sharedWith in 0.2.0 catalog', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: bio
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  databases:
+    - type: mongodb
+      name: bio
+      sharedWith:
+        - service: portal
+          access: readWrite
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.databases).toHaveLength(1)
+    expect(result!.databases[0].sharedWith).toEqual([
+      { service: 'portal', access: 'readWrite' },
+    ])
+  })
+})
+
+describe('checkCatalogVersion', () => {
+  // Import the exported function directly
+  let checkCatalogVersion: typeof import('./catalog.js').checkCatalogVersion
+
+  beforeAll(async () => {
+    const mod = await import('./catalog.js')
+    checkCatalogVersion = mod.checkCatalogVersion
+  })
+
+  it('should return ok for matching version', () => {
+    expect(checkCatalogVersion('0.4.0').result).toBe('ok')
+  })
+
+  it('should return warn for lower minor version', () => {
+    const result = checkCatalogVersion('0.1.0')
+    expect(result.result).toBe('warn')
+    expect(result.message).toContain('behind')
+  })
+
+  it('should return reject for higher minor version', () => {
+    const result = checkCatalogVersion('0.9.0')
+    expect(result.result).toBe('reject')
+    expect(result.message).toContain('not supported')
+  })
+
+  it('should return reject for different major version', () => {
+    const result = checkCatalogVersion('1.0.0')
+    expect(result.result).toBe('reject')
+    expect(result.message).toContain('not compatible')
+  })
+
+  it('should return reject for invalid format', () => {
+    const result = checkCatalogVersion('abc')
+    expect(result.result).toBe('reject')
+    expect(result.message).toContain('Invalid catalog version format')
+  })
+})
+
+describe('catalog minimum version enforcement', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+    mockEnv.ENFORCE_MINIMUM_CATALOG_VERSION = 'false'
+  })
+
+  it('should reject legacy version "1" when enforcement is enabled', async () => {
+    mockEnv.ENFORCE_MINIMUM_CATALOG_VERSION = 'true'
+
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'below the minimum supported version'
+    )
+  })
+
+  it('should warn but accept legacy version "1" when enforcement is off', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.catalogVersion).toBe('0.1.0')
+  })
+
+  it('should reject version 0.1.0 when enforcement is enabled', async () => {
+    mockEnv.ENFORCE_MINIMUM_CATALOG_VERSION = 'true'
+
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.1.0"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'below the minimum supported version'
+    )
+  })
+
+  it('should include upgrade instructions in minimum version error', async () => {
+    mockEnv.ENFORCE_MINIMUM_CATALOG_VERSION = 'true'
+
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "1"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'tawa.insureco.io/docs/catalog-reference'
+    )
+  })
+})
+
+describe('catalog spec field validation', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should reject 0.2.0 catalog with missing owner', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'spec.owner is required'
+    )
+  })
+
+  it('should reject 0.2.0 catalog with owner set to unknown', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: unknown
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'spec.owner is required'
+    )
+  })
+
+  it('should reject 0.2.0 catalog with missing lifecycle', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'spec.lifecycle is required'
+    )
+  })
+
+  it('should reject 0.2.0 catalog with missing type', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'spec.type is required'
+    )
+  })
+
+  it('should accept 0.2.0 catalog with all required fields', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.catalogVersion).toBe('0.2.0')
+    expect(result!.owner).toBe('test-org')
+    expect(result!.framework).toBe('express')
+  })
+
+  it('should NOT validate spec fields for legacy 0.1.0 catalogs', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.1.0"
+    insureco.io/framework: express
+spec:
+  type: service
+  lifecycle: production
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.owner).toBe('unknown')
+  })
+
+  it('should include field name and example in spec validation error', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.2.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+`)
+    tempDirs.push(dir)
+
+    try {
+      await parseCatalogInfo(dir)
+      expect.fail('Should have thrown')
+    } catch (error) {
+      const message = (error as Error).message
+      expect(message).toContain('spec.owner')
+      expect(message).toContain('owner: my-org')
+      expect(message).toContain('tawa.insureco.io/docs/catalog-reference')
+    }
+  })
+})
+
+describe('catalog unified dependencies parsing', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(d => rm(d, { recursive: true, force: true })))
+    tempDirs.splice(0, tempDirs.length)
+  })
+
+  it('should parse spec.dependencies with transport direct in 0.4.0 catalog', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: relay
+      scopes: [relay:send]
+      transport: direct
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toEqual([
+      { service: 'relay', scopes: ['relay:send'], transport: 'direct' },
+    ])
+  })
+
+  it('should parse spec.dependencies with transport gateway', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: raterspot
+      scopes: [raterspot:rate, raterspot:quote]
+      transport: gateway
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toEqual([
+      { service: 'raterspot', scopes: ['raterspot:rate', 'raterspot:quote'], transport: 'gateway' },
+    ])
+  })
+
+  it('should reject invalid transport value', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: relay
+      scopes: [relay:send]
+      transport: invalid
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'Invalid transport "invalid"'
+    )
+  })
+
+  it('should reject dependency with missing service name', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - scopes: [relay:send]
+      transport: direct
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'service is required'
+    )
+  })
+
+  it('should reject dependency with empty scopes', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: relay
+      scopes: []
+      transport: direct
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'at least one scope is required'
+    )
+  })
+
+  it('should reject duplicate service dependencies', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: relay
+      scopes: [relay:send]
+      transport: direct
+    - service: relay
+      scopes: [relay:receive]
+      transport: direct
+`)
+    tempDirs.push(dir)
+
+    await expect(parseCatalogInfo(dir)).rejects.toThrow(
+      'Duplicate dependency on service "relay"'
+    )
+  })
+
+  it('should default transport to direct when omitted', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: relay
+      scopes: [relay:send]
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies[0].transport).toBe('direct')
+  })
+
+  it('should ignore spec.dependencies in pre-0.4.0 catalogs', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.3.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  dependencies:
+    - service: relay
+      scopes: [relay:send]
+      transport: direct
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toEqual([])
+  })
+
+  it('should map legacy internalDependencies to transport:direct with empty scopes', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.3.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  internalDependencies:
+    - service: iec-wallet
+      port: 3000
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toEqual([
+      { service: 'iec-wallet', scopes: [], transport: 'direct', port: 3000 },
+    ])
+  })
+
+  it('should map legacy externalDependencies to transport:gateway', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.3.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  externalDependencies:
+    - service: raterspot
+      scopes: [raterspot:rate]
+      reason: Rating engine
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toEqual([
+      { service: 'raterspot', scopes: ['raterspot:rate'], transport: 'gateway' },
+    ])
+  })
+
+  it('should merge both legacy fields into dependencies', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.3.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+  internalDependencies:
+    - service: iec-wallet
+      port: 3000
+  externalDependencies:
+    - service: raterspot
+      scopes: [raterspot:rate]
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toHaveLength(2)
+    expect(result!.dependencies[0]).toEqual({ service: 'iec-wallet', scopes: [], transport: 'direct', port: 3000 })
+    expect(result!.dependencies[1]).toEqual({ service: 'raterspot', scopes: ['raterspot:rate'], transport: 'gateway' })
+  })
+
+  it('should return empty dependencies when no deps declared', async () => {
+    const dir = await createFixture(`
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-api
+  annotations:
+    insureco.io/catalog-version: "0.4.0"
+    insureco.io/framework: express
+    insureco.io/health-endpoint: /health
+spec:
+  type: service
+  lifecycle: production
+  owner: test-org
+`)
+    tempDirs.push(dir)
+
+    const result = await parseCatalogInfo(dir)
+    expect(result).not.toBeNull()
+    expect(result!.dependencies).toEqual([])
+  })
+})