@alint-js/languages 0.3.2 → 0.5.0

package/README.md

@@ -59,6 +59,36 @@ plugin_languages = "./node_modules/@alint-js/languages"
 The directory lock records physical identity, so upgrading the package re-locks it. Re-run
 `alint plugin install` when it says the target changed.
 
+## Add a language
+
+This package reads the prebuilt grammars in `tree-sitter-wasms`. That dependency supplies 36
+grammars, and this package uses three of them (by the time this is written). A new language needs a query, not a grammar. The
+query maps the node names of the grammar to the six captures that `extract.ts` reads.
+
+To add a language, do these steps:
+
+1. Add the file name of the grammar to `GRAMMAR` in `src/grammar.ts`.
+2. Add the query to `QUERIES` in `src/queries.ts`.
+3. Add a case to `isExported` in `src/extract.ts`.
+4. Add a `LanguageDefinition` to `src/index.ts`.
+5. Add the new language to `languagesPlugin` in the same file.
+6. Add a test for the new language to `src/extract.test.ts`.
+
+Note: `LanguageId` comes from the keys of `GRAMMAR`. After step 1, the code does not compile until
+you complete step 2 and step 3. The compiler gives no error for step 4, step 5, or step 6.
+
+To find the node names of a grammar, read the `grammar.js` file of that tree-sitter parser.
+
+CAUTION: Make sure that the grammar uses these three node names. If the grammar uses other names,
+the code still compiles and `FunctionInfo` is wrong:
+
+- `block` is the node type of a branch or a loop (`holdsBlock` in `src/extract.ts`).
+- `body` is the field name for the body of a function (`bodyStatements`).
+- `name` is the field name for the name of a function (`withOwnName`).
+
+Go, Python, and Rust use these three names. Other grammars use other names. For example, TypeScript
+calls the block `statement_block`.
+
 ## When to use
 
 - Your project has Go, Python or Rust files and you want rules to see functions in them rather than

package/dist/index.d.mts

@@ -747,7 +747,7 @@ interface Config<TIssue extends BaseIssue<unknown>> {
   readonly abortPipeEarly?: boolean | undefined;
 }
 //#endregion
-//#region ../core/dist/types-deBCDA4_.d.mts
+//#region ../core/dist/types-BK5CADYK.d.mts
 //#region src/config/types.d.ts
 type ModelSize = 'large' | 'medium' | 'small';
 interface RunnerCacheConfig {
@@ -974,8 +974,10 @@ interface RuleInferenceUsageRecord {
   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.
+ * - `'any'` — every language except `plaintext`, and never a failure. Plain text is what a file
+ *   falls back to when no language claims it, so a rule asking for any language is asking for a
+ *   real one. Rules that work from `FunctionInfo` alone want this: install another language pack
+ *   and they cover it too, unchanged.
  * - 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:`
@@ -1013,11 +1015,12 @@ type Target = DirectoryTarget | PlannedSourceTarget | ProjectTarget;
 //#endregion
 //#region src/extract.d.ts
 /**
- * One file target carrying every call site, then one function target per function, each with the
- * `FunctionInfo` a consumer would otherwise need its own parser to work out.
+ * One file target holding every call site, then one function target per function. Each function
+ * target carries a `FunctionInfo`, so a consumer can fingerprint or classify it without parsing
+ * anything itself.
  *
- * The language comes from the file rather than a second argument, because every target carries that
- * same file and the two could then disagree. Pass the file through `withLanguage` first.
+ * The language is read off the file rather than passed in as an argument. Every target carries that
+ * same file, so an argument could only ever contradict it. Stamp the file with `withLanguage` first.
  */
 declare function extractTargets(file: SourceFile): Promise<SourceTarget[]>;
 //#endregion

package/dist/index.mjs

@@ -93,11 +93,12 @@ const QUERIES = {
 //#region src/extract.ts
 const queries = /* @__PURE__ */ new Map();
 /**
-* One file target carrying every call site, then one function target per function, each with the
-* `FunctionInfo` a consumer would otherwise need its own parser to work out.
+* One file target holding every call site, then one function target per function. Each function
+* target carries a `FunctionInfo`, so a consumer can fingerprint or classify it without parsing
+* anything itself.
 *
-* The language comes from the file rather than a second argument, because every target carries that
-* same file and the two could then disagree. Pass the file through `withLanguage` first.
+* The language is read off the file rather than passed in as an argument. Every target carries that
+* same file, so an argument could only ever contradict it. Stamp the file with `withLanguage` first.
 */
 async function extractTargets(file) {
 	if (!isLanguageId(file.language)) throw new Error(`Language "${file.language}" is not provided by @alint-js/languages.`);
@@ -216,7 +217,7 @@ function holdsBlock(node) {
 	}
 	return false;
 }
-/** Reachable from outside its file. Go says it with a capital, Python with the absence of a leading underscore, Rust with `pub`. */
+/** Reachable from outside its file: a capital in Go, no leading underscore in Python, `pub` in Rust. */
 function isExported(node, language, name) {
 	switch (language) {
 		case "go": return /^[A-Z]/.test(name);
@@ -231,7 +232,7 @@ function rangeOf(node) {
 		start: node.startIndex
 	};
 }
-/** Rebases the ranges inside `outer` onto the function's own `text`, which is where `FunctionInfo` says they point. */
+/** Turns absolute file offsets into offsets within the function's own `text`, as `FunctionInfo` documents. */
 function rangesInside(ranges, outer) {
 	return ranges.filter((range) => range.start >= outer.start && range.end <= outer.end).map((range) => ({
 		end: range.end - outer.start,
@@ -241,10 +242,11 @@ function rangesInside(ranges, outer) {
 /**
 * Adds the function's own name to its renameable identifiers.
 *
-* This only has anything to add for a Go method, whose name is a `field_identifier` rather than an
-* `identifier`. The Go query leaves `field_identifier` out on purpose, because reading a struct
-* field is not renameable, but a method naming itself is. Every other name the queries capture is
-* already an `@identifier`, so the dedupe by start offset drops the second copy.
+* In practice this only matters for Go methods, whose name is a `field_identifier`. The Go query
+* skips `field_identifier` on purpose: a consumer that replaces renameable names would otherwise
+* make `entry.name` and `entry.size` look identical. A method's own name is safe to replace. Every
+* other name the queries capture is already an `@identifier`, so the dedupe by start offset drops
+* the duplicate.
 */
 function withOwnName(ranges, nameNode, outer) {
 	if (nameNode === null) return ranges;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/languages",
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -13,15 +13,15 @@
     "dist"
   ],
   "peerDependencies": {
-    "@alint-js/core": "0.3.2"
+    "@alint-js/core": "0.5.0"
   },
   "dependencies": {
     "tree-sitter-wasms": "^0.1.13",
     "web-tree-sitter": "^0.24.7"
   },
   "devDependencies": {
-    "@alint-js/core": "0.3.2",
-    "@alint-js/plugin": "0.3.2"
+    "@alint-js/core": "0.5.0",
+    "@alint-js/plugin": "0.5.0"
   },
   "scripts": {
     "build": "tsdown",