@erclx/aitk 3.52.0 → 3.53.0

package/src/pr/paths.ts

@@ -0,0 +1,335 @@
+/**
+ * The heading whose bullets state what a branch changed.
+ *
+ * Read alone, and never widened to a sibling section. `## Technical Context`
+ * legitimately names files a branch never touched, such as an install stamp
+ * inside a target, so a reader that took the whole body would manufacture a
+ * finding out of every argument the author made for the change.
+ */
+export const KEY_CHANGES = 'Key Changes'
+
+/** What one bullet claimed, kept with its bullet so a finding can quote it. */
+export interface PathClaim {
+  /** Repository-relative, with a trailing slash kept on a directory claim. */
+  readonly path: string
+  /** True when the span named a folder, which covers every file beneath it. */
+  readonly directory: boolean
+  /**
+   * True when the first segment names an entry the tree actually holds.
+   *
+   * An unanchored claim is a path written partially, such as
+   * `claude-worker/SKILL.md` for a file under `claude/skills/`. It can confirm
+   * that a changed file was named and can never accuse one of being absent,
+   * because the comparison has no way to tell a partial spelling from a
+   * genuinely wrong one.
+   */
+  readonly anchored: boolean
+  /** The span exactly as the body wrote it, before the line suffix came off. */
+  readonly span: string
+  /** One-based index of the bullet inside the section. */
+  readonly bullet: number
+  /** The bullet, trimmed, so a finding names the sentence it came from. */
+  readonly preview: string
+}
+
+export type KeyChangeRead =
+  | {
+      readonly kind: 'read'
+      readonly claims: readonly PathClaim[]
+      /** Bullets the section carried, so an empty claim set is separable. */
+      readonly bullets: number
+    }
+  | { readonly kind: 'no-section' }
+
+/** The longest bullet a claim carries forward, matching the citation sweep. */
+const PREVIEW_LIMIT = 200
+
+/** A backticked span, the only carrier this corpus writes a path in. */
+const BACKTICKED = /`([^`\n]+)`/g
+
+/** A list item at any indent, in either bullet spelling or as an ordinal. */
+const BULLET = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/
+
+const FENCE = /^\s*(?:```|~~~)/
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/
+
+/**
+ * A `file.ts:42` or `file.ts:42-58` suffix, which is a reader's click target
+ * rather than part of the name.
+ */
+const LINE_SUFFIX = /:\d+(?:-\d+)?$/
+
+/**
+ * A character that puts the span outside a path this comparison resolves.
+ *
+ * Whitespace separates a backticked command from a backticked path, and it is
+ * the whole answer to one of the four observed false-positive classes:
+ * `aitk markdown audit .claude/rules --json` carries a slash and names no file.
+ * Angle brackets answer a second, since `.claude/plans/feature-<slug>.md`
+ * describes a shape rather than naming a file. A glob and a caret describe a
+ * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
+ * a leading anchor names something outside this repository.
+ *
+ * Deliberately not shared with `classifySpan` in `@/gov/citations`, which asks
+ * a different question. That sweep resolves what a rule points a reader at,
+ * against the filesystem, with a sibling resolving inside the citing rule's own
+ * folder. This one resolves what a bullet claims to have changed, against a
+ * changed-file list, and it admits a folder where that sweep declines one.
+ */
+function isNotRepositoryPath(span: string): boolean {
+  if (/[\s<>$*|?^]/.test(span)) return true
+  if (span.includes('://')) return true
+  return /^[/~@#!]/.test(span)
+}
+
+/**
+ * Whether the span's last segment carries a file extension.
+ *
+ * The extension has to start with a letter, which is what keeps `127.0.0.1`
+ * out. A bare dotted number reaching the comparison is the shape that put
+ * `src/serve/127.0.0.1` in a report over a body that was correct.
+ */
+function hasExtension(span: string): boolean {
+  const segment = span.slice(span.lastIndexOf('/') + 1)
+  return /\.[A-Za-z][A-Za-z0-9]*$/.test(segment)
+}
+
+/** Blanks every backticked span so a cue search never fires inside one. */
+function maskSpans(text: string): string {
+  return text.replace(/`[^`\n]*`/g, (span) => ' '.repeat(span.length))
+}
+
+/**
+ * The part of a bullet that asserts a change, which ends at its first comma.
+ *
+ * This is the one lever that separates a claim from a mention, and it was
+ * chosen by measurement rather than by grammar. Over the 23 merged pull
+ * requests in this repository that carry the section, reading whole bullets
+ * reported 16 paths as claimed-but-untouched and every one of them was a file
+ * the body named for context. Cutting at the comma left 110 claims of the
+ * original 149 and took the false reports to 2. A list of clause-opening words
+ * tried beside it (`which`, `since`, `because`, `rather than`, and eleven more)
+ * removed nothing the comma had not already removed, because this corpus
+ * punctuates every one of them.
+ *
+ * What it costs is a claim in a second coordinated clause, as in "Add `x` to
+ * `a.ts`, and delete the old inline `y` from `b.ts`", where `b.ts` stops being
+ * claimed and falls to the unnamed direction instead. That direction reports
+ * without grading, so the cost lands where it does no damage.
+ */
+function claimRegion(bullet: string): string {
+  const at = maskSpans(bullet).indexOf(',')
+  return at === -1 ? bullet : bullet.slice(0, at)
+}
+
+/**
+ * A claim region that asserts nothing changed.
+ *
+ * A body writes such a bullet to record a decision it declined, and the path it
+ * names is the file it deliberately did not touch, which is the exact inverse
+ * of a claim. `#1274` opens one with "Leave `...expect.toml` untouched" and the
+ * path sits ahead of the first comma, so the region cut cannot reach it: a
+ * stricter cut would not catch this and a looser one would find more.
+ *
+ * The marker rather than the leading verb decides it, because `keep` and
+ * `leave` both open a real claim often enough and neither is safe alone. The
+ * set is deliberately three words. `in place` was measured and dropped, since
+ * rewriting a file in place is an ordinary claim, and `no other line` was
+ * dropped because `#1269` writes "as one insertion that touches no other line"
+ * about a change it did make. `alone` was in the set and came out on review:
+ * every occurrence across the 40-pull-request corpus sits past the first
+ * comma, where the region cut already excludes it, so the word caught nothing
+ * real there. Kept, it turns restrictive on a comma-free bullet, which is this
+ * repository's more common use of the word: "Move the threshold read into
+ * `src/gate/stages.ts` alone." asserts an edit and voided to an empty claim
+ * set while the word was in the set, unlike the other three, which disclaim
+ * wherever they land.
+ */
+const NO_CHANGE =
+  /\b(?:untouched|unchanged)\b|\bas written\b|^\s*(?:do not|don't|never)\b/i
+
+function disclaimsChange(region: string): boolean {
+  return NO_CHANGE.test(maskSpans(region))
+}
+
+/**
+ * The lines under a heading, ending at the next heading of the same level or
+ * higher. Undefined when the body carries no such heading, which the caller
+ * reports rather than reading as an empty section.
+ */
+export function readSection(body: string, title: string): string | undefined {
+  const lines = body.replace(/\r\n/g, '\n').split('\n')
+  const wanted = title.toLowerCase()
+
+  let start = -1
+  let level = 0
+  let fenced = false
+
+  for (const [index, line] of lines.entries()) {
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    const heading = line.match(HEADING)
+    if (heading === null) continue
+    if ((heading[2] ?? '').toLowerCase() !== wanted) continue
+    start = index + 1
+    level = (heading[1] ?? '').length
+    break
+  }
+
+  if (start === -1) return undefined
+
+  const out: string[] = []
+  fenced = false
+  for (const line of lines.slice(start)) {
+    if (FENCE.test(line)) fenced = !fenced
+    const heading = fenced ? null : line.match(HEADING)
+    if (heading !== null && (heading[1] ?? '').length <= level) break
+    out.push(line)
+  }
+
+  return out.join('\n')
+}
+
+/**
+ * Splits a section into bullets, folding a wrapped continuation line into the
+ * bullet above it and starting a new one at every list marker.
+ *
+ * A nested bullet is its own bullet rather than part of its parent, which keeps
+ * one claim region per claim a reader sees.
+ */
+function splitBullets(section: string): string[] {
+  const bullets: string[] = []
+  let current: string[] | undefined
+  let fenced = false
+
+  for (const line of section.split('\n')) {
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      current?.push(line)
+      continue
+    }
+
+    const marker = fenced ? null : line.match(BULLET)
+    if (marker !== null) {
+      if (current !== undefined) bullets.push(current.join(' '))
+      current = [marker[1] ?? '']
+      continue
+    }
+
+    if (current === undefined) continue
+    if (!fenced && line.trim() === '') {
+      bullets.push(current.join(' '))
+      current = undefined
+      continue
+    }
+    current.push(line.trim())
+  }
+
+  if (current !== undefined) bullets.push(current.join(' '))
+  return bullets
+}
+
+/** What one span resolved to, or nothing when it names no comparable path. */
+interface ResolvedSpan {
+  readonly path: string
+  readonly directory: boolean
+}
+
+function resolveSpan(span: string): ResolvedSpan | undefined {
+  if (span === '' || isNotRepositoryPath(span)) return undefined
+
+  // A bare name is the fourth observed false-positive class and it drops
+  // outright. Resolved as a sibling of a path earlier in the bullet it produced
+  // seven wrong paths across this corpus against two right ones, because a
+  // compound bullet names a sibling folder as often as a sibling file. Dropping
+  // it under-reports in the unnamed direction and never fires in the other.
+  if (!span.includes('/')) return undefined
+
+  if (span.endsWith('/')) {
+    // A single top-level folder is never a claim. Nobody reports having changed
+    // the whole of `src/`, and every body that spelled one was naming where
+    // something lives.
+    return span.indexOf('/') === span.length - 1
+      ? undefined
+      : { path: span, directory: true }
+  }
+
+  return hasExtension(span) ? { path: span, directory: false } : undefined
+}
+
+/**
+ * Every path the `## Key Changes` section claims a change to.
+ *
+ * `roots` names the entries the tree holds at its top level, which is what
+ * separates a whole path from one written partially. It is passed in rather
+ * than read here so the extractor stays a pure function of the body, and there
+ * is no default: an absent set would silently mark every claim anchored, which
+ * is the direction that accuses.
+ *
+ * Reports `no-section` rather than an empty read when the heading is absent,
+ * and an empty claim set with a bullet count when the heading is there and
+ * nothing resolved. The caller needs those apart. A body with no section states
+ * nothing, a section that produced no claim is this extractor failing over
+ * prose, and only a section that produced claims supports a comparison. An
+ * empty extraction read as a clean pass is the failure shape this repository
+ * has already recorded twice.
+ */
+export function extractKeyChangePaths(
+  body: string,
+  roots: ReadonlySet<string>,
+  title: string = KEY_CHANGES,
+): KeyChangeRead {
+  const section = readSection(body, title)
+  if (section === undefined) return { kind: 'no-section' }
+
+  const bullets = splitBullets(section)
+  const claims: PathClaim[] = []
+  const seen = new Set<string>()
+
+  for (const [index, bullet] of bullets.entries()) {
+    const trimmed = bullet.trim()
+    const preview =
+      trimmed.length > PREVIEW_LIMIT
+        ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
+        : trimmed
+    const region = claimRegion(trimmed)
+    if (disclaimsChange(region)) continue
+
+    let claimed = false
+
+    for (const match of region.matchAll(BACKTICKED)) {
+      const span = match[1] ?? ''
+      const bare = span.replace(LINE_SUFFIX, '')
+
+      // A `file:line` span following another claim in the same bullet is a
+      // citation into a file being described rather than a second claim, which
+      // is what "the stages at `verify.sh:634` and `:642`" is doing inside a
+      // bullet whose claim is the context entry that describes them. Leading
+      // its bullet it is an ordinary claim, which is how a body names the exact
+      // line it rewrote.
+      const cited = bare !== span
+      if (cited && claimed) continue
+
+      const resolved = resolveSpan(bare)
+      if (resolved === undefined) continue
+      claimed = true
+      if (seen.has(resolved.path)) continue
+      seen.add(resolved.path)
+
+      claims.push({
+        path: resolved.path,
+        directory: resolved.directory,
+        anchored: roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
+        span,
+        bullet: index + 1,
+        preview,
+      })
+    }
+  }
+
+  return { kind: 'read', claims, bullets: bullets.length }
+}