@spec-engine/spec-engine 0.8.0 → 0.8.1

package/dist/docs/agent-reference/index.html

@@ -97,7 +97,7 @@
 <div class="sl-heading-wrapper level-h2"><h2 id="path-rules-for-spec-resolve">Path rules for <code dir="auto">spec resolve</code></h2><a class="sl-anchor-link" href="#path-rules-for-spec-resolve"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore>Section titled “Path rules for spec resolve”</span></a></div>
 <ul>
 <li><strong>Multi-repo platform:</strong> pass <code dir="auto">&lt;repo&gt;/&lt;path&gt;</code> — e.g., <code dir="auto">spec resolve api/src/renew.ts .</code></li>
-<li><strong>Single-repo (rung-1):</strong> both repo-relative (<code dir="auto">src/orders.ts</code>) and basename-prefixed forms accepted</li>
+<li><strong>Single-repo (rung-1):</strong> pass the path from the platform root (<code dir="auto">src/orders.ts</code>, <code dir="auto">.github/workflows/ci.yml</code>); a lone repository’s files carry no directory-name prefix</li>
 <li>Absolute paths normalized against <code dir="auto">platformDir</code>; paths outside it exit 2</li>
 </ul>
 <div class="sl-heading-wrapper level-h2"><h2 id="gotchas">Gotchas</h2><a class="sl-anchor-link" href="#gotchas"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore>Section titled “Gotchas”</span></a></div>

package/dist/docs/pagefind/pagefind-entry.json

@@ -1 +1 @@
-{"version":"1.5.2","languages":{"en":{"hash":"en_d0b5c328bc","wasm":"en","page_count":12}},"include_characters":["_","‿","⁀","⁔","︳","︴","﹍","﹎","﹏","＿"]}
+{"version":"1.5.2","languages":{"en":{"hash":"en_ced49c317e","wasm":"en","page_count":12}},"include_characters":["_","‿","⁀","⁔","︳","︴","﹍","﹎","﹏","＿"]}

package/dist/impl.js

@@ -20,7 +20,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@spec-engine/spec-engine",
-    version: "0.8.0",
+    version: "0.8.1",
     description: "Cross-repo spec engine \u2014 durable requirements with permanent IDs, bound to code via @spec tags, checked in CI. Ships the spec CLI, the local coverage webapp (spec serve), and offline docs (spec docs).",
     license: "MIT",
     type: "module",
@@ -73,6 +73,31 @@ var init_package = __esm(() => {
   };
 });
 
+// src/stdout.ts
+import { format } from "util";
+function isEpipe(e) {
+  return typeof e === "object" && e !== null && "code" in e && (e.code === "EPIPE" || e.code === "ERR_STREAM_DESTROYED");
+}
+function routeStdout() {
+  process.stdout.on("error", (e) => {
+    if (!isEpipe(e))
+      throw e;
+  });
+  console.log = (...args) => {
+    const text = `${format(...args)}
+`;
+    lastWrite = new Promise((written) => process.stdout.write(text, () => written()));
+  };
+}
+async function exit(code) {
+  await lastWrite;
+  process.exit(code);
+}
+var lastWrite;
+var init_stdout = __esm(() => {
+  lastWrite = Promise.resolve();
+});
+
 // ../shared/src/diagnostics.ts
 var DiagnosticCode, NotASpecPlatformError, InvalidDomainFilesError;
 var init_diagnostics = __esm(() => {
@@ -2193,33 +2218,9 @@ class SqliteStorage {
     if (files.length > FILES_MAX) {
       throw new Error(`resolveByFiles: too many files (max ${FILES_MAX} per call; got ${files.length})`);
     }
-    const queryFiles = this.#expandSelfMemberFiles(files);
-    if (queryFiles.length > 32000) {
-      throw new Error(`resolveByFiles: expanded bind count ${queryFiles.length} would exceed ` + "SQLITE_MAX_VARIABLE_NUMBER (32766); lower FILES_MAX");
-    }
-    const placeholders = queryFiles.map(() => "?").join(",");
+    const placeholders = files.map(() => "?").join(",");
     const sql = RESOLVE_BY_FILES_SQL_PREFIX + placeholders + RESOLVE_BY_FILES_SQL_SUFFIX;
-    return this.#db.query(sql).all(...queryFiles);
-  }
-  #selfMemberName() {
-    const canonical = this.getRepo("spec-engine");
-    if (!canonical)
-      return null;
-    const platformRoot = dirname2(canonical.path);
-    const row = this.#db.query("SELECT name FROM repos WHERE name != 'spec-engine' AND path = $path").get({ path: platformRoot });
-    return row?.name ?? null;
-  }
-  #expandSelfMemberFiles(files) {
-    const self = this.#selfMemberName();
-    if (!self)
-      return files;
-    const prefix = `${self}/`;
-    const expanded = [...files];
-    for (const f of files) {
-      if (!f.startsWith(prefix))
-        expanded.push(prefix + f);
-    }
-    return expanded;
+    return this.#db.query(sql).all(...files);
   }
   withWriteTx(fn) {
     const wrapped = this.#db.transaction((arg) => fn(arg));
@@ -2702,7 +2703,10 @@ function scannedTagFile(members, platformDir, platformRel) {
     return null;
   if (!isTagSource(rel) && !isDocSource(rel))
     return null;
-  return `${member.name}/${rel}`;
+  return tagFile(member, rel);
+}
+function tagFile(member, rel) {
+  return member.selfMember ? rel : `${member.name}/${rel}`;
 }
 async function scanMemberCode(member, extraIgnore) {
   const hitsOut = [];
@@ -2710,7 +2714,7 @@ async function scanMemberCode(member, extraIgnore) {
   for (const rel of codePaths) {
     const absPath = join4(member.path, rel);
     const text = await Bun.file(absPath).text();
-    const platformRelative = `${member.name}/${rel}`;
+    const platformRelative = tagFile(member, rel);
     const hits = scanTagsInFile(member.name, platformRelative, text);
     for (const h of hits)
       hitsOut.push(h);
@@ -2724,7 +2728,7 @@ async function scanMemberDocs(member, extraIgnore) {
   for (const rel of docPaths) {
     const absPath = join4(member.path, rel);
     const text = await Bun.file(absPath).text();
-    const platformRelative = `${member.name}/${rel}`;
+    const platformRelative = tagFile(member, rel);
     const { tags, mentions } = scanDocFile(member.name, platformRelative, text);
     for (const t of tags)
       tagsOut.push(t);
@@ -3348,14 +3352,14 @@ function handleNotAPlatform(e) {
   }
   throw e;
 }
-function handleInvalidDomainFiles(e, json, code = EXIT.FAILURE) {
+async function handleInvalidDomainFiles(e, json, code = EXIT.FAILURE) {
   if (!(e instanceof InvalidDomainFilesError))
     return;
   if (json)
     console.log(renderDiagnostics(e.diagnostics, "json"));
   else
     console.error(renderDiagnostics(e.diagnostics, "text"));
-  process.exit(code);
+  await exit(code);
 }
 function cliFreshTags(platformDir) {
   const fresh = coldFreshTags(platformDir);
@@ -3363,7 +3367,7 @@ function cliFreshTags(platformDir) {
     try {
       return await fresh(reqId);
     } catch (e) {
-      handleInvalidDomainFiles(e, false, EXIT.USAGE);
+      await handleInvalidDomainFiles(e, false, EXIT.USAGE);
       throw e;
     }
   };
@@ -3405,7 +3409,7 @@ async function withReadStorage(opts, fn) {
     });
   } catch (e) {
     handleStorageUnavailable(e, dbPath);
-    handleInvalidDomainFiles(e, json);
+    await handleInvalidDomainFiles(e, json);
     handleNotAPlatform(e);
   }
 }
@@ -3414,6 +3418,7 @@ var init__shared = __esm(() => {
   init_constants();
   init_discover();
   init__index();
+  init_stdout();
   init_errors();
   init_sqlite();
 });
@@ -3719,7 +3724,7 @@ var init_commands = __esm(() => {
           console.error(formatNotASpecPlatform(err.platformDir));
           process.exit(EXIT.USAGE);
         }
-        handleInvalidDomainFiles(err, !!args.json);
+        await handleInvalidDomainFiles(err, !!args.json);
         console.error("spec index FAILED:", err);
         process.exit(EXIT.FAILURE);
       } finally {
@@ -5699,6 +5704,7 @@ var init_check2 = __esm(() => {
   init_prompt();
   init__index();
   init_check();
+  init_stdout();
   init__args();
   init__shared();
   checkCommand = defineCommand3({
@@ -5772,7 +5778,7 @@ var init_check2 = __esm(() => {
           return result;
         });
       } catch (e) {
-        handleInvalidDomainFiles(e, jsonMode);
+        await handleInvalidDomainFiles(e, jsonMode);
         exitAfterCrash(e);
       }
       if (outcome === undefined) {
@@ -5790,7 +5796,7 @@ var init_check2 = __esm(() => {
       console.log(renderDiagnostics(diagnostics2, jsonMode ? "json" : "text"));
       if (!jsonMode)
         console.log(`build_id: ${outcome.buildId}`);
-      process.exit(outcome.failing ? EXIT.FAILURE : EXIT.OK);
+      await exit(outcome.failing ? EXIT.FAILURE : EXIT.OK);
     }
   });
 });
@@ -7431,8 +7437,8 @@ async function confirmTermCommand(opts) {
     exitOnFailure("spec term confirm", result);
   await withIndex({ platformDir, build: "fresh" }, () => {
     return;
-  }).catch((e) => {
-    handleInvalidDomainFiles(e, false, EXIT.USAGE);
+  }).catch(async (e) => {
+    await handleInvalidDomainFiles(e, false, EXIT.USAGE);
     throw e;
   });
   const { pinned, file } = result;
@@ -7639,7 +7645,7 @@ async function generate(platformDir, json) {
   else
     console.log(`generated GLOSSARY.md from ${result.generated} terms`);
 }
-function check2(platformDir, json) {
+async function check2(platformDir, json) {
   if (checkGlossary(platformDir).clean) {
     if (json)
       console.log(JSON.stringify({ ok: true }));
@@ -7651,13 +7657,14 @@ function check2(platformDir, json) {
   console.error("run `spec glossary .` to regenerate the human view from the store");
   if (json)
     console.log(JSON.stringify({ ok: false }));
-  process.exit(EXIT.FAILURE);
+  await exit(EXIT.FAILURE);
 }
 var glossaryCommand;
 var init_glossary2 = __esm(() => {
   init_constants();
   init_discover();
   init_glossary();
+  init_stdout();
   init__args();
   init__shared();
   glossaryCommand = defineCommand14({
@@ -7683,7 +7690,7 @@ var init_glossary2 = __esm(() => {
       if (args.migrate)
         await migrate(platformDir, json);
       else if (args.check)
-        check2(platformDir, json);
+        await check2(platformDir, json);
       else
         await generate(platformDir, json);
     }
@@ -9395,7 +9402,7 @@ __export(exports_gate, {
 import { existsSync as existsSync13 } from "fs";
 import { join as join15 } from "path";
 import { defineCommand as defineCommand22 } from "citty";
-function isEpipe(e) {
+function isEpipe2(e) {
   if (e === null || typeof e !== "object" || !("code" in e))
     return false;
   const code = e.code;
@@ -9405,7 +9412,7 @@ function writeStdoutTolerant(line) {
   try {
     console.log(line);
   } catch (writeErr) {
-    if (!isEpipe(writeErr))
+    if (!isEpipe2(writeErr))
       throw writeErr;
   }
 }
@@ -9430,6 +9437,7 @@ var init_gate2 = __esm(() => {
   init_prompt();
   init__index();
   init_gate();
+  init_stdout();
   init__args();
   init__shared();
   gateArgs = {
@@ -9490,7 +9498,7 @@ var init_gate2 = __esm(() => {
             writeStdoutTolerant(`build_id: ${gated.buildId}`);
         }
       } catch (e) {
-        handleInvalidDomainFiles(e, Boolean(args.json));
+        await handleInvalidDomainFiles(e, Boolean(args.json));
         const msg = e instanceof Error ? e.message : String(e);
         console.error(`spec gate: crashed: ${msg}`);
         process.exit(EXIT.USAGE);
@@ -9500,7 +9508,7 @@ var init_gate2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      process.exit(gated.outcome.pass ? EXIT.OK : EXIT.FAILURE);
+      await exit(gated.outcome.pass ? EXIT.OK : EXIT.FAILURE);
     }
   });
 });
@@ -9586,6 +9594,7 @@ var guardCommand;
 var init_guard2 = __esm(() => {
   init_constants();
   init_guard();
+  init_stdout();
   init__args();
   init__shared();
   guardCommand = defineCommand23({
@@ -9611,14 +9620,14 @@ var init_guard2 = __esm(() => {
       if (!gitRefResolves(platformDir, ref)) {
         console.error(`spec guard: NOT_A_GIT_REPO \u2014 ref '${ref}' does not resolve in ${platformDir} ` + "(not a git repo, a fresh repo with no commit, or an unfetched/misspelled ref); " + "skipping loss detection");
         console.log(jsonMode ? "[]" : `\u2713 spec guard: no requirements about to be lost (non-git context)`);
-        process.exit(EXIT.OK);
+        await exit(EXIT.OK);
       }
       let losses = [];
       await withReadStorage({ platformDir, dbPath: defaultIndexPath(platformDir), fresh: true, json: jsonMode }, async (storage2) => {
         losses = (await guard(storage2, platformDir, ref)).losses;
       });
       console.log(renderGuard(losses, jsonMode ? "json" : "text", ref));
-      process.exit(losses.length > 0 ? EXIT.FAILURE : EXIT.OK);
+      await exit(losses.length > 0 ? EXIT.FAILURE : EXIT.OK);
     }
   });
 });
@@ -12901,12 +12910,12 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
     if (!featureEnabled("relations")) {
       return c.json({ error: featureDisabledMessage("relations") }, 404);
     }
-    const format = c.req.query("format");
-    if (format !== undefined && format !== "mermaid") {
+    const format2 = c.req.query("format");
+    if (format2 !== undefined && format2 !== "mermaid") {
       return c.json({ error: 'format must be "mermaid" when provided' }, 400);
     }
     const rows = relations(storage2).rows;
-    if (format === "mermaid") {
+    if (format2 === "mermaid") {
       return c.text(renderRelations(rows, "mermaid"));
     }
     return c.json(sortRelations(rows));
@@ -13161,7 +13170,7 @@ async function runProbe() {
   }
   console.log("serve --probe OK");
   server.stop();
-  process.exit(EXIT.OK);
+  await exit(EXIT.OK);
 }
 var serveCommand;
 var init_serve = __esm(() => {
@@ -13173,6 +13182,7 @@ var init_serve = __esm(() => {
   init_prompt();
   init_api();
   init_lan();
+  init_stdout();
   init_sqlite();
   init__args();
   init__shared();
@@ -13270,7 +13280,7 @@ var init_serve = __esm(() => {
         });
       } catch (err) {
         storage2.close();
-        handleInvalidDomainFiles(err, false);
+        await handleInvalidDomainFiles(err, false);
         handleStorageUnavailable(err, dbPath);
         console.error(`spec serve: failed to start on ${urlHost(host, port)}:`, err);
         process.exit(EXIT.FAILURE);
@@ -13369,7 +13379,7 @@ async function runProbe2(root) {
   }
   console.log("docs --probe OK");
   server.stop();
-  process.exit(EXIT.OK);
+  await exit(EXIT.OK);
 }
 function exitNoDocsRoot() {
   console.error("spec docs: no built documentation found. From a checkout run `bun run build:site` " + "(writes packages/site/dist); the published npm package ships it at dist/docs.");
@@ -13378,6 +13388,7 @@ function exitNoDocsRoot() {
 var docsCommand;
 var init_docs2 = __esm(() => {
   init_constants();
+  init_stdout();
   docsCommand = defineCommand25({
     meta: {
       name: "docs",
@@ -13511,7 +13522,9 @@ var init___smoke = __esm(() => {
 
 // src/cli.ts
 init_package();
+init_stdout();
 import { defineCommand as defineCommand27, runMain, showUsage } from "citty";
+routeStdout();
 var main = defineCommand27({
   meta: {
     name: "spec",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-engine/spec-engine",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Cross-repo spec engine — durable requirements with permanent IDs, bound to code via @spec tags, checked in CI. Ships the spec CLI, the local coverage webapp (spec serve), and offline docs (spec docs).",
   "license": "MIT",
   "type": "module",