specguard-mcp 0.1.35 → 0.1.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -12
- package/dist/src/config.d.ts +2 -1
- package/dist/src/config.js.map +1 -1
- package/dist/src/tools/lint-intent-annotations.d.ts +4 -2
- package/dist/src/tools/lint-intent-annotations.js +29 -16
- package/dist/src/tools/lint-intent-annotations.js.map +1 -1
- package/dist/src/tools/near-duplicate-clusters.d.ts +24 -1
- package/dist/src/tools/near-duplicate-clusters.js +53 -5
- package/dist/src/tools/near-duplicate-clusters.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -36,7 +36,7 @@ refuses to boot and takes the tools that needed no configuration down with it.
|
|
|
36
36
|
| `SPECGUARD_API_KEY` | `get_repository_overview`, `near_duplicate_clusters` (default calls) | — | an agent/CI API key (`sgk_…`) issued by that deployment — a **per-repository** key, which is the single repository those tools answer about by default |
|
|
37
37
|
| `SPECGUARD_USER_API_KEY` | `list_repositories` (fallback), `add_repository`, `registrable_repositories`, `remove_repository` (fallback), `create_repository_api_key` (fallback), `revoke_repository_api_key` (fallback), `list_repository_api_keys` (fallback), `list_repository_agent_keys` (fallback), `revoke_repository_agent_key` (fallback), `list_repository_agent_keys_presented_revoked` (fallback), `list_repository_members` (fallback), `add_repository_member` (fallback), `update_repository_member_permissions` (fallback), `remove_repository_member` (fallback), `get_repository_overview` / `near_duplicate_clusters` **with** `repository` (fallback), `rename_repository` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
|
|
38
38
|
| `SPECGUARD_AGENT_API_KEY` | `list_repositories` (preferred), `remove_repository` (preferred), `create_repository_api_key` (preferred), `revoke_repository_api_key` (preferred), `list_repository_api_keys` (preferred), `list_repository_agent_keys` (preferred), `revoke_repository_agent_key` (preferred), `list_repository_agent_keys_presented_revoked` (preferred), `list_repository_members` (preferred), `add_repository_member` (preferred), `update_repository_member_permissions` (preferred), `remove_repository_member` (preferred), `get_repository_overview` / `near_duplicate_clusters` **with** `repository` (preferred) | — | an **agent** API key (`sga_…`), minted from that deployment's account page (Agent keys panel) with an explicit set of repositories and permissions. It speaks for nobody: its reach is exactly the set granted onto it, fixed at mint time, and every read is bounded by that set server-side. This is the credential to give an automated agent — one key, many repositories, none of a person's rights. When it and `SPECGUARD_USER_API_KEY` are both set, every tool that answers either key — `list_repositories`, `remove_repository`, the members tools, the key-lifecycle tools, and `get_repository_overview` / `near_duplicate_clusters` **with** `repository` — uses **this** one, so discovery stays inside the set the other tools can reach |
|
|
39
|
-
| `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter. Most Ruby projects need `bundle exec specguard-lint` |
|
|
39
|
+
| `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter — the one switch between the Ruby and the JS/TS client. Most Ruby projects need `bundle exec specguard-lint`; a JS/TS project sets `npx -p @yatfa/specguard specguard lint` (and needs the validator backend: `SPECGUARD_VALIDATE_INTENT`, or the prebuilt package) |
|
|
40
40
|
| `SPECGUARD_TIMEOUT_MS` | HTTP tools | `30000` | how long a call to SpecGuard may take |
|
|
41
41
|
|
|
42
42
|
`SPECGUARD_ENDPOINT` and `SPECGUARD_API_KEY` are the same variables
|
|
@@ -69,22 +69,31 @@ Register it with your MCP client — for Claude Code:
|
|
|
69
69
|
|
|
70
70
|
### `lint_intent_annotations`
|
|
71
71
|
|
|
72
|
-
Validates the `@intent:` annotations in a
|
|
72
|
+
Validates the `@intent:` annotations in a project's test files against the
|
|
73
73
|
[OpenTestIntent](https://github.com/yatfa-ai/open-test-intent) schema, by running that project's own
|
|
74
|
-
|
|
74
|
+
linter with `--json` — `specguard-lint` (Ruby/RSpec, `*_spec.rb`) or `specguard lint` (JS/TS,
|
|
75
|
+
`@yatfa/specguard`; `.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`). `SPECGUARD_LINT_COMMAND` selects which;
|
|
76
|
+
the server does not auto-detect it. A JS/TS run needs the validator backend
|
|
77
|
+
(`SPECGUARD_VALIDATE_INTENT`, or the prebuilt package) — without one the linter exits `2` and says why
|
|
78
|
+
(see the specguard-ts README, "The validate-intent binary"). Findings come back as data — file, line, failure kind, every violated rule
|
|
75
79
|
— rather than as a prose report to regex.
|
|
76
80
|
|
|
77
81
|
| argument | |
|
|
78
82
|
| --- | --- |
|
|
79
83
|
| `project_dir` | the project to lint; defaults to the server's working directory. A path that does not exist, or is not a directory, is refused by name — never reported as a missing linter |
|
|
80
|
-
| `paths` | specific
|
|
81
|
-
| `changed` | check what the branch changed since the merge base with the default branch — CI's mode; untracked spec files count too (no `git add` needed); `--exclude-standard` keeps `.gitignore`d paths out of the untracked leg alone, and a tracked file is never subject to `.gitignore`, so the dependency/build directory fence holds ignored tracked paths out |
|
|
84
|
+
| `paths` | specific test files, relative to `project_dir`; omit to check every spec file outside dependency/build directories. An empty list is an error rather than a synonym for "everything", because a run that selected nothing must not come back clean |
|
|
85
|
+
| `changed` | check what the branch changed since the merge base with the default branch — CI's mode; **needs a linter version that ships `--changed`**: the Ruby gem and `@yatfa/specguard` main do, `@yatfa/specguard` 0.1.1 on npm does not (exit `2`, `invalid option: --changed`); untracked spec files count too (no `git add` needed); `--exclude-standard` keeps `.gitignore`d paths out of the untracked leg alone, and a tracked file is never subject to `.gitignore`, so the dependency/build directory fence holds ignored tracked paths out |
|
|
82
86
|
| `base` | diff `changed` against this ref instead |
|
|
83
87
|
|
|
88
|
+
The report is the linter's own document, echoed untouched, so its `summary` keys and finding kinds
|
|
89
|
+
differ per client — Ruby reports `files`/`annotations`/`failed`; JS/TS reports
|
|
90
|
+
`files`/`annotations`/`malformed`/`unreadable` and can also emit an `unreachable` finding kind — read the
|
|
91
|
+
report rather than assuming one shape.
|
|
92
|
+
|
|
84
93
|
Needs no SpecGuard deployment and no API key. A **missing** annotation is never a failure: adoption
|
|
85
94
|
is gradual by design, so a suite with no annotations lints clean.
|
|
86
95
|
|
|
87
|
-
**The exit code is a verdict, and the mapping matters.**
|
|
96
|
+
**The exit code is a verdict, and the mapping matters.** Either linter exits `0` clean, `1` on a
|
|
88
97
|
malformed annotation, and `2` when it could not do its job. Exit `1` comes back as a **successful**
|
|
89
98
|
tool call carrying findings — an agent told "the tool failed" retries the tool, where an agent handed
|
|
90
99
|
a finding fixes the annotation. Only exit `2` is a tool error, and it carries the linter's stderr,
|
|
@@ -628,12 +637,15 @@ body text, whatever file they sit in), clustered by similarity. Answers the refa
|
|
|
628
637
|
the overview's per-run rankings cannot: where the same test is written twice, before you delete or
|
|
629
638
|
merge anything.
|
|
630
639
|
|
|
631
|
-
**This is
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
640
|
+
**This call is served stored** (SPGD-1474): the platform computes the census once per write that
|
|
641
|
+
moves its inputs — at each ingest, after identity resolution settles the run's identities, and
|
|
642
|
+
again when a run is deleted from the repository (which can move the run the weight figures are
|
|
643
|
+
weighed on) — and keeps it — so the answer returns in
|
|
644
|
+
milliseconds instead of running the minutes-scale computation that used to sit behind the ask and
|
|
645
|
+
never fit this bridge's 30-second deadline. The opt-in ask is unchanged wire contract
|
|
646
|
+
(`?near_duplicates=`, shipped by SPGD-703, still opens the block; the plain overview still answers
|
|
647
|
+
`near_duplicates: null` without it, and `get_repository_overview` never sends the ask). Calling
|
|
648
|
+
this tool **is** the ask.
|
|
637
649
|
|
|
638
650
|
Nothing about the **census** is choosable — the clusters are the repository's, computed over
|
|
639
651
|
every run; one call returns them all. (The server reads only that the `near_duplicates` key is
|
|
@@ -657,6 +669,12 @@ Read the response with its own rules in mind:
|
|
|
657
669
|
|
|
658
670
|
- `similarity_floor` and `similarity_basis` sit **first** in the block and qualify every figure
|
|
659
671
|
below them — a cluster count without what "similar" meant is a count you cannot act on.
|
|
672
|
+
- `computed_at` is when the stored census was taken and `weighed_run_id` is the run its weight
|
|
673
|
+
figures are from — read the stamp before acting on the figures. A census read shortly after an
|
|
674
|
+
ingest **or a run deletion** may be the **previous** artifact, carrying its own stamp, while the
|
|
675
|
+
recompute for the new state is still running; a `near_duplicates` block of `null` on this tool
|
|
676
|
+
means no census has
|
|
677
|
+
been computed for the repository yet (never a live computation, never zeros).
|
|
660
678
|
- `member_count` (texts in the repository, across every run) and `example_count` (examples in the
|
|
661
679
|
one run `weighed_run_id` names) are **different grains**: a three-example table-driven loop is
|
|
662
680
|
one member and three examples. Never fold them.
|
|
@@ -667,6 +685,21 @@ Read the response with its own rules in mind:
|
|
|
667
685
|
run's examples.
|
|
668
686
|
- `similarity_range` is `[strongest, weakest]`: membership is transitive, similarity is not.
|
|
669
687
|
- `total_seconds` is `null` where nothing was timed — never a zero that would read as free.
|
|
688
|
+
- `layer_source` at the head of the block states where the layer dimension comes from: **declared
|
|
689
|
+
via the intent protocol** when at least one clustered member's examples declared a layer, `null`
|
|
690
|
+
on a suite that declared nothing — absence stated, never an empty fiction. The layers are
|
|
691
|
+
DECLARED, never inferred: no path or directory convention is consulted anywhere in the cut (a
|
|
692
|
+
`request`-declared test under `spec/models/` reports `request`).
|
|
693
|
+
- `layer_redundancy` classifies each cluster: `cross_layer` when its members declared two or more
|
|
694
|
+
DISTINCT layers (the same behaviour covered on several levels — the test-pyramid question),
|
|
695
|
+
`same_layer` when confined to one (a plain duplicate), `null` when its members declared nothing
|
|
696
|
+
— neither state, never folded into `same_layer`.
|
|
697
|
+
- `layer_groups` holds the members grouped by declared layer (alphabetically, the undeclared LAST
|
|
698
|
+
as the `layer: null` group), each group's members in the same five-field shape the flat list
|
|
699
|
+
serves. A member whose own examples declared two layers appears in EACH group it declared, so
|
|
700
|
+
the groups' sizes can exceed `member_count` by exactly those members — that is the finding, not
|
|
701
|
+
an arithmetic bug — and a member that declared nothing stays in its cluster's null group, never
|
|
702
|
+
dropped.
|
|
670
703
|
- `clusters: []` with a real `identity_count` is the **success** state (nothing reads alike); the
|
|
671
704
|
three silences — nothing ingested, nothing embedded, nothing alike — are kept distinguishable by
|
|
672
705
|
`recorded_count` / `identity_count` / the list itself.
|
package/dist/src/config.d.ts
CHANGED
|
@@ -93,7 +93,8 @@ export interface Config {
|
|
|
93
93
|
/**
|
|
94
94
|
* The command that runs the `@intent` linter, already tokenised.
|
|
95
95
|
*
|
|
96
|
-
* Defaults to `["specguard-lint"]
|
|
96
|
+
* Defaults to `["specguard-lint"]` (the Ruby client; a JS/TS project sets
|
|
97
|
+
* `npx -p @yatfa/specguard specguard lint`). Most Ruby projects need the gem resolved
|
|
97
98
|
* through their bundle, which is a deployment fact this server cannot guess —
|
|
98
99
|
* set `SPECGUARD_LINT_COMMAND="bundle exec specguard-lint"` for those. It is
|
|
99
100
|
* tokenised here rather than handed to a shell, so nothing an agent passes as
|
package/dist/src/config.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import type { ToolDefinition } from "./types.js";
|
|
2
2
|
/**
|
|
3
|
-
* `specguard-lint --json`
|
|
4
|
-
*
|
|
3
|
+
* `specguard-lint --json` (Ruby) or `specguard lint --json` (JS/TS) as a tool —
|
|
4
|
+
* the `@intent` linter, shipped in `specguard-ruby` (`bin/specguard-lint`,
|
|
5
|
+
* SPGD-12 §1) and in `@yatfa/specguard` (`specguard lint`). Which one runs is
|
|
6
|
+
* decided by `SPECGUARD_LINT_COMMAND` alone; this file does not detect it.
|
|
5
7
|
*
|
|
6
8
|
* == Why this wraps the JSON renderer and not the human one
|
|
7
9
|
*
|
|
@@ -4,8 +4,10 @@ import { ArgumentError, CommandError } from "../errors.js";
|
|
|
4
4
|
import { EXIT_CLOSE_GRACE_MS, MAX_OUTPUT_BYTES } from "../support/run-command.js";
|
|
5
5
|
import { optionalBoolean, optionalString } from "./args.js";
|
|
6
6
|
/**
|
|
7
|
-
* `specguard-lint --json`
|
|
8
|
-
*
|
|
7
|
+
* `specguard-lint --json` (Ruby) or `specguard lint --json` (JS/TS) as a tool —
|
|
8
|
+
* the `@intent` linter, shipped in `specguard-ruby` (`bin/specguard-lint`,
|
|
9
|
+
* SPGD-12 §1) and in `@yatfa/specguard` (`specguard lint`). Which one runs is
|
|
10
|
+
* decided by `SPECGUARD_LINT_COMMAND` alone; this file does not detect it.
|
|
9
11
|
*
|
|
10
12
|
* == Why this wraps the JSON renderer and not the human one
|
|
11
13
|
*
|
|
@@ -48,32 +50,42 @@ import { optionalBoolean, optionalString } from "./args.js";
|
|
|
48
50
|
const lintIntentAnnotations = {
|
|
49
51
|
name: "lint_intent_annotations",
|
|
50
52
|
title: "Lint @intent annotations",
|
|
51
|
-
description: "Validate the `@intent:` annotations in a
|
|
52
|
-
"OpenTestIntent schema, using that project's own `specguard-lint
|
|
53
|
+
description: "Validate the `@intent:` annotations in a project's test files against the " +
|
|
54
|
+
"OpenTestIntent schema, using that project's own SpecGuard linter: `specguard-lint` for Ruby " +
|
|
55
|
+
"(RSpec, *_spec.rb) or `specguard lint` for JS/TS (@yatfa/specguard; .ts/.tsx/.js/.jsx/.mjs/.cjs). " +
|
|
56
|
+
"SPECGUARD_LINT_COMMAND picks which one runs; a JS/TS run also needs the validator backend " +
|
|
57
|
+
"(SPECGUARD_VALIDATE_INTENT, or the prebuilt package), otherwise the linter exits 2 and says why. " +
|
|
58
|
+
"Returns each finding as " +
|
|
53
59
|
"structured data — file, line, failure kind (schema / extraction / parse / read), and every " +
|
|
54
60
|
"violated rule — so a malformed annotation can be fixed without reading a CI log. " +
|
|
55
61
|
"Use it after writing or editing `@intent:` annotations, or to audit a suite. " +
|
|
56
62
|
"A MISSING annotation is never a failure: adoption is gradual by design, so a suite with no " +
|
|
57
|
-
"annotations at all lints clean.
|
|
63
|
+
"annotations at all lints clean. The report is the linter's own document, echoed untouched, so " +
|
|
64
|
+
"its summary keys and finding kinds differ per client — read the report rather than assuming " +
|
|
65
|
+
"one shape. Runs locally and needs no SpecGuard deployment or API key.",
|
|
58
66
|
inputSchema: {
|
|
59
67
|
type: "object",
|
|
60
68
|
properties: {
|
|
61
69
|
project_dir: {
|
|
62
70
|
type: "string",
|
|
63
|
-
description: "Absolute path to the
|
|
64
|
-
"
|
|
71
|
+
description: "Absolute path to the project to lint — the Ruby project root (Gemfile, spec/) or the " +
|
|
72
|
+
"JS/TS project root (package.json, test sources). Defaults to the directory this server " +
|
|
73
|
+
"was started in.",
|
|
65
74
|
},
|
|
66
75
|
paths: {
|
|
67
76
|
type: "array",
|
|
68
77
|
items: { type: "string" },
|
|
69
|
-
description: "Specific
|
|
70
|
-
"under it outside dependency/build directories.
|
|
78
|
+
description: "Specific test files to check, relative to project_dir. Omit to check every spec file " +
|
|
79
|
+
"under it outside dependency/build directories (*_spec.rb for specguard-lint; " +
|
|
80
|
+
".ts/.tsx/.js/.jsx/.mjs/.cjs for specguard lint). An empty list is an error, not a way " +
|
|
71
81
|
"to say 'everything'. Cannot be combined with `changed`.",
|
|
72
82
|
},
|
|
73
83
|
changed: {
|
|
74
84
|
type: "boolean",
|
|
75
85
|
description: "Check the spec files the branch changed since the merge base with the default branch — " +
|
|
76
|
-
"the mode CI uses.
|
|
86
|
+
"the mode CI uses. Needs a linter version that ships --changed: the Ruby gem and " +
|
|
87
|
+
"@yatfa/specguard main do, but @yatfa/specguard 0.1.1 on npm does not and exits 2 with " +
|
|
88
|
+
"`invalid option: --changed`. Untracked spec files count as changed too, so a brand-new spec needs " +
|
|
77
89
|
"no `git add`; `--exclude-standard` keeps `.gitignore`d paths out of the untracked leg " +
|
|
78
90
|
"alone, and a tracked file is never subject to `.gitignore`, so the dependency/build " +
|
|
79
91
|
"directory fence is what holds ignored tracked paths out of the selection. When " +
|
|
@@ -141,8 +153,9 @@ export default lintIntentAnnotations;
|
|
|
141
153
|
* names one tool's variable would misdirect every later tool that spawns
|
|
142
154
|
* something else.
|
|
143
155
|
*/
|
|
144
|
-
const LINT_COMMAND_HINT = "Set SPECGUARD_LINT_COMMAND to the command that runs
|
|
145
|
-
'
|
|
156
|
+
const LINT_COMMAND_HINT = "Set SPECGUARD_LINT_COMMAND to the command that runs the linter here — " +
|
|
157
|
+
'for a bundled Ruby project that is usually "bundle exec specguard-lint", ' +
|
|
158
|
+
'for a JS/TS project "npx -p @yatfa/specguard specguard lint".';
|
|
146
159
|
/**
|
|
147
160
|
* `project_dir` names a directory that exists, or the failure says exactly that.
|
|
148
161
|
*
|
|
@@ -167,14 +180,14 @@ async function requireProjectDir(projectDir) {
|
|
|
167
180
|
}
|
|
168
181
|
catch {
|
|
169
182
|
throw new CommandError(`\`project_dir\` ${JSON.stringify(projectDir)} does not exist${resolvedNote(projectDir)}. ` +
|
|
170
|
-
"Pass the absolute path of the project root — the directory holding its Gemfile
|
|
171
|
-
"
|
|
183
|
+
"Pass the absolute path of the project root — the directory holding its Gemfile " +
|
|
184
|
+
"(Ruby) or package.json (JS/TS) — or omit `project_dir` to lint the directory this server was started in. " +
|
|
172
185
|
"(specguard-lint itself was not the problem.)");
|
|
173
186
|
}
|
|
174
187
|
if (!isDirectory) {
|
|
175
188
|
throw new CommandError(`\`project_dir\` ${JSON.stringify(projectDir)} is not a directory${resolvedNote(projectDir)}. ` +
|
|
176
|
-
"Pass the project root — the directory holding its Gemfile
|
|
177
|
-
"it. To lint one file, pass it in `paths` instead.");
|
|
189
|
+
"Pass the project root — the directory holding its Gemfile (Ruby) or package.json " +
|
|
190
|
+
"(JS/TS) — not a file inside it. To lint one file, pass it in `paths` instead.");
|
|
178
191
|
}
|
|
179
192
|
}
|
|
180
193
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lint-intent-annotations.js","sourceRoot":"","sources":["../../../src/tools/lint-intent-annotations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAsB,MAAM,2BAA2B,CAAC;AACtG,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG5D
|
|
1
|
+
{"version":3,"file":"lint-intent-annotations.js","sourceRoot":"","sources":["../../../src/tools/lint-intent-annotations.ts"],"names":[],"mappings":"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"}
|
|
@@ -4,7 +4,9 @@ import type { ToolDefinition } from "./types.js";
|
|
|
4
4
|
* platform by SPGD-703 (`specguard` `c43dc19`, 2026-08-28), which added the
|
|
5
5
|
* `near_duplicates` block to `RepositoryOverview` behind an opt-in ask.
|
|
6
6
|
*
|
|
7
|
-
* == What the block is, and why it is behind an ask at all
|
|
7
|
+
* == What the block is, and why it is behind an ask at all (this section is
|
|
8
|
+
* the pre-SPGD-1474 story — the cost was live on the request; the next section
|
|
9
|
+
* is what changed)
|
|
8
10
|
*
|
|
9
11
|
* It is the suite-wide near-duplicate census: which tests READ alike — same
|
|
10
12
|
* body text, not same file — clustered by the engine SPGD-369 shipped
|
|
@@ -21,6 +23,27 @@ import type { ToolDefinition } from "./types.js";
|
|
|
21
23
|
* else. Splitting the tools splits the cost along exactly the line the server
|
|
22
24
|
* drew.
|
|
23
25
|
*
|
|
26
|
+
* == SPGD-1474: the census is computed at ingest, and this read is stored
|
|
27
|
+
*
|
|
28
|
+
* The minutes-scale compute no longer sits behind the request (and could never
|
|
29
|
+
* fit this bridge's 30-second default deadline). The server computes the census
|
|
30
|
+
* once per write that moves its inputs — at each ingest, after identity
|
|
31
|
+
* resolution settles the run's identities, and again when a run is deleted from
|
|
32
|
+
* the repository (which can move the run the weight figures are weighed on) —
|
|
33
|
+
* persists it, and serves the stored artifact, so a call here costs one stored
|
|
34
|
+
* read and returns in milliseconds. The opt-in ask is unchanged wire contract
|
|
35
|
+
* (`?near_duplicates=` still opens the block; the plain overview still answers
|
|
36
|
+
* `null` without it), and the tool split still stands: one call, one census,
|
|
37
|
+
* no accidental cost. What changed is the latency story and the honesty
|
|
38
|
+
* machinery around it: the block carries `computed_at` (when the stored
|
|
39
|
+
* artifact was taken) and `weighed_run_id` (which run its weight figures are
|
|
40
|
+
* from), so a consumer can always tell how fresh the census it is reading is.
|
|
41
|
+
* A request arriving between a completed write and the finished recompute
|
|
42
|
+
* serves the PREVIOUS stored census with its own stamp — never a live
|
|
43
|
+
* computation, never an unstamped answer. Between those writes (an ingest, or a
|
|
44
|
+
* run deletion) the stored census is exactly what a live computation would
|
|
45
|
+
* return: the inputs change only there.
|
|
46
|
+
*
|
|
24
47
|
* == The ask is always sent, and always spelled `"true"`
|
|
25
48
|
*
|
|
26
49
|
* The server reads only whether the parameter is PRESENT
|
|
@@ -5,7 +5,9 @@ import { optionalString } from "./args.js";
|
|
|
5
5
|
* platform by SPGD-703 (`specguard` `c43dc19`, 2026-08-28), which added the
|
|
6
6
|
* `near_duplicates` block to `RepositoryOverview` behind an opt-in ask.
|
|
7
7
|
*
|
|
8
|
-
* == What the block is, and why it is behind an ask at all
|
|
8
|
+
* == What the block is, and why it is behind an ask at all (this section is
|
|
9
|
+
* the pre-SPGD-1474 story — the cost was live on the request; the next section
|
|
10
|
+
* is what changed)
|
|
9
11
|
*
|
|
10
12
|
* It is the suite-wide near-duplicate census: which tests READ alike — same
|
|
11
13
|
* body text, not same file — clustered by the engine SPGD-369 shipped
|
|
@@ -22,6 +24,27 @@ import { optionalString } from "./args.js";
|
|
|
22
24
|
* else. Splitting the tools splits the cost along exactly the line the server
|
|
23
25
|
* drew.
|
|
24
26
|
*
|
|
27
|
+
* == SPGD-1474: the census is computed at ingest, and this read is stored
|
|
28
|
+
*
|
|
29
|
+
* The minutes-scale compute no longer sits behind the request (and could never
|
|
30
|
+
* fit this bridge's 30-second default deadline). The server computes the census
|
|
31
|
+
* once per write that moves its inputs — at each ingest, after identity
|
|
32
|
+
* resolution settles the run's identities, and again when a run is deleted from
|
|
33
|
+
* the repository (which can move the run the weight figures are weighed on) —
|
|
34
|
+
* persists it, and serves the stored artifact, so a call here costs one stored
|
|
35
|
+
* read and returns in milliseconds. The opt-in ask is unchanged wire contract
|
|
36
|
+
* (`?near_duplicates=` still opens the block; the plain overview still answers
|
|
37
|
+
* `null` without it), and the tool split still stands: one call, one census,
|
|
38
|
+
* no accidental cost. What changed is the latency story and the honesty
|
|
39
|
+
* machinery around it: the block carries `computed_at` (when the stored
|
|
40
|
+
* artifact was taken) and `weighed_run_id` (which run its weight figures are
|
|
41
|
+
* from), so a consumer can always tell how fresh the census it is reading is.
|
|
42
|
+
* A request arriving between a completed write and the finished recompute
|
|
43
|
+
* serves the PREVIOUS stored census with its own stamp — never a live
|
|
44
|
+
* computation, never an unstamped answer. Between those writes (an ingest, or a
|
|
45
|
+
* run deletion) the stored census is exactly what a live computation would
|
|
46
|
+
* return: the inputs change only there.
|
|
47
|
+
*
|
|
25
48
|
* == The ask is always sent, and always spelled `"true"`
|
|
26
49
|
*
|
|
27
50
|
* The server reads only whether the parameter is PRESENT
|
|
@@ -78,10 +101,20 @@ const nearDuplicateClusters = {
|
|
|
78
101
|
"(same body text, whatever file they sit in), clustered by similarity. Answers the refactoring " +
|
|
79
102
|
"question the overview's per-run rankings cannot: where is the same test written twice, before " +
|
|
80
103
|
"you delete or merge anything. " +
|
|
81
|
-
"
|
|
82
|
-
"
|
|
83
|
-
"
|
|
84
|
-
"
|
|
104
|
+
"This call is SERVED STORED: the server computes the census at each ingest and on each run " +
|
|
105
|
+
"deletion and keeps it, so the " +
|
|
106
|
+
"answer returns in milliseconds instead of running the minutes-scale computation that used to " +
|
|
107
|
+
"sit behind the ask (and never fit this bridge's 30-second deadline). READ THE STAMP: " +
|
|
108
|
+
"`computed_at` is when the stored artifact was taken and `weighed_run_id` is the run its weight " +
|
|
109
|
+
"figures are from — a census read shortly after an ingest or a run deletion may be the PREVIOUS " +
|
|
110
|
+
"artifact, stamped, " +
|
|
111
|
+
"while the recompute runs; between such writes the stored census is exactly what a live computation " +
|
|
112
|
+
"would return. The opt-in ask is unchanged wire contract: the server answers `near_duplicates: " +
|
|
113
|
+
"null` on the plain overview (no ask, not one query), and `null` ON THIS TOOL means no census has " +
|
|
114
|
+
"been computed for the repository yet — a repository that has never ingested, read in the window " +
|
|
115
|
+
"before its first computation lands. It is never a live computation and never zeros: a repository " +
|
|
116
|
+
"whose every test reads differently serves a stored block with `clusters: []` and real counts. " +
|
|
117
|
+
"Calling this tool IS the ask; nothing about the " +
|
|
85
118
|
"census is choosable — the clusters are the repository's, computed over every run, and one call " +
|
|
86
119
|
"returns them all. WHICH repository is censused is the one choice there is: pass `repository` " +
|
|
87
120
|
"(a numeric id from `list_repositories`) to census that named repository under either member " +
|
|
@@ -102,6 +135,21 @@ const nearDuplicateClusters = {
|
|
|
102
135
|
"[strongest, weakest]: membership is transitive, similarity is not, and the gap between the edges " +
|
|
103
136
|
"is the merge risk. `total_seconds` is raw and `null` where nothing was timed — never a zero " +
|
|
104
137
|
"that would read as free. " +
|
|
138
|
+
"READ THE LAYER CUT AS DECLARATIONS, NEVER AS A GUESS: `layer_source` at the head of the block " +
|
|
139
|
+
"states where the layer dimension comes from — it is 'declared via the intent protocol' when at " +
|
|
140
|
+
"least one clustered member's examples declared a layer, and `null` on a suite that declared " +
|
|
141
|
+
"nothing, which is absence STATED, not an empty grouping to read as a finding. Each cluster " +
|
|
142
|
+
"carries `layer_redundancy` — `cross_layer` when its members declared two or more DISTINCT " +
|
|
143
|
+
"layers (the same behaviour covered on several levels: the test-pyramid question), `same_layer` " +
|
|
144
|
+
"when confined to one (a plain duplicate), `null` when its members declared nothing, which is " +
|
|
145
|
+
"neither and must not be folded into `same_layer` — and `layer_groups`, the members grouped by " +
|
|
146
|
+
"the layer their examples declared, alphabetically, with the undeclared LAST as the " +
|
|
147
|
+
"`layer: null` group. No path or directory convention is consulted anywhere in the cut: a " +
|
|
148
|
+
"`request`-declared test living under spec/models is reported `request`, because declarations " +
|
|
149
|
+
"do not lie and paths do. A member whose own examples declared two layers appears in EACH group " +
|
|
150
|
+
"it declared — so the groups' sizes can exceed `member_count` by exactly those members, which " +
|
|
151
|
+
"is the finding, not an arithmetic bug — and a member that declared nothing stays in its " +
|
|
152
|
+
"cluster's null group, never dropped. " +
|
|
105
153
|
"A quiet answer is a FINDING, not a gap: `clusters: []` with a real `identity_count` is the " +
|
|
106
154
|
"success state (nothing reads alike), and the three silences — nothing ingested " +
|
|
107
155
|
"(`recorded_count: 0`), nothing embedded (`identity_count: 0`), nothing alike — are kept " +
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C
|
|
1
|
+
{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"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"}
|