@alint-js/plugin-js 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,9 +1,14 @@
 //#region ../plugin/dist/index.d.mts
-//#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;
+}
+type ClassTarget = PlannedSourceTargetOfKind<'class'>;
+type FileTarget = PlannedSourceTargetOfKind<'file'>;
+type FunctionTarget = PlannedSourceTargetOfKind<'function'>;
 interface LanguageContext {
   cwd: string;
   languageOptions: Record<string, unknown>;
@@ -13,6 +18,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;
@@ -34,16 +53,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;
@@ -53,8 +82,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;
 }
@@ -64,16 +107,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 SourceTargetOfKind<Kind extends SourceTargetKind> = Omit<SourceTarget, 'kind'> & {
-  kind: Kind;
-};
+type SourceTargetMetadata = Readonly<Record<string, SourceMetadataValue>>;
 interface SourceTargetOrigin {
   physicalPath: string;
   range?: SourceRange;
@@ -705,7 +746,7 @@ interface Config$1<TIssue extends BaseIssue$1<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 {
@@ -797,6 +838,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;
@@ -826,6 +873,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>>> {
@@ -838,10 +899,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 {
@@ -891,6 +949,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;
 }
@@ -905,6 +972,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 RuleOptionsOutput<OptionsSchema extends RuleOptionsSchema> = { readonly [Index in keyof OptionsSchema]: InferOutput$1<OptionsSchema[Index]>; };
 type RuleOptionsSchema = readonly GenericSchema[];
 type RuleSeverity = 'error' | 'off' | 'warn';
@@ -924,7 +1008,7 @@ interface RuleWithHandler {
   onTargetProject?: never;
   onTargetWith: (target: Target) => Awaitable<void>;
 }
-type Target = DirectoryTarget | ProjectTarget | SourceTarget;
+type Target = DirectoryTarget | PlannedSourceTarget | ProjectTarget;
 //#endregion
 //#region ../../node_modules/.pnpm/valibot@1.4.2_typescript@6.0.3/node_modules/valibot/dist/index.d.mts
 //#endregion

package/dist/index.mjs

@@ -1983,8 +1983,26 @@ async function judgeSource(options) {
 //#region src/rules/inline-miniature-normalizer/rule.ts
 const inlineMiniatureNormalizerRule = defineRule({
 	cacheKey: inlineMiniatureNormalizerPrompt,
-	create: (ctx) => ({ async onTargetFile(target) {
+	create: (ctx) => ({ 
+	/**
+	* Reviews one planned file for inline miniature normalizers.
+	*
+	* Triggering workflow:
+	*
+	* {@link inlineMiniatureNormalizerRule}
+	*   -> `RuleHandlers.onTargetFile`
+	*     -> {@link judgeSource}
+	*
+	* Upstream:
+	* - {@link inlineMiniatureNormalizerRule}
+	*
+	* Downstream:
+	* - {@link judgeSource}
+	* - `RuleContext.report`
+	*/
+async onTargetFile(target) {
 		const model = await ctx.model();
+		const file = await ctx.src.readFile(target.file);
 		const findings = await judgeSource({
 			logger: ctx.logger,
 			metering: ctx.metering,
@@ -1993,7 +2011,7 @@ const inlineMiniatureNormalizerRule = defineRule({
 			outputLanguage: ctx.outputLanguage,
 			prompt: inlineMiniatureNormalizerPrompt,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source: file.text
 		});
 		for (const finding of findings) ctx.report({
 			evidence: {
@@ -4959,9 +4977,10 @@ var RepositoryReviewProtocolError = class extends Error {
 async function reviewRepository(ctx, target, options) {
 	const agent = requireAgent(ctx);
 	const model = await ctx.model();
+	const file = await ctx.src.readFile(target.file);
 	const submission = createSubmitReviewTool({
 		allowedCategories: options.allowedCategories,
-		lineCount: target.file.lines.length,
+		lineCount: file.lines.length,
 		requireFutureFailure: options.requireFutureFailure ?? false,
 		requireRelatedLocations: options.requireRelatedLocations ?? false
 	});
@@ -4974,7 +4993,7 @@ async function reviewRepository(ctx, target, options) {
 		model,
 		prompt: [options.prompt, JSON.stringify({
 			path: repositoryRelativePath(ctx.cwd, target.file.path),
-			source: formatSourceWithLineNumbers(target.file.text)
+			source: formatSourceWithLineNumbers(file.text)
 		})].join("\n\n"),
 		tools: [...withNumberedReads(createTools(ctx.cwd)), submission.tool]
 	});
@@ -5207,7 +5226,7 @@ function createMixedLayersWithoutAbstractionRule(dependencies = defaultMixedLaye
 			*
 			* Triggering workflow:
 			*
-			* `executeSourceSession`
+			* `planSource`
 			*   -> `sourceExecution`
 			*     -> `RuleHandlers.onTargetFile`
 			*       -> {@link onTargetFile}
@@ -5218,8 +5237,8 @@ function createMixedLayersWithoutAbstractionRule(dependencies = defaultMixedLaye
 			*                 -> {@link reportMixedLayerFindings}
 			*
 			* Upstream:
-			* - `executeSourceSession` owns source extraction, source-backed job lifetime, and
-			*   handler selection through `sourceExecution` in `packages/core/src/core/source/session.ts`
+			* - `planSource` owns source extraction and compact job admission, with handler selection
+			*   through `sourceExecution` in `packages/core/src/core/source/planner.ts`
 			*
 			* Downstream:
 			* - {@link generateStructured} -> coverage and data-flow draft
@@ -5230,7 +5249,7 @@ function createMixedLayersWithoutAbstractionRule(dependencies = defaultMixedLaye
 			*/
 			async function onTargetFile(target) {
 				const model = await ctx.model();
-				const source = ctx.src.getText(target);
+				const source = (await ctx.src.readFile(target.file)).text;
 				const firstDraft = await dependencies.generateDraft({
 					createMessages: (retryFeedback) => createMixedLayerMessages(source, mixedLayersWithoutAbstractionCoveragePerspective, retryFeedback, ctx.outputLanguage),
 					logger: ctx.logger,
@@ -5513,8 +5532,26 @@ Return warnings only. If uncertain, use medium or low confidence instead of forc
 //#region src/rules/no-private-schema-toolkit/rule.ts
 const privateSchemaToolkitRule = defineRule({
 	cacheKey: privateSchemaToolkitPrompt,
-	create: (ctx) => ({ async onTargetFile(target) {
+	create: (ctx) => ({ 
+	/**
+	* Reviews one planned file for private schema toolkits.
+	*
+	* Triggering workflow:
+	*
+	* {@link privateSchemaToolkitRule}
+	*   -> `RuleHandlers.onTargetFile`
+	*     -> {@link judgeSource}
+	*
+	* Upstream:
+	* - {@link privateSchemaToolkitRule}
+	*
+	* Downstream:
+	* - {@link judgeSource}
+	* - `RuleContext.report`
+	*/
+async onTargetFile(target) {
 		const model = await ctx.model();
+		const file = await ctx.src.readFile(target.file);
 		const findings = await judgeSource({
 			logger: ctx.logger,
 			metering: ctx.metering,
@@ -5523,7 +5560,7 @@ const privateSchemaToolkitRule = defineRule({
 			outputLanguage: ctx.outputLanguage,
 			prompt: privateSchemaToolkitPrompt,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source: file.text
 		});
 		for (const finding of findings) ctx.report({
 			evidence: {
@@ -5703,7 +5740,7 @@ const redundantBindingRule = defineRule({
 	* Triggering workflow:
 	*
 	* {@link defineRule}
-	*   -> `SourceTarget.kind === "file"`
+	*   -> `PlannedSourceTarget.kind === "file"`
 	*     -> `onTargetFile`
 	*       -> {@link judgeSource} / {@link verifyRedundantBindings}
 	*
@@ -5717,6 +5754,7 @@ const redundantBindingRule = defineRule({
 	*/
 async onTargetFile(target) {
 		const model = await ctx.model();
+		const source = (await ctx.src.readFile(target.file)).text;
 		const candidates = await judgeSource({
 			logger: ctx.logger,
 			metering: ctx.metering,
@@ -5725,7 +5763,7 @@ async onTargetFile(target) {
 			outputLanguage: ctx.outputLanguage,
 			prompt: redundantBindingPrompt,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source
 		});
 		if (candidates.length === 0) return;
 		const candidateLines = new Set(candidates.map((candidate) => candidate.line));
@@ -5736,7 +5774,7 @@ async onTargetFile(target) {
 			model,
 			outputLanguage: ctx.outputLanguage,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source
 		});
 		const reportedLines = /* @__PURE__ */ new Set();
 		for (const finding of verifiedFindings) {
@@ -5835,8 +5873,26 @@ Return warnings only. If uncertain, use medium or low confidence instead of forc
 //#region src/rules/no-redundant-jsdoc/rule.ts
 const redundantJsdocRule = defineRule({
 	cacheKey: redundantJsdocPrompt,
-	create: (ctx) => ({ async onTargetFile(target) {
+	create: (ctx) => ({ 
+	/**
+	* Reviews one planned file for redundant JSDoc.
+	*
+	* Triggering workflow:
+	*
+	* {@link redundantJsdocRule}
+	*   -> `RuleHandlers.onTargetFile`
+	*     -> {@link judgeSource}
+	*
+	* Upstream:
+	* - {@link redundantJsdocRule}
+	*
+	* Downstream:
+	* - {@link judgeSource}
+	* - `RuleContext.report`
+	*/
+async onTargetFile(target) {
 		const model = await ctx.model();
+		const file = await ctx.src.readFile(target.file);
 		const findings = await judgeSource({
 			logger: ctx.logger,
 			metering: ctx.metering,
@@ -5845,7 +5901,7 @@ const redundantJsdocRule = defineRule({
 			outputLanguage: ctx.outputLanguage,
 			prompt: redundantJsdocPrompt,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source: file.text
 		});
 		for (const finding of findings) ctx.report({
 			evidence: {
@@ -6012,8 +6068,26 @@ Return warnings only. If uncertain, use medium or low confidence instead of forc
 //#region src/rules/no-trivial-wrapper-stack/rule.ts
 const trivialWrapperStackRule = defineRule({
 	cacheKey: trivialWrapperStackPrompt,
-	create: (ctx) => ({ async onTargetFile(target) {
+	create: (ctx) => ({ 
+	/**
+	* Reviews one planned file for trivial wrapper stacks.
+	*
+	* Triggering workflow:
+	*
+	* {@link trivialWrapperStackRule}
+	*   -> `RuleHandlers.onTargetFile`
+	*     -> {@link judgeSource}
+	*
+	* Upstream:
+	* - {@link trivialWrapperStackRule}
+	*
+	* Downstream:
+	* - {@link judgeSource}
+	* - `RuleContext.report`
+	*/
+async onTargetFile(target) {
 		const model = await ctx.model();
+		const file = await ctx.src.readFile(target.file);
 		const findings = await judgeSource({
 			logger: ctx.logger,
 			metering: ctx.metering,
@@ -6022,7 +6096,7 @@ const trivialWrapperStackRule = defineRule({
 			outputLanguage: ctx.outputLanguage,
 			prompt: trivialWrapperStackPrompt,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source: file.text
 		});
 		for (const finding of findings) ctx.report({
 			evidence: {
@@ -6094,7 +6168,7 @@ const vacuousFunctionRule = defineRule({
 	* Triggering workflow:
 	*
 	* {@link defineRule}
-	*   -> `SourceTarget.kind === "file"`
+	*   -> `PlannedSourceTarget.kind === "file"`
 	*     -> `onTargetFile`
 	*       -> {@link judgeSource}
 	*
@@ -6107,6 +6181,7 @@ const vacuousFunctionRule = defineRule({
 	*/
 async onTargetFile(target) {
 		const model = await ctx.model();
+		const file = await ctx.src.readFile(target.file);
 		const findings = await judgeSource({
 			logger: ctx.logger,
 			metering: ctx.metering,
@@ -6115,7 +6190,7 @@ async onTargetFile(target) {
 			outputLanguage: ctx.outputLanguage,
 			prompt: vacuousFunctionPrompt,
 			signal: ctx.signal,
-			source: ctx.src.getText(target)
+			source: file.text
 		});
 		for (const finding of findings) ctx.report({
 			evidence: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/plugin-js",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -16,9 +16,9 @@
     "@valibot/to-json-schema": "^1.7.1",
     "apeira": "^0.0.7",
     "valibot": "^1.4.2",
-    "@alint-js/plugin": "0.1.3",
-    "@alint-js/tools-fs": "0.1.3",
-    "@alint-js/core": "0.1.3"
+    "@alint-js/core": "0.1.5",
+    "@alint-js/tools-fs": "0.1.5",
+    "@alint-js/plugin": "0.1.5"
   },
   "scripts": {
     "build": "tsdown",