speckeeper 0.4.1 → 0.6.0

package/dist/dsl/index.js

@@ -1,3 +1,633 @@
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'fs';
+import { join, isAbsolute } from 'path';
+import { glob } from 'glob';
+import { parse } from 'yaml';
+import nodeSqlParser from 'node-sql-parser';
 
+// src/core/dsl/schema.ts
+var RELATION_TYPES = [
+  "dependsOn",
+  "uses",
+  "includes",
+  "implements",
+  "refines",
+  "verifies",
+  "verifiedBy",
+  "satisfies",
+  "traces",
+  "relatedTo"
+];
+var RelationSchema = z.object({
+  /** Relation type */
+  type: z.enum(RELATION_TYPES),
+  /** Target ID */
+  target: z.string(),
+  /** Description (optional) */
+  description: z.string().optional()
+});
+z.array(RelationSchema).optional();
+
+// src/core/dsl/schema.ts
+var baseSpecSchema = z.object({
+  id: z.string(),
+  name: z.string().min(1),
+  description: z.string(),
+  relations: z.array(RelationSchema).optional()
+});
+
+// src/core/dsl/lint-rules.ts
+function requireField(field, severity = "warning") {
+  return {
+    id: `has-${field}`,
+    severity,
+    message: `${field} must not be empty`,
+    check: (spec) => {
+      const value = spec[field];
+      return !value || typeof value === "string" && value.trim() === "";
+    }
+  };
+}
+function arrayMinLength(field, min, severity = "error") {
+  return {
+    id: `${field}-min-${min}`,
+    severity,
+    message: `${field} must have at least ${min} item(s)`,
+    check: (spec) => {
+      const value = spec[field];
+      return !Array.isArray(value) || value.length < min;
+    }
+  };
+}
+function idFormat(prefix, opts) {
+  const pattern = opts?.pattern ?? new RegExp(`^${prefix}-\\d{${opts?.digits ?? 3}}$`);
+  return {
+    id: "id-format",
+    severity: "warning",
+    message: `ID should match format ${pattern}`,
+    check: (spec) => {
+      const id = spec["id"];
+      return typeof id !== "string" || !pattern.test(id);
+    }
+  };
+}
+function childIdFormat(arrayField, idField) {
+  return {
+    id: `${arrayField}-id-format`,
+    severity: "warning",
+    message: `${arrayField} IDs should follow parent ID pattern`,
+    check: (spec) => {
+      const parentId = spec["id"];
+      const children = spec[arrayField];
+      if (!Array.isArray(children) || !parentId) return false;
+      return children.some((child) => {
+        const childId = child[idField];
+        return typeof childId === "string" && !childId.startsWith(parentId + "-");
+      });
+    }
+  };
+}
+
+// src/core/dsl/exporters.ts
+function markdownExporter(config) {
+  const exporter = {
+    format: "markdown",
+    outputDir: config.outputDir,
+    filename: (spec) => spec.id
+  };
+  if (config.single) {
+    const singleCfg = config.single;
+    exporter.single = (spec) => {
+      const lines = [];
+      const title = typeof singleCfg.title === "function" ? singleCfg.title(spec) : String(spec[singleCfg.title] ?? "");
+      lines.push(`# ${title}`, "");
+      if (singleCfg.meta) {
+        for (const m of singleCfg.meta) {
+          const key = typeof m === "string" ? m : m.key;
+          const label = typeof m === "string" ? key : m.label ?? m.key;
+          const value = spec[key];
+          if (value !== void 0 && value !== null) {
+            lines.push(`**${label}**: ${String(value)}`);
+          }
+        }
+        lines.push("");
+      }
+      if (singleCfg.sections) {
+        for (const section of singleCfg.sections) {
+          let content;
+          if (section.render) {
+            content = section.render(spec);
+          } else if (section.field) {
+            const value = spec[section.field];
+            if (typeof value === "string") content = value;
+          }
+          if (section.optional && !content) continue;
+          lines.push(`## ${section.heading}`, "");
+          if (content) lines.push(content, "");
+        }
+      }
+      return lines.join("\n");
+    };
+  }
+  if (config.index) {
+    const indexCfg = config.index;
+    exporter.index = (specs) => {
+      const lines = [];
+      const title = indexCfg.title ?? "Index";
+      lines.push(`# ${title}`, "");
+      const columns = indexCfg.columns.map(
+        (c) => typeof c === "string" ? { key: c, label: c } : { key: c.key, label: c.label ?? c.key, render: c.render }
+      );
+      lines.push("| " + columns.map((c) => c.label).join(" | ") + " |");
+      lines.push("| " + columns.map(() => "---").join(" | ") + " |");
+      for (const spec of specs) {
+        const cells = columns.map((col) => {
+          const value = spec[col.key];
+          if ("render" in col && col.render) return col.render(value, spec);
+          if (col.key === "id") return `[${value}](./${value}.md)`;
+          return String(value ?? "-");
+        });
+        lines.push("| " + cells.join(" | ") + " |");
+      }
+      return lines.join("\n");
+    };
+  }
+  return exporter;
+}
+
+// src/core/dsl/type-compat.ts
+var ALIASES = {
+  INTEGER: "INT",
+  BOOL: "BOOLEAN",
+  REAL: "FLOAT",
+  "DOUBLE PRECISION": "DOUBLE",
+  SERIAL: "INT",
+  BIGSERIAL: "BIGINT",
+  SMALLSERIAL: "SMALLINT",
+  TIMESTAMPTZ: "TIMESTAMP",
+  "TIMESTAMP WITH TIME ZONE": "TIMESTAMP",
+  "TIMESTAMP WITHOUT TIME ZONE": "TIMESTAMP",
+  "CHARACTER VARYING": "VARCHAR",
+  CHARACTER: "CHAR",
+  INT2: "SMALLINT",
+  INT4: "INT",
+  INT8: "BIGINT",
+  FLOAT4: "FLOAT",
+  FLOAT8: "DOUBLE"
+};
+var CONTAINMENT_CHAINS = [
+  ["SMALLINT", "INT", "BIGINT"],
+  ["FLOAT", "DOUBLE"],
+  ["CHAR", "VARCHAR", "TEXT"],
+  ["INTEGER", "NUMBER"]
+];
+function parseType(raw) {
+  const trimmed = raw.trim().toUpperCase();
+  const match = trimmed.match(/^([A-Z\s]+?)(?:\(\s*(\d+)(?:\s*,\s*(\d+))?\s*\))?$/);
+  if (!match) {
+    return { base: trimmed };
+  }
+  const base = match[1].trim();
+  return {
+    base,
+    length: match[2] !== void 0 ? Number(match[2]) : void 0,
+    precision: match[2] !== void 0 ? Number(match[2]) : void 0,
+    scale: match[3] !== void 0 ? Number(match[3]) : void 0
+  };
+}
+function normalize(base) {
+  return ALIASES[base] ?? base;
+}
+function findAllChainPositions(base, chains) {
+  const results = [];
+  const resolved = normalize(base);
+  for (const chain of chains) {
+    let idx = chain.indexOf(base);
+    if (idx === -1) idx = chain.indexOf(resolved);
+    if (idx !== -1) results.push({ chain, index: idx });
+  }
+  return results;
+}
+function isTypeContainedBy(specType, ddlType) {
+  const spec = parseType(specType);
+  const ddl = parseType(ddlType);
+  const specNorm = normalize(spec.base);
+  const ddlNorm = normalize(ddl.base);
+  if (specNorm === ddlNorm) {
+    if (specNorm === "DECIMAL" || specNorm === "NUMERIC") {
+      if (spec.precision !== void 0 && ddl.precision !== void 0) {
+        if (ddl.precision < spec.precision) return false;
+      }
+      if (spec.scale !== void 0 && ddl.scale !== void 0) {
+        if (ddl.scale < spec.scale) return false;
+      }
+      return true;
+    }
+    if (spec.length !== void 0 && ddl.length !== void 0) {
+      return ddl.length >= spec.length;
+    }
+    return true;
+  }
+  const specPositions = findAllChainPositions(spec.base, CONTAINMENT_CHAINS);
+  const ddlPositions = findAllChainPositions(ddl.base, CONTAINMENT_CHAINS);
+  for (const sp of specPositions) {
+    for (const dp of ddlPositions) {
+      if (sp.chain === dp.chain) {
+        return dp.index >= sp.index;
+      }
+    }
+  }
+  return false;
+}
+
+// src/core/dsl/checkers.ts
+function testChecker(config) {
+  return {
+    targetType: "test",
+    sourcePath: config?.sourcePath ?? (() => "."),
+    check: (spec) => {
+      const errors = [];
+      const warnings = [];
+      const basePath = process.cwd();
+      const testPatterns = [
+        "test/**/*.test.ts",
+        "test/**/*.spec.ts",
+        "tests/**/*.test.ts",
+        "tests/**/*.spec.ts"
+      ];
+      let testFiles = [];
+      for (const pattern of testPatterns) {
+        testFiles = testFiles.concat(glob.sync(pattern, { cwd: basePath }));
+      }
+      if (testFiles.length === 0) {
+        warnings.push({ message: `No test files found for ${spec.id}`, specId: spec.id });
+        return { success: true, errors, warnings };
+      }
+      let specIdFound = false;
+      for (const testFile of testFiles) {
+        const fullPath = join(basePath, testFile);
+        try {
+          const content = readFileSync(fullPath, "utf-8");
+          const patterns = [
+            new RegExp(`describe\\s*\\(\\s*['"\`].*${spec.id}`, "m"),
+            new RegExp(`it\\s*\\(\\s*['"\`].*${spec.id}`, "m"),
+            new RegExp(`test\\s*\\(\\s*['"\`].*${spec.id}`, "m")
+          ];
+          if (patterns.some((p) => p.test(content))) {
+            specIdFound = true;
+            break;
+          }
+        } catch {
+        }
+      }
+      if (!specIdFound) {
+        warnings.push({
+          message: `Spec ID "${spec.id}" not found in any test file`,
+          specId: spec.id
+        });
+      }
+      return { success: errors.length === 0, errors, warnings };
+    }
+  };
+}
+function resolveRef(doc, ref) {
+  if (!ref.startsWith("#/")) return void 0;
+  const parts = ref.substring(2).split("/");
+  let current = doc;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function maybeResolveRef(doc, value) {
+  if (value && typeof value === "object" && typeof value.$ref === "string") {
+    return resolveRef(doc, value.$ref);
+  }
+  return value;
+}
+function findSpecIdInOpenAPI(doc, specId) {
+  const paths = doc.paths;
+  if (!paths || typeof paths !== "object") return null;
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    if (pathItem == null || typeof pathItem !== "object") continue;
+    const methods = ["get", "post", "put", "delete", "patch", "options", "head"];
+    for (const method of methods) {
+      const op = pathItem[method];
+      if (!op) continue;
+      if (op.operationId === specId) return { pathKey, operation: op, method };
+      if (op["x-spec-id"] === specId) return { pathKey, operation: op, method };
+    }
+  }
+  for (const pathKey of Object.keys(paths)) {
+    const segments = pathKey.split("/").filter(Boolean);
+    const cleanSegments = segments.map((s) => s.replace(/^\{|\}$/g, ""));
+    if (cleanSegments.includes(specId)) return { pathKey };
+  }
+  const schemas = doc.components?.schemas;
+  if (schemas && typeof schemas === "object") {
+    if (specId in schemas) return { pathKey: `#/components/schemas/${specId}` };
+  }
+  function searchXSpecId(obj) {
+    if (obj == null || typeof obj !== "object") return false;
+    if (obj["x-spec-id"] === specId) return true;
+    for (const val of Object.values(obj)) {
+      if (searchXSpecId(val)) return true;
+    }
+    return false;
+  }
+  if (searchXSpecId(doc)) return { pathKey: "(x-spec-id match)" };
+  return null;
+}
+function externalOpenAPIChecker(config) {
+  return {
+    targetType: "openapi",
+    sourcePath: config?.sourcePath ?? (() => "api/openapi.yaml"),
+    check: (spec) => {
+      const errors = [];
+      const warnings = [];
+      const filePath = (config?.sourcePath ?? (() => "api/openapi.yaml"))(spec);
+      const fullPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
+      if (!existsSync(fullPath)) {
+        errors.push({ message: `OpenAPI file not found: ${filePath}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      let content;
+      try {
+        content = readFileSync(fullPath, "utf-8");
+      } catch {
+        errors.push({ message: `Failed to read OpenAPI file: ${filePath}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      if (content.length === 0) {
+        errors.push({ message: `OpenAPI file is empty: ${filePath}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      let doc;
+      try {
+        if (fullPath.endsWith(".json")) {
+          doc = JSON.parse(content);
+        } else {
+          doc = parse(content);
+        }
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        errors.push({ message: `Failed to parse OpenAPI file ${filePath}: ${msg}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      const match = findSpecIdInOpenAPI(doc, spec.id);
+      if (!match) {
+        warnings.push({ message: `Spec ID "${spec.id}" not found in OpenAPI document ${filePath}`, specId: spec.id });
+        return { success: true, errors, warnings };
+      }
+      if (!config?.mapper) {
+        return { success: errors.length === 0, errors, warnings };
+      }
+      const mapping = config.mapper(spec);
+      if (mapping.method && match.operation) {
+        const expectedMethod = mapping.method.toLowerCase();
+        const actualMethod = match.method?.toLowerCase();
+        if (actualMethod && actualMethod !== expectedMethod) {
+          warnings.push({
+            message: `Method mismatch for "${spec.id}": expected ${expectedMethod.toUpperCase()}, found ${actualMethod.toUpperCase()}`,
+            specId: spec.id
+          });
+        }
+      }
+      if (match.operation && mapping.parameters) {
+        const opParams = (match.operation.parameters || []).map(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (p) => maybeResolveRef(doc, p)
+        );
+        for (const expectedParam of mapping.parameters) {
+          const found = opParams.find(
+            (p) => p?.name === expectedParam.name && (!expectedParam.in || p?.in === expectedParam.in)
+          );
+          if (!found) {
+            warnings.push({
+              message: `Parameter "${expectedParam.name}" not found in operation "${spec.id}"`,
+              specId: spec.id,
+              field: expectedParam.name
+            });
+          } else if (expectedParam.type && found.schema?.type) {
+            if (!isTypeContainedBy(expectedParam.type, found.schema.type)) {
+              warnings.push({
+                message: `Parameter "${expectedParam.name}" type mismatch: expected ${expectedParam.type}, found ${found.schema.type}`,
+                specId: spec.id,
+                field: expectedParam.name
+              });
+            }
+          }
+        }
+      }
+      if (match.operation && mapping.responseProperties) {
+        const successResponse = match.operation.responses?.["200"] || match.operation.responses?.["201"];
+        let responseSchema = successResponse?.content?.["application/json"]?.schema;
+        responseSchema = maybeResolveRef(doc, responseSchema);
+        if (responseSchema?.type === "array") {
+          responseSchema = maybeResolveRef(doc, responseSchema.items);
+        }
+        const responseProps = responseSchema?.properties || {};
+        for (const expectedProp of mapping.responseProperties) {
+          const foundProp = responseProps[expectedProp.name];
+          if (!foundProp) {
+            warnings.push({
+              message: `Response property "${expectedProp.name}" not found in operation "${spec.id}"`,
+              specId: spec.id,
+              field: expectedProp.name
+            });
+          } else if (expectedProp.type && foundProp.type) {
+            if (!isTypeContainedBy(expectedProp.type, foundProp.type)) {
+              warnings.push({
+                message: `Response property "${expectedProp.name}" type mismatch: expected ${expectedProp.type}, found ${foundProp.type}`,
+                specId: spec.id,
+                field: expectedProp.name
+              });
+            }
+          }
+        }
+      }
+      return { success: errors.length === 0, errors, warnings };
+    }
+  };
+}
+function parseDDLWithParser(content) {
+  const parser = new nodeSqlParser.Parser();
+  const tables = [];
+  try {
+    const ast = parser.astify(content);
+    const statements = Array.isArray(ast) ? ast : [ast];
+    for (const stmt of statements) {
+      if (stmt.type !== "create" || stmt.keyword !== "table") continue;
+      const tableName = typeof stmt.table === "string" ? stmt.table : stmt.table?.[0]?.table ?? "";
+      const columns = (stmt.create_definitions || []).filter((def) => def.resource === "column").map((def) => {
+        const colName = def.column?.column ?? "";
+        let colType = def.definition?.dataType ?? "";
+        if (def.definition?.length) {
+          colType += `(${def.definition.length})`;
+        }
+        if (def.definition?.scale) {
+          colType = colType.replace(/\)$/, `,${def.definition.scale})`);
+        }
+        return { name: colName, type: colType };
+      });
+      if (tableName) {
+        tables.push({ name: tableName, columns });
+      }
+    }
+    return tables.length > 0 ? tables : null;
+  } catch {
+    return null;
+  }
+}
+function parseDDLWithRegex(content) {
+  const tables = [];
+  const tableRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:`|"|')?(\w+)(?:`|"|')?\s*\(([\s\S]*?)\);/gi;
+  let match;
+  while ((match = tableRegex.exec(content)) !== null) {
+    const tableName = match[1];
+    const body = match[2];
+    const columns = [];
+    const lines = body.split(",").map((l) => l.trim()).filter(Boolean);
+    for (const line of lines) {
+      if (/^\s*(PRIMARY\s+KEY|UNIQUE|CHECK|CONSTRAINT|INDEX|FOREIGN\s+KEY)/i.test(line)) continue;
+      const colMatch = line.match(/^(?:`|"|')?(\w+)(?:`|"|')?\s+(\w+(?:\([^)]*\))?)/i);
+      if (colMatch) {
+        columns.push({ name: colMatch[1], type: colMatch[2] });
+      }
+    }
+    if (tableName) {
+      tables.push({ name: tableName, columns });
+    }
+  }
+  return tables;
+}
+function externalSqlSchemaChecker(config) {
+  return {
+    targetType: "ddl",
+    sourcePath: config?.sourcePath ?? (() => "db/schema.sql"),
+    check: (spec) => {
+      const errors = [];
+      const warnings = [];
+      const filePath = (config?.sourcePath ?? (() => "db/schema.sql"))(spec);
+      const fullPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
+      if (!existsSync(fullPath)) {
+        errors.push({ message: `DDL file not found: ${filePath}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      let content;
+      try {
+        content = readFileSync(fullPath, "utf-8");
+      } catch {
+        errors.push({ message: `Failed to read DDL file: ${filePath}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      if (content.length === 0) {
+        errors.push({ message: `DDL file is empty: ${filePath}`, specId: spec.id });
+        return { success: false, errors, warnings };
+      }
+      let tables = parseDDLWithParser(content);
+      if (!tables) {
+        warnings.push({ message: `DDL parser failed for ${filePath}, using regex fallback`, specId: spec.id });
+        tables = parseDDLWithRegex(content);
+      }
+      if (!config?.mapper) {
+        return { success: errors.length === 0, errors, warnings };
+      }
+      const mapping = config.mapper(spec);
+      const table = tables.find(
+        (t) => t.name.toLowerCase() === mapping.tableName.toLowerCase()
+      );
+      if (!table) {
+        warnings.push({
+          message: `Table "${mapping.tableName}" not found in DDL file ${filePath}`,
+          specId: spec.id
+        });
+        return { success: errors.length === 0, errors, warnings };
+      }
+      if (!mapping.columns) {
+        return { success: errors.length === 0, errors, warnings };
+      }
+      for (const expectedCol of mapping.columns) {
+        const foundCol = table.columns.find(
+          (c) => c.name.toLowerCase() === expectedCol.name.toLowerCase()
+        );
+        if (!foundCol) {
+          warnings.push({
+            message: `Column "${expectedCol.name}" not found in table "${mapping.tableName}"`,
+            specId: spec.id,
+            field: expectedCol.name
+          });
+          continue;
+        }
+        if (config.checkTypes && expectedCol.type && foundCol.type) {
+          if (!isTypeContainedBy(expectedCol.type, foundCol.type)) {
+            warnings.push({
+              message: `Column "${expectedCol.name}" type mismatch in table "${mapping.tableName}": expected ${expectedCol.type}, found ${foundCol.type}`,
+              specId: spec.id,
+              field: expectedCol.name
+            });
+          }
+        }
+      }
+      return { success: errors.length === 0, errors, warnings };
+    }
+  };
+}
+function relationCoverage(config) {
+  return {
+    targetModel: config.targetModel,
+    description: config.description,
+    check: (specs, registry) => {
+      const targets = registry[config.targetModel];
+      if (!targets) {
+        return { total: 0, covered: 0, uncovered: 0, coveragePercent: 100, coveredItems: [], uncoveredItems: [] };
+      }
+      const allTargetIds = /* @__PURE__ */ new Set();
+      const targetDescriptions = /* @__PURE__ */ new Map();
+      for (const t of targets.values()) {
+        if (config.targetPrefix && !t.id.startsWith(config.targetPrefix)) continue;
+        allTargetIds.add(t.id);
+        targetDescriptions.set(t.id, t.name ?? t.description ?? t.id);
+      }
+      const coveredIds = /* @__PURE__ */ new Set();
+      for (const spec of specs) {
+        if (!spec.relations) continue;
+        for (const rel of spec.relations) {
+          if (config.relationType && rel.type !== config.relationType) continue;
+          if (allTargetIds.has(rel.target)) coveredIds.add(rel.target);
+        }
+      }
+      const coveredItems = [];
+      const uncoveredItems = [];
+      for (const id of allTargetIds) {
+        const desc = targetDescriptions.get(id);
+        if (coveredIds.has(id)) {
+          coveredItems.push({ id, description: desc });
+        } else {
+          uncoveredItems.push({ id, description: desc });
+        }
+      }
+      const total = allTargetIds.size;
+      const covered = coveredItems.length;
+      const coveragePercent = total > 0 ? Math.round(covered / total * 100) : 100;
+      return { total, covered, uncovered: total - covered, coveragePercent, coveredItems, uncoveredItems };
+    }
+  };
+}
+var ImplementsRelationSchema = z.object({
+  target: z.string(),
+  targetType: z.string(),
+  sourcePath: z.string().optional(),
+  description: z.string().optional()
+});
+var VerifiedByRelationSchema = z.object({
+  target: z.string(),
+  testPath: z.string().optional(),
+  framework: z.string().optional(),
+  description: z.string().optional()
+});
+
+export { ImplementsRelationSchema, VerifiedByRelationSchema, arrayMinLength, baseSpecSchema, childIdFormat, externalOpenAPIChecker, externalSqlSchemaChecker, idFormat, isTypeContainedBy, markdownExporter, relationCoverage, requireField, testChecker };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map