@contractspec/integration.example-generator 1.48.1

package/README.md

@@ -0,0 +1,151 @@
+# @contractspec/integration.example-generator
+
+Example plugin for ContractSpec that generates markdown documentation from ContractSpec specifications.
+
+## Overview
+
+This plugin demonstrates how to create a ContractSpec generator plugin. It transforms structured spec definitions into human-readable markdown documentation that can be used for API docs, user guides, or technical specifications.
+
+## Features
+
+- 🚀 **Spec-First Generation**: Converts ContractSpec specs to markdown automatically
+- 📝 **Rich Formatting**: Supports tables, lists, and detail views
+- 🔧 **Configurable Output**: Customize formatting, field selection, and styling
+- 📊 **Data Integration**: Works with schema models and instance data
+- 🎯 **Type Safe**: Full TypeScript support with proper type definitions
+- 🧪 **Well Tested**: Comprehensive test suite included
+
+## Installation
+
+```bash
+npm install @contractspec/integration.example-generator
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { ExampleGeneratorPlugin } from "@contractspec/integration.example-generator";
+
+const generator = new ExampleGeneratorPlugin({
+  outputDir: "./docs",
+  format: "table", // or "list", "detail", "auto"
+  includeFields: ["id", "name", "description"],
+});
+
+// Generate markdown from specs
+await generator.generateFromSpec(specPath, outputPath);
+```
+
+### Advanced Configuration
+
+```typescript
+import { ExampleGeneratorPlugin } from "@contractspec/integration.example-generator";
+
+const generator = new ExampleGeneratorPlugin({
+  outputDir: "./docs",
+  format: "auto",
+  title: "API Documentation",
+  description: "Auto-generated API documentation",
+  maxItems: 100,
+  maxDepth: 3,
+  fieldLabels: {
+    id: "ID",
+    createdAt: "Created Date",
+    updatedAt: "Last Modified"
+  },
+  summaryFields: ["id", "name", "status"],
+  excludeFields: ["internalNotes", "metadata"]
+});
+```
+
+## Configuration Options
+
+| Option          | Type                     | Default    | Description                                              |
+| --------------- | ------------------------ | ---------- | -------------------------------------------------------- |
+| `outputDir`     | `string`                 | `"./docs"` | Directory for generated files                            |
+| `format`        | `string`                 | `"auto"`   | Output format: `"table"`, `"list"`, `"detail"`, `"auto"` |
+| `title`         | `string`                 | undefined  | Document title                                           |
+| `description`   | `string`                 | undefined  | Document description                                     |
+| `maxItems`      | `number`                 | `100`      | Maximum items to render in tables                        |
+| `maxDepth`      | `number`                 | `2`        | Maximum nesting depth for objects                        |
+| `includeFields` | `string[]`               | undefined  | Only include these fields                                |
+| `excludeFields` | `string[]`               | `[]`       | Exclude these fields from output                         |
+| `fieldLabels`   | `Record<string, string>` | undefined  | Custom field labels                                      |
+| `summaryFields` | `string[]`               | undefined  | Fields for list summaries                                |
+
+## Plugin Interface
+
+This plugin implements the ContractSpec generator interface:
+
+```typescript
+interface GeneratorPlugin {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+
+  initialize(config: GeneratorConfig): Promise<void>;
+  generate(spec: SpecDefinition, context: GeneratorContext): Promise<GeneratorResult>;
+  cleanup(): Promise<void>;
+}
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/lssm-tech/contractspec.git
+cd contractspec/packages/libs/plugins/example-generator
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build the plugin
+bun run build
+```
+
+### Testing
+
+```bash
+# Run all tests
+bun test
+
+# Run tests in watch mode
+bun test:watch
+
+# Run tests with coverage
+bun test:coverage
+```
+
+### Building
+
+```bash
+# Build the plugin
+bun run build
+
+# Build types only
+bun run build:types
+
+# Build bundle only
+bun run build:bundle
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT © ContractSpec Team
+
+## Support
+
+- 📖 [Documentation](https://contractspec.io/docs)
+- 🐛 [Issues](https://github.com/lssm-tech/contractspec/issues)
+- 💬 [Discussions](https://github.com/lssm-tech/contractspec/discussions)

package/dist/index.d.mts

@@ -0,0 +1,123 @@
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/types.d.ts
+type SpecDefinition = unknown;
+/**
+ * Configuration for the ExampleGeneratorPlugin
+ */
+interface ExampleGeneratorPluginConfig {
+  /** Directory where markdown files will be generated */
+  outputDir: string;
+  /** Output format: table, list, detail, or auto */
+  format?: 'table' | 'list' | 'detail' | 'auto';
+  /** Title for the generated documentation */
+  title?: string;
+  /** Description to include below the title */
+  description?: string;
+  /** Maximum number of items to render in tables */
+  maxItems?: number;
+  /** Maximum nesting depth for nested objects */
+  maxDepth?: number;
+  /** Only include these fields (if not specified, all fields are included) */
+  includeFields?: string[];
+  /** Exclude these fields from output */
+  excludeFields?: string[];
+  /** Custom field labels (field name -> display label) */
+  fieldLabels?: Record<string, string>;
+  /** Fields to use for summary in list format */
+  summaryFields?: string[];
+}
+/**
+ * Context provided during generation
+ */
+interface GeneratorContext {
+  /** The spec definition being processed */
+  spec: SpecDefinition;
+  /** Schema models from the spec */
+  schemas: Record<string, AnySchemaModel>;
+  /** Instance data (optional) */
+  data?: unknown;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Result of generation
+ */
+interface GeneratorResult {
+  /** Path to the generated file */
+  outputPath: string;
+  /** Number of items processed */
+  itemCount: number;
+  /** Generation metadata */
+  metadata: {
+    specId: string;
+    generatedAt: Date;
+    format: string;
+    config: Partial<ExampleGeneratorPluginConfig>;
+  };
+}
+/**
+ * Plugin metadata
+ */
+interface PluginMetadata {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly description: string;
+  readonly author: string;
+  readonly homepage?: string;
+}
+/**
+ * Error types for the plugin
+ */
+declare class ExampleGeneratorError extends Error {
+  readonly code: string;
+  readonly details?: unknown | undefined;
+  constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Validation errors
+ */
+declare class ValidationError extends ExampleGeneratorError {
+  constructor(message: string, details?: unknown);
+}
+/**
+ * Configuration errors
+ */
+declare class ConfigurationError extends ExampleGeneratorError {
+  constructor(message: string, details?: unknown);
+}
+/**
+ * Generation errors
+ */
+declare class GenerationError extends ExampleGeneratorError {
+  constructor(message: string, details?: unknown);
+}
+//#endregion
+//#region src/generator.d.ts
+declare class ExampleGeneratorPlugin {
+  private config;
+  private readonly metadata;
+  constructor(config?: Partial<ExampleGeneratorPluginConfig>);
+  getConfig(): ExampleGeneratorPluginConfig;
+  updateConfig(config: Partial<ExampleGeneratorPluginConfig>): void;
+  getMetadata(): PluginMetadata;
+  generate(context: GeneratorContext): Promise<GeneratorResult>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Default configuration for the ExampleGeneratorPlugin
+ */
+declare const defaultConfig: ExampleGeneratorPluginConfig;
+/**
+ * Merge user config with defaults
+ */
+declare function mergeConfig(userConfig: Partial<ExampleGeneratorPluginConfig>): ExampleGeneratorPluginConfig;
+/**
+ * Validate configuration
+ */
+declare function validateConfig(config: ExampleGeneratorPluginConfig): void;
+//#endregion
+export { type ConfigurationError, type ExampleGeneratorError, ExampleGeneratorPlugin, type ExampleGeneratorPluginConfig, type GenerationError, type GeneratorResult, type PluginMetadata, type ValidationError, defaultConfig, mergeConfig, validateConfig };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/generator.ts","../src/config.ts"],"sourcesContent":[],"mappings":";;;KACY,cAAA;;AAAZ;AAKA;AA0BiB,UA1BA,4BAAA,CA0BgB;EAEzB;EAEkB,SAAA,EAAA,MAAA;EAAf;EAIE,MAAA,CAAA,EAAA,OAAA,GAAA,MAAA,GAAA,QAAA,GAAA,MAAA;EAAM;EAMF,KAAA,CAAA,EAAA,MAAA;EAQA;EAEG,WAAA,CAAA,EAAA,MAAA;EAAR;EAAO,QAAA,CAAA,EAAA,MAAA;EAOF;EAYJ,QAAA,CAAA,EAAA,MAAA;EAcA;EAUA,aAAA,CAAA,EAAA,MAAmB,EAAA;EAUnB;;;gBArFG;ECdH;EAIiB,aAAA,CAAA,EAAA,MAAA,EAAA;;;;;AAuBb,UDLA,gBAAA,CCKA;EAIS;EAA2B,IAAA,EDP7C,cCO6C;EAAR;EAAO,OAAA,EDLzC,MCKyC,CAAA,MAAA,EDL1B,cCK0B,CAAA;;;;ECpCvC,QAAA,CAAA,EFmCA,ME7BZ,CAAA,MAAA,EAAA,OAN2B,CAAA;AAW5B;;;;AAE+B,UF4Bd,eAAA,CE5Bc;EAUf;;;;;;;iBF0BC;;YAEL,QAAQ;;;;;;UAOH,cAAA;;;;;;;;;;;cAYJ,qBAAA,SAA8B,KAAA;;;;;;;;cAc9B,eAAA,SAAwB,qBAAA;;;;;;cAUxB,kBAAA,SAA2B,qBAAA;;;;;;cAU3B,eAAA,SAAwB,qBAAA;;;;;cCnGxB,sBAAA;;EDTD,iBAAc,QAAA;EAKT,WAAA,CAAA,MAkBK,CAlBL,ECQK,ODRL,CCQa,4BDUR,CAAA;EAQL,SAAA,CAAA,CAAA,ECLF,4BDKkB;EAEzB,YAAA,CAAA,MAAA,ECHe,ODGf,CCHuB,4BDGvB,CAAA,CAAA,EAAA,IAAA;EAEkB,WAAA,CAAA,CAAA,ECCT,cDDS;EAAf,QAAA,CAAA,OAAA,ECKe,gBDLf,CAAA,ECKkC,ODLlC,CCK0C,eDL1C,CAAA;;;;;;AAnCX;AAKiB,cEDJ,aFCI,EEDW,4BFmBN;AAQtB;;;AAIW,iBEpBK,WAAA,CFoBL,UAAA,EEnBG,OFmBH,CEnBW,4BFmBX,CAAA,CAAA,EElBR,4BFkBQ;;;AAUX;AAQiB,iBE1BD,cAAA,CF0BC,MAAA,EE1BsB,4BF0BtB,CAAA,EAAA,IAAA"}

package/dist/index.mjs

@@ -0,0 +1,91 @@
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+
+//#region src/config.ts
+/**
+* Default configuration for the ExampleGeneratorPlugin
+*/
+const defaultConfig = {
+	outputDir: "./docs",
+	format: "auto",
+	maxItems: 100,
+	maxDepth: 2,
+	excludeFields: []
+};
+/**
+* Merge user config with defaults
+*/
+function mergeConfig(userConfig) {
+	return {
+		...defaultConfig,
+		...userConfig
+	};
+}
+/**
+* Validate configuration
+*/
+function validateConfig(config) {
+	if (!config.outputDir) throw new Error("outputDir is required");
+	if (config.format && ![
+		"table",
+		"list",
+		"detail",
+		"auto"
+	].includes(config.format)) throw new Error("format must be one of: table, list, detail, auto");
+	if (config.maxItems !== void 0 && config.maxItems < 1) throw new Error("maxItems must be greater than 0");
+	if (config.maxDepth !== void 0 && config.maxDepth < 1) throw new Error("maxDepth must be greater than 0");
+}
+
+//#endregion
+//#region src/generator.ts
+var ExampleGeneratorPlugin = class {
+	config;
+	metadata;
+	constructor(config = {}) {
+		const merged = mergeConfig(config);
+		validateConfig(merged);
+		this.config = merged;
+		this.metadata = {
+			id: "example-generator",
+			name: "@contractspec/integration.example-generator",
+			version: "1.0.0",
+			description: "Example markdown documentation generator",
+			author: "ContractSpec"
+		};
+	}
+	getConfig() {
+		return { ...this.config };
+	}
+	updateConfig(config) {
+		const merged = mergeConfig({
+			...this.config,
+			...config
+		});
+		validateConfig(merged);
+		this.config = merged;
+	}
+	getMetadata() {
+		return { ...this.metadata };
+	}
+	async generate(context) {
+		if (!context.spec) throw new Error("Spec is required to generate documentation");
+		const outputDir = this.config.outputDir;
+		mkdirSync(outputDir, { recursive: true });
+		const outputPath = join(outputDir, "spec-" + Date.now() + ".md");
+		writeFileSync(outputPath, `# Spec Documentation\n\nGenerated for spec: ${String(context.spec.id ?? "unknown")}`, "utf8");
+		return {
+			outputPath,
+			itemCount: 1,
+			metadata: {
+				specId: String(context.spec.id ?? "unknown"),
+				generatedAt: /* @__PURE__ */ new Date(),
+				format: this.config.format ?? "auto",
+				config: this.config
+			}
+		};
+	}
+};
+
+//#endregion
+export { ExampleGeneratorPlugin, defaultConfig, mergeConfig, validateConfig };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/config.ts","../src/generator.ts"],"sourcesContent":["import type { ExampleGeneratorPluginConfig } from './types.js';\n\n/**\n * Default configuration for the ExampleGeneratorPlugin\n */\nexport const defaultConfig: ExampleGeneratorPluginConfig = {\n  outputDir: './docs',\n  format: 'auto',\n  maxItems: 100,\n  maxDepth: 2,\n  excludeFields: [],\n};\n\n/**\n * Merge user config with defaults\n */\nexport function mergeConfig(\n  userConfig: Partial<ExampleGeneratorPluginConfig>\n): ExampleGeneratorPluginConfig {\n  return {\n    ...defaultConfig,\n    ...userConfig,\n  };\n}\n\n/**\n * Validate configuration\n */\nexport function validateConfig(config: ExampleGeneratorPluginConfig): void {\n  if (!config.outputDir) {\n    throw new Error('outputDir is required');\n  }\n\n  if (\n    config.format &&\n    !['table', 'list', 'detail', 'auto'].includes(config.format)\n  ) {\n    throw new Error('format must be one of: table, list, detail, auto');\n  }\n\n  if (config.maxItems !== undefined && config.maxItems < 1) {\n    throw new Error('maxItems must be greater than 0');\n  }\n\n  if (config.maxDepth !== undefined && config.maxDepth < 1) {\n    throw new Error('maxDepth must be greater than 0');\n  }\n}\n","import { mkdirSync, writeFileSync } from 'fs';\nimport { join } from 'path';\nimport { mergeConfig, validateConfig } from './config.js';\nimport type {\n  ExampleGeneratorPluginConfig,\n  GeneratorContext,\n  GeneratorResult,\n  PluginMetadata,\n} from './types.js';\n\nexport class ExampleGeneratorPlugin {\n  private config: ExampleGeneratorPluginConfig;\n  private readonly metadata: PluginMetadata;\n\n  constructor(config: Partial<ExampleGeneratorPluginConfig> = {}) {\n    const merged = mergeConfig(config);\n    validateConfig(merged);\n    this.config = merged;\n    this.metadata = {\n      id: 'example-generator',\n      name: '@contractspec/integration.example-generator',\n      version: '1.0.0',\n      description: 'Example markdown documentation generator',\n      author: 'ContractSpec',\n    };\n  }\n\n  getConfig(): ExampleGeneratorPluginConfig {\n    return { ...this.config };\n  }\n\n  updateConfig(config: Partial<ExampleGeneratorPluginConfig>): void {\n    const merged = mergeConfig({ ...this.config, ...config });\n    validateConfig(merged);\n    this.config = merged;\n  }\n\n  getMetadata(): PluginMetadata {\n    return { ...this.metadata };\n  }\n\n  async generate(context: GeneratorContext): Promise<GeneratorResult> {\n    if (!context.spec) {\n      throw new Error('Spec is required to generate documentation');\n    }\n\n    const outputDir = this.config.outputDir;\n    mkdirSync(outputDir, { recursive: true });\n\n    const fileName = 'spec-' + Date.now() + '.md';\n    const outputPath = join(outputDir, fileName);\n    const content = `# Spec Documentation\\n\\nGenerated for spec: ${String(\n      (context.spec as { id?: string }).id ?? 'unknown'\n    )}`;\n\n    writeFileSync(outputPath, content, 'utf8');\n\n    return {\n      outputPath,\n      itemCount: 1,\n      metadata: {\n        specId: String((context.spec as { id?: string }).id ?? 'unknown'),\n        generatedAt: new Date(),\n        format: this.config.format ?? 'auto',\n        config: this.config,\n      },\n    };\n  }\n}\n"],"mappings":";;;;;;;AAKA,MAAa,gBAA8C;CACzD,WAAW;CACX,QAAQ;CACR,UAAU;CACV,UAAU;CACV,eAAe,EAAE;CAClB;;;;AAKD,SAAgB,YACd,YAC8B;AAC9B,QAAO;EACL,GAAG;EACH,GAAG;EACJ;;;;;AAMH,SAAgB,eAAe,QAA4C;AACzE,KAAI,CAAC,OAAO,UACV,OAAM,IAAI,MAAM,wBAAwB;AAG1C,KACE,OAAO,UACP,CAAC;EAAC;EAAS;EAAQ;EAAU;EAAO,CAAC,SAAS,OAAO,OAAO,CAE5D,OAAM,IAAI,MAAM,mDAAmD;AAGrE,KAAI,OAAO,aAAa,UAAa,OAAO,WAAW,EACrD,OAAM,IAAI,MAAM,kCAAkC;AAGpD,KAAI,OAAO,aAAa,UAAa,OAAO,WAAW,EACrD,OAAM,IAAI,MAAM,kCAAkC;;;;;ACnCtD,IAAa,yBAAb,MAAoC;CAClC,AAAQ;CACR,AAAiB;CAEjB,YAAY,SAAgD,EAAE,EAAE;EAC9D,MAAM,SAAS,YAAY,OAAO;AAClC,iBAAe,OAAO;AACtB,OAAK,SAAS;AACd,OAAK,WAAW;GACd,IAAI;GACJ,MAAM;GACN,SAAS;GACT,aAAa;GACb,QAAQ;GACT;;CAGH,YAA0C;AACxC,SAAO,EAAE,GAAG,KAAK,QAAQ;;CAG3B,aAAa,QAAqD;EAChE,MAAM,SAAS,YAAY;GAAE,GAAG,KAAK;GAAQ,GAAG;GAAQ,CAAC;AACzD,iBAAe,OAAO;AACtB,OAAK,SAAS;;CAGhB,cAA8B;AAC5B,SAAO,EAAE,GAAG,KAAK,UAAU;;CAG7B,MAAM,SAAS,SAAqD;AAClE,MAAI,CAAC,QAAQ,KACX,OAAM,IAAI,MAAM,6CAA6C;EAG/D,MAAM,YAAY,KAAK,OAAO;AAC9B,YAAU,WAAW,EAAE,WAAW,MAAM,CAAC;EAGzC,MAAM,aAAa,KAAK,WADP,UAAU,KAAK,KAAK,GAAG,MACI;AAK5C,gBAAc,YAJE,+CAA+C,OAC5D,QAAQ,KAAyB,MAAM,UACzC,IAEkC,OAAO;AAE1C,SAAO;GACL;GACA,WAAW;GACX,UAAU;IACR,QAAQ,OAAQ,QAAQ,KAAyB,MAAM,UAAU;IACjE,6BAAa,IAAI,MAAM;IACvB,QAAQ,KAAK,OAAO,UAAU;IAC9B,QAAQ,KAAK;IACd;GACF"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@contractspec/integration.example-generator",
+  "version": "1.48.1",
+  "description": "Example plugin: Markdown documentation generator for ContractSpec specs",
+  "keywords": [
+    "contractspec",
+    "plugin",
+    "generator",
+    "markdown",
+    "documentation",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./types": "./dist/types.js",
+    "./generator": "./dist/generator.js",
+    "./config": "./dist/config.js",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "@contractspec/lib.contracts": "1.48.1",
+    "@contractspec/lib.schema": "1.48.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.48.0",
+    "@contractspec/tool.typescript": "1.48.0",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.1"
+  },
+  "peerDependencies": {
+    "@contractspec/lib.contracts": "^1.0.0",
+    "@contractspec/lib.schema": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/integrations/example-generator"
+  },
+  "homepage": "https://contractspec.io",
+  "bugs": {
+    "url": "https://github.com/lssm-tech/contractspec/issues"
+  },
+  "author": {
+    "name": "ContractSpec Team",
+    "email": "team@contractspec.io"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  }
+}