@shrkcrft/structural-search 0.1.0-alpha.10

package/dist/schema/pattern.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Declarative AST pattern DSL. Patterns describe an AST *shape*; the
+ * matcher walks the tree and emits a match per matching node. There are
+ * deliberately no executable predicates — patterns serialise as plain
+ * JSON, sign cleanly, and never run user JS in the matcher.
+ *
+ * Schema: sharkcraft.structural-pattern/v1.
+ *
+ * Supported kinds in Wave 4 (foundation):
+ *   - CallExpression
+ *   - NewExpression
+ *   - ImportDeclaration
+ *   - ClassDeclaration
+ *   - Decorator
+ *   - Identifier
+ *   - StringLiteral
+ *
+ * Additional kinds (function/method declarations, JSX, conditional types,
+ * etc.) slot in by adding a new variant to `StructuralPattern` plus a
+ * branch in `matchPattern`.
+ */
+export declare const STRUCTURAL_PATTERN_SCHEMA: "sharkcraft.structural-pattern/v1";
+export type StructuralPattern = ICallExpressionPattern | INewExpressionPattern | IImportDeclarationPattern | IClassDeclarationPattern | IDecoratorPattern | IIdentifierPattern | IStringLiteralPattern;
+export interface IPatternEnvelope {
+    schema: typeof STRUCTURAL_PATTERN_SCHEMA;
+    id?: string;
+    title?: string;
+    description?: string;
+    pattern: StructuralPattern;
+}
+export interface IIdentifierPattern {
+    kind: 'Identifier';
+    /** Exact-match name. `*` matches any identifier. */
+    name?: string;
+    /** ECMAScript regex source (without flags). Matched against the identifier text. */
+    nameRegex?: string;
+}
+export interface IStringLiteralPattern {
+    kind: 'StringLiteral';
+    /** Exact match. */
+    text?: string;
+    textRegex?: string;
+}
+export interface ICallExpressionPattern {
+    kind: 'CallExpression';
+    /** Match against the callee identifier name. */
+    callee?: IIdentifierPattern;
+    /** Optional minimum argument count. */
+    minArgs?: number;
+    /** Optional exact argument count. */
+    argCount?: number;
+}
+export interface INewExpressionPattern {
+    kind: 'NewExpression';
+    callee?: IIdentifierPattern;
+}
+export interface IImportDeclarationPattern {
+    kind: 'ImportDeclaration';
+    /** Exact specifier match. */
+    from?: string;
+    fromRegex?: string;
+    /** True → match only side-effect imports `import "x";`. */
+    sideEffectOnly?: boolean;
+    /** Match only when this named import exists. */
+    importedName?: string;
+}
+export interface IClassDeclarationPattern {
+    kind: 'ClassDeclaration';
+    name?: string;
+    nameRegex?: string;
+    /** Require a decorator with this identifier name. */
+    hasDecoratorNamed?: string;
+}
+export interface IDecoratorPattern {
+    kind: 'Decorator';
+    /** Decorator identifier name (e.g. `Controller`). */
+    name?: string;
+    /**
+     * Match only when the decorator is invoked as a call expression
+     * `@Foo(...)` (true) vs a bare identifier `@Foo` (false). Omit to
+     * accept either.
+     */
+    isCall?: boolean;
+}
+//# sourceMappingURL=pattern.d.ts.map

package/dist/schema/pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/schema/pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,yBAAyB,EAAG,kCAA2C,CAAC;AAErF,MAAM,MAAM,iBAAiB,GACzB,sBAAsB,GACtB,qBAAqB,GACrB,yBAAyB,GACzB,wBAAwB,GACxB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,yBAAyB,CAAC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAID,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,YAAY,CAAC;IACnB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,mBAAmB;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,gBAAgB,CAAC;IACvB,gDAAgD;IAChD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/schema/pattern.js

@@ -0,0 +1,22 @@
+/**
+ * Declarative AST pattern DSL. Patterns describe an AST *shape*; the
+ * matcher walks the tree and emits a match per matching node. There are
+ * deliberately no executable predicates — patterns serialise as plain
+ * JSON, sign cleanly, and never run user JS in the matcher.
+ *
+ * Schema: sharkcraft.structural-pattern/v1.
+ *
+ * Supported kinds in Wave 4 (foundation):
+ *   - CallExpression
+ *   - NewExpression
+ *   - ImportDeclaration
+ *   - ClassDeclaration
+ *   - Decorator
+ *   - Identifier
+ *   - StringLiteral
+ *
+ * Additional kinds (function/method declarations, JSX, conditional types,
+ * etc.) slot in by adding a new variant to `StructuralPattern` plus a
+ * branch in `matchPattern`.
+ */
+export const STRUCTURAL_PATTERN_SCHEMA = 'sharkcraft.structural-pattern/v1';

package/dist/schema/rewrite.d.ts

@@ -0,0 +1,58 @@
+import type { StructuralPattern } from './pattern.js';
+export declare const STRUCTURAL_REWRITE_SCHEMA: "sharkcraft.structural-rewrite-plan/v1";
+/**
+ * A rewrite recipe describes what to do at each pattern match.
+ *
+ * Recipes are intentionally narrow — each one targets one shape of
+ * match. Mixing kinds in a single rewrite is not supported; run two
+ * passes instead.
+ *
+ * Supported recipes (Wave 8 foundation):
+ *
+ *   - `replace-identifier-name` — given an `Identifier` pattern,
+ *     replace the matched identifier's text with `to`.
+ *   - `replace-call-callee` — given a `CallExpression` pattern,
+ *     replace the callee identifier text with `to`. Useful for
+ *     `console.log(...)` → `logger.info(...)`.
+ *   - `replace-import-from` — given an `ImportDeclaration` pattern,
+ *     replace the module specifier string with `to`. Useful for
+ *     `from 'lodash'` → `from 'lodash-es'`.
+ */
+export type RewriteRecipe = {
+    kind: 'replace-identifier-name';
+    to: string;
+} | {
+    kind: 'replace-call-callee';
+    to: string;
+} | {
+    kind: 'replace-import-from';
+    to: string;
+};
+export interface IEdit {
+    /** Character offset (inclusive) where the edit starts. */
+    start: number;
+    /** Character offset (exclusive) where the edit ends. */
+    end: number;
+    /** New text. */
+    replacement: string;
+    /** Old text. Provided for human review. */
+    before: string;
+    /** 1-based line number for display. */
+    line: number;
+}
+export interface IFileEdits {
+    /** Project-relative POSIX path. */
+    path: string;
+    /** Edits sorted by `start` ascending. */
+    edits: readonly IEdit[];
+}
+export interface IRewritePlan {
+    schema: typeof STRUCTURAL_REWRITE_SCHEMA;
+    pattern: StructuralPattern;
+    recipe: RewriteRecipe;
+    filesScanned: number;
+    totalEdits: number;
+    files: readonly IFileEdits[];
+    diagnostics: readonly string[];
+}
+//# sourceMappingURL=rewrite.d.ts.map

package/dist/schema/rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite.d.ts","sourceRoot":"","sources":["../../src/schema/rewrite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,eAAO,MAAM,yBAAyB,EAAG,uCAAgD,CAAC;AAE1F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD,MAAM,WAAW,KAAK;IACpB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,SAAS,KAAK,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,yBAAyB,CAAC;IACzC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC"}

package/dist/schema/rewrite.js

@@ -0,0 +1 @@
+export const STRUCTURAL_REWRITE_SCHEMA = 'sharkcraft.structural-rewrite-plan/v1';

package/dist/schema/signed-rewrite.d.ts

@@ -0,0 +1,20 @@
+import type { IRewritePlan } from './rewrite.js';
+export declare const SIGNED_REWRITE_SCHEMA: "sharkcraft.structural-rewrite-plan-signed/v1";
+export interface ISignedRewriteProvenance {
+    /** ISO timestamp of the signing event. */
+    signedAt: string;
+    /** Tool that signed the plan (`shrk search-structural` by default). */
+    signedBy: string;
+    /** SharkCraft / structural-search schema version of the inner plan. */
+    planSchema: string;
+}
+export interface ISignedRewritePlan {
+    schema: typeof SIGNED_REWRITE_SCHEMA;
+    /** HMAC-SHA256 of the canonical-JSON inner plan + provenance, hex. */
+    hmac: string;
+    /** Algorithm identifier; always `sha256` for v1. */
+    algo: 'sha256';
+    provenance: ISignedRewriteProvenance;
+    plan: IRewritePlan;
+}
+//# sourceMappingURL=signed-rewrite.d.ts.map

package/dist/schema/signed-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-rewrite.d.ts","sourceRoot":"","sources":["../../src/schema/signed-rewrite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,eAAO,MAAM,qBAAqB,EAAG,8CAAuD,CAAC;AAE7F,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IACrC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,wBAAwB,CAAC;IACrC,IAAI,EAAE,YAAY,CAAC;CACpB"}

package/dist/schema/signed-rewrite.js

@@ -0,0 +1 @@
+export const SIGNED_REWRITE_SCHEMA = 'sharkcraft.structural-rewrite-plan-signed/v1';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@shrkcrft/structural-search",
+  "version": "0.1.0-alpha.10",
+  "description": "SharkCraft structural search: declarative AST patterns for TypeScript codebases. Find call sites, decorators, classes, imports — preview-only by default; rewrite mode lands in Wave 8.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/structural-search"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "structural-search",
+    "ast",
+    "typescript",
+    "codemod"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.10",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}