@smthrs/plan 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/internal/EffectCandidates.js

@@ -0,0 +1,86 @@
+/**
+ * Rebuildable candidate index for the compiler's existing overlap predicate.
+ * Exact paths and tree prefixes share a trie keyed by case-folded segments, the
+ * form FileSet.overlaps compares. A plain string is a literal path there, even
+ * one holding `*`. Globs stay conservative: their exclusions and pair semantics
+ * are decided by FileSet.overlaps, never here.
+ * Nothing in this index becomes persisted plan or key material.
+ * @since 0.1.0
+ * @private
+ */
+import * as FileSet from "../FileSet.js";
+const branch = () => ({ children: new Map(), exact: new Set(), trees: new Set() });
+const add = (target, values) => {
+    for (const value of values)
+        target.add(value);
+};
+/** A Glob has no single trie position, so it stays conservative. */
+const patternLike = (entry) => typeof entry !== "string" && entry._tag === "Glob";
+const ordered = (values) => Array.from(values).sort((left, right) => left - right);
+/**
+ * Selects possible producers in declaration order; callers retain the final
+ * FileSet.overlaps check for every selected pair.
+ * @since 0.1.0
+ * @private
+ */
+export const make = (produced) => {
+    const root = branch();
+    const all = new Set();
+    const globs = new Set();
+    for (let owner = 0; owner < produced.length; owner++) {
+        for (const entry of produced[owner]) {
+            all.add(owner);
+            if (patternLike(entry)) {
+                globs.add(owner);
+                continue;
+            }
+            const path = typeof entry === "string" ? entry : entry.path;
+            let current = root;
+            for (const segment of FileSet.folded(path).split("/")) {
+                let child = current.children.get(segment);
+                if (child === undefined) {
+                    child = branch();
+                    current.children.set(segment, child);
+                }
+                current = child;
+            }
+            const owners = typeof entry === "string" ? current.exact : current.trees;
+            owners.add(owner);
+        }
+    }
+    return (entries) => {
+        const found = new Set();
+        for (const entry of entries) {
+            // A glob can overlap every other glob/tree; literal matches and
+            // exclusions remain the final predicate's responsibility as well.
+            if (patternLike(entry))
+                return ordered(all);
+            add(found, globs);
+            const path = typeof entry === "string" ? entry : entry.path;
+            let current = root;
+            for (const segment of FileSet.folded(path).split("/")) {
+                current = current.children.get(segment);
+                if (current === undefined)
+                    break;
+                add(found, current.trees);
+            }
+            if (current === undefined)
+                continue;
+            add(found, current.exact);
+            if (typeof entry === "string")
+                continue;
+            const stack = Array.from(current.children.values());
+            while (stack.length > 0) {
+                const descendant = stack.pop();
+                add(found, descendant.exact);
+                add(found, descendant.trees);
+                for (const child of descendant.children.values())
+                    stack.push(child);
+            }
+        }
+        // Original declaration order controls annotations, conflict precedence,
+        // and cycle diagnostics, irrespective of trie or Set traversal order.
+        return ordered(found);
+    };
+};
+//# sourceMappingURL=EffectCandidates.js.map

package/dist/esm/internal/EffectCandidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectCandidates.js","sourceRoot":"","sources":["../../../src/internal/EffectCandidates.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Rebuildable candidate index for the compiler's existing overlap predicate.\n * Exact paths and tree prefixes share a trie keyed by case-folded segments, the\n * form FileSet.overlaps compares. A plain string is a literal path there, even\n * one holding `*`. Globs stay conservative: their exclusions and pair semantics\n * are decided by FileSet.overlaps, never here.\n * Nothing in this index becomes persisted plan or key material.\n * @since 0.1.0\n * @private\n */\n\nimport * as FileSet from \"../FileSet.ts\"\n\ninterface Branch {\n  readonly children: Map<string, Branch>\n  readonly exact: Set<number>\n  readonly trees: Set<number>\n}\n\nconst branch = (): Branch => ({ children: new Map(), exact: new Set(), trees: new Set() })\nconst add = (target: Set<number>, values: ReadonlySet<number>): void => {\n  for (const value of values) target.add(value)\n}\n/** A Glob has no single trie position, so it stays conservative. */\nconst patternLike = (entry: FileSet.Entry): entry is FileSet.Glob => typeof entry !== \"string\" && entry._tag === \"Glob\"\nconst ordered = (values: ReadonlySet<number>): Array<number> => Array.from(values).sort((left, right) => left - right)\n\n/**\n * Selects possible producers in declaration order; callers retain the final\n * FileSet.overlaps check for every selected pair.\n * @since 0.1.0\n * @private\n */\nexport const make = (produced: ReadonlyArray<ReadonlyArray<FileSet.Entry>>) => {\n  const root = branch()\n  const all = new Set<number>()\n  const globs = new Set<number>()\n  for (let owner = 0; owner < produced.length; owner++) {\n    for (const entry of produced[owner]!) {\n      all.add(owner)\n      if (patternLike(entry)) {\n        globs.add(owner)\n        continue\n      }\n      const path = typeof entry === \"string\" ? entry : entry.path\n      let current = root\n      for (const segment of FileSet.folded(path).split(\"/\")) {\n        let child = current.children.get(segment)\n        if (child === undefined) {\n          child = branch()\n          current.children.set(segment, child)\n        }\n        current = child\n      }\n      const owners = typeof entry === \"string\" ? current.exact : current.trees\n      owners.add(owner)\n    }\n  }\n\n  return (entries: ReadonlyArray<FileSet.Entry>): ReadonlyArray<number> => {\n    const found = new Set<number>()\n    for (const entry of entries) {\n      // A glob can overlap every other glob/tree; literal matches and\n      // exclusions remain the final predicate's responsibility as well.\n      if (patternLike(entry)) return ordered(all)\n      add(found, globs)\n      const path = typeof entry === \"string\" ? entry : entry.path\n      let current: Branch | undefined = root\n      for (const segment of FileSet.folded(path).split(\"/\")) {\n        current = current.children.get(segment)\n        if (current === undefined) break\n        add(found, current.trees)\n      }\n      if (current === undefined) continue\n      add(found, current.exact)\n      if (typeof entry === \"string\") continue\n      const stack = Array.from(current.children.values())\n      while (stack.length > 0) {\n        const descendant = stack.pop()!\n        add(found, descendant.exact)\n        add(found, descendant.trees)\n        for (const child of descendant.children.values()) stack.push(child)\n      }\n    }\n    // Original declaration order controls annotations, conflict precedence,\n    // and cycle diagnostics, irrespective of trie or Set traversal order.\n    return ordered(found)\n  }\n}\n"]}

package/dist/esm/internal/JsonMirror.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The inert JSON mirror of a value: what `JSON.stringify` would see, as data.
+ *
+ * The AST stores payloads this way, the plan compiler stores key material this
+ * way, and a plan diff compares declarations this way, so all three share the
+ * one walk. A planned value is the only member with no JSON meaning of its
+ * own, and each caller decides what it becomes.
+ *
+ * @since 0.1.0
+ * @private
+ */
+import * as Planned from "../Planned.ts";
+/**
+ * Clones the JSON mirror of the input, so {@link module:StepKey.content} over
+ * the clone and the input produce the same key and the clone holds only inert
+ * JSON data. The walk uses an explicit stack, memoizes shared references and
+ * cycles, honors callable `toJSON`, omits object members without a JSON
+ * representation, and writes `null` for those values in arrays.
+ *
+ * `toJSON` receives the key canonical serialization passes it: the member
+ * name, the array index, or `""` at the root. Its replacement is therefore
+ * memoized per source and key, since one shared source may serialize
+ * differently at two positions. A source met again inside its own
+ * replacement reuses that replacement, so a cycle through `toJSON` clones as
+ * a cycle whatever key it recurs at.
+ *
+ * A planned value becomes whatever `plannedValue` returns for it. Refusals
+ * throw a {@link GraphBuildError} naming the member's path.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export declare const jsonMirror: (input: unknown, plannedValue: (value: unknown, reference: Planned.Reference) => unknown) => unknown;
+//# sourceMappingURL=JsonMirror.d.ts.map

package/dist/esm/internal/JsonMirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonMirror.d.ts","sourceRoot":"","sources":["../../../src/internal/JsonMirror.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,OAAO,MAAM,eAAe,CAAA;AAqFxC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,OAAO,EACd,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,KAAK,OAAO,KACtE,OAqIF,CAAA"}

package/dist/esm/internal/JsonMirror.js

@@ -0,0 +1,204 @@
+/**
+ * The inert JSON mirror of a value: what `JSON.stringify` would see, as data.
+ *
+ * The AST stores payloads this way, the plan compiler stores key material this
+ * way, and a plan diff compares declarations this way, so all three share the
+ * one walk. A planned value is the only member with no JSON meaning of its
+ * own, and each caller decides what it becomes.
+ *
+ * @since 0.1.0
+ * @private
+ */
+import { GraphBuildError } from "../GraphBuildError.js";
+import * as Planned from "../Planned.js";
+/** The chain read outwards, root first: the array the refusals report. */
+const clonePath = (path) => {
+    const keys = [];
+    for (let current = path; current !== undefined; current = current.parent)
+        keys.push(current.key);
+    return keys.reverse();
+};
+const payloadError = (at, reason) => {
+    const path = clonePath(at);
+    return new GraphBuildError({
+        code: "invalid_payload",
+        node: "payload",
+        path,
+        message: `Plan payload at ${path.length === 0 ? "$" : `$.${path.join(".")}`} ${reason}`
+    });
+};
+const cyclicPayloadError = (at) => {
+    const path = clonePath(at);
+    return new GraphBuildError({
+        code: "cyclic_payload",
+        node: "payload",
+        path,
+        message: `Plan payload at ${path.length === 0 ? "$" : `$.${path.join(".")}`} has a toJSON method that returns itself`
+    });
+};
+const inheritedDataProperty = (value, key) => {
+    let current = value;
+    while (current !== null) {
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (descriptor !== undefined) {
+            return "value" in descriptor ? { kind: "data", value: descriptor.value } : { kind: "accessor" };
+        }
+        current = Object.getPrototypeOf(current);
+    }
+    return { kind: "missing" };
+};
+/**
+ * Clones the JSON mirror of the input, so {@link module:StepKey.content} over
+ * the clone and the input produce the same key and the clone holds only inert
+ * JSON data. The walk uses an explicit stack, memoizes shared references and
+ * cycles, honors callable `toJSON`, omits object members without a JSON
+ * representation, and writes `null` for those values in arrays.
+ *
+ * `toJSON` receives the key canonical serialization passes it: the member
+ * name, the array index, or `""` at the root. Its replacement is therefore
+ * memoized per source and key, since one shared source may serialize
+ * differently at two positions. A source met again inside its own
+ * replacement reuses that replacement, so a cycle through `toJSON` clones as
+ * a cycle whatever key it recurs at.
+ *
+ * A planned value becomes whatever `plannedValue` returns for it. Refusals
+ * throw a {@link GraphBuildError} naming the member's path.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const jsonMirror = (input, plannedValue) => {
+    const missing = Symbol("missing JSON representation");
+    const seen = new WeakMap();
+    const replacedAt = new WeakMap();
+    const open = new Map();
+    let result;
+    const frames = [];
+    /** Resolves one member, opening a frame when it is an unseen container. */
+    const enter = (initial, place, path) => {
+        let current = initial;
+        const key = path === undefined ? "" : path.key;
+        const replacements = [];
+        const resolving = new WeakSet();
+        const finish = (member) => {
+            for (const replacement of replacements) {
+                let byKey = replacedAt.get(replacement);
+                if (byKey === undefined)
+                    replacedAt.set(replacement, byKey = new Map());
+                byKey.set(key, member);
+            }
+            place(member);
+        };
+        while (true) {
+            const reference = Planned.reference(current);
+            if (reference !== undefined) {
+                finish(plannedValue(current, reference));
+                return;
+            }
+            const kind = typeof current;
+            if (current === null || (kind !== "object" && kind !== "function")) {
+                finish(kind === "undefined" || kind === "symbol" ? missing : current);
+                return;
+            }
+            const source = current;
+            if (seen.has(source)) {
+                finish(seen.get(source));
+                return;
+            }
+            if (resolving.has(source)) {
+                throw cyclicPayloadError(path);
+            }
+            const toJSON = inheritedDataProperty(source, "toJSON");
+            if (toJSON.kind === "accessor") {
+                throw payloadError(path, "has an accessor-backed toJSON member");
+            }
+            if (toJSON.kind === "data" && typeof toJSON.value === "function") {
+                const byKey = replacedAt.get(source);
+                if (byKey !== undefined && byKey.has(key)) {
+                    finish(byKey.get(key));
+                    return;
+                }
+                if (open.has(source)) {
+                    finish(open.get(source));
+                    return;
+                }
+                resolving.add(source);
+                replacements.push(source);
+                current = Reflect.apply(toJSON.value, source, [key]);
+                continue;
+            }
+            if (kind === "function") {
+                seen.set(source, missing);
+                finish(missing);
+                return;
+            }
+            const prototype = Object.getPrototypeOf(source);
+            if (!Array.isArray(source) && prototype !== Object.prototype && prototype !== null) {
+                throw payloadError(path, "has an unsupported prototype and no data-valued toJSON method");
+            }
+            const container = current;
+            const descriptors = Object.getOwnPropertyDescriptors(container);
+            const output = Array.isArray(container)
+                ? []
+                : Object.create(null);
+            seen.set(container, output);
+            finish(output);
+            frames.push({
+                source: container,
+                output,
+                descriptors,
+                keys: Array.isArray(container)
+                    ? undefined
+                    : Reflect.ownKeys(descriptors).filter((key) => typeof key === "string" && descriptors[key].enumerable === true),
+                path,
+                replaced: replacements,
+                index: 0
+            });
+            for (const replacement of replacements)
+                open.set(replacement, output);
+            return;
+        }
+    };
+    enter(input, (member) => {
+        result = member === missing ? undefined : member;
+    }, undefined);
+    while (frames.length > 0) {
+        const frame = frames[frames.length - 1];
+        if (frame.index >= (frame.keys ?? frame.source).length) {
+            frames.pop();
+            for (const replacement of frame.replaced)
+                open.delete(replacement);
+            continue;
+        }
+        const position = frame.index;
+        frame.index = position + 1;
+        if (frame.keys === undefined) {
+            const members = frame.output;
+            const descriptor = frame.descriptors[String(position)];
+            if (descriptor !== undefined && !("value" in descriptor)) {
+                throw payloadError({ parent: frame.path, key: String(position) }, "is an accessor");
+            }
+            enter(descriptor === undefined ? undefined : descriptor.value, (member) => {
+                members.push(member === missing ? null : member);
+            }, { parent: frame.path, key: String(position) });
+        }
+        else {
+            const key = frame.keys[position];
+            const descriptor = frame.descriptors[key];
+            if (!("value" in descriptor))
+                throw payloadError({ parent: frame.path, key }, "is an accessor");
+            enter(descriptor.value, (member) => {
+                if (member === missing)
+                    return;
+                Object.defineProperty(frame.output, key, {
+                    configurable: true,
+                    enumerable: true,
+                    value: member,
+                    writable: true
+                });
+            }, { parent: frame.path, key });
+        }
+    }
+    return result;
+};
+//# sourceMappingURL=JsonMirror.js.map

package/dist/esm/internal/JsonMirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonMirror.js","sourceRoot":"","sources":["../../../src/internal/JsonMirror.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The inert JSON mirror of a value: what `JSON.stringify` would see, as data.\n *\n * The AST stores payloads this way, the plan compiler stores key material this\n * way, and a plan diff compares declarations this way, so all three share the\n * one walk. A planned value is the only member with no JSON meaning of its\n * own, and each caller decides what it becomes.\n *\n * @since 0.1.0\n * @private\n */\n\nimport { GraphBuildError } from \"../GraphBuildError.ts\"\nimport * as Planned from \"../Planned.ts\"\n\n/**\n * One container being cloned: the object walked, the clone being filled, and\n * the member position the walk has reached. `keys` is `undefined` for an\n * array, whose members are positional.\n *\n * @since 0.1.0\n * @private\n */\ninterface CloneFrame {\n  readonly source: Record<string, unknown> | ReadonlyArray<unknown>\n  readonly output: Record<string, unknown> | Array<unknown>\n  readonly descriptors: PropertyDescriptorMap\n  readonly keys: ReadonlyArray<string> | undefined\n  readonly path: ClonePath\n  /** Sources whose callable `toJSON` resolved to this container. */\n  readonly replaced: ReadonlyArray<object>\n  index: number\n}\n\n/**\n * Where the walk stands, as a link to its parent rather than a copy of the\n * whole path. Payload depth is bounded only by the caller, and copying the\n * path at each member made a clone cost memory quadratic in that depth: a\n * 20,000-deep payload held 20,000 live frames whose paths together ran to\n * hundreds of millions of entries, several gigabytes, for a result that is\n * linear. The path is read only to name a member in a refusal, so it stays a\n * chain here and is flattened at the throw.\n *\n * `undefined` is the root, whose path is empty.\n *\n * @since 0.1.0\n * @private\n */\ntype ClonePath = { readonly parent: ClonePath; readonly key: string } | undefined\n\n/** The chain read outwards, root first: the array the refusals report. */\nconst clonePath = (path: ClonePath): ReadonlyArray<string> => {\n  const keys: Array<string> = []\n  for (let current = path; current !== undefined; current = current.parent) keys.push(current.key)\n  return keys.reverse()\n}\n\nconst payloadError = (at: ClonePath, reason: string): GraphBuildError => {\n  const path = clonePath(at)\n  return new GraphBuildError({\n    code: \"invalid_payload\",\n    node: \"payload\",\n    path,\n    message: `Plan payload at ${path.length === 0 ? \"$\" : `$.${path.join(\".\")}`} ${reason}`\n  })\n}\n\nconst cyclicPayloadError = (at: ClonePath): GraphBuildError => {\n  const path = clonePath(at)\n  return new GraphBuildError({\n    code: \"cyclic_payload\",\n    node: \"payload\",\n    path,\n    message: `Plan payload at ${\n      path.length === 0 ? \"$\" : `$.${path.join(\".\")}`\n    } has a toJSON method that returns itself`\n  })\n}\n\nconst inheritedDataProperty = (\n  value: object,\n  key: PropertyKey\n):\n  | { readonly kind: \"data\"; readonly value: unknown }\n  | { readonly kind: \"accessor\" }\n  | { readonly kind: \"missing\" } =>\n{\n  let current: object | null = value\n  while (current !== null) {\n    const descriptor = Object.getOwnPropertyDescriptor(current, key)\n    if (descriptor !== undefined) {\n      return \"value\" in descriptor ? { kind: \"data\", value: descriptor.value } : { kind: \"accessor\" }\n    }\n    current = Object.getPrototypeOf(current) as object | null\n  }\n  return { kind: \"missing\" }\n}\n\n/**\n * Clones the JSON mirror of the input, so {@link module:StepKey.content} over\n * the clone and the input produce the same key and the clone holds only inert\n * JSON data. The walk uses an explicit stack, memoizes shared references and\n * cycles, honors callable `toJSON`, omits object members without a JSON\n * representation, and writes `null` for those values in arrays.\n *\n * `toJSON` receives the key canonical serialization passes it: the member\n * name, the array index, or `\"\"` at the root. Its replacement is therefore\n * memoized per source and key, since one shared source may serialize\n * differently at two positions. A source met again inside its own\n * replacement reuses that replacement, so a cycle through `toJSON` clones as\n * a cycle whatever key it recurs at.\n *\n * A planned value becomes whatever `plannedValue` returns for it. Refusals\n * throw a {@link GraphBuildError} naming the member's path.\n *\n * @since 0.1.0\n * @private\n */\nexport const jsonMirror = (\n  input: unknown,\n  plannedValue: (value: unknown, reference: Planned.Reference) => unknown\n): unknown => {\n  const missing = Symbol(\"missing JSON representation\")\n  const seen = new WeakMap<object, unknown>()\n  const replacedAt = new WeakMap<object, Map<string, unknown>>()\n  const open = new Map<object, unknown>()\n  let result: unknown\n  const frames: Array<CloneFrame> = []\n  /** Resolves one member, opening a frame when it is an unseen container. */\n  const enter = (\n    initial: unknown,\n    place: (member: unknown | typeof missing) => void,\n    path: ClonePath\n  ): void => {\n    let current = initial\n    const key = path === undefined ? \"\" : path.key\n    const replacements: Array<object> = []\n    const resolving = new WeakSet<object>()\n    const finish = (member: unknown | typeof missing): void => {\n      for (const replacement of replacements) {\n        let byKey = replacedAt.get(replacement)\n        if (byKey === undefined) replacedAt.set(replacement, byKey = new Map())\n        byKey.set(key, member)\n      }\n      place(member)\n    }\n    while (true) {\n      const reference = Planned.reference(current)\n      if (reference !== undefined) {\n        finish(plannedValue(current, reference))\n        return\n      }\n      const kind = typeof current\n      if (current === null || (kind !== \"object\" && kind !== \"function\")) {\n        finish(kind === \"undefined\" || kind === \"symbol\" ? missing : current)\n        return\n      }\n      const source = current as object\n      if (seen.has(source)) {\n        finish(seen.get(source))\n        return\n      }\n      if (resolving.has(source)) {\n        throw cyclicPayloadError(path)\n      }\n      const toJSON = inheritedDataProperty(source, \"toJSON\")\n      if (toJSON.kind === \"accessor\") {\n        throw payloadError(path, \"has an accessor-backed toJSON member\")\n      }\n      if (toJSON.kind === \"data\" && typeof toJSON.value === \"function\") {\n        const byKey = replacedAt.get(source)\n        if (byKey !== undefined && byKey.has(key)) {\n          finish(byKey.get(key))\n          return\n        }\n        if (open.has(source)) {\n          finish(open.get(source))\n          return\n        }\n        resolving.add(source)\n        replacements.push(source)\n        current = Reflect.apply(toJSON.value, source, [key])\n        continue\n      }\n      if (kind === \"function\") {\n        seen.set(source, missing)\n        finish(missing)\n        return\n      }\n      const prototype = Object.getPrototypeOf(source)\n      if (!Array.isArray(source) && prototype !== Object.prototype && prototype !== null) {\n        throw payloadError(path, \"has an unsupported prototype and no data-valued toJSON method\")\n      }\n      const container = current as Record<string, unknown> | ReadonlyArray<unknown>\n      const descriptors = Object.getOwnPropertyDescriptors(container) as PropertyDescriptorMap\n      const output: Record<string, unknown> | Array<unknown> = Array.isArray(container)\n        ? []\n        : Object.create(null) as Record<string, unknown>\n      seen.set(container, output)\n      finish(output)\n      frames.push({\n        source: container,\n        output,\n        descriptors,\n        keys: Array.isArray(container)\n          ? undefined\n          : Reflect.ownKeys(descriptors).filter((key): key is string =>\n            typeof key === \"string\" && descriptors[key]!.enumerable === true\n          ),\n        path,\n        replaced: replacements,\n        index: 0\n      })\n      for (const replacement of replacements) open.set(replacement, output)\n      return\n    }\n  }\n  enter(input, (member) => {\n    result = member === missing ? undefined : member\n  }, undefined)\n  while (frames.length > 0) {\n    const frame = frames[frames.length - 1]!\n    if (frame.index >= (frame.keys ?? frame.source as ReadonlyArray<unknown>).length) {\n      frames.pop()\n      for (const replacement of frame.replaced) open.delete(replacement)\n      continue\n    }\n    const position = frame.index\n    frame.index = position + 1\n    if (frame.keys === undefined) {\n      const members = frame.output as Array<unknown>\n      const descriptor = frame.descriptors[String(position)]\n      if (descriptor !== undefined && !(\"value\" in descriptor)) {\n        throw payloadError({ parent: frame.path, key: String(position) }, \"is an accessor\")\n      }\n      enter(descriptor === undefined ? undefined : descriptor.value, (member) => {\n        members.push(member === missing ? null : member)\n      }, { parent: frame.path, key: String(position) })\n    } else {\n      const key = frame.keys[position]!\n      const descriptor = frame.descriptors[key]!\n      if (!(\"value\" in descriptor)) throw payloadError({ parent: frame.path, key }, \"is an accessor\")\n      enter(descriptor.value, (member) => {\n        if (member === missing) return\n        Object.defineProperty(frame.output, key, {\n          configurable: true,\n          enumerable: true,\n          value: member,\n          writable: true\n        })\n      }, { parent: frame.path, key })\n    }\n  }\n  return result\n}\n"]}

package/dist/esm/internal/effects.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Path indexing shared by effect matching and the graph's write-conflict pass.
+ *
+ * The pattern grammar is exhaustive: an entry ending in `*` matches by string
+ * prefix and every other entry matches itself alone. Every path is read a
+ * bounded number of times: once to look for a dot segment, once to detect a
+ * pattern, and once per comparison a binary search needs while the distinct
+ * paths are sorted and each pattern's prefix is located. After that a path is
+ * an integer rank and every match is an integer comparison, so matching two
+ * declarations costs their combined length plus the matches, whatever the
+ * paths' lengths or how many patterns nest. An envelope is prepared once for
+ * every step it encloses: its exact entries go into a set and its covering
+ * patterns collapse to disjoint sorted prefixes, so a step path costs one
+ * lookup and one binary search however wide the envelope is.
+ *
+ * Governing contract: `packages/smithers/flows/plan/docs/api.md`, published as
+ * https://smithers.sh/docs/reference/api/plan.
+ *
+ * @since 1.0.0-rc.0
+ */
+import type * as Effects from "../Effects.ts";
+/**
+ * Whether `path` contains a whole `.` or `..` segment.
+ *
+ * A path with no `.` costs one native search. Otherwise the segments from the
+ * one holding the first `.` onward are scanned once, without allocating.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const hasDotSegment: (path: string) => boolean;
+/**
+ * Whether an entry is a pattern: only a trailing `*` makes one.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const isGlob: (entry: string) => boolean;
+/**
+ * The string prefix a pattern matches by: everything for `*` and `**`,
+ * `prefix/` for `prefix/**`, and `prefix` for `prefix*`.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const globPrefix: (glob: string) => string;
+/**
+ * The distinct paths of one or more declarations in code-unit order, with
+ * what matching needs to know about each: its rank, whether it carries a dot
+ * segment, whether it is a pattern that can cover anything, and for such a
+ * pattern the rank interval its prefix covers.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export interface PathIndex {
+    readonly paths: ReadonlyArray<string>;
+    readonly rank: ReadonlyMap<string, number>;
+    readonly dotted: Uint8Array;
+    readonly glob: Uint8Array;
+    readonly low: Int32Array;
+    readonly high: Int32Array;
+}
+/**
+ * Indexes the union of the given path lists.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const indexPaths: (lists: Iterable<ReadonlyArray<string>>) => PathIndex;
+/**
+ * One declaration's paths as ranks of a {@link PathIndex}: every path in
+ * ascending rank order, and the patterns whose prefix intervals are not
+ * contained in another of the declaration's patterns. Those intervals are
+ * disjoint and ascending, so enumerating them visits each covered rank once.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export interface Ranked {
+    readonly ranks: Int32Array;
+    readonly globs: Int32Array;
+}
+/**
+ * Ranks a declaration's paths against an index that contains them.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const rankPaths: (index: PathIndex, paths: ReadonlyArray<string>) => Ranked;
+/**
+ * The ranks of the paths two write declarations share, ascending: a path of
+ * `b` that `a` names or covers, and a path of `a` that `b` covers unless it is
+ * the same pattern or itself covers that pattern. This is the pairwise
+ * definition, exact paths matched through the merge of two sorted rank lists
+ * and each covering pattern enumerating the ranks of the other declaration
+ * inside its interval. Each of the three passes yields an ascending list, so
+ * the result is their merge and no sort is needed.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const overlapRanks: (index: PathIndex, a: Ranked, b: Ranked) => Array<number>;
+/**
+ * One envelope list prepared for repeated coverage checks: its distinct
+ * entries, matched exactly through a set, and the prefixes of its covering
+ * patterns with every pattern nested under another collapsed into the
+ * outermost. The kept prefixes are disjoint and sorted, so the only prefix
+ * that can cover a path is the greatest one not greater than the path, and
+ * one binary search finds it.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export interface Prepared {
+    readonly exact: ReadonlySet<string>;
+    readonly prefixes: ReadonlyArray<string>;
+}
+/**
+ * Prepares one envelope list. Each entry is read a bounded number of times:
+ * once into the set, once to detect a pattern, and for a pattern once to take
+ * its prefix and once to test that prefix for a dot segment, plus the
+ * comparisons that sort the prefixes and one prefix comparison that collapses
+ * a nested one.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const prepare: (paths: ReadonlyArray<string>) => Prepared;
+/**
+ * Whether a prepared list names or covers `path`. A path carrying a dot
+ * segment is never covered, so the path is scanned once for one and, when
+ * clean, looked up once and compared against at most one prefix.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const covered: (prepared: Prepared, path: string) => boolean;
+/**
+ * The fields of a declaration that narrowing reads. Structural, so this module
+ * needs nothing from the public module built on it.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export interface DeclarationLike {
+    readonly reads: ReadonlyArray<string>;
+    readonly writes: ReadonlyArray<string>;
+    readonly mode: Effects.Mode;
+    readonly tier?: Effects.Tier | undefined;
+}
+/**
+ * An envelope prepared once for every step it encloses.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export interface PreparedEnvelope {
+    readonly reads: Prepared;
+    readonly writes: Prepared;
+    readonly mode: Effects.Mode;
+    readonly tier: Effects.Tier;
+}
+/**
+ * The outcome of narrowing a step against a prepared envelope, shaped as the
+ * public `NarrowResult`.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export type NarrowOutcome = Effects.NarrowResult;
+/**
+ * Prepares both lists of an envelope.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const prepareEnvelope: (envelope: DeclarationLike) => PreparedEnvelope;
+/**
+ * Verifies that a step stays within a prepared envelope: every read and write
+ * path must be covered by the matching list, the mode may only tighten, and
+ * the tier may only narrow. Each step path costs one coverage check.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export declare const narrowPrepared: (envelope: PreparedEnvelope, step: DeclarationLike) => NarrowOutcome;
+/**
+ * Maximum length, in UTF-16 code units, of one effect path a graph build
+ * admits before it refuses the plan as too large. 4096 is `PATH_MAX`
+ * on Linux, the longest path a supported host can open, so no path that names
+ * a file is refused. Every per-character cost of a build is bounded by it:
+ * the one dot-segment scan each path gets, the comparisons that sort the
+ * distinct paths, and the comparisons that locate each pattern's prefix. The
+ * length is read before any character is, so an over-long path costs one
+ * property read.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumPathLength = 4096;
+/**
+ * Maximum number of patterns, entries ending in `*`, one read list or one
+ * write list of an effect declaration may carry before a graph build refuses
+ * the plan as too large. A pattern never costs a match more than a
+ * literal path does: its prefix is located once by binary search, patterns
+ * nested under another collapse into the outermost before the paths they
+ * cover are enumerated, and every match after that is an integer comparison.
+ * What a pattern costs beyond a literal is that search, two binary searches
+ * of at most 16 comparisons each over a plan at the builder's plan-wide path
+ * ceiling,
+ * every comparison reading up to {@link maximumPathLength} code units.
+ * 128 keeps that term, 4,096 comparisons per list, below the sort that admits
+ * a per-declaration list of literal paths, while still letting one
+ * declaration name a subtree per package of a large monorepo. The count is
+ * read from the last character of each path as it is admitted, so a pattern
+ * past the limit costs one character read.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumGlobs = 128;
+/**
+ * Copies one declaration's paths, refusing before the copy grows past
+ * `limit`. A real array is refused by its length before a member is read; any
+ * other iterable is copied one path at a time and refused as soon as it
+ * exceeds the limit, so a caller-assembled declaration cannot dodge the bound
+ * by hiding its size from `length`. Each path is then refused by its length
+ * before any character is read, and by the count of patterns the list has
+ * carried so far, so an over-long path or a pattern past the limit costs one
+ * property read.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const copyPaths: (paths: ReadonlyArray<string>, limit: number, refuse: () => Error) => Array<string>;
+/**
+ * Snapshots a declaration into graph-owned data, copying at most `limit`
+ * paths in total across its reads and writes.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const boundedEffects: (declaration: Effects.Declaration, limit: number, refuse: () => Error) => Effects.Declaration;
+//# sourceMappingURL=effects.d.ts.map

package/dist/esm/internal/effects.d.ts.map

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