state-machine-cat copilot-instructions.md

GitHub Copilot Instructions for state-machine-cat

These instructions guide GitHub Copilot on how to generate and modify code for the state-machine-cat project.

Core Concepts

State Machine Cat is a tool for visualizing state charts. It parses state machine descriptions and renders them as diagrams.

Code Structure & Conventions

• TypeScript/ESM Module System: Use .mts file extension for TypeScript files

• Import Style:

  • Use import { x } from "node:module"; for Node.js built-ins
  • Use import x from "#subfolder/module.mjs"; for internal imports (using the # prefix)
  • Use import type { IType } from "#types/file.mjs"; for types

• Formatting:

  • Use double quotes for strings
  • Use semicolons at statement ends
  • Use trailing commas in multi-line expressions

• TypeScript: Use strict typing with TypeScript interfaces prefixed with I (e.g., IStateMachine)

Writing Tests

Tests must be created for all new functionality using Mocha and Node's assert module.

Test Structure

import { deepEqual, equal, throws } from "node:assert/strict";
import myFunction from "#my-module.mjs";

describe("my feature", () => {
  it("should do something specific", () => {
    equal(myFunction("input"), "expected output");
  });
  
  it("should throw on invalid input", () => {
    throws(() => myFunction(null), /Error message pattern/);
  });
});

Test File Naming

• Place tests in the /test directory mirroring the source structure
• Name test files with .spec.mts extension (e.g., src/parse/index.mts → test/parse/index.spec.mts)

Parser Generation

• Parser files are generated from .peggy grammar files in the src/parse directory
• The build process (node --run=build) handles parser generation using the Peggy parser generator

Type Declarations

• Use interfaces for complex types
• Prefix interfaces with I (e.g., IStateMachine, IRenderOptions)
• Place type definitions in the /types directory or alongside their implementation