@stll/template-conditions 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -258,9 +258,53 @@ type InvalidMarker = {
  * complement of {@link scanMarkers}: a span is in one list or the other.
  */
 declare const scanInvalidMarkers: (text: string) => InvalidMarker[];
+/**
+ * Why a `{{...}}` span misses the grammar in a way that names the authoring
+ * mistake rather than merely failing to classify. Consumers derive their own
+ * warning codes from {@link MARKER_DEFECT_KINDS} so the two never drift.
+ */
+type MarkerDefectKind = "unknown_directive" | "bracket_index";
+declare const MARKER_DEFECT_KINDS: readonly ["unknown_directive", "bracket_index"];
+/**
+ * Name the authoring mistake behind one marker's inner text, or `null` when the
+ * text is a recognized directive ({@link classifyMarker} accepts it) or an
+ * unrecognizable span with no specific diagnosis (`{{my field}}`). The
+ * recognized-directive check is what makes `DIRECTIVE_KINDS` the single
+ * authority on which `{{#...}}` tokens exist: adding a directive to the grammar
+ * stops it being reported here, with no list to update.
+ */
+declare const classifyMarkerDefect: (innerRaw: string) => MarkerDefectKind | null;
 /** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
 declare const assertNever: (value: never) => never;
 //#endregion
+//#region src/row-blocks.d.ts
+/** One end of a row block, addressed within the row that was scanned. */
+type RowBlockMarker = {
+  /** Index into the row's cells. */
+  cellIndex: number;
+  /** Index into that cell's paragraphs. */
+  paragraphIndex: number;
+  marker: ScannedMarker;
+};
+type RowBlockPair = {
+  open: RowBlockMarker;
+  close: RowBlockMarker;
+};
+/**
+ * The one row block a table row declares in the lenient form, or `null`.
+ *
+ * `cells` is the row's cells in document order, each as its paragraph texts in
+ * document order.
+ *
+ * A row qualifies when exactly two block markers reach outside their own
+ * paragraph, they are a matching opener/closer pair, the closer sits in a LATER
+ * cell than the opener, the opener prefixes its cell and the closer suffixes
+ * its cell. Everything else — one half of a pair, two nested pairs, a stray
+ * `{{#else}}`, a pair wrapping the paragraphs of a single cell — is left to the
+ * engine's existing structure errors rather than guessed at.
+ */
+declare const detectRowBlockPair: (cells: readonly (readonly string[])[]) => RowBlockPair | null;
+//#endregion
 //#region src/index.d.ts
 type NamedCondition = {
   name: string;
@@ -294,4 +338,4 @@ declare const MAX_CONDITION_DEPTH = 50;
  */
 declare const evaluateCondition: (expression: string, data: Record<string, unknown>, namedConditions?: readonly NamedCondition[], _resolved?: ReadonlySet<string>, _depth?: number) => boolean;
 //#endregion
-export { BLOCK_DIRECTIVE_KINDS, type BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, type FieldDateFormat, type GroupNode, type InvalidMarker, MAX_CONDITION_DEPTH, type MarkerMeta, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, type Operand, type PartConfig, type PredicateNode, type PredicateOp, type ScannedMarker, assertNever, blockDirectiveLinePattern, classifyMarker, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };
+export { BLOCK_DIRECTIVE_KINDS, type BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, type FieldDateFormat, type GroupNode, type InvalidMarker, MARKER_DEFECT_KINDS, MAX_CONDITION_DEPTH, type MarkerDefectKind, type MarkerMeta, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, type Operand, type PartConfig, type PredicateNode, type PredicateOp, type RowBlockMarker, type RowBlockPair, type ScannedMarker, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };

package/dist/index.js

@@ -6,7 +6,14 @@ import { panic } from "better-result";
 * the condition engine (index.ts) and the arithmetic evaluator (compute.ts) can
 * import it without a dependency cycle.
 */
-/** Narrow `unknown` to a string-keyed record. */
+/**
+* Narrow `unknown` to something a path segment can be read from.
+*
+* Unlike the same-named predicates that screen JSON payload shapes, this one
+* accepts arrays on purpose: a dotted path segment may be an array index
+* (`parties.1.name`), and rejecting arrays would silently resolve those to
+* `undefined`.
+*/
 const isRecord = (v) => typeof v === "object" && v !== null;
 /** Resolve a dotted path like `company.name` against data. */
 const resolvePath = (path, data) => {
@@ -101,7 +108,7 @@ const callFunction = (name, args) => {
 			const factor = 10 ** Math.trunc(digits);
 			return Math.round(value * factor) / factor;
 		}
-		default: return name;
+		default: return panic(`Unhandled name: ${String(name)}`);
 	}
 };
 const evaluateNumericExpression = (expression, data) => {
@@ -542,6 +549,26 @@ const scanInvalidMarkers = (text) => {
 	}
 	return out;
 };
+const MARKER_DEFECT_KINDS = ["unknown_directive", "bracket_index"];
+/** A `{{#...}}` / `{{/...}}` shape: an author reaching for a block directive. */
+const DIRECTIVE_SHAPE_RE = /^[#/]/u;
+/** Bracket indexing (`items[0].name`), which no directive kind admits. */
+const BRACKET_INDEX_RE = /[[\]]/u;
+/**
+* Name the authoring mistake behind one marker's inner text, or `null` when the
+* text is a recognized directive ({@link classifyMarker} accepts it) or an
+* unrecognizable span with no specific diagnosis (`{{my field}}`). The
+* recognized-directive check is what makes `DIRECTIVE_KINDS` the single
+* authority on which `{{#...}}` tokens exist: adding a directive to the grammar
+* stops it being reported here, with no list to update.
+*/
+const classifyMarkerDefect = (innerRaw) => {
+	const inner = innerRaw.trim();
+	if (classifyMarker(inner) !== null) return null;
+	if (DIRECTIVE_SHAPE_RE.test(inner)) return "unknown_directive";
+	if (BRACKET_INDEX_RE.test(inner)) return "bracket_index";
+	return null;
+};
 /** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
 const assertNever = (value) => panic(`Unhandled template directive: ${JSON.stringify(value)}`);
 //#endregion
@@ -733,6 +760,116 @@ const serializeNode = (node, top) => {
 */
 const serializeCondition = (node) => serializeNode(node, true);
 //#endregion
+//#region src/row-blocks.ts
+/**
+* Row-form block markers: the lenient placement authoring agents actually
+* write for a "one row per item" table.
+*
+* The canonical placement gives a block marker its own paragraph. In a table
+* that costs an extra empty-looking paragraph in the first and last cell, so
+* an author instead types the opener in front of the first cell's text and the
+* closer behind the last cell's text:
+*
+*     | {{#each deliverables}}{{deliverables.item}} | {{deliverables.fee}}{{/each}} |
+*
+* Both placements mean the same thing — the `w:tr` is the unit — so this
+* module recognizes the row form purely from text, and the consumer rewrites
+* it into the canonical form before any engine runs.
+*
+* Text-only and structure-free on purpose: the fill/discovery pipeline feeds
+* it OOXML run text, the authoring eval feeds it the cells a model produced,
+* and neither can drift from the other's idea of what a row block is.
+*/
+const CLOSER_OF = {
+	each: "endeach",
+	if: "endif"
+};
+const isOpenKind = (kind) => kind === "each" || kind === "if";
+/**
+* Block markers in one paragraph that do not pair inside it. A pair that opens
+* and closes within the paragraph is an inline span (`the Buyer{{#if x}} and
+* spouse{{/if}}`), which the inline engine already owns; only what is left
+* over can reach across cells.
+*
+* A branch marker (`{{#elseif}}`, `{{#else}}`) counts as left over unless its
+* `{{#if}}` also closes in this paragraph. Only the opener and the closer of a
+* row block are hoisted, so a branch marker stranded between them would stay
+* buried in the cell text: a false condition would drop the whole row and the
+* branch that should have rendered with it, and a true one would leave the
+* marker behind as an inline orphan. Counting it here refuses the placement
+* instead.
+*
+* A paragraph that is nothing but a directive is the canonical form and
+* belongs to the block engine, so it contributes nothing here.
+*/
+const danglingBlockMarkers = (text) => {
+	if (blockDirectiveLinePattern().test(text)) return [];
+	const open = [];
+	const dangling = [];
+	for (const marker of scanMarkers(text)) {
+		const { kind } = marker.meta;
+		if (isOpenKind(kind)) {
+			open.push({
+				kind,
+				marker,
+				branches: []
+			});
+			continue;
+		}
+		if (kind === "endeach" || kind === "endif") {
+			const innermost = open.at(-1);
+			if (innermost && CLOSER_OF[innermost.kind] === kind) open.pop();
+			else dangling.push(marker);
+			continue;
+		}
+		if (kind === "elseif" || kind === "else") {
+			const innermost = open.at(-1);
+			if (innermost?.kind === "if") innermost.branches.push(marker);
+			else dangling.push(marker);
+		}
+	}
+	for (const { branches, marker } of open) dangling.push(marker, ...branches);
+	return dangling.toSorted((a, b) => a.start - b.start);
+};
+const firstContentParagraph = (paragraphs) => paragraphs.findIndex((text) => text.trim() !== "");
+const lastContentParagraph = (paragraphs) => paragraphs.findLastIndex((text) => text.trim() !== "");
+/** The marker stands in front of everything the cell says. */
+const prefixesCell = (paragraphs, { marker, paragraphIndex }) => paragraphIndex === firstContentParagraph(paragraphs) && (paragraphs[paragraphIndex] ?? "").slice(0, marker.start).trim() === "";
+/** The marker stands behind everything the cell says. */
+const suffixesCell = (paragraphs, { marker, paragraphIndex }) => paragraphIndex === lastContentParagraph(paragraphs) && (paragraphs[paragraphIndex] ?? "").slice(marker.end).trim() === "";
+/**
+* The one row block a table row declares in the lenient form, or `null`.
+*
+* `cells` is the row's cells in document order, each as its paragraph texts in
+* document order.
+*
+* A row qualifies when exactly two block markers reach outside their own
+* paragraph, they are a matching opener/closer pair, the closer sits in a LATER
+* cell than the opener, the opener prefixes its cell and the closer suffixes
+* its cell. Everything else — one half of a pair, two nested pairs, a stray
+* `{{#else}}`, a pair wrapping the paragraphs of a single cell — is left to the
+* engine's existing structure errors rather than guessed at.
+*/
+const detectRowBlockPair = (cells) => {
+	const located = [];
+	for (const [cellIndex, paragraphs] of cells.entries()) for (const [paragraphIndex, text] of paragraphs.entries()) for (const marker of danglingBlockMarkers(text)) located.push({
+		cellIndex,
+		paragraphIndex,
+		marker
+	});
+	if (located.length !== 2) return null;
+	const [open, close] = located;
+	if (!open || !close) return null;
+	const openKind = open.marker.meta.kind;
+	if (!isOpenKind(openKind) || close.marker.meta.kind !== CLOSER_OF[openKind]) return null;
+	if (open.cellIndex >= close.cellIndex) return null;
+	if (!prefixesCell(cells[open.cellIndex] ?? [], open) || !suffixesCell(cells[close.cellIndex] ?? [], close)) return null;
+	return {
+		open,
+		close
+	};
+};
+//#endregion
 //#region src/index.ts
 /**
 * Shared condition evaluation + marker grammar for DOCX templates. Small,
@@ -806,4 +943,4 @@ const evaluateCondition = (expression, data, namedConditions, _resolved = /* @__
 	return evaluateCondition$1(node, makeResolver(data, namedConditions, _resolved, _depth));
 };
 //#endregion
-export { BLOCK_DIRECTIVE_KINDS, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, MAX_CONDITION_DEPTH, NUMERIC_FUNCTION_NAMES, assertNever, blockDirectiveLinePattern, classifyMarker, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };
+export { BLOCK_DIRECTIVE_KINDS, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, MARKER_DEFECT_KINDS, MAX_CONDITION_DEPTH, NUMERIC_FUNCTION_NAMES, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/template-conditions",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A document-template marker and condition engine: {{...}} marker grammar, parse, compute, serialize, field values.",
   "keywords": [
     "condition",
@@ -45,17 +45,17 @@
     "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
     "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/template-conditions",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/template-conditions",
-    "format": "oxfmt .",
+    "format": "bun ../../scripts/run-oxfmt.ts .",
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@stll/conditions": "^0.3.0",
-    "better-result": "3.0.0"
+    "@stll/conditions": "^0.3.1",
+    "better-result": "3.0.1"
   },
   "devDependencies": {
     "@stll/property-testing": "0.0.0",
     "@stll/typescript-config": "0.0.0",
-    "bun-types": "1.4.0",
+    "bun-types": "1.4.2",
     "fast-check": "^4.9.0",
     "tsdown": "0.22.14"
   },