docs: document _getDependencyData() directory parameter semantics

Add a Provider Implementation section to CONVENTIONS.md explaining that
_createSbom passes both manifestDir (project directory) and workspaceDir
(lock file directory) to _getDependencyData. Documents when each should
be used and provides guidance for new provider implementations.

Implements TC-4102

Assisted-by: Claude Code

Author: ruromero

CONVENTIONS.md

@@ -0,0 +1,119 @@
+# Coding Conventions
+
+<!-- This file documents project-specific coding standards for exhort-javascript-api. -->
+
+## Language and Framework
+
+- **Primary Language**: JavaScript (ES modules, `"type": "module"` in package.json)
+- **TypeScript**: Configuration present but code is primarily JavaScript with JSDoc
+- **Node.js**: Requires Node >= 20.0.0, npm >= 11.5.1
+- **CLI**: `yargs` for command-line argument parsing
+- **Parsing Libraries**: `fast-xml-parser`, `fast-toml`, `smol-toml`, `tree-sitter-requirements`
+
+## Code Style
+
+- **Linter**: ESLint with recommended config + editorconfig + import plugins
+- **Indentation**: Tabs (4 spaces for YAML/Markdown)
+- **Line endings**: LF
+- **Max line length**: 100 (120 for Markdown)
+- **Charset**: UTF-8, final newline, trim trailing whitespace
+- **Import ordering** (ESLint enforced): builtin, external, internal, parent, sibling, index — alphabetical within groups
+- **Strict equality**: `eqeqeq: ["warn", "always", {"null": "never"}]`
+- **Curly braces**: Required (`curly: "warn"`)
+- **No throw literals**: `no-throw-literal: "warn"`
+- **No Prettier** — ESLint + EditorConfig handle formatting
+
+## Naming Conventions
+
+- **Classes**: PascalCase with underscore-separated language names (`Java_maven`, `Base_java`, `Javascript_npm`)
+- **Files**: snake_case for providers (`base_java.js`, `javascript_npm.js`, `python_pip.js`)
+- **Test files**: `*.test.js` suffix (`analysis.test.js`, `provider.test.js`)
+- **Functions/Methods**: camelCase (`provideComponent()`, `provideStack()`, `validateLockFile()`)
+- **Variables**: camelCase (`manifestPath`, `backendUrl`)
+- **Constants**: UPPER_SNAKE_CASE (`ecosystem_maven`, `DEFAULT_WORKSPACE_DISCOVERY_IGNORE`)
+- **Private class fields**: `#` prefix (`#manifest`, `#cmd`, `#ecosystem`)
+- **Protected methods**: `_` prefix (`_lockFileName()`, `_cmdName()`, `_listCmdArgs()`)
+
+## File Organization
+
+```
+src/
+├── index.js                    # Main export
+├── cli.js                      # CLI entry point
+├── analysis.js                 # API request handling
+├── provider.js                 # Provider matching logic
+├── workspace.js                # Workspace discovery
+├── tools.js                    # Utilities
+├── sbom.js                     # SBOM handling
+├── cyclone_dx_sbom.js          # CycloneDX SBOM generation
+├── providers/                  # Ecosystem providers
+│   ├── base_java.js
+│   ├── base_javascript.js
+│   ├── java_maven.js
+│   ├── javascript_npm.js
+│   ├── python_pip.js
+│   ├── rust_cargo.js
+│   └── processors/            # Specialized processors
+├── license/                    # License detection
+└── oci_image/                  # OCI image analysis
+
+test/
+├── analysis.test.js
+├── provider.test.js
+├── tools.test.js
+└── providers/                  # Provider-specific tests
+```
+
+## Provider Implementation
+
+### `_getDependencyData()` directory parameters
+
+`Base_pyproject._createSbom()` resolves two directories before calling `_getDependencyData()`:
+
+- **`manifestDir`** — the directory containing the `pyproject.toml` being analyzed (`path.dirname(manifest)`). This is always the project directory.
+- **`workspaceDir`** — the directory containing the lock file, found by `_findLockFileDir()` walking up from `manifestDir`. Falls back to `manifestDir` when no lock file is found.
+
+The base class calls `_getDependencyData(manifestDir, workspaceDir, parsed, opts)` with both directories. Subclasses must implement this method with the same 4-parameter signature.
+
+**Lock-file-based providers** (uv, poetry) use `workspaceDir` for lock-file-related operations (parsing, resolving workspace dependencies). They may also use `manifestDir` for running package manager commands that need to execute in the project directory.
+
+**Non-lock-file providers** (pip) must use `manifestDir` for command execution because tools like `pip install .` run relative to the project directory where `pyproject.toml` lives. Since these providers have no lock file, `_findLockFileDir()` returns `null` and `workspaceDir` equals `manifestDir` — but providers must still accept the `workspaceDir` parameter to match the base class signature.
+
+**Guidance for new providers:**
+
+- Always declare all four parameters: `(manifestDir, workspaceDir, parsed, opts)`
+- Use `manifestDir` when running package manager commands that operate on the project (e.g., `pip install .`, `poetry show`)
+- Use `workspaceDir` when reading or resolving lock file contents
+- If your provider does not use a lock file, prefix the unused parameter with `_` (e.g., `_workspaceDir`) to signal that it is intentionally ignored
+
+## Error Handling
+
+- **Throw Error objects**: `throw new Error("message")`, `throw new TypeError("message")`
+- **No custom error classes** — uses built-in `Error` and `TypeError`
+- **HTTP errors**: Check `resp.status`, throw with status code and response text
+- **Async errors**: Bubble up naturally via async/await (no blanket try-catch)
+- **Validation errors**: Thrown early with descriptive context (manifest type, lock file)
+
+## Testing Conventions
+
+- **Framework**: Mocha with TDD UI (`suite()` / `test()`)
+- **Assertions**: Chai with `expect()` syntax
+- **Mocking**: Sinon for stubs; MSW (Mock Service Worker) for HTTP mocking
+- **Module mocking**: `esmock` with experimental loader
+- **Coverage**: C8 with 82% line coverage requirement
+- **Test patterns**: `expect(res).to.deep.equal(...)`, `expect(() => ...).to.throw('message')`
+- **Higher-order setup**: Functions like `interceptAndRun()` for test setup/teardown
+
+## Commit Messages
+
+- Likely Conventional Commits format
+- DCO (Developer Certificate of Origin) required
+- Semantic versioning (`0.3.0` in package.json)
+
+## Dependencies
+
+- **Package manager**: npm with `package-lock.json`
+- **Module system**: ES modules with explicit `.js` extensions in relative imports
+- **Import convention**: `import fs from 'node:fs'` (node: protocol for built-ins)
+- **Environment variables**: Prefixed with `TRUSTIFY_DA_` (e.g., `TRUSTIFY_DA_MVN_PATH`, `TRUSTIFY_DA_TOKEN`, `TRUSTIFY_DA_DEBUG`)
+- **Multi-ecosystem support**: npm, pnpm, yarn, Maven, Gradle, pip, cargo, Go modules, Docker/Podman