@alint-js/plugin 0.1.3 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -1,8 +1,62 @@
-//#region ../core/dist/types-DSvXUVZ7.d.mts
+//#region ../core/dist/types-DM4idR4w.d.mts
 //#region src/core/source/types.d.ts
-type ClassTarget = SourceTargetOfKind<'class'>;
-type FileTarget = SourceTargetOfKind<'file'>;
-type FunctionTarget = SourceTargetOfKind<'function'>;
+interface BaseSourceFile {
+  contentHash: string;
+  language: string;
+  path: string;
+}
+/**
+ * Carried on a file target under `metadata.calls`, in source order.
+ *
+ * Every call in the file, including those outside any function: a consumer counting how often a
+ * name is used has to see the uses, not just the definitions.
+ */
+interface CallSite extends SourceMetadataObject {
+  /** The last segment only: `a.b.helper()` and `helper()` both yield `helper`. */
+  name: string;
+  /** Absolute, into the file's text. */
+  range: SourceRange;
+}
+type ClassTarget = PlannedSourceTargetOfKind<'class'>;
+type FileTarget = PlannedSourceTargetOfKind<'file'>;
+/**
+ * Carried under `metadata.function`, so a consumer can fingerprint, count and classify a function
+ * without reaching for a parser of its own.
+ *
+ * Every producer of function targets should fill it in; a consumer still validates the expected
+ * domain fields when reading the recursive JSON metadata contract.
+ *
+ * Ranges are relative to the target's own `text`, not to the file, so a consumer can slice that
+ * text directly and never has to rebase.
+ */
+interface FunctionInfo extends SourceMetadataObject {
+  /**
+   * Stricter than one statement: a body that is one `if` and its two returns is one statement and
+   * not one expression.
+   */
+  bodyIsSingleExpression: boolean;
+  /** Statements in the body, not counting comments. */
+  bodyStatements: number;
+  commentRanges: readonly SourceRange[];
+  /**
+   * The names the function declares: its own name, its parameters and its locals.
+   *
+   * A copy can rename what it declares and stay a copy, so this is the set an α-renaming
+   * fingerprint may replace. Everything else — callees, globals, types, properties — stays
+   * verbatim and is what tells two same-shaped functions apart.
+   */
+  declaredNames: readonly string[];
+  /** Reachable from outside its file, however the language spells it. */
+  exported: boolean;
+  /**
+   * Identifiers that MAY be renamed away, which is narrower than "every identifier token".
+   *
+   * Property, field and type names must not be here: replacing them collapses `entry.name` and
+   * `entry.size` into the same fingerprint, which is the mistake this set exists to avoid.
+   */
+  identifierRanges: readonly SourceRange[];
+}
+type FunctionTarget = PlannedSourceTargetOfKind<'function'>;
 interface LanguageContext {
   cwd: string;
   languageOptions: Record<string, unknown>;
@@ -12,6 +66,20 @@ interface LineRange {
   endLine: number;
   startLine: number;
 }
+interface PlannedSourceTarget {
+  file: BaseSourceFile;
+  identity: string;
+  kind: SourceTargetKind;
+  language: string;
+  loc?: SourceLocation;
+  metadata?: SourceTargetMetadata;
+  name?: string;
+  origin?: SourceTargetOrigin;
+  range?: SourceRange;
+}
+type PlannedSourceTargetOfKind<Kind extends SourceTargetKind> = Omit<PlannedSourceTarget, 'kind'> & {
+  kind: Kind;
+};
 interface ProcessedSource {
   identity: string;
   language?: string;
@@ -33,16 +101,26 @@ interface ProcessorPostprocessContext extends ProcessorContext {
   file: SourceFile;
   processedSources: ProcessedSource[];
 }
-interface SourceFile {
-  language: string;
+interface SourceExtractOptions {
+  /**
+   * Overrides the file's configured `language:` pin.
+   *
+   * For a caller walking a mixed tree, where the file's own config cannot know what each file is.
+   */
+  language?: string;
+}
+interface SourceFile extends BaseSourceFile {
   lines: string[];
-  path: string;
   text: string;
 }
 interface SourceLocation {
   end: SourcePosition;
   start: SourcePosition;
 }
+interface SourceMetadataObject {
+  readonly [key: string]: SourceMetadataValue;
+}
+type SourceMetadataValue = boolean | null | number | readonly SourceMetadataValue[] | SourceMetadataObject | SourceRange | string;
 interface SourcePosition {
   column: number;
   line: number;
@@ -52,8 +130,22 @@ interface SourceRange {
   start: number;
 }
 interface SourceRuntime {
-  getText: (target: SourceFile | SourceTarget) => string;
-  readFile: (filePath: string) => Promise<SourceFile>;
+  /**
+   * Targets for any file, linted or not.
+   *
+   * Resolves the file's own config the way linting does, resolves its language from that config,
+   * and runs that language's extract. A rule handed `ProjectTarget.files`, or an index builder
+   * sweeping files outside the lint set, has no other way to parse them.
+   *
+   * An ignored file extracts to `[]` rather than throwing: sweeping broadly and skipping what the
+   * config excluded is the normal case, not an error.
+   *
+   * Only wired inside a run. A runtime built by `createSourceRuntime()` with no extractor throws,
+   * because there is no config to resolve the file against.
+   */
+  extract: (filePath: string, options?: SourceExtractOptions) => Promise<SourceTarget[]>;
+  getText: (file: SourceFile) => string;
+  readFile: (file: BaseSourceFile | string) => Promise<SourceFile>;
   sliceLines: (file: SourceFile, range: LineRange) => SourceText;
   sliceRange: (file: SourceFile, range: SourceRange) => SourceText;
 }
@@ -63,13 +155,14 @@ interface SourceTarget {
   kind: SourceTargetKind;
   language: string;
   loc?: SourceLocation;
-  metadata?: Record<string, unknown>;
+  metadata?: SourceTargetMetadata;
   name?: string;
   origin?: SourceTargetOrigin;
   range?: SourceRange;
   text: string;
 }
 type SourceTargetKind = 'class' | 'file' | 'fragment' | 'function' | 'symbol' | (string & {});
+type SourceTargetMetadata = Readonly<Record<string, SourceMetadataValue>>;
 type SourceTargetOfKind<Kind extends SourceTargetKind> = Omit<SourceTarget, 'kind'> & {
   kind: Kind;
 };
@@ -710,7 +803,7 @@ interface Config<TIssue extends BaseIssue<unknown>> {
   readonly abortPipeEarly?: boolean | undefined;
 }
 //#endregion
-//#region ../core/dist/types-DKylUrAn.d.mts
+//#region ../core/dist/types-deBCDA4_.d.mts
 //#region src/config/types.d.ts
 type ModelSize = 'large' | 'medium' | 'small';
 interface RunnerCacheConfig {
@@ -805,6 +898,12 @@ interface AlintConfigItem {
 }
 interface AlintLinterOptions {
   noInlineConfig?: boolean;
+  /**
+   * How the run reports files it lints that no language claimed, so they were handled as plain
+   * text. Defaults to `'warn'`. An explicit `language: 'plaintext'` pin means plain text was the
+   * intent, so pinned files are never reported.
+   */
+  reportUnregisteredLanguages?: RuleSeverity;
   reportUnusedDisableDirectives?: RuleSeverity;
 }
 type Awaitable<T> = Promise<T> | T;
@@ -841,6 +940,20 @@ interface IgnoreConfig {
 interface LanguageDefinition {
   extensions?: readonly string[];
   extract: (file: SourceFile, context: LanguageContext) => Awaitable<SourceTarget[]>;
+  /**
+   * The language's id: what a config pins through `language:`, what a rule's `languages` lists, and
+   * what every target it extracts reports. The registry is keyed by it, so two packs cannot claim
+   * the same one.
+   *
+   * Use the identifier editors already use — `go`, `python`, `rust`, `typescript`, `plaintext` —
+   * rather than inventing a spelling. Anyone can register a language, so the set is open by
+   * definition and only a shared convention keeps one language from arriving under three names.
+   *
+   * NOTICE: the list is VS Code's. The Language Server Protocol shares it for the languages it
+   * covers, but its table has no entry for plain text, so `plaintext` comes from VS Code alone.
+   * https://code.visualstudio.com/docs/languages/identifiers
+   * https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentItem
+   */
   name: string;
 }
 interface PluginDefinition<Rules extends Record<string, RuleDefinition<any>> = Record<string, RuleDefinition<any>>> {
@@ -853,10 +966,7 @@ interface ProcessorDefinition {
   postprocess?: (diagnostics: DiagnosticDescriptor[], context: ProcessorPostprocessContext) => Awaitable<DiagnosticDescriptor[]>;
   preprocess: (file: SourceFile, context: ProcessorContext) => Awaitable<ProcessedSource[]>;
 }
-interface ProjectFileEntry {
-  contentHash: string;
-  language: string;
-  path: string;
+interface ProjectFileEntry extends BaseSourceFile {
   targetCount: number;
 }
 interface ProjectTarget {
@@ -906,6 +1016,15 @@ interface RuleDefinition<OptionsSchema extends RuleOptionsSchema = []> {
   /** Additional stable rule inputs, such as imported prompts, that invalidate cached results when changed. */
   cacheKey?: unknown;
   create: (context: RuleContext<RuleOptionsOutput<OptionsSchema>>) => RuleHandlers;
+  /**
+   * Which languages this rule reads. Omitting it opts out of extraction: the rule still receives
+   * file targets, but never the function and class targets a language produces.
+   *
+   * It does not choose how a file is parsed. A config's `language:` pin, or the extension, settles
+   * that before any rule is consulted. Directory and project targets ignore it too: they index a
+   * tree rather than come from a language.
+   */
+  languages?: RuleLanguages;
   model?: ModelRequirement;
   options?: OptionsSchema;
 }
@@ -920,6 +1039,23 @@ interface RuleInferenceUsageRecord {
   ruleId?: string;
   totalTokens?: number;
 }
+/**
+ * - `'any'` — every registered language, and never a failure. A rule that works from `FunctionInfo`
+ *   alone wants this: a language pack the user installs later is covered without a new release.
+ * - A list of language ids — `LanguageDefinition.name` values such as `go` or `typescript`, never
+ *   file extensions. The rule handles exactly these. Files of other languages are skipped
+ *   rather than failed, so one plugin can carry rules for several languages behind one `files:`
+ *   glob. If a listed language is not registered at all the run fails, because a rule scoped to a
+ *   language nothing provides would otherwise skip every file in silence.
+ * - `{ ids: string[], skipMissing?: boolean }` — the same scoping, but an unregistered id can be
+ *   skipped instead of failing. For a plugin whose rules span languages a given user may not have installed.
+ */
+type RuleLanguages = 'any' | readonly string[] | {
+  /** Language ids this rule applies to. */
+  ids: readonly string[];
+  /** Whether to skip unregistered languages instead of failing. */
+  skipMissing?: boolean;
+};
 type RuleOptionsInput<OptionsSchema extends RuleOptionsSchema> = { readonly [Index in keyof OptionsSchema]: InferInput<OptionsSchema[Index]>; };
 type RuleOptionsOutput<OptionsSchema extends RuleOptionsSchema> = { readonly [Index in keyof OptionsSchema]: InferOutput<OptionsSchema[Index]>; };
 type RuleOptionsSchema = readonly GenericSchema[];
@@ -944,9 +1080,9 @@ interface RuleWithHandler {
   onTargetProject?: never;
   onTargetWith: (target: Target) => Awaitable<void>;
 }
-type Target = DirectoryTarget | ProjectTarget | SourceTarget;
+type Target = DirectoryTarget | PlannedSourceTarget | ProjectTarget;
 //#endregion
-//#region ../core/dist/define-8BzWDcPs.d.mts
+//#region ../core/dist/define-CJ2QJPZ8.d.mts
 //#region src/dsl/define.d.ts
 type AnyRuleDefinition = RuleDefinition<any>;
 type ConfigItemWithPluginRules<Plugins, Rules> = Omit<AlintConfigItem, 'plugins' | 'rules'> & {
@@ -991,4 +1127,4 @@ declare function isRetryableAgentError(error: unknown): error is RetryableAgentE
 declare function defineTool(tool: AgentTool): AgentTool;
 declare function requireAgent(context: Pick<RuleContext, 'agent' | 'id' | 'signal'>): AgentAdapter;
 //#endregion
-export { type AgentAdapter, type AgentRequest, type AgentResult, type AgentTool, type AgentUsage, type AlintConfig, type AlintConfigExtends, type AlintConfigInput, type AlintConfigItem, type AlintLinterOptions, type Awaitable, type ClassTarget, type DiagnosticDescriptor, type DiagnosticLocation, type DirectoryTarget, type EnabledRule, type FileTarget, type FunctionTarget, type IgnoreConfig, type LanguageContext, type LanguageDefinition, type LineRange, type ModelRequirement, type PluginDefinition, type ProcessedSource, type ProcessedSourceOrigin, type ProcessorContext, type ProcessorDefinition, type ProcessorPostprocessContext, type ProjectFileEntry, type ProjectTarget, type ProjectTargetEntry, type ResolvedModel, type ResolvedProvider, RetryableAgentError, type RuleCacheConfig, type RuleConfigEntry, type RuleContext, type RuleDefinition, type RuleHandlers, type RuleInferenceUsageRecord, type RuleRegistry, type RuleSeverity, type RuleSpecializedHandlers, type RuleWithHandler, type SourceFile, type SourceLocation, type SourcePosition, type SourceRange, type SourceRuntime, type SourceTarget, type SourceTargetKind, type SourceTargetOfKind, type SourceTargetOrigin, type SourceText, type Target, defineConfig, definePlugin, defineRule, defineTool, isRetryableAgentError, requireAgent };
+export { type AgentAdapter, type AgentRequest, type AgentResult, type AgentTool, type AgentUsage, type AlintConfig, type AlintConfigExtends, type AlintConfigInput, type AlintConfigItem, type AlintLinterOptions, type Awaitable, type BaseSourceFile, type CallSite, type ClassTarget, type DiagnosticDescriptor, type DiagnosticLocation, type DirectoryTarget, type EnabledRule, type FileTarget, type FunctionInfo, type FunctionTarget, type IgnoreConfig, type LanguageContext, type LanguageDefinition, type LineRange, type ModelRequirement, type PlannedSourceTarget, type PlannedSourceTargetOfKind, type PluginDefinition, type ProcessedSource, type ProcessedSourceOrigin, type ProcessorContext, type ProcessorDefinition, type ProcessorPostprocessContext, type ProjectFileEntry, type ProjectTarget, type ProjectTargetEntry, type ResolvedModel, type ResolvedProvider, RetryableAgentError, type RuleCacheConfig, type RuleConfigEntry, type RuleContext, type RuleDefinition, type RuleHandlers, type RuleInferenceUsageRecord, type RuleRegistry, type RuleSeverity, type RuleSpecializedHandlers, type RuleWithHandler, type SourceFile, type SourceLocation, type SourceMetadataObject, type SourceMetadataValue, type SourcePosition, type SourceRange, type SourceRuntime, type SourceTarget, type SourceTargetKind, type SourceTargetMetadata, type SourceTargetOfKind, type SourceTargetOrigin, type SourceText, type Target, defineConfig, definePlugin, defineRule, defineTool, isRetryableAgentError, requireAgent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/plugin",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -14,7 +14,7 @@
   ],
   "devDependencies": {
     "valibot": "^1.4.2",
-    "@alint-js/core": "0.1.3"
+    "@alint-js/core": "0.1.5"
   },
   "scripts": {
     "build": "tsdown",