@tricoteuses/tisseuse 0.20.0 → 0.21.0

package/dist/src/lib/extractors/action_directives_cpu.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/extractors/links.citation_scope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/extractors/portion_references_cpu.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/extractors/references.d.ts

@@ -5,15 +5,15 @@ export type ExtractReferencesDiagnostics = {
     citationCount: number;
     fastPath: FastPathExtractDiagnostics;
 };
-export declare function extractCitationReferences(context: TextParserContext, citation: TextAstCitation, options?: {
-    diagnostics?: ExtractReferencesDiagnostics;
-}): Generator<TextAstReference, void>;
-export declare function extractReferences(context: TextParserContext, options?: {
+type ExtractReferencesOptions = {
     diagnostics?: ExtractReferencesDiagnostics;
     overlapWindowForCandidate?: (anchor: string) => number;
-}): Generator<TextAstReference, void>;
-export declare function extractReferencesWithOriginalTransformations(context: TextParserContext, transformation: Transformation, options?: {
-    diagnostics?: ExtractReferencesDiagnostics;
-}): Generator<TextAstReference, void>;
+    /** Scoping metadata for flattened standalone quotations; never added to the AST. */
+    onStandaloneCitationReference?: (reference: TextAstReference, citation: TextAstCitation) => void;
+};
+export declare function extractCitationReferences(context: TextParserContext, citation: TextAstCitation, options?: ExtractReferencesOptions): Generator<TextAstReference, void>;
+export declare function extractReferences(context: TextParserContext, options?: ExtractReferencesOptions): Generator<TextAstReference, void>;
+export declare function extractReferencesWithOriginalTransformations(context: TextParserContext, transformation: Transformation, options?: ExtractReferencesOptions): Generator<TextAstReference, void>;
 export declare const getExtractedReferences: (context: TextParserContext) => TextAstReference[];
 export declare const getExtractedReferencesWithOriginalTransformations: (context: TextParserContext, transformation: Transformation) => TextAstReference[];
+export {};

package/dist/src/lib/f_legi/resolver.d.ts

@@ -45,13 +45,11 @@ export declare class FlegiResolver extends LegiResolver {
     private queryUniqueActiveArticlesByNumsUsingContextHeuristic;
     private queryGloballyUniqueArticleRowsByNums;
     private getActiveArticleRowsByNum;
-    private getActiveArticleRowsForContextTextIds;
     private getActiveArticleRowsForContextTextIdsWithRoots;
     private queryActiveArticleRowsForContextTextIds;
     private preloadDirectSectionChildrenByRootPath;
     private getTextIdFromSegmentIdUsingContextHeuristic;
     private getTextIdFromSegmentIdUsingSctaHeuristic;
-    private getContextTextIdsFromTextId;
     private getContextTextIdsByTextIds;
     private getRootTextIdsFromTextId;
     private getRootTextIdsByTextIds;

package/dist/src/lib/index.d.ts

@@ -1,6 +1,7 @@
 import { addLinksToMarkdown } from './linkers/markdown.js';
 export { classifyArticleTemporalStatus, getArticleDateDebut, getArticleDateSignature, getOrLoadArticleSiblingId, isLegifranceSentinelDate, sortArticlesByDate, type ArticleTemporalStatus, } from './articles.js';
 export { assertNever } from './asserts.js';
+export { startCanutesTitlesMetrics } from './legi/canutes_titles_metrics.js';
 export { newAssembleeObjectCache, newLegifranceObjectCache, newObjectCache, type AssembleeObjectCache, type AssembleeObjectType, type LegifranceObjectCache, type ObjectCache, } from './cache.js';
 export { formatLongDate } from './dates.js';
 export { extractBillDefinitions } from './extractors/definitions.js';

package/dist/src/lib/legi/canutes_article_preload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/legi/canutes_candidates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/legi/canutes_resolver.d.ts

@@ -1,5 +1,5 @@
-import { Sql } from 'postgres';
-import { LegiResolver, LegiArticleHistoryInfo, LegiArticleInfo, LegiSectionInfo, PreloadTextTitlesInfosOptions } from './resolver.js';
+import { CanutesSql } from './canutes_sql.js';
+import { LegiResolver, LegiArticleHistoryInfo, LegiArticleInfo, LegiSectionInfo, PreloadActiveArticlesByTextIdsOptions, PreloadTextTitlesInfosOptions } from './resolver.js';
 /**
  * Minimal structural view of a Légifrance article row needed to compute an
  * article history entry point; shared with the audit preload.
@@ -23,17 +23,18 @@ export declare class CanutesResolver extends LegiResolver {
     private readonly canutesDb;
     private readonly articleHistoryInfoByTextAndNum;
     private readonly articleRowsByNumByTextAndDate;
+    private readonly articleNumsLoadedByTextAndDate;
     private readonly directSectionChildrenByParentAndDate;
     private readonly globalArticleRowsByNumAndDate;
     private readonly europeanTextUrlByTitleId;
     private readonly textIdBySegmentId;
-    private textTitlesInfosLoaded;
-    constructor(canutesDb: Sql);
+    constructor(canutesDb: CanutesSql);
     getActiveArticlesByTextAndNum({ date, num, textId, }: {
         date: string;
         num: string | undefined;
         textId: string;
     }): Promise<LegiArticleInfo[]>;
+    preloadActiveArticlesByTextIds({ date, nums, textIds, }: PreloadActiveArticlesByTextIdsOptions): Promise<void>;
     getArticleHistoryInfo({ num, textId, }: {
         num: string | undefined;
         textId: string;

package/dist/src/lib/legi/canutes_resolver_cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/legi/canutes_section_roots.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/legi/canutes_sql.d.ts

@@ -0,0 +1,4 @@
+import { Sql, TransactionSql } from 'postgres';
+export type CanutesSql = Sql | TransactionSql;
+/** Reuse a caller-owned stable snapshot, or open a read-only one on a pool. */
+export declare function withCanutesReadOnlySnapshot<T>(db: CanutesSql, read: (sql: TransactionSql) => Promise<T>): Promise<T>;

package/dist/src/lib/legi/canutes_text_titles_cache.d.ts

@@ -0,0 +1,24 @@
+import { Sql } from 'postgres';
+import { PreloadTextTitlesInfosOptions } from './resolver.js';
+import { CanutesSql } from './canutes_sql.js';
+import { TextTitlesInfoRow } from './text_titles_infos.js';
+type QuerySql = CanutesSql;
+export type CanutesTitlesCacheMeta = {
+    guarded: boolean;
+    revision: string | null;
+    cacheRevision: string | null;
+    formatVersion: number | null;
+    generatedAt: string | null;
+    sourceRowCount: number | null;
+};
+export declare function readCanutesTitlesCacheMeta(sql: QuerySql): Promise<CanutesTitlesCacheMeta | undefined>;
+export declare function readCanutesTextTitleRows(sql: QuerySql): Promise<TextTitlesInfoRow[]>;
+export declare function preloadCanutesTextTitlesInfos(db: CanutesSql, options?: PreloadTextTitlesInfosOptions): Promise<void>;
+export declare function warmCanutesTextTitlesCache(db: Sql, options?: PreloadTextTitlesInfosOptions & {
+    maxAttempts?: number;
+    force?: boolean;
+}): Promise<{
+    revision: string;
+    sourceRowCount: number;
+}>;
+export {};

package/dist/src/lib/legi/canutes_text_titles_cache.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/legi/canutes_titles_metrics.d.ts

@@ -0,0 +1,13 @@
+type Scope = "pool" | "transaction";
+type Path = "metadata" | "source" | "persistent" | "memory" | "coalesced";
+type Outcome = "success" | "error";
+export type CanutesTitlesMetric = {
+    path: Path;
+    end: (outcome: Outcome) => void;
+};
+/** Start zero-inclusive heartbeats, without enabling general PJL diagnostics.
+ * An absolute deadline is mandatory and may be at most 24 hours away.
+ */
+export declare function startCanutesTitlesMetrics(): void;
+export declare function beginCanutesTitlesMetric(sqlScope: Scope): CanutesTitlesMetric | undefined;
+export {};

package/dist/src/lib/legi/text_titles_infos.d.ts

@@ -30,6 +30,7 @@ export declare function buildAndInstallTextTitlesInfos(rows: TextTitlesInfoRow[]
     onProgress?: (progress: BuildTextTitlesInfosProgress) => void;
 }): Promise<void>;
 export declare function installTextTitlesInfos(textTitlesInfos: TextTitlesInfos): void;
+export declare function isTextTitlesInfosInstalled(textTitlesInfos: TextTitlesInfos): boolean;
 export declare function buildTextTitlesInfos(rows: TextTitlesInfoRow[], { onProgress, }?: {
     onProgress?: (progress: BuildTextTitlesInfosProgress) => void;
 }): Promise<TextTitlesInfos>;

package/dist/src/lib/linkers/html.d.ts

@@ -1,4 +1,4 @@
-import { Sql } from 'postgres';
+import { CanutesSql } from '../legi/canutes_sql.js';
 import { DefinitionOrLink, TextLinksParserState } from '../extractors/links.js';
 import { LegiResolver } from '../legi/resolver.js';
 import { LinkType } from '../links.js';
@@ -6,7 +6,7 @@ import { FragmentPosition } from '../text_parsers/fragments.js';
 import { TextParserContext } from '../text_parsers/parsers.js';
 import { Transformation } from '../text_parsers/transformers.js';
 export declare function addLinksToHtml({ canutesDb, excludedHtmlRanges, includeInternalArticleLinks, legiResolver: providedLegiResolver, date, html, linkBaseUrl, linkType, logIgnoredReferencesTypes, logPartialReferences, logReferences, onLink, previousContext, state, }: {
-    canutesDb?: Sql;
+    canutesDb?: CanutesSql;
     excludedHtmlRanges?: FragmentPosition[];
     includeInternalArticleLinks?: boolean;
     legiResolver?: LegiResolver;
@@ -37,7 +37,7 @@ interface HtmlReplacement {
     stop: number;
 }
 export declare function addLinksOrReferencesToHtmlPage({ canutesDb, legiResolver: providedLegiResolver, date, defaultTextId, htmlTransformation, inputHtml, linkBaseUrl, linkType, logIgnoredReferencesTypes, logPartialReferences, logReferences, outputTypes: requestedOutputTypes, referredLegifranceTextsInfos, }: {
-    canutesDb?: Sql;
+    canutesDb?: CanutesSql;
     legiResolver?: LegiResolver;
     date: string;
     defaultTextId?: string;

package/dist/src/lib/linkers/markdown.d.ts

@@ -1,9 +1,9 @@
-import { Sql } from 'postgres';
+import { CanutesSql } from '../legi/canutes_sql.js';
 import { LegiResolver } from '../legi/resolver.js';
 import { LinkType } from '../links.js';
 import { TextParserContext } from '../text_parsers/parsers.js';
 export declare function addLinksToMarkdown({ canutesDb, legiResolver: providedLegiResolver, date, linkBaseUrl, linkType, previousContext, text, }: {
-    canutesDb?: Sql;
+    canutesDb?: CanutesSql;
     legiResolver?: LegiResolver;
     date: string;
     linkBaseUrl: string;

package/dist/src/lib/server/akn_rendering.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/bill_action_resolver_invariance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/bill_action_target_fixtures.d.ts

@@ -0,0 +1,7 @@
+export declare const actionTargetAnchor: (id: string, label: string, type?: string) => string;
+export declare const actionTargetFixtures: {
+    name: string;
+    paragraphs: string[];
+}[];
+export declare function actionTargetHtml(paragraphs: string[]): string;
+export declare function installActionTargetTitles(): Promise<void>;

package/dist/src/lib/server/bill_citation_anaphora.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/bill_comparison.d.ts

@@ -0,0 +1,42 @@
+import { ParsedBillDirective } from './parsed_bills.js';
+export type SavedBillOutput = {
+    html: string;
+    directives: ParsedBillDirective[];
+};
+/** Compare exact output, grammatical ASTs, per-directive targets and link multisets separately. */
+export declare function compareBillOutputs(left: SavedBillOutput, right: SavedBillOutput, maxExamples?: number): {
+    exactHtmlEqual: boolean;
+    exactDirectivesEqual: boolean;
+    directiveCounts: {
+        left: number;
+        right: number;
+    };
+    grammarDifferences: number;
+    targetDifferences: number;
+    directiveExamples: {
+        index: number;
+        articleId: string;
+        blockId: string | undefined;
+        kind: "delete" | "insert_after" | "insert_before" | "replace" | "replace_portion" | "delete_portion" | "delete_article" | "compound";
+        sourcePosition: import('../index.js').FragmentPosition;
+        grammarEqual: boolean;
+        leftTargets: string[];
+        rightTargets: string[];
+    }[];
+    links: {
+        leftOnly: number;
+        rightOnly: number;
+        differencesByClass: Record<string, {
+            leftOnly: number;
+            rightOnly: number;
+        }>;
+        examples: {
+            leftCount: number;
+            rightCount: number;
+            className: string;
+            href: string;
+            text: string;
+            count: number;
+        }[];
+    };
+};

package/dist/src/lib/server/bill_comparison.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/bill_target_scope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/canutes_legacy_candidates.d.ts

@@ -0,0 +1,19 @@
+import { Sql } from 'postgres';
+import { CanutesResolver } from '../legi/canutes_resolver.js';
+import { LegiArticleInfo } from '../legi/resolver.js';
+/** Profiling reference only: the original full-transfer global preload.
+ * Keep outside the production resolver so before/after uses the same parser,
+ * titles and SQL connection. Like the original, row order is unspecified. */
+export declare class CanutesLegacyCandidatesResolver extends CanutesResolver {
+    private readonly legacyDb;
+    private readonly globals;
+    constructor(legacyDb: Sql);
+    getUniqueActiveArticlesByNum({ date, num, }: {
+        date: string;
+        num: string | undefined;
+    }): Promise<LegiArticleInfo[]>;
+    preloadUniqueActiveArticlesByNums({ date, nums, }: {
+        date: string;
+        nums: Iterable<string | undefined>;
+    }): Promise<void>;
+}

package/dist/src/lib/server/canutes_only_compatibility.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/databases/canutes_text_titles_cache.d.ts

@@ -0,0 +1,8 @@
+import { Sql } from 'postgres';
+export declare function configureCanutesTextTitlesCache(db: Sql): Promise<void>;
+export declare function configureCanutesTextTitlesTriggers(db: Sql): Promise<void>;
+export declare function grantCanutesTextTitlesCacheRoles(db: Sql, options?: {
+    readers?: string[];
+    builders?: string[];
+}): Promise<void>;
+export declare function ensureCanutesArticleNumberIndex(db: Sql): Promise<string>;

package/dist/src/lib/server/flegi_profiling.d.ts

@@ -0,0 +1,14 @@
+import { Sql } from 'postgres';
+import { FlegiResolver } from '../f_legi/resolver.js';
+export type ProfilingTitleStages = {
+    rows: number;
+    queryMs: number;
+    buildInstallMs: number;
+    cacheHit?: boolean;
+};
+/** Profiling only: never invoke FlegiResolver's cache builder, locks or DML. */
+export declare function createReadOnlyFlegiProfilingResolver(db: Sql, titleMode: "source" | "cache"): {
+    create: () => FlegiResolver;
+    getTitleStages: () => ProfilingTitleStages | undefined;
+    titlesLoaded: () => boolean;
+};

package/dist/src/lib/server/flegi_profiling.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/masquage-typesense.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/server/masquage_typesense.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Titres occultés du pilote masquage, pour la projection Typesense publique
+ * (`textes_juridiques`) : quand un texte est couvert par une copie, son
+ * titre — et celui des autres versions du même CID — est remplacé par le
+ * titre occulté, afin qu'aucun nom ne soit indexé ni retrouvable par nom.
+ *
+ * Le rôle de lecture doit posséder USAGE sur le schéma `masquage` et SELECT
+ * sur `masquage.public_document`. Sans ces droits, l'occultation est
+ * désactivée avec un avertissement explicite (titres bruts servis comme
+ * aujourd'hui) : la reconstruction ne doit jamais échouer faute de droits,
+ * et l'écart est détecté par le sondage Typesense de #280.
+ */
+export interface TitresOccultes {
+    /** Titre occulté, par identifiant JORFTEXT couvert. */
+    parId: Map<string, string>;
+    /** Titre occulté, par CID ayant au moins une version couverte. */
+    parCid: Map<string, string>;
+}
+/** Titres occultés (cache process d'une minute). */
+export declare function chargerTitresOccultes(): Promise<TitresOccultes>;
+/** Réinitialise le cache ; réservé aux tests. */
+export declare function _videCachePourTests(): void;
+/**
+ * Dérive, à partir des descriptions brutes, les descriptions à indexer dans
+ * la collection publique : pour tout CID couvert par une copie (et donc pour
+ * toutes ses versions), le titre des cartouches devient le titre occulté.
+ * Sans occultation active, les descriptions sont retournées telles quelles.
+ */
+export declare function deriverDescriptionsOccultees<D extends {
+    cid: string;
+    cartouches: ArrayLike<{
+        titre: string;
+    }>;
+}>(descriptions: Map<string, D>, titres: {
+    parCid: Map<string, string>;
+}): Map<string, D>;

package/dist/src/lib/server/sql_profiling.d.ts

@@ -0,0 +1,30 @@
+import { Sql } from 'postgres';
+export type SqlProfileEntry = {
+    signature: string;
+    calls: number;
+    errors: number;
+    rows: number;
+    totalMs: number;
+    maxMs: number;
+};
+/** Client wall time: includes connection setup, transfer and decoding, not
+ * just PostgreSQL execution. Parameters/credentials are never recorded. */
+export declare class SqlQueryProfiler {
+    private entries;
+    reset(): void;
+    summary(): SqlProfileEntry[];
+    private observe;
+    /** Instruments the awaited tagged/unsafe queries used by the resolver.
+     * Identifier/list/json fragments stay untouched; transaction callbacks get
+     * the same instrumentation. Streaming/cursor queries are not profiled. */
+    wrap<T extends Sql>(sql: T): T;
+}
+export type CapturedTiming = {
+    label: string;
+    details: Record<string, unknown>;
+};
+/** CLI-only capture of existing timing diagnostics. No runtime parser changes. */
+export declare function captureTimingDiagnostics<T>(task: () => Promise<T>, timings?: CapturedTiming[]): Promise<{
+    result: T;
+    timings: CapturedTiming[];
+}>;

package/dist/src/lib/server/sql_profiling.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/text_parsers/action_words.d.ts

@@ -1,5 +1,7 @@
 export declare const ACTION_VERB_RE: RegExp;
 export declare function normalizeActionText(text: string): string;
+/** Create a bounded cache owned by one synchronous directive extraction. */
+export declare function createActionTextNormalizer(): typeof normalizeActionText;
 export declare function hasActionRedactionIntro(normalizedActionScope: string, normalizedText?: string, actionScope?: string): boolean;
 export declare function hasAfterCue(normalizedActionScope: string): boolean;
 export declare function hasBeforeCue(normalizedActionScope: string): boolean;

package/dist/src/lib/text_parsers/action_words.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/text_parsers/texts.d.ts

@@ -1,3 +1,4 @@
+export declare function getTextTitlesInfosInstallationVersion(): number;
 export declare function setTextTitlesInfos(textTitlesInfos: unknown): void;
 /** Keep the successive titles of one CID together when ranking code editions. */
 export declare function rankCodeTitleCids(cids: string[], date: string): string[];

package/dist/src/scripts/compare_legi_bills.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/configure_postgres_legi_resolver.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/profile_canutes_bill.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/test_canutes_titles_cache.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/warm_canutes_text_titles_cache.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tricoteuses/tisseuse",
   "description": "Find links in/to French legislative documents",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "keywords": [
     "Assemblée nationale",
     "France",
@@ -65,6 +65,12 @@
     "configure": "tsx src/scripts/configure.ts",
     "configure:postgres:assemblee-triggers": "tsx src/scripts/configure_postgres_assemblee_document_triggers.ts",
     "configure:postgres:senat-triggers": "tsx src/scripts/configure_postgres_senat_document_triggers.ts",
+    "configure:postgres:legi-resolver": "tsx src/scripts/configure_postgres_legi_resolver.ts",
+    "warm:postgres:legi-titles": "tsx src/scripts/warm_canutes_text_titles_cache.ts",
+    "test:postgres:legi-cache": "tsx src/scripts/test_canutes_titles_cache.ts",
+    "profile:canutes-bill": "tsx src/scripts/profile_canutes_bill.ts",
+    "profile:legi-bill": "tsx src/scripts/profile_canutes_bill.ts",
+    "compare:legi-bills": "tsx src/scripts/compare_legi_bills.ts",
     "format": "prettier --write \"src/**/*.ts\" \"*.md\"",
     "index:jos": "tsx src/scripts/extract_jos_infos.ts",
     "index:postgres:assemblee": "tsx src/scripts/index_postgres_assemblee_texts.ts",