agent-docs 1.0.0

package/docs/VSCODE.md

@@ -0,0 +1,231 @@
+# VS Code Extension for Code Analyzer
+
+> **Version**: 1.0.0
+
+## Overview
+
+The Salesforce Code Analyzer Visual Studio Code Extension integrates Code
+Analyzer's static analysis capabilities directly into the VS Code environment,
+providing real-time feedback and code scanning during development.
+
+**Reference:**
+[Use the VS Code Extension to Analyze Your Code](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.html)
+
+## Prerequisites
+
+- Visual Studio Code installed
+- Salesforce CLI installed and configured
+- Salesforce Extensions for VS Code installed
+
+## Installation
+
+### Step 1: Install Salesforce CLI
+
+Ensure Salesforce CLI is installed on your system:
+
+```bash
+sf --version
+```
+
+If not installed, download from
+[Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli).
+
+### Step 2: Install Salesforce Extensions for VS Code
+
+The Code Analyzer extension is included in the Salesforce Extensions for VS Code
+extension pack:
+
+1. Open VS Code
+2. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
+3. Search for "Salesforce Extension Pack"
+4. Click Install
+
+Alternatively, install the Code Analyzer extension directly by searching for
+"Salesforce Code Analyzer".
+
+### Step 3: Install Code Analyzer CLI Plugin
+
+The VS Code extension requires the Code Analyzer CLI plugin. Install it via
+terminal:
+
+```bash
+sf plugins install @salesforce/sfdx-scanner
+```
+
+Or open the VS Code integrated terminal (Ctrl+` / Cmd+`) and run:
+
+```bash
+sf plugins install @salesforce/sfdx-scanner
+```
+
+Verify installation:
+
+```bash
+sf scanner --help
+```
+
+## Usage
+
+### Scan Selected Files or Folders
+
+1. In VS Code Explorer, select one or more files or folders
+2. Right-click the selection
+3. Choose **"SFDX: Scan Selected Files or Folders with Code Analyzer"**
+
+The extension will analyze the selected items and display results in the
+Problems panel.
+
+### Scan Current File
+
+1. Open a file in the editor
+2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
+3. Type and select **"SFDX: Scan Current File with Code Analyzer"**
+
+The current file will be analyzed and violations will be shown in the Problems
+panel.
+
+### Scan Workspace
+
+To scan the entire workspace:
+
+1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
+2. Type and select **"SFDX: Scan Workspace with Code Analyzer"**
+
+## Viewing Results
+
+### Problems Panel
+
+After scanning, results are displayed in the **Problems** panel (View → Problems
+or Ctrl+Shift+M / Cmd+Shift+M):
+
+- **Severity**: Indicated by icon color (Error/Warning/Info)
+- **File**: Click to navigate to the violation location
+- **Rule**: Rule name and description
+- **Line**: Line number where violation occurs
+- **Message**: Detailed violation message
+
+### Inline Annotations
+
+Violations appear as inline annotations in the editor:
+
+- Red squiggles for errors (High/Critical severity)
+- Yellow squiggles for warnings (Moderate severity)
+- Blue squiggles for info (Low/Info severity)
+
+Hover over annotations to see detailed violation information.
+
+### Quick Actions
+
+Right-click on a violation in the Problems panel or editor to access:
+
+- **Go to Definition**: Navigate to rule definition
+- **View Rule Details**: See full rule documentation
+- **Copy Violation**: Copy violation details to clipboard
+
+## Configuration
+
+### Extension Settings
+
+Configure Code Analyzer extension behavior via VS Code settings:
+
+1. Open Settings (Ctrl+, / Cmd+,)
+2. Search for "Salesforce Code Analyzer"
+
+Available settings:
+
+- **Enable/Disable**: Toggle Code Analyzer on/off
+- **Auto-scan on Save**: Automatically scan files when saved
+- **Default Engine**: Set default engine for scanning
+- **Severity Mapping**: Map Code Analyzer severities to VS Code severities
+- **Excluded Patterns**: Patterns to exclude from scanning
+
+### Project Configuration
+
+The extension respects `code-analyzer.yml` configuration in your project root.
+For detailed configuration options, see
+[Code Analyzer Configuration](CODEANALYZER.md).
+
+Example `code-analyzer.yml`:
+
+```yaml
+engines:
+    pmd:
+        custom_rulesets:
+            - rulesets/design/InnerClassesCannotBeStatic.xml
+
+rules:
+    pmd:
+        NoSingleLetterVariableNames:
+            severity: 'High'
+            tags: ['Recommended']
+```
+
+## Keyboard Shortcuts
+
+Default keyboard shortcuts:
+
+- **Scan Current File**: Not assigned by default (use Command Palette)
+- **Scan Selected Files**: Not assigned by default (use context menu)
+
+You can assign custom shortcuts via:
+
+1. File → Preferences → Keyboard Shortcuts (Ctrl+K Ctrl+S / Cmd+K Cmd+S)
+2. Search for "Salesforce Code Analyzer"
+3. Assign desired shortcuts
+
+## Troubleshooting
+
+### Extension Not Working
+
+1. Verify Salesforce CLI is installed and in PATH
+2. Verify Code Analyzer plugin is installed: `sf plugins list`
+3. Check VS Code Output panel for errors (View → Output, select "Salesforce Code
+   Analyzer")
+4. Reload VS Code window (Ctrl+Shift+P → "Developer: Reload Window")
+
+### No Results Displayed
+
+1. Verify files are supported file types (`.cls`, `.trigger`, `.js`, `.ts`,
+   `.html`, `.cmp`, etc.)
+2. Check `code-analyzer.yml` configuration
+3. Verify rules are enabled and not filtered out
+4. Check VS Code Output panel for scanning errors
+
+### Slow Performance
+
+1. Exclude unnecessary files via `code-analyzer.yml` patterns
+2. Disable auto-scan on save for large workspaces
+3. Scan individual files/folders instead of entire workspace
+4. Check system resources (CPU, memory)
+
+### Plugin Not Found
+
+If extension reports CLI plugin not found:
+
+1. Verify plugin installation: `sf plugins list | grep scanner`
+2. Reinstall plugin: `sf plugins install @salesforce/sfdx-scanner --force`
+3. Check Salesforce CLI version compatibility
+4. Restart VS Code
+
+## Best Practices
+
+1. **Configure Rules**: Customize `code-analyzer.yml` to match your team's
+   standards
+2. **Regular Scanning**: Scan code regularly during development, not just before
+   commits
+3. **Fix High Priority**: Address High and Critical severity violations first
+4. **Use Tags**: Leverage rule tags (e.g., "Recommended") to focus on important
+   rules
+5. **Review Results**: Don't blindly fix all violations; understand rule
+   rationale
+6. **Exclude Patterns**: Exclude generated files and third-party code from
+   scanning
+
+## Related Documentation
+
+- **[CLI Commands](CODEANALYZER.md#cli-commands)** - Command-line usage of Code
+  Analyzer
+- **[Code Analyzer Configuration](CODEANALYZER.md)** - Complete configuration
+  reference
+- **[PMD Engine](PMD.md)** - PMD rules and configuration
+- **[ESLint Engine](ESLINT.md)** - ESLint rules for JavaScript/TypeScript/LWC

package/docs/XPATH31.md

@@ -0,0 +1,213 @@
+````markdown
+# XPath 3.1 Reference
+
+> **Version**: 1.0.0
+
+## Core
+
+- **Model:** Sequences of items (nodes, atomics, maps, arrays, functions). `()`
+  = empty.
+- **Context:** `.` (current), `position()`, `last()`, `$var`
+- **Paths:** `/` (root), `//` (descendant-or-self), `..` (parent), `@`
+  (attribute)
+
+## Operators
+
+| Type        | Operators                                                             |
+| ----------- | --------------------------------------------------------------------- |
+| Arithmetic  | `+ - * div idiv mod`                                                  |
+| Value cmp   | `= != < <= > >=` (atomizes)                                           |
+| General cmp | `eq ne lt le gt ge` (singleton)                                       |
+| Logical     | `and or not()`                                                        |
+| Other       | `\|\|` (concat), `!` (map), `?` (lookup), `:=` (assign), `=>` (arrow) |
+| Type        | `instance of`, `cast as`, `castable as`, `treat as`                   |
+
+## Axes
+
+`child::` (default), `descendant::`, `descendant-or-self::` (//), `parent::`
+(..), `ancestor::`, `ancestor-or-self::`, `following-sibling::`,
+`preceding-sibling::`, `following::`, `preceding::`, `attribute::` (@),
+`namespace::`, `self::` (.)
+
+## Node Tests
+
+`*` (any element), `node()`, `text()`, `comment()`, `processing-instruction()`,
+`element(name?)`, `attribute(name?)`, `document-node()`
+
+## Predicates
+
+`[1]` (first), `[last()]`, `[position()=1]`, `[@attr='val']`, `[count(x)>0]`,
+`[some $x in y satisfies cond]`
+
+## Functions
+
+### String
+
+`concat`, `substring($s,$start,$len?)`, `string-length`, `contains`,
+`starts-with`, `ends-with`, `matches($s,$regex)`, `replace($s,$pat,$repl)`,
+`lower-case`, `upper-case`, `normalize-space`, `substring-before`,
+`substring-after`
+
+### Numeric
+
+`count`, `sum`, `avg`, `min`, `max`, `abs`, `floor`, `ceiling`, `round`
+
+### Boolean
+
+`not`, `true`, `false`, `empty`, `exists`
+
+### Sequence
+
+`distinct-values`, `reverse`, `subsequence($seq,$start,$len?)`, `index-of`,
+`remove($seq,$pos)`, `insert-before`, `head`, `tail`
+
+### Node
+
+`name`, `local-name`, `namespace-uri`, `root`
+
+### Type
+
+`data`, `string`, `number`, `boolean`
+
+## Maps
+
+```xpath
+map { 'k': v }                    # Constructor
+$m('k')  $m?k  $m?('k')  ?k       # Lookup
+map:keys  map:contains  map:get  map:put  map:remove  map:size  map:merge  map:entry
+```
+````
+
+## Arrays
+
+```xpath
+[v1, v2]  array { $a, $b }       # Constructor (1-based)
+$a(1)  $a?1  ?1  ?*              # Lookup (?* = all/flatten)
+array:size  array:get  array:put  array:append  array:subarray  array:remove
+array:reverse  array:join  array:flatten  array:for-each  array:filter  array:fold-left/right
+```
+
+## Expressions
+
+### Conditional
+
+```xpath
+if ($cond) then $a else $b
+```
+
+### Quantified
+
+```xpath
+some $v in $seq satisfies $expr   # exists
+every $v in $seq satisfies $expr  # forall
+```
+
+### Let (comma-separated bindings preferred)
+
+```xpath
+let $a := 1, $b := 2 return $a + $b
+```
+
+### For
+
+```xpath
+for $i in (1 to 10) return $i * 2
+```
+
+### Arrow
+
+```xpath
+$seq => distinct-values() => reverse()   # = reverse(distinct-values($seq))
+```
+
+### Simple Map
+
+```xpath
+$seq ! (./child/@attr)   # apply to each, flatten
+```
+
+## Common Patterns
+
+### Basic
+
+```xpath
+//Node[@Attr='val']                      # attr match
+//Parent[child/@a='v']                   # child condition
+//Node[ancestor::Class[@Name='X']]       # ancestor check
+//Node[following-sibling::Node[@T='x']]  # sibling check
+```
+
+### With let (must be parenthesized in predicates)
+
+```xpath
+//Node[
+    condition1
+    and (
+        let $v := @Attr
+        return count(following-sibling::Node[@Attr=$v]) >= 2
+    )
+]
+```
+
+### Ancestor scope aggregation
+
+```xpath
+//IfBlock[
+    let $method := ancestor::Method[1],
+        $all := $method//IfBlock
+    return count($all) >= 5
+]
+```
+
+### Sum with conditional for
+
+```xpath
+//Node[
+    let $var := @Image, $method := ancestor::Method[1]
+    return sum(
+        for $b in $method//Node return
+            if (exists($b/X)) then count($b//Y[@V=$var]) else 0
+    ) >= 5
+]
+```
+
+### Consecutive siblings
+
+```xpath
+//Node[
+    @A='v'
+    and not(preceding-sibling::*[1][self::Node[@A=current()/@A]])
+    and (let $a := @A return count(following-sibling::Node[@A=$a]) + 1 >= 2)
+]
+```
+
+### Quantified with parentheses (required with and/or)
+
+```xpath
+//Node[
+    (some $x in $s1 satisfies $x/@v='a')
+    and not((some $y in $s2 satisfies $y/@v='b'))
+]
+```
+
+## Pitfalls
+
+| Issue                      | Solution                                              |
+| -------------------------- | ----------------------------------------------------- |
+| `let` in predicate         | Wrap in parens: `cond and (let $x:=... return ...)`   |
+| `let` in `not()`           | Restructure: use `some`/`every` or move `let` outside |
+| `some`/`every` after `and` | Wrap quantifier: `and (some $x in...)`                |
+| `tokenize('')`             | Check `string-length($s)>0` first                     |
+| Nested `let`               | Use comma-separated: `let $a:=1, $b:=2 return...`     |
+
+## Notes
+
+- Atomization: comparisons auto-atomize
+- EBV: non-empty seq = true (except `""`, `0`, `NaN`, `false()`)
+- Document order preserved
+- Namespaces: prefixes or `Q{uri}local`
+- Errors: `try/catch` in 3.1
+
+```
+
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "agent-docs",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A tool for generating reusable, low-token AI agent instruction documents",
+  "keywords": [
+    "ai",
+    "agent",
+    "documentation",
+    "docs",
+    "ide",
+    "cursor"
+  ],
+  "author": "starch-uk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/starch-uk/agent-docs.git"
+  },
+  "devDependencies": {
+    "prettier": "^3.7.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "format": "prettier --write \"**/*.{ts,md,json,yml,yaml}\"",
+    "format:fix": "prettier --write \"**/*.{ts,md,json,yml,yaml}\"",
+    "format:check": "prettier --check \"**/*.{ts,md,json,yml,yaml}\"",
+    "postinstall": "node postinstall.mjs"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import url from 'url';
+
+const __filename = url.fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Root of the installed package
+const packageRoot = __dirname;
+
+// Root of the consumer project (where npm/pnpm/yarn runs postinstall)
+const consumerRoot = process.cwd();
+
+// This package's docs directory
+const packageDocsDir = path.join(packageRoot, 'docs');
+
+// The docs directory in the consumer project
+const consumerDocsDir = path.join(consumerRoot, 'docs');
+
+async function main() {
+  try {
+    // Ensure this package actually has a docs directory
+    const pkgDocsStats = await fs.promises.stat(packageDocsDir).catch(() => null);
+    if (!pkgDocsStats || !pkgDocsStats.isDirectory()) {
+      return;
+    }
+
+    // If the consumer already has a docs directory, do nothing
+    const consumerDocsStats = await fs.promises.stat(consumerDocsDir).catch(() => null);
+    if (consumerDocsStats) {
+      return;
+    }
+
+    const isWindows = process.platform === 'win32';
+
+    if (isWindows) {
+      // On Windows, create a junction from consumerRoot/docs to this package's docs
+      // Junction target must be an absolute path
+      await fs.promises.symlink(packageDocsDir, consumerDocsDir, 'junction');
+    } else {
+      // On POSIX, create a directory symlink
+      await fs.promises.symlink(packageDocsDir, consumerDocsDir, 'dir');
+    }
+  } catch {
+    // Never fail install because of docs-linking issues
+  }
+}
+
+main();
+
+

package/prettier.config.js

@@ -0,0 +1,18 @@
+/** @type {import('prettier').Config} */
+export default {
+	"semi": true,
+	"singleQuote": true,
+	"trailingComma": "all",
+	"printWidth": 80,
+	"proseWrap": "always",
+	"tabWidth": 4,
+	"useTabs": true,
+	"overrides": [
+		{
+			"files": ".github/workflows/**/*.{yml,yaml}",
+			"options": {
+				"proseWrap": "preserve"
+			}
+		}
+	]
+};