@goodbones/ast-grep 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Data Quail
+
+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/build/dts/index.d.ts

@@ -0,0 +1,2 @@
+export { astGrepMatcher, type AstGrepOptions, TYPESCRIPT_LANGUAGES } from "./matcher.js";
+//# sourceMappingURL=index.d.ts.map

package/build/dts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/build/dts/matcher.d.ts

@@ -0,0 +1,8 @@
+import { Lang } from "@ast-grep/napi";
+import type { SyntaxMatcher } from "@goodbones/core";
+export type AstGrepOptions = {
+    readonly languages: Readonly<Record<string, Lang>>;
+};
+export declare const TYPESCRIPT_LANGUAGES: Readonly<Record<string, Lang>>;
+export declare const astGrepMatcher: (options?: AstGrepOptions) => SyntaxMatcher;
+//# sourceMappingURL=matcher.d.ts.map

package/build/dts/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/matcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAsB,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAyB,aAAa,EAAc,MAAM,iBAAiB,CAAC;AAcxF,MAAM,MAAM,cAAc,GAAG;IAE3B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;CACpD,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAS/D,CAAC;AAkJF,eAAO,MAAM,cAAc,aAChB,cAAc,KACtB,aAuBD,CAAC"}

package/build/esm/index.js

@@ -0,0 +1,7 @@
+// The ast-grep syntax matcher, as one package: a campaign's `syntax` term
+// evaluated through `@ast-grep/napi`, behind the core's `SyntaxMatcher` port.
+// A host composes it into a language pack (`typescriptLanguage({ syntax:
+// astGrepMatcher() })`); the pack never names it, and the core never imports
+// it. A second engine over another tree is a second package shaped like this.
+export { astGrepMatcher, TYPESCRIPT_LANGUAGES } from "./matcher.js";
+//# sourceMappingURL=index.js.map

package/build/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,yEAAyE;AACzE,6EAA6E;AAC7E,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAuB,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/build/esm/matcher.js

@@ -0,0 +1,165 @@
+import { Lang, parse } from "@ast-grep/napi";
+export const TYPESCRIPT_LANGUAGES = {
+    ".ts": Lang.TypeScript,
+    ".mts": Lang.TypeScript,
+    ".cts": Lang.TypeScript,
+    ".tsx": Lang.Tsx,
+    ".js": Lang.JavaScript,
+    ".mjs": Lang.JavaScript,
+    ".cjs": Lang.JavaScript,
+    ".jsx": Lang.JavaScript,
+};
+// The tree-sitter kinds that declare a name, and where the name sits. A
+// class, function, method, variable declarator, type alias, interface, enum
+// or module carries it in its `name` field.
+const DECLARATION_KINDS = new Set([
+    "class_declaration",
+    "abstract_class_declaration",
+    "function_declaration",
+    "generator_function_declaration",
+    "method_definition",
+    "method_signature",
+    "variable_declarator",
+    "type_alias_declaration",
+    "interface_declaration",
+    "enum_declaration",
+    "internal_module",
+    "module",
+]);
+// `kind()` is typed as a union over the grammar's static map; what it holds
+// at runtime is the kind's name.
+const kindOf = (node) => String(node.kind());
+const nameOf = (node) => {
+    try {
+        const name = node.field("name");
+        return name === null ? null : name.text();
+    }
+    catch {
+        return null;
+    }
+};
+// The match itself when it is a named declaration, else the nearest ancestor
+// that is one; `null` at the top level of the file.
+const anchorOf = (node) => {
+    if (DECLARATION_KINDS.has(kindOf(node))) {
+        const own = nameOf(node);
+        if (own !== null)
+            return own;
+    }
+    for (const ancestor of node.ancestors()) {
+        if (!DECLARATION_KINDS.has(kindOf(ancestor)))
+            continue;
+        const name = nameOf(ancestor);
+        if (name !== null)
+            return name;
+    }
+    return null;
+};
+// A metavariable of the rule: `$NAME` in a pattern, or a key of `constraints`.
+// ast-grep reports captures by name on request rather than as a map, so the
+// names are read off the rule's text and asked for one by one.
+const METAVARIABLE = /\$([A-Z_][A-Z0-9_]*)/g;
+const metavariablesOf = (rule) => {
+    const found = new Set();
+    for (const match of JSON.stringify(rule).matchAll(METAVARIABLE)) {
+        if (match[1] !== undefined)
+            found.add(match[1]);
+    }
+    return [...found];
+};
+const capturesOf = (node, names) => {
+    const captures = new Map();
+    for (const name of names) {
+        const single = node.getMatch(name);
+        if (single !== null) {
+            captures.set(name, single.text());
+            continue;
+        }
+        const several = node.getMultipleMatches(name);
+        if (several.length > 0)
+            captures.set(name, several.map((one) => one.text()).join(""));
+    }
+    return captures;
+};
+const matchOf = (node, names) => {
+    const range = node.range();
+    return {
+        text: node.text(),
+        captures: capturesOf(node, names),
+        range: {
+            start: { line: range.start.line, column: range.start.column },
+            end: { line: range.end.line, column: range.end.column },
+        },
+        anchor: anchorOf(node),
+    };
+};
+const declarationsOf = (root) => {
+    const found = [];
+    for (const kind of DECLARATION_KINDS) {
+        let nodes;
+        try {
+            nodes = root.findAll({ rule: { kind } });
+        }
+        catch {
+            continue;
+        }
+        for (const node of nodes) {
+            const name = nameOf(node);
+            if (name === null)
+                continue;
+            const range = node.range();
+            found.push({
+                name,
+                start: { line: range.start.line, column: range.start.column },
+                end: { line: range.end.line, column: range.end.column },
+            });
+        }
+    }
+    return found;
+};
+const before = (left, right) => left.line < right.line || (left.line === right.line && left.column <= right.column);
+const contains = (one, at) => before(one.start, at) && before(at, one.end);
+// The innermost declaration containing the position: of those that do, the
+// one that starts last.
+const anchorAtOf = (declared, at) => {
+    let innermost = null;
+    for (const one of declared) {
+        if (!contains(one, at))
+            continue;
+        if (innermost === null || before(innermost.start, one.start))
+            innermost = one;
+    }
+    return innermost === null ? null : innermost.name;
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const extensionOf = (file) => {
+    const base = file.slice(file.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot === -1 ? "" : base.slice(dot);
+};
+export const astGrepMatcher = (options = { languages: TYPESCRIPT_LANGUAGES }) => ({
+    parse: (file, text) => {
+        const language = options.languages[extensionOf(file)];
+        if (language === undefined)
+            return null;
+        const root = parse(language, text).root();
+        let declared = null;
+        return {
+            anchorAt: (position) => {
+                declared ??= declarationsOf(root);
+                return anchorAtOf(declared, position);
+            },
+            findAll: (rule) => {
+                if (!isRecord(rule)) {
+                    throw new Error(`a syntax rule is an object of ast-grep rule keys, not ${typeof rule}`);
+                }
+                // The engine refuses a rule it cannot read with its own sentence; it
+                // is thrown as-is, since the probe check is what turns it into a
+                // load failure that names the campaign.
+                const names = metavariablesOf(rule);
+                return root.findAll({ rule }).map((node) => matchOf(node, names));
+            },
+        };
+    },
+});
+//# sourceMappingURL=matcher.js.map

package/build/esm/matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.js","sourceRoot":"","sources":["../../src/matcher.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@goodbones/ast-grep",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "The ast-grep syntax matcher for @goodbones/core: a campaign's `syntax` term, evaluated through @ast-grep/napi behind the core's SyntaxMatcher port.",
+  "author": "zacharyweidenbach",
+  "keywords": [
+    "architecture",
+    "lint",
+    "ast-grep",
+    "campaigns",
+    "monorepo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dataquail/goodbones.git",
+    "directory": "packages/ast-grep"
+  },
+  "homepage": "https://dataquail.github.io/goodbones",
+  "bugs": {
+    "url": "https://github.com/dataquail/goodbones/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/dts/index.d.ts",
+      "default": "./build/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./build/dts/index.d.ts",
+  "files": [
+    "build/dts",
+    "build/esm",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "dependencies": {
+    "@ast-grep/napi": "^0.45.3",
+    "@goodbones/core": "0.1.0-beta.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.4"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "check": "tsc -b tsconfig.json",
+    "clean": "rm -rf build .tsbuildinfo",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// The ast-grep syntax matcher, as one package: a campaign's `syntax` term
+// evaluated through `@ast-grep/napi`, behind the core's `SyntaxMatcher` port.
+// A host composes it into a language pack (`typescriptLanguage({ syntax:
+// astGrepMatcher() })`); the pack never names it, and the core never imports
+// it. A second engine over another tree is a second package shaped like this.
+export { astGrepMatcher, type AstGrepOptions, TYPESCRIPT_LANGUAGES } from "./matcher.js";

package/src/matcher.ts

@@ -0,0 +1,201 @@
+import { Lang, parse, type SgNode } from "@ast-grep/napi";
+import type { Position, SyntaxMatch, SyntaxMatcher, SyntaxTree } from "@goodbones/core";
+
+// The core's `SyntaxMatcher` port over ast-grep. A campaign's `syntax` term is
+// an ast-grep rule object, passed through as the `rule` of a `NapiConfig`;
+// each node it matches becomes a `SyntaxMatch` with its text, what every
+// metavariable captured, its range, and the nearest enclosing named
+// declaration as its anchor. Nothing here knows about imports: narrowing a
+// capture by what it is bound to is the core's, against the file's facts.
+//
+// The `kind` names a rule may use are tree-sitter's for the grammar ast-grep
+// parses the file with (`class_declaration`, `call_expression`), and so is
+// the anchor's notion of a declaration below. A matcher over another tree
+// would ship its own mapping.
+
+export type AstGrepOptions = {
+  // File extension (with the dot) to ast-grep language id.
+  readonly languages: Readonly<Record<string, Lang>>;
+};
+
+export const TYPESCRIPT_LANGUAGES: Readonly<Record<string, Lang>> = {
+  ".ts": Lang.TypeScript,
+  ".mts": Lang.TypeScript,
+  ".cts": Lang.TypeScript,
+  ".tsx": Lang.Tsx,
+  ".js": Lang.JavaScript,
+  ".mjs": Lang.JavaScript,
+  ".cjs": Lang.JavaScript,
+  ".jsx": Lang.JavaScript,
+};
+
+// The tree-sitter kinds that declare a name, and where the name sits. A
+// class, function, method, variable declarator, type alias, interface, enum
+// or module carries it in its `name` field.
+const DECLARATION_KINDS: ReadonlySet<string> = new Set([
+  "class_declaration",
+  "abstract_class_declaration",
+  "function_declaration",
+  "generator_function_declaration",
+  "method_definition",
+  "method_signature",
+  "variable_declarator",
+  "type_alias_declaration",
+  "interface_declaration",
+  "enum_declaration",
+  "internal_module",
+  "module",
+]);
+
+// `kind()` is typed as a union over the grammar's static map; what it holds
+// at runtime is the kind's name.
+const kindOf = (node: SgNode): string => String(node.kind());
+
+const nameOf = (node: SgNode): string | null => {
+  try {
+    const name = (node as SgNode & { field: (name: string) => SgNode | null }).field("name");
+    return name === null ? null : name.text();
+  } catch {
+    return null;
+  }
+};
+
+// The match itself when it is a named declaration, else the nearest ancestor
+// that is one; `null` at the top level of the file.
+const anchorOf = (node: SgNode): string | null => {
+  if (DECLARATION_KINDS.has(kindOf(node))) {
+    const own = nameOf(node);
+    if (own !== null) return own;
+  }
+  for (const ancestor of node.ancestors()) {
+    if (!DECLARATION_KINDS.has(kindOf(ancestor))) continue;
+    const name = nameOf(ancestor);
+    if (name !== null) return name;
+  }
+  return null;
+};
+
+// A metavariable of the rule: `$NAME` in a pattern, or a key of `constraints`.
+// ast-grep reports captures by name on request rather than as a map, so the
+// names are read off the rule's text and asked for one by one.
+const METAVARIABLE = /\$([A-Z_][A-Z0-9_]*)/g;
+
+const metavariablesOf = (rule: unknown): ReadonlyArray<string> => {
+  const found = new Set<string>();
+  for (const match of JSON.stringify(rule).matchAll(METAVARIABLE)) {
+    if (match[1] !== undefined) found.add(match[1]);
+  }
+  return [...found];
+};
+
+const capturesOf = (node: SgNode, names: ReadonlyArray<string>): ReadonlyMap<string, string> => {
+  const captures = new Map<string, string>();
+  for (const name of names) {
+    const single = node.getMatch(name);
+    if (single !== null) {
+      captures.set(name, single.text());
+      continue;
+    }
+    const several = node.getMultipleMatches(name);
+    if (several.length > 0) captures.set(name, several.map((one) => one.text()).join(""));
+  }
+  return captures;
+};
+
+const matchOf = (node: SgNode, names: ReadonlyArray<string>): SyntaxMatch => {
+  const range = node.range();
+  return {
+    text: node.text(),
+    captures: capturesOf(node, names),
+    range: {
+      start: { line: range.start.line, column: range.start.column },
+      end: { line: range.end.line, column: range.end.column },
+    },
+    anchor: anchorOf(node),
+  };
+};
+
+// Every named declaration in the tree, innermost last, for anchoring a
+// position. Found once per tree; a kind the grammar does not have (a type
+// alias in JavaScript) is skipped.
+type Declared = {
+  readonly name: string;
+  readonly start: Position;
+  readonly end: Position;
+};
+
+const declarationsOf = (root: SgNode): ReadonlyArray<Declared> => {
+  const found: Array<Declared> = [];
+  for (const kind of DECLARATION_KINDS) {
+    let nodes: ReadonlyArray<SgNode>;
+    try {
+      nodes = root.findAll({ rule: { kind } });
+    } catch {
+      continue;
+    }
+    for (const node of nodes) {
+      const name = nameOf(node);
+      if (name === null) continue;
+      const range = node.range();
+      found.push({
+        name,
+        start: { line: range.start.line, column: range.start.column },
+        end: { line: range.end.line, column: range.end.column },
+      });
+    }
+  }
+  return found;
+};
+
+const before = (left: Position, right: Position): boolean =>
+  left.line < right.line || (left.line === right.line && left.column <= right.column);
+
+const contains = (one: Declared, at: Position): boolean =>
+  before(one.start, at) && before(at, one.end);
+
+// The innermost declaration containing the position: of those that do, the
+// one that starts last.
+const anchorAtOf = (declared: ReadonlyArray<Declared>, at: Position): string | null => {
+  let innermost: Declared | null = null;
+  for (const one of declared) {
+    if (!contains(one, at)) continue;
+    if (innermost === null || before(innermost.start, one.start)) innermost = one;
+  }
+  return innermost === null ? null : innermost.name;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const extensionOf = (file: string): string => {
+  const base = file.slice(file.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot === -1 ? "" : base.slice(dot);
+};
+
+export const astGrepMatcher = (
+  options: AstGrepOptions = { languages: TYPESCRIPT_LANGUAGES },
+): SyntaxMatcher => ({
+  parse: (file, text): SyntaxTree | null => {
+    const language = options.languages[extensionOf(file)];
+    if (language === undefined) return null;
+    const root = parse(language, text).root();
+    let declared: ReadonlyArray<Declared> | null = null;
+    return {
+      anchorAt: (position) => {
+        declared ??= declarationsOf(root);
+        return anchorAtOf(declared, position);
+      },
+      findAll: (rule) => {
+        if (!isRecord(rule)) {
+          throw new Error(`a syntax rule is an object of ast-grep rule keys, not ${typeof rule}`);
+        }
+        // The engine refuses a rule it cannot read with its own sentence; it
+        // is thrown as-is, since the probe check is what turns it into a
+        // load failure that names the campaign.
+        const names = metavariablesOf(rule);
+        return root.findAll({ rule }).map((node) => matchOf(node, names));
+      },
+    };
+  },
+});