etymd 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,444 @@
+type PackageManager = "pnpm" | "yarn" | "npm" | "bun" | "unknown";
+type WorkspaceKind = "pnpm" | "yarn" | "npm" | "nx" | "turbo" | "lerna" | "none";
+type CiSystem = "gitlab" | "github" | "none";
+/** A project script classified into the roles that make up a "Done =" definition. */
+interface DiscoveredCommands {
+    test?: string;
+    lint?: string;
+    typecheck?: string;
+    format?: string;
+    formatCheck?: string;
+    build?: string;
+    dev?: string;
+    /** Every raw `scripts` key, kept so nothing is silently lost. */
+    raw: Record<string, string>;
+}
+interface PackageInfo {
+    name: string;
+    /** Path relative to the scan root. */
+    dir: string;
+    private: boolean;
+    version?: string;
+}
+/** An agent-workflow artifact etymd knows how to read or generate. */
+interface DetectedArtifact {
+    id: string;
+    label: string;
+    path: string;
+    /** What role it plays: the single source of truth, a per-agent pointer, a skill, a gate, etc. */
+    kind: "contract" | "state" | "adapter" | "skill" | "gate" | "map" | "sessions" | "other";
+    exists: boolean;
+}
+interface GitFacts {
+    isRepo: boolean;
+    branch?: string;
+    head?: string;
+    hooksPath?: string;
+    husky: boolean;
+    /** Distinct commit authors in recent history — the solo-vs-team profile signal. */
+    recentAuthors?: number;
+    /** Ticket-key prefix inferred from recent commit subjects (e.g. "NGRE2E"). */
+    ticketKey?: string;
+}
+interface HookFacts {
+    /** husky-legacy = husky v3/v4 config (package.json `husky` key or husky.config.js), no .husky dir. */
+    source: "githooks" | "husky" | "husky-legacy" | "custom" | "none";
+    /** The actual hooks directory when known (covers a custom core.hooksPath). */
+    dir?: string;
+    preCommit: boolean;
+    prePush: boolean;
+    commitMsg: boolean;
+    lintStaged: boolean;
+}
+interface ProjectFacts {
+    etymdVersion: string;
+    packVersion: string;
+    generatedAt: string;
+    root: string;
+    name: string;
+    git: GitFacts;
+    packageManager: PackageManager;
+    node?: string;
+    workspace: {
+        kind: WorkspaceKind;
+        packageGlobs: string[];
+    };
+    packages: PackageInfo[];
+    frameworks: string[];
+    commands: DiscoveredCommands;
+    ci: {
+        system: CiSystem;
+        files: string[];
+    };
+    hooks: HookFacts;
+    artifacts: DetectedArtifact[];
+    tree: {
+        dirs: {
+            name: string;
+            files: number;
+        }[];
+        /** True when the file count hit the walk cap (large repo). */
+        truncated: boolean;
+    };
+}
+interface ContextFile {
+    path: string;
+    role: string;
+    words: number;
+    approxTokens: number;
+}
+interface ContextBudget {
+    files: ContextFile[];
+    totalWords: number;
+    totalApproxTokens: number;
+    /** The per-file threshold this measurement used (config-overridable). */
+    perFileWords: number;
+    /** Files large enough to be worth extracting into an on-demand skill. */
+    extractionCandidates: ContextFile[];
+}
+
+/**
+ * The deterministic half of a reckoning: everything knowable without an LLM. Kept pure of any
+ * terminal output so it can back both the CLI and programmatic use, and so it is trivially
+ * testable against a fixture directory.
+ */
+declare function scanProject(root: string): Promise<ProjectFacts>;
+
+/**
+ * Default word count above which a single always-loaded file is worth extracting into an
+ * on-demand skill. Overridable per repo via `context.perFileWords` in `.etymd/config.json`.
+ */
+declare const EXTRACTION_THRESHOLD: number;
+/**
+ * A Cursor rule only loads every session when it is genuinely always-applied. Scoped rules
+ * (globs, or alwaysApply omitted/false in frontmatter) load on demand and must not inflate the
+ * budget — the flagship metric has to be honest to be worth anything.
+ */
+declare function isAlwaysAppliedCursorRule(text: string): boolean;
+declare function measureContext(root: string, perFileWords?: number): Promise<ContextBudget>;
+
+interface GeneratedFile {
+    path: string;
+    contents: string;
+    /** Present on disk already — apply will skip or ask before overwriting. */
+    exists: boolean;
+    /** The existing file's content differs from what the pack would generate (hand-edited or stale). */
+    differs?: boolean;
+    /** Hooks need the executable bit. */
+    executable?: boolean;
+    label: string;
+}
+interface PlanOptions {
+    /** Scaffold a minimal AGENTS.md (init only offers this when none exists). */
+    agents: boolean;
+    gates: boolean;
+}
+/** Build the file set an onboarding would write, flagging which exist and which differ. */
+declare function planWorkflow(root: string, facts: ProjectFacts, opts: PlanOptions): Promise<GeneratedFile[]>;
+
+interface ApplyResult {
+    written: string[];
+    skipped: string[];
+}
+/**
+ * Write a planned file set. Idempotent by default: an existing file is skipped unless `overwrite`
+ * names it — etymd never clobbers hand-authored contracts without consent.
+ */
+declare function applyFiles(root: string, files: GeneratedFile[], overwrite?: Set<string>): Promise<ApplyResult>;
+
+declare const CONFIG_FILE: string;
+interface InstructionScope {
+    /** Extra instruction files to audit beyond the auto-detected set (globs, repo-relative). */
+    include: string[];
+    /** Instruction files to leave out of the audit (globs, repo-relative). */
+    exclude: string[];
+}
+interface ContextBudgets {
+    /** Words in one always-loaded file past which extraction is worth it. */
+    perFileWords: number;
+    /** Total always-loaded words past which the footprint itself is a finding. */
+    totalWords: number;
+}
+interface EtymdConfig {
+    instructions: InstructionScope;
+    context: ContextBudgets;
+}
+interface LoadedConfig {
+    config: EtymdConfig;
+    /** True when .etymd/config.json exists on disk (whether or not every key was usable). */
+    present: boolean;
+    /** Malformed or ignored input — surfaced as disclosures, never silently dropped. */
+    problems: string[];
+}
+declare const DEFAULT_CONFIG: EtymdConfig;
+declare function configPath(root: string): string;
+/**
+ * Load `.etymd/config.json`, falling back to defaults per key. Unreadable or malformed input is
+ * reported in `problems` rather than swallowed: config that silently fails to apply would let a
+ * repo believe it is scoping an audit that is in fact running unscoped (or vice versa).
+ */
+declare function readConfig(root: string): Promise<LoadedConfig>;
+
+type FindingTier = "risk" | "gap" | "polish";
+type Effort = "S" | "M" | "L";
+type Confidence = "high" | "medium" | "low";
+interface Finding {
+    /** Stable across runs: `<lens>/<slug>` — the ledger keys on this. */
+    id: string;
+    lens: string;
+    tier: FindingTier;
+    /** One sentence: what is wrong / missing. */
+    claim: string;
+    /** File paths, job names, or metrics that ground the claim. Never empty. */
+    evidence: string[];
+    /** The concrete cost of NOT acting. */
+    why: string;
+    /** What to do about it (may name a etymd command as the fix). */
+    action?: string;
+    effort: Effort;
+    confidence: Confidence;
+}
+type LensKind = "truth" | "improvement";
+type LensStatus = "ran" | "skipped";
+interface LensReport {
+    lens: string;
+    version: string;
+    title: string;
+    kind: LensKind;
+    status: LensStatus;
+    /** Honest coverage: why the lens could not run, or what it could not see. */
+    reason?: string;
+    /** Partial-visibility disclosures (e.g. "3 CI jobs inherited from an unseen template"). */
+    disclosures: string[];
+    findings: Finding[];
+    /**
+     * Files this run deliberately did not examine (config exclusions). Their absence from
+     * `findings` means "unexamined", never "fixed" — the ledger must not resolve them.
+     */
+    outOfScope?: string[];
+}
+interface LensContext {
+    root: string;
+    facts: ProjectFacts;
+    profile: WorkflowProfile;
+    /** The committed, approved reckoning — what truth lenses measure drift against. */
+    baseline: Baseline | null;
+    /** The repo's optional `.etymd/config.json` (scope + budgets); defaults when absent. */
+    config?: LoadedConfig;
+}
+/** Solo vs team changes what counts as a gap (state docs and session archives are solo ritual). */
+type WorkflowProfile = "solo" | "team";
+interface Lens {
+    id: string;
+    version: string;
+    title: string;
+    kind: LensKind;
+    run(ctx: LensContext): Promise<LensReport>;
+}
+/** Canonical ranking: severity first, then cheapest wins inside a tier. */
+declare function rankFindings(findings: Finding[]): Finding[];
+
+interface Baseline {
+    packVersion: string;
+    etymdVersion: string;
+    approvedAt: string;
+    profile: WorkflowProfile;
+    facts: ProjectFacts;
+}
+declare function cacheFactsPath(root: string): string;
+declare function baselinePath(root: string): string;
+declare function writeCachedFacts(root: string, facts: ProjectFacts): Promise<string>;
+declare function readCachedFacts(root: string): Promise<ProjectFacts | null>;
+/**
+ * The scan's absolute root is a MACHINE path — it carries the author's username and directory
+ * layout. It must never reach the baseline, because the baseline is the one file etymd tells
+ * people to commit (and therefore to publish). It is redundant there anyway: the baseline lives
+ * inside the repo it describes, and `facts.name` already identifies the project.
+ *
+ * True for the gitignored cache too, but that one stays absolute on purpose — it never leaves the
+ * machine, and a wrong-checkout cache is easier to spot with the real path in it.
+ */
+declare function withoutMachinePath(facts: ProjectFacts): ProjectFacts;
+/** True for a baseline written before the root was elided — its holder should re-approve. */
+declare function baselineCarriesMachinePath(baseline: Baseline): boolean;
+declare function writeBaseline(root: string, baseline: Baseline): Promise<string>;
+declare function readBaseline(root: string): Promise<Baseline | null>;
+/** Solo vs team, from recent-author cardinality; init lets the human confirm/override. */
+declare function deriveProfile(facts: ProjectFacts): WorkflowProfile;
+
+type LedgerStatus = "open" | "accepted" | "done" | "dismissed" | "regressed";
+interface LedgerEntry {
+    id: string;
+    status: LedgerStatus;
+    tier: Finding["tier"];
+    claim: string;
+    /** Only for dismissed — the human's reason, so the decision survives. */
+    reason?: string;
+    firstSeen: string;
+    lastSeen: string;
+}
+interface Ledger {
+    version: 1;
+    entries: LedgerEntry[];
+}
+interface LedgerDiff {
+    new: Finding[];
+    stillOpen: Finding[];
+    regressed: Finding[];
+    resolved: LedgerEntry[];
+    dismissed: Finding[];
+    accepted: Finding[];
+    /** Tracked findings in files this run excluded — held open, never counted as resolved. */
+    outOfScope: LedgerEntry[];
+}
+declare function readLedger(root: string): Promise<Ledger>;
+declare function writeLedger(root: string, ledger: Ledger): Promise<void>;
+/**
+ * Reconcile fresh findings against the ledger. Pure: returns the updated ledger + the diff;
+ * the caller decides whether to persist. A finding absent from a run is marked `done`
+ * (resolved); a `done` entry that reappears becomes `regressed`; `dismissed` stays dismissed.
+ *
+ * `outOfScope` names files the run deliberately did not look at (config exclusions). Their
+ * tracked findings are NOT absent because they were fixed — they are absent because nobody
+ * looked. Recording them as resolved would let scoping rewrite unfixed problems as successes,
+ * which is the same silence the exclusion disclosures exist to prevent. They are held untouched.
+ */
+declare function reconcileLedger(ledger: Ledger, findings: Finding[], now?: string, outOfScope?: string[]): {
+    ledger: Ledger;
+    diff: LedgerDiff;
+};
+
+/** The lens registry — adding a lens means registering it here. */
+declare const LENSES: Lens[];
+interface AuditOptions {
+    /** Restrict to one kind (doctor = truth). */
+    kind?: LensKind;
+    /** Restrict to specific lens ids. */
+    lensIds?: string[];
+    /** Persist the reconciled ledger (the default; false = read-only report). */
+    persistLedger?: boolean;
+}
+interface AuditResult {
+    facts: ProjectFacts;
+    profile: WorkflowProfile;
+    baseline: Baseline | null;
+    config: LoadedConfig;
+    reports: LensReport[];
+    /** Ranked, dismissed-filtered — what the report shows. */
+    findings: Finding[];
+    ledger: Ledger;
+    diff: LedgerDiff;
+}
+declare function runAudit(root: string, opts?: AuditOptions): Promise<AuditResult>;
+
+/**
+ * The truth lens: does what the instruction files CLAIM still hold against the actual repo?
+ * Commands must exist as scripts, paths must exist on disk, files must agree on the package
+ * manager, cross-references must resolve — plus drift against the committed baseline.
+ */
+declare const instructionTruthLens: Lens;
+
+interface InstructionFile {
+    /** Repo-relative path. */
+    path: string;
+    text: string;
+}
+interface InstructionFileSet {
+    /** The files the lens will actually audit. */
+    files: InstructionFile[];
+    /** Auto-detected files dropped by `instructions.exclude` — counted so scoping stays visible. */
+    excluded: string[];
+    /** Files pulled in by `instructions.include` that detection would have missed. */
+    included: string[];
+}
+/**
+ * Every agent-facing instruction file the scan knows how to find, then narrowed by the repo's
+ * optional scope: auto-detected ∪ `include`, minus `exclude`. The excluded set is returned rather
+ * than discarded — a scoped audit that quietly looked clean would be the exact dishonesty this
+ * tool exists to catch.
+ */
+declare function listInstructionFiles(root: string, facts: ProjectFacts, scope?: InstructionScope): Promise<InstructionFileSet>;
+interface CommandClaims {
+    /** Script names the file claims exist (deduped). */
+    scripts: Map<string, string>;
+    /** Workspace-filtered invocations we deliberately did not validate. */
+    filteredSkipped: number;
+}
+/** Script names referenced via `pnpm X` / `yarn X` / `npm run X` / `bun run X` / `npm test`. */
+declare function extractCommandClaims(text: string): CommandClaims;
+interface PathClaims {
+    /** Claims to verify against the repo. */
+    paths: string[];
+    /** Claims whose every mention sits in create-this prose — skipped, counted, disclosed. */
+    prospective: string[];
+    /** Naming stand-ins (`my-custom-skill`) — never real claims. */
+    placeholder: string[];
+}
+/**
+ * Repo-relative path claims from single-token inline spans, conservatively filtered. The
+ * load-bearing precision rule (learned from real corpus prose): an extensionless bare token
+ * (`research/trust`, `milestone/mNN`) is prose — a dir claim must end with `/`, a file claim
+ * must carry an extension.
+ */
+declare function extractPathClaims(text: string): PathClaims;
+
+/** Default total always-loaded words past which the footprint itself becomes a finding. */
+declare const TOTAL_BUDGET_WORDS: number;
+/**
+ * Economy lens: the always-loaded instruction footprint, as findings. Context is the dominant
+ * cost of the agent loop, and attention dilutes long before windows fill — a lean contract is
+ * a correctness feature, not a style preference.
+ */
+declare const contextEconomyLens: Lens;
+
+type GateTool = "typecheck" | "lint" | "format-check" | "format-write" | "test" | "coverage" | "e2e" | "sonar" | "codecov" | "commitlint" | "size" | "chromatic";
+interface CiJobGate {
+    job: string;
+    file: string;
+    tools: GateTool[];
+    /** allow_failure / continue-on-error — an advisory job is NOT an enforced gate. */
+    advisory: boolean;
+    /** rules/only/except present — blocking-ness may differ per branch. */
+    branchScoped: boolean;
+    /** False when the job's script lives in an inherited template — tools are then inferred from
+     * the job name/variables only and may be incomplete. */
+    scriptVisible: boolean;
+}
+interface GateInventory {
+    local: {
+        source: ProjectFacts["hooks"]["source"];
+        wired: boolean;
+        preCommit: GateTool[];
+        prePush: GateTool[];
+        commitMsg: GateTool[];
+        lintStaged: GateTool[];
+    };
+    ci: {
+        system: ProjectFacts["ci"]["system"];
+        jobs: CiJobGate[];
+        /** include: entries pointing outside the repo — jobs we cannot see. */
+        inheritedIncludes: string[];
+        parseErrors: string[];
+    };
+    thresholds: {
+        sonarConfigured: boolean;
+        coverageThresholdLocal: boolean;
+        coverageCollected: boolean;
+    };
+    commitlintDep: boolean;
+}
+declare function buildGateInventory(root: string, facts: ProjectFacts): Promise<GateInventory>;
+
+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.
+ */
+declare const PACK_VERSION = "2";
+
+declare const VERSION: string;
+declare const NAME: string;
+
+export { type ApplyResult, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ContextBudget, type ContextBudgets, type ContextFile, DEFAULT_CONFIG, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, type Finding, 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, NAME, PACK_VERSION, type PackageManager, type PathClaims, type PlanOptions, type ProjectFacts, TOTAL_BUDGET_WORDS, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, configPath, contextEconomyLens, deriveProfile, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };