devtools-model-management

name	devtools-model-management
description	Guidelines for creating, migrating, and registering models in front_end/models/. Covers BUILD.gn, devtools_grd_files.gni, and entrypoints.

Creating or Migrating a Model in DevTools

This guide outlines the standard procedure for creating a new model or migrating an existing one to front_end/models/.

0. Preparation (Before you start)

• Baseline: Run existing tests for the code you are moving to ensure they pass before you touch anything.
  • npm run test -- front_end/<old_location>
• Impact Analysis: Search for usages of the class/file to understand the scope of refactoring.
  • grep -r "ClassName" front_end/

1. File Structure

• Location: front_end/models/<model_name>/ (must be lowercase).
• Entrypoint: Create a barrel file front_end/models/<model_name>/<model_name>.ts that exports the model's public API.
• Implementation: The actual logic goes in <ClassName>.ts.
• Tests: Unit tests go in <ClassName>.test.ts alongside the implementation.

2. Build Configuration (BUILD.gn)

Every model requires a BUILD.gn file in its directory with three specific targets:

1. devtools_module("<model_name>"): Lists implementation source files (sources) and dependencies (deps).
   • Crucial: Do NOT include the barrel file (<model_name>.ts) in sources.
2. devtools_entrypoint("bundle"): Defines the barrel file (entrypoint = "<model_name>.ts").
   • Crucial: Must depend on the module target: deps = [ ":<model_name>" ].
3. ts_library("unittests"): Lists test files and test-only dependencies.
   • Crucial: Must depend on the bundle: deps = [ ":bundle" ].

3. Global Registration (Crucial)

The build system does not auto-detect new modules. You must manually register them in config/gni/devtools_grd_files.gni:

• Bundled (Release) Build: Add the new barrel file path (e.g., front_end/models/<model_name>/<model_name>.js) to the grd_files_bundled_sources list.
• Unbundled (Debug) Build: Add all other implementation files (e.g., front_end/models/<model_name>/<ClassName>.js) to the grd_files_unbundled_sources list.
• Test Runner: Add the new model's unittest target (e.g., models/<model_name>:unittests) to the deps list in front_end/BUILD.gn.

4. Refactoring Imports & Exports

• Consumers: Update all files importing the model to use the new entrypoint: import * as ModelName from '../../models/<model_name>/<model_name>.js';
• Old Barrel File (Migration only): If moving a file, remove its export from the original directory's barrel file (e.g., front_end/panels/elements/elements.ts).
• Internal Imports: Files within the model directory must import each other via relative paths (e.g., ./OtherClass.js), never via the model's own barrel file.

5. Verification Checklist

1. Build: autoninja -C out/Default (Ensures BUILD.gn and GRD files are correct).
2. Lint: npm run lint (Checks style and formatting).
3. Test:
   • npm run test -- front_end/models/<model_name> (New tests).
   • npm run test -- front_end/<old_location> (Regression check for previous owner).

Common Pitfalls

• Circular Dependencies: Occur when internal files import from the directory's own barrel file.
• Missing Tests: Failing to add the target to front_end/BUILD.gn means tests exist but never run.
• Legacy Exports: Forgetting to remove the class from the old location's files or exports allows old patterns to persist.
• Build Errors: Including the barrel file in devtools_module sources causes duplicate definition errors.