@milehimikey/em 1.9.1 → 1.10.0

package/dist/query/format.d.ts

@@ -0,0 +1,8 @@
+import { ConsumerEntry, ProducerEntry, ClosureEntry, SliceQueryEntry, InvariantQueryEntry, FieldQueryEntry, PathQueryEntry } from "./verbs.js";
+export declare function formatConsumers(results: ConsumerEntry[]): string;
+export declare function formatProducers(results: ProducerEntry[]): string;
+export declare function formatClosure(results: ClosureEntry[]): string;
+export declare function formatSlices(results: SliceQueryEntry[]): string;
+export declare function formatInvariant(results: InvariantQueryEntry[]): string;
+export declare function formatField(results: FieldQueryEntry[]): string;
+export declare function formatPath(results: PathQueryEntry[]): string;

package/dist/query/format.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT
+// Human-text formatting for `em query`'s eight verbs (the default output — `--json` bypasses
+// this entirely and prints `emit/queryJson.ts`'s document instead). An empty `results` array
+// always prints a bare `(none)` line and still exits 0 — a query with a legitimately empty
+// answer (an event nobody consumes, two elements with no path between them) is not an error.
+function tagList(label, items) {
+    return items.length > 0 ? ` ${label}=[${items.join(", ")}]` : "";
+}
+export function formatConsumers(results) {
+    if (results.length === 0)
+        return "(none)";
+    return results.map((r) => `${r.ref}  (${r.kind}) in slice "${r.sliceName}" [${r.sliceKey}] — via ${r.via}`).join("\n");
+}
+export function formatProducers(results) {
+    if (results.length === 0)
+        return "(none)";
+    const lines = [];
+    for (const r of results) {
+        lines.push(`${r.ref}  (${r.kind}) in slice "${r.sliceName}" [${r.sliceKey}] — via ${r.via}`);
+        for (const t of r.uiTriggers)
+            lines.push(`  triggered by ui: ${t.ref}  "${t.name}"`);
+    }
+    return lines.join("\n");
+}
+export function formatClosure(results) {
+    if (results.length === 0)
+        return "(none)";
+    return results.map((r) => `depth ${r.depth}  ${r.ref}  (${r.kind}) via ${r.via} — slice "${r.sliceName}" [${r.sliceKey}]`).join("\n");
+}
+export function formatSlices(results) {
+    if (results.length === 0)
+        return "(none)";
+    return results
+        .map((r) => `${r.ref}  "${r.name}"  pattern=${r.pattern} status=${r.status ?? "no-doc"}` +
+        tagList("personas", r.personas) +
+        tagList("contexts", r.contexts) +
+        tagList("tags", r.tags))
+        .join("\n");
+}
+export function formatInvariant(results) {
+    if (results.length === 0)
+        return "(none)";
+    const r = results[0];
+    const lines = [
+        `${r.id}  declared in slice "${r.sliceName}" [${r.sliceRef}]`,
+        `  doc: ${r.docPath ?? "(no doc)"}  status: ${r.status ?? "(none)"}`,
+    ];
+    if (r.citations !== null) {
+        if (r.citations.length === 0)
+            lines.push("  citations: (none)");
+        else {
+            lines.push("  citations:");
+            for (const c of r.citations)
+                lines.push(`    ${c.file}:${c.line}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatField(results) {
+    if (results.length === 0)
+        return "(none)";
+    const r = results[0];
+    const renamed = tagList("renamedFrom", r.renamedFrom ?? []);
+    const elementRenamed = tagList("elementRenamedFrom", r.elementRenamedFrom ?? []);
+    return `${r.elementRef}.${r.name}: ${r.type ?? "(untyped)"} tag=${r.tag} assigned=${r.assigned}${renamed}${elementRenamed}`;
+}
+export function formatPath(results) {
+    if (results.length === 0)
+        return "(none)";
+    const r = results[0];
+    if (r.length === 0)
+        return r.refs[0];
+    const parts = [r.refs[0]];
+    for (let i = 0; i < r.edgeKinds.length; i++) {
+        parts.push(`--[${r.edgeKinds[i]}]-->`);
+        parts.push(r.refs[i + 1]);
+    }
+    return parts.join(" ");
+}
+//# sourceMappingURL=format.js.map

package/dist/query/format.js.map

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

package/dist/query/pipeline.d.ts

@@ -0,0 +1,17 @@
+import { NormalizedModel } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { Diagnostic } from "../model/validate.js";
+import { ModelIndex } from "../model/queryIndex.js";
+export interface QueryCompileResult {
+    model: NormalizedModel;
+    refs: RefsResult;
+    diagnostics: Diagnostic[];
+    index: ModelIndex;
+}
+/** Compile one `.em` source for query use: parse + normalize + refs + validate (grid-free, see
+ *  header) + the ModelIndex every verb queries. `baseDir` is the `.em` file's own directory —
+ *  same doc-resolution convention every other command uses (passed straight through to
+ *  `buildModelIndex`'s slice-doc join). Throws `ParseError` on a syntax error, same as
+ *  `pipeline.ts`'s `compile()` — callers (cli.ts's compileFile-style wrapper, the MCP tool)
+ *  catch it the same way. */
+export declare function compileForQuery(source: string, baseDir: string): QueryCompileResult;

package/dist/query/pipeline.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+// `em query`'s sub-pipeline (MIL-168): `parse -> normalize -> computeRefs -> buildIndex`,
+// skipping `pipeline.ts`'s own `layout()` (the dense per-cell Grid allocation — rows x slice
+// columns) and `emitDot()` entirely. Neither is query work: nothing here renders, and
+// `layout()`'s only diagnostic contribution `validate()` reads is `grid.collisions` (row/col
+// placement clashes — a rendering-only concern, `src/model/validate.ts` greps clean for any
+// other `grid.` use). `EMPTY_GRID` below hands `validate()` a real, empty `Grid` shape instead
+// of computing one, so query pays zero layout cost while every OTHER validate.ts diagnostic
+// (unresolved refs, dangling views, tag/field completeness, ...) still runs at full strength.
+//
+// validate() itself is deliberately still called, one explicit deviation from this ticket's
+// design note (which named it alongside layout/DOT as work to skip): the CLI/MCP contract
+// this ticket also specifies is "refuse (exit 1) if a model has compile errors," the same
+// `hasErrors(diagnostics)` gate `em export`/`em status`/every other JSON surface uses — dropping
+// validate() would mean `em query` silently traverses a model with unresolved references
+// instead of refusing, a behavior change from every sibling command with no upside once
+// layout's own cost is already zero. See this ticket's report for the full tradeoff.
+import { parse } from "../parser/parser.js";
+import { normalize } from "../model/model.js";
+import { computeRefs } from "../model/refs.js";
+import { validate } from "../model/validate.js";
+import { buildModelIndex } from "../model/queryIndex.js";
+const EMPTY_GRID = { rows: [], cols: 0, sliceNames: [], cells: [], rowIndexByKey: new Map(), collisions: [] };
+/** Compile one `.em` source for query use: parse + normalize + refs + validate (grid-free, see
+ *  header) + the ModelIndex every verb queries. `baseDir` is the `.em` file's own directory —
+ *  same doc-resolution convention every other command uses (passed straight through to
+ *  `buildModelIndex`'s slice-doc join). Throws `ParseError` on a syntax error, same as
+ *  `pipeline.ts`'s `compile()` — callers (cli.ts's compileFile-style wrapper, the MCP tool)
+ *  catch it the same way. */
+export function compileForQuery(source, baseDir) {
+    const ast = parse(source);
+    const model = normalize(ast);
+    const refs = computeRefs(model);
+    const diagnostics = [...validate(model, EMPTY_GRID, refs), ...refs.diagnostics];
+    const index = buildModelIndex(model, refs, baseDir);
+    return { model, refs, diagnostics, index };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/query/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/query/pipeline.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,0FAA0F;AAC1F,6FAA6F;AAC7F,sFAAsF;AACtF,6FAA6F;AAC7F,4FAA4F;AAC5F,+FAA+F;AAC/F,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,4FAA4F;AAC5F,0FAA0F;AAC1F,0FAA0F;AAC1F,iGAAiG;AACjG,yFAAyF;AACzF,wFAAwF;AACxF,qFAAqF;AAErF,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAc,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAc,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAc,MAAM,wBAAwB,CAAC;AAGrE,MAAM,UAAU,GAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,GAAG,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AASpH;;;;;6BAK6B;AAC7B,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,OAAe;IAC7D,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,WAAW,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC"}

package/dist/query/system.d.ts

@@ -0,0 +1,60 @@
+import { NormalizedModel } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { ModelIndex } from "../model/queryIndex.js";
+import type { Diagnostic } from "../model/validate.js";
+export interface QueryModelEntry {
+    file: string;
+    modelKey: string;
+    model: NormalizedModel;
+    refs: RefsResult;
+    index: ModelIndex;
+}
+export interface QuerySystem {
+    entries: QueryModelEntry[];
+    /** True once more than one file was given — the CLI/MCP layer's signal to qualify every ref
+     *  in its output (`qualifyRef` below), and the signal `resolveElement`'s ambiguity rule uses
+     *  ("unqualified + multi-model + ambiguous" -> list qualified candidates, per this ticket's
+     *  design note). */
+    multiModel: boolean;
+    /** `duplicate-model-key` warnings from keying the entries (MIL-193, `computeModelKeys()`):
+     *  two input models deriving the same key, the later one suffixed `~2`/`~3`, … in file-list
+     *  order. Empty for a single-model system. The CLI prints these to stderr like any other
+     *  compile warning; the JSON document is unaffected (MCP parity holds). */
+    diagnostics: Diagnostic[];
+}
+export declare function buildQuerySystem(entries: Array<{
+    file: string;
+    model: NormalizedModel;
+    refs: RefsResult;
+    index: ModelIndex;
+}>): QuerySystem;
+/** `<modelKey>:<ref>` when the system spans more than one model, else the bare ref — the one
+ *  place every query verb decides whether to qualify a ref for output, so the WHEN can't drift
+ *  between verbs (the HOW is `formatQualifiedRef()`'s). */
+export declare function qualifyRef(system: QuerySystem, modelKey: string, ref: string): string;
+export interface ResolvedElement {
+    modelKey: string;
+    file: string;
+    entry: QueryModelEntry;
+    ref: string;
+    qualifiedRef: string;
+    elementKind: string;
+    elementName: string;
+}
+export type ResolveResult = {
+    ok: true;
+    match: ResolvedElement;
+} | {
+    ok: false;
+    error: string;
+};
+/** Resolve one user-supplied element reference — a stable ref, a `<modelKey>:`-qualified ref, or
+ *  a bare display name — against every model in `system` (or just the named model, when
+ *  qualified). A bare name/ref matching more than one element across the searched model(s) is
+ *  always an error listing every candidate as a fully-qualified ref (`<modelKey>:<ref>`, even
+ *  when `system` is single-model — a candidate list must be unambiguous on its own) — resolution
+ *  never guesses. "Resolution is per-model" (MIL-168's spec): a bare name is looked up in each
+ *  candidate model's OWN `byName` index, never merged across models before matching. A repeated
+ *  read model's later instances (`view X again`) don't count as separate name matches — see
+ *  the bare-name branch below. */
+export declare function resolveElement(system: QuerySystem, raw: string): ResolveResult;

package/dist/query/system.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: MIT
+// `em query`'s multi-model addressing (MIL-168): a `QuerySystem` is one or more compiled
+// models, each keyed by a short, stable `modelKey`. Refs (`<sliceKey>/<kind>.<slug>`) are, and
+// remain, model-UNQUALIFIED — `computeRefs()`'s contract is untouched. For a query answer that
+// spans more than one input file, that's ambiguous on its own (two models can easily mint the
+// same slice/element ref independently), so `em query` addresses cross-model results with the
+// qualified form `<modelKey>:<sliceKey>/<kind>.<slug>` — accepted on input alongside a bare
+// ref/display name, and used to disambiguate/print results whenever more than one file was given.
+//
+// Query was the first surface to need this (MIL-168) and originally derived `modelKey` from the
+// input filename. Since MIL-193 the key, the grammar, and the parse/format live in
+// model/qualifiedRef.ts — the ONE cross-model addressing scheme every em surface shares
+// (`em export`'s `model.key`, MIL-194's seam manifest, em-portal deep links): the key is the
+// kebab-slug of the declared `model "Name"` (basename fallback when none is declared), so a
+// query result's qualified ref is the same string an export consumer would mint for the same
+// element. This module only decides WHEN to qualify (more than one file given) and how a
+// user-supplied ref resolves; it never spells the grammar itself.
+import { normalizeName } from "../model/model.js";
+import { computeModelKeys, formatQualifiedRef, parseQualifiedRef } from "../model/qualifiedRef.js";
+export function buildQuerySystem(entries) {
+    const { keys, diagnostics } = computeModelKeys(entries);
+    return {
+        entries: entries.map((e, i) => ({ file: e.file, modelKey: keys[i], model: e.model, refs: e.refs, index: e.index })),
+        multiModel: entries.length > 1,
+        diagnostics,
+    };
+}
+/** `<modelKey>:<ref>` when the system spans more than one model, else the bare ref — the one
+ *  place every query verb decides whether to qualify a ref for output, so the WHEN can't drift
+ *  between verbs (the HOW is `formatQualifiedRef()`'s). */
+export function qualifyRef(system, modelKey, ref) {
+    return system.multiModel ? formatQualifiedRef(modelKey, ref) : ref;
+}
+const REF_SHAPE_RE = /\//;
+/** Resolve one user-supplied element reference — a stable ref, a `<modelKey>:`-qualified ref, or
+ *  a bare display name — against every model in `system` (or just the named model, when
+ *  qualified). A bare name/ref matching more than one element across the searched model(s) is
+ *  always an error listing every candidate as a fully-qualified ref (`<modelKey>:<ref>`, even
+ *  when `system` is single-model — a candidate list must be unambiguous on its own) — resolution
+ *  never guesses. "Resolution is per-model" (MIL-168's spec): a bare name is looked up in each
+ *  candidate model's OWN `byName` index, never merged across models before matching. A repeated
+ *  read model's later instances (`view X again`) don't count as separate name matches — see
+ *  the bare-name branch below. */
+export function resolveElement(system, raw) {
+    // `parseQualifiedRef` only splits when the prefix has the model-key SHAPE; a prefix that
+    // isn't one of THIS system's keys is then left in place — a display name may legitimately
+    // contain a colon — so the search runs over every model; if nothing matches, the miss names
+    // the unrecognised prefix (a typo'd qualifier is the likely cause).
+    const parsed = parseQualifiedRef(raw);
+    const known = parsed.modelKey !== null && system.entries.some((e) => e.modelKey === parsed.modelKey);
+    const modelKey = known ? parsed.modelKey : undefined;
+    const rest = known ? parsed.ref : raw;
+    const candidates = modelKey ? system.entries.filter((e) => e.modelKey === modelKey) : system.entries;
+    const matches = [];
+    for (const entry of candidates) {
+        // A slash makes the input look like a ref; when no ref matches, fall through to the
+        // display-name lookup — a name may itself contain a slash ("Approve/Reject Screen").
+        const byRef = REF_SHAPE_RE.test(rest) ? entry.index.byRef.get(rest) : undefined;
+        if (byRef) {
+            const ref = entry.refs.refById.get(byRef.id);
+            matches.push({ modelKey: entry.modelKey, file: entry.file, entry, ref, qualifiedRef: formatQualifiedRef(entry.modelKey, ref), elementKind: byRef.kind, elementName: byRef.name });
+        }
+        else {
+            // A repeated read model (`view X again`) has one name and several instances; the bare
+            // name means the read model, which resolves to its FIRST instance (`logicalId`) — every
+            // closure/path verb then follows the instance chain from there (verbs.ts's header). A
+            // later instance stays addressable by its own ref.
+            const bucket = (entry.model.byName.get(normalizeName(rest)) ?? []).filter((el) => el.logicalId === el.id);
+            for (const el of bucket) {
+                const ref = entry.refs.refById.get(el.id);
+                matches.push({ modelKey: entry.modelKey, file: entry.file, entry, ref, qualifiedRef: formatQualifiedRef(entry.modelKey, ref), elementKind: el.kind, elementName: el.name });
+            }
+        }
+    }
+    if (matches.length === 0) {
+        const hint = parsed.modelKey !== null && !known
+            ? ` ("${parsed.modelKey}" is not a model key — input models are: ${system.entries.map((e) => e.modelKey).join(", ")})`
+            : "";
+        return { ok: false, error: `em query: no element matches "${raw}"${hint}` };
+    }
+    if (matches.length > 1) {
+        const candidateRefs = matches.map((m) => m.qualifiedRef).join(", ");
+        return { ok: false, error: `em query: "${raw}" is ambiguous — matches ${matches.length} elements: ${candidateRefs}` };
+    }
+    return { ok: true, match: matches[0] };
+}
+//# sourceMappingURL=system.js.map

package/dist/query/system.js.map

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

package/dist/query/verbs.d.ts

@@ -0,0 +1,100 @@
+import { QuerySystem } from "./system.js";
+import { Citation } from "../cli/coverage.js";
+export interface ElementSummary {
+    ref: string;
+    kind: string;
+    name: string;
+    sliceKey: string;
+    sliceName: string;
+}
+export type VerbResult<T> = {
+    ok: true;
+    results: T[];
+} | {
+    ok: false;
+    error: string;
+};
+export interface ConsumerEntry extends ElementSummary {
+    via: string;
+}
+/** Views/reactions (and anything wired by an explicit `arrow`) consuming the named event — its
+ *  direct out-neighbors in the legal-connection graph, each with the slice it lives in. */
+export declare function queryConsumers(system: QuerySystem, eventRef: string): VerbResult<ConsumerEntry>;
+export interface ProducerEntry extends ElementSummary {
+    via: string;
+    uiTriggers: ElementSummary[];
+}
+/** Commands producing the named event, each with its own slice and (MIL-168 spec: "+ slices, ui
+ *  triggers") the `ui` elements that trigger that command in turn. */
+export declare function queryProducers(system: QuerySystem, eventRef: string): VerbResult<ProducerEntry>;
+export interface ClosureEntry extends ElementSummary {
+    depth: number;
+    via: string;
+}
+/** Transitive closure along legal edges (direction: element -> whatever it feeds) — impact
+ *  analysis: "what breaks if this changes." */
+export declare function queryDownstream(system: QuerySystem, ofRef: string, depth?: number): VerbResult<ClosureEntry>;
+/** Transitive closure against legal-edge direction — "what feeds this." */
+export declare function queryUpstream(system: QuerySystem, ofRef: string, depth?: number): VerbResult<ClosureEntry>;
+export interface SliceQueryEntry {
+    ref: string;
+    name: string;
+    index: number;
+    pattern: string;
+    status: string | null;
+    personas: string[];
+    contexts: string[];
+    tags: string[];
+}
+export interface SliceFilters {
+    pattern?: string;
+    status?: string;
+    context?: string;
+    persona?: string;
+    tag?: string;
+}
+/** The filtered slice list — every filter AND-combines. `pattern`/`status` match the slice's
+ *  own single value exactly (case-insensitive); `context`/`persona`/`tag` match when ANY
+ *  element in the slice carries that context/persona/tag key. */
+export declare function querySlices(system: QuerySystem, filters: SliceFilters): VerbResult<SliceQueryEntry>;
+export interface InvariantQueryEntry {
+    id: string;
+    sliceRef: string;
+    sliceName: string;
+    docPath: string | null;
+    status: string | null;
+    citations: Citation[] | null;
+}
+/** The declaring slice + doc facts for one `INV-*` id, and (with `testsDir`) every test file
+ *  citing it — a single-ID `scanTestCitations()` call, the same word-boundary citation scan
+ *  `em coverage` uses for every ID in the model, reused rather than reimplemented. An id
+ *  matching more than one input model is the same "unqualified + multi-model + ambiguous" case
+ *  every other verb refuses on, listing qualified candidates. */
+export declare function queryInvariant(system: QuerySystem, id: string, testsDir?: string): VerbResult<InvariantQueryEntry>;
+export interface FieldQueryEntry {
+    elementRef: string;
+    name: string;
+    type: string | null;
+    tag: boolean;
+    assigned: boolean;
+    renamedFrom: string[] | null;
+    /** The owning element's own `renamed from` chain (event/command only, MIL-68) — provenance
+     *  has two axes: the field's prior names, and the prior names of the element it lives on. */
+    elementRenamedFrom: string[] | null;
+}
+/** One field's facts on the named element — type, identity-tag/system-assigned markers, its
+ *  `renamed from` chain, and the owning element's. An element that resolves but carries no
+ *  field of that name is a legitimate empty result (`results: []`), not an error — same "none,
+ *  exit 0" contract as every other verb's empty answer. */
+export declare function queryField(system: QuerySystem, ofRef: string, name: string): VerbResult<FieldQueryEntry>;
+export interface PathQueryEntry {
+    refs: string[];
+    edgeKinds: string[];
+    length: number;
+}
+/** Shortest directed path from `fromRef` to `toRef` through the legal-connection graph (BFS,
+ *  unweighted — first-found is shortest by construction; a `view-instance` hop costs nothing
+ *  and isn't counted in `length`). Endpoints resolving to different models is a legitimate
+ *  empty result (edges never cross model files — see system.ts's header) rather than an
+ *  error. */
+export declare function queryPath(system: QuerySystem, fromRef: string, toRef: string): VerbResult<PathQueryEntry>;