@aiwg/cli 2026.10.14 → 2026.10.16
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/agentic/code/addons/aiwg-utils/rules/anti-laziness.core.md +13 -0
- package/agentic/code/addons/aiwg-utils/rules/anti-laziness.md +118 -0
- package/agentic/code/providers/pi/aiwg-bridge.ts +45 -7
- package/dist/src/artifacts/citation-parser.js +7 -6
- package/dist/src/artifacts/corpus-tools/citation-densify.js +4 -2
- package/dist/src/artifacts/corpus-tools/cli.js +37 -0
- package/dist/src/artifacts/corpus-tools/discovery-log.js +27 -25
- package/dist/src/artifacts/corpus-tools/expand-cli.js +90 -0
- package/dist/src/artifacts/corpus-tools/expand-dates.js +107 -0
- package/dist/src/artifacts/corpus-tools/expand-queue.js +41 -0
- package/dist/src/artifacts/corpus-tools/expand-review.js +104 -0
- package/dist/src/artifacts/corpus-tools/expand-state.js +56 -0
- package/dist/src/artifacts/corpus-tools/expand.js +124 -0
- package/dist/src/artifacts/corpus-tools/induction-audit.js +7 -6
- package/dist/src/artifacts/corpus-tools/integrity-scan.js +3 -3
- package/dist/src/artifacts/corpus-tools/radar-shared.js +7 -9
- package/dist/src/artifacts/corpus-tools/ref-files.js +11 -0
- package/dist/src/artifacts/corpus-tools/resolve-cli.js +99 -0
- package/dist/src/artifacts/corpus-tools/resolve-corpus.js +41 -0
- package/dist/src/artifacts/corpus-tools/resolve.js +119 -0
- package/dist/src/artifacts/corpus-tools/retrieval-lab.js +2 -1
- package/dist/src/artifacts/corpus-tools/sidecar-lint.js +4 -4
- package/dist/src/artifacts/corpus-tools/sidecar-repair.js +2 -1
- package/dist/src/artifacts/corpus-views/ref-parser.js +3 -17
- package/dist/src/artifacts/graph-query.js +5 -3
- package/dist/src/artifacts/hybrid-query.js +11 -2
- package/dist/src/artifacts/index-refresh.js +2 -0
- package/dist/src/cli/handlers/daemon.js +17 -1
- package/dist/src/cli/handlers/doctor-args.js +45 -0
- package/dist/src/cli/handlers/doctor-help.js +8 -3
- package/dist/src/cli/handlers/index.js +2 -2
- package/dist/src/cli/handlers/models-resource-sample.js +10 -0
- package/dist/src/cli/handlers/models.js +3 -2
- package/dist/src/cli/handlers/regenerate.js +8 -16
- package/dist/src/cli/handlers/sessions.js +7 -7
- package/dist/src/cli/handlers/subcommands.js +8 -0
- package/dist/src/cli/handlers/update.js +157 -0
- package/dist/src/cli/handlers/use.js +14 -4
- package/dist/src/cli/handlers/utilities.js +3 -586
- package/dist/src/cli/handlers/utility-doctor.js +412 -0
- package/dist/src/cli/services/deployment-verification.js +0 -1
- package/dist/src/config/aiwg-config.js +2 -1
- package/dist/src/config/authorization-cli.js +7 -3
- package/dist/src/config/dispatch-thresholds-runtime.d.mts +3 -2
- package/dist/src/config/dispatch-thresholds-runtime.mjs +17 -7
- package/dist/src/config/framework-aliases.js +12 -0
- package/dist/src/config/host-resource-report.d.mts +19 -0
- package/dist/src/config/host-resource-report.mjs +80 -0
- package/dist/src/config/host-resource-runtime.d.mts +34 -0
- package/dist/src/config/host-resource-runtime.mjs +293 -0
- package/dist/src/config/installed-selection.js +22 -0
- package/dist/src/config/worker-context.js +33 -4
- package/dist/src/config/worker-invocation-marker.d.mts +1 -0
- package/dist/src/config/worker-invocation-marker.mjs +2 -0
- package/dist/src/decision/heldout/access.js +74 -0
- package/dist/src/decision/heldout/calibration.js +1 -0
- package/dist/src/decision/heldout/collector.js +9 -2
- package/dist/src/effects/verifiers/file.js +22 -5
- package/dist/src/extensions/claude-attribution.js +82 -0
- package/dist/src/extensions/claude-hooks-installer.js +115 -69
- package/dist/src/extensions/commands/daemon.js +109 -0
- package/dist/src/extensions/commands/definitions.js +5 -89
- package/dist/src/features/catalog.js +1 -1
- package/dist/src/gates/evaluate.js +2 -2
- package/dist/src/gates/heldout.js +52 -0
- package/dist/src/gates/index.js +2 -1
- package/dist/src/lint/check-patterns.js +163 -0
- package/dist/src/lint/checks.js +268 -0
- package/dist/src/lint/reference-resolution.js +54 -0
- package/dist/src/lint/runner.js +3 -465
- package/dist/src/mcp/helpers.mjs +11 -1
- package/dist/src/memory/project-registry.js +44 -4
- package/dist/src/models/worker-installation-store.mjs +228 -0
- package/dist/src/models/worker-installation.mjs +7 -162
- package/dist/src/models/worker-plan.js +36 -5
- package/dist/src/models/wrapper-deployment.js +25 -12
- package/dist/src/models/wrapper-enforcement.js +47 -7
- package/dist/src/network-analysis/research.js +2 -1
- package/dist/src/policy/hitl-check.js +14 -4
- package/dist/src/policy/hitl-consume.js +54 -0
- package/dist/src/policy/hitl-receipt.js +2 -0
- package/dist/src/policy/hitl.js +11 -3
- package/dist/src/providers/provider-context-contracts.js +162 -0
- package/dist/src/providers/provider-definition-schema.js +136 -0
- package/dist/src/providers/provider-definitions.js +8 -1298
- package/dist/src/providers/provider-seeds-1.js +360 -0
- package/dist/src/providers/provider-seeds-2.js +387 -0
- package/dist/src/providers/provider-seeds-3.js +262 -0
- package/dist/src/research/clients/arxiv.js +14 -34
- package/dist/src/research/clients/base.js +53 -26
- package/dist/src/research/clients/crossref.js +9 -1
- package/dist/src/research/clients/semantic-scholar.js +73 -44
- package/dist/src/research/identity.js +117 -0
- package/dist/src/research/index.js +1 -0
- package/dist/src/research/query-cli.js +3 -87
- package/dist/src/research/query-options.js +87 -0
- package/dist/src/research/reference-match.js +135 -0
- package/dist/src/research/services/acquisition.js +9 -7
- package/dist/src/research/services/citation.js +5 -2
- package/dist/src/research/types.js +2 -0
- package/dist/src/rules/core-startup.d.mts +2 -0
- package/dist/src/rules/core-startup.mjs +31 -0
- package/dist/src/serve/mission-conductor.js +48 -4
- package/dist/src/sessions/adapters/grok-build-native.js +23 -0
- package/dist/src/sessions/adapters/grok-build.js +14 -7
- package/dist/src/sessions/workspace-discovery.js +5 -5
- package/dist/src/smiths/context-pipeline/agents-md.js +34 -0
- package/dist/src/smiths/context-pipeline/aiwg-md.js +19 -46
- package/dist/src/smiths/context-pipeline/bridge-ownership.js +50 -0
- package/dist/src/smiths/context-pipeline/claude-hook.js +1 -1
- package/dist/src/smiths/context-pipeline/code-regions.js +28 -0
- package/dist/src/smiths/context-pipeline/finalization.js +81 -51
- package/dist/src/smiths/context-pipeline/generator.js +49 -114
- package/dist/src/smiths/context-pipeline/managed-hook.js +11 -1
- package/dist/src/smiths/context-pipeline/muse-bridge.js +2 -2
- package/dist/src/smiths/context-pipeline/provider-policy.js +6 -12
- package/dist/src/smiths/context-pipeline/workspace-audit.js +299 -0
- package/dist/src/smiths/context-pipeline/workspace-bootstrap.js +148 -0
- package/dist/src/smiths/context-pipeline/workspace-context-shared.js +111 -0
- package/dist/src/smiths/context-pipeline/workspace-context.js +8 -1373
- package/dist/src/smiths/context-pipeline/workspace-doctor.js +192 -0
- package/dist/src/smiths/context-pipeline/workspace-document.js +201 -0
- package/dist/src/smiths/context-pipeline/workspace-extraction.js +205 -0
- package/dist/src/smiths/context-pipeline/workspace-migration.js +250 -0
- package/package.json +13 -2
- package/schemas/decision/D29Study.v10.schema.json +65 -0
- package/tools/agents/deploy-agents.mjs +12 -123
- package/tools/agents/providers/antigravity.mjs +1 -1
- package/tools/agents/providers/claude-post-deploy.mjs +12 -1
- package/tools/agents/providers/context-write.mjs +16 -0
- package/tools/agents/providers/grok-build.mjs +8 -5
- package/tools/agents/providers/hermes-skill-lifecycle.mjs +144 -0
- package/tools/agents/providers/hermes-startup.mjs +209 -0
- package/tools/agents/providers/hermes.mjs +9 -359
- package/tools/agents/providers/model-wrapper.mjs +5 -1
- package/tools/agents/providers/muse.mjs +3 -3
- package/tools/agents/providers/pi.mjs +4 -2
- package/tools/agents/providers/rule-delivery-surface.mjs +332 -0
- package/tools/agents/providers/rule-delivery.mjs +20 -1346
- package/tools/agents/providers/rule-deployment-commit.mjs +144 -0
- package/tools/agents/providers/rule-deployment-prepare.mjs +452 -0
- package/tools/agents/providers/rule-deployment-state.mjs +300 -0
- package/tools/agents/providers/rule-presentation.mjs +13 -4
- package/tools/agents/providers/rule-projection.mjs +119 -0
- package/tools/agents/providers/rule-startup.mjs +70 -0
- package/tools/agents/providers/stale-artifact-prune.mjs +128 -0
- package/tools/agents/providers/warp.mjs +2 -2
- package/tools/agents/providers/windsurf.mjs +11 -57
- package/tools/daemon/README.md +511 -0
- package/tools/daemon/adapters/base-adapter.mjs +84 -0
- package/tools/daemon/adapters/webhook-adapter.mjs +107 -0
- package/tools/daemon/agent-supervisor.mjs +299 -0
- package/tools/daemon/automation-engine.mjs +310 -0
- package/tools/daemon/autonomous-engine.mjs +346 -0
- package/tools/daemon/behavior-loader.mjs +316 -0
- package/tools/daemon/behavior.mjs +174 -0
- package/tools/daemon/concierge/intent-router.mjs +401 -0
- package/tools/daemon/concierge/orchestrator.mjs +272 -0
- package/tools/daemon/concierge/response-translator.mjs +462 -0
- package/tools/daemon/config.mjs +377 -0
- package/tools/daemon/cron-scheduler.mjs +178 -0
- package/tools/daemon/daemon-main.mjs +1169 -0
- package/tools/daemon/event-router.mjs +84 -0
- package/tools/daemon/file-watcher.mjs +383 -0
- package/tools/daemon/index.mjs +1181 -0
- package/tools/daemon/init-profile.mjs +124 -0
- package/tools/daemon/ipc-client.mjs +197 -0
- package/tools/daemon/ipc-ops-handlers.mjs +236 -0
- package/tools/daemon/ipc-server.mjs +275 -0
- package/tools/daemon/maintenance-owner.mjs +79 -0
- package/tools/daemon/memory-manager.mjs +386 -0
- package/tools/daemon/message-router.mjs +194 -0
- package/tools/daemon/provider-watcher.mjs +585 -0
- package/tools/daemon/pty-adapter.mjs +420 -0
- package/tools/daemon/repl-chat.mjs +359 -0
- package/tools/daemon/resource-bounds.mjs +88 -0
- package/tools/daemon/sandbox-transport.mjs +295 -0
- package/tools/daemon/scheduled-task-runner.mjs +535 -0
- package/tools/daemon/task-store.mjs +450 -0
- package/tools/daemon/tmux-manager.mjs +324 -0
- package/tools/daemon/update-policy.mjs +517 -0
- package/tools/daemon/web-server.mjs +399 -0
- package/tools/daemon/web-ui/index.html +585 -0
- package/tools/daemon/web-ui/styles.css +156 -0
- package/tools/docker/Dockerfile.daemon +35 -0
- package/tools/docker/container-manager.mjs +291 -0
- package/tools/messaging/adapter-registry.mjs +230 -0
- package/tools/messaging/adapters/base.mjs +326 -0
- package/tools/messaging/adapters/discord.mjs +462 -0
- package/tools/messaging/adapters/slack.mjs +402 -0
- package/tools/messaging/adapters/telegram.mjs +552 -0
- package/tools/messaging/chat-handler.mjs +297 -0
- package/tools/messaging/command-router.mjs +269 -0
- package/tools/messaging/event-bus.mjs +199 -0
- package/tools/messaging/index.mjs +456 -0
- package/tools/messaging/message-formatter.mjs +320 -0
- package/tools/messaging/room-manager.mjs +277 -0
- package/tools/messaging/types.mjs +94 -0
- package/tools/plugin/plugin-links.mjs +3 -0
- package/tools/providers/pi-bridge-policy.mjs +4 -0
- package/tools/ralph-external/daemon-supervisor.mjs +394 -0
- package/tools/ralph-external/lib/behavior-registry.mjs +270 -0
- package/tools/ralph-external/lib/worker-invocation-processes.mjs +3 -2
- package/tools/ralph-external/lib/worker-isolation-args.mjs +217 -0
- package/tools/ralph-external/lib/worker-isolation-status.mjs +19 -0
- package/tools/ralph-external/lib/worker-isolation.mjs +11 -237
- package/tools/ralph-external/lib/worker-overflow.mjs +10 -2
- package/tools/ralph-external/lib/worker-unit-cleanup.mjs +72 -0
- package/tools/ralph-external/session-launcher.mjs +7 -7
- package/tools/scripts/resource-preflight.mjs +3 -242
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* @module research/clients/arxiv
|
|
5
5
|
*/
|
|
6
6
|
import { BaseClient } from './base.js';
|
|
7
|
+
import { normalizeDoi, parseArxivId } from '../identity.js';
|
|
7
8
|
import { ResearchError, ResearchErrorCode, } from '../types.js';
|
|
8
9
|
/**
|
|
9
10
|
* arXiv API client
|
|
@@ -14,9 +15,9 @@ export class ArxivClient extends BaseClient {
|
|
|
14
15
|
baseUrl: 'http://export.arxiv.org/api',
|
|
15
16
|
timeout: 30000,
|
|
16
17
|
rateLimit: {
|
|
17
|
-
maxTokens:
|
|
18
|
+
maxTokens: 1,
|
|
18
19
|
refillRate: 1 / 3, // 1 request per 3 seconds
|
|
19
|
-
currentTokens:
|
|
20
|
+
currentTokens: 1,
|
|
20
21
|
lastRefill: Date.now(),
|
|
21
22
|
},
|
|
22
23
|
retry: {
|
|
@@ -33,12 +34,12 @@ export class ArxivClient extends BaseClient {
|
|
|
33
34
|
*/
|
|
34
35
|
async getPaperById(arxivId) {
|
|
35
36
|
// Normalize arXiv ID (remove version if present)
|
|
36
|
-
const normalizedId = arxivId
|
|
37
|
+
const normalizedId = parseArxivId(arxivId)?.id ?? arxivId;
|
|
37
38
|
const url = this.buildUrl('/query', {
|
|
38
39
|
id_list: normalizedId,
|
|
39
40
|
max_results: 1,
|
|
40
41
|
});
|
|
41
|
-
const xmlText = await this.
|
|
42
|
+
const xmlText = await this.requestText(url);
|
|
42
43
|
const papers = this.parseAtomFeed(xmlText);
|
|
43
44
|
if (papers.length === 0) {
|
|
44
45
|
throw new ResearchError(ResearchErrorCode.RF_300, `arXiv paper not found: ${arxivId}`);
|
|
@@ -55,7 +56,7 @@ export class ArxivClient extends BaseClient {
|
|
|
55
56
|
start: offset,
|
|
56
57
|
max_results: limit,
|
|
57
58
|
});
|
|
58
|
-
const xmlText = await this.
|
|
59
|
+
const xmlText = await this.requestText(url);
|
|
59
60
|
const papers = this.parseAtomFeed(xmlText);
|
|
60
61
|
// arXiv doesn't provide total count, so we estimate
|
|
61
62
|
const hasMore = papers.length === limit;
|
|
@@ -67,32 +68,6 @@ export class ArxivClient extends BaseClient {
|
|
|
67
68
|
hasMore,
|
|
68
69
|
};
|
|
69
70
|
}
|
|
70
|
-
/**
|
|
71
|
-
* Request XML from arXiv API
|
|
72
|
-
*/
|
|
73
|
-
async requestXml(url) {
|
|
74
|
-
await this.rateLimiter.acquire();
|
|
75
|
-
const controller = new AbortController();
|
|
76
|
-
const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
|
|
77
|
-
try {
|
|
78
|
-
const response = await fetch(url, {
|
|
79
|
-
signal: controller.signal,
|
|
80
|
-
});
|
|
81
|
-
if (!response.ok) {
|
|
82
|
-
throw new ResearchError(ResearchErrorCode.RF_200, `arXiv API error: ${response.status}`);
|
|
83
|
-
}
|
|
84
|
-
return await response.text();
|
|
85
|
-
}
|
|
86
|
-
catch (error) {
|
|
87
|
-
if (error instanceof Error && error.name === 'AbortError') {
|
|
88
|
-
throw new ResearchError(ResearchErrorCode.RF_104, `Request timeout after ${this.config.timeout}ms`, error);
|
|
89
|
-
}
|
|
90
|
-
throw error;
|
|
91
|
-
}
|
|
92
|
-
finally {
|
|
93
|
-
clearTimeout(timeoutId);
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
71
|
/**
|
|
97
72
|
* Parse Atom XML feed from arXiv
|
|
98
73
|
*/
|
|
@@ -125,7 +100,10 @@ export class ArxivClient extends BaseClient {
|
|
|
125
100
|
});
|
|
126
101
|
};
|
|
127
102
|
const id = extractTag('id');
|
|
128
|
-
const
|
|
103
|
+
const identity = parseArxivId(id);
|
|
104
|
+
if (!identity)
|
|
105
|
+
throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid arXiv entry identifier');
|
|
106
|
+
const arxivId = identity.id;
|
|
129
107
|
const title = extractTag('title').replace(/\s+/g, ' ');
|
|
130
108
|
const summary = extractTag('summary').replace(/\s+/g, ' ');
|
|
131
109
|
const published = extractTag('published');
|
|
@@ -133,8 +111,8 @@ export class ArxivClient extends BaseClient {
|
|
|
133
111
|
const authorNames = extractAllTags('name');
|
|
134
112
|
const authors = authorNames.map((name) => ({ name }));
|
|
135
113
|
// Extract DOI if present
|
|
136
|
-
const doiMatch = entry.match(
|
|
137
|
-
const doi = doiMatch ? doiMatch[1] : undefined;
|
|
114
|
+
const doiMatch = entry.match(/<arxiv:doi[^>]*>([^<]+)<\/arxiv:doi>/i);
|
|
115
|
+
const doi = doiMatch ? normalizeDoi(doiMatch[1]) : undefined;
|
|
138
116
|
// Extract PDF link
|
|
139
117
|
const pdfLinkMatch = entry.match(/<link[^>]*title="pdf"[^>]*href="([^"]+)"/i);
|
|
140
118
|
const pdfUrl = pdfLinkMatch ? pdfLinkMatch[1] : undefined;
|
|
@@ -145,6 +123,8 @@ export class ArxivClient extends BaseClient {
|
|
|
145
123
|
year,
|
|
146
124
|
abstract: summary,
|
|
147
125
|
arxivId,
|
|
126
|
+
arxivVersion: identity.version,
|
|
127
|
+
publicationDate: published || undefined,
|
|
148
128
|
doi,
|
|
149
129
|
pdfUrl,
|
|
150
130
|
type: 'preprint',
|
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
* @module research/clients/base
|
|
5
5
|
*/
|
|
6
6
|
import { ResearchError, ResearchErrorCode, } from '../types.js';
|
|
7
|
+
// Bound server-directed cooldowns for both retries and later shared-client requests.
|
|
8
|
+
const MAX_RETRY_AFTER_MS = 30_000;
|
|
7
9
|
/**
|
|
8
10
|
* Token bucket rate limiter
|
|
9
11
|
*/
|
|
@@ -11,6 +13,8 @@ export class RateLimiter {
|
|
|
11
13
|
config;
|
|
12
14
|
tokens;
|
|
13
15
|
lastRefill;
|
|
16
|
+
blockedUntil = 0;
|
|
17
|
+
queue = Promise.resolve();
|
|
14
18
|
constructor(config) {
|
|
15
19
|
this.config = config;
|
|
16
20
|
this.tokens = config.currentTokens;
|
|
@@ -29,19 +33,25 @@ export class RateLimiter {
|
|
|
29
33
|
/**
|
|
30
34
|
* Acquire a token, waiting if necessary
|
|
31
35
|
*/
|
|
32
|
-
|
|
33
|
-
this.
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
36
|
+
acquire() {
|
|
37
|
+
const pending = this.queue.then(() => this.acquireToken());
|
|
38
|
+
this.queue = pending.catch(() => { });
|
|
39
|
+
return pending;
|
|
40
|
+
}
|
|
41
|
+
/** Share a server cooldown with subsequent requests, including exhausted retries. */
|
|
42
|
+
defer(ms) {
|
|
43
|
+
this.blockedUntil = Math.max(this.blockedUntil, Date.now() + ms);
|
|
44
|
+
}
|
|
45
|
+
async acquireToken() {
|
|
46
|
+
for (;;) {
|
|
47
|
+
this.refill();
|
|
48
|
+
const waitMs = Math.max(this.blockedUntil - Date.now(), (1 - this.tokens) / this.config.refillRate * 1000);
|
|
49
|
+
if (waitMs <= 0) {
|
|
50
|
+
this.tokens -= 1;
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
await this.sleep(Math.ceil(waitMs));
|
|
37
54
|
}
|
|
38
|
-
// Calculate wait time
|
|
39
|
-
const deficit = 1 - this.tokens;
|
|
40
|
-
const waitMs = (deficit / this.config.refillRate) * 1000;
|
|
41
|
-
await this.sleep(waitMs);
|
|
42
|
-
// Refill again after waiting
|
|
43
|
-
this.refill();
|
|
44
|
-
this.tokens -= 1;
|
|
45
55
|
}
|
|
46
56
|
sleep(ms) {
|
|
47
57
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
@@ -70,15 +80,19 @@ export class BaseClient {
|
|
|
70
80
|
* Execute an HTTP request with rate limiting and retry logic
|
|
71
81
|
*/
|
|
72
82
|
async request(url, options = {}) {
|
|
73
|
-
// Apply rate limiting
|
|
74
|
-
await this.rateLimiter.acquire();
|
|
75
83
|
// Execute with retry
|
|
76
84
|
return this.executeWithRetry(url, options);
|
|
77
85
|
}
|
|
86
|
+
/** XML clients use the same limiter, timeout and HTTP retry policy as JSON. */
|
|
87
|
+
requestText(url, options = {}) {
|
|
88
|
+
return this.executeWithRetry(url, options, 0, undefined, response => response.text());
|
|
89
|
+
}
|
|
78
90
|
/**
|
|
79
91
|
* Execute request with exponential backoff retry
|
|
80
92
|
*/
|
|
81
|
-
async executeWithRetry(url, options, attempt = 0, firstError) {
|
|
93
|
+
async executeWithRetry(url, options, attempt = 0, firstError, read = response => response.json()) {
|
|
94
|
+
// Every attempt consumes a token, after any retry backoff and before timeout.
|
|
95
|
+
await this.rateLimiter.acquire();
|
|
82
96
|
const controller = new AbortController();
|
|
83
97
|
let timeoutId;
|
|
84
98
|
try {
|
|
@@ -104,7 +118,7 @@ export class BaseClient {
|
|
|
104
118
|
const error = await this.handleHttpError(response);
|
|
105
119
|
throw error;
|
|
106
120
|
}
|
|
107
|
-
return
|
|
121
|
+
return await read(response);
|
|
108
122
|
}
|
|
109
123
|
catch (error) {
|
|
110
124
|
// Clear timeout on error
|
|
@@ -117,13 +131,18 @@ export class BaseClient {
|
|
|
117
131
|
}
|
|
118
132
|
// Track the first error for better error reporting
|
|
119
133
|
const currentFirstError = firstError || (error instanceof ResearchError ? error : undefined);
|
|
120
|
-
//
|
|
134
|
+
// A throttle cooldown survives exhaustion so the next batch line also waits.
|
|
135
|
+
const delay = Math.max(this.calculateBackoff(attempt), error instanceof ResearchError ? Math.min(error.retryAfterMs ?? 0, MAX_RETRY_AFTER_MS) : 0);
|
|
136
|
+
if (error instanceof ResearchError && error.code === ResearchErrorCode.RF_103) {
|
|
137
|
+
this.rateLimiter.defer(delay);
|
|
138
|
+
}
|
|
139
|
+
// Retry transient HTTP failures with the same limiter on every attempt.
|
|
121
140
|
if (error instanceof ResearchError) {
|
|
122
141
|
// Retry on transient errors
|
|
123
142
|
if (this.isRetriable(error) && attempt < this.retryConfig.maxRetries) {
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
return this.executeWithRetry(url, options, attempt + 1, currentFirstError);
|
|
143
|
+
if (error.code !== ResearchErrorCode.RF_103)
|
|
144
|
+
await this.sleep(delay);
|
|
145
|
+
return this.executeWithRetry(url, options, attempt + 1, currentFirstError, read);
|
|
127
146
|
}
|
|
128
147
|
throw error;
|
|
129
148
|
}
|
|
@@ -131,7 +150,7 @@ export class BaseClient {
|
|
|
131
150
|
if (attempt < this.retryConfig.maxRetries) {
|
|
132
151
|
const delay = this.calculateBackoff(attempt);
|
|
133
152
|
await this.sleep(delay);
|
|
134
|
-
return this.executeWithRetry(url, options, attempt + 1, currentFirstError);
|
|
153
|
+
return this.executeWithRetry(url, options, attempt + 1, currentFirstError, read);
|
|
135
154
|
}
|
|
136
155
|
// If we have a first error from an HTTP response, throw that instead of generic network error
|
|
137
156
|
if (currentFirstError) {
|
|
@@ -149,7 +168,14 @@ export class BaseClient {
|
|
|
149
168
|
return new ResearchError(ResearchErrorCode.RF_300, 'Resource not found');
|
|
150
169
|
}
|
|
151
170
|
if (status === 429) {
|
|
152
|
-
|
|
171
|
+
const error = new ResearchError(ResearchErrorCode.RF_103, 'Rate limit exceeded');
|
|
172
|
+
const value = response.headers?.get('retry-after');
|
|
173
|
+
if (value) {
|
|
174
|
+
const ms = /^\d+(?:\.\d+)?$/.test(value.trim()) ? Number(value) * 1000 : Date.parse(value) - Date.now();
|
|
175
|
+
if (Number.isFinite(ms))
|
|
176
|
+
error.retryAfterMs = Math.max(0, ms);
|
|
177
|
+
}
|
|
178
|
+
return error;
|
|
153
179
|
}
|
|
154
180
|
if (status === 401 || status === 403) {
|
|
155
181
|
return new ResearchError(ResearchErrorCode.RF_102, 'Invalid API key or unauthorized');
|
|
@@ -164,8 +190,8 @@ export class BaseClient {
|
|
|
164
190
|
*/
|
|
165
191
|
isRetriable(error) {
|
|
166
192
|
if (error instanceof ResearchError) {
|
|
167
|
-
//
|
|
168
|
-
return error.code === ResearchErrorCode.RF_200;
|
|
193
|
+
// Rate limits and server errors are transient.
|
|
194
|
+
return error.code === ResearchErrorCode.RF_200 || error.code === ResearchErrorCode.RF_103;
|
|
169
195
|
}
|
|
170
196
|
// Retry on network errors
|
|
171
197
|
return true;
|
|
@@ -184,8 +210,9 @@ export class BaseClient {
|
|
|
184
210
|
/**
|
|
185
211
|
* Build URL with query parameters
|
|
186
212
|
*/
|
|
187
|
-
buildUrl(path, params) {
|
|
188
|
-
|
|
213
|
+
buildUrl(path, params, baseUrl = this.config.baseUrl) {
|
|
214
|
+
// API endpoints are relative to the complete base path, even with a slash.
|
|
215
|
+
const url = new URL(path.replace(/^\/+/, ''), `${baseUrl.replace(/\/+$/, '')}/`);
|
|
189
216
|
Object.entries(params).forEach(([key, value]) => {
|
|
190
217
|
if (value !== undefined) {
|
|
191
218
|
url.searchParams.append(key, String(value));
|
|
@@ -39,9 +39,16 @@ export class CrossRefClient extends BaseClient {
|
|
|
39
39
|
* Search papers by query
|
|
40
40
|
*/
|
|
41
41
|
async search(query, options = {}) {
|
|
42
|
+
return this.queryWorks('query', query, options);
|
|
43
|
+
}
|
|
44
|
+
/** Resolve a partial citation using CrossRef's bibliographic search field. */
|
|
45
|
+
async searchBibliographic(query, options = {}) {
|
|
46
|
+
return this.queryWorks('query.bibliographic', query, options);
|
|
47
|
+
}
|
|
48
|
+
async queryWorks(field, query, options) {
|
|
42
49
|
const { limit = 10, offset = 0 } = options;
|
|
43
50
|
const url = this.buildUrl('/works', {
|
|
44
|
-
query,
|
|
51
|
+
[field]: query,
|
|
45
52
|
rows: limit,
|
|
46
53
|
offset,
|
|
47
54
|
});
|
|
@@ -80,6 +87,7 @@ export class CrossRefClient extends BaseClient {
|
|
|
80
87
|
title,
|
|
81
88
|
authors,
|
|
82
89
|
year,
|
|
90
|
+
publicationDate: response.published?.['date-parts']?.[0]?.map((part, i) => String(part).padStart(i === 0 ? 4 : 2, '0')).join('-'),
|
|
83
91
|
abstract: response.abstract,
|
|
84
92
|
doi: response.DOI,
|
|
85
93
|
venue,
|
|
@@ -4,18 +4,21 @@
|
|
|
4
4
|
* @module research/clients/semantic-scholar
|
|
5
5
|
*/
|
|
6
6
|
import { BaseClient } from './base.js';
|
|
7
|
+
import { ResearchError, ResearchErrorCode, } from '../types.js';
|
|
8
|
+
const IDENTITY_FIELDS = 'paperId,title,abstract,year,authors,citationCount,venue,publicationDate,publicationVenue,externalIds,openAccessPdf';
|
|
7
9
|
/**
|
|
8
10
|
* Semantic Scholar API client
|
|
9
11
|
*/
|
|
10
12
|
export class SemanticScholarClient extends BaseClient {
|
|
13
|
+
recommendationsBaseUrl;
|
|
11
14
|
constructor(config) {
|
|
12
15
|
super({
|
|
13
16
|
baseUrl: 'https://api.semanticscholar.org/graph/v1',
|
|
14
17
|
timeout: 30000,
|
|
15
18
|
rateLimit: {
|
|
16
|
-
maxTokens:
|
|
19
|
+
maxTokens: 1,
|
|
17
20
|
refillRate: 1, // 1 request per second
|
|
18
|
-
currentTokens:
|
|
21
|
+
currentTokens: 1,
|
|
19
22
|
lastRefill: Date.now(),
|
|
20
23
|
},
|
|
21
24
|
retry: {
|
|
@@ -25,65 +28,86 @@ export class SemanticScholarClient extends BaseClient {
|
|
|
25
28
|
backoffMultiplier: 2,
|
|
26
29
|
},
|
|
27
30
|
...config,
|
|
31
|
+
apiKey: config?.apiKey ?? process.env.S2_API_KEY,
|
|
28
32
|
});
|
|
33
|
+
this.recommendationsBaseUrl = config?.recommendationsBaseUrl ??
|
|
34
|
+
'https://api.semanticscholar.org/recommendations/v1';
|
|
35
|
+
}
|
|
36
|
+
/** Request raw JSON in an explicit namespace; baseUrl overrides graph only. */
|
|
37
|
+
async requestApi(namespace, path, params = {}) {
|
|
38
|
+
const baseUrl = namespace === 'graph'
|
|
39
|
+
? this.config.baseUrl
|
|
40
|
+
: this.recommendationsBaseUrl;
|
|
41
|
+
return this.request(this.buildUrl(path, params, baseUrl));
|
|
42
|
+
}
|
|
43
|
+
/** Attach credentials once for all endpoints and keep transport causes private. */
|
|
44
|
+
async request(url, options = {}) {
|
|
45
|
+
const key = this.config.apiKey;
|
|
46
|
+
try {
|
|
47
|
+
const headers = new Headers(options.headers);
|
|
48
|
+
if (key)
|
|
49
|
+
headers.set('x-api-key', key);
|
|
50
|
+
return await super.request(url, { ...options, headers });
|
|
51
|
+
}
|
|
52
|
+
catch (error) {
|
|
53
|
+
// A transport error can echo request headers, including in its cause/stack.
|
|
54
|
+
if (key) {
|
|
55
|
+
throw new ResearchError(error instanceof ResearchError ? error.code : ResearchErrorCode.RF_500, error instanceof ResearchError
|
|
56
|
+
? error.message.replaceAll(key, '[REDACTED]')
|
|
57
|
+
: 'Semantic Scholar request failed');
|
|
58
|
+
}
|
|
59
|
+
throw error;
|
|
60
|
+
}
|
|
29
61
|
}
|
|
30
62
|
/**
|
|
31
63
|
* Get paper by DOI
|
|
32
64
|
*/
|
|
33
65
|
async getPaperByDoi(doi) {
|
|
34
|
-
|
|
35
|
-
'paperId',
|
|
36
|
-
'title',
|
|
37
|
-
'abstract',
|
|
38
|
-
'year',
|
|
39
|
-
'authors',
|
|
40
|
-
'citationCount',
|
|
41
|
-
'venue',
|
|
42
|
-
'externalIds',
|
|
43
|
-
'openAccessPdf',
|
|
44
|
-
];
|
|
45
|
-
const url = this.buildUrl(`/paper/DOI:${encodeURIComponent(doi)}`, {
|
|
46
|
-
fields: fields.join(','),
|
|
47
|
-
});
|
|
48
|
-
const response = await this.request(url);
|
|
49
|
-
return this.transformResponse(response);
|
|
66
|
+
return this.getPaperById(`DOI:${doi}`);
|
|
50
67
|
}
|
|
51
68
|
/**
|
|
52
69
|
* Get paper by arXiv ID
|
|
53
70
|
*/
|
|
54
71
|
async getPaperByArxivId(arxivId) {
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
'externalIds',
|
|
64
|
-
'openAccessPdf',
|
|
65
|
-
];
|
|
66
|
-
const url = this.buildUrl(`/paper/ARXIV:${encodeURIComponent(arxivId)}`, {
|
|
67
|
-
fields: fields.join(','),
|
|
68
|
-
});
|
|
69
|
-
const response = await this.request(url);
|
|
72
|
+
return this.getPaperById(`ARXIV:${arxivId}`);
|
|
73
|
+
}
|
|
74
|
+
/** Graph lookup by paperId, DOI:, ARXIV:, ACL:, CorpusId: or URL: identifier. */
|
|
75
|
+
async getPaperById(identifier) {
|
|
76
|
+
const colon = identifier.indexOf(':');
|
|
77
|
+
const encoded = colon < 0 ? encodeURIComponent(identifier)
|
|
78
|
+
: `${identifier.slice(0, colon + 1)}${encodeURIComponent(identifier.slice(colon + 1))}`;
|
|
79
|
+
const response = await this.requestApi('graph', `/paper/${encoded}`, { fields: IDENTITY_FIELDS });
|
|
70
80
|
return this.transformResponse(response);
|
|
71
81
|
}
|
|
82
|
+
/** Title matching uses the graph match endpoint, retaining every returned candidate. */
|
|
83
|
+
async matchTitle(query) {
|
|
84
|
+
const response = await this.requestApi('graph', '/paper/search/match', {
|
|
85
|
+
query, fields: IDENTITY_FIELDS,
|
|
86
|
+
});
|
|
87
|
+
return response.data.map(paper => this.transformResponse(paper));
|
|
88
|
+
}
|
|
89
|
+
/** Similar papers share the normal transport, key header, limiter and retries. */
|
|
90
|
+
async recommendations(identifier, limit = 20, from = 'recent') {
|
|
91
|
+
const colon = identifier.indexOf(':');
|
|
92
|
+
const encoded = `${identifier.slice(0, colon + 1)}${encodeURIComponent(identifier.slice(colon + 1))}`;
|
|
93
|
+
const response = await this.requestApi('recommendations', `/papers/forpaper/${encoded}`, { limit, from, fields: IDENTITY_FIELDS });
|
|
94
|
+
if (!Array.isArray(response.recommendedPapers) || response.recommendedPapers.some(p => !p?.paperId || !p.title)) {
|
|
95
|
+
throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid recommendations response');
|
|
96
|
+
}
|
|
97
|
+
return response.recommendedPapers.map(paper => this.transformResponse(paper));
|
|
98
|
+
}
|
|
99
|
+
/** One graph lookup for each candidate selected for optional citation overlap. */
|
|
100
|
+
async recommendationReferences(paperId) {
|
|
101
|
+
const response = await this.requestApi('graph', `/paper/${encodeURIComponent(paperId)}`, { fields: 'references.paperId,references.title,references.externalIds' });
|
|
102
|
+
if (!Array.isArray(response.references))
|
|
103
|
+
throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid references response');
|
|
104
|
+
return response.references.filter(paper => paper?.paperId).map(paper => this.transformResponse(paper));
|
|
105
|
+
}
|
|
72
106
|
/**
|
|
73
107
|
* Search papers by query
|
|
74
108
|
*/
|
|
75
109
|
async search(query, options = {}) {
|
|
76
|
-
const { limit = 10, offset = 0, fields =
|
|
77
|
-
'paperId',
|
|
78
|
-
'title',
|
|
79
|
-
'abstract',
|
|
80
|
-
'year',
|
|
81
|
-
'authors',
|
|
82
|
-
'citationCount',
|
|
83
|
-
'venue',
|
|
84
|
-
'externalIds',
|
|
85
|
-
'openAccessPdf',
|
|
86
|
-
], } = options;
|
|
110
|
+
const { limit = 10, offset = 0, fields = IDENTITY_FIELDS.split(','), } = options;
|
|
87
111
|
const url = this.buildUrl('/paper/search', {
|
|
88
112
|
query,
|
|
89
113
|
limit,
|
|
@@ -109,12 +133,17 @@ export class SemanticScholarClient extends BaseClient {
|
|
|
109
133
|
}));
|
|
110
134
|
return {
|
|
111
135
|
id: response.paperId,
|
|
136
|
+
s2PaperId: response.paperId,
|
|
112
137
|
title: response.title,
|
|
113
138
|
authors,
|
|
114
139
|
year: response.year || 0,
|
|
115
140
|
abstract: response.abstract,
|
|
116
141
|
doi: response.externalIds?.DOI,
|
|
117
142
|
arxivId: response.externalIds?.ArXiv,
|
|
143
|
+
aclId: response.externalIds?.ACL,
|
|
144
|
+
openReviewId: response.externalIds?.OpenReview,
|
|
145
|
+
publicationDate: response.publicationDate ?? undefined,
|
|
146
|
+
publicationVenue: response.publicationVenue ?? undefined,
|
|
118
147
|
venue: response.venue,
|
|
119
148
|
citationCount: response.citationCount,
|
|
120
149
|
pdfUrl: response.openAccessPdf?.url,
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
const ARXIV = '(?:\\d{4}\\.\\d{4,5}|[a-z][a-z.-]*(?:\\.[A-Z]{2})?/\\d{7})(?:v\\d+)?';
|
|
2
|
+
/** Parse abs/pdf/html URLs, arXiv DOIs, new/old IDs and an optional version. */
|
|
3
|
+
export function parseArxivId(input) {
|
|
4
|
+
const text = input.trim().replace(/\.pdf(?:[?#].*)?$/i, '').replace(/[?#].*$/, '');
|
|
5
|
+
const match = text.match(new RegExp(`^(?:(?:https?://(?:export\\.)?arxiv\\.org/(?:abs|pdf|html)/)|(?:https?://(?:dx\\.)?doi\\.org/)?10\\.48550/arxiv\\.|arxiv:\\s*)?(${ARXIV})$`, 'i'));
|
|
6
|
+
if (!match)
|
|
7
|
+
return undefined;
|
|
8
|
+
const version = match[1].match(/v(\d+)$/i);
|
|
9
|
+
return { id: match[1].replace(/v\d+$/i, '').toLowerCase(), ...(version ? { version: Number(version[1]) } : {}) };
|
|
10
|
+
}
|
|
11
|
+
/** Canonical DOI spelling, including DOI URLs; trailing citation punctuation is ignored. */
|
|
12
|
+
export function normalizeDoi(input) {
|
|
13
|
+
let text = input.trim().replace(/^(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:\s*)/i, '');
|
|
14
|
+
try {
|
|
15
|
+
text = decodeURIComponent(text);
|
|
16
|
+
}
|
|
17
|
+
catch { /* Keep a literal DOI on malformed escapes. */ }
|
|
18
|
+
text = text.replace(/[.,;]+$/, '');
|
|
19
|
+
while (text.endsWith(')') && (text.match(/\)/g)?.length ?? 0) > (text.match(/\(/g)?.length ?? 0))
|
|
20
|
+
text = text.slice(0, -1);
|
|
21
|
+
return /^10\.\d{4,9}\/\S+$/i.test(text) ? text.toLowerCase() : undefined;
|
|
22
|
+
}
|
|
23
|
+
/** Parse a recognized identifier even when embedded in a bibliography line. */
|
|
24
|
+
export function parseResearchIdentifier(input) {
|
|
25
|
+
const arxiv = input.match(new RegExp(`(?:https?://(?:export\\.)?arxiv\\.org/(?:abs|pdf|html)/|(?:https?://(?:dx\\.)?doi\\.org/)?10\\.48550/arxiv\\.|arxiv:\\s*)${ARXIV}(?:\\.pdf)?(?:[?#][^\\s<>]*)?|(?<![\\w./])${ARXIV}(?![\\w.])`, 'i'));
|
|
26
|
+
if (arxiv) {
|
|
27
|
+
const parsed = parseArxivId(arxiv[0]);
|
|
28
|
+
if (parsed)
|
|
29
|
+
return { kind: 'arxiv', ...parsed, matched: arxiv[0] };
|
|
30
|
+
}
|
|
31
|
+
const doi = input.match(/(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:\s*)?10\.\d{4,9}\/[^\s<>"\]]+/i);
|
|
32
|
+
if (doi) {
|
|
33
|
+
const id = normalizeDoi(doi[0]);
|
|
34
|
+
if (id)
|
|
35
|
+
return { kind: 'doi', id, matched: doi[0] };
|
|
36
|
+
}
|
|
37
|
+
const review = input.match(/https?:\/\/(?:www\.)?openreview\.net\/(?:forum|pdf)\?[^\s<>]*/i);
|
|
38
|
+
if (review) {
|
|
39
|
+
const id = new URL(review[0]).searchParams.get('id');
|
|
40
|
+
if (id)
|
|
41
|
+
return { kind: 'openreview', id, matched: review[0] };
|
|
42
|
+
}
|
|
43
|
+
const reviewId = input.match(/\bopenreview:\s*([\w-]+)/i);
|
|
44
|
+
if (reviewId)
|
|
45
|
+
return { kind: 'openreview', id: reviewId[1], matched: reviewId[0] };
|
|
46
|
+
const acl = input.match(/https?:\/\/(?:www\.)?aclanthology\.org\/([\w.-]+)\/?(?:[?#][^\s<>]*)?|\bacl:\s*([\w.-]+)|\b((?:\d{4}\.[a-z][\w-]*\.\d+|[A-Z]\d{2}-\d{4}))\b/i);
|
|
47
|
+
if (acl)
|
|
48
|
+
return { kind: 'acl', id: (acl[1] ?? acl[2] ?? acl[3]).replace(/\.pdf$/i, ''), matched: acl[0] };
|
|
49
|
+
const s2 = input.match(/https?:\/\/(?:www\.)?semanticscholar\.org\/paper\/(?:[^\s/]+\/)?([a-f\d]{40})\b|\b(?:s2|semanticscholar):\s*([a-f\d]{40})\b|\b(CorpusId:\d+)\b/i);
|
|
50
|
+
if (s2)
|
|
51
|
+
return { kind: 's2', id: (s2[1] ?? s2[2] ?? s2[3]).toLowerCase().replace(/^corpusid:/, 'CorpusId:'), matched: s2[0] };
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
/** Remove LaTeX formatting while retaining its text, then normalize Unicode and punctuation. */
|
|
55
|
+
export function normalizeTitle(input) {
|
|
56
|
+
return input.normalize('NFKC')
|
|
57
|
+
.replace(/\\(?:begin|end)\{[^}]*\}/g, ' ')
|
|
58
|
+
.replace(/\\[a-zA-Z]+\*?/g, '')
|
|
59
|
+
.replace(/\\([^a-zA-Z])/g, '$1')
|
|
60
|
+
.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ')
|
|
61
|
+
.replace(/\s+/g, ' ').trim();
|
|
62
|
+
}
|
|
63
|
+
/** Accept both corpus frontmatter spellings and canonical client metadata. */
|
|
64
|
+
export function normalizeIdentity(value) {
|
|
65
|
+
const fields = value;
|
|
66
|
+
const str = (...keys) => keys.map(k => fields[k])
|
|
67
|
+
.map(v => typeof v === 'number' && Number.isFinite(v) ? String(v) : v)
|
|
68
|
+
.find(v => typeof v === 'string' && v.trim());
|
|
69
|
+
const arxiv = parseArxivId(str('arxivId', 'arxiv_id', 'arxiv') ?? '') ?? parseArxivId(str('doi') ?? '');
|
|
70
|
+
return {
|
|
71
|
+
...(arxiv ? { arxivId: arxiv.id, arxivVersion: arxiv.version ?? (typeof fields.arxivVersion === 'number' ? fields.arxivVersion : undefined) } : {}),
|
|
72
|
+
doi: normalizeDoi(str('doi', 'DOI') ?? ''),
|
|
73
|
+
s2PaperId: str('s2PaperId', 's2_paper_id', 'paperId')?.toLowerCase(),
|
|
74
|
+
openReviewId: str('openReviewId', 'openreview_id')?.toLowerCase(),
|
|
75
|
+
aclId: str('aclId', 'acl_id')?.toLowerCase(),
|
|
76
|
+
title: str('title') ? normalizeTitle(str('title')) : undefined,
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/** Stable keys for matching any identifier or a normalized title across corpus sources. */
|
|
80
|
+
export function identityKeys(value) {
|
|
81
|
+
const identity = normalizeIdentity(value);
|
|
82
|
+
return ['arxivId', 'doi', 's2PaperId', 'openReviewId', 'aclId', 'title']
|
|
83
|
+
.flatMap(key => identity[key] ? [`${key}:${identity[key]}`] : []);
|
|
84
|
+
}
|
|
85
|
+
/** REF spelling is case-sensitive, including the optional legacy suffix letter. */
|
|
86
|
+
export const REF_ID_SOURCE = 'REF-\\d+[a-zA-Z]?';
|
|
87
|
+
/** Match whole tokens in prose and paths without accepting a malformed ID prefix. */
|
|
88
|
+
export const REF_ID_PATTERN = `(?<![A-Za-z0-9_])${REF_ID_SOURCE}(?![A-Za-z0-9_])`;
|
|
89
|
+
const REF_ID_FULL = new RegExp(`^${REF_ID_SOURCE}$`);
|
|
90
|
+
export function refIdsInText(text) {
|
|
91
|
+
return text.match(new RegExp(REF_ID_PATTERN, 'g')) ?? [];
|
|
92
|
+
}
|
|
93
|
+
/** Exact lexical REF identity: preserve zero padding and suffix case. */
|
|
94
|
+
export function isRefId(value) {
|
|
95
|
+
return value.trim() === value && REF_ID_FULL.test(value);
|
|
96
|
+
}
|
|
97
|
+
/** Read the REF token before a slug or extension; never normalize its spelling. */
|
|
98
|
+
export function refIdFromFilename(filename, extension = '.md') {
|
|
99
|
+
if (!filename.endsWith(extension))
|
|
100
|
+
return null;
|
|
101
|
+
const stem = filename.slice(0, -extension.length);
|
|
102
|
+
const slug = stem.indexOf('-', 4);
|
|
103
|
+
const ref = slug === -1 ? stem : stem.slice(0, slug);
|
|
104
|
+
return isRefId(ref) ? ref : null;
|
|
105
|
+
}
|
|
106
|
+
/** Sort key for REF ids: [numeric, alpha-suffix]. Mirrors build.py ref_sort_key. */
|
|
107
|
+
export function refSortKey(refId) {
|
|
108
|
+
const m = isRefId(refId) ? refId.match(/^REF-(\d+)([a-zA-Z]?)$/) : null;
|
|
109
|
+
return m ? [parseInt(m[1], 10), m[2]] : [999999, refId];
|
|
110
|
+
}
|
|
111
|
+
/** Compare two REF ids by (numeric, suffix). */
|
|
112
|
+
export function compareRefId(a, b) {
|
|
113
|
+
const [an, as_] = refSortKey(a);
|
|
114
|
+
const [bn, bs] = refSortKey(b);
|
|
115
|
+
return an !== bn ? an - bn : as_ < bs ? -1 : as_ > bs ? 1 : 0;
|
|
116
|
+
}
|
|
117
|
+
//# sourceMappingURL=identity.js.map
|