@formspec/build 0.1.0-alpha.5 → 0.1.0-alpha.51

package/dist/analyzer/program.d.ts

@@ -0,0 +1,97 @@
+/**
+ * TypeScript program setup for static analysis.
+ *
+ * Creates a TypeScript program with type checker from a source file,
+ * using the project's tsconfig.json for compiler options.
+ */
+import * as ts from "typescript";
+import type { ConstraintSemanticDiagnostic } from "@formspec/analysis/internal";
+import { type DiscriminatorResolutionOptions, type IRClassAnalysis } from "./class-analyzer.js";
+import type { ExtensionRegistry } from "../extensions/index.js";
+import type { MetadataPolicyInput } from "@formspec/core";
+/**
+ * Result of creating a TypeScript program for analysis.
+ */
+export interface ProgramContext {
+    /** The TypeScript program */
+    program: ts.Program;
+    /** Type checker for resolving types */
+    checker: ts.TypeChecker;
+    /** The source file being analyzed */
+    sourceFile: ts.SourceFile;
+}
+export type AnalyzeNamedTypeToIRDetailedResult = {
+    readonly ok: true;
+    readonly analysis: IRClassAnalysis;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly ConstraintSemanticDiagnostic[];
+};
+/**
+ * Resolves a source file and checker from an existing TypeScript program.
+ *
+ * @param program - Existing TypeScript program supplied by the host
+ * @param filePath - Absolute or relative path to the TypeScript source file
+ * @returns Program context with checker and source file
+ */
+export declare function createProgramContextFromProgram(program: ts.Program, filePath: string): ProgramContext;
+/**
+ * Creates a TypeScript program for analyzing a source file.
+ *
+ * Looks for tsconfig.json in the file's directory or parent directories.
+ * Falls back to default compiler options if no config is found.
+ *
+ * @param filePath - Absolute path to the TypeScript source file
+ * @param additionalFiles - Optional additional files to include in the program
+ *   (e.g., the FormSpec config file for symbol-based custom type detection).
+ *   Duplicates are silently removed.
+ * @returns Program context with checker and source file
+ */
+export declare function createProgramContext(filePath: string, additionalFiles?: readonly string[]): ProgramContext;
+/**
+ * Finds a class declaration by name in a source file.
+ *
+ * @param sourceFile - The source file to search
+ * @param className - Name of the class to find
+ * @returns The class declaration node, or null if not found
+ */
+export declare function findClassByName(sourceFile: ts.SourceFile, className: string): ts.ClassDeclaration | null;
+/**
+ * Finds an interface declaration by name in a source file.
+ *
+ * @param sourceFile - The source file to search
+ * @param interfaceName - Name of the interface to find
+ * @returns The interface declaration node, or null if not found
+ */
+export declare function findInterfaceByName(sourceFile: ts.SourceFile, interfaceName: string): ts.InterfaceDeclaration | null;
+/**
+ * Finds a type alias declaration by name in a source file.
+ *
+ * @param sourceFile - The source file to search
+ * @param aliasName - Name of the type alias to find
+ * @returns The type alias declaration node, or null if not found
+ */
+export declare function findTypeAliasByName(sourceFile: ts.SourceFile, aliasName: string): ts.TypeAliasDeclaration | null;
+/**
+ * Analyzes a named type (class, interface, or type alias) from a TypeScript
+ * source file and returns an `IRClassAnalysis`.
+ *
+ * Tries each declaration kind in order: class → interface → type alias.
+ * Throws if the name is not found or if the type alias analysis fails.
+ *
+ * @param filePath - Absolute or relative path to the TypeScript source file (resolved internally)
+ * @param typeName - Name of the class, interface, or type alias to analyze
+ * @param extensionRegistry - Optional extension registry for custom type handling
+ * @returns IR analysis result
+ */
+export declare function analyzeNamedTypeToIR(filePath: string, typeName: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): IRClassAnalysis;
+/**
+ * Analyzes a named type from an existing program context and returns either an
+ * `IRClassAnalysis` or structured diagnostics instead of throwing.
+ */
+export declare function analyzeNamedTypeToIRFromProgramContextDetailed(ctx: ProgramContext, filePath: string, typeName: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): AnalyzeNamedTypeToIRDetailedResult;
+/**
+ * Analyzes a named type from an existing program context and returns an `IRClassAnalysis`.
+ */
+export declare function analyzeNamedTypeToIRFromProgramContext(ctx: ProgramContext, filePath: string, typeName: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): IRClassAnalysis;
+//# sourceMappingURL=program.d.ts.map

package/dist/analyzer/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/analyzer/program.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EASL,KAAK,8BAA8B,EACnC,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC;IACxB,qCAAqC;IACrC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;CAC3B;AAED,MAAM,MAAM,kCAAkC,GAC1C;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,GACzD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,QAAQ,EAAE,MAAM,GACf,cAAc,CAahB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,cAAc,CA8DhB;AA6BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,gBAAgB,GAAG,IAAI,CAE5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,aAAa,EAAE,MAAM,GACpB,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAEhC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAEhC;AAoID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,eAAe,CAUjB;AAED;;;GAGG;AACH,wBAAgB,8CAA8C,CAC5D,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,kCAAkC,CA0IpC;AAED;;GAEG;AACH,wBAAgB,sCAAsC,CACpD,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,eAAe,CAcjB"}

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

@@ -0,0 +1,124 @@
+/**
+ * TSDoc-based structured tag parser.
+ *
+ * Bridges the TypeScript compiler AST with the official `@microsoft/tsdoc`
+ * parser to extract constraint and annotation tags from JSDoc comments
+ * on class/interface/type-alias properties.
+ *
+ * The parser recognises two categories of tags:
+ *
+ * 1. **Constraint tags** (all alphanumeric, TSDoc-compliant):
+ *    `@minimum`, `@maximum`, `@exclusiveMinimum`, `@exclusiveMaximum`,
+ *    `@multipleOf`, `@minLength`, `@maxLength`, `@minItems`, `@maxItems`,
+ *    `@uniqueItems`, `@pattern`, `@enumOptions`, `@const`
+ *    — Parsed via TSDocParser as custom block tags.
+ *    Both camelCase and PascalCase forms are accepted (e.g., `@Minimum`).
+ *
+ * 2. **Metadata and annotation tags** (`@apiName`, `@displayName`,
+ *    `@format`, `@placeholder`):
+ *    These are parsed as structured custom block tags so summary extraction
+ *    stops at recognized FormSpec tags. `@displayName`, `@format`, and
+ *    `@placeholder` also map onto annotation IR nodes, while `@apiName`
+ *    remains metadata-only and is resolved separately by the class analyzer.
+ *
+ * The `@deprecated` tag is a standard TSDoc block tag, parsed structurally.
+ *
+ * Description and remarks extraction (spec 002 §2.3):
+ * - Summary text (bare text before the first block tag) → `description` annotation
+ * - `@remarks` block → `remarks` annotation (separate channel)
+ * - `@description` is NOT supported (not a standard TSDoc tag)
+ *
+ * **Fallback strategy**: TSDoc treats `{` / `}` as inline tag delimiters and
+ * `@` as a tag prefix, so content containing these characters (e.g. JSON
+ * objects in `@EnumOptions`, regex patterns with `@` in `@Pattern`) gets
+ * mangled by the TSDoc parser. The shared comment syntax parser is the
+ * primary source for these payloads; the TS compiler's `ts.getJSDocTags()`
+ * API remains as a fallback when a raw payload cannot be recovered from the
+ * shared parse.
+ */
+import * as ts from "typescript";
+import { type ConstraintSemanticDiagnostic } from "@formspec/analysis/internal";
+import { type ConstraintNode, type AnnotationNode, type PathTarget, type TypeNode } from "@formspec/core/internals";
+import type { ExtensionRegistry } from "../extensions/index.js";
+/**
+ * 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 canonical TSDoc block tags. */
+    readonly annotations: readonly AnnotationNode[];
+    /** Compiler-backed extraction diagnostics for invalid tag applications. */
+    readonly diagnostics: readonly ConstraintSemanticDiagnostic[];
+}
+/**
+ * Optional extension-aware parsing inputs for TSDoc extraction.
+ */
+export interface ParseTSDocOptions {
+    /**
+     * Extension registry used to resolve custom tags and custom-type-specific
+     * broadening of built-in constraint tags.
+     */
+    readonly extensionRegistry?: ExtensionRegistry;
+    /**
+     * Effective field/type node for the declaration being parsed. Required when
+     * built-in tags may broaden onto a custom type.
+     */
+    readonly fieldType?: TypeNode;
+    /** Type checker used for compiler-backed placement and type validation. */
+    readonly checker?: ts.TypeChecker;
+    /** The declaration type that the parsed tag applies to. */
+    readonly subjectType?: ts.Type;
+    /** Optional enclosing host type for future cross-field signature checks. */
+    readonly hostType?: ts.Type;
+}
+/**
+ * Display-name metadata extracted from a node's JSDoc tags.
+ *
+ * The root display name is returned separately from member-target labels so
+ * callers can apply the former to the enclosing type/form and the latter to
+ * enum members.
+ */
+export interface DisplayNameMetadata {
+    readonly displayName?: string;
+    readonly memberDisplayNames: ReadonlyMap<string, string>;
+}
+/**
+ * Parses the JSDoc comment attached to a TypeScript AST node using the
+ * unified comment parser and returns canonical IR constraint and annotation
+ * nodes.
+ *
+ * For constraint tags (`@minimum`, `@pattern`, `@enumOptions`, etc.),
+ * the unified parser provides aligned span and TSDoc block information.
+ * Canonical annotation tags (`@displayName`) are also parsed structurally.
+ * Summary text and `@remarks` are extracted as separate annotation nodes.
+ *
+ * @param node - The TS AST node to inspect (PropertyDeclaration, PropertySignature, etc.)
+ * @param file - Absolute source file path for provenance
+ * @returns Parsed constraint and annotation nodes
+ */
+export declare function parseTSDocTags(node: ts.Node, file?: string, options?: ParseTSDocOptions): TSDocParseResult;
+/**
+ * Checks if a TS AST node has a `@deprecated` tag using the unified parser.
+ */
+export declare function hasDeprecatedTagTSDoc(node: ts.Node): boolean;
+/**
+ * Extracts root and member-target display-name metadata from a node's JSDoc tags.
+ *
+ * Member-target display-name tags use the syntax `@displayName :member Label`.
+ * The first non-target `@displayName` is returned as the root display name.
+ */
+export declare function extractDisplayNameMetadata(node: ts.Node): DisplayNameMetadata;
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc-parser.d.ts","sourceRoot":"","sources":["../../src/analyzer/tsdoc-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAcL,KAAK,4BAA4B,EAIlC,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA6vBhE;;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;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1D;AA2DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAyNlB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAkB5D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,mBAAmB,CAmC7E;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEpD"}