etymd 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -154,6 +154,11 @@ interface ContextFile {
     role: string;
     words: number;
     approxTokens: number;
+    /**
+     * Other always-loaded names that are THIS SAME FILE — a symlink or hardlink resolving to one
+     * inode. Present so output can name every alias while the words are counted once.
+     */
+    aliases?: string[];
 }
 interface ContextBudget {
     files: ContextFile[];
@@ -681,6 +686,169 @@ declare function sweepFleet(manifest: FleetManifest, opts?: FleetSweepOptions):
  */
 declare const instructionTruthLens: Lens;
 
+/** Everything a truth check needs from the repo, resolved once per run. */
+interface TruthEnv {
+    root: string;
+    facts: ProjectFacts;
+    /** Package scripts across the root and every workspace manifest. */
+    knownScripts: Set<string>;
+    nodeModulesInstalled: boolean;
+    /** A manifest exists somewhere, so a script claim is checkable even without an install. */
+    manifestExists: boolean;
+    /** The root plus every workspace package dir — where claims are resolved. */
+    bases: string[];
+    /** A repo-relative claim resolves in the root, any workspace package, or their src/ scripts/. */
+    pathResolves(claim: string): Promise<boolean>;
+    /** `yarn X` / `pnpm X` may legitimately run an installed node_modules/.bin binary. */
+    binResolves(name: string): Promise<boolean>;
+}
+declare function buildTruthEnv(root: string, facts: ProjectFacts): Promise<TruthEnv>;
+/** Skip-class tallies — every class a check declines to accuse is counted, then disclosed. */
+interface ClaimCounters {
+    filteredSkipped: number;
+    tildeSkipped: number;
+    binaryResolved: number;
+    unverifiableCommands: number;
+    gitignoredSkipped: number;
+    prospectiveSkipped: number;
+    placeholderSkipped: number;
+    /** Decision references naming another record (a fleet-level ledger) — not this repo's. */
+    qualifiedRefsSkipped: number;
+    /** Decision references with no `## D-NNN` ledger to resolve against. */
+    unresolvableRefs: number;
+}
+declare function emptyCounters(): ClaimCounters;
+/**
+ * One thing a check looked for, and what it found. `null` = could not be checked from the repo
+ * (counted and disclosed), never a guess. The honest-coverage half of a report: what was
+ * examined, not only what failed.
+ */
+interface ExaminedClaim {
+    kind: "script" | "path" | "doc" | "decision";
+    value: string;
+    exists: boolean | null;
+}
+/** A piece of text making claims about the repo: an instruction file, a state doc, a task. */
+interface ClaimText {
+    /** Repo-relative path, or a label such as `task` — becomes part of every finding id. */
+    path: string;
+    text: string;
+}
+interface TextClaimsOptions {
+    /** The lens the findings report under (`instruction-truth`, `premise`). */
+    lensId: string;
+    /** How the text is named in a claim sentence — a file path, or "The task". */
+    subject?: string;
+    /**
+     * A missing path is `gap` for an instruction file (a dead reference among many) and `risk` for
+     * a task (the task is ABOUT the path — an agent acting on it does the wrong thing).
+     */
+    missingPathTier: FindingTier;
+    maxPathFindings: number;
+    whyCommand?: string;
+    actionCommand?: string;
+    whyPath?: string;
+    actionPath?: string;
+}
+interface TextClaimsResult {
+    findings: Finding[];
+    disclosures: string[];
+    /** Every script and path claim the text made, found or not. */
+    examined: ExaminedClaim[];
+}
+/**
+ * Command and path claims in one text, verified against the repo. Precision over recall: every
+ * class it declines to accuse is counted in `counters` for the caller to disclose.
+ */
+declare function checkTextClaims(env: TruthEnv, file: ClaimText, opts: TextClaimsOptions, counters: ClaimCounters): Promise<TextClaimsResult>;
+interface RefsResult {
+    findings: Finding[];
+    examined: ExaminedClaim[];
+}
+/** Cross-references to well-known docs (AGENTS.md, CLAUDE.md, …) must resolve to real files. */
+declare function checkDocRefs(env: TruthEnv, file: ClaimText, lensId: string, counters: ClaimCounters, subject?: string): Promise<RefsResult>;
+/** The repo's own decision record: every `## D-NNN` id, and which files carried them. */
+interface DecisionLedger {
+    /** Null when no decisions file with parseable `## D-NNN` entries exists. */
+    ids: Set<number> | null;
+    sources: string[];
+}
+declare function loadDecisionLedger(root: string, facts: ProjectFacts): Promise<DecisionLedger>;
+interface DecisionRefsOptions {
+    lensId: string;
+    /** How the text is named in a claim sentence — a file path, or "The task". */
+    subject?: string;
+    why?: string;
+    action?: string;
+}
+/**
+ * `D-NNN` references in one text, resolved against the repo's own decision record. A citation
+ * the record cannot back is stale in a way age cannot reveal. Qualified refs (another record's)
+ * and refs with no ledger to resolve against are counted, never accused.
+ */
+declare function checkDecisionRefs(file: ClaimText, ledger: DecisionLedger, opts: DecisionRefsOptions, counters: ClaimCounters): RefsResult;
+
+declare const PREMISE_LENS = "premise";
+declare const PREMISE_BRIEF_FILE: string;
+/** One thing the task named, found or not — the checked half of the brief. */
+type PremiseEntity = ExaminedClaim;
+interface PremiseResult {
+    /** The `--json` schema version. */
+    schema: "premise/1";
+    task: string;
+    /** Where the task came from: `argument`, `stdin`, or the file path it was read from. */
+    source: string;
+    /** The project name from the reckoning. */
+    name: string;
+    findings: Finding[];
+    disclosures: string[];
+    /** Everything the task named that etymd could look for — found or not. */
+    entities: PremiseEntity[];
+    brief: string;
+    /** Repo-relative path the brief was written to, or `null` when the repo never opted in. */
+    briefPath: string | null;
+}
+interface PremiseOptions {
+    root: string;
+    task: string;
+    source?: string;
+    /** Write the brief under `.etymd/` when that directory exists (default true). */
+    writeBrief?: boolean;
+}
+/** What the prose promotion declined to read as a claim — counted, then disclosed. */
+interface PromotionSkips {
+    /** `pnpm X` / `yarn X` / `bun X` in prose without `run` — a phrase as often as an invocation. */
+    bareInvocations: number;
+    /** `… run the`, `… run X` — a function word or a one-letter stand-in where a script would be. */
+    proseScripts: number;
+    /** `github.com/org/repo/…` — a scheme-less URL, not a repo path. */
+    hostnameLike: number;
+    /** `input/output/` — a slash-joined phrase whose first segment is no directory here. */
+    unrootedDirs: number;
+}
+interface PromotionContext {
+    /** Directory names that exist at the root, in a workspace package, or under their src/ scripts/. */
+    rootedDirs: ReadonlySet<string>;
+}
+interface PromotedText {
+    text: string;
+    skips: PromotionSkips;
+}
+/**
+ * People do not backtick paths in a prompt. Promote the bare mentions the claim extractors would
+ * otherwise treat as prose — `src/x.ts`, `docs/design/`, `npm run lint` — into code spans, leaving
+ * anything already in a code span untouched. Precision over recall: only what an instruction
+ * file's extractor would accept is promoted, and every class left as prose is counted.
+ */
+declare function promoteBareTokens(text: string, ctx: PromotionContext): PromotedText;
+declare function runPremise(opts: PremiseOptions): Promise<PremiseResult>;
+/**
+ * The half of the premise check only an agent can do, written as a brief it reads before acting.
+ * Deterministic: it lists what etymd verified and hands over the three questions reading files
+ * cannot answer. It never speculates about what the task "really" means.
+ */
+declare function renderBrief(task: string, findings: Finding[], entities: PremiseEntity[]): string;
+
 interface InstructionFile {
     /** Repo-relative path. */
     path: string;
@@ -811,10 +979,13 @@ declare const gateIntegrityLens: Lens;
  * The knowledge-pack version — bumped whenever templates, the rubric, or the encoded rules
  * change meaning. Stamped into facts, baselines, and generated artifacts so drift against the
  * pack is computable and `harvest` has something to diff.
+ *
+ * Gaps in the sequence are deliberate: a number stays retired even when the change that took it
+ * never shipped, so a version cited in a baseline or a record means exactly one pack, ever.
  */
-declare const PACK_VERSION = "8";
+declare const PACK_VERSION = "12";
 
 declare const VERSION: string;
 declare const NAME: string;
 
-export { type ApplyResult, type ArtifactFreshness, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ContextBudget, type ContextBudgets, type ContextFile, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, FLEET_JSON_SCHEMA, FLEET_LENS, type Finding, type FleetContract, type FleetEntry, type FleetManifest, type FleetProfile, type FleetProjectSweep, type FleetSweepOptions, type FleetSweepResult, type FreshnessFacts, type GateInventory, type GateTool, type GeneratedFile, type HookFacts, type InstructionFileSet, type InstructionScope, LENSES, type Ledger, type LedgerDiff, type LedgerEntry, type Lens, type LensReport, type LoadedConfig, type ManifestProblem, NAME, PACK_VERSION, type PackageManager, type PathClaims, type PlanOptions, type ProjectFacts, type StateBudgets, TOTAL_BUDGET_WORDS, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, checkManifest, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadFleetManifest, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };
+export { type ApplyResult, type ArtifactFreshness, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ClaimCounters, type ClaimText, type ContextBudget, type ContextBudgets, type ContextFile, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, type DecisionLedger, type DecisionRefsOptions, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, type ExaminedClaim, FLEET_JSON_SCHEMA, FLEET_LENS, type Finding, type FleetContract, type FleetEntry, type FleetManifest, type FleetProfile, type FleetProjectSweep, type FleetSweepOptions, type FleetSweepResult, type FreshnessFacts, type GateInventory, type GateTool, type GeneratedFile, type HookFacts, type InstructionFileSet, type InstructionScope, LENSES, type Ledger, type LedgerDiff, type LedgerEntry, type Lens, type LensReport, type LoadedConfig, type ManifestProblem, NAME, PACK_VERSION, PREMISE_BRIEF_FILE, PREMISE_LENS, type PackageManager, type PathClaims, type PlanOptions, type PremiseEntity, type PremiseOptions, type PremiseResult, type ProjectFacts, type PromotedText, type PromotionContext, type PromotionSkips, type RefsResult, type StateBudgets, TOTAL_BUDGET_WORDS, type TextClaimsOptions, type TextClaimsResult, type TruthEnv, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, buildTruthEnv, cacheFactsPath, checkDecisionRefs, checkDocRefs, checkManifest, checkTextClaims, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, emptyCounters, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadDecisionLedger, loadFleetManifest, measureContext, planWorkflow, promoteBareTokens, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, renderBrief, runAudit, runPremise, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };