@optique/core 1.0.0-dev.552 → 1.0.0-dev.555

package/dist/context.cjs

@@ -4,8 +4,9 @@
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.

package/dist/context.d.cts

@@ -154,8 +154,9 @@ interface SourceContext<TRequiredOptions = void> {
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.

package/dist/context.d.ts

@@ -154,8 +154,9 @@ interface SourceContext<TRequiredOptions = void> {
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.

package/dist/context.js

@@ -3,8 +3,9 @@
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.

package/dist/facade.cjs

@@ -870,13 +870,8 @@ async function collectPhase1Annotations(contexts, options) {
 	let hasDynamic = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
@@ -914,7 +909,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+		hasDynamic ||= needsTwoPhaseContext(context, result);
 		annotationsList.push(result);
 	}
 	return {
@@ -923,6 +918,18 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.

package/dist/facade.js

@@ -870,13 +870,8 @@ async function collectPhase1Annotations(contexts, options) {
 	let hasDynamic = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
@@ -914,7 +909,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+		hasDynamic ||= needsTwoPhaseContext(context, result);
 		annotationsList.push(result);
 	}
 	return {
@@ -923,6 +918,18 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.552+30c7ea22",
+  "version": "1.0.0-dev.555+975ed8c5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",