Phase 3, Task 15: SWE Common Index

[Sam-Bolling]

Task

Create the SWE Common index (index.ts) — a barrel file that re-exports all SWE Common parsers, types, and utilities from a single entry point with tree-shaking friendly exports.

ROADMAP Reference: Phase 3, Task 15 — SWE Common Index (~0.5-1 hour, Low complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/formats/swecommon/index.ts	Create	~50-100	Barrel file re-exporting all SWE Common parsers and types
src/ogc-api/csapi/formats/swecommon/index.spec.ts	Create	~20-30	Verify exports are accessible and tree-shaking works

Blueprint Reference

Follow the EDR pattern in src/ogc-api/edr/model.ts (126 lines) for file structure and src/ogc-api/edr/model.spec.ts (42 lines) for test patterns.

Scope — What to Implement

Barrel File Exports

The index file re-exports from the 5 SWE Common module files. Use named re-exports (not wildcard export *) for tree-shaking friendliness and explicit API surface control.

Type exports (from types.ts — Issue #17):

• SWEDataComponent — discriminated union of all 16 component types
• DataRecord, DataField — record structures
• DataArray, ElementCount, EncodedValues — array structures
• Vector, Matrix, DataChoice, Geometry — complex aggregates
• Quantity, Count, Boolean, Text, Time, Category — simple scalars
• QuantityRange, CountRange, TimeRange, CategoryRange — range components
• DataEncoding, JSONEncoding, TextEncoding, BinaryEncoding, BinaryMember — encoding types
• UnitOfMeasure, AllowedValues, AllowedTokens, Quality, NilValues — supporting types
• ValidationResult, ValidationError — validation result types

Parser exports (from parser.ts — Issue #27):

• parseSWEComponent — main entry point for parsing any data component
• parseVector, parseMatrix, parseDataChoice, parseGeometry — complex component parsers
• detectEncoding — encoding type detection
• validateAgainstSchema — schema validation

Sub-parser exports (from Issues #24, #25, #26):

• parseSimpleComponent (from components.ts — Issue Phase 3, Task 11: SWE Common Simple Components Parser #24)
• parseDataRecord (from data-record.ts — Issue Phase 3, Task 12: SWE Common DataRecord Parser #25)
• parseDataArray, parseEncoding, decodeValues (from data-array.ts — Issue Phase 3, Task 13: SWE Common DataArray Parser #26)

Export Organization

Group exports logically with JSDoc section comments:

// --- Types ---
export type { SWEDataComponent, DataRecord, DataField, ... } from './types.js';

// --- Main Parser ---
export { parseSWEComponent, detectEncoding, validateAgainstSchema, ... } from './parser.js';

// --- Sub-Parsers ---
export { parseSimpleComponent } from './components.js';
export { parseDataRecord } from './data-record.js';
export { parseDataArray, parseEncoding, decodeValues } from './data-array.js';

Use export type for all type/interface re-exports (TypeScript isolatedModules compatibility).

JSDoc Requirements

• Module-level JSDoc comment documenting the SWE Common module purpose, entry points, and usage example
• Example showing recommended import pattern: import { parseSWEComponent, type DataRecord } from './formats/swecommon/index.js'
• Add @see link to OGC SWE Common 3.0 (24-014)
• Follow the JSDoc style in src/ogc-api/edr/model.ts

Testing Requirements

• Create src/ogc-api/csapi/formats/swecommon/index.spec.ts (~20-30 lines)
• Export accessibility tests:
  • Main parser function is exported and callable
  • Sub-parser functions are exported and callable
  • Type exports resolve (TypeScript compilation test)
• Tree-shaking tests:
  • Importing a single function does not pull in unrelated modules
  • Named exports (not default) used throughout
• Follow test patterns from src/ogc-api/edr/model.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT create or modify types.ts — that belongs to Issue Phase 3.4: SWE Common Types #17 (SWE Common Types)
• ❌ Do NOT create or modify components.ts — that belongs to Issue Phase 3, Task 11: SWE Common Simple Components Parser #24 (SWE Common Simple Components Parser)
• ❌ Do NOT create or modify data-record.ts — that belongs to Issue Phase 3, Task 12: SWE Common DataRecord Parser #25 (SWE Common DataRecord Parser)
• ❌ Do NOT create or modify data-array.ts — that belongs to Issue Phase 3, Task 13: SWE Common DataArray Parser #26 (SWE Common DataArray Parser)
• ❌ Do NOT create or modify parser.ts — that belongs to Issue Phase 3, Task 14: SWE Common Main Parser #27 (SWE Common Main Parser)
• ❌ Do NOT create or modify any SensorML files — those belong to Issues Phase 3, Task 5: SensorML Types #18-Phase 3, Task 10: SensorML Index #23
• ❌ Do NOT modify files outside the "Files to Create or Modify" table above
• ❌ Do NOT refactor existing code unless required to complete this task

Acceptance Criteria

• index.ts exists as barrel file re-exporting all SWE Common public API
• All type exports use export type syntax
• All parser function exports use named export (no default exports)
• Exports are organized with logical grouping comments
• Module-level JSDoc documents purpose and usage patterns
• index.spec.ts exists verifying export accessibility
• Tree-shaking friendly (named exports, no side effects)
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Issue #17 — SWE Common Types, Issue #24 — Simple Components Parser, Issue #25 — DataRecord Parser, Issue #26 — DataArray Parser, Issue #27 — Main Parser
Blocks: Issue #30 — Format Index (re-exports from this barrel file)

---

Operational Constraints

⚠️ MANDATORY: Before starting work on this issue, review docs/governance/AI_OPERATIONAL_CONSTRAINTS.md.

Key constraints for this task:

• Precedence: OGC specifications → AI Collaboration Agreement → This issue description → Existing code → Conversational context
• No scope expansion: Do not infer unstated requirements or add unrequested features
• No refactoring: Do not rename, restructure, or "improve" code outside this issue's scope
• Minimal diffs: Prefer the smallest change that satisfies the acceptance criteria
• Ask when unclear: If intent is ambiguous, stop and ask for clarification

---

References

Read these documents before starting implementation. They are ordered by priority.

Primary References (must read)

#	Document	Section/Lines	What It Provides
1	docs/planning/csapi-implementation-guide.md	Lines 2098-2120 (File Structure)	File organization showing index.ts (~50-100 lines) as SWE exports barrel
2	src/ogc-api/edr/model.ts	Full file (126 lines)	Blueprint — file structure, JSDoc style, export conventions
3	src/ogc-api/edr/model.spec.ts	Full file (42 lines)	Blueprint — test structure and patterns

Upstream Source Files (files this task re-exports from)

#	File	Issue	What It Exports
1	src/ogc-api/csapi/formats/swecommon/types.ts	#17	All SWE Common TypeScript interfaces and type unions
2	src/ogc-api/csapi/formats/swecommon/components.ts	#24	parseSimpleComponent and related utilities
3	src/ogc-api/csapi/formats/swecommon/data-record.ts	#25	parseDataRecord
4	src/ogc-api/csapi/formats/swecommon/data-array.ts	#26	parseDataArray, parseEncoding, decodeValues
5	src/ogc-api/csapi/formats/swecommon/parser.ts	#27	parseSWEComponent, detectEncoding, validateAgainstSchema, complex component parsers

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	export { X } from './file.js'
Use export type for interfaces/types	export type { Y } from './model.js'
Named exports only (no default)	export { parseSWEComponent } from './parser.js'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi
HTTP mocking: globalThis.fetch = jest.fn()	Never use nock, msw, or other libraries
Meaningful tests only	Verify behavior, not that code runs without throwing

[Sam-Bolling]

📋 Required Reading: Phase 3 Lessons Learned

Before starting work on this issue, review the Phase 3 Lessons Learned document:

👉 docs/governance/phase-3-lessons-learned.md

Instructions:

1. Read the lessons learned document first — before reading the issue body
2. Read phase-2-lessons-learned.md second — Lessons 8 (multi-server) and 10 (read-only smoke tests) remain mandatory
3. Review AI_OPERATIONAL_CONSTRAINTS.md as always

Key lessons applicable to all Phase 3 work:

• Lesson 1: Upstream audit check — before building new layers
• Lesson 2: Postel's Law — never gate extraction on validation
• Lesson 10: Type naming rules when defining types from external specs