@atscript/typescript 0.1.19 → 0.1.21

package/skills/atscript-typescript/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: atscript-typescript
+description: Atscript TypeScript language extension — .as file syntax, code generation, runtime type system, validation, and utilities for the Atscript metadata description language.
+---
+
+# @atscript/typescript
+
+Atscript is a universal type and metadata description language. `@atscript/typescript` is the TypeScript language extension that compiles `.as` files into `.d.ts` type declarations and `.js` runtime modules with full metadata, validation, and JSON Schema support.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain | File | Load when… |
+|--------|------|------------|
+| Setup & configuration | [core.md](core.md) | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI |
+| `.as` file syntax | [syntax.md](syntax.md) | Writing `.as` files — interfaces, types, imports/exports, property syntax |
+| Annotations & primitives | [annotations.md](annotations.md) | Using built-in `@meta.*`/`@expect.*` annotations, defining custom annotations or primitives |
+| Code generation | [codegen.md](codegen.md) | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types |
+| Runtime type system | [runtime.md](runtime.md) | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType` |
+| Validation | [validation.md](validation.md) | Validating data, type guards, error handling, custom validator plugins |
+| Utility functions | [utilities.md](utilities.md) | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType` |
+
+## Quick reference
+
+```ts
+// Main export (plugin for atscript.config)
+import tsPlugin from '@atscript/typescript'
+
+// Runtime utilities (used in app code)
+import {
+  defineAnnotatedType, isAnnotatedType, annotate,
+  Validator, ValidatorError,
+  buildJsonSchema, fromJsonSchema,
+  serializeAnnotatedType, deserializeAnnotatedType,
+  flattenAnnotatedType, createDataFromAnnotatedType,
+  forAnnotatedType, throwFeatureDisabled,
+} from '@atscript/typescript/utils'
+
+// CLI
+// npx asc -f dts        — generate .d.ts files
+// npx asc -f js         — generate .js files (not usually needed with unplugin)
+// npx asc               — generate default formats (for typescript plugin this is d.ts only, but if there are other language plugins it may generate multiple formats)
+```

package/skills/atscript-typescript/annotations.md

@@ -0,0 +1,240 @@
+# Annotations & Primitives — @atscript/typescript
+
+> All built-in annotations, their arguments, and how to define custom annotations and primitives.
+
+## Built-in Annotations
+
+### `@meta.*` — Metadata Annotations
+
+| Annotation | Arguments | Description |
+|------------|-----------|-------------|
+| `@meta.label` | `text: string` | Human-readable label for UI, logs, documentation |
+| `@meta.id` | `name?: string` (optional) | Mark field as unique identifier; optional custom name |
+| `@meta.description` | `text: string` | Detailed description of a field or entity |
+| `@meta.documentation` | `text: string` | Multi-line docs (Markdown). Multiple allowed — each appends |
+| `@meta.placeholder` | `text: string` | Placeholder for UI input fields (props/types only) |
+| `@meta.sensitive` | *(none)* | Mark as sensitive (passwords, API keys). Strips from serialization |
+| `@meta.readonly` | *(none)* | Mark as read-only |
+| `@meta.required` | `message?: string` | Required field. Strings: non-whitespace. Booleans: must be `true` |
+| `@meta.default` | `value: string` | Default value (strings as-is, others parsed as JSON) |
+| `@meta.example` | `value: string` | Example value (strings as-is, others parsed as JSON) |
+| `@meta.isKey` | *(none)* | Mark field as key inside array (string/number types only) |
+
+### `@expect.*` — Validation Constraints
+
+| Annotation | Arguments | Applies To | Description |
+|------------|-----------|-----------|-------------|
+| `@expect.minLength` | `length: number`, `message?: string` | string, array | Minimum length |
+| `@expect.maxLength` | `length: number`, `message?: string` | string, array | Maximum length |
+| `@expect.min` | `minValue: number`, `message?: string` | number | Minimum value |
+| `@expect.max` | `maxValue: number`, `message?: string` | number | Maximum value |
+| `@expect.int` | *(none)* | number | Must be integer |
+| `@expect.pattern` | `pattern: string`, `flags?: string`, `message?: string` | string | Regex validation. **Multiple allowed** (all must pass) |
+
+### `@emit.*` — Build-time Directives
+
+| Annotation | Applies To | Description |
+|------------|-----------|-------------|
+| `@emit.jsonSchema` | interface | Pre-compute and embed JSON Schema at build time |
+
+## Custom Annotations
+
+Define custom annotations in `atscript.config.ts` using `AnnotationSpec`:
+
+```ts
+import { defineConfig, AnnotationSpec } from '@atscript/core'
+import tsPlugin from '@atscript/typescript'
+
+export default defineConfig({
+  plugins: [tsPlugin()],
+  annotations: {
+    // Namespaced annotations use nested objects
+    ui: {
+      // @ui.component "DatePicker"
+      component: new AnnotationSpec({
+        argument: { name: 'name', type: 'string' },
+        description: 'UI component to render this field',
+      }),
+
+      // @ui.hidden (no arguments — boolean flag)
+      hidden: new AnnotationSpec({
+        description: 'Hide this field in the UI',
+      }),
+
+      // @ui.order 5
+      order: new AnnotationSpec({
+        argument: { name: 'position', type: 'number' },
+      }),
+    },
+
+    // @tag "important" (multiple allowed, each appended)
+    tag: new AnnotationSpec({
+      multiple: true,
+      mergeStrategy: 'append',
+      argument: { name: 'value', type: 'string' },
+    }),
+
+    // Annotation with multiple named arguments
+    // @api.endpoint "/users" "GET"
+    api: {
+      endpoint: new AnnotationSpec({
+        argument: [
+          { name: 'path', type: 'string' },
+          { name: 'method', type: 'string', optional: true },
+        ],
+      }),
+    },
+  },
+})
+```
+
+### `AnnotationSpec` Options
+
+```ts
+new AnnotationSpec({
+  // Single argument
+  argument: { name: 'value', type: 'string' },
+
+  // Or multiple arguments
+  argument: [
+    { name: 'first', type: 'string' },
+    { name: 'second', type: 'number', optional: true },
+  ],
+
+  // Allow multiple instances on the same target
+  multiple: true,               // default: false
+
+  // How duplicates merge: 'replace' (last wins) or 'append' (collect into array)
+  mergeStrategy: 'append',      // default: 'replace'
+
+  // Human-readable description
+  description: 'What this annotation does',
+
+  // Restrict to specific node types
+  nodeType: ['interface', 'type', 'prop'],
+
+  // Custom validation function
+  validate: (mainToken, args, doc) => {
+    // Return array of diagnostic messages, or undefined
+  },
+})
+```
+
+### Argument Types
+
+Each argument accepts:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Argument name (used in metadata object key) |
+| `type` | `'string' \| 'number' \| 'boolean'` | Expected type |
+| `optional` | `boolean` | Whether the argument can be omitted |
+| `description` | `string` | Human-readable description |
+| `values` | `string[]` | Allowed values (enum-like constraint) |
+
+### How Annotations Map to Runtime Metadata
+
+- **Single argument** → metadata value is the argument value directly
+- **Multiple named arguments** → metadata value is an object with argument names as keys
+- **No arguments** → metadata value is `true`
+- **`multiple: true`** → metadata value is an array
+
+Example: `@api.endpoint "/users" "GET"` becomes:
+```ts
+metadata.get('api.endpoint') // → { path: "/users", method: "GET" }
+```
+
+## Custom Primitives
+
+Define custom primitive types in `atscript.config.ts`:
+
+```ts
+export default defineConfig({
+  primitives: {
+    // Simple alias with built-in validation
+    currency: {
+      type: 'string',
+      tags: ['string'],
+      expect: {
+        pattern: /^\d+\.\d{2}$/,
+        message: 'Must be in format 0.00',
+      },
+    },
+
+    // Primitive with extensions (subtypes)
+    url: {
+      type: 'string',
+      tags: ['string'],
+      expect: {
+        pattern: /^https?:\/\/.+/,
+      },
+      extensions: {
+        // url.https — only HTTPS
+        https: {
+          expect: {
+            pattern: /^https:\/\/.+/,
+          },
+        },
+        // url.relative — relative URLs
+        relative: {
+          expect: {
+            pattern: /^\/.+/,
+          },
+        },
+      },
+    },
+
+    // Object-shaped primitive
+    point: {
+      type: {
+        kind: 'object',
+        props: {
+          x: 'number',
+          y: 'number',
+        },
+      },
+    },
+  },
+})
+```
+
+### `TPrimitiveConfig` Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `TPrimitiveTypeDef` | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex type |
+| `tags` | `string[]` | Custom tags for categorization |
+| `documentation` | `string` | Documentation string |
+| `expect` | object | Built-in validation constraints |
+| `extensions` | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types accessible via dot notation |
+
+### `expect` Validation on Primitives
+
+| Field | Applies To | Description |
+|-------|-----------|-------------|
+| `min` | number | Minimum value |
+| `max` | number | Maximum value |
+| `int` | number | Must be integer |
+| `minLength` | string, array | Minimum length |
+| `maxLength` | string, array | Maximum length |
+| `pattern` | string | Regex pattern(s) |
+| `required` | string, boolean | Non-empty / must be true |
+| `message` | any | Custom error message for pattern |
+
+### Usage in `.as` Files
+
+After defining custom primitives/annotations, use them directly:
+
+```as
+interface Product {
+  @meta.label "Price"
+  price: currency
+
+  @ui.component "UrlInput"
+  website: url.https
+
+  @tag "featured"
+  @tag "new"
+  featured: boolean
+}
+```

package/skills/atscript-typescript/codegen.md

@@ -0,0 +1,126 @@
+# Code Generation — @atscript/typescript
+
+> How `.as` files are transformed into `.d.ts` type declarations and `.js` runtime modules.
+
+## Overview
+
+Each `.as` file produces two outputs:
+
+| Output | Generated By | Contains |
+|--------|-------------|----------|
+| `*.as.d.ts` | `npx asc -f dts` or build tool | TypeScript type declarations — interfaces become `declare class` with static type/metadata/validator |
+| `*.as.js` | Build tool (unplugin-atscript) | Runtime module — classes with full type definitions, metadata maps, and validator factories |
+
+## `.d.ts` Output
+
+The TypeScript declaration file makes `.as` types importable with full IntelliSense:
+
+```as
+// user.as
+@meta.label "User"
+export interface User {
+  name: string
+  age: number
+  email?: string
+}
+
+export type Status = "active" | "inactive"
+```
+
+Generates `user.as.d.ts`:
+
+```ts
+import type {
+  TAtscriptTypeObject, TAtscriptAnnotatedType,
+  TMetadataMap, Validator, TValidatorOptions
+} from "@atscript/typescript/utils"
+
+export declare class User {
+  name: string
+  age: number
+  email?: string
+  static __is_atscript_annotated_type: true
+  static type: TAtscriptTypeObject<keyof User, User>
+  static metadata: TMetadataMap<AtscriptMetadata>
+  static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof User>
+  static toJsonSchema: () => any
+  /** When exampleData is disabled (default), marked @deprecated + optional */
+  static toExampleData?: () => any
+}
+
+export type Status = "active" | "inactive"
+declare namespace Status {
+  const __is_atscript_annotated_type: true
+  const type: TAtscriptTypeComplex<Status>
+  const metadata: TMetadataMap<AtscriptMetadata>
+  const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof Status>
+  const toJsonSchema: () => any
+  const toExampleData: (() => any) | undefined
+}
+```
+
+Key points:
+- **Interfaces** become `declare class` — so they work both as types and runtime values
+- **Types** become a `type` alias + a companion `namespace` with runtime statics
+- Each has `type`, `metadata`, `validator()`, `toJsonSchema()`, and `toExampleData()` statics
+- `toExampleData` is always optional in `.d.ts`. When `exampleData: true`, it's rendered without deprecation; when disabled, it's marked `@deprecated`
+
+## `.js` Output
+
+The JS module creates actual classes with runtime type definitions and metadata:
+
+- Uses `defineAnnotatedType` (aliased as `$`) to build the type tree
+- Populates metadata maps with all annotation values
+- Wires up `validator()` and `toJsonSchema()` methods
+- When `exampleData: true`, adds `toExampleData()` that calls `createDataFromAnnotatedType(this, { mode: 'example' })` (aliased as `$e`)
+- When `jsonSchema: false` (default), `toJsonSchema()` calls `throwFeatureDisabled()` (aliased as `$d`) instead of inlining the error message
+
+You don't normally read or modify generated JS — the build tool handles it.
+
+## `atscript.d.ts` — Global Type Declarations
+
+Running `npx asc -f dts` also generates `atscript.d.ts` in your project root:
+
+```ts
+export {}
+
+declare global {
+  interface AtscriptMetadata {
+    'meta.label': string
+    'meta.required': { message?: string } | true
+    'expect.minLength': { length: number; message?: string }
+    // ... all annotations used in your project
+  }
+  type AtscriptPrimitiveTags = "string" | "number" | "boolean" | "null"
+}
+```
+
+This file is **auto-generated** based on the annotations actually used across all your `.as` files. It enables:
+
+- Type-safe `metadata.get('meta.label')` calls — TypeScript knows the return type
+- Autocompletion for annotation keys
+- Correct types for primitive tags
+
+**Important**: Re-run `npx asc -f dts` after adding new annotations to your config. The `atscript.d.ts` file should be committed to your repository.
+
+## Import Paths
+
+Generated files use these import paths:
+
+| Import | Source |
+|--------|--------|
+| `@atscript/typescript/utils` | Runtime utilities (used by generated `.js` files) |
+
+When importing from `.as` files in your TypeScript code:
+
+```ts
+// Import the generated interface — works as both a type and a runtime value
+import { User } from './models/user.as'
+
+// Use as a type
+function greet(user: User) { ... }
+
+// Use as a runtime value (has metadata, validator, etc.)
+User.metadata.get('meta.label')  // "User"
+User.validator().validate(data)
+```

package/skills/atscript-typescript/core.md

@@ -0,0 +1,164 @@
+# Setup & Configuration — @atscript/typescript
+
+> Installation, configuration file, TypeScript plugin options, and CLI usage.
+
+## Installation
+
+```bash
+pnpm add @atscript/typescript @atscript/core
+# or
+npm install @atscript/typescript @atscript/core
+```
+
+For build-tool integration (Vite, Webpack, Rollup, esbuild, Rspack):
+
+```bash
+pnpm add unplugin-atscript
+```
+
+## Configuration File
+
+Create `atscript.config.ts` (or `.js`, `.mjs`) in your project root:
+
+```ts
+import { defineConfig } from '@atscript/core'
+import tsPlugin from '@atscript/typescript'
+
+export default defineConfig({
+  // Root directory for resolving .as files (defaults to cwd)
+  rootDir: '.',
+
+  // Entry points — glob patterns for .as files to compile
+  entries: ['src/**/*.as'],
+
+  // Include/exclude globs for dependency resolution
+  include: ['src/**/*.as'],
+  exclude: ['node_modules/**'],
+
+  // Plugins — tsPlugin is the TypeScript language extension
+  plugins: [tsPlugin()],
+
+  // How to handle unknown annotations: 'allow' | 'warn' | 'error'
+  unknownAnnotation: 'warn',
+
+  // Custom primitives (merged with built-in ones)
+  primitives: {},
+
+  // Custom annotations (merged with built-in ones)
+  annotations: {},
+})
+```
+
+### `TAtscriptConfig` Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rootDir` | `string` | Root directory for resolving files |
+| `entries` | `string[]` | Entry point globs for `.as` files |
+| `include` | `string[]` | Include globs |
+| `exclude` | `string[]` | Exclude globs |
+| `plugins` | `TAtscriptPlugin[]` | Build plugins (e.g. `tsPlugin()`) |
+| `primitives` | `Record<string, TPrimitiveConfig>` | Custom primitive type definitions |
+| `annotations` | `TAnnotationsTree` | Custom annotation definitions |
+| `unknownAnnotation` | `'allow' \| 'warn' \| 'error'` | Unknown annotation handling |
+| `format` | `string` | Output format (set by CLI or build tool) |
+| `outDir` | `string` | Output directory |
+
+## TypeScript Plugin Options
+
+```ts
+tsPlugin({
+  jsonSchema: false    // default — toJsonSchema() throws at runtime
+  // jsonSchema: 'lazy'   — import buildJsonSchema, compute on demand, cache
+  // jsonSchema: 'bundle' — pre-compute at build time, embed in output
+
+  exampleData: false   // default — toExampleData() not rendered
+  // exampleData: true  — render toExampleData() using createDataFromAnnotatedType
+})
+```
+
+### `jsonSchema`
+
+Individual interfaces can override the JSON Schema setting with `@emit.jsonSchema` annotation to force build-time embedding regardless of plugin setting.
+
+### `exampleData`
+
+Controls whether `toExampleData()` is generated on output classes:
+- `false` *(default)* — method is not rendered in `.js`; `.d.ts` marks it as optional + `@deprecated`
+- `true` — each class gets `static toExampleData()` that calls `createDataFromAnnotatedType(this, { mode: 'example' })`, creating a new example data object on each call (no caching)
+
+## Build Tool Integration
+
+### Vite
+
+```ts
+// vite.config.ts
+import atscript from 'unplugin-atscript/vite'
+
+export default {
+  plugins: [atscript()]
+}
+```
+
+### Webpack
+
+```ts
+// webpack.config.js
+const atscript = require('unplugin-atscript/webpack')
+module.exports = {
+  plugins: [atscript()]
+}
+```
+
+The unplugin automatically compiles `.as` files during development and build, generating `.as.js` modules that are importable.
+
+## CLI — `asc`
+
+The `asc` CLI compiles `.as` files outside of build tools (e.g. for generating `.d.ts` files).
+
+```bash
+# Generate .d.ts files (most common use case)
+npx asc -f dts
+
+# Generate .js files
+npx asc -f js
+
+# Use a specific config file
+npx asc -c atscript.config.ts
+
+# Only run diagnostics, no file output
+npx asc --noEmit
+
+# Skip diagnostics, always emit
+npx asc --skipDiag
+```
+
+### Why run `npx asc -f dts`?
+
+This generates two things:
+1. **`*.as.d.ts`** files next to each `.as` file — TypeScript type declarations for all interfaces/types
+2. **`atscript.d.ts`** in the project root — global type declarations for `AtscriptMetadata` and `AtscriptPrimitiveTags`
+
+The `atscript.d.ts` file is **crucial for type safety** — it tells TypeScript about all annotations used in your project, enabling type-safe metadata access at runtime.
+
+### CLI Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--config <path>` | `-c` | Path to config file |
+| `--format <fmt>` | `-f` | Output format: `dts`, `js` |
+| `--noEmit` | | Only check for errors |
+| `--skipDiag` | | Skip diagnostics, always emit |
+
+## Project Structure Example
+
+```
+my-project/
+  atscript.config.ts      ← config file
+  atscript.d.ts           ← generated by `npx asc -f dts` (global types)
+  src/
+    models/
+      user.as             ← source file
+      user.as.d.ts        ← generated type declarations
+      user.as.js          ← generated runtime module (by build tool)
+```