@formspec/build 0.1.0-alpha.13 → 0.1.0-alpha.15

package/dist/analyzer/jsdoc-constraints.d.ts

@@ -3,37 +3,17 @@
  *
  * Extracts constraints and annotation tags from JSDoc comments on
  * class/interface fields and returns canonical IR nodes directly:
- * - {@link ConstraintNode} for set-influencing tags (@Minimum, @Pattern, etc.)
- * - {@link AnnotationNode} for value-influencing tags (@Field_displayName, etc.)
+ * - {@link ConstraintNode} for set-influencing tags (@minimum, @pattern, etc.)
+ * - {@link AnnotationNode} for value-influencing tags (@displayName, etc.)
  *
  * The IR extraction path uses the official `@microsoft/tsdoc` parser for
- * constraints (all TSDoc-compliant alphanumeric names) and the TypeScript
- * compiler JSDoc API for annotation tags (which contain underscores, e.g.
- * `@Field_displayName`).
+ * all canonical tags.
  *
- * Supported constraints correspond to keys in {@link BUILTIN_CONSTRAINT_DEFINITIONS}
- * from `@formspec/core` (e.g., `@Minimum`, `@Maximum`, `@Pattern`).
+ * Supported constraints correspond to the built-in FormSpec constraint tags
+ * (e.g., `@minimum`, `@maximum`, `@pattern`).
  */
 import * as ts from "typescript";
-import { type ConstraintNode, type AnnotationNode } from "@formspec/core";
-/**
- * A constraint argument value.
- */
-export type ConstraintArg = string | number | boolean | null | ConstraintArg[] | {
-    [key: string]: ConstraintArg;
-};
-/**
- * Extracted constraint information from a JSDoc tag.
- * @deprecated Use {@link ConstraintNode} from the IR path instead.
- */
-export interface ConstraintInfo {
-    /** Constraint name (e.g., "Minimum", "Pattern", "Field") */
-    name: string;
-    /** Constraint arguments as literal values */
-    args: ConstraintArg[];
-    /** Raw AST node (undefined for synthetic JSDoc constraint entries) */
-    node: ts.Decorator | undefined;
-}
+import type { ConstraintNode, AnnotationNode } from "@formspec/core";
 /**
  * Extracts constraints from JSDoc comments on a TypeScript AST node and returns
  * canonical {@link ConstraintNode} objects.
@@ -47,14 +27,8 @@ export interface ConstraintInfo {
  */
 export declare function extractJSDocConstraintNodes(node: ts.Node, file?: string): ConstraintNode[];
 /**
- * Extracts `@Field_displayName`, `@Field_description`, and `@deprecated`
- * TSDoc tags from a node and returns canonical {@link AnnotationNode} objects.
- *
- * Uses a hybrid approach:
- * - `@deprecated` is extracted via the TSDoc parser (standard tag).
- * - `@Field_displayName` and `@Field_description` are extracted via the
- *   TypeScript compiler JSDoc API because they contain underscores which
- *   are invalid in TSDoc tag names.
+ * Extracts canonical annotation tags from a node and returns
+ * {@link AnnotationNode} objects.
  *
  * @param node - The AST node to inspect for annotation tags
  * @param file - Absolute path to the source file for provenance
@@ -74,22 +48,4 @@ export declare function hasDeprecatedTag(node: ts.Node): boolean;
  * Only extracts literal values (strings, numbers, booleans, null).
  */
 export declare function extractDefaultValueAnnotation(initializer: ts.Expression | undefined, file?: string): AnnotationNode | null;
-/**
- * Extracts JSDoc constraint tags and returns synthetic {@link ConstraintInfo}
- * objects for backward compatibility with the decorator-based pipeline.
- *
- * Uses the TypeScript compiler JSDoc API (not TSDoc parser) to maintain
- * identical behavior with the legacy pipeline.
- *
- * @deprecated Use {@link extractJSDocConstraintNodes} for IR output.
- */
-export declare function extractJSDocConstraints(node: ts.Node): ConstraintInfo[];
-/**
- * Extracts `@Field_displayName` and `@Field_description` TSDoc tags
- * and returns a synthetic `Field` {@link ConstraintInfo} for backward
- * compatibility with the decorator-based pipeline.
- *
- * @deprecated Use {@link extractJSDocAnnotationNodes} for IR output.
- */
-export declare function extractJSDocFieldMetadata(node: ts.Node): ConstraintInfo | null;
 //# sourceMappingURL=jsdoc-constraints.d.ts.map

package/dist/analyzer/jsdoc-constraints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-constraints.d.ts","sourceRoot":"","sources":["../../src/analyzer/jsdoc-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAOxB;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,aAAa,EAAE,GACf;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,sEAAsE;IACtE,IAAI,EAAE,EAAE,CAAC,SAAS,GAAG,SAAS,CAAC;CAChC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,cAAc,EAAE,CAGtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,cAAc,EAAE,CAGtF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,EACtC,IAAI,SAAK,GACR,cAAc,GAAG,IAAI,CAwCvB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,cAAc,EAAE,CA8CvE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,cAAc,GAAG,IAAI,CAgC9E"}
+{"version":3,"file":"jsdoc-constraints.d.ts","sourceRoot":"","sources":["../../src/analyzer/jsdoc-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAa,MAAM,gBAAgB,CAAC;AAOhF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,cAAc,EAAE,CAGtF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,cAAc,EAAE,CAGtF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,EACtC,IAAI,SAAK,GACR,cAAc,GAAG,IAAI,CAwCvB"}

package/dist/analyzer/json-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared JSON parsing utilities for the analyzer pipeline.
+ */
+/**
+ * Attempts to parse `text` as JSON.
+ *
+ * Returns the parsed value on success, or `null` if the input is not valid
+ * JSON. This is the canonical "try-parse" wrapper used by the constraint tag
+ * parsers so that every `JSON.parse` call in this package is consistent and
+ * centrally tested.
+ *
+ * Note: when the input is the literal string `"null"`, the return value is
+ * also `null` (valid JSON). This helper therefore cannot distinguish parse
+ * failure from a successfully-parsed JSON `null`. Callers that need to
+ * distinguish these cases should use a different API (for example, a wrapper
+ * that returns a discriminated result such as `{ ok: boolean, value?: unknown }`).
+ *
+ * @param text - Raw string to parse
+ * @returns The parsed value, or `null` on parse failure
+ */
+export declare function tryParseJson(text: string): unknown;
+//# sourceMappingURL=json-utils.d.ts.map

package/dist/analyzer/json-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-utils.d.ts","sourceRoot":"","sources":["../../src/analyzer/json-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMlD"}

package/dist/analyzer/tsdoc-parser.d.ts

@@ -8,14 +8,15 @@
  * The parser recognises two categories of tags:
  *
  * 1. **Constraint tags** (all alphanumeric, TSDoc-compliant):
- *    `@Minimum`, `@Maximum`, `@ExclusiveMinimum`, `@ExclusiveMaximum`,
- *    `@MinLength`, `@MaxLength`, `@Pattern`, `@EnumOptions`
+ *    `@minimum`, `@maximum`, `@exclusiveMinimum`, `@exclusiveMaximum`,
+ *    `@multipleOf`, `@minLength`, `@maxLength`, `@minItems`, `@maxItems`,
+ *    `@pattern`, `@enumOptions`
  *    — Parsed via TSDocParser as custom block tags.
+ *    Both camelCase and PascalCase forms are accepted (e.g., `@Minimum`).
  *
- * 2. **Annotation tags** (`@Field_displayName`, `@Field_description`):
- *    These contain underscores which are not valid in TSDoc tag names.
- *    They are extracted via the TypeScript compiler's `ts.getJSDocTags()`
- *    until a future migration to underscore-free tag names.
+ * 2. **Annotation tags** (`@displayName`, `@description`):
+ *    These are parsed as structured custom block tags and mapped directly
+ *    onto annotation IR nodes.
  *
  * The `@deprecated` tag is a standard TSDoc block tag, parsed structurally.
  *
@@ -27,14 +28,14 @@
  * verbatim.
  */
 import * as ts from "typescript";
-import { type ConstraintNode, type AnnotationNode } from "@formspec/core";
+import { type ConstraintNode, type AnnotationNode, type PathTarget } from "@formspec/core";
 /**
  * Result of parsing a single JSDoc comment attached to a TS AST node.
  */
 export interface TSDocParseResult {
     /** Constraint IR nodes extracted from custom block tags. */
     readonly constraints: readonly ConstraintNode[];
-    /** Annotation IR nodes extracted from modifier/block tags and TS JSDoc API. */
+    /** Annotation IR nodes extracted from canonical TSDoc block tags. */
     readonly annotations: readonly AnnotationNode[];
 }
 /**
@@ -42,10 +43,9 @@ export interface TSDocParseResult {
  * official TSDoc parser and returns canonical IR constraint and annotation
  * nodes.
  *
- * For constraint tags (`@Minimum`, `@Pattern`, `@EnumOptions`, etc.),
- * the structured TSDoc parser is used. For annotation tags that contain
- * underscores (`@Field_displayName`, `@Field_description`), the TypeScript
- * compiler JSDoc API is used as a fallback.
+ * For constraint tags (`@minimum`, `@pattern`, `@enumOptions`, etc.),
+ * the structured TSDoc parser is used. Canonical annotation tags
+ * (`@displayName`, `@description`) are also parsed structurally.
  *
  * @param node - The TS AST node to inspect (PropertyDeclaration, PropertySignature, etc.)
  * @param file - Absolute source file path for provenance
@@ -58,4 +58,16 @@ export declare function parseTSDocTags(node: ts.Node, file?: string): TSDocParse
  * Falls back to the TS compiler API for nodes without doc comments.
  */
 export declare function hasDeprecatedTagTSDoc(node: ts.Node): boolean;
+/**
+ * Extracts a path-target prefix (`:fieldName`) from constraint tag text.
+ * Returns the parsed PathTarget and remaining text, or null if no path target.
+ *
+ * @example
+ * extractPathTarget(":value 0") // → { path: { segments: ["value"] }, remainingText: "0" }
+ * extractPathTarget("42")       // → null
+ */
+export declare function extractPathTarget(text: string): {
+    path: PathTarget;
+    remainingText: string;
+} | null;
 //# sourceMappingURL=tsdoc-parser.d.ts.map

package/dist/analyzer/tsdoc-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc-parser.d.ts","sourceRoot":"","sources":["../../src/analyzer/tsdoc-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAYjC,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EAIpB,MAAM,gBAAgB,CAAC;AA8ExB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,gBAAgB,CAuHzE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAsB5D"}
+{"version":3,"file":"tsdoc-parser.d.ts","sourceRoot":"","sources":["../../src/analyzer/tsdoc-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAYjC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,cAAc,EAInB,KAAK,UAAU,EAChB,MAAM,gBAAgB,CAAC;AAwFxB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,gBAAgB,CAkGzE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAsB5D;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQpD"}