forgedock 1.0.22 → 1.1.2

package/packages/protocol/src/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * forge-protocol-conformance — FORGE Annotation Protocol conformance test runner.
+ *
+ * Usage:
+ *   forge-protocol-conformance [fixtures-dir]
+ *   node src/cli.js [fixtures-dir]
+ *
+ * Reads fixtures from the given directory (default: ./fixtures/).
+ * Each fixture is a JSON file with:
+ *   {
+ *     "description": "human-readable test name",
+ *     "input": "comment body string to parse",
+ *     "expect": {
+ *       "type": "INVESTIGATOR",
+ *       "valid": true,
+ *       "sentinelState": "complete",
+ *       "inlineValue": null,
+ *       "fieldChecks": { "Verdict": "CONFIRMED" }  // optional
+ *     }
+ *   }
+ *
+ * Exit code: 0 if all fixtures pass, 1 if any fail.
+ *
+ * @license MIT
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, extname } from 'node:path';
+import { parse } from './parse.js';
+import { validate } from './validate.js';
+
+const fixturesDir = resolve(process.argv[2] ?? 'fixtures');
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+let files;
+try {
+  files = readdirSync(fixturesDir).filter(f => extname(f) === '.json').sort();
+} catch (err) {
+  console.error(`Cannot read fixtures directory: ${fixturesDir}`);
+  console.error(err.message);
+  process.exit(1);
+}
+
+if (files.length === 0) {
+  console.error(`No .json fixtures found in ${fixturesDir}`);
+  process.exit(1);
+}
+
+for (const file of files) {
+  const fixturePath = resolve(fixturesDir, file);
+  let fixture;
+  try {
+    fixture = JSON.parse(readFileSync(fixturePath, 'utf8'));
+  } catch (err) {
+    console.error(`SKIP  ${file} — cannot parse JSON: ${err.message}`);
+    continue;
+  }
+
+  const { description, input, expect: expected } = fixture;
+  const label = `${file}: ${description ?? '(no description)'}`;
+
+  if (typeof input !== 'string') {
+    console.error(`SKIP  ${label} — "input" must be a string`);
+    continue;
+  }
+
+  const annotations = parse(input);
+
+  // Find the annotation matching the expected type
+  const ann = annotations.find(a => a.type === expected.type);
+
+  const fixtureErrors = [];
+
+  if (!ann) {
+    fixtureErrors.push(`Expected annotation type "${expected.type}" not found in parsed output`);
+  } else {
+    // Sentinel state check
+    if (expected.sentinelState !== undefined && ann.sentinelState !== expected.sentinelState) {
+      fixtureErrors.push(
+        `sentinelState: expected "${expected.sentinelState}", got "${ann.sentinelState}"`,
+      );
+    }
+
+    // Inline value check
+    if ('inlineValue' in expected) {
+      if (ann.inlineValue !== expected.inlineValue) {
+        fixtureErrors.push(
+          `inlineValue: expected ${JSON.stringify(expected.inlineValue)}, got ${JSON.stringify(ann.inlineValue)}`,
+        );
+      }
+    }
+
+    // Field checks
+    if (expected.fieldChecks) {
+      for (const [key, val] of Object.entries(expected.fieldChecks)) {
+        if (ann.fields[key] !== val) {
+          fixtureErrors.push(
+            `field "${key}": expected "${val}", got "${ann.fields[key] ?? '(missing)'}"`,
+          );
+        }
+      }
+    }
+
+    // validate() result check
+    const { valid, errors } = validate(ann);
+    if (expected.valid === true && !valid) {
+      fixtureErrors.push(`Expected valid=true but got errors: ${errors.join('; ')}`);
+    } else if (expected.valid === false && valid) {
+      fixtureErrors.push(`Expected valid=false but annotation passed validation`);
+    }
+  }
+
+  if (fixtureErrors.length === 0) {
+    console.log(`ok    ${label}`);
+    passed++;
+  } else {
+    console.log(`FAIL  ${label}`);
+    for (const e of fixtureErrors) {
+      console.log(`        ${e}`);
+    }
+    failures.push(label);
+    failed++;
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed (${files.length} fixtures total)`);
+
+if (failed > 0) {
+  process.exit(1);
+}

package/packages/protocol/src/emit.js

@@ -0,0 +1,146 @@
+/**
+ * FORGE Annotation Protocol v1.0 — emitter.
+ *
+ * emit(type, fields) → well-formed annotation string
+ *
+ * Produces the canonical text for a FORGE annotation including:
+ *   - Opening tag (§3.1)
+ *   - Inline-value form (§3.4) when the type uses it
+ *   - Completion sentinel (§3.2) when the type defines one
+ *
+ * @license MIT
+ */
+
+import { RESERVED_TYPES, RESERVED_TYPE_NAMES } from './types.js';
+
+// A folded field/inline value that is itself (whole, trimmed) shaped like a FORGE
+// opening tag or a generic sentinel line has no legitimate reason to look that way —
+// parse()'s line-anchored matching (see parse.js OPENING_TAG_RE / resolveSentinelState)
+// treats any line matching this shape as live protocol structure. Untrusted text
+// (issue titles, branch names, freeform error/output strings) flowing into emit()
+// must never be able to forge one. (forge#1594)
+const FORGE_TAG_LINE_RE =
+  /^\s*<!--\s*(?:FORGE:[A-Z_]+(?::.*)?|[A-Z_][A-Z_:]*:(?:COMPLETE|PARTIAL))\s*-->\s*$/;
+
+// Newline variants that would let a value spill onto its own line(s).
+const NEWLINE_RE = /\r\n|\r|\n/g;
+
+/**
+ * Sanitize a value before it is serialized into a `**Key**: value` field line or
+ * an inline-value tag. Two independent protections:
+ *
+ *   1. Newlines are folded to a single space so a multi-line value can never
+ *      produce a new line of its own — every real FORGE tag (opening tag,
+ *      sentinel, control marker) occupies a whole line, so folding denies an
+ *      injected value the only shape parse() treats as structural.
+ *   2. HTML comment delimiters (`<!--`, `-->`, and `--!>`) are escaped so a
+ *      value can never open a new unterminated HTML comment or prematurely close
+ *      the enclosing `<!-- ... -->` comment — GitHub's renderer treats a literal
+ *      `<!--` as the start of a new (nested-looking) comment, visually swallowing
+ *      subsequent lines including the completion sentinel, and treats a literal
+ *      `-->` as ending the enclosing comment early, leaking the remainder as
+ *      visible rendered text. Both directions of the delimiter pair must be
+ *      escaped. (forge#1594, forge#1638)
+ *
+ * As defense in depth, if a value still folds down to a line that is itself a
+ * bare FORGE tag/sentinel shape, emit() rejects it outright rather than silently
+ * emitting something a parser could mistake for real protocol structure.
+ *
+ * @param {*} rawValue
+ * @returns {string}
+ */
+function sanitizeFieldValue(rawValue) {
+  const folded = String(rawValue).replace(NEWLINE_RE, ' ');
+  if (FORGE_TAG_LINE_RE.test(folded.trim())) {
+    throw new TypeError(
+      `emit(): field value resolves to a bare FORGE tag/sentinel line, which is not permitted: ${JSON.stringify(rawValue)}`,
+    );
+  }
+  // Escape the HTML comment opener ("<!--") so a value cannot start a new
+  // unterminated HTML comment in GitHub's renderer, which would visually swallow
+  // subsequent lines — the same rendering-leak the closer escaping below prevents
+  // from the opposite direction. (forge#1638)
+  const withOpenerEscaped = folded.replace(/<!--/g, '&lt;!--');
+  // Escape both HTML comment-close forms ("-->" and "--!>") — only replacing the
+  // literal character sequence (not just documenting the risk) prevents the
+  // enclosing comment from terminating early. (forge#1594; noted but never fixed
+  // for the FORGE:STATE codec in bin/engine/state.mjs — see issue investigation)
+  return withOpenerEscaped.replace(/--(!)?>/g, (_, bang) => `--${bang || ''}&gt;`);
+}
+
+/**
+ * Emit a well-formed FORGE annotation string.
+ *
+ * @param {string} type  - Annotation type (e.g. "INVESTIGATOR", "KNOWLEDGE_GIST")
+ * @param {Object} [fields={}]  - Key/value pairs to include as **Key**: value lines,
+ *   OR for inline-value types, pass { value: 'https://...' }
+ * @returns {string}
+ */
+export function emit(type, fields = {}) {
+  if (typeof type !== 'string' || !type) {
+    throw new TypeError('emit() requires a non-empty type string');
+  }
+
+  const upperType = type.toUpperCase();
+  const typeDef = RESERVED_TYPES[upperType];
+
+  // Inline-value form (§3.4)
+  if (typeDef?.inlineValue) {
+    const value = fields.value ?? '';
+    return `<!-- FORGE:${upperType}: ${sanitizeFieldValue(value)} -->`;
+  }
+
+  // Control marker form (§4.3) — just the tag, no body
+  if (typeDef?.controlMarker) {
+    return `<!-- FORGE:${upperType} -->`;
+  }
+
+  // Full annotation form
+  const lines = [`<!-- FORGE:${upperType} -->`];
+
+  // Emit each field as a **Key**: value line
+  // Both key and val are sanitized — a partial-sanitization hole where only the
+  // value was sanitized was identified in forge#1637. Keys can carry the same
+  // newline / comment-terminator injection vectors as values.
+  const fieldEntries = Object.entries(fields);
+  if (fieldEntries.length > 0) {
+    for (const [key, val] of fieldEntries) {
+      lines.push(`**${sanitizeFieldValue(key)}**: ${sanitizeFieldValue(val)}`);
+    }
+  }
+
+  // Completion sentinel (§3.2)
+  if (typeDef?.completionSentinel) {
+    lines.push(`<!-- ${typeDef.completionSentinel} -->`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Emit a partial sentinel for an annotation that was interrupted.
+ * Spec §3.3: producers MAY mark interrupted annotations partial.
+ *
+ * @param {string} type
+ * @returns {string}
+ */
+export function emitPartial(type) {
+  const upperType = type.toUpperCase();
+  const typeDef = RESERVED_TYPES[upperType];
+
+  if (typeDef?.partialSentinel) {
+    return `<!-- ${typeDef.partialSentinel} -->`;
+  }
+  // Fallback generic form
+  return `<!-- ${upperType}:PARTIAL -->`;
+}
+
+/**
+ * Check if a type is known/reserved.
+ *
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function isKnownType(type) {
+  return RESERVED_TYPE_NAMES.has(typeof type === 'string' ? type.toUpperCase() : type);
+}

package/packages/protocol/src/index.js

@@ -0,0 +1,43 @@
+/**
+ * @forgedock/protocol — FORGE Annotation Protocol v1.0 reference implementation.
+ *
+ * Provides parse, validate, and emit for all 13 reserved annotation types
+ * defined in the FORGE Annotation Protocol specification (CC-BY-4.0).
+ *
+ * @example
+ * import { parse, validate, emit } from '@forgedock/protocol';
+ *
+ * // Parse annotations from a GitHub issue/PR comment body
+ * const annotations = parse(commentBody);
+ *
+ * // Validate a parsed annotation
+ * const { valid, errors } = validate(annotations[0]);
+ *
+ * // Emit a well-formed annotation string
+ * const text = emit('INVESTIGATOR', {
+ *   Verdict: 'CONFIRMED',
+ *   Confidence: 'HIGH',
+ *   Severity: 'MEDIUM',
+ *   'Task Type': 'Bug Fix',
+ *   'Decomposition Assessment': 'NO — single-file fix',
+ * });
+ *
+ * @license MIT
+ */
+
+export { parse } from './parse.js';
+export { validate } from './validate.js';
+export { emit, emitPartial, isKnownType } from './emit.js';
+export { RESERVED_TYPES, RESERVED_TYPE_NAMES, Category, SentinelState } from './types.js';
+
+/**
+ * @typedef {Object} ParsedAnnotation
+ * @property {string} type - Annotation type identifier (e.g. "INVESTIGATOR")
+ * @property {string} raw - Full annotation text including opening tag
+ * @property {string} body - Markdown body (lines after opening tag)
+ * @property {string|null} inlineValue - Value for inline-value form, null otherwise
+ * @property {import('./types.js').SentinelState} sentinelState - complete/partial/interrupted
+ * @property {boolean} isReserved - True if type is in the reserved set
+ * @property {boolean} isControl - True if type is a control/error marker
+ * @property {Object.<string,string>} fields - Extracted **Key**: value pairs
+ */

package/packages/protocol/src/parse.js

@@ -0,0 +1,229 @@
+/**
+ * FORGE Annotation Protocol v1.0 — parser.
+ *
+ * parse(commentBody) → Array<ParsedAnnotation>
+ *
+ * Each ParsedAnnotation has:
+ *   type        {string}   annotation type identifier (e.g. "INVESTIGATOR")
+ *   raw         {string}   the full text of the annotation (opening tag + body)
+ *   body        {string}   Markdown body (everything after the opening tag line)
+ *   inlineValue {string|null}  value for inline-value form (§3.4), null otherwise
+ *   sentinelState {SentinelState}  complete / partial / interrupted
+ *   isReserved  {boolean}  true if type is in the reserved set (§4)
+ *   isControl   {boolean}  true if type is a control/error marker (§4.3)
+ *   fields      {Object}   key/value pairs extracted from bold-header lines
+ *
+ * @license MIT
+ */
+
+import { RESERVED_TYPES, RESERVED_TYPE_NAMES, SentinelState } from './types.js';
+
+// Matches: <!-- FORGE:TYPE --> or <!-- FORGE:TYPE: value -->
+// Anchored to require the tag to be the ENTIRE (trimmed) line — a FORGE-tag-shaped
+// substring embedded inside other line content (e.g. a **Commits**: field value that
+// happens to mention a FORGE tag) is never a structural annotation opener. Every real
+// FORGE tag emission (opening tags and sentinel markers alike) occupies its own line;
+// this anchor makes "is the whole line" the structural test instead of a bare substring
+// search, which previously let field-value text split/corrupt annotations. (forge#1524)
+const OPENING_TAG_RE = /^\s*<!--\s*FORGE:([A-Z_]+)(?::\s*(.*?))?\s*-->\s*$/;
+
+// Sentinel suffixes that appear as inline-values in tags that look like opening tags
+// but are actually completion/partial markers, e.g. <!-- FORGE:CONTEXT:COMPLETE -->
+const SENTINEL_SUFFIXES = new Set(['COMPLETE', 'PARTIAL']);
+
+// Matches bold-key lines: **Key**: value  (used for field extraction)
+const BOLD_FIELD_RE = /^\*\*([^*]+)\*\*\s*:\s*(.+)$/;
+
+// Generic (unknown-type) sentinel patterns, anchored to a whole line — see
+// resolveSentinelState() below for why anchoring matters. (forge#1594)
+const GENERIC_COMPLETE_RE = /^\s*<!--\s*[A-Z_:]+:COMPLETE\s*-->\s*$/m;
+const GENERIC_PARTIAL_RE = /^\s*<!--\s*[A-Z_:]+:PARTIAL\s*-->\s*$/m;
+
+/**
+ * Determine sentinel state for an annotation body given its type definition.
+ *
+ * @param {string} body
+ * @param {object|undefined} typeDef
+ * @returns {SentinelState}
+ */
+function resolveSentinelState(body, typeDef) {
+  if (!typeDef) {
+    // Unknown type — look for generic sentinel patterns. Anchored to require the
+    // sentinel to occupy its own (trimmed) line — the same structural test as
+    // OPENING_TAG_RE above. A field value that merely *mentions* sentinel-shaped
+    // text (e.g. **Commits**: ... <!-- FORGE:BUILDER:COMPLETE -->) must not be
+    // able to spoof completion; only a sentinel on its own line is real. (forge#1594)
+    if (GENERIC_COMPLETE_RE.test(body)) return SentinelState.COMPLETE;
+    if (GENERIC_PARTIAL_RE.test(body)) return SentinelState.PARTIAL;
+    return SentinelState.INTERRUPTED;
+  }
+
+  if (typeDef.controlMarker) {
+    // Control markers carry no body; their presence is the signal — treat as complete
+    return SentinelState.COMPLETE;
+  }
+
+  if (!typeDef.completionSentinel) {
+    // Types without a defined sentinel (CONTRACT, REVIEWER, TRAJECTORY) are
+    // always treated as complete once they exist — there is no incompleteness signal.
+    return SentinelState.COMPLETE;
+  }
+
+  // Anchored to a whole line (with the `m` flag so `^`/`$` match at every line
+  // boundary within body, not just start/end of the whole string) — a real
+  // sentinel always occupies its own line (see emit.js, which always emits it
+  // that way). This is the sentinel-detection mirror of the OPENING_TAG_RE
+  // anchor above: an unanchored substring test previously let a field value
+  // that merely *contains* the sentinel text (e.g. a **Commits** message quoting
+  // it) spoof completion for an annotation that was never actually completed.
+  // (forge#1594 — inverse of the #1524 opening-tag anchor gap)
+  const completionPattern = new RegExp(
+    `^\\s*<!--\\s*${escapeRegExp(typeDef.completionSentinel)}\\s*-->\\s*$`,
+    'm',
+  );
+  if (completionPattern.test(body)) return SentinelState.COMPLETE;
+
+  if (typeDef.partialSentinel) {
+    const partialPattern = new RegExp(
+      `^\\s*<!--\\s*${escapeRegExp(typeDef.partialSentinel)}\\s*-->\\s*$`,
+      'm',
+    );
+    if (partialPattern.test(body)) return SentinelState.PARTIAL;
+  }
+
+  return SentinelState.INTERRUPTED;
+}
+
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Extract **Key**: value fields from an annotation body.
+ *
+ * @param {string} body
+ * @returns {Object.<string,string>}
+ */
+function extractFields(body) {
+  const fields = {};
+  for (const line of body.split('\n')) {
+    const m = line.trim().match(BOLD_FIELD_RE);
+    if (m) {
+      fields[m[1].trim()] = m[2].trim();
+    }
+  }
+  return fields;
+}
+
+/**
+ * Parse all FORGE annotations from a comment body.
+ *
+ * Spec §3.1: an annotation ends at the next <!-- FORGE: tag or end of comment.
+ * Spec §3.4: inline-value form — value is extracted directly from the tag.
+ * Spec §7.2.4: unknown types are tolerated; never throw on them.
+ *
+ * @param {string} commentBody
+ * @returns {Array<import('./index.js').ParsedAnnotation>}
+ */
+export function parse(commentBody) {
+  if (typeof commentBody !== 'string') {
+    throw new TypeError(`parse() expects a string, got ${typeof commentBody}`);
+  }
+
+  const lines = commentBody.split('\n');
+  const annotations = [];
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const tagMatch = line.match(OPENING_TAG_RE);
+
+    if (!tagMatch) {
+      i++;
+      continue;
+    }
+
+    const type = tagMatch[1];
+    const rawInlineValue = tagMatch[2] !== undefined ? tagMatch[2].trim() : null;
+    const typeDefForTag = RESERVED_TYPES[type];
+
+    // Sentinel lines like <!-- FORGE:CONTEXT:COMPLETE --> match the opening tag regex
+    // because the regex captures "CONTEXT" as type and "COMPLETE" as inlineValue.
+    // These are NOT new annotations — they are closing markers and must stay in
+    // the preceding annotation's body. The inner body-accumulation loop handles
+    // this by including such lines rather than breaking on them. However, if a
+    // sentinel line appears at the very beginning (before any annotation), skip it.
+    //
+    // Exception: types that declare inlineValue: true (KNOWLEDGE_GIST, MILESTONE_INDEX,
+    // PRIOR_GIST) use COMPLETE/PARTIAL as legitimate inline values, not sentinel markers
+    // — e.g. <!-- FORGE:PRIOR_GIST: COMPLETE --> is a real annotation whose value is the
+    // string "COMPLETE". Only guess "sentinel" for types that don't use inline-value form
+    // (typeDefForTag?.inlineValue is false/undefined for all of those, including unknown
+    // types where typeDefForTag itself is undefined). (forge#1526)
+    if (
+      rawInlineValue !== null &&
+      SENTINEL_SUFFIXES.has(rawInlineValue) &&
+      !typeDefForTag?.inlineValue
+    ) {
+      i++;
+      continue;
+    }
+
+    const inlineValue = rawInlineValue;
+    const typeDef = typeDefForTag;
+    const isControl = typeDef?.controlMarker === true;
+    const isReserved = RESERVED_TYPE_NAMES.has(type);
+
+    // Collect body lines until the next true annotation opening tag or end of comment.
+    // Sentinel lines like <!-- FORGE:CONTEXT:COMPLETE --> match OPENING_TAG_RE but are
+    // closing markers, not new annotation openings — include them in the body.
+    const bodyLines = [];
+    let j = i + 1;
+    while (j < lines.length) {
+      const bodyLineMatch = lines[j].match(OPENING_TAG_RE);
+      if (bodyLineMatch) {
+        const bodyLineType = bodyLineMatch[1];
+        const bodyLineInlineValue = bodyLineMatch[2] !== undefined ? bodyLineMatch[2].trim() : null;
+        const bodyLineTypeDef = RESERVED_TYPES[bodyLineType];
+        // Sentinel-like tags (COMPLETE/PARTIAL inline value) → include in body, don't break.
+        // Exception: if bodyLineType is an inline-value type (KNOWLEDGE_GIST, MILESTONE_INDEX,
+        // PRIOR_GIST), COMPLETE/PARTIAL is a genuine inline value for a NEW annotation, not a
+        // sentinel — fall through to "True opening tag" below so it starts its own annotation
+        // instead of being folded into the preceding one's body. (forge#1526)
+        if (
+          bodyLineInlineValue !== null &&
+          SENTINEL_SUFFIXES.has(bodyLineInlineValue) &&
+          !bodyLineTypeDef?.inlineValue
+        ) {
+          bodyLines.push(lines[j]);
+          j++;
+          continue;
+        }
+        // True opening tag → end this annotation's body
+        break;
+      }
+      bodyLines.push(lines[j]);
+      j++;
+    }
+
+    const body = bodyLines.join('\n');
+    const raw = line + (body.length > 0 ? '\n' + body : '');
+    const sentinelState = resolveSentinelState(body, typeDef);
+    const fields = inlineValue !== null ? {} : extractFields(body);
+
+    annotations.push({
+      type,
+      raw,
+      body,
+      inlineValue,
+      sentinelState,
+      isReserved,
+      isControl,
+      fields,
+    });
+
+    i = j;
+  }
+
+  return annotations;
+}