scip-query 0.22.0 → 0.24.0

package/skills/scip-system-compression/references/compression-atlas.md

@@ -0,0 +1,116 @@
+# Compression Atlas
+
+Use this reference when the compression scope is broad enough that local refactors may interact. The atlas is a written planning artifact: save it before implementation when filesystem edits are allowed, and update it after each cluster if code changes reveal new facts.
+
+Preferred paths are `docs/plans/YYYY-MM-DD-<scope>-compression-atlas.md` or `reports/compression/YYYY-MM-DD-<scope>-atlas.md`. If neither directory exists, create the one that best matches the repository's existing planning/reporting conventions.
+
+## Atlas Template
+
+```text
+Scope
+- Target:
+- Assumed boundaries:
+- Explicit non-goals, including health-score or detector-count optimization:
+- Public surfaces to preserve:
+
+System Map
+- Entry points:
+- Major subsystems:
+- Tests/docs/generated artifacts:
+- Current ownership boundaries:
+
+Role Inventory
+- Role:
+  Referents:
+  Execution shape:
+  Evidence:
+  Pressure:
+
+Opportunity Ledger
+- ID:
+  Opportunity:
+  Evidence:
+  Root cause:
+  Proposed disposition: merge | delete | inline | extract | generate | enforce | supersede | defer | skip
+  Disposition reason:
+  Cluster:
+  Public behavior constraints:
+
+Deferred Register
+- Opportunity ID:
+  Evidence:
+  Blocking fact:
+  Dependency or owner:
+  Revisit condition:
+  Next-pass priority:
+
+Compression Clusters
+- Name:
+  Thesis:
+  Opportunities:
+  Old mechanisms:
+  New mechanism:
+  What disappears:
+  Touch map:
+  Depends on:
+  Validation:
+  Risk:
+
+Dependency Order
+1. Cluster:
+   Enables:
+   Must precede:
+   Validation after cluster:
+
+Sense-Check
+- Content check:
+- Structure check:
+- Value check:
+- Rework check:
+- Public-surface check:
+- Ambition check:
+
+Final Audit
+- Concepts removed:
+- Concepts added:
+- Net concept count:
+- Largest remaining pressure point:
+- Deferred opportunities:
+```
+
+## Ledger Rules
+
+Every discovered opportunity gets exactly one disposition. Do not use `defer` just because the change is large or cross-cutting. If an opportunity is false, net-negative, or too speculative, mark it `skip`. If it is valid but blocked, mark it `defer` and add it to the deferred register.
+
+Every deferred entry must name a verified blocking fact and a revisit condition. Acceptable blockers include an explicit scope limit, missing evidence that would make implementation unsafe, dependency on an earlier cluster, conflict with unrelated user changes, unavailable runtime/generated artifacts, or user-imposed time/slice limits.
+
+Major cleanup is in scope when it is the right compression. Prefer ordered clusters, public-behavior validation, and implementation over deferral.
+
+Use `supersede` when a local opportunity will be absorbed by a larger mechanism. For example, a wrapper-candidate finding may be superseded by a broader adapter-core split if the wrapper disappears as part of moving behavior into the core.
+
+Use `enforce` when the goal is to make drift impossible. The real referents are repeated predicates, option defaults, SQL fragments, lint rules, typed descriptors, tests, or generated surfaces. The narrower policy should become easier to use than the scattered alternatives.
+
+## Ordering Rules
+
+Order by enabling power, not by apparent size.
+
+Prefer this order when the evidence supports it:
+
+1. Public behavior characterization: tests, snapshots, help output, or documented API constraints.
+2. Shared policy or descriptor center: one place to name the rule or execution shape.
+3. Adapters and callers: migrate concrete units onto the new center.
+4. Compatibility shells: keep thin aliases only when needed for public stability.
+5. Deletions and inlining: remove old mechanisms after references prove they are replaced.
+6. Docs and generated surfaces: update or derive them once runtime behavior is settled.
+
+Reject an order when it causes a file to be rewritten by multiple clusters without a stated reason. Merge those clusters or introduce the enabling mechanism first.
+
+## Sense-Check Questions
+
+- Does each cluster remove a concept, policy branch, lifecycle, or hand-maintained surface?
+- Does the new mechanism have one clear role, or is it a false center?
+- Are skipped opportunities skipped because of verified facts, not convenience?
+- Are deferred opportunities still visible with a blocking fact and revisit condition?
+- Is any major but correct compression being deferred merely because it is large?
+- Would an executor know exactly which files and symbols to change?
+- Can focused validation prove behavior stayed stable after each cluster?

package/skills/scip-system-compression/references/compression-patterns.md

@@ -0,0 +1,87 @@
+# Compression Patterns
+
+Use this reference after the first evidence pass, when generating possible simplification models. These are prompts for thought, not templates to impose.
+
+## Atlas-First Compression
+
+Use when the user wants to think ahead across a whole repository, module family, command surface, query family, or subsystem before editing. The real referents are source files, symbols, command handlers, query modules, docs, tests, generated artifacts, and previously discovered opportunities that could interact. The deeper pattern is that discovery and ordering must be completed before implementation, so local opportunities are not rediscovered as new work after each edit.
+
+Typical compression: build a compression atlas with an opportunity ledger and deferred register, cluster by root cause, order clusters by enabling power, enrich steps, sense-check overlap and value, then execute the unblocked clusters in dependency order even when the right cleanup is large.
+
+Reject when the scope is a single isolated bug or one clearly bounded refactor where a full atlas would add planning overhead without reducing rework risk.
+
+## Metadata-Rendered Surface
+
+Use when command help, docs, examples, tests, and runtime behavior all describe the same external surface. The real referents are command registrations, option definitions, usage text, README sections, snapshots, and smoke tests. The deeper pattern is that hand-maintained text should become a rendered view of executable metadata.
+
+Typical compression: introduce a command descriptor or schema that owns name, arguments, options, examples, analysis function, and renderer hooks; generate help/docs/tests from it where practical.
+
+Reject when docs intentionally teach concepts that cannot be derived from command metadata.
+
+## Pipeline
+
+Use when many flows repeatedly parse input, load state, run analysis, transform results, render output, and handle errors. The real referents are command actions, scripts, batch jobs, worker handlers, and tests that assert their outputs. The deeper pattern is one lifecycle with different stages plugged in.
+
+Typical compression: make the lifecycle explicit, keep stage functions small, and move policy decisions into named stage inputs instead of scattered inline code.
+
+Reject when the flows have materially different ordering, resource lifetime, or error semantics.
+
+## Registry or Descriptor Table
+
+Use when many branches select behavior by name, language, kind, command, file type, or analysis phase. The real referents are switch statements, if chains, command builders, language dispatch, test matrices, and documentation tables. The deeper pattern is a finite set of cases with shared fields and per-case functions.
+
+Typical compression: replace scattered branches with a typed table of descriptors and one executor that consumes the table.
+
+Reject when the table becomes a bag of unrelated optional fields.
+
+## Execution Algebra
+
+Use when a descriptor table centralizes names and metadata but leaves many handlers repeating the same lifecycle. The real referents are command handlers, API handlers, worker phases, query calls, renderers, option decoders, budget checks, and hidden commands. The deeper pattern is that each unit is an instance of one of a few execution shapes.
+
+Typical compression: define typed command shapes such as pure query, heuristic query, project readiness, lifecycle side effect, and isolated worker. Each shape owns its required setup order, allowed variant points, result renderer, and error behavior. Descriptors choose a shape instead of pointing at a bespoke handler whenever possible.
+
+Reject when shape variants require many unrelated escape hatches, or when lifecycle order differs enough that a custom handler is clearer.
+
+## Shared Policy Object
+
+Use when separate modules answer the same rule question differently, such as "what is live?", "what is public?", "what is ignored?", "what counts as a test?", or "which edge is real?" The real referents are repeated predicates, SQL fragments, filters, option defaults, and tests that encode the same domain boundary. The deeper pattern is one policy that multiple analyses should import.
+
+Typical compression: name the policy in domain language, centralize it in a narrow module, and make each caller pass only the context it actually owns.
+
+Reject when the apparent rule is only similar because the words are similar; user-visible behavior may require separate policies.
+
+## Query Algebra
+
+Use when query modules repeatedly build the same graph, candidate set, scoring pass, or summary rows before applying different final filters. The real referents are SQL fragments, graph builders, row mappers, symbol classifiers, candidate gates, and report summaries. The deeper pattern is a small vocabulary of query operations that can be composed.
+
+Typical compression: factor the repeated operation as a named data transformation with explicit inputs and outputs; keep command-specific ranking and rendering outside it.
+
+Reject when a generalized operation hides expensive work or makes precision/confidence rules less visible.
+
+## Adapter-Core Split
+
+Use when UI, CLI, API, or worker code owns business logic while pure modules merely support it. The real referents are command actions, HTTP handlers, worker messages, renderers, and pure query functions. The deeper pattern is that adapters translate boundaries while the core owns analysis.
+
+Typical compression: move behavior into pure functions with typed results; make adapters responsible only for input parsing, resource setup, output formatting, and exit behavior.
+
+Reject when moving logic would destabilize a public surface without reducing duplicated policy.
+
+## Compatibility Shell
+
+Use when old APIs, scripts, command names, or file paths remain only to preserve callers after the real implementation moved. The real referents are wrappers, aliases, barrels, deprecated modules, and release notes. The deeper pattern is a temporary shell around a new center.
+
+Typical compression: keep the shell thin, document the compatibility boundary, and delete it when references prove it is no longer used.
+
+Reject when the wrapper adds meaningful validation, translation, or lifecycle management.
+
+## Anti-Patterns
+
+Helper cemetery: a refactor extracts many tiny helpers but leaves the original concepts scattered.
+
+Parameter swamp: one generic function gains many flags because the grouped cases are not actually the same kind of thing.
+
+False center: a new module becomes a dependency hub without owning a coherent policy or workflow.
+
+Name-level unification: code is grouped because names sound similar, while call graphs, data flow, or user-visible behavior show different roles.
+
+Premature deletion: code is removed because it looks conceptually redundant before references, entry points, and tests prove it is unused or replaceable.

package/skills/scip-twin-drift/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: scip-twin-drift
+description: Find and resolve twin drift with scip-query. Use for same-name or near-name functions across files with diverged bodies, drifted policy thresholds, one-sided fixes, or consolidating a duplicated concept into one canonical helper.
+metadata:
+  commands:
+    - template: 'scip-query twin-drift -s <scope> --json'
+      when: 'Enumerate same-name or near-name callable groups whose bodies partially overlap.'
+    - template: 'scip-query duplicate-bodies -s <scope>'
+      when: 'Separate exact clones, which belong to this detector, from drifted twins.'
+    - template: 'scip-query code <selector>'
+      when: 'Read every member of a divergent group to classify the divergence.'
+    - template: 'scip-query refs <symbol>'
+      when: 'Pick the canonical twin by consumer count.'
+    - template: 'scip-query diff-impact'
+      when: 'After consolidating, map the changed symbols and every downstream consumer.'
+---
+
+# scip-twin-drift
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Command and question manual
+
+| Command syntax | Question it answers |
+| --- | --- |
+| `scip-query twin-drift -s <scope> --json` | Enumerate same-name or near-name callable groups whose bodies partially overlap. |
+| `scip-query duplicate-bodies -s <scope>` | Separate exact clones, which belong to this detector, from drifted twins. |
+| `scip-query code <selector>` | Read every member of a divergent group to classify the divergence. |
+| `scip-query refs <symbol>` | Pick the canonical twin by consumer count. |
+| `scip-query diff-impact` | After consolidating, map the changed symbols and every downstream consumer. |
+
+These commands are controls, not a checklist. Use every capability needed by the task, but make each query answer a distinct question. There is no required sequence or query limit. Run a command's `--help` when you need a flag not shown in its template.
+<!-- END GENERATED SKILL COMMANDS -->
+
+Use this skill when the same concept exists in more than one place under the same or a near-name (case-insensitive, or edit-distance at most 2 for names of 8 or more characters) and the bodies have silently diverged. A twin drift group is a same-leaf-name family of callables spanning at least two files whose normalized-token bodies are neither identical (that is the job of `duplicate-bodies`) nor unrelated (a homonym like `render` or `parse`) but partially overlapping. That overlap is the signature of a concept that was copied once and then edited independently in only some of its copies.
+
+## Rules
+
+1. `IDENTICAL` groups defer to `duplicate-bodies`; do not re-report them here.
+2. Homonyms (similarity below `--min-similarity`, default 0.3) are noise unless `--include-homonyms` was requested; do not chase them.
+3. Every `DIVERGENT` group in scope gets a classification before this skill reports done.
+4. Prefer consolidation to one exported helper over leaving parallel copies. When consolidation is unsafe or premature, record the intent gap explicitly in a comment or a suppression with a reason rather than silently accepting drift.
+5. If your own diff introduces a new twin, you just reproduced the defect class this skill exists to catch. Fix or explicitly accept it before finishing.
+
+## Workflow
+
+### 1. Run the detector
+
+```bash
+scip-query twin-drift -s <scope> --json
+scip-query duplicate-bodies -s <scope>
+```
+
+Scope with `-s <path>` when the review is bounded to a module. Record group count, member count, and the maximum divergence per group.
+
+This step is complete only when every group in scope is enumerated with its relationship (`divergent` versus suppressed homonym).
+
+### 2. Classify each DIVERGENT group
+
+For each group, read every member with `scip-query code <symbol-or-file:range>` and use the group's first divergent tokens as a starting point for where the bodies diverge. Classify the group as one of:
+
+- **Intentional variation**: the copies differ because the domains genuinely differ, for example a React-specific versus Vue-specific structural comparator that must branch on framework-specific overlap checks. Essential variation stays; record why.
+- **Drifted policy**: the copies encode what should be one policy (a threshold, a normalization rule, an edge-case guard) that only some copies received when it last changed. This is a bug: pick the correct value and propagate it, or extract the policy into one named function or constant.
+- **One-sided fix**: one copy was bugfixed or hardened and its twins were not. This is also a bug: apply the same fix to every member, or consolidate.
+
+This step is complete only when every DIVERGENT group in scope has one of these three labels with a one-line reason.
+
+### 3. Pick the canonical twin and act
+
+For groups getting consolidated, pick the canonical member by consumer count:
+
+```bash
+scip-query refs <symbol-in-file-A>
+scip-query refs <symbol-in-file-B>
+```
+
+Prefer the member with the most consumers, or the one in the more general or shared location when counts tie. Extract or move the canonical body to one exported helper; update the other members to call it, or delete them if they were pure duplication with different names for the caller's convenience. Preserve any classified-essential variation as a parameter or a thin caller-side branch, not as a second copy of the whole body.
+
+For groups marked intentional variation, do not force consolidation. Record the reason in a comment near one of the members so the next `twin-drift` run and the next reader both see it was considered.
+
+This step is complete only when every DIVERGENT group is either consolidated (with the old copies gone or forwarding) or has a recorded reason it stays separate.
+
+### 4. Verify
+
+Rerun the detector to confirm consolidated groups no longer appear as DIVERGENT, run the repository's own tests and typecheck for the touched files, then:
+
+```bash
+scip-query diff-impact
+```
+
+Read every downstream consumer it lists. A consumer that depended on the deleted twin's behavior, not the canonical one's, is a regression this skill must catch before finishing.
+
+This step is complete only when `twin-drift` shows no unclassified `DIVERGENT` groups in scope and every consumer named by `diff-impact` has been checked.
+
+## Report
+
+```markdown
+Scope:
+Groups found: N (M divergent, K suppressed homonyms)
+
+Divergent groups:
+
+- <leaf name> (<files>): classification: intentional variation | drifted policy | one-sided fix
+  - action: consolidated into <canonical file:symbol> | reason kept separate
+
+Verification:
+
+- `scip-query twin-drift -s <scope> --json`: <result>
+- `scip-query diff-impact`: <consumers checked>
+```

package/skills/scip-twin-drift/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'SCIP Twin Drift'
+  short_description: 'Find and resolve same-name twins that have silently diverged'
+  default_prompt: 'Use $scip-twin-drift to find same-name or near-name functions that have diverged across files, classify each divergence as intentional variation, drifted policy, or one-sided fix, and consolidate or record the intent gap.'

package/dist/by-kind-4IYG2SKW.js

@@ -1,2 +0,0 @@
-import{a,b}from"./chunk-JAT6C3VX.js";import"./chunk-MTDBHTSF.js";import"./chunk-C7IJMOFP.js";import"./chunk-YXPUP5G2.js";import"./chunk-DRENNWRG.js";import"./chunk-DKM723YF.js";import"./chunk-K3XFWJI2.js";import"./chunk-IW5XQG5G.js";import"./chunk-H5EXS3HM.js";import"./chunk-HGFDYOVB.js";import"./chunk-AK3PYTIK.js";export{a as byKind,b as kindCounts};
-//# sourceMappingURL=by-kind-4IYG2SKW.js.map

package/dist/call-graph-WQNXMNNN.js

@@ -1,2 +0,0 @@
-import{a}from"./chunk-GQIDEID3.js";import"./chunk-7KCZELVM.js";import"./chunk-BGBBVSH4.js";import"./chunk-6NC3YSPY.js";import"./chunk-MTDBHTSF.js";import"./chunk-IXESDH3J.js";import"./chunk-OXYAWIEA.js";import"./chunk-FKGQOTKD.js";import"./chunk-2XCGSDIT.js";import"./chunk-WRQXLNYE.js";import"./chunk-T6QD2ZQB.js";import"./chunk-EELPBR7E.js";import"./chunk-BJT7LSPK.js";import"./chunk-WSLEJSFR.js";import"./chunk-VUSKPCUB.js";import"./chunk-F4FNK44D.js";import"./chunk-HCVJR2V4.js";import"./chunk-EETGXQY7.js";import"./chunk-TQZV7KV4.js";import"./chunk-C7IJMOFP.js";import"./chunk-YXPUP5G2.js";import"./chunk-DRENNWRG.js";import"./chunk-BVFYEEBH.js";import"./chunk-JHH5SCZ3.js";import"./chunk-ENWQWA2R.js";import"./chunk-DKM723YF.js";import"./chunk-K3XFWJI2.js";import"./chunk-IW5XQG5G.js";import"./chunk-JT6XX7QY.js";import"./chunk-H5EXS3HM.js";import"./chunk-HGFDYOVB.js";import"./chunk-SB25YMEQ.js";import"./chunk-AK3PYTIK.js";export{a as callGraph};
-//# sourceMappingURL=call-graph-WQNXMNNN.js.map

package/dist/call-graph-evidence-lZa2dwQA.d.ts

@@ -1,11 +0,0 @@
-type CalleeEvidenceSource = 'ast-callsite' | 'semantic-callee' | 'scip-chunk';
-interface CalleeRow {
-    symbol: string;
-    file: string;
-    chunkId: number;
-    source: CalleeEvidenceSource;
-    /** Zero-based source line of the call expression when retained by the evidence source. */
-    callsiteLine?: number;
-}
-
-export type { CalleeRow as C, CalleeEvidenceSource as a };