@suss/extractor 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -312,7 +312,7 @@ type DiscoveryMatch = {
      * bound to a `const` one hop away, gets expanded. Cross-file and
      * computed iterables are outside v0.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationLoop";
     elementShape: {
@@ -340,7 +340,7 @@ type DiscoveryMatch = {
      * one specific module, which helps when two packages happen to export
      * a function with the same name.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationTemplate";
     helperName: string;
@@ -1127,6 +1127,41 @@ interface PatternPack {
      * same reason as in invocationRecognizers.
      */
     accessRecognizers?: AccessRecognizer[];
+    /**
+     * What the pack wrote as data rather than as code, for the health
+     * report. Absent for a pack written as a hand-rolled walk, which is
+     * itself the thing the report says.
+     */
+    declarations?: PackDeclarations;
+}
+/**
+ * The price a pack paid for what it matches, so the migration onto the
+ * declared surface can be measured rather than asserted.
+ *
+ * Expressiveness is bought link by link: a link answered with data is
+ * inspectable, serializable and runs on any adapter, while a link
+ * answered with a function is code that only its own language runs.
+ * Both are allowed, and the report says which is which.
+ */
+interface PackDeclarations {
+    declarations: DeclaredMatch[];
+}
+/** One thing a pack declared it matches. */
+interface DeclaredMatch {
+    /** What it matches, in the pack's own words. */
+    name: string;
+    /** Links whose answer is data. */
+    dataLinks: number;
+    /** Links answered with a function, by the question each one asks. */
+    functionLinks: string[];
+    /**
+     * Links whose function reaches the adapter's own syntax tree, by the
+     * question each one asks. Reaching the tree needs a separate import,
+     * so a pack cannot arrive here without saying so.
+     */
+    astLinks: string[];
+    /** A line of code the pack says this matches, or null when it says none. */
+    example: string | null;
 }
 /**
  * Per-call-site recognizer hook. See `PatternPack.invocationRecognizers`
@@ -1755,7 +1790,14 @@ type EffectArg = {
 } | {
     kind: "object";
     fields: Record<string, EffectArg>;
-} | {
+}
+/**
+ * The element shapes the adapter could read, which is not always one
+ * per runtime element. An array a callback builds,
+ * `tags.map((tag) => ({ name: tag }))`, arrives with a single item,
+ * because every element it produces has that one shape.
+ */
+ | {
     kind: "array";
     items: EffectArg[];
 } | {
@@ -1964,4 +2006,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, type PackDeclarations, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };

package/dist/index.d.ts

@@ -312,7 +312,7 @@ type DiscoveryMatch = {
      * bound to a `const` one hop away, gets expanded. Cross-file and
      * computed iterables are outside v0.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationLoop";
     elementShape: {
@@ -340,7 +340,7 @@ type DiscoveryMatch = {
      * one specific module, which helps when two packages happen to export
      * a function with the same name.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationTemplate";
     helperName: string;
@@ -1127,6 +1127,41 @@ interface PatternPack {
      * same reason as in invocationRecognizers.
      */
     accessRecognizers?: AccessRecognizer[];
+    /**
+     * What the pack wrote as data rather than as code, for the health
+     * report. Absent for a pack written as a hand-rolled walk, which is
+     * itself the thing the report says.
+     */
+    declarations?: PackDeclarations;
+}
+/**
+ * The price a pack paid for what it matches, so the migration onto the
+ * declared surface can be measured rather than asserted.
+ *
+ * Expressiveness is bought link by link: a link answered with data is
+ * inspectable, serializable and runs on any adapter, while a link
+ * answered with a function is code that only its own language runs.
+ * Both are allowed, and the report says which is which.
+ */
+interface PackDeclarations {
+    declarations: DeclaredMatch[];
+}
+/** One thing a pack declared it matches. */
+interface DeclaredMatch {
+    /** What it matches, in the pack's own words. */
+    name: string;
+    /** Links whose answer is data. */
+    dataLinks: number;
+    /** Links answered with a function, by the question each one asks. */
+    functionLinks: string[];
+    /**
+     * Links whose function reaches the adapter's own syntax tree, by the
+     * question each one asks. Reaching the tree needs a separate import,
+     * so a pack cannot arrive here without saying so.
+     */
+    astLinks: string[];
+    /** A line of code the pack says this matches, or null when it says none. */
+    example: string | null;
 }
 /**
  * Per-call-site recognizer hook. See `PatternPack.invocationRecognizers`
@@ -1755,7 +1790,14 @@ type EffectArg = {
 } | {
     kind: "object";
     fields: Record<string, EffectArg>;
-} | {
+}
+/**
+ * The element shapes the adapter could read, which is not always one
+ * per runtime element. An array a callback builds,
+ * `tags.map((tag) => ({ name: tag }))`, arrives with a single item,
+ * because every element it produces has that one shape.
+ */
+ | {
     kind: "array";
     items: EffectArg[];
 } | {
@@ -1964,4 +2006,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, type PackDeclarations, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/extractor",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Framework-agnostic extraction pipeline that turns raw extractions into suss behavioral summaries.",
   "keywords": [
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.11.0"
+    "@suss/behavioral-ir": "0.12.0"
   },
   "devDependencies": {
     "tsup": "*",