@atscript/typescript 0.1.49 → 0.1.51

package/skills/atscript-typescript/annotations.md

@@ -1,259 +0,0 @@
-# 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`            | _(none)_                   | Mark field as unique identifier; multiple fields form composite PK |
-| `@meta.description`   | `text: string`             | Detailed description of a field or entity                          |
-| `@meta.documentation` | `text: string`             | Multi-line docs (Markdown). Multiple allowed — each appends        |
-| `@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)               |
-| `@expect.array.key`   | `message?: string`         | Mark field as key inside array (string/number only, non-optional). Multiple = composite key |
-
-### `@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) |
-| `@expect.array.uniqueItems` | `message?: string`                             | array         | No duplicate items (by key fields or deep equality)    |
-
-### `@ui.*` — UI / Presentation Hints
-
-| Annotation        | Arguments                      | Description                                    |
-| ----------------- | ------------------------------ | ---------------------------------------------- |
-| `@ui.placeholder` | `text: string`                 | Input placeholder text                         |
-| `@ui.component`   | `name: string`                 | UI component hint (`"select"`, `"datepicker"`) |
-| `@ui.hidden`      | _(none)_                       | Hide from UI forms/tables                      |
-| `@ui.group`       | `name: string`                 | Group fields into form sections                |
-| `@ui.order`       | `order: number`                | Display order (lower = first)                  |
-| `@ui.width`       | `width: string`                | Layout hint (`"half"`, `"full"`, `"third"`)    |
-| `@ui.icon`        | `name: string`                 | Icon hint                                      |
-| `@ui.hint`        | `text: string`                 | Help text / tooltip                            |
-| `@ui.disabled`    | _(none)_                       | Non-interactive field                          |
-| `@ui.type`        | `type: string`                 | Input type (`"textarea"`, `"password"`, etc.)  |
-| `@ui.attr`        | `key: string`, `value: string` | Arbitrary attribute (**multiple**, append)      |
-| `@ui.class`       | `names: string`                | CSS class names (**multiple**, append)          |
-| `@ui.style`       | `css: string`                  | Inline CSS styles (**multiple**, append)        |
-
-### `@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
-    grid: {
-      // @grid.column 200
-      column: new AnnotationSpec({
-        argument: { name: 'width', type: 'number' },
-        description: 'Table column width in data grid',
-      }),
-
-      // @grid.hidden (no arguments — boolean flag)
-      hidden: new AnnotationSpec({
-        description: 'Hide column in data grid',
-      }),
-
-      // @grid.sortable
-      sortable: new AnnotationSpec({
-        description: 'Allow sorting by this column',
-      }),
-    },
-
-    // @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

@@ -1,131 +0,0 @@
-# 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
-- Each class gets a `static id` field with the stable type name (collision-safe via `__N` suffix)
-- 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

@@ -1,166 +0,0 @@
-# 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)
-```