@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/docs-coherence.ts

@@ -0,0 +1,136 @@
+/**
+ * C6 — the docs-coherence check (state-machine.md Section 15c). Pure: given
+ * every parsed doc entry from `aeg-root/` and the model-backed surfaced-path
+ * allowlist (`modelBackedDocPaths`, passed in because deriving
+ * it requires reading doctrine, which this pure module never does), asserts:
+ *   (a) every surfaced doc is reachable in the doc-nav tree the docs engine
+ *       (`buildDocNav`) would build for the surfaced set;
+ *   (b) no surfaced doc's `parent:` reference points at a doc that doesn't
+ *       exist, or exists but isn't itself surfaced;
+ *   (c) every relative `.md` link between two surfaced docs resolves to
+ *       another surfaced doc.
+ *
+ * (a) and (b) mirror the real parent/child resolution
+ * `apps/vinaya/web/src/lib/docs/nest-doc-children.ts` performs when building
+ * Vinaya's live `/docs` nav (a Portal route since `vinaya-pages-v1` task 8;
+ * that file is read-only reference here, never imported): a doc whose
+ * `parent:` frontmatter points at
+ * a nonexistent (or excluded) slug is silently dropped from that nav's flat
+ * list — reachable neither at the top level nor as anyone's child. That
+ * silent-drop is the exact defect this check exists to catch.
+ */
+
+import { deriveTitle, type ParsedDoc } from './parse-doc'
+import { isSurfacedDoc } from './surfaced-manifest'
+import type { Doc, DocFrontmatter } from './types'
+
+export type DocsCoherenceEntry = {
+  /** Path relative to `aeg-root/`, e.g. `roles/developer.md`. */
+  relPath: string
+  frontmatter: DocFrontmatter
+  body: string
+  firstH1?: string
+}
+
+export type DocsCoherenceResult = { errors: string[]; notes: string[] }
+
+function slugOf(relPath: string): string {
+  return relPath.replace(/\.md$/, '')
+}
+
+function relPathOf(slug: string): string {
+  return `${slug}.md`
+}
+
+function defaultSectionFor(relPath: string): string {
+  const segments = relPath.split('/')
+  return segments.length === 1 ? 'Overview' : (segments[0] ?? 'Overview')
+}
+
+function toDoc(entry: DocsCoherenceEntry): Doc {
+  const slug = slugOf(entry.relPath)
+  const parsed: ParsedDoc = { frontmatter: entry.frontmatter, body: entry.body, firstH1: entry.firstH1 }
+  return {
+    slug,
+    title: deriveTitle(parsed, slug),
+    sidebarTitle: entry.frontmatter.sidebarTitle,
+    description: entry.frontmatter.description,
+    section: entry.frontmatter.section ?? defaultSectionFor(entry.relPath),
+    order: entry.frontmatter.order ?? 0,
+    href: `/docs/${slug}`,
+    filePath: `aeg-root/${entry.relPath}`,
+    parentSlug: entry.frontmatter.parent
+  }
+}
+
+function isReachable(doc: Doc, bySlug: Map<string, Doc>, seen: Set<string> = new Set()): boolean {
+  if (!doc.parentSlug) return true
+  if (seen.has(doc.slug)) return false // cycle guard
+  const parent = bySlug.get(doc.parentSlug)
+  if (!parent) return false
+  seen.add(doc.slug)
+  return isReachable(parent, bySlug, seen)
+}
+
+const MD_LINK_PATTERN = /\]\(([^)]+)\)/g
+
+/** Resolves `target` relative to the directory of `fromRelPath`. Returns null if it escapes `aeg-root/`. */
+function resolveRelativeMdLink(fromRelPath: string, target: string): string | null {
+  const fromDir = fromRelPath.includes('/') ? fromRelPath.slice(0, fromRelPath.lastIndexOf('/')) : ''
+  const combined = target.startsWith('/') ? target.slice(1) : fromDir ? `${fromDir}/${target}` : target
+
+  const stack: string[] = []
+  for (const part of combined.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') {
+      if (stack.length === 0) return null
+      stack.pop()
+    } else {
+      stack.push(part)
+    }
+  }
+  return stack.join('/')
+}
+
+export function evaluateDocsCoherence(
+  entries: DocsCoherenceEntry[],
+  surfacedPaths: ReadonlySet<string> = new Set()
+): DocsCoherenceResult {
+  const errors: string[] = []
+  const notes: string[] = []
+
+  const surfacedEntries = entries.filter((e) => isSurfacedDoc(e.relPath, e.frontmatter, surfacedPaths))
+  const surfacedRelPaths = new Set(surfacedEntries.map((e) => e.relPath))
+  const docs = surfacedEntries.map(toDoc)
+  const bySlug = new Map(docs.map((d) => [d.slug, d]))
+
+  for (const doc of docs) {
+    if (!isReachable(doc, bySlug)) {
+      errors.push(`C6: surfaced doc "${relPathOf(doc.slug)}" is not reachable in the doc nav`)
+    }
+    if (doc.parentSlug && !bySlug.has(doc.parentSlug)) {
+      errors.push(
+        `C6: nav entry "${relPathOf(doc.slug)}" points at a non-existent/excluded doc "${relPathOf(doc.parentSlug)}"`
+      )
+    }
+  }
+
+  for (const entry of surfacedEntries) {
+    for (const match of entry.body.matchAll(MD_LINK_PATTERN)) {
+      const raw = (match[1] ?? '').trim()
+      const target = (raw.split('#')[0] ?? '').trim()
+      if (!target) continue // pure same-doc anchor, e.g. `(#some-heading)`
+      if (/^https?:\/\//.test(target) || target.startsWith('mailto:')) continue
+      if (!target.endsWith('.md')) continue
+
+      const resolved = resolveRelativeMdLink(entry.relPath, target)
+      if (resolved === null) continue // escapes aeg-root/ — out of scope for this check
+
+      if (!surfacedRelPaths.has(resolved)) {
+        errors.push(`C6: link "${target}" in "${entry.relPath}" resolves to no surfaced doc`)
+      }
+    }
+  }
+
+  return { errors, notes }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/index.ts

@@ -0,0 +1,29 @@
+export type { Doc, DocFrontmatter, DocNav, DocSection } from './types'
+export { parseDocFrontmatter, deriveTitle, stripLeadingH1 } from './parse-doc'
+export type { ParsedDoc } from './parse-doc'
+export { buildDocNav } from './build-doc-nav'
+export type { BuildDocNavOptions } from './build-doc-nav'
+export { findDoc, getNextDoc, getPrevDoc } from './nav-helpers'
+export { isSurfacedDoc, surfacedDocs, modelBackedDocPaths } from './surfaced-manifest'
+export type { SurfacedManifestEntry } from './surfaced-manifest'
+export { nodeDocRoute, nodeDocHref } from './node-route'
+export type { NodeDocRoute } from './node-route'
+export { legacyAnchorSlugs } from './legacy-anchors'
+export { evaluateDocsCoherence } from './docs-coherence'
+export type { DocsCoherenceEntry, DocsCoherenceResult } from './docs-coherence'
+export {
+  ALLOWED_MECHANICS,
+  CONTRACT_BLOCKS,
+  countWords,
+  enforcementPublishedText,
+  evaluatePublishedProse,
+  extractShortVersion,
+  publishedDoctrineBody,
+  readabilityErrors,
+  REFERENCE_HEADING,
+  ROLE_BLOCKS,
+  SHORT_VERSION_HEADING,
+  SHORT_VERSION_MAX_WORDS,
+  SHORT_VERSION_MIN_WORDS
+} from './published-prose'
+export type { PublishedProseEntry, PublishedProseResult } from './published-prose'

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/legacy-anchors.ts

@@ -0,0 +1,48 @@
+/**
+ * The old-slug → new-slug alias derivation for `/docs` gate/check anchors.
+ * `node-route.ts`'s `nodeSlug()` computes an anchor from a node's display
+ * form (G-code stripped, over-length names cut at a clause boundary), which
+ * for a handful of nodes now differs from the slug `diagram-model.ts`
+ * originally stamped into the node id. A reader who bookmarked, or a page
+ * that still links to, the old `#g1-implementation-exists`-style fragment
+ * must keep landing on the right section — this is the input to that alias.
+ *
+ * Derived, not hand-listed: the failure mode this replaces is exactly the
+ * one `node-route.ts`'s own header comment warns against for a second slug
+ * source. Zero I/O, additive export — takes an already-derived node, returns
+ * data, never reads a file (aeg-core purity, #372/#382/#506).
+ */
+
+import type { DiagramNode } from '../diagram-model'
+import { nodeDocRoute } from './node-route'
+
+/**
+ * A doctrine cell's own text renamed outright (not a G-code strip, not an
+ * over-length cut) is the one case this file cannot derive. `node.id` is
+ * `slugify(row.action)` computed fresh from whatever `enforcement.md` says
+ * RIGHT NOW — by the time a rename lands, the old text is gone from the
+ * doctrine snapshot entirely, so there is nothing left in `node.id`/
+ * `node.label` for a derivation to diff against. This is not a second
+ * routing authority — `nodeSlug()`/`nodeDocRoute()` still compute every
+ * live anchor unconditionally; this map only remembers what one specific
+ * anchor used to be before an editor rewrote the cell it came from, and it
+ * grows by exactly one entry, once, at the moment of a rename. Keyed by the
+ * node id the rename produced. */
+const RENAMED_CELL_ALIASES: Record<string, string> = {
+  'check:coherence-check': 'coherence-oracle'
+}
+
+/**
+ * The anchor slugs this node used to publish and must continue to answer
+ * to. `[]` when the node's canonical slug is unchanged — most nodes, since
+ * `nodeSlug()`'s cleanup is a no-op on an already-clean display form.
+ */
+export function legacyAnchorSlugs(node: DiagramNode): string[] {
+  const rawSlug = node.id.slice(node.kind.length + 1)
+  const canonicalSlug = nodeDocRoute(node)?.slug
+  const aliases = new Set<string>()
+  if (canonicalSlug && canonicalSlug !== rawSlug) aliases.add(rawSlug)
+  const renamed = RENAMED_CELL_ALIASES[node.id]
+  if (renamed) aliases.add(renamed)
+  return [...aliases]
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/nav-helpers.ts

@@ -0,0 +1,17 @@
+import type { Doc, DocNav } from './types'
+
+export function findDoc(nav: DocNav, slug: string): Doc | undefined {
+  return nav.flat.find((d) => d.slug === slug)
+}
+
+export function getNextDoc(nav: DocNav, slug: string): Doc | undefined {
+  const idx = nav.flat.findIndex((d) => d.slug === slug)
+  if (idx === -1 || idx === nav.flat.length - 1) return undefined
+  return nav.flat[idx + 1]
+}
+
+export function getPrevDoc(nav: DocNav, slug: string): Doc | undefined {
+  const idx = nav.flat.findIndex((d) => d.slug === slug)
+  if (idx <= 0) return undefined
+  return nav.flat[idx - 1]
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/node-route.ts

@@ -0,0 +1,134 @@
+/**
+ * The single node → `/docs` route derivation. Nav construction
+ * (`load-aeg-docs.ts`), the "Read more" resolver (`read-more.ts`), and the
+ * harness map (`/docs` `page.tsx`) all resolve a `DiagramNode` to its docs
+ * location through THIS function — one source of truth, so a card's deep-link,
+ * a "Read more" anchor, and a ring/action page's heading `id` can never point
+ * at three different places for the same node. A parallel, hand-maintained
+ * slug list is the exact failure mode this replaces (the same discipline
+ * `surfaced-manifest.ts` holds for the file allowlist).
+ *
+ * Granularity follows content size. A role or contract is a whole
+ * `aeg-root/**.md` file, so it keeps its own page and needs no anchor. A gate
+ * or check is one row of `enforcement.md`, and an action is one entry of
+ * `ACTIONS`, so each is an `#`-anchored section inside a grouping page
+ * (`/docs/rings/ring-<n>` or `/docs/actions`).
+ *
+ * The anchor slug is recomputed here from the node's DISPLAY form, not read
+ * verbatim off the node id. `node.id`/`node.label` keep the full doctrine
+ * text — G-codes included — because the registry check (G1-G5,
+ * `registry-checks.ts`) matches on that exact id; a slug that a reader
+ * follows into a URL fragment has no such constraint, so it is cleaned at
+ * this one edge instead. Both the heading (`humanLabel`/`shortLabel`, in
+ * `apps/vinaya/web`) and this anchor apply the same two rules — strip a
+ * leading G-code, cut a pathologically long name at its first clause — so a
+ * heading and its anchor still agree, just no longer byte-identical to the
+ * doctrine id. A node whose display form needs no cleanup still gets the
+ * same slug it always did, since stripping/cutting are no-ops on it.
+ *
+ * Zero I/O, additive export — takes an already-derived node, returns data,
+ * never reads a file (aeg-core purity, #372/#382/#506).
+ */
+
+import type { DiagramNode } from '../diagram-model'
+
+export type NodeDocRoute = {
+  /** The page a node lives on. */
+  route: string
+  /** The heading anchor within that page, or `null` for a file-sized node
+   * (role/contract) that owns its whole page. */
+  slug: string | null
+}
+
+/** A pathologically long anchor is cut at its first clause boundary rather
+ * than published whole. 100 is chosen against the current doctrine, not a
+ * round guess: the longest anchor slug outside the one row this exists to
+ * fix is 84 characters (a ring-0 gate's compound name), so 100 leaves that
+ * row untouched while still catching genuinely oversized names — the one
+ * 127-character row this was written for included. */
+const MAX_ANCHOR_SLUG_LENGTH = 100
+
+/** Strips a leading `g<n>-` code off an already-slugified anchor. Operates on
+ * the slug form (not `node.label`) so a node whose id isn't `slugify(label)`
+ * to begin with — an `action`, whose id is the hand-authored `ACTIONS` entry
+ * id, not a re-derivation of its label — is never touched: no G-coded or
+ * over-length action exists today, so this function is a no-op for every one
+ * of them, exactly preserving their existing anchors. */
+function stripGCodeSlug(slug: string): string {
+  return slug.replace(/^g\d+-/, '')
+}
+
+/** Strips the same `G<n> — ` doctrine code off raw label text, for the
+ * over-length fallback below. Same contract as `humanLabel` in
+ * `apps/vinaya/web`'s `display-label.ts` (duplicated rather than shared:
+ * aeg-core cannot import from the web app, and this rule is small enough
+ * that keeping two copies in sync by inspection is cheaper than a new
+ * cross-package export). */
+function stripGCodeLabel(label: string): string {
+  return label.replace(/^G\d+\s*—\s*/, '')
+}
+
+/** Cuts at the first clause boundary, same separator set `shortLabel` uses
+ * in `display-label.ts` — kept in sync with that function's comment by
+ * inspection, for the same reason `stripGCodeLabel` is duplicated above. */
+function firstClause(label: string): string {
+  return label.split(/ \(| \/ |—|–|: /)[0]?.trim() ?? label
+}
+
+/** Same cleanup `diagram-model.ts`'s own (private, un-exported) `slugify`
+ * applies when it stamps a node id — duplicated here rather than imported so
+ * this file never needs `diagram-model.ts` to export it. Reached only by the
+ * over-length fallback below, never by the common case. */
+function slugifyText(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/`/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** The anchor slug for a node's display form. Strips a G-code off the
+ * existing id-stamped slug first — a byte-preserving operation for every
+ * node that never had one. Only if the result is STILL too long to publish
+ * does this fall back to re-deriving a short slug from `node.label`'s first
+ * clause; that fallback is the one path that can produce a slug other than
+ * a prefix of the id-stamped one, and today only one row (a 127-character
+ * ring-0 gate name) reaches it. */
+function nodeSlug(node: DiagramNode): string {
+  const rawSlug = node.id.slice(node.kind.length + 1)
+  const stripped = stripGCodeSlug(rawSlug)
+  if (stripped.length <= MAX_ANCHOR_SLUG_LENGTH) return stripped
+  return slugifyText(firstClause(stripGCodeLabel(node.label)))
+}
+
+/**
+ * Resolve a node to its `/docs` route + anchor slug. Returns `null` for a kind
+ * with no docs surface (there is none today — every kind resolves).
+ */
+export function nodeDocRoute(node: DiagramNode): NodeDocRoute | null {
+  switch (node.kind) {
+    case 'role':
+      return { route: `/docs/roles/${node.label}`, slug: null }
+    case 'contract':
+      return { route: `/docs/contracts/${node.label}`, slug: null }
+    case 'gate':
+    case 'check':
+      if (node.ringIndex === undefined) return null
+      return { route: `/docs/rings/ring-${node.ringIndex}`, slug: nodeSlug(node) }
+    case 'action':
+      return { route: '/docs/actions', slug: nodeSlug(node) }
+    case 'ring':
+      if (node.ringIndex === undefined) return null
+      return { route: `/docs/rings/ring-${node.ringIndex}`, slug: null }
+    default:
+      return null
+  }
+}
+
+/** The full in-app href — `route` plus a `#slug` fragment when the node is an
+ * anchored section. The form the map and `read-more.ts` link to directly. */
+export function nodeDocHref(node: DiagramNode): string | null {
+  const resolved = nodeDocRoute(node)
+  if (!resolved) return null
+  return resolved.slug ? `${resolved.route}#${resolved.slug}` : resolved.route
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/parse-doc.ts

@@ -0,0 +1,43 @@
+import matter from 'gray-matter'
+import type { DocFrontmatter } from './types'
+
+export type ParsedDoc = {
+  frontmatter: DocFrontmatter
+  body: string
+  firstH1?: string
+}
+
+const H1_PATTERN = /^\s*#\s+(.+?)\s*$/m
+
+export function parseDocFrontmatter(raw: string): ParsedDoc {
+  const { data, content } = matter(raw)
+  const fm = data as Record<string, unknown>
+
+  const frontmatter: DocFrontmatter = {}
+  if (typeof fm.title === 'string') frontmatter.title = fm.title
+  if (typeof fm.sidebarTitle === 'string') {
+    frontmatter.sidebarTitle = fm.sidebarTitle
+  } else if (typeof fm.sidebar_title === 'string') {
+    frontmatter.sidebarTitle = fm.sidebar_title
+  }
+  if (typeof fm.description === 'string') frontmatter.description = fm.description
+  if (typeof fm.section === 'string') frontmatter.section = fm.section
+  if (typeof fm.order === 'number') frontmatter.order = fm.order
+  if (typeof fm.parent === 'string') frontmatter.parent = fm.parent
+  if (typeof fm.surfaced === 'boolean') frontmatter.surfaced = fm.surfaced
+
+  const h1Match = content.match(H1_PATTERN)
+  const firstH1 = h1Match?.[1]?.trim()
+
+  return { frontmatter, body: content, firstH1 }
+}
+
+export function deriveTitle(parsed: ParsedDoc, fallbackFromPath: string): string {
+  if (parsed.frontmatter.title) return parsed.frontmatter.title
+  if (parsed.firstH1) return parsed.firstH1
+  return fallbackFromPath
+}
+
+export function stripLeadingH1(body: string): string {
+  return body.replace(/^\s*#\s+.*\n+/, '')
+}