@elevasis/core 0.10.0 → 0.11.1

package/src/scaffold-registry/index.ts

@@ -1,8 +1,10 @@
-import { readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import { type ScaffoldRegistry, type ScaffoldRegistryEntry, ScaffoldRegistrySchema } from './schema'
 
+const MODULE_DIR = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1'))
+
 export {
   ExternalSyncCategorySchema,
   ExternalSyncDeletePolicySchema,
@@ -21,190 +23,236 @@ export type {
   ScaffoldRegistry,
   ScaffoldRegistryEntry
 } from './schema'
-
-// ---------------------------------------------------------------------------
-// Paths (resolved relative to the monorepo root, not this file's location)
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a path relative to the monorepo root.
- * Works whether this module is running from packages/core/src or from dist/.
- */
-function monorepoRoot(): string {
-  // Walk up from __dirname until we find the .claude directory (monorepo marker)
-  const { dirname } = path
-  let dir = __dirname
-  for (let i = 0; i < 8; i++) {
-    try {
-      readFileSync(path.join(dir, '.claude', 'settings.json'))
-      return dir
-    } catch {
-      dir = dirname(dir)
-    }
-  }
-  throw new Error(
-    'scaffold-registry: could not locate monorepo root (no .claude/settings.json found in ancestor directories)'
-  )
-}
-
-const YAML_FILENAME = '.claude/scaffold-registry.yml'
-const JSON_FILENAME = '.claude/scaffold-registry.compiled.json'
-
-// ---------------------------------------------------------------------------
-// Load + validate
-// ---------------------------------------------------------------------------
-
-/**
- * Load and Zod-validate the scaffold registry from `.claude/scaffold-registry.yml`.
- *
- * Throws if:
- * - The YAML file is missing or unreadable
- * - The YAML fails Zod validation
- * - The compiled JSON is present but its `entries` count differs from the YAML
- *   (drift detection — regenerate with `compileScaffoldRegistry()` to fix)
- */
-export function loadScaffoldRegistry(): ScaffoldRegistry {
-  const root = monorepoRoot()
-  const yamlPath = path.join(root, YAML_FILENAME)
-
-  let raw: string
-  try {
-    raw = readFileSync(yamlPath, 'utf-8')
-  } catch (err) {
-    throw new Error(`scaffold-registry: could not read ${YAML_FILENAME} — ${String(err)}`)
-  }
-
-  const parsed = parseYaml(raw) as unknown
-  const result = ScaffoldRegistrySchema.safeParse(parsed)
-
-  if (!result.success) {
-    const issues = result.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
-    throw new Error(`scaffold-registry: YAML validation failed:\n${issues}`)
-  }
-
-  const registry = result.data
-
-  // Drift check: if compiled JSON exists, verify entry count matches
-  const jsonPath = path.join(root, JSON_FILENAME)
-  try {
-    const compiledRaw = readFileSync(jsonPath, 'utf-8')
-    const compiled = JSON.parse(compiledRaw) as { entries?: unknown[] }
-    if (compiled.entries?.length !== registry.entries.length) {
-      throw new Error(
-        `scaffold-registry: compiled JSON is out of sync with YAML ` +
-          `(YAML has ${registry.entries.length} entries, JSON has ${compiled.entries?.length ?? 0}). ` +
-          `Run compileScaffoldRegistry() to regenerate.`
-      )
-    }
-  } catch (err) {
-    // If the file doesn't exist, skip drift check silently (first-run scenario)
-    if ((err as { code?: string }).code !== 'ENOENT') {
-      throw err
-    }
-  }
-
-  return registry
-}
-
-// ---------------------------------------------------------------------------
-// Compile
-// ---------------------------------------------------------------------------
-
-/**
- * Load, validate, and write the pre-compiled JSON lookup file.
- * Run this whenever `.claude/scaffold-registry.yml` changes.
- *
- * Called by the `pnpm scaffold:compile-registry` script (wired in Step 2 CI).
- */
-export function compileScaffoldRegistry(): ScaffoldRegistry {
-  const root = monorepoRoot()
-  const registry = loadScaffoldRegistryNoSyncCheck(root)
-
-  const jsonPath = path.join(root, JSON_FILENAME)
-  writeFileSync(jsonPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8')
-
-  return registry
-}
-
-// ---------------------------------------------------------------------------
-// Lookup helpers (used by hooks for fast path matching)
-// ---------------------------------------------------------------------------
-
-/**
- * Load from the pre-compiled JSON only (fastest path; used by PostToolUse hooks).
- * Falls back to YAML if the JSON is missing.
- */
-export function loadScaffoldRegistryFast(): ScaffoldRegistry {
-  const root = monorepoRoot()
-  const jsonPath = path.join(root, JSON_FILENAME)
-
-  try {
-    const raw = readFileSync(jsonPath, 'utf-8')
-    const parsed = JSON.parse(raw) as unknown
-    const result = ScaffoldRegistrySchema.safeParse(parsed)
-    if (result.success) return result.data
-  } catch {
-    // fall through to YAML
-  }
-
-  return loadScaffoldRegistryNoSyncCheck(root)
-}
-
-/**
- * Return all entries whose `sources` contain at least one pattern that matches
- * the given file path. Pattern matching is a simple substring/glob-prefix check
- * suitable for hook use; Step 3 will upgrade to full micromatch when the hook
- * is implemented.
- */
-export function findMatchingEntries(registry: ScaffoldRegistry, filePath: string): ScaffoldRegistryEntry[] {
-  return registry.entries.filter((entry) => entry.sources.some((pattern) => pathMatchesPattern(filePath, pattern)))
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-function loadScaffoldRegistryNoSyncCheck(root: string): ScaffoldRegistry {
-  const yamlPath = path.join(root, YAML_FILENAME)
-  let raw: string
-  try {
-    raw = readFileSync(yamlPath, 'utf-8')
-  } catch (err) {
-    throw new Error(`scaffold-registry: could not read ${YAML_FILENAME} — ${String(err)}`)
-  }
-  const parsed = parseYaml(raw) as unknown
-  const result = ScaffoldRegistrySchema.safeParse(parsed)
-  if (!result.success) {
-    const issues = result.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
-    throw new Error(`scaffold-registry: YAML validation failed:\n${issues}`)
-  }
-  return result.data
-}
-
-/**
- * Lightweight pattern match: handles exact paths, directory prefixes, and
- * simple `*` wildcards at the end of a segment. Full micromatch lands in Step 3.
- */
-function pathMatchesPattern(filePath: string, pattern: string): boolean {
-  // Normalize separators
-  const normalizedFile = filePath.replace(/\\/g, '/')
-  const normalizedPattern = pattern.replace(/\\/g, '/')
-
-  // Exact match
-  if (normalizedFile === normalizedPattern) return true
-
-  // If pattern ends with `/**` or `/*`, check prefix
-  if (normalizedPattern.endsWith('/**') || normalizedPattern.endsWith('/*')) {
-    const prefix = normalizedPattern.slice(0, normalizedPattern.lastIndexOf('/*'))
-    return normalizedFile.startsWith(prefix + '/')
-  }
-
-  // If pattern contains `*`, convert to simple regex
-  if (normalizedPattern.includes('*')) {
-    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
-    return new RegExp(`^${escaped}$`).test(normalizedFile)
-  }
-
-  // Directory prefix match (pattern is a directory)
-  return normalizedFile.startsWith(normalizedPattern + '/')
-}
+
+// ---------------------------------------------------------------------------
+// Paths (resolved relative to the monorepo root, not this file's location)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a path relative to the monorepo root.
+ * Works whether this module is running from packages/core/src or from dist/.
+ */
+function monorepoRoot(): string {
+  // Walk up from __dirname until we find the .claude directory (monorepo marker)
+  const { dirname } = path
+  let dir = MODULE_DIR
+  for (let i = 0; i < 8; i++) {
+    try {
+      readFileSync(path.join(dir, '.claude', 'settings.json'))
+      return dir
+    } catch {
+      dir = dirname(dir)
+    }
+  }
+  throw new Error(
+    'scaffold-registry: could not locate monorepo root (no .claude/settings.json found in ancestor directories)'
+  )
+}
+
+const YAML_FILENAME = '.claude/scaffold-registry.yml'
+const JSON_FILENAME = '.claude/scaffold-registry.compiled.json'
+
+// ---------------------------------------------------------------------------
+// Load + validate
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and Zod-validate the scaffold registry from `.claude/scaffold-registry.yml`.
+ *
+ * Throws if:
+ * - The YAML file is missing or unreadable
+ * - The YAML fails Zod validation
+ * - The compiled JSON is present but its `entries` count differs from the YAML
+ *   (drift detection — regenerate with `compileScaffoldRegistry()` to fix)
+ */
+export function loadScaffoldRegistry(): ScaffoldRegistry {
+  const root = monorepoRoot()
+  const yamlPath = path.join(root, YAML_FILENAME)
+
+  let raw: string
+  try {
+    raw = readFileSync(yamlPath, 'utf-8')
+  } catch (err) {
+    throw new Error(`scaffold-registry: could not read ${YAML_FILENAME} — ${String(err)}`)
+  }
+
+  const parsed = parseYaml(raw) as unknown
+  const result = ScaffoldRegistrySchema.safeParse(parsed)
+
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
+    throw new Error(`scaffold-registry: YAML validation failed:\n${issues}`)
+  }
+
+  const registry = result.data
+
+  // Drift check: if compiled JSON exists, verify entry count matches
+  const jsonPath = path.join(root, JSON_FILENAME)
+  try {
+    const compiledRaw = readFileSync(jsonPath, 'utf-8')
+    const compiled = JSON.parse(compiledRaw) as { entries?: unknown[] }
+    if (compiled.entries?.length !== registry.entries.length) {
+      throw new Error(
+        `scaffold-registry: compiled JSON is out of sync with YAML ` +
+          `(YAML has ${registry.entries.length} entries, JSON has ${compiled.entries?.length ?? 0}). ` +
+          `Run compileScaffoldRegistry() to regenerate.`
+      )
+    }
+  } catch (err) {
+    // If the file doesn't exist, skip drift check silently (first-run scenario)
+    if ((err as { code?: string }).code !== 'ENOENT') {
+      throw err
+    }
+  }
+
+  return registry
+}
+
+// ---------------------------------------------------------------------------
+// Compile
+// ---------------------------------------------------------------------------
+
+/**
+ * Load, validate, and write the pre-compiled JSON lookup file.
+ * Run this whenever `.claude/scaffold-registry.yml` changes.
+ *
+ * Called by the `pnpm scaffold:compile-registry` script (wired in Step 2 CI).
+ */
+export function compileScaffoldRegistry(): ScaffoldRegistry {
+  const root = monorepoRoot()
+  const registry = loadScaffoldRegistryNoSyncCheck(root)
+
+  const missing = findMissingDependentPaths(registry, root)
+  if (missing.length > 0) {
+    const formatted = missing.map((m) => `  [${m.entryId}] ${m.path}`).join('\n')
+    throw new Error(
+      `scaffold-registry: ${missing.length} dependent path(s) do not exist on disk:\n${formatted}\n` +
+        `Fix the typo, create the file, or convert the path to a glob/symbolic target.`
+    )
+  }
+
+  const jsonPath = path.join(root, JSON_FILENAME)
+  writeFileSync(jsonPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8')
+
+  return registry
+}
+
+/**
+ * Return dependent paths declared in the registry that don't exist on disk.
+ * Skips symbolic targets (`docs:`, `autogen-target:`) and glob patterns
+ * (those containing `*`, `?`, or `[`), which can't be resolved to a single file.
+ *
+ * Exported so external scripts (e.g. CI gates) can run the same check.
+ */
+export function findMissingDependentPaths(
+  registry: ScaffoldRegistry,
+  monorepoRootDir: string
+): Array<{ entryId: string; path: string }> {
+  const missing: Array<{ entryId: string; path: string }> = []
+  for (const entry of registry.entries) {
+    // sync-preservation dependents describe paths inside derived external
+    // projects (not files that physically exist in this monorepo), so skip them.
+    if (entry.kind === 'sync-preservation') continue
+    for (const dependent of entry.dependents) {
+      if (isSymbolicTarget(dependent.path) || isGlobPattern(dependent.path) || dependent.path === '(self)') {
+        continue
+      }
+      const absolute = path.join(monorepoRootDir, dependent.path)
+      if (!existsSync(absolute)) {
+        missing.push({ entryId: entry.id, path: dependent.path })
+      }
+    }
+  }
+  return missing
+}
+
+// ---------------------------------------------------------------------------
+// Lookup helpers (used by hooks for fast path matching)
+// ---------------------------------------------------------------------------
+
+/**
+ * Load from the pre-compiled JSON only (fastest path; used by PostToolUse hooks).
+ * Falls back to YAML if the JSON is missing.
+ */
+export function loadScaffoldRegistryFast(): ScaffoldRegistry {
+  const root = monorepoRoot()
+  const jsonPath = path.join(root, JSON_FILENAME)
+
+  try {
+    const raw = readFileSync(jsonPath, 'utf-8')
+    const parsed = JSON.parse(raw) as unknown
+    const result = ScaffoldRegistrySchema.safeParse(parsed)
+    if (result.success) return result.data
+  } catch {
+    // fall through to YAML
+  }
+
+  return loadScaffoldRegistryNoSyncCheck(root)
+}
+
+/**
+ * Return all entries whose `sources` contain at least one pattern that matches
+ * the given file path. Pattern matching is a simple substring/glob-prefix check
+ * suitable for hook use; Step 3 will upgrade to full micromatch when the hook
+ * is implemented.
+ */
+export function findMatchingEntries(registry: ScaffoldRegistry, filePath: string): ScaffoldRegistryEntry[] {
+  return registry.entries.filter((entry) => entry.sources.some((pattern) => pathMatchesPattern(filePath, pattern)))
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function loadScaffoldRegistryNoSyncCheck(root: string): ScaffoldRegistry {
+  const yamlPath = path.join(root, YAML_FILENAME)
+  let raw: string
+  try {
+    raw = readFileSync(yamlPath, 'utf-8')
+  } catch (err) {
+    throw new Error(`scaffold-registry: could not read ${YAML_FILENAME} — ${String(err)}`)
+  }
+  const parsed = parseYaml(raw) as unknown
+  const result = ScaffoldRegistrySchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
+    throw new Error(`scaffold-registry: YAML validation failed:\n${issues}`)
+  }
+  return result.data
+}
+
+function isSymbolicTarget(p: string): boolean {
+  return p.startsWith('docs:') || p.startsWith('autogen-target:')
+}
+
+function isGlobPattern(p: string): boolean {
+  return /[*?[]/.test(p)
+}
+
+/**
+ * Lightweight pattern match: handles exact paths, directory prefixes, and
+ * simple `*` wildcards at the end of a segment. Full micromatch lands in Step 3.
+ */
+function pathMatchesPattern(filePath: string, pattern: string): boolean {
+  // Normalize separators
+  const normalizedFile = filePath.replace(/\\/g, '/')
+  const normalizedPattern = pattern.replace(/\\/g, '/')
+
+  // Exact match
+  if (normalizedFile === normalizedPattern) return true
+
+  // If pattern ends with `/**` or `/*`, check prefix
+  if (normalizedPattern.endsWith('/**') || normalizedPattern.endsWith('/*')) {
+    const prefix = normalizedPattern.slice(0, normalizedPattern.lastIndexOf('/*'))
+    return normalizedFile.startsWith(prefix + '/')
+  }
+
+  // If pattern contains `*`, convert to simple regex
+  if (normalizedPattern.includes('*')) {
+    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
+    return new RegExp(`^${escaped}$`).test(normalizedFile)
+  }
+
+  // Directory prefix match (pattern is a directory)
+  return normalizedFile.startsWith(normalizedPattern + '/')
+}

package/src/scaffold-registry/schema.ts

@@ -9,23 +9,17 @@ import { z } from 'zod'
  *
  * - autogen: fully derivable from source; regen command is the fix
  * - manual-scaffold: hand-authored structure that must be updated on source change
- * - typed-id: typed-ID constants that encode semantic naming decisions
- * - sync-preservation: external-template files with a declared sync tier
- * - vibe-gated: paths protected by the pre-edit-vibe-gate hook
- * - sdk-cli-generator: SDK CLI generators (generate-docs-index, generate-resources, etc.)
- * - validator: drift-detection scripts or CI checks (meta.json pages[] validators, etc.)
- * - other: escape hatch; requires free-form notes
- */
+ * - sync-preservation: external-template files with a declared sync tier
+ * - validator: drift-detection scripts or CI checks (meta.json pages[] validators, etc.)
+ * - other: escape hatch; requires free-form notes
+ */
 export const ScaffoldEntryKindSchema = z.enum([
   'autogen',
   'manual-scaffold',
-  'typed-id',
   'sync-preservation',
-  'vibe-gated',
-  'sdk-cli-generator',
-  'validator',
-  'other'
-])
+  'validator',
+  'other'
+])
 
 export type ScaffoldEntryKind = z.infer<typeof ScaffoldEntryKindSchema>
 
@@ -78,15 +72,9 @@ export const ScaffoldRefSchema = z.object({
    */
   regen: z.string().min(1).optional(),
 
-  /**
-   * Optionally narrow the kind of this specific scaffold reference, when it
-   * differs from the parent entry's kind.
-   */
-  kind: ScaffoldEntryKindSchema.optional(),
-
-  /**
-   * Human-readable hint shown in reminder messages.
-   */
+  /**
+   * Human-readable hint shown in reminder messages.
+   */
   hint: z.string().optional()
 })
 
@@ -191,6 +179,43 @@ export const ScaffoldRegistryEntrySchema = z
         })
       }
     }
+
+    if (entry.kind === 'autogen' && !entry.regen) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['regen'],
+        message: 'kind: autogen requires a top-level regen command'
+      })
+    }
+
+    if (entry.kind === 'validator') {
+      const hasVerifier = entry.dependents.some((dependent) => dependent.regen && dependent.regen !== 'manual')
+      if (!hasVerifier) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['dependents'],
+          message: 'kind: validator requires at least one executable dependent regen command'
+        })
+      }
+    }
+
+    if (entry.kind === 'other' && !entry.notes) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['notes'],
+        message: 'kind: other requires notes explaining why no narrower kind fits'
+      })
+    }
+
+    if (entry.kind === 'sync-preservation') {
+      if (!entry.category || !entry.strategy || !entry.delete_policy) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['category'],
+          message: 'kind: sync-preservation requires category, strategy, and delete_policy'
+        })
+      }
+    }
   })
 
 export type ScaffoldRegistryEntry = z.infer<typeof ScaffoldRegistryEntrySchema>