dsh-model-everything 0.1.0 → 0.3.0

package/lib/report-view.js

@@ -1,4 +1,4 @@
-const DEFAULTS = { maxFindingsPerCheck: 24, maxEvidenceChars: 160, includePassing: false, full: false };
+const DEFAULTS = { maxFindingsPerCheck: 24, maxEvidenceChars: 160, includePassing: false, full: false, check: undefined };
 const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
 const array = (value) => (Array.isArray(value) ? value : []);
 const text = (value) => (typeof value === 'string' ? value : undefined);
@@ -93,8 +93,20 @@ function findingLines(findings, options, seenFacts) {
         group.events.push(event);
         stateGroups.set(state, group);
     }
+    // The same event set on every state is one fact, not one per state: a 26-state machine whose
+    // states all ignore the same four events printed 24 near-identical lines, a quarter of the body.
+    // States that share a set are counted; a handful still name themselves, because there the names
+    // are what the reader acts on.
+    const byEventSet = new Map();
     for (const [state, group] of stateGroups) {
-        lines.push(`  ${state} (${String(group.events.length)}) [${group.severity}/${group.code}]: ${group.events.join(', ')}`);
+        const key = `${group.severity}|${group.code}|${group.events.join(',')}`;
+        const bucket = byEventSet.get(key) ?? { severity: group.severity, code: group.code, events: group.events, states: [] };
+        bucket.states.push(state);
+        byEventSet.set(key, bucket);
+    }
+    for (const group of byEventSet.values()) {
+        const who = group.states.length > 3 ? `${String(group.states.length)} states` : group.states.join(', ');
+        lines.push(`  ${who} (${String(group.events.length)}) [${group.severity}/${group.code}]: ${group.events.join(', ')}`);
     }
     const rendered = collapse(singles.map((finding) => findingLine(finding, options)));
     const budget = options.maxFindingsPerCheck;
@@ -126,6 +138,30 @@ function headerLines(report, options) {
         ok === undefined || verdict === undefined ? '' : `ok=${String(ok)}`,
     ].filter((bit) => bit !== '');
     lines.push(bits.join('  '));
+    // A graph report answers "which module is the hub" in one line: counting incoming edges off the graph by
+    // hand is where a correct graph still produced a wrong answer, in both conditions of the round that asked.
+    const degreeSummary = record(report.summary);
+    const hubs = array(degreeSummary?.hubs).map((entry) => record(entry)).filter((entry) => entry !== undefined);
+    if (hubs.length > 0) {
+        const counts = degreeSummary?.nodes !== undefined && degreeSummary?.edges !== undefined ? `  ${String(degreeSummary.nodes)} modules, ${String(degreeSummary.edges)} edges` : '';
+        lines.push(`GRAPH${counts}`);
+        lines.push('  ' + hubs.map((entry) => `${String(entry.id)} (${String(entry.dependents)} dependents)`).join(', '));
+        const leaves = array(degreeSummary?.leaves).map((leaf) => String(leaf));
+        if (leaves.length > 0)
+            lines.push('  imports nothing: ' + leaves.join(', '));
+    }
+    // A scan has to say what it covered, or a model that cannot see the boundary recounts the tree by hand
+    // and spends more than the tool saved. The numbers are the boundary: files read, references resolved.
+    const scan = record(report.scan);
+    if (scan !== undefined) {
+        const files = String(scan.files ?? '?');
+        const unresolved = Number(scan.unresolved ?? 0);
+        const languages = array(scan.languages).map((entry) => String(entry));
+        lines.push(`SCAN  ${files} files read, ${String(unresolved)} unresolved${languages.length === 0 ? '' : ', ' + languages.join(', ')}`);
+        lines.push(unresolved === 0
+            ? '  this is the whole tree: every relative reference resolved, so a recount by hand cannot find more'
+            : '  the unresolved lines above are outside this tree; count nothing twice');
+    }
     // A refusal carries no model to hash, and the field is an empty string rather than absent, so it rendered
     // as `modelHash=…` - which reads as a truncated hash rather than as nothing to hash. An empty value means
     // the same thing as a missing one here.
@@ -192,6 +228,29 @@ function footerLines(report) {
     return lines;
 }
 /** A `checks[]` report (verify, compose, datamodel): silence pass, expand the rest. */
+/**
+ * An edit result: what changed in the model, then what changed in the findings.
+ *
+ * The two belong together because the second is the reason the first happened. The delta is
+ * rendered by the delta renderer rather than restated here, so an edit and a `report_diff` of the
+ * same two reports cannot drift apart.
+ */
+function renderEditReport(report, options) {
+    const lines = headerLines(report, options);
+    const changes = array(report.changes).map((value) => record(value) ?? {});
+    const added = changes.filter((change) => text(change.kind) === 'added').length;
+    const removed = changes.filter((change) => text(change.kind) === 'removed').length;
+    const updated = changes.filter((change) => text(change.kind) === 'updated').length;
+    lines.push(`CHANGES  ${String(added)} added, ${String(removed)} removed, ${String(updated)} updated`);
+    for (const change of changes) {
+        const detail = text(change.detail);
+        lines.push(`  ${text(change.kind) ?? '?'} ${text(change.what) ?? '?'}${detail === undefined || detail === '' ? '' : ` — ${detail}`}`);
+    }
+    const delta = record(report.reportDelta);
+    if (delta !== undefined)
+        lines.push('', ...renderDeltaReport(delta, options));
+    return [...lines, ...wrapFooter(report)];
+}
 function renderChecksReport(report, options) {
     const checks = array(report.checks).map((value) => record(value) ?? {});
     const byStatus = (status) => checks.filter((check) => text(check.status) === status).map((check) => text(check.id) ?? '?');
@@ -218,14 +277,26 @@ function renderChecksReport(report, options) {
         .filter(([, ids]) => ids.length > 0)
         .map(([status, ids]) => `${String(status)} ${ids.join(' ')}`)
         .join(' | ');
-    const lines = [...headerLines(report, options), `CHECKS  ${inventory}`];
+    const lines = [...headerLines(report, options)];
+    lines.push(`CHECKS  ${inventory}`);
+    const requested = options.check;
+    const ids = checks.map((check) => text(check.id)).filter((id) => id !== undefined);
+    const selected = requested === undefined ? checks : checks.filter((check) => text(check.id) === requested);
+    // A name that matches nothing is answered with the names that exist: silently printing the whole
+    // report, or an empty body, both read as "that check was clean".
+    if (requested !== undefined && selected.length === 0) {
+        lines.push(`NOTE  no check \`${requested}\` in this report; it carries: ${ids.join(' ')}`);
+    }
+    // Asking for one check is a request for its lines: the per-check budget that keeps the digest
+    // small does not apply, since the caller has already paid for the narrowing.
+    const view = requested === undefined ? options : { ...options, includePassing: true, maxFindingsPerCheck: Number.MAX_SAFE_INTEGER };
     const seenFacts = new Set();
-    for (const check of checks) {
+    for (const check of selected) {
         const status = text(check.status) ?? 'skip';
         const findings = array(check.findings).map((finding) => toViewFinding(finding, text(check.id)));
         if (status === 'pass' && !options.includePassing)
             continue;
-        const body = findingLines(findings, options, seenFacts);
+        const body = findingLines(findings, view, seenFacts);
         if (status !== 'fail' && body.length === 0)
             continue;
         lines.push('');
@@ -380,8 +451,10 @@ function renderFallbackReport(report, options) {
  */
 export function renderReportText(value, options = {}) {
     const resolved = { ...DEFAULTS, ...options };
+    // Compact rather than pretty: `full` exists so a caller can hand the object on (report_diff matches
+    // on check + code + evidence), and indentation is a third of a large report's bytes for no reader.
     if (resolved.full)
-        return JSON.stringify(value, null, 2);
+        return JSON.stringify(value);
     const report = record(value);
     if (report === undefined)
         return JSON.stringify(value) ?? String(value);
@@ -395,14 +468,18 @@ export function renderReportText(value, options = {}) {
     // which printed the whole object as JSON.
     const isDelta = Array.isArray(report.added) || Array.isArray(report.removed) || Array.isArray(report.changed) || typeof report.currentVerdict === 'string';
     const isPayload = typeof report.diagram === 'string' || typeof report.primary === 'string';
-    const lines = hasChecks
-        ? renderChecksReport(report, resolved)
-        : isDelta
-            ? renderDeltaReport(report, resolved)
-            : hasFindings
-                ? renderFindingsReport(report, resolved)
-                : isPayload
-                    ? renderPayloadReport(report, resolved)
-                    : renderFallbackReport(report, resolved);
+    // An edit result names its changes; the findings it brings along are a delta, which already has a renderer.
+    const isEdit = Array.isArray(report.changes);
+    const lines = isEdit
+        ? renderEditReport(report, resolved)
+        : hasChecks
+            ? renderChecksReport(report, resolved)
+            : isDelta
+                ? renderDeltaReport(report, resolved)
+                : hasFindings
+                    ? renderFindingsReport(report, resolved)
+                    : isPayload
+                        ? renderPayloadReport(report, resolved)
+                        : renderFallbackReport(report, resolved);
     return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
 }

package/lib/routing.js

@@ -0,0 +1,85 @@
+/**
+ * Which tool owns which question, in one table.
+ *
+ * Two consumers read this, and they used to read two different things: the result a model gets
+ * (`nextSteps` naming a sibling) and the toolset map a human reads (hand-written prose). That is how the
+ * map came to say "about ten thousand characters" while the descriptions measured twenty-nine: a fact
+ * stated twice drifts, and nothing fails when it does.
+ *
+ * So the table states the routing once. `routeFor` hands it to the card a UI draws; the toolset map
+ * generator reads the same table and refuses to write a map for a tool that is missing from it.
+ *
+ * What it is not: a decision. The tool a request should use is chosen by the model from the descriptions.
+ * This table says what each tool owns and which neighbour takes the case just outside that line, so a
+ * report can redirect without a reader having to remember the roster.
+ */
+export const ROUTES = {
+    model_verify: {
+        owns: 'one machine: reachable states, invariants, deadlock, and a before/after regression',
+        notFor: { when: 'two or more machines must handshake or share a location', tool: 'model_compose_verify' },
+    },
+    model_compose_verify: {
+        owns: 'several machines run together: rendezvous, shared locations, lost updates',
+        notFor: { when: 'the question is about one machine on its own', tool: 'model_verify' },
+    },
+    model_automaton_verify: {
+        owns: 'a finite-word language, and its relation to another automaton',
+        notFor: { when: 'the question is reachability or deadlock inside one state machine', tool: 'model_verify' },
+    },
+    model_edit: {
+        owns: 'one editing round on a model file, answered with the structural diff and the change in findings',
+        notFor: { when: 'the edit is done and the model has to be decided again', tool: 'model_verify' },
+    },
+    model_datamodel_verify: {
+        owns: 'entities, keys, migrations, and whether the data survived them',
+        notFor: { when: 'the question is about behaviour over time rather than stored state', tool: 'model_verify' },
+    },
+    model_design_review: {
+        owns: "a design's own declarations: layering, responsibility, substitutability, interface width",
+        notFor: { when: 'the question is a fact about the graph - does this edge exist', tool: 'uml_structure_verify' },
+    },
+    model_interleaving_scan: {
+        owns: 'mining a document or plan for concurrency claims, and routing each to the analysis that decides it',
+        notFor: { when: 'the protocol itself has to be decided', tool: 'model_compose_verify' },
+    },
+    model_export: {
+        owns: 'a model translated into UPPAAL, TLA+, PRISM or SPIN for a property this plugin does not decide',
+        notFor: { when: 'the property can be decided here', tool: 'model_verify' },
+    },
+    report_diff: {
+        owns: 'what changed between two reports of the same family',
+        notFor: { when: 'the current report does not exist yet', tool: 'model_verify' },
+    },
+    uml_render: {
+        owns: 'drawing a model in the notation that can carry its family',
+        notFor: { when: 'the question is whether the modelling is sound', tool: 'uml_review' },
+    },
+    uml_parse: {
+        owns: 'reading a diagram back into the model its family declares',
+        notFor: { when: 'the question is whether the diagram says something sound', tool: 'uml_review' },
+    },
+    uml_review: {
+        owns: 'auditing the modelling: reachability, ambiguity, round-trip fidelity, family-specific defects',
+        notFor: { when: 'the claim is about behaviour rather than the drawing', tool: 'model_verify' },
+    },
+    uml_explain_labels: {
+        owns: 'the label spellings a notation accepts and the directives that pin the rest',
+        notFor: { when: 'a diagram has to be read rather than explained', tool: 'uml_parse' },
+    },
+    uml_structure_verify: {
+        owns: 'a dependency graph as a graph - cycles, layers, dangling edges - from a drawing or a source tree',
+        notFor: { when: 'the question is a rule the design declared for itself, not an edge that exists', tool: 'model_design_review' },
+    },
+};
+/** The route for a tool, or undefined when the tool has none. */
+export function routeFor(tool) {
+    return ROUTES[tool];
+}
+/** Every tool a route names, for a caller that has to check the table against the registry. */
+export function routedTools() {
+    return Object.keys(ROUTES);
+}
+/** The tools named as the owner of an adjacent case. */
+export function siblingTools() {
+    return [...new Set(Object.values(ROUTES).map((route) => route.notFor.tool))].sort();
+}