code-auditor-mcp 4.1.0 → 5.0.1

package/dist/analyzers/handleIdentification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleIdentification.d.ts","sourceRoot":"","sources":["../../src/analyzers/handleIdentification.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/handleIdentification.js

@@ -0,0 +1,424 @@
+/**
+ * Handle identification — the seam.
+ *
+ * Standing correction `specs/correction-seams-not-placement.md`: one concept,
+ * one seam, declared as a type, with a compile-time residue check. Handle
+ * identification ("is this receiver a DB handle?") is answered by exactly one
+ * entry point built from two walk-time evidence sources. A third source —
+ * `external-classifier` — re-disposes `unproven` sites after the audit from a
+ * separate `classify` command, never from the walk. No rule and no processor
+ * decides handle-ness any other way.
+ *
+ * ─── Shape ───
+ *
+ *   combineVerdicts(EVIDENCE_SOURCES.map(s => s.evaluate(site, facts)))
+ *
+ * Two walk-time evidence sources, registered against `WalkTimeEvidenceSourceId`:
+ *
+ *   - `sql-argument`            — the call's argument is literally SQL, so the
+ *                                 receiver must be a DB handle. Can only prove
+ *                                 `handle` or stay silent (`unproven`) — the
+ *                                 narrowing is compile-enforced on `evaluate`.
+ *   - `declaration-resolution`  — the receiver's declaration resolves to a DB
+ *                                 handle (package import, type annotation, or
+ *                                 binding). The only source that can prove
+ *                                 `not-handle`, so `not-handle.via` is narrowed
+ *                                 to it in the type.
+ *
+ * `external-classifier` is a third `via` value (a full member of
+ * `EvidenceSourceId`) reserved for post-audit attribution: its implementation is
+ * *not* in `EVIDENCE_SOURCES` and is *not* called from `identifyHandle` or
+ * anything downstream, so the walk stays synchronous. The `classify` command
+ * folds its verdict through `combineVerdicts` with the same invariant.
+ *
+ * `declaration-resolution` is itself a nested seam: one `ResolutionImplementation`
+ * per `Format`, registered against `RESOLUTION_IMPLEMENTATIONS`. A caller asks the
+ * interface and never learns which implementation answered — no caller names a
+ * format, and no format name appears above an implementation's own module.
+ */
+import { classifyRootIdentifier, deriveMemberPath, deriveThisMemberPath } from './receiverRoot.js';
+import { classifyGoRootIdentifier, buildGoImportMap, buildGoBindingEnv, classifyGoBindings, describeGoUnprovenCause, } from '../languages/go/goResolution.js';
+import { parseSql, DEFAULT_SQL_DIALECT } from '../languages/sql/sqlAst.js';
+import { extractTsWithinFileProvenance } from './provenance.js';
+import { classifyTsWithinFileProvenance } from './tsExpressionDescriptor.js';
+// ─── Combination rule ────────────────────────────────────────────────────────
+/**
+ * Fold the evidence sources' verdicts into one, exhaustive over `HandleVerdict`
+ * with no `default` arm. The precedence is `handle` > `not-handle` > `unproven`:
+ *
+ *   - any `handle` wins and records which source proved it;
+ *   - else any `not-handle` wins (only `declaration-resolution` can produce it,
+ *     so this arm is decided by that one source);
+ *   - else `unproven` carrying the union of reasons.
+ *
+ * @param verdicts — the verdicts from the walk-time evidence sources, in
+ *                   registration order.
+ * @returns the folded verdict: any `handle` (with its `via`), else `not-handle`,
+ *          else `unproven` carrying the union of non-empty reasons.
+ */
+export function combineVerdicts(verdicts) {
+    const unprovenReasons = [];
+    let notHandle = null;
+    for (const verdict of verdicts) {
+        if (verdict.kind === 'handle') {
+            return verdict; // handle wins immediately, records `via`
+        }
+        if (verdict.kind === 'not-handle') {
+            notHandle = verdict;
+            continue;
+        }
+        // unproven
+        unprovenReasons.push(verdict.reason);
+    }
+    if (notHandle !== null) {
+        return notHandle; // not-handle beats unproven
+    }
+    // An empty reason is a source *staying silent* rather than asserting an
+    // unproven cause (`sql-argument` sees no SQL argument). Drop those so the
+    // combined reason is the union of the sources that actually have a cause.
+    const reasons = [...new Set(unprovenReasons)].filter((r) => r.length > 0);
+    return {
+        kind: 'unproven',
+        reason: reasons.length === 0 ? 'no evidence source produced a verdict' : reasons.join('; '),
+    };
+}
+/** The TS word for an unproven, un-annotated `field` declaration. */
+export const TYPESCRIPT_FIELD_WORDING = 'class field';
+/** The Go word for an unproven, un-annotated `field` declaration. */
+export const GO_FIELD_WORDING = 'struct field';
+/**
+ * Why a root classified `unproven` could not be resolved to handle or
+ * not-handle. The single implementation behind the two `resolveRoot`s; the
+ * former `unprovenCause` / `goUnprovenCause` pair ceased to exist as a pair and
+ * its two halves became one function parameterized on the one `field` word that
+ * differs.
+ *
+ * @param root — the receiver's base identifier being described.
+ * @param provenance — the `has(key)` predicate over the file's DB-provenance set.
+ * @param binding — the root's binding in the file scope chain, or `undefined`.
+ * @param fieldNoValueWord — the format's word for an un-annotated field
+ *                           (`class field` / `struct field`).
+ * @returns a human-readable reason the root stayed `unproven`.
+ */
+export function describeUnprovenCause(root, provenance, binding, fieldNoValueWord) {
+    if (provenance.has(root))
+        return 'resolved to a DB handle (misclassified)';
+    if (!binding)
+        return 'has no binding in the file scope chain';
+    switch (binding.kind) {
+        case 'import':
+            return `imports from '${binding.source ?? '?'}' — an unrecognized package (not in the database-packages manifest)`;
+        case 'parameter':
+            return binding.typeText ? `parameter type \`${binding.typeText}\` is indeterminate` : 'is an un-annotated parameter';
+        case 'variable':
+            if (binding.typeText)
+                return `declared type \`${binding.typeText}\` is indeterminate`;
+            return binding.value ? 'is an un-annotated factory return' : 'is an un-annotated declaration';
+        case 'field':
+            if (binding.typeText)
+                return `field type \`${binding.typeText}\` is indeterminate`;
+            return binding.value ? 'is an un-annotated field initializer' : `is an un-annotated ${fieldNoValueWord}`;
+        case 'function':
+        case 'method':
+            return 'is a function reference without a DB return type';
+        case 'class':
+            return 'is a class reference without DB provenance';
+        case 'type':
+            return 'is a local type name';
+        default:
+            return 'is indeterminate';
+    }
+}
+// ─── Resolution implementations (nested seam) ────────────────────────────────
+const NON_CODE_FORMATS = ['css', 'scss', 'json', 'sql', 'markup'];
+/** A non-code file has no executable receiver, so its root is `not-handle` and
+ *  its within-file provenance is the empty map. */
+function nonCodeResolution(format) {
+    return {
+        format,
+        resolveRoot(site) {
+            return {
+                root: site.root,
+                disposition: 'not-handle',
+                reason: `a ${format} file carries no executable receiver, so \`${site.root}\` is not a DB handle`,
+            };
+        },
+        extract() {
+            return { kind: 'none' };
+        },
+        classify() {
+            return new Map();
+        },
+    };
+}
+/**
+ * The TypeScript-family implementation, shared by `typescript`/`tsx`/`javascript`.
+ * The three formats differ only by file extension; their receiver resolution is
+ * identical, so one implementation serves all three keys.
+ */
+const typescriptResolution = {
+    format: 'typescript',
+    resolveRoot(site, facts) {
+        if (facts.resolution.dialect !== 'ts') {
+            return { root: site.root, disposition: 'unproven', reason: 'missing TypeScript resolution environment' };
+        }
+        const env = facts.resolution.env;
+        // Clear the ambient-rejection + import-resolution out-params before
+        // classifying — the reason below reads them only when this classification
+        // set them, never a stale value from a prior site sharing the env.
+        env.ambientRejectionReason = undefined;
+        env.importResolutionReason = undefined;
+        const classified = classifyRootIdentifier(site.root, env, 0, {
+            thisField: site.thisField,
+            memberPath: site.thisField
+                ? deriveThisMemberPath(site.root, site.receiver)
+                : deriveMemberPath(site.root, site.receiver, false),
+            thisHeritage: site.thisHeritage,
+            scope: site.scope,
+        });
+        // The package discriminant (not the method name) decides the disposition: an
+        // unrecognized root is `unproven` (cannot-fire), never downgraded by method
+        // shape — `join` is `Array.prototype.join` and also `SQL JOIN`.
+        const disposition = classified;
+        return {
+            root: site.root,
+            disposition,
+            reason: disposition === 'unproven'
+                ? env.ambientRejectionReason ?? env.importResolutionReason ?? describeUnprovenCause(site.root, env.provenance, env.bindings.get(site.root), TYPESCRIPT_FIELD_WORDING)
+                : disposition,
+        };
+    },
+    extract(ast, adapter, sourceCode) {
+        return { kind: 'ts', projection: extractTsWithinFileProvenance(ast, adapter, sourceCode) };
+    },
+    classify(extract, extraSeeds = new Map()) {
+        if (extract.kind !== 'ts') {
+            throw new Error(`TypeScript resolution classified a ${extract.kind} within-file extract`);
+        }
+        return classifyTsWithinFileProvenance(extract.projection, extraSeeds);
+    },
+};
+/** The Go implementation. */
+const goResolution = {
+    format: 'go',
+    resolveRoot(site, facts) {
+        if (facts.resolution.dialect !== 'go') {
+            return { root: site.root, disposition: 'unproven', reason: 'missing Go resolution environment' };
+        }
+        const env = facts.resolution.env;
+        const classified = classifyGoRootIdentifier(site.root, env);
+        // The package discriminant (not the method name) decides the disposition: an
+        // unrecognized root is `unproven` (cannot-fire), never downgraded by method
+        // shape — `join` is `Array.prototype.join` and also `SQL JOIN`.
+        const disposition = classified;
+        return {
+            root: site.root,
+            disposition,
+            reason: disposition === 'unproven'
+                ? describeGoUnprovenCause(site.root, env)
+                : disposition,
+        };
+    },
+    extract(ast, adapter, sourceCode) {
+        return {
+            kind: 'go',
+            projection: {
+                imports: buildGoImportMap(ast, adapter),
+                bindings: buildGoBindingEnv(ast, adapter, sourceCode),
+            },
+        };
+    },
+    classify(extract, extraSeeds = new Map(), goPackageBindings) {
+        if (extract.kind !== 'go') {
+            throw new Error(`Go resolution classified a ${extract.kind} within-file extract`);
+        }
+        // `classifyGoBindings` seeds DB packages + classifies every binding; the
+        // cross-file `extraSeeds` merge is the one step `computeTsWithinFileProvenance`
+        // applied *outside* `buildGoWithinFileProvenance`, so it is reproduced here.
+        const prov = classifyGoBindings(extract.projection.imports, extract.projection.bindings, goPackageBindings);
+        for (const [name, evidence] of extraSeeds) {
+            if (!prov.has(name))
+                prov.set(name, evidence);
+        }
+        return prov;
+    },
+};
+export const RESOLUTION_IMPLEMENTATIONS = {
+    typescript: typescriptResolution,
+    tsx: typescriptResolution,
+    javascript: typescriptResolution,
+    go: goResolution,
+    css: nonCodeResolution('css'),
+    scss: nonCodeResolution('scss'),
+    json: nonCodeResolution('json'),
+    sql: nonCodeResolution('sql'),
+    markup: nonCodeResolution('markup'),
+};
+// ─── Evidence sources ────────────────────────────────────────────────────────
+/**
+ * `sql-argument`: the call's argument parses as a SQL statement, so the receiver
+ * must be a DB handle. It can only prove `handle`; on an absent argument it
+ * stays *silent* — `unproven` with an empty reason that `combineVerdicts` drops,
+ * so it never contributes a cause to the cannot-fire report.
+ *
+ * Spec 70 R3: the proof is the parsed format, not a method-name or package list.
+ * `site.sqlArgument` is the extracted SQL string (already stripped of its
+ * surrounding quotes/backticks); it proves `handle` only when {@link parseSql}
+ * accepts it. Spec 70 R2 says parsing a literal does not require *proving* the
+ * site's dialect first — one grammar is named and the parse is attempted under
+ * it — so the source parses under the corpus's named dialect
+ * (`facts.sqlDialect`), or under {@link DEFAULT_SQL_DIALECT} when that is `null`.
+ * An argument that does *not* parse is a genuine `unproven` with a reason — "I
+ * was handed SQL-shaped text and could not read it" — which surfaces as
+ * `cannot-fire`, never `clean` (criterion 3). When the dialect was undetermined,
+ * that reason names **both** the parse failure and the undetermined dialect (the
+ * failure may be dialect-specific syntax), rather than abstaining before the
+ * parse. A string that never reaches a data-access call site is not parsed at
+ * all (R5), so a non-SQL string argument on a non-query-shaped call is not this
+ * source's concern.
+ */
+const sqlArgumentSource = {
+    id: 'sql-argument',
+    evaluate(site, facts) {
+        if (site.sqlArgument === null)
+            return { kind: 'unproven', reason: '' };
+        const parsed = parseSql(site.sqlArgument, facts.sqlDialect ?? DEFAULT_SQL_DIALECT);
+        if (parsed.ok) {
+            // A parse success is not enough to prove a handle: node-sql-parser accepts
+            // fragments that are not standalone data-access statements (e.g. a bare
+            // `RETURN return_type` — the `RETURN` keyword plus an expression — which is
+            // how tree-sitter field names like `return_type`/`returnType` leak through
+            // and mis-prove a TreeSitterNode receiver as a DB handle). Only a statement
+            // of a real query/mutation kind (SELECT/INSERT/UPDATE/…), or a recognized
+            // standalone transaction-control marker, is unambiguously SQL that names a
+            // database receiver. Anything else parses to `kind === 'other'` with no
+            // statement type and stays unproven so declaration-resolution decides.
+            const astType = parsed.ast.type;
+            const isDataAccess = parsed.kind !== 'other' || astType === 'transaction';
+            if (isDataAccess)
+                return { kind: 'handle', via: 'sql-argument' };
+            return {
+                kind: 'unproven',
+                reason: `the SQL argument parses but is not a standalone data-access statement (kind: ${parsed.kind})`,
+            };
+        }
+        if (facts.sqlDialect === null) {
+            return {
+                kind: 'unproven',
+                reason: `node-sql-parser could not parse the SQL argument under the default ${DEFAULT_SQL_DIALECT} grammar, and the dialect is undetermined — the failure may be dialect-specific syntax: ${parsed.reason}`,
+            };
+        }
+        return { kind: 'unproven', reason: `node-sql-parser could not parse the SQL argument under ${facts.sqlDialect}: ${parsed.reason}` };
+    },
+};
+/**
+ * `declaration-resolution`: the receiver's declaration resolves to a DB handle
+ * (package import, type annotation, or binding). The only source that can prove
+ * `not-handle`. It delegates to the format's `ResolutionImplementation`.
+ */
+const declarationResolutionSource = {
+    id: 'declaration-resolution',
+    evaluate(site, facts) {
+        const resolved = RESOLUTION_IMPLEMENTATIONS[site.format].resolveRoot(site, facts);
+        switch (resolved.disposition) {
+            case 'handle':
+                return { kind: 'handle', via: 'declaration-resolution' };
+            case 'not-handle':
+                return { kind: 'not-handle', via: 'declaration-resolution' };
+            case 'unproven':
+                return { kind: 'unproven', reason: resolved.reason };
+        }
+    },
+};
+export const EVIDENCE_SOURCES = {
+    'sql-argument': sqlArgumentSource,
+    'declaration-resolution': declarationResolutionSource,
+};
+// ─── The entry point ──────────────────────────────────────────────────────────
+/**
+ * The single handle-identification entry point: fold both evidence sources.
+ *
+ * @param site — the query-shaped call site whose handle-ness is being resolved.
+ * @param facts — the flat + deep resolution facts the sources read.
+ * @returns the combined `HandleVerdict` from both walk-time sources.
+ */
+export function identifyHandle(site, facts) {
+    return combineVerdicts([
+        EVIDENCE_SOURCES['sql-argument'].evaluate(site, facts),
+        EVIDENCE_SOURCES['declaration-resolution'].evaluate(site, facts),
+    ]);
+}
+/** The accurate disposition when no classifier is configured: the question cannot
+ *  be answered, so the source abstains with this exact reason. */
+export const NO_EXTERNAL_CLASSIFIER = {
+    kind: 'unproven',
+    reason: 'no external classifier configured',
+};
+/**
+ * The single upper threshold (the "band") the tool applies to a classifier's
+ * confidence. At or above it the site is attributed `handle` with the confidence
+ * and provenance; below it the source abstains — with the confidence recorded in
+ * the reason so the near-miss is visible, not discarded. A low confidence is
+ * absence of evidence, not evidence of absence: this mapper proves or abstains,
+ * never `not-handle`.
+ *
+ * @param result — the classifier's confidence plus opaque provenance.
+ * @param threshold — the handle threshold; at or above it the site is `handle`.
+ * @returns `handle` (with confidence + provenance) at/above threshold, else
+ *          `unproven` with the confidence recorded in the reason.
+ */
+export function externalClassifierVerdict(result, threshold) {
+    const { confidence, provenance } = result;
+    if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+        return {
+            kind: 'unproven',
+            reason: `external classifier confidence ${confidence} is out of range [0, 1]`,
+        };
+    }
+    if (confidence < threshold) {
+        return {
+            kind: 'unproven',
+            reason: `external classifier confidence ${confidence} is below the handle threshold ${threshold}`,
+        };
+    }
+    return { kind: 'handle', via: 'external-classifier', confidence, provenance };
+}
+/**
+ * Validate classifier configuration, refusing loudly on a missing or non-finite
+ * threshold. Returns the config on success; throws otherwise. The threshold has
+ * no default — a guessed number would be a silent wrong answer at the
+ * configuration layer.
+ *
+ * @param config — the raw, unvalidated classifier configuration.
+ * @returns the validated `ExternalClassifierConfig` with a finite `threshold` in
+ *          [0, 1].
+ */
+export function validateExternalClassifierConfig(config) {
+    if (typeof config !== 'object' || config === null) {
+        throw new Error('external classifier config must be an object with a `threshold`');
+    }
+    const threshold = config.threshold;
+    if (typeof threshold !== 'number' || !Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+        throw new Error('external classifier `threshold` is required and must be a finite number in [0, 1]');
+    }
+    return { threshold };
+}
+const _allEvidenceSourcesRegistered = true;
+const _allFormatsImplemented = true;
+// Liveness seeds — each names a discriminant and is legal only while the residue
+// above is `never`. Remove one registration, the residue widens to that name,
+// the assignment compiles, and the `@ts-expect-error` goes unused → the build
+// fails. Same idiom as `phase/seeded-defects.ts`, colocated so the seam's
+// totality is checked wherever the seam is compiled.
+// @ts-expect-error — an unregistered walk-time source would make this a non-never type
+const _missingEvidenceSource = 'sql-argument';
+// @ts-expect-error — an unimplemented format would make this a non-never type
+const _missingFormat = 'go';
+// @ts-expect-error — a prove-or-abstain source cannot disprove handle-ness (narrowing liveness)
+const _proveOrAbstainCannotDisprove = { kind: 'not-handle', via: 'declaration-resolution' };
+void _allEvidenceSourcesRegistered;
+void _allFormatsImplemented;
+void _missingEvidenceSource;
+void _missingFormat;
+void _proveOrAbstainCannotDisprove;
+//# sourceMappingURL=handleIdentification.js.map

package/dist/analyzers/handleIdentification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleIdentification.js","sourceRoot":"","sources":["../../src/analyzers/handleIdentification.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/manifestStaleness.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Manifest staleness — the ecosystem-list self-check (Part 2b).
+ *
+ * The package manifest does not participate in classification. It is a staleness
+ * report — "our list names drizzle-orm, this project doesn't depend on it" —
+ * emitted as a diagnostic and affecting no verdict. A receiver classifies as a
+ * DB handle by declaration resolution and SQL-argument evidence, never by
+ * whether the project's package.json names the package.
+ *
+ * "Our list" is the TS implementation's `DB_PACKAGES` (tsEcosystem.ts, npm
+ * packages) and the Go implementation's `GO_DB_PACKAGES` (goResolution.ts, Go
+ * import paths). "This project depends on" is the union of package.json
+ * `dependencies`/`devDependencies`/`peerDependencies` (TS) and go.mod `require`
+ * lines (Go). The gap — a name our list carries that the project does not
+ * actually depend on — is the only per-project signal that a hardcoded ecosystem
+ * list has drifted from the ecosystem it claims to describe.
+ *
+ * This module reads the two manifests but owns nothing in them: `DB_PACKAGES` /
+ * `GO_DB_PACKAGES` stay behind their implementations' interfaces, read here only
+ * because this module *is* part of the resolution layer that owns them. Callers
+ * above the interface surface the resulting {@link ManifestStaleEntry} list, not
+ * the sets.
+ */
+/** One stale entry: a package our ecosystem list names that the project doesn't. */
+export interface ManifestStaleEntry {
+    ecosystem: 'ts' | 'go';
+    /** The package name (TS) or import path (Go) our list carries. */
+    package: string;
+    /** Absolute path to the manifest the comparison was made against. */
+    manifestPath: string;
+}
+/** The project's declared dependency names, plus where they were read from. */
+export interface ProjectManifest {
+    /** Union of package.json dependencies + go.mod requires. */
+    names: ReadonlySet<string>;
+    /** Absolute path to package.json, or null when absent/unreadable. */
+    tsManifestPath: string | null;
+    /** Absolute path to go.mod, or null when absent/unreadable. */
+    goManifestPath: string | null;
+}
+/**
+ * Read the project's dependency names from package.json (TS) and go.mod (Go).
+ * A missing or unreadable manifest contributes nothing — an empty manifest means
+ * "no manifest to compare against", which produces no staleness (see
+ * {@link computeManifestStaleness}).
+ *
+ * @param projectRoot — the project root containing package.json and/or go.mod.
+ * @returns the union of declared dependency names plus the path to each manifest
+ *          actually read (`null` when absent/unreadable).
+ */
+export declare function readProjectManifest(projectRoot: string): Promise<ProjectManifest>;
+/**
+ * The gap between our ecosystem lists and the project's manifest: every package
+ * `DB_PACKAGES` / `GO_DB_PACKAGES` names that the project does not depend on.
+ * Emitted only when the corresponding manifest exists — an absent package.json
+ * produces no TS staleness (there is nothing to be stale against), and likewise
+ * for go.mod and the Go list. Affects no verdict.
+ *
+ * @param manifest — the project's declared names and manifest paths.
+ * @returns the stale entries: every ecosystem-list package the project does not
+ *          depend on, restricted to manifests that actually exist.
+ */
+export declare function computeManifestStaleness(manifest: ProjectManifest): ManifestStaleEntry[];
+//# sourceMappingURL=manifestStaleness.d.ts.map

package/dist/analyzers/manifestStaleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifestStaleness.d.ts","sourceRoot":"","sources":["../../src/analyzers/manifestStaleness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,qEAAqE;IACrE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,+DAA+D;IAC/D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAmDvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,kBAAkB,EAAE,CAaxF"}

package/dist/analyzers/manifestStaleness.js

@@ -0,0 +1,115 @@
+/**
+ * Manifest staleness — the ecosystem-list self-check (Part 2b).
+ *
+ * The package manifest does not participate in classification. It is a staleness
+ * report — "our list names drizzle-orm, this project doesn't depend on it" —
+ * emitted as a diagnostic and affecting no verdict. A receiver classifies as a
+ * DB handle by declaration resolution and SQL-argument evidence, never by
+ * whether the project's package.json names the package.
+ *
+ * "Our list" is the TS implementation's `DB_PACKAGES` (tsEcosystem.ts, npm
+ * packages) and the Go implementation's `GO_DB_PACKAGES` (goResolution.ts, Go
+ * import paths). "This project depends on" is the union of package.json
+ * `dependencies`/`devDependencies`/`peerDependencies` (TS) and go.mod `require`
+ * lines (Go). The gap — a name our list carries that the project does not
+ * actually depend on — is the only per-project signal that a hardcoded ecosystem
+ * list has drifted from the ecosystem it claims to describe.
+ *
+ * This module reads the two manifests but owns nothing in them: `DB_PACKAGES` /
+ * `GO_DB_PACKAGES` stay behind their implementations' interfaces, read here only
+ * because this module *is* part of the resolution layer that owns them. Callers
+ * above the interface surface the resulting {@link ManifestStaleEntry} list, not
+ * the sets.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DB_PACKAGES } from './tsEcosystem.js';
+import { GO_DB_PACKAGES } from '../languages/go/goResolution.js';
+/**
+ * Read the project's dependency names from package.json (TS) and go.mod (Go).
+ * A missing or unreadable manifest contributes nothing — an empty manifest means
+ * "no manifest to compare against", which produces no staleness (see
+ * {@link computeManifestStaleness}).
+ *
+ * @param projectRoot — the project root containing package.json and/or go.mod.
+ * @returns the union of declared dependency names plus the path to each manifest
+ *          actually read (`null` when absent/unreadable).
+ */
+export async function readProjectManifest(projectRoot) {
+    const names = new Set();
+    let tsManifestPath = null;
+    let goManifestPath = null;
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    try {
+        const raw = await readFile(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(raw);
+        for (const group of [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies]) {
+            for (const name of Object.keys(group ?? {}))
+                names.add(name);
+        }
+        tsManifestPath = packageJsonPath;
+    }
+    catch {
+        // no package.json (or unreadable) — nothing to compare the TS list against
+    }
+    const goModPath = path.join(projectRoot, 'go.mod');
+    try {
+        const raw = await readFile(goModPath, 'utf-8');
+        let inRequireBlock = false;
+        for (const line of raw.split('\n')) {
+            const t = line.trim();
+            if (t.startsWith('require (')) {
+                inRequireBlock = true;
+                continue;
+            }
+            if (inRequireBlock) {
+                if (t === ')') {
+                    inRequireBlock = false;
+                    continue;
+                }
+                const mod = t.split(/\s+/)[0];
+                if (mod)
+                    names.add(mod);
+                continue;
+            }
+            if (t.startsWith('require ')) {
+                const mod = t.slice('require '.length).trim().split(/\s+/)[0];
+                if (mod)
+                    names.add(mod);
+            }
+        }
+        goManifestPath = goModPath;
+    }
+    catch {
+        // no go.mod (or unreadable) — nothing to compare the Go list against
+    }
+    return { names, tsManifestPath, goManifestPath };
+}
+/**
+ * The gap between our ecosystem lists and the project's manifest: every package
+ * `DB_PACKAGES` / `GO_DB_PACKAGES` names that the project does not depend on.
+ * Emitted only when the corresponding manifest exists — an absent package.json
+ * produces no TS staleness (there is nothing to be stale against), and likewise
+ * for go.mod and the Go list. Affects no verdict.
+ *
+ * @param manifest — the project's declared names and manifest paths.
+ * @returns the stale entries: every ecosystem-list package the project does not
+ *          depend on, restricted to manifests that actually exist.
+ */
+export function computeManifestStaleness(manifest) {
+    const stale = [];
+    if (manifest.tsManifestPath !== null) {
+        for (const pkg of DB_PACKAGES) {
+            if (!manifest.names.has(pkg))
+                stale.push({ ecosystem: 'ts', package: pkg, manifestPath: manifest.tsManifestPath });
+        }
+    }
+    if (manifest.goManifestPath !== null) {
+        for (const pkg of GO_DB_PACKAGES) {
+            if (!manifest.names.has(pkg))
+                stale.push({ ecosystem: 'go', package: pkg, manifestPath: manifest.goManifestPath });
+        }
+    }
+    return stale;
+}
+//# sourceMappingURL=manifestStaleness.js.map

package/dist/analyzers/manifestStaleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifestStaleness.js","sourceRoot":"","sources":["../../src/analyzers/manifestStaleness.ts"],"names":[],"mappings":"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"}