@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/structural-search/references/diagnostics.md

@@ -0,0 +1,307 @@
+# Structural-search diagnostics
+
+Diagnose the matcher before changing the repository. A zero-result query may mean “no matching
+syntax,” but it may also mean the wrong parser, an invalid pattern root, shell expansion, ignored
+files, unsupported syntax, or a traversal boundary.
+
+## Diagnostic order
+
+Use this order because each step removes one class of uncertainty:
+
+1. verify executable identity and version;
+2. verify the target path exists and contains a known example;
+3. verify the selected language;
+4. verify shell quoting;
+5. run on one minimal positive sample;
+6. inspect how the pattern parses;
+7. simplify to a larger stable node;
+8. add captures and relations one at a time;
+9. inspect ignores and globs;
+10. expand to the real target only after the sample works.
+
+Do not debug a repository-wide scan while the same query fails on a ten-line sample.
+
+## Executable confusion
+
+Symptom:
+
+- `sg` exists, but flags are rejected or output is unrelated to source parsing.
+
+Check:
+
+```sh
+command -v sg
+sg --version 2>&1
+```
+
+Proceed only if the version output identifies ast-grep. Otherwise leave `sg` untouched and use the
+validated `ast-grep` binary, a labeled `rg` fallback, or a blocker.
+
+## Shell expansion
+
+Symptom:
+
+- a pattern containing `$NAME` becomes empty, returns surprising results, or differs between an
+  interactive shell and a script.
+
+Cause:
+
+- double quotes or an unquoted argument allowed the shell to expand the metavariable.
+
+Use:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern 'console.log($$$ARGUMENTS)' src
+```
+
+Avoid dynamically building command strings. Pass each pattern, path, and option as a distinct
+argument.
+
+## Known source exists, but zero matches
+
+### Wrong language
+
+Check the project metadata and actual file. `.h`, templates, embedded code, Vue/Svelte-like files,
+and nonstandard extensions are especially ambiguous. Use an explicit language and a minimal file
+with the same syntax version.
+
+### Pattern is not valid standalone code
+
+A fragment such as a class member, decorator attachment, list element, or partial control-flow form
+may need surrounding context. Move to a YAML pattern object with valid context and select the
+intended node.
+
+### Pattern root differs from target root
+
+The parser may treat the snippet as a larger or smaller node than expected. If the installed CLI
+supports pattern debug output, inspect it:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run \
+  --lang TypeScript \
+  --pattern '$OBJECT.$METHOD($$$ARGUMENTS)' \
+  --debug-query=pattern \
+  src/example.ts
+```
+
+Confirm this option first with `run --help`. If unavailable, simplify the pattern and use a known
+source file to infer the root.
+
+### Reused captures over-constrain
+
+`$VALUE === $VALUE` excludes comparisons whose two source expressions differ. Rename captures when
+equality was not intended:
+
+```text
+$LEFT === $RIGHT
+```
+
+### Sequence capture is in the wrong grammar position
+
+`$$$ITEMS` represents a sequence only where the grammar admits one. Move it to an argument list,
+statement body, import list, array, parameter list, or another actual repeated-child position.
+
+### Traversal stops too early
+
+An ancestor or descendant relation may inspect only a near neighbor unless `stopBy` is set. Add an
+explicit traversal boundary supported by the installed rule schema, then test both immediate and
+distant nesting.
+
+### Files were ignored
+
+Check:
+
+- `.gitignore` and tool-specific ignores;
+- rule-level `files` and `ignores`;
+- explicit globs;
+- current working directory;
+- symlink behavior;
+- generated/vendor exclusions added by the operator.
+
+Do not disable all ignores globally as a first reaction. Target one known path explicitly.
+
+## Too many matches
+
+Reduce false positives in this order:
+
+1. anchor more fixed syntax in `pattern`;
+2. use an observed `kind`;
+3. constrain a capture;
+4. add a required ancestor/descendant relation;
+5. exclude a syntax alternative with `not`;
+6. narrow file paths and language globs;
+7. add a bounded regex to an already structural candidate.
+
+Avoid starting with a repository-wide regex rule. It gives the parser little work to do and may be
+slower than `rg`.
+
+## YAML parse or schema errors
+
+Check:
+
+- spaces rather than tabs;
+- quoting around strings containing `:`, `{`, `}`, `#`, or leading special characters;
+- correct nesting under `rule`;
+- one top-level `id` and `language`;
+- valid severity for the installed version;
+- capture names in `constraints`, messages, transforms, and fixes;
+- installed support for experimental transform/rewriter fields;
+- whether multiple documents require YAML separators.
+
+Keep pattern strings quoted when YAML could interpret punctuation:
+
+```yaml
+rule:
+  pattern: "console.log($$$ARGUMENTS)"
+```
+
+For multiline code, use a block scalar:
+
+```yaml
+rule:
+  pattern: |
+    if ($CONDITION) {
+      $$$BODY
+    }
+```
+
+## Rule matches the relation, but not the intended node
+
+Composite children are evaluated against one candidate node. If the policy says a function
+contains two different constructs, make the function the candidate and use two `has` relations.
+Do not assume one `has` containing `all` distributes those children over different descendants.
+
+Likewise, `inside` reports the inner candidate, not necessarily the enclosing function. Reverse the
+candidate/relationship arrangement when the diagnostic should highlight the outer node.
+
+## Regex surprises
+
+Within a structural rule, regex generally examines the text of the current node or capture:
+
+- anchor it if full-node matching is intended;
+- combine it with `kind` or `pattern`;
+- remember that comments/trivia may or may not be part of the selected node text;
+- do not infer identifier binding from spelling;
+- use `rg` instead when raw text is the actual requirement.
+
+## Unsupported semantic question
+
+The following cannot be proven by syntax shape alone:
+
+- whether two identifiers resolve to the same declaration;
+- the inferred or runtime type of a receiver;
+- import resolution and re-export identity;
+- data flow from source to sink;
+- reachability and dead code;
+- side effects or purity;
+- whether a promise is eventually awaited through another abstraction;
+- macro expansion or preprocessor behavior;
+- behavioral equivalence of a rewrite.
+
+Use a compiler, language server, type-aware linter, security analyzer, or project tests. A
+structural query can generate candidates for those tools but cannot replace them.
+
+## Slow scan
+
+First verify the task truly needs structure. If the target is literal text, use `rg`.
+
+For structural scans:
+
+- narrow roots;
+- exclude dependency, build, cache, generated, and vendor trees;
+- select one language;
+- start with `pattern` or `kind`;
+- apply regex only after candidate reduction;
+- split unrelated alternatives into separate measurable rules;
+- avoid deep `stopBy: end` traversal when an intermediate ancestor can bound it;
+- record timing only after a warm-up if performance itself is being evaluated.
+
+Do not trade correctness for an undocumented file omission.
+
+## Parse errors in some files
+
+Possible causes:
+
+- the project uses newer syntax than the bundled grammar;
+- an extension maps to the wrong language;
+- a file is a template or generated hybrid;
+- the source is incomplete or intentionally invalid;
+- preprocessing is required before parsing.
+
+Identify exact failing files. Do not report full-repository coverage if some in-scope files failed to
+parse. Options are:
+
+- upgrade the explicitly authorized project/tool dependency;
+- use a project-specific parser or codemod;
+- separate supported and unsupported path sets in the report;
+- use textual candidate search with an explicit limitation;
+- stop the rewrite.
+
+## Unexpected rewrite output
+
+Stop applying. Inspect:
+
+```sh
+git status --short
+git diff --check
+git diff --name-only
+git diff -- path/to/unexpected-file
+```
+
+Common causes:
+
+- greedy sequence capture consumed a larger list than expected;
+- the replacement omitted a capture;
+- the match root included punctuation or comments;
+- a relation selected a different node than the highlighted syntax suggested;
+- the target scope included generated files;
+- an output/fix flag behaved differently in the installed version.
+
+Reduce to one file and return to preview. Recover only task-owned edits; never use a broad
+destructive reset.
+
+## `rg` fallback diagnostics
+
+When ast-grep is unavailable, a text query can still answer:
+
+- whether a literal string appears;
+- which files mention an API spelling;
+- where comments contain a marker;
+- candidate locations for later structural review.
+
+It cannot safely prove:
+
+- node type;
+- nesting or parent relation;
+- argument count;
+- declaration versus use;
+- code versus comment/string;
+- formatting-insensitive completeness;
+- safe replacement boundaries.
+
+Phrase the result as “textual candidates” and include the exact regex and glob exclusions.
+
+## Evidence template
+
+Record:
+
+```text
+engine:
+version:
+query class:
+language:
+pattern or rule path:
+target roots:
+exclusions:
+known positive:
+known negative:
+result count:
+parse failures:
+exit status:
+next verifier:
+cleanup:
+```
+
+For zero matches, add which diagnostic steps were completed. For excessive matches, record the
+false-positive classes and the constraint that removed each class.

package/marketplace/plugins/litcodex/skills/structural-search/references/patterns-and-rules.md

@@ -0,0 +1,381 @@
+# Structural patterns and reusable rules
+
+Use this reference after the capability probe in `SKILL.md` has identified a real ast-grep
+executable. Examples use `$STRUCTURAL_SEARCH_BIN`, the validated shell variable from that probe.
+CLI options can drift, so confirm unfamiliar flags with:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run --help
+"$STRUCTURAL_SEARCH_BIN" scan --help
+```
+
+## Start from a semantic sentence
+
+Write the target in plain language before writing syntax:
+
+> Match a call whose callee is `console.log`, capture every argument, and ignore property reads that
+> are not called.
+
+That sentence identifies the root node (call), fixed syntax (`console.log`), capture
+(`$$$ARGUMENTS`), and a negative boundary (property access without invocation). Translate it to the
+smallest valid pattern:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern 'console.log($$$ARGUMENTS)' src
+```
+
+If the sentence includes ancestors, descendants, siblings, exclusions, or multiple alternatives,
+move to a YAML rule rather than squeezing relationships into one pattern.
+
+## Capture behavior
+
+### One node
+
+`$EXPRESSION` represents one syntax node:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern 'await $EXPRESSION' src
+```
+
+Use a descriptive uppercase name. A wildcard-like name may be convenient for discovery, but named
+captures make rewrites and diagnostics reviewable.
+
+### A sequence of nodes
+
+`$$$ARGUMENTS` represents a sequence in a grammar position that accepts multiple children:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern 'Promise.all([$$$ITEMS])' src
+```
+
+The sequence may be empty. If emptiness is invalid for the requested policy, add a constraint or
+test the specific arity with a more precise pattern.
+
+### Repeated names
+
+Reusing a capture name asks the matcher to compare the captured source:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern '$VALUE === $VALUE' src
+```
+
+This is source equality within the structural matcher, not type identity or runtime equality.
+Choose different names when the nodes may legitimately differ.
+
+## Valid parse context
+
+Patterns are parsed as code in the selected language. Some fragments are not valid standalone
+program fragments or parse as a node other than the one you intend. When that happens, place the
+fragment inside valid surrounding code and select the relevant subnode in a YAML pattern object.
+
+Example shape:
+
+```yaml
+id: class-field-initializer
+language: TypeScript
+severity: hint
+message: "Selected field initializer"
+rule:
+  pattern:
+    context: |
+      class Example {
+        target = $VALUE
+      }
+    selector: public_field_definition
+```
+
+The exact selector names come from the installed language grammar. Do not guess a kind name from
+another language or another parser release. Use the installed CLI's debug output on a minimal
+sample, then record the observed node kind.
+
+## Inline patterns versus YAML
+
+Use an inline pattern when all of these are true:
+
+- one syntax shape is sufficient;
+- no ancestor, descendant, sibling, field, or exclusion relation is needed;
+- there is no reusable diagnostic message or severity;
+- the query is exploratory or one-off.
+
+Use YAML when any of these apply:
+
+- the target depends on `inside`, `has`, `precedes`, or `follows`;
+- multiple alternatives or a negation are required;
+- capture constraints reduce false positives;
+- the rule needs a stable id, message, severity, file set, test, or fix;
+- another rule should reuse the logic.
+
+## Minimal reusable rule
+
+```yaml
+id: direct-console-log
+language: TypeScript
+severity: warning
+message: "Review direct console logging"
+rule:
+  pattern: console.log($$$ARGUMENTS)
+files:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+ignores:
+  - "**/*.generated.ts"
+  - "**/vendor/**"
+```
+
+Run one explicit file before scanning a whole configured project:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" scan \
+  --rule rules/direct-console-log.yml \
+  src/example.ts
+```
+
+Then expand to the approved target:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" scan \
+  --rule rules/direct-console-log.yml \
+  src
+```
+
+Check the installed `scan --help` before relying on output-format or fix flags.
+
+## Rule building blocks
+
+### Atomic matchers
+
+Use one or combine several:
+
+- `pattern`: match parsed source shape and bind captures.
+- `kind`: match an observed grammar node kind.
+- `regex`: restrict the full text of the current node; combine with a structural candidate to keep
+  the search bounded.
+- `nthChild`: constrain position among siblings.
+- `range`: constrain source position when location itself is part of the policy.
+
+A broad regex at the root of a large tree is usually both slower and less expressive than using
+`kind` or `pattern` first.
+
+### Relations
+
+Relations evaluate from the current candidate node:
+
+- `inside`: the candidate is enclosed by a matching parent or ancestor.
+- `has`: the candidate contains a matching child or descendant.
+- `precedes`: a matching sibling appears later.
+- `follows`: a matching sibling appears earlier.
+
+Traversal depth matters. A default neighbor-only traversal can miss a distant ancestor or deeply
+nested descendant. When the installed rule schema supports `stopBy`, choose it deliberately and
+test both a near and distant example.
+
+Example: an `await` expression anywhere inside an async function:
+
+```yaml
+id: await-in-async-function
+language: TypeScript
+severity: hint
+message: "Await inside an async function"
+rule:
+  pattern: await $EXPRESSION
+  inside:
+    pattern: async function $NAME($$$PARAMETERS) { $$$BODY }
+    stopBy: end
+```
+
+This does not prove anything about what `$EXPRESSION` resolves to.
+
+### Boolean composition
+
+- `all`: every child rule must match the same candidate node.
+- `any`: at least one child rule must match the candidate.
+- `not`: the child rule must not match the candidate.
+- `matches`: reuse a named utility rule when supported by the project configuration.
+
+Keep the candidate node explicit. If the intent says “a function contains both X and Y,” the
+function is the candidate and the two descendant checks are separate `has` relations:
+
+```yaml
+id: function-with-log-and-return
+language: TypeScript
+severity: hint
+message: "Function contains logging and a return"
+rule:
+  all:
+    - kind: function_declaration
+    - has:
+        pattern: console.log($$$ARGUMENTS)
+        stopBy: end
+    - has:
+        kind: return_statement
+        stopBy: end
+```
+
+Do not place `all` under one `has` when the sub-rules are meant to match different descendants.
+
+### Capture constraints
+
+Constraints refine metavariables after the main pattern has bound them:
+
+```yaml
+id: suspicious-handler-name
+language: TypeScript
+severity: warning
+message: "Review handler naming"
+rule:
+  pattern: function $NAME($$$PARAMETERS) { $$$BODY }
+constraints:
+  NAME:
+    regex: "^handle[A-Z].*"
+```
+
+Regex constraints operate on captured source text, not resolved symbols. Anchor deliberately and
+test near-miss names.
+
+## Project configuration
+
+A repository may expose rules, tests, and reusable utilities through `sgconfig.yml`:
+
+```yaml
+ruleDirs:
+  - rules
+testConfigs:
+  - testDir: rule-tests
+utilDirs:
+  - rule-utils
+languageGlobs:
+  TypeScript:
+    - "**/*.cts"
+    - "**/*.mts"
+```
+
+Treat configuration as project behavior:
+
+- do not create or change it unless the user requested durable rule enrollment;
+- preserve existing rule/test directory conventions;
+- confirm language glob overrides do not reclassify unrelated files;
+- keep custom parser or injection configuration out of a one-off search;
+- use project-native rule tests where configuration already declares them.
+
+For a single rule, `scan --rule <path>` is usually safer than modifying global configuration.
+
+## Language-oriented examples
+
+These are syntax starting points, not universal semantic truths. Prototype against the project's
+actual language version.
+
+### TypeScript and JavaScript
+
+```sh
+# Named import declaration
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern 'import { $$$SPECIFIERS } from $SOURCE' src
+
+# A catch block with a bound error
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern 'try { $$$BODY } catch ($ERROR) { $$$HANDLER }' src
+
+# Direct method call on any receiver
+"$STRUCTURAL_SEARCH_BIN" run --lang TypeScript \
+  --pattern '$RECEIVER.map($CALLBACK)' src
+```
+
+The last pattern finds a syntactic `.map` call. It does not prove that the receiver is an array.
+
+### Python
+
+```sh
+# Decorated function
+"$STRUCTURAL_SEARCH_BIN" run --lang Python \
+  --pattern '@$DECORATOR
+def $NAME($$$PARAMETERS):
+    $$$BODY' .
+
+# Context manager
+"$STRUCTURAL_SEARCH_BIN" run --lang Python \
+  --pattern 'with $RESOURCE as $NAME:
+    $$$BODY' .
+
+# Async function
+"$STRUCTURAL_SEARCH_BIN" run --lang Python \
+  --pattern 'async def $NAME($$$PARAMETERS):
+    $$$BODY' .
+```
+
+Indentation belongs to Python syntax. If a multi-line shell pattern becomes hard to audit, place it
+in a reviewed YAML rule instead of assembling it dynamically.
+
+### Go
+
+```sh
+# Error guard
+"$STRUCTURAL_SEARCH_BIN" run --lang Go \
+  --pattern 'if $ERR != nil { $$$BODY }' .
+
+# Deferred call
+"$STRUCTURAL_SEARCH_BIN" run --lang Go \
+  --pattern 'defer $FUNCTION($$$ARGUMENTS)' .
+```
+
+The first pattern compares syntax only; it does not establish that `$ERR` has the built-in `error`
+interface type.
+
+### Rust
+
+```sh
+# Result propagation
+"$STRUCTURAL_SEARCH_BIN" run --lang Rust \
+  --pattern '$EXPRESSION?' src
+
+# Debug macro
+"$STRUCTURAL_SEARCH_BIN" run --lang Rust \
+  --pattern 'dbg!($$$ARGUMENTS)' src
+```
+
+Macros can have parser-specific shapes. Validate macro queries on one known match.
+
+### Java
+
+```sh
+# Constructor call
+"$STRUCTURAL_SEARCH_BIN" run --lang Java \
+  --pattern 'new $TYPE($$$ARGUMENTS)' src
+
+# try-with-resources
+"$STRUCTURAL_SEARCH_BIN" run --lang Java \
+  --pattern 'try ($$$RESOURCES) { $$$BODY }' src
+```
+
+### C and C++
+
+```sh
+# Allocation call
+"$STRUCTURAL_SEARCH_BIN" run --lang C \
+  --pattern 'malloc($SIZE)' src
+
+# Smart-pointer factory
+"$STRUCTURAL_SEARCH_BIN" run --lang Cpp \
+  --pattern 'std::make_unique<$TYPE>($$$ARGUMENTS)' src
+```
+
+Language label spelling is version-sensitive; verify it from the installed help or language list.
+Preprocessor expansion and template semantics exceed pure syntax matching.
+
+## Rule acceptance checklist
+
+Before keeping a rule:
+
+- the id is stable and describes policy, not implementation history;
+- language and file scope are explicit;
+- one positive example matches;
+- a formatting variant still matches when it should;
+- a syntactically similar negative example does not match;
+- a nested relation test reaches the intended depth;
+- every capture used by a message or fix is bound on every match path;
+- the diagnostic explains action rather than restating syntax;
+- any fix is separately previewed under the rewrite workflow;
+- project configuration changes, if any, are intentional and verified.