@elevasis/core 0.11.2 → 0.13.0

package/src/scaffold-registry/__tests__/index.test.ts

@@ -1,5 +1,15 @@
-import { describe, expect, it } from 'vitest'
-import { findMatchingEntries, findMissingDependentPaths, loadScaffoldRegistryFast } from '../index'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  findEmptySourcePatterns,
+  findMatchingEntries,
+  findMissingDependentPaths,
+  loadScaffoldRegistryFast,
+  normalizeScaffoldPath,
+  scaffoldPathMatchesPattern
+} from '../index'
 import type { ScaffoldRegistry, ScaffoldRegistryEntry } from '../schema'
 
 function makeEntry(id: string, sources: string[]): ScaffoldRegistryEntry {
@@ -20,6 +30,21 @@ function matchedIds(registry: ScaffoldRegistry, filePath: string): string[] {
   return findMatchingEntries(registry, filePath).map((e) => e.id)
 }
 
+let tempRoots: string[] = []
+
+function makeTempRoot(): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'scaffold-registry-'))
+  tempRoots.push(root)
+  return root
+}
+
+afterEach(() => {
+  for (const root of tempRoots) {
+    rmSync(root, { recursive: true, force: true })
+  }
+  tempRoots = []
+})
+
 describe('loadScaffoldRegistryFast', () => {
   it('preserves external sync metadata from the compiled registry', () => {
     const registry = loadScaffoldRegistryFast()
@@ -89,6 +114,10 @@ describe('findMissingDependentPaths', () => {
 })
 
 describe('findMatchingEntries (pattern matching)', () => {
+  it('normalizes Windows and relative paths', () => {
+    expect(normalizeScaffoldPath('.\\packages\\core\\src\\')).toBe('packages/core/src')
+  })
+
   it('matches exact paths', () => {
     const reg = registryFromEntries([makeEntry('exact', ['packages/core/src/index.ts'])])
     expect(matchedIds(reg, 'packages/core/src/index.ts')).toEqual(['exact'])
@@ -110,12 +139,11 @@ describe('findMatchingEntries (pattern matching)', () => {
     expect(matchedIds(reg, 'packages/core/nested/package.json')).toEqual([])
   })
 
-  it('current matcher does NOT support mixed **/*.ext patterns (Step 3 upgrade)', () => {
-    // The simple matcher's `/*` suffix branch only handles a single trailing
-    // wildcard. Patterns like `**/*.ts` fall through and effectively miss real
-    // files. Locked in to flag any change when full micromatch lands.
+  it('matches mixed **/*.ext patterns at direct-child and nested depths', () => {
     const reg = registryFromEntries([makeEntry('ext', ['apps/api/src/**/*.ts'])])
-    expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual([])
+    expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual(['ext'])
+    expect(matchedIds(reg, 'apps/api/src/nested/deeply/foo.ts')).toEqual(['ext'])
+    expect(matchedIds(reg, 'apps/api/src/foo.tsx')).toEqual([])
   })
 
   it('normalizes Windows backslashes to forward slashes', () => {
@@ -138,4 +166,41 @@ describe('findMatchingEntries (pattern matching)', () => {
     const reg = registryFromEntries([makeEntry('a', ['packages/core/src/**'])])
     expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual([])
   })
+
+  it('exposes the same matcher for direct consumers', () => {
+    expect(scaffoldPathMatchesPattern('packages/core/src/foo.test.ts', 'packages/core/src/**/*.ts')).toBe(true)
+    expect(scaffoldPathMatchesPattern('packages/core/src/foo.test.ts', 'packages/ui/src/**/*.ts')).toBe(false)
+  })
+})
+
+describe('findEmptySourcePatterns', () => {
+  it('flags source patterns that do not match any file or directory', () => {
+    const root = makeTempRoot()
+    mkdirSync(path.join(root, 'packages', 'core', 'src'), { recursive: true })
+    writeFileSync(path.join(root, 'packages', 'core', 'src', 'index.ts'), 'export {}\n', 'utf8')
+
+    const registry = registryFromEntries([
+      makeEntry('ok-exact', ['packages/core/src/index.ts']),
+      makeEntry('ok-glob', ['packages/core/src/**/*.ts']),
+      makeEntry('empty', ['packages/core/src/**/*.tsx'])
+    ])
+
+    expect(findEmptySourcePatterns(registry, root)).toEqual([
+      { entryId: 'empty', pattern: 'packages/core/src/**/*.tsx' }
+    ])
+  })
+
+  it('treats exact directories as non-empty source coverage', () => {
+    const root = makeTempRoot()
+    mkdirSync(path.join(root, 'external', '_template', '.claude', 'skills'), { recursive: true })
+
+    const registry = registryFromEntries([
+      makeEntry('dir', ['external/_template/.claude/skills']),
+      makeEntry('missing-dir', ['external/_template/.claude/commands'])
+    ])
+
+    expect(findEmptySourcePatterns(registry, root)).toEqual([
+      { entryId: 'missing-dir', pattern: 'external/_template/.claude/commands' }
+    ])
+  })
 })

package/src/scaffold-registry/index.ts

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import { type ScaffoldRegistry, type ScaffoldRegistryEntry, ScaffoldRegistrySchema } from './schema'
@@ -86,15 +87,23 @@ export function loadScaffoldRegistry(): ScaffoldRegistry {
 
   const registry = result.data
 
-  // Drift check: if compiled JSON exists, verify entry count matches
+  // Drift check: if compiled JSON exists, verify the full normalized content 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) {
+    const compiledParsed = JSON.parse(compiledRaw) as unknown
+    const compiledResult = ScaffoldRegistrySchema.safeParse(compiledParsed)
+    if (!compiledResult.success) {
+      const issues = compiledResult.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
+      throw new Error(`scaffold-registry: compiled JSON validation failed:\n${issues}`)
+    }
+
+    const yamlHash = stableRegistryHash(registry)
+    const compiledHash = stableRegistryHash(compiledResult.data)
+    if (compiledHash !== yamlHash) {
       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}). ` +
+          `(YAML hash ${yamlHash.slice(0, 12)}, JSON hash ${compiledHash.slice(0, 12)}). ` +
           `Run compileScaffoldRegistry() to regenerate.`
       )
     }
@@ -131,6 +140,15 @@ export function compileScaffoldRegistry(): ScaffoldRegistry {
     )
   }
 
+  const emptySources = findEmptySourcePatterns(registry, root)
+  if (emptySources.length > 0) {
+    const formatted = emptySources.map((source) => `  [${source.entryId}] ${source.pattern}`).join('\n')
+    throw new Error(
+      `scaffold-registry: ${emptySources.length} source pattern(s) match no files or directories:\n${formatted}\n` +
+        `Fix the stale source glob, create the scaffold surface, or add explicit registry support for intentional empty patterns.`
+    )
+  }
+
   const jsonPath = path.join(root, JSON_FILENAME)
   writeFileSync(jsonPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8')
 
@@ -166,6 +184,29 @@ export function findMissingDependentPaths(
   return missing
 }
 
+/**
+ * Return source patterns that do not currently match any file or directory.
+ * Symbolic sources are skipped because they intentionally do not resolve to
+ * monorepo paths.
+ */
+export function findEmptySourcePatterns(
+  registry: ScaffoldRegistry,
+  monorepoRootDir: string
+): Array<{ entryId: string; pattern: string }> {
+  const empty: Array<{ entryId: string; pattern: string }> = []
+
+  for (const entry of registry.entries) {
+    for (const sourcePattern of entry.sources) {
+      if (isSymbolicTarget(sourcePattern)) continue
+      if (!sourcePatternMatchesAnyPath(sourcePattern, monorepoRootDir)) {
+        empty.push({ entryId: entry.id, pattern: sourcePattern })
+      }
+    }
+  }
+
+  return empty
+}
+
 // ---------------------------------------------------------------------------
 // Lookup helpers (used by hooks for fast path matching)
 // ---------------------------------------------------------------------------
@@ -192,12 +233,17 @@ export function loadScaffoldRegistryFast(): ScaffoldRegistry {
 
 /**
  * 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.
+ * the given file path AND whose `excludes` contain no pattern that matches.
+ * 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)))
+  return registry.entries.filter((entry) => {
+    const sourceMatch = entry.sources.some((pattern) => scaffoldPathMatchesPattern(filePath, pattern))
+    if (!sourceMatch) return false
+    const excluded = (entry.excludes ?? []).some((pattern) => scaffoldPathMatchesPattern(filePath, pattern))
+    return !excluded
+  })
 }
 
 // ---------------------------------------------------------------------------
@@ -221,6 +267,24 @@ function loadScaffoldRegistryNoSyncCheck(root: string): ScaffoldRegistry {
   return result.data
 }
 
+export function normalizeScaffoldPath(p: string): string {
+  return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
+}
+
+export function scaffoldPathMatchesPattern(filePath: string, pattern: string): boolean {
+  const normalizedFile = normalizeScaffoldPath(filePath)
+  const normalizedPattern = normalizeScaffoldPath(pattern)
+
+  if (!normalizedFile || !normalizedPattern) return false
+  if (normalizedFile === normalizedPattern) return true
+
+  if (!isGlobPattern(normalizedPattern)) {
+    return normalizedFile.startsWith(normalizedPattern + '/')
+  }
+
+  return globToRegExp(normalizedPattern).test(normalizedFile)
+}
+
 function isSymbolicTarget(p: string): boolean {
   return p.startsWith('docs:') || p.startsWith('autogen-target:')
 }
@@ -229,30 +293,100 @@ 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, '/')
+function stableRegistryHash(registry: ScaffoldRegistry): string {
+  return createHash('sha256').update(JSON.stringify(registry)).digest('hex')
+}
 
-  // Exact match
-  if (normalizedFile === normalizedPattern) return true
+function globToRegExp(pattern: string): RegExp {
+  const segments = pattern.split('/')
+  let regex = '^'
+
+  for (let index = 0; index < segments.length; index++) {
+    const segment = segments[index]
+    const isLast = index === segments.length - 1
+
+    if (segment === '**') {
+      regex += isLast ? '(?:.*)?' : '(?:[^/]+/)*'
+      continue
+    }
+
+    regex += segmentToRegExpSource(segment)
+    if (!isLast) regex += '/'
+  }
+
+  regex += '$'
+  return new RegExp(regex)
+}
+
+function segmentToRegExpSource(segment: string): string {
+  let source = ''
+  for (let index = 0; index < segment.length; index++) {
+    const char = segment[index]
+    if (char === '*') {
+      source += '[^/]*'
+    } else if (char === '?') {
+      source += '[^/]'
+    } else {
+      source += escapeRegExp(char)
+    }
+  }
+  return source
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')
+}
+
+function sourcePatternMatchesAnyPath(sourcePattern: string, monorepoRootDir: string): boolean {
+  const normalizedPattern = normalizeScaffoldPath(sourcePattern)
 
-  // If pattern ends with `/**` or `/*`, check prefix
-  if (normalizedPattern.endsWith('/**') || normalizedPattern.endsWith('/*')) {
-    const prefix = normalizedPattern.slice(0, normalizedPattern.lastIndexOf('/*'))
-    return normalizedFile.startsWith(prefix + '/')
+  if (!isGlobPattern(normalizedPattern)) {
+    return existsSync(path.join(monorepoRootDir, normalizedPattern))
   }
 
-  // If pattern contains `*`, convert to simple regex
-  if (normalizedPattern.includes('*')) {
-    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
-    return new RegExp(`^${escaped}$`).test(normalizedFile)
+  const baseDir = findGlobBaseDirectory(normalizedPattern)
+  const absoluteBase = path.join(monorepoRootDir, baseDir)
+  if (!existsSync(absoluteBase)) return false
+
+  return walkUntilMatch(absoluteBase, monorepoRootDir, normalizedPattern)
+}
+
+function findGlobBaseDirectory(pattern: string): string {
+  const segments = pattern.split('/')
+  const baseSegments: string[] = []
+  for (const segment of segments) {
+    if (isGlobPattern(segment)) break
+    baseSegments.push(segment)
+  }
+  return baseSegments.join('/')
+}
+
+function walkUntilMatch(currentPath: string, monorepoRootDir: string, pattern: string): boolean {
+  const rel = normalizeScaffoldPath(path.relative(monorepoRootDir, currentPath))
+  if (rel && scaffoldPathMatchesPattern(rel, pattern)) return true
+
+  let entries
+  try {
+    entries = readdirSync(currentPath, { withFileTypes: true })
+  } catch {
+    return false
+  }
+
+  for (const entry of entries) {
+    const absolutePath = path.join(currentPath, entry.name)
+    const relativePath = normalizeScaffoldPath(path.relative(monorepoRootDir, absolutePath))
+
+    if (scaffoldPathMatchesPattern(relativePath, pattern)) return true
+    if (entry.isDirectory()) {
+      try {
+        if (statSync(absolutePath).isDirectory() && walkUntilMatch(absolutePath, monorepoRootDir, pattern)) {
+          return true
+        }
+      } catch {
+        continue
+      }
+    }
   }
 
-  // Directory prefix match (pattern is a directory)
-  return normalizedFile.startsWith(normalizedPattern + '/')
+  return false
 }

package/src/scaffold-registry/schema.ts

@@ -1,25 +1,19 @@
-import { z } from 'zod'
-
-// ---------------------------------------------------------------------------
-// Kind taxonomy
-// ---------------------------------------------------------------------------
-
-/**
- * The kind of scaffold entry:
- *
- * - autogen: fully derivable from source; regen command is the fix
- * - manual-scaffold: hand-authored structure that must be updated on source change
+import { z } from 'zod'
+
+// ---------------------------------------------------------------------------
+// Kind taxonomy
+// ---------------------------------------------------------------------------
+
+/**
+ * The kind of scaffold entry:
+ *
+ * - autogen: fully derivable from source; regen command is the fix
+ * - manual-scaffold: hand-authored structure that must be updated on source change
  * - 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',
-  'sync-preservation',
-  'validator',
-  'other'
-])
+export const ScaffoldEntryKindSchema = z.enum(['autogen', 'manual-scaffold', 'sync-preservation', 'validator', 'other'])
 
 export type ScaffoldEntryKind = z.infer<typeof ScaffoldEntryKindSchema>
 
@@ -55,35 +49,35 @@ export type ExternalSyncStrategy = z.infer<typeof ExternalSyncStrategySchema>
 export const ExternalSyncDeletePolicySchema = z.enum(['none', 'manifest-only'])
 
 export type ExternalSyncDeletePolicy = z.infer<typeof ExternalSyncDeletePolicySchema>
-
-// ---------------------------------------------------------------------------
-// Scaffold reference (a single downstream artifact that needs attention)
-// ---------------------------------------------------------------------------
-
-export const ScaffoldRefSchema = z.object({
-  /**
-   * File path, glob, or symbolic target (e.g. "docs: sync-preservation-matrix").
-   * Symbolic targets begin with "docs:" or "autogen-target:".
-   */
-  path: z.string().min(1),
-
-  /**
-   * Command to regenerate, or "manual" if human judgment is required.
-   */
-  regen: z.string().min(1).optional(),
-
+
+// ---------------------------------------------------------------------------
+// Scaffold reference (a single downstream artifact that needs attention)
+// ---------------------------------------------------------------------------
+
+export const ScaffoldRefSchema = z.object({
+  /**
+   * File path, glob, or symbolic target (e.g. "docs: sync-preservation-matrix").
+   * Symbolic targets begin with "docs:" or "autogen-target:".
+   */
+  path: z.string().min(1),
+
+  /**
+   * Command to regenerate, or "manual" if human judgment is required.
+   */
+  regen: z.string().min(1).optional(),
+
   /**
    * Human-readable hint shown in reminder messages.
    */
-  hint: z.string().optional()
-})
-
-export type ScaffoldRef = z.infer<typeof ScaffoldRefSchema>
-
-// ---------------------------------------------------------------------------
-// Registry entry
-// ---------------------------------------------------------------------------
-
+  hint: z.string().optional()
+})
+
+export type ScaffoldRef = z.infer<typeof ScaffoldRefSchema>
+
+// ---------------------------------------------------------------------------
+// Registry entry
+// ---------------------------------------------------------------------------
+
 export const ScaffoldRegistryEntrySchema = z
   .object({
     /**
@@ -106,6 +100,18 @@ export const ScaffoldRegistryEntrySchema = z
      */
     sources: z.array(z.string().min(1)).min(1, 'At least one source pattern is required'),
 
+    /**
+     * Optional glob patterns that suppress this entry's reminder when the
+     * touched file matches. Applied after `sources`: a path that matches any
+     * `sources` pattern AND any `excludes` pattern is treated as no-match.
+     *
+     * Use case: a broad source glob (e.g. `apps/docs/content/docs/**\/*.mdx`)
+     * that should not fire on a sub-tree where the dependent scaffold does not
+     * apply (e.g. `apps/docs/content/docs/in-progress/**`, where MDX docs do
+     * not take meta.json files).
+     */
+    excludes: z.array(z.string().min(1)).optional(),
+
     /**
      * Downstream artifacts that need attention when a source changes.
      */
@@ -217,21 +223,21 @@ export const ScaffoldRegistryEntrySchema = z
       }
     }
   })
-
-export type ScaffoldRegistryEntry = z.infer<typeof ScaffoldRegistryEntrySchema>
-
-// ---------------------------------------------------------------------------
-// Top-level registry document
-// ---------------------------------------------------------------------------
-
-export const ScaffoldRegistrySchema = z.object({
-  /**
-   * Schema version for forward-compatibility detection.
-   * Bump when the shape changes in a breaking way.
-   */
-  version: z.string().default('1'),
-
-  entries: z.array(ScaffoldRegistryEntrySchema).min(1)
-})
-
-export type ScaffoldRegistry = z.infer<typeof ScaffoldRegistrySchema>
+
+export type ScaffoldRegistryEntry = z.infer<typeof ScaffoldRegistryEntrySchema>
+
+// ---------------------------------------------------------------------------
+// Top-level registry document
+// ---------------------------------------------------------------------------
+
+export const ScaffoldRegistrySchema = z.object({
+  /**
+   * Schema version for forward-compatibility detection.
+   * Bump when the shape changes in a breaking way.
+   */
+  version: z.string().default('1'),
+
+  entries: z.array(ScaffoldRegistryEntrySchema).min(1)
+})
+
+export type ScaffoldRegistry = z.infer<typeof ScaffoldRegistrySchema>