@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/examples/wiki/lib/source-doc-parser.js

@@ -0,0 +1,318 @@
+"use strict";
+// source-doc-parser — extract @primitive / @module wiki blocks from
+// framework lib/*.js source files.
+//
+// Tag-ordering convention (enforced by validate-source-comment-blocks):
+//
+//   1. Single-line tags first: @primitive, @signature, @since,
+//      @status, @compliance, @related, @anchor, @headingTag
+//   2. Then the prose body (untagged lines — paragraphs separated
+//      by blank lines).
+//   3. Multi-line tags LAST: @opts, @example, @exampleFile, @intro.
+//      These accumulate every following line as their value until the
+//      next @-tag or block end — so any prose that sneaks in after
+//      them gets silently swallowed into the previous multi-line tag.
+//
+// Schema (lives in JSDoc-style /** */ comment blocks immediately
+// preceding the function or at the top of the module):
+//
+//   /**
+//    * @primitive   b.csv.parse
+//    * @signature   b.csv.parse(input, opts?)
+//    * @since       0.4.0
+//    * @status      stable
+//    * @compliance  gdpr, soc2
+//    * @related     b.csv.stringify, b.guardCsv
+//    *
+//    * Description prose. Multiple paragraphs separated by blank
+//    * lines. Inline `code` and links pass through.
+//    *
+//    * @example
+//    *   var rows = b.csv.parse("name,age");
+//    *
+//    * @exampleFile csv/parse.example.js   (alternative to @example)
+//    */
+//   function parse(input, opts) { ... }
+//
+// Module-level block (one per file, tagged @module):
+//
+//   /**
+//    * @module b.uuid
+//    *
+//    * @intro
+//    *   Namespace-wide prose.
+//    */
+//
+// The parser is intentionally regex-based — no AST dependency. Three
+// passes:
+//   1. extractBlocks(source)   - array of raw block strings
+//   2. parseBlock(rawBlock)    - { kind, tags, prose }
+//   3. parseFile(source, path) - { module?, primitives: [...] }
+
+var path = require("node:path");
+var fs   = require("node:fs");
+
+var BLOCK_RE = /\/\*\*([\s\S]*?)\*\//g;
+
+var SINGLE_LINE_TAGS = {
+  primitive:   true,
+  module:      true,
+  concept:     true,
+  title:       true,
+  nav:         true,
+  order:       true,
+  slug:        true,
+  featured:    true,
+  signature:   true,
+  since:       true,
+  status:      true,
+  compliance:  true,
+  related:     true,
+  exampleFile: true,
+  anchor:      true,
+  headingTag:  true,
+};
+
+var MULTI_LINE_TAGS = {
+  intro:       true,
+  example:     true,
+  opts:        true,
+  section:     true,
+  card:        true,
+};
+
+// Strip the smallest common leading-whitespace prefix from a block of
+// lines. Matches Python's textwrap.dedent. Authors who indent a
+// multi-line @example by 2 spaces in the source comment shouldn't see
+// that indentation leak into the rendered <pre> block.
+function _dedent(text) {
+  if (!text) return text;
+  var lines = text.split("\n");
+  // Find min indent across non-empty lines.
+  var minIndent = Infinity;
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    if (!line.trim()) continue;
+    var m = line.match(/^[ \t]*/);
+    var indent = m ? m[0].length : 0;
+    if (indent < minIndent) minIndent = indent;
+  }
+  if (!isFinite(minIndent) || minIndent === 0) return text;
+  return lines.map(function (l) {
+    return l.length >= minIndent ? l.slice(minIndent) : l;
+  }).join("\n");
+}
+
+function _stripCommentMarker(line) {
+  // Strip trailing \r FIRST so the tag regex's `$` anchor matches at
+  // end-of-line (the regex doesn't treat \r as a line terminator;
+  // without this, every CRLF-line tag appears unmatchable).
+  return line.replace(/\r$/, "").replace(/^\s*\*\s?/, "");
+}
+
+function _normalizeBlock(raw) {
+  return String(raw).split("\n").map(_stripCommentMarker);
+}
+
+function parseBlock(raw) {
+  var lines = _normalizeBlock(raw);
+  var tags = {};
+  var prose = [];
+  var current = null;
+  // Track ordering: did any prose appear AFTER a multi-line tag opened?
+  // The validator surfaces this as "multi-line tag preceded prose"
+  // because that prose got swallowed into the tag's value.
+  var sawMultiLineThenProse = false;
+  var openedMultiLine = false;
+
+  function _flushMulti() {
+    if (!current) return;
+    var key = current.tag;
+    var raw = current.lines.join("\n").replace(/^\n+|\n+$/g, "");
+    // Strip per-line trailing whitespace too — comment-block authors
+    // often leave a trailing space on the " * " marker line that
+    // becomes a stray space at the end of the rendered code block.
+    raw = raw.split("\n").map(function (l) {
+      return l.replace(/\s+$/, "");
+    }).join("\n").replace(/\n+$/, "");
+    // Dedent multi-line tag bodies — author indentation (commonly 2-3
+    // spaces inside the comment block) shouldn't leak into rendered
+    // output. @example/@intro/@opts/@section all benefit; the dedent
+    // is a no-op when authors didn't indent.
+    var value = _dedent(raw);
+    if (key === "example") {
+      if (!Array.isArray(tags.examples)) tags.examples = [];
+      tags.examples.push(value);
+    } else if (key === "section") {
+      // @section blocks accumulate as an ordered list. The first line
+      // is the section heading; following lines are the body. Lets a
+      // @concept block carry several sub-headings without a separate
+      // tag per heading.
+      if (!Array.isArray(tags.sections)) tags.sections = [];
+      var lines = value.split("\n");
+      var heading = lines.shift();
+      tags.sections.push({
+        heading: (heading || "").replace(/^\s+|\s+$/g, ""),
+        body:    lines.join("\n").replace(/^\n+|\n+$/g, ""),
+      });
+    } else {
+      tags[key] = value;
+    }
+    current = null;
+  }
+
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    var tagMatch = line.match(/^\s*@([a-zA-Z][a-zA-Z0-9]*)\b\s*(.*)$/);
+    if (tagMatch) {
+      _flushMulti();
+      var tag = tagMatch[1];
+      var rest = tagMatch[2];
+      if (SINGLE_LINE_TAGS[tag]) {
+        tags[tag] = rest.trim();
+      } else if (MULTI_LINE_TAGS[tag]) {
+        current = { tag: tag, lines: rest ? [rest] : [] };
+        openedMultiLine = true;
+      } else {
+        tags[tag] = rest.trim();
+      }
+      continue;
+    }
+    if (current) {
+      current.lines.push(line);
+      // Heuristic: a non-blank line that looks like a sentence (starts
+      // with a capital letter and ends with a period) inside a
+      // multi-line tag's body is *probably* prose the author placed in
+      // the wrong order. Mark it; the validator surfaces it.
+      var trimmed = line.replace(/^\s+|\s+$/g, "");
+      if (openedMultiLine && /^[A-Z]/.test(trimmed) && /[.!?]$/.test(trimmed)) {
+        sawMultiLineThenProse = true;
+      }
+      continue;
+    }
+    prose.push(line);
+  }
+  _flushMulti();
+
+  // Detect mixed-kind blocks — a single block declaring more than one
+  // of @primitive / @module / @concept. The validator surfaces these
+  // because the parser has to pick ONE kind silently and the unused
+  // tag is hidden.
+  var kindFlags = [];
+  if (tags.primitive) kindFlags.push("primitive");
+  if (tags.module) kindFlags.push("module");
+  if (tags.concept) kindFlags.push("concept");
+  var kind = kindFlags[0] || null;
+  var mixedKind = kindFlags.length > 1 ? kindFlags : null;
+
+  var proseText = prose.join("\n").replace(/^\n+|\n+$/g, "");
+
+  return {
+    kind:  kind,
+    tags:  tags,
+    prose: proseText,
+    // Ordering signal — surfaced by validate-source-comment-blocks so
+    // a wrong-order block fails the gate instead of silently producing
+    // an empty prose body.
+    proseAfterMultiLine: sawMultiLineThenProse,
+    // Mixed-kind signal — the block declared more than one of
+    // @primitive / @module / @concept. Surfaced as a finding because
+    // the parser silently picks one and the others are hidden.
+    mixedKind: mixedKind,
+  };
+}
+
+function extractBlocks(source) {
+  var blocks = [];
+  BLOCK_RE.lastIndex = 0;
+  var m;
+  while ((m = BLOCK_RE.exec(source)) !== null) {
+    blocks.push({
+      raw:      m[1],
+      startIdx: m.index,
+    });
+  }
+  return blocks;
+}
+
+function parseFile(source, sourcePath) {
+  var blocks = extractBlocks(source);
+  var module_ = null;
+  var primitives = [];
+  var concepts = [];
+  for (var i = 0; i < blocks.length; i++) {
+    var parsed = parseBlock(blocks[i].raw);
+    if (!parsed.kind) continue;
+    if (parsed.kind === "module") {
+      if (module_) {
+         
+        console.warn("[source-doc-parser] duplicate @module block in", sourcePath); // allow:console-direct — wiki seeder helper, runs at boot before b.log is wired
+      }
+      module_ = parsed;
+    } else if (parsed.kind === "primitive") {
+      primitives.push(parsed);
+    } else if (parsed.kind === "concept") {
+      concepts.push(parsed);
+    }
+  }
+  return {
+    sourcePath: sourcePath,
+    module:     module_,
+    primitives: primitives,
+    concepts:   concepts,
+  };
+}
+
+function parseTree(rootDir) {
+  var byPath = {};
+  function _walk(dir) {
+    var entries;
+    try { entries = fs.readdirSync(dir); } catch (_e) { return; }
+    for (var i = 0; i < entries.length; i++) {
+      var name = entries[i];
+      // Skip vendored libs + node_modules; they're not framework source.
+      if (name === "vendor" || name === "node_modules") continue;
+      var full = path.join(dir, name);
+      var stat;
+      try { stat = fs.statSync(full); } catch (_e) { continue; }
+      if (stat.isDirectory()) { _walk(full); continue; }
+      if (!stat.isFile()) continue;
+      if (!/\.js$/.test(name)) continue;
+      // CodeQL js/file-system-race defense — fd-based read binds the
+      // bytes we parse to the inode fs.statSync just measured. Even
+      // though the wiki doc-parser walks framework source files (not
+      // attacker-controlled), narrowing to a single fd matches the
+      // discipline of the rest of the framework's read paths.
+      var src;
+      try {
+        var srcFd = fs.openSync(full, "r");
+        try {
+          var srcStat = fs.fstatSync(srcFd);
+          var srcBuf = Buffer.alloc(srcStat.size);
+          var srcRead = 0;
+          while (srcRead < srcStat.size) {
+            var srcN = fs.readSync(srcFd, srcBuf, srcRead, srcStat.size - srcRead, null);
+            if (srcN === 0) break;
+            srcRead += srcN;
+          }
+          src = srcBuf.slice(0, srcRead).toString("utf8");
+        } finally {
+          try { fs.closeSync(srcFd); } catch (_c) { /* close best-effort */ }
+        }
+      } catch (_e) { continue; }
+      var parsed = parseFile(src, full);
+      if (parsed.module || parsed.primitives.length > 0 || parsed.concepts.length > 0) {
+        byPath[full] = parsed;
+      }
+    }
+  }
+  _walk(rootDir);
+  return byPath;
+}
+
+module.exports = {
+  parseBlock:    parseBlock,
+  parseFile:     parseFile,
+  parseTree:     parseTree,
+  extractBlocks: extractBlocks,
+};

package/lib/vendor/blamejs/examples/wiki/lib/symbol-index.js

@@ -0,0 +1,122 @@
+"use strict";
+// symbol-index — build-time harvest of every primitive signature
+// documented in the wiki, keyed by `b.X.Y` for client-side autocomplete.
+//
+// Walks the page seeders under seeders/prod/pages/, parses every
+// <h2>/<h3> heading, extracts the leading `b.X.Y(...)` signature
+// (matching the same pattern the primitive-section validator uses),
+// and produces a JSON manifest of:
+//
+//   [ { sig: "b.crypto.encryptEnvelope", page: "crypto-vault",
+//       anchor: "b-crypto-encryptenvelope", title: "Crypto & Vault" },
+//     ... ]
+//
+// Loaded by the buildApp boot sequence at app start. The wiki exposes
+// the manifest at /api/symbols.json so the client autocomplete reads
+// it as a static JSON resource.
+
+var HEADING_RE = /<h([23])(?:\s+[^>]*)?>([\s\S]*?)<\/h\1>/g;
+var SIG_RE     = /b\.[a-zA-Z][a-zA-Z0-9_.]*(?:\s*\([^)]*\))?/g;
+var ID_ATTR_RE = /\bid\s*=\s*"([^"]+)"/;
+
+function _stripAnchorMarkup(s) {
+  return String(s)
+    .replace(/<a\s+class="anchor"[^>]*>[\s\S]*?<\/a>/g, "")
+    .replace(/<\/?code>/g, "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/\s+/g, " ")
+    .replace(/^\s+|\s+$/g, "");
+}
+
+function _slugFromSig(sig) {
+  return String(sig)
+    .replace(/^\s*b\./, "")
+    .replace(/\([^)]*\)/g, "")
+    .replace(/\s+\/\s+/g, "-")
+    .replace(/[^a-zA-Z0-9_]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function _findHeadings(body) {
+  var rows = [];
+  HEADING_RE.lastIndex = 0;
+  var m;
+  while ((m = HEADING_RE.exec(body)) !== null) {
+    var idMatch = ID_ATTR_RE.exec(m[0]);
+    rows.push({
+      level: parseInt(m[1], 10),
+      idAttr: idMatch ? idMatch[1] : null,
+      inner: m[2],
+    });
+  }
+  return rows;
+}
+
+function _signaturesIn(innerHtml) {
+  var stripped = _stripAnchorMarkup(innerHtml);
+  if (stripped.indexOf("b.") !== 0) return [];
+  SIG_RE.lastIndex = 0;
+  var sigs = [];
+  var m;
+  while ((m = SIG_RE.exec(stripped)) !== null) {
+    var sig = m[0].replace(/\s+/g, " ");
+    sigs.push(sig);
+  }
+  return sigs;
+}
+
+function build(pages) {
+  if (!Array.isArray(pages)) throw new TypeError("build: pages array required");
+  var manifest = [];
+  for (var i = 0; i < pages.length; i++) {
+    var page = pages[i];
+    if (!page || typeof page.body !== "string") continue;
+    var headings = _findHeadings(page.body);
+    for (var h = 0; h < headings.length; h++) {
+      var heading = headings[h];
+      var sigs = _signaturesIn(heading.inner);
+      if (sigs.length === 0) continue;
+      var anchor = heading.idAttr || _slugFromSig(sigs[0]);
+      for (var s = 0; s < sigs.length; s++) {
+        manifest.push({
+          sig:     sigs[s],
+          sigBare: sigs[s].replace(/\([^)]*\)/g, "").replace(/\s+/g, ""),
+          page:    page.slug,
+          title:   page.title || page.slug,
+          anchor:  anchor,
+          level:   heading.level,
+        });
+      }
+    }
+  }
+  manifest.sort(function (a, b) {
+    if (a.sigBare < b.sigBare) return -1;
+    if (a.sigBare > b.sigBare) return 1;
+    return 0;
+  });
+  return manifest;
+}
+
+function groupByNamespace(manifest) {
+  var groups = {};
+  for (var i = 0; i < manifest.length; i++) {
+    var entry = manifest[i];
+    var parts = entry.sigBare.split(".");
+    var ns = parts.length >= 2 ? parts[1] : "_root";
+    if (!groups[ns]) groups[ns] = [];
+    groups[ns].push(entry);
+  }
+  return groups;
+}
+
+module.exports = {
+  build:            build,
+  groupByNamespace: groupByNamespace,
+  _findHeadings:    _findHeadings,
+  _signaturesIn:    _signaturesIn,
+  _slugFromSig:     _slugFromSig,
+};

package/lib/vendor/blamejs/examples/wiki/migrations/0001-pages-schema.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Pages schema for the wiki + FTS5 virtual table for /search recipe.
+ *
+ * Schema columns:
+ *   group, slug — composite PK so the same slug can exist in different groups
+ *   title       — display title
+ *   body        — operator-trusted HTML (rendered raw via {{{ }}})
+ *   updatedAt   — unix ms
+ *   updatedBy   — user id of the last editor (admin)
+ *
+ * FTS5 mirror is operator-side; we ship it here so /search works
+ * out-of-the-box and serves as the "search recipe" the docs reference.
+ * Triggers keep the FTS5 table in sync with the pages table on insert /
+ * update / delete — same shape every modern SQLite app uses.
+ */
+
+module.exports = {
+  description: "Create pages table + FTS5 search mirror",
+  up: function (db) {
+    db["exec"](
+      "CREATE TABLE IF NOT EXISTS pages (" +
+      "  groupName  TEXT NOT NULL," +
+      "  slug       TEXT NOT NULL," +
+      "  title      TEXT NOT NULL," +
+      "  body       TEXT NOT NULL," +
+      "  updatedAt  INTEGER NOT NULL," +
+      "  updatedBy  TEXT," +
+      "  PRIMARY KEY (groupName, slug)" +
+      ")"
+    );
+    db["exec"]("CREATE INDEX IF NOT EXISTS idx_pages_updatedAt ON pages (updatedAt)");
+
+    // FTS5 virtual table — operator-side recipe. Indexes title + body
+    // for full-text search via /search?q=...
+    db["exec"](
+      "CREATE VIRTUAL TABLE IF NOT EXISTS pages_fts USING fts5(" +
+      "  groupName UNINDEXED," +
+      "  slug      UNINDEXED," +
+      "  title," +
+      "  body," +
+      "  tokenize = 'porter'" +
+      ")"
+    );
+
+    // Triggers keep pages_fts in sync with pages. Drop-and-recreate
+    // approach inside each trigger keeps the SQL single-statement.
+    db["exec"](
+      "CREATE TRIGGER IF NOT EXISTS pages_fts_insert AFTER INSERT ON pages BEGIN " +
+      "  INSERT INTO pages_fts (groupName, slug, title, body) " +
+      "  VALUES (new.groupName, new.slug, new.title, new.body); " +
+      "END"
+    );
+    db["exec"](
+      "CREATE TRIGGER IF NOT EXISTS pages_fts_delete AFTER DELETE ON pages BEGIN " +
+      "  DELETE FROM pages_fts WHERE groupName = old.groupName AND slug = old.slug; " +
+      "END"
+    );
+    db["exec"](
+      "CREATE TRIGGER IF NOT EXISTS pages_fts_update AFTER UPDATE ON pages BEGIN " +
+      "  DELETE FROM pages_fts WHERE groupName = old.groupName AND slug = old.slug; " +
+      "  INSERT INTO pages_fts (groupName, slug, title, body) " +
+      "  VALUES (new.groupName, new.slug, new.title, new.body); " +
+      "END"
+    );
+  },
+  down: function (db) {
+    db["exec"]("DROP TRIGGER IF EXISTS pages_fts_update");
+    db["exec"]("DROP TRIGGER IF EXISTS pages_fts_delete");
+    db["exec"]("DROP TRIGGER IF EXISTS pages_fts_insert");
+    db["exec"]("DROP TABLE IF EXISTS pages_fts");
+    db["exec"]("DROP TABLE IF EXISTS pages");
+  },
+};

package/lib/vendor/blamejs/examples/wiki/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@blamejs/example-wiki",
+  "version": "0.1.0",
+  "description": "Wiki + docs reference app for blamejs — built on the framework it documents",
+  "private": true,
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24.14.1"
+  },
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "test":  "node test/e2e.js"
+  },
+  "dependencies": {
+    "@blamejs/core": "file:../.."
+  }
+}