@agentskit/doc-bridge 1.0.2 → 1.1.1

package/src/conformance/ecosystem-contract.ts

@@ -0,0 +1,175 @@
+import { z } from 'zod'
+
+const NonEmptyStringSchema = z.string().refine((value) => value.trim().length > 0, 'must be non-empty')
+const HttpsUrlSchema = z.string().url().refine((value) => value.startsWith('https://'), 'must use https')
+const RepoSchema = z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/)
+const SlugSchema = z.string().regex(/^[a-z][a-z0-9-]*$/)
+
+const SurfaceSchema = z.object({
+  home: HttpsUrlSchema.optional(),
+  docs: HttpsUrlSchema.optional(),
+  llms: HttpsUrlSchema.optional(),
+  stats: HttpsUrlSchema.optional(),
+  documentation: z.enum(['fumadocs', 'repository']),
+  chat: z.enum(['agentschat', 'custom', 'none']),
+}).passthrough()
+
+const ProductSchema = z.object({
+  id: SlugSchema,
+  name: NonEmptyStringSchema,
+  shortName: NonEmptyStringSchema,
+  kind: NonEmptyStringSchema,
+  role: NonEmptyStringSchema,
+  promise: NonEmptyStringSchema,
+  maturity: z.enum(['planning', 'alpha', 'beta', 'stable', 'deprecated']),
+  repo: RepoSchema,
+  accent: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  surfaces: SurfaceSchema,
+  navigation: z.object({
+    showInBar: z.boolean(),
+    order: z.number().int().nonnegative().optional(),
+    next: z.array(SlugSchema),
+  }).passthrough(),
+}).passthrough()
+
+const LegacyPropertySchema = z.object({
+  id: SlugSchema,
+  name: NonEmptyStringSchema,
+  barLabel: NonEmptyStringSchema,
+  domain: NonEmptyStringSchema,
+  url: HttpsUrlSchema,
+  repo: RepoSchema,
+  tagline: NonEmptyStringSchema,
+  kind: NonEmptyStringSchema,
+  accent: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  llms: HttpsUrlSchema.optional(),
+  stats: HttpsUrlSchema.optional(),
+}).passthrough()
+
+const ManifestSchema = z.object({
+  schemaVersion: z.literal(2),
+  parentBrand: z.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema }).passthrough(),
+  products: z.array(ProductSchema).min(1),
+  properties: z.array(LegacyPropertySchema).length(4),
+  builder: z.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema, url: HttpsUrlSchema }).passthrough().optional(),
+}).passthrough()
+
+const EvidenceSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('repository-derivation'),
+    repo: RepoSchema,
+    path: NonEmptyStringSchema,
+    summary: NonEmptyStringSchema,
+  }).passthrough(),
+  z.object({ type: z.literal('endpoint'), url: HttpsUrlSchema, summary: NonEmptyStringSchema }).passthrough(),
+])
+
+const ClaimSchema = z.object({
+  id: NonEmptyStringSchema,
+  value: z.number().finite().nonnegative(),
+  noun: NonEmptyStringSchema,
+  conservativeFloor: z.number().int().nonnegative().optional(),
+  evidence: EvidenceSchema,
+}).passthrough()
+
+const ClaimProductSchema = z.object({
+  productId: SlugSchema,
+  source: z.discriminatedUnion('type', [
+    z.object({ type: z.literal('endpoint'), url: HttpsUrlSchema }).passthrough(),
+    z.object({ type: z.literal('repository'), repo: RepoSchema }).passthrough(),
+  ]),
+  verification: z.enum(['verified', 'declared']),
+  claims: z.array(ClaimSchema),
+}).passthrough()
+
+const ClaimsSchema = z.object({
+  schemaVersion: z.literal(1),
+  manifestSchemaVersion: z.literal(2),
+  products: z.array(ClaimProductSchema),
+}).passthrough()
+
+const LEGACY_PRODUCT_IDS = ['agentskit', 'akos', 'playbook', 'registry'] as const
+
+export const parseCanonicalEcosystemContract = (
+  manifestInput: unknown,
+  claimsInput: unknown,
+): { readonly manifest: z.infer<typeof ManifestSchema>; readonly claims: z.infer<typeof ClaimsSchema> } => {
+  const manifest = ManifestSchema.parse(manifestInput)
+  const claims = ClaimsSchema.parse(claimsInput)
+  const products = new Map(manifest.products.map((product) => [product.id, product]))
+  if (products.size !== manifest.products.length) throw new Error('Manifest product IDs must be unique.')
+
+  const navigationOrders = new Set<number>()
+  for (const product of manifest.products) {
+    if (product.surfaces.documentation === 'fumadocs' && !product.surfaces.docs) {
+      throw new Error(`Product ${product.id} requires a docs surface for Fumadocs.`)
+    }
+    if (product.navigation.showInBar) {
+      if (!product.surfaces.home || product.navigation.order === undefined) {
+        throw new Error(`Product ${product.id} requires home and order for shared navigation.`)
+      }
+      if (navigationOrders.has(product.navigation.order)) throw new Error('Navigation orders must be unique.')
+      navigationOrders.add(product.navigation.order)
+    }
+    const next = new Set(product.navigation.next)
+    if (next.size !== product.navigation.next.length || next.has(product.id)) {
+      throw new Error(`Product ${product.id} has duplicate or self-referential navigation.`)
+    }
+    for (const nextId of next) {
+      if (!products.has(nextId)) throw new Error(`Product ${product.id} references unknown product ${nextId}.`)
+    }
+  }
+
+  for (const [index, id] of LEGACY_PRODUCT_IDS.entries()) {
+    const legacy = manifest.properties[index]
+    const product = products.get(id)
+    if (!legacy || !product || legacy.id !== id || !product.surfaces.home) {
+      throw new Error(`Legacy property ${index} must project product ${id}.`)
+    }
+    const expected = {
+      name: product.name,
+      barLabel: product.shortName,
+      domain: new URL(product.surfaces.home).host,
+      url: product.surfaces.home,
+      repo: product.repo,
+      tagline: product.promise,
+      kind: product.kind,
+      accent: product.accent,
+      llms: product.surfaces.llms,
+      stats: product.surfaces.stats,
+    }
+    for (const [key, value] of Object.entries(expected)) {
+      if (legacy[key as keyof typeof legacy] !== value) throw new Error(`Legacy ${id}.${key} must match v2.`)
+    }
+  }
+
+  const claimProducts = new Map(claims.products.map((product) => [product.productId, product]))
+  if (claimProducts.size !== claims.products.length || claimProducts.size !== products.size) {
+    throw new Error('Claims must include every manifest product exactly once.')
+  }
+  for (const [productId, product] of products) {
+    const claimProduct = claimProducts.get(productId)
+    if (!claimProduct) throw new Error(`Claims are missing product ${productId}.`)
+    if (claimProduct.source.type === 'endpoint') {
+      if (claimProduct.source.url !== product.surfaces.stats) throw new Error(`Claims source for ${productId} must match stats.`)
+    } else if (claimProduct.source.repo !== product.repo) {
+      throw new Error(`Claims source for ${productId} must match repo.`)
+    }
+    if (claimProduct.verification === 'declared' && claimProduct.claims.length > 0) {
+      throw new Error(`Declared product ${productId} cannot publish claims.`)
+    }
+    const claimIds = new Set<string>()
+    for (const claim of claimProduct.claims) {
+      if (claimIds.has(claim.id)) throw new Error(`Product ${productId} has duplicate claim ${claim.id}.`)
+      claimIds.add(claim.id)
+      if (claim.conservativeFloor !== undefined && claim.conservativeFloor > claim.value) {
+        throw new Error(`Claim ${productId}:${claim.id} has a floor above its value.`)
+      }
+      if (claim.evidence.type === 'repository-derivation' && claim.evidence.repo !== product.repo) {
+        throw new Error(`Claim ${productId}:${claim.id} evidence must match the product repo.`)
+      }
+    }
+  }
+
+  return { manifest, claims }
+}

package/src/gates/run-gates.ts

@@ -1,14 +1,23 @@
 import { readFileSync } from 'node:fs'
 
 import type { DocBridgeConfigV1 } from '../config/schema.js'
+import {
+  runDocumentationStandardV1,
+  type DocumentationConformanceReportV1,
+} from '../conformance/documentation-standard-v1.js'
 import { buildDocBridgeIndex } from '../index-builder/build-index.js'
 import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
 import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
 import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
 
-export type GateId = 'index-freshness' | 'human-guide-links' | 'okf-type' | 'docs-style'
+export type GateId =
+  | 'index-freshness'
+  | 'human-guide-links'
+  | 'okf-type'
+  | 'docs-style'
+  | 'documentation-standard-v1'
 
-const SUPPORTED_GATES = ['index-freshness', 'human-guide-links', 'okf-type', 'docs-style'] as const
+const RESERVED_GATE_IDS = new Set(['link-rot', 'routing-currency', 'bootstrap-size'])
 
 export type GateResult = {
   readonly id: GateId
@@ -16,6 +25,7 @@ export type GateResult = {
   readonly message: string
   readonly expected?: string
   readonly actual?: string
+  readonly details?: DocumentationConformanceReportV1
 }
 
 export type GateRunResult = {
@@ -28,6 +38,19 @@ export const runGate = (
   config: DocBridgeConfigV1,
   id: GateId,
 ): GateResult => {
+  if (id === 'documentation-standard-v1') {
+    const details = runDocumentationStandardV1(root, config)
+    return {
+      id,
+      ok: details.ok,
+      message: details.ok
+        ? 'Documentation Standard v1 required rules pass'
+        : `${details.summary.required.failed} Documentation Standard v1 required rule(s) failed`,
+      expected: 'all required rules pass or have approved exceptions',
+      actual: `${details.summary.required.passed} passed, ${details.summary.required.failed} failed, ${details.summary.required.excepted} excepted`,
+      details,
+    }
+  }
   if (id === 'human-guide-links') return runHumanGuideLinksGate(root, config)
   if (id === 'okf-type') return runOkfTypeGate(root, config)
   if (id === 'docs-style') return runDocsStyleGate(root, config)
@@ -264,10 +287,16 @@ export const resolveGateIds = (config: DocBridgeConfigV1): GateId[] => {
   )
 
   for (const id of config.gates?.include ?? []) {
-    if (SUPPORTED_GATES.includes(id as GateId)) ids.add(id as GateId)
+    if (RESERVED_GATE_IDS.has(id)) {
+      process.emitWarning(`Gate "${id}" is reserved and has no runtime implementation; it was not executed.`, {
+        code: 'AK_DOCS_RESERVED_GATE',
+      })
+      continue
+    }
+    ids.add(id as GateId)
   }
   for (const id of config.gates?.exclude ?? []) {
-    if (SUPPORTED_GATES.includes(id as GateId)) ids.delete(id as GateId)
+    if (!RESERVED_GATE_IDS.has(id)) ids.delete(id as GateId)
   }
 
   return [...ids]

package/src/index-builder/human-adapters/core.ts

@@ -1,9 +1,10 @@
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { realpathSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 import type { HumanCorpusConfig } from '../../config/schema.js'
 import { slugFromPath } from '../../lib/markdown.js'
-import { toPosix } from '../../lib/paths.js'
+import { readBoundedText } from '../../lib/bounded-text.js'
+import { containedProjectPath, toPosix } from '../../lib/paths.js'
 import { walkFiles } from '../../lib/walk.js'
 
 export type HumanDocRecord = {
@@ -79,11 +80,17 @@ export const scanMarkdownDocs = (
   },
 ): HumanDocRecord[] => {
   const out: HumanDocRecord[] = []
-  const absRoot = join(root, humanRoot)
+  const projectRoot = realpathSync.native(resolve(root))
+  const absRoot = containedProjectPath(root, humanRoot)
+  if (!absRoot) return out
+  const budget = { used: 0 }
 
   for (const abs of walkFiles(absRoot, { extensions: ['.md', '.mdx'] })) {
+    const canonical = realpathSync.native(abs)
+    const fileRelative = relative(projectRoot, canonical)
+    if (isAbsolute(fileRelative) || fileRelative === '..' || fileRelative.startsWith(`..${sep}`)) continue
     const relToHumanRoot = toPosix(abs.replace(`${toPosix(absRoot)}/`, ''))
-    const raw = readFileSync(abs, 'utf8')
+    const raw = readBoundedText(abs, budget)
     if (options?.includeRelPath && !options.includeRelPath(relToHumanRoot, raw)) continue
     out.push({
       id: options?.idForDoc?.(relToHumanRoot, raw) ?? docId(relToHumanRoot, raw),

package/src/index-builder/human-adapters/docusaurus.ts

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import vm from 'node:vm'
+import { existsSync } from 'node:fs'
 
+import { readBoundedText } from '../../lib/bounded-text.js'
+import { containedProjectPath } from '../../lib/paths.js'
+import { parseStaticJsObject } from '../../lib/static-js-literal.js'
 import {
   optionString,
   parseFrontmatter,
@@ -43,48 +44,31 @@ const docusaurusRecordId = (relPath: string, raw: string): string => {
   return frontmatter.package ?? frontmatter.module ?? docusaurusSidebarId(relPath, raw)
 }
 
-const sidebarsValue = (file: string): unknown => {
-  if (!existsSync(file)) return undefined
-  const raw = readFileSync(file, 'utf8')
-    .replace(/import\s+type\s+[\s\S]*?;?\n/g, '')
-    .replace(/:\s*[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*=)/g, '')
-    .replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\n|$))/g, '')
-    .replace(/export\s+default/, 'module.exports =')
-  const sandbox = { module: { exports: {} as unknown }, exports: {} }
-  vm.runInNewContext(raw, sandbox, { timeout: 250 })
-  return sandbox.module.exports
-}
-
-const visitSidebar = (value: unknown, filter: { ids: Set<string>; autogenDirs: string[] }): void => {
-  if (typeof value === 'string') {
-    filter.ids.add(value)
-    return
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) visitSidebar(item, filter)
-    return
-  }
-  if (!value || typeof value !== 'object') return
-
-  const item = value as Record<string, unknown>
-  if ((item.type === 'doc' || item.type === 'ref') && typeof item.id === 'string') {
-    filter.ids.add(item.id)
-  }
-  if (item.type === 'autogenerated' && typeof item.dirName === 'string') {
-    filter.autogenDirs.push(item.dirName)
-  }
-  if (Array.isArray(item.items)) visitSidebar(item.items, filter)
-  if (item.link && typeof item.link === 'object') visitSidebar(item.link, filter)
-  for (const child of Object.values(item)) {
-    if (Array.isArray(child)) visitSidebar(child, filter)
-  }
-}
-
-const readSidebars = (root: string, sidebarsFile: string | undefined): SidebarDocFilter => {
+const readSidebars = (sidebarsFile: string | undefined): SidebarDocFilter => {
   if (!sidebarsFile) return { enabled: false, ids: new Set(), autogenDirs: [] }
-  const value = sidebarsValue(join(root, sidebarsFile))
+  if (!existsSync(sidebarsFile)) return { enabled: false, ids: new Set(), autogenDirs: [] }
+  const raw = readBoundedText(sidebarsFile, { used: 0 }, { maxFileBytes: 1_048_576, maxCorpusBytes: 1_048_576 })
   const filter = { ids: new Set<string>(), autogenDirs: [] as string[] }
-  visitSidebar(value, filter)
+  const visit = (value: unknown): void => {
+    if (typeof value === 'string') {
+      filter.ids.add(value)
+      return
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item)
+      return
+    }
+    if (!value || typeof value !== 'object') return
+    const item = value as Record<string, unknown>
+    if ((item.type === 'doc' || item.type === 'ref') && typeof item.id === 'string') filter.ids.add(item.id)
+    if (item.type === 'autogenerated' && typeof item.dirName === 'string') filter.autogenDirs.push(item.dirName)
+    if (Array.isArray(item.items)) visit(item.items)
+    if (item.link && typeof item.link === 'object') visit(item.link)
+    for (const child of Object.values(item)) {
+      if (Array.isArray(child)) visit(child)
+    }
+  }
+  visit(parseStaticJsObject(raw))
   return { enabled: true, ...filter }
 }
 
@@ -102,7 +86,8 @@ export const docusaurusAdapter: HumanAdapter = {
   scan: ({ root, config }) => {
     const docsDir = optionString(config.options, ['docsDir', 'root'])
     if (!docsDir) return []
-    const sidebarFilter = readSidebars(root, optionString(config.options, ['sidebarsFile']))
+    const sidebarsFile = optionString(config.options, ['sidebarsFile'])
+    const sidebarFilter = readSidebars(sidebarsFile ? containedProjectPath(root, sidebarsFile) : undefined)
     return scanMarkdownDocs(root, docsDir, {
       includeRelPath: (relPath, raw) => isIncludedBySidebar(sidebarFilter, docusaurusSidebarId(relPath, raw)),
       idForDoc: docusaurusRecordId,

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

@@ -1,3 +1,6 @@
+import { realpathSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+
 import type { DocBridgeConfigV1, HumanCorpusConfig } from '../../config/schema.js'
 import { docusaurusAdapter } from './docusaurus.js'
 import { fumadocsAdapter } from './fumadocs.js'
@@ -18,22 +21,31 @@ const humanConfigs = (config: DocBridgeConfigV1): HumanCorpusConfig[] => {
   return Array.isArray(human) ? human : [human]
 }
 
+const canonicalPath = (path: string): string => {
+  try {
+    return realpathSync.native(path)
+  } catch {
+    return resolve(path)
+  }
+}
+
 export const scanHumanDocRecords = (
   root: string,
   config: DocBridgeConfigV1,
 ): HumanDocRecord[] => {
   const out: HumanDocRecord[] = []
   const seen = new Set<string>()
-  const agentRoot = config.corpus.agent.root.replace(/\/$/, '')
+  const agentRoot = canonicalPath(resolve(root, config.corpus.agent.root))
 
   for (const human of humanConfigs(config)) {
     const adapter = ADAPTERS.find((candidate) => candidate.plugin === human.plugin)
     if (!adapter) continue
     for (const record of adapter.scan({ root, config: human })) {
       // Never treat agent-corpus files as human docs (nested for-agents, etc.)
+      const recordPath = canonicalPath(record.path)
       if (
-        record.path === agentRoot ||
-        record.path.startsWith(`${agentRoot}/`) ||
+        recordPath === agentRoot ||
+        recordPath.startsWith(`${agentRoot}${sep}`) ||
         record.path.includes('/for-agents/') ||
         record.path.endsWith('/for-agents')
       ) {

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

@@ -1,7 +1,5 @@
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-
 import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { readBoundedText } from '../lib/bounded-text.js'
 import {
   extractSearchBody,
   firstHeading,
@@ -12,7 +10,7 @@ import {
   slugFromPath,
   type FrontmatterData,
 } from '../lib/markdown.js'
-import { toPosix } from '../lib/paths.js'
+import { containedProjectPath, toPosix } from '../lib/paths.js'
 import { walkFiles } from '../lib/walk.js'
 import type { KnowledgeEntry } from '../schemas/doc-bridge-index.js'
 
@@ -34,14 +32,16 @@ export type OwnershipSeed = {
 const relFromRoot = (root: string, abs: string): string => toPosix(abs.replace(`${toPosix(root)}/`, ''))
 
 export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): CorpusDoc[] => {
-  const agentRoot = join(root, config.corpus.agent.root)
+  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 corpusRelRoot = toPosix(config.corpus.agent.root)
 
+  const budget = { used: 0 }
   return files.map((abs) => {
     const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ''))
     const relPath = `${corpusRelRoot}/${relToCorpus}`
-    const raw = readFileSync(abs, 'utf8')
+    const raw = readBoundedText(abs, budget)
     const { data: frontmatter } = parseFrontmatter(raw)
     const id =
       frontmatterString(frontmatter, 'id') ??

package/src/index.ts

@@ -9,8 +9,12 @@ export {
 } from './config/load-config.js'
 export {
   DocBridgeConfigV1Schema,
+  DocumentationStandardRuleIdSchema,
+  DocumentationStandardV1ConfigSchema,
+  EcosystemContractEvidenceSchema,
   type DocBridgeConfigV1,
   type AgentCorpusConfig,
+  type DocumentationStandardV1Config,
 } from './config/schema.js'
 
 export {
@@ -75,6 +79,19 @@ export {
   type GateResult,
   type GateRunResult,
 } from './gates/run-gates.js'
+export {
+  DOCUMENTATION_STANDARD_V1_ID,
+  DOCUMENTATION_STANDARD_V1_STATUS,
+  formatDocumentationStandardText,
+  runDocumentationStandardV1,
+  type DocumentationConformanceReportV1,
+  type DocumentationStandardEvidence,
+  type DocumentationStandardRemediation,
+  type DocumentationStandardRuleId,
+  type DocumentationStandardRuleLevel,
+  type DocumentationStandardRuleResult,
+  type DocumentationStandardRuleStatus,
+} from './conformance/documentation-standard-v1.js'
 export { MCP_TOOLS, handleMcpRequest, 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'

package/src/lib/bounded-text.ts

@@ -0,0 +1,25 @@
+import { readFileSync, statSync } from 'node:fs'
+
+export const MAX_DOCUMENT_BYTES = 4 * 1_024 * 1_024
+export const MAX_CORPUS_BYTES = 64 * 1_024 * 1_024
+
+export type TextReadBudget = { used: number }
+
+export const readBoundedText = (
+  path: string,
+  budget: TextReadBudget,
+  limits?: { readonly maxFileBytes?: number; readonly maxCorpusBytes?: number },
+): string => {
+  const maxFileBytes = limits?.maxFileBytes ?? MAX_DOCUMENT_BYTES
+  const maxCorpusBytes = limits?.maxCorpusBytes ?? MAX_CORPUS_BYTES
+  const stat = statSync(path)
+  if (!stat.isFile()) throw new Error(`Documentation path is not a regular file: ${path}`)
+  if (stat.size > maxFileBytes) {
+    throw new Error(`Documentation file exceeds the ${maxFileBytes} byte limit: ${path}`)
+  }
+  if (budget.used + stat.size > maxCorpusBytes) {
+    throw new Error(`Documentation corpus exceeds the ${maxCorpusBytes} byte read budget.`)
+  }
+  budget.used += stat.size
+  return readFileSync(path, 'utf8')
+}

package/src/lib/paths.ts

@@ -1,6 +1,24 @@
-import { resolve } from 'node:path'
+import { existsSync, realpathSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 export const toPosix = (value: string): string => value.split('\\').join('/')
 
 export const resolveFromRoot = (root: string, rel: string): string =>
-  resolve(root, rel)
+  resolve(root, rel)
+
+export const containedProjectPath = (root: string, path: string): string | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const unresolved = resolve(projectRoot, path)
+  const unresolvedRelative = relative(projectRoot, unresolved)
+  if (
+    isAbsolute(unresolvedRelative) ||
+    unresolvedRelative === '..' ||
+    unresolvedRelative.startsWith(`..${sep}`)
+  ) return undefined
+
+  const canonical = existsSync(unresolved) ? realpathSync.native(unresolved) : unresolved
+  const canonicalRelative = relative(projectRoot, canonical)
+  return isAbsolute(canonicalRelative) || canonicalRelative === '..' || canonicalRelative.startsWith(`..${sep}`)
+    ? undefined
+    : canonical
+}