dsh-plugin-inspector 0.1.0

package/lib/types/cordis-yaml.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Parsing a Cordis patch layer with the harness's own `!!js` dialect, and
+ * modelling it the way `applyEntryPatches` does.
+ *
+ * The dialect is transcribed from `dsh/scripts/verify-cordis-config.ts` and
+ * `dsh/vendor/include/src/index.ts`: `yaml.JSON_SCHEMA` extended with one
+ * scalar type for `tag:yaml.org,2002:js`, whose constructor produces an inert
+ * `{ __jsExpr }` node. **The expression text is never evaluated here.** Where
+ * the harness would call `new Function('ctx', 'expr', 'with (ctx) { return
+ * eval(expr) }')`, this module only ever compiles `return (expr)` to learn
+ * whether it parses, and parses it a second time with the TypeScript parser to
+ * classify what it reaches. Neither compiles-and-calls.
+ *
+ * js-yaml is pinned to the harness's `^4.2.0`. Parsing the same bytes
+ * differently from the runtime would make every downstream result unsound.
+ * @module dsh-plugin-inspector/cordis-yaml
+ */
+import yaml from 'js-yaml';
+/** The inert node a `!!js` scalar becomes. Mirrors the loader's own representation. */
+export interface JsExprNode {
+    readonly __jsExpr: string;
+}
+/**
+ * The entry-list dialect: JSON schema plus `!!js`. Deliberately *not*
+ * `DEFAULT_SCHEMA`, which would also accept `!!python`, `!!binary` and friends
+ * — matching the harness exactly means a tag the harness rejects is rejected
+ * here too, and shows up as a finding rather than as parsed data.
+ */
+export declare const patchSchema: yaml.Schema;
+/** What a `!!js` expression can reach, in ascending order of reach. */
+export type ExpressionClass = 'literal' | 'inert-read' | 'harness-call' | 'call' | 'mutation' | 'module-access' | 'unparseable';
+/** Every classification, in the order the report tallies them. */
+export declare const EXPRESSION_CLASSES: readonly ExpressionClass[];
+/** Whether the loader ever evaluates the node at this location. */
+export type ExpressionSlot = 'config' | 'disabled' | 'inert';
+/** One `!!js` node found in a patch document. */
+export interface ExpressionSite {
+    /** Diagnostic path, e.g. `[0].insert[1].config.cwd`. */
+    readonly path: string;
+    readonly expression: string;
+    readonly slot: ExpressionSlot;
+    readonly classification: ExpressionClass;
+    /** Parse diagnostic when `classification` is `unparseable`. */
+    readonly parseError?: string;
+}
+/** A patch that modifies a row that some earlier layer already defined. */
+export interface OverridePatch {
+    readonly path: string;
+    readonly id: string;
+    /** `name` on a non-insert patch is an assertion guard, not an override. */
+    readonly nameGuard: string | null;
+    /** Keys copied verbatim onto the target row, in declaration order. */
+    readonly overriddenKeys: readonly string[];
+    /** The raw `disabled` value, present only when the patch sets it. */
+    readonly disabled: unknown;
+    readonly config: unknown;
+}
+/** A row this layer adds to the composed profile. */
+export interface InsertedRow {
+    readonly path: string;
+    readonly id: string | null;
+    readonly name: string | null;
+    readonly config: unknown;
+    /** Id of the group row this insert targets, or `null` for a top-level insert. */
+    readonly intoGroupId: string | null;
+    /** Service names the row re-maps to a fresh realm for its whole subtree. */
+    readonly isolate: readonly string[];
+    /** Service names the row interposes on for its whole subtree. */
+    readonly intercept: readonly string[];
+}
+/** Why a walk stopped early, or `null` when it ran to completion. */
+export type WalkLimit = 'nodes' | 'depth' | null;
+/** One parsed patch layer. */
+export interface PatchDocument {
+    /** Package-relative path of the YAML file. */
+    readonly file: string;
+    readonly overrides: readonly OverridePatch[];
+    readonly inserts: readonly InsertedRow[];
+    readonly expressions: readonly ExpressionSite[];
+    /**
+     * Which walk ceiling stopped the analysis of this layer, or `null`. Non-null
+     * means the layer was read in part, which Tier C reports.
+     */
+    readonly limit: WalkLimit;
+}
+/** Nodes one patch layer may be walked through before the walk gives up. */
+export declare const MAX_WALK_NODES = 200000;
+/** Nesting one patch layer may reach before the walk gives up. */
+export declare const MAX_WALK_DEPTH = 200;
+/** Thrown when the patch file cannot be parsed as an entry list. */
+export declare class PatchParseError extends Error {
+    /** True when the failure is a `!js` single-bang tag, which never loads anywhere. */
+    readonly singleBangTag: boolean;
+    /**
+     * @param message - the underlying parse diagnostic.
+     * @param singleBangTag - whether the raw text contains a `!js` tag.
+     */
+    constructor(message: string, singleBangTag: boolean);
+}
+/**
+ * Whether a value is a `!!js` node. Matches the loader's own predicate.
+ * @param value - the parsed value.
+ * @returns true for an expression node.
+ */
+export declare function isJsExpr(value: unknown): value is JsExprNode;
+/**
+ * Classify what a `!!js` expression can reach, by parsing it — never running
+ * it. Precedence is by reach: module access beats mutation beats an unknown
+ * call beats a known-inert call beats a read, so an expression is reported at
+ * its most capable form.
+ *
+ * The grading is by reach, not by syntactic form. `dshHomePath('sessions')` is
+ * a `CallExpression` and so is `steal()`, but the first is a helper the harness
+ * itself provides to these expressions and uses in its own shipped bundle,
+ * while the second names something this tool cannot resolve. Grading both as
+ * the same thing puts the harness's own configuration at the same severity as
+ * an attack and teaches the reader to skip the class.
+ * @param expression - the raw expression text.
+ * @returns the classification and, when it does not parse, the diagnostic.
+ */
+export declare function classifyExpression(expression: string): {
+    class: ExpressionClass;
+    parseError?: string;
+};
+/**
+ * Parse a patch layer.
+ * @param file - package-relative path, used in findings.
+ * @param text - the YAML text.
+ * @returns the modelled patch document.
+ * @throws PatchParseError when the text is not a loadable entry list.
+ */
+export declare function parsePatchDocument(file: string, text: string): PatchDocument;
+//# sourceMappingURL=cordis-yaml.d.ts.map

package/lib/types/files.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Classifying the files inside an analysed package, and formatting excerpts of
+ * them for evidence.
+ * @module dsh-plugin-inspector/files
+ */
+/**
+ * Whether a path is JavaScript or TypeScript source this tool will parse.
+ * Declaration files are excluded: they carry types, never behavior.
+ * @param path - package-relative path.
+ * @returns true when the file should be parsed.
+ */
+export declare function isSourceFile(path: string): boolean;
+/**
+ * Whether a path is markdown that can reach the model verbatim.
+ *
+ * The reach is conditional and PLAN.md §6.1 says so: a `SKILL.md` inside an npm
+ * package is only discovered when the plugin registers it through
+ * `ctx.skills`, when a patch row redirects a skill root into the package, or
+ * when something copies it into the user's workspace. This predicate answers
+ * "is this the kind of file that would reach the model if it were found", not
+ * "will it be found".
+ * @param path - package-relative POSIX path.
+ * @returns true for skill and agent-instruction markdown.
+ */
+export declare function isModelVisibleText(path: string): boolean;
+/**
+ * Whether a path is a Cordis config file, using the harness's own naming
+ * convention from `scripts/cordis-config-files.ts`.
+ * @param path - package-relative POSIX path.
+ * @returns true for a cordis YAML file.
+ */
+export declare function isCordisConfigFile(path: string): boolean;
+/**
+ * Resolve a manifest-declared path to the package-relative POSIX form used as
+ * map keys, or report that it leaves the package.
+ *
+ * Only `..` escapes. An absolute path does **not**: the launcher resolves the
+ * patch as `join(packageDir, declared)` (`packages/boot/app-boot/src/profile.ts`),
+ * and `join` re-roots an absolute second argument *inside* the first, so
+ * `join('/…/pkg', '/etc/passwd')` is `/…/pkg/etc/passwd`. A leading slash
+ * therefore names a file the package does not ship, not a file outside it.
+ * @param declared - the path exactly as the manifest declares it.
+ * @returns the normalised package-relative path, or `null` when it escapes.
+ */
+export declare function normalizePackagePath(declared: string): string | null;
+/**
+ * Render a value as JSON-like evidence without walking a graph as a tree.
+ * A YAML anchor makes one node reachable by many paths, so `JSON.stringify` on
+ * a patch row's `config` can be asked to serialise billions of nodes from a
+ * few hundred bytes of input. This stops at a depth and a length instead.
+ * @param value - the value to describe.
+ * @param maxDepth - how far to descend before writing an ellipsis.
+ * @param limit - the longest string to return.
+ * @returns the bounded rendering.
+ */
+export declare function boundedJson(value: unknown, maxDepth?: number, limit?: number): string;
+/**
+ * Reduce text to a single-line excerpt safe to print in a report.
+ * @param text - the source text.
+ * @param limit - maximum characters to keep.
+ * @returns the collapsed, truncated excerpt.
+ */
+export declare function snippet(text: string, limit?: number): string;
+/**
+ * Convert a character offset to a `line:column` locator, both 1-based.
+ * @param text - the file text.
+ * @param offset - the character offset.
+ * @returns the locator.
+ */
+export declare function lineColumn(text: string, offset: number): string;
+//# sourceMappingURL=files.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `dsh-plugin-inspector` — static pre-install analysis of a DeepSeek Harness
+ * plugin.
+ *
+ * The library face of the tool, for callers that want the report rather than
+ * the exit code. {@link inspect} decodes a plugin directory or npm tarball,
+ * runs the three check tiers over the decoded form, and returns a
+ * {@link Report}. It never installs, builds, imports, spawns, or evaluates
+ * anything from the analysed package.
+ *
+ * The ceiling is triage, not containment. See `README.md` §Limitations.
+ * @module dsh-plugin-inspector
+ */
+export { exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from './inspect.ts';
+export { renderHuman, renderJson } from './report.ts';
+export { classifyExpression, isJsExpr, parsePatchDocument, patchSchema, PatchParseError, type ExpressionClass, type ExpressionSite, type ExpressionSlot, type InsertedRow, type JsExprNode, type OverridePatch, type PatchDocument, } from './cordis-yaml.ts';
+export { declaredPackages, ManifestError, parseManifest, type PackageManifest } from './manifest.ts';
+export { DEFAULT_LIMITS, loadSource, SourceError, type PluginSource, type ReadLimits } from './source.ts';
+export { globMatch, publishSet, type PublishBasis, type PublishInputs, type PublishSet } from './publish.ts';
+export { INJECTION_RULES, scanInjection, type InjectionMatch, type InjectionRule } from './injection.ts';
+export { compareFindings, SEVERITIES, SEVERITY_RANK, summarize, type AnalysisIntegrity, type Confidence, type Evidence, type Facts, type Finding, type Report, type Severity, type Tier, } from './model.ts';
+export { CORE_ROWS, CORE_ROW_IDS, HARNESS_BUNDLE_PACKAGES, HARNESS_REFERENCE, SEAM_KEYS, SECURITY_ROW_IDS, WATERFALL_EVENTS, type BundleName, type CoreRow, } from './knowledge.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/injection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Prompt-injection heuristics, applied to model-visible text only.
+ *
+ * "Model-visible" is a narrow set on purpose: shipped skill and
+ * agent-instruction markdown, and the `description` string of a registered
+ * tool. Those reach the model verbatim, unescaped and uncapped. Ordinary source
+ * comments do not, and scanning them would produce a stream of false positives
+ * from documentation that happens to quote an attack.
+ *
+ * These are heuristics over natural language. They will miss a rephrased
+ * instruction and they will occasionally fire on a legitimate document that
+ * discusses prompt injection. Both directions are stated in the finding.
+ * @module dsh-plugin-inspector/injection
+ */
+/** One heuristic and what it is looking for. */
+export interface InjectionRule {
+    readonly id: string;
+    readonly pattern: RegExp;
+    /** What a match would mean, phrased for a report. */
+    readonly meaning: string;
+}
+/**
+ * The rule table. Each pattern targets an instruction that only makes sense if
+ * the author expects a model rather than a person to read it.
+ */
+export declare const INJECTION_RULES: readonly InjectionRule[];
+/** One heuristic match. */
+export interface InjectionMatch {
+    readonly ruleId: string;
+    readonly meaning: string;
+    /** Character offset of the match in the scanned text. */
+    readonly index: number;
+    readonly excerpt: string;
+}
+/**
+ * Scan model-visible text for injection phrasing.
+ * @param text - the text a model would receive.
+ * @returns one match per rule that fired, at its first occurrence.
+ */
+export declare function scanInjection(text: string): InjectionMatch[];
+//# sourceMappingURL=injection.d.ts.map

package/lib/types/inspect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Orchestration: decode the package once, run the three tiers over the decoded
+ * form, apply the Tier C downgrade, and assemble the report.
+ *
+ * This module is the only place that reads the package and the only place that
+ * decides confidence. Nothing here — and nothing it calls — imports, requires,
+ * spawns, or evaluates anything from the analysed package. The only `Function`
+ * constructed anywhere in this tool is the parse-only compile in
+ * `cordis-yaml.ts`, and its result is discarded without being called.
+ * @module dsh-plugin-inspector/inspect
+ */
+import { type Report, type Severity } from './model.ts';
+/** This tool's own version, reported in the JSON document. */
+export declare const TOOL_VERSION = "0.1.0";
+/** This tool's package name, reported in the JSON document. */
+export declare const TOOL_NAME = "dsh-plugin-inspector";
+/**
+ * Inspect a plugin package.
+ * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.
+ * @returns the complete report.
+ * @throws SourceError or ManifestError when the target cannot be analysed at all.
+ */
+export declare function inspect(target: string): Promise<Report>;
+/**
+ * Whether a report should fail a CI gate.
+ * @param report - the report.
+ * @param threshold - the lowest severity that fails, or `none` to never fail.
+ * @returns true when at least one finding is at or above the threshold.
+ */
+export declare function exceedsThreshold(report: Report, threshold: Severity | 'none'): boolean;
+//# sourceMappingURL=inspect.d.ts.map

package/lib/types/knowledge.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Ground truth read out of the DeepSeek Harness checkout: the core row
+ * inventory, the capability seam keys, the waterfall event set, and the
+ * capabilities the harness's own sandbox denies untrusted code.
+ *
+ * Every table here cites the harness file it was transcribed from. These are
+ * facts about a specific harness version, not opinions — when the harness
+ * changes, these tables are what needs updating, and keeping them in one
+ * module is what makes that a single reviewable diff.
+ * @module dsh-plugin-inspector/knowledge
+ */
+/**
+ * Harness version these tables were transcribed from — the version string in
+ * the checkout's own `packages/bundle/*/package.json`.
+ */
+export declare const HARNESS_REFERENCE = "0.1.0-rc.5";
+/** The shipped bundles, each of which is one patch layer over the profile root. */
+export type BundleName = 'base' | 'headless' | 'web-app';
+/**
+ * The three profile bundles the harness ships, mapped to what each one is.
+ * A package that *is* one of these composes the core rows rather than modifying
+ * somebody else's: `@deepseek-ai/dsh-web-app` disabling two dozen rows the base
+ * layer inserted is the definition of a bundle, not an attack on one.
+ * Transcribed from `packages/bundle/{base,headless,web-app}/package.json`.
+ */
+export declare const HARNESS_BUNDLE_PACKAGES: ReadonlyMap<string, BundleName>;
+/** One row a shipped bundle defines. */
+export interface CoreRow {
+    /** The module specifier that implements the row. */
+    readonly module: string;
+    /** Which shipped bundles insert this row. A profile may mount only some of them. */
+    readonly bundles: readonly BundleName[];
+}
+/**
+ * Every row the shipped bundles define, mapped from row id to the module that
+ * implements it and the bundles that insert it. Transcribed from
+ * `packages/bundle/{base,headless,web-app}/cordis.patch.yml`.
+ *
+ * A patch row whose `id` is a key here is modifying core behavior rather than
+ * contributing its own. The name half matters because `applyEntryPatches`
+ * treats `name` on a non-insert patch as an assertion guard: on mismatch it
+ * warns and skips the whole patch, so a patch naming the wrong module silently
+ * does nothing at all. The bundle half matters because the three layers are not
+ * one profile: a `ui-*` row exists only where the web bundle is mounted, so a
+ * headless profile never had it to lose.
+ */
+export declare const CORE_ROWS: ReadonlyMap<string, CoreRow>;
+/** Row ids the shipped bundles define. */
+export declare const CORE_ROW_IDS: ReadonlySet<string>;
+/**
+ * The core rows whose whole purpose is to constrain what the agent may do.
+ * Disabling or reconfiguring one of these from a third-party patch layer is
+ * the highest-value finding this tool produces, and it is plain YAML.
+ *
+ * Each entry names what stops holding when the row stops running.
+ */
+export declare const SECURITY_ROW_IDS: ReadonlyMap<string, string>;
+/**
+ * Capability seam keys from
+ * `packages/extensions/tool-cordis/src/api-catalog.ts` (`SERVICE_API[].key`).
+ * A plugin calling `ctx.provide(key, …)` or `ctx.set(key, …)` on one of these
+ * replaces a core service for every consumer in its scope.
+ */
+export declare const SEAM_KEYS: ReadonlySet<string>;
+/** The subset of {@link SEAM_KEYS} whose replacement removes a constraint. */
+export declare const SECURITY_SEAM_KEYS: ReadonlySet<string>;
+/**
+ * Waterfall events, from `EVENT_API` in the api-catalog. A listener on one of
+ * these receives a trailing `next` and MUST call it to delegate; returning
+ * without calling it short-circuits the chain including the built-in behavior.
+ *
+ * Note there is no `fs/read-intent` — the intent family is write and edit only.
+ */
+export declare const WATERFALL_EVENTS: ReadonlySet<string>;
+/** Waterfall events whose short-circuit removes a decision the user would otherwise make. */
+export declare const DECISION_EVENTS: ReadonlySet<string>;
+/**
+ * Globals the dynamic-package sandbox (`cordis-host-runner/src/sandbox.ts`)
+ * traps and redirects to a `ctx` service, plus `process`, which it leaves
+ * `undefined`. An installed bundle layer is a plain ESM import and gets none of
+ * these restrictions — which is exactly why using one is worth reporting.
+ */
+export declare const SANDBOX_DENIED_GLOBALS: ReadonlyMap<string, string>;
+/**
+ * Node builtins that start or evaluate code off the mediated path. A mounted
+ * layer importing one of these is doing what `ctx.subprocess` and `ctx.sandbox`
+ * exist to mediate, from a position where nothing mediates it.
+ */
+export declare const UNMEDIATED_PROCESS_MODULES: ReadonlyMap<string, string>;
+/**
+ * Modules and globals that move bytes off the machine. The harness's own
+ * dynamic-package sandbox traps `fetch` and redirects it to the `ctx.web`
+ * service; a mounted layer gets no such redirect.
+ */
+export declare const NETWORK_MODULES: ReadonlySet<string>;
+/**
+ * Filesystem modules that bypass `ctx.fs`. Reads and writes through these are
+ * invisible to `fs/write-intent`, `fs/edit-intent`, `fs/observed`, and the
+ * `fs-sandbox` row, so no policy sees them.
+ */
+export declare const UNMEDIATED_FS_MODULES: ReadonlySet<string>;
+/** The npm package that turns a Cordis row into an MCP server connection. */
+export declare const MCP_CLIENT_PACKAGE = "@deepseek-ai/dsh-mcp-client";
+/** The row id that owns filesystem skill discovery, and whose config selects the roots. */
+export declare const SKILL_FILESYSTEM_ROW = "skill-filesystem";
+/** `skill-filesystem` config keys that point discovery at a new directory. */
+export declare const SKILL_ROOT_CONFIG_KEYS: readonly string[];
+/**
+ * `package.json` script names npm and pnpm run around installation. A plugin
+ * only needs one of these to run code before the user has read a line of it.
+ */
+export declare const INSTALL_LIFECYCLE_SCRIPTS: readonly string[];
+/** Entry fields the loader never interpolates: a `!!js` node here is inert data. */
+export declare const STATIC_ENTRY_FIELDS: readonly string[];
+/**
+ * Calls a `!!js` expression may make that reach nothing the harness does not
+ * already hand it.
+ *
+ * `dsh-app-boot` does `ctx.provide('dshHomePath', dshHomePath)` before mounting
+ * any entry (`packages/boot/app-boot/src/index.ts`), and the loader evaluates
+ * every expression under `with (ctx)`, so `dshHomePath(...)` is in scope by
+ * design and documented as such in that package's README. The two `process`
+ * reads are the ones the shipped bundles use.
+ */
+export declare const HARNESS_INERT_CALLS: ReadonlySet<string>;
+/**
+ * The entry fields that decide which services a row sees, and which of them it
+ * substitutes for its subtree.
+ *
+ * `isolate` is the sharpest: `vendor/loader/src/config/isolate.ts` re-maps a
+ * named service to a fresh symbol realm, so every descendant that injects that
+ * name gets the row's realm instead of the profile's. Setting it on a security
+ * service is a Tier A declaration with the same reach as replacing the service
+ * in code, and it is plain YAML.
+ */
+export declare const SERVICE_REMAPPING_FIELDS: readonly string[];
+//# sourceMappingURL=knowledge.d.ts.map

package/lib/types/manifest.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Reading `package.json` from an untrusted package.
+ *
+ * This is a file boundary with a hostile author on the other side, so nothing
+ * here trusts the parse type. Every field is narrowed before use and a field
+ * of the wrong shape is treated as absent rather than throwing — a plugin that
+ * ships `"scripts": "postinstall"` should still be analysed for everything
+ * else, and "this manifest is malformed" is itself worth reporting.
+ * @module dsh-plugin-inspector/manifest
+ */
+/** The `dsh.bundle` declaration that promotes a package to a mounted patch layer. */
+export interface DshBundleSection {
+    /** Patch file path relative to the package root, verbatim and unresolved. */
+    readonly patch?: string;
+}
+/** The `dsh`-owned section of `package.json`, as far as this tool reads it. */
+export interface DshSection {
+    readonly bundle?: DshBundleSection;
+    readonly profile?: {
+        readonly bundles?: readonly string[];
+    };
+    /** Present means the package ships a bundle executed in the user's browser. */
+    readonly client?: Record<string, unknown>;
+}
+/** The slice of `package.json` this tool reads. */
+export interface PackageManifest {
+    readonly name: string;
+    readonly version: string;
+    readonly license: string | null;
+    readonly scripts: Readonly<Record<string, string>>;
+    readonly dependencies: Readonly<Record<string, string>>;
+    readonly peerDependencies: Readonly<Record<string, string>>;
+    readonly optionalDependencies: Readonly<Record<string, string>>;
+    readonly devDependencies: Readonly<Record<string, string>>;
+    /** The publish allowlist, or `null` when the manifest declares none. */
+    readonly files: readonly string[] | null;
+    /** Command names the package installs on the user's PATH, in declaration order. */
+    readonly binNames: readonly string[];
+    readonly exportPaths: readonly string[];
+    readonly dsh: DshSection;
+    /** Problems found while reading the manifest, reported as Tier A findings. */
+    readonly defects: readonly string[];
+}
+/** Thrown when `package.json` is not JSON at all. */
+export declare class ManifestError extends Error {
+}
+/**
+ * Parse an untrusted `package.json`.
+ * @param text - the file's UTF-8 content.
+ * @returns the narrowed manifest, including any shape defects found.
+ * @throws ManifestError when the text is not a JSON object.
+ */
+export declare function parseManifest(text: string): PackageManifest;
+/**
+ * Every package name the manifest admits the package may load at runtime:
+ * its own name, its dependencies, and its peer dependencies. Used to decide
+ * whether an inserted Cordis row names a module the manifest accounts for.
+ * @param manifest - the parsed manifest.
+ * @returns the declared package names.
+ */
+export declare function declaredPackages(manifest: PackageManifest): ReadonlySet<string>;
+//# sourceMappingURL=manifest.d.ts.map

package/lib/types/model.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The report vocabulary: what a finding is, how findings rank, and what the
+ * complete inspection document looks like.
+ *
+ * The document separates `facts` from `findings` deliberately. Facts carry no
+ * severity and answer "what does this plugin do"; findings carry severity and
+ * answer "what warrants a decision". A well-behaved plugin has a full facts
+ * section and an empty findings section — emitting `dsh.bundle` as a finding
+ * would fire on every legitimate plugin and train users to ignore the tool.
+ * @module dsh-plugin-inspector/model
+ */
+/** How much a finding should weigh on an install decision. */
+export type Severity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * How much the detection itself can be trusted, which is separate from how bad
+ * the thing detected is. Tier A reads structured declarations and is always
+ * `certain`; Tier B recognises syntax and is downgraded when Tier C fires.
+ */
+export type Confidence = 'certain' | 'high' | 'moderate' | 'low';
+/** Which analysis produced a finding. See PLAN.md §6. */
+export type Tier = 'A' | 'B' | 'C';
+/** Severity ordering, ascending. Used for `--fail-on` comparison and ranking. */
+export declare const SEVERITY_RANK: Readonly<Record<Severity, number>>;
+/** Every severity, most severe first — the order the human report prints in. */
+export declare const SEVERITIES: readonly Severity[];
+/** Where in the analysed package a finding was observed. */
+export interface Evidence {
+    /** Package-relative path of the file the finding came from. */
+    readonly file: string;
+    /** A locator inside that file: a YAML path, a JSON pointer, or `line:column`. */
+    readonly path?: string;
+    /** A short verbatim excerpt, truncated and single-lined for display. */
+    readonly snippet?: string;
+}
+/** One thing the inspector believes warrants a decision. */
+export interface Finding {
+    /** Catalogue id from PLAN.md §6, e.g. `A2`. Stable across releases. */
+    readonly checkId: string;
+    /** Machine-readable check name, e.g. `core-row-disabled`. Stable across releases. */
+    readonly name: string;
+    readonly tier: Tier;
+    readonly severity: Severity;
+    readonly confidence: Confidence;
+    /** One line naming what was found. */
+    readonly title: string;
+    /** Why it matters, in terms of what the harness does with the declaration. */
+    readonly detail: string;
+    readonly evidence: Evidence;
+    /**
+     * The one-line evasion for this specific check, or `null` when there is none.
+     * Non-null for every Tier B and Tier C check. Carried inside the finding
+     * rather than in a footnote so a consumer cannot render the finding without
+     * also holding its caveat.
+     */
+    readonly bypass: string | null;
+}
+/** A Cordis row this patch layer inserts or modifies. */
+export interface RowFact {
+    readonly id: string;
+    /** Module specifier for an inserted row; absent when the row only overrides. */
+    readonly name?: string;
+}
+/** The "what does this plugin do" half of the report. No severities here. */
+export interface Facts {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly license: string | null;
+    /** True when `package.json` declares `dsh.bundle.patch` — a mounted patch layer. */
+    readonly mountsAsBundle: boolean;
+    /** The declared patch path, verbatim and unresolved, or `null`. */
+    readonly bundlePatchPath: string | null;
+    /** True when the package declares `dsh.client`, shipping browser-executed code. */
+    readonly shipsClientBundle: boolean;
+    /** Bundles this package's `dsh.profile.bundles` mounts, when it is a profile. */
+    readonly profileBundles: readonly string[];
+    /** Command names the package installs on the user's PATH. */
+    readonly binNames: readonly string[];
+    /** Rows this layer adds to the composed profile. */
+    readonly insertedRows: readonly RowFact[];
+    /** Ids of pre-existing rows this layer modifies by id. */
+    readonly targetedRows: readonly string[];
+    /** The mounted layer's `!!js` inventory, counted by what each expression reaches. */
+    readonly jsExpressions: Readonly<Record<string, number>>;
+    /**
+     * Cordis YAML the package ships that no manifest key mounts. Examples,
+     * documentation, and test fixtures live here; none of it is a profile layer.
+     */
+    readonly unmountedPatchFiles: readonly string[];
+    readonly dependencies: readonly string[];
+    readonly peerDependencies: readonly string[];
+    /** Shipped markdown that can reach the model. See PLAN.md §6.1 reach note. */
+    readonly modelVisibleFiles: readonly string[];
+    readonly filesRead: number;
+    readonly bytesRead: number;
+    readonly sourceFilesParsed: number;
+    /**
+     * How the analysed file set was chosen: a tarball is already the published
+     * set, a directory is narrowed to what npm would publish out of it.
+     */
+    readonly publishBasis: 'files-allowlist' | 'ignore-rules' | 'tarball';
+    /** Working-tree files npm would not publish, and which were therefore not read. */
+    readonly unpublishedFiles: number;
+}
+/** A file the analyzer chose not to or could not read. */
+export interface SkippedFile {
+    readonly path: string;
+    readonly reason: 'size-cap' | 'total-cap' | 'entry-cap' | 'binary' | 'unreadable';
+}
+/** How much of the package the analyzer could actually see. */
+export interface AnalysisIntegrity {
+    readonly integrity: 'complete' | 'degraded';
+    /**
+     * False when any Tier C check fired. A Tier B *negative* carries no
+     * information under those conditions, so the report is forbidden from
+     * claiming nothing was found.
+     */
+    readonly negativesReliable: boolean;
+    /** Check ids that caused the degradation, e.g. `['C2']`. */
+    readonly degradedBy: readonly string[];
+    readonly filesSkipped: readonly SkippedFile[];
+}
+/** The complete inspection result, and the shape of `--json` output. */
+export interface Report {
+    readonly schemaVersion: 1;
+    readonly tool: {
+        readonly name: string;
+        readonly version: string;
+        /**
+         * The harness version the row inventory, seam keys, and event tables were
+         * transcribed from. Every Tier A verdict is a claim about what *that*
+         * version does with a declaration, so a report is only as current as this.
+         */
+        readonly harnessReference: string;
+    };
+    readonly target: {
+        readonly kind: 'directory' | 'tarball';
+        readonly path: string;
+    };
+    readonly facts: Facts;
+    readonly analysis: AnalysisIntegrity;
+    readonly summary: Readonly<Record<Severity, number>>;
+    readonly findings: readonly Finding[];
+}
+/**
+ * Order findings for display: most severe first, then by tier (A before B
+ * before C, since A carries verdicts), then by check id, then by evidence
+ * location. Total and deterministic, so two runs diff cleanly.
+ * @param a - left finding.
+ * @param b - right finding.
+ * @returns negative when `a` sorts first.
+ */
+export declare function compareFindings(a: Finding, b: Finding): number;
+/**
+ * Count findings per severity, including zeroes, so the JSON summary has a
+ * fixed key set that consumers can rely on.
+ * @param findings - the findings to tally.
+ * @returns one count per severity.
+ */
+export declare function summarize(findings: readonly Finding[]): Record<Severity, number>;
+//# sourceMappingURL=model.d.ts.map