Build Tools Testing Guidelines

Overview

This document describes conventions and guidelines for testing build tools, workspace analyzers, and code generators in the workspace.

Related Documentation:

tom_ai/devops/tom_build/README.md - Full Workspace Analyzer documentation

Where the entry points live: ws_analyzer.dart and ws_analyzer_all.dart are in tom_ai/devops/tom_build_cli/bin/; tom_ai/devops/tom_build/bin/workspace_analyzer.dart is the dependency-light equivalent (wa-path=, wa-include-tests). Precompiled ws_analyzer binaries are in <workspace-root>/_bin/<os>/ for linux, macos and ubuntu.

Test Project Naming Convention

zom_ Prefix

Projects and folders starting with zom_ are designated for test purposes only:

Purpose: Used to test build tools, workspace analyzers, and code generators
Exclusion: Should not be included in production builds or documentation
Examples: zom_test_standalone, zom_test_flutter, zom_test_package

Why "zom_"?

The zom_ prefix is chosen because:

1. It sorts alphabetically after all tom_ prefixed projects 2. It's visually distinct and easy to identify 3. It clearly indicates "zombie" or "test" status - projects that exist but aren't production

Workspace Analyzer Entrypoints

The workspace analyzer has two entrypoints with different default behaviors:

Entrypoint	Default Behavior	Use Case
`ws_analyzer.dart`	Excludes `zom_*` projects	Production metadata generation
`ws_analyzer_all.dart`	Includes all projects	Testing and development

Command Line Options

The ws_analyzer.dart entrypoint supports a command-line switch:

# Exclude test projects (default)
dart run bin/ws_analyzer.dart

# Include test projects
dart run bin/ws_analyzer.dart --include-tests

Creating Test Projects

When creating test projects for build tools:

1. Use the zom_ prefix: Name projects with zom_test_ followed by a descriptive name 2. Match project types: Create test projects for each supported type: - zom_test_standalone - dart_console type (bin + lib) - zom_test_flutter - flutter_app type - zom_test_package - dart_package type

3. Create test structures: Add nested folder structures to test: - Multiple parts and modules - Nested subfolders (arbitrary depth) - Various file patterns

Creating Test Projects with CLI

# Create a console/CLI project
dart create zom_test_standalone -t console

# Create a package project
dart create zom_test_package -t package

# Create a Flutter project
flutter create zom_test_flutter

Test File Organization

Place test files and structures within zom_* projects:

zom_test_standalone/
├── bin/
│   └── zom_test_standalone.dart
├── lib/
│   ├── zom_test_standalone.dart
│   └── src/
│       ├── analysis/
│       │   ├── analysis.dart
│       │   ├── parsers/
│       │   │   ├── parsers.dart
│       │   │   ├── yaml/
│       │   │   │   └── yaml_parser.dart
│       │   │   └── dart/
│       │   │       └── dart_parser.dart
│       │   └── validators/
│       │       └── validator.dart
│       └── generators/
│           ├── generators.dart
│           └── metadata_generator.dart
└── pubspec.yaml

Verification Process

After making changes to build tools:

1. Run the test analyzer: Use ws_analyzer_all.dart to include test projects 2. Verify output: Check that zom_* projects are correctly analyzed 3. Run the production analyzer: Use ws_analyzer.dart to verify exclusion 4. Compare results: Ensure the difference matches expected test project count

# Test with all projects
cd tom_ai_build
dart run bin/ws_analyzer_all.dart

# Production run (excludes zom_*)
dart run bin/ws_analyzer.dart