SuperAPI AI Directory

devtools-model-management

Coding & development

View repository

Updated 11-06 18:11

About this skill

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.
    • ./dt 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 TypeScript dependencies (ts_deps). Non-TypeScript dependencies (e.g. CSS, assets) go into 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: ts_deps = [ ":<model_name>" ].
  3. ts_library("unittests"): Lists test files and test-only dependencies.
    • Crucial: Must depend on the bundle: ts_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: ./dt lint (Checks style and formatting).
  3. Test:
    • ./dt test front_end/models/<model_name> (New tests).
    • ./dt 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.