analytics_gen

Features

• Studio remembers your project file — after a reload the Studio reconnects to the last opened analytics-studio.json (Chrome/Edge, via the File System Access API) and remembers the file name on every browser, so you no longer re-open it each session. Save writes straight back to the same file; data is auto-saved locally regardless.
• Project identity & content revision for CI/CD — saved and generated analytics-studio.json now carries a meta block with a stable projectId, an optional name, and a content revision hash. The revision is deterministic and timestamp-free, so CI can compare project files across commits to detect analytics changes. The Dart studio target emits the same meta and preserves projectId across regenerations.
• Customizable / unique export names — set a project name (drives both the .json and ZIP file names) and optionally append the content-revision hash for unique CI-artifact names, via the new "Project…" dialog (which also shows the project ID and revision).
• External-change detection — when analytics-studio.json changes on disk (an external edit, a git pull, a CI regeneration), the Studio offers to reload it instead of silently diverging (Chrome/Edge).

Internals

• Shared cross-language revision hash (cyrb53 over canonical, key-sorted JSON) implemented in both the Studio (project-meta.ts) and the Dart generator (project_revision.dart), locked by a parity test so a studio-saved and a CI-generated file agree for identical content.

Features

• Studio export as a first-class generation target — added targets.studio (with outputs.studio path) to analytics_gen.yaml. The Studio project file is now produced by the main pipeline alongside Dart code, docs, and exports.
• --studio CLI flag for dart run analytics_gen:generate. CLI flags follow the same precedence as --docs / --exports: explicit flag wins over config, with --no-studio to disable.
• Flat aliases generate_studio and studio_path are accepted at the root of the config for parity with other targets.

Fixes

• Studio now normalizes events when loading a project file — events without a parameters block (allowed by schema) no longer crash the import. YAML and JSON import paths share the same normalization logic.

Internals

• Extracted studio export logic into StudioGenerator so the standalone analytics_gen:studio_export binary and the main pipeline use the same zero-knowledge YAML reader.

Features

• Analytics Gen Studio — web-based visual editor for analytics configuration, events, shared parameters, and contexts with real-time YAML preview.
• Schema as Single Source of Truth — JSON schemas in schema/ now drive everything: Studio UI, TypeScript types, YAML templates, and documentation.
• Schema-driven generation — YAML templates, schema reference docs, and Studio TypeScript types are all auto-generated from JSON schemas.
• Studio features: search/filter in event tree, keyboard shortcuts (Ctrl+S/O), notifications, compact array inputs, validation error badges on tabs, confirm dialogs for all deletions, auto-fill context name from filename.

Architecture

• Studio renders all forms dynamically from JSON schemas — no hardcoded data.
• TypeScript types auto-generated from schemas.
• YAML templates and schema reference docs auto-generated from schemas.
• All YAML field names centralized via constants — no raw string literals in parsers.

Features

• Added boolean as an alias for bool type across type mapping, parsing, and documentation generation.
• Added automatic tracking creation date injection via a new ledger file and meta.auto_tracking_creation_date config option.
  • When enabled, the generator maintains a .analytics_tracking.json ledger file that records an ISO 8601 timestamp (yyyy-MM-ddTHH:mm:ss) when each event is first seen.
  • The tracking_creation_date value is automatically injected into each event's meta field during generation.
  • Existing entries are never overwritten — the ledger preserves the original creation timestamp.
  • The ledger file is placed next to analytics_gen.yaml and should be committed to version control.
• Added meta.include_meta_in_parameters config option to include event meta fields in the generated eventParameters map sent to analytics providers (e.g. Amplitude, Mixpanel). Default: false.

Features

• Added dartReservedWords to StringUtil to prevent enum member name collisions with Dart keywords.

Features

• Export generated events from the analytics class renderer for easier access

Bug Fixes

• Fixed NamingStrategy._toTitleCase stripping structural punctuation (e.g. :) from event_name_template. Previously, using casing: title_case with a template like "{domain}: {event}" produced "Chat Under Dev Sheet Shown" instead of "Chat: Under Dev Sheet Shown". Only _ and - are now treated as word boundaries.

• Added templates/analytics_gen.yaml as a reference for all configuration options.
• Added templates/events.yaml demonstrating event and parameter definitions.
• Update README to enhance clarity and structure of analytics_gen documentation.
• Add onboarding and AI prompt guides to documentation; enhance README with new links.

v1.0.4

• Introduced CapabilityProviderBase to replace CapabilityProviderMixin (deprecated).
• Added --metrics flag to track generation performance.
• Added "Dead Event" Audit Enhancement with git commit info.
• Glob Pattern Support: EventLoader now supports glob patterns (e.g., events/**/*.yaml).
• Improved Fingerprint Sensitivity: covers all event/parameter fields.
• Cross-Platform Robustness: Normalized path handling for Windows/macOS/Linux.
• Added doc/PERFORMANCE.md, doc/TROUBLESHOOTING.md, doc/TESTING.md.

What's Changed

• Feature/v1.0.1 by @yelmuratoff in #6
• v1.0.4 by @yelmuratoff in #7

Full Changelog: v1.0.1...v1.0.4

Features

• Added "Dead Event" Audit Command (dart run analytics_gen:audit).
• Added test_matchers target to generate typed package:test matchers.
• Added dart_type parameter option to map parameters to existing Dart types.
• Added imports configuration for including external types.
• Added configurable event naming strategy (casing: snake_case, title_case, original).

Improvements

• Generated code now uses const maps for constant event parameters.
• Removed auto-generated tests in favor of test_matchers.

• Enhanced SQL/CSV/JSON export formats with additional metadata.
• Formalized analytics data representation with AnalyticsParameter and AnalyticsDomain models.
• Conditionally generate Flutter or Dart test imports based on project type.

[1.0.1]

• Enhance SQL generator with additional event and parameter metadata, sorting, and utility functions for improved data representation.
• Update analytics CSV and JSON export formats with new event metadata fields and improved structure.
• Delete ParameterParser and its tests, consolidating parameter parsing logic into shared components.
• Formalize analytics data representation with dedicated AnalyticsParameter and AnalyticsDomain models.
• Conditionally generate Flutter or Dart test imports based on project type.

Full Changelog: v1.0.0...v1.0.1

[1.0.0]

• Add new documentation files and configure pubspec for API reference links and dartdoc inclusion.

Full Changelog: v0.2.1...v1.0.0

[0.2.1] - 2025-11-21

Breaking Changes

• Configuration Structure Update: The analytics_gen.yaml file has been completely restructured into logical groups (inputs, outputs, targets, rules) to improve readability and organization.
  • Migration Guide:

    # Old (v0.2.0)
    analytics_gen:
      events_path: events
      output_path: lib/src/analytics
      docs_path: docs/analytics.md
      generate_docs: true
      strict_event_names: true
      event_parameters_path: events/shared.yaml
    
    # New (v0.2.1)
    analytics_gen:
      inputs:
        events: events
        shared_parameters:
          - events/shared.yaml
      outputs:
        dart: lib/src/analytics
        docs: docs/analytics.md
      targets:
        docs: true
      rules:
        strict_event_names: true

  • Note: The old flat structure is deprecated but may still work for some fields during a transition period, though migration is strongly recommended. event_parameters_path is strictly removed in favor of inputs.shared_parameters.

Highlights

• Improved error reporting, validation, and generated code ergonomics.
• Better CSV/exports, optional PII scrubbing, and safer enum generation for parameter values.
• Added telemetry hooks and testing helpers (e.g., Analytics.reset()).

Documentation & DX

• Clarified BatchingAnalytics.flush() behavior and updated README guidance.
• Added CI example for plan validation in doc/VALIDATION.md.

Key Additions

• Shared Event Parameters: Support for centrally defined parameters via shared_parameters.
  • Reuse parameters across events by referencing them (or leaving value as null).
  • Enforce consistency with enforce_centrally_defined_parameters.
  • Prevent duplicates with prevent_event_parameter_duplicates.
• Enhanced CSV export (multiple files, better escaping).
• Parameter validation DSL: regex, min_length, max_length, min, max with runtime checks.
• PII scrubbing support (PiiRenderer + Analytics.sanitizeParams).
• Enum generation for parameters with allowed_values.

Internal Improvements

• BaseRenderer to share common rendering logic across generators.
• Generation telemetry (GenerationTelemetry + implementations) integrated into CodeGenerator.
• Validator separation: SchemaValidator extracted from YamlParser with tests.
• YamlParser refactored to use loadYamlNode and enforces strict event-name rules.

Misc

• Added ignore_for_file lints and generation timestamp to generated files.
• Analytics.reset() for testing and hot-restart scenarios.

Full Changelog: v0.2.0...v0.2.1

[0.2.0] - 2025-11-20

• Updates:
  • Optimized generator performance with parallel processing and smart I/O.
  • Stable API supporting both Dependency Injection and Singleton patterns.
• Major Features:
  • Extensible Metadata: Support for arbitrary key-value pairs (meta) in YAML, propagated to code and exports.
  • Batching & Async: Added BatchingAnalytics for buffering events and AsyncAnalyticsAdapter for heavy providers.
  • Flexible Naming: Configurable naming strategies for domains, events, and parameters.
  • Strict Mode: Added strict_event_names to prevent high-cardinality anti-patterns.
• Developer Experience:
  • Improved Error Reporting: Aggregated validation errors for faster debugging.
  • Performance: Parallelized generation and incremental file writes.
  • Documentation: Added migration guides, scalability benchmarks, and onboarding checklists.
• Quality Assurance:
  • Full test coverage (100%).
  • Stricter linting rules and CI guardrails.

Full Changelog: v1.0.6...v0.2.0

• Add include_event_description config option to optionally include an
  event's description property inside the emitted logger.logEvent
  parameters map. This flag defaults to false to preserve existing
  behavior; enable it via analytics_gen.yaml (key: include_event_description).
  • The code generator now inserts a 'description' key for events that
    have a non-empty description when the flag is enabled.
  • The example config and README.md were updated to document this flag.
  • Unit tests assert that descriptions are properly included when enabled
    and omitted otherwise.
• Support interpolated placeholders in custom event_name strings
  • You can now include parameter placeholders in event_name using
    {parameter_name} and the code generator will replace them with
    Dart string interpolation in generated methods (for example,
    "Screen: {screen_name}" → "Screen: ${screenName}").
  • The raw event_name still appears unchanged in docs/exports so
    metadata remains stable across teams and exports.
  • If a placeholder doesn't match a parameter, it is preserved as-is
    (no silent mutations), so designs and engineers can detect typos
    or handle advanced use cases explicitly.

• Full test coverage.
• Added GitHub Actions CI.

Features

• Added CLI flags: --validate-only, --watch, --verbose, --plan.
• MultiProviderAnalytics with error isolation and onProviderFailure hook.
• Event deprecation lifecycle with deprecated + replacement.
• allowed_values for parameters with runtime validation.
• Deterministic fingerprints in exports (no timestamps).

Improvements

• Stricter YAML parser with better error messages.
• RecordedAnalyticsEvent for typed mock assertions.

• Fix badge issues.

• Refactor string interpolation in code generation.

• Minor updates and fixes.

• Minor updates and fixes.

• Initial release.