trackfw 6.9.1 → 7.0.0

package/src/ship/runner.js

@@ -28,11 +28,26 @@ function isGitWriteCmd(args) {
 }
 
 /**
- * isShipBranch returns true when branch matches feat|fix|refactor/<slug>.
+ * isShipBranch returns true when branch matches feat|fix|refactor|chore|docs/<slug> — the full
+ * vocabulary `trackfw ship` accepts on the branch name. feat/fix/refactor are gated on Step 2's
+ * branch_has_wip_roadmap governance check (a hard gate not affected by lenient mode); chore/docs
+ * are housekeeping types — already exempted from that gate by `trackfw branch new` and
+ * `trackfw commit` — and ship without it too.
  * @param {string} branch
  * @returns {boolean}
  */
 function isShipBranch(branch) {
+  return /^(feat|fix|refactor|chore|docs)\/.+/.test(branch)
+}
+
+/**
+ * isGatedShipBranch returns true when branch matches feat|fix|refactor/<slug> — the subset of
+ * isShipBranch's vocabulary that requires Step 2's branch_has_wip_roadmap governance check.
+ * chore/docs branches satisfy isShipBranch but return false here.
+ * @param {string} branch
+ * @returns {boolean}
+ */
+function isGatedShipBranch(branch) {
   return /^(feat|fix|refactor)\/.+/.test(branch)
 }
 
@@ -78,8 +93,10 @@ function checkShipGovernance() {
   const branchResult = defaultExecGit(['symbolic-ref', '--short', 'HEAD'])
   const branch = branchResult.error ? '' : branchResult.stdout.trim()
 
-  // Check branch has matching roadmap in wip/
-  if (branch && isShipBranch(branch)) {
+  // Check branch has matching roadmap in wip/ — gated types only (feat/fix/refactor); chore/docs
+  // are exempted by the outer runShip Step 2 skip and never reach this function in practice, but
+  // isGatedShipBranch keeps this check correct in isolation too.
+  if (branch && isGatedShipBranch(branch)) {
     const slug = normalizeBranchSlug(branch.split('/').slice(1).join('/'))
     let hasMatch = false
     let wipFiles = []
@@ -217,6 +234,137 @@ function firstLine(s) {
   return idx >= 0 ? s.slice(0, idx) : s
 }
 
+/**
+ * splitNonEmptyLines splits git output (e.g. `diff --cached --name-only`) into an array
+ * of trimmed, non-empty lines.
+ * @param {string} s
+ * @returns {string[]}
+ */
+function splitNonEmptyLines(s) {
+  const trimmed = (s || '').trim()
+  if (!trimmed) return []
+  return trimmed
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+}
+
+/**
+ * allDocOnly returns true when there is at least one staged file and every staged file is
+ * doc-only: under docs/ or vault/ (path prefix), or has a .md extension. A single file
+ * outside that criterion makes it return false. Mirrors the doc-only exception documented
+ * in CLAUDE.md §7 ("Alteração doc-only (markdown, comentários)").
+ * @param {string[]} files
+ * @returns {boolean}
+ */
+function allDocOnly(files) {
+  if (!files || files.length === 0) return false
+  for (const f of files) {
+    if (f.startsWith('docs/') || f.startsWith('vault/') || f.endsWith('.md')) continue
+    return false
+  }
+  return true
+}
+
+/**
+ * commitMessageSep delimits full commit messages (%B) in the output of gitCommitsSince's
+ * `git log --format=%B<sep>`. Same non-printable separator used by the Go implementation
+ * (internal/commands/ship.go) — cannot appear in a real commit message.
+ */
+const COMMIT_MESSAGE_SEP = '\x1e'
+
+/**
+ * defaultBaseBranch resolves the repository's default branch for `git log <base>..HEAD`.
+ * Tries `git symbolic-ref refs/remotes/origin/HEAD` (format "refs/remotes/origin/main" —
+ * only the name after the last slash is kept) and falls back to "main" when that fails or
+ * yields nothing.
+ * @param {function} execGit
+ * @returns {string}
+ */
+function defaultBaseBranch(execGit) {
+  const { stdout, error } = execGit(['symbolic-ref', 'refs/remotes/origin/HEAD'])
+  if (error) return 'main'
+  const out = (stdout || '').trim()
+  const idx = out.lastIndexOf('/')
+  if (idx < 0 || idx + 1 >= out.length) return 'main'
+  return out.slice(idx + 1)
+}
+
+/**
+ * gitCommitsSince returns the full message (subject + body) of every non-merge commit in
+ * base..HEAD, most-recent-first (git log's natural order). Returns [] on any git error or
+ * when the range is empty.
+ * @param {string} base
+ * @param {function} execGit
+ * @returns {string[]}
+ */
+function gitCommitsSince(base, execGit) {
+  const { stdout, error } = execGit(['log', `${base}..HEAD`, '--no-merges', `--format=%B${COMMIT_MESSAGE_SEP}`])
+  if (error) return []
+  const out = (stdout || '').trim()
+  if (!out) return []
+  const parts = out.split(COMMIT_MESSAGE_SEP)
+  const commits = []
+  for (let p of parts) {
+    p = p.replace(/^\n+|\n+$/g, '')
+    if (p.trim() === '') continue
+    commits.push(p)
+  }
+  return commits
+}
+
+/**
+ * buildPRBody constructs the PR/MR body. With 0 or 1 non-merge commit on the branch (the
+ * trivial case — just the commit `ship` itself made), it keeps the original minimal body,
+ * not a regression. With 2+ commits, it aggregates the branch's commit history:
+ *
+ *   ## Commits
+ *   - <subject of commit 1>
+ *   - <subject of commit 2>
+ *
+ *   ## Detalhes
+ *   <full body of each commit that has one, in blocks>
+ *
+ *   ---
+ *   Branch: <branch>
+ *
+ * @param {string} branch
+ * @param {string[]} commits
+ * @returns {string}
+ */
+function buildPRBody(branch, commits) {
+  if (!commits || commits.length <= 1) {
+    return `Branch: ${branch}\n\nCreated by trackfw ship.`
+  }
+
+  const subjects = []
+  const details = []
+  for (const c of commits) {
+    const nlIdx = c.indexOf('\n')
+    const subject = (nlIdx >= 0 ? c.slice(0, nlIdx) : c).trim()
+    if (subject === '') continue
+    subjects.push(subject)
+    if (nlIdx >= 0) {
+      const bodyText = c.slice(nlIdx + 1).trim()
+      if (bodyText !== '') {
+        details.push(`**${subject}**\n\n${bodyText}`)
+      }
+    }
+  }
+
+  let b = '## Commits\n\n'
+  for (const s of subjects) {
+    b += `- ${s}\n`
+  }
+  if (details.length > 0) {
+    b += '\n## Detalhes\n\n'
+    b += details.join('\n\n')
+    b += '\n'
+  }
+  b += `\n---\nBranch: ${branch}\n`
+  return b
+}
+
 /**
  * buildForgeCreateArgs appends --title and --body (or --description for azure)
  * to a copy of adapter.cliArgs. Never mutates the original array.
@@ -258,6 +406,13 @@ function runShip(opts, deps = {}) {
     return execGit(args)
   }
 
+  // ─── Step 0: staged files ───────────────────────────────────────────────────
+  // Read once, up front, so Steps 1 and 2 can grant a doc-only exception before they run —
+  // and so Step 4 below reuses the same read instead of querying git twice.
+  const { stdout: stagedOut } = execGit(['diff', '--cached', '--name-only'])
+  const stagedFiles = splitNonEmptyLines(stagedOut)
+  const docOnly = allDocOnly(stagedFiles)
+
   // ─── Step 1: Branch validation ─────────────────────────────────────────────
   const branchResult = execGit(['symbolic-ref', '--short', 'HEAD'])
   if (branchResult.error) {
@@ -266,14 +421,15 @@ function runShip(opts, deps = {}) {
   }
   const branch = branchResult.stdout.trim()
 
+  // main/master is blocked unconditionally — the doc-only exception never applies here.
   if (branch === 'main' || branch === 'master') {
     writeln(`error: trackfw ship cannot run on "${branch}" — use a feature branch:\n  git checkout -b feat/<slug>`)
     return 1
   }
 
-  if (!isShipBranch(branch)) {
+  if (!docOnly && !isShipBranch(branch)) {
     writeln(
-      `error: branch "${branch}" does not match the required pattern feat|fix|refactor/<slug>\n` +
+      `error: branch "${branch}" does not match the required pattern feat|fix|refactor|chore|docs/<slug>\n` +
       'Rename your branch or create a new one:\n  git checkout -b feat/<slug>'
     )
     return 1
@@ -282,25 +438,35 @@ function runShip(opts, deps = {}) {
   writeln(`Branch: ${branch}`)
 
   // ─── Step 2: Governance ────────────────────────────────────────────────────
-  const violations = checkGovernanceFn()
-  if (violations.length > 0) {
-    writeln('\nGovernance check failed:')
-    for (const v of violations) {
-      writeln(`  ${v}`)
+  // Doc-only changes (all staged files under docs/, vault/, or *.md) are exempt from
+  // REQ+roadmap governance — mirrors the CLAUDE.md §7 exception for doc-only changes.
+  if (docOnly) {
+    writeln('Governance: skipped (doc-only change)')
+  } else if (isShipBranch(branch) && !isGatedShipBranch(branch)) {
+    // chore/docs: housekeeping types already exempted from this gate by
+    // `trackfw branch new` and `trackfw commit` — ship without it too.
+    writeln('Governance: skipped (chore/docs branch)')
+  } else {
+    const violations = checkGovernanceFn()
+    if (violations.length > 0) {
+      writeln('\nGovernance check failed:')
+      for (const v of violations) {
+        writeln(`  ${v}`)
+      }
+      writeln('\nCreate the required artifacts before running ship:')
+      writeln('  trackfw req new "<title>"')
+      writeln('  trackfw roadmap new "<title>"')
+      writeln('  trackfw roadmap move <name> wip')
+      writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
+      writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")
+      writeln("passes but 'trackfw ship' aborts here, you likely have lenient mode")
+      writeln("configured — ship always requires REQ + roadmap in wip/.")
+      writeln(`\nerror: governance check failed: ${violations.length} violation(s)`)
+      return 1
     }
-    writeln('\nCreate the required artifacts before running ship:')
-    writeln('  trackfw req new "<title>"')
-    writeln('  trackfw roadmap new "<title>"')
-    writeln('  trackfw roadmap move <name> wip')
-    writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
-    writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")
-    writeln("passes but 'trackfw ship' aborts here, you likely have lenient mode")
-    writeln("configured — ship always requires REQ + roadmap in wip/.")
-    writeln(`\nerror: governance check failed: ${violations.length} violation(s)`)
-    return 1
-  }
 
-  writeln('Governance: OK')
+    writeln('Governance: OK')
+  }
 
   // ─── Step 3: Squash-merge detection ────────────────────────────────────────
   if (opts.dryRun) {
@@ -323,8 +489,8 @@ function runShip(opts, deps = {}) {
   if (diffStatOut) writeln(diffStatOut)
   writeln('────────────────────────────────────────────────────────\n')
 
-  const { stdout: cachedFiles } = execGit(['diff', '--cached', '--name-only'])
-  if (!cachedFiles.trim()) {
+  // Reuses stagedFiles read at the top of the function (Step 0) — never re-query git here.
+  if (stagedFiles.length === 0) {
     writeln(
       'error: nothing is staged — stage your files explicitly before running ship:\n' +
       '  git add <file1> <file2> ...\n' +
@@ -391,7 +557,23 @@ function runShip(opts, deps = {}) {
     return 0
   }
 
+  // Title/body computed once for every remaining branch below (dry-run and real CLI
+  // invocation alike). git log/diff are read-only — they run in --dry-run mode too, same
+  // as the staged-files read in Step 0.
+  //
+  // Design decision (documented per roadmap ML-1A, mirrored from the Go implementation):
+  // the title is always firstLine(opts.message), the -m message passed to this very `ship`
+  // call, even when the branch carries multiple prior commits. Deriving a distinct "PR
+  // title" from N unrelated commit subjects would need a heuristic with no unambiguous
+  // answer — the simplest, least surprising rule is that -m is the PR's summary.
+  const base = defaultBaseBranch(execGit)
+  const commits = gitCommitsSince(base, execGit)
+  const title = firstLine(opts.message || '')
+  const body = buildPRBody(branch, commits)
+
   if (opts.dryRun) {
+    writeln(`[dry-run] Title: ${title}`)
+    writeln(`[dry-run] Body:\n${body}`)
     if (!adapter.available && resolution.forge !== 'manual') {
       const url = adapter.fallbackURL(remoteURL, branch)
       if (url) {
@@ -423,8 +605,6 @@ function runShip(opts, deps = {}) {
   }
 
   // CLI is available — invoke it.
-  const title = firstLine(opts.message || '')
-  const body = `Branch: ${branch}\n\nCreated by trackfw ship.`
   const cliArgs = buildForgeCreateArgs(adapter, title, body)
   const execForgeCLI = deps.execForgeCLI || defaultExecForgeCLI
   const cliErr = execForgeCLI(adapter.cliName, cliArgs)
@@ -443,6 +623,7 @@ function runShip(opts, deps = {}) {
 module.exports = {
   runShip,
   isShipBranch,
+  isGatedShipBranch,
   isGitWriteCmd,
   normalizeBranchSlug,
   checkShipGovernance,
@@ -451,4 +632,10 @@ module.exports = {
   GIT_WRITE_COMMANDS,
   buildForgeCreateArgs,
   firstLine,
+  allDocOnly,
+  splitNonEmptyLines,
+  defaultBaseBranch,
+  gitCommitsSince,
+  buildPRBody,
+  COMMIT_MESSAGE_SEP,
 }

package/src/thirdparty/fetch.js

@@ -0,0 +1,140 @@
+'use strict'
+
+// Node port of internal/thirdparty/fetch.go — the network fetch primitive
+// used by the two-phase third-party artifact gate (skills/agents installed
+// from a URL). See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D7).
+
+const https = require('node:https')
+const { URL } = require('node:url')
+
+// MAX_CONTENT_SIZE is the network fetch cap for third-party text artifacts
+// (D7): 2 MiB — mirrors internal/thirdparty/fetch.go:maxContentSize.
+const MAX_CONTENT_SIZE = 2 * 1024 * 1024
+
+// MAX_REDIRECTS mirrors internal/thirdparty/fetch.go:maxRedirects (3). Note
+// the Go reference's own net/http.Client.CheckRedirect semantics: the check
+// runs BEFORE following a redirect and compares the count of requests
+// ALREADY COMPLETED (via.length, which includes the request that just
+// returned the redirect) against maxRedirects — so in practice only
+// (maxRedirects - 1) redirects are ever followed before the next one is
+// refused. Reproduced here byte-for-byte via requestsCompleted, not
+// "fixed" to what the doc comment alone might suggest.
+const MAX_REDIRECTS = 3
+
+const TIMEOUT_MS = 30 * 1000
+
+// ALLOWED_CONTENT_TYPES mirrors internal/thirdparty/fetch.go:allowedContentTypes.
+const ALLOWED_CONTENT_TYPES = new Set(['text/plain', 'text/markdown', 'text/x-markdown'])
+
+// contentTypeAllowed mirrors internal/thirdparty/fetch.go:contentTypeAllowed
+// — tolerates an optional "; charset=..." (or any other parameter) suffix.
+function contentTypeAllowed(contentType) {
+  const raw = String(contentType || '')
+  const semi = raw.indexOf(';')
+  const base = (semi >= 0 ? raw.slice(0, semi) : raw).trim().toLowerCase()
+  return ALLOWED_CONTENT_TYPES.has(base)
+}
+
+// api is the module.exports object itself, referenced internally via
+// `api.requestOnce(...)` so tests can substitute the single HTTP round
+// trip without a real TLS socket — mirrors the thirdPartyFetch
+// package-var substitution pattern already used at the command layer
+// (npm/src/commands/thirdparty.js). Added in ML-4C to close a coverage
+// gap hefesto-tf found: the resp.statusCode !== 200 branch below existed
+// but was never exercised by any test.
+const api = {}
+
+function requestOnce(rawURL) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(rawURL, { timeout: TIMEOUT_MS }, res => {
+      const chunks = []
+      let total = 0
+      let tooLarge = false
+      res.on('data', chunk => {
+        if (tooLarge) return
+        total += chunk.length
+        if (total > MAX_CONTENT_SIZE) {
+          tooLarge = true
+          res.destroy()
+          return
+        }
+        chunks.push(chunk)
+      })
+      res.on('end', () => {
+        resolve({ statusCode: res.statusCode, headers: res.headers, body: Buffer.concat(chunks), tooLarge })
+      })
+      res.on('error', err => reject(new Error(`failed to read response body: ${err.message}`)))
+    })
+    req.on('timeout', () => req.destroy(new Error('fetch failed: request timed out after 30s')))
+    req.on('error', err => reject(new Error(`fetch failed: ${err.message}`)))
+  })
+}
+
+// fetchOnce follows redirects with the same accounting as Go's
+// fetchClient.CheckRedirect (see MAX_REDIRECTS doc above). requestsCompleted
+// starts at 0 and is incremented after every completed HTTP request.
+async function fetchOnce(rawURL, requestsCompleted) {
+  let parsed
+  try {
+    parsed = new URL(rawURL)
+  } catch (err) {
+    throw new Error(`invalid URL "${rawURL}": ${err.message}`)
+  }
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`refused: URL scheme must be https, got "${parsed.protocol.replace(/:$/, '')}"`)
+  }
+
+  const res = await api.requestOnce(rawURL)
+  requestsCompleted += 1
+
+  if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+    if (requestsCompleted >= MAX_REDIRECTS) {
+      throw new Error(`fetch failed: stopped after ${MAX_REDIRECTS} redirects`)
+    }
+    let next
+    try {
+      next = new URL(res.headers.location, rawURL).toString()
+    } catch (err) {
+      throw new Error(`invalid redirect location: ${err.message}`)
+    }
+    const nextScheme = new URL(next).protocol
+    if (nextScheme !== 'https:') {
+      throw new Error(`redirect to non-https URL refused: ${next}`)
+    }
+    return fetchOnce(next, requestsCompleted)
+  }
+
+  if (res.statusCode !== 200) {
+    throw new Error(`fetch failed: HTTP ${res.statusCode} for ${rawURL}`)
+  }
+
+  const contentType = res.headers['content-type']
+  if (!contentTypeAllowed(contentType)) {
+    throw new Error(`refused: unsupported Content-Type "${contentType || ''}" (allowed: text/plain, text/markdown, text/x-markdown)`)
+  }
+
+  if (res.tooLarge) {
+    throw new Error(`refused: content exceeds ${MAX_CONTENT_SIZE} bytes`)
+  }
+
+  return res.body
+}
+
+// fetch downloads the content at rawURL under the D7 network policy:
+// https-only (validated before the first request), a 30s timeout, at most
+// (MAX_REDIRECTS - 1) redirect hops (each revalidated for https), a 2 MiB
+// size cap, and a Content-Type allowlist. Mirrors
+// internal/thirdparty/fetch.go:Fetch.
+async function fetch(rawURL) {
+  return fetchOnce(rawURL, 0)
+}
+
+api.fetch = fetch
+api.contentTypeAllowed = contentTypeAllowed
+api.requestOnce = requestOnce
+api.MAX_CONTENT_SIZE = MAX_CONTENT_SIZE
+api.MAX_REDIRECTS = MAX_REDIRECTS
+
+module.exports = api

package/src/thirdparty/markers.js

@@ -0,0 +1,207 @@
+'use strict'
+
+// Node port of internal/thirdparty/markers.go — the D3 objective-refusal
+// marker check and the Checksum primitive. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D3, D6).
+
+const crypto = require('node:crypto')
+const { URL } = require('node:url')
+
+// LITERAL_MARKERS mirrors internal/thirdparty/markers.go:literalMarkers — an
+// objective, literal tripwire list, not a filter against a competent
+// adversary (see the ADR's "o que este critério NÃO cobre" section).
+const LITERAL_MARKERS = [
+  'git authority',
+  'mode lock',
+  'governance prerequisite',
+  'reporting boundary',
+  'scope boundary',
+  'dispatch contract',
+]
+
+// HTML_COMMENT_PATTERN matches HTML comments; step 1 of the D3 pipeline
+// NEUTRALIZES them (strips only the delimiters, keeping the inner content
+// in place to be scanned), mirroring internal/thirdparty/markers.go's
+// D3-ter(b) amendment — see neutralizeHTMLComments below.
+const HTML_COMMENT_PATTERN = /<!--([\s\S]*?)-->/g
+
+// neutralizeHTMLComments strips only the HTML comment delimiters ("<!--"
+// and "-->"), keeping whatever text was between them in place to be
+// scanned by the later steps of the pipeline. D3-ter(b): the previous
+// wholesale removal contradicted D3's own written justification for this
+// step ("an LLM reads HTML comments in the token stream") — a marker
+// hidden as `<!-- ## Git authority -->` passed clean.
+function neutralizeHTMLComments(text) {
+  return text.replace(HTML_COMMENT_PATTERN, '$1')
+}
+
+// FENCE_PREFIX_PATTERN detects a fence-opening/closing line: optional
+// leading whitespace followed by three or more backticks or tildes.
+//
+// Unlike the Go reference — which is forced into an explicit line-scanner
+// because Go's RE2-based regexp package rejects backreferences at runtime
+// (see vault/notes/go-regexp-re2-sem-backreference-fenced-block-removal-2026-08-15.md)
+// — JS RegExp does support backreferences. This port still uses the same
+// explicit line-scanner algorithm as the Go reference (removeFencedBlocks
+// below), NOT because JS requires it, but because the scanner is what
+// implements the actual CommonMark closing rule correctly (same delimiter
+// character, closer repeat count >= opener repeat count, unclosed fence
+// never re-opens a heading read). A single backreference regex here would
+// diverge from the Go reference on: an unclosed fence, a closing run
+// shorter than the opener, and an indented fence — porting the algorithm,
+// not the regex, is what keeps behavior byte-identical to Go.
+const FENCE_PREFIX_PATTERN = /^\s*(```+|~~~+)/
+
+// trimChar mirrors Go's strings.Trim(s, cutset) for a single-char cutset:
+// strips ONLY leading/trailing runs of ch, never occurrences in the middle.
+function trimChar(str, ch) {
+  let start = 0
+  let end = str.length
+  while (start < end && str[start] === ch) start++
+  while (end > start && str[end - 1] === ch) end--
+  return str.slice(start, end)
+}
+
+// removeFencedBlocks strips PROPERLY-CLOSED fenced code blocks (``` or
+// ~~~), step 2 of the D3 pipeline: lines inside a closed fence are not read
+// as headings, otherwise documentation that merely quotes the marker list
+// would be refused by its own criterion. A fence is closed by a line
+// starting with the same delimiter character, with at least as many
+// repeats as the opener — the CommonMark rule.
+//
+// D3-ter(a) amendment: an opener with NO matching closer before EOF is NOT
+// a fence for this check — the buffered lines (including the opener) are
+// replayed as ordinary text instead of being dropped. Before this
+// amendment, an unclosed fence swallowed the rest of the document as
+// "fenced" content, silently hiding any marker after it. Mirrors
+// internal/thirdparty/markers.go:removeFencedBlocks.
+function removeFencedBlocks(text) {
+  const lines = text.split('\n')
+  const out = []
+  let buffered = [] // lines consumed since the current fence opener; replayed verbatim if it never closes
+  let closer = '' // fence delimiter run that closes the current block, '' if not in a fence
+  for (const line of lines) {
+    if (closer === '') {
+      const match = FENCE_PREFIX_PATTERN.exec(line)
+      if (match) {
+        closer = match[1]
+        buffered = [line] // keep the opener in case this fence never closes
+        continue
+      }
+      out.push(line)
+      continue
+    }
+    // Inside a (possibly-never-closing) fence: buffer the line, then check
+    // if it closes the block.
+    buffered.push(line)
+    const trimmed = line.trim()
+    const delimChar = closer[0]
+    if (trimmed.startsWith(delimChar.repeat(closer.length)) && trimChar(trimmed, delimChar) === '') {
+      closer = ''
+      buffered = [] // closed properly: the buffered fenced content is discarded, as before
+    }
+  }
+  if (closer !== '') {
+    // Reached EOF still "inside" a fence that never closed (D3-ter(a)): not
+    // a fence at all — replay every buffered line, including the opener,
+    // as ordinary text to be scanned.
+    out.push(...buffered)
+  }
+  return out.join('\n')
+}
+
+// HEADING_LINE_PATTERN matches a single, already-collapsed Markdown heading
+// line (level 1-6). Applied per-line after step 5, on text that no longer
+// contains internal runs of whitespace.
+const HEADING_LINE_PATTERN = /^#{1,6}\s+(.*)$/
+
+// WHITESPACE_PATTERN collapses runs of internal whitespace, step 5.
+const WHITESPACE_PATTERN = /\s+/g
+
+// checkMarkers applies the D3 objective-refusal criterion to content and
+// returns the literal marker names (from LITERAL_MARKERS) that matched as a
+// heading. The normalization pipeline, in fixed order, mirrors
+// internal/thirdparty/markers.go:CheckMarkers exactly:
+//  1. remove HTML comments;
+//  2. remove fenced code blocks (``` and ~~~);
+//  3. NFKC normalize;
+//  4. casefold (String.prototype.toLowerCase(), matching Go's
+//     strings.ToLower — not a true Unicode casefold, deliberately, to stay
+//     byte-identical to the Go reference);
+//  5. collapse internal whitespace + strip, applied per line;
+//  6. match only lines matching ^#{1,6}\s+ against the literal marker list.
+//
+// content may be a Buffer or a string; Buffers are decoded as UTF-8,
+// mirroring Go's string(content) over raw bytes.
+function checkMarkers(content) {
+  let text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content)
+
+  // 1. Neutralize HTML comments — strip only the delimiters, keep the
+  // inner content in place to be scanned (D3-ter(b)).
+  text = neutralizeHTMLComments(text)
+
+  // 2. Remove fenced code blocks — lines inside a fence are not headings.
+  text = removeFencedBlocks(text)
+
+  // 3. NFKC normalize.
+  text = text.normalize('NFKC')
+
+  // 4. Casefold.
+  text = text.toLowerCase()
+
+  const matched = []
+  const seen = new Set()
+  for (const line of text.split('\n')) {
+    // 5. Collapse internal whitespace + strip.
+    const collapsed = line.replace(WHITESPACE_PATTERN, ' ').trim()
+
+    // 6. Match only heading lines against the literal marker list.
+    const match = HEADING_LINE_PATTERN.exec(collapsed)
+    if (!match) continue
+    const body = match[1]
+    for (const marker of LITERAL_MARKERS) {
+      if (body === marker && !seen.has(marker)) {
+        matched.push(marker)
+        seen.add(marker)
+      }
+    }
+  }
+  return matched
+}
+
+// checksum returns the SHA-256 hex digest of the raw bytes, before any
+// normalization. Mirrors internal/thirdparty/markers.go:Checksum. raw may be
+// a Buffer or a string (encoded as UTF-8).
+function checksum(raw) {
+  const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw), 'utf8')
+  return crypto.createHash('sha256').update(buf).digest('hex')
+}
+
+// redactURL returns rawURL with its query string — and userinfo, if
+// present — replaced by the literal marker "[redacted]" (D6-bis). Used
+// before persisting a third-party artifact's source URL to disk (the
+// quarantine record and the provenance entry): a pre-signed URL can carry a
+// bearer token in its query string, which would otherwise become a
+// permanent secret in the git history the moment either file is committed.
+// The full, unredacted URL is used only in memory, for the network fetch
+// itself (D7) — never for anything persisted. Mirrors
+// internal/thirdparty/markers.go:RedactURL. Deliberately constructs the
+// result manually (protocol/host/pathname/hash) rather than mutating and
+// re-serializing via the URL object's own .toString(), to stay
+// byte-identical to the Go/Python output shape rather than depend on
+// WHATWG URL serialization nuances.
+function redactURL(rawURL) {
+  let parsed
+  try {
+    parsed = new URL(rawURL)
+  } catch {
+    return rawURL
+  }
+  let result = `${parsed.protocol}//${parsed.host}${parsed.pathname}`
+  if (parsed.search !== '') result += '?[redacted]'
+  result += parsed.hash
+  return result
+}
+
+module.exports = { checkMarkers, checksum, redactURL, literalMarkers: LITERAL_MARKERS, removeFencedBlocks }