feat(js): public user-type accessors on SailsProgram and SailsService

[ukint-vs]

Closes #1320.

Summary

API additions (sails-js v2)

• Adds SailsProgram.programTypes: ReadonlyMap<string, Type> for program-level user types declared in the IDL's program {…} block.
• Adds SailsService.types: ReadonlyMap<string, Type> for the service's own types {…} block (declared-only — does not include types inherited via extends).
• Re-exports the v2 IDL AST typings (Type, TypeDecl, ITypeStruct, ITypeEnum, ITypeAlias, IIdlDoc, IServiceUnit, …) from the top-level sails-js entry, so consumers can import type { Type } from 'sails-js' without the sails-js/types subpath.

Both maps are eager-built in the constructor and return an empty Map when the corresponding IDL block is absent. They are typed ReadonlyMap to block .set() at the type level; runtime mutation is not enforced.

For the merged extends-chain scope, consumers continue to use program.resolveInService(name, decl) or walk service.extends[base].types. The new service.types accessor intentionally does not surface inherited types — making each service's declared surface explicit and keeping the existing resolution semantics untouched.

Why

vara-wallet and other downstream consumers were reaching into SailsProgram._doc via as any to enumerate user types (see #1320 for the full writeup). That escape hatch breaks silently the moment a private field is renamed between betas, and consumers couldn't stay type-safe at the AST level because sails-js-types was only reachable through the sails-js/types subpath.

Test Coverage

10 new tests in js/test/idl-v2-types-accessors.test.ts covering every code path on the new surface:

[+] SailsProgram.programTypes
  ├── [★★★ TESTED] populated from program.types
  ├── [★★★ TESTED] empty Map when program block has no types
  ├── [★★★ TESTED] empty Map when no program block (services-only IDL)
  └── [★★★ TESTED] same Map instance on repeated access (eager build)

[+] SailsService.types
  ├── [★★★ TESTED] populated from service.types
  ├── [★★★ TESTED] empty Map when service has no types block
  ├── [★★★ TESTED] declared-only: types in service A absent from service B.types
  ├── [★★★ TESTED] declared-only: base types not pulled into derived via extends
  │                  + sanity check: child.extends.Base.types includes the base type
  │                  + sanity check: program.resolveInService still merges scope
  └── [★★★ TESTED] same Map instance on repeated access (eager build)

[+] Top-level type re-export
  └── [★★★ TESTED] `import type { Type, ITypeStruct } from 'sails-js'` typechecks

COVERAGE: 10/10 paths tested (100%)

Tests: 14 → 15 (+1 new file, 10 new test cases). 84 of 84 v2 tests pass on the merged state (10 new + 74 adjacent regression-coverage suites: idl-v2-parser-type-resolver, idl-v2-type-resolver, event-type-shape, route-idx-header-validation, partial-idl).

Pre-Landing Review

Five review passes ran before landing. All findings resolved.

Pass	Findings	Resolution
/plan-eng-review	4 design tradeoffs (F1 empty-program contract, F2 lazy-vs-eager, F3 test placement, F4 mutation contract honesty)	All 4 resolved as documented in the plan file.
/review (gstack pre-landing)	1 INFORMATIONAL (sails-js-types resolution)	Tracked in #1344 at the time, then fully closed for this PR by Codex's later finding.
/code-review-graph review-pr	Graph reported "high risk" (488-node blast radius)	False signal — graph counts transitive dependents, not behavioral delta. Real delta is additive (zero existing surface modified).
/simplify (3 parallel reviewers)	1 actionable: ISailsService interface missing types member	Fixed in d47b2e95.
/codex review	1 P1: export type * from 'sails-js-types' ships unresolvable external module ref	Fixed in c4696f41 by re-exporting from the bundled ./types.js instead. Issue #1344 updated to reflect 1/4 of the historical leaks closed; 3 pre-existing references remain in lib/sails-idl-v2.d.ts, lib/util.d.ts, lib/parser.d.ts and will be addressed by the build-side fix tracked in #1344.

Bot comment from gemini-code-assist[bot] (eager-vs-lazy Map build) replied with the F2 rationale; no code change needed (review thread r3201667845).

Plan Completion

Item from plan	Status
Add SailsProgram.programTypes getter	DONE — js/src/sails-idl-v2.ts:259
Add SailsService.types getter	DONE — js/src/sails-idl-v2.ts:502
Add types to ISailsService interface	DONE — js/src/sails-idl-v2.ts:25
Top-level export type * from sails-js	DONE — js/src/index.ts:12 (via ./types.js)
New test file: idl-v2-types-accessors.test.ts	DONE — 10 tests
CHANGELOG ## Unreleased entries	DONE — 2 bullets added
JSDoc with declared-only contract on service.types	DONE
JSDoc with empty-Map contract on programTypes	DONE

COMPLETION: 8/8 DONE. No PARTIAL, no NOT DONE.

Documentation

js/CHANGELOG.md updated under ## Unreleased with two bullets covering the new accessors and the top-level type re-export (including the resolution path via bundled ./types.js). No README sync needed — the existing README documents only the sails-js/types subpath and that path still works exactly as before; the top-level alias is purely additive.

No version bump: js/package.json stays at 0.5.1 since this is part of the next unreleased.

Test plan

• pnpm test test/idl-v2-types-accessors.test.ts — 10/10 pass
• pnpm test for adjacent v2 suites — 74/74 pass (no regressions)
• pnpm build — clean; lib/index.d.ts emits export type * from './types.js'; lib/types.d.ts is fully dts-bundled (241 lines, all 49 AST types inlined, zero external module references)
• Type-level smoke check: import type { Type, ITypeStruct } from 'sails-js' typechecks at consumer install time without sails-js-types in node_modules
• CI: lint + test green on every commit
• Codex P1 (sails-js-types external ref in lib/index.d.ts) — fixed in this PR
• Pre-existing unrelated leaks in lib/sails-idl-v2.d.ts, lib/util.d.ts, lib/parser.d.ts — out of scope for this PR, tracked in sails-js: published .d.ts files reference private sails-js-types module #1344

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces public ReadonlyMap accessors for user types in SailsProgram and SailsService, and re-exports IDL AST types from the package root. A review comment suggests adopting a lazy indexing strategy for these type maps to improve performance and maintainability by avoiding unnecessary initialization overhead in the constructor.