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

package/README.md

@@ -106,11 +106,11 @@ The analyzer extracts type information and JSDoc constraint tags (e.g., `/** @Mi
 
 ### Entry Points
 
-| Entry Point               | Audience           | Description                                                                                       |
-| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
-| `@formspec/build`         | Public API         | `buildFormSchemas`, `writeSchemas`, `generateSchemasFromClass`, schema generators                 |
-| `@formspec/build/browser` | Browser (playground) | Schema generators without Node.js `fs`/`path` — safe for bundlers                              |
-| `@formspec/build/internals` | CLI (unstable)   | Internal APIs: `createProgramContext`, `analyzeClass`, `generateClassSchemas`                     |
+| Entry Point                 | Audience             | Description                                                                       |
+| --------------------------- | -------------------- | --------------------------------------------------------------------------------- |
+| `@formspec/build`           | Public API           | `buildFormSchemas`, `writeSchemas`, `generateSchemasFromClass`, schema generators |
+| `@formspec/build/browser`   | Browser (playground) | Schema generators without Node.js `fs`/`path` — safe for bundlers                 |
+| `@formspec/build/internals` | CLI (unstable)       | Internal APIs: `createProgramContext`, `analyzeClass`, `generateClassSchemas`     |
 
 ## Generated Output
 
@@ -149,25 +149,25 @@ The analyzer extracts type information and JSDoc constraint tags (e.g., `/** @Mi
 
 ### Functions
 
-| Function                             | Description                                                        |
-| ------------------------------------ | ------------------------------------------------------------------ |
-| `buildFormSchemas(form)`             | Generate both JSON Schema and UI Schema                            |
-| `generateJsonSchema(form)`           | Generate only JSON Schema                                          |
-| `generateUiSchema(form)`             | Generate only UI Schema                                            |
-| `writeSchemas(form, options)`        | Build and write schemas to disk                                    |
-| `generateSchemasFromClass(options)`  | Generate schemas from a TypeScript class via static analysis       |
-| `generateSchemas(options)`           | Generate schemas from a TypeScript type via static analysis        |
+| Function                            | Description                                                  |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `buildFormSchemas(form)`            | Generate both JSON Schema and UI Schema                      |
+| `generateJsonSchema(form)`          | Generate only JSON Schema                                    |
+| `generateUiSchema(form)`            | Generate only UI Schema                                      |
+| `writeSchemas(form, options)`       | Build and write schemas to disk                              |
+| `generateSchemasFromClass(options)` | Generate schemas from a TypeScript class via static analysis |
+| `generateSchemas(options)`          | Generate schemas from a TypeScript type via static analysis  |
 
 ### Types
 
-| Type                      | Description                             |
-| ------------------------- | --------------------------------------- |
-| `BuildResult`             | Return type of `buildFormSchemas`       |
-| `WriteSchemasOptions`     | Options for `writeSchemas`              |
-| `WriteSchemasResult`      | Return type of `writeSchemas`           |
-| `JsonSchema2020`          | JSON Schema 2020-12 type                |
+| Type                       | Description                            |
+| -------------------------- | -------------------------------------- |
+| `BuildResult`              | Return type of `buildFormSchemas`      |
+| `WriteSchemasOptions`      | Options for `writeSchemas`             |
+| `WriteSchemasResult`       | Return type of `writeSchemas`          |
+| `JsonSchema2020`           | JSON Schema 2020-12 type               |
 | `GenerateFromClassOptions` | Options for `generateSchemasFromClass` |
-| `UISchema`                | JSON Forms UI Schema type               |
+| `UISchema`                 | JSON Forms UI Schema type              |
 
 ## License
 

package/dist/__tests__/alias-chain-propagation.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for transitive type alias constraint propagation.
+ *
+ * Verifies that constraints declared on type aliases propagate transitively
+ * through alias chains (e.g., Integer → Percentage → field), and that
+ * excessively deep chains throw a clear error.
+ */
+export {};
+//# sourceMappingURL=alias-chain-propagation.test.d.ts.map

package/dist/__tests__/alias-chain-propagation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-chain-propagation.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/alias-chain-propagation.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/__tests__/fixtures/alias-chains.d.ts

@@ -0,0 +1,37 @@
+/** @multipleOf 1 */
+type Integer = number;
+/** @minimum 0 @maximum 100 */
+type Percentage = Integer;
+export declare class TwoLevelChain {
+    /** @minimum 10 */
+    cpuUsage: Percentage;
+    memoryUsage: Percentage;
+}
+/** @minimum 0 */
+type Base = number;
+/** @maximum 1000 */
+type Mid = Base;
+/** @multipleOf 5 */
+type Leaf = Mid;
+export declare class ThreeLevelChain {
+    value: Leaf;
+}
+export declare class NoAlias {
+    /** @minimum 0 */
+    count: number;
+}
+type D0 = number;
+type D1 = D0;
+type D2 = D1;
+type D3 = D2;
+type D4 = D3;
+type D5 = D4;
+type D6 = D5;
+type D7 = D6;
+type D8 = D7;
+type D9 = D8;
+export declare class ExceedsMaxDepth {
+    value: D9;
+}
+export {};
+//# sourceMappingURL=alias-chains.d.ts.map

package/dist/__tests__/fixtures/alias-chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-chains.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/alias-chains.ts"],"names":[],"mappings":"AAIA,oBAAoB;AACpB,KAAK,OAAO,GAAG,MAAM,CAAC;AAEtB,8BAA8B;AAC9B,KAAK,UAAU,GAAG,OAAO,CAAC;AAE1B,qBAAa,aAAa;IACxB,kBAAkB;IAClB,QAAQ,EAAG,UAAU,CAAC;IACtB,WAAW,EAAG,UAAU,CAAC;CAC1B;AAID,iBAAiB;AACjB,KAAK,IAAI,GAAG,MAAM,CAAC;AAEnB,oBAAoB;AACpB,KAAK,GAAG,GAAG,IAAI,CAAC;AAEhB,oBAAoB;AACpB,KAAK,IAAI,GAAG,GAAG,CAAC;AAEhB,qBAAa,eAAe;IAC1B,KAAK,EAAG,IAAI,CAAC;CACd;AAID,qBAAa,OAAO;IAClB,iBAAiB;IACjB,KAAK,EAAG,MAAM,CAAC;CAChB;AAOD,KAAK,EAAE,GAAG,MAAM,CAAC;AACjB,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AACb,KAAK,EAAE,GAAG,EAAE,CAAC;AAEb,qBAAa,eAAe;IAC1B,KAAK,EAAG,EAAE,CAAC;CACZ"}

package/dist/__tests__/fixtures/example-a-builtins.d.ts

@@ -1,25 +1,25 @@
 export declare class ExampleAForm {
     /** @Field_displayName Full Name
      *  @Field_description Your legal name
-     *  @MinLength 2
-     *  @MaxLength 100
+     *  @minLength 2
+     *  @maxLength 100
      */
     name: string;
     /** @Field_displayName Age
-     *  @Minimum 0
-     *  @Maximum 150
+     *  @minimum 0
+     *  @maximum 150
      */
     age: number;
     /** @Field_displayName Score
-     *  @ExclusiveMinimum 0
+     *  @exclusiveMinimum 0
      */
     score: number;
     /** @Field_displayName Email
-     *  @Pattern ^[^@]+@[^@]+$
+     *  @pattern ^[^@]+@[^@]+$
      */
     email?: string;
     /** @Field_displayName Country
-     *  @EnumOptions [{"id":"us","label":"United States"},{"id":"ca","label":"Canada"}]
+     *  @enumOptions [{"id":"us","label":"United States"},{"id":"ca","label":"Canada"}]
      */
     country: "us" | "ca";
     state?: string;

package/dist/__tests__/fixtures/example-interface-types.d.ts

@@ -8,13 +8,13 @@ export interface SimpleConfig {
     /**
      * @Field_displayName Full Name
      * @Field_description The user's legal name
-     * @MinLength 1
-     * @MaxLength 200
+     * @minLength 1
+     * @maxLength 200
      */
     name: string;
-    /** @Field_displayName Age @Minimum 0 @Maximum 150 */
+    /** @Field_displayName Age @minimum 0 @maximum 150 */
     age: number;
-    /** @Field_displayName Email @Pattern ^[^@]+@[^@]+$ */
+    /** @Field_displayName Email @pattern ^[^@]+@[^@]+$ */
     email?: string;
     /** @Field_displayName Active */
     active: boolean;
@@ -22,12 +22,12 @@ export interface SimpleConfig {
 export interface WithEnumOptions {
     /**
      * @Field_displayName Status
-     * @EnumOptions ["draft","active","archived"]
+     * @enumOptions ["draft","active","archived"]
      */
     status: "draft" | "active" | "archived";
     /**
      * @Field_displayName Priority
-     * @EnumOptions [{"id":"low","label":"Low Priority"},{"id":"high","label":"High Priority"}]
+     * @enumOptions [{"id":"low","label":"Low Priority"},{"id":"high","label":"High Priority"}]
      */
     priority: "low" | "high";
 }
@@ -47,9 +47,9 @@ export interface DeprecatedFieldInterface {
     fullName: string;
 }
 export type SimpleTypeAlias = {
-    /** @Field_displayName Label @MinLength 1 */
+    /** @Field_displayName Label @minLength 1 */
     label: string;
-    /** @Field_displayName Count @Minimum 0 */
+    /** @Field_displayName Count @minimum 0 */
     count: number;
     /** @Field_displayName Description */
     description?: string;
@@ -57,17 +57,17 @@ export type SimpleTypeAlias = {
 export type TypeAliasWithEnumOptions = {
     /**
      * @Field_displayName Color
-     * @EnumOptions ["red","green","blue"]
+     * @enumOptions ["red","green","blue"]
      */
     color: "red" | "green" | "blue";
 };
 export type StringAlias = string;
 export type UnionAlias = "a" | "b" | "c";
-/** @Minimum 0 @Maximum 100 */
+/** @minimum 0 @maximum 100 */
 export type Percent = number;
-/** @MinLength 1 @MaxLength 255 @Pattern ^[^@]+@[^@]+$ */
+/** @minLength 1 @maxLength 255 @pattern ^[^@]+@[^@]+$ */
 export type Email = string;
-/** @Field_displayName Discount Rate @Field_description Percentage discount applied @Minimum 0 @Maximum 100 */
+/** @Field_displayName Discount Rate @Field_description Percentage discount applied @minimum 0 @maximum 100 */
 export type AnnotatedPercent = number;
 export interface ConfigWithAliasedTypes {
     /** @Field_displayName Discount */
@@ -78,17 +78,17 @@ export interface ConfigWithAliasedTypes {
     taxRate: AnnotatedPercent;
 }
 export interface Address {
-    /** @Field_displayName Street @MinLength 1 @MaxLength 200 */
+    /** @Field_displayName Street @minLength 1 @maxLength 200 */
     street: string;
-    /** @Field_displayName City @MinLength 1 */
+    /** @Field_displayName City @minLength 1 */
     city: string;
-    /** @Field_displayName Zip @Pattern ^[0-9]{5}$ */
+    /** @Field_displayName Zip @pattern ^[0-9]{5}$ */
     zip?: string;
 }
 export type ContactInfo = {
-    /** @Field_displayName Email @Pattern ^[^@]+@[^@]+$ */
+    /** @Field_displayName Email @pattern ^[^@]+@[^@]+$ */
     email: string;
-    /** @Field_displayName Phone @MaxLength 20 */
+    /** @Field_displayName Phone @maxLength 20 */
     phone?: string;
 };
 export interface NestedConfig {

package/dist/__tests__/json-utils.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for the shared JSON parsing utility used by the analyzer pipeline.
+ */
+export {};
+//# sourceMappingURL=json-utils.test.d.ts.map

package/dist/__tests__/json-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-utils.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/json-utils.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/path-target-parser.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unit tests for path-target extraction in TSDoc constraint tags.
+ *
+ * Covers both the low-level `extractPathTarget` helper and integration
+ * via `parseTSDocTags` to confirm that ConstraintNode objects carry the
+ * parsed `path` field when a `:identifier` prefix is present.
+ */
+export {};
+//# sourceMappingURL=path-target-parser.test.d.ts.map

package/dist/__tests__/path-target-parser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-target-parser.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/path-target-parser.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/analyzer/class-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"class-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/class-analyzer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"class-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/class-analyzer.ts"],"names":[],"mappings":"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"}

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

@@ -3,7 +3,7 @@
  *
  * 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 ConstraintNode} for set-influencing tags (@minimum, @pattern, etc.)
  * - {@link AnnotationNode} for value-influencing tags (@Field_displayName, etc.)
  *
  * The IR extraction path uses the official `@microsoft/tsdoc` parser for
@@ -12,7 +12,7 @@
  * `@Field_displayName`).
  *
  * Supported constraints correspond to keys in {@link BUILTIN_CONSTRAINT_DEFINITIONS}
- * from `@formspec/core` (e.g., `@Minimum`, `@Maximum`, `@Pattern`).
+ * from `@formspec/core` (e.g., `@minimum`, `@maximum`, `@pattern`).
  */
 import * as ts from "typescript";
 import { type ConstraintNode, type AnnotationNode } from "@formspec/core";

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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAQxB;;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,CA0CvE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,cAAc,GAAG,IAAI,CAgC9E"}

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,9 +8,11 @@
  * 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.
@@ -27,7 +29,7 @@
  * 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.
  */
@@ -42,7 +44,7 @@ export interface TSDocParseResult {
  * official TSDoc parser and returns canonical IR constraint and annotation
  * nodes.
  *
- * For constraint tags (`@Minimum`, `@Pattern`, `@EnumOptions`, etc.),
+ * 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.
@@ -58,4 +60,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAYjC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,cAAc,EAInB,KAAK,UAAU,EAChB,MAAM,gBAAgB,CAAC;AA6ExB;;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;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"}

package/dist/browser.cjs

@@ -408,8 +408,70 @@ function collectFields(elements, properties, required, ctx) {
 }
 function generateFieldSchema(field, ctx) {
   const schema = generateTypeNode(field.type, ctx);
-  applyConstraints(schema, field.constraints);
+  const directConstraints = [];
+  const pathConstraints = [];
+  for (const c of field.constraints) {
+    if (c.path) {
+      pathConstraints.push(c);
+    } else {
+      directConstraints.push(c);
+    }
+  }
+  applyConstraints(schema, directConstraints);
   applyAnnotations(schema, field.annotations);
+  if (pathConstraints.length === 0) {
+    return schema;
+  }
+  return applyPathTargetedConstraints(schema, pathConstraints);
+}
+function applyPathTargetedConstraints(schema, pathConstraints) {
+  if (schema.type === "array" && schema.items) {
+    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints);
+    return schema;
+  }
+  const byTarget = /* @__PURE__ */ new Map();
+  for (const c of pathConstraints) {
+    const target = c.path?.segments[0];
+    if (!target) continue;
+    const group = byTarget.get(target) ?? [];
+    group.push(c);
+    byTarget.set(target, group);
+  }
+  const propertyOverrides = {};
+  for (const [target, constraints] of byTarget) {
+    const subSchema = {};
+    applyConstraints(subSchema, constraints);
+    propertyOverrides[target] = subSchema;
+  }
+  if (schema.$ref) {
+    const { $ref, ...rest } = schema;
+    const refPart = { $ref };
+    const overridePart = {
+      properties: propertyOverrides,
+      ...rest
+    };
+    return { allOf: [refPart, overridePart] };
+  }
+  if (schema.type === "object" && schema.properties) {
+    const missingOverrides = {};
+    for (const [target, overrideSchema] of Object.entries(propertyOverrides)) {
+      if (schema.properties[target]) {
+        Object.assign(schema.properties[target], overrideSchema);
+      } else {
+        missingOverrides[target] = overrideSchema;
+      }
+    }
+    if (Object.keys(missingOverrides).length === 0) {
+      return schema;
+    }
+    return {
+      allOf: [schema, { properties: missingOverrides }]
+    };
+  }
+  if (schema.allOf) {
+    schema.allOf = [...schema.allOf, { properties: propertyOverrides }];
+    return schema;
+  }
   return schema;
 }
 function generateTypeNode(type, ctx) {
@@ -929,14 +991,10 @@ function addUnknownExtension(ctx, message, primary) {
   });
 }
 function findNumeric(constraints, constraintKind) {
-  return constraints.find(
-    (c) => c.constraintKind === constraintKind
-  );
+  return constraints.find((c) => c.constraintKind === constraintKind);
 }
 function findLength(constraints, constraintKind) {
-  return constraints.find(
-    (c) => c.constraintKind === constraintKind
-  );
+  return constraints.find((c) => c.constraintKind === constraintKind);
 }
 function findAllowedMembers(constraints) {
   return constraints.filter(
@@ -1060,6 +1118,17 @@ function checkTypeApplicability(ctx, fieldName, type, constraints) {
   const isEnum = type.kind === "enum";
   const label = typeLabel(type);
   for (const constraint of constraints) {
+    if (constraint.path) {
+      const isTraversable = type.kind === "object" || type.kind === "array" || type.kind === "reference";
+      if (!isTraversable) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": path-targeted constraint "${constraint.constraintKind}" is invalid because type "${label}" cannot be traversed`,
+          constraint.provenance
+        );
+      }
+      continue;
+    }
     const ck = constraint.constraintKind;
     switch (ck) {
       case "minimum":