@handsupmin/gc-tree 0.8.2 → 0.8.3

package/dist/src/verify-onboarding.js

@@ -1,6 +1,9 @@
-import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
 import { parseIndexEntries } from './markdown.js';
-import { branchIndexPath, DEFAULT_BRANCH } from './paths.js';
+import { resolveContext } from './resolve.js';
+import { branchDocsDir, branchIndexPath, DEFAULT_BRANCH } from './paths.js';
 import { ensureBranchExists, statusForBranch } from './store.js';
 const VALID_CATEGORIES = new Set(['role', 'repos', 'domain', 'workflows', 'conventions', 'infra', 'verification']);
 export async function verifyOnboarding({ home, branch, }) {
@@ -12,6 +15,42 @@ export async function verifyOnboarding({ home, branch, }) {
     const indexedDocCount = docs.length;
     const hasDocs = status.doc_count > 0 && indexedDocCount > 0;
     const qualityIssues = [];
+    const docsDir = branchDocsDir(home, gcBranch);
+    const sourceDocs = await listSourceDocPaths(docsDir);
+    const nonIndexSourceDocs = sourceDocs.filter((path) => !/(^|\/)index\.md$/i.test(path));
+    if (sourceDocs.some((path) => /(^|\/)index\.md$/i.test(path))) {
+        qualityIssues.push('Source docs must not include docs/index.md. The branch-level index.md is the only dictionary.');
+    }
+    const indexedPaths = new Set(docs.map((doc) => doc.path));
+    for (const path of indexedPaths) {
+        if (!existsSync(join(branchDirForDoc(home, gcBranch), path))) {
+            qualityIssues.push(`Index points to a missing source doc: ${path}.`);
+        }
+    }
+    for (const path of nonIndexSourceDocs) {
+        const indexPath = `docs/${path}`;
+        if (!indexedPaths.has(indexPath)) {
+            qualityIssues.push(`Source doc is not reachable from index.md: ${indexPath}.`);
+        }
+    }
+    const pathLikeLabels = docs
+        .filter((doc) => /^\.?docs\//i.test(doc.label) || /\.md$/i.test(doc.label))
+        .map((doc) => doc.label);
+    if (pathLikeLabels.length > 0) {
+        qualityIssues.push(`Index labels must be search terms, not paths: ${dedupe(pathLikeLabels).join(', ')}.`);
+    }
+    const prefixedLabels = docs
+        .filter((doc) => /^(repo|repository|domain|workflow|convention|role|infra|verification)\s*:/i.test(doc.label))
+        .map((doc) => doc.label);
+    if (prefixedLabels.length > 0) {
+        qualityIssues.push(`Index labels must not keep category prefixes: ${dedupe(prefixedLabels).join(', ')}.`);
+    }
+    const invalidCategories = docs
+        .filter((doc) => doc.category !== 'general' && !VALID_CATEGORIES.has(doc.category))
+        .map((doc) => `${doc.label} (${doc.category})`);
+    if (invalidCategories.length > 0) {
+        qualityIssues.push(`Index contains invalid categories: ${dedupe(invalidCategories).join(', ')}.`);
+    }
     if (hasDocs && indexedDocCount >= 3) {
         const categoryCounts = new Map();
         for (const doc of docs) {
@@ -25,6 +64,25 @@ export async function verifyOnboarding({ home, branch, }) {
             const generalDocLabels = docs.filter((d) => d.category === 'general').map((d) => d.label);
             qualityIssues.push(`${generalCount} doc(s) still have category "general": ${generalDocLabels.join(', ')}. Move them to one of: ${[...VALID_CATEGORIES].join(', ')}.`);
         }
+        if (indexedDocCount >= 5) {
+            const presentCategories = new Set(docs.map((doc) => doc.category));
+            const missingCore = ['role', 'repos', 'domain', 'workflows'].filter((category) => !presentCategories.has(category));
+            if (missingCore.length > 0) {
+                qualityIssues.push(`Onboarding is missing core dictionary categories: ${missingCore.join(', ')}. Capture them or explicitly add small docs for unavailable categories.`);
+            }
+        }
+    }
+    if (status.warnings.length > 0) {
+        qualityIssues.push(...status.warnings);
+    }
+    const searchQuality = [];
+    for (const doc of docs.slice(0, 12)) {
+        const resolved = await resolveContext({ home, branch: gcBranch, query: doc.label });
+        const matched = resolved.matches.some((match) => match.path === doc.path);
+        searchQuality.push({ query: doc.label, expected_path: doc.path, matched });
+        if (!matched) {
+            qualityIssues.push(`Resolve smoke test failed: query "${doc.label}" did not return ${doc.path}.`);
+        }
     }
     const complete = hasDocs && qualityIssues.length === 0;
     return {
@@ -35,6 +93,7 @@ export async function verifyOnboarding({ home, branch, }) {
         docs,
         warnings: status.warnings,
         quality_issues: qualityIssues,
+        search_quality: searchQuality,
         message: complete
             ? `Onboarding is complete for gc-branch "${gcBranch}".`
             : hasDocs
@@ -42,3 +101,23 @@ export async function verifyOnboarding({ home, branch, }) {
                 : `Onboarding is incomplete for gc-branch "${gcBranch}". Docs or index entries are missing.`,
     };
 }
+async function listSourceDocPaths(dir, prefix = '') {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...(await listSourceDocPaths(join(dir, entry.name), relative)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            files.push(relative);
+        }
+    }
+    return files.sort();
+}
+function branchDirForDoc(home, branch) {
+    return join(home, 'branches', branch);
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,