@contractspec/lib.source-extractors 0.0.0-canary-20260119222405

package/dist/types.d.ts

@@ -0,0 +1,272 @@
+//#region src/types.d.ts
+/**
+ * Intermediate Representation (IR) types for source extraction.
+ *
+ * The IR provides a framework-agnostic representation of API endpoints,
+ * schemas, errors, and events discovered in source code.
+ */
+/**
+ * Confidence level for extracted candidates.
+ * Indicates how certain we are about the extraction.
+ */
+type ConfidenceLevel = 'high' | 'medium' | 'low' | 'ambiguous';
+/**
+ * Reason for the assigned confidence level.
+ */
+type ConfidenceReason = 'explicit-schema' | 'explicit-decorator' | 'inferred-types' | 'decorator-hints' | 'naming-convention' | 'missing-schema' | 'partial-extraction';
+/**
+ * Source location information.
+ */
+interface SourceLocation {
+  /** File path (relative to project root) */
+  file: string;
+  /** Start line number (1-indexed) */
+  startLine: number;
+  /** End line number (1-indexed) */
+  endLine: number;
+  /** Optional column information */
+  startColumn?: number;
+  endColumn?: number;
+}
+/**
+ * HTTP method types.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Operation kind derived from HTTP method or explicit annotation.
+ */
+type OpKind = 'command' | 'query';
+/**
+ * Confidence metadata attached to extracted items.
+ */
+interface ConfidenceMeta {
+  level: ConfidenceLevel;
+  reasons: ConfidenceReason[];
+  notes?: string[];
+}
+/**
+ * Schema candidate extracted from source code.
+ * Can represent Zod schemas, class-validator DTOs, JSON Schema, etc.
+ */
+interface SchemaCandidate {
+  /** Unique identifier for this schema */
+  id: string;
+  /** Schema name (e.g., class name, export name) */
+  name: string;
+  /** Type of schema source */
+  schemaType: 'zod' | 'class-validator' | 'json-schema' | 'typebox' | 'typescript' | 'unknown';
+  /** Raw schema definition (for Zod, the code; for class-validator, the class def) */
+  rawDefinition?: string;
+  /** Parsed fields if available */
+  fields?: SchemaField[];
+  /** Source location */
+  source: SourceLocation;
+  /** Confidence in this extraction */
+  confidence: ConfidenceMeta;
+}
+/**
+ * Individual field in a schema.
+ */
+interface SchemaField {
+  name: string;
+  type: string;
+  optional: boolean;
+  description?: string;
+  validation?: string[];
+}
+/**
+ * Endpoint candidate extracted from source code.
+ * Represents an API route/handler.
+ */
+interface EndpointCandidate {
+  /** Unique identifier for this endpoint */
+  id: string;
+  /** HTTP method */
+  method: HttpMethod;
+  /** Route path (e.g., '/users/:id') */
+  path: string;
+  /** Operation kind (command/query) */
+  kind: OpKind;
+  /** Handler function name */
+  handlerName: string;
+  /** Controller/router name if applicable */
+  controllerName?: string;
+  /** Input schema reference */
+  input?: SchemaRef;
+  /** Output schema reference */
+  output?: SchemaRef;
+  /** Path parameters */
+  pathParams?: SchemaRef;
+  /** Query parameters */
+  queryParams?: SchemaRef;
+  /** Associated errors */
+  errors?: ErrorRef[];
+  /** Framework-specific metadata */
+  frameworkMeta?: Record<string, unknown>;
+  /** Source location */
+  source: SourceLocation;
+  /** Confidence in this extraction */
+  confidence: ConfidenceMeta;
+}
+/**
+ * Reference to a schema (either inline or by ID).
+ */
+interface SchemaRef {
+  /** Reference to a SchemaCandidate.id */
+  ref?: string;
+  /** Inline schema definition if not a reference */
+  inline?: SchemaCandidate;
+}
+/**
+ * Error candidate extracted from source code.
+ */
+interface ErrorCandidate {
+  /** Unique identifier for this error */
+  id: string;
+  /** Error name/code */
+  name: string;
+  /** HTTP status code if applicable */
+  httpStatus?: number;
+  /** Error description */
+  description?: string;
+  /** Error payload schema if any */
+  payload?: SchemaRef;
+  /** Source location */
+  source: SourceLocation;
+  /** Confidence in this extraction */
+  confidence: ConfidenceMeta;
+}
+/**
+ * Reference to an error.
+ */
+interface ErrorRef {
+  /** Reference to an ErrorCandidate.id */
+  ref?: string;
+  /** Condition when this error is thrown */
+  when?: string;
+}
+/**
+ * Event candidate extracted from source code.
+ */
+interface EventCandidate {
+  /** Unique identifier for this event */
+  id: string;
+  /** Event name/key */
+  name: string;
+  /** Event payload schema */
+  payload?: SchemaRef;
+  /** Source location */
+  source: SourceLocation;
+  /** Confidence in this extraction */
+  confidence: ConfidenceMeta;
+}
+/**
+ * Ambiguity detected during extraction.
+ * Used to flag items that need human review.
+ */
+interface Ambiguity {
+  /** Type of ambiguous item */
+  type: 'endpoint' | 'schema' | 'error' | 'event';
+  /** Reference to the item ID */
+  itemId: string;
+  /** Description of the ambiguity */
+  description: string;
+  /** Suggested resolution */
+  suggestion?: string;
+  /** Source location */
+  source: SourceLocation;
+}
+/**
+ * Framework detection result.
+ */
+interface FrameworkInfo {
+  /** Framework identifier */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Version if detected */
+  version?: string;
+  /** Detection confidence */
+  confidence: ConfidenceLevel;
+}
+/**
+ * Project information used for extraction.
+ */
+interface ProjectInfo {
+  /** Project root path */
+  rootPath: string;
+  /** Detected frameworks */
+  frameworks: FrameworkInfo[];
+  /** TypeScript config path if found */
+  tsConfigPath?: string;
+  /** Package.json path if found */
+  packageJsonPath?: string;
+}
+/**
+ * Options for extraction.
+ */
+interface ExtractOptions {
+  /** Force a specific framework */
+  framework?: string;
+  /** Limit extraction to specific paths (glob patterns) */
+  scope?: string[];
+  /** Exclude paths (glob patterns) */
+  exclude?: string[];
+  /** Include node_modules */
+  includeNodeModules?: boolean;
+  /** Extraction mode */
+  mode?: 'full' | 'endpoints-only' | 'schemas-only';
+}
+/**
+ * The complete Intermediate Representation of extracted contracts.
+ */
+interface ImportIR {
+  /** IR schema version */
+  version: '1.0';
+  /** Extraction timestamp (ISO 8601) */
+  extractedAt: string;
+  /** Project information */
+  project: ProjectInfo;
+  /** Extracted endpoints */
+  endpoints: EndpointCandidate[];
+  /** Extracted schemas */
+  schemas: SchemaCandidate[];
+  /** Extracted errors */
+  errors: ErrorCandidate[];
+  /** Extracted events */
+  events: EventCandidate[];
+  /** Detected ambiguities requiring review */
+  ambiguities: Ambiguity[];
+  /** Extraction statistics */
+  stats: {
+    filesScanned: number;
+    endpointsFound: number;
+    schemasFound: number;
+    errorsFound: number;
+    eventsFound: number;
+    ambiguitiesFound: number;
+    highConfidence: number;
+    mediumConfidence: number;
+    lowConfidence: number;
+  };
+}
+/**
+ * Result of an extraction operation.
+ */
+interface ExtractResult {
+  success: boolean;
+  ir?: ImportIR;
+  errors?: ExtractError[];
+}
+/**
+ * Error during extraction.
+ */
+interface ExtractError {
+  code: string;
+  message: string;
+  source?: SourceLocation;
+  recoverable: boolean;
+}
+//#endregion
+export { Ambiguity, ConfidenceLevel, ConfidenceMeta, ConfidenceReason, EndpointCandidate, ErrorCandidate, ErrorRef, EventCandidate, ExtractError, ExtractOptions, ExtractResult, FrameworkInfo, HttpMethod, ImportIR, OpKind, ProjectInfo, SchemaCandidate, SchemaField, SchemaRef, SourceLocation };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;AAWA;AAKA;AAYA;AAeA;AAYA;AAKA;AAUA;;;AAoBc,KA/EF,eAAA,GA+EE,MAAA,GAAA,QAAA,GAAA,KAAA,GAAA,WAAA;;AAMd;AAYA;AAIU,KAhGE,gBAAA,GAgGF,iBAAA,GAAA,oBAAA,GAAA,gBAAA,GAAA,iBAAA,GAAA,mBAAA,GAAA,gBAAA,GAAA,oBAAA;;;;AAcK,UAlGE,cAAA,CAkGF;EAEC;EAEL,IAAA,EAAA,MAAA;EAEO;EAER,SAAA,EAAA,MAAA;EAEI;EAAc,OAAA,EAAA,MAAA;EAMX;EAUA,WAAA,CAAA,EAAA,MAAc;EAUnB,SAAA,CAAA,EAAA,MAAA;;;;AAUZ;AAUiB,KA3IL,UAAA,GA2ImB,KAAA,GAAA,MAAA,GAAA,KAAA,GAAA,OAAA,GAAA,QAAA,GAAA,MAAA,GAAA,SAAA;;;;AAUH,KAzIhB,MAAA,GAyIgB,SAAA,GAAA,OAAA;AAO5B;AAgBA;AAcA;AAciB,UAvLA,cAAA,CAuLc;EAgBd,KAAA,EAtMR,eAsMgB;EAMd,OAAA,EA3MA,gBA2MA,EAAA;EAEE,KAAA,CAAA,EAAA,MAAA,EAAA;;;;;;AA0BI,UA/NA,eAAA,CAiOV;EAOU;;;;;;;;;WAxNN;;UAED;;cAEI;;;;;UAMG,WAAA;;;;;;;;;;;UAYA,iBAAA;;;;UAIP;;;;QAIF;;;;;;UAME;;WAEC;;eAEI;;gBAEC;;WAEL;;kBAEO;;UAER;;cAEI;;;;;UAMG,SAAA;;;;WAIN;;;;;UAMM,cAAA;;;;;;;;;;YAUL;;UAEF;;cAEI;;;;;UAMG,QAAA;;;;;;;;;UAUA,cAAA;;;;;;YAML;;UAEF;;cAEI;;;;;;UAOG,SAAA;;;;;;;;;;UAUP;;;;;UAMO,aAAA;;;;;;;;cAQH;;;;;UAMG,WAAA;;;;cAIH;;;;;;;;;UAUG,cAAA;;;;;;;;;;;;;;;UAgBA,QAAA;;;;;;WAMN;;aAEE;;WAEF;;UAED;;UAEA;;eAEK;;;;;;;;;;;;;;;;;UAkBE,aAAA;;OAEV;WACI;;;;;UAMM,YAAA;;;WAGN"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@contractspec/lib.source-extractors",
+  "version": "0.0.0-canary-20260119222405",
+  "description": "Extract contract candidates from TypeScript source code across multiple frameworks (NestJS, Express, Fastify, Hono, Elysia, tRPC, Next.js)",
+  "keywords": [
+    "contractspec",
+    "source-extraction",
+    "nestjs",
+    "express",
+    "fastify",
+    "hono",
+    "elysia",
+    "trpc",
+    "typescript"
+  ],
+  "type": "module",
+  "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"
+  },
+  "dependencies": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260119222405",
+    "@contractspec/lib.schema": "1.48.0",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.48.0",
+    "@contractspec/tool.typescript": "1.48.0",
+    "tsdown": "^0.19.0"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./codegen": "./dist/codegen/index.js",
+    "./extractors": "./dist/extractors/index.js",
+    "./types": "./dist/types.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./types": "./dist/types.js",
+      "./extractors": "./dist/extractors/index.js",
+      "./codegen": "./dist/codegen/index.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/libs/source-extractors"
+  },
+  "homepage": "https://contractspec.io"
+}