@libar-dev/architect 1.0.0-pre.3

package/dist/validation-schemas/extracted-shape.js

@@ -0,0 +1,182 @@
+/**
+ * @architect
+ * @architect-pattern ExtractedShapeSchema
+ * @architect-status completed
+ * @architect-implements ShapeExtraction
+ *
+ * ## ExtractedShape Schema
+ *
+ * Zod schema for TypeScript type definitions extracted from source files
+ * via the @architect-extract-shapes tag.
+ *
+ * ### When to Use
+ *
+ * - When validating shapes extracted by the shape extractor
+ * - When serializing/deserializing shape data for documentation generation
+ * - When rendering API types in documentation codecs
+ */
+import { z } from 'zod';
+// =============================================================================
+// Shape Kind Enum
+// =============================================================================
+/**
+ * Kind of TypeScript construct that was extracted.
+ */
+export const ShapeKindSchema = z.enum(['interface', 'type', 'enum', 'function', 'const']);
+// =============================================================================
+// Property Documentation Schema
+// =============================================================================
+/**
+ * JSDoc documentation for an interface property.
+ *
+ * Used to capture property-level documentation from interfaces,
+ * enabling generation of description tables alongside code blocks.
+ */
+export const PropertyDocSchema = z.object({
+    /** Property name */
+    name: z.string(),
+    /** JSDoc comment text (without delimiters) */
+    jsDoc: z.string(),
+});
+// =============================================================================
+// JSDoc Tag Documentation Schemas (DD-3)
+// =============================================================================
+/**
+ * JSDoc @param tag documentation for a function parameter.
+ */
+export const ParamDocSchema = z.object({
+    /** Parameter name */
+    name: z.string(),
+    /** Type annotation from JSDoc {Type} syntax (optional in TypeScript) */
+    type: z.string().optional(),
+    /** Parameter description */
+    description: z.string(),
+});
+/**
+ * JSDoc @returns tag documentation.
+ */
+export const ReturnsDocSchema = z.object({
+    /** Return type from JSDoc {Type} syntax (optional in TypeScript) */
+    type: z.string().optional(),
+    /** Return value description */
+    description: z.string(),
+});
+/**
+ * JSDoc @throws tag documentation.
+ */
+export const ThrowsDocSchema = z.object({
+    /** Exception type from JSDoc {Type} syntax */
+    type: z.string().optional(),
+    /** Description of when this exception is thrown */
+    description: z.string(),
+});
+// =============================================================================
+// Extracted Shape Schema
+// =============================================================================
+/**
+ * A single extracted shape from TypeScript source.
+ *
+ * Represents an interface, type alias, enum, function signature, or const
+ * that was extracted via @architect-extract-shapes for documentation.
+ */
+export const ExtractedShapeSchema = z.object({
+    /** Shape name (interface/type/enum/function name) */
+    name: z.string().min(1, 'Shape name cannot be empty'),
+    /** Kind of TypeScript construct */
+    kind: ShapeKindSchema,
+    /** Extracted source text (exact from file) */
+    sourceText: z.string(),
+    /** JSDoc comment above the shape, if present */
+    jsDoc: z.string().optional(),
+    /** Line number in source file */
+    lineNumber: z.number().int().positive(),
+    /** Generic type parameters, if any (e.g., ["T", "E = Error"]) */
+    typeParameters: z.array(z.string()).readonly().optional(),
+    /** For interfaces: what it extends (e.g., ["BaseConfig", "Serializable"]) */
+    extends: z.array(z.string()).readonly().optional(),
+    /** For functions: overload signatures (excludes implementation signature) */
+    overloads: z.array(z.string()).readonly().optional(),
+    /** Whether this is an exported shape */
+    exported: z.boolean().default(true),
+    /** DD-5: Optional group name from @architect-shape tag value */
+    group: z.string().optional(),
+    /** DD-3: Cross-cutting document inclusion tags from @architect-include CSV */
+    includes: z.array(z.string().min(1)).readonly().optional(),
+    /** For interfaces: JSDoc documentation for each property */
+    propertyDocs: z.array(PropertyDocSchema).readonly().optional(),
+    /** DD-3: For functions: documented @param tags from JSDoc */
+    params: z.array(ParamDocSchema).readonly().optional(),
+    /** DD-3: For functions: documented @returns tag from JSDoc */
+    returns: ReturnsDocSchema.optional(),
+    /** DD-3: For functions: documented @throws tags from JSDoc */
+    throws: z.array(ThrowsDocSchema).readonly().optional(),
+});
+// =============================================================================
+// Re-exported Shape Schema
+// =============================================================================
+/**
+ * Information about a shape that was re-exported from another file.
+ *
+ * Re-exports are treated like imports - not extracted, but tracked
+ * so we can provide helpful warnings with source module info.
+ */
+export const ReExportedShapeSchema = z.object({
+    /** The shape name that was re-exported */
+    name: z.string(),
+    /** The source module path (e.g., './types.js') */
+    sourceModule: z.string(),
+    /** Whether it's a type-only re-export (export type { ... }) */
+    typeOnly: z.boolean().default(false),
+});
+// =============================================================================
+// Shape Extraction Result Schema
+// =============================================================================
+/**
+ * Result of shape extraction from a file.
+ */
+export const ShapeExtractionResultSchema = z.object({
+    /** Successfully extracted shapes, in requested order */
+    shapes: z.array(ExtractedShapeSchema).readonly(),
+    /** Shape names that were requested but not found */
+    notFound: z.array(z.string()).readonly(),
+    /** Shape names that exist but are imports (not defined in file) */
+    imported: z.array(z.string()).readonly(),
+    /** Shape names that are re-exported from other files */
+    reExported: z.array(ReExportedShapeSchema).readonly(),
+    /** Any warnings generated during extraction */
+    warnings: z.array(z.string()).readonly(),
+});
+// =============================================================================
+// Shape Extraction Options Schema
+// =============================================================================
+/**
+ * Options for shape extraction.
+ */
+export const ShapeExtractionOptionsSchema = z.object({
+    /** Include JSDoc comments in extraction (default: true) */
+    includeJsDoc: z.boolean().default(true),
+    /** For functions, include full signature or just name+params (default: 'signature') */
+    functionDetail: z.enum(['signature', 'name-only']).default('signature'),
+    /** Preserve original formatting vs normalize (default: true) */
+    preserveFormatting: z.boolean().default(true),
+    /** Enable JSX parsing — only for .tsx files (default: false).
+     *  Enabling for .ts files causes generic arrows like `<T>(v: T)` to be
+     *  mis-parsed as JSX elements. */
+    jsx: z.boolean().default(false),
+});
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Runtime type guard for ExtractedShape
+ */
+export function isExtractedShape(value) {
+    return ExtractedShapeSchema.safeParse(value).success;
+}
+/**
+ * Runtime type guard for ShapeExtractionResult
+ */
+export function isShapeExtractionResult(value) {
+    return ShapeExtractionResultSchema.safeParse(value).success;
+}
+//# sourceMappingURL=extracted-shape.js.map

package/dist/validation-schemas/extracted-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extracted-shape.js","sourceRoot":"","sources":["../../src/validation-schemas/extracted-shape.ts"],"names":[],"mappings":"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"}