@agentskit/doc-bridge 1.4.1 → 1.5.0

package/src/fixes/proposals.ts

@@ -0,0 +1,165 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
+
+import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { FixProposalV1Schema, type FixProposalV1 } from '../schemas/knowledge.js'
+import { containedPath } from '../safety/repository.js'
+
+export type FixProposalOptions = {
+  readonly baseRevision: string
+  readonly configurationHash: string
+  readonly projectName?: string
+  readonly toolVersion?: string
+}
+
+export type FixApplyOptions = {
+  readonly currentRevision?: string
+  readonly verify?: (changedPaths: readonly string[]) => void
+}
+
+type FixChange = { readonly path: string; readonly before: string; readonly after: string }
+
+const hash = (value: unknown): string => sha256NormalizedV1(value)
+
+const artifactMetadata = (root: string, options: FixProposalOptions) => ({
+  schemaVersion: 1 as const,
+  contentHash: '0'.repeat(64),
+  contentHashAlgo: 'sha256-normalized-v1' as const,
+  project: { name: options.projectName ?? basename(resolve(root)), root: '.' },
+  sourceRevision: options.baseRevision,
+  sourceRevisionKind: options.baseRevision.length === 40 ? 'git' as const : 'content' as const,
+  configurationHash: options.configurationHash,
+  pipelineVersion: '1.0.0',
+  analyzerVersions: { fixes: options.toolVersion ?? '1.0.0' },
+})
+
+const unifiedDiff = (changes: readonly FixChange[]): string => changes.map((change) => {
+  const before = change.before.split('\n').map((line) => `-${line}`).join('\n')
+  const after = change.after.split('\n').map((line) => `+${line}`).join('\n')
+  return `--- a/${change.path}\n+++ b/${change.path}\n@@\n${before}\n${after}`
+}).join('\n')
+
+const makeProposal = (root: string, options: FixProposalOptions, changes: readonly FixChange[], preconditions: readonly string[], postconditions: readonly string[]): FixProposalV1 => {
+  const draft = {
+    ...artifactMetadata(root, options),
+    type: 'fix-proposal' as const,
+    proposalId: `fix-${hash(changes).slice(0, 20)}`,
+    baseRevision: options.baseRevision,
+    affectedFiles: changes.map(({ path, before }) => ({ path, contentHash: sha256NormalizedV1(before) })),
+    changes,
+    preconditions,
+    diff: unifiedDiff(changes),
+    postconditions,
+    status: 'proposed' as const,
+  }
+  return FixProposalV1Schema.parse({ ...draft, contentHash: contentHashForArtifactV1(draft) })
+}
+
+const walkMarkdown = (root: string, directory = root): string[] => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+  if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') return []
+  const path = join(directory, entry.name)
+  if (entry.isDirectory()) return walkMarkdown(root, path)
+  return entry.isFile() && ['.md', '.mdx'].includes(extname(entry.name).toLowerCase()) ? [relative(root, path).split(sep).join('/')] : []
+})
+
+const localLink = /(!?)\[([^\]]*)\]\(([^)\s]+)(?:\s+["'][^)]*["'])?\)/g
+
+const sortJson = (value: unknown): unknown => Array.isArray(value)
+  ? value.map(sortJson)
+  : value && typeof value === 'object'
+    ? Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sortJson(item)]))
+    : value
+
+export const createMarkdownLinkFixProposal = (root: string, options: FixProposalOptions): FixProposalV1 | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const paths = walkMarkdown(projectRoot)
+  const changes: FixChange[] = []
+  for (const path of paths) {
+    const content = readFileSync(join(projectRoot, path), 'utf8')
+    let next = content
+    for (const match of content.matchAll(localLink)) {
+      const target = match[3]
+      if (!target || match[1] === '!' || /^(?:[a-z]+:|\/|#)/i.test(target)) continue
+      const targetPath = target.split('#')[0]?.split('?')[0]
+      if (!targetPath || existsSync(resolve(projectRoot, dirname(path), targetPath))) continue
+      const targetStem = basename(targetPath, extname(targetPath)).toLowerCase()
+      const labelStem = (match[2] ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '')
+      const candidates = paths.filter((candidate) => basename(candidate, extname(candidate)).toLowerCase() === targetStem || basename(candidate, extname(candidate)).toLowerCase().replace(/[^a-z0-9]+/g, '') === labelStem)
+      if (candidates.length !== 1) continue
+      let replacement = relative(dirname(path), candidates[0]!).split(sep).join('/')
+      if (target.startsWith('./') && !replacement.startsWith('.')) replacement = `./${replacement}`
+      next = next.replace(match[0], match[0].replace(target, replacement))
+    }
+    if (next !== content) changes.push({ path, before: content, after: next })
+  }
+  return changes.length ? makeProposal(projectRoot, options, changes, ['Each replacement has exactly one Markdown target.'], ['All corrected local Markdown links resolve.']) : undefined
+}
+
+export const createArtifactNormalizationProposal = (root: string, artifactPath: string, options: FixProposalOptions): FixProposalV1 | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const path = artifactPath.split(sep).join('/')
+  const absolute = containedPath(projectRoot, path)
+  if (!absolute || !existsSync(absolute) || !statSync(absolute).isFile()) return undefined
+  const before = readFileSync(absolute, 'utf8')
+  let after: string
+  try { after = `${JSON.stringify(sortJson(JSON.parse(before) as unknown), null, 2)}\n` } catch { return undefined }
+  return after === before ? undefined : makeProposal(projectRoot, options, [{ path: relative(projectRoot, absolute).split(sep).join('/'), before, after }], ['The artifact contains valid JSON.'], ['The artifact is valid canonical JSON with one trailing newline.'])
+}
+
+export const approveFixProposal = (proposalInput: unknown, approvedBy: string, approvedAt = new Date().toISOString()): FixProposalV1 => {
+  const proposal = FixProposalV1Schema.parse(proposalInput)
+  if (proposal.status !== 'proposed') throw new Error(`Only proposed fixes can be approved; received "${proposal.status}".`)
+  const approved = { ...proposal, status: 'approved' as const, approval: { proposalHash: proposal.contentHash, approvedAt, approvedBy }, contentHash: '0'.repeat(64) }
+  return FixProposalV1Schema.parse({ ...approved, contentHash: contentHashForArtifactV1(approved) })
+}
+
+const bindingHash = (proposal: FixProposalV1): string => {
+  const { approval: _approval, contentHash: _contentHash, status: _status, ...rest } = proposal
+  return contentHashForArtifactV1({ ...rest, contentHash: '0'.repeat(64), status: 'proposed' as const })
+}
+
+export const applyFixProposal = (root: string, proposalInput: unknown, options: FixApplyOptions = {}): FixProposalV1 => {
+  const proposal = FixProposalV1Schema.parse(proposalInput)
+  if (proposal.status !== 'approved' || !proposal.approval) throw new Error('Only an explicitly approved fix proposal can be applied.')
+  if (proposal.approval.proposalHash !== bindingHash(proposal)) throw new Error('Approval is not bound to the exact proposal content.')
+  if (options.currentRevision && options.currentRevision !== proposal.baseRevision) throw new Error('The repository revision changed since this proposal was created.')
+  if (!proposal.changes?.length) throw new Error('This proposal has no executable changes.')
+
+  const projectRoot = realpathSync.native(resolve(root))
+  const originals = new Map<string, string>()
+  const affected = new Map(proposal.affectedFiles.map((file) => [file.path, file]))
+  if (proposal.changes.some((change) => !affected.has(change.path) || affected.get(change.path)?.contentHash !== sha256NormalizedV1(change.before)) || affected.size !== proposal.changes.length) {
+    throw new Error('Proposal changes do not match its affected-file hashes.')
+  }
+  for (const file of proposal.affectedFiles) {
+    const absolute = containedPath(projectRoot, file.path)
+    if (!absolute || !existsSync(absolute)) throw new Error(`Affected file is unavailable or escapes the repository root: ${file.path}`)
+    const current = readFileSync(absolute, 'utf8')
+    if (sha256NormalizedV1(current) !== file.contentHash) throw new Error(`Affected file changed since proposal creation: ${file.path}`)
+    originals.set(absolute, current)
+  }
+
+  try {
+    for (const change of proposal.changes) {
+      const absolute = resolve(projectRoot, change.path)
+      writeFileSync(`${absolute}.docbridge-${process.pid}.tmp`, change.after, 'utf8')
+    }
+    for (const change of proposal.changes) {
+      const absolute = resolve(projectRoot, change.path)
+      renameSync(`${absolute}.docbridge-${process.pid}.tmp`, absolute)
+    }
+    for (const change of proposal.changes) {
+      if (readFileSync(resolve(projectRoot, change.path), 'utf8') !== change.after) throw new Error(`Postcondition failed for ${change.path}`)
+    }
+    options.verify?.(proposal.changes.map((change) => change.path))
+  } catch (error) {
+    for (const [absolute, content] of originals) writeFileSync(absolute, content, 'utf8')
+    for (const change of proposal.changes) {
+      const temp = `${resolve(projectRoot, change.path)}.docbridge-${process.pid}.tmp`
+      if (existsSync(temp)) unlinkSync(temp)
+    }
+    throw error
+  }
+  const applied = { ...proposal, status: 'applied' as const, contentHash: '0'.repeat(64) }
+  return FixProposalV1Schema.parse({ ...applied, contentHash: contentHashForArtifactV1(applied) })
+}

package/src/index-builder/content-hash.ts

@@ -13,7 +13,14 @@ const sortValue = (value: unknown): unknown => {
   return value
 }
 
+export const canonicalJsonV1 = (payload: unknown): string => JSON.stringify(sortValue(payload))
+
 export const sha256NormalizedV1 = (payload: unknown): string => {
-  const normalized = JSON.stringify(sortValue(payload))
+  const normalized = canonicalJsonV1(payload)
   return createHash('sha256').update(normalized, 'utf8').digest('hex')
-}
+}
+
+export const contentHashForArtifactV1 = <T extends { readonly contentHash: string }>(artifact: T): string => {
+  const { contentHash: _contentHash, ...payload } = artifact
+  return sha256NormalizedV1(payload)
+}

package/src/index-builder/human-adapters/plain-markdown.ts

@@ -1,10 +1,26 @@
+import { minimatch } from 'minimatch'
+
 import { optionString, scanMarkdownDocs, type HumanAdapter } from './core.js'
 
+const stringPatterns = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string' && item.length > 0) : []
+
+const matchesConfiguredPath = (relPath: string, options: Record<string, unknown> | undefined): boolean => {
+  const normalize = (pattern: string): string => pattern.replaceAll('\\', '/').replace(/^\.\//, '')
+  const include = stringPatterns(options?.include).map(normalize)
+  const exclude = stringPatterns(options?.exclude).map(normalize)
+  if (exclude.some((pattern) => minimatch(relPath, pattern, { dot: true }))) return false
+  return include.length === 0 || include.some((pattern) => minimatch(relPath, pattern, { dot: true }))
+}
+
 export const plainMarkdownAdapter: HumanAdapter = {
   plugin: 'plain-markdown',
   scan: ({ root, config }) => {
     const humanRoot =
       optionString(config.options, ['contentDir', 'root', 'docsDir']) ?? 'docs'
-    return scanMarkdownDocs(root, humanRoot, { urlPrefix: config.options?.urlPrefix })
+    return scanMarkdownDocs(root, humanRoot, {
+      urlPrefix: config.options?.urlPrefix,
+      includeRelPath: (relPath) => matchesConfiguredPath(relPath, config.options),
+    })
   },
 }

package/src/index-builder/llms-txt.ts

@@ -1,6 +1,25 @@
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import type { KnowledgeEntry } from '../schemas/doc-bridge-index.js'
 
+const routePath = (path: string, pathPrefix: string | undefined): string => {
+  const normalizedPath = path.replaceAll('\\', '/').replace(/\.(?:md|mdx)$/, '')
+  const normalizedPrefix = pathPrefix?.replaceAll('\\', '/').replace(/\/$/, '')
+  const relativePath = normalizedPrefix && normalizedPath.startsWith(`${normalizedPrefix}/`)
+    ? normalizedPath.slice(normalizedPrefix.length + 1)
+    : normalizedPath
+  return relativePath.replace(/^\/+/, '')
+}
+
+export const knowledgeUrl = (
+  path: string,
+  options: { readonly urlPrefix?: string | undefined; readonly pathPrefix?: string | undefined } = {},
+): string => {
+  const relativePath = routePath(path, options.pathPrefix)
+  if (!options.urlPrefix) return path
+  const base = options.urlPrefix.endsWith('/') ? options.urlPrefix : `${options.urlPrefix}/`
+  return new URL(relativePath, base).toString()
+}
+
 export const renderLlmsTxt = (
   config: DocBridgeConfigV1,
   knowledge: readonly KnowledgeEntry[],
@@ -12,8 +31,9 @@ export const renderLlmsTxt = (
 
   const lines = knowledge.slice(0, 500).map((entry) => {
     const desc = entry.description ? `: ${entry.description}` : ''
-    return `- [${entry.title}](${entry.path})${desc}`
+    const url = knowledgeUrl(entry.path, config.index?.llmsTxt)
+    return `- [${entry.title}](${url})${desc}`
   })
 
   return `${preamble.trim()}\n\n## Knowledge\n\n${lines.join('\n')}\n`
-}
+}

package/src/index-builder/scan-corpus.ts

@@ -1,4 +1,5 @@
 import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { minimatch } from 'minimatch'
 import { readBoundedText } from '../lib/bounded-text.js'
 import {
   extractSearchBody,
@@ -31,10 +32,25 @@ export type OwnershipSeed = {
 
 const relFromRoot = (root: string, abs: string): string => toPosix(abs.replace(`${toPosix(root)}/`, ''))
 
+const configuredPathMatches = (
+  relPath: string,
+  include: readonly string[] | undefined,
+  exclude: readonly string[] | undefined,
+): boolean => {
+  const normalize = (pattern: string): string => toPosix(pattern).replace(/^\.\//, '')
+  const included = include?.filter(Boolean).map(normalize) ?? []
+  const excluded = exclude?.filter(Boolean).map(normalize) ?? []
+  if (excluded.some((pattern) => minimatch(relPath, pattern, { dot: true }))) return false
+  return included.length === 0 || included.some((pattern) => minimatch(relPath, pattern, { dot: true }))
+}
+
 export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): CorpusDoc[] => {
   const agentRoot = containedProjectPath(root, config.corpus.agent.root)
   if (!agentRoot) throw new Error('Agent corpus root escapes the project root.')
-  const files = walkFiles(agentRoot, { extensions: ['.md', '.mdx'] })
+  const files = walkFiles(agentRoot, { extensions: ['.md', '.mdx'] }).filter((abs) => {
+    const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ''))
+    return configuredPathMatches(relToCorpus, config.corpus.agent.include, config.corpus.agent.exclude)
+  })
   const corpusRelRoot = toPosix(config.corpus.agent.root)
 
   const budget = { used: 0 }

package/src/index.ts

@@ -15,6 +15,16 @@ export {
   type DocBridgeConfigV1,
   type AgentCorpusConfig,
   type DocumentationStandardV1Config,
+  RuleIdSchema,
+  RuleSeveritySchema,
+  RulesConfigSchema,
+  WorkflowConfigSchema,
+  RepositorySafetyConfigSchema,
+  type RuleId,
+  type RuleSeverity,
+  type RulesConfig,
+  type WorkflowConfig,
+  type RepositorySafetyConfig,
 } from './config/schema.js'
 
 export {
@@ -55,16 +65,63 @@ export {
 
 export {
   parseAgentHandoff,
+  parseAgentProposal,
   parseAgentSearch,
   parseDocBridgeConfig,
   parseDocBridgeIndex,
+  parseDiscoverySnapshot,
+  parseFixProposal,
   parseMemoryCandidate,
+  parseReconciliationReport,
+  parseWorkflowRun,
   safeParseAgentHandoff,
   type ParseIssue,
   type ParseResult,
 } from './validate.js'
 
 export { buildDocBridgeIndex, type BuildIndexOptions, type BuildIndexResult } from './index-builder/build-index.js'
+export { discoverRepository, type DiscoveryOptions } from './discovery/repository.js'
+export { containedPath, DEFAULT_SAFETY_EXCLUDES, redactSecrets, redactValue, safeWalkFiles, type SafeWalkOptions, type SafeWalkResult } from './safety/repository.js'
+export { DEFAULT_REGISTRY_AGENT_ID, createRegistryAgentAdapter, loadRegistryAgentMetadata, loadRegistryAgentRunner, persistRegistryAgentProposal, type RegistryAgentAdapter, type RegistryAgentContext, type RegistryAgentMetadata, type RegistryAgentRunner } from './agents/registry-adapter.js'
+export {
+  applyDocumentationDeclarations,
+  parseDocumentationDeclarations,
+  type DocumentationAnalysisResult,
+  type DocumentationDeclarationInput,
+  type DocumentationDeclarationOptions,
+  type DocumentationDeclarationResult,
+  type DocumentationDiagnostic,
+} from './discovery/documentation.js'
+export { reconcileKnowledge } from './reconciliation/reconcile.js'
+export { renderOfflineReport, type OfflineReportInput, type OfflineReportOptions } from './report/html.js'
+export {
+  applyFixProposal,
+  approveFixProposal,
+  createArtifactNormalizationProposal,
+  createMarkdownLinkFixProposal,
+  type FixApplyOptions,
+  type FixProposalOptions,
+} from './fixes/proposals.js'
+export {
+  WORKFLOW_STAGES,
+  loadWorkflowManifest,
+  loadWorkflowStepOutput,
+  runWorkflow,
+  type WorkflowExecutionResult,
+  type WorkflowOptions,
+  type WorkflowStage,
+  type WorkflowStageContext,
+  type WorkflowStageHandler,
+} from './workflow/engine.js'
+export {
+  evaluateRules,
+  parseRuleId,
+  parseRuleSeverity,
+  type RuleEngineOptions,
+  type RuleEvaluationResult,
+  type RuleFinding,
+  type RuleMode,
+} from './rules/engine.js'
 export {
   formatEcosystemLlmsBlock,
   formatEcosystemLlmsSection,
@@ -98,7 +155,7 @@ export {
   type DocumentationStandardRuleResult,
   type DocumentationStandardRuleStatus,
 } from './conformance/documentation-standard-v1.js'
-export { MCP_TOOLS, handleMcpRequest, startMcpStdioServer } from './mcp/server.js'
+export { MCP_TOOLS, handleMcpRequest, respondMcpRequest, startMcpStdioServer } from './mcp/server.js'
 export { installMcpConfig, mcpSnippet, type McpInstallResult, type McpInstallTarget } from './mcp/install.js'
 export { runDoctor, formatDoctorText, type DoctorReport, type DoctorIssue, type DoctorCoverage } from './doctor/run-doctor.js'
 export {
@@ -115,7 +172,47 @@ export {
   type GithubPrOptions,
   type GithubPrResult,
 } from './memory/github-pr.js'
-export { sha256NormalizedV1 } from './index-builder/content-hash.js'
+export { canonicalJsonV1, contentHashForArtifactV1, sha256NormalizedV1 } from './index-builder/content-hash.js'
+export {
+  AgentProposalV1Schema,
+  AffectedFileSchema,
+  CoverageSchema,
+  DiagnosticSeveritySchema,
+  DiscoverySnapshotV1Schema,
+  EntitySchema,
+  EvidenceSchema,
+  EvidenceSourceSchema,
+  FindingStatusSchema,
+  FixProposalStatusSchema,
+  FixChangeSchema,
+  FixProposalV1Schema,
+  KNOWLEDGE_CONTENT_HASH_ALGO,
+  KNOWLEDGE_SCHEMA_VERSION,
+  ProvenanceSchema,
+  ProjectIdentitySchema,
+  ProposalOriginSchema,
+  ReconciliationReportV1Schema,
+  RelationSchema,
+  WorkflowRunV1Schema,
+  WorkflowStepSchema,
+  WorkflowStateSchema,
+  WorkflowTransitionSchema,
+  type AgentProposalV1,
+  type DiagnosticSeverity,
+  type DiscoverySnapshotV1,
+  type Evidence,
+  type FindingStatus,
+  type FixProposalV1,
+  type FixChange,
+  type KnowledgeArtifactV1,
+  type KnowledgeDiagnostic,
+  type KnowledgeEntity,
+  type KnowledgeRelation,
+  type Provenance,
+  type ReconciliationReportV1,
+  type WorkflowRunV1,
+  type WorkflowState,
+} from './schemas/knowledge.js'
 export { IndexNotFoundError, indexFilePath, loadDocBridgeIndex, resolveRoot } from './query/load-index.js'
 export { runQuery, type QueryKind, type QueryRequest, type QueryResult } from './query/query.js'
 export { searchIndex, type SearchMatch } from './query/search.js'