prolog-notebook 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.1.2] — 2026-08-04
+
+Two bugs, both of which made the library quietly say something untrue. Found by
+running the published entry point, not by reading the code.
+
+### Fixed
+
+- **Compound terms lost their arguments.** `foo(1,2)` rendered as `foo()`,
+  `a-b` as `-()`, `f(g(h))` as `f()`. The arguments of a compound arrive under
+  the key *named by the functor* and wrapped in one extra array, not under
+  `args` as the formatter assumed. Atoms, numbers and lists were unaffected,
+  which is why the `once/1` example never showed it — that chapter only ever
+  binds variables to atoms.
+- **A syntax error reported a successful consult.** SWI prints the offending
+  clause, skips it and carries on, so `consult/1` still succeeded and the cell
+  said `✓ consulted` while the predicate was not there.
+- **A cell could silently destroy another cell's clauses.** Two cells defining
+  the same predicate make SWI print "Redefined static procedure" and keep only
+  the later one. That warning went to the console and nothing reached the page.
+- `consult` no longer produces paths like `/chapter.pl.pl` when the cell name
+  already ends in `.pl`.
+
+### Added
+
+- `PrologSession#formatTerm` and `#formatSolution` render through SWI itself, so
+  operators, quoting and every other rule of the writer come out right —
+  `X = a-b`, not `X = -(a, b)`. `query.next()` now carries a `text` field with
+  the solution already rendered this way; prefer it over `formatSolution`.
+- `consult` returns `messages: [{kind, text}]` — SWI's warnings and errors for
+  that cell, captured through `message_hook/3`.
+- `argumentsOf`, `textOf` and `toEngineTerm` are exported for anything that
+  needs to walk a term.
+- Eleven more tests, including the reconsult behaviour the notebook renderer
+  will depend on: re-consulting one cell replaces exactly that cell's clauses,
+  leaves dependent cells working, and leaves no ghost behind when a predicate is
+  renamed.
+
+## [0.1.1] — 2026-08-02
+
+No functional change. Published from CI via npm trusted publishing (OIDC) to
+verify the release pipeline end to end — v0.1.0 was published by hand to claim
+the name.
+
+### Changed
+
+- Release workflow authenticates over OIDC instead of an `NPM_TOKEN`. npm
+  deprecates 2FA-bypass granular tokens for direct publishing around January
+  2027 and points at trusted publishing instead; it also removes the 90-day
+  token expiry from the loop.
+- The example page now says so when it has not started, instead of leaving the
+  buttons silently inert (browsers block ES modules over `file://`).
+
 ## [0.1.0] — 2026-08-02
 
 First release. The execution core works; the file-backed renderer does not exist yet.

package/README.md

@@ -140,4 +140,4 @@ MIT
 
 [kernel]: https://github.com/hhu-stups/prolog-jupyter-kernel
 [wasm]: https://github.com/SWI-Prolog/swipl-wasm
-[ptv]: https://github.com/jarecsni/prolog-trace-viz
+[ptv]: https://github.com/textologylabs/prolog-trace-viz

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Jupyter-style notebooks for Prolog. Runs in the browser, installs nothing.",
   "type": "module",
   "main": "./src/node.js",

package/src/engine.js

@@ -6,6 +6,21 @@
 
 let fileSerial = 0;
 
+// SWI reports "Redefined static procedure" and friends by printing to user_error
+// and then carrying on, so a consult that quietly destroyed another cell's
+// clauses still succeeds. message_hook/3 is the documented way to intercept
+// those; failing at the end lets the normal printing happen as well.
+const MESSAGE_HOOK = `
+:- dynamic '$nb_message'/2.
+user:message_hook(_Term, Kind, Lines) :-
+    memberchk(Kind, [warning, error]),
+    catch(with_output_to(string(S),
+                         print_message_lines(current_output, '', Lines)),
+          _, S = ''),
+    assertz('$nb_message'(Kind, S)),
+    fail.
+`;
+
 export class PrologSession {
   /**
    * @param {Function} swiplFactory the SWIPL factory from swipl-wasm
@@ -13,7 +28,12 @@ export class PrologSession {
    */
   static async create(swiplFactory, options = {}) {
     const module = await swiplFactory({ arguments: ['-q'], ...options });
-    return new PrologSession(module);
+    const session = new PrologSession(module);
+    // No `$` in the path: SWI expands $var in file names like a shell does, so
+    // /$nb-hook.pl resolves to nothing and the consult fails silently.
+    module.FS.writeFile('/nb-hook.pl', MESSAGE_HOOK);
+    module.prolog.query("user:consult('/nb-hook.pl')").once();
+    return session;
   }
 
   constructor(module) {
@@ -22,18 +42,31 @@ export class PrologSession {
 
   /**
    * Load a clause base into the `user` module.
+   *
+   * Each cell should pass its own stable `name`: SWI attributes clauses to the
+   * file they came from, so re-consulting the same name replaces exactly that
+   * cell's clauses and leaves every other cell alone.
+   *
    * @param {string} text Prolog source
-   * @returns {{ok: boolean, error?: string}}
+   * @param {string} [name] virtual file name; identifies the cell
+   * @returns {{ok: boolean, error?: string, messages: {kind: string, text: string}[]}}
    */
   consult(text, name = `cell${fileSerial++}`) {
-    const path = `/${name}.pl`;
+    const path = `/${name.replace(/\.pl$/, '')}.pl`;
     try {
       this.module.FS.writeFile(path, text);
+      this.#drainMessages();
       const r = this.module.prolog.query(`user:consult('${path}')`).once();
-      if (r && r.error) return { ok: false, error: r.message };
-      return { ok: true };
+      const messages = this.#drainMessages();
+      if (r && r.error) return { ok: false, error: r.message, messages };
+      // A clause SWI could not read is reported and then skipped, so consult
+      // itself still succeeds. Reporting that as "✓ consulted" would leave the
+      // reader with a cell that looks loaded and a predicate that is not there.
+      const failed = messages.find((m) => m.kind === 'error');
+      if (failed) return { ok: false, error: failed.text, messages };
+      return { ok: true, messages };
     } catch (e) {
-      return { ok: false, error: e.message };
+      return { ok: false, error: e.message, messages: [] };
     }
   }
 
@@ -47,20 +80,68 @@ export class PrologSession {
     // Cells consult into `user`, but prolog.query/1 runs with `system` as the
     // context module, so an unqualified goal resolves against the wrong one.
     const cleaned = goal.trim().replace(/\.$/, '');
-    return new PrologQuery(this.module.prolog.query(`user:( ${cleaned} )`));
+    return new PrologQuery(this.module.prolog.query(`user:( ${cleaned} )`), this);
+  }
+
+  /**
+   * Render a term the way SWI's own top level would, by asking SWI. Worth the
+   * round trip: it gets operators (a-b, not -(a,b)), atom quoting and every
+   * other rule of the writer right, none of which we want to reimplement.
+   * @returns {string}
+   */
+  formatTerm(term) {
+    try {
+      const r = this.module.prolog
+        .query('term_string(T, S)', { T: toEngineTerm(term) })
+        .once();
+      const s = r && r.S;
+      if (typeof s === 'string') return s;
+      if (s && typeof s.v === 'string') return s.v;
+    } catch {
+      // fall through to the DOM-free renderer below
+    }
+    return formatTerm(term);
+  }
+
+  /** Render a full solution the way a top level would. */
+  formatSolution(solution) {
+    const pairs = Object.entries(solution);
+    if (!pairs.length) return 'true';
+    return pairs.map(([k, v]) => `${k} = ${this.formatTerm(v)}`).join(',  ');
+  }
+
+  #drainMessages() {
+    try {
+      const r = this.module.prolog
+        .query("user:( findall(m(K,T), '$nb_message'(K,T), L ), retractall('$nb_message'(_,_)) )")
+        .once();
+      if (!r || !Array.isArray(r.L)) return [];
+      return r.L.map((m) => {
+        const [kind, text] = argumentsOf(m);
+        return { kind: String(kind), text: textOf(text).trim() };
+      });
+    } catch {
+      return [];
+    }
   }
 }
 
 export class PrologQuery {
-  constructor(handle) {
+  constructor(handle, session) {
     this.handle = handle;
+    this.session = session;
     this.exhausted = false;
     this.count = 0;
   }
 
   /**
    * Pull the next solution.
-   * @returns {{done: boolean, solution?: object, error?: string}}
+   *
+   * `text` is the solution rendered by SWI itself; prefer it over calling
+   * formatSolution, which has no engine to ask and so cannot know about
+   * operators or quoting.
+   *
+   * @returns {{done: boolean, solution?: object, text?: string, error?: string}}
    */
   next() {
     if (this.exhausted) return { done: true };
@@ -83,6 +164,9 @@ export class PrologQuery {
     if (r.value) {
       this.count += 1;
       out.solution = bindingsOf(r.value);
+      // Safe while the outer query is still open — verified by stepping a
+      // three-solution query with a term_string call between every step.
+      if (this.session) out.text = this.session.formatSolution(out.solution);
     }
     if (r.done) this.exhausted = true;
     return out;
@@ -121,13 +205,67 @@ export function formatSolution(solution) {
   return pairs.map(([k, v]) => `${k} = ${formatTerm(v)}`).join(',  ');
 }
 
+// swipl-wasm tags every non-atomic value it hands back:
+//   compound  { $t: 't', functor: 'f', f: [[arg, ...]] }
+//   string    { $t: 's', v: 'text' }
+//   variable  { $t: 'v', v: '_123' }
+//   rational  { $t: 'r', n, d }
+//   list      { $t: 'l', v: [...], tail }
+// Note the compound's arguments live under the key NAMED BY THE FUNCTOR, and
+// arrive wrapped in one extra array — swipl-wasm builds them with
+// `new Compound(name, args)` against a `(name, ...args)` signature. Its own
+// arguments()/arity()/arg() accessors are wrong for the same reason, so read
+// the arguments here rather than trusting them.
+export function argumentsOf(term) {
+  if (!term || typeof term !== 'object' || !term.functor) return [];
+  const raw = term[term.functor];
+  if (!Array.isArray(raw)) return [];
+  return raw.length === 1 && Array.isArray(raw[0]) ? raw[0] : raw;
+}
+
+/**
+ * Undo the extra wrapping so a term can be handed back to the engine.
+ * swipl-wasm's JS-to-Prolog direction expects `term[functor]` to BE the
+ * argument list, which is not what its Prolog-to-JS direction produces — round
+ * tripping an untouched term turns point(1,2) into point([1,2]).
+ */
+export function toEngineTerm(v) {
+  if (Array.isArray(v)) return v.map(toEngineTerm);
+  if (!v || typeof v !== 'object') return v;
+  if (v.$t !== 't' || !v.functor) return v;
+  return { $t: 't', functor: v.functor, [v.functor]: argumentsOf(v).map(toEngineTerm) };
+}
+
+/** The text of a Prolog string, which arrives tagged rather than as a JS string. */
+export function textOf(v) {
+  if (typeof v === 'string') return v;
+  if (v && typeof v === 'object' && typeof v.v === 'string') return v.v;
+  return String(v);
+}
+
+/**
+ * Render a term without an engine to ask.
+ *
+ * This is the fallback: it writes compounds in canonical functional notation,
+ * so `a-b` comes out as `-(a, b)`. Correct, but not what a top level shows —
+ * prefer PrologSession#formatTerm whenever a session is at hand.
+ */
 export function formatTerm(v) {
   if (v === null || v === undefined) return '_';
   if (Array.isArray(v)) return `[${v.map(formatTerm).join(', ')}]`;
   if (typeof v === 'object') {
-    if (v.$tag === 'string') return `"${v.text}"`;
-    if (v.functor) return `${v.functor}(${(v.args || []).map(formatTerm).join(', ')})`;
-    if (v.v !== undefined) return `_${v.v}`;
+    switch (v.$t) {
+      case 't': return `${v.functor}(${argumentsOf(v).map(formatTerm).join(', ')})`;
+      case 's': return `"${textOf(v)}"`;
+      case 'v': return String(v.v ?? '_');
+      case 'r': return `${v.d}r${v.n}`;
+      case 'l': {
+        const items = (v.v || []).map(formatTerm).join(', ');
+        return v.tail === undefined ? `[${items}]` : `[${items}|${formatTerm(v.tail)}]`;
+      }
+      default: break;
+    }
+    if (v.functor) return `${v.functor}(${argumentsOf(v).map(formatTerm).join(', ')})`;
     return JSON.stringify(v);
   }
   return String(v);

package/src/notebook.css

@@ -100,6 +100,9 @@ button.primary:hover { background: #98380f; }
 .status.ok { color: var(--ok); }
 .status.err { color: var(--err); }
 .status.busy { color: #8a8371; }
+/* Loaded, but SWI said something the reader needs to see — most often that this
+   cell has redefined a predicate another cell owns. */
+.status.warn { color: #a8730f; white-space: pre-line; line-height: 1.4; }
 
 .out {
   font: 13.5px/1.7 ui-monospace, Menlo, monospace;

package/src/notebook.js

@@ -45,8 +45,11 @@ function mountProgram(cell) {
     try {
       const session = await boot(status);
       const r = session.consult(source.value, name);
-      status.textContent = r.ok ? '✓ consulted' : r.error;
-      status.className = `status ${r.ok ? 'ok' : 'err'}`;
+      // A warning here usually means this cell has just destroyed another
+      // cell's clauses, which the reader has no other way of finding out.
+      const warning = r.messages && r.messages.find((m) => m.kind === 'warning');
+      status.textContent = r.ok ? warning ? warning.text : '✓ consulted' : r.error;
+      status.className = `status ${r.ok ? (warning ? 'warn' : 'ok') : 'err'}`;
     } catch (e) {
       status.textContent = e.message;
       status.className = 'status err';
@@ -84,7 +87,8 @@ function mountQuery(cell) {
   const step = () => {
     if (!query) return;
     const r = query.next();
-    if (r.solution) write(`${++count}.  ${formatSolution(r.solution)}`, 'sol');
+    // r.text is rendered by SWI itself, so operators and quoting are right.
+    if (r.solution) write(`${++count}.  ${r.text ?? formatSolution(r.solution)}`, 'sol');
     if (r.error) {
       write(r.error, 'err');
       finish();