mongo-query-normalizer 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -1,8 +1,11 @@
+import type { PredicateSafetyPolicy } from "./predicate/safety/predicate-safety-policy";
+import type { ScopeSafetyPolicy } from "./scope/safety/scope-safety-policy";
+import type { ConstraintExtractionRejection } from "./scope/context/constraint-set";
 /**
  * MongoDB 查询对象（规范化入口的输入/输出形状）
  */
 export type Query = Record<string, unknown>;
-export type NormalizeLevel = "shape" | "predicate" | "logical" | "experimental";
+export type NormalizeLevel = "shape" | "predicate" | "scope";
 export interface NormalizeRules {
     flattenLogical: boolean;
     removeEmptyLogical: boolean;
@@ -14,7 +17,6 @@ export interface NormalizeRules {
     sortLogicalChildren: boolean;
     sortFieldPredicates: boolean;
     detectCommonPredicatesInOr: boolean;
-    hoistCommonPredicatesFromOr: boolean;
 }
 export interface NormalizeSafety {
     maxNormalizeDepth: number;
@@ -23,18 +25,36 @@ export interface NormalizeSafety {
 export interface NormalizeObserve {
     collectWarnings: boolean;
     collectMetrics: boolean;
+    /** When true, `meta.predicateTraces` lists per-field planner and skip signals. */
+    collectPredicateTraces: boolean;
+    /** When true, `meta.scopeTrace` records propagation / prune / coverage decisions. */
+    collectScopeTraces: boolean;
+}
+export interface NormalizePredicateOptions {
+    safetyPolicy: PredicateSafetyPolicy;
+}
+export interface NormalizeScopeLayerOptions {
+    safetyPolicy: ScopeSafetyPolicy;
 }
 export interface NormalizeOptions {
     level?: NormalizeLevel;
     rules?: Partial<NormalizeRules>;
     safety?: Partial<NormalizeSafety>;
     observe?: Partial<NormalizeObserve>;
+    predicate?: {
+        safetyPolicy?: Partial<PredicateSafetyPolicy>;
+    };
+    scope?: {
+        safetyPolicy?: Partial<ScopeSafetyPolicy>;
+    };
 }
 export interface ResolvedNormalizeOptions {
     level: NormalizeLevel;
     rules: NormalizeRules;
     safety: NormalizeSafety;
     observe: NormalizeObserve;
+    predicate: NormalizePredicateOptions;
+    scope: NormalizeScopeLayerOptions;
 }
 export interface NodeStats {
     nodeCount: number;
@@ -44,6 +64,51 @@ export interface NodeStats {
 }
 /** 对外名称：`meta.stats` 中 before/after 的树统计。 */
 export type NormalizeStats = NodeStats;
+export type PredicateCapabilitySkipTrace = {
+    id: string;
+    reason: string;
+};
+export type PredicateFieldTrace = {
+    field: string;
+    atomKinds: string[];
+    appliedCapabilityIds: string[];
+    skippedCapabilities: PredicateCapabilitySkipTrace[];
+    contradiction: boolean;
+    /** When set, identifies the capability that first reported local contradiction. */
+    contradictionCapabilityId?: string;
+    hadCoverage: boolean;
+    /** Number of predicate atoms removed as redundant (same round). */
+    coverageAtomCount: number;
+    hadTighten: boolean;
+    /** True when this field normalized to an unsatisfiable selector (FalseNode → IMPOSSIBLE_SELECTOR). */
+    impossibleEmitted: boolean;
+};
+export type ScopeTraceEvent = {
+    type: "or-branch-inherited";
+    satisfiabilityCheck: "skipped" | "ran";
+    satisfiable?: boolean;
+    detail: string;
+} | {
+    type: "prune-branch";
+    outcome: "pruned-to-false" | "skipped-by-policy";
+    detail: string;
+} | {
+    type: "coverage-removal";
+    outcome: "replaced-with-true" | "unchanged";
+    detail: string;
+} | {
+    type: "collapse-or";
+    outcome: "collapsed-single-child" | "unchanged";
+    detail: string;
+} | {
+    type: "and-propagation";
+    outcome: "applied" | "skipped-by-policy";
+    detail: string;
+};
+export type ScopeNormalizationTrace = {
+    constraintRejections: ConstraintExtractionRejection[];
+    events: ScopeTraceEvent[];
+};
 export interface NormalizeMeta {
     changed: boolean;
     level: NormalizeLevel;
@@ -58,6 +123,8 @@ export interface NormalizeMeta {
         before: NodeStats;
         after: NodeStats;
     };
+    predicateTraces?: PredicateFieldTrace[];
+    scopeTrace?: ScopeNormalizationTrace;
 }
 export interface NormalizeResult<Q = Query> {
     query: Q;
@@ -66,5 +133,6 @@ export interface NormalizeResult<Q = Query> {
 /**
  * FalseNode 编译结果：不可满足选择器（与设计文档一致）
  */
+/** Canonical unsatisfiable filter: no document has a missing top-level `_id` in normal collections. */
 export declare const IMPOSSIBLE_SELECTOR: Query;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,cAAc,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC3B,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,0BAA0B,EAAE,OAAO,CAAC;IACpC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,yBAAyB,EAAE,OAAO,CAAC;IACnC,yBAAyB,EAAE,OAAO,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;IAChC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,0BAA0B,EAAE,OAAO,CAAC;IACpC,2BAA2B,EAAE,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,cAAc,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QACJ,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,SAAS,CAAC;KACpB,CAAC;CACL;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,KAAK;IACtC,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAA2C,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -4,5 +4,6 @@ exports.IMPOSSIBLE_SELECTOR = void 0;
 /**
  * FalseNode 编译结果：不可满足选择器（与设计文档一致）
  */
-exports.IMPOSSIBLE_SELECTOR = { $expr: { $eq: [1, 0] } };
+/** Canonical unsatisfiable filter: no document has a missing top-level `_id` in normal collections. */
+exports.IMPOSSIBLE_SELECTOR = { _id: { $exists: false } };
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA4EA;;GAEG;AACU,QAAA,mBAAmB,GAAU,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAW,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA2JA;;GAEG;AACH,uGAAuG;AAC1F,QAAA,mBAAmB,GAAU,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAW,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongo-query-normalizer",
-  "version": "0.1.0",
-  "description": "Observable, level-based normalizer for MongoDB query objects. Defaults to conservative shape stabilization; higher levels are preview surfaces in v0.1.0. Predictable output and metadata—not planner optimization.",
+  "version": "0.2.0",
+  "description": "Observable, level-based normalizer for MongoDB query objects. Defaults to conservative shape stabilization; optional predicate and scope levels with documented contracts. Predictable output and metadata—not planner optimization.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -13,11 +13,13 @@
   "scripts": {
     "build": "tsc",
     "test": "npm run build && npm run test:unit && npm run test:semantic",
+    "test:api": "mocha \"test/api/**/*.test.js\"",
+    "test:levels": "mocha \"test/levels/**/*.test.js\" \"test/contracts/*.test.js\"",
     "test:unit": "mocha \"test/**/*.test.js\" --ignore \"test/semantic/**/*.test.js\" --ignore \"test/regression/**/*.test.js\" --ignore \"test/property/**/*.test.js\"",
     "test:semantic": "mocha --require ./test/helpers/mocha-semantic-hooks.js \"test/semantic/**/*.test.js\" \"test/regression/**/*.test.js\" \"test/property/**/*.test.js\"",
     "test:semantic:quick": "FC_SEED=42 FC_RUNS=45 mocha --require ./test/helpers/mocha-semantic-hooks.js \"test/semantic/**/*.test.js\" \"test/regression/**/*.test.js\" \"test/property/**/*.test.js\"",
     "test:semantic:ci": "FC_RUNS=200 FC_SEED=42 mocha --require ./test/helpers/mocha-semantic-hooks.js \"test/semantic/**/*.test.js\" \"test/regression/**/*.test.js\" \"test/property/**/*.test.js\"",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm test && npm run build"
   },
   "author": "",
   "license": "ISC",
@@ -48,4 +50,4 @@
     "mongodb-memory-server": "^11.0.1",
     "typescript": "^5.0.0"
   }
-}
+}