Skip to content
Open

Bump #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
88 commits
Select commit Hold shift + click to select a range
6d043c1
Version bump
Feb 13, 2024
e009ac9
copilot instructions
lmajano Dec 12, 2025
bb70895
new build
lmajano Dec 12, 2025
bc9ccf6
new servers
lmajano Dec 12, 2025
6dc5db0
boxlang prime
lmajano Dec 12, 2025
4225e1e
bootstrap upgrade
lmajano Dec 12, 2025
32c8afc
nav working
lmajano Dec 12, 2025
5a96bff
fix abstract annotations
lmajano Dec 12, 2025
ec4e117
fix nav
lmajano Dec 12, 2025
69b4ac9
all metadata works now
lmajano Dec 12, 2025
fad4278
metadata good
lmajano Dec 12, 2025
7c739b1
everything should be upgraded by now
lmajano Dec 12, 2025
71cc446
fixed old tests
lmajano Dec 12, 2025
df4476a
more fixes
lmajano Dec 12, 2025
730f402
more updates
lmajano Dec 12, 2025
ff45d9c
fixed subquerys
lmajano Dec 12, 2025
1db51f1
more class fixes
lmajano Dec 12, 2025
3da21cd
more fixes to new look
lmajano Dec 12, 2025
b5d7da7
much better UI
lmajano Dec 12, 2025
1436579
more great looks
lmajano Dec 13, 2025
e1b9a64
theming support
lmajano Dec 13, 2025
3f9bf3b
fix icons
lmajano Dec 13, 2025
b984da9
method search
lmajano Dec 13, 2025
e147e3e
copilot updates
lmajano Dec 13, 2025
9c5def3
new theme
lmajano Dec 13, 2025
7e2c03f
spacing
lmajano Dec 13, 2025
6257ad5
spacing
lmajano Dec 13, 2025
094d3f2
more fixes to get tests to pass
lmajano Dec 13, 2025
11ea74d
fixed some tests
lmajano Dec 13, 2025
64df01c
more test updates
lmajano Dec 13, 2025
1156ea2
fixed strategy tests
lmajano Dec 13, 2025
d6af255
ui updates
lmajano Dec 13, 2025
4004d7f
inheritance trail
lmajano Dec 13, 2025
18eada6
class hierarchy links
lmajano Dec 13, 2025
5f97507
class annotations
lmajano Dec 13, 2025
8535be7
mre ui
lmajano Dec 13, 2025
ec2bdb6
inherited methods
lmajano Dec 13, 2025
2328b82
finalized for release
lmajano Dec 13, 2025
1d3f139
build updates
lmajano Dec 13, 2025
29afc1c
more updates
lmajano Dec 13, 2025
1eb5353
setting up release cycle
lmajano Dec 13, 2025
e17e1f4
testing updates
lmajano Dec 13, 2025
5dc5f94
Apply cfformat changes
lmajano Dec 13, 2025
0f74d9c
update testing ports
lmajano Dec 13, 2025
b47f975
more updates
lmajano Dec 13, 2025
251a3ad
work in progress
lmajano Dec 13, 2025
cf4b0cb
fixing stupid adobe parser bugs
lmajano Dec 13, 2025
41b6cae
more dumb adobe crap
lmajano Dec 13, 2025
f6370cf
migration to script and using interfaces
lmajano Dec 15, 2025
bc8e7c7
@see links
lmajano Dec 15, 2025
335cb2e
see annotations
lmajano Dec 15, 2025
718b2e3
Apply cfformat changes
lmajano Dec 15, 2025
6cc6efa
nav data
lmajano Dec 15, 2025
ea46980
file protocol warnings
lmajano Dec 15, 2025
97fd3a8
docs
lmajano Dec 15, 2025
475ba51
missing return
lmajano Dec 15, 2025
78b6b00
more fixes
lmajano Dec 15, 2025
beea9be
more tons of fixes
lmajano Dec 15, 2025
ea20699
formatting docs
lmajano Dec 15, 2025
c00fbb8
Apply cfformat changes
lmajano Dec 15, 2025
230af42
making docs pretty
lmajano Dec 15, 2025
625ad61
pre tags
lmajano Dec 15, 2025
637b4bd
Apply cfformat changes
lmajano Dec 15, 2025
21332a0
more updates
lmajano Dec 15, 2025
c7f3713
Merge branch 'development' of github.com:Ortus-Solutions/DocBox into …
lmajano Dec 15, 2025
664d364
adobe does it again
lmajano Dec 15, 2025
c4fe14a
Apply cfformat changes
lmajano Dec 15, 2025
7e90ed9
removing old test
lmajano Dec 15, 2025
558306c
Apply cfformat changes
lmajano Dec 15, 2025
8a248c8
messed up location of docs
lmajano Dec 15, 2025
d46e128
updated readme
lmajano Dec 15, 2025
6675f02
wrong docs again
lmajano Dec 15, 2025
d29db6a
missing version now
lmajano Dec 15, 2025
4793bd3
skip known classes and interfaces
lmajano Dec 19, 2025
5d9fc8f
more ui fixes
lmajano Dec 19, 2025
a03f52a
fix no case
lmajano Dec 20, 2025
02f6b99
fixes all around
lmajano Dec 20, 2025
771e8b7
navigation fixed
lmajano Dec 20, 2025
11b30db
project description
lmajano Dec 20, 2025
568d341
global stats
lmajano Dec 20, 2025
2a05a05
serialiable
lmajano Dec 21, 2025
aa5cda5
deep links
lmajano Dec 21, 2025
c6c806b
more update
lmajano Dec 21, 2025
b41e378
more updates
lmajano Dec 21, 2025
c8c7da5
more ui updates
lmajano Dec 24, 2025
da8f0d8
wip
lmajano Dec 31, 2025
3ea1954
all good
lmajano Dec 31, 2025
b9b283a
Merge branch 'master' into development
lmajano Jan 1, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .cfconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"adminPassword" : "testbox",
"debuggingEnabled": true,
"debuggingReportExecutionTimes":false,
"debuggingShowDatabase":true,
"debuggingShowException":true,
"debuggingShowGeneral":true,
"disableInternalCFJavaComponents":false,
"inspectTemplate":"always",
"maxCFThreads":100,
"robustExceptionEnabled":true,
"systemErr":"System",
"systemOut":"System",
"whitespaceManagement":"white-space-pref"
}
197 changes: 197 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
# DocBox - AI Coding Instructions

DocBox is a JavaDoc-style API documentation generator for CFML/BoxLang codebases. It parses CFC metadata and generates documentation in multiple formats (HTML, JSON, XMI) using a pluggable strategy pattern.

## Architecture & Core Components

**Core Generator** (`DocBox.cfc`): Main orchestrator that accepts source directories and delegates to one or more output strategies. Supports multiple strategies simultaneously (e.g., generate both HTML and JSON in one pass).

**Strategy Pattern**: All output formats extend `AbstractTemplateStrategy.cfc` and implement a `run(query metadata)` method:
- `strategy/api/HTMLAPIStrategy.cfc` - Default HTML documentation with frames/navigation using Bootstrap 5
- `strategy/json/JSONAPIStrategy.cfc` - Machine-readable JSON output
- `strategy/uml2tools/XMIStrategy.cfc` - XMI/UML diagram generation
- `strategy/CommandBox/CommandBoxStrategy.cfc` - CommandBox-specific output format

**Theme Support**: HTMLAPIStrategy now supports theming via the `theme` property (default: "frames"). Theme resources are organized under `/strategy/api/themes/{themeName}/resources/`:
- `/templates/` - CFML template files
- `/static/` - CSS, JS, image assets

**Metadata Pipeline**: DocBox builds a query object containing parsed CFC metadata via `buildMetaDataCollection()` which:
1. Recursively scans source directories for `*.cfc` files
2. Parses JavaDoc-style comments and component metadata
3. Resolves inheritance chains (`extends`, `implements`)
4. Applies exclusion regex patterns
5. Returns query with columns: `package`, `name`, `extends`, `metadata`, `type`, `implements`, `fullextends`, `currentMapping`

**Strategy Initialization**: Strategies can be specified as:
- String shortcuts: `"HTML"`, `"JSON"`, `"XMI"`, `"CommandBox"`
- Full class paths: `"docbox.strategy.api.HTMLAPIStrategy"`
- Instantiated objects: `new docbox.strategy.api.HTMLAPIStrategy(outputDir="/docs", theme="frames")`

## Critical Developer Workflows

**Self-Documentation Pattern** (`build/Docs.cfc`): DocBox generates its own API docs by instantiating itself and calling `generate()`. This is the canonical example:
```cfml
new docbox.DocBox()
.addStrategy("HTML", { projectTitle: "DocBox API Docs", outputDir: "/apidocs" })
.addStrategy("JSON", { projectTitle: "DocBox API Docs", outputDir: "/apidocs" })
.generate(source="/docbox", mapping="docbox", excludes="(.github|build|tests)");
```

**Build Scripts** (via CommandBox):
- `box run-script build` - Full build process (source copy, token replacement, checksums)
- `box run-script build:docs` - Generate DocBox's own documentation
- `box run-script tests` - Run TestBox suite via `testbox run` command
- `box run-script format` - Format code using CFFormat
- `box run-script format:watch` - Auto-format on file changes

**Testing**: Uses TestBox BDD suite in `/tests/specs/`. Tests verify:
- Multiple strategy execution
- Default HTML strategy fallback
- Custom strategy injection via mocking
- Directory existence validation
- Exclusion pattern application

## Key Implementation Patterns

**Query-Based Metadata**: Unlike typical ORM patterns, DocBox uses CFML Query objects throughout for metadata storage and manipulation. The `AbstractTemplateStrategy` includes helper methods like `getPackageQuery()`, `buildPackageTree()`, and `visitPackageTree()` that operate on query results using QoQ (Query of Queries).

**Template Rendering**: HTML strategy uses CFML includes (not a template engine) with theme-based template paths:
- `/strategy/api/themes/{theme}/resources/templates/` - CFML template files
- `/strategy/api/themes/{theme}/resources/static/` - CSS, JS, image assets
- Templates receive metadata via local scope variables, not arguments

**Modern UI/UX Design** (Bootstrap 5):
- **Framework**: Bootstrap 5.3.2 with modern component syntax and data-bs-* attributes
- **Icons**: Bootstrap Icons 1.11.2 for UI elements and visual indicators
- **Design System**: CSS custom properties for theming with light/dark mode support
- **Color Scheme**: Purple gradient accents (#5e72e4 primary), softer colors, reduced blue overload
- **Emojis**: Visual indicators throughout (📚 packages, 📁 folders, 🔌 interfaces, 📦 classes, 🟢 public, 🔒 private, ⚡ static, 📝 abstract)
- **Typography**: Modern font stack with proper hierarchy and spacing
- **Cards**: Modern card-based layouts with subtle shadows and hover effects
- **Breadcrumbs**: Package navigation with clickable hierarchy
- **Method Tabs**: Tabbed interface for filtering methods (All/Public/Private/Static/Abstract)
- **Visibility Indicators**: Emoji badges with Bootstrap tooltips for access levels and modifiers
- **Dark Mode**: Full dark mode support with theme toggle, localStorage persistence, and smooth transitions
- **Method Search**: Real-time search with keyboard navigation (Enter/Shift+Enter), visual highlighting, and auto-scroll

**Interactive Features**:
- **jstree Navigation**: Auto-expands first 2 levels for better UX
- **Bootstrap Tooltips**: Contextual help on visibility badges and deprecated methods
- **Method Search**: Live filtering with highlight, navigate with Enter (next) / Shift+Enter (previous), clear with Escape
- **Smooth Scrolling**: Enhanced navigation with smooth scroll behavior
- **Theme Toggle**: Persistent dark/light mode preference with moon/sun icon indicator

**Package Tree Navigation**: `buildPackageTree()` converts flat package names into nested structures for navigation. Example: `"coldbox.system.web"` becomes `{coldbox: {system: {web: {}}}}`. Used by HTML strategy for hierarchical navigation.

**Custom Annotations**: DocBox recognizes standard JavaDoc tags plus custom annotations:
- `@doc_generic` - Specify generic types for returns/arguments (e.g., `@doc_generic="Array<User>"`)

**Exclusion Regex**: Applied to relative file paths (not absolute) to ensure portability. Example: `excludes="(coldbox|build|tests)"` matches paths containing those strings.

## Multi-Engine Compatibility

**Server Configurations**: Project includes server JSON files for testing on multiple engines:
- `[email protected]`, `[email protected]` - Lucee 5.x and 6.x
- `[email protected]`, `[email protected]` - Adobe ColdFusion
- `[email protected]`, `[email protected]` - BoxLang runtime and bleeding edge

**Engine-Specific Considerations**: Code avoids engine-specific features. Uses native CFML query operations, file I/O, and component metadata introspection that work across all engines.

## Build Process Details

**Token Replacement**: Build system replaces `@build.version@` and `@build.number@` tokens in files during packaging. Handled by CommandBox's `tokenReplace` command.

**Artifact Structure**: Build outputs to `.artifacts/{projectName}/{version}/` with:
- Source ZIP with version in filename
- API docs ZIP
- MD5 and SHA-512 checksums for all artifacts

**Exclusion Patterns** (`variables.excludes` in Build.cfc):
```cfml
["build", "testbox", "tests", "server-.*\.json", "^\..*", "coldbox-5-router-documentation.png", "docs"]
```

## Common Development Patterns

**Adding New Strategies**: Extend `AbstractTemplateStrategy.cfc` and implement `run(required query qMetadata)`. Register in `DocBox.cfc` switch statement if using shortcut name.

**Strategy Properties**: Pass via constructor or properties struct. HTML strategy requires `outputDir` and optional `projectTitle`. JSON strategy requires same. XMI requires `outputFile` instead.

**Error Handling**: Strategies throw `InvalidConfigurationException` for missing directories or invalid configuration. DocBox's `generate()` method accepts `throwOnError` boolean to control behavior on invalid components.

**Caching**: `AbstractTemplateStrategy` includes `functionQueryCache` and `propertyQueryCache` properties for storing filtered query results to avoid repeated QoQ operations during rendering.

## HTML Documentation Styling & Components

**CSS Architecture**:
- **Custom Properties**: Comprehensive theming system with CSS variables for colors, spacing, and component styles
- **Light Mode**: Clean white backgrounds, dark text, soft borders (#e9ecef), purple primary (#5e72e4)
- **Dark Mode**: Dark blue-gray backgrounds (#1a202c), light text (#e2e8f0), adjusted colors for visibility
- **Transitions**: Smooth 0.3s transitions for theme changes and interactive elements
- **Responsive Design**: Mobile-friendly layouts with proper breakpoints

**Key Template Files**:
- `class.cfm` - Individual class/interface documentation with method details, tabbed summaries, and search
- `package-summary.cfm` - Package overview with class/interface listings
- `overview-summary.cfm` - Project overview with all packages
- `overview-frame.cfm` - Left navigation tree with jstree
- `inc/nav.cfm` - Top navigation bar with theme toggle
- `inc/common.cfm` - Shared assets (Bootstrap CDN, jQuery, tooltips, theme toggle JS)

**UI Components**:
- **Breadcrumbs**: Package hierarchy navigation with emoji indicators (📚 All Packages, 📁 package names)
- **Cards**: Modern card layouts for sections (properties, constructors, methods)
- **Tables**: Hover states, proper borders, responsive design
- **Badges**: Access modifiers (public/private), abstract indicators, deprecated warnings
- **Method Tabs**: Bootstrap 5 nav-tabs with counts for each visibility level
- **Signatures**: Code blocks with syntax highlighting and border accents
- **Search Input**: Positioned in Method Summary header with real-time filtering

**JavaScript Features**:
- **Tooltip Initialization**: Bootstrap tooltips for visibility badges and metadata
- **Theme Toggle**: Detects saved preference, toggles data-theme attribute, updates icon (moon/sun)
- **Method Search**: Indexes methods by name/signature, filters on input, highlights matches, keyboard navigation
- **Smooth Scroll**: Auto-scrolls to search results and hash targets
- **jstree Auto-expand**: Expands first 2 levels of package tree on load

**Accessibility**:
- **ARIA Labels**: Proper labeling for navigation, tabs, and interactive elements
- **Semantic HTML**: Proper heading hierarchy, nav elements, table structure
- **Tooltips**: Descriptive titles for icons and badges
- **Keyboard Navigation**: Tab order, Enter/Escape for search, arrow keys supported

## Coding Conventions

**JavaScript Style**:
- **Spacing Requirements**: All JavaScript code must include spacing in parentheses, brackets, and quotes for improved readability
- **Function Calls**: Space after function name and inside parentheses: `func( arg1, arg2 )`
- **Array Literals**: Space inside brackets: `[ item1, item2, item3 ]`
- **Object Literals**: Space inside braces and around colons: `{ key: value, another: val }`
- **Conditionals**: Space inside condition parentheses: `if ( condition )`, `while ( test )`
- **Template Literals**: Space inside interpolation: `${ variable }` not `${variable}`
- **Method Chaining**: Proper spacing in chains: `.filter( x => x.active ).map( x => x.name )`
- **Arrow Functions**: Space around arrows: `( x ) => x + 1` or `x => x + 1` for single param
- **Examples**:
```javascript
// Correct spacing
const result = array.filter( item => item.active ).slice( 0, 10 );
if ( !value ) return null;
localStorage.setItem( 'key', data );
obj.method( param1, param2 );
const html = `<p>${ value }</p>`;

// Incorrect - missing spacing
const result = array.filter(item => item.active).slice(0, 10);
if (!value) return null;
localStorage.setItem('key', data);
obj.method(param1, param2);
const html = `<p>${value}</p>`;
```

**CFML/BoxLang Style**:
- Follow CFFormat rules defined in `.cfformat.json`
- Spacing in all markers: function calls `func( arg )`, conditions `if ( test )`, arrays `[ 1, 2 ]`, structs `{ key : value }`
- Binary operators require padding: `a + b`, `x == y`
- 4-space tabs, max 115 columns, double quotes for strings
- Consecutive assignments, properties, and parameters are aligned
7 changes: 7 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
version: 2
updates:
# GitHub Actions - updates uses: statements in workflows
- package-ecosystem: "github-actions"
directory: "/" # Where your .github/workflows/ folder is
schedule:
interval: "monthly"
4 changes: 2 additions & 2 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ jobs:

formatCheck:
name: Checks Source Code Formatting
runs-on: ubuntu-20.04
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
uses: actions/checkout@v6

- uses: Ortus-Solutions/[email protected]
with:
Expand Down
31 changes: 17 additions & 14 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ on:
default: false
type: boolean

# Manual Trigger for manual releases
workflow_dispatch:
env:
MODULE_ID: docbox
SNAPSHOT: ${{ inputs.snapshot || false }}
Expand All @@ -28,19 +30,19 @@ jobs:
#############################################
build:
name: Build & Publish Release
runs-on: ubuntu-20.04
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
uses: actions/checkout@v6

- name: Setup Java
uses: actions/setup-java@v4
uses: actions/setup-java@v5
with:
distribution: "temurin"
java-version: "11"
java-version: "21"

- name: Setup CommandBox
uses: Ortus-Solutions/setup-commandbox@v2.0.1
uses: Ortus-Solutions/setup-commandbox@main
with:
forgeboxAPIKey: ${{ secrets.FORGEBOX_API_TOKEN }}

Expand Down Expand Up @@ -95,7 +97,7 @@ jobs:

- name: Upload Build Artifacts
if: success()
uses: actions/upload-artifact@v4
uses: actions/upload-artifact@v6
with:
name: ${{ env.MODULE_ID }}
path: |
Expand All @@ -121,17 +123,18 @@ jobs:
AWS_S3_BUCKET: "apidocs.ortussolutions.com"
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_ACCESS_SECRET }}
SOURCE_DIR: ".artifacts/${{ env.MODULE_ID }}"
DEST_DIR: "ortussolutions/${{ env.MODULE_ID }}"
SOURCE_DIR: ".tmp/apidocs"
DEST_DIR: "${{ env.MODULE_ID }}/${{ env.VERSION }}"

- name: Publish to ForgeBox
run: |
cd .tmp/${{ env.MODULE_ID }}
cat box.json
box forgebox publish
cd ../bx-docbox
box forgebox publish

- name: Create Github Release
uses: taiki-e/create-gh-release-action@v1.8.0
uses: taiki-e/create-gh-release-action@v1.9.1
continue-on-error: true
if: env.SNAPSHOT == 'false'
with:
Expand All @@ -158,21 +161,21 @@ jobs:
prep_next_release:
name: Prep Next Release
if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main'
runs-on: ubuntu-20.04
runs-on: ubuntu-latest
needs: [ build ]
steps:
- name: Checkout Development Repository
uses: actions/checkout@v4
uses: actions/checkout@v6
with:
ref: development

- name: Setup CommandBox
uses: Ortus-Solutions/setup-commandbox@v2.0.1
uses: Ortus-Solutions/setup-commandbox@main
with:
forgeboxAPIKey: ${{ secrets.FORGEBOX_TOKEN }}

- name: Download build artifacts
uses: actions/download-artifact@v4
uses: actions/download-artifact@v7
with:
name: ${{ env.MODULE_ID }}
path: .tmp
Expand Down
14 changes: 10 additions & 4 deletions .github/workflows/snapshot.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,15 @@
name: Snapshots
name: TestBox Snapshots

on:
push:
branches:
- development
workflow_dispatch:

# Unique group name per workflow-branch/tag combo
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
#############################################
Expand All @@ -18,17 +24,17 @@ jobs:
##########################################################################################
format:
name: Code Auto-Formatting
runs-on: ubuntu-20.04
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v6

- name: Auto-format
uses: Ortus-Solutions/[email protected]
with:
cmd: run-script format

- name: Commit Format Changes
uses: stefanzweifel/git-auto-commit-action@v5
uses: stefanzweifel/git-auto-commit-action@v7
with:
commit_message: Apply cfformat changes
push_options: --force
Expand Down
Loading
Loading