@metaobjectsdev/sdk 0.23.2 → 0.24.0

package/dist/collection.js

@@ -0,0 +1,121 @@
+// server/typescript/packages/sdk/src/collection.ts
+//
+// Phase-1 metadata-source-resolution — the single authority.
+//
+// `resolveCollection()` composes discovery (`discovery.ts`), config
+// (`config.ts`), source resolution (`sources.ts`) and the scope engine
+// (`scope.ts`) into one function that decides where a project's metadata
+// lives. `metaobjects/` is the DEFAULT value of `sources`, never a
+// requirement — a project that declares nothing still resolves exactly as
+// today (`DEFAULT_SOURCES` in `sources.ts`); a project that declares
+// `sources` can point anywhere. No other call site may assume the directory
+// name — this is where that assumption is allowed to live, exactly once.
+import { join, resolve } from "node:path";
+import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { CONFIG_FILE, loadConfig } from "./config.js";
+import { discoverCollectionRoot, exists, isDir } from "./discovery.js";
+import { compileScope, matchesScope } from "./scope.js";
+import { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+import { DEFAULT_SOURCES, orderedPathSpecs, resolveSpecPath, resolveSources, } from "./sources.js";
+/** Narrow the zod-inferred `Config["scope"]` (whose `.optional()` fields are
+ *  typed `T | undefined` even when present) down to `Scope`'s
+ *  exactOptionalPropertyTypes-safe shape — a key is omitted entirely rather
+ *  than assigned `undefined`. */
+function toScope(spec) {
+    return {
+        ...(spec?.include !== undefined && { include: spec.include }),
+        ...(spec?.exclude !== undefined && { exclude: spec.exclude }),
+    };
+}
+/**
+ * THE single authority on where metadata lives. Every read path routes
+ * through this — `metaobjects/` is the DEFAULT value of `sources`, never an
+ * assumption baked into a call site.
+ *
+ * Resolution order: an explicit `opts.explicitDir` wins outright; otherwise
+ * `discoverCollectionRoot` walks up from `startDir` for the nearest directory
+ * carrying `.metaobjects/config.json` — the ONLY project marker (`discovery.ts`
+ * says why a directory that merely holds metadata is not one) — falling back to
+ * `startDir` itself when none is found. When the resolved directory carries a
+ * config, its declared `sources`/`scope`/`migrate.scope` govern. Only a
+ * genuinely ABSENT `config.json` falls through to `DEFAULT_SOURCES` — the same
+ * directory the pre-source-resolution toolchain always read; a config.json
+ * that EXISTS but fails to load (malformed JSON, schema violation) is the
+ * author's error and propagates rather than silently degrading — a source
+ * that fails to resolve must never look like one that was never declared.
+ * Throws `ERR_COLLECTION_NOT_FOUND` only when BOTH have failed: no
+ * `sources` were declared AND the default source directory does not exist
+ * either.
+ *
+ * A declared source that fails to resolve is a different, louder failure —
+ * `resolveSources` throws `ERR_SOURCE_UNRESOLVED` for that case; only the
+ * DEFAULT is allowed to be silently absent.
+ */
+export async function resolveCollection(startDir, opts) {
+    const explicit = opts?.explicitDir;
+    // Whether `configDir` carries a `config.json` — threaded through rather
+    // than re-`stat`'d below. On the non-explicit path, `discoverCollectionRoot`
+    // already proved it either way: it reports `hasConfig` from the same
+    // `.metaobjects/config.json` probe that decided where to stop, and reports
+    // false only after confirming that file is absent at every directory it
+    // examined, `resolve(startDir)` included. A second `stat` of the identical
+    // file would just re-prove what discovery established. The check is only
+    // load-bearing on the `explicitDir` path, where discovery never runs at all.
+    let configDir;
+    let hasConfig;
+    if (explicit !== undefined) {
+        configDir = resolve(explicit);
+        hasConfig = await exists(join(configDir, DEFAULT_METAOBJECTS_DIR, CONFIG_FILE));
+    }
+    else {
+        ({ dir: configDir, hasConfig } = await discoverCollectionRoot(startDir));
+    }
+    let specs = DEFAULT_SOURCES;
+    let scopeSpec;
+    let migrateSpec;
+    if (hasConfig) {
+        // No try/catch here: a config.json that EXISTS but fails to load
+        // (malformed JSON, a ConfigSchema violation) propagates. Swallowing it
+        // would make a typo'd config behave identically to no config at all —
+        // silently generating from a possibly-stale `metaobjects/` with no
+        // diagnostic, which is a worse failure than the one this design exists
+        // to remove.
+        const cfg = await loadConfig(join(configDir, DEFAULT_METAOBJECTS_DIR));
+        if (cfg.sources.length > 0)
+            specs = cfg.sources;
+        scopeSpec = cfg.scope;
+        migrateSpec = cfg.migrate?.scope;
+    }
+    // Only the DEFAULT is allowed to be absent — an explicitly declared source
+    // that does not resolve is `resolveSources`'s ERR_SOURCE_UNRESOLVED, not this.
+    //
+    // This re-`stat`s a directory the non-explicit discovery walk may already
+    // have probed, and that redundancy is intentional: it exists to produce the
+    // friendlier `ERR_COLLECTION_NOT_FOUND` diagnostic below rather than the raw
+    // `ERR_SOURCE_UNRESOLVED` `resolveSources` would throw on a genuinely missing
+    // default directory. Trading that clearer error for one syscall is a bad
+    // trade. It is also load-bearing outright on the `explicitDir` path and
+    // whenever a discovered config declares no `sources`, where nothing has
+    // probed it at all.
+    if (specs === DEFAULT_SOURCES && !(await isDir(join(configDir, DEFAULT_METADATA_DIR)))) {
+        throw new ParseError(`no metadata sources declared in ${configDir} and no default "${DEFAULT_METADATA_DIR}" directory found. ` +
+            `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/config.json, or run 'meta init' to scaffold.`, { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") });
+    }
+    const sources = await resolveSources(configDir, specs);
+    const scope = compileScope(toScope(scopeSpec));
+    const migrateScope = migrateSpec === undefined ? undefined : compileScope({ include: migrateSpec });
+    return {
+        configDir,
+        files: sources.map((s) => s.file),
+        sources,
+        // Canonical (content) order, from `resolveSources`'s own ordering — so this
+        // list is a pure function of the source SET, exactly like `files`.
+        sourceRoots: [
+            ...new Set(orderedPathSpecs(specs).map((spec) => resolveSpecPath(configDir, spec))),
+        ],
+        inScope: (fqn) => matchesScope(fqn, scope),
+        inMigrateScope: migrateScope === undefined ? undefined : (fqn) => matchesScope(fqn, migrateScope),
+        migrateScopePatterns: migrateSpec,
+    };
+}
+//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,6DAA6D;AAC7D,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,yEAAyE;AACzE,mEAAmE;AACnE,0EAA0E;AAC1E,qEAAqE;AACrE,4EAA4E;AAC5E,yEAAyE;AACzE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,cAAc,GAGf,MAAM,cAAc,CAAC;AA6CtB;;;iCAGiC;AACjC,SAAS,OAAO,CAAC,IAAqB;IACpC,OAAO;QACL,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,IAA+B;IAE/B,MAAM,QAAQ,GAAG,IAAI,EAAE,WAAW,CAAC;IAEnC,wEAAwE;IACxE,6EAA6E;IAC7E,qEAAqE;IACrE,2EAA2E;IAC3E,wEAAwE;IACxE,2EAA2E;IAC3E,yEAAyE;IACzE,6EAA6E;IAC7E,IAAI,SAAiB,CAAC;IACtB,IAAI,SAAkB,CAAC;IACvB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,EAAE,WAAW,CAAC,CAAC,CAAC;IAClF,CAAC;SAAM,CAAC;QACN,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,KAAK,GAA0B,eAAe,CAAC;IACnD,IAAI,SAA0B,CAAC;IAC/B,IAAI,WAAiC,CAAC;IAEtC,IAAI,SAAS,EAAE,CAAC;QACd,iEAAiE;QACjE,uEAAuE;QACvE,sEAAsE;QACtE,mEAAmE;QACnE,uEAAuE;QACvE,aAAa;QACb,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC;QACvE,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC;QAChD,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC;QACtB,WAAW,GAAG,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC;IACnC,CAAC;IAED,2EAA2E;IAC3E,+EAA+E;IAC/E,EAAE;IACF,0EAA0E;IAC1E,4EAA4E;IAC5E,6EAA6E;IAC7E,8EAA8E;IAC9E,yEAAyE;IACzE,wEAAwE;IACxE,wEAAwE;IACxE,oBAAoB;IACpB,IAAI,KAAK,KAAK,eAAe,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,UAAU,CAClB,mCAAmC,SAAS,oBAAoB,oBAAoB,qBAAqB;YACvG,wBAAwB,uBAAuB,+CAA+C,EAChG,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,MAAM,YAAY,GAChB,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACjF,OAAO;QACL,SAAS;QACT,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACjC,OAAO;QACP,4EAA4E;QAC5E,mEAAmE;QACnE,WAAW,EAAE;YACX,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;SACpF;QACD,OAAO,EAAE,CAAC,GAAW,EAAW,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC;QAC3D,cAAc,EACZ,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAW,EAAW,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,CAAC;QACpG,oBAAoB,EAAE,WAAW;KAClC,CAAC;AACJ,CAAC"}

package/dist/config.d.ts

@@ -11,7 +11,7 @@ import { z } from "zod";
  * `adopt-view`/`drop-identity-default` were added to `cli` without a
  * matching update here).
  */
-export declare const AllowTokenEnum: z.ZodEnum<["drop-column", "drop-table", "type-change", "drop-index", "drop-fk", "drop-check", "drop-view", "drop-view-cascade", "adopt-view", "nullable-to-not-null", "drop-identity-default"]>;
+export declare const AllowTokenEnum: z.ZodEnum<["drop-column", "drop-table", "type-change", "drop-index", "drop-fk", "drop-check", "drop-view", "drop-view-cascade", "adopt-view", "nullable-to-not-null", "drop-identity-default", "drop-unmanaged"]>;
 export declare const ConfigSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<1>;
     pending_in_git: z.ZodDefault<z.ZodBoolean>;
@@ -26,24 +26,36 @@ export declare const ConfigSchema: z.ZodObject<{
         drift_warn?: number | undefined;
     }>>;
     sources: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"path">;
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
-        kind: "path";
     }, {
         path: string;
-        kind: "path";
     }>, z.ZodObject<{
-        kind: z.ZodLiteral<"package">;
+        resource: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        resource: string;
+    }, {
+        resource: string;
+    }>, z.ZodObject<{
         package: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "package";
+    }, "strict", z.ZodTypeAny, {
         package: string;
     }, {
-        kind: "package";
         package: string;
     }>]>, "many">>;
+    /** Output filter applied across every command — see `./scope.ts`. Absent
+     *  means "everything" (no filtering), matching `Scope`'s own contract. */
+    scope: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    }, {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    }>>;
     extract: z.ZodDefault<z.ZodObject<{
         metaignore: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
@@ -57,13 +69,13 @@ export declare const ConfigSchema: z.ZodObject<{
         dialect: z.ZodOptional<z.ZodEnum<["sqlite", "postgres", "d1"]>>;
         format: z.ZodOptional<z.ZodEnum<["default", "flyway"]>>;
         onAmbiguous: z.ZodOptional<z.ZodEnum<["abort", "rename", "drop-add"]>>;
-        allow: z.ZodOptional<z.ZodArray<z.ZodEnum<["drop-column", "drop-table", "type-change", "drop-index", "drop-fk", "drop-check", "drop-view", "drop-view-cascade", "adopt-view", "nullable-to-not-null", "drop-identity-default"]>, "many">>;
+        allow: z.ZodOptional<z.ZodArray<z.ZodEnum<["drop-column", "drop-table", "type-change", "drop-index", "drop-fk", "drop-check", "drop-view", "drop-view-cascade", "adopt-view", "nullable-to-not-null", "drop-identity-default", "drop-unmanaged"]>, "many">>;
         d1: z.ZodOptional<z.ZodObject<{
             binding: z.ZodOptional<z.ZodString>;
             remote: z.ZodOptional<z.ZodBoolean>;
             autoApply: z.ZodOptional<z.ZodBoolean>;
             wranglerConfigPath: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
+        }, "strict", z.ZodTypeAny, {
             binding?: string | undefined;
             remote?: boolean | undefined;
             autoApply?: boolean | undefined;
@@ -74,7 +86,8 @@ export declare const ConfigSchema: z.ZodObject<{
             autoApply?: boolean | undefined;
             wranglerConfigPath?: string | undefined;
         }>>;
-    }, "strip", z.ZodTypeAny, {
+        scope: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
         d1?: {
             binding?: string | undefined;
             remote?: boolean | undefined;
@@ -86,7 +99,8 @@ export declare const ConfigSchema: z.ZodObject<{
         dialect?: "sqlite" | "postgres" | "d1" | undefined;
         format?: "default" | "flyway" | undefined;
         onAmbiguous?: "abort" | "rename" | "drop-add" | undefined;
-        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default")[] | undefined;
+        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default" | "drop-unmanaged")[] | undefined;
+        scope?: string[] | undefined;
     }, {
         d1?: {
             binding?: string | undefined;
@@ -99,9 +113,10 @@ export declare const ConfigSchema: z.ZodObject<{
         dialect?: "sqlite" | "postgres" | "d1" | undefined;
         format?: "default" | "flyway" | undefined;
         onAmbiguous?: "abort" | "rename" | "drop-add" | undefined;
-        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default")[] | undefined;
+        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default" | "drop-unmanaged")[] | undefined;
+        scope?: string[] | undefined;
     }>>;
-}, "strip", z.ZodTypeAny, {
+}, "strict", z.ZodTypeAny, {
     schema_version: 1;
     pending_in_git: boolean;
     confidence_thresholds: {
@@ -110,14 +125,18 @@ export declare const ConfigSchema: z.ZodObject<{
     };
     sources: ({
         path: string;
-        kind: "path";
     } | {
-        kind: "package";
+        resource: string;
+    } | {
         package: string;
     })[];
     extract: {
         metaignore?: string | undefined;
     };
+    scope?: {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
     migrate?: {
         d1?: {
             binding?: string | undefined;
@@ -130,10 +149,15 @@ export declare const ConfigSchema: z.ZodObject<{
         dialect?: "sqlite" | "postgres" | "d1" | undefined;
         format?: "default" | "flyway" | undefined;
         onAmbiguous?: "abort" | "rename" | "drop-add" | undefined;
-        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default")[] | undefined;
+        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default" | "drop-unmanaged")[] | undefined;
+        scope?: string[] | undefined;
     } | undefined;
 }, {
     schema_version: 1;
+    scope?: {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
     pending_in_git?: boolean | undefined;
     confidence_thresholds?: {
         pending_promote?: number | undefined;
@@ -141,9 +165,9 @@ export declare const ConfigSchema: z.ZodObject<{
     } | undefined;
     sources?: ({
         path: string;
-        kind: "path";
     } | {
-        kind: "package";
+        resource: string;
+    } | {
         package: string;
     })[] | undefined;
     extract?: {
@@ -161,11 +185,17 @@ export declare const ConfigSchema: z.ZodObject<{
         dialect?: "sqlite" | "postgres" | "d1" | undefined;
         format?: "default" | "flyway" | undefined;
         onAmbiguous?: "abort" | "rename" | "drop-add" | undefined;
-        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default")[] | undefined;
+        allow?: ("drop-column" | "drop-table" | "type-change" | "drop-index" | "drop-fk" | "drop-check" | "drop-view" | "drop-view-cascade" | "adopt-view" | "nullable-to-not-null" | "drop-identity-default" | "drop-unmanaged")[] | undefined;
+        scope?: string[] | undefined;
     } | undefined;
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
 export declare const DEFAULT_CONFIG: Config;
+/** `config.json`'s basename — the single owner. `discovery.ts` and
+ *  `collection.ts` import this rather than each keeping their own copy of
+ *  the literal (a duplication that had drifted into three separate
+ *  declarations of the same string). */
+export declare const CONFIG_FILE = "config.json";
 export declare function loadConfig(metaRoot: string): Promise<Config>;
 export declare function saveConfig(metaRoot: string, config: Config): Promise<void>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,iMAYzB,CAAC;AAsBH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBvB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,eAAO,MAAM,cAAc,EAAE,MAAkD,CAAC;AAIhF,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlE;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,mNAazB,CAAC;AAwFH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAUvB;8EAC0E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQjE,CAAC;AAEZ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,eAAO,MAAM,cAAc,EAAE,MAAkD,CAAC;AAEhF;;;wCAGwC;AACxC,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlE;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhF"}

package/dist/config.js

@@ -27,13 +27,17 @@ export const AllowTokenEnum = z.enum([
     "adopt-view",
     "nullable-to-not-null",
     "drop-identity-default",
+    "drop-unmanaged",
 ]);
+// .strict(), like every other object in this schema: `.partial()` alone leaves
+// zod's default STRIP policy in place, so a misspelled key is silently deleted
+// and the block reads as if the author never wrote it.
 const D1Block = z.object({
     binding: z.string(),
     remote: z.boolean(),
     autoApply: z.boolean(),
     wranglerConfigPath: z.string(),
-}).partial();
+}).partial().strict();
 /** #192 — migration output-format adapters; orthogonal to dialect. */
 const MigrateFormatEnum = z.enum(["default", "flyway"]);
 const MigrateBlock = z.object({
@@ -44,7 +48,67 @@ const MigrateBlock = z.object({
     onAmbiguous: OnAmbiguousEnum,
     allow: z.array(AllowTokenEnum),
     d1: D1Block,
-}).partial();
+    /** Restricts a `meta migrate` run to a subset of the loaded metadata, by the
+     *  same package-glob pattern grammar as top-level `scope` (see `scope.ts`).
+     *  Include-only — there's no `migrate.scope.exclude`, since a migration run
+     *  is scoped to what it's touching, not filtered down from "everything". */
+    scope: z.array(z.string().min(1)),
+    // .strict() for the same reason as the top level and the source arms below, and
+    // with sharper teeth here: `{ migrate: { scopee: [...], dialect: "postgres" } }`
+    // used to parse to `{ dialect: "postgres" }`, so a typo'd `scope` key meant
+    // "unscoped" — silently governing every table in the database, which is the
+    // hazard `migrate.scope` exists to remove.
+}).partial().strict();
+/**
+ * Mirrors the hand-written `SourceSpec` union in `./sources.ts` — a
+ * declared source kind, one of `path` (resolves today), `resource`, or
+ * `package` (both reserved, throw `ERR_SOURCE_KIND_UNSUPPORTED` until a
+ * later phase). `.strict()` on every arm: this project is fail-closed on
+ * undeclared keys everywhere else (ADR-0023 makes an unregistered metadata
+ * attribute a hard error for the same reason) — a config schema that
+ * silently strips an unknown key would let `{ path: "model", pathh: "typo"
+ * }` parse clean and resolve one source instead of erroring on the typo.
+ * The pre-phase-1 `{ kind: "path", path: "..." }` shape (the dead 2-arm
+ * discriminated union this replaces) never shipped to an adopter — `meta
+ * init` has only ever scaffolded `"sources": []`, and nothing under `src/`
+ * ever read the old shape — so there is no live config to be lenient for;
+ * it only ever existed in this package's own tests, updated alongside this
+ * schema.
+ */
+const SourceSpecSchema = z.union([
+    z.object({ path: z.string().min(1) }).strict(),
+    z.object({ resource: z.string().min(1) }).strict(),
+    z.object({ package: z.string().min(1) }).strict(),
+]);
+// Compile-time parity, BOTH directions: if SourceSpecSchema and the
+// hand-written SourceSpec (./sources.ts) ever drift, one of these two
+// assignments stops compiling. Each direction alone catches only HALF the
+// drift — `z.infer<...>` assignable to `SourceSpec` catches an arm added to
+// the schema but missing from SourceSpec, while `SourceSpec` assignable to
+// `z.infer<...>` catches the opposite: an arm added to the hand-written
+// SourceSpec that the schema never gained. A single one-directional
+// assignment (the prior form of this guard) let a SourceSpec-only addition
+// compile clean — proven by deliberately breaking each direction in
+// isolation; see the quality-pass report for both failing `tsc` outputs. A
+// conditional type (`X extends Y ? true : never`) would silently resolve to
+// `never` instead of erroring — this direct-assignment form fails for real.
+const _sourceSpecParityInferToSpec = {};
+const _sourceSpecParitySpecToInfer = {};
+void _sourceSpecParityInferToSpec;
+void _sourceSpecParitySpecToInfer;
+/** Mirrors the hand-written `Scope` interface in `./scope.ts`. An absent or
+ *  empty `include` means "everything" — see `matchesScope`. */
+const ScopeSchema = z
+    .object({
+    include: z.array(z.string().min(1)).optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+// .strict() at the TOP level too, not just the source-spec arms and the
+// scope block: without it, a misspelled top-level key (e.g. "scopes" for
+// "scope") is silently stripped by zod and the collection resolves as
+// "everything in scope" — the exact silent fail-open .strict() on the
+// nested arms exists to prevent, one level up.
 export const ConfigSchema = z.object({
     schema_version: z.literal(1),
     pending_in_git: z.boolean().default(true),
@@ -54,21 +118,23 @@ export const ConfigSchema = z.object({
         drift_warn: z.number().min(0).max(1).default(0.7),
     })
         .default({}),
-    sources: z
-        .array(z.union([
-        z.object({ kind: z.literal("path"), path: z.string() }),
-        z.object({ kind: z.literal("package"), package: z.string() }),
-    ]))
-        .default([]),
+    sources: z.array(SourceSpecSchema).default([]),
+    /** Output filter applied across every command — see `./scope.ts`. Absent
+     *  means "everything" (no filtering), matching `Scope`'s own contract. */
+    scope: ScopeSchema.optional(),
     extract: z
         .object({
         metaignore: z.string().optional(),
     })
         .default({}),
     migrate: MigrateBlock.optional(),
-});
+}).strict();
 export const DEFAULT_CONFIG = ConfigSchema.parse({ schema_version: 1 });
-const CONFIG_FILE = "config.json";
+/** `config.json`'s basename — the single owner. `discovery.ts` and
+ *  `collection.ts` import this rather than each keeping their own copy of
+ *  the literal (a duplication that had drifted into three separate
+ *  declarations of the same string). */
+export const CONFIG_FILE = "config.json";
 export async function loadConfig(metaRoot) {
     const raw = await readFile(join(metaRoot, CONFIG_FILE), "utf8");
     return ConfigSchema.parse(JSON.parse(raw));

package/dist/config.js.map

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

package/dist/discovery.d.ts

@@ -0,0 +1,43 @@
+/** Exported for reuse — `collection.ts` had its own byte-identical copy
+ *  (`fileExists`); one definition, imported. */
+export declare function exists(path: string): Promise<boolean>;
+/** `exists`, narrowed to directories — `collection.ts`'s default-source probe
+ *  needs that distinction to raise its friendlier `ERR_COLLECTION_NOT_FOUND`
+ *  (a plain FILE where the default source directory should be is not a
+ *  metadata home). Lives here beside `exists` so there is one filesystem
+ *  predicate pair in the package rather than a copy per caller. */
+export declare function isDir(path: string): Promise<boolean>;
+/** Where the discovery walk stopped, and what it found there. */
+export interface DiscoveredRoot {
+    /** The project root the walk settled on. Always absolute; falls back to the
+     *  resolved start directory when the walk found no marker at all. */
+    readonly dir: string;
+    /** Whether `dir` carries `.metaobjects/config.json`. False only on the
+     *  no-marker fallback, where the DEFAULT sources apply. */
+    readonly hasConfig: boolean;
+}
+/**
+ * Walk up from `startDir` for the nearest project root — a directory holding
+ * `.metaobjects/config.json`, and nothing else (see the file header). The walk
+ * stops after examining a directory that contains `.git`, so a monorepo can
+ * never silently adopt a parent checkout's configuration.
+ *
+ * Never fails: with no config anywhere below the boundary it reports the
+ * resolved `startDir` with `hasConfig: false`, which is what
+ * `resolveCollection` turns into either the default source or
+ * `ERR_COLLECTION_NOT_FOUND`.
+ */
+export declare function discoverCollectionRoot(startDir: string): Promise<DiscoveredRoot>;
+/**
+ * The directory whose configuration governs a run started in `startDir` — the
+ * `dir` half of {@link discoverCollectionRoot}.
+ *
+ * Exists as its own export for the callers that must NOT require metadata to
+ * exist: `meta migrate apply-pending` and `--rollback` replay committed SQL and
+ * load no model at all, so they resolve their `.metaobjects/` directory through
+ * this rather than through `resolveCollection`. Sharing the walk is the point —
+ * a second "find the project root" implementation is how the migrations
+ * directory and the metadata directory come to disagree.
+ */
+export declare function resolveConfigDir(startDir: string): Promise<string>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAkCA;gDACgD;AAChD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;;;mEAImE;AACnE,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM1D;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B;yEACqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;+DAC2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAetF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE"}

package/dist/discovery.js

@@ -0,0 +1,100 @@
+// server/typescript/packages/sdk/src/discovery.ts
+//
+// Phase-1 metadata-source-resolution — nearest-ancestor collection discovery.
+//
+// Walks up from a starting directory to find the nearest directory that IS a
+// project root. This is what makes a CLI *contextual*: run it inside an app in
+// a monorepo and it finds that app's configuration rather than the repo root's.
+//
+// Three properties are load-bearing.
+//
+// 1. **One marker.** A directory is a project root when it carries
+//    `.metaobjects/config.json`, and on no other evidence. A directory that
+//    merely *holds* metadata is not a project boundary: where metadata lives is
+//    the `sources` key's answer, and `metaobjects/` is only that key's default
+//    value. Stopping on a bare `metaobjects/` directory would put a second
+//    definition of "where metadata lives" back into the walk — the exact
+//    duplication `resolveCollection` exists to be the only instance of — and it
+//    would ignore a project whose config points its `sources` somewhere else
+//    entirely. See design §4.6.1.
+// 2. **Nearest wins** — the walk returns on the FIRST directory carrying the
+//    marker, so a config in a subdirectory beats one in an ancestor.
+// 3. **The walk stops at a repository boundary** (`.git`), so a monorepo
+//    checkout can never silently adopt a *parent checkout's* configuration. The
+//    marker check runs BEFORE the `.git` check within each directory —
+//    reversed, a root-level project (where `.git` also lives) would be
+//    unreachable from any subdirectory, since the boundary would stop the walk
+//    one directory too early.
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_FILE } from "./config.js";
+import { DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+const GIT_DIR = ".git";
+/** Exported for reuse — `collection.ts` had its own byte-identical copy
+ *  (`fileExists`); one definition, imported. */
+export async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `exists`, narrowed to directories — `collection.ts`'s default-source probe
+ *  needs that distinction to raise its friendlier `ERR_COLLECTION_NOT_FOUND`
+ *  (a plain FILE where the default source directory should be is not a
+ *  metadata home). Lives here beside `exists` so there is one filesystem
+ *  predicate pair in the package rather than a copy per caller. */
+export async function isDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk up from `startDir` for the nearest project root — a directory holding
+ * `.metaobjects/config.json`, and nothing else (see the file header). The walk
+ * stops after examining a directory that contains `.git`, so a monorepo can
+ * never silently adopt a parent checkout's configuration.
+ *
+ * Never fails: with no config anywhere below the boundary it reports the
+ * resolved `startDir` with `hasConfig: false`, which is what
+ * `resolveCollection` turns into either the default source or
+ * `ERR_COLLECTION_NOT_FOUND`.
+ */
+export async function discoverCollectionRoot(startDir) {
+    const start = resolve(startDir);
+    let dir = start;
+    for (;;) {
+        if (await exists(join(dir, DEFAULT_METAOBJECTS_DIR, CONFIG_FILE))) {
+            return { dir, hasConfig: true };
+        }
+        // Boundary check AFTER the marker check: a repo-root project (sharing its
+        // directory with `.git`) is still findable from any subdirectory.
+        if (await exists(join(dir, GIT_DIR)))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { dir: start, hasConfig: false };
+}
+/**
+ * The directory whose configuration governs a run started in `startDir` — the
+ * `dir` half of {@link discoverCollectionRoot}.
+ *
+ * Exists as its own export for the callers that must NOT require metadata to
+ * exist: `meta migrate apply-pending` and `--rollback` replay committed SQL and
+ * load no model at all, so they resolve their `.metaobjects/` directory through
+ * this rather than through `resolveCollection`. Sharing the walk is the point —
+ * a second "find the project root" implementation is how the migrations
+ * directory and the metadata directory come to disagree.
+ */
+export async function resolveConfigDir(startDir) {
+    return (await discoverCollectionRoot(startDir)).dir;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,8EAA8E;AAC9E,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,qCAAqC;AACrC,EAAE;AACF,mEAAmE;AACnE,4EAA4E;AAC5E,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,yEAAyE;AACzE,gFAAgF;AAChF,6EAA6E;AAC7E,kCAAkC;AAClC,6EAA6E;AAC7E,qEAAqE;AACrE,yEAAyE;AACzE,gFAAgF;AAChF,uEAAuE;AACvE,uEAAuE;AACvE,+EAA+E;AAC/E,8BAA8B;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,OAAO,GAAG,MAAM,CAAC;AAEvB;gDACgD;AAChD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;mEAImE;AACnE,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAgB;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,SAAS,CAAC;QACR,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,uBAAuB,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClC,CAAC;QACD,0EAA0E;QAC1E,kEAAkE;QAClE,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAAE,MAAM;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAgB;IACrD,OAAO,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;AACtD,CAAC"}

package/dist/index.d.ts

@@ -12,8 +12,17 @@ export { ConfigSchema, DEFAULT_CONFIG, loadConfig, saveConfig, AllowTokenEnum }
 export type { Config } from "./config.js";
 export { FORGE_TYPE_DECISION, FORGE_TYPE_PRINCIPLE, FORGE_TYPE_CONVENTION, FORGE_TYPE_GLOSSARY, FORGE_TYPE_FAILURE, FORGE_TYPES, FORGE_DECISION_SUBTYPES, FORGE_PRINCIPLE_SUBTYPES, FORGE_CONVENTION_SUBTYPES, FORGE_GLOSSARY_SUBTYPES, FORGE_FAILURE_SUBTYPES, FORGE_ATTR_CONFIDENCE, FORGE_ATTR_SOURCE, FORGE_ATTR_CAPTURED_AT, FORGE_ATTR_LAST_VALIDATED_COMMIT, FORGE_ATTR_PRIMARY_LOCATION, FORGE_ATTR_OCCURRENCES, FORGE_ATTR_RATIONALE, FORGE_ATTR_ALTERNATIVES, FORGE_ATTR_SCOPE, FORGE_ATTR_STATEMENT, FORGE_ATTR_ENFORCEMENT, FORGE_ATTR_PATTERN_DESCRIPTION, FORGE_ATTR_EXAMPLES, FORGE_ATTR_COUNTER_EXAMPLES, FORGE_ATTR_APPLIES_TO, FORGE_ATTR_TERM, FORGE_ATTR_SYNONYMS, FORGE_ATTR_DEFINITION, FORGE_ATTR_CODE_ANCHORS, FORGE_ATTR_SEE_ALSO, FORGE_ATTR_WHAT_WAS_TRIED, FORGE_ATTR_WHY_IT_FAILED, FORGE_ATTRS, registerForgeTypes, forgeTypesProvider, } from "./forge-types.js";
 export type { ForgeType, ForgeAttr } from "./forge-types.js";
-export { loadMemory, defaultLoadMemoryProviders, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR, } from "./memory.js";
+export { loadMemory, defaultLoadMemoryProviders } from "./memory.js";
 export type { LoadMemoryOptions } from "./memory.js";
+export { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+export { compileScope, matchesScope } from "./scope.js";
+export type { Scope, CompiledScope } from "./scope.js";
+export { resolveSources, resolveSpecPath, orderedPathSpecs, DEFAULT_SOURCES } from "./sources.js";
+export type { SourceSpec, ResolvedSource } from "./sources.js";
+export { discoverCollectionRoot, resolveConfigDir } from "./discovery.js";
+export type { DiscoveredRoot } from "./discovery.js";
+export { resolveCollection } from "./collection.js";
+export type { Collection } from "./collection.js";
 export { discoverWorkspace, resolveExtendsOrder, packageLabel } from "./workspace.js";
 export type { Workspace, WorkspacePackage } from "./workspace.js";
 export { PackageManifestSchema, readPackageManifest, resolveMetaobjectsPackage, PACKAGE_MANIFEST_FILE, } from "./package.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACnG,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C,OAAO,EAEL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EAEX,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB,EAEtB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,mBAAmB,EACnB,2BAA2B,EAC3B,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,EACxB,WAAW,EAEX,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK7D,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtF,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAOlE,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}