Skip to content

Reorganize workshop-rs internals around discoverable Workshop domains #149

Description

@Teakowa

Goal

Make the workshop-rs source tree navigable from Workshop domain ownership alone, using domain/feature first, phase second as the default internal organization principle.

A contributor looking for Action, Rule, Value, Event, Settings, or another Workshop concept should be able to find that concept's implementation and its related operations without first navigating compiler phases such as parser/emitter/validator.

Context

workshop-rs has correct ecosystem-level ownership, but its current crate root mixes several different categories at one level. Canonical model/infrastructure (wir, ids/source/error), raw Workshop text handling (lexer, parser, emitter, convert), semantic fact domains (catalog, settings, gameplay/signatures), analysis/query code (validate, semantic inspection, element counting), evidence/conformance support (census, conformance, roundtrip, live_capture, real_projects), and generator support currently coexist in a mostly flat module surface.

Some domains already have explicit module trees (catalog/, settings/, wir/) while closely related domains remain split across root-level siblings such as gameplay.rs, gameplay_data.rs, and gameplay_query.rs. At the same time, Workshop features such as actions, rules, values, and events are primarily discoverable by searching phase-oriented files rather than by following their domain ownership.

The intended structural direction is not to reproduce the same feature across separate parser/, emitter/, and analysis/ trees. Parse, validation, emission, semantic queries, and related behavior should normally live under the owning Workshop feature/domain where that improves locality. Shared infrastructure may remain outside feature modules when it is genuinely cross-cutting.

This is an internal structural/readability problem. Public API stability and semantic behavior remain separate contracts.

Scope

  • Establish a small, durable internal taxonomy based primarily on Workshop domains/features rather than compiler phases or historical extraction order.
  • Treat Workshop concepts such as actions, rules, values, events, settings, gameplay, and catalog identities as natural ownership units where they have meaningful behavior.
  • Keep operations such as parse, validate, emit, inspect/query, and layout/counting local to the owning feature when practical; split further within a feature only when the feature itself has grown enough to justify it.
  • Keep genuinely shared infrastructure explicit and separate, such as tokenization, source/span handling, WIR storage, localization/catalog resolution, diagnostics, and shared parser/emitter context.
  • Consolidate flat sibling modules that are one domain into a discoverable local module tree where doing so improves ownership locality.
  • Keep repository/test/evidence/generator support visibly separate from ordinary semantic/runtime implementation.
  • Preserve existing public Rust paths through re-exports or equivalent compatibility shims where required until the separately reviewed pre-1.0 API hardening work decides the durable public surface.
  • Keep dependency direction between internal domains explicit and avoid cycles introduced solely by reorganization.

Non-goals

  • Changing Workshop semantics, accepted syntax, WIR, settings behavior, localization, validation, emission, or observable diagnostics.
  • Redesigning the public Rust API owned by Harden the Workshop-facing Rust API for the 1.0 candidate #112.
  • Reorganizing primarily into phase-first trees such as parser/action.rs, emitter/action.rs, and analysis/action.rs while leaving one feature scattered across the repository.
  • Splitting files to satisfy line-count or module-count targets.
  • Creating one file/module per catalog entry or builtin without a cohesive behavioral reason.
  • Introducing generic manager/service/context/visitor/framework layers.
  • Moving OPY/DEL/Wright behavior into this repository.
  • Replacing appropriate bulk declarative datasets with handwritten Rust.
  • Unrelated cleanup or architecture redesign.

Acceptance criteria

  • The primary source tree communicates Workshop feature/domain ownership without requiring contributors to reconstruct compiler phases or implementation history.
  • A contributor investigating a Workshop concept can locate its parsing, validation, emission, semantic/query, or related behavior from that concept's module or a clearly documented shared boundary rather than searching multiple phase-wide buckets.
  • The resulting structure is domain/feature-first; it does not merely replace large root files with parallel phase-oriented subtrees.
  • Shared parsing/emission/validation state remains available as small orchestration/context infrastructure where genuinely needed, without becoming the semantic home of all features.
  • Closely related implementation units have one discoverable module home rather than unrelated-looking root siblings.
  • Evidence/conformance/generator support is structurally distinguishable from the normal library semantic path.
  • Existing public consumer paths remain compatible unless a public-surface change is separately approved under Harden the Workshop-facing Rust API for the 1.0 candidate #112.
  • No semantic output, diagnostics, corpus expectation, or supported behavior changes as a consequence of the reorganization.
  • Existing workspace tests, catalog checks, corpus/conformance gates, and representative consumer integrations remain regression-green.
  • The implementation does not introduce a new abstraction or dependency solely to enforce the directory layout.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions