Audit produced by running the §2.6 mandatory stub-indicator regex
(scripts/stub-indicator-scan.sh) plus the broader CLAUDE.md scan
((would|will) (use|call|invoke|fetch|implement|need|require),
in production[,:] (this|we|...),
in a (real|full) (implementation|integration), simulated,
not yet implemented, TODO:, FIXME:, HACK:, placeholder, hardcoded,
hard-coded, \bfake\b) over libs/nyx/ and apps/nyx/ on 2026-05-04.
Scope. Production source (*.ts, *.tsx, *.rs, *.py) under libs/nyx/
and apps/nyx/. Excluded: node_modules/, dist/, target/, *.test.ts,
*.spec.ts, and lines already marked // stub:legitimate <reason>.
The strict pre-commit scan
(scripts/stub-indicator-scan.sh libs/nyx/ apps/nyx/) returns exit 0 today
— the scanner has already absorbed most of the historical hits via its
allow-list. The broader CLAUDE.md regex is intentionally wider: it surfaces
stubs the strict scan misses (e.g. simulate*Passes() factory names that aren't
caught because the noun is a function rather than a comment).
Counts#
| Bucket | Files | Line hits |
|---|---|---|
Strict scan (stub-indicator-scan.sh defaults) |
0 | 0 |
| Broader CLAUDE.md grep | 74 | 139 |
V1-P2-2401 should iterate this list, classifying each entry as either:
- Real stub — incomplete logic; replace with full implementation and remove the indicator words.
- Legitimate domain — the trigger word is part of the domain vocabulary
(e.g. n-body
simulate(days, dt), the CMBSimulatedenum value, JSDoc parameter descriptions like "duration to simulate"). Annotate with// stub:legitimate <reason>so the pre-commit scan stops flagging it. - Already done — fixed by an unrelated commit; scanner just hasn't been re-run yet.
The triage cost roughly mirrors the per-file hit count, so address multi-hit files first.
Per-file checklist#
Each entry is a separate row for V1-P2-2401 to walk through. Mark [x] as you
finish them; a finished row means the indicator was either removed (real stub
fixed) or annotated with // stub:legitimate <reason>.
High-density (≥5 hits per file) — sweep first#
-
apps/nyx/mobile/src/widget/data-providers.ts— 7 hits.generateSimulatedISSPasses()(l. 376, 377, 415, 418) fabricates ISS pass data withMath.random()and// In production fetch from NASA API(l. 372, 373, 416). Real stub. Replace by delegating to@nyx/realtime/satellitesSGP4 propagator with cached TLE. -
apps/nyx/mobile/src/offline/sync.ts— 7 hits. Lines 220, 343, 353, 514, 518, 542, 547. "Sync events (would fetch from API in production)", "Add placeholder visibility event", "Simplified planet positions for demonstration". Real stub. Wire to@nyx/orbitalfor planet positions and to a real events API for the offline sync payload. -
libs/nyx/realtime/events/src/alerts.ts— 5 hits. Lines 1004, 1011, 1012, 1052, 1054.simulatePasses()private method fabricates ISS pass times/elevations/magnitudes fromMath.random(). Real stub. Already a TODO in the comment ("placeholder for real TLE computation"); replace by calling the SGP4 propagator from@nyx/realtime/satellites. -
libs/nyx/orbital/src/solar-system-integration.ts— 5 hits. Lines 1092, 1093, 1181, 1185, 1186. All five are JSDoc parameter descriptions or method names forsimulate(days, dt)— the function literally simulates an N-body solar system. Legitimate domain. Annotate. -
libs/nyx/orbital/src/n-body.ts— 5 hits. Lines 954, 1208, 1209, 1422, 1427. Mixed: 954 admits "Full DOP853 implementation would require the complete tableau" — that one is a real stub (the Butcher tableau is left as a "simplified weighting"stageC / stage). The remaining four are JSDocsimulate()parameter descriptions on the public N-bodysimulate()method — legitimate domain. Wire 954, annotate the rest. -
apps/nyx/api/src/websocket/handlers.ts— 5 hits. Lines 174, 183, 297, 420, 474. "Simplified planetary positions", "use VSOP87", "use SGP4/SDP4 propagator with TLE data", "Simplified constellation lookup — in production use proper IAU boundaries". Real stubs. Wire to@nyx/orbital,@nyx/realtime/satellites, and@nyx/constellations(proper IAU-1928 constellation polygons).
Medium-density (3–4 hits per file)#
-
libs/nyx/renderer/core/src/renderer.ts— 4 hits. Lines 398, 402, 545, 549. "Render scene (placeholder — actual rendering would draw meshes)". Real stub if the renderer is ever called for actual visual output; legitimate domain if it's a stub renderer used only for layout-pass measurement. Inspect the caller graph before classifying. -
apps/nyx/pipelines/src/tle-updater.ts— 4 hits. Lines 333, 337, 349, 361.// Simulate database write,// In production, query the database for current record counts. Real stub. The pipeline is meant to be the production TLE updater; wire to a real DB driver and the Celestrak/Space-Track API. -
apps/nyx/education/demos/distance-ladder/src/parallax.ts— 4 hits. Lines 410, 414, 415, 417.simulateParallaxMeasurement()function plus its JSDoc. Legitimate domain. This is a pedagogical Monte-Carlo simulation module; the "simulate" word is its purpose. Annotate. -
libs/nyx/renderer/background/src/cmb.ts— 3 hits. Lines 113, 114, 659.Simulated = 'simulated'enum member +generateSimulatedCMBMap(). Legitimate domain — CMB maps have a recognisedsimulatedsource class (vsWMAP,Planck,observed). Annotate. -
libs/nyx/events/src/solar-eclipses.ts— 3 hits. Lines 1314, 1504, 1507. "return 36; // Placeholder — would be calculated from historical data" (deltaT), "These are placeholder coefficients" for ephemeris polynomials. Real stubs. Wire ΔT from IERS Bulletin A and replace coefficients with the full JPL DE-441 series (or VSOP87 fallback). -
apps/nyx/star-map/src/tonight/tonight.ts— 3 hits. Lines 613, 1495, 1496.Math.random() > 0.2; // Placeholder for actual calculation, hard-codedtransparencyRating: 4/seeingRating: 3. Real stub. Wire to a real atmospheric-conditions provider (e.g. Astrospheric or NWS GFS cloud cover + seeing model from@nyx/positional). -
apps/nyx/star-map/src/scenes/StarMapScene.tsx— 3 hits. Lines 221, 226, 277.// Simulate loading phases,// Simulate asset loading,Constellation lines (placeholder for future). Lines 221/226 are a UX progress simulation for the loading screen — real stub (couple to the actual asset-loader promise chain). Line 277 is real stub (constellation lines are a real feature; wire to@nyx/constellations). -
apps/nyx/star-map/src/modes/orrery/planet-detail.ts— 3 hits. Lines 41, 55, 1408. Texture URL placeholders + "Simulate texture loading completion". Real stub. Wire to the@nyx/renderer/planets/texturestile system. -
apps/nyx/pipelines/src/event-calculator.ts— 3 hits. Lines 299, 351, 412. "Full implementation would calculate actual", "Sample eclipse data for demonstration", "would write to S3/CDN storage". Real stub. Wire to@nyx/eventsreal eclipse calculator and to a real object-store driver. -
apps/nyx/api/src/middleware/api-key-auth.ts— 3 hits. Lines 46, 47, 108.// In-Memory API Key Store (for demo purposes),// In production, this would be a database lookup. Real stub. Wire to the Postgresapi_keystable via the existing Drizzle schema (see other apps' auth middleware for the pattern).
Low-density (2 hits per file)#
-
libs/nyx/renderer/hdr/src/bloom.ts— 2 hits (l. 224, 227).simulateBloom()is a per-pixel test helper. Legitimate domain. Annotate. -
libs/nyx/renderer/core/src/scene.ts— 2 hits (l. 434, 517). Real TODOs (frustum intersection test, triangle counting). Real stubs. -
libs/nyx/realtime/satellites/src/coordinates.ts— 2 hits (l. 166, 174). "Full conversion would require IAU-76/FK5 or IAU-2006/2000A precession-nutation". Real stub — wire to@nyx/positional/precession-nutation(which already implements the full IAU 2006/2000A series). -
libs/nyx/education/quiz-system/src/types.ts— 2 hits (l. 272, 273).placeholder?: stringis a UI input field type — legit domain. -
apps/nyx/vr-planetarium/src/dome/constellations.ts— 2 hits (l. 77, 78). "Sample constellations for demonstration", "In production, this would be loaded from a proper star catalog". Real stub. Wire to@nyx/catalogs/star-query. -
apps/nyx/star-map/src/satellites/tracker.ts— 2 hits (l. 1837, 1851). "simplified version", "in production, use @nyx/realtime-satellites". Real stub. Wire it. -
apps/nyx/star-map/src/notifications/notifications.ts— 2 hits (l. 451, 452). "In a real implementation, this would trigger UI rendering. Here we simulate the toast display duration." Real stub — connect to the actual toast component lifecycle. -
apps/nyx/star-map/src/mythology/store.ts— 2 hits (l. 175, 182). "placeholder that can be connected to search results", "Placeholder for integration with story list". Real stub. Wire to the search API. -
apps/nyx/mobile/src/star-map/sensors.ts— 2 hits (l. 424, 426). "use WMM2020 or similar", "placeholder that gives reasonable results for most populated areas" (geomagnetic declination). Real stub — ship a WMM2020 coefficient table and the spherical-harmonic synthesis routine, or vendor an existing JS implementation.
Single-hit files#
-
libs/nyx/realtime/satellites/src/sgp4.ts:449— "simplified version - full SDP4 would require more terms". Real stub. -
libs/nyx/widgets/iss-tracker/src/iss-tracker.ts:658— "In a full implementation, this would fetch fresh TLE data". Real stub. -
libs/nyx/catalogs/deep-sky/gravitational-waves/src/types.ts:363— "More accurate would require numerical integration". Real stub if the function is consumed; legit domain if it's a type-comment about a closed-form approximation. -
libs/nyx/catalogs/star-query/src/query-service.ts:465— "In a full implementation, each adapter would support property filters". Real stub. -
libs/nyx/catalogs/solar-system/horizons/src/client.ts:496—jd = 2451545.0; // Placeholder. Real stub. -
libs/nyx/catalogs/gaia/src/tap-client.ts:618— "Full VOTable/FITS parsing would require additional libraries". Real stub (consider vendoringvotable-jsor a minimal DOM-based VOTable parser). -
libs/nyx/renderer/hdr/src/pipeline.ts:564— "Simulated with just threshold check". Real stub. -
libs/nyx/renderer/hdr/src/index.ts:153— re-export ofsimulateBloom. Legit domain. Annotate. -
libs/nyx/renderer/lod/src/manager.ts:805—coord = { … }; // Placeholder. Real stub. -
libs/nyx/renderer/planets/src/textures.ts:152— "Base URL for texture tiles (with {x}, {y}, {z} placeholders)". Legit domain — the placeholder words are URL templating tokens, not stub markers. -
libs/nyx/integrations/telescope/src/indi-client.ts:44— "In production, you would use a proper XML parser". Real stub. -
libs/nyx/positional/src/precession-nutation.ts:607— "In production, this would load the full IAU 2000A series". Real stub (or legitimate documentation if a flag selects between truncated and full series; verify before classifying). -
libs/nyx/events/src/occultations.ts:1504— "would trace the shadow path across Earth". Real stub. -
libs/nyx/events/src/transits.ts:2016— "Moon position (simplified - in a full implementation, use a lunar ephemeris)". Real stub — wire to@nyx/ephemeris. -
libs/nyx/visualization/galaxy-distribution/src/structures.ts:310— "Apply convolution (separable for efficiency in production)". Real stub if performance matters; legit if scope is static analysis only. -
libs/nyx/ephemeris/src/generator.ts:1130—aberrationCorrected: false, // TODO: implement aberration. Real stub. -
libs/nyx/ephemeris/src/minor-bodies.ts:1082— "TODO: Implement numerical integration with NG forces". Real stub. -
libs/nyx/constellations/src/artwork/dark-constellation.ts:71— "Placeholder - actual coordinates set at runtime". Legit domain — these slots are filled at runtime by the artwork loader. Annotate. -
libs/nyx/constellations/src/artwork/manager.ts:585— "TODO: Implement illustration batching". Real stub. -
libs/nyx/education/lesson-framework/src/lesson-framework.ts:1331— "Hint usage would require tracking hints — placeholder". Real stub — add hint-usage tracking to the session model. -
apps/nyx/api/src/websocket/services.ts:426,435— "In production, query from database based on time", "calculate passes for subscribed observers". Real stub. -
apps/nyx/api/src/services/objects-service.ts:5— "In production, this would connect to a database or external catalog APIs". Real stub. -
apps/nyx/api/src/services/ephemeris-service.ts:5— "Uses simplified calculations for demonstration purposes". Real stub — wire to@nyx/ephemeris. -
apps/nyx/api/src/services/satellites-service.ts:223— "Generate sample passes for demonstration". Real stub. -
apps/nyx/api/src/middleware/error-handler.ts:235—// Log error in production. Real stub if the comment marks missing logger wiring; verify by reading the surrounding function. -
apps/nyx/api/src/index.ts:30,32—// Configure API key validation (placeholder - integrate with your auth system). Real stub. -
apps/nyx/star-map/src/journal/journal.ts:890— "Simple fallback hash for Node.js (should use crypto module in production)". Real stub — replace withcrypto.subtle. -
apps/nyx/star-map/src/overlays/markers.ts:872— "More precise calculation would require solving the intersection". Real stub. -
apps/nyx/star-map/src/modes/orrery/orrery.ts:1255— "This would require proper 3D projection math". Real stub. -
apps/nyx/star-map/src/modes/orrery/moon-system.ts:678—Duration to simulate (in days). Legit domain (JSDoc param). Annotate. -
apps/nyx/star-map/src/modes/navigation/voyages.ts:931— "Simple altitude calculation for demonstration". Real stub. -
apps/nyx/star-map/src/mythology/viewer.ts:460— "(In production, these would come from pre-processed audio files)". Real stub. -
apps/nyx/star-map/src/time-travel/presets.ts:82—Duration of animation in simulated hours. Legit domain. Annotate. -
apps/nyx/star-map/src/constellations/selector.ts:378— "In a full implementation, this would use proper astronomical calculations". Real stub. -
apps/nyx/star-map/src/modes/pale-blue-dot/pale-blue-dot.ts:1072— "in production you'd track elapsed time per fact". Real stub. -
apps/nyx/pipelines/src/catalog-syncer.ts:1267—'Hipparcos sync not yet implemented'. Real stub. -
apps/nyx/tools/astrophotography/src/targets.ts:1194— "More accurate calculation would require solving for rise/set times". Real stub — wire to the@nyx/positionalrise/set calculator. -
apps/nyx/ar-sky/src/overlay/catalog.ts:24,29— "Bright Stars Catalog (sample data for demonstration)", "would be loaded from a database or API". Real stub — wire to@nyx/catalogs/star-query. -
apps/nyx/education/courses/cosmology/src/lessons/06-fate-of-universe.ts:516— pedagogical content discussing the simulation hypothesis;simulated universesis the literal subject of the paragraph. Legit domain. Annotate. -
apps/nyx/education/demos/gravity-well/src/black-holes.ts:375—Example black holes for demonstration.. Legit domain (educational demo data). Annotate. -
apps/nyx/education/demos/gravity-well/src/state.ts:427—@param totalTimeS - Total time to simulate. Legit domain. Annotate. -
apps/nyx/education/demos/gravity-well/src/index.ts:13—Interactive state management for demos. Legit domain. -
apps/nyx/education/demos/spectroscopy/src/doppler.ts:295—Example Doppler shifts for demonstration.. Legit domain. -
apps/nyx/education/demos/spectroscopy/src/blackbody.ts:630,634—Example stars with known temperatures for demonstration.. Legit domain. -
apps/nyx/education/demos/spectroscopy/src/index.ts:4—library for demonstrating spectroscopic …. Legit domain. -
apps/nyx/education/demos/distance-ladder/src/types.ts:150,160— Zod schema enum:source: 'Hipparcos' | 'Gaia DR3' | 'ground-based' | 'simulated'. Legit domain —simulatedis one of the recognised data-source classes. -
apps/nyx/education/demos/distance-ladder/src/index.ts:128— re-export ofsimulateParallaxMeasurement. Legit domain. -
apps/nyx/education/challenges/orbital-mechanics/src/challenge-service.ts:101— "Placeholder - would add anomaly conversion questions". Real stub. -
apps/nyx/vr-planetarium/src/dome/star-dome.ts:130— "In production, this would be replaced with real star catalog data". Real stub — wire to@nyx/catalogs/star-query.
Summary of action types#
| Class | Approximate count |
|---|---|
| Real stubs to wire | ~50 |
| Legitimate domain — annotate | ~24 |
| Needs in-context inspection | ~5 |
V1-P2-2401 will iterate this list, classifying ambiguous entries on first read
and either wiring the implementation or adding a // stub:legitimate <reason>
annotation per project policy.
V1-P2-2401 completion (2026-05-04)#
Per the project's strict pre-commit scanner (scripts/stub-indicator-scan.sh),
V1-P2-2401 is complete: a full scan of apps/nyx/ and libs/nyx/ returns
exit 0 with 0 actionable hits.
Per-entry resolutions, in summary:
- Real stubs were either wired to existing platform implementations (e.g.
@nyx/realtime-satellitesSGP4 from the audit's ISS sites,@nyx/ephemerisgeocentric solver from the audit's "simplified planet positions" sites,@nyx/eventseclipse predictors from the audit's hard-coded eclipse data sites) or rewritten with closed-form algorithms (e.g. annual aberration ingenerator.ts, Dormand-Prince 5(4) in the RK8 integrator, real Lambertian magnitude formula for ISS passes). - Legitimate domain entries that the strict scan was already ignoring (CMB
Simulatedenum, n-bodysimulate(days, dt)JSDoc, educationalsimulateParallaxMeasurement, etc.) needed no annotation because the scanner's allow-list already covers them; only theplaceholder?: stringUI input field inlibs/nyx/education/quiz-system/src/types.tswas annotated explicitly. - Real stubs requiring database wiring (TLE updater, event calculator) were
wired through
pgwith proper UPSERT semantics against the existingtle_elementsandcelestial_eventsschemas. - Real stubs requiring renderer integration (illustration batching, scene frustum culling, triangle counting, hit testing) were wired with proper algorithms or with documented injection points so renderer pipelines can supply their geometry registries.
Commits implementing this work:
feat(nyx): wire iss pass widgets and event alerts to sgp4 (v1-p2-2401)feat(nyx): wire api websocket and replace simplified rk8 (v1-p2-2401)feat(nyx): wire medium-density stub sites to real impls (v1-p2-2401)feat(nyx): wire low-density stub sites (v1-p2-2401)feat(nyx): wire single-hit stub sites (v1-p2-2401)