@rqml/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { __commonJS, __toESM } from './chunk-5WRI5ZAA.js';
+import { createRequire } from 'module';
 import { createHash } from 'crypto';
 import { writeFileSync, existsSync, readFileSync, mkdirSync, statSync, readdirSync } from 'fs';
 import { resolve, join, dirname, isAbsolute } from 'path';
@@ -3372,6 +3373,86 @@ ${sectionIndent}</trace>
   }
   return { ok: true, xml: updated, edgeId, edgeXml: edgeXml.trim() };
 }
+function escapeRegExp2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var EXTERNAL_ELEMENT = /<external\b[^>]*(?:\/>|>[\s\S]*?<\/external>)/g;
+function updateTraceEdge(xml, request) {
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    return { ok: false, error: `document does not parse: ${parsed.error.message}` };
+  }
+  if (request.uri.trim() === "") {
+    return { ok: false, error: "locator uri must not be empty" };
+  }
+  const prefix = request.type === "implements" ? "E-IMPL-" : "E-VER-";
+  const edgeId = request.edgeId ?? prefix + request.artifactId.replace(/^REQ-/, "");
+  const edge = parsed.document.trace.find((e) => e.id === edgeId);
+  if (edge === void 0) {
+    return {
+      ok: false,
+      error: request.edgeId !== void 0 ? `no trace edge with id "${edgeId}" exists` : `no trace edge with the derived id "${edgeId}" exists; pass --id for an explicitly named edge`
+    };
+  }
+  if (edge.type !== request.type) {
+    return {
+      ok: false,
+      error: `edge "${edgeId}" has type "${edge.type}", not "${request.type}"`
+    };
+  }
+  const local = edge.from.kind === "local" ? edge.from : edge.to.kind === "local" ? edge.to : void 0;
+  if (local === void 0 || local.id !== request.artifactId) {
+    return {
+      ok: false,
+      error: `edge "${edgeId}" does not link artifact "${request.artifactId}"`
+    };
+  }
+  const external = edge.from.kind === "external" ? edge.from : edge.to.kind === "external" ? edge.to : void 0;
+  if (external === void 0) {
+    return { ok: false, error: `edge "${edgeId}" has no external locator to update` };
+  }
+  const openTag = new RegExp(`<edge\\b[^>]*\\bid="${escapeRegExp2(edgeId)}"[^>]*>`);
+  const open = openTag.exec(xml);
+  const closeIdx = open === null ? -1 : xml.indexOf("</edge>", open.index);
+  if (open === null || closeIdx < 0) {
+    return { ok: false, error: `could not locate edge "${edgeId}" in the document text` };
+  }
+  const span = xml.slice(open.index, closeIdx);
+  const occurrences = span.match(EXTERNAL_ELEMENT) ?? [];
+  if (occurrences.length !== 1) {
+    return {
+      ok: false,
+      error: `edge "${edgeId}" does not contain exactly one external locator element`
+    };
+  }
+  const kind = request.kind ?? external.hintKind ?? (request.type === "implements" ? "code" : "test");
+  const title = request.title ?? external.title;
+  const titleAttr = title !== void 0 ? ` title="${escapeAttr(title)}"` : "";
+  const replacement = `<external uri="${escapeAttr(request.uri)}" kind="${escapeAttr(kind)}"${titleAttr}/>`;
+  const editedSpan = span.replace(occurrences[0], () => replacement);
+  const updated = xml.slice(0, open.index) + editedSpan + xml.slice(closeIdx);
+  const before = checkIntegrity(xml).length;
+  const reparsed = parse(updated);
+  if (!reparsed.ok) {
+    return {
+      ok: false,
+      error: `edit produced an unparseable document: ${reparsed.error.message}`
+    };
+  }
+  if (checkIntegrity(updated).length > before) {
+    return {
+      ok: false,
+      error: "edit introduced an integrity violation; document left unchanged"
+    };
+  }
+  return {
+    ok: true,
+    xml: updated,
+    edgeId,
+    edgeXml: `${editedSpan}</edge>`.trim(),
+    previousUri: external.uri
+  };
+}
 function endpointKey2(locator) {
   return locator.kind === "local" ? locator.id : locator.uri;
 }
@@ -4053,15 +4134,21 @@ async function runInit(rest) {
   if (!wrote) process.stdout.write("nothing to do; project already initialized\n");
   return EXIT.OK;
 }
-var USAGE = "usage: rqml link <artifact-id> <uri> [--type implements|verifiedBy] [--id <edge-id>] [--kind <k>] [--title <t>] [--spec <path>]";
+var USAGE = "usage: rqml link <artifact-id> <uri> [--update] [--type implements|verifiedBy] [--id <edge-id>] [--kind <k>] [--title <t>] [--spec <path>]\n       rqml link --refresh <edge-id> [--spec <path>]";
 async function runLink(rest) {
   const args = parseArgs(rest);
+  if (args.flags.has("refresh")) {
+    const edgeId2 = flagString(args, "refresh");
+    if (edgeId2 === void 0) throw new UsageError(USAGE);
+    return runRefresh(args, edgeId2);
+  }
   const [artifactId, uri] = args.positionals;
   if (artifactId === void 0 || uri === void 0) throw new UsageError(USAGE);
   const type = flagString(args, "type") ?? "implements";
   if (type !== "implements" && type !== "verifiedBy") {
     throw new UsageError(`unknown link type "${type}" (implements|verifiedBy)`);
   }
+  const update = args.flags.get("update") === true || args.flags.get("update") === "true";
   const { path, xml } = readSpec(specArgs(args));
   const request = { artifactId, uri, type };
   const edgeId = flagString(args, "id");
@@ -4070,7 +4157,7 @@ async function runLink(rest) {
   if (kind !== void 0) request.kind = kind;
   const title = flagString(args, "title");
   if (title !== void 0) request.title = title;
-  const result = appendTraceEdge(xml, request);
+  const result = update ? updateTraceEdge(xml, request) : appendTraceEdge(xml, request);
   if (!result.ok) {
     process.stderr.write(`\u2717 link failed: ${result.error}
 `);
@@ -4099,6 +4186,7 @@ async function runLink(rest) {
   if (args.json) {
     const report = {
       spec: path,
+      mode: update ? "update" : "append",
       edgeId: result.edgeId,
       type,
       artifactId,
@@ -4109,14 +4197,52 @@ async function runLink(rest) {
 `);
   } else {
     const arrow = type === "implements" ? "\u2190" : "\u2192";
+    const mode = update ? ", updated" : "";
     const baseline = baselineRecorded ? ", baseline recorded" : "";
     process.stdout.write(
-      `\u2713 ${artifactId} ${arrow} ${uri} (${result.edgeId}, ${type}${baseline})
+      `\u2713 ${artifactId} ${arrow} ${uri} (${result.edgeId}, ${type}${mode}${baseline})
 `
     );
   }
   return EXIT.OK;
 }
+function runRefresh(args, edgeId) {
+  const { path, xml } = readSpec(specArgs(args));
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    process.stderr.write(`\u2717 refresh failed: ${parsed.error.message}
+`);
+    return EXIT.VALIDATION;
+  }
+  const link = implementsLinks(parsed.document).find((l) => l.edgeId === edgeId);
+  if (link === void 0) {
+    process.stderr.write(
+      `\u2717 refresh failed: no implements edge "${edgeId}" with an external locator exists (only implements edges carry baselines)
+`
+    );
+    return EXIT.VALIDATION;
+  }
+  const hash = computeBaseline(parsed.document, { baseDir: args.baseDir })[edgeId];
+  if (hash === void 0) {
+    process.stderr.write(
+      `\u2717 refresh failed: "${link.uri}" cannot be hashed (missing file or non-filesystem URI)
+`
+    );
+    return EXIT.VALIDATION;
+  }
+  const baseline = loadBaseline(args.baseDir) ?? {};
+  baseline[edgeId] = hash;
+  saveBaseline(args.baseDir, baseline);
+  if (args.json) {
+    const report = { spec: path, mode: "refresh", edgeId, uri: link.uri, hash };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+  } else {
+    process.stdout.write(`\u2713 baseline refreshed for ${edgeId} (${link.uri})
+`);
+  }
+  return EXIT.OK;
+}
 
 // src/commands/show.ts
 async function runShow(rest) {
@@ -4234,7 +4360,7 @@ async function runValidate(rest) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = createRequire(import.meta.url)("../package.json").version;
 var HELP = `rqml \u2014 RQML reference CLI (v${VERSION})
 
 Usage:
@@ -4246,6 +4372,8 @@ Commands:
   status [path]      Show spec, coverage, and lint summary
   check [path]       Deterministic enforcement gate (validation + coverage + drift)
   link <id> <uri>    Record an implements/verifiedBy edge and its drift baseline
+                     (--update repoints an existing edge; --refresh <edge-id>
+                     re-records only the baseline for an intentional change)
   show <id>          Extract one artifact with its trace neighborhood
   impact <id>        What is affected, transitively, if this artifact changes
   skeleton <kind>    Print a schema-valid snippet (req|edge|testCase|stateMachine)
@@ -4259,6 +4387,8 @@ Options:
   --id <id>              Explicit edge id (link) or skeleton root id
   --kind <kind>          Locator kind hint for link (default: code/test by type)
   --title <title>        Locator title hint for link
+  --update               Replace the external locator of an existing edge (link)
+  --refresh <edge-id>    Re-record the drift baseline for one edge (link)
   -h, --help             Show this help
   -v, --version          Show version