@numbered/docs-to-context 0.1.5 → 0.3.0

package/scripts/extract.ts

@@ -199,7 +199,7 @@ function generateNextjsMdx(comp: NextjsComponent): string {
 
 function scanNextjs(projectRoot: string, dirs?: string[], outputDir?: string): NextjsComponent[] {
 	const root = resolve(projectRoot)
-	const outDir = outputDir ?? join(root, 'docs', 'components')
+	const outDir = outputDir ?? join(root, '.context', 'components')
 	const scanDirs = dirs ?? ['packages/ui/components']
 
 	mkdirSync(outDir, { recursive: true })
@@ -340,7 +340,7 @@ function generateShopifyMdx(snippet: ShopifySnippet): string {
 
 function scanShopify(projectRoot: string, outputDir?: string): ShopifySnippet[] {
 	const root = resolve(projectRoot)
-	const outDir = outputDir ?? join(root, 'docs', 'components')
+	const outDir = outputDir ?? join(root, '.context', 'components')
 	const snippetsDir = join(root, 'snippets')
 
 	if (!isDir(snippetsDir)) {

package/scripts/generate.ts

@@ -11,7 +11,7 @@
  */
 
 import { resolve } from 'node:path'
-import { extract } from './extract'
+import { detectPlatform, extract } from './extract'
 import { inject } from './inject'
 import { log } from './log'
 
@@ -42,6 +42,13 @@ for (let i = 0; i < args.length; i++) {
 
 projectRoot = resolve(projectRoot)
 
+// ── Detect platform early ──────────────────────────────────────────────
+
+if (!platform) {
+	const detected = detectPlatform(projectRoot)
+	if (detected) platform = detected
+}
+
 // ── Run ────────────────────────────────────────────────────────────────
 
 log.banner()
@@ -50,6 +57,6 @@ log.section('Extract')
 extract({ projectRoot, platform, dirs, outputDir })
 
 log.section('Inject')
-inject({ projectRoot, docsDir: outputDir })
+inject({ projectRoot, docsDir: outputDir, platform })
 
 log.done()

package/scripts/inject.ts

@@ -1,12 +1,13 @@
 /**
  * Inject project docs INDEX into CLAUDE.md between marker comments.
  *
- * Reads the INDEX file from docs/components/ and injects a compact reference
+ * Reads the INDEX file from .context/components/ and injects a compact reference
  * between <!-- PROJECT_DOCS_START --> and <!-- PROJECT_DOCS_END --> markers.
- * Also discovers core docs (design system, grid, architecture) and includes them.
+ * Also discovers core docs (design system, grid, architecture) and copies
+ * bundled best-practice docs for the detected platform.
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import { isDir, isFile, walkDir } from './fs'
 import { log } from './log'
@@ -21,6 +22,7 @@ const MARKER_PATTERN = new RegExp(
 	+ MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
 )
 const CORE_DOCS_ROOT = 'docs'
+const CONTEXT_ROOT = '.context'
 const REGENERATE_CMD = 'bunx @numbered/docs-to-context'
 
 // ── Types ──────────────────────────────────────────────────────────────
@@ -28,6 +30,7 @@ const REGENERATE_CMD = 'bunx @numbered/docs-to-context'
 interface CoreDocs {
 	frontend: string[]
 	entities: string[]
+	bestPractices: string[]
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────
@@ -45,11 +48,57 @@ function groupByDir(paths: string[]): [string, string[]][] {
 	return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))
 }
 
+// ── Platform → doc folder mapping ─────────────────────────────────────
+
+const PLATFORM_DOC_FOLDER: Record<string, string> = {
+	nextjs: 'react',
+	shopify: 'liquid',
+}
+
+// ── Best practices copy ───────────────────────────────────────────────
+
+function copyBestPractices(projectRoot: string, platform: string): string[] {
+	const folder = PLATFORM_DOC_FOLDER[platform]
+	if (!folder) return []
+
+	const bundledDir = resolve(import.meta.dir, '..', 'docs', folder)
+	if (!isDir(bundledDir)) return []
+
+	const destDir = join(projectRoot, CONTEXT_ROOT, 'best-practices')
+	mkdirSync(destDir, { recursive: true })
+
+	const files = walkDir(bundledDir, ['.md', '.mdx'])
+	const copied: string[] = []
+
+	// Ensure README is first so the index is always listed before patterns
+	files.sort((a, b) => {
+		const aName = a.slice(a.lastIndexOf('/') + 1)
+		const bName = b.slice(b.lastIndexOf('/') + 1)
+		const aReadme = aName.toLowerCase().startsWith('readme')
+		const bReadme = bName.toLowerCase().startsWith('readme')
+		if (aReadme && !bReadme) return -1
+		if (!aReadme && bReadme) return 1
+		return aName.localeCompare(bName)
+	})
+
+	for (const src of files) {
+		const name = src.slice(src.lastIndexOf('/') + 1)
+		copyFileSync(src, join(destDir, name))
+		copied.push(`best-practices/${name}`)
+	}
+
+	if (copied.length) {
+		log.success(`Copied ${copied.length} best practice doc(s)`)
+	}
+
+	return copied
+}
+
 // ── Core docs discovery ────────────────────────────────────────────────
 
-function discoverCoreDocs(projectRoot: string): CoreDocs {
+function discoverCoreDocs(projectRoot: string, bestPractices: string[]): CoreDocs {
 	const docsDir = join(projectRoot, CORE_DOCS_ROOT)
-	const result: CoreDocs = { frontend: [], entities: [] }
+	const result: CoreDocs = { frontend: [], entities: [], bestPractices }
 
 	if (!isDir(docsDir)) return result
 
@@ -69,16 +118,17 @@ function discoverCoreDocs(projectRoot: string): CoreDocs {
 
 // ── Block builder ──────────────────────────────────────────────────────
 
-function buildComponentLines(docsDirRel: string, names: string[]): string[] {
+function buildComponentLines(names: string[]): string[] {
+	const root = `./${CONTEXT_ROOT}/components`
 	return [
-		`[Component Index]|root: ./${docsDirRel}`,
+		`[Component Index]|root: ${root}`,
 		'|IMPORTANT: Read component MDX before using any component',
 		`|components:{${names.join(',')}}`,
-		`|If ./${docsDirRel} is missing, run: ${REGENERATE_CMD}`,
+		`|If ${root} is missing, run: ${REGENERATE_CMD}`,
 	]
 }
 
-function buildIndexBlock(indexPath: string, docsDirRel: string, coreDocs: CoreDocs | null): string | null {
+function buildIndexBlock(indexPath: string, coreDocs: CoreDocs | null): string | null {
 	const indexContent = readFileSync(indexPath, 'utf-8').trim()
 
 	const names: string[] = []
@@ -91,20 +141,29 @@ function buildIndexBlock(indexPath: string, docsDirRel: string, coreDocs: CoreDo
 	if (names.length === 0) return null
 
 	const lines: string[] = [MARKER_START, '## Project Docs']
-	const root = `./${CORE_DOCS_ROOT}`
+	const docsRoot = `./${CORE_DOCS_ROOT}`
 
 	// Frontend
 	if (coreDocs?.frontend.length) {
-		lines.push(`|[Frontend]|root: ${root}`)
+		lines.push(`|[Frontend]|root: ${docsRoot}`)
 		lines.push(`|frontend:{${coreDocs.frontend.join(',')}}`)
 	}
 
+	// Best Practices
+	if (coreDocs?.bestPractices.length) {
+		const contextRoot = `./${CONTEXT_ROOT}`
+		const fileNames = coreDocs.bestPractices.map((p) => p.slice(p.lastIndexOf('/') + 1))
+		lines.push(`|[Best Practices]|root: ${contextRoot}`)
+		lines.push(`|best-practices:{${fileNames.join(',')}}`)
+		lines.push('|IMPORTANT: Read best-practices/README.mdx first — it indexes all patterns by category and impact')
+	}
+
 	// Components (always present)
-	lines.push(...buildComponentLines(docsDirRel, names))
+	lines.push(...buildComponentLines(names))
 
 	// Entities (grouped by directory)
 	if (coreDocs?.entities.length) {
-		lines.push(`|[Entities]|root: ${root}`)
+		lines.push(`|[Entities]|root: ${docsRoot}`)
 		for (const [dirPath, files] of groupByDir(coreDocs.entities)) {
 			lines.push(`|${dirPath}:{${files.join(',')}}`)
 		}
@@ -140,18 +199,18 @@ function injectIntoClaudeMd(claudeMdPath: string, block: string) {
 
 // ── .gitignore ─────────────────────────────────────────────────────────
 
-function ensureGitignore(projectRoot: string, docsDirRel: string) {
+function ensureGitignore(projectRoot: string) {
 	const gitignorePath = join(projectRoot, '.gitignore')
-	const entry = docsDirRel.replace(/\/+$/, '') + '/'
+	const entry = `${CONTEXT_ROOT}/`
 
 	if (existsSync(gitignorePath)) {
 		const content = readFileSync(gitignorePath, 'utf-8')
-		if (content.includes(entry) || content.includes(docsDirRel)) return
+		if (content.includes(entry) || content.includes(CONTEXT_ROOT)) return
 
 		const padded = content.endsWith('\n') ? content : content + '\n'
-		writeFileSync(gitignorePath, padded + `\n# Generated component docs\n${entry}\n`, 'utf-8')
+		writeFileSync(gitignorePath, padded + `\n# Generated project context\n${entry}\n`, 'utf-8')
 	} else {
-		writeFileSync(gitignorePath, `# Generated component docs\n${entry}\n`, 'utf-8')
+		writeFileSync(gitignorePath, `# Generated project context\n${entry}\n`, 'utf-8')
 	}
 
 	log.info(`Added ${entry} to .gitignore`)
@@ -164,11 +223,12 @@ export interface InjectOptions {
 	indexPath?: string
 	claudeMdPath?: string
 	docsDir?: string
+	platform?: 'nextjs' | 'shopify'
 }
 
 export function inject(opts: InjectOptions) {
 	const root = resolve(opts.projectRoot)
-	const docsDir = opts.docsDir ?? 'docs/components'
+	const docsDir = opts.docsDir ?? `${CONTEXT_ROOT}/components`
 	const indexPath = opts.indexPath ?? join(root, docsDir, 'INDEX')
 	const claudeMdPath = opts.claudeMdPath ?? join(root, 'CLAUDE.md')
 
@@ -178,16 +238,19 @@ export function inject(opts: InjectOptions) {
 		process.exit(1)
 	}
 
-	const coreDocs = discoverCoreDocs(root)
-	const total = coreDocs.frontend.length + coreDocs.entities.length
+	// Copy best practices if platform is known
+	const bestPractices = opts.platform ? copyBestPractices(root, opts.platform) : []
+
+	const coreDocs = discoverCoreDocs(root, bestPractices)
+	const total = coreDocs.frontend.length + coreDocs.entities.length + coreDocs.bestPractices.length
 	if (total) log.info(`Found ${total} core doc(s)`)
 
-	const block = buildIndexBlock(indexPath, docsDir, total ? coreDocs : null)
+	const block = buildIndexBlock(indexPath, total ? coreDocs : null)
 	if (!block) {
 		log.error('INDEX file is empty, nothing to inject.')
 		process.exit(1)
 	}
 
 	injectIntoClaudeMd(claudeMdPath, block)
-	ensureGitignore(root, docsDir)
+	ensureGitignore(root)
 }