npm - spexcode - Versions diffs - 0.1.1 → 0.1.2 - Mend

spexcode 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

package/{dashboard-dist → spec-dashboard/dist}/index.html RENAMED Viewed

@@ -7,7 +7,7 @@
     <!-- tab-icon: pre-load default favicon (🔭, on brand with the watch glyph); a configured dashboard.icon
          replaces it at runtime once the board loads. Inline emoji SVG — no asset to ship. -->
     <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E%F0%9F%94%AD%3C/text%3E%3C/svg%3E" />
-    <script type="module" crossorigin src="/assets/index-B60MILFg.js"></script>
+    <script type="module" crossorigin src="/assets/index-Bk4E1EQy.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Cq7hwngj.css">
   </head>
   <body>

package/spec-forge/src/__fixtures__/github-forge.json ADDED Viewed

@@ -0,0 +1,63 @@
+{
+  "_note": "Fixture mirroring githubDriver output (the vendor-neutral ForgeIssue[]/ForgePR[] a `gh issue/pr list` collapses to) for a sample repo. Drives the needs-yatsu-eval resolver test with no network.",
+  "issues": [
+    {
+      "number": 1,
+      "title": "login redirect is broken on /logout",
+      "body": "Steps to repro: click logout, land on a 404.\n\nSpec: sessions\nneeds-yatsu-eval\n",
+      "url": "https://github.com/acme/repo/issues/1",
+      "state": "open",
+      "labels": []
+    },
+    {
+      "number": 2,
+      "title": "board badge count is off by one",
+      "body": "The open-issue badge over-counts.\n\nSpec: dashboard-issues",
+      "url": "https://github.com/acme/repo/issues/2",
+      "state": "open",
+      "labels": ["bug", "needs-yatsu-eval"]
+    },
+    {
+      "number": 3,
+      "title": "tracer mislinks a node/<id> branch with a dash",
+      "body": "branchToNode picks the short id.\n\nSpec: links",
+      "url": "https://github.com/acme/repo/issues/3",
+      "state": "open",
+      "labels": ["bug"]
+    },
+    {
+      "number": 4,
+      "title": "old freshness drift already verified",
+      "body": "Spec: freshness\nNeeds-Yatsu-Eval\n",
+      "url": "https://github.com/acme/repo/issues/4",
+      "state": "closed",
+      "labels": []
+    },
+    {
+      "number": 5,
+      "title": "flagged but names no node",
+      "body": "This one is flagged but carries no Spec: marker and no closing PR.\n\nneeds-yatsu-eval\n",
+      "url": "https://github.com/acme/repo/issues/5",
+      "state": "open",
+      "labels": ["needs-yatsu-eval"]
+    },
+    {
+      "number": 6,
+      "title": "fixed via an open PR, no marker on the issue",
+      "body": "A worked bug; the node comes transitively from the closing PR.\n\nneeds-yatsu-eval: ignore-the-trailing-text",
+      "url": "https://github.com/acme/repo/issues/6",
+      "state": "open",
+      "labels": ["needs-yatsu-eval"]
+    }
+  ],
+  "prs": [
+    {
+      "number": 20,
+      "title": "fix logout redirect",
+      "url": "https://github.com/acme/repo/pull/20",
+      "state": "open",
+      "headRefName": "node/port-7f3a1c2",
+      "closesIssues": [6]
+    }
+  ]
+}

package/spec-forge/src/cache.ts ADDED Viewed

@@ -0,0 +1,28 @@
+import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js'
+import { resolveLinks, type NodeLinks } from './links.js'
+export type ForgeDelta =
+  | { kind: 'issue'; issue: ForgeIssue }
+  | { kind: 'pr'; pr: ForgePR }
+  | { kind: 'remove'; target: 'issue' | 'pr'; number: number }
+export class ForgeCache {
+  private issues = new Map<number, ForgeIssue>()
+  private prs = new Map<number, ForgePR>()
+  apply(delta: ForgeDelta): void {
+    if (delta.kind === 'issue') this.issues.set(delta.issue.number, delta.issue)
+    else if (delta.kind === 'pr') this.prs.set(delta.pr.number, delta.pr)
+    else (delta.target === 'issue' ? this.issues : this.prs).delete(delta.number)
+  }
+  async reconcile(driver: ForgeDriver): Promise<void> {
+    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
+    this.issues = new Map(issues.map((i) => [i.number, i]))
+    this.prs = new Map(prs.map((p) => [p.number, p]))
+  }
+  view(nodeIds: string[]): NodeLinks[] {
+    return resolveLinks([...this.issues.values()], [...this.prs.values()], nodeIds)
+  }
+}

package/spec-forge/src/cli.ts ADDED Viewed

@@ -0,0 +1,110 @@
+import { loadSpecs } from '../../spec-cli/src/specs.js'
+import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js'
+import { githubDriver } from './drivers/github.js'
+import { resolveLinks, type NodeLinks } from './links.js'
+import { resolveEvalPending, type NodeEvalPending } from './needs-yatsu-eval.js'
+const DRIVERS: ForgeDriver[] = [githubDriver]
+const DEFAULT_HOST = 'github'
+function driverFor(host: string): ForgeDriver | undefined {
+  return DRIVERS.find((d) => d.host === host)
+}
+// tiny flag reader over this command's own arg slice (everything after `forge`), so cli.ts stays routing-only.
+function flag(args: string[], name: string): string | undefined {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : undefined
+}
+const has = (args: string[], name: string) => args.includes(`--${name}`)
+async function readForge(
+  args: string[],
+): Promise<{ driver: ForgeDriver; nodeIds: string[]; issues: ForgeIssue[]; prs: ForgePR[] } | null> {
+  const host = flag(args, 'host') ?? DEFAULT_HOST
+  const driver = driverFor(host)
+  if (!driver) {
+    console.error(`forge: unknown host '${host}' (known: ${DRIVERS.map((d) => d.host).join(', ')})`)
+    return null
+  }
+  const nodeIds = (await loadSpecs()).map((s) => s.id)
+  const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
+  return { driver, nodeIds, issues, prs }
+}
+function render(links: NodeLinks[]): string {
+  const out: string[] = []
+  for (const n of links) {
+    out.push(`\n${n.node}`)
+    if (n.issues.length) {
+      out.push('  issues:')
+      for (const i of n.issues) out.push(`    #${i.number} ${i.state}  ${i.title}  (via ${i.via})  ${i.url}`)
+    }
+    if (n.prs.length) {
+      out.push('  prs:')
+      for (const p of n.prs) out.push(`    #${p.number} ${p.state}  ${p.title}  ${p.headRefName}  ${p.url}`)
+    }
+  }
+  return out.join('\n')
+}
+async function links(args: string[]): Promise<number> {
+  const forge = await readForge(args)
+  if (!forge) return 2
+  const { driver, nodeIds, issues, prs } = forge
+  let resolved = resolveLinks(issues, prs, nodeIds)
+  const only = flag(args, 'node')
+  if (only) {
+    if (!nodeIds.includes(only)) { console.error(`forge: no such node '${only}'`); return 1 }
+    resolved = resolved.filter((n) => n.node === only)
+  }
+  if (has(args, 'json')) { console.log(JSON.stringify(resolved, null, 2)); return 0 }
+  const nIssues = resolved.reduce((a, n) => a + n.issues.length, 0)
+  const nPRs = resolved.reduce((a, n) => a + n.prs.length, 0)
+  console.log(
+    `spec-forge · ${driver.host} · ${resolved.length} linked node(s) · ${nIssues} issue(s), ${nPRs} pr(s)` +
+      ` · scanned ${issues.length} issue(s), ${prs.length} pr(s)`,
+  )
+  if (resolved.length) console.log(render(resolved))
+  return 0
+}
+function renderPending(pending: NodeEvalPending[]): string {
+  const out: string[] = []
+  for (const n of pending) {
+    out.push(`\n${n.node}`)
+    for (const i of n.pending) out.push(`    #${i.number} ${i.state}  ${i.title}  (via ${i.via})  ${i.url}`)
+  }
+  return out.join('\n')
+}
+async function evalPending(args: string[]): Promise<number> {
+  const forge = await readForge(args)
+  if (!forge) return 2
+  const { driver, nodeIds, issues, prs } = forge
+  let resolved = resolveEvalPending(issues, prs, nodeIds)
+  const only = flag(args, 'node')
+  if (only) {
+    if (!nodeIds.includes(only)) { console.error(`forge: no such node '${only}'`); return 1 }
+    resolved = resolved.filter((n) => n.node === only)
+  }
+  if (has(args, 'json')) { console.log(JSON.stringify(resolved, null, 2)); return 0 }
+  const nPending = resolved.reduce((a, n) => a + n.pending.length, 0)
+  console.log(
+    `spec-forge · ${driver.host} · ${resolved.length} node(s) with eval pending · ${nPending} issue(s)` +
+      ` · scanned ${issues.length} issue(s), ${prs.length} pr(s)`,
+  )
+  if (resolved.length) console.log(renderPending(resolved))
+  return 0
+}
+export async function runForge(args: string[]): Promise<number> {
+  const sub = args[0]
+  if (sub === 'links') return links(args.slice(1))
+  if (sub === 'eval-pending') return evalPending(args.slice(1))
+  console.error('spex forge: links [--host github] [--node <id>] [--json] | eval-pending [--host github] [--node <id>] [--json]')
+  return 2
+}

package/spec-forge/src/drivers/github.ts ADDED Viewed

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { ForgeDriver, ForgeIssue, ForgePR } from '../port.js'
+const run = promisify(execFile)
+// maxBuffer is raised above the 1MB default: a busy repo's issue/PR JSON can exceed it
+async function gh<T>(args: string[]): Promise<T> {
+  const { stdout } = await run('gh', args, { maxBuffer: 16 * 1024 * 1024 })
+  return JSON.parse(stdout) as T
+}
+export const githubDriver: ForgeDriver = {
+  host: 'github',
+  // fetch open and closed in separate `--limit 200` windows and merge, so a flood of closed issues can't crowd the open set out of one shared `--state all` limit
+  async listIssues(): Promise<ForgeIssue[]> {
+    const list = (state: string) =>
+      gh<{ number: number; title: string; body: string; url: string; state: string; labels: { name: string }[] }[]>(
+        ['issue', 'list', '--state', state, '--limit', '200', '--json', 'number,title,body,url,state,labels'],
+      )
+    const [open, closed] = await Promise.all([list('open'), list('closed')])
+    return [...open, ...closed].map((r) => ({
+      number: r.number,
+      title: r.title,
+      body: r.body ?? '',
+      url: r.url,
+      state: r.state,
+      labels: (r.labels ?? []).map((l) => l.name),
+    }))
+  },
+  async listPRs(): Promise<ForgePR[]> {
+    type Row = {
+      number: number; title: string; url: string; state: string; headRefName: string
+      closingIssuesReferences?: { number: number }[]
+    }
+    const base = ['pr', 'list', '--state', 'open', '--limit', '200', '--json']
+    const fields = 'number,title,url,state,headRefName'
+    let rows: Row[]
+    try {
+      rows = await gh<Row[]>([...base, `${fields},closingIssuesReferences`])
+    } catch (err) {
+      if (!isUnknownFieldError(err)) throw err
+      warnNoTransitiveOnce()
+      rows = await gh<Row[]>([...base, fields])
+    }
+    return rows.map((r) => ({
+      number: r.number,
+      title: r.title,
+      url: r.url,
+      state: r.state,
+      headRefName: r.headRefName,
+      closesIssues: (r.closingIssuesReferences ?? []).map((c) => c.number),
+    }))
+  },
+}
+function isUnknownFieldError(err: unknown): boolean {
+  const e = err as { stderr?: string; message?: string }
+  const text = `${e?.stderr ?? ''}\n${e?.message ?? ''}`
+  return /unknown json field/i.test(text)
+}
+let warnedNoTransitive = false
+function warnNoTransitiveOnce(): void {
+  if (warnedNoTransitive) return
+  warnedNoTransitive = true
+  console.warn(
+    'spec-forge: this `gh` is too old for `closingIssuesReferences` — transitive issue↔PR links are ' +
+      'disabled (branch + `Spec:` marker links still work). Upgrade `gh` to restore them.',
+  )
+}

package/spec-forge/src/links.ts ADDED Viewed

@@ -0,0 +1,76 @@
+import type { ForgeIssue, ForgePR } from './port.js'
+export type LinkedIssue = ForgeIssue & { via: 'marker' | 'pr' }
+export type LinkedPR = ForgePR & { via: 'branch' }
+export type NodeLinks = { node: string; issues: LinkedIssue[]; prs: LinkedPR[] }
+export function parseSpecMarkers(body: string): string[] {
+  const ids: string[] = []
+  for (const m of (body || '').matchAll(/^\s*spec:\s*(.+)$/gim)) {
+    for (const part of m[1].split(',')) {
+      const id = part.trim()
+      if (id) ids.push(id)
+    }
+  }
+  return ids
+}
+export function branchToNode(branch: string, nodeIds: string[]): string | null {
+  if (!branch?.startsWith('node/')) return null
+  const rest = branch.slice('node/'.length)
+  let best: string | null = null
+  for (const id of nodeIds) {
+    if (rest === id || rest.startsWith(id + '-')) {
+      if (!best || id.length > best.length) best = id
+    }
+  }
+  return best
+}
+export function resolveLinks(
+  issues: ForgeIssue[],
+  prs: ForgePR[],
+  nodeIds: string[],
+): NodeLinks[] {
+  const known = new Set(nodeIds)
+  const byNode = new Map<string, { issues: Map<number, LinkedIssue>; prs: Map<number, LinkedPR> }>()
+  const slot = (node: string) => {
+    let s = byNode.get(node)
+    if (!s) { s = { issues: new Map(), prs: new Map() }; byNode.set(node, s) }
+    return s
+  }
+  // PRs: branch → node (free structural link), and remember which node each PR belongs to.
+  const prNode = new Map<number, string>()
+  for (const pr of prs) {
+    const node = branchToNode(pr.headRefName, nodeIds)
+    if (!node) continue
+    prNode.set(pr.number, node)
+    slot(node).prs.set(pr.number, { ...pr, via: 'branch' })
+  }
+  // Issues by marker — the explicit convention. Unknown ids are dropped (no inventing nodes).
+  const issueByNumber = new Map(issues.map((i) => [i.number, i]))
+  for (const issue of issues) {
+    for (const id of parseSpecMarkers(issue.body)) {
+      if (known.has(id)) slot(id).issues.set(issue.number, { ...issue, via: 'marker' })
+    }
+  }
+  // Transitive: a PR on a node branch that closes an issue links that issue to the node — unless a marker
+  // already linked it (marker wins, so we don't overwrite the explicit source with the inferred one).
+  for (const pr of prs) {
+    const node = prNode.get(pr.number)
+    if (!node) continue
+    for (const num of pr.closesIssues) {
+      const issue = issueByNumber.get(num)
+      if (issue && !slot(node).issues.has(num)) {
+        slot(node).issues.set(num, { ...issue, via: 'pr' })
+      }
+    }
+  }
+  return [...byNode.entries()]
+    .map(([node, s]) => ({ node, issues: [...s.issues.values()], prs: [...s.prs.values()] }))
+    .sort((a, b) => a.node.localeCompare(b.node))
+}

package/spec-forge/src/needs-yatsu-eval.ts ADDED Viewed

@@ -0,0 +1,30 @@
+import type { ForgeIssue, ForgePR } from './port.js'
+import { resolveLinks, type LinkedIssue } from './links.js'
+export const NEEDS_YATSU_EVAL = 'needs-yatsu-eval'
+// a bare-marker body line: the name alone, case-insensitive, any indent, optional trailing colon — content after it (`needs-yatsu-eval: foo`) is NOT a match
+const BODY_MARKER = new RegExp(`^\\s*${NEEDS_YATSU_EVAL}\\s*:?\\s*$`, 'im')
+export function isNeedsYatsuEval(issue: ForgeIssue): boolean {
+  if (issue.labels.some((l) => l.trim().toLowerCase() === NEEDS_YATSU_EVAL)) return true
+  return BODY_MARKER.test(issue.body || '')
+}
+export type EvalPending = LinkedIssue
+export type NodeEvalPending = { node: string; pending: EvalPending[] }
+export function resolveEvalPending(
+  issues: ForgeIssue[],
+  prs: ForgePR[],
+  nodeIds: string[],
+): NodeEvalPending[] {
+  const flagged = new Set(issues.filter(isNeedsYatsuEval).map((i) => i.number))
+  if (!flagged.size) return []
+  const out: NodeEvalPending[] = []
+  for (const { node, issues: linked } of resolveLinks(issues, prs, nodeIds)) {
+    const pending = linked.filter((i) => i.state === 'open' && flagged.has(i.number))
+    if (pending.length) out.push({ node, pending })
+  }
+  return out
+}

package/spec-forge/src/port.ts ADDED Viewed

@@ -0,0 +1,23 @@
+export type ForgeIssue = {
+  number: number
+  title: string
+  body: string
+  url: string
+  state: string
+  labels: string[]
+}
+export type ForgePR = {
+  number: number
+  title: string
+  url: string
+  state: string
+  headRefName: string
+  closesIssues: number[]
+}
+export interface ForgeDriver {
+  readonly host: string
+  listIssues(): Promise<ForgeIssue[]>
+  listPRs(): Promise<ForgePR[]>
+}

package/spec-forge/src/resident.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import { ForgeCache } from './cache.js'
+import { githubDriver } from './drivers/github.js'
+import type { NodeLinks } from './links.js'
+const cache = new ForgeCache()
+let inFlight: Promise<void> | null = null
+// track last ATTEMPT, not last success, so the TTL also backs off failures — else a forge-less repo respawns `gh` every poll
+let lastAttempt = 0
+const TTL_MS = 60_000
+function refreshIfStale(now: number): void {
+  if (inFlight || (lastAttempt && now - lastAttempt < TTL_MS)) return
+  lastAttempt = now
+  inFlight = cache
+    .reconcile(githubDriver)
+    .catch(() => {})
+    .finally(() => { inFlight = null })
+}
+export function residentForgeView(nodeIds: string[]): NodeLinks[] {
+  refreshIfStale(Date.now())
+  return cache.view(nodeIds)
+}

package/spec-yatsu/src/cache.ts ADDED Viewed

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto'
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { gitCommonDir } from '../../spec-cli/src/layout.js'
+export const MISS_BLOB = 'miss original file'
+// every cache fn takes an optional `dir` (defaulting to the live cache dir) so the logic is testable
+// against a temp dir without a git repo.
+export function cacheDir(): string {
+  return join(gitCommonDir(), 'spexcode', 'yatsu-blobs')
+}
+// a content-addressed blob name = the sha256 of its bytes (64 hex). The backstop recognises a stray one.
+const BLOB_NAME = /^[0-9a-f]{64}$/
+// store bytes, return the content hash (the value recorded as a reading's `blob`). Idempotent: identical
+// content maps to the same name, written once.
+export function putBlob(bytes: Buffer, dir = cacheDir()): string {
+  const sha = createHash('sha256').update(bytes).digest('hex')
+  mkdirSync(dir, { recursive: true })
+  const p = join(dir, sha)
+  if (!existsSync(p)) writeFileSync(p, bytes)
+  return sha
+}
+export function blobPath(sha: string, dir = cacheDir()): string {
+  return join(dir, sha)
+}
+export function hasBlob(sha: string | null, dir = cacheDir()): boolean {
+  return !!sha && existsSync(blobPath(sha, dir))
+}
+// render a reading's blob reference: the cache path when present, the MISS sentinel when the record
+// outlived its bytes, '' when the reading had no image at all (a pixel-less observation).
+export function resolveBlob(sha: string | null, dir = cacheDir()): string {
+  if (!sha) return ''
+  return hasBlob(sha, dir) ? blobPath(sha, dir) : MISS_BLOB
+}
+// every content-addressed blob currently in the cache.
+export function listBlobs(dir = cacheDir()): string[] {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((n) => BLOB_NAME.test(n)).sort()
+}
+export function gc(keep: Set<string>, dir = cacheDir()): string[] {
+  const removed: string[] = []
+  for (const name of listBlobs(dir)) {
+    if (keep.has(name)) continue
+    rmSync(blobPath(name, dir))
+    removed.push(name)
+  }
+  return removed
+}
+// read a blob's bytes (used by callers that render/serve a reading's pixels); null when absent.
+export function getBlob(sha: string | null, dir = cacheDir()): Buffer | null {
+  return hasBlob(sha, dir) ? readFileSync(blobPath(sha!, dir)) : null
+}
+// is a staged repo path a stray content-addressed blob? (a 64-hex basename, or anything under a
+// yatsu-blobs dir). The pre-commit backstop rejects these so pixels never leak into git history.
+export function isStrayBlob(path: string): boolean {
+  const base = path.slice(path.lastIndexOf('/') + 1)
+  return BLOB_NAME.test(base) || path.includes('/yatsu-blobs/')
+}