@canonical/pragma-cli 0.36.0 → 0.38.0

package/dist/src/capabilities/graph/queryText.js

@@ -0,0 +1,206 @@
+/**
+ * Making the graph's OWN names typable in `graph query`, and making the
+ * parser's complaint about the user's text.
+ *
+ * Two defects with one cause: the query a caller writes is not the query the
+ * parser reads. `rt.query.sparql` prepends one `PREFIX` line per registered
+ * namespace, so a caller's line 1 is the parser's line 16 — and the names the
+ * rest of this CLI hands out (`ds:global.component.button` from `graph
+ * inspect`, `dt:s4/web/--color-text` from `variable list`) are not spellable as
+ * SPARQL `PN_LOCAL` at all. Pasting a name pragma itself printed produced a
+ * Unicode-range dump pointing at a line the caller could not see.
+ *
+ * So this module owns both halves of the seam:
+ *
+ * - {@link expandPrefixedNames} rewrites a prefixed name whose local part the
+ *   grammar cannot carry into the `<absolute IRI>` it stands for — the same
+ *   expansion `graph inspect` has always done for its one argument, applied to
+ *   every token of a query. It is a pure text transform: same namespaces, same
+ *   meaning, so a query that already parsed answers exactly as before.
+ * - {@link trimQueryError} reports the position in the CALLER's text and cuts
+ *   the parser's expected-token dump to one line.
+ */
+import { isEmbeddableIri } from "../../kernel/packs/iri.js";
+/**
+ * The query's own `PREFIX` declarations. Captured (rather than merely detected)
+ * because a caller who declares a prefix wins over the prepended one, so an
+ * expansion has to use the namespace the parser would have used.
+ */
+const PREFIX_DECLARATION = /\bPREFIX\s+([A-Za-z][\w.-]*)?\s*:\s*<([^<>\s]*)>/gi;
+/**
+ * One pass over the query, in precedence order: comment, long literal, short
+ * literal, IRI, prefixed-name candidate, any other character.
+ *
+ * The first four alternatives exist to be SKIPPED — a `ds:x/y` inside a string
+ * literal is data the caller wrote, and inside `<…>` it is already an IRI.
+ * Everything the scanner does not recognise passes through one character at a
+ * time, which is what keeps an unparsable query byte-identical apart from the
+ * names this module set out to expand.
+ */
+const SCANNER = new RegExp([
+    "#[^\\n]*", // comment to end of line
+    '"""[\\s\\S]*?"""', // long literals
+    "'''[\\s\\S]*?'''",
+    '"(?:[^"\\\\\\n]|\\\\.)*"', // short literals
+    "'(?:[^'\\\\\\n]|\\\\.)*'",
+    '<[^<>"{}|^`\\\\\\s]*>', // an absolute IRI, already written out
+    // A prefixed-name candidate: a name, a colon, and the longest run of
+    // characters that could belong to a local part. `/` is included because
+    // the token IRIs contain it (`dt:s4/web/--color-text`); a property path
+    // is told apart from a local part in `splitPropertyPath`.
+    "[A-Za-z_\\u00C0-\\uFFFF][\\w.\\-\\u00C0-\\uFFFF]*:[^\\s<>\"'`{}()\\[\\],;|^\\\\*+?!=&#@$]*",
+    "[\\s\\S]", // anything else, one character at a time
+].join("|"), "g");
+/** A local part every SPARQL parser carries as written — left alone. */
+const PLAIN_LOCAL = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
+/**
+ * Expand every prefixed name whose local part the SPARQL grammar cannot carry.
+ *
+ * Conservative in the direction that matters: a name is rewritten only when its
+ * prefix is one the query will be parsed with, its local part is not a plain
+ * name (letters, digits, `_`, `-`), and the expansion is a safe `<IRI>` token.
+ * A name inside a string literal, a comment or an existing IRI is never
+ * touched, and neither is a property path's operator (`ds:a/ds:b` stays two
+ * steps, `dt:s4/web/--x` stays one name).
+ *
+ * @param sparql - The query as the caller wrote it.
+ * @param prefixes - The namespaces the query will be parsed with.
+ * @returns The query to execute, and whether anything moved.
+ */
+export function expandPrefixedNames(sparql, prefixes) {
+    const namespaces = { ...prefixes, ...declaredPrefixes(sparql) };
+    let rewritten = false;
+    const text = sparql.replace(SCANNER, (token) => {
+        const expanded = expandToken(token, namespaces);
+        if (expanded === undefined)
+            return token;
+        rewritten = true;
+        return expanded;
+    });
+    return { text, rewritten };
+}
+/** The prefixes the query declares for itself, which outrank the prepended ones. */
+function declaredPrefixes(sparql) {
+    const declared = {};
+    for (const match of sparql.matchAll(PREFIX_DECLARATION)) {
+        declared[match[1] ?? ""] = match[2] ?? "";
+    }
+    return declared;
+}
+/**
+ * One matched token, expanded — or `undefined` when it must be left as it is.
+ *
+ * The token may be a whole property path (`ds:a/ds:b`), because `/` is both the
+ * path operator and a character in this graph's local names. The two are told
+ * apart by what follows the slash: a segment that itself opens a KNOWN prefixed
+ * name is the next step of a path, anything else (`s4/web/--color-text`) is
+ * more of the same name. Each step is then expanded on its own, so a path may
+ * be half rewritten and stay a path.
+ *
+ * @param token - The matched token (it may not be a prefixed name at all).
+ * @param namespaces - Prefix → namespace, the caller's declarations winning.
+ * @returns The rewritten token, or undefined to keep the original.
+ */
+function expandToken(token, namespaces) {
+    // Every alternative but the candidate one is skipped here: a comment, a
+    // literal and an IRI all fail one of these guards.
+    if (token.indexOf(":") <= 0 ||
+        token.startsWith("<") ||
+        token.startsWith("#")) {
+        return undefined;
+    }
+    let rewritten = false;
+    const steps = pathSteps(token, namespaces).map((step) => {
+        const expanded = expandName(step, namespaces);
+        if (expanded === undefined)
+            return step;
+        rewritten = true;
+        return expanded;
+    });
+    return rewritten ? steps.join("/") : undefined;
+}
+/** Split a token into the property-path steps it is made of (usually one). */
+function pathSteps(token, namespaces) {
+    const segments = token.split("/");
+    const steps = [];
+    let step = segments[0];
+    for (const segment of segments.slice(1)) {
+        const colon = segment.indexOf(":");
+        if (colon > 0 && namespaces[segment.slice(0, colon)] !== undefined) {
+            steps.push(step);
+            step = segment;
+        }
+        else {
+            step = `${step}/${segment}`;
+        }
+    }
+    steps.push(step);
+    return steps;
+}
+/**
+ * One prefixed name, as the `<IRI>` it stands for — or `undefined` to keep it.
+ *
+ * @param name - One path step: `prefix:local`, plus any trailing punctuation.
+ * @param namespaces - Prefix → namespace, the caller's declarations winning.
+ * @returns The rewritten name, or undefined to keep the original.
+ */
+function expandName(name, namespaces) {
+    const colon = name.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const namespace = namespaces[name.slice(0, colon)];
+    if (namespace === undefined)
+        return undefined;
+    // A local part may not END in a dot, so a trailing one is the statement
+    // terminator the caller typed, not part of the name.
+    const local = name.slice(colon + 1).replace(/\.+$/, "");
+    const tail = name.slice(colon + 1 + local.length);
+    if (local === "" || PLAIN_LOCAL.test(local))
+        return undefined;
+    const iri = `${namespace}${local}`;
+    return isEmbeddableIri(iri) ? `<${iri}>${tail}` : undefined;
+}
+/** How much of the parser's expected-token dump a reader is served by. */
+const MAX_PARSER_DETAIL = 140;
+/** `error at <line>:<column>: <what the parser expected>`. */
+const PARSER_POSITION = /^error at (\d+):(\d+):\s*([\s\S]*)$/;
+/**
+ * Restate a parser failure in terms of the text the CALLER wrote.
+ *
+ * Two edits, both about the same lie: the position is the parser's, and the
+ * parser read a query with N prepended `PREFIX` lines the caller never saw
+ * ("16:41" for an error on line 1). And the expectation is a full dump of every
+ * admissible Unicode range — five lines of `'\\u{00C0}'..='\\u{00D6}'` that tell
+ * a reader nothing they can act on. The line number is corrected, the dump is
+ * collapsed to one line and cut.
+ *
+ * The COLUMN is dropped when names were expanded: an expansion lengthens the
+ * line it sits on, so the parser's column is a position in text the caller
+ * never wrote. The line is safe either way — an expansion never adds a newline.
+ *
+ * @param detail - The parser's own message.
+ * @param prependedLines - How many `PREFIX` lines were added above the query.
+ * @param rewritten - Whether names were expanded (columns therefore moved).
+ * @returns A one-line message positioned in the caller's own text.
+ */
+export function trimQueryError(detail, prependedLines, rewritten) {
+    const collapsed = detail.replace(/\s+/g, " ").trim();
+    const match = PARSER_POSITION.exec(collapsed);
+    if (!match)
+        return cut(collapsed);
+    const line = Number(match[1]) - prependedLines;
+    const expected = cut(match[3] ?? "");
+    if (line < 1)
+        return `error at line ${match[1]}, column ${match[2]}: ${expected}`;
+    const at = rewritten
+        ? `error at line ${line}`
+        : `error at line ${line}, column ${match[2]}`;
+    return `${at}: ${expected}`;
+}
+/** One line, at most {@link MAX_PARSER_DETAIL} characters of it. */
+function cut(text) {
+    return text.length <= MAX_PARSER_DETAIL
+        ? text
+        : `${text.slice(0, MAX_PARSER_DETAIL - 1).trimEnd()}…`;
+}
+//# sourceMappingURL=queryText.js.map

package/dist/src/capabilities/graph/queryText.js.map

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

package/dist/src/capabilities/graph/relationIndex.js

@@ -0,0 +1,302 @@
+/**
+ * The relation graph: which edges `graph connect` may walk, and the rosters it
+ * may not.
+ *
+ * ## What a relation is
+ *
+ * The kernel's entity reader already draws this distinction, and defends it in
+ * its own source (`readEntity.ts:37-50`): a RELATION "fans in narrowly and
+ * every subject is part of the answer", a ROSTER "fans in without bound because
+ * it grows with the data rather than the model" and "is already answered by
+ * `pragma/instanceCount` and by the noun's list verb". Then the sentence that
+ * makes it reusable here: "The two are told apart by FAN-IN, not by predicate
+ * name, so the kernel names no vocabulary."
+ *
+ * This module applies that same rule to TRAVERSAL. An edge `(s, p, o)` is
+ * walkable only if neither of its groups is a roster:
+ *
+ * - at most {@link ROSTER_THRESHOLD} subjects share its `(p, o)` pair, and
+ * - at most that many objects share its `(s, p)` pair.
+ *
+ * The threshold is IMPORTED, never restated — one constant with two consumers,
+ * so the traversal cannot drift from the doctrine it claims to obey.
+ *
+ * ## Why not a list of predicates
+ *
+ * Because the rule is per edge, per node and per direction, and a list cannot
+ * be. On the pack this CLI ships, twelve predicates carry both kinds of edge:
+ * `ds:tier` fans in 218-deep for the global tier and 1-to-a-handful for a small
+ * one, so the same predicate is a roster at one node and a real relation at
+ * another. A list would also be an editorial judgement about five vocabularies
+ * frozen into this file, stale the day a pack ships a predicate nobody listed.
+ * Nothing in this module names a predicate, and nothing may start to: the rule
+ * has to hold for a graph whose rosters hang off terms this code never saw.
+ *
+ * Nor can the distinction be read off the ontology. It is not asserted there:
+ * 72 predicates are declared `owl:ObjectProperty` and every one of the eleven
+ * classifiers is among them. The fan-in rule is a measurement standing in for a
+ * statement the graph does not make — which is exactly why it is computed here,
+ * fresh, from whatever is loaded, rather than written down anywhere.
+ *
+ * ## What the scan covers, and what it costs
+ *
+ * ONE scan of every triple with a non-literal object. Both group tables are
+ * counted over that same edge set, because a literal object is not an edge and
+ * cannot be walked — counting attributes into a fan-in would refuse edges on
+ * the strength of triples no traversal could ever use. The counts must be taken
+ * over the whole edge set before any edge is admitted, so the two tests cannot
+ * be applied in sequence: dropping a hub edge first would shrink the group its
+ * sibling is measured against and quietly admit an edge the rule refuses.
+ *
+ * The index is built ONCE per store session and memoised on it, and nothing
+ * here is written into the pack (`C.05` forbids a pre-joined view artifact, and
+ * prescribes exactly this: a thin loader that joins at runtime, because "the
+ * join is milliseconds at this scale — code, not data"). It is reached only
+ * through the connect verb's dynamically-imported run body, behind
+ * `needsStore`, so a process that never asks a connect question never loads
+ * this module, let alone runs the scan.
+ */
+import { compactUri } from "../../kernel/render/index.js";
+import { isInformativeName, nameIndex, ROSTER_THRESHOLD, } from "../../kernel/runtime/readEntity.js";
+/** Every triple whose object is a node rather than an attribute — one scan. */
+const EDGE_SCAN = "SELECT ?s ?p ?o WHERE { ?s ?p ?o . FILTER(!isLiteral(?o)) }";
+/**
+ * Field separator for composite map keys.
+ *
+ * A NUL, written as an ESCAPE so this file stays text: a literal NUL byte in
+ * the source makes git classify the module as binary, and a reviewer then gets
+ * no diff at all. It is the one character that cannot appear in an IRI or in a
+ * blank-node label, so a composite key is unambiguous.
+ */
+const SEP = "\u0000";
+/**
+ * The memo. Keyed on the session OBJECT, so it lives exactly as long as the
+ * session does: the lazy store hands out one immutable session per boot and
+ * `invalidate()` replaces it, which means a rebuilt store gets a rebuilt index
+ * with no invalidation hook of its own to forget to call. A WeakMap rather than
+ * a field on the session, because the index is this capability's concern and
+ * the kernel should not carry a structure only one verb reads.
+ */
+const memo = new WeakMap();
+/**
+ * The relation index for a session, built on first use and reused after.
+ *
+ * @param ctx - The booted session and its query facade.
+ * @returns The session's relation index.
+ * @note Impure — scans the store on the first call for a given session.
+ */
+export function relationIndex(ctx) {
+    const cached = memo.get(ctx.session);
+    if (cached)
+        return cached;
+    // Memoise the PROMISE, not the result, so two concurrent questions on one
+    // session share a single scan instead of racing two.
+    const building = buildRelationIndex(ctx).catch((error) => {
+        memo.delete(ctx.session);
+        throw error;
+    });
+    memo.set(ctx.session, building);
+    return building;
+}
+/** Read every edge out of the store, deduplicated. */
+async function scanEdges(ctx) {
+    const result = await ctx.sparql(EDGE_SCAN);
+    if (result.type !== "select")
+        return [];
+    const edges = [];
+    // Deduplicate by triple: ke queries with `use_default_graph_as_union` and
+    // oxigraph does not deduplicate across that union, so one triple asserted in
+    // two named graphs arrives twice. Left in, it would inflate every fan-in
+    // count it touches AND return the same path twice.
+    const seen = new Set();
+    for (const binding of result.termBindings) {
+        const s = binding.s;
+        const p = binding.p;
+        const o = binding.o;
+        if (!s || !p || !o)
+            continue;
+        const key = `${s.value}${SEP}${p.value}${SEP}${o.value}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push({
+            s: s.value,
+            p: p.value,
+            o: o.value,
+            sBlank: s.termType === "BlankNode",
+            oBlank: o.termType === "BlankNode",
+        });
+    }
+    return edges;
+}
+/**
+ * Build the relation index: one scan, two group tables, then the rule.
+ *
+ * @param ctx - The booted session and its query facade.
+ * @returns The relation index, with the cost of producing it recorded.
+ * @note Impure — queries the store.
+ */
+async function buildRelationIndex(ctx) {
+    const scanStart = performance.now();
+    const edges = await scanEdges(ctx);
+    const scanMs = performance.now() - scanStart;
+    const buildStart = performance.now();
+    // Both tables over the SAME edge set, before anything is admitted.
+    const bySubjectSide = new Map();
+    const byObjectSide = new Map();
+    for (const edge of edges) {
+        const inbound = `${edge.p}${SEP}${edge.o}`;
+        const outbound = `${edge.s}${SEP}${edge.p}`;
+        bySubjectSide.set(inbound, (bySubjectSide.get(inbound) ?? 0) + 1);
+        byObjectSide.set(outbound, (byObjectSide.get(outbound) ?? 0) + 1);
+    }
+    const adjacency = new Map();
+    const rosters = new Map();
+    const groups = new Map();
+    const blanks = new Set();
+    let relationEdges = 0;
+    const link = (from, edge) => {
+        const list = adjacency.get(from);
+        if (list)
+            list.push(edge);
+        else
+            adjacency.set(from, [edge]);
+    };
+    const enrol = (node, key, group) => {
+        if (!groups.has(key))
+            groups.set(key, group);
+        const list = rosters.get(node);
+        if (list) {
+            if (!list.includes(key))
+                list.push(key);
+        }
+        else
+            rosters.set(node, [key]);
+    };
+    for (const edge of edges) {
+        if (edge.sBlank)
+            blanks.add(edge.s);
+        if (edge.oBlank)
+            blanks.add(edge.o);
+        const inboundKey = `${edge.p}${SEP}${edge.o}`;
+        const outboundKey = `${edge.s}${SEP}${edge.p}`;
+        const subjectsSharing = bySubjectSide.get(inboundKey) ?? 0;
+        const objectsSharing = byObjectSide.get(outboundKey) ?? 0;
+        const inboundRoster = subjectsSharing > ROSTER_THRESHOLD;
+        const outboundRoster = objectsSharing > ROSTER_THRESHOLD;
+        if (!inboundRoster && !outboundRoster) {
+            relationEdges++;
+            link(edge.s, { to: edge.o, predicate: edge.p, forward: true });
+            link(edge.o, { to: edge.s, predicate: edge.p, forward: false });
+            continue;
+        }
+        // A refused edge still says something true: it records the node's
+        // MEMBERSHIP of the group that refused it, which is the whole content of a
+        // negative answer about two things that share only a classification.
+        if (inboundRoster) {
+            enrol(edge.s, `subjects${SEP}${inboundKey}`, {
+                side: "subjects",
+                predicate: edge.p,
+                node: edge.o,
+                members: subjectsSharing,
+            });
+        }
+        if (outboundRoster) {
+            enrol(edge.o, `objects${SEP}${outboundKey}`, {
+                side: "objects",
+                predicate: edge.p,
+                node: edge.s,
+                members: objectsSharing,
+            });
+        }
+    }
+    const names = nameIndex(ctx.session.index);
+    const prefixes = ctx.session.prefixes;
+    const term = (value, blank) => {
+        if (blank ?? blanks.has(value)) {
+            return { value, addressable: false };
+        }
+        const prefixed = compactUri(value, prefixes);
+        const name = names.get(value);
+        return {
+            value,
+            // `compactUri` returns its input when no namespace matches, so an
+            // unmatched IRI carries no `prefixed` echoing `value`.
+            ...(prefixed === value ? {} : { prefixed }),
+            ...(name && isInformativeName(name, prefixed) ? { title: name } : {}),
+        };
+    };
+    return {
+        adjacency,
+        rosters,
+        groups,
+        scannedEdges: edges.length,
+        relationEdges,
+        relationNodes: adjacency.size,
+        scanMs,
+        buildMs: performance.now() - buildStart,
+        term,
+    };
+}
+/**
+ * The roster groups two nodes both belong to, ordered deterministically.
+ *
+ * Scoped to one hop in each direction, which is what makes it cost nothing —
+ * and what it cannot see: two blocks whose shared library is attributed to
+ * their implementation objects rather than to themselves share that roster one
+ * step removed, and this will not report it.
+ *
+ * @param index - The session's relation index.
+ * @param a - One node's IRI or blank label.
+ * @param b - The other node's IRI or blank label.
+ * @returns The shared roster groups, largest first then by predicate.
+ */
+export function sharedRosters(index, a, b) {
+    const mine = index.rosters.get(a) ?? [];
+    const theirs = new Set(index.rosters.get(b) ?? []);
+    const shared = [];
+    for (const key of mine) {
+        if (!theirs.has(key))
+            continue;
+        const group = index.groups.get(key);
+        if (!group)
+            continue;
+        shared.push({
+            side: group.side,
+            predicate: index.term(group.predicate),
+            node: index.term(group.node),
+            members: group.members,
+        });
+    }
+    return sortRosters(shared);
+}
+/**
+ * The roster groups one node belongs to — what classifies an entity that
+ * carries no relation at all.
+ *
+ * @param index - The session's relation index.
+ * @param node - The node's IRI or blank label.
+ * @returns The node's roster groups, largest first then by predicate.
+ */
+export function rosterMemberships(index, node) {
+    const groups = [];
+    for (const key of index.rosters.get(node) ?? []) {
+        const group = index.groups.get(key);
+        if (!group)
+            continue;
+        groups.push({
+            side: group.side,
+            predicate: index.term(group.predicate),
+            node: index.term(group.node),
+            members: group.members,
+        });
+    }
+    return sortRosters(groups);
+}
+/** Order rosters by size then by name, so two runs agree. */
+function sortRosters(groups) {
+    return groups.sort((x, y) => y.members - x.members ||
+        x.predicate.value.localeCompare(y.predicate.value) ||
+        x.node.value.localeCompare(y.node.value));
+}
+//# sourceMappingURL=relationIndex.js.map

package/dist/src/capabilities/graph/relationIndex.js.map

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