Enforce Rules For Typescript

Enforce AIRI TypeScript Rules

Apply these rules to every TypeScript and Vue source change in AIRI. The root AGENTS.md gives the core code rules. This skill gives the detailed rules.

Imports and Types

• Import types from the module or package that owns the contract. Do not redeclare an external or public contract locally to use a narrower subset.
• Do not route type imports through local runtime assembly modules when the original side-effect-free type source is available.
• If Node-only and browser-only types mix in one import chain, move the type declarations into a neutral type file. Keep the runtime modules environment-specific.
• Do not import values from a module that has side effects only to get its types.
• If a wrong or missing export causes an error, trace the full import chain and side-effect chain first. Fix the package exports or the owning boundary. Do not add a local workaround import at the leaf.
• Before you fix an import or type error, examine the compilation behavior and the type declarations. Also examine the exports field in package.json, and the browser and Node entry points of the dependency.
• Keep JSON Schemas compliant with providers. Give an explicit type: object and the required fields. Do not use unbounded records.

Naming

• Let module boundaries provide context. Do not repeat package, product, protocol, or transport names in symbols. The exception is a symbol that crosses a boundary where that context is otherwise lost.
• Name functions after domain operations, not implementation layers.
• Use nouns for resolved domain concepts. Use verbs for transformations and side effects.
• If a symbol needs several ownership qualifiers to be clear, reconsider the module boundary or introduce a clearer domain concept.

Comments

• Write a comment only for information that the code cannot express clearly: intent, constraints, ownership, invariants, precedence, lifecycle, ordering, side effects, protocol shape, or non-obvious fallbacks.
• Do not add comments that only restate names, types, or visible operations.
• Treat a contract comment as an explanation of the relationship between a producer and its consumers.
• Explain why a value exists in the system before you explain how the code represents it.
• Describe the decision, behavior, or invariant that a value controls.
• If different values select different control-flow or UI paths, describe each observable outcome.
• If a value crosses a module or component boundary, identify the consumer and how it applies the value.
• Put representation details after behavior: units, coordinate systems, thresholds, clamps, and source API fields.
• Put background evidence after the contract: browser behavior, issue links, investigation history, and removal conditions.
• If the name, type, and surrounding code express the full contract, omit the comment.
• Put an implementation comment next to the branch, calculation, transition, or side effect that it explains.
• In calculation-heavy code, explain non-obvious coordinate systems, units, conversions, clamps, rounding, aggregation, and precedence. Put each explanation next to the related intermediate value or branch.
• Prefer clearer names, types, and structured state over comments that compensate for hidden or encoded concepts.
• When you move code, keep the accurate comments. Remove the comments that no longer describe current behavior.
• Write an investigation-heavy comment as short paragraphs. When useful, give the context and the observed failure. Then give the reason that the obvious fix is not sufficient. Give the chosen fix and its removal condition or references.
• Use these markers:
  • // TODO: for follow-up work.
  • // REVIEW: for a concern that needs another opinion.
  • // NOTICE: for workarounds, magic values, external constraints, and other important non-obvious context. The root AGENTS.md gives the required format for a workaround.

JSDoc

• Use JSDoc for public APIs, package-level exports, shared architectural boundaries, and non-trivial exported functions, classes, and types.

• In JSDoc, document only the contract details that the signature cannot express: assumptions, side effects, lifecycle, and return guarantees.

• Do not export a helper only to satisfy tests or documentation rules. Keep implementation helpers private unless production code reuses them.

• Do not add JSDoc to trivial helpers, local projections, or pass-through functions.

• Do not use fixed section templates that restate names and signatures. Prefer precise names and branch-local comments for implementation details.

• For exported test helpers or non-obvious reusable test fixtures, add @example when it clarifies the intended usage.

• Do not attach JSDoc or @example blocks to ordinary describe, it, or expect* calls.

• For exported interfaces and type aliases, keep the top-level JSDoc on what the type represents. Put detailed semantics on the related fields.

• Document generic parameters with @param. Add @default to every option that has a default value.

• Give each runner and CLI entry point /** ... */ JSDoc with a clear ASCII call-stack diagram. Use {@link ...} references where applicable.

• For a server orchestrator, add a call-stack diagram only when it clarifies a stable architecture boundary. Do not add diagrams to shallow glue code.

• Use this format for the call-stack section:

  /**
   * ...
   *
   * Call stack:
   *
   * collectEvalEntries (../runner)
   *   -> {@link createRunnerSchedule}
   *     -> {@link createMatrixCombinations}
   *       -> {@link VievalScheduledTask}[]
   */

• Give /** ... */ JSDoc with an @example to each exported normalizer, shared normalizer, and non-obvious local normalizer. This applies to normalizers of outputs, formats, file names, and values. It does not apply to config default normalization.

• In the example, show a representative input and output. Use this format:

  /**
   * Normalizes <target>.
   *
   * @example
   * normalizeTarget('ExampleInput')
   * // => 'example-output'
   */

Fallbacks and Precedence

• If a fallback chain has more than two sources, make the precedence explicit.
• Some fallback sources represent different schema versions, compatibility behavior, specificity levels, or user and system overrides. For these sources, explain why each non-primary branch exists and why it has that priority.
• Do not use nested ternaries for a fallback chain when any branch is non-obvious. Use named intermediate variables or if / else if blocks, so that each comment can be next to its branch.
• Do not use a new object or array as a casual fallback. Expressions such as value ?? {}, value ?? [], value || {}, and value || [] create a new reference each time.
• Never use an inline object or array fallback in a reactive getter, computed value, watcher source, or Pinia state projection. New references can cause false changes, watcher loops, and state broadcasts.
• If an immutable empty fallback is valid, reuse a stable module-level value. If consumers must not mutate the value, freeze it.
• Use ?? only when null and undefined mean that a value is missing. Use || only when false, 0, and an empty string must also select the fallback.
• In non-trivial domain or protocol code, a fallback can return an empty string, stale value, cached value, default value, or ignored result. At that return or branch site, explain why the fallback is safe.
• The root AGENTS.md gives the rules for backward-compatibility fallbacks.