File Source

The file source allows you to include files from your local filesystem. It's the most commonly used source type for analyzing your codebase.

Basic Usage

documents:  - description: "Basic Source Code Example"  outputPath: "docs/source-code.md"  sources:  - type: file  description: "Source Code"  sourcePaths: src  filePattern: "*.php"  notPath: [ "tests", "vendor" ]  modifiers: [ "php-signature" ]

Parameters

Parameter	Type	Default	Description
type	string	required	Must be "file"
description	string	""	Human-readable description of the source
sourcePaths	string|array	required	Path(s) to directory or files to include
filePattern	string|array	"*.*"	File pattern(s) to match
notPath (or excludePatterns)	array	[]	Patterns to exclude files
path	string|array	[]	Patterns to include only files in specific paths
contains	string|array	[]	Patterns to include only files containing specific content
notContains	string|array	[]	Patterns to exclude files containing specific content
size	string|array	[]	Size constraints for files (e.g., "> 10K", "< 1M")
date	string|array	[]	Date constraints for files (e.g., "since yesterday", "> 2023-01-01")
ignoreUnreadableDirs	boolean	false	Whether to ignore unreadable directories
maxFiles	integer	0	Maximum number of files to include (0 for no limit)
showTreeView	boolean	true	Whether to display a directory tree visualization (deprecated, use treeView instead)
treeView	boolean|object	true	Tree view configuration, can be a boolean or detailed configuration object
modifiers	array	[]	Content modifiers to apply
tags	array	[]	List of tags for this source

Multiple Source Paths

You can include files from multiple directories:

documents:  - description: "Multiple Source Directories Example"  outputPath: "docs/multiple-dirs.md"  sources:  - type: file  description: "Multiple Source Directories"  sourcePaths: [ "src/Controllers", "src/Models", "config" ]  filePattern: "*.php"  showTreeView: true

Multiple File Patterns

Include different file types:

documents:  - description: "Multiple File Types Example"  outputPath: "docs/multiple-types.md"  sources:  - type: file  description: "Multiple File Types"  sourcePaths: src  filePattern: [ "*.php", "*.json", "*.md" ]  showTreeView: true

Path-Based Filtering

Target specific subdirectories or files:

documents:  - description: "Controller Files Only"  outputPath: "docs/controllers.md"  sources:  - type: file  description: "Only Controller Files"  sourcePaths: src  path: "Controller"  filePattern: "*.php"

This will only include files with "Controller" in their path. You can also use an array:

 documents:  - description: "Controller Files Only"  outputPath: "docs/controllers.md"  sources:  - type: file  description: "Only Controller Files"  sourcePaths: src  path:  - Controller  - Service  filePattern: "*.php"

Content-Based Filtering

Include or exclude files based on their content:

documents:  - description: "Repository Classes"  outputPath: "docs/repositories.md"  sources:  - type: file  description: "Repository Classes"  sourcePaths: src  contains: "class Repository"  filePattern: "*.php"

You can also exclude files containing specific content:

documents:  - description: "Repository Classes"  outputPath: "docs/repositories.md"  sources:  - type: file  description: "Repository Classes"  sourcePaths: src  notContains: "@deprecated"  filePattern: "*.php"

Use arrays for multiple patterns:

documents:  - description: "Repository Classes"  outputPath: "docs/repositories.md"  sources:  - type: file  description: "Repository Classes"  sourcePaths: src  contains:  - "class Service"  - "implements ServiceInterface"  notContains:  - @deprecated  - @internal  filePattern: "*.php"

Size-Based Filtering

Filter files by their size:

documents:  - description: "Medium-Sized Files"  outputPath: "docs/medium-files.md"  sources:  - type: file  description: "Medium-Sized Files"  sourcePaths: src  size: [ "> 1K", "< 50K" ]  filePattern: "*.php"  showTreeView: true

Size modifiers support these formats:

• k, ki for kilobytes (e.g., 10k, 5ki)
• m, mi for megabytes (e.g., 1m, 2mi)
• g, gi for gigabytes (e.g., 1g, 1gi)

Operators include:

• >, >=, <, <= for comparisons

Date-Based Filtering

Include files based on their modification date:

documents:  - description: "Recent Files"  outputPath: "docs/recent-files.md"  sources:  - type: file  description: "Recently Modified Files"  sourcePaths: src  date: "since 2 weeks ago"  filePattern: "*.php"  showTreeView: true

Date modifiers support:

• Relative dates: yesterday, last week, 2 days ago, etc.
• Absolute dates: 2023-01-01, 2023/01/01, etc.
• Operators: > (after), < (before), >=, <=, ==
• Alternative syntax: since (for >), until or before (for <)

Examples:

date: "since yesterday"

date:  - "> 2023-05-01"  - "< 2023-06-01"

Limiting the Number of Files

You can limit the number of files to process:

documents:  - description: "Limited File Sample"  outputPath: "docs/limited-sample.md"  sources:  - type: file  description: "First 10 PHP Files (Alphabetically)"  sourcePaths: src  filePattern: "*.php"  maxFiles: 10  showTreeView: true

This will:

1. Find all files matching the criteria
2. Sort them alphabetically
3. Take only the first 10 files for processing
4. Still show all matching files in the tree view for context

Combined Filtering (Advanced Example)

You can combine multiple filters for precise targeting:

documents:  - description: "Recently Modified Controllers"  outputPath: "docs/recent-controllers.md"  sources:  - type: file  description: "Recently Modified Controller Classes"  sourcePaths: src  filePattern: "*.php"  path: "Controller"  contains: "namespace App\\Controller"  notContains: "@deprecated"  size: "< 100K"  date: "since 1 month ago"  maxFiles: 20  ignoreUnreadableDirs: true  showTreeView: true  modifiers: [ "php-signature" ]

This will:

1. Scan the src directory for PHP files
2. Only include files with "Controller" in their path
3. Only include files containing "namespace App\Controller"
4. Exclude files containing "@deprecated"
5. Only include files smaller than 100KB
6. Only include files modified in the last month
7. Limit to the first 20 matching files
8. Skip directories that can't be read due to permissions
9. Show a directory tree in the output
10. Apply the PHP signature modifier to simplify method implementations

Tree View Configuration

You can customize the tree view with detailed configuration options:

documents:  - description: "Enhanced Tree View Example"  outputPath: "docs/enhanced-tree.md"  sources:  - type: file  description: "Files with Enhanced Tree View"  sourcePaths: src  filePattern: "*.php"  treeView:  enabled: true  showSize: true  showLastModified: true  showCharCount: true  includeFiles: true  maxDepth: 3  dirContext:  "src/Controller": "Application controllers"  "src/Models": "Domain models and entities"

Tree View Options

Option	Type	Default	Description
enabled	boolean	true	Whether to show the tree view
showSize	boolean	false	Include file/directory sizes in the tree
showLastModified	boolean	false	Include last modified dates in the tree
showCharCount	boolean	false	Include character counts in the tree
includeFiles	boolean	true	Whether to include files (true) or only show directories (false)
maxDepth	integer	0	Maximum depth of the tree to display (0 for unlimited)
dirContext	object	{}	Optional descriptions for specific directories

Example output with enhanced tree view:

Project ├── src/ [4.2 MB, 2024-03-12, 25,483 chars] │ ├── Controller/ [756 KB, 2024-03-10, 7,521 chars] # Application controllers │ │ ├── ApiController.php [328 KB, 2024-03-10, 3,845 chars] │ │ └── WebController.php [428 KB, 2024-03-05, 3,676 chars] │ ├── Models/ [1.2 MB, 2024-03-12, 12,345 chars] # Domain models and entities │ │ ├── User.php [128 KB, 2024-03-05, 1,234 chars] │ │ └── Product.php [96 KB, 2024-03-12, 987 chars]

Simple Boolean Usage

For backward compatibility, you can still use a boolean value:

documents:  - description: "Simple Tree View Example"  outputPath: "docs/simple-tree.md"  sources:  - type: file  description: "Files with Simple Tree View"  sourcePaths: src  filePattern: "*.php"  treeView: false # Disable tree view