Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,10 +174,11 @@ rss-summary runs show <run-label>
## 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` 通过后再合并。
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/technology-decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions src/acquisition/application/ports.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ export type GrokProcessRequest = {
timeoutMs?: number;
};

/** @internal */
export class GrokProcess extends Context.Service<
GrokProcess,
{
Expand Down
1 change: 1 addition & 0 deletions src/acquisition/application/services/with-fallback.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
6 changes: 5 additions & 1 deletion src/acquisition/application/services/with-retry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -40,6 +42,7 @@ function retrySchedule(attemptBase = 0) {
);
}

/** @internal */
export function retryEffect<A>(run: () => Promise<A>, attemptBase = 0) {
return Effect.tryPromise({
try: run,
Expand Down Expand Up @@ -80,6 +83,7 @@ function provideRetryClock<A, E, R>(
return provided;
}

/** @internal */
export function searchWithRetry(
input: SearchInput,
search: (input: SearchInput) => Promise<SearchPage>,
Expand Down
1 change: 1 addition & 0 deletions src/acquisition/application/use-cases/collect-x-posts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ type XAccountClient = {
search: (value: GrokProcessRequest) => Promise<SearchPage>;
};

/** @internal */
export type OpenSearchBudget = (options: {
provider: string;
stateFile: string;
Expand Down
3 changes: 2 additions & 1 deletion src/acquisition/domain/budget/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
1 change: 1 addition & 0 deletions src/acquisition/domain/budget/value-objects/budget.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ export type Reservation = {
cached?: SearchPage;
};

/** @internal */
export function cacheKeyMaterial(request: CacheRequest): string {
return JSON.stringify([
request.provider,
Expand Down
4 changes: 2 additions & 2 deletions src/acquisition/domain/search/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ export type {
MergedSearchSource,
NativeSearchReceipt,
NewsSearchInput,
NewsSearchPage,
NewsSearchResult,
ProviderFallback,
SearchFallback,
SearchHitFields,
Expand All @@ -16,3 +14,5 @@ export type {
SearchUsage,
SourceVerification
} from "./value-objects/search.js";
/** @internal */
export type { NewsSearchPage, NewsSearchResult } from "./value-objects/search.js";
2 changes: 2 additions & 0 deletions src/acquisition/domain/search/value-objects/search.ts
Original file line number Diff line number Diff line change
Expand Up @@ -120,5 +120,7 @@ export type SearchFallback = {
};

export type NewsSearchInput = SearchInput;
/** @internal */
export type NewsSearchResult = SearchResult;
/** @internal */
export type NewsSearchPage = SearchPage;
9 changes: 3 additions & 6 deletions src/acquisition/domain/source/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
8 changes: 5 additions & 3 deletions src/acquisition/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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";
Expand Down
1 change: 1 addition & 0 deletions src/app/cli/github-home.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
1 change: 1 addition & 0 deletions src/app/config/assets.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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));
Expand Down
4 changes: 4 additions & 0 deletions src/app/config/parse.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -61,6 +62,7 @@ export function optionalBoolean(value: unknown, fallback: boolean, label: string
return value;
}

/** @internal */
export function requireBoundedInteger(
value: unknown,
fallback: number,
Expand All @@ -78,6 +80,7 @@ export function requireBoundedInteger(
return Number(value);
}

/** @internal */
export function requireBoundedNumber(
value: unknown,
fallback: number,
Expand Down Expand Up @@ -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);
Expand Down
8 changes: 6 additions & 2 deletions src/app/config/state-root.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down
8 changes: 7 additions & 1 deletion src/app/layers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ export function ReadingLive(
return Layer.mergeAll(http, browser, video, glm);
}

/** @internal */
export type AcquisitionOptions = {
token?: string;
fetch?: typeof fetch;
Expand All @@ -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 = {}
Expand Down Expand Up @@ -151,6 +153,7 @@ export type AppServices =
| VideoReader
| GlmReader;

/** @internal */
export type AppLiveOptions = {
acquisition?: AcquisitionOptions;
delivery?: DeliveryOptions;
Expand All @@ -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<AppServices> {
return Layer.provideMerge(
Expand All @@ -169,7 +173,9 @@ export function AppLive(options: AppLiveOptions = {}): Layer.Layer<AppServices>
);
}

/** Layer options derived from a resolved configuration. */
/** Layer options derived from a resolved configuration.
* @internal
*/
export function appLiveOptions(config: AppConfig): AppLiveOptions {
return {
acquisition: {
Expand Down
4 changes: 4 additions & 0 deletions src/app/products/news/flow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions src/app/products/news/topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)) {
Expand Down
1 change: 1 addition & 0 deletions src/app/products/research/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
5 changes: 4 additions & 1 deletion src/app/products/subscriptions/output.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,9 +82,12 @@ export function applySubscriptionSelection<T extends DigestDocument>(
};
}

/** @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<string, { at: string; decision?: string; reason?: string }> },
candidate: CandidateProject,
Expand Down
1 change: 1 addition & 0 deletions src/app/render/automation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
3 changes: 3 additions & 0 deletions src/app/render/layouts/candidate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -15,6 +16,7 @@ export type CandidateCopy = {
summary: string;
};

/** @internal */
export type CandidateCopyOptions = {
editorialSummary?: string;
};
Expand Down Expand Up @@ -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}`;
Expand Down
Loading
Loading