@atscript/typescript 0.1.25 → 0.1.27

package/README.md

@@ -0,0 +1,50 @@
+# @atscript/typescript
+
+TypeScript language extension for [Atscript](https://atscript.moost.org). Compiles `.as` files into `.d.ts` type declarations and `.js` runtime modules with full metadata, validation, and JSON Schema support.
+
+## Installation
+
+```bash
+pnpm add @atscript/typescript @atscript/core
+```
+
+For build-tool integration (Vite, Webpack, Rollup, esbuild, Rspack), also add:
+
+```bash
+pnpm add unplugin-atscript
+```
+
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx atscript-typescript-skill
+
+# Global (available across all your projects)
+npx atscript-typescript-skill --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "atscript-typescript-skill --postinstall"
+  }
+}
+```
+
+## Features
+
+- **Type declarations** — `.d.ts` files from `.as` interfaces and types
+- **Runtime metadata** — `.js` files with full metadata for validators and serializers
+- **JSON Schema** — Build, parse, and merge JSON schemas from annotated types
+- **Validation** — Validate data against types with plugin support
+- **Serialization** — JSON-safe round-trip serialization/deserialization
+- **CLI** — `asc` command for compiling `.as` files
+
+## Documentation
+
+Full documentation: [atscript.moost.org](https://atscript.moost.org)

package/dist/cli.cjs

@@ -971,6 +971,7 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 					__is_atscript_annotated_type: true,
 					type: newBase.type,
 					metadata,
+					id: newBase.id,
 					validator(opts) {
 						return new Validator(this, opts);
 					}
@@ -981,6 +982,10 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 		annotate(key, value, asArray) {
 			annotate(this.$metadata, key, value, asArray);
 			return this;
+		},
+		id(value) {
+			this.$type.id = value;
+			return this;
 		}
 	};
 	return handle;
@@ -1032,47 +1037,71 @@ function isPhantomType(def) {
 	return null;
 }
 function buildJsonSchema(type) {
+	const defs = {};
+	let isRoot = true;
+	const buildObject = (d) => {
+		const properties = {};
+		const required = [];
+		for (const [key, val] of d.type.props.entries()) {
+			if (isPhantomType(val)) continue;
+			properties[key] = build$1(val);
+			if (!val.optional) required.push(key);
+		}
+		const schema$1 = {
+			type: "object",
+			properties
+		};
+		if (required.length > 0) schema$1.required = required;
+		return schema$1;
+	};
 	const build$1 = (def) => {
+		if (def.id && def.type.kind === "object" && !isRoot) {
+			const name = def.id;
+			if (!defs[name]) {
+				defs[name] = {};
+				defs[name] = buildObject(def);
+			}
+			return { $ref: `#/$defs/${name}` };
+		}
+		isRoot = false;
 		const meta = def.metadata;
 		return forAnnotatedType(def, {
 			phantom() {
 				return {};
 			},
 			object(d) {
-				const properties = {};
-				const required = [];
-				for (const [key, val] of d.type.props.entries()) {
-					if (isPhantomType(val)) continue;
-					properties[key] = build$1(val);
-					if (!val.optional) required.push(key);
-				}
-				const schema = {
-					type: "object",
-					properties
-				};
-				if (required.length > 0) schema.required = required;
-				return schema;
+				return buildObject(d);
 			},
 			array(d) {
-				const schema = {
+				const schema$1 = {
 					type: "array",
 					items: build$1(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
-				if (minLength) schema.minItems = typeof minLength === "number" ? minLength : minLength.length;
+				if (minLength) schema$1.minItems = typeof minLength === "number" ? minLength : minLength.length;
 				const maxLength = meta.get("expect.maxLength");
-				if (maxLength) schema.maxItems = typeof maxLength === "number" ? maxLength : maxLength.length;
-				return schema;
+				if (maxLength) schema$1.maxItems = typeof maxLength === "number" ? maxLength : maxLength.length;
+				return schema$1;
 			},
 			union(d) {
 				const disc = detectDiscriminator(d.type.items);
-				if (disc) return {
-					oneOf: d.type.items.map(build$1),
-					discriminator: {
-						propertyName: disc.propertyName,
-						mapping: disc.mapping
+				if (disc) {
+					const oneOf = d.type.items.map(build$1);
+					const mapping = {};
+					for (const [val, origPath] of Object.entries(disc.mapping)) {
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
+						const item = d.type.items[idx];
+						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
+else mapping[val] = origPath;
 					}
-				};
+					return {
+						oneOf,
+						discriminator: {
+							propertyName: disc.propertyName,
+							mapping
+						}
+					};
+				}
 				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
@@ -1086,33 +1115,38 @@ function buildJsonSchema(type) {
 				};
 			},
 			final(d) {
-				const schema = {};
-				if (d.type.value !== undefined) schema.const = d.type.value;
+				const schema$1 = {};
+				if (d.type.value !== undefined) schema$1.const = d.type.value;
 				if (d.type.designType && d.type.designType !== "any") {
-					schema.type = d.type.designType === "undefined" ? "null" : d.type.designType;
-					if (schema.type === "number" && meta.get("expect.int")) schema.type = "integer";
+					schema$1.type = d.type.designType === "undefined" ? "null" : d.type.designType;
+					if (schema$1.type === "number" && meta.get("expect.int")) schema$1.type = "integer";
 				}
-				if (schema.type === "string") {
-					if (meta.get("meta.required")) schema.minLength = 1;
+				if (schema$1.type === "string") {
+					if (meta.get("meta.required")) schema$1.minLength = 1;
 					const minLength = meta.get("expect.minLength");
-					if (minLength) schema.minLength = typeof minLength === "number" ? minLength : minLength.length;
+					if (minLength) schema$1.minLength = typeof minLength === "number" ? minLength : minLength.length;
 					const maxLength = meta.get("expect.maxLength");
-					if (maxLength) schema.maxLength = typeof maxLength === "number" ? maxLength : maxLength.length;
+					if (maxLength) schema$1.maxLength = typeof maxLength === "number" ? maxLength : maxLength.length;
 					const patterns = meta.get("expect.pattern");
-					if (patterns?.length) if (patterns.length === 1) schema.pattern = patterns[0].pattern;
-else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern: p.pattern })));
+					if (patterns?.length) if (patterns.length === 1) schema$1.pattern = patterns[0].pattern;
+else schema$1.allOf = (schema$1.allOf || []).concat(patterns.map((p) => ({ pattern: p.pattern })));
 				}
-				if (schema.type === "number" || schema.type === "integer") {
+				if (schema$1.type === "number" || schema$1.type === "integer") {
 					const min = meta.get("expect.min");
-					if (min) schema.minimum = typeof min === "number" ? min : min.minValue;
+					if (min) schema$1.minimum = typeof min === "number" ? min : min.minValue;
 					const max = meta.get("expect.max");
-					if (max) schema.maximum = typeof max === "number" ? max : max.maxValue;
+					if (max) schema$1.maximum = typeof max === "number" ? max : max.maxValue;
 				}
-				return schema;
+				return schema$1;
 			}
 		});
 	};
-	return build$1(type);
+	const schema = build$1(type);
+	if (Object.keys(defs).length > 0) return {
+		...schema,
+		$defs: defs
+	};
+	return schema;
 }
 
 //#endregion
@@ -1133,11 +1167,23 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
+		const hasMutatingAnnotate = this.doc.nodes.some((n) => n.entity === "annotate" && n.isMutating);
+		if (hasMutatingAnnotate) imports.push("cloneRefProp as $c");
 		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
 		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
 		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
 		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
+		const nameCounts = new Map();
+		const nodesByName = new Map();
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
+			const name = node.id;
+			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
+			if (!nodesByName.has(name)) nodesByName.set(name, []);
+			nodesByName.get(name).push(node);
+		}
+		for (const [name, nodes] of nodesByName) if (nodes.length === 1) this.typeIds.set(nodes[0], name);
+else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}__${i + 1}`);
 	}
 	buildAdHocMap(annotateNodes) {
 		const map = new Map();
@@ -1151,6 +1197,15 @@ var JsRenderer = class extends BaseRenderer {
 		}
 		return map.size > 0 ? map : null;
 	}
+	/**
+	* Checks if any ad-hoc annotation path extends beyond the current _propPath,
+	* meaning annotations target properties inside a referenced type.
+	*/ hasAdHocAnnotationsThroughRef() {
+		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
+		const prefix = `${this._propPath.join(".")}.`;
+		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
+		return false;
+	}
 	post() {
 		for (const node of this.postAnnotate) if (node.entity === "annotate") {
 			const annotateNode = node;
@@ -1181,6 +1236,8 @@ else {
 		this.writeln("static __is_atscript_annotated_type = true");
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
+		const typeId = this.typeIds.get(node);
+		if (typeId) this.writeln(`static id = "${typeId}"`);
 		this.renderJsonSchemaMethod(node);
 		this.renderExampleDataMethod(node);
 	}
@@ -1259,6 +1316,8 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
+				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}
 			case "prop": {
@@ -1385,6 +1444,14 @@ else handle.prop(prop.id, propHandle.$type);
 						return this;
 					}
 				}
+				if (this._adHocAnnotations && this.hasAdHocAnnotationsThroughRef()) {
+					let resolved = decl ? this.doc.mergeIntersection(decl) : undefined;
+					if (resolved && (0, __atscript_core.isInterface)(resolved)) resolved = resolved.getDefinition() || resolved;
+					if (resolved) {
+						this.annotateType(resolved, name);
+						return this;
+					}
+				}
 				const chain = ref.hasChain ? `, [${ref.chain.map((c) => `"${escapeQuotes(c.text)}"`).join(", ")}]` : "";
 				this.writeln(`$(${name ? `"", ${name}` : ""})`).indent().writeln(`.refTo(${ref.id}${chain})`);
 				if (!ref.hasChain) {
@@ -1618,11 +1685,29 @@ else targetValue = "true";
 		const targetName = node.targetName;
 		const targetDef = this.resolveTargetDef(targetName);
 		this.writeln("// Ad-hoc annotations for ", targetName);
+		const allClones = [];
+		const entryAccessors = [];
 		for (const entry of node.entries) {
 			const anns = entry.annotations;
 			if (!anns || anns.length === 0) continue;
 			const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
-			const accessors = this.buildMutatingAccessors(targetName, targetDef, parts);
+			const { accessors, clones } = this.buildMutatingAccessors(targetName, targetDef, parts);
+			allClones.push(...clones);
+			entryAccessors.push({
+				entry,
+				accessors
+			});
+		}
+		const cloneKeys = new Set();
+		for (const clone of allClones) {
+			const key = `${clone.parentPath}|${clone.propName}`;
+			if (!cloneKeys.has(key)) {
+				cloneKeys.add(key);
+				this.writeln(`$c(${clone.parentPath}, "${escapeQuotes(clone.propName)}")`);
+			}
+		}
+		for (const { entry, accessors } of entryAccessors) {
+			const anns = entry.annotations;
 			for (const accessor of accessors) {
 				const cleared = new Set();
 				for (const an of anns) {
@@ -1672,15 +1757,21 @@ else targetValue = "true";
 			prefix: `${targetName}.type`,
 			def: targetDef
 		}];
+		const clones = [];
 		for (let i = 0; i < parts.length; i++) {
 			const nextAccessors = [];
 			for (const { prefix, def } of accessors) {
 				const results = this.buildPropPaths(def, parts[i]);
-				if (results.length > 0) for (const result of results) if (i < parts.length - 1) nextAccessors.push({
-					prefix: `${prefix}${result.path}?.type`,
-					def: result.propDef
-				});
-else nextAccessors.push({
+				if (results.length > 0) for (const result of results) if (i < parts.length - 1) {
+					if (result.propDef && (0, __atscript_core.isRef)(result.propDef)) clones.push({
+						parentPath: prefix,
+						propName: parts[i]
+					});
+					nextAccessors.push({
+						prefix: `${prefix}${result.path}?.type`,
+						def: result.propDef
+					});
+				} else nextAccessors.push({
 					prefix: `${prefix}${result.path}?`,
 					def: result.propDef
 				});
@@ -1694,7 +1785,10 @@ else {
 			}
 			accessors = nextAccessors;
 		}
-		return accessors.map((a) => a.prefix);
+		return {
+			accessors: accessors.map((a) => a.prefix),
+			clones
+		};
 	}
 	/**
 	* Finds a property in a type tree at compile time, returning all
@@ -1730,7 +1824,7 @@ else {
 		return [];
 	}
 	constructor(doc, opts) {
-		super(doc), _define_property$1(this, "opts", void 0), _define_property$1(this, "postAnnotate", void 0), _define_property$1(this, "_adHocAnnotations", void 0), _define_property$1(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this._adHocAnnotations = null, this._propPath = [];
+		super(doc), _define_property$1(this, "opts", void 0), _define_property$1(this, "postAnnotate", void 0), _define_property$1(this, "_adHocAnnotations", void 0), _define_property$1(this, "_propPath", void 0), _define_property$1(this, "typeIds", void 0), this.opts = opts, this.postAnnotate = [], this._adHocAnnotations = null, this._propPath = [], this.typeIds = new Map();
 	}
 };