Skip to content

AGENTS.md

Latest commit

 

History

History
99 lines (73 loc) · 4.23 KB

AGENTS.md

File metadata and controls

99 lines (73 loc) · 4.23 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

UI5 CLI v5 — an open, modular toolchain for developing UI5 framework applications. This is a monorepo using npm workspaces containing 6 public packages and 3 internal packages. All code uses ESM ("type": "module").

Node requirement: ^22.20.0 || >=24.0.0

Commands

Install

npm ci --engine-strict

Run all tests (lint + coverage + license checks + knip)

npm test

Lint

npm run lint                              # All workspaces
npm run lint --workspace=@ui5/cli         # Single package

Unit tests

npm run unit                              # All workspaces
npm run unit --workspace=@ui5/builder     # Single package
npx ava test/lib/some/test.js             # Single test file (run from package dir)

Unit tests with verbose logging

npm run unit-verbose --workspace=@ui5/cli

Coverage

npm run coverage                          # All workspaces
npm run coverage --workspace=@ui5/server  # Single package

Architecture

@ui5/cli          CLI entry point (yargs). Commands in lib/cli/commands/
  ├── @ui5/project   Project graph, config loading, dependency resolution (AJV schemas)
  ├── @ui5/builder   Build tasks & processors (JS bundling, minification, CSS, JSDoc)
  ├── @ui5/server    Express dev server with middleware architecture
  ├── @ui5/fs        Virtual file system with AbstractReader/AbstractReaderWriter
  └── @ui5/logger    Logging with configurable levels and progress bars
  • Entry point: packages/cli/bin/ui5.cjs (CJS wrapper for Node compatibility) → loads packages/cli/lib/cli/cli.js (ESM)
  • Builder uses a task/processor pattern: tasks orchestrate processors, both are loaded from repositories (taskRepository.js)
  • Server uses an Express middleware pipeline; middlewares are loaded dynamically via MiddlewareManager
  • FS provides a resource abstraction layer — ReaderCollection composes multiple readers; adapters handle real FS backends
  • Project builds a ProjectGraph of dependencies from npm packages and UI5 config files (YAML/XML); validates configs with AJV JSON schemas

Internal packages:

  • internal/benchmark — CLI performance benchmark tooling
  • internal/documentation — VitePress docs + JSDoc + JSON schema generation
  • internal/e2e-tests — end-to-end tests for packaged CLI workflows

Internal package dependencies

Packages under internal/* are private and never published. They MUST declare all dependencies as devDependencies — declaring a production "dependencies" entry is not allowed. Reason: Dependabot derives the commit-message type from prod vs. dev dependency updates (deps vs. build(deps-dev)) and does not treat internal packages differently, so a production dependency there yields a misleading deps commit. A CI check in .github/workflows/github-ci.yml ("Check internal packages declare no production dependencies") enforces this.

Code Style

  • Indentation: tabs
  • Quotes: double
  • Max line length: 120
  • Semicolons: required
  • No console.log() — use @ui5/logger instead
  • ESLint flat config with Google style base + JSDoc + AVA plugins

Testing

  • Framework: AVA with esmock for ESM module mocking, sinon for stubs/spies
  • Test location: packages/*/test/lib/**/*.js
  • Helpers (excluded from test runs): test/**/__helper__/**
  • Fixtures: test/fixtures/, Expected outputs: test/expected/
  • Coverage: NYC (Istanbul) — thresholds vary per package (70-90%)
  • Temp files: test/tmp/ (cleaned before each run via rimraf)

Commit Convention

Conventional commits enforced via commitlint + husky. Subject must be sentence-case.

Types: build, ci, deps, docs, feat, fix, perf, refactor, release, revert, style, test

Scopes are package names: builder, cli, documentation, fs, logger, project, server. Some types restrict which scopes are valid (e.g., feat and fix only allow public package scopes).

Examples: feat(builder): Add CSS source map support, fix(server): Correct middleware ordering