@alint-js/core

公共 SDK 运行引擎 alint。 。 。 .

它会做什么

这个软件包提供了插件,规则,语言处理器,嵌入工具和代理适配器所使用的核心SDK并运行引擎API:

• definePlugin 财务报告和审定财务报表 defineRule
• runAlint
• 规则登记和统一配置正常化
• 源运行时帮助
• 内建的 JavaScript 源代码提取, 并附加其它语言支持
• 按规模和能力分列的模型分辨率
• 诊断和进步有效载荷类型
• 框架中立代理合同 @alint-js/core/agent
• 工具调用结构输出 @alint-js/core/structured-output
• 为 SDK 高级消费者配置 DSL和类型

如何使用

写一条规则 :

import { defineRule } from '@alint-js/core'

export const rule = defineRule({
  create: ctx => ({
    async onTargetFile(target) {
      const model = await ctx.model({ size: 'small' })
      const file = await ctx.src.readFile(target.file)

      ctx.report({
        filePath: target.file.path,
        loc: target.loc,
        message: `reviewed ${file.lines.length} lines with ${model.id}`,
      })
    },
  }),
})

来源和项目规则都得到紧凑的说明。 源处理器应该通过 target.file 改为 ctx.src.readFile() 因此核心可以检测出规划以来的变化. 仅在需要时读取源 :

import { defineRule } from '@alint-js/core'

export const projectRule = defineRule({
  create: ctx => ({
    async onTargetProject(project) {
      for (const entry of project.files) {
        const file = await ctx.src.readFile(entry.path)
        if (file.text.includes('deprecated-api'))
          ctx.report({ filePath: entry.path, message: 'deprecated API used' })
      }
    },
  }),
})

PlannedSourceTarget, (中文(简体) ), ProjectFileEntry,以及 ProjectTargetEntry 故意省去源文本. 呼吁 ctx.src.readFile() 是明确和插件拥有的,所以规则控制了源文件 并保留了多久。 缓存命中不引用处理器,因此不 执行时读取.

将代理合同用于工具使用规则:

import { requireAgent } from '@alint-js/core/agent'

const agent = requireAgent(ctx)

询问一个验证的、 键入结果的模型 @alint-js/core/structured-output它迫使 用于调用一个单一报告工具的模型,该工具的参数与 valibot 计划相符,验证 并反馈到模型中:

import { generateStructured } from '@alint-js/core/structured-output'
import { array, description, object, pipe } from 'valibot'

const responseSchema = pipe(
  object({ findings: array(findingSchema) }),
  description('Report findings for this file.'),
)

const { findings } = await generateStructured({
  createMessages: retryFeedback => [
    { content: prompt, role: 'system' },
    ...(retryFeedback ? [{ content: retryFeedback, role: 'user' as const }] : []),
    { content: numberedSource, role: 'user' },
  ],
  logger: ctx.logger,
  metering: ctx.metering,
  model: await ctx.model(),
  operation: 'my-rule-judge',
  schema: responseSchema,
})

报告工具的名称 reportFindings 默认(toolName 超过它)及其 描述默认到 schema 的 valibot description(...)。 。 。 . toolParametersFromSchema, (中文(简体) ), formatSourceWithLineNumbers,以及 formatOutputLanguageInstruction 为呼叫者输出 建立自己的工具 或提示。 使用 ctx.agent 当模型需要时 在回答前用工具来探索,因为强制工具呼叫是一发一发,而不是循环.

语文

核心解析 JavaScript 和 TypeScript. 其它东西都用插件注册 所以规则是 哪些语言可以读取,核心决定如何交接:

defineRule({
  create: () => ({ onTargetFunction: (target) => { /* ... */ } }),
  languages: 'any',
})

'any' 不包括 plaintext 这是故意的 当一个文件没有语言时, 普通文本会回到什么位置 请求其扩展,所以要求使用语言的规则,否则会被解析出文本. 当这种情况发生时,运行报告 alint/unregistered-language 每延长一次——警告 默认, 可配置通过 linterOptions.reportUnregisteredLanguages。 。 。 .

宣布名单是更严格的选择。 当用户未安装包时, 运行失败 它提供了其中之一, 而不是让规则 匹配无 和看起来像一个通过.

一个插件通过描述如何将文件变成目标来注册语言 :

definePlugin({
  languages: {
    zig: {
      extensions: ['.zig'],
      extract: file => [/* SourceTarget[] */],
      name: 'zig',
    },
  },
})

Ids是编辑器使用的识别器—— go, (中文(简体) ), python, (中文(简体) ), typescript, (中文(简体) ), plaintext。注册失败 在重复名称或扩展名上,因此两个插件永远不能要求同一语言.

来个 FunctionInfo 下级 metadata.function 和文件的调用站点 下级 metadata.calls 在文件目标。 这两个键让规则读懂任何语言 没有自己的分析.

@alint-js/languages 提供去,Python和Rust这样.

要解析一个文件, 运行未被要求擦入, 例如, 当构建全工作空间索引时, 使用 ctx.src.extract(path)。它解决了文件本身的配置和语言,并且不返回一个 文件配置忽略而非丢弃.

何时使用

• 你在写一个 alint 插件或规则包.
• 您正在添加语言处理器或源提取器 .
• 您正在嵌入 alint 在另一个工具.
• 您正在执行一个 AgentAdapter。 。 。 .
• 您需要全项目分析, 能够消耗紧凑的描述符 和懒散地装入源 .

不使用时

• 使用 @alint-js/cli 用于命令行和普通 alint.config.* 文档.
• 使用 @alint-js/config 仅用于设置 TOML、配置加载和配置文件工具.
• 需要持续存储器数据库的插件应建立和注入该数据库. 不保留每个 SourceFile 返回时间 ctx.src.readFile() 以代替一个.

内存边界

alint 同步源规划读取并解析工作。 计划释放丰富的提取器 值; 队列任务不会保留源文本。 无法约束 插件代码后保留源文件 ctx.src.readFile() 返回.

由相同者撰写的有效缓存 alint 版本仍然从一个单一的JSON文档读取. 因此,巨大的缓存可能会耗尽现有的内存.

每次缓存规则任务完成后, alint 在释放缓存检查点前写入该检查点 排程档. 每个检查点在解剖上取代了单质缓存文件. 运行中断 因此,可以重新使用已经具有持久性的每一种结果,但大型缓存可引起 运行时有大量磁盘写入, 并丢失了许多缓存 。 缓存点击,跳出任务,失败任务, 并且选择退出缓存的规则不会添加检查站的文字。 检查点或最后缓存写入 错误是致命的,并导致运行失败.