speckeeper 0.9.0 → 0.9.1

package/README.md

@@ -290,6 +290,28 @@ class EntityModel extends Model<typeof EntitySchema> {
 
 Without `deepValidation`, speckeeper still performs existence checks for all spec IDs across all configured sources.
 
+#### Lookup keys (when spec ID differs from external identifier)
+
+By default, the global scanner searches for each spec's `id` in external sources. When the external identifier differs — for example, entity ID `"user"` vs DDL table name `"users"` — define `lookupKeys` on the model to map per source type:
+
+```typescript
+class EntityModel extends Model<typeof EntitySchema> {
+  readonly id = 'entity';
+  readonly name = 'Entity';
+  readonly idPrefix = 'ENT';
+  readonly schema = EntitySchema;
+
+  protected lookupKeys: LookupKeyConfig<Entity> = {
+    ddl: (spec) => spec.tableName,
+    openapi: (spec) => spec.schemaName ?? spec.id,
+  };
+}
+```
+
+With this configuration, when scanning DDL sources the scanner searches for `spec.tableName` instead of `spec.id`. If a match is found, the result is mapped back to the original spec ID for reporting and deep validation.
+
+`lookupKeys` is optional per source type — any source type not listed falls back to `spec.id`.
+
 #### Custom scanners
 
 For file formats not covered by the built-in scanners, provide a custom `SourceScanner` plugin:

package/dist/cli.js

@@ -727,7 +727,7 @@ function loadFileContent(filePath, sourceType) {
   }
   return content;
 }
-function runGlobalScan(sources, specIds, basePath) {
+function runGlobalScan(sources, specIds, basePath, lookupKeyMap) {
   const cwd = basePath ?? process.cwd();
   const result = /* @__PURE__ */ new Map();
   const warnings = [];
@@ -740,6 +740,13 @@ function runGlobalScan(sources, specIds, basePath) {
       });
       continue;
     }
+    const keyToSpecId = /* @__PURE__ */ new Map();
+    for (const specId of specIds) {
+      const overrides = lookupKeyMap?.get(specId);
+      const key = overrides?.[source.type] ?? specId;
+      keyToSpecId.set(key, specId);
+    }
+    const keysToSearch = Array.from(keyToSpecId.keys());
     const allFiles = /* @__PURE__ */ new Set();
     for (const pattern of source.paths) {
       const found = glob.sync(pattern, {
@@ -768,7 +775,7 @@ function runGlobalScan(sources, specIds, basePath) {
       if (content == null) continue;
       let matches;
       try {
-        matches = scanner.findSpecIds(content, specIds, relPath);
+        matches = scanner.findSpecIds(content, keysToSearch, relPath);
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         warnings.push({
@@ -779,17 +786,19 @@ function runGlobalScan(sources, specIds, basePath) {
         continue;
       }
       for (const match of matches) {
+        const originalSpecId = keyToSpecId.get(match.specId) ?? match.specId;
         const globalMatch = {
           ...match,
+          specId: originalSpecId,
           sourceType: source.type,
           relation: source.relation,
           filePath: relPath
         };
-        const existing = result.get(match.specId);
+        const existing = result.get(originalSpecId);
         if (existing) {
           existing.push(globalMatch);
         } else {
-          result.set(match.specId, [globalMatch]);
+          result.set(originalSpecId, [globalMatch]);
         }
       }
     }
@@ -932,17 +941,35 @@ async function checkCommand(type, options) {
     const results = [];
     const allSpecIds = [];
     const specIdToModel = /* @__PURE__ */ new Map();
+    const lookupKeyMap = /* @__PURE__ */ new Map();
     for (const model of models) {
       const modelSpecs = getSpecsFromConfig(specs, model.id);
+      const modelLookupKeys = model.getLookupKeys?.();
       for (const spec of modelSpecs) {
         const specId = spec.id;
         allSpecIds.push(specId);
         specIdToModel.set(specId, { modelId: model.id, spec });
+        if (modelLookupKeys) {
+          const overrides = {};
+          for (const [sourceType, mapper] of Object.entries(modelLookupKeys)) {
+            if (typeof mapper === "function") {
+              overrides[sourceType] = mapper(spec);
+            }
+          }
+          if (Object.keys(overrides).length > 0) {
+            lookupKeyMap.set(specId, overrides);
+          }
+        }
       }
     }
     if (sources.length > 0 && allSpecIds.length > 0) {
       const filteredSources = checkType === "all" ? sources : sources.filter((s) => s.type === checkType);
-      const { matches, warnings: scanWarnings } = runGlobalScan(filteredSources, allSpecIds, cwd);
+      const { matches, warnings: scanWarnings } = runGlobalScan(
+        filteredSources,
+        allSpecIds,
+        cwd,
+        lookupKeyMap.size > 0 ? lookupKeyMap : void 0
+      );
       for (const sw of scanWarnings) {
         results.push({
           type: sw.sourceType,