@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/kernel/packs/sparql/applyFilters.js

@@ -0,0 +1,167 @@
+/**
+ * Apply declared pack filters to resolved list rows.
+ *
+ * Filters are row predicates on projected SELECT variables — the author query is
+ * never modified, so user input cannot inject SPARQL and the query's ordering is
+ * preserved. With declared `values` the input is canonicalized against the set
+ * (NFC, case-insensitive) and rows are matched case-insensitively; without them
+ * the input is a free term matched the same way. A row lacking the variable never
+ * matches. Several filters combine conjunctively; several values for one
+ * filter (a repeated flag) combine as a union.
+ *
+ * A filter declaring `match: "set"` reads its cell as a space-separated SET and
+ * matches any member — the shape a query produces for a dimension a row belongs
+ * to several values of at once (a category and its ancestors, say). The
+ * comparison is otherwise identical, so exactly one code path decides what a
+ * match is.
+ *
+ * A value-free filter still REJECTS a value the data does not carry, with the
+ * admissible values as `validOptions` — the same courtesy a declared-`values`
+ * filter has always extended, without copying the vocabulary into the consumer.
+ * The vocabulary is read from the graph, because the graph IS the vocabulary; a
+ * story that hard-coded the slugs would go stale the first time the data grew a
+ * category. Before this, a typo'd `--category` returned
+ * `{"ok":true,"data":[],"meta":{}}` — indistinguishable, over MCP, from a
+ * genuinely empty category.
+ *
+ * WHICH part of the graph is the vocabulary matters, and it is NOT the rows.
+ * Rows are a population: a value can be perfectly real while no row carries it —
+ * `standard categories` lists a category with count 0, `ds:ConceptType` declares
+ * "Decision guide" before any concept uses it. Validating against rows called
+ * those `INVALID_INPUT`, when the documented answer is a calm empty list. So a
+ * filter DECLARES where its vocabulary lives ({@link PackFilter.vocabulary},
+ * resolved by the caller and handed in here), and the observed rows are the
+ * fallback for a filter that declares none — the only evidence there is, and
+ * knowingly narrower than the truth.
+ */
+import { PragmaError } from "../../error/index.js";
+/**
+ * @param rows - Rows produced by the pack's list query.
+ * @param filters - Declared filters (absent means no filtering).
+ * @param params - Story parameters as provided by the surface.
+ * @param vocabularies - Authoritative values per filter param, resolved from
+ *   each filter's declared `vocabulary` (see {@link FilterVocabularies}).
+ * @returns Rows matching every provided filter.
+ * @throws PragmaError INVALID_INPUT when a value is not in a filter's declared
+ *   set, or when a value-free filter receives a non-string value.
+ */
+export function applyPackFilters(rows, filters, params, vocabularies) {
+    let result = rows;
+    for (const filter of filters ?? []) {
+        const provided = params[filter.param];
+        if (provided === undefined)
+            continue;
+        // A repeated CLI flag accumulates into an array; MCP args stay scalar.
+        // Several values for ONE filter are a union (a row matches any of them);
+        // several filters still combine conjunctively.
+        const occurrences = Array.isArray(provided) ? provided : [provided];
+        if (occurrences.length === 0)
+            continue;
+        const values = filter.values;
+        const terms = occurrences.map((occurrence) => values === undefined
+            ? requireStringValue(occurrence, filter).toLowerCase()
+            : canonicalizeFilterValue(occurrence, filter, values).toLowerCase());
+        // The fallback vocabulary is read from the UNFILTERED rows: a value that
+        // exists but is excluded by a conjunction is a legitimately empty answer,
+        // not a bad argument.
+        if (values === undefined)
+            rejectUnknownValue(vocabularies?.get(filter.param) ?? observedValues(rows, filter), filter, occurrences, terms);
+        result = result.filter((row) => cellValues(row, filter).some((value) => terms.includes(value.toLowerCase())));
+    }
+    return result;
+}
+/**
+ * The values the rows themselves carry — the fallback vocabulary for a filter
+ * that declares no authoritative one, in the data's own DISPLAY spelling.
+ */
+function observedValues(rows, filter) {
+    const observed = new Map();
+    for (const row of rows) {
+        for (const value of cellValues(row, filter)) {
+            const key = value.toLowerCase();
+            if (!observed.has(key))
+                observed.set(key, value);
+        }
+    }
+    return [...observed.values()];
+}
+/**
+ * Reject a value-free filter value the vocabulary does not admit, naming the
+ * ones it does.
+ *
+ * Silent when the vocabulary is EMPTY: an unbuilt or genuinely-empty store is
+ * not the caller's mistake, and the list's own `emptyRecovery` is the right
+ * voice for it.
+ *
+ * A value the vocabulary admits is never rejected here even when no row carries
+ * it — a real slug with zero standards is a calm empty list, which is what the
+ * tool descriptions document and what `standard categories` reporting count 0
+ * promises.
+ *
+ * @throws PragmaError INVALID_INPUT when a term matches none of the admissible
+ *   values, carrying them as `validOptions`.
+ */
+function rejectUnknownValue(vocabulary, filter, occurrences, terms) {
+    const admissible = new Map();
+    for (const value of vocabulary) {
+        const key = value.normalize("NFC").toLowerCase();
+        if (!admissible.has(key))
+            admissible.set(key, value.normalize("NFC"));
+    }
+    if (admissible.size === 0)
+        return;
+    const index = terms.findIndex((term) => !admissible.has(term));
+    if (index === -1)
+        return;
+    const validOptions = [...admissible.values()].sort();
+    throw PragmaError.invalidInput(filter.param, String(occurrences[index]), {
+        validOptions,
+        recovery: {
+            message: `Values allowed for --${filter.param}: ${validOptions.join(", ")}.`,
+        },
+    });
+}
+/**
+ * The values a row offers for one filter, in their DISPLAY spelling (NFC).
+ *
+ * One value for an ordinary filter; every space-separated member for a `"set"`
+ * one. A row lacking the variable offers none, so it never matches. Kept in the
+ * data's own casing because these are also what an INVALID_INPUT lists back as
+ * `validOptions` — lowercasing here would hand the caller a value the graph does
+ * not spell that way. Comparison lowercases at the point of comparison instead.
+ */
+function cellValues(row, filter) {
+    const cell = row[filter.variable];
+    if (cell === undefined)
+        return [];
+    const normalized = cell.normalize("NFC");
+    if (filter.match !== "set") {
+        return normalized === "" ? [] : [normalized];
+    }
+    return normalized.split(/\s+/).filter((value) => value !== "");
+}
+/** @throws PragmaError INVALID_INPUT when a value-free filter value is not a string. */
+function requireStringValue(provided, filter) {
+    if (typeof provided !== "string") {
+        throw PragmaError.invalidInput(filter.param, String(provided), {
+            recovery: { message: `Provide a string value for --${filter.param}.` },
+        });
+    }
+    return provided.trim().normalize("NFC");
+}
+/** @throws PragmaError INVALID_INPUT when the value is not in the declared set. */
+function canonicalizeFilterValue(provided, filter, values) {
+    if (typeof provided === "string") {
+        const normalized = provided.trim().normalize("NFC");
+        const match = values.find((value) => value.normalize("NFC").toLowerCase() === normalized.toLowerCase());
+        if (match !== undefined)
+            return match.normalize("NFC");
+    }
+    throw PragmaError.invalidInput(filter.param, String(provided), {
+        validOptions: [...values],
+        recovery: {
+            message: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
+        },
+    });
+}
+//# sourceMappingURL=applyFilters.js.map

package/dist/src/kernel/packs/sparql/applyFilters.js.map

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

package/dist/src/kernel/packs/sparql/applySearch.js

@@ -0,0 +1,25 @@
+/**
+ * Apply a pack list's free-text search to resolved rows.
+ *
+ * Like filters, search runs AFTER the author query, so user input never touches
+ * the query text (injection-safe) and the author's ORDER BY is preserved. The
+ * term is NFC-normalized and matched case-insensitively; a row passes when ANY
+ * declared variable contains it as a substring. A non-string or empty term is a
+ * no-op.
+ */
+/**
+ * @param rows - Rows produced by the pack's list query (post-filter).
+ * @param search - The declared search (absent means no searching).
+ * @param params - Story parameters as provided by the surface.
+ * @returns Rows containing the term in at least one searched variable.
+ */
+export function applyPackSearch(rows, search, params) {
+    const provided = params.search;
+    if (search === undefined || typeof provided !== "string")
+        return rows;
+    const term = provided.trim().normalize("NFC").toLowerCase();
+    if (term === "")
+        return rows;
+    return rows.filter((row) => search.variables.some((variable) => row[variable]?.normalize("NFC").toLowerCase().includes(term)));
+}
+//# sourceMappingURL=applySearch.js.map

package/dist/src/kernel/packs/sparql/applySearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applySearch.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/applySearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAe,EACf,MAA8B,EAC9B,MAA+B;IAE/B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5D,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACzB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CACjC,GAAG,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAC7D,CACF,CAAC;AACJ,CAAC"}