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.

[gemini-code-assist]

To improve maintainability and performance, and to address the duplication in type mapping logic, implement a lazy indexing strategy using a Map. This ensures O(1) lookup time for frequent access to the IDL tree while avoiding unnecessary initialization overhead in the constructor, as per the project's performance guidelines for large data structures.

private _typesMap?: Map<string, Type>;
private get typesMap(): Map<string, Type> {
  if (!this._typesMap) {
    this._typesMap = new Map((this.types ?? []).map(t => [t.name, t]));
  }
  return this._typesMap;
}

References

1. For methods performing frequent lookups in large data structures (such as IDL trees), implement a lazy indexing strategy using a Map to achieve O(1) lookup time and avoid unnecessary initialization overhead.

[ukint-vs]

This is a deliberate eager-build choice, not an oversight. The tradeoff was weighed during plan review (F2) and resolved as eager:

• The maps are O(N) over a small N (per-program/per-service user-type counts are typically <50). Build cost is negligible compared to the parse step that already runs to produce the IIdlDoc.
• _doc is immutable post-parse (see existing comment at sails-idl-v2.ts:174–176). Lazy invalidation is a non-feature here.
• Lazy adds a private _typesMap?: Map<string, Type> field plus a guard branch in every access. The maps are tiny — that's noise without payoff.
• The existing lazy field on this class (_serviceTypeIndex at sails-idl-v2.ts:178) is lazy because it walks the extends chain across all services in one pass, which is genuine work. (service.types ?? []).map(t => [t.name, t]) from a single unit is a flat copy and isn't comparable.

The "performance guidelines" reference in the suggestion isn't from this repo — there's no project rule advocating lazy indexing for tiny user-type maps.

Going to leave the eager construction as-is.