@codacy/analysis-runner 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -218,14 +218,54 @@ declare function readBaselineConfig(repositoryRoot: string, configFile?: string)
  * {@link resolveBaselinePath}). No `.codacy/` side effects. Callers write this
  * after every `init`/`update-config` so the next update diffs against the exact
  * generator output. Returns the path written.
+ *
+ * Config paths are relativized exactly as in {@link writeCodacyConfigFile} — the
+ * baseline is compared against the config it snapshots, so the two must agree on
+ * the stored form.
  */
 declare function writeBaselineConfig(repositoryRoot: string, config: CodacyConfig, configFile?: string): Promise<string>;
+/**
+ * Rewrites every tool's `localConfigurationFile` to its repository-relative form,
+ * for serialization.
+ *
+ * Adapters detect their native config by joining `ctx.repositoryRoot`, so the
+ * in-memory value is absolute — and an absolute path names the machine that ran
+ * `init` (`/Users/someone/dev/repo/eslint.config.mjs`). Serializing it verbatim made
+ * `codacy.config.json` unshareable: committed and cloned elsewhere, every tool
+ * pointed at a directory that does not exist. The stored form is therefore relative
+ * (`eslint.config.mjs`), and {@link resolveLocalConfigPaths} restores absolute paths
+ * on read, so adapters see no difference.
+ *
+ * Returns a copy rather than mutating: `init` and `update-config` keep using the
+ * config object after writing it (baseline snapshot, summary output), and they need
+ * the resolved paths.
+ */
+declare function relativizeLocalConfigPaths(config: CodacyConfig, repositoryRoot: string): CodacyConfig;
+/**
+ * Resolves every stored `localConfigurationFile` against `repositoryRoot`, so
+ * adapters always receive an absolute path regardless of how the file on disk
+ * stored it.
+ *
+ * `path.resolve` covers both forms with no branching: a repo-relative path is
+ * joined to the root, and a legacy absolute path — written by a CLI version that
+ * serialized paths verbatim — is returned unchanged. Such a path is only usable on
+ * the machine that produced it; that is the pre-existing breakage this normalization
+ * stops from spreading further, not one it can repair.
+ *
+ * Mutates in place, like {@link coerceParameterValues}: both run on a config that
+ * was just parsed and has no other owner yet.
+ */
+declare function resolveLocalConfigPaths(config: CodacyConfig, repositoryRoot: string): void;
 /**
  * Writes a CodacyConfig to disk at the exact resolved path, creating only the
  * parent directory. Unlike {@link writeCodacyConfig}, this has NO `.codacy/`
  * side effects, so it is safe to write to an arbitrary location (e.g. a scratch
  * config a user is experimenting with).
  *
+ * Per-tool `localConfigurationFile` paths are stored relative to `repositoryRoot`
+ * so the written file stays machine-independent — see
+ * {@link relativizeLocalConfigPaths}.
+ *
  * Pass `configFile` to write to a non-default location.
  */
 declare function writeCodacyConfigFile(repositoryRoot: string, config: CodacyConfig, configFile?: string): Promise<string>;
@@ -410,9 +450,14 @@ declare function parseAutoFilters(raw: string): {
  * The generated client (src/api/client/) is produced from the Codacy OpenAPI spec
  * and should never be edited by hand. All API interactions go through this file.
  *
- * Authentication: Codacy uses an `api-token` header (not Bearer). We set it via
- * `OpenAPI.HEADERS` before each call group. `configureApiToken()` must be called
- * before any authenticated endpoint is used.
+ * Authentication: Codacy uses an `api-token` header (account token) or a
+ * `project-token` header (repository token). `configureApiToken()`
+ * sets exactly one via `OpenAPI.HEADERS` and must be called before any
+ * authenticated endpoint is used. Most operations only accept `api-token`; a
+ * small whitelisted subset of repository-scoped reads (`getRepository`,
+ * `listRepositoryTools`, `listRepositoryToolPatterns`, `listIgnoredFiles`) also
+ * accept `project-token` — the backend rejects it everywhere else exactly as
+ * if no token had been sent.
  *
  * Pagination: all list endpoints use cursor-based pagination. `fetchAllPages()`
  * follows cursors until the response contains no next cursor.
@@ -428,12 +473,41 @@ interface IgnoredFilesResult {
     capped: boolean;
 }
 /**
- * Configures the API token used for authenticated requests.
- * Must be called before `getRepository`, `listRepositoryTools`, or
- * `listRepositoryToolPatterns`. Public endpoints (listTools, listPatterns)
- * do not require a token.
+ * Auth for API calls that accept either an account token or a repository
+ * (project) token — currently only the 4 reads `initRemoteConfig` makes. A
+ * discriminated union (same shape and naming as `UploadAuth` in `upload.ts`)
+ * so "exactly one token" is a compile-time guarantee, not a runtime check,
+ * and so there is never a "both configured" state for the backend to have to
+ * arbitrate — sending both was never useful anyway, since the backend always
+ * prefers `api-token` when both are present.
+ */
+type RemoteAuth = {
+    kind: "account-token";
+    token: string;
+} | {
+    kind: "repository-token";
+    token: string;
+};
+/**
+ * Configures the auth header used for authenticated requests. Must be called
+ * before `getRepository`, `listRepositoryTools`, `listRepositoryToolPatterns`,
+ * or `listIgnoredFiles`. Public endpoints (listTools, listPatterns) do not
+ * require a token.
+ *
+ * Accepts a bare account-token string, for source compatibility with this
+ * function's original `(token: string)` shape — this is a published package,
+ * and embedders (a VSCode extension, an MCP server) call it directly with a
+ * bare string — or a {@link RemoteAuth} object to configure a repository
+ * token instead. Throws if given neither a non-empty string nor a valid
+ * `RemoteAuth`, rather than silently configuring no auth at all.
+ *
+ * Fully replaces any previously configured auth — it does not merge with a
+ * prior call. A process driving multiple auth contexts (e.g. an embedder
+ * juggling an account token for one repository and a project token for
+ * another) must call this again immediately before each authenticated call
+ * group, the same way `initRemoteConfig` does internally.
  */
-declare function configureApiToken(token: string): void;
+declare function configureApiToken(auth: string | RemoteAuth): void;
 /**
  * Validates an API token by calling the authenticated user endpoint.
  * Returns user info on success; caller should catch errors for invalid tokens.
@@ -447,7 +521,8 @@ declare function validateApiToken(token: string): Promise<{
  * Fetches files individually ignored in Codacy Cloud for a repository.
  * Uses cursor-based pagination capped at 10 pages (1000 files max) to avoid
  * unbounded fetching for repositories with very large ignore lists.
- * Requires `configureApiToken()` to have been called.
+ * Requires `configureApiToken()` to have been called with an account token
+ * or a repository (project) token — this operation accepts either.
  */
 declare function listIgnoredFiles(provider: string, org: string, repo: string): Promise<IgnoredFilesResult>;
 
@@ -557,6 +632,13 @@ interface InitRemoteStats {
  * as unsupported (cloud-only) entries (subject to the trackability filter — deprecated and
  * client-side/standalone-only tools are skipped).
  *
+ * @param auth - Account token or repository (project) token — a repository token alone
+ *   is enough for all four API calls this function makes, no login required. Also
+ *   accepts a bare account-token string, for source compatibility with callers written
+ *   against this function's original `apiToken: string` shape — this parameter used to
+ *   be exactly that, and this is a published package (embedders like a VSCode extension
+ *   or MCP server call it directly), so the old call shape must keep working unchanged.
+ *   See {@link configureApiToken} for the exact accepted shapes and validation.
  * @param onRemoteToolsFound - Optional callback invoked once after the list of enabled
  *   remote tools is fetched. Receives the total count of enabled tools and the count
  *   that have a registered local adapter. Fires before per-tool pattern fetching begins.
@@ -566,7 +648,7 @@ interface InitRemoteStats {
  * @param onIgnoredFilesFetched - Optional callback invoked after cloud-ignored files are
  *   fetched. Receives the count and whether the 1000-file cap was reached.
  */
-declare function initRemoteConfig(repositoryRoot: string, provider: string, organization: string, repositoryName: string, adapters: Readonly<ToolAdapter>[], apiToken: string, onRemoteToolsFound?: (totalEnabledTools: number, matchedAdapters: number) => void, onToolProcessed?: (displayName: string, patternCount: number, usesConfigFile: boolean) => void, onIgnoredFilesFetched?: (count: number, capped: boolean) => void): Promise<{
+declare function initRemoteConfig(repositoryRoot: string, provider: string, organization: string, repositoryName: string, adapters: Readonly<ToolAdapter>[], auth: string | RemoteAuth, onRemoteToolsFound?: (totalEnabledTools: number, matchedAdapters: number) => void, onToolProcessed?: (displayName: string, patternCount: number, usesConfigFile: boolean) => void, onIgnoredFilesFetched?: (count: number, capped: boolean) => void): Promise<{
     config: CodacyConfig;
     stats: InitRemoteStats;
 }>;
@@ -852,6 +934,7 @@ declare function createLogger(options?: LoggerOptions): Logger;
  *
  * All crypto uses Node.js built-in `crypto` — no external dependencies.
  */
+
 /**
  * Encrypts and saves an API token to ~/.codacy/credentials.
  * Creates the ~/.codacy/ directory if it doesn't exist.
@@ -876,6 +959,41 @@ declare function deleteCredentials(): Promise<boolean>;
  * 3. Throws with instructions if neither source has a token.
  */
 declare function resolveApiToken(): Promise<string>;
+/**
+ * Resolves auth for `init --remote` / `update-config --remote`: an explicit
+ * repository token (`repositoryToken` argument, or `CODACY_PROJECT_TOKEN`)
+ * wins outright — matching `upload`'s precedence for the same flag
+ * (`upload.ts:87-90`) — without even attempting to resolve an account token,
+ * so an explicitly-scoped run never pays the cost of loading a stored login
+ * it didn't ask for, and is never silently re-scoped to a broader token an
+ * ambient `CODACY_API_TOKEN` or prior `login` happens to leave lying around.
+ * Only when no repository token is given does this fall back to an account
+ * token, read the same way {@link resolveApiToken} does (env var, then
+ * stored credentials) — inlined here rather than calling it, so a missing
+ * account token falls through to the error below instead of throwing.
+ */
+declare function resolveRemoteAuth(repositoryToken?: string): Promise<RemoteAuth>;
+
+/**
+ * Turning a raw manifest identifier into an entity.
+ *
+ * Classification is **scoped to the ecosystem the identifier came from**, with no
+ * global fallback. A fallback is the bug this module exists to prevent: with one
+ * name-keyed catalog, the sbt artifact `requests` (com.lihaoyi) matched PyPI's
+ * Requests, and any bare gem or crate name could borrow another language's
+ * package. An artifact id is only meaningful inside its own registry, so that is
+ * the only place it is looked up.
+ */
+
+/**
+ * Display names of every entity discovery can emit.
+ *
+ * Kept for consumers that report on the catalog. Note it is **not** the set of
+ * gating keys — those are entity keys ({@link getEntityProviders}) — precisely
+ * because display names are not unique: Angular 2+, AngularJS and AngularDart all
+ * display as "Angular".
+ */
+declare function getKnownDisplayNames(): Set<string>;
 
 /**
  * Repository discovery — scans a codebase and identifies languages, file patterns,
@@ -884,8 +1002,12 @@ declare function resolveApiToken(): Promise<string>;
  * The discover() function is the main entry point. It runs a 4-phase pipeline:
  * 1. File discovery (extensions, notable files)
  * 2. Language detection (reuses detectLanguages)
- * 3. Manifest parsing (dependency extraction)
- * 4. Dependency classification (framework / library / platform / tool)
+ * 3. Manifest parsing (dependency extraction, per owning ecosystem)
+ * 4. Classification (raw identifier → entity, scoped to that ecosystem)
+ *
+ * The static knowledge behind phases 3 and 4 lives in `./ecosystems/` (one module
+ * per package registry), `./signals.ts` and `./notable-files.ts`; the entity
+ * vocabulary itself is in `@codacy/tooling`.
  */
 
 /** Options for the discover function. */
@@ -897,7 +1019,7 @@ interface DiscoverOptions {
      *
      * Callers that feed discovery into configuration decisions **must** pass the
      * same excludes `analyze` will apply (see `resolveDiscoveryExcludes` in
-     * `./codacy-yaml`). Otherwise discovery reports languages, frameworks, and
+     * `../codacy-yaml`). Otherwise discovery reports languages, frameworks, and
      * libraries that only exist in excluded paths — e.g. a tool-orchestration
      * monorepo whose per-language sample files all live under
      * `**\/test/fixtures/**` looks like a 20-language polyglot repo, and every
@@ -911,23 +1033,6 @@ interface DiscoverOptions {
  */
 declare function discover(repositoryRoot: string, options?: DiscoverOptions): Promise<DiscoveryResult>;
 
-/**
- * Discovery catalog — static knowledge base for the discover command.
- *
- * Contains manifest file parsers, a curated dependency classification catalog,
- * and notable file detection rules. All parsers are pure functions that accept
- * raw file content and return dependency name arrays. They never throw.
- */
-
-/**
- * Every display name discovery can emit from a dependency/file/package.json signal.
- * This is the authoritative set a framework-mapping key must belong to (together
- * with detected language names) for its patterns to ever gate on. The drift-guard
- * test uses it to catch mapping keys that no signal can produce (e.g. a rename
- * like react-intl → formatjs that updates the mapping but not the catalog).
- */
-declare function getKnownDisplayNames(): Set<string>;
-
 /**
  * Git repository introspection helpers used by commands that need to know
  * *where* they are (repository root) and *what* they are looking at (the current
@@ -1119,4 +1224,4 @@ declare function buildPayloads(issues: NormalizedIssue[], resolveShortName: (too
  */
 declare function uploadReport(options: UploadOptions): Promise<UploadResult>;
 
-export { type AdapterFactory, type AnalyzeOptions, type AutoFilters, type CategoryFilter, type CodacyYamlConfig, type CodacyYamlEngineConfig, type ConfigOperation, type DiscoverOptions, type DiscoveryExcludes, type ExecutionMode, type IgnoredFilesResult, type InitAutoStats, type InitDefaultStats, type InitDiscoveryOptions, type InitLocalStats, type InitRemoteStats, type LoggerOptions, type MergeOptions, type NormalizedIssue, type PatternMetadataLookup, type SeverityFilter, type UploadAuth, type UploadOptions, type UploadResult, analyze, applyCodacyYamlExcludes, applyConfigOperation, buildPayloads, buildToolConfig, clearAdapters, computePatternSummary, configureApiToken, createCodacyConfig, createLogger, createNullLogger, deleteCredentials, detectLanguages, diffConfigs, discover, formatOutput, formatTextSummary, getAdapter, getKnownDisplayNames, getRegisteredAdapters, getRegisteredDescriptors, initAutoConfig, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, intersectConfigs, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, loadCredentials, mergeConfigs, parseAutoFilters, parseReport, pruneEmptyTools, readBaselineConfig, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveDiscoveryExcludes, resolveEngineToAdapter, resolveHeadCommit, resolveRepositoryRoot, resolveResultsApiBaseUrl, rotateLogFiles, saveCredentials, updateConfigIncremental, uploadReport, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };
+export { type AdapterFactory, type AnalyzeOptions, type AutoFilters, type CategoryFilter, type CodacyYamlConfig, type CodacyYamlEngineConfig, type ConfigOperation, type DiscoverOptions, type DiscoveryExcludes, type ExecutionMode, type IgnoredFilesResult, type InitAutoStats, type InitDefaultStats, type InitDiscoveryOptions, type InitLocalStats, type InitRemoteStats, type LoggerOptions, type MergeOptions, type NormalizedIssue, type PatternMetadataLookup, type RemoteAuth, type SeverityFilter, type UploadAuth, type UploadOptions, type UploadResult, analyze, applyCodacyYamlExcludes, applyConfigOperation, buildPayloads, buildToolConfig, clearAdapters, computePatternSummary, configureApiToken, createCodacyConfig, createLogger, createNullLogger, deleteCredentials, detectLanguages, diffConfigs, discover, formatOutput, formatTextSummary, getAdapter, getKnownDisplayNames, getRegisteredAdapters, getRegisteredDescriptors, initAutoConfig, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, intersectConfigs, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, loadCredentials, mergeConfigs, parseAutoFilters, parseReport, pruneEmptyTools, readBaselineConfig, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, relativizeLocalConfigPaths, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveDiscoveryExcludes, resolveEngineToAdapter, resolveHeadCommit, resolveLocalConfigPaths, resolveRemoteAuth, resolveRepositoryRoot, resolveResultsApiBaseUrl, rotateLogFiles, saveCredentials, updateConfigIncremental, uploadReport, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };