@atscript/typescript 0.1.48 → 0.1.50

package/dist/test-utils.cjs

@@ -0,0 +1,27 @@
+"use strict";
+const require_plugin = require('./plugin-cY7VLpmN.cjs');
+require('./json-schema-BgW_S2sP.cjs');
+const path = require_plugin.__toESM(require("path"));
+const __atscript_core = require_plugin.__toESM(require("@atscript/core"));
+const fs = require_plugin.__toESM(require("fs"));
+
+//#region packages/typescript/src/test-utils.ts
+async function prepareFixtures(options) {
+	const { rootDir, plugins = [], entries, include, formats = ["js", "dts"] } = options;
+	const repo = await (0, __atscript_core.build)({
+		rootDir,
+		plugins: [require_plugin.tsPlugin(), ...plugins],
+		...entries ? { entries } : { include: include ?? ["**/*.as"] }
+	});
+	const results = await Promise.all(formats.map((format) => repo.generate({
+		outDir: ".",
+		format
+	})));
+	for (const files of results) for (const file of files) {
+		const target = file.target ?? path.default.join(rootDir, file.fileName);
+		(0, fs.writeFileSync)(target, file.content);
+	}
+}
+
+//#endregion
+exports.prepareFixtures = prepareFixtures

package/dist/test-utils.d.ts

@@ -0,0 +1,25 @@
+import { TAtscriptPlugin } from '@atscript/core';
+
+interface PrepareFixturesOptions {
+    /** Absolute directory containing the `.as` fixture files. */
+    rootDir: string;
+    /** Additional plugins. `tsPlugin()` is auto-injected; do not pass it here. */
+    plugins?: TAtscriptPlugin[];
+    /** Glob includes; defaults to `['**\/*.as']` when `entries` is not set. */
+    include?: string[];
+    /** Explicit entry filenames relative to `rootDir`; takes precedence over `include`. */
+    entries?: string[];
+    /** Output formats to generate; defaults to `['js', 'dts']`. */
+    formats?: Array<'js' | 'dts'>;
+}
+/**
+ * Compiles `.as` fixture files under `rootDir` and writes the generated
+ * artifacts (`.as.js` and/or `.as.d.ts`) next to their sources.
+ *
+ * `tsPlugin()` is injected automatically — callers pass only extra plugins.
+ * Writes are unconditional; artifacts are treated as test-run outputs.
+ */
+declare function prepareFixtures(options: PrepareFixturesOptions): Promise<void>;
+
+export { prepareFixtures };
+export type { PrepareFixturesOptions };

package/dist/test-utils.mjs

@@ -0,0 +1,26 @@
+import { tsPlugin } from "./plugin-D96fH7Va.mjs";
+import "./json-schema-DrJMwvm1.mjs";
+import path from "path";
+import { build } from "@atscript/core";
+import { writeFileSync } from "fs";
+
+//#region packages/typescript/src/test-utils.ts
+async function prepareFixtures(options) {
+	const { rootDir, plugins = [], entries, include, formats = ["js", "dts"] } = options;
+	const repo = await build({
+		rootDir,
+		plugins: [tsPlugin(), ...plugins],
+		...entries ? { entries } : { include: include ?? ["**/*.as"] }
+	});
+	const results = await Promise.all(formats.map((format) => repo.generate({
+		outDir: ".",
+		format
+	})));
+	for (const files of results) for (const file of files) {
+		const target = file.target ?? path.join(rootDir, file.fileName);
+		writeFileSync(target, file.content);
+	}
+}
+
+//#endregion
+export { prepareFixtures };

package/dist/utils.cjs

@@ -1,5 +1,5 @@
 "use strict";
-const require_json_schema = require('./json-schema-Bu4xgpQn.cjs');
+const require_json_schema = require('./json-schema-BgW_S2sP.cjs');
 
 //#region packages/typescript/src/runtime/default-value.ts
 /**
@@ -247,15 +247,21 @@ function serializeNode(def, path, options, visited) {
 	if (refDepth > 0 && def.ref) {
 		const refTarget = def.ref.type();
 		if (refTarget) result.ref = {
-			type: serializeNode(refTarget, [], {
+			field: def.ref.field,
+			type: refDepth < 1 && isHalfStep(refDepth) ? {
+				id: refTarget.id ?? "",
+				metadata: serializeMetadata(refTarget.metadata, [], refTarget.type.kind, options)
+			} : serializeNode(refTarget, [], {
 				...options,
 				refDepth: refDepth - 1
-			}, visited),
-			field: def.ref.field
+			}, visited)
 		};
 	}
 	return result;
 }
+function isHalfStep(refDepth) {
+	return refDepth - Math.floor(refDepth) === .5;
+}
 function serializeTypeDef(def, path, options, visited) {
 	return require_json_schema.forAnnotatedType(def, {
 		phantom(d) {
@@ -346,27 +352,28 @@ function deserializeAnnotatedType(data) {
 	const resolved = new Map();
 	return deserializeNode(data, resolved);
 }
+function emptyObjectTypeDef() {
+	return {
+		kind: "object",
+		props: new Map(),
+		propsPatterns: [],
+		tags: new Set()
+	};
+}
+function toMetadataMap(record) {
+	return new Map(Object.entries(record));
+}
 function deserializeNode(data, resolved) {
 	if (data.type.kind === "$ref") {
 		const refId = data.type.id;
-		return resolved.get(refId) || require_json_schema.createAnnotatedTypeNode({
-			kind: "object",
-			props: new Map(),
-			propsPatterns: [],
-			tags: new Set()
-		}, new Map(), { id: refId });
+		return resolved.get(refId) || require_json_schema.createAnnotatedTypeNode(emptyObjectTypeDef(), new Map(), { id: refId });
 	}
-	const metadata = new Map(Object.entries(data.metadata));
+	const metadata = toMetadataMap(data.metadata);
 	let result;
 	if (data.id) {
 		const existing = resolved.get(data.id);
 		if (existing) return existing;
-		result = require_json_schema.createAnnotatedTypeNode({
-			kind: "object",
-			props: new Map(),
-			propsPatterns: [],
-			tags: new Set()
-		}, metadata, {
+		result = require_json_schema.createAnnotatedTypeNode(emptyObjectTypeDef(), metadata, {
 			optional: data.optional || undefined,
 			id: data.id
 		});
@@ -375,11 +382,20 @@ function deserializeNode(data, resolved) {
 	const type = deserializeTypeDef(data.type, resolved);
 	let ref;
 	if (data.ref) {
-		const deserializedRefTarget = deserializeNode(data.ref.type, resolved);
-		ref = {
-			type: () => deserializedRefTarget,
-			field: data.ref.field
-		};
+		const refTargetData = data.ref.type;
+		if ("type" in refTargetData) {
+			const deserializedRefTarget = deserializeNode(refTargetData, resolved);
+			ref = {
+				type: () => deserializedRefTarget,
+				field: data.ref.field
+			};
+		} else {
+			const sentinel = require_json_schema.createAnnotatedTypeNode(emptyObjectTypeDef(), toMetadataMap(refTargetData.metadata), { id: refTargetData.id || undefined });
+			ref = {
+				type: () => sentinel,
+				field: data.ref.field
+			};
+		}
 	}
 	if (result) {
 		result.type = type;

package/dist/utils.d.ts

@@ -491,12 +491,17 @@ interface TSerializedAnnotatedTypeInner {
     metadata: Record<string, unknown>;
     optional?: boolean;
     id?: string;
-    /** FK reference — present when serialized with `refDepth > 0` */
+    /** FK reference; shallow `{ id, metadata }` target when `refDepth` has a `.5` fractional part. */
     ref?: {
-        type: TSerializedAnnotatedTypeInner;
+        type: TSerializedAnnotatedTypeInner | TSerializedShallowRefTarget;
         field: string;
     };
 }
+/** Shallow ref-target shape: identity + interface-level metadata only, no structural body. */
+interface TSerializedShallowRefTarget {
+    id: string;
+    metadata: Record<string, unknown>;
+}
 interface TSerializedTypeFinal {
     kind: '';
     designType: string;
@@ -555,10 +560,9 @@ interface TSerializeOptions {
         value: unknown;
     } | undefined | void;
     /**
-     * How many levels of `.ref` (FK references) to expand during serialization.
-     * - `0` (default): refs are stripped (backward-compatible)
-     * - `1`: immediate refs are serialized, but refs inside referenced types are stripped
-     * - `2+`: deeper expansion
+     * How many levels of `.ref` (FK references) to expand. `0` (default) strips refs; integer
+     * `N` expands N levels with full target bodies. A `.5` fractional part (e.g. `0.5`, `1.5`)
+     * emits a shallow `{ id, metadata }` at the tail level instead of the full body.
      */
     refDepth?: number;
 }

package/dist/utils.mjs

@@ -1,4 +1,4 @@
-import { Validator, ValidatorError, annotate, buildJsonSchema, cloneRefProp, createAnnotatedTypeNode, defineAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, mergeJsonSchemas } from "./json-schema-Bl8jkrCj.mjs";
+import { Validator, ValidatorError, annotate, buildJsonSchema, cloneRefProp, createAnnotatedTypeNode, defineAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, mergeJsonSchemas } from "./json-schema-DrJMwvm1.mjs";
 
 //#region packages/typescript/src/runtime/default-value.ts
 /**
@@ -246,15 +246,21 @@ function serializeNode(def, path, options, visited) {
 	if (refDepth > 0 && def.ref) {
 		const refTarget = def.ref.type();
 		if (refTarget) result.ref = {
-			type: serializeNode(refTarget, [], {
+			field: def.ref.field,
+			type: refDepth < 1 && isHalfStep(refDepth) ? {
+				id: refTarget.id ?? "",
+				metadata: serializeMetadata(refTarget.metadata, [], refTarget.type.kind, options)
+			} : serializeNode(refTarget, [], {
 				...options,
 				refDepth: refDepth - 1
-			}, visited),
-			field: def.ref.field
+			}, visited)
 		};
 	}
 	return result;
 }
+function isHalfStep(refDepth) {
+	return refDepth - Math.floor(refDepth) === .5;
+}
 function serializeTypeDef(def, path, options, visited) {
 	return forAnnotatedType(def, {
 		phantom(d) {
@@ -345,27 +351,28 @@ function deserializeAnnotatedType(data) {
 	const resolved = new Map();
 	return deserializeNode(data, resolved);
 }
+function emptyObjectTypeDef() {
+	return {
+		kind: "object",
+		props: new Map(),
+		propsPatterns: [],
+		tags: new Set()
+	};
+}
+function toMetadataMap(record) {
+	return new Map(Object.entries(record));
+}
 function deserializeNode(data, resolved) {
 	if (data.type.kind === "$ref") {
 		const refId = data.type.id;
-		return resolved.get(refId) || createAnnotatedTypeNode({
-			kind: "object",
-			props: new Map(),
-			propsPatterns: [],
-			tags: new Set()
-		}, new Map(), { id: refId });
+		return resolved.get(refId) || createAnnotatedTypeNode(emptyObjectTypeDef(), new Map(), { id: refId });
 	}
-	const metadata = new Map(Object.entries(data.metadata));
+	const metadata = toMetadataMap(data.metadata);
 	let result;
 	if (data.id) {
 		const existing = resolved.get(data.id);
 		if (existing) return existing;
-		result = createAnnotatedTypeNode({
-			kind: "object",
-			props: new Map(),
-			propsPatterns: [],
-			tags: new Set()
-		}, metadata, {
+		result = createAnnotatedTypeNode(emptyObjectTypeDef(), metadata, {
 			optional: data.optional || undefined,
 			id: data.id
 		});
@@ -374,11 +381,20 @@ function deserializeNode(data, resolved) {
 	const type = deserializeTypeDef(data.type, resolved);
 	let ref;
 	if (data.ref) {
-		const deserializedRefTarget = deserializeNode(data.ref.type, resolved);
-		ref = {
-			type: () => deserializedRefTarget,
-			field: data.ref.field
-		};
+		const refTargetData = data.ref.type;
+		if ("type" in refTargetData) {
+			const deserializedRefTarget = deserializeNode(refTargetData, resolved);
+			ref = {
+				type: () => deserializedRefTarget,
+				field: data.ref.field
+			};
+		} else {
+			const sentinel = createAnnotatedTypeNode(emptyObjectTypeDef(), toMetadataMap(refTargetData.metadata), { id: refTargetData.id || undefined });
+			ref = {
+				type: () => sentinel,
+				field: data.ref.field
+			};
+		}
 	}
 	if (result) {
 		result.type = type;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -19,14 +19,11 @@
     "directory": "packages/typescript"
   },
   "bin": {
-    "asc": "./cli.cjs",
-    "atscript-typescript-skill": "./scripts/setup-skills.js"
+    "asc": "./cli.cjs"
   },
   "files": [
     "dist",
-    "cli.cjs",
-    "skills",
-    "scripts/setup-skills.js"
+    "cli.cjs"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -36,6 +33,9 @@
       "utils": [
         "dist/utils.d.ts"
       ],
+      "test-utils": [
+        "dist/test-utils.d.ts"
+      ],
       "": [
         "dist/index.d.ts"
       ]
@@ -54,19 +54,25 @@
       "require": "./dist/utils.cjs",
       "default": "./dist/utils.mjs"
     },
+    "./test-utils": {
+      "types": "./dist/test-utils.d.ts",
+      "import": "./dist/test-utils.mjs",
+      "require": "./dist/test-utils.cjs",
+      "default": "./dist/test-utils.mjs"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@moostjs/event-cli": "^0.6.7",
-    "moost": "^0.6.7"
+    "@moostjs/event-cli": "^0.6.8",
+    "moost": "^0.6.8"
   },
   "devDependencies": {
-    "vitest": "3.2.4",
-    "@atscript/db": "^0.1.48"
+    "@atscript/db": "^0.1.48",
+    "vitest": "3.2.4"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.48",
-    "@atscript/core": "^0.1.48"
+    "@atscript/core": "^0.1.50"
   },
   "peerDependenciesMeta": {
     "@atscript/db": {
@@ -77,7 +83,8 @@
     {
       "entries": [
         "src/index.ts",
-        "src/utils.ts"
+        "src/utils.ts",
+        "src/test-utils.ts"
       ]
     },
     {
@@ -90,7 +97,6 @@
   ],
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "test": "vitest"
   }
 }

package/scripts/setup-skills.js

@@ -1,88 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-import fs from 'fs'
-import os from 'os'
-import path from 'path'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const SKILL_NAME = 'atscript-typescript'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills', global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor': { dir: '.cursor/skills', global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf': { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex': { dir: '.codex/skills', global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode': { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0,
-  skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) {
-      skipped++
-      continue
-    }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try {
-    gitignoreContent = fs.readFileSync(gitignorePath, 'utf8')
-  } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block =
-      (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '') +
-      (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n') +
-      linesToAdd.join('\n') +
-      '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log(
-    'No agent directories detected. Try --global or run without it for project-local install.'
-  )
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/atscript-typescript/SKILL.md

@@ -1,52 +0,0 @@
----
-name: atscript-typescript
-description: Use when working with Atscript (.as files) in TypeScript projects — writing or editing .as interfaces/types/annotations, configuring atscript.config.ts or tsPlugin, understanding generated .d.ts/.js output, using runtime APIs (TAtscriptAnnotatedType, metadata, validators), generating JSON Schema or example data from types, serializing/deserializing annotated types, or running the asc CLI.
----
-
-# @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.*`/`@ui.*`/`@db.*` 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,
-  mergeJsonSchemas,
-  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)
-```