@fcon-tech/portolan 0.4.5

package/core/src/tools/sweep.ts

@@ -0,0 +1,198 @@
+/**
+ * `sweep`: ripgrep-backed pattern search over the target. Every match comes
+ * back as an anchored chunk (path, line, matched text, optional context)
+ * labeled `measured`. No match is an honest empty list; a malformed pattern
+ * is an error naming the pattern with zero results; a missing ripgrep is an
+ * error naming the binary — never a substitute search.
+ * specs/tools/spec.md
+ */
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import type { Anchor } from "../types";
+import { findBinary, firstLine, MissingBinaryError, relativeToTarget, type Env } from "./shared";
+
+export interface SweepOptions {
+  /** Surrounding context lines handed to ripgrep (`rg -C`). */
+  context?: number;
+  /** Glob filter handed to ripgrep (`rg -g`). */
+  glob?: string;
+  /** Environment override; tests restrict PATH to probe missing-binary paths. */
+  env?: Env;
+}
+
+/** One anchored match: where it is, what matched, optional context. */
+export interface SweepChunk {
+  /** File path, relative to the target root when ripgrep reports one. */
+  path: string;
+  /** 1-based line number of the match. */
+  line: number;
+  /** The full matching line, without trailing newline. */
+  text: string;
+  /** The first matched substring. */
+  match: string;
+  /** Every matched substring on the line. */
+  matches: string[];
+  /** Surrounding lines, present when `context` was requested. */
+  context?: string[];
+  /** file:line anchor for chart citations. */
+  anchor: Anchor;
+}
+
+export interface SweepResult {
+  trust: "measured";
+  pattern: string;
+  chunks: SweepChunk[];
+}
+
+/** Raised when ripgrep itself fails (malformed pattern, bad root, ...). */
+export class SweepError extends Error {
+  readonly pattern: string;
+  constructor(pattern: string, message: string) {
+    super(`sweep: ${message}`);
+    this.name = "SweepError";
+    this.pattern = pattern;
+  }
+}
+
+interface RgText {
+  text?: string;
+}
+
+/** The subset of ripgrep's --json event stream the tool consumes. */
+interface RgEvent {
+  type: string;
+  data?: {
+    path?: RgText;
+    lines?: RgText;
+    line_number?: number;
+    submatches?: Array<{ match?: RgText }>;
+  };
+}
+
+interface FileEvent {
+  line: number;
+  text: string;
+  isMatch: boolean;
+  matches: string[];
+}
+
+/**
+ * Map ripgrep's --json events to anchored chunks. Only `match` and
+ * `context` events carry evidence; begin/end/summary and any unknown event
+ * kinds are ignored so a ripgrep version bump degrades gracefully.
+ */
+function parseRgEvents(
+  stdout: string,
+  targetRoot: string,
+  contextRequested: number,
+): SweepChunk[] {
+  const perFile = new Map<string, FileEvent[]>();
+  for (const raw of stdout.split("\n")) {
+    if (raw.trim().length === 0) continue;
+    let event: RgEvent;
+    try {
+      event = JSON.parse(raw) as RgEvent;
+    } catch {
+      throw new Error(
+        `sweep: ripgrep emitted unparseable output: ${raw.slice(0, 120)}`,
+      );
+    }
+    if (event.type !== "match" && event.type !== "context") continue;
+    const data = event.data ?? {};
+    const path = data.path?.text;
+    const line = data.line_number;
+    if (path === undefined || line === undefined) continue;
+    const events = perFile.get(path) ?? [];
+    events.push({
+      line,
+      text: (data.lines?.text ?? "").replace(/\r?\n$/, ""),
+      isMatch: event.type === "match",
+      matches: (data.submatches ?? []).map((s) => s.match?.text ?? ""),
+    });
+    perFile.set(path, events);
+  }
+
+  const chunks: SweepChunk[] = [];
+  for (const [rawPath, events] of perFile) {
+    const path = relativeToTarget(rawPath, targetRoot);
+    for (const ev of events) {
+      if (!ev.isMatch) continue;
+      const context =
+        contextRequested > 0
+          ? events
+              .filter(
+                (e) =>
+                  !e.isMatch &&
+                  e.line !== ev.line &&
+                  Math.abs(e.line - ev.line) <= contextRequested,
+              )
+              .sort((a, b) => a.line - b.line)
+              .map((e) => e.text)
+          : undefined;
+      chunks.push({
+        path,
+        line: ev.line,
+        text: ev.text,
+        match: ev.matches[0] ?? "",
+        matches: ev.matches,
+        ...(context !== undefined ? { context } : {}),
+        anchor: { type: "file", path, line: ev.line },
+      });
+    }
+  }
+  chunks.sort((a, b) =>
+    a.path === b.path ? a.line - b.line : a.path < b.path ? -1 : 1,
+  );
+  return chunks;
+}
+
+/** Search `targetRoot` for `pattern`; anchored chunks labeled `measured`. */
+export function sweep(
+  targetRoot: string,
+  pattern: string,
+  options: SweepOptions = {},
+): SweepResult {
+  const env: Env = options.env ?? process.env;
+  let isDir = false;
+  try {
+    isDir = statSync(targetRoot).isDirectory();
+  } catch {
+    // fall through to the honest error below
+  }
+  if (!isDir) {
+    throw new SweepError(pattern, `target root ${targetRoot} is not a directory`);
+  }
+
+  const rg = findBinary("rg", env);
+  if (!rg) throw new MissingBinaryError("rg", "sweep");
+
+  const args = ["--json"];
+  if (options.context !== undefined && options.context > 0) {
+    args.push("-C", String(Math.floor(options.context)));
+  }
+  if (options.glob !== undefined) args.push("-g", options.glob);
+  args.push("--", pattern, ".");
+
+  const run = spawnSync(rg, args, {
+    cwd: targetRoot,
+    env,
+    encoding: "utf8",
+    maxBuffer: 512 * 1024 * 1024,
+  });
+  if (run.error) throw new MissingBinaryError("rg", "sweep");
+  // ripgrep: 0 = matches found, 1 = no matches, >=2 = error (bad pattern, ...).
+  if (run.status !== 0 && run.status !== 1) {
+    const reason =
+      firstLine(run.stderr ?? "") || `ripgrep exited with code ${run.status}`;
+    throw new SweepError(
+      pattern,
+      `pattern ${JSON.stringify(pattern)} rejected by ripgrep: ${reason}`,
+    );
+  }
+  const context = options.context ?? 0;
+  return {
+    trust: "measured",
+    pattern,
+    chunks: parseRgEvents(run.stdout ?? "", targetRoot, context),
+  };
+}

package/core/src/tools/symbols.ts

@@ -0,0 +1,176 @@
+/**
+ * `symbols`: ctags-backed symbol lookup. Definitions (name, kind, path,
+ * line) are authoritative ctags output; references are resolved only by a
+ * corroborating sweep of the symbol name at definition-free sites — never
+ * invented. An absent symbol is an honest empty result; a missing ctags is
+ * an error naming the binary.
+ * specs/tools/spec.md
+ */
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import type { Anchor } from "../types";
+import { escapeRegExp, findBinary, firstLine, MissingBinaryError, relativeToTarget, type Env } from "./shared";
+import { sweep } from "./sweep";
+
+export interface SymbolOptions {
+  /** Resolve references via a corroborating sweep of the symbol name. */
+  references?: boolean;
+  /** Environment override; tests restrict PATH to probe missing-binary paths. */
+  env?: Env;
+}
+
+export interface SymbolDefinition {
+  name: string;
+  kind: string;
+  path: string;
+  line: number;
+  anchor: Anchor;
+}
+
+export interface SymbolReference {
+  path: string;
+  line: number;
+  text: string;
+  anchor: Anchor;
+}
+
+/** References are either resolved occurrences or honestly absent. */
+export type SymbolReferences =
+  | { resolvable: true; items: SymbolReference[] }
+  | { resolvable: false; reason: string };
+
+export interface SymbolResult {
+  trust: "measured";
+  name: string;
+  /** Empty (not an error) when the symbol is unknown to ctags. */
+  definitions: SymbolDefinition[];
+  /** Present only when references were requested. */
+  references?: SymbolReferences;
+}
+
+export class SymbolsError extends Error {
+  constructor(message: string) {
+    super(`symbols: ${message}`);
+    this.name = "SymbolsError";
+  }
+}
+
+/** The subset of universal-ctags JSON output the tool consumes. */
+interface TagRecord {
+  _type?: string;
+  name?: unknown;
+  path?: unknown;
+  line?: unknown;
+  kind?: unknown;
+}
+
+/**
+ * Names shorter than this cannot be corroborated by a text sweep without
+ * guessing (design.md, decision 2): their references stay honestly absent.
+ */
+const MIN_REFERENCE_NAME_LENGTH = 4;
+
+/** Run ctags over the target and return every usable tag record. */
+function runCtags(targetRoot: string, env: Env): TagRecord[] {
+  const ctags = findBinary("ctags", env);
+  if (!ctags) throw new MissingBinaryError("ctags", "symbols");
+  const run = spawnSync(
+    ctags,
+    ["--output-format=json", "--fields=+nK", "-f", "-", "--recurse", "."],
+    { cwd: targetRoot, env, encoding: "utf8", maxBuffer: 512 * 1024 * 1024 },
+  );
+  if (run.error) throw new MissingBinaryError("ctags", "symbols");
+  if (run.status !== 0) {
+    const reason =
+      firstLine(run.stderr ?? "") || `ctags exited with code ${run.status}`;
+    throw new SymbolsError(`ctags failed: ${reason}`);
+  }
+  const records: TagRecord[] = [];
+  for (const raw of (run.stdout ?? "").split("\n")) {
+    if (raw.trim().length === 0) continue;
+    let record: TagRecord;
+    try {
+      record = JSON.parse(raw) as TagRecord;
+    } catch {
+      throw new SymbolsError(
+        `ctags emitted unparseable output: ${raw.slice(0, 120)}`,
+      );
+    }
+    // Pseudo-tags and any non-tag records carry no symbol evidence.
+    if (record._type !== undefined && record._type !== "tag") continue;
+    if (typeof record.name !== "string" || typeof record.path !== "string") continue;
+    records.push(record);
+  }
+  return records;
+}
+
+/** Look up `name` in `targetRoot` through ctags; results labeled `measured`. */
+export function symbols(
+  targetRoot: string,
+  name: string,
+  options: SymbolOptions = {},
+): SymbolResult {
+  const env: Env = options.env ?? process.env;
+  let isDir = false;
+  try {
+    isDir = statSync(targetRoot).isDirectory();
+  } catch {
+    // fall through to the honest error below
+  }
+  if (!isDir) {
+    throw new SymbolsError(`target root ${targetRoot} is not a directory`);
+  }
+
+  const all = runCtags(targetRoot, env);
+  const definitions: SymbolDefinition[] = [];
+  for (const record of all) {
+    if (record.name !== name || typeof record.line !== "number") continue;
+    const path = relativeToTarget(record.path as string, targetRoot);
+    const line = record.line;
+    definitions.push({
+      name,
+      kind: typeof record.kind === "string" ? record.kind : "unknown",
+      path,
+      line,
+      anchor: { type: "file", path, line },
+    });
+  }
+  definitions.sort((a, b) =>
+    a.path === b.path ? a.line - b.line : a.path < b.path ? -1 : 1,
+  );
+
+  let references: SymbolReferences | undefined;
+  if (options.references) {
+    if (name.length < MIN_REFERENCE_NAME_LENGTH) {
+      references = {
+        resolvable: false,
+        reason:
+          `the name "${name}" is too short or too common to corroborate by ` +
+          `sweep; references are reported as not resolvable rather than guessed`,
+      };
+    } else {
+      // Corroborating sweep of the name; definition sites are excluded so
+      // what remains are occurrences, never the definition itself.
+      const swept = sweep(targetRoot, `\\b${escapeRegExp(name)}\\b`, { env });
+      const definitionSites = new Set(
+        definitions.map((d) => `${d.path}:${d.line}`),
+      );
+      const items = swept.chunks
+        .filter((chunk) => !definitionSites.has(`${chunk.path}:${chunk.line}`))
+        .map((chunk) => ({
+          path: chunk.path,
+          line: chunk.line,
+          text: chunk.text,
+          anchor: chunk.anchor,
+        }));
+      references = { resolvable: true, items };
+    }
+  }
+
+  return {
+    trust: "measured",
+    name,
+    definitions,
+    ...(references !== undefined ? { references } : {}),
+  };
+}

package/core/src/tools/trust-report.ts

@@ -0,0 +1,193 @@
+/**
+ * `trust.report`: the province's verification summary in one call
+ * (openspec/changes/verification-spine). Aggregates the chart — trust-label
+ * distribution, per-kind counts, staleness — and re-sounds every anchor
+ * live through the existing `sound.anchor` machinery, so the report states
+ * what holds now, not what the index last claimed. Refuted anchors are
+ * named, never smoothed over — including a citation so malformed that
+ * `sound.anchor` refuses it (a hand-edited index): it counts as refuted
+ * with the refusal as its finding, so one planted anchor cannot sink the
+ * report. Adoption counts the mandated query tools' invocations from the
+ * ship's log — invocation facts, never a measure of mandate compliance.
+ *
+ * Refreshes staleness first, exactly as `chart.read` does; that refresh is
+ * the only write the report may cause (inside `.portolan/`, per the
+ * refresh's own contract). No receipt is appended.
+ */
+import type { Anchor, EntryKind, TrustLabel } from "../types";
+import { ENTRY_KINDS, TRUST_LABELS } from "../types";
+import { readChart } from "../chart-store";
+import { chargeStaleEntries, compareVesselRank, vesselFanIn } from "../fan-in";
+import { refreshStaleness } from "../staleness";
+import { readReceipts, type Receipt } from "./log";
+import { SoundingError, soundAnchor } from "./sound";
+
+/**
+ * The mandated query tools whose invocations the report must account for
+ * (specs/invocation/spec.md: a query tool ships only with a per-tool
+ * adoption counter). A future mandated tool just appends here.
+ */
+export const ADOPTION_TOOLS = ["chart.neighborhood"] as const;
+
+/** The concrete tools in the adoption registry. */
+export type MandatedQueryTool = (typeof ADOPTION_TOOLS)[number];
+
+/** Invocation facts for one mandated query tool, read from the ship's log. */
+export interface ToolAdoption {
+  /** Receipts in the log whose command names the tool. */
+  invocations: number;
+  /** First invocation's receipt id; null when the log holds none. */
+  firstReceipt: string | null;
+  /** Most recent invocation's receipt id; null when the log holds none. */
+  lastReceipt: string | null;
+}
+
+/** One refuted anchor: the entry that cites it, the citation, what was found. */
+export interface RefutedAnchor {
+  /** The citing entry's chart id. */
+  entryId: string;
+  /** The anchor exactly as cited by the entry. */
+  anchor: Anchor;
+  /** What the sounding actually found at the citation. */
+  found: string;
+}
+
+/** One vessel dragging entries into `pending correction`. */
+export interface PendingVessel {
+  id: string;
+  /** Chart entries marked pending correction that hang from this vessel. */
+  entries: number;
+}
+
+/** What `trust.report` returns: the one-call verification summary. */
+export interface TrustReport {
+  /** Chart entries per trust label; all five labels stated, zero-filled. */
+  trust: Record<TrustLabel, number>;
+  /** Chart entries per kind; all six kinds stated, zero-filled. */
+  kinds: Record<EntryKind, number>;
+  /** Pending-correction vessels, in the repair rank's order (../fan-in.ts), read from the chart's stale flags after the refresh. */
+  staleness: { pendingVessels: PendingVessel[] };
+  /** Live re-sounding of every chart anchor. */
+  anchors: {
+    /** Anchors cited on the chart. */
+    total: number;
+    /** Anchors sounded — equal to `total` by construction: no sampling. */
+    sounded: number;
+    /** Soundings that resolved `confirmed`. */
+    confirmed: number;
+    /** Soundings that resolved `refuted`. */
+    refuted: number;
+    /** Every refuted anchor, sorted by entry id then anchor index. */
+    refutedList: RefutedAnchor[];
+  };
+  /** The ship's log: total receipts and the most recent one (null on an empty log). */
+  log: { receipts: number; lastReceipt: Receipt | null };
+  /** Per-tool invocation facts for every mandated query tool, zero-filled. */
+  adoption: { tools: Record<MandatedQueryTool, ToolAdoption> };
+}
+
+/**
+ * A receipt's command names the tool when it is the bare tool name or the
+ * tool followed by its arguments ("chart.neighborhood vessel=tug").
+ */
+function namesTool(command: string, tool: MandatedQueryTool): boolean {
+  return command === tool || command.startsWith(`${tool} `);
+}
+
+/**
+ * `trust.report`: the one-call verification summary. Deterministic — no
+ * timestamps participate, so two runs over an unchanged province return the
+ * same report, refuted list in the same order.
+ */
+export function trustReport(targetRoot: string): TrustReport {
+  // Staleness first, chart.read semantics: the staleness section is never
+  // served from a stale signature. This is the report's only possible write.
+  refreshStaleness(targetRoot);
+  const entries = readChart(targetRoot);
+
+  const trust = Object.fromEntries(TRUST_LABELS.map((l) => [l, 0])) as Record<TrustLabel, number>;
+  const kinds = Object.fromEntries(ENTRY_KINDS.map((k) => [k, 0])) as Record<EntryKind, number>;
+  for (const entry of entries) {
+    trust[entry.trust] += 1;
+    kinds[entry.kind] += 1;
+  }
+
+  // The queue's voice (openspec/changes/resurvey-queue/specs/tools/spec.md):
+  // pending vessels list in the repair rank's order — fan-in desc, vessel id
+  // — while membership stays this report's own attribution: a stale fairway
+  // charges both endpoints, so the list names vessels the repair queue does
+  // not.
+  const pending = chargeStaleEntries(entries);
+  const fanIn = vesselFanIn(entries);
+  const pendingVessels = [...pending.keys()]
+    .sort((a, b) => compareVesselRank(a, b, fanIn))
+    .map((id) => ({ id, entries: pending.get(id)! }));
+
+  const refuted: (RefutedAnchor & { index: number })[] = [];
+  let confirmed = 0;
+  let total = 0;
+  for (const entry of entries) {
+    for (const [index, anchor] of entry.anchors.entries()) {
+      total += 1;
+      let verdict: ReturnType<typeof soundAnchor>;
+      try {
+        verdict = soundAnchor(targetRoot, { anchor });
+      } catch (err) {
+        if (!(err instanceof SoundingError)) throw err;
+        // A non-citable anchor (plantable by a hand-edited index) is
+        // refuted by name like any other unresolvable citation — one bad
+        // citation never sinks the whole report, and the report never
+        // sounds fewer anchors than the chart cites.
+        refuted.push({ entryId: entry.id, anchor, index, found: err.message });
+        continue;
+      }
+      if (verdict.verdict === "confirmed") confirmed += 1;
+      else {
+        // sound.anchor yields confirmed or refuted only; its evidence names
+        // what was actually found — the one-line summary is the fallback so
+        // the cross-module evidence invariant is not assumed blindly here.
+        refuted.push({
+          entryId: entry.id,
+          anchor,
+          index,
+          found: verdict.evidence[0]?.found ?? verdict.report,
+        });
+      }
+    }
+  }
+  refuted.sort((a, b) =>
+    a.entryId < b.entryId ? -1 : a.entryId > b.entryId ? 1 : a.index - b.index,
+  );
+  const refutedList: RefutedAnchor[] = refuted.map(({ index: _index, ...r }) => r);
+
+  const receipts = readReceipts(targetRoot);
+  // Append-only log: file order is invocation order, so first/last by it.
+  const adoption = Object.fromEntries(
+    ADOPTION_TOOLS.map((tool) => {
+      const mine = receipts.filter((receipt) => namesTool(receipt.command, tool));
+      const stat: ToolAdoption = {
+        invocations: mine.length,
+        firstReceipt: mine[0]?.id ?? null,
+        lastReceipt: mine.length > 0 ? mine[mine.length - 1]!.id : null,
+      };
+      return [tool, stat] as const;
+    }),
+  ) as Record<MandatedQueryTool, ToolAdoption>;
+  return {
+    trust,
+    kinds,
+    staleness: { pendingVessels },
+    anchors: {
+      total,
+      sounded: total,
+      confirmed,
+      refuted: refutedList.length,
+      refutedList,
+    },
+    log: {
+      receipts: receipts.length,
+      lastReceipt: receipts.length > 0 ? receipts[receipts.length - 1]! : null,
+    },
+    adoption: { tools: adoption },
+  };
+}