BUILD SCRIPTS ANALYSIS

Comprehensive documentation system guides

🔧 Build Scripts Analysis - Project-Scoped Architecture

Date: October 28, 2025
Status: ✅ Scripts are compatible with project-scoped architecture

Overview

Analyzed build scripts for compatibility with the new project-scoped architecture. Good news: The scripts already support the new model!

✅ `scan-folders-config.js` - ALREADY COMPATIBLE

Location: apps/docs-angular/scripts/scan-folders-config.js

Root Project Detection Logic

// Line 169: Determine if folder is a prospective root project
const isDirectChildOfLanguage = pathParts.length >= 2 && 
                                pathParts[pathParts.length - 2] === language;
const prospectiveRoot = isDirectChildOfLanguage || !!password;

// Line 206: Finalize isRoot flag
const finalIsRoot = (typeof cfg.isRoot === 'boolean') 
  ? cfg.isRoot  // Explicit override from docs.json or _folder.md
  : (prospectiveRoot && node.totalFiles > 0); // Auto-detect

if (finalIsRoot) node.isRoot = true;

Root Project Criteria

A project is marked as isRoot: true if ANY of these conditions are met:

Explicit Configuration: isRoot: true in docs.json or _folder.md frontmatter
Direct Child of Language: Folder is directly under docs/english/ or docs/spanish/
Has Password: Folder has a password (private project marker)
AND Has Content: Must have at least one markdown file (own or in subtree)

Examples

docs/
├── english/
│   ├── GoGrab-Space/           ← ✅ isRoot: true (direct child + has content)
│   ├── public/                 ← ✅ isRoot: true (direct child + has content)
│   ├── private/                ← ⚠️ isRoot: false (container, not project)
│   │   └── SecretProject/      ← ✅ isRoot: true (has password + has content)
│   └── GoGrab-Pulse/           ← ✅ isRoot: true (direct child + has content)
└── spanish/
    └── GoGrab-Space/           ← ✅ isRoot: true (direct child + has content)

What It Does

Scans docs/ directory recursively
Reads docs.json or _folder.md frontmatter from each folder
Inherits passwords from parent folders
Counts markdown files (.md, .mdc) in each folder and subtree
Marks folders as isRoot based on criteria above
Generates docs-folders-config.json with folder hierarchy
Preserves existing configuration on re-scan
Merges changes from frontmatter metadata

Configuration Options (in `_folder.md` or `docs.json`)

---
title: "Project Name"
password: "secret123"           # Makes it a root project
isRoot: true                    # Explicit root marker
config:
  search:
    hasAccessToPublic: true     # Can search public projects
    scopeToCurrentProject: true # Search only within project
  navigation:
    enableBreadcrumbs: true
  ui:
    theme: "custom"
---

Output Format (`docs-folders-config.json`)

{
  "globalConfig": {...},
  "folders": [
    {
      "name": "GoGrab-Space",
      "path": "docs/english/GoGrab-Space",
      "language": "english",
      "password": null,
      "isRoot": true,          ← ✅ Marked as root project
      "config": {
        "search": {
          "hasAccessToPublic": true
        }
      },
      "children": [...]
    }
  ]
}

✅ `scan-docs-structure.js` - NEEDS VERIFICATION

Location: apps/docs-angular/scripts/scan-docs-structure.js

What It Does

Generates docs-manifest.json with complete file tree:

All markdown files (.md, .mdc)
Frontmatter metadata (title, description, tags, etc.)
Directory hierarchy
File signatures (name, path, size, modified date)

Compatibility Check

✅ Already project-agnostic - It scans all files regardless of project structure.

The manifest includes the full path for each file:

{
  "structure": [
    {
      "name": "english",
      "type": "directory",
      "items": [
        {
          "name": "GoGrab-Space",
          "type": "directory",
          "items": [
            {
              "name": "libs-structural.md",
              "type": "file",
              "path": "docs/english/GoGrab-Space/libs-structural.md"
            }
          ]
        }
      ]
    }
  ]
}

Services like StructureSyncService then filter this manifest based on the currently selected project from ProjectSelectionState.

No Changes Needed ✅

The manifest generation already works with project-scoped architecture because:

It captures the full folder structure
Project filtering happens at read time (in services), not build time
Each file's full path is preserved

⚠️ `start-admin-server.js` - NEEDS REVIEW

Location: apps/docs-angular/scripts/start-admin-server.js

Purpose

Serves documentation files during development:

Serves files from docs/ directory
Handles API endpoints (/docs-config.json, /docs-folders-config.json)
Proxies requests to documentation content
Enables hot reload during development

Potential Updates Needed

Path Resolution
- Currently serves from hardcoded paths
- May need dynamic path resolution based on project selection
- Should handle project-scoped URLs like /docs/english/GoGrab-Space/...
CORS Configuration
- Ensure CORS allows project-scoped requests
- Update allowed origins if needed
Caching Strategy
- Consider caching based on project context
- Invalidate caches when project selection changes

Action Required

🔍 Manual Review - Test the admin server with:

Navigate to /select-project
Select a project
Navigate within project (e.g., /GoGrab-Space/libs/ux-portal)
Verify files are served correctly
Check browser console for 404 errors

If files aren't served, check:

Path rewriting in server config
Base path resolution
Proxy rules

📋 Build Script Summary

Script	Status	Changes Needed
scan-folders-config.js	✅ Compatible	None - Already marks root projects
scan-docs-structure.js	✅ Compatible	None - Project-agnostic manifest
start-admin-server.js	⚠️ Needs Testing	Verify path serving & proxying

🧪 Testing Recommendations

1. Generate Fresh Configs

# From project root
cd apps/docs-angular/scripts

# Generate folders config
node scan-folders-config.js

# Generate manifest
node scan-docs-structure.js

# Verify output
cat ../src/assets/docs-folders-config.json
cat ../src/assets/docs-manifest.json

2. Verify `isRoot` Flags

Check docs-folders-config.json:

# Should show isRoot: true for direct children of language folders
grep -A 5 '"isRoot": true' ../src/assets/docs-folders-config.json

Expected projects with isRoot: true:

docs/english/GoGrab-Space
docs/english/GoGrab-Pulse
docs/english/public
Any project with a password

3. Test Admin Server

# Start the admin server
node start-admin-server.js

# In browser:
# 1. http://localhost:5011/docs-config.json (should load)
# 2. http://localhost:5011/docs-folders-config.json (should load)
# 3. http://localhost:5011/docs/english/GoGrab-Space/libs-structural.md (should load)

🎯 Recommendations

Immediate Actions

✅ No changes needed for scan-folders-config.js
✅ No changes needed for scan-docs-structure.js
⚠️ Test start-admin-server.js with project-scoped URLs

Future Enhancements

Add Validation - Script to validate isRoot flags match expected projects
Add Tests - Unit tests for root project detection logic
Document Overrides - How to explicitly set isRoot in frontmatter
Performance - Consider caching folder scans for large repos

📖 Documentation Updates Needed

Update add-documentation.md to explain:
- Where to place new project folders (docs/english/{ProjectName}/)
- How isRoot flag is automatically set
- How to override with explicit isRoot: true in frontmatter
Create project-structure-guide.md explaining:
- Root project criteria
- How to create a new project
- Access control configuration
- Cross-project visibility rules

Status: ✅ Build scripts are compatible
Action Required: Test admin server, update documentation

🔧 Build Scripts Analysis - Project-Scoped Architecture

Overview

✅ scan-folders-config.js - ALREADY COMPATIBLE

Root Project Detection Logic

Root Project Criteria

Examples

What It Does

Configuration Options (in _folder.md or docs.json)

Output Format (docs-folders-config.json)

✅ scan-docs-structure.js - NEEDS VERIFICATION

What It Does

Compatibility Check

No Changes Needed ✅

⚠️ start-admin-server.js - NEEDS REVIEW

Purpose

Potential Updates Needed

Action Required

📋 Build Script Summary

🧪 Testing Recommendations

1. Generate Fresh Configs

2. Verify isRoot Flags

3. Test Admin Server

🎯 Recommendations

Immediate Actions

Future Enhancements

📖 Documentation Updates Needed

✅ `scan-folders-config.js` - ALREADY COMPATIBLE

Configuration Options (in `_folder.md` or `docs.json`)

Output Format (`docs-folders-config.json`)

✅ `scan-docs-structure.js` - NEEDS VERIFICATION

⚠️ `start-admin-server.js` - NEEDS REVIEW

2. Verify `isRoot` Flags