From 82546e9ba1cead9a1c1e1cfcade16e615521952e Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:41:31 +0800 Subject: [PATCH] ci(checks): run the Knip production analysis during verification Wire the existing knip:production script into pnpm verify after pnpm knip, update the two tests that pin the verify string, and document the gate in README, CONTRIBUTING, AGENTS and the technology-decisions record. - Delete the test-only provider layers (deepseek, doubao, grok) and the github repository mapper together with their tests; the grok transport suite builds its SearchProvider layer inline now. - Tag exports and types that only tests reach with @internal, which knip ignores in production mode; split barrel clauses so production-used symbols keep their untagged re-export. --- AGENTS.md | 3 +- CONTRIBUTING.md | 3 +- README.md | 3 +- docs/architecture/technology-decisions.md | 2 +- package.json | 2 +- src/acquisition/application/ports.ts | 1 + .../application/services/with-fallback.ts | 1 + .../application/services/with-retry.ts | 6 +- .../application/use-cases/collect-x-posts.ts | 1 + src/acquisition/domain/budget/index.ts | 3 +- .../domain/budget/value-objects/budget.ts | 1 + src/acquisition/domain/search/index.ts | 4 +- .../domain/search/value-objects/search.ts | 2 + src/acquisition/domain/source/index.ts | 9 +- src/acquisition/index.ts | 8 +- src/app/cli/github-home.ts | 1 + src/app/config/assets.ts | 1 + src/app/config/parse.ts | 4 + src/app/config/state-root.ts | 8 +- src/app/layers.ts | 8 +- src/app/products/news/flow.ts | 4 + src/app/products/news/topics.ts | 1 + src/app/products/research/cli.ts | 1 + src/app/products/subscriptions/output.ts | 5 +- src/app/render/automation.ts | 1 + src/app/render/layouts/candidate.ts | 3 + src/app/render/markdown.ts | 1 + src/delivery/domain/receipt/index.ts | 8 +- .../receipt/value-objects/daily-ai-receipt.ts | 1 + src/delivery/index.ts | 30 +++--- .../infra/repository/feed-state-file.ts | 1 + .../infra/repository/run-archive-files.ts | 4 + src/editorial/domain/daily-ai/index.ts | 1 + src/editorial/domain/evidence/index.ts | 3 +- .../domain/news/policies/news-funnel.ts | 2 + src/editorial/domain/subscription/index.ts | 3 +- .../subscription/policies/presentation.ts | 4 +- src/editorial/index.ts | 17 ++- src/integrations/deepseek/client.ts | 2 + src/integrations/deepseek/mapper.ts | 1 + src/integrations/deepseek/provider.test.ts | 49 --------- src/integrations/deepseek/provider.ts | 16 --- src/integrations/doubao/client.ts | 1 + src/integrations/doubao/index.ts | 1 + src/integrations/doubao/mapper.ts | 1 + src/integrations/doubao/provider.test.ts | 42 -------- src/integrations/doubao/provider.ts | 16 --- src/integrations/github/client.ts | 1 + src/integrations/github/event/dto.ts | 4 +- src/integrations/github/home-browser.ts | 2 + src/integrations/github/home/dto.ts | 1 + src/integrations/github/home/mapper.ts | 2 + src/integrations/github/index.ts | 2 + .../github/repository/mapper.test.ts | 55 ---------- src/integrations/github/repository/mapper.ts | 102 ------------------ src/integrations/glm/search/provider.ts | 1 + src/integrations/grok/audit.ts | 3 + src/integrations/grok/cli.test.ts | 19 +++- src/integrations/grok/provider.ts | 16 --- src/integrations/grok/search/dto.ts | 2 + src/integrations/rss/client.ts | 1 + src/integrations/rss/index.ts | 1 + src/integrations/rss/mapper.ts | 2 + src/integrations/shared/index.ts | 5 +- src/integrations/shared/scoring-trace.ts | 1 + src/integrations/shared/search-plumbing.ts | 4 +- src/integrations/web-page/client.ts | 1 + src/integrations/web-page/index.ts | 1 + src/integrations/web-page/mapper.ts | 1 + src/kernel/result.ts | 1 + .../domain/document/policies/url-policy.ts | 1 + .../domain/document/value-objects/document.ts | 5 +- tests/repo/ci-harness.test.ts | 2 +- tests/repo/package-bin.test.ts | 2 +- 74 files changed, 166 insertions(+), 362 deletions(-) delete mode 100644 src/integrations/deepseek/provider.test.ts delete mode 100644 src/integrations/deepseek/provider.ts delete mode 100644 src/integrations/doubao/provider.test.ts delete mode 100644 src/integrations/doubao/provider.ts delete mode 100644 src/integrations/github/repository/mapper.test.ts delete mode 100644 src/integrations/github/repository/mapper.ts delete mode 100644 src/integrations/grok/provider.ts diff --git a/AGENTS.md b/AGENTS.md index 9b67dd3..f352202 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ This repository is a local TypeScript CLI plus portable Codex skills. Treat ever - Do not commit `.env`, `.state/`, build output, local logs, tokens, temporary workspaces, or machine-specific paths. - Do not add private tokens, internal hostnames, private repository names, or personal filesystem paths. - Use `rg` for searches when available. -- Run `pnpm verify` before claiming a change is ready (`test:layout` + `vp check` + duplicates + knip + tests + `tsc` build + package check). Prefer `vp` for lint/fmt/test when Vite+ is installed (`pnpm exec vp …`). +- Run `pnpm verify` before claiming a change is ready (`test:layout` + `vp check` + duplicates + knip + knip:production + tests + `tsc` build + package check). Prefer `vp` for lint/fmt/test when Vite+ is installed (`pnpm exec vp …`). - Do not claim implementation work is complete until the relevant commands pass, or until skipped commands are explained with concrete blockers. - Update tests and documentation when behavior changes. - `feeds.json` is the repository-maintained RSS subscription list. Update it through `rss-summary feeds ...` when possible and include intentional feed changes in the pull request. @@ -38,6 +38,7 @@ pnpm lint pnpm duplicates # Fails on any reported duplicate. pnpm duplicates:audit # Reports duplicates without failing on findings. pnpm knip # Fails CI on unused files, exports, or dependencies and on configuration or tag hints. +pnpm knip:production # The same analysis over the production entries only; code only tests reach shows up here. # Full local gate: pnpm verify diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf5afa0..28e288a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,8 +54,9 @@ pnpm lint pnpm duplicates # Fails on any reported duplicate. pnpm duplicates:audit # Reports duplicates without failing on findings. pnpm knip # Fails CI on unused files, exports, or dependencies and on configuration or tag hints. +pnpm knip:production # The same analysis over the production entries only; code only tests reach shows up here. -# Full local gate (test layout + vp check + duplicates + knip + tests + build + package check): +# Full local gate (test layout + vp check + duplicates + knip + knip:production + tests + build + package check): pnpm verify # Coverage: diff --git a/README.md b/README.md index 06d32c8..9dda4b1 100644 --- a/README.md +++ b/README.md @@ -174,10 +174,11 @@ rss-summary runs show ## Development ```bash -pnpm verify # test:layout + check + duplicates + knip + test + build + package:check +pnpm verify # test:layout + check + duplicates + knip + knip:production + test + build + package:check pnpm duplicates # 检出任何一处重复都会失败。 pnpm duplicates:audit # 只生成报告,发现重复也不会拦截。 pnpm knip # 检出未使用的文件、导出、依赖,或出现配置、标签提示时,CI 失败。 +pnpm knip:production # 只跟随生产入口的同一检查:测试才可达的代码只在这里出现。 ``` `main` 受保护。在功能分支上改,开 PR,等 `Verify` + `Coverage` 通过后再合并。 diff --git a/docs/architecture/technology-decisions.md b/docs/architecture/technology-decisions.md index ff06a05..bb50bf2 100644 --- a/docs/architecture/technology-decisions.md +++ b/docs/architecture/technology-decisions.md @@ -82,7 +82,7 @@ Alternatives considered and rejected: - Import direction is enforced by the architecture test (`scripts/architecture/boundaries.ts` + `tests/repo/architecture.test.ts`, zero violations), not by lint rules. - `pnpm verify` runs `pnpm check` (`vp check`) after `test:layout`. - The next step, `pnpm duplicates`, fails on any reported duplicate. Run `pnpm duplicates:audit` separately for a report without failing on findings. -- `pnpm knip` then checks for unused files, exports, and dependencies. Findings and configuration or tag hints fail the Verify job. +- `pnpm knip` then checks for unused files, exports, and dependencies, followed by `pnpm knip:production`, which follows only the production entries so code that only tests reach is caught too. Findings and configuration or tag hints fail the Verify job. ## CI Gates diff --git a/package.json b/package.json index fd2cf10..e7fc5fb 100644 --- a/package.json +++ b/package.json @@ -46,7 +46,7 @@ "test:coverage": "vp test run --coverage", "test:layout": "node scripts/check-test-layout.mjs", "typecheck": "tsc --noEmit", - "verify": "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm test && pnpm build && pnpm package:check" + "verify": "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm knip:production && pnpm test && pnpm build && pnpm package:check" }, "devDependencies": { "@rivus/agent": "0.18.0", diff --git a/src/acquisition/application/ports.ts b/src/acquisition/application/ports.ts index 4f27c99..8aa8521 100644 --- a/src/acquisition/application/ports.ts +++ b/src/acquisition/application/ports.ts @@ -79,6 +79,7 @@ export type GrokProcessRequest = { timeoutMs?: number; }; +/** @internal */ export class GrokProcess extends Context.Service< GrokProcess, { diff --git a/src/acquisition/application/services/with-fallback.ts b/src/acquisition/application/services/with-fallback.ts index 6ce8de7..8897986 100644 --- a/src/acquisition/application/services/with-fallback.ts +++ b/src/acquisition/application/services/with-fallback.ts @@ -37,6 +37,7 @@ export type FallbackSearchProvider = { * - `grok_invalid_response`: the CLI search stream lacked a complete receipt. * - `grok_source_policy`: the CLI search cannot serve this query's policy. * - `10406`: account-quota exhaustion on the primary web-search provider. + * @internal */ export const fallbackTriggerCodes: readonly string[] = [ "network_error", diff --git a/src/acquisition/application/services/with-retry.ts b/src/acquisition/application/services/with-retry.ts index 7abe929..d6c7469 100644 --- a/src/acquisition/application/services/with-retry.ts +++ b/src/acquisition/application/services/with-retry.ts @@ -14,7 +14,9 @@ function isTransientSearchError(error: unknown): error is NewsSearchError { return isSearchFailure(error) && (error.code === "rate_limit_exceeded" || error.code === "http_429"); } -/** Historical backoff: `retryAfterMs`, otherwise `round(250 * 2^(n-1) * (0.5 + clamp(random, 0, 1)))`. */ +/** Historical backoff: `retryAfterMs`, otherwise `round(250 * 2^(n-1) * (0.5 + clamp(random, 0, 1)))`. + * @internal + */ export function retryDelayMs(error: { retryAfterMs?: number }, attemptNumber: number, random: () => number): number { if (error.retryAfterMs !== undefined) { return error.retryAfterMs; @@ -40,6 +42,7 @@ function retrySchedule(attemptBase = 0) { ); } +/** @internal */ export function retryEffect(run: () => Promise, attemptBase = 0) { return Effect.tryPromise({ try: run, @@ -80,6 +83,7 @@ function provideRetryClock( return provided; } +/** @internal */ export function searchWithRetry( input: SearchInput, search: (input: SearchInput) => Promise, diff --git a/src/acquisition/application/use-cases/collect-x-posts.ts b/src/acquisition/application/use-cases/collect-x-posts.ts index 80b01b3..ce58eed 100644 --- a/src/acquisition/application/use-cases/collect-x-posts.ts +++ b/src/acquisition/application/use-cases/collect-x-posts.ts @@ -57,6 +57,7 @@ type XAccountClient = { search: (value: GrokProcessRequest) => Promise; }; +/** @internal */ export type OpenSearchBudget = (options: { provider: string; stateFile: string; diff --git a/src/acquisition/domain/budget/index.ts b/src/acquisition/domain/budget/index.ts index d403f1c..f100a22 100644 --- a/src/acquisition/domain/budget/index.ts +++ b/src/acquisition/domain/budget/index.ts @@ -2,12 +2,13 @@ export { SearchBudget, type BudgetState, type PresentCache } from "./aggregates/ export { validateBudgetOptions } from "./policies/budget-options.js"; export { cacheKey, - cacheKeyMaterial, type BudgetLimits, type BudgetUsage, type CachedPage, type CacheRequest, type HashText } from "./value-objects/budget.js"; +/** @internal */ +export { cacheKeyMaterial } from "./value-objects/budget.js"; export { cacheablePage, presentCachedPage } from "./services/cached-page.js"; export { normalizeHttpProvider } from "./services/provider-identity.js"; diff --git a/src/acquisition/domain/budget/value-objects/budget.ts b/src/acquisition/domain/budget/value-objects/budget.ts index 2e1f4d9..7b0a736 100644 --- a/src/acquisition/domain/budget/value-objects/budget.ts +++ b/src/acquisition/domain/budget/value-objects/budget.ts @@ -39,6 +39,7 @@ export type Reservation = { cached?: SearchPage; }; +/** @internal */ export function cacheKeyMaterial(request: CacheRequest): string { return JSON.stringify([ request.provider, diff --git a/src/acquisition/domain/search/index.ts b/src/acquisition/domain/search/index.ts index f3e4a3a..a0b5e60 100644 --- a/src/acquisition/domain/search/index.ts +++ b/src/acquisition/domain/search/index.ts @@ -4,8 +4,6 @@ export type { MergedSearchSource, NativeSearchReceipt, NewsSearchInput, - NewsSearchPage, - NewsSearchResult, ProviderFallback, SearchFallback, SearchHitFields, @@ -16,3 +14,5 @@ export type { SearchUsage, SourceVerification } from "./value-objects/search.js"; +/** @internal */ +export type { NewsSearchPage, NewsSearchResult } from "./value-objects/search.js"; diff --git a/src/acquisition/domain/search/value-objects/search.ts b/src/acquisition/domain/search/value-objects/search.ts index caab7a2..624a14e 100644 --- a/src/acquisition/domain/search/value-objects/search.ts +++ b/src/acquisition/domain/search/value-objects/search.ts @@ -120,5 +120,7 @@ export type SearchFallback = { }; export type NewsSearchInput = SearchInput; +/** @internal */ export type NewsSearchResult = SearchResult; +/** @internal */ export type NewsSearchPage = SearchPage; diff --git a/src/acquisition/domain/source/index.ts b/src/acquisition/domain/source/index.ts index 8ef4f85..c58eb8e 100644 --- a/src/acquisition/domain/source/index.ts +++ b/src/acquisition/domain/source/index.ts @@ -5,9 +5,6 @@ export { type IndustrySource, type WebPageSubscription } from "./value-objects/subscription.js"; -export { - addFeedSubscription, - parseFeedSubscriptions, - parseIndustrySources, - removeFeedSubscription -} from "./services/catalog.js"; +export { addFeedSubscription, removeFeedSubscription } from "./services/catalog.js"; +/** @internal */ +export { parseFeedSubscriptions, parseIndustrySources } from "./services/catalog.js"; diff --git a/src/acquisition/index.ts b/src/acquisition/index.ts index 1d4ac04..dc01596 100644 --- a/src/acquisition/index.ts +++ b/src/acquisition/index.ts @@ -15,7 +15,9 @@ export type { SignalType } from "./domain/item/index.js"; export { resolveNewsCredibility } from "./domain/item/policies/news-credibility.js"; -export { addFeedSubscription, parseFeedSubscriptions, parseIndustrySources } from "./domain/source/index.js"; +export { addFeedSubscription } from "./domain/source/index.js"; +/** @internal */ +export { parseFeedSubscriptions, parseIndustrySources } from "./domain/source/index.js"; export { listingPublicationType } from "./domain/source/policies/publication.js"; export { type FeedSubscription, type IndustrySource, type WebPageSubscription } from "./domain/source/index.js"; export { @@ -40,13 +42,13 @@ export { shareSearchBudget, type NativeSearchReceipt, type NewsSearchInput, - type NewsSearchResult, type SearchInput, type SearchPage, type SearchResult, - type SearchUsage, type SearchSourcePolicy } from "./domain/search/index.js"; +/** @internal */ +export { type NewsSearchResult, type SearchUsage } from "./domain/search/index.js"; export { searchBudgetDefaults } from "./application/services/budget-defaults.js"; export { SearchBudgetRepository, SearchProvider } from "./application/ports.js"; export { retrySearchEffect } from "./application/services/with-retry.js"; diff --git a/src/app/cli/github-home.ts b/src/app/cli/github-home.ts index e9b985e..b6c6c43 100644 --- a/src/app/cli/github-home.ts +++ b/src/app/cli/github-home.ts @@ -11,6 +11,7 @@ type GithubHomeCommandDeps = { stderr?: Writable; }; +/** @internal */ export function writeGithubHomeHelp(stdout: Writable): void { stdout.write(`Usage: rss-summary github-home login [--storage-state .state/github-home-storage.json] [--browser-channel chrome] diff --git a/src/app/config/assets.ts b/src/app/config/assets.ts index 3856500..4b11036 100644 --- a/src/app/config/assets.ts +++ b/src/app/config/assets.ts @@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url"; * news-topics.json). Walking up to the nearest package.json keeps the path * stable whether this module runs from src/ or from the packed dist/ tree, * instead of depending on the source file's directory depth. + * @internal */ export function packageAsset(name: string): string { let directory = dirname(fileURLToPath(import.meta.url)); diff --git a/src/app/config/parse.ts b/src/app/config/parse.ts index 933146c..5412c14 100644 --- a/src/app/config/parse.ts +++ b/src/app/config/parse.ts @@ -44,6 +44,7 @@ export function requiredString(value: unknown, label: string): string { return text.trim(); } +/** @internal */ export function optionalString(value: unknown, fallback: string, label: string): string { if (value === undefined) { return fallback; @@ -61,6 +62,7 @@ export function optionalBoolean(value: unknown, fallback: boolean, label: string return value; } +/** @internal */ export function requireBoundedInteger( value: unknown, fallback: number, @@ -78,6 +80,7 @@ export function requireBoundedInteger( return Number(value); } +/** @internal */ export function requireBoundedNumber( value: unknown, fallback: number, @@ -112,6 +115,7 @@ function requireArray(value: unknown, label: string): unknown[] { return value; } +/** @internal */ export function requireStringList(value: unknown, label: string): string[] { return requireArray(value, label).map((item, index) => { const text = stringValue(item); diff --git a/src/app/config/state-root.ts b/src/app/config/state-root.ts index 9e7d990..6b94db5 100644 --- a/src/app/config/state-root.ts +++ b/src/app/config/state-root.ts @@ -13,12 +13,16 @@ export const defaultIndustryStateFile = `${defaultStateDir}/industry-state.json` export const defaultRunLogDir = `${defaultStateDir}/runs`; export const defaultGithubHomeStorageState = `${defaultStateDir}/github-home-storage.json`; -/** Root for Rivus-deployment-owned state; undefined when the override is unset. */ +/** Root for Rivus-deployment-owned state; undefined when the override is unset. + * @internal + */ export function deploymentStateRoot(env: NodeJS.ProcessEnv): string | undefined { return env.RIVUS_DEPLOYMENT_STATE_DIR || undefined; } -/** Diagnostics directory for the Daily AI tool, matching delivery's layout. */ +/** Diagnostics directory for the Daily AI tool, matching delivery's layout. + * @internal + */ export function dailyAiDiagnosticsDir(env: NodeJS.ProcessEnv): string { const root = deploymentStateRoot(env); return root ? join(root, "rss-summary", "daily-ai") : join(defaultStateDir, "daily-ai"); diff --git a/src/app/layers.ts b/src/app/layers.ts index 572a139..1227001 100644 --- a/src/app/layers.ts +++ b/src/app/layers.ts @@ -111,6 +111,7 @@ export function ReadingLive( return Layer.mergeAll(http, browser, video, glm); } +/** @internal */ export type AcquisitionOptions = { token?: string; fetch?: typeof fetch; @@ -120,6 +121,7 @@ export type AcquisitionOptions = { /** * Assemble the acquisition ports from their integrations (feed, listing pages, * GitHub activity and catalog) plus the module's own state-backed stores. + * @internal */ export function AcquisitionLive( options: AcquisitionOptions = {} @@ -151,6 +153,7 @@ export type AppServices = | VideoReader | GlmReader; +/** @internal */ export type AppLiveOptions = { acquisition?: AcquisitionOptions; delivery?: DeliveryOptions; @@ -161,6 +164,7 @@ export type AppLiveOptions = { * Assemble every module's live layer plus the Node platform layer. The module * layers receive their environment-derived options; NodeFileSystem comes from * @effect/platform-node and stays merged into the output. + * @internal */ export function AppLive(options: AppLiveOptions = {}): Layer.Layer { return Layer.provideMerge( @@ -169,7 +173,9 @@ export function AppLive(options: AppLiveOptions = {}): Layer.Layer ); } -/** Layer options derived from a resolved configuration. */ +/** Layer options derived from a resolved configuration. + * @internal + */ export function appLiveOptions(config: AppConfig): AppLiveOptions { return { acquisition: { diff --git a/src/app/products/news/flow.ts b/src/app/products/news/flow.ts index 9b7c0d4..d8396c8 100644 --- a/src/app/products/news/flow.ts +++ b/src/app/products/news/flow.ts @@ -48,8 +48,10 @@ import { GrokSearchClient, normalizeProvider } from "../../../integrations/grok/ import type { AuditedSearchPage as NewsSearchPage } from "../../../integrations/grok/index.js"; import { createHybridNewsSearch } from "./hybrid.js"; +/** @internal */ export type { NewsBriefEdition }; +/** @internal */ export type RivusNewsBriefInput = { occurrence: string; edition: NewsBriefEdition; @@ -78,6 +80,7 @@ export type RivusNewsBriefOutput = RivusNewsBriefResult & { markdown: string }; * Every configured query failed because of provider or network availability. * Standalone news briefs still fail; aggregate products may safely degrade by * consuming the attached empty result and its complete per-query audit. + * @internal */ export class AllNewsQueriesFailedError extends Error { readonly result: RivusNewsBriefResult; @@ -121,6 +124,7 @@ function timeAtOffset(instant: number, timezoneOffset: string): string { return shifted.toISOString().slice(11, 16); } +/** @internal */ export function resolveNewsEditionWindow( occurrence: string, timezoneOffset: string, diff --git a/src/app/products/news/topics.ts b/src/app/products/news/topics.ts index 86860c6..c2526e7 100644 --- a/src/app/products/news/topics.ts +++ b/src/app/products/news/topics.ts @@ -128,6 +128,7 @@ function parseQuery(value: unknown, topicId: string, queryIndex: number, queryId }; } +/** @internal */ export function parseNewsTopics(value: string): NewsTopic[] { const parsed: unknown = JSON.parse(value); if (!Array.isArray(parsed)) { diff --git a/src/app/products/research/cli.ts b/src/app/products/research/cli.ts index fe98454..cb4607f 100644 --- a/src/app/products/research/cli.ts +++ b/src/app/products/research/cli.ts @@ -40,6 +40,7 @@ function parseArgs(argv: string[]): ParsedArgs { /** * Parse the `调研状态更新建议:` block emitted by the feed-research prompt. * Each accepted line looks like: `- github:owner/repo - decision=track reason="why"` . + * @internal */ export function parseResearchSuggestions(text: string): ResearchSuggestion[] { const lineRegex = /^\s*-\s+(github:\S+|rss:\S+)\s+-\s+decision=(\S+)(?:\s+reason="(.*)")?\s*$/u; diff --git a/src/app/products/subscriptions/output.ts b/src/app/products/subscriptions/output.ts index 1ea9b98..6c23280 100644 --- a/src/app/products/subscriptions/output.ts +++ b/src/app/products/subscriptions/output.ts @@ -82,9 +82,12 @@ export function applySubscriptionSelection( }; } +/** @internal */ export { candidateIdentity } from "../../../integrations/shared/index.js"; -/** Record a research decision under the historical ledger key. */ +/** Record a research decision under the historical ledger key. + * @internal + */ export function markCandidateResearched( state: { researched: Record }, candidate: CandidateProject, diff --git a/src/app/render/automation.ts b/src/app/render/automation.ts index ae1fba9..ac96422 100644 --- a/src/app/render/automation.ts +++ b/src/app/render/automation.ts @@ -172,6 +172,7 @@ function replayTrailing( * in each channel. Bounds, section ids, and source labels reproduce the * values the earlier Markdown parser produced, locked by the golden * registration snapshot and automation.test.ts. + * @internal */ export function renderAutomationPresentation( view: ViewDocument, diff --git a/src/app/render/layouts/candidate.ts b/src/app/render/layouts/candidate.ts index b723a83..3ad9d8c 100644 --- a/src/app/render/layouts/candidate.ts +++ b/src/app/render/layouts/candidate.ts @@ -6,6 +6,7 @@ import { import { subscriptionEvidenceId } from "../../products/subscriptions/output.js"; import type { ViewDocument, ViewItem } from "../view.js"; +/** @internal */ export type CandidateCopy = { facts: string[]; label: string; @@ -15,6 +16,7 @@ export type CandidateCopy = { summary: string; }; +/** @internal */ export type CandidateCopyOptions = { editorialSummary?: string; }; @@ -45,6 +47,7 @@ function oneLineFor(candidate: CandidateProject, label: string, facts: string[]) : `${candidate.repo} 有一条新的项目动态。`; } +/** @internal */ export function candidateCopy(candidate: CandidateProject, options: CandidateCopyOptions = {}): CandidateCopy { const label = candidate.label ?? candidate.repo; const url = candidate.url ?? candidate.repository?.htmlUrl ?? `https://github.com/${candidate.repo}`; diff --git a/src/app/render/markdown.ts b/src/app/render/markdown.ts index c51de67..b696457 100644 --- a/src/app/render/markdown.ts +++ b/src/app/render/markdown.ts @@ -5,6 +5,7 @@ export function markdownLinkText(value: string): string { return value.replace(/([\\[\]])/gu, "\\$1"); } +/** @internal */ export const formatStarCount = formatCompactCount; export function displayTime(value: string | undefined): string | undefined { diff --git a/src/delivery/domain/receipt/index.ts b/src/delivery/domain/receipt/index.ts index 664e4dd..f94cb87 100644 --- a/src/delivery/domain/receipt/index.ts +++ b/src/delivery/domain/receipt/index.ts @@ -1,5 +1,3 @@ -export { - commitDailyAiDeliveryReceipt, - createDailyAiDeliveryReceipt, - type DailyAiDeliveryReceipt -} from "./value-objects/daily-ai-receipt.js"; +export { createDailyAiDeliveryReceipt, type DailyAiDeliveryReceipt } from "./value-objects/daily-ai-receipt.js"; +/** @internal */ +export { commitDailyAiDeliveryReceipt } from "./value-objects/daily-ai-receipt.js"; diff --git a/src/delivery/domain/receipt/value-objects/daily-ai-receipt.ts b/src/delivery/domain/receipt/value-objects/daily-ai-receipt.ts index 7809288..46c0edf 100644 --- a/src/delivery/domain/receipt/value-objects/daily-ai-receipt.ts +++ b/src/delivery/domain/receipt/value-objects/daily-ai-receipt.ts @@ -23,6 +23,7 @@ export function createDailyAiDeliveryReceipt(occurrence: string, evidenceIds: st * Persist the committed receipt once delivery succeeded. Returns the new * committed receipt, or `undefined` when nothing was committed (delivery * failed or the receipt was already committed). + * @internal */ export async function commitDailyAiDeliveryReceipt( receipt: DailyAiDeliveryReceipt, diff --git a/src/delivery/index.ts b/src/delivery/index.ts index dcb8f0d..233fabf 100644 --- a/src/delivery/index.ts +++ b/src/delivery/index.ts @@ -10,22 +10,16 @@ import { FeedStateFileLive } from "./infra/repository/feed-state-file.js"; import { RunArchiveFilesLive } from "./infra/repository/run-archive-files.js"; import { DiagnosticsFileLive } from "./infra/repository/diagnostics-file.js"; -export { - createEmptyFeedState, - filterUndelivered, - filterUnresearched, - markDelivered, - type FeedState -} from "./domain/ledger/index.js"; +export { filterUndelivered, filterUnresearched, markDelivered, type FeedState } from "./domain/ledger/index.js"; +/** @internal */ +export { createEmptyFeedState } from "./domain/ledger/index.js"; export { createDailyAiDeliveryReceipt, type DailyAiDeliveryReceipt } from "./domain/receipt/index.js"; -export { type RunAudit, type RunDelivery, type RunSourceResult } from "./domain/run-audit/index.js"; -export { - Notifier, - FeedStateStore, - RunArchive, - DiagnosticsStore, - type DailyAiDiagnosticSnapshot -} from "./application/ports.js"; +export { type RunAudit, type RunSourceResult } from "./domain/run-audit/index.js"; +/** @internal */ +export { type RunDelivery } from "./domain/run-audit/index.js"; +export { Notifier, FeedStateStore, RunArchive, DiagnosticsStore } from "./application/ports.js"; +/** @internal */ +export { type DailyAiDiagnosticSnapshot } from "./application/ports.js"; export { deliver } from "./application/use-cases/deliver.js"; export { recordResearch } from "./application/use-cases/record-research.js"; export { @@ -34,8 +28,12 @@ export { runArtifactForLabel, readRunArtifact } from "./application/use-cases/inspect-runs.js"; +/** @internal */ export { NotifierLive } from "./infra/notifier/notifier.js"; -export { loadFeedState, saveFeedState, FeedStateFileLive } from "./infra/repository/feed-state-file.js"; +export { loadFeedState } from "./infra/repository/feed-state-file.js"; +/** @internal */ +export { saveFeedState, FeedStateFileLive } from "./infra/repository/feed-state-file.js"; +/** @internal */ export { listRunArtifacts, loadRunArtifact, diff --git a/src/delivery/infra/repository/feed-state-file.ts b/src/delivery/infra/repository/feed-state-file.ts index 55fe981..a647f42 100644 --- a/src/delivery/infra/repository/feed-state-file.ts +++ b/src/delivery/infra/repository/feed-state-file.ts @@ -17,6 +17,7 @@ export function loadFeedState(path: string): FeedState { return decodeFeedState(JSON.parse(readFileSync(path, "utf8"))); } +/** @internal */ export function saveFeedState(path: string, state: FeedState): void { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`); diff --git a/src/delivery/infra/repository/run-archive-files.ts b/src/delivery/infra/repository/run-archive-files.ts index fda9088..ae40f05 100644 --- a/src/delivery/infra/repository/run-archive-files.ts +++ b/src/delivery/infra/repository/run-archive-files.ts @@ -8,6 +8,7 @@ import type { RunAudit, RunDelivery, StoredRunAudit } from "../../domain/run-aud const toError = (error: unknown): Error => (error instanceof Error ? error : new Error(String(error))); +/** @internal */ export function saveRunArtifact( root: string, audit: RunAudit, @@ -26,6 +27,7 @@ export function saveRunArtifact( return { jsonPath, markdownPath }; } +/** @internal */ export function listRunArtifacts(root: string): string[] { if (!existsSync(root)) { return []; @@ -37,10 +39,12 @@ export function listRunArtifacts(root: string): string[] { .reverse(); } +/** @internal */ export function loadRunArtifact(path: string): StoredRunAudit { return JSON.parse(readFileSync(path, "utf8")) as StoredRunAudit; } +/** @internal */ export function runArtifactLabel(path: string): string { return basename(path, ".json"); } diff --git a/src/editorial/domain/daily-ai/index.ts b/src/editorial/domain/daily-ai/index.ts index 97c9d1a..4f12dde 100644 --- a/src/editorial/domain/daily-ai/index.ts +++ b/src/editorial/domain/daily-ai/index.ts @@ -1,3 +1,4 @@ +/** @internal */ export { validateEditorialDraft } from "./policies/editorial-draft.js"; export { buildDailyAiDigest, industryEvidence } from "./services/digest.js"; export { diff --git a/src/editorial/domain/evidence/index.ts b/src/editorial/domain/evidence/index.ts index f628e0d..437c8b1 100644 --- a/src/editorial/domain/evidence/index.ts +++ b/src/editorial/domain/evidence/index.ts @@ -1,10 +1,11 @@ export { invalidEditorialCollectionMessage, invalidEditorialItemMessage, - validateSubscriptionEditorialDraft, validateSubscriptionResearch, validateSubscriptionSelectionDraft } from "./policies/validation.js"; +/** @internal */ +export { validateSubscriptionEditorialDraft } from "./policies/validation.js"; export { assembleSubscriptionEditorial, assembleSubscriptionEvidence, diff --git a/src/editorial/domain/news/policies/news-funnel.ts b/src/editorial/domain/news/policies/news-funnel.ts index 526af90..edea182 100644 --- a/src/editorial/domain/news/policies/news-funnel.ts +++ b/src/editorial/domain/news/policies/news-funnel.ts @@ -195,6 +195,7 @@ export function buildNewsStoriesWithAudit(hits: NewsSearchHit[], window: NewsTim }; } +/** @internal */ export function buildNewsStories(hits: NewsSearchHit[], window: NewsTimeWindow): NewsStory[] { return buildNewsStoriesWithAudit(hits, window).stories; } @@ -250,6 +251,7 @@ export function selectNewsStoriesWithAudit( }; } +/** @internal */ export function selectNewsStories(stories: NewsStory[], topics: readonly NewsTopic[]): SelectedNewsStory[] { return selectNewsStoriesWithAudit(stories, topics).stories; } diff --git a/src/editorial/domain/subscription/index.ts b/src/editorial/domain/subscription/index.ts index c475934..a0dae31 100644 --- a/src/editorial/domain/subscription/index.ts +++ b/src/editorial/domain/subscription/index.ts @@ -1,9 +1,10 @@ export { presentationDecisionForCandidate, - presentationDepthForCandidate, repositoryFactsForCandidate, selectCandidatePresentationSections } from "./policies/presentation.js"; +/** @internal */ +export { presentationDepthForCandidate } from "./policies/presentation.js"; export { scoreAcquired, selectResearchCandidates } from "./policies/scoring.js"; export { applyEditorialSelectionToAudit } from "./services/editorial-audit.js"; export type { diff --git a/src/editorial/domain/subscription/policies/presentation.ts b/src/editorial/domain/subscription/policies/presentation.ts index d19388e..43eb651 100644 --- a/src/editorial/domain/subscription/policies/presentation.ts +++ b/src/editorial/domain/subscription/policies/presentation.ts @@ -71,7 +71,9 @@ export function presentationDecisionForCandidate( return { depth: "link", reasonCode: "ordinary-update" }; } -/** Decide how much space a candidate deserves without coupling ranking to Markdown. */ +/** Decide how much space a candidate deserves without coupling ranking to Markdown. + * @internal + */ export function presentationDepthForCandidate( candidate: CandidateProject, policy: PresentationPolicy = {} diff --git a/src/editorial/index.ts b/src/editorial/index.ts index bf69b5c..ab6d116 100644 --- a/src/editorial/index.ts +++ b/src/editorial/index.ts @@ -1,28 +1,25 @@ export type { CandidateDecision } from "./domain/decision/index.js"; -export { - buildDailyAiDigest, - cleanDailyAiTitle, - dailyAiCategories, - industryEvidence, - validateEditorialDraft -} from "./domain/daily-ai/index.js"; +export { buildDailyAiDigest, cleanDailyAiTitle, dailyAiCategories, industryEvidence } from "./domain/daily-ai/index.js"; +/** @internal */ +export { validateEditorialDraft } from "./domain/daily-ai/index.js"; export type { DailyAiDigest, DailyAiEditorialItem, DailyAiEvidence } from "./domain/daily-ai/index.js"; export { excludeSubscriptionResearchFailures, - validateSubscriptionEditorialDraft, validateSubscriptionResearch, validateSubscriptionSelectionDraft } from "./domain/evidence/index.js"; +/** @internal */ +export { validateSubscriptionEditorialDraft } from "./domain/evidence/index.js"; export type { SubscriptionEvidence } from "./domain/evidence/index.js"; export { applyEditorialSelectionToAudit, - presentationDecisionForCandidate, - presentationDepthForCandidate, repositoryFactsForCandidate, scoreAcquired, selectCandidatePresentationSections, selectResearchCandidates } from "./domain/subscription/index.js"; +/** @internal */ +export { presentationDecisionForCandidate, presentationDepthForCandidate } from "./domain/subscription/index.js"; export type { CandidateProject } from "./domain/subscription/index.js"; export { assembleSubscriptionEditorial, diff --git a/src/integrations/deepseek/client.ts b/src/integrations/deepseek/client.ts index 531bc1d..c250716 100644 --- a/src/integrations/deepseek/client.ts +++ b/src/integrations/deepseek/client.ts @@ -18,6 +18,7 @@ type SearchInputContract = { /** The endpoint rejects queries longer than 128 characters. */ const maxOutgoingQueryLength = 128; +/** @internal */ export function validateDeepSeekInput(input: SearchInputContract): void { if (input.query.trim() === "" || input.query.length > 128) { throw new Error("DeepSeek search query must contain 1 to 128 characters."); @@ -34,6 +35,7 @@ export function validateDeepSeekInput(input: SearchInputContract): void { * (as seen from the caller's timezone offset) unless the query already * constrains the window itself, truncating the keywords — never the operator — * to stay within the length limit. + * @internal */ export function deepSeekOutgoingQuery(query: string, sinceDay?: string): string { if (!sinceDay) { diff --git a/src/integrations/deepseek/mapper.ts b/src/integrations/deepseek/mapper.ts index 577fa3e..0e1d16b 100644 --- a/src/integrations/deepseek/mapper.ts +++ b/src/integrations/deepseek/mapper.ts @@ -7,6 +7,7 @@ import { itemFromPublication } from "../shared/search-item.js"; * A provider authority score (0–4, `-1` unknown): 3 and above is highly * authoritative, every other value stays unrated. The scale has no official * level, so a result carrying such a score is never official. + * @internal */ export function credibilityForAuthority(authority: number | undefined): { tier: CredibilityTier; diff --git a/src/integrations/deepseek/provider.test.ts b/src/integrations/deepseek/provider.test.ts deleted file mode 100644 index 2c449f6..0000000 --- a/src/integrations/deepseek/provider.test.ts +++ /dev/null @@ -1,49 +0,0 @@ -import { Effect } from "effect"; - -import { SearchProvider } from "../../acquisition/index.js"; -import { describeSearchProvider, type ProviderStep } from "../../../tests/support/search-provider-suite.js"; - -import { DeepSeekSearchLive } from "./provider.js"; - -describeSearchProvider({ - name: "deepseek", - emitsRateLimit: true, - cacheable: true, - create(next) { - let invocations = 0; - return { - invocations: () => invocations, - search: (value) => { - invocations += 1; - const step: ProviderStep = next(); - const fetchImpl: typeof fetch = async () => { - if (step === "http_429") { - return new Response("slow", { status: 429 }); - } - if (step === "permanent") { - return new Response("no", { status: 500 }); - } - return new Response( - JSON.stringify({ - results: [ - { - rerank_score: 2.4, - title: "Suite", - url: "https://example.com/suite", - snippet: "Suite result", - site_name: "Example", - date: "2026-08-16T02:00:00Z", - authority: 3 - } - ] - }) - ); - }; - return Effect.gen(function* () { - const provider = yield* SearchProvider; - return yield* provider.search(value); - }).pipe(Effect.provide(DeepSeekSearchLive({ apiKey: "suite", fetch: fetchImpl }))); - } - }; - } -}); diff --git a/src/integrations/deepseek/provider.ts b/src/integrations/deepseek/provider.ts deleted file mode 100644 index 97a044f..0000000 --- a/src/integrations/deepseek/provider.ts +++ /dev/null @@ -1,16 +0,0 @@ -import type { Layer } from "effect"; - -import type { SearchProvider } from "../../acquisition/index.js"; - -import { searchProviderLayer } from "../shared/search-plumbing.js"; -import { DeepSeekSearchClient } from "./client.js"; - -export type DeepSeekSearchClientOptions = { - apiKey: string; - baseUrl?: string; - fetch?: typeof fetch; - timeoutMs?: number; -}; - -export const DeepSeekSearchLive = (options: DeepSeekSearchClientOptions): Layer.Layer => - searchProviderLayer(new DeepSeekSearchClient(options)); diff --git a/src/integrations/doubao/client.ts b/src/integrations/doubao/client.ts index 2ab1f42..6c0cb6e 100644 --- a/src/integrations/doubao/client.ts +++ b/src/integrations/doubao/client.ts @@ -18,6 +18,7 @@ type SearchInputContract = { sourcePolicy: string; }; +/** @internal */ export function validateDoubaoInput(input: SearchInputContract): void { if (input.query.trim() === "" || input.query.length > 100) { throw new Error("Doubao search query must contain 1 to 100 characters."); diff --git a/src/integrations/doubao/index.ts b/src/integrations/doubao/index.ts index d1a7679..1b4b4d9 100644 --- a/src/integrations/doubao/index.ts +++ b/src/integrations/doubao/index.ts @@ -1,2 +1,3 @@ export { DoubaoSearchClient } from "./client.js"; +/** @internal */ export { DoubaoSearchError } from "./dto.js"; diff --git a/src/integrations/doubao/mapper.ts b/src/integrations/doubao/mapper.ts index 9043dca..5276f91 100644 --- a/src/integrations/doubao/mapper.ts +++ b/src/integrations/doubao/mapper.ts @@ -5,6 +5,7 @@ import { itemFromPublication } from "../shared/search-item.js"; /** * Authority levels follow the news score table: 1 is an official source, * 2 is authoritative, and every other level stays unrated. + * @internal */ export function credibilityForAuthLevel(level: number | undefined): { tier: CredibilityTier } { if (level === 1) { diff --git a/src/integrations/doubao/provider.test.ts b/src/integrations/doubao/provider.test.ts deleted file mode 100644 index a6ceb54..0000000 --- a/src/integrations/doubao/provider.test.ts +++ /dev/null @@ -1,42 +0,0 @@ -import { Effect } from "effect"; - -import { SearchProvider } from "../../acquisition/index.js"; -import { describeSearchProvider, type ProviderStep } from "../../../tests/support/search-provider-suite.js"; - -import { DoubaoSearchLive } from "./provider.js"; - -describeSearchProvider({ - name: "doubao", - emitsRateLimit: true, - cacheable: true, - create(next) { - let invocations = 0; - return { - invocations: () => invocations, - search: (value) => { - invocations += 1; - const step: ProviderStep = next(); - const fetchImpl: typeof fetch = async () => { - if (step === "http_429") { - return new Response("slow", { status: 429 }); - } - if (step === "permanent") { - return new Response("no", { status: 500 }); - } - return new Response( - JSON.stringify({ - Result: { - ResultCount: 1, - WebResults: [{ Id: "suite", Title: "Suite", Url: "https://example.com/suite", SortId: 1 }] - } - }) - ); - }; - return Effect.gen(function* () { - const provider = yield* SearchProvider; - return yield* provider.search(value); - }).pipe(Effect.provide(DoubaoSearchLive({ apiKey: "suite", fetch: fetchImpl }))); - } - }; - } -}); diff --git a/src/integrations/doubao/provider.ts b/src/integrations/doubao/provider.ts deleted file mode 100644 index b413139..0000000 --- a/src/integrations/doubao/provider.ts +++ /dev/null @@ -1,16 +0,0 @@ -import type { Layer } from "effect"; - -import type { SearchProvider } from "../../acquisition/index.js"; - -import { searchProviderLayer } from "../shared/search-plumbing.js"; -import { DoubaoSearchClient } from "./client.js"; - -export type DoubaoSearchClientOptions = { - apiKey: string; - baseUrl?: string; - fetch?: typeof fetch; - timeoutMs?: number; -}; - -export const DoubaoSearchLive = (options: DoubaoSearchClientOptions): Layer.Layer => - searchProviderLayer(new DoubaoSearchClient(options)); diff --git a/src/integrations/github/client.ts b/src/integrations/github/client.ts index 0492ee6..5fe0cff 100644 --- a/src/integrations/github/client.ts +++ b/src/integrations/github/client.ts @@ -10,6 +10,7 @@ export type GitHubRestOptions = { fetch?: typeof fetch; }; +/** @internal */ export const githubHeaders = (token: string | undefined): Record => { const headers: Record = { Accept: "application/vnd.github+json", diff --git a/src/integrations/github/event/dto.ts b/src/integrations/github/event/dto.ts index 21f5daf..506d9f3 100644 --- a/src/integrations/github/event/dto.ts +++ b/src/integrations/github/event/dto.ts @@ -105,7 +105,9 @@ export function decodeEventCard(input: unknown): Result 0 && $("#conduit-feed-frame").length > 0; diff --git a/src/integrations/github/home/mapper.ts b/src/integrations/github/home/mapper.ts index 1ecd3d2..4538a99 100644 --- a/src/integrations/github/home/mapper.ts +++ b/src/integrations/github/home/mapper.ts @@ -147,6 +147,7 @@ function stringField(record: Record | null, key: string): strin return typeof value === "string" ? value : ""; } +/** @internal */ export function normalizeHomeCardSnapshot(snapshot: HomeFeedCardSnapshot): ActivityCardDto { const cardType = stringField(snapshot.card, "card_type"); const createdAt = stringField(snapshot.card, "created_at"); @@ -172,6 +173,7 @@ export function normalizeHomeCardSnapshot(snapshot: HomeFeedCardSnapshot): Activ }; } +/** @internal */ export function acquireHomeCard(input: unknown): Acquired { const card = normalizeHomeCardSnapshot(homeSnapshot(input)); return { card, item: itemFromGitHubCard(card) }; diff --git a/src/integrations/github/index.ts b/src/integrations/github/index.ts index 98eec0d..9f599f1 100644 --- a/src/integrations/github/index.ts +++ b/src/integrations/github/index.ts @@ -1,5 +1,7 @@ +/** @internal */ export { githubHeaders } from "./client.js"; export { GitHubCatalogLive } from "./catalog.js"; +/** @internal */ export { normalizeEvent } from "./event/dto.js"; export { saveLoginStorageState, type GithubHomeClientOptions } from "./home-browser.js"; export { GitHubActivityLive } from "./activity.js"; diff --git a/src/integrations/github/repository/mapper.test.ts b/src/integrations/github/repository/mapper.test.ts deleted file mode 100644 index 9accad9..0000000 --- a/src/integrations/github/repository/mapper.test.ts +++ /dev/null @@ -1,55 +0,0 @@ -import { describe, expect, it } from "vite-plus/test"; - -import { acquireFollowing, acquirePullRequest, acquireRepository } from "./mapper.js"; - -describe("github repository adapter", () => { - it("maps a repository document onto metadata and a project profile", () => { - const acquired = acquireRepository({ - full_name: "acme/agent-kit", - html_url: "https://github.com/acme/agent-kit", - description: "An agent harness", - language: "TypeScript", - stargazers_count: 1500, - topics: ["agent"], - pushed_at: "2026-07-30T10:00:00Z" - }); - expect(acquired.metadata).toEqual({ - fullName: "acme/agent-kit", - htmlUrl: "https://github.com/acme/agent-kit", - description: "An agent harness", - language: "TypeScript", - stargazersCount: 1500, - topics: ["agent"], - pushedAt: "2026-07-30T10:00:00Z" - }); - expect(acquired.item.subject.profile).toEqual({ - description: "An agent harness", - keywords: ["agent", "TypeScript"], - popularity: 1500, - lastActiveAt: "2026-07-30T10:00:00Z" - }); - expect(acquired.item.display.facts).toEqual(["⭐ 1.5k"]); - }); - - it("maps pull request details and followed accounts", () => { - const pull = acquirePullRequest( - { - title: "feat: add search", - html_url: "https://github.com/acme/agent-kit/pull/12", - body: "Adds search." - }, - "acme/agent-kit", - 12 - ); - expect(pull.details).toEqual({ - title: "feat: add search", - htmlUrl: "https://github.com/acme/agent-kit/pull/12", - body: "Adds search." - }); - expect(pull.item.subject.key).toBe("github-pull-request:acme/agent-kit:12"); - - const followed = acquireFollowing([{ login: "ada" }, { login: "" }, {}]); - expect(followed.logins).toEqual(["ada"]); - expect(followed.items[0]?.provenance.actor).toEqual({ name: "ada", followed: true }); - }); -}); diff --git a/src/integrations/github/repository/mapper.ts b/src/integrations/github/repository/mapper.ts deleted file mode 100644 index 0240457..0000000 --- a/src/integrations/github/repository/mapper.ts +++ /dev/null @@ -1,102 +0,0 @@ -import { formatCompactCount } from "../../../kernel/text.js"; -import type { Item, PullRequestDetails, RepositoryMetadata } from "../../../acquisition/index.js"; - -import { followingLogins, pullRequestDetails, repositoryMetadata } from "./dto.js"; - -export type RepositoryAcquired = { - metadata: RepositoryMetadata; - item: Item; -}; - -export type PullRequestAcquired = { - details: PullRequestDetails; - item: Item; -}; - -function repositoryItem(metadata: RepositoryMetadata): Item { - const keywords = [...metadata.topics, ...(metadata.language ? [metadata.language] : [])]; - return { - id: `repository:${metadata.fullName}`, - kind: "project", - subject: { - key: `github-repository:${metadata.fullName}`, - name: metadata.fullName, - ...(metadata.htmlUrl ? { url: metadata.htmlUrl } : {}), - profile: { - ...(metadata.description ? { description: metadata.description } : {}), - keywords, - popularity: metadata.stargazersCount, - ...(metadata.pushedAt ? { lastActiveAt: metadata.pushedAt } : {}) - } - }, - content: { - ...(metadata.description ? { excerpt: metadata.description } : {}), - ...(metadata.htmlUrl ? { url: metadata.htmlUrl } : {}) - }, - publishedAt: { value: metadata.pushedAt ?? "", precision: "instant" }, - provenance: { origin: metadata.htmlUrl || metadata.fullName }, - credibility: { tier: "official", method: "configured-domain" }, - signals: [], - display: { - ...(metadata.fullName ? { label: metadata.fullName } : {}), - ...(metadata.htmlUrl ? { reference: metadata.htmlUrl } : {}), - facts: [`⭐ ${formatCompactCount(metadata.stargazersCount)}`] - } - }; -} - -function pullRequestItem(details: PullRequestDetails, fullName: string, number: number): Item { - return { - id: `pull-request:${fullName}:${number}`, - kind: "change", - subject: { - key: `github-pull-request:${fullName}:${number}`, - name: fullName, - ...(details.htmlUrl ? { url: details.htmlUrl } : {}) - }, - content: { - ...(details.title ? { title: details.title } : {}), - ...(details.body ? { excerpt: details.body } : {}), - ...(details.htmlUrl ? { url: details.htmlUrl } : {}) - }, - publishedAt: { value: "", precision: "instant" }, - provenance: { origin: details.htmlUrl || fullName }, - credibility: { tier: "unrated" }, - signals: [{ type: "change-other", label: "pull request" }], - display: { - label: `${fullName} #${number}${details.title ? ` · ${details.title}` : ""}`, - ...(details.htmlUrl ? { reference: details.htmlUrl } : {}), - facts: [] - } - }; -} - -function followedAccount(login: string): Item { - const url = `https://github.com/${login}`; - return { - id: `follow:${login}`, - kind: "project", - subject: { key: `account:${login}`, name: login, url }, - content: { url }, - publishedAt: { value: "", precision: "instant" }, - provenance: { origin: url, actor: { name: login, followed: true } }, - credibility: { tier: "unrated" }, - signals: [{ type: "relationship", label: "follow relationship from GitHub Home" }], - display: { label: login, reference: url, facts: [] } - }; -} - -export function acquireRepository(input: unknown): RepositoryAcquired { - const metadata = repositoryMetadata(input); - return { metadata, item: repositoryItem(metadata) }; -} - -export function acquirePullRequest(input: unknown, fullName: string, number: number): PullRequestAcquired { - const details = pullRequestDetails(input); - return { details, item: pullRequestItem(details, fullName, number) }; -} - -export function acquireFollowing(input: unknown): { logins: string[]; items: Item[] } { - const logins = followingLogins(input); - return { logins, items: logins.map(followedAccount) }; -} diff --git a/src/integrations/glm/search/provider.ts b/src/integrations/glm/search/provider.ts index b36fd7f..4bfddb9 100644 --- a/src/integrations/glm/search/provider.ts +++ b/src/integrations/glm/search/provider.ts @@ -78,6 +78,7 @@ export class GlmSearchClient { } } +/** @internal */ export const GlmSearchLive = (options: Options): Layer.Layer => { const client = new GlmSearchClient(options); return Layer.succeed(SearchProvider, { diff --git a/src/integrations/grok/audit.ts b/src/integrations/grok/audit.ts index 5ecee12..fde8d2c 100644 --- a/src/integrations/grok/audit.ts +++ b/src/integrations/grok/audit.ts @@ -9,14 +9,17 @@ export function pageAudit(page: SearchPage): GrokSearchAudit | undefined { return (page as AuditedSearchPage).grok; } +/** @internal */ export function errorAudit(error: NewsSearchError): GrokSearchAudit | undefined { return (error as NewsSearchError & { grok?: GrokSearchAudit }).grok; } +/** @internal */ export function withPageAudit(page: SearchPage, grok: GrokSearchAudit | undefined): AuditedSearchPage { return grok ? { ...page, grok } : page; } +/** @internal */ export function clonePageAudit(grok: GrokSearchAudit | undefined): GrokSearchAudit | undefined { return grok ? { ...grok, nativeTools: [...grok.nativeTools] } : undefined; } diff --git a/src/integrations/grok/cli.test.ts b/src/integrations/grok/cli.test.ts index 0f5bf0f..5fc39f9 100644 --- a/src/integrations/grok/cli.test.ts +++ b/src/integrations/grok/cli.test.ts @@ -1,17 +1,28 @@ import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { Effect } from "effect"; +import { Effect, Layer } from "effect"; import { afterEach, describe, expect, it } from "vite-plus/test"; import { SearchProvider, type NewsSearchInput } from "../../acquisition/index.js"; -import { GrokSearchClient, GrokXClient } from "./cli.js"; -import { GrokSearchLive } from "./provider.js"; +import { GrokSearchClient, GrokXClient, type GrokSearchOptions } from "./cli.js"; import { describeSearchProvider } from "../../../tests/support/search-provider-suite.js"; const directories: string[] = []; afterEach(async () => { await Promise.all(directories.splice(0).map((path) => rm(path, { recursive: true, force: true }))); }); +// The transport suites exercise `GrokSearchClient` through the SearchProvider surface; +// the layer is built inline because the production wiring no longer ships a provider module. +const grokSearchLive = (options: GrokSearchOptions): Layer.Layer => { + const client = new GrokSearchClient(options); + return Layer.succeed(SearchProvider, { + search: (input) => + Effect.tryPromise({ + try: () => client.search(input), + catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))) + }) + }); +}; const publishedAt = "2026-10-08T01:00:00.000Z"; const postId = ((BigInt(Date.parse(publishedAt)) - 1288834974657n) << 22n).toString(); const post = { @@ -509,7 +520,7 @@ describeSearchProvider({ return yield* provider.search(value); }).pipe( Effect.provide( - GrokSearchLive({ + grokSearchLive({ executable: step === "permanent" ? "/no/such/grok-suite" : executable, timezoneOffset: "+08:00", timeoutMs: 5_000 diff --git a/src/integrations/grok/provider.ts b/src/integrations/grok/provider.ts deleted file mode 100644 index 63056a5..0000000 --- a/src/integrations/grok/provider.ts +++ /dev/null @@ -1,16 +0,0 @@ -import { Effect, Layer } from "effect"; - -import { SearchProvider } from "../../acquisition/index.js"; - -import { GrokSearchClient, type GrokSearchOptions } from "./cli.js"; - -export const GrokSearchLive = (options: GrokSearchOptions): Layer.Layer => { - const client = new GrokSearchClient(options); - return Layer.succeed(SearchProvider, { - search: (input) => - Effect.tryPromise({ - try: () => client.search(input), - catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))) - }) - }); -}; diff --git a/src/integrations/grok/search/dto.ts b/src/integrations/grok/search/dto.ts index 28d37df..db4ec14 100644 --- a/src/integrations/grok/search/dto.ts +++ b/src/integrations/grok/search/dto.ts @@ -31,6 +31,7 @@ export type GrokRequest = typeof grokRequestSchema.Type; export { responseSchema }; +/** @internal */ export function isNativeCall( event: Record ): event is Record & { toolCallId: string } { @@ -43,6 +44,7 @@ export function isNativeCall( ); } +/** @internal */ export function isNativeReceipt( event: Record, calls: Set diff --git a/src/integrations/rss/client.ts b/src/integrations/rss/client.ts index f61063c..85bd0cf 100644 --- a/src/integrations/rss/client.ts +++ b/src/integrations/rss/client.ts @@ -6,6 +6,7 @@ import type { ActivityCardDto, FeedSubscription } from "../../acquisition/index. import { parseFeedXml } from "./mapper.js"; import { asError, provideHttp, timeoutFetch } from "../shared/http.js"; +/** @internal */ export const rssHeaders = { accept: "application/rss+xml, application/atom+xml, application/xml, text/xml;q=0.9, */*;q=0.8", "user-agent": "rss-summary/0.1" diff --git a/src/integrations/rss/index.ts b/src/integrations/rss/index.ts index 1763db2..f349fca 100644 --- a/src/integrations/rss/index.ts +++ b/src/integrations/rss/index.ts @@ -1,3 +1,4 @@ +/** @internal */ export { rssHeaders } from "./client.js"; export { isDailyAiPaperSource } from "./mapper.js"; export { RssFeedLive } from "./feed.js"; diff --git a/src/integrations/rss/mapper.ts b/src/integrations/rss/mapper.ts index e33b34e..2d82ad5 100644 --- a/src/integrations/rss/mapper.ts +++ b/src/integrations/rss/mapper.ts @@ -24,6 +24,7 @@ function hostIsAcademic(value: string | undefined): boolean { * the academic-host convention (arXiv hosts publish papers). Academic hosts * are checked on the entry URL and the feed URL; a releases tag wins only * when the entry is not academic. + * @internal */ export function rssPublicationType( htmlUrl: string | undefined, @@ -156,6 +157,7 @@ export function parseFeedXml(xml: string, feed: FeedSubscription, now: Date): Ac ]; } +/** @internal */ export function parseFeed(xml: string, feed: FeedSubscription, now: Date): Acquired[] { return parseFeedXml(xml, feed, now).map((card) => publicationAcquired(card)); } diff --git a/src/integrations/shared/index.ts b/src/integrations/shared/index.ts index ed5caca..f0b94bb 100644 --- a/src/integrations/shared/index.ts +++ b/src/integrations/shared/index.ts @@ -1,3 +1,6 @@ +/** @internal */ export { publicationAcquired } from "./activity-card.js"; -export { acquireActivityCard, applyScoringContext, projectActivity, refreshRouting } from "./scoring-trace.js"; +export { applyScoringContext, refreshRouting } from "./scoring-trace.js"; +/** @internal */ +export { acquireActivityCard, projectActivity } from "./scoring-trace.js"; export { candidateEvidenceUrl, candidateIdentity, researchKeyForCandidate } from "./identity.js"; diff --git a/src/integrations/shared/scoring-trace.ts b/src/integrations/shared/scoring-trace.ts index 6cd9275..9e0ab8e 100644 --- a/src/integrations/shared/scoring-trace.ts +++ b/src/integrations/shared/scoring-trace.ts @@ -128,6 +128,7 @@ export function applyScoringContext(acquired: Acquired, context: ScoringContext) }; } +/** @internal */ export function projectActivity(card: ActivityCardDto, context: ScoringContext): Acquired { return applyScoringContext(acquireActivityCard(card), context); } diff --git a/src/integrations/shared/search-plumbing.ts b/src/integrations/shared/search-plumbing.ts index 79bfa99..64f00bc 100644 --- a/src/integrations/shared/search-plumbing.ts +++ b/src/integrations/shared/search-plumbing.ts @@ -64,7 +64,9 @@ export async function postSearchJson(options: { return { response, retryAfterMs }; } -/** The Effect layer every search client lives behind: its `search` over a checked `Error`. */ +/** The Effect layer every search client lives behind: its `search` over a checked `Error`. + * @internal + */ export function searchProviderLayer(client: { search: (input: SearchInput) => Promise; }): Layer.Layer { diff --git a/src/integrations/web-page/client.ts b/src/integrations/web-page/client.ts index 6eac528..1112888 100644 --- a/src/integrations/web-page/client.ts +++ b/src/integrations/web-page/client.ts @@ -7,6 +7,7 @@ import { extractWebPageEntries } from "./dto.js"; import { normalizeWebPageEntry } from "./mapper.js"; import { asError, provideHttp, timeoutFetch } from "../shared/http.js"; +/** @internal */ export const webHeaders = { accept: "text/html, application/xhtml+xml;q=0.9, */*;q=0.8", "user-agent": "rss-summary/0.1" diff --git a/src/integrations/web-page/index.ts b/src/integrations/web-page/index.ts index 7ae0848..eae20a2 100644 --- a/src/integrations/web-page/index.ts +++ b/src/integrations/web-page/index.ts @@ -1,2 +1,3 @@ +/** @internal */ export { webHeaders } from "./client.js"; export { WebPageLive } from "./feed.js"; diff --git a/src/integrations/web-page/mapper.ts b/src/integrations/web-page/mapper.ts index 54ccef7..08eee6a 100644 --- a/src/integrations/web-page/mapper.ts +++ b/src/integrations/web-page/mapper.ts @@ -22,6 +22,7 @@ export function normalizeWebPageEntry(entry: WebPageEntry, source: WebPageSubscr }; } +/** @internal */ export function acquireWebPage(html: string, source: WebPageSubscription): Acquired[] { return extractWebPageEntries(html, source).flatMap((entry) => { const decoded = decodeEntry(entry); diff --git a/src/kernel/result.ts b/src/kernel/result.ts index 429fa1b..72877b1 100644 --- a/src/kernel/result.ts +++ b/src/kernel/result.ts @@ -8,6 +8,7 @@ export function err(error: E): Result { return { _tag: "Err", error }; } +/** @internal */ export function isOk(result: Result): result is { readonly _tag: "Ok"; readonly value: A } { return result._tag === "Ok"; } diff --git a/src/reading/domain/document/policies/url-policy.ts b/src/reading/domain/document/policies/url-policy.ts index 6531979..35776d8 100644 --- a/src/reading/domain/document/policies/url-policy.ts +++ b/src/reading/domain/document/policies/url-policy.ts @@ -1,3 +1,4 @@ +/** @internal */ export function isPrivateIpv4(hostname: string): boolean { const octets = hostname.split(".").map(Number); if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) { diff --git a/src/reading/domain/document/value-objects/document.ts b/src/reading/domain/document/value-objects/document.ts index 32a7179..7dfbf09 100644 --- a/src/reading/domain/document/value-objects/document.ts +++ b/src/reading/domain/document/value-objects/document.ts @@ -1,3 +1,4 @@ +/** @internal */ export const documentMethods = ["browser", "http", "captions", "transcription"] as const; export type DocumentMethod = (typeof documentMethods)[number]; @@ -22,7 +23,9 @@ export type DocumentMaterials = { manifestPath: string; }; -/** Successful read of one URL. `method` excludes the reader name that the source-vocabulary rule forbids in domain. */ +/** Successful read of one URL. `method` excludes the reader name that the source-vocabulary rule forbids in domain. + * @internal + */ export type Document = { url: string; fetchedUrl: string; diff --git a/tests/repo/ci-harness.test.ts b/tests/repo/ci-harness.test.ts index 951994d..afa30ee 100644 --- a/tests/repo/ci-harness.test.ts +++ b/tests/repo/ci-harness.test.ts @@ -9,7 +9,7 @@ describe("CI harness", () => { }; expect(pkg.scripts?.verify).toBe( - "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm test && pnpm build && pnpm package:check" + "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm knip:production && pnpm test && pnpm build && pnpm package:check" ); expect(pkg.scripts?.check).toBe("vp check"); expect(pkg.scripts?.lint).toBe("vp lint"); diff --git a/tests/repo/package-bin.test.ts b/tests/repo/package-bin.test.ts index e2140dd..9501037 100644 --- a/tests/repo/package-bin.test.ts +++ b/tests/repo/package-bin.test.ts @@ -55,7 +55,7 @@ describe("package CLI metadata", () => { expect(pkg.scripts?.build).toBe("tsc -p tsconfig.build.json"); expect(pkg.scripts?.["package:check"]).toBe("node scripts/check-package.mjs"); expect(pkg.scripts?.verify).toBe( - "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm test && pnpm build && pnpm package:check" + "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm knip:production && pnpm test && pnpm build && pnpm package:check" ); expect(buildConfig.compilerOptions?.declaration).toBe(true); });