@oevery/rsp 4.0.0 → 4.2.0

package/dist/chunk-LGDCIQYL.mjs

@@ -0,0 +1,725 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_DECISION_RECORDS_PATH,
+  OBSOLETE_RSP_RULES_PATH,
+  RSP_DIR,
+  inspectManagedFile,
+  inspectManagedFileTree,
+  inspectRspConfig,
+  markdownText,
+  parseFrontmatter,
+  parseMarkdown,
+  pc,
+  resolveDecisionRecordsPath,
+  validateDecisionRecordsFilesystemPath
+} from "./chunk-P3KO3GZW.mjs";
+
+// src/core/output.ts
+import pc2 from "picocolors";
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function emitJson(data, options = {}) {
+  const indentation = options.compact ? void 0 : 2;
+  process.stdout.write(`${JSON.stringify(data, null, indentation)}
+`);
+}
+
+// src/core/filesystem.ts
+import { existsSync } from "fs";
+import { readdir, readFile, rmdir } from "fs/promises";
+import { basename, dirname, join, relative, sep } from "path";
+async function walkMarkdownFiles(dir, options = {}) {
+  const all = await walkFiles(dir, options);
+  return all.filter((f) => f.endsWith(".md"));
+}
+async function inspectUnsupportedRules() {
+  const rulesDir = join(RSP_DIR, "rules");
+  const diagnostics = [];
+  const rawEntries = await walkAllEntries(rulesDir, diagnostics);
+  const entries = rawEntries.filter((entry) => entry.path !== OBSOLETE_RSP_RULES_PATH).map((entry) => ({ path: normalizeLogicalPath(relative(rulesDir, entry.path)), kind: entry.kind }));
+  return {
+    entries,
+    diagnostics,
+    directoryRemaining: entries.length > 0
+  };
+}
+async function walkAllEntries(dir, diagnostics) {
+  const entries = [];
+  try {
+    const items = await readdir(dir, { withFileTypes: true });
+    for (const item of items) {
+      const path = join(dir, item.name);
+      const kind = item.isDirectory() ? "directory" : "file";
+      entries.push({ path, kind });
+      if (kind === "directory")
+        entries.push(...await walkAllEntries(path, diagnostics));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      diagnostics.push({ code: "walk_failed", operation: "readdir", path: dir, message: toErrorMessage(error) });
+    }
+  }
+  return entries;
+}
+async function walkFiles(dir, options = {}) {
+  const files = [];
+  try {
+    const items = await readdir(dir, { withFileTypes: true });
+    for (const item of items) {
+      if (item.name.startsWith("."))
+        continue;
+      const filePath = join(dir, item.name);
+      if (item.isDirectory())
+        files.push(...await walkFiles(filePath, options));
+      else
+        files.push(filePath);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      options.onError?.({ code: "walk_failed", operation: "readdir", path: dir, message: toErrorMessage(error) });
+    }
+  }
+  return files;
+}
+function normalizeLogicalPath(pathValue) {
+  return pathValue.split(sep).join("/").replace(/\\/g, "/");
+}
+var SPEC_NAME_RE = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
+function isValidSpecName(name) {
+  return SPEC_NAME_RE.test(name);
+}
+function inspectRspInitialization() {
+  const designPath = join(RSP_DIR, "specs", "design.md");
+  const design = inspectManagedFile(designPath, "design Spec", { allowMissing: true });
+  if (design.issue)
+    return `${design.issue.message}
+  Check path types and permissions; init/update do not repair existing user content.`;
+  if (design.exists)
+    return void 0;
+  return existsSync(RSP_DIR) ? `${designPath} is missing.
+  Restore your design file, or run rsp init to create missing scaffolding.` : "RSP is not initialized in this project\n  Run: rsp init";
+}
+function guardRspInitialized() {
+  const issue = inspectRspInitialization();
+  if (issue) {
+    console.error(`  ${pc.red("Error:")} ${issue}`);
+    process.exit(1);
+  }
+}
+async function cleanupEmptyParentDirs(path, stopDir) {
+  let parent = dirname(path);
+  while (parent !== stopDir) {
+    try {
+      const remaining = await readdir(parent);
+      if (remaining.length === 0)
+        await rmdir(parent);
+      else
+        break;
+    } catch {
+      break;
+    }
+    parent = dirname(parent);
+  }
+}
+async function detectProjectName() {
+  try {
+    if (existsSync("package.json")) {
+      const raw = await readFile("package.json", "utf-8");
+      const pkg = JSON.parse(raw);
+      if (pkg.name && pkg.name !== "")
+        return pkg.name;
+    }
+  } catch {
+  }
+  return basename(process.cwd());
+}
+
+// src/specs/model.ts
+var SPECS_DEFAULT_RESULT_LIMIT = 20;
+var SPECS_MAX_RESULT_LIMIT = 100;
+var SPECS_MAX_CANDIDATES = 1e3;
+var SPECS_MAX_FILE_BYTES = 512 * 1024;
+var SPECS_SEARCH_EXCERPT_CODE_POINTS = 240;
+var SPECS_DETAIL_CONTENT_CODE_POINTS = 12e3;
+var SPECS_MAX_DIAGNOSTICS = 20;
+
+// src/specs/query.ts
+import { Buffer } from "buffer";
+import { spawnSync } from "child_process";
+import { constants } from "fs";
+import { lstat, open, realpath } from "fs/promises";
+import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative as relative2, resolve, sep as sep2 } from "path";
+var SPECS_ROOT = join2(RSP_DIR, "specs");
+var GENERATED_INDEX_FILENAME = "00-index.md";
+var LEGACY_GENERATED_INDEX_FILENAME = "INDEX.md";
+var READ_NO_FOLLOW_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);
+var SpecsQueryError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SpecsQueryError";
+  }
+  code;
+};
+async function inspectSpecs(options = {}) {
+  const projectRoot = await realpath(resolve(options.cwd ?? process.cwd()));
+  const specsRoot = resolve(projectRoot, SPECS_ROOT);
+  const maxCandidates = options.maxCandidates ?? SPECS_MAX_CANDIDATES;
+  const maxFileBytes = options.maxFileBytes ?? SPECS_MAX_FILE_BYTES;
+  validatePositiveBound(maxCandidates, "maxCandidates");
+  validatePositiveBound(maxFileBytes, "maxFileBytes");
+  const configInspection = await inspectRspConfig(projectRoot);
+  if (configInspection.issues.length > 0)
+    throw new SpecsQueryError("invalid_config", configInspection.issues.join("; "));
+  const decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+  const decisionPathIssue = await validateDecisionRecordsFilesystemPath(decisionRecordsPath, projectRoot);
+  if (decisionPathIssue)
+    throw new SpecsQueryError("invalid_decision_records_path", decisionPathIssue);
+  const decisionRecordsRoot = resolve(projectRoot, decisionRecordsPath);
+  const accumulator = {
+    documents: [],
+    generatedIndexes: [],
+    diagnostics: [],
+    candidateCount: 0,
+    candidateLimitReported: false
+  };
+  const excludedSpecDirectories = [DEFAULT_DECISION_RECORDS_PATH, decisionRecordsPath].map((path) => resolve(projectRoot, path)).filter((path) => isInside(specsRoot, path));
+  await inspectDocumentRoot({
+    projectRoot,
+    root: specsRoot,
+    label: "Specs",
+    kind: "spec",
+    excludedDirectories: excludedSpecDirectories,
+    accumulator,
+    maxCandidates,
+    maxFileBytes,
+    allowMissing: false
+  });
+  await inspectDocumentRoot({
+    projectRoot,
+    root: decisionRecordsRoot,
+    label: "Decision Records",
+    kind: "decision-record",
+    excludedDirectories: [],
+    accumulator,
+    maxCandidates,
+    maxFileBytes,
+    allowMissing: options.allowMissingDecisionRecords === true
+  });
+  detectPathCollisions(accumulator);
+  accumulator.documents.sort(compareDocument);
+  accumulator.generatedIndexes.sort((left, right) => left.path.localeCompare(right.path));
+  const boundedDiagnostics = accumulator.diagnostics.slice(0, SPECS_MAX_DIAGNOSTICS);
+  return {
+    source: await inspectSourceIdentity(projectRoot),
+    roots: {
+      specs: toProjectPath(projectRoot, specsRoot),
+      decisions: toProjectPath(projectRoot, decisionRecordsRoot)
+    },
+    tree: buildDirectoryTree(projectRoot, specsRoot, "spec", accumulator.documents),
+    decisionRecords: buildDirectoryTree(projectRoot, decisionRecordsRoot, "decision-record", accumulator.documents),
+    documents: accumulator.documents.map(stripSource),
+    generatedIndexes: accumulator.generatedIndexes,
+    diagnostics: boundedDiagnostics,
+    diagnosticSummary: {
+      total: accumulator.diagnostics.length,
+      returned: boundedDiagnostics.length,
+      hasMore: accumulator.diagnostics.length > boundedDiagnostics.length
+    },
+    runtime: [],
+    limits: {
+      candidates: maxCandidates,
+      fileBytes: maxFileBytes,
+      results: SPECS_MAX_RESULT_LIMIT,
+      searchExcerptCodePoints: SPECS_SEARCH_EXCERPT_CODE_POINTS,
+      detailContentCodePoints: SPECS_DETAIL_CONTENT_CODE_POINTS
+    }
+  };
+}
+function specsInspectionComplete(inspection) {
+  return inspection.diagnostics.every((diagnostic) => diagnostic.severity !== "error");
+}
+async function readSpecsDetail(inspection, projectPath) {
+  const current = await readCurrentSpecsDocument(inspection, projectPath);
+  const bounded = boundCodePoints(current.content, SPECS_DETAIL_CONTENT_CODE_POINTS);
+  return {
+    ...current,
+    content: bounded.value,
+    contentTruncated: bounded.truncated
+  };
+}
+async function readCurrentSpecsDocument(inspection, projectPath) {
+  const normalized = normalizeRequestedPath(projectPath);
+  const document = inspection.documents.find((candidate) => candidate.path === normalized);
+  if (!document)
+    throw new SpecsQueryError("specs_document_not_found", `Specs document not found: ${projectPath}`);
+  const sourcePath = resolve(inspection.source.root, normalized);
+  const current = await readCurrentDocument(
+    sourcePath,
+    inspection.source.root,
+    document.path,
+    inspection.limits.fileBytes
+  );
+  const currentDocument = parseDocumentRecord(parseMarkdown(current.content), current.bytes, document.path, document.kind);
+  return {
+    ...currentDocument,
+    content: current.content
+  };
+}
+async function searchSpecs(inspection, literal, options = {}) {
+  return (await searchSpecsWithSources(inspection, literal, options)).result;
+}
+async function searchSpecsWithSources(inspection, literal, options = {}) {
+  const query = literal.trim();
+  if (query === "")
+    throw new SpecsQueryError("invalid_specs_search", "Specs search literal must be non-empty");
+  const limit = options.limit ?? 20;
+  if (!Number.isInteger(limit) || limit < 1 || limit > SPECS_MAX_RESULT_LIMIT)
+    throw new SpecsQueryError("invalid_specs_limit", `Specs search limit must be an integer from 1 through ${SPECS_MAX_RESULT_LIMIT}`);
+  const excerptCodePoints = options.excerptCodePoints ?? SPECS_SEARCH_EXCERPT_CODE_POINTS;
+  if (!Number.isInteger(excerptCodePoints) || excerptCodePoints < 40 || excerptCodePoints > 1e3)
+    throw new SpecsQueryError("invalid_specs_excerpt", "Specs search excerpt must be an integer from 40 through 1000 code points");
+  const lowered = query.toLowerCase();
+  const matches = [];
+  const documents = /* @__PURE__ */ new Map();
+  let matched = 0;
+  for (const document of inspection.documents) {
+    const current = await readCurrentDocument(
+      resolve(inspection.source.root, document.path),
+      inspection.source.root,
+      document.path,
+      inspection.limits.fileBytes
+    );
+    const currentDocument = parseDocumentRecord(parseMarkdown(current.content), current.bytes, document.path, document.kind);
+    const lines = current.content.split(/\r?\n/);
+    const headingsByLine = new Map(currentDocument.headings.map((item) => [item.line, item.title]));
+    let heading = null;
+    for (let index = 0; index < lines.length; index++) {
+      heading = headingsByLine.get(index + 1) ?? heading;
+      const position = lines[index].toLowerCase().indexOf(lowered);
+      if (position < 0)
+        continue;
+      matched += 1;
+      if (matches.length < limit) {
+        if (!documents.has(document.path)) {
+          documents.set(document.path, {
+            ...currentDocument,
+            content: current.content
+          });
+        }
+        matches.push({
+          path: document.path,
+          kind: document.kind,
+          title: currentDocument.title,
+          heading,
+          line: index + 1,
+          excerpt: excerptAround(
+            lines[index],
+            [...lines[index].slice(0, position)].length,
+            [...query].length,
+            excerptCodePoints
+          )
+        });
+      }
+    }
+  }
+  return {
+    result: {
+      matches,
+      summary: {
+        candidates: inspection.documents.length,
+        searched: inspection.documents.length,
+        matched,
+        returned: matches.length,
+        hasMore: matched > matches.length
+      }
+    },
+    documents
+  };
+}
+async function inspectDocumentRoot(options) {
+  const inspection = await inspectManagedFileTree(options.root, options.label, { allowMissing: options.allowMissing });
+  for (const issue of inspection.issues) {
+    options.accumulator.diagnostics.push({
+      severity: "error",
+      code: "specs_tree_invalid",
+      path: toProjectPath(options.projectRoot, issue.path),
+      message: issue.message
+    });
+  }
+  if (!inspection.rootExists)
+    return;
+  for (const path of inspection.files) {
+    if (options.excludedDirectories.some((directory) => isInside(directory, path)))
+      continue;
+    const projectPath = toProjectPath(options.projectRoot, path);
+    const reserved = reservedIndexKind(options.root, path);
+    if (reserved) {
+      await classifyGeneratedIndex(path, options.projectRoot, projectPath, options.maxFileBytes, options.accumulator);
+      continue;
+    }
+    if (!path.endsWith(".md"))
+      continue;
+    options.accumulator.candidateCount += 1;
+    if (options.accumulator.candidateCount > options.maxCandidates) {
+      if (!options.accumulator.candidateLimitReported) {
+        options.accumulator.diagnostics.push({
+          severity: "error",
+          code: "specs_candidate_limit_exceeded",
+          path: projectPath,
+          message: `Specs candidate limit exceeded (${options.maxCandidates})`
+        });
+        options.accumulator.candidateLimitReported = true;
+      }
+      continue;
+    }
+    await inspectDocument(path, options.projectRoot, projectPath, options.kind, options.maxFileBytes, options.accumulator);
+  }
+}
+async function classifyGeneratedIndex(path, projectRoot, projectPath, maxFileBytes, accumulator) {
+  try {
+    const current = await readCurrentDocument(path, projectRoot, projectPath, maxFileBytes);
+    const recognized = isRecognizedGeneratedSpecsIndex(current.content, projectPath);
+    accumulator.generatedIndexes.push({
+      path: projectPath,
+      classification: recognized ? "safe-removal" : "owner-controlled",
+      reason: recognized ? "metadata recognizes the reserved path as a generated Specs index" : "reserved path content is not recognized generated Specs-index output"
+    });
+    if (!recognized) {
+      accumulator.diagnostics.push({
+        severity: "error",
+        code: "unrecognized_reserved_specs_index",
+        path: projectPath,
+        message: `reserved Specs index is owner-controlled and cannot be treated as generated content: ${projectPath}`
+      });
+    }
+  } catch (error) {
+    accumulator.generatedIndexes.push({
+      path: projectPath,
+      classification: "owner-controlled",
+      reason: "reserved path could not be boundedly inspected as generated Specs-index output"
+    });
+    accumulator.diagnostics.push({
+      severity: "error",
+      code: error instanceof SpecsQueryError ? error.code : "specs_index_read_failed",
+      path: projectPath,
+      message: `unable to inspect reserved Specs index ${projectPath}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+}
+function isRecognizedGeneratedSpecsIndex(content, projectPath) {
+  const metadata = parseFrontmatter(content);
+  const expectedSourceDirectory = normalizeLogicalPath(dirname2(projectPath));
+  return metadata?.kind === "generated-index" && metadata.index_type === "specs" && metadata.source_dir === expectedSourceDirectory;
+}
+async function inspectDocument(path, projectRoot, projectPath, kind, maxFileBytes, accumulator) {
+  try {
+    const current = await readCurrentDocument(path, projectRoot, projectPath, maxFileBytes);
+    const document = parseMarkdown(current.content);
+    const metadata = parseFrontmatter(document);
+    if (metadata?.kind === "generated-index")
+      return;
+    accumulator.documents.push({
+      sourcePath: path,
+      ...parseDocumentRecord(document, current.bytes, projectPath, kind, metadata)
+    });
+  } catch (error) {
+    accumulator.diagnostics.push({
+      severity: "error",
+      code: error instanceof SpecsQueryError ? error.code : "specs_file_read_failed",
+      path: projectPath,
+      message: `unable to read Specs document ${projectPath}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+}
+function detectPathCollisions(accumulator) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const document of accumulator.documents) {
+    const canonical = document.path.normalize("NFC");
+    const existing = seen.get(canonical);
+    if (existing && existing !== document.path) {
+      accumulator.diagnostics.push({
+        severity: "error",
+        code: "specs_path_collision",
+        path: document.path,
+        message: `Specs path normalization collision: ${existing} and ${document.path}`
+      });
+    } else {
+      seen.set(canonical, document.path);
+    }
+    if (canonical !== document.path) {
+      accumulator.diagnostics.push({
+        severity: "error",
+        code: "specs_path_not_canonical",
+        path: document.path,
+        message: `Specs path must use canonical NFC form: ${document.path}`
+      });
+    }
+  }
+}
+function buildDirectoryTree(projectRoot, root, kind, documents) {
+  const rootPath = toProjectPath(projectRoot, root);
+  const tree = {
+    name: basename2(root),
+    path: rootPath,
+    directories: [],
+    documents: []
+  };
+  for (const document of documents.filter((candidate) => candidate.kind === kind)) {
+    const rel = relative2(root, document.sourcePath);
+    if (rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute(rel))
+      continue;
+    const segments = normalizeLogicalPath(rel).split("/");
+    let current = tree;
+    for (const segment of segments.slice(0, -1)) {
+      let child = current.directories.find((directory) => directory.name === segment);
+      if (!child) {
+        child = {
+          name: segment,
+          path: `${current.path}/${segment}`,
+          directories: [],
+          documents: []
+        };
+        current.directories.push(child);
+        current.directories.sort((left, right) => left.name.localeCompare(right.name));
+      }
+      current = child;
+    }
+    current.documents.push(stripSource(document));
+    current.documents.sort(compareDocument);
+  }
+  return tree;
+}
+function extractHeadings(document) {
+  return document.root.children.flatMap((node) => node.type === "heading" ? [{ depth: node.depth, title: markdownText(node), line: node.position.start.line }] : []);
+}
+function extractSummary(document, frontmatterSummary) {
+  if (typeof frontmatterSummary === "string" && frontmatterSummary.trim() !== "")
+    return frontmatterSummary.trim();
+  for (const node of document.root.children) {
+    if (node.type !== "paragraph" && node.type !== "list")
+      continue;
+    const text = markdownText(node).split("\n", 1)[0].trim();
+    if (text)
+      return text;
+  }
+  return null;
+}
+async function inspectSourceIdentity(projectRoot) {
+  const root = normalizeLogicalPath(projectRoot);
+  const head = runGit(["rev-parse", "HEAD"], projectRoot);
+  const branch = runGit(["symbolic-ref", "--quiet", "--short", "HEAD"], projectRoot);
+  const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=normal"], {
+    cwd: root,
+    encoding: "utf-8",
+    maxBuffer: 256 * 1024
+  });
+  return {
+    root,
+    gitHead: head,
+    gitBranch: branch,
+    dirty: status.status === 0 ? status.stdout.trim() !== "" : status.error && status.error.code === "ENOBUFS" ? true : null
+  };
+}
+function runGit(args, cwd) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf-8", maxBuffer: 64 * 1024 });
+  return result.status === 0 ? result.stdout.trim() || null : null;
+}
+function normalizeRequestedPath(pathValue) {
+  const trimmed = pathValue.trim();
+  if (trimmed === "")
+    throw new SpecsQueryError("invalid_specs_path", "Specs detail path must be non-empty");
+  const normalized = normalizeLogicalPath(trimmed.replace(/^\.\//, ""));
+  if (isAbsolute(trimmed) || normalized === ".." || normalized.startsWith("../"))
+    throw new SpecsQueryError("invalid_specs_path", "Specs detail path must be one project-relative path returned by rsp specs");
+  return normalized;
+}
+function reservedIndexKind(root, path) {
+  if (basename2(path) === GENERATED_INDEX_FILENAME)
+    return "current";
+  if (path === join2(root, LEGACY_GENERATED_INDEX_FILENAME))
+    return "legacy";
+  return null;
+}
+function excerptAround(line, matchStart, matchLength, limit) {
+  const codePoints = [...line];
+  if (codePoints.length <= limit)
+    return codePoints.join("").trim();
+  const before = Math.max(0, matchStart - Math.floor((limit - matchLength) / 2));
+  const value = codePoints.slice(before, before + limit).join("").trim();
+  return `${before > 0 ? "\u2026" : ""}${value}${before + limit < codePoints.length ? "\u2026" : ""}`;
+}
+async function readCurrentDocument(path, root, projectPath, maxFileBytes, binary = false) {
+  const changed = () => new SpecsQueryError("specs_file_changed", `Specs document is no longer a readable regular file: ${projectPath}`);
+  const sourcePath = resolve(path);
+  const sourceRoot = resolve(root);
+  const relativePath = relative2(sourceRoot, sourcePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep2}`) || isAbsolute(relativePath)) {
+    throw changed();
+  }
+  const inspection = inspectManagedFile(sourcePath, "Specs document");
+  if (inspection.issue)
+    throw changed();
+  let inspectedRoot;
+  let inspected;
+  let realRoot;
+  try {
+    inspectedRoot = await lstat(sourceRoot, { bigint: true });
+    inspected = await lstat(sourcePath, { bigint: true });
+    realRoot = await realpath(sourceRoot);
+    const resolvedPath = await realpath(sourcePath);
+    if (!inspectedRoot.isDirectory() || !inspected.isFile() || resolvedPath !== resolve(realRoot, relativePath) || !isContained(realRoot, resolvedPath)) {
+      throw changed();
+    }
+  } catch (error) {
+    if (error instanceof SpecsQueryError)
+      throw error;
+    throw changed();
+  }
+  let handle;
+  try {
+    handle = await open(sourcePath, READ_NO_FOLLOW_FLAGS);
+  } catch {
+    throw changed();
+  }
+  try {
+    const opened = await handle.stat({ bigint: true });
+    const currentRoot = await realpath(sourceRoot);
+    const currentPath = await realpath(sourcePath);
+    if (!opened.isFile() || currentRoot !== realRoot || currentPath !== resolve(currentRoot, relativePath) || !isContained(currentRoot, currentPath) || !sameIdentity(inspected, opened) || !sameSnapshot(inspected, opened)) {
+      throw changed();
+    }
+    if (opened.size > BigInt(maxFileBytes))
+      throw new SpecsQueryError("specs_file_too_large", `Specs document exceeds the ${maxFileBytes}-byte inspection limit: ${projectPath}`);
+    const current = await readBoundedDocument(handle, opened, projectPath, maxFileBytes, binary);
+    await validateCurrentSpecsPath({
+      sourcePath,
+      sourceRoot,
+      relativePath,
+      realRoot,
+      inspectedRoot,
+      finalHandle: current.final,
+      projectPath
+    });
+    return {
+      content: current.content,
+      bytes: current.bytes,
+      ...current.data ? { data: current.data } : {}
+    };
+  } catch (error) {
+    if (error instanceof SpecsQueryError)
+      throw error;
+    throw changed();
+  } finally {
+    await handle.close();
+  }
+}
+async function readBoundedDocument(handle, opened, projectPath, maxFileBytes, binary) {
+  const buffer = Buffer.allocUnsafe(maxFileBytes + 1);
+  let bytes = 0;
+  while (bytes < buffer.length) {
+    const result = await handle.read(buffer, bytes, buffer.length - bytes, bytes);
+    if (result.bytesRead === 0)
+      break;
+    bytes += result.bytesRead;
+  }
+  const final = await handle.stat({ bigint: true });
+  if (bytes > maxFileBytes || final.size > BigInt(maxFileBytes))
+    throw new SpecsQueryError("specs_file_too_large", `Specs document exceeds the ${maxFileBytes}-byte inspection limit: ${projectPath}`);
+  if (!sameIdentity(opened, final) || !sameSnapshot(opened, final) || final.size !== BigInt(bytes)) {
+    throw new SpecsQueryError("specs_file_changed", `Specs document is no longer a readable regular file: ${projectPath}`);
+  }
+  return {
+    content: binary ? "" : buffer.subarray(0, bytes).toString("utf-8"),
+    ...binary ? { data: Buffer.from(buffer.subarray(0, bytes)) } : {},
+    bytes,
+    final
+  };
+}
+async function validateCurrentSpecsPath(options) {
+  const changed = () => new SpecsQueryError("specs_file_changed", `Specs document is no longer a readable regular file: ${options.projectPath}`);
+  try {
+    const currentRoot = await lstat(options.sourceRoot, { bigint: true });
+    const currentPath = await lstat(options.sourcePath, { bigint: true });
+    const realCurrentRoot = await realpath(options.sourceRoot);
+    const realCurrentPath = await realpath(options.sourcePath);
+    if (!currentRoot.isDirectory() || !currentPath.isFile() || !sameIdentity(options.inspectedRoot, currentRoot) || realCurrentRoot !== options.realRoot || realCurrentPath !== resolve(realCurrentRoot, options.relativePath) || !isContained(realCurrentRoot, realCurrentPath) || !sameIdentity(currentPath, options.finalHandle) || !sameSnapshot(currentPath, options.finalHandle)) {
+      throw changed();
+    }
+  } catch (error) {
+    if (error instanceof SpecsQueryError)
+      throw error;
+    throw changed();
+  }
+}
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot(left, right) {
+  return left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function isContained(root, path) {
+  const candidate = relative2(root, path);
+  return candidate !== "" && candidate !== ".." && !candidate.startsWith(`..${sep2}`) && !isAbsolute(candidate);
+}
+function boundCodePoints(value, limit) {
+  const codePoints = [...value];
+  return {
+    value: codePoints.slice(0, limit).join(""),
+    truncated: codePoints.length > limit
+  };
+}
+function stripSource(document) {
+  const { sourcePath: _sourcePath, ...record } = document;
+  return record;
+}
+function parseDocumentRecord(document, bytes, path, kind, metadata = parseFrontmatter(document)) {
+  const headings = extractHeadings(document);
+  return {
+    path,
+    kind,
+    title: typeof metadata?.title === "string" && metadata.title.trim() !== "" ? metadata.title.trim() : headings.find((heading) => heading.depth === 1)?.title ?? basename2(path, ".md"),
+    summary: extractSummary(document, metadata?.summary),
+    bytes,
+    headings
+  };
+}
+function compareDocument(left, right) {
+  return left.path.localeCompare(right.path);
+}
+function validatePositiveBound(value, label) {
+  if (!Number.isInteger(value) || value < 1)
+    throw new SpecsQueryError("invalid_specs_bound", `${label} must be a positive integer`);
+}
+function isInside(directory, path) {
+  const rel = relative2(directory, path);
+  return rel === "" || !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep2}`);
+}
+function toProjectPath(projectRoot, path) {
+  return normalizeLogicalPath(relative2(projectRoot, path)) || ".";
+}
+
+export {
+  toErrorMessage,
+  emitJson,
+  walkMarkdownFiles,
+  inspectUnsupportedRules,
+  normalizeLogicalPath,
+  isValidSpecName,
+  inspectRspInitialization,
+  guardRspInitialized,
+  cleanupEmptyParentDirs,
+  detectProjectName,
+  SPECS_DEFAULT_RESULT_LIMIT,
+  SPECS_MAX_RESULT_LIMIT,
+  SPECS_SEARCH_EXCERPT_CODE_POINTS,
+  SPECS_DETAIL_CONTENT_CODE_POINTS,
+  SpecsQueryError,
+  inspectSpecs,
+  specsInspectionComplete,
+  readSpecsDetail,
+  searchSpecs,
+  isRecognizedGeneratedSpecsIndex,
+  readCurrentDocument
+};